14

While looking at the documentation for git fetch I noticed the --append option. The documentation says it does this:

Append ref names and object names of fetched refs to the existing contents of .git/FETCH_HEAD. Without this option old data in .git/FETCH_HEAD will be overwritten.

What use does this have? From what I understand, FETCH_HEAD keeps track of the tips of the remotes branche that were just fetched so that merge or rebase gets called on them.

Why would appending to the list matter? Why does keeping old fetch heads matter?

Yazeed Sabri
  • 346
  • 3
  • 17
  • 3
    There's a really great explanation of `git fetch` and its use of `--append` in relation to `pull` [**here**](https://stackoverflow.com/a/41710011/2341603). – Obsidian Age Feb 26 '18 at 23:37
  • 1
    @ObsidianAge: it's not much of an explanation "You only need/want --append in special cases that won't apply here (when you are fetching from multiple separate repositories, or fetching in separate steps for debugging purposes, or some such)." == handwaving. – Fizz Mar 13 '20 at 22:40

1 Answers1

7

Sometimes you may need to fetch one branch at a time:

$ git fetch origin master

# FETCH_HEAD now points to origin/master
$ cat .git/FETCH_HEAD
1234567890abcdef        branch 'master' of https://git.example.com/someproject

# Let's fetch another branch
$ git fetch origin dev

# FETCH_HEAD is overwritten and points to origin/dev
$ cat .git/FETCH_HEAD
fedcba0987654321        branch 'dev' of https://git.example.com/someproject

# Fetch origin/master again, preserving the previous contents of .git/FETCH
$ git fetch --append origin master

# FETCH_HEAD now contains pointers to both origin/master and origin/dev
$ cat .git/FETCH_HEAD
fedcba0987654321        branch 'dev' of https://git.example.com/someproject
1234567890abcdef        branch 'master' of https://git.example.com/someproject

Similarly you can fetch from multiple remotes, accumulating the results in .git/FETCH_HEAD instead of having there only the results of the most recent git fetch.

Then you can merge all branches registered in .git/FETCH_HEAD with a single git merge FETCH_HEAD operation1:

When FETCH_HEAD (and no other commit) is specified, the branches recorded in the .git/FETCH_HEAD file by the previous invocation of git fetch for merging are merged to the current branch.

1 Whether it is a good practice, compared to merging each branch separately, is outside of the scope of this answer.

Leon
  • 31,443
  • 4
  • 72
  • 97
  • The order of the octopus merge here will be taken from the FETCH_HEAD file I'm assuming? This also feels weird to me, one can just explicitly specify each ref to the merge command than relying on the fetch command to put them in a file. – Yazeed Sabri Jul 08 '20 at 16:06
  • Hmm interesting, I typically do `git fetch --all` and pull selectively, so I have all the remote branches in `FETCH_HEAD`. I feel it would be worth it to add at least one use case for 1 vs many entries in `FETCH_HEAD` – Dima Tisnek Jul 09 '20 at 03:04