Re: FETCH_HEAD question

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

Jay Soffian <jaysoffian@gmail.com> writes:

> I did this the other day out of mild curiosity:
>
> $ git fetch
> $ git merge FETCH_HEAD
>
> Which did something, but not something that was at all useful. It
> merges in the first ref listed in FETCH_HEAD. It does not appear to be
> an accident that it does this, as git merge has special treatment for
> FETCH_HEAD to generate the merge message.

"git pull" internally invokes "git fetch" to learn the tips of branches
the invoking user is interested in.  "git fetch" downloads the necessary
objects to complete the ancestry chain from local refs to these tips of
branches, and then uses FETCH_HEAD to communicate which commit object
these branches point at, and at the same time which lines in the file
describe the commits that need to be merged into the current HEAD by
marking lines with not-for-merge markers ("cat .git/FETCH_HEAD" to see how
it is done), back to the invoking "git pull".  "git pull" then inspects
this file to decide which commit object to pass to "git merge".

This division of labor makes sense because "git fetch" knows more about
the user preference ("remotes.*.fetch" and "branch.*.merge" configuration
items, .git/remotes/* files, and .git/branches/* files are inspected by
the command).  

The rule initially was that the first non-wildcard Pull: rule in remotes/*
file specifies the commits to be merged or something, and over time, the
system learned the more elaborate per-branch settings via branch.*.merge
variables, but the idea has always been that you cannot just grab the
first line of FETCH_HEAD and expect that is what you want to merge.  At
least you need to omit the ones that are marked not-for-merge (see how it
is done by "git-pull.sh" with a simple sed script), even though
"FETCH_HEAD" can be used as an extended SHA-1 to name the commit object
recorded on the first line in the file.

Having said that, being able to directly use FETCH_HEAD as an extended
SHA-1 is often useful when somebody asks an integrator to pull one-shot
with git-request-pull.  Upon receiving such a request, the integrator can
say:

	$ git fetch git://repo.or.cz/his.git for-linus
        $ git log -p ..FETCH_HEAD ;# to inspect
        $ git merge FETCH_HEAD

to take advantage of the fact that the commit object name that appears at
the beginning of resulting FETCH_HEAD file is actually the commit we would
want, because by definition FETCH_HEAD records only one commit when we are
fetching only one branch.

Incidentally, such a command line to explicitly fetch one single branch is
interpreted by "git fetch" to mean that you are interested in merging the
tip of the fetched branch, and the first line of the resulting FETCH_HEAD
file is not marked with not-for-merge.  Therefore,

	$ git pull git://repo.or.cz/his.git for-linus

would also work regardless of what you have in .git/config file.