Merge pull request #2491 from Kobzol/switch-to-rustc-josh-sync

8 files changed, 57 insertions, 820 deletions

diff --git a/src/doc/rustc-dev-guide/.github/workflows/rustc-pull.yml b/src/doc/rustc-dev-guide/.github/workflows/rustc-pull.yml
index 1e430d8b4e6..7190fc733db 100644
--- a/src/doc/rustc-dev-guide/.github/workflows/rustc-pull.yml
+++ b/src/doc/rustc-dev-guide/.github/workflows/rustc-pull.yml
@@ -24,11 +24,10 @@ jobs:
         run: rustup update stable
       - uses: Swatinem/rust-cache@v2
         with:
-          workspaces: "josh-sync"
           # Cache the josh directory with checked out rustc
-          cache-directories: "/home/runner/.cache/rustc-dev-guide-josh"
-      - name: Install josh
-        run: RUSTFLAGS="--cap-lints warn" cargo install josh-proxy --git https://github.com/josh-project/josh --tag r24.10.04
+          cache-directories: "/home/runner/.cache/rustc-josh"
+      - name: Install rustc-josh-sync
+        run: cargo install --locked --git https://github.com/rust-lang/josh-sync
       - name: Setup bot git name and email
         run: |
           git config --global user.name 'The rustc-dev-guide Cronjob Bot'
@@ -38,7 +37,7 @@ jobs:
         # Turn off -e to disable early exit
         shell: bash {0}
         run: |
-          cargo run --manifest-path josh-sync/Cargo.toml -- rustc-pull
+          rustc-josh-sync pull
           exitcode=$?
 
           # If no pull was performed, we want to mark this job as successful,
diff --git a/src/doc/rustc-dev-guide/README.md b/src/doc/rustc-dev-guide/README.md
index 0425c15f83c..5932da467ab 100644
--- a/src/doc/rustc-dev-guide/README.md
+++ b/src/doc/rustc-dev-guide/README.md
@@ -72,49 +72,6 @@ including the `<!-- toc -->` marker at the place where you want the TOC.
 
 ## Synchronizing josh subtree with rustc
 
-This repository is linked to `rust-lang/rust` as a [josh](https://josh-project.github.io/josh/intro.html) subtree. You can use the following commands to synchronize the subtree in both directions.
+This repository is linked to `rust-lang/rust` as a [josh](https://josh-project.github.io/josh/intro.html) subtree. You can use the [rustc-josh-sync](https://github.com/rust-lang/josh-sync) tool to perform synchronization.
 
-You'll need to install `josh-proxy` locally via
-
-```
-cargo install josh-proxy --git https://github.com/josh-project/josh --tag r24.10.04
-```
-Older versions of `josh-proxy` may not round trip commits losslessly so it is important to install this exact version.
-
-### Pull changes from `rust-lang/rust` into this repository
-
-1) Checkout a new branch that will be used to create a PR into `rust-lang/rustc-dev-guide`
-2) Run the pull command
-    ```
-    cargo run --manifest-path josh-sync/Cargo.toml rustc-pull
-    ```
-3) Push the branch to your fork and create a PR into `rustc-dev-guide`
-
-### Push changes from this repository into `rust-lang/rust`
-
-NOTE: If you use Git protocol to push to your fork of `rust-lang/rust`,
-ensure that you have this entry in your Git config,
-else the 2 steps that follow would prompt for a username and password:
-
-```
-[url "git@github.com:"]
-insteadOf = "https://github.com/"
-```
-
-1) Run the push command to create a branch named `<branch-name>` in a `rustc` fork under the `<gh-username>` account
-    ```
-    cargo run --manifest-path josh-sync/Cargo.toml rustc-push <branch-name> <gh-username>
-    ```
-2) Create a PR from `<branch-name>` into `rust-lang/rust`
-
-#### Minimal git config
-
-For simplicity (ease of implementation purposes), the josh-sync script simply calls out to system git. This means that the git invocation may be influenced by global (or local) git configuration.
-
-You may observe "Nothing to pull" even if you *know* rustc-pull has something to pull if your global git config sets `fetch.prunetags = true` (and possibly other configurations may cause unexpected outcomes).
-
-To minimize the likelihood of this happening, you may wish to keep a separate *minimal* git config that *only* has `[user]` entries from global git config, then repoint system git to use the minimal git config instead. E.g.
-
-```
-GIT_CONFIG_GLOBAL=/path/to/minimal/gitconfig GIT_CONFIG_SYSTEM='' cargo run --manifest-path josh-sync/Cargo.toml -- rustc-pull
-```
+You can find a guide on how to perform the synchronization [here](./src/external-repos.md#synchronizing-a-josh-subtree).
diff --git a/src/doc/rustc-dev-guide/josh-sync/Cargo.lock b/src/doc/rustc-dev-guide/josh-sync/Cargo.lock
deleted file mode 100644
index a8183a740db..00000000000
--- a/src/doc/rustc-dev-guide/josh-sync/Cargo.lock
+++ /dev/null
@@ -1,430 +0,0 @@
-# This file is automatically @generated by Cargo.
-# It is not intended for manual editing.
-version = 4
-
-[[package]]
-name = "anstream"
-version = "0.6.18"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8acc5369981196006228e28809f761875c0327210a891e941f4c683b3a99529b"
-dependencies = [
- "anstyle",
- "anstyle-parse",
- "anstyle-query",
- "anstyle-wincon",
- "colorchoice",
- "is_terminal_polyfill",
- "utf8parse",
-]
-
-[[package]]
-name = "anstyle"
-version = "1.0.10"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "55cc3b69f167a1ef2e161439aa98aed94e6028e5f9a59be9a6ffb47aef1651f9"
-
-[[package]]
-name = "anstyle-parse"
-version = "0.2.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3b2d16507662817a6a20a9ea92df6652ee4f94f914589377d69f3b21bc5798a9"
-dependencies = [
- "utf8parse",
-]
-
-[[package]]
-name = "anstyle-query"
-version = "1.1.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "79947af37f4177cfead1110013d678905c37501914fba0efea834c3fe9a8d60c"
-dependencies = [
- "windows-sys 0.59.0",
-]
-
-[[package]]
-name = "anstyle-wincon"
-version = "3.0.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2109dbce0e72be3ec00bed26e6a7479ca384ad226efdd66db8fa2e3a38c83125"
-dependencies = [
- "anstyle",
- "windows-sys 0.59.0",
-]
-
-[[package]]
-name = "anyhow"
-version = "1.0.95"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34ac096ce696dc2fcabef30516bb13c0a68a11d30131d3df6f04711467681b04"
-
-[[package]]
-name = "bitflags"
-version = "2.6.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b048fb63fd8b5923fc5aa7b340d8e156aec7ec02f0c78fa8a6ddc2613f6f71de"
-
-[[package]]
-name = "cfg-if"
-version = "1.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
-
-[[package]]
-name = "clap"
-version = "4.5.23"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3135e7ec2ef7b10c6ed8950f0f792ed96ee093fa088608f1c76e569722700c84"
-dependencies = [
- "clap_builder",
- "clap_derive",
-]
-
-[[package]]
-name = "clap_builder"
-version = "4.5.23"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "30582fc632330df2bd26877bde0c1f4470d57c582bbc070376afcd04d8cb4838"
-dependencies = [
- "anstream",
- "anstyle",
- "clap_lex",
- "strsim",
-]
-
-[[package]]
-name = "clap_derive"
-version = "4.5.18"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4ac6a0c7b1a9e9a5186361f67dfa1b88213572f427fb9ab038efb2bd8c582dab"
-dependencies = [
- "heck",
- "proc-macro2",
- "quote",
- "syn",
-]
-
-[[package]]
-name = "clap_lex"
-version = "0.7.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f46ad14479a25103f283c0f10005961cf086d8dc42205bb44c46ac563475dca6"
-
-[[package]]
-name = "colorchoice"
-version = "1.0.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5b63caa9aa9397e2d9480a9b13673856c78d8ac123288526c37d7839f2a86990"
-
-[[package]]
-name = "directories"
-version = "5.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a49173b84e034382284f27f1af4dcbbd231ffa358c0fe316541a7337f376a35"
-dependencies = [
- "dirs-sys",
-]
-
-[[package]]
-name = "dirs-sys"
-version = "0.4.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "520f05a5cbd335fae5a99ff7a6ab8627577660ee5cfd6a94a6a929b52ff0321c"
-dependencies = [
- "libc",
- "option-ext",
- "redox_users",
- "windows-sys 0.48.0",
-]
-
-[[package]]
-name = "getrandom"
-version = "0.2.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4567c8db10ae91089c99af84c68c38da3ec2f087c3f82960bcdbf3656b6f4d7"
-dependencies = [
- "cfg-if",
- "libc",
- "wasi",
-]
-
-[[package]]
-name = "heck"
-version = "0.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
-
-[[package]]
-name = "is_terminal_polyfill"
-version = "1.70.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7943c866cc5cd64cbc25b2e01621d07fa8eb2a1a23160ee81ce38704e97b8ecf"
-
-[[package]]
-name = "josh-sync"
-version = "0.0.0"
-dependencies = [
- "anyhow",
- "clap",
- "directories",
- "xshell",
-]
-
-[[package]]
-name = "libc"
-version = "0.2.169"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b5aba8db14291edd000dfcc4d620c7ebfb122c613afb886ca8803fa4e128a20a"
-
-[[package]]
-name = "libredox"
-version = "0.1.3"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c0ff37bd590ca25063e35af745c343cb7a0271906fb7b37e4813e8f79f00268d"
-dependencies = [
- "bitflags",
- "libc",
-]
-
-[[package]]
-name = "option-ext"
-version = "0.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
-
-[[package]]
-name = "proc-macro2"
-version = "1.0.92"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37d3544b3f2748c54e147655edb5025752e2303145b5aefb3c3ea2c78b973bb0"
-dependencies = [
- "unicode-ident",
-]
-
-[[package]]
-name = "quote"
-version = "1.0.38"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0e4dccaaaf89514f546c693ddc140f729f958c247918a13380cccc6078391acc"
-dependencies = [
- "proc-macro2",
-]
-
-[[package]]
-name = "redox_users"
-version = "0.4.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ba009ff324d1fc1b900bd1fdb31564febe58a8ccc8a6fdbb93b543d33b13ca43"
-dependencies = [
- "getrandom",
- "libredox",
- "thiserror",
-]
-
-[[package]]
-name = "strsim"
-version = "0.11.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
-
-[[package]]
-name = "syn"
-version = "2.0.93"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9c786062daee0d6db1132800e623df74274a0a87322d8e183338e01b3d98d058"
-dependencies = [
- "proc-macro2",
- "quote",
- "unicode-ident",
-]
-
-[[package]]
-name = "thiserror"
-version = "1.0.69"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
-dependencies = [
- "thiserror-impl",
-]
-
-[[package]]
-name = "thiserror-impl"
-version = "1.0.69"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn",
-]
-
-[[package]]
-name = "unicode-ident"
-version = "1.0.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "adb9e6ca4f869e1180728b7950e35922a7fc6397f7b641499e8f3ef06e50dc83"
-
-[[package]]
-name = "utf8parse"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
-
-[[package]]
-name = "wasi"
-version = "0.11.0+wasi-snapshot-preview1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423"
-
-[[package]]
-name = "windows-sys"
-version = "0.48.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "677d2418bec65e3338edb076e806bc1ec15693c5d0104683f2efe857f61056a9"
-dependencies = [
- "windows-targets 0.48.5",
-]
-
-[[package]]
-name = "windows-sys"
-version = "0.59.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
-dependencies = [
- "windows-targets 0.52.6",
-]
-
-[[package]]
-name = "windows-targets"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a2fa6e2155d7247be68c096456083145c183cbbbc2764150dda45a87197940c"
-dependencies = [
- "windows_aarch64_gnullvm 0.48.5",
- "windows_aarch64_msvc 0.48.5",
- "windows_i686_gnu 0.48.5",
- "windows_i686_msvc 0.48.5",
- "windows_x86_64_gnu 0.48.5",
- "windows_x86_64_gnullvm 0.48.5",
- "windows_x86_64_msvc 0.48.5",
-]
-
-[[package]]
-name = "windows-targets"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
-dependencies = [
- "windows_aarch64_gnullvm 0.52.6",
- "windows_aarch64_msvc 0.52.6",
- "windows_i686_gnu 0.52.6",
- "windows_i686_gnullvm",
- "windows_i686_msvc 0.52.6",
- "windows_x86_64_gnu 0.52.6",
- "windows_x86_64_gnullvm 0.52.6",
- "windows_x86_64_msvc 0.52.6",
-]
-
-[[package]]
-name = "windows_aarch64_gnullvm"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2b38e32f0abccf9987a4e3079dfb67dcd799fb61361e53e2882c3cbaf0d905d8"
-
-[[package]]
-name = "windows_aarch64_gnullvm"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
-
-[[package]]
-name = "windows_aarch64_msvc"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dc35310971f3b2dbbf3f0690a219f40e2d9afcf64f9ab7cc1be722937c26b4bc"
-
-[[package]]
-name = "windows_aarch64_msvc"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
-
-[[package]]
-name = "windows_i686_gnu"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a75915e7def60c94dcef72200b9a8e58e5091744960da64ec734a6c6e9b3743e"
-
-[[package]]
-name = "windows_i686_gnu"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
-
-[[package]]
-name = "windows_i686_gnullvm"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
-
-[[package]]
-name = "windows_i686_msvc"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8f55c233f70c4b27f66c523580f78f1004e8b5a8b659e05a4eb49d4166cca406"
-
-[[package]]
-name = "windows_i686_msvc"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
-
-[[package]]
-name = "windows_x86_64_gnu"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "53d40abd2583d23e4718fddf1ebec84dbff8381c07cae67ff7768bbf19c6718e"
-
-[[package]]
-name = "windows_x86_64_gnu"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
-
-[[package]]
-name = "windows_x86_64_gnullvm"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b7b52767868a23d5bab768e390dc5f5c55825b6d30b86c844ff2dc7414044cc"
-
-[[package]]
-name = "windows_x86_64_gnullvm"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
-
-[[package]]
-name = "windows_x86_64_msvc"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538"
-
-[[package]]
-name = "windows_x86_64_msvc"
-version = "0.52.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
-
-[[package]]
-name = "xshell"
-version = "0.2.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9e7290c623014758632efe00737145b6867b66292c42167f2ec381eb566a373d"
-dependencies = [
- "xshell-macros",
-]
-
-[[package]]
-name = "xshell-macros"
-version = "0.2.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32ac00cd3f8ec9c1d33fb3e7958a82df6989c42d747bd326c822b1d625283547"
diff --git a/src/doc/rustc-dev-guide/josh-sync/Cargo.toml b/src/doc/rustc-dev-guide/josh-sync/Cargo.toml
deleted file mode 100644
index 1f8bf2a0093..00000000000
--- a/src/doc/rustc-dev-guide/josh-sync/Cargo.toml
+++ /dev/null
@@ -1,9 +0,0 @@
-[package]
-name = "josh-sync"
-edition = "2024"
-
-[dependencies]
-anyhow = "1.0.95"
-clap = { version = "4.5.21", features = ["derive"] }
-directories = "5"
-xshell = "0.2.6"
diff --git a/src/doc/rustc-dev-guide/josh-sync/README.md b/src/doc/rustc-dev-guide/josh-sync/README.md
deleted file mode 100644
index a3dd876e8b8..00000000000
--- a/src/doc/rustc-dev-guide/josh-sync/README.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# Git josh sync
-This utility serves for syncing the josh git subtree to and from the rust-lang/rust repository.
-
-See CLI help for usage.
diff --git a/src/doc/rustc-dev-guide/josh-sync/src/main.rs b/src/doc/rustc-dev-guide/josh-sync/src/main.rs
deleted file mode 100644
index aeedee5be22..00000000000
--- a/src/doc/rustc-dev-guide/josh-sync/src/main.rs
+++ /dev/null
@@ -1,41 +0,0 @@
-use clap::Parser;
-
-use crate::sync::{GitSync, RustcPullError};
-
-mod sync;
-
-#[derive(clap::Parser)]
-enum Args {
-    /// Pull changes from the main `rustc` repository.
-    /// This creates new commits that should be then merged into `rustc-dev-guide`.
-    RustcPull,
-    /// Push changes from `rustc-dev-guide` to the given `branch` of a `rustc` fork under the given
-    /// GitHub `username`.
-    /// The pushed branch should then be merged into the `rustc` repository.
-    RustcPush { branch: String, github_username: String },
-}
-
-fn main() -> anyhow::Result<()> {
-    let args = Args::parse();
-    let sync = GitSync::from_current_dir()?;
-    match args {
-        Args::RustcPull => {
-            if let Err(error) = sync.rustc_pull(None) {
-                match error {
-                    RustcPullError::NothingToPull => {
-                        eprintln!("Nothing to pull");
-                        std::process::exit(2);
-                    }
-                    RustcPullError::PullFailed(error) => {
-                        eprintln!("Pull failure: {error:?}");
-                        std::process::exit(1);
-                    }
-                }
-            }
-        }
-        Args::RustcPush { github_username, branch } => {
-            sync.rustc_push(github_username, branch)?;
-        }
-    }
-    Ok(())
-}
diff --git a/src/doc/rustc-dev-guide/josh-sync/src/sync.rs b/src/doc/rustc-dev-guide/josh-sync/src/sync.rs
deleted file mode 100644
index ed38d1403a0..00000000000
--- a/src/doc/rustc-dev-guide/josh-sync/src/sync.rs
+++ /dev/null
@@ -1,275 +0,0 @@
-use std::io::Write;
-use std::ops::Not;
-use std::path::PathBuf;
-use std::time::Duration;
-use std::{env, net, process};
-
-use anyhow::{Context, anyhow, bail};
-use xshell::{Shell, cmd};
-
-/// Used for rustc syncs.
-const JOSH_FILTER: &str = ":/src/doc/rustc-dev-guide";
-const JOSH_PORT: u16 = 42042;
-const UPSTREAM_REPO: &str = "rust-lang/rust";
-
-pub enum RustcPullError {
-    /// No changes are available to be pulled.
-    NothingToPull,
-    /// A rustc-pull has failed, probably a git operation error has occurred.
-    PullFailed(anyhow::Error),
-}
-
-impl<E> From<E> for RustcPullError
-where
-    E: Into<anyhow::Error>,
-{
-    fn from(error: E) -> Self {
-        Self::PullFailed(error.into())
-    }
-}
-
-pub struct GitSync {
-    dir: PathBuf,
-}
-
-/// This code was adapted from the miri repository
-/// (https://github.com/rust-lang/miri/blob/6a68a79f38064c3bc30617cca4bdbfb2c336b140/miri-script/src/commands.rs#L236).
-impl GitSync {
-    pub fn from_current_dir() -> anyhow::Result<Self> {
-        Ok(Self { dir: std::env::current_dir()? })
-    }
-
-    pub fn rustc_pull(&self, commit: Option<String>) -> Result<(), RustcPullError> {
-        let sh = Shell::new()?;
-        sh.change_dir(&self.dir);
-        let commit = commit.map(Ok).unwrap_or_else(|| {
-            let rust_repo_head =
-                cmd!(sh, "git ls-remote https://github.com/{UPSTREAM_REPO}/ HEAD").read()?;
-            rust_repo_head
-                .split_whitespace()
-                .next()
-                .map(|front| front.trim().to_owned())
-                .ok_or_else(|| anyhow!("Could not obtain Rust repo HEAD from remote."))
-        })?;
-        // Make sure the repo is clean.
-        if cmd!(sh, "git status --untracked-files=no --porcelain").read()?.is_empty().not() {
-            return Err(anyhow::anyhow!(
-                "working directory must be clean before performing rustc pull"
-            )
-            .into());
-        }
-        // Make sure josh is running.
-        let josh = Self::start_josh()?;
-        let josh_url =
-            format!("http://localhost:{JOSH_PORT}/{UPSTREAM_REPO}.git@{commit}{JOSH_FILTER}.git");
-
-        let previous_base_commit = sh.read_file("rust-version")?.trim().to_string();
-        if previous_base_commit == commit {
-            return Err(RustcPullError::NothingToPull);
-        }
-
-        // Update rust-version file. As a separate commit, since making it part of
-        // the merge has confused the heck out of josh in the past.
-        // We pass `--no-verify` to avoid running git hooks.
-        // We do this before the merge so that if there are merge conflicts, we have
-        // the right rust-version file while resolving them.
-        sh.write_file("rust-version", format!("{commit}\n"))?;
-        const PREPARING_COMMIT_MESSAGE: &str = "Preparing for merge from rustc";
-        cmd!(sh, "git commit rust-version --no-verify -m {PREPARING_COMMIT_MESSAGE}")
-            .run()
-            .context("FAILED to commit rust-version file, something went wrong")?;
-
-        // Fetch given rustc commit.
-        cmd!(sh, "git fetch {josh_url}")
-            .run()
-            .inspect_err(|_| {
-                // Try to un-do the previous `git commit`, to leave the repo in the state we found it.
-                cmd!(sh, "git reset --hard HEAD^")
-                    .run()
-                    .expect("FAILED to clean up again after failed `git fetch`, sorry for that");
-            })
-            .context("FAILED to fetch new commits, something went wrong (committing the rust-version file has been undone)")?;
-
-        // This should not add any new root commits. So count those before and after merging.
-        let num_roots = || -> anyhow::Result<u32> {
-            Ok(cmd!(sh, "git rev-list HEAD --max-parents=0 --count")
-                .read()
-                .context("failed to determine the number of root commits")?
-                .parse::<u32>()?)
-        };
-        let num_roots_before = num_roots()?;
-
-        let sha =
-            cmd!(sh, "git rev-parse HEAD").output().context("FAILED to get current commit")?.stdout;
-
-        // Merge the fetched commit.
-        const MERGE_COMMIT_MESSAGE: &str = "Merge from rustc";
-        cmd!(sh, "git merge FETCH_HEAD --no-verify --no-ff -m {MERGE_COMMIT_MESSAGE}")
-            .run()
-            .context("FAILED to merge new commits, something went wrong")?;
-
-        let current_sha =
-            cmd!(sh, "git rev-parse HEAD").output().context("FAILED to get current commit")?.stdout;
-        if current_sha == sha {
-            cmd!(sh, "git reset --hard HEAD^")
-                .run()
-                .expect("FAILED to clean up after creating the preparation commit");
-            eprintln!(
-                "No merge was performed, no changes to pull were found. Rolled back the preparation commit."
-            );
-            return Err(RustcPullError::NothingToPull);
-        }
-
-        // Check that the number of roots did not increase.
-        if num_roots()? != num_roots_before {
-            return Err(anyhow::anyhow!(
-                "Josh created a new root commit. This is probably not the history you want."
-            )
-            .into());
-        }
-
-        drop(josh);
-        Ok(())
-    }
-
-    pub fn rustc_push(&self, github_user: String, branch: String) -> anyhow::Result<()> {
-        let sh = Shell::new()?;
-        sh.change_dir(&self.dir);
-        let base = sh.read_file("rust-version")?.trim().to_owned();
-        // Make sure the repo is clean.
-        if cmd!(sh, "git status --untracked-files=no --porcelain").read()?.is_empty().not() {
-            bail!("working directory must be clean before running `rustc-push`");
-        }
-        // Make sure josh is running.
-        let josh = Self::start_josh()?;
-        let josh_url =
-            format!("http://localhost:{JOSH_PORT}/{github_user}/rust.git{JOSH_FILTER}.git");
-
-        // Find a repo we can do our preparation in.
-        if let Ok(rustc_git) = env::var("RUSTC_GIT") {
-            // If rustc_git is `Some`, we'll use an existing fork for the branch updates.
-            sh.change_dir(rustc_git);
-        } else {
-            // Otherwise, do this in the local repo.
-            println!(
-                "This will pull a copy of the rust-lang/rust history into this checkout, growing it by about 1GB."
-            );
-            print!(
-                "To avoid that, abort now and set the `RUSTC_GIT` environment variable to an existing rustc checkout. Proceed? [y/N] "
-            );
-            std::io::stdout().flush()?;
-            let mut answer = String::new();
-            std::io::stdin().read_line(&mut answer)?;
-            if answer.trim().to_lowercase() != "y" {
-                std::process::exit(1);
-            }
-        };
-        // Prepare the branch. Pushing works much better if we use as base exactly
-        // the commit that we pulled from last time, so we use the `rust-version`
-        // file to find out which commit that would be.
-        println!("Preparing {github_user}/rust (base: {base})...");
-        if cmd!(sh, "git fetch https://github.com/{github_user}/rust {branch}")
-            .ignore_stderr()
-            .read()
-            .is_ok()
-        {
-            println!(
-                "The branch '{branch}' seems to already exist in 'https://github.com/{github_user}/rust'. Please delete it and try again."
-            );
-            std::process::exit(1);
-        }
-        cmd!(sh, "git fetch https://github.com/{UPSTREAM_REPO} {base}").run()?;
-        cmd!(sh, "git push https://github.com/{github_user}/rust {base}:refs/heads/{branch}")
-            .ignore_stdout()
-            .ignore_stderr() // silence the "create GitHub PR" message
-            .run()?;
-        println!();
-
-        // Do the actual push.
-        sh.change_dir(&self.dir);
-        println!("Pushing changes...");
-        cmd!(sh, "git push {josh_url} HEAD:{branch}").run()?;
-        println!();
-
-        // Do a round-trip check to make sure the push worked as expected.
-        cmd!(sh, "git fetch {josh_url} {branch}").ignore_stderr().read()?;
-        let head = cmd!(sh, "git rev-parse HEAD").read()?;
-        let fetch_head = cmd!(sh, "git rev-parse FETCH_HEAD").read()?;
-        if head != fetch_head {
-            bail!(
-                "Josh created a non-roundtrip push! Do NOT merge this into rustc!\n\
-                Expected {head}, got {fetch_head}."
-            );
-        }
-        println!(
-            "Confirmed that the push round-trips back to rustc-dev-guide properly. Please create a rustc PR:"
-        );
-        println!(
-            // Open PR with `subtree update` title to silence the `no-merges` triagebot check
-            "    https://github.com/{UPSTREAM_REPO}/compare/{github_user}:{branch}?quick_pull=1&title=rustc-dev-guide+subtree+update&body=r?+@ghost"
-        );
-
-        drop(josh);
-        Ok(())
-    }
-
-    fn start_josh() -> anyhow::Result<impl Drop> {
-        // Determine cache directory.
-        let local_dir = {
-            let user_dirs =
-                directories::ProjectDirs::from("org", "rust-lang", "rustc-dev-guide-josh").unwrap();
-            user_dirs.cache_dir().to_owned()
-        };
-
-        // Start josh, silencing its output.
-        let mut cmd = process::Command::new("josh-proxy");
-        cmd.arg("--local").arg(local_dir);
-        cmd.arg("--remote").arg("https://github.com");
-        cmd.arg("--port").arg(JOSH_PORT.to_string());
-        cmd.arg("--no-background");
-        cmd.stdout(process::Stdio::null());
-        cmd.stderr(process::Stdio::null());
-        let josh = cmd.spawn().context("failed to start josh-proxy, make sure it is installed")?;
-
-        // Create a wrapper that stops it on drop.
-        struct Josh(process::Child);
-        impl Drop for Josh {
-            fn drop(&mut self) {
-                #[cfg(unix)]
-                {
-                    // Try to gracefully shut it down.
-                    process::Command::new("kill")
-                        .args(["-s", "INT", &self.0.id().to_string()])
-                        .output()
-                        .expect("failed to SIGINT josh-proxy");
-                    // Sadly there is no "wait with timeout"... so we just give it some time to finish.
-                    std::thread::sleep(Duration::from_millis(100));
-                    // Now hopefully it is gone.
-                    if self.0.try_wait().expect("failed to wait for josh-proxy").is_some() {
-                        return;
-                    }
-                }
-                // If that didn't work (or we're not on Unix), kill it hard.
-                eprintln!(
-                    "I have to kill josh-proxy the hard way, let's hope this does not break anything."
-                );
-                self.0.kill().expect("failed to SIGKILL josh-proxy");
-            }
-        }
-
-        // Wait until the port is open. We try every 10ms until 1s passed.
-        for _ in 0..100 {
-            // This will generally fail immediately when the port is still closed.
-            let josh_ready = net::TcpStream::connect_timeout(
-                &net::SocketAddr::from(([127, 0, 0, 1], JOSH_PORT)),
-                Duration::from_millis(1),
-            );
-            if josh_ready.is_ok() {
-                return Ok(Josh(josh));
-            }
-            // Not ready yet.
-            std::thread::sleep(Duration::from_millis(10));
-        }
-        bail!("Even after waiting for 1s, josh-proxy is still not available.")
-    }
-}
diff --git a/src/doc/rustc-dev-guide/src/external-repos.md b/src/doc/rustc-dev-guide/src/external-repos.md
index f3170c9222d..a19b1116de8 100644
--- a/src/doc/rustc-dev-guide/src/external-repos.md
+++ b/src/doc/rustc-dev-guide/src/external-repos.md
@@ -9,7 +9,7 @@ There are three main ways we use dependencies:
 As a general rule:
 - Use crates.io for libraries that could be useful for others in the ecosystem
 - Use subtrees for tools that depend on compiler internals and need to be updated if there are breaking
-changes
+  changes
 - Use submodules for tools that are independent of the compiler
 
 ## External Dependencies (subtrees)
@@ -23,6 +23,8 @@ The following external projects are managed using some form of a `subtree`:
 * [rust-analyzer](https://github.com/rust-lang/rust-analyzer)
 * [rustc_codegen_cranelift](https://github.com/rust-lang/rustc_codegen_cranelift)
 * [rustc-dev-guide](https://github.com/rust-lang/rustc-dev-guide)
+* [compiler-builtins](https://github.com/rust-lang/compiler-builtins)
+* [stdarch](https://github.com/rust-lang/stdarch)
 
 In contrast to `submodule` dependencies
 (see below for those), the `subtree` dependencies are just regular files and directories which can
@@ -34,20 +36,57 @@ implement a new tool feature or test, that should happen in one collective rustc
 `subtree` dependencies are currently managed by two distinct approaches:
 
 * Using `git subtree`
-  * `clippy` ([sync guide](https://doc.rust-lang.org/nightly/clippy/development/infrastructure/sync.html#performing-the-sync-from-rust-langrust-to-clippy))
-  * `portable-simd` ([sync script](https://github.com/rust-lang/portable-simd/blob/master/subtree-sync.sh))
-  * `rustfmt`
-  * `rustc_codegen_cranelift` ([sync script](https://github.com/rust-lang/rustc_codegen_cranelift/blob/113af154d459e41b3dc2c5d7d878e3d3a8f33c69/scripts/rustup.sh#L7))
+    * `clippy` ([sync guide](https://doc.rust-lang.org/nightly/clippy/development/infrastructure/sync.html#performing-the-sync-from-rust-langrust-to-clippy))
+    * `portable-simd` ([sync script](https://github.com/rust-lang/portable-simd/blob/master/subtree-sync.sh))
+    * `rustfmt`
+    * `rustc_codegen_cranelift` ([sync script](https://github.com/rust-lang/rustc_codegen_cranelift/blob/113af154d459e41b3dc2c5d7d878e3d3a8f33c69/scripts/rustup.sh#L7))
 * Using the [josh] tool
-  * `miri` ([sync guide](https://github.com/rust-lang/miri/blob/master/CONTRIBUTING.md#advanced-topic-syncing-with-the-rustc-repo))
-  * `rust-analyzer` ([sync script](https://github.com/rust-lang/rust-analyzer/blob/2e13684be123eca7181aa48e043e185d8044a84a/xtask/src/release.rs#L147))
-  * `rustc-dev-guide` ([sync guide](https://github.com/rust-lang/rustc-dev-guide#synchronizing-josh-subtree-with-rustc))
+    * `miri` ([sync guide](https://github.com/rust-lang/miri/blob/master/CONTRIBUTING.md#advanced-topic-syncing-with-the-rustc-repo))
+    * `rust-analyzer` ([sync script](https://github.com/rust-lang/rust-analyzer/blob/2e13684be123eca7181aa48e043e185d8044a84a/xtask/src/release.rs#L147))
+    * `rustc-dev-guide`
+    * `compiler-builtins`
+    * `stdarch`
 
-The [josh] tool is an alternative to git subtrees, which manages git history in a different way and scales better to larger repositories. Specific tooling is required to work with josh, you can check out the `miri` or `rust-analyzer` scripts linked above for inspiration. If you want to migrate a repository dependency from `git subtree` or `git submodule` to josh, you can check out [this guide](https://hackmd.io/7pOuxnkdQDaL1Y1FQr65xg).
+### Josh subtrees
 
-Below you can find a guide on how to perform push and pull synchronization with the main rustc repo using `git subtree`, although these instructions might differ repo from repo.
+The [josh] tool is an alternative to git subtrees, which manages git history in a different way and scales better to larger repositories. Specific tooling is required to work with josh, you can check out the `miri` or `rust-analyzer` scripts linked above for inspiration. We provide a helper [`rustc-josh-sync`][josh-sync] tool to help with the synchronization, it is described [below](#synchronizing-a-josh-subtree).
 
-### Synchronizing a subtree
+### Synchronizing a Josh subtree
+
+We use a dedicated tool called [`rustc-josh-sync`][josh-sync] for performing Josh subtree updates.
+Currently, we are migrating Josh repositories to it. So far, it is used in:
+
+- rustc-dev-guide
+
+To use the tool, first install it with `cargo install --locked --git https://github.
+com/rust-lang/josh-sync`.
+
+Both pulls (synchronize changes from rust-lang/rust into the subtree) and pushes (synchronize
+changes from the subtree to rust-lang/rust) are performed from the subtree repository (so first
+switch to its repository checkout directory in your terminal).
+
+#### Performing pull
+1) Checkout a new branch that will be used to create a PR into the subtree
+2) Run the pull command
+    ```
+    rustc-josh-sync pull
+    ```
+3) Push the branch to your fork and create a PR into the subtree repository
+    - If you have `gh` CLI installed, `rustc-josh-sync` can create the PR for you.
+
+#### Performing push
+
+1) Run the push command to create a branch named `<branch-name>` in a `rustc` fork under the `<gh-username>` account
+    ```
+    rustc-josh-sync push <branch-name> <gh-username>
+    ```
+2) Create a PR from `<branch-name>` into `rust-lang/rust`
+
+### Creating a new Josh subtree dependency
+
+If you want to migrate a repository dependency from `git subtree` or `git submodule` to josh, you can check out [this guide](https://hackmd.io/7pOuxnkdQDaL1Y1FQr65xg).
+
+### Synchronizing a git subtree
 
 Periodically the changes made to subtree based dependencies need to be synchronized between this
 repository and the upstream tool repositories.
@@ -129,3 +168,4 @@ the week leading up to the beta cut.
 [toolstate website]: https://rust-lang-nursery.github.io/rust-toolstate/
 [Toolstate chapter]: https://forge.rust-lang.org/infra/toolstate.html
 [josh]: https://josh-project.github.io/josh/intro.html
+[josh-sync]: https://github.com/rust-lang/josh-sync