Contributing to rclone

This is a short guide on how to contribute things to rclone.

Reporting a bug

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 (e.g. output from rclone version)
• Which OS you are using and how many bits (e.g. Windows 10, 64 bit)
• 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)
  • if the log contains secrets then edit the file with a text editor first to obscure them

Submitting a new feature or bug fix

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

• Add unit tests for a new feature.
• Add documentation for a new feature.
• Commit your changes using the commit message guidelines.

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.

AI-assisted contributions

You are welcome to use AI coding assistants (Claude Code, Codex, Cursor, Gemini CLI, and similar) to help write your contribution. Rclone has an AGENTS.md file at the top of the repository describing the project's conventions; point your tool at it so the code it produces matches rclone's style.

However, the same standard applies to every pull request whether or not a tool was involved: you are responsible for the code you submit. Before you open a pull request please make sure that:

• You understand every line of the change and can explain why it is correct. If a reviewer asks a question about it, you should be able to answer without going back to the tool.
• You have actually built and run it. At a minimum go build and make quicktest must pass, and for a backend change you should run the backend tests against a real remote where you can.
• The change is a genuine fix or feature that you have verified solves the problem, not a plausible-looking guess. Unverified, AI-generated pull requests that do not compile, do not pass the tests, invent APIs that do not exist, or do not actually do what the description claims waste maintainer time and are likely to be closed.
• You have trimmed the comments. AI tools tend to add verbose comments that restate what the code plainly does or narrate the change being made; please cut these down to match the code commenting style.

In short: an AI assistant is a tool to help you contribute, not a substitute for understanding and testing your own work.

Using Git and GitHub

Committing your changes

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.

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:

git push --force origin my-new-feature 

Basing your changes on the latest master

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.

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.

Tip: You may like to use git rebase -i master if you are experienced or have a more complex situation.

GitHub Continuous Integration

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.

Testing

Code quality tests

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).

Quick testing

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.

Backend testing

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 run ./fstest/test_all -backends drive

Full integration testing

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://integration.rclone.org

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 tests of commands, flags, environment variables,...
• docs - the documentation and website
  • content - adjust these docs only, except those marked autogenerated or portions marked autogenerated where the corresponding .go file must be edited instead, and everything else is autogenerated
    • commands - these are auto-generated, edit the corresponding .go file
• 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
  • hash - defines rclone's hash types and functions
  • list - list a remote
  • log - logging facilities
  • march - iterates directories in lock step
  • object - in memory Fs objects
  • operations - primitives for sync, e.g. Copy, Move
  • 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
• graphics - the images used in the website, etc.
• lib - libraries used by the backend
  • atexit - register functions to run when rclone exits
  • 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
• librclone - in memory interface to rclone's API for embedding rclone
• vfs - Virtual FileSystem layer for implementing rclone mount and similar

Writing Documentation

If you are adding a new feature then please update the documentation.

The documentation sources are generally in Markdown format, in conformance with the CommonMark specification and compatible with GitHub Flavored Markdown (GFM). The markdown format and style is checked as part of the lint operation that runs automatically on pull requests, to enforce standards and consistency. This is based on the markdownlint tool by David Anson, which can also be integrated into editors so you can perform the same checks while writing. It generally follows Ciro Santilli's Markdown Style Guide, which is good source if you want to know more.

HTML pages, served as website <rclone.org>, are generated from the Markdown, using Hugo. Note that when generating the HTML pages, there is currently used a different algorithm for generating header anchors than what GitHub uses for its Markdown rendering. For example, in the HTML docs generated by Hugo any leading - characters are ignored, which means when linking to a header with text --config string we therefore need to use the link #config-string in our Markdown source, which will not work in GitHub's preview where #--config-string would be the correct link.

Most of the documentation are written directly in text files with extension .md, mainly within folder docs/content. Note that several of such files are autogenerated (e.g. the command documentation, and docs/content/flags.md), or contain autogenerated portions (e.g. the backend documentation under docs/content/commands). These are marked with an autogenerated comment. The sources of the autogenerated text are usually Markdown formatted text embedded as string values in the Go source code, so you need to locate these and edit the .go file instead. The MANUAL.*, rclone.1 and other text files in the root of the repository are also autogenerated. The autogeneration of files, and the website, will be done 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.

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:

• Start with the most important information about the option, as a single sentence on a single line.
  • This text will be used for the command-line flag help.
  • It will be combined with other information, such as any default value, and the result will look odd if not written as a single sentence.
  • It should end with a period/full stop character, which will be shown in docs but automatically removed when producing the flag help.
  • Try to keep it below 80 characters, to reduce text wrapping in the terminal.
• More details can be added in a new paragraph, after an empty line ("\n\n").
  • Like with docs generated from Markdown, a single line break is ignored and two line breaks creates a new paragraph.
  • This text will be shown to the user in rclone config and in the docs (where it will be added by make backenddocs, normally run some time before next release).
• To create options of enumeration type use the Examples: field.
  • Each example value have their own 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.
• You can run make backenddocs to verify the resulting Markdown.
  • This will update the autogenerated sections of the backend docs Markdown files under docs/content.
  • It requires you to have Python installed.
  • The backenddocs make target runs the Python script bin/make_backend_docs.py, and you can also run this directly, optionally with the name of a backend as argument to only update the docs for a specific backend.
  • Do not commit the updated Markdown files. This operation is run as part of the release process. Since any manual changes in the autogenerated sections of the Markdown files will then be lost, we have a pull request check that reports error for any changes within the autogenerated sections. Should you have done manual changes outside of the autogenerated sections they must be committed, of course.
• You can run make serve to verify the resulting website.
  • This will build the website and serve it locally, so you can open it in your web browser and verify that the end result looks OK. Check specifically any added links, also in light of the note above regarding different algorithms for generated header anchors.
  • It requires you to have the Hugo tool available.
  • The serve make target depends on the website target, which runs the hugo command from the docs directory to build the website, and then it serves the website locally with an embedded web server using a command hugo server --logLevel info -w --disableFastRender --ignoreCache, so you can run similar Hugo commands directly as well.

When writing documentation for an entirely new backend, see backend documentation.

If you are updating documentation for a command, you must do that in the command source 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. Just remember the caveat when linking to header anchors, noted above, which means that GitHub's Markdown preview may not be an entirely reliable verification of the results.

After your changes have been merged, you can verify them on tip.rclone.org. This site is updated daily with the current state of the master branch at 07:00 UTC. The changes will be on the main rclone.org site once they have been included in a release.

Making a release

There are separate instructions for making a release in the RELEASE.md file.

Commit messages

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