This is a short guide on how to contribute things to rclone.
If you've just got a question or aren't sure if you've found a bug then please use the rclone forum instead of filing an issue.
When filing an issue, please include the following information if possible as well as a description of the problem. Make sure you test with the latest beta of rclone:
rclone version
)rclone copy /tmp remote:tmp
)-vv
flag (e.g. output from rclone -vv copy /tmp remote:tmp
)
If you find a bug that you'd like to fix, or a new feature that you'd like to implement then please submit a pull request via GitHub.
If it is a big feature, then make an issue first so it can be discussed.
To prepare your pull request first press the fork button on rclone's GitHub page.
Then install Git and set your public contribution name and email.
Next open your terminal, change directory to your preferred folder and initialise your local rclone project:
git clone https://github.com/rclone/rclone.git
cd rclone
git remote rename origin upstream
# if you have SSH keys setup in your GitHub account:
git remote add origin git@github.com:YOURUSER/rclone.git
# otherwise:
git remote add origin https://github.com/YOURUSER/rclone.git
Note that most of the terminal commands in the rest of this guide must be executed from the rclone folder created above.
Now install Go and verify your installation:
go version
Great, you can now compile and execute your own version of rclone:
go build
./rclone version
(Note that you can also replace go build
with make
, which will include a
more accurate version number in the executable as well as enable you to specify
more build options.) Finally make a branch to add your new feature
git checkout -b my-new-feature
And get hacking.
You may like one of the popular editors/IDE's for Go and a quick view on the rclone code organisation.
When ready - test the affected functionality and run the unit tests for the code you changed
cd folder/with/changed/files
go test -v
Note that you may need to make a test remote, e.g. TestSwift
for some
of the unit tests.
This is typically enough if you made a simple bug fix, otherwise please read the rclone testing section too.
Make sure you
When you are done with that push your changes to GitHub:
git push -u origin my-new-feature
and open the GitHub website to create your pull request.
Your changes will then get reviewed and you might get asked to fix some stuff. If so, then make the changes in the same branch, commit and push your updates to GitHub.
You may sometimes be asked to base your changes on the latest master or squash your commits.
Follow the guideline for commit messages and then:
git checkout my-new-feature # To switch to your branch
git status # To see the new and changed files
git add FILENAME # To select FILENAME for the commit
git status # To verify the changes to be committed
git commit # To do the commit
git log # To verify the commit. Use q to quit the log
You can modify the message or changes in the latest commit using:
git commit --amend
If you amend to commits that have been pushed to GitHub, then you will have to replace your previously pushed commits.
Note that you are about to rewrite the GitHub history of your branch. It is good practice to involve your collaborators before modifying commits that have been pushed to GitHub.
Your previously pushed commits are replaced by:
git push --force origin my-new-feature
To base your changes on the latest version of the rclone master (upstream):
git checkout master
git fetch upstream
git merge --ff-only
git push origin --follow-tags # optional update of your fork in GitHub
git checkout my-new-feature
git rebase master
If you rebase commits that have been pushed to GitHub, then you will have to replace your previously pushed commits.
To combine your commits into one commit:
git log # To count the commits to squash, e.g. the last 2
git reset --soft HEAD~2 # To undo the 2 latest commits
git status # To check everything is as expected
If everything is fine, then make the new combined commit:
git commit # To commit the undone commits as one
otherwise, you may roll back using:
git reflog # To check that HEAD{1} is your previous state
git reset --soft 'HEAD@{1}' # To roll back to your previous state
If you squash commits that have been pushed to GitHub, then you will have to replace your previously pushed commits.
Tip: You may like to use git rebase -i master
if you are experienced or have a more complex situation.
rclone currently uses GitHub Actions to build and test the project, which should be automatically available for your fork too from the Actions
tab in your repository.
If you install golangci-lint then you can run the same tests as get run in the CI which can be very helpful.
You can run them with make check
or with golangci-lint run ./...
.
Using these tests ensures that the rclone codebase all uses the same coding standards. These tests also check for easy mistakes to make (like forgetting to check an error return).
rclone's tests are run from the go testing framework, so at the top level you can run this to run all the tests.
go test -v ./...
You can also use make
, if supported by your platform
make quicktest
The quicktest is automatically run by GitHub when you push your branch to GitHub.
rclone contains a mixture of unit tests and integration tests. Because it is difficult (and in some respects pointless) to test cloud storage systems by mocking all their interfaces, rclone unit tests can run against any of the backends. This is done by making specially named remotes in the default config file.
If you wanted to test changes in the drive
backend, then you would
need to make a remote called TestDrive
.
You can then run the unit tests in the drive directory. These tests
are skipped if TestDrive:
isn't defined.
cd backend/drive
go test -v
You can then run the integration tests which test all of rclone's operations. Normally these get run against the local file system, but they can be run against any of the remotes.
cd fs/sync
go test -v -remote TestDrive:
go test -v -remote TestDrive: -fast-list
cd fs/operations
go test -v -remote TestDrive:
If you want to use the integration test framework to run these tests altogether with an HTML report and test retries then from the project root:
go install github.com/rclone/rclone/fstest/test_all
test_all -backends drive
If you want to run all the integration tests against all the remotes, then change into the project root and run
make check
make test
The commands may require some extra go packages which you can install with
make build_dep
The full integration tests are run daily on the integration test server. You can find the results at https://pub.rclone.org/integration-tests/
Rclone code is organised into a small number of top level directories with modules beneath.
If you are adding a new feature then please update the documentation.
If you add a new general flag (not for a backend), then document it in
docs/content/docs.md
- the flags there are supposed to be in
alphabetical order.
If you add a new backend option/flag, then it should be documented in
the source file in the Help:
field.
"\n\n"
).
rclone config
and in the docs (where it will be added by make backenddocs
,
normally run some time before next release).Examples:
field.
Help:
field, but they are treated
a bit different than the main option help text. They will be shown
as an unordered list, therefore a single line break is enough to
create a new list item. Also, for enumeration texts like name of
countries, it looks better without an ending period/full stop character.The only documentation you need to edit are the docs/content/*.md
files. The MANUAL.*
, rclone.1
, website, etc. are all auto-generated
from those during the release process. See the make doc
and make
website
targets in the Makefile if you are interested in how. You
don't need to run these when adding a feature.
Documentation for rclone sub commands is with their code, e.g.
cmd/ls/ls.go
. Write flag help strings as a single sentence on a single
line, without a period/full stop character at the end, as it will be
combined unmodified with other information (such as any default value).
Note that you can use GitHub's online editor for small changes in the docs which makes it very easy.
There are separate instructions for making a release in the RELEASE.md file.
Please make the first line of your commit message a summary of the change that a user (not a developer) of rclone would like to read, and prefix it with the directory of the change followed by a colon. The changelog gets made by looking at just these first lines so make it good!
If you have more to say about the commit, then enter a blank line and carry on the description. Remember to say why the change was needed - the commit itself shows what was changed.
Writing more is better than less. Comparing the behaviour before the change to that after the change is very useful. Imagine you are writing to yourself in 12 months time when you've forgotten everything about what you just did and you need to get up to speed quickly.
If the change fixes an issue then write Fixes #1234
in the commit
message. This can be on the subject line if it will fit. If you
don't want to close the associated issue just put #1234
and the
change will get linked into the issue.
Here is an example of a short commit message:
drive: add team drive support - fixes #885
And here is an example of a longer one:
mount: fix hang on errored upload
In certain circumstances, if an upload failed then the mount could hang
indefinitely. This was fixed by closing the read pipe after the Put
completed. This will cause the write side to return a pipe closed
error fixing the hang.
Fixes #1498
rclone uses the go modules support in go1.11 and later to manage its dependencies.
rclone can be built with modules outside of the GOPATH
.
To add a dependency github.com/ncw/new_dependency
see the
instructions below. These will fetch the dependency and add it to
go.mod
and go.sum
.
go get github.com/ncw/new_dependency
You can add constraints on that package when doing go get
(see the
go docs linked above), but don't unless you really need to.
Please check in the changes generated by go mod
including go.mod
and go.sum
in the same commit as your other changes.
If you need to update a dependency then run
go get golang.org/x/crypto
Check in a single commit as above.
In order to update all the dependencies then run make update
. This
just uses the go modules to update all the modules to their latest
stable release. Check in the changes in a single commit as above.
This should be done early in the release cycle to pick up new versions of packages in time for them to get some testing.
If you update a backend then please run the unit tests and the integration tests for that backend.
Assuming the backend is called remote
, make create a config entry
called TestRemote
for the tests to use.
Now cd remote
and run go test -v
to run the unit tests.
Then cd fs
and run go test -v -remote TestRemote:
to run the
integration tests.
The next section goes into more detail about the tests.
Choose a name. The docs here will use remote
as an example.
Note that in rclone terminology a file system backend is called a remote or an fs.
fs/types.go
backend/remote/remote.go
(copy this from a similar remote)
backend/all/all.go
rclone info
to help determine the encodings needed
rclone purge -v TestRemote:rclone-info
rclone test info --all --remote-encoding None -vv --write-json remote.json TestRemote:rclone-info
go run cmd/test/info/internal/build_csv/main.go -o remote.csv remote.json
remote.csv
in a spreadsheet and examine--dump bodies
, --tpslimit
, --user-agent
without you having to code anything!fs.go
and object.go
(there are a few backends like that - don't follow them!)api/types.go
TestRemote
for the unit tests to usebackend/remote/remote_test.go
- copy and adjust your example remotego test -v
fstest/test_all/config.yaml
Or if you want to run the integration tests manually:
cd fs/operations
go test -v -remote TestRemote:
cd fs/sync
go test -v -remote TestRemote:
ListR
check with this also
go test -v -remote TestRemote: -fast-list
See the testing section for more information on integration tests.
Add your backend to the docs - you'll need to pick an icon for it from
fontawesome. Keep lists of remotes in
alphabetical order of full name of remote (e.g. drive
is ordered as
Google Drive
) but with the local file system last.
README.md
- main GitHub pagedocs/content/remote.md
- main docs page (note the backend options are automatically added to this file with make backenddocs
)
autogenerated options
comments in (see your reference backend docs)bin/make_backend_docs.py remote
docs/content/overview.md
- overview docsdocs/content/docs.md
- list of remotes in config sectiondocs/content/_index.md
- front page of rclone.orgdocs/layouts/chrome/navbar.html
- add it to the website navigationbin/make_manual.py
- add the page to the docs
constantOnce you've written the docs, run make serve
and check they look OK
in the web browser and the links (internal and external) all work.
It is quite easy to add a new S3 provider to rclone.
You'll need to modify the following files
backend/s3/s3.go
providerOption
at the top of the filefs.RegInfo
.region
and `endpoint).setQuirks
function - see the documentation there.docs/content/s3.md
rclone config
session
s3.md
make backenddocs
or bin/make_backend_docs.py s3
README.md
- this is the home page in github
docs/contents/s3.md
docs/content/_index.md
- this is the home page of rclone.org
docs/contents/s3.md
When adding the provider, endpoints, quirks, docs etc keep them in
alphabetical order by Provider
name, but with AWS
first and
Other
last.
Once you've written the docs, run make serve
and check they look OK
in the web browser and the links (internal and external) all work.
Once you've written the code, test rclone config
works to your
satisfaction, and check the integration tests work go test -v -remote
NewS3Provider:
. You may need to adjust the quirks to get them to
pass. Some providers just can't pass the tests with control characters
in the names so if these fail and the provider doesn't support
urlEncodeListings
in the quirks then ignore them. Note that the
SetTier
test may also fail on non AWS providers.
For an example of adding an s3 provider see eb3082a1.
New features (backends, commands) can also be added "out-of-tree", through Go plugins. Changes will be kept in a dynamically loaded file instead of being compiled into the main binary. This is useful if you can't merge your changes upstream or don't want to maintain a fork of rclone.
librcloneplugin_KIND_NAME.so
.KIND
should be one of backend
, command
or bundle
.librcloneplugin_backend_pifs.so
.$RCLONE_PLUGIN_PATH
are loaded.To turn your existing additions into a Go plugin, move them to an external repository
and change the top-level package name to main
.
Check rclone --version
and make sure that the plugin's rclone dependency and host Go version match.
Then, run go build -buildmode=plugin -o PLUGIN_NAME.so .
to build the plugin.