# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

Rclone ("rsync for cloud storage") is a command-line Go program that syncs files and directories to/from 70+ cloud storage providers. Entry point is `rclone.go` → `cmd.Main()`. Current Go toolchain requirement is in `go.mod` (the `go` directive); check it before assuming a version.

## Build & install

```bash
go build                      # plain build
make                          # build with version metadata baked in (preferred on Unix)
make rclone                   # same as above, also installs into $(go env GOPATH)/bin
```

On Windows, `make rclone` also generates a version-stamped `.syso` resource file via `bin/resource_windows.go` before building, then deletes it. If you see a stray `resource_windows_*.syso` it was left behind by an interrupted build.

`-X github.com/rclone/rclone/fs.Version=$(TAG)` is passed via `-ldflags`; the version string the binary reports is built from `VERSION` + git metadata in the Makefile (`TAG := $(VERSION)$(VERSION_SUFFIX)$(TAG_BRANCH)`). Bump `VERSION` only via the `startdev`/`startstable` Makefile targets, not by hand.

## Tests

Rclone's tests run against **real backends** configured as `Test<Name>:` sections in the rclone config file. Tests requiring a missing section are skipped automatically — a clean `go test ./...` from a fresh checkout just runs the local-FS-only subset.

```bash
# Run a single package's tests
cd backend/drive && go test -v

# Run one test in one package
cd fs/sync && go test -v -run TestSync

# Quick test of everything (no remote creds needed; sets bogus config to force skips)
make quicktest

# Run a package's integration tests against a configured remote
cd fs/sync && go test -v -remote TestDrive:
cd fs/sync && go test -v -remote TestDrive: -fast-list   # exercise ListR path
cd fs/operations && go test -v -remote TestDrive:

# Full integration framework from repo root, one backend at a time
go run ./fstest/test_all -backends drive

# Race detector
make racequicktest
```

Backend test remotes are registered in `fstest/test_all/config.yaml`. Some tests there have `ignore:` entries that document intentional skips (e.g. B2 versioning makes certain purge tests impossible).

## Lint / quality

```bash
make check                    # golangci-lint + markdownlint, same as CI
golangci-lint run ./...       # Go only
bin/markdown-lint             # Markdown only
```

`.golangci.yml` enables: errcheck, govet, ineffassign, staticcheck, unused, gocritic, misspell, revive, unconvert, plus the `goimports` formatter. `gocritic` ruleguard rules live in `bin/rules.go`. golangci-lint v2 config format is in use.

## Architecture

Layered, with `fs/` as the contract layer:

- **`fs/`** — core interfaces and primitives. `fs.Fs`, `fs.Object`, `fs.DirInfo` (in `fs/types.go` and `fs/fs.go`) are the contracts every backend implements. Sub-packages:
  - `fs/operations` — primitives (`Copy`, `Move`, `MoveDir`, `check`, dedupe, listdirsorted, lsjson)
  - `fs/sync` — `sync.Sync` (one-way) and the pipe-based engine; also drives `bisync`
  - `fs/march` — walks two Fs trees in lock step, emitting diffs
  - `fs/filter` — include/exclude rules
  - `fs/config` — config file, flags, obscured creds, rc config; `configfile`/`configflags`/`configstruct`/`configmap` are sub-packages
  - `fs/fshttp` — rclone's `http.Client`/`Transport`; backends **must** use this to inherit `--dump`, `--tpslimit`, `--user-agent`, etc.
  - `fs/accounting`, `fs/cache`, `fs/fspath`, `fs/hash`, `fs/log`, `fs/rc` (+ `rcserver`)
- **`backend/`** — one subdirectory per provider (drive, s3, dropbox, sftp, local, …). `backend/all/all.go` imports them all via blank imports; `rclone.go` imports `backend/all`. There are virtual/wrapper backends too: `alias`, `archive`, `cache`, `chunker`, `combine`, `compress`, `crypt`, `hasher`, `union`.
- **`cmd/`** — one subdirectory per CLI subcommand (`copy`, `sync`, `mount`, `serve`, `bisync`, …). `cmd/all/all.go` registers them; `cmd/cmd.go` is the cobra entry point.
- **`lib/`** — cross-cutting libraries backends and fs both use: `rest` (thin net/http wrapper for REST APIs), `pacer` (retry/backoff), `dircache`, `oauthutil`, `encoder` (filename encoding), `readers`, `atexit`, `errcount`, `exitcode`, `multipart`, `plugin`, etc.
- **`vfs/`** — virtual filesystem layer for `mount`/`cmount`/`mountlib`/`nfsmount`.
- **`librclone/`** — embeddable in-memory API for users who want rclone as a library.
- **`fstest/`** — integration test framework: `fstests` (per-backend suite), `mockdir`/`mockobject`, `test_all` (driver that reads `config.yaml`).
- **`cmdtest/`** — end-to-end tests of CLI flags, env vars, exit codes.

`rclone.go` is intentionally tiny: it blank-imports `backend/all`, `cmd/all`, `lib/plugin`, then calls `cmd.Main()`.

## Conventions

**Commit messages** follow `<area>: <summary>` where `<area>` is the directory touched (`drive:`, `fs/sync:`, `mount:`, `completion:`). The changelog is generated from these first lines, so make them user-readable. Long form goes after a blank line, mentioning `Fixes #N` to auto-close.

**New backend layout** (see CONTRIBUTING.md "Writing a new backend"):
- Implement in a single `backend/<name>/<name>.go` — **do not** split into `fs.go` and `object.go`. The maintainers explicitly reject this for the >50 existing backends.
- Put API type definitions in `api/types.go`.
- Follow the structure of `backend/box` (directory-based) or `backend/b2` (bucket-based) exactly — same function names, same order, same comments.
- For HTTP backends, use `lib/rest` and the client from `fs/fshttp`. Don't roll your own transport.
- Register in `backend/all/all.go` and add to `fstest/test_all/config.yaml`.

**Backend options** are declared in Go with `Help:` fields that get rendered into docs and `--flag` help. See CONTRIBUTING.md "Writing Documentation" for the rules: first sentence on one line ≤80 chars, ends with period, more detail after a blank `"\n\n"`. The Markdown in `docs/content/<name>.md` between `<!-- autogenerated options start -->…<!-- autogenerated options stop -->` markers is regenerated by `bin/make_backend_docs.py` — never edit those regions by hand.

**Documentation autogeneration.** `MANUAL.md`, `MANUAL.html`, `MANUAL.txt`, `rclone.1`, `docs/content/flags.md`, `docs/content/commands/*.md`, and the autogenerated portions of backend docs are all produced from Go source by Makefile targets (`make doc`, `make commanddocs`, `make backenddocs`, `make rcdocs`). `bin/check_autogenerated_edits.py` runs in CI and rejects PRs that hand-edit those regions. You normally don't run these locally — they run during the release process. The `docs/` site is built with Hugo (`make serve` to preview).

**`go generate` is used** in `lib/transform` and `cmd/bisync` (see the `commanddocs` target). Run those before regenerating command docs.

**Configuration system.** Top-level flags live in `fs/config/configflags`. Backend options are defined per-backend via `Options` structs with `configstruct` tags and surfaced automatically. The `--config` flag points at the rclone.conf used both at runtime and for `Test<Name>:` test remotes.

**Version tagging.** Tags are GPG-signed (`make retag`). `make beta` / `make ci_beta` publish to `beta.rclone.org`. Full release flow is in `RELEASE.md`.