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 <dstolee@microsoft.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 43b9ff3bce218e986e9dabd57a0e7981ff59166a..17fe086c7fdb2642d2978cd6431e89a3dcecca6f 100644 (file)
--- 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.
 
 -t::

diff --git a/t/t5510-fetch.sh b/t/t5510-fetch.sh
index 4b602826895e21154376391333c6517b4ec1ec54..5f8f1c287f417cb9a30d7e4db71bfb5ba4ef91ce 100755 (executable)
--- a/t/t5510-fetch.sh
+++ b/t/t5510-fetch.sh
@@ -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' '
+       cd "$TRASH_DIRECTORY" &&
+       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" &&