fetch: document and test --refmap=""
authorDerrick Stolee <dstolee@microsoft.com>
Tue, 21 Jan 2020 01:38:12 +0000 (01:38 +0000)
committerJunio C Hamano <gitster@pobox.com>
Tue, 21 Jan 2020 18:24:48 +0000 (10:24 -0800)
commitb40a50264acab504faa2b444dab3603682dc1785
treeee30a33457cf38740b4190b41be54523bc5a980b
parentb6d4d82bd5a49197d5d2f4f81c08da0d461cfcf1
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>
Documentation/fetch-options.txt
t/t5510-fetch.sh