Re: Could this be done simpler?

[Junio C Hamano <gitster@pobox.com>]

Matthias Andree <matthias.andree@gmx.de> writes:

> Could we ditch the current git-pull --append description? Can then please
> somebody rewrite this paragraph? This somebody must have completely understood

> (1) what this feature is good for (practically speaking)
>
> (2) how it works (technically speaking, to provide reference information)
>
> That would be much more useful, and the use would last longer :-)
>
> I don't dare ask Junio directly.

But if you run blame and mailing list archive search, you would discover
that "fetch --append" was my invention.  After all, the entire Octopus
idea originates from me at 211232b (Octopus merge of the following five
patches., 2005-05-05).  It is interesting to realize that it was actually
a Pentapus made on the day of 5/5/5 ;-)

I thought I was going to take blame on the incomprehensive documentation
and pass it on to me being non-native speaker/writer of English, but the
situation is bit funny.  Documentation/fetch-options.txt says this:

    -a::
    --append::
            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.

Perhaps there has a cut&paste error?  I haven't looked.

Now answers to (1) and (2).

 (1) The feature was designed exactly for the use case Linus described.

 (2) "git fetch" leaves list of <commit object, repo, branch, flag> for
     each ref fetched from repository in .git/FETCH_HEAD, where flag tells
     if it is meant for merging.  "git pull" runs "git fetch", reads from
     this file to learn which ones to pass to "git merge".  The
     information also is given to "git fmt-merge-msg" to come up with the
     message.

     Usually "git fetch" first empties the existing contents of the file
     and stores the list of refs it fetched.  With --append, it doesn't
     empty the file; refs fetched by the previous invocation of "git
     fetch" will be kept and the refs it fetched are appenede.

     So:

	$ git fetch one a
        $ git fetch --append two b
        $ git pull --apend three c

     will end up having all the three refs from different repositories in
     .git/FETCH_HEAD.  I.e.

	branch a, from repo one, to be merged
	branch b, from repo two, to be merged
	branch c, from repo three, to be merged

     when "git fetch" run by the the last "git pull" returns.  "git pull"
     reads the file and learn what to give to "git fmt-merge-msg" (to come
     up with the message for the merge commit) and "git merge" (to create
     the merge commit).