2015-12-29 19:06:40 +00:00
# Contributing to rclone #
This is a short guide on how to contribute things to rclone.
## Reporting a bug ##
2017-02-11 20:19:44 +00:00
If you've just got a question or aren't sure if you've found a bug
then please use the [rclone forum ](https://forum.rclone.org/ ) 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
2017-03-29 12:38:34 +00:00
with the [latest beta of rclone ](https://beta.rclone.org/ ):
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
* Rclone version (e.g. output from `rclone version` )
* Which OS you are using and how many bits (e.g. Windows 10, 64 bit)
2020-10-13 21:49:58 +00:00
* The command you were trying to run (e.g. `rclone copy /tmp remote:tmp` )
* A log of the command with the `-vv` flag (e.g. output from `rclone -vv copy /tmp remote:tmp` )
2015-12-29 19:06:40 +00:00
* if the log contains secrets then edit the file with a text editor first to obscure them
2021-07-05 15:03:53 +00:00
## Submitting a new feature or bug fix ##
2015-12-29 19:06:40 +00:00
If you find a bug that you'd like to fix, or a new feature that you'd
2018-10-12 15:46:15 +00:00
like to implement then please submit a pull request via GitHub.
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
If it is a big feature, then [make an issue ](https://github.com/rclone/rclone/issues ) first so it can be discussed.
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
To prepare your pull request first press the fork button on [rclone's GitHub
2019-07-28 17:47:38 +00:00
page](https://github.com/rclone/rclone).
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
Then [install Git ](https://git-scm.com/downloads ) and set your public contribution [name ](https://docs.github.com/en/github/getting-started-with-github/setting-your-username-in-git ) and [email ](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address#setting-your-commit-email-address-in-git ).
Next open your terminal, change directory to your preferred folder and initialise your local rclone project:
2015-12-29 19:06:40 +00:00
2021-04-03 22:07:52 +00:00
git clone https://github.com/rclone/rclone.git
cd rclone
2015-12-29 19:06:40 +00:00
git remote rename origin upstream
2021-07-05 15:03:53 +00:00
# if you have SSH keys setup in your GitHub account:
2015-12-29 19:06:40 +00:00
git remote add origin git@github.com:YOURUSER/rclone.git
2021-07-05 15:03:53 +00:00
# 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 ](https://golang.org/doc/install ) and verify your installation:
go version
Great, you can now compile and execute your own version of rclone:
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
go build
./rclone version
Finally make a branch to add your new feature
2015-12-29 19:06:40 +00:00
git checkout -b my-new-feature
And get hacking.
2021-07-05 15:03:53 +00:00
You may like one of the [popular editors/IDE's for Go ](https://github.com/golang/go/wiki/IDEsAndTextEditorPlugins ) and a quick view on the rclone [code organisation ](#code-organisation ).
When ready - test the affected functionality and run the unit tests for the code you changed
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
cd folder/with/changed/files
2015-12-29 19:06:40 +00:00
go test -v
2020-10-13 21:49:58 +00:00
Note that you may need to make a test remote, e.g. `TestSwift` for some
2015-12-29 19:06:40 +00:00
of the unit tests.
2021-07-05 15:03:53 +00:00
This is typically enough if you made a simple bug fix, otherwise please read the rclone [testing ](#testing ) section too.
2015-12-29 19:06:40 +00:00
Make sure you
2021-07-05 15:03:53 +00:00
* Add [unit tests ](#testing ) for a new feature.
2018-09-21 17:17:32 +00:00
* Add [documentation ](#writing-documentation ) for a new feature.
2021-07-05 15:03:53 +00:00
* [Commit your changes ](#committing-your-changes ) using the [message guideline ](#commit-messages ).
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
When you are done with that push your changes to Github:
2015-12-29 19:06:40 +00:00
2021-02-24 19:16:19 +00:00
git push -u origin my-new-feature
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
and open the GitHub website to [create your pull
2015-12-29 19:06:40 +00:00
request](https://help.github.com/articles/creating-a-pull-request/).
2021-07-05 15:03:53 +00:00
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 ](#basing-your-changes-on-the-latest-master ) or [squash your commits ](#squashing-your-commits ).
## Using Git and Github ##
### Committing your changes ###
Follow the guideline for [commit messages ](#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 ](#replacing-your-previously-pushed-commits ).
### Replacing 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:
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
git push --force origin my-new-feature
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
### Basing your changes on the latest master ###
To base your changes on the latest version of the [rclone master ](https://github.com/rclone/rclone/tree/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 ](#replacing-your-previously-pushed-commits ).
### Squashing your 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 ](#replacing-your-previously-pushed-commits ).
Tip: You may like to use `git rebase -i master` if you are experienced or have a more complex situation.
### GitHub Continuous Integration ###
2018-09-07 09:17:27 +00:00
2020-01-08 17:27:44 +00:00
rclone currently uses [GitHub Actions ](https://github.com/rclone/rclone/actions ) to build and test the project, which should be automatically available for your fork too from the `Actions` tab in your repository.
2018-09-07 09:17:27 +00:00
2015-12-29 19:06:40 +00:00
## Testing ##
2021-07-05 15:03:53 +00:00
### Quick testing ###
2015-12-29 19:06:40 +00:00
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 ./...
2021-02-24 19:16:19 +00:00
2021-07-05 15:03:53 +00:00
You can also use `make` , if supported by your platform
make quicktest
The quicktest is [automatically run by GitHub ](#github-continuous-integration ) when you push your branch to GitHub.
### Backend testing ###
2015-12-29 19:06:40 +00:00
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.
2018-01-20 09:52:56 +00:00
cd backend/drive
2015-12-29 19:06:40 +00:00
go test -v
2021-02-24 19:16:19 +00:00
You can then run the integration tests which test all of rclone's
operations. Normally these get run against the local file system,
2015-12-29 19:06:40 +00:00
but they can be run against any of the remotes.
2018-01-20 09:52:56 +00:00
cd fs/sync
2015-12-29 19:06:40 +00:00
go test -v -remote TestDrive:
2019-08-08 18:58:02 +00:00
go test -v -remote TestDrive: -fast-list
2015-12-29 19:06:40 +00:00
2018-01-20 09:52:56 +00:00
cd fs/operations
go test -v -remote TestDrive:
2018-09-29 13:48:29 +00:00
If you want to use the integration test framework to run these tests
2021-02-24 19:16:19 +00:00
altogether with an HTML report and test retries then from the
2018-09-29 13:48:29 +00:00
project root:
2019-07-28 17:47:38 +00:00
go install github.com/rclone/rclone/fstest/test_all
2018-09-29 13:48:29 +00:00
test_all -backend drive
2021-07-05 15:03:53 +00:00
### Full integration testing ###
2015-12-29 19:06:40 +00:00
If you want to run all the integration tests against all the remotes,
2018-01-20 09:52:56 +00:00
then change into the project root and run
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
make check
2018-01-20 09:52:56 +00:00
make test
2015-12-29 19:06:40 +00:00
2021-07-05 15:03:53 +00:00
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
2018-01-26 09:36:33 +00:00
find the results at https://pub.rclone.org/integration-tests/
2018-01-12 16:30:54 +00:00
## Code Organisation ##
Rclone code is organised into a small number of top level directories
with modules beneath.
* backend - the rclone backends for interfacing to cloud providers -
* all - import this to load all the cloud providers
* ...providers
* bin - scripts for use while building or maintaining rclone
* cmd - the rclone commands
* all - import this to load all the commands
* ...commands
cmdtest: end-to-end test for commands, flags and environment variables
There was no easy way to automatically test the end-to-end functionality
of commands, flags, environment variables etc.
The need for end-to-end testing was highlighted by the issues fixed
in #5341. There was no automated test to continually verify current
behaviour, nor a framework to quickly test the correctness of the fixes.
This change adds an end-to-end testing framework in the cmdtest folder.
It has some simple examples in func TestCmdTest in cmdtest_test.go. The
tests should be readable by anybody familiar with rclone and look like
this:
// Test the rclone version command with debug logging (-vv)
out, err = rclone("version", "-vv")
if assert.NoError(t, err) {
assert.Contains(t, out, "rclone v")
assert.Contains(t, out, "os/version:")
assert.Contains(t, out, " DEBUG : ")
}
The end-to-end tests are executed just like the Go unit tests, that is:
go test ./cmdtest -v
The change also contains a thorough test of environment variables in
environment_test.go.
Thanks to @ncw for encouragement and introduction to the TestMain trick.
2021-06-04 08:56:40 +00:00
* cmdtest - end-to-end tests of commands, flags, environment variables,...
2018-01-12 16:30:54 +00:00
* docs - the documentation and website
* content - adjust these docs only - everything else is autogenerated
2020-02-10 12:31:45 +00:00
* command - these are auto generated - edit the corresponding .go file
2018-01-12 16:30:54 +00:00
* fs - main rclone definitions - minimal amount of code
* accounting - bandwidth limiting and statistics
* asyncreader - an io.Reader which reads ahead
* config - manage the config file and flags
* driveletter - detect if a name is a drive letter
* filter - implements include/exclude filtering
* fserrors - rclone specific error handling
* fshttp - http handling for rclone
* fspath - path handling for rclone
2020-05-20 10:39:20 +00:00
* hash - defines rclone's hash types and functions
2018-01-12 16:30:54 +00:00
* list - list a remote
* log - logging facilities
* march - iterates directories in lock step
* object - in memory Fs objects
2020-10-13 21:49:58 +00:00
* operations - primitives for sync, e.g. Copy, Move
2018-01-12 16:30:54 +00:00
* sync - sync directories
* walk - walk a directory
* fstest - provides integration test framework
* fstests - integration tests for the backends
* mockdir - mocks an fs.Directory
* mockobject - mocks an fs.Object
* test_all - Runs integration tests for everything
2020-10-13 22:07:12 +00:00
* graphics - the images used in the website, etc.
2018-01-12 16:30:54 +00:00
* lib - libraries used by the backend
2018-01-26 09:36:33 +00:00
* atexit - register functions to run when rclone exits
2018-01-12 16:30:54 +00:00
* dircache - directory ID to name caching
* oauthutil - helpers for using oauth
* pacer - retries with backoff and paces operations
* readers - a selection of useful io.Readers
* rest - a thin abstraction over net/http for REST
* vfs - Virtual FileSystem layer for implementing rclone mount and similar
2017-01-29 09:47:28 +00:00
## Writing Documentation ##
If you are adding a new feature then please update the documentation.
2018-10-01 19:48:54 +00:00
If you add a new general flag (not for a backend), then document it in
2017-01-29 09:47:28 +00:00
`docs/content/docs.md` - the flags there are supposed to be in
2018-10-01 19:48:54 +00:00
alphabetical order.
If you add a new backend option/flag, then it should be documented in
the source file in the `Help:` field. The first line of this is used
for the flag help, the remainder is shown to the user in `rclone
config` and is added to the docs with `make backenddocs` .
2017-01-29 09:47:28 +00:00
The only documentation you need to edit are the `docs/content/*.md`
2021-02-24 19:16:19 +00:00
files. The `MANUAL.*` , `rclone.1` , web site, etc. are all auto generated
2017-01-29 09:47:28 +00:00
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.
2020-10-13 21:49:58 +00:00
Documentation for rclone sub commands is with their code, e.g.
2017-01-29 09:47:28 +00:00
`cmd/ls/ls.go` .
2020-02-01 13:44:03 +00:00
Note that you can use [GitHub's online editor ](https://help.github.com/en/github/managing-files-in-a-repository/editing-files-in-another-users-repository )
for small changes in the docs which makes it very easy.
2015-12-29 19:06:40 +00:00
## Making a release ##
There are separate instructions for making a release in the RELEASE.md
2017-01-29 09:47:28 +00:00
file.
2015-12-29 19:06:40 +00:00
2017-07-23 12:23:42 +00:00
## Commit messages ##
Please make the first line of your commit message a summary of the
2018-09-21 17:17:32 +00:00
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!
2017-07-23 12:23:42 +00:00
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.
2018-09-21 17:17:32 +00:00
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.
2017-07-23 12:23:42 +00:00
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
```
2017-05-11 14:39:54 +00:00
## Adding a dependency ##
2016-11-19 10:09:50 +00:00
2018-08-28 14:30:47 +00:00
rclone uses the [go
modules](https://tip.golang.org/cmd/go/#hdr-Modules__module_versions__and_more)
support in go1.11 and later to manage its dependencies.
2016-11-19 10:09:50 +00:00
2021-02-24 19:16:19 +00:00
rclone can be built with modules outside of the `GOPATH` .
2018-08-28 14:30:47 +00:00
To add a dependency `github.com/ncw/new_dependency` see the
2020-03-04 14:01:25 +00:00
instructions below. These will fetch the dependency and add it to
`go.mod` and `go.sum` .
2018-08-28 14:30:47 +00:00
2018-09-21 17:17:32 +00:00
GO111MODULE=on go get github.com/ncw/new_dependency
2017-05-11 14:39:54 +00:00
2018-08-28 14:30:47 +00:00
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.
2017-05-11 14:39:54 +00:00
2020-03-04 14:01:25 +00:00
Please check in the changes generated by `go mod` including `go.mod`
and `go.sum` in the same commit as your other changes.
2017-05-11 14:39:54 +00:00
## Updating a dependency ##
If you need to update a dependency then run
2018-09-21 17:17:32 +00:00
GO111MODULE=on go get -u github.com/pkg/errors
2017-05-11 14:39:54 +00:00
2020-05-20 10:39:20 +00:00
Check in a single commit as above.
2017-05-11 14:39:54 +00:00
## Updating all the dependencies ##
In order to update all the dependencies then run `make update` . This
2018-08-28 14:30:47 +00:00
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.
2017-05-11 14:39:54 +00:00
This should be done early in the release cycle to pick up new versions
of packages in time for them to get some testing.
2017-07-23 12:23:42 +00:00
## Updating a backend ##
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.
2015-12-29 19:06:40 +00:00
## Writing a new backend ##
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.
Research
* Look at the interfaces defined in `fs/fs.go`
* Study one or more of the existing remotes
Getting going
2018-01-12 16:30:54 +00:00
* Create `backend/remote/remote.go` (copy this from a similar remote)
2017-09-19 15:09:43 +00:00
* box is a good one to start from if you have a directory based remote
2017-07-08 22:31:58 +00:00
* b2 is a good one to start from if you have a bucket based remote
2018-01-12 16:30:54 +00:00
* Add your remote to the imports in `backend/all/all.go`
2017-07-25 14:18:13 +00:00
* HTTP based remotes are easiest to maintain if they use rclone's rest module, but if there is a really good go SDK then use that instead.
2017-09-19 15:09:43 +00:00
* Try to implement as many optional methods as possible as it makes the remote more usable.
2020-01-17 14:58:23 +00:00
* Use lib/encoder to make sure we can encode any path name and `rclone info` to help determine the encodings needed
2019-09-23 11:55:28 +00:00
* `rclone purge -v TestRemote:rclone-info`
2020-08-08 17:02:18 +00:00
* `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`
2019-09-23 11:55:28 +00:00
* open `remote.csv` in a spreadsheet and examine
2015-12-29 19:06:40 +00:00
Unit tests
* Create a config entry called `TestRemote` for the unit tests to use
2018-04-07 17:48:11 +00:00
* Create a `backend/remote/remote_test.go` - copy and adjust your example remote
2015-12-29 19:06:40 +00:00
* Make sure all tests pass with `go test -v`
Integration tests
2018-09-29 13:48:29 +00:00
* Add your backend to `fstest/test_all/config.yaml`
2019-01-12 18:28:51 +00:00
* Once you've done that then you can use the integration test framework from the project root:
* go install ./...
2019-10-24 11:35:50 +00:00
* test_all -backends remote
2019-01-12 18:28:51 +00:00
Or if you want to run the integration tests manually:
2015-12-29 19:06:40 +00:00
* Make sure integration tests pass with
2018-01-12 16:30:54 +00:00
* `cd fs/operations`
2017-06-20 14:56:48 +00:00
* `go test -v -remote TestRemote:`
2018-01-26 09:36:33 +00:00
* `cd fs/sync`
* `go test -v -remote TestRemote:`
2019-08-08 18:58:02 +00:00
* If your remote defines `ListR` check with this also
2017-06-20 14:56:48 +00:00
* `go test -v -remote TestRemote: -fast-list`
2015-12-29 19:06:40 +00:00
2018-01-26 09:36:33 +00:00
See the [testing ](#testing ) section for more information on integration tests.
2019-09-30 11:26:33 +00:00
Add your fs to the docs - you'll need to pick an icon for it from
[fontawesome ](http://fontawesome.io/icons/ ). Keep lists of remotes in
2020-10-13 21:49:58 +00:00
alphabetical order of full name of remote (e.g. `drive` is ordered as
2019-09-30 11:26:33 +00:00
`Google Drive` ) but with the local file system last.
2015-12-29 19:06:40 +00:00
2018-10-12 15:46:15 +00:00
* `README.md` - main GitHub page
2018-10-01 19:48:54 +00:00
* `docs/content/remote.md` - main docs page (note the backend options are automatically added to this file with `make backenddocs` )
2019-09-30 11:26:33 +00:00
* make sure this has the `autogenerated options` comments in (see your reference backend docs)
* update them with `make backenddocs` - revert any changes in other backends
2015-12-29 19:06:40 +00:00
* `docs/content/overview.md` - overview docs
2016-01-07 15:20:32 +00:00
* `docs/content/docs.md` - list of remotes in config section
2020-05-15 17:17:46 +00:00
* `docs/content/_index.md` - front page of rclone.org
2015-12-29 19:06:40 +00:00
* `docs/layouts/chrome/navbar.html` - add it to the website navigation
2016-10-04 10:37:31 +00:00
* `bin/make_manual.py` - add the page to the `docs` constant
2019-09-23 00:41:02 +00:00
2019-09-30 11:26:33 +00:00
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.
2019-09-23 00:41:02 +00:00
## Writing a plugin ##
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.
Usage
- Naming
- Plugins names must have the pattern `librcloneplugin_KIND_NAME.so` .
- `KIND` should be one of `backend` , `command` or `bundle` .
- Example: A plugin with backend support for PiFS would be called
`librcloneplugin_backend_pifs.so` .
- Loading
- Supported on macOS & Linux as of now. ([Go issue for Windows support](https://github.com/golang/go/issues/19282))
- Supported on rclone v1.50 or greater.
- All plugins in the folder specified by variable `$RCLONE_PLUGIN_PATH` are loaded.
- If this variable doesn't exist, plugin support is disabled.
- Plugins must be compiled against the exact version of rclone to work.
(The rclone used during building the plugin must be the same as the source of rclone)
2021-02-24 19:16:19 +00:00
2019-09-23 00:41:02 +00:00
Building
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.
[Go reference ](https://godoc.org/github.com/rclone/rclone/lib/plugin )
[Minimal example ](https://gist.github.com/terorie/21b517ee347828e899e1913efc1d684f )