rustfmt subtree sync procedure

Note that rustfmt has not migrated to josh yet, so the git subtree sync is somewhat involved. This procedure is mostly adapted from the clippy subtree sync process at https://doc.rust-lang.org/stable/clippy/development/infrastructure/sync.html, but adapted for rustfmt. We are keeping a separate copy of the instructions for rustfmt in case clippy moves off of git subtree in the mean time (and also slightly adjusted to be rustfmt-specific.

Tooling

The git-subtree tooling still has a bug that prevents it from working properly with the rust-lang/rust repository. This means that you need to build and use a patched version of git-subtree.

On Linux, place git-subtree under /usr/lib/git-core (make sure to keep a backup copy of the 'standard' git-subtree), and make sure it has proper permissions:

$ sudo cp --backup /path/to/patched/git-subtree.sh /usr/lib/git-core/git-subtree
$ sudo chmod --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree
$ sudo chown --reference=/usr/lib/git-core/git-subtree~ /usr/lib/git-core/git-subtree

$ ulimit -s 60000

$ git remote add upstream git@github.com:rust-lang/rustfmt

Subtree push direction: syncing changes from rust-lang/rust to rustfmt

1. Acquire a checkout of rust-lang/rust

Either acquire a clone of rust-lang/rust, or if you already have a checkout, make sure the checkout is up-to-date via git fetch.

2. Checkout the commit from the latest available nightly

You can fetch the commit hash of the latest available nightly by inspecting rustup check output.

3. Sync changes from the rust-copy of rustfmt to your rustfmt fork

$ git subtree push -P src/tools/rustfmt /path/to/rustfmt/checkout subtree-push

Most of the time, you will need to create a merge commit in the rustfmt repository. Note that this must be done in the subtree repo (i.e. rustfmt repo) and not in the rust-copy of rustfmt.

Assuming the upstream remote is the rust-lang/rust remote:

$ git fetch upstream
$ git switch subtree-push
$ git merge upstream/main --no-ff

4. Bump the nightly toolchain version in the rustfmt repository

Using the same latest nightly date (that you can obtain by inspecting rustup check output), manually edit rust-toolchain:

 [toolchain]
-channel = "nightly-2025-04-02"
+channel = "nightly-$LATEST_NIGHTLY_DATE"
 components = ["llvm-tools", "rustc-dev"]

Substituting $LATEST_NIGHTLY_DATE with the latest nightly date.

Create a separate commit dedicated to making the rust-toolchain change. You can use the following commit message template.

rust-toolchain bump commit message template

chore: bump rustfmt toolchain to nightly-$LATEST_NIGHTLY_DATE

Bumping the toolchain version as part of a git subtree push.

Before:

```
$CURRENT_NIGHTLY_VERSION-nightly ($CURRENT_NIGHTLY_HASH $CURRENT_NIGHTLY_DATE)
```

After:

```
$LATEST_NIGHTLY_VERSION-nightly ($LATEST_NIGHTLY_HASH $LATEST_NIGHTLY_DATE)
```

Substituting the placeholders with the right information.

5. Open a PR against rustfmt

And wait for the sync PR to be merged. The rustfmt maintainers will run Diff Check against the PR to catch any unexpected formatting changes.

• Maintainers should trigger Diff-Check for the combinations of Edition {2021, 2024} x Style Edition {2021, 2024}.

Once Diff Check failures are investigated and are resolved, the PR can then be merged.

For the PR:

• Use the title subtree-push nightly-$LATEST_NIGHTLY_DATE for consistency with previous subtree-pushes.
• Include a copy of the bump commit message in the PR description for quick reference. Feel free to include additional notes that might be helpful for the maintainers when reviewing.

Make sure to minimize the time between the subtree-push direction and the subtree-pull direction to avoid unnecessary complications.

5. (Where applicable) Update changelog and bump rustfmt version number

Where applicable, we may need to update the CHANGELOG entries with merged PRs (both in rustfmt repository and also in the rust-lang/rust rustfmt subtree that was included in the subtree-push merge), and then bump rustfmt version number.

Subtree pull direction: syncing from rustfmt to rust-lang/rust

1. Make sure latest main of rust-lang/rust is checked out

2. Sync rustfmt main to the rust-copy of rustfmt

$ git switch -c rustfmt-subtree-update
$ git subtree pull -P src/tools/rustfmt /path/to/rustfmt/checkout main

3. Open a PR against rust-lang/rust

Use the PR title

rustfmt subtree update

so that triagebot will not warn against the PR containing a merge commit, and makes it easy for rustfmt maintainers to discover.

Back link to the rustfmt subtree-push PR as helpful context.