diff options
authorDerrick Stolee <>2020-01-21 01:38:12 (GMT)
committerJunio C Hamano <>2020-01-21 18:24:48 (GMT)
commitb40a50264acab504faa2b444dab3603682dc1785 (patch)
parentb6d4d82bd5a49197d5d2f4f81c08da0d461cfcf1 (diff)
fetch: document and test --refmap=""
To prevent long blocking time during a 'git fetch' call, a user may want to set up a schedule for background 'git fetch' processes. However, these runs will update the refs/remotes branches due to the default refspec set in the config when Git adds a remote. Hence the user will not notice when remote refs are updated during their foreground fetches. In fact, they may _want_ those refs to stay put so they can work with the refs from their last foreground fetch call. This can be accomplished by overriding the configured refspec using '--refmap=' along with a custom refspec: git fetch --refmap='' <remote> +refs/heads/*:refs/hidden/<remote>/* to populate a custom ref space and download a pack of the new reachable objects. This kind of call allows a few things to happen: 1. We download a new pack if refs have updated. 2. Since the refs/hidden branches exist, GC will not remove the newly-downloaded data. 3. With fetch.writeCommitGraph enabled, the refs/hidden refs are used to update the commit-graph file. To avoid the refs/hidden directory from filling without bound, the --prune option can be included. When providing a refspec like this, the --prune option does not delete remote refs and instead only deletes refs in the target refspace. Update the documentation to clarify how '--refmap=""' works and create tests to guarantee this behavior remains in the future. Signed-off-by: Derrick Stolee <> Signed-off-by: Junio C Hamano <>
2 files changed, 28 insertions, 1 deletions
diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 43b9ff3..17fe086 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -135,7 +135,10 @@ ifndef::git-pull[]
specified refspec (can be given more than once) to map the
refs to remote-tracking branches, instead of the values of
`remote.*.fetch` configuration variables for the remote
- repository. See section on "Configured Remote-tracking
+ repository. Providing an empty `<refspec>` to the
+ `--refmap` option causes Git to ignore the configured
+ refspecs and rely entirely on the refspecs supplied as
+ command-line arguments. See section on "Configured Remote-tracking
Branches" for details.
diff --git a/t/ b/t/
index 4b60282..5f8f1c2 100755
--- a/t/
+++ b/t/
@@ -174,6 +174,30 @@ test_expect_success 'fetch --prune --tags with refspec prunes based on refspec'
git rev-parse sometag
+test_expect_success '--refmap="" ignores configured refspec' '
+ git clone "$D" remote-refs &&
+ git -C remote-refs rev-parse remotes/origin/master >old &&
+ git -C remote-refs update-ref refs/remotes/origin/master master~1 &&
+ git -C remote-refs rev-parse remotes/origin/master >new &&
+ git -C remote-refs fetch --refmap= origin "+refs/heads/*:refs/hidden/origin/*" &&
+ git -C remote-refs rev-parse remotes/origin/master >actual &&
+ test_cmp new actual &&
+ git -C remote-refs fetch origin &&
+ git -C remote-refs rev-parse remotes/origin/master >actual &&
+ test_cmp old actual
+test_expect_success '--refmap="" and --prune' '
+ git -C remote-refs update-ref refs/remotes/origin/foo/otherbranch master &&
+ git -C remote-refs update-ref refs/hidden/foo/otherbranch master &&
+ git -C remote-refs fetch --prune --refmap="" origin +refs/heads/*:refs/hidden/* &&
+ git -C remote-refs rev-parse remotes/origin/foo/otherbranch &&
+ test_must_fail git -C remote-refs rev-parse refs/hidden/foo/otherbranch &&
+ git -C remote-refs fetch --prune origin &&
+ test_must_fail git -C remote-refs rev-parse remotes/origin/foo/otherbranch
test_expect_success 'fetch tags when there is no tags' '
cd "$D" &&