Matthias Andree <matthias.andree@xxxxxx> 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).
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html