AGENTS.md

1# AGENTS.md
2 
3This file provides guidance to AI coding agents (e.g. Claude Code, Codex, Cursor, Gemini CLI, and similar tools) when working with code in this repository.
4 
5Rclone welcomes AI-assisted contributions, but the expectation is that you, the human submitter, understand every line you propose and have compiled and tested it against real rclone code - not just generated it. See the "AI-assisted contributions" section of [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
6 
7## Project Overview
8 
9Rclone is a command-line program to sync files and directories to and from cloud storage providers. It's written in Go and supports 70+ backends (cloud storage systems). Think "rsync for cloud storage".
10 
11## General Notes
12 
13**We take backwards compatibility very seriously.** PRs should not change the observable behaviour of existing commands, flags or rc API without very good reason. Rclone does not try to preserve a stable Go API but try not to change it gratuitously.
14 
15Rclone operates with a lot of different backends, so **compatibility is key**. It is the backend integration tests which guarantee that compatibility. Changes should consider both known and unknown backends and should take care not to break functionality of existing installations.
16 
17The core parts of rclone under `fs` and `vfs` need to work with all backends and **backend specific hacks won't be merged**. Fixes likely need to go in the relevant backend or if new behaviour is really needed, a new Feature flag needs to be added.
18 
19**Changes should be kept to the minimum.** Work hard to make the most elegant, smallest change you can. Do not refactor or re-order code unless necessary as this makes review more challenging. Re-use existing test scaffolding, existing or library routines (e.g. `lib`) where possible.
20 
21Make sure added tests **actually test the code you have written** and test the intention behind the change. If you are fixing a problem, write the tests first to reproduce the problem before starting on the fix.
22 
23## Build and Test Commands
24 
25```bash
26# Build rclone (simple)
27go build
28 
29# Build with version info (preferred)
30make
31 
32# Run all unit tests (no cloud credentials needed)
33make quicktest
34# or equivalently:
35RCLONE_CONFIG="/notfound" go test ./...
36 
37# Run tests for a specific package
38cd backend/memory && go test -v
39# or from root:
40go test -v ./backend/memory/
41 
42# Run a single test
43go test -v -run TestIntegration/FsCheckWrap ./backend/memory/
44 
45# Run tests with race detector
46make racequicktest
47 
48# Lint (requires golangci-lint)
49golangci-lint run ./...
50 
51# Run backend integration tests (requires configured TestRemote remote)
52cd backend/drive && go test -v
53# Run sync/operations integration tests against a remote
54cd fs/sync && go test -v -remote TestDrive:
55cd fs/operations && go test -v -remote TestDrive:
56 
57# Run integration tests via test framework
58go run ./fstest/test_all -backends drive
59```
60 
61## Architecture
62 
63### Entry Point and Plugin Registration
64 
65`rclone.go` is the main entry point. It imports `backend/all` and `cmd/all` which use Go's `init()` pattern to register all backends and commands. Each backend calls `fs.Register()` with a `fs.RegInfo` struct during init.
66 
67### Core Interfaces (`fs/`)
68 
69The `fs` package defines the core abstractions:
70- **`fs.Fs`** (`fs/types.go`): The filesystem interface every backend must implement (List, NewObject, Put, Mkdir, Rmdir).
71- **`fs.Object`** (`fs/types.go`): Interface for a file/object (Open, Update, Remove, SetModTime).
72- **`fs.Features`** (`fs/features.go`): Optional capabilities a backend can declare (Purge, Copy, Move, DirMove, etc.). Backends set function pointers for operations they support; nil means not supported.
73- **`fs.RegInfo`** (`fs/registry.go`): Registration metadata for a backend including its name, config options, and NewFs constructor.
74 
75### Backend Structure (`backend/`)
76 
77Each backend is a single Go package (e.g., `backend/s3/`, `backend/drive/`). Key conventions:
78- Main implementation in a single file (e.g., `s3.go`) - **do not** split into `fs.go`/`object.go`.
79- API types go in a separate `api/types.go` file.
80- Test file (e.g., `s3_test.go`) uses `fstests.Run()` from `fstest/fstests` for standardized integration tests.
81- Register in `backend/all/all.go` via blank import.
82- HTTP-based backends should use `lib/rest` for HTTP calls and `fs/fshttp` for the HTTP client.
83- Use `lib/dircache` for directory-ID-based remotes, `lib/oauthutil` for OAuth, `lib/pacer` for rate limiting.
84 
85### Command Structure (`cmd/`)
86 
87Each command is a package under `cmd/` registered in `cmd/all/all.go` via blank import. Commands use cobra via `cmd.Main()`.
88 
89### Key Subsystems
90 
91- **`fs/operations/`**: Core file operations (Copy, Move, Delete, etc.)
92- **`fs/sync/`**: Directory sync logic
93- **`fs/march/`**: Parallel directory tree walker used by sync
94- **`fs/filter/`**: Include/exclude filtering
95- **`fs/accounting/`**: Transfer statistics and bandwidth limiting
96- **`fs/config/`**: Configuration file management
97- **`vfs/`**: Virtual filesystem layer (used by mount, serve)
98- **`librclone/`**: C-compatible library interface for embedding rclone
99- **`fstest/`**: Integration test framework; `fstest/fstests/` has the generic backend test suite
100 
101## Commit Message Convention
102 
103Prefix with the directory of the change, then a colon: `drive: add team drive support - fixes #885`. For cross-cutting changes use a broader prefix like `fs` or `operations`.
104 
105Make the first line of your commit message a summary of the change that a user (not a developer) of rclone would like to read. So write `drive: fix server side copy of big files` instead of `drive: no longer set the MimeType in Move or Copy`. This is important because these lines go into the change log which is read by users.
106 
107## Code Commenting Style
108 
109Comments describe the code as it is now, for a future reader who has no knowledge of the change that introduced it.
110 
111Every exported type, function, field, and constant has a **godoc comment** that starts with its name and is phrased as a present-tense statement of what it is or does (`// Mkdir makes the directory (container, bucket)`)
112 
113**Document the contract** callers need - preconditions, what's returned, which sentinel errors are returned and when, and any "shouldn't return an error if it already exists" style caveats - rather than the implementation.
114 
115**Keep comments terse**: a single line for most things, with extra paragraphs (separated by blank `//` lines) reserved for genuine subtlety.
116 
117Inline comments inside function bodies should **explain why** - a non-obvious API quirk, a workaround, a gotcha, or an ordering constraint - and may cite an external reference (forum thread, vendor docs, RFC) when that's what makes the behaviour non-obvious; skip comments that merely restate what the code plainly does.
118 
119Use `FIXME` and `TODO` for known shortcomings.
120 
121**Do not write comments that narrate the change itself** or compare against the previous behaviour (no "now we also handle...", "changed to...", "previously this returned...", or references to bug/PR numbers in the code) - that context belongs in the commit message, not in source that will outlive the change.
122 
123Code comments should only refer to **current** behaviour - and shouldn't describe behaviour that is trivially deducible from reading the code.
124 
125## Linting Configuration
126 
127Uses golangci-lint v2 with config in `.golangci.yml`. Enabled linters: errcheck, govet, ineffassign, staticcheck, unused, gocritic, misspell, revive, unconvert. The `goimports` formatter is also enabled.
128 
129## Documentation
130 
131- Backend option docs come from `Help:` fields in the Go source Options structs, not from markdown files.
132- Command docs are in the command source code (e.g., `cmd/ls/ls.go`).
133- Don't commit autogenerated doc changes from `make backenddocs` or `make commanddocs`.
134- Website docs are in `docs/content/` as markdown, built with Hugo (`make serve` to preview).
135