Document `fetch.prunetags = true` gotcha during rustc-pull

1 files changed, 13 insertions, 0 deletions

diff --git a/src/doc/rustc-dev-guide/README.md b/src/doc/rustc-dev-guide/README.md
index 2464ffbbc50..6a25a91f56a 100644
--- a/src/doc/rustc-dev-guide/README.md
+++ b/src/doc/rustc-dev-guide/README.md
@@ -82,6 +82,7 @@ cargo +stable install josh-proxy --git https://github.com/josh-project/josh --ta
 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
     ```
@@ -95,3 +96,15 @@ Older versions of `josh-proxy` may not round trip commits losslessly so it is im
     $ 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 +stable run --manifest-path josh-sync/Cargo.toml -- rustc-pull
+```