Re: fetch and pull

On 2009.03.18 06:31:03 +0900, Nanako Shiraishi wrote:

Quoting John Dlugosz [off-list ref]:

quoted

I think the documentation for git-pull might also be garbled from
text being of different eras.  "Normally the branch merged is the
HEAD of the remote"?  That will be basically random since the last
thing the upstream repo user did will control what his HEAD is.

That's how it's supposed to work, and the documentation isn't from a
different era, either. Majority of users clone from a central
repository and keep pulling to update their clones, and in that kind
of setting, HEAD will never change. A HEAD in a bare repository tells
people which branch is the primary branch of the project.

But _if_ HEAD changes in the remote repo, that has normally no effect on
the behaviour of pull. Especially since the examples in the man page are
"git pull" and "git pull origin".

AFAICT the remote's HEAD affects the pull behaviour when:

1) You do "git pull git://host/repo.git" or similar, i.e. you don't use
a remote. Because then, no refspec is given to fetch, and it defaults to
fetching HEAD.

2) You do "git pull origin" and there's no remote.origin.fetch set, same
as above then.

3) You do "git pull" and either is branch.<name>.remote set to an url
(same as 1) then) or to a remote that has no default fetch refspec set
(same as 2) then).


1) probably isn't that common for most users, and even if, it's not
one of the commands given as examples to which the paragraph applies.

2) I don't think that's a common setup, and it's not a default setup, so
that hardly qualifies for "normally".

3) I've actually seen cases of the first form of this setup (remote set
to an url), but usually that was paired with a confused user.


So while it's true that the remote's HEAD might be what you merge, it's
not quite what happens "normally". Of course it's true that the most
common setup is probably that HEAD references master and that
branch.<name>.merge is also set to refs/heads/master, but while the
outcome is basically the same, I'd rather say that that is a coincidence
rather than what the text means to the reader.


I'm unsure about how to improve that section though. Basically, the last
paragraph ("When no refspec was given ...") above the EXAMPLES section
needs to be repeated, but that feels wrong. Anyone got a better idea?

Well, at least I finally realised that pull _might_ default to the
remote's HEAD, and for that part, I'll send a patch.

Björn