Did anyone have trouble learning the idea of local vs. remote branches?

Did anyone have trouble learning the idea of local vs. remote branches?

[Shawn Pearce]

Today I was talking with someone that I collaborate with through
Git and they still seemed to not get the idea that all branches
in their repository are local, and that at least a 'git fetch'
is needed to update the local tracking branches to the version
in the central repository that we collaborate through.  And this
isn't the first time we've had such discussions.

It dawned on me that this person still hasn't grasped the idea
behind fetch.  A few other users that I know also have commented on
how difficult fetch is to learn.

Most seemed to think that fetch would update their working directory,
or their current branch, as there is no other way to "download
changes from origin".  They also seem to expect their local tracking
branch to automatically update, especially when invoking
`git checkout -b foo tracking-branch`.


Clearly there is a gap in communicating these ideas in a way that
they can be understood by users.  Of course in at least one case
the users just isn't reading any Git documentation and plows ahead
as though it were CVS ('cause everything's "just like CVS") *sigh*.

-- 

Re: Did anyone have trouble learning the idea of local vs. remote branches?

[Salikh Zakirov]

Shawn Pearce wrote:
> Clearly there is a gap in communicating these ideas in a way that
> they can be understood by users.  Of course in at least one case
> the users just isn't reading any Git documentation and plows ahead
> as though it were CVS ('cause everything's "just like CVS") *sigh*.

I've went through persuading my colleagues (~30 engineers) to use Git and tutoring on it
through the three summer months, and my experience is very similar to Shawn's.
(i.e. confusing local and remote branches, not reading documentation,
and "just like CVS" attitude)

Below is the one git feature that I think was stumbled upon most often:

* people were often anaware of *multiple* branches created by git-clone,
  as the operation they wanted was analog of "cvs checkout". 

* git-fetch / git-pull tries to download all of the branches that were
  preset at git-clone time, and subsequently gives errors if some topic
  branches were rewound or dropped, while most of the time my colleagues
  were interested in just one "mainline" branch.

I think that the particular issue with the workflow in my organization
could have been solved by the git-checkout and git-clone hybrid

    git-checkout ssh://path.to/repo.git#branch [work_dir]

which would clone repository with just one branch and setup the remotes
file accordingly (The syntax is completely made up, of course)

P.S. a few words on the workflow we use:
- there is a "mainline" branch of development, kept as ssh-shared git repository
- mainline commits require some pre-commit testing, which takes ~1.5 hours,
  so people tend not to commit to mainline too often. On average, a given
  person commits to mainline once or twice a week.
- mainlines commits also require a fellow developer review, that's where
  topic branches come in handy. Topic branches are also useful for testing,
  as pre-commit testing should be run on several different platforms, thus
  on a different machines. Topic branches are kept on the same shared server.

Re: Did anyone have trouble learning the idea of local vs. remote branches?

[Shawn Pearce]

Salikh Zakirov <Salikh.Zakirov@Intel.com> wrote:
> I think that the particular issue with the workflow in my organization
> could have been solved by the git-checkout and git-clone hybrid
> 
>     git-checkout ssh://path.to/repo.git#branch [work_dir]
> 
> which would clone repository with just one branch and setup the remotes
> file accordingly (The syntax is completely made up, of course)

Right; that would help us to but developers really want two mainline
branches locally (stable and slightly less stable) as they access
them frequently.

Hence the "git clone --only a,b" syntax that was floating around
on the mailing list the past few days.  Of course no implementation
exists yet...
 
> - there is a "mainline" branch of development, kept as ssh-shared git repository
> - mainline commits require some pre-commit testing, which takes ~1.5 hours,
>   so people tend not to commit to mainline too often. On average, a given
>   person commits to mainline once or twice a week.
> - mainlines commits also require a fellow developer review, that's where
>   topic branches come in handy. Topic branches are also useful for testing,
>   as pre-commit testing should be run on several different platforms, thus
>   on a different machines. Topic branches are kept on the same shared server.

Pretty much the same workflow here; except that instead of a 1.5
hour testing requirement to move code into the mainline we have a
several day manual process where humans redo the changes that were
already made in git in the "real" SCM.

Usually humans screw up redoing those changes and it takes a few more
days to figure out why a topic branch it Git that works correctly
fails to even compile in the mainline.  So we don't push to the
mainline often.

-- 

Re: Did anyone have trouble learning the idea of local vs. remote branches?

[Matthieu Moy]

Shawn Pearce <spearce@spearce.org> writes:

> Today I was talking with someone that I collaborate with through
> Git and they still seemed to not get the idea that all branches
> in their repository are local, and that at least a 'git fetch'
> is needed to update the local tracking branches to the version
> in the central repository that we collaborate through.  And this
> isn't the first time we've had such discussions.

To me, the biggest difficulty was to understand the vocubulary. I
started with cogito, and looked for branching features in cg-branch-*.
The /features/ themselves seem nice, but the names of commands are
confusing to me. I'd expect something called cg-branch-add to create a
new branch, while it just tells cogito where to find one. And the git
Vs cogito increased the confusion.

-- 

Re: Did anyone have trouble learning the idea of local vs. remote branches?

[Andreas Ericsson]

Matthieu Moy wrote:
> Shawn Pearce <spearce@spearce.org> writes:
> 
>> Today I was talking with someone that I collaborate with through
>> Git and they still seemed to not get the idea that all branches
>> in their repository are local, and that at least a 'git fetch'
>> is needed to update the local tracking branches to the version
>> in the central repository that we collaborate through.  And this
>> isn't the first time we've had such discussions.
> 
> To me, the biggest difficulty was to understand the vocubulary.

I had that same problem, although I started with git and came from CVS / 
SVN. I am sufficiently experienced with those two system to hope that I 
wouldn't come across any similarities at all, so I wasn't expecting any, 
so I didn't get too badly bitten.

The Documentation/glossary.txt file is a very good place to start 
reading, although I wouldn't object to it being re-arranged to have the 
terms described there pop up "in order of appearance", so to speak. I 
sent in a couple of patches to the glossary file whenever I encountered 
something in gittish that I didn't understand. Sometimes I had managed 
to guess the correct meaning and the patch got applied. In other cases I 
had it completely wrong and other, more gittish-fluent, people corrected 
the patches and amended the documentation that led to the confusion.

I think this is the only way to keep the docs alive and 
newcomer-friendly. Sadly, neither the maintainer nor the active 
contributors have newbie-eyes so we're relying on everyone who *are* new 
to git to help keep git easy for new people.


> And the git Vs cogito increased the confusion.
> 

I've found that too. It's a shame that some things can be done with git 
that isn't possible (or at least easy) with cogito and the other way 
around. The shared but divergent terminology doesn't exactly help 
either. Now I fear it's too late to do anything about it.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se

Re: Did anyone have trouble learning the idea of local vs. remote branches?

[Wink Saville]

As a newbie I'm confused, recently I attempted to get Andrew Morton's -mm "tree". It turns out the instructions were incorrect and Junio was kind enough to correct the mistake. But I for one am still confused.

  git-fetch is; "Download objects and a head from another repository"

Fair enough and that make sense, but where does it go? Apparently it just gets stored in the object database and a reference to it in "FETCH_HEAD". Now what? Ok the documentation says:

  'The information is left for a later merge operation done by "git merge"'

Now in the case of fetching -mm apparently you don't do a merge, instead the instructions now read:

  git-fetch git://git.kernel.org/pub/scm/linux/kernel/git/smurf/linux-trees.git tag v2.6.16-rc2-mm1
  git-checkout -b local-v2.6.16-rc2-mm1 v2.6.16-rc2-mm1

The git-fetch apparently gets "linux-trees.git" and places a reference to it in a tag named 'v2.6.16-rc2-mm1'. Then the git-checkout, check's out this tag to a new branch, there was no merge! This is confusing and makes no sense to this newbie.

Now lets take a quick look at the git-merge documentation "HOW MERGE WORKS":

"A merge is always between the current HEAD and one or more remote branch heads, and the index file must exactly match the tree of HEAD commit (i.e. the contents of the last commit) when it happens. In other words, git-diff --cached HEAD must report no changes."

Sorry, there is basically no information in those two sentences that makes any sense to me. Take the first part, "between the current HEAD and one or more remote branch heads". So apparently merges occur against the current checkout branch, but I would guess the origin is also involved somehow? Secondly, what is the relationship between "remote branch heads" and FETCH_HEAD? I see no mention of FETCH_HEAD or how it might be used anywhere in the git-merge documentation.  Then we come to "the index file must exactly match the tree HEAD commit", sorry but my question is how could it not match? Obviously I don't understand how the index file is used, but I can say that adding "git-diff --cached HEAD must report no no changes" adds nothing to the explanation, yet I'm sure it does mean something to an expert.

It then goes onto say "it may fetch the objects from remote" I thought that is what "fetch" does.

Anyway, as you can see there is room for confusion for some people.

Regards,

Re: Did anyone have trouble learning the idea of local vs. remote branches?

[Jakub Narebski]

Could you word-wrap your messages at some reasonable column, for example at
72 or 76-columns wide?

Wink Saville wrote:

> As a newbie I'm confused, recently I attempted to get Andrew Morton's
> -mm "tree".

Which is unusual git usage, as Andrew Morton uses Quilt/his own patch tools,
and not git, if I remember correctly.

> It turns out the instructions were incorrect and Junio was 
> kind enough to correct the mistake. But I for one am still confused.  
>
>   git-fetch is; "Download objects and a head from another repository"
> 
> Fair enough and that make sense, but where does it go? Apparently it just
> gets stored in the object database and a reference to it in "FETCH_HEAD".
> Now what? Ok the documentation says:  

Objects gets stored into object database. Then (using FETCH_HEAD) heads
of tracking branches gets updated (i.e. if there were some changes on
branch 'master' in remote, the objects are downloaded, then head of local
tracking branch corresponding to remote branch 'master', e.g. 'origin',
gets updated with the value in 'master'; so called fast-forward case).
 
>   'The information is left for a later merge operation done by "git
>   merge"' 

Or done by git pull. The information in FETCH_HEAD is for commit message
in later merge (for example due to pull).
 
> Now in the case of fetching -mm apparently you don't do a merge, instead
> the instructions now read: 
> 
>   $ git-fetch \
>     git://git.kernel.org/pub/scm/linux/kernel/git/smurf/linux-trees.git \
>     tag v2.6.16-rc2-mm1  
>   $ git-checkout -b local-v2.6.16-rc2-mm1 v2.6.16-rc2-mm1

Are you sure that it is 'tag' there?

BTW. you are actually encouraged to use "git fetch" and "git checkout",
unless in scripts.

> The git-fetch apparently gets "linux-trees.git" and places a reference to
> it in a tag named 'v2.6.16-rc2-mm1'. Then the git-checkout, check's out
> this tag to a new branch, there was no merge! This is confusing and makes
> no sense to this newbie.   

The git-fetch fetches _from_ linux-trees.git repository. It fetches tag
v2.6.16-rc2-mm1 (and its lineage, i.e. everything pointed by this tag,
transitively) and stores it as local tag v2.6.16-rc2-mm1. You cannot
checkout tag (you can't commit to tag), so you have to create new branch
for your changes (or for checkout).
 
> Now lets take a quick look at the git-merge documentation "HOW MERGE
> WORKS": 
> 
> "A merge is always between the current HEAD and one or more remote branch
> heads, and the index file must exactly match the tree of HEAD commit (i.e.
> the contents of the last commit) when it happens. In other words, git-diff
> --cached HEAD must report no changes."   

That's a bit untrue, because merge can happen between local branches too.
 
> Sorry, there is basically no information in those two sentences that makes
> any sense to me. Take the first part, "between the current HEAD and one or
> more remote branch heads". So apparently merges occur against the current
> checkout branch, but I would guess the origin is also involved somehow? 

Current HEAD is current checked out branch. You merge current HEAD and one
or more [remote] branch heads (in the pull case, those not marked
not-for-merge in FETCH_HEAD), and place result in current branch.

> Secondly, what is the relationship between "remote branch heads" and
> FETCH_HEAD? I see no mention of FETCH_HEAD or how it might be used
> anywhere in the git-merge documentation.

FETCH_HEAD is low-lewel, not to be used by end-user (unless he/she wants to
do something unusual).

> Then we come to "the index file 
> must exactly match the tree HEAD commit", sorry but my question is how
> could it not match? 

For example if you git-add'ed some files, but not committed the addition.

> Obviously I don't understand how the index file is 
> used, but I can say that adding "git-diff --cached HEAD must report no no
> changes" adds nothing to the explanation, yet I'm sure it does mean
> something to an expert.          

It adds command which you can use to check _why_ merge failed to run.

> It then goes onto say "it may fetch the objects from remote" I thought
> that is what "fetch" does. 

IIRC this explanation is in git-pull(1). Pull in git is _fetch_ + merge.
 
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Did anyone have trouble learning the idea of local vs. remote branches?

[Wink Saville]

Jakub Narebski wrote:
> Could you word-wrap your messages at some reasonable column, for example at
> 72 or 76-columns wide?

done

> Wink Saville wrote:
> 
>> As a newbie I'm confused, recently I attempted to get Andrew Morton's
>> -mm "tree".
> 
> Which is unusual git usage, as Andrew Morton uses Quilt/his own patch tools,
> and not git, if I remember correctly.
> 
>> It turns out the instructions were incorrect and Junio was 
>> kind enough to correct the mistake. But I for one am still confused.  
>>
>>   git-fetch is; "Download objects and a head from another repository"
>>
>> Fair enough and that make sense, but where does it go? Apparently it just
>> gets stored in the object database and a reference to it in "FETCH_HEAD".
>> Now what? Ok the documentation says:  
> 
> Objects gets stored into object database. Then (using FETCH_HEAD) heads
> of tracking branches gets updated (i.e. if there were some changes on
> branch 'master' in remote, the objects are downloaded, then head of local
> tracking branch corresponding to remote branch 'master', e.g. 'origin',
> gets updated with the value in 'master'; so called fast-forward case).
>  

OK, so fetch does more than just fetching, it also merges, confusing 
especially given the that the Description says otherwise.

I just searched git-fetch documentation and I see it mentioned under the 
<refspec> documentation. I read the words but why do I have to tell it 
what the source & destination. From my perspective the source is the url 
and the destination is my repository. So refspec doesn't make sense, of 
course it's my problem I'm not blaming git or the documentation. But as 
a newbie I'm confused.

As I continue to investigate the <refspec> documentation it mentions in 
the first "Note" that ".. rewound and rebased frequently, the a pull .." 
. OK, so why is "pull" mentioned here I'm not pulling I'm fetching. Of 
course if you go to the git-pull documentation we see the <refspec> 
repeated. Which maybe isn't surprising since pull is a fetch+merge. So I 
guess the confusing part is that fetch does do merging, even though it 
says it implies it doesn't.

>>   'The information is left for a later merge operation done by "git
>>   merge"' 
> 
> Or done by git pull. The information in FETCH_HEAD is for commit message
> in later merge (for example due to pull).
>  
>> Now in the case of fetching -mm apparently you don't do a merge, instead
>> the instructions now read: 
>>
>>   $ git-fetch \
>>     git://git.kernel.org/pub/scm/linux/kernel/git/smurf/linux-trees.git \
>>     tag v2.6.16-rc2-mm1  
>>   $ git-checkout -b local-v2.6.16-rc2-mm1 v2.6.16-rc2-mm1
> 
> Are you sure that it is 'tag' there?
> 

Yes, this is directly from Junio.

> BTW. you are actually encouraged to use "git fetch" and "git checkout",
> unless in scripts.
>
>> The git-fetch apparently gets "linux-trees.git" and places a reference to
>> it in a tag named 'v2.6.16-rc2-mm1'. Then the git-checkout, check's out
>> this tag to a new branch, there was no merge! This is confusing and makes
>> no sense to this newbie.   
> 
> The git-fetch fetches _from_ linux-trees.git repository. It fetches tag
> v2.6.16-rc2-mm1 (and its lineage, i.e. everything pointed by this tag,
> transitively) and stores it as local tag v2.6.16-rc2-mm1. You cannot
> checkout tag (you can't commit to tag), so you have to create new branch
> for your changes (or for checkout).
>  
>> Now lets take a quick look at the git-merge documentation "HOW MERGE
>> WORKS": 
>>
>> "A merge is always between the current HEAD and one or more remote branch
>> heads, and the index file must exactly match the tree of HEAD commit (i.e.
>> the contents of the last commit) when it happens. In other words, git-diff
>> --cached HEAD must report no changes."   
> 
> That's a bit untrue, because merge can happen between local branches too.
>  
>> Sorry, there is basically no information in those two sentences that makes
>> any sense to me. Take the first part, "between the current HEAD and one or
>> more remote branch heads". So apparently merges occur against the current
>> checkout branch, but I would guess the origin is also involved somehow? 
> 
> Current HEAD is current checked out branch. You merge current HEAD and one
> or more [remote] branch heads (in the pull case, those not marked
> not-for-merge in FETCH_HEAD), and place result in current branch.
> 
>> Secondly, what is the relationship between "remote branch heads" and
>> FETCH_HEAD? I see no mention of FETCH_HEAD or how it might be used
>> anywhere in the git-merge documentation.
> 
> FETCH_HEAD is low-lewel, not to be used by end-user (unless he/she wants to
> do something unusual).
> 

Then why mention it at all?

>> Then we come to "the index file 
>> must exactly match the tree HEAD commit", sorry but my question is how
>> could it not match? 
> 
> For example if you git-add'ed some files, but not committed the addition.

But if I've added some files, it would seem perfectly reasonable that 
git could still "merge" unless the new files conflicted with new files 
in the fetch.

> 
>> Obviously I don't understand how the index file is 
>> used, but I can say that adding "git-diff --cached HEAD must report no no
>> changes" adds nothing to the explanation, yet I'm sure it does mean
>> something to an expert.          
> 
> It adds command which you can use to check _why_ merge failed to run.
> 
>> It then goes onto say "it may fetch the objects from remote" I thought
>> that is what "fetch" does. 
> 
> IIRC this explanation is in git-pull(1). Pull in git is _fetch_ + merge.
>  

So a source of confusion is fetch also does merging/fast-forwarding, 
this is confusing. Fetch should fetch, merge should merge, pull should 
do both.

Another source of confusion is we start out with two branches after 
cloning _master_ & _origin_. Now if I create my own branch and check it 
out and then do a pull, what is going to be merged where and when?

I need to read, re-read and actually understand git-merge the "Grand 
Unified Merge Driver", I can see it's very powerful but with that power 
comes confusion.

At the moment my current situation is that I've cloned 2.6.19 done some 
pulls created some of my own branches and done a git-fetch on Andrew 
Morton's "tree". In .git/remotes I only have the file origin.

git-branch shows:

wink@winkc2d1:~/linux/linux-2.6$ git-branch
* ace
   local-2.6.19-rc4-mm2
   master
   origin
   w8

In tags I have:

wink@winkc2d1:~/linux/linux-2.6$ ls .git/refs/tags
ace-0.0.1     v2.6.13-rc3  v2.6.15-rc1  v2.6.16-rc5  v2.6.18-rc3
v2.6.11       v2.6.13-rc4  v2.6.15-rc2  v2.6.16-rc6  v2.6.18-rc4
v2.6.11-tree  v2.6.13-rc5  v2.6.15-rc3  v2.6.17      v2.6.18-rc5
v2.6.12       v2.6.13-rc6  v2.6.15-rc4  v2.6.17-rc1  v2.6.18-rc6
v2.6.12-rc2   v2.6.13-rc7  v2.6.15-rc5  v2.6.17-rc2  v2.6.18-rc7
v2.6.12-rc3   v2.6.14      v2.6.15-rc6  v2.6.17-rc3  v2.6.19-rc1
v2.6.12-rc4   v2.6.14-rc1  v2.6.15-rc7  v2.6.17-rc4  v2.6.19-rc2
v2.6.12-rc5   v2.6.14-rc2  v2.6.16      v2.6.17-rc5  v2.6.19-rc3
v2.6.12-rc6   v2.6.14-rc3  v2.6.16-rc1  v2.6.17-rc6  v2.6.19-rc4
v2.6.13       v2.6.14-rc4  v2.6.16-rc2  v2.6.18      v2.6.19-rc4-mm2
v2.6.13-rc1   v2.6.14-rc5  v2.6.16-rc3  v2.6.18-rc1
v2.6.13-rc2   v2.6.15      v2.6.16-rc4  v2.6.18-rc2

In remotes I have:

wink@winkc2d1:~/linux/linux-2.6$ ls .git/remotes
origin

So it would seem that I have no _remote_ connection to AM's tree and 
when I did the fetch it added objects which, from the perspective of 
linus's tree, is just a branch that I could have created by hand.

Now when I do my next git-pull from linu's tree what is going to happen 
with regards to my various branches if we assume that *ace is currently 
checked out.

Here is the current state:

origin			unchanged
master			unchanged
ace			locally modified and currently checked out
w8			locally modified
local-2.6.19-rc4-mm2	unchanged just a checkout of tag v2.6.19-rc4-mm2

Thanks,

Wink

Re: Did anyone have trouble learning the idea of local vs. remote branches?

[Jakub Narebski]

Please leave only the parts you are replying to when replying.
Thanks in advance.

Wink Saville wrote:
> Jakub Narebski wrote:
>> Wink Saville wrote:
>> 
>>> It turns out the instructions were incorrect and Junio was 
>>> kind enough to correct the mistake. But I for one am still confused.  
>>>
>>>   git-fetch is; "Download objects and a head from another repository"
>>>
>>> Fair enough and that make sense, but where does it go? Apparently it just
>>> gets stored in the object database and a reference to it in "FETCH_HEAD".
>>> Now what? Ok the documentation says:  
>> 
>> Objects gets stored into object database. Then (using FETCH_HEAD) heads
>> of tracking branches gets updated (i.e. if there were some changes on
>> branch 'master' in remote, the objects are downloaded, then head of local
>> tracking branch corresponding to remote branch 'master', e.g. 'origin',
>> gets updated with the value in 'master'; so called fast-forward case).
>>  
> 
> OK, so fetch does more than just fetching, it also merges, confusing 
> especially given the that the Description says otherwise.

No, git-fetch just (for each head/each branch) download the changes,
_and_ updates head i.e. pointer to the downloaded changes. Without updating
head you wouldn't be able to access downloaded changes. git-fetch doesn't
do merge: it does only fast-forward.

For example, if you have on your branch 'next':

  [local]   A---B---C <-- next

and the repository you fetch from has few more commits:

  [remote]  A---B---C---D---E <-- next

git-fetch downloads the objects (see that graoh for [local] is subgraph
of graph for [remote] - this is fast-forward case)

  [local]   A---B---C---D---E
                    ^
                    \--- next

and then updates next, but only in fast-forward case (the exception being
that you can demand fetch also for non-fast forward case)

  [local]  A---B---C---D---E <-- next

> I just searched git-fetch documentation and I see it mentioned under the 
> <refspec> documentation. I read the words but why do I have to tell it 
> what the source & destination. From my perspective the source is the url 
> and the destination is my repository. So refspec doesn't make sense, of 
> course it's my problem I'm not blaming git or the documentation. But as 
> a newbie I'm confused.

The confusion seems to descend from the fact, that there can be multiple
branches in git repository. When fetching, you must provide the URL to the
repository, which remote branches do you want to download, and what those
tracking branches should be named in your repository. You can create shortcut
name which contains all those info: the URL of repository and the <refspecs>,
i.e. mapping from remote branches (which you want to download) names to the
local branch names (what you want to save them as...) either as so called
'remotes' file (file in .git/remotes) or, in latest version of git, in the
repository config. git-clone (or git-clone --use-separate-remotes)
creates remote file called 'origin', so you can use "git fetch origin" to
fetch the changes made since the time you cloned the repository or fetched
from it.
 
> As I continue to investigate the <refspec> documentation it mentions in 
> the first "Note" that ".. rewound and rebased frequently, the a pull .." 
> . OK, so why is "pull" mentioned here I'm not pulling I'm fetching. Of 
> course if you go to the git-pull documentation we see the <refspec> 
> repeated. Which maybe isn't surprising since pull is a fetch+merge. So I 
> guess the confusing part is that fetch does do merging, even though it 
> says it implies it doesn't.

Again: fetch does not do merging. It's historical that the fetch refspecs
are called "Pull:" lines.

>>> Now in the case of fetching -mm apparently you don't do a merge, instead
>>> the instructions now read: 
>>>
>>>   $ git-fetch \
>>>     git://git.kernel.org/pub/scm/linux/kernel/git/smurf/linux-trees.git \
>>>     tag v2.6.16-rc2-mm1  
>>>   $ git-checkout -b local-v2.6.16-rc2-mm1 v2.6.16-rc2-mm1
>> 
>> Are you sure that it is 'tag' there?
> 
> Yes, this is directly from Junio.

Ooops, I haven't read git-fetch(1) carefully enough:

  Some short-cut notations are also supported.

  * tag <tag> means the same as refs/tags/<tag>:refs/tags/<tag>;  it
    requests fetching everything up to the given tag.

>>> Secondly, what is the relationship between "remote branch heads" and
>>> FETCH_HEAD? I see no mention of FETCH_HEAD or how it might be used
>>> anywhere in the git-merge documentation.
>> 
>> FETCH_HEAD is low-lewel, not to be used by end-user (unless he/she wants to
>> do something unusual).
> 
> Then why mention it at all?

Obsolete documentation? It's agreed that git-merge is neither fish nor fowl,
neither plumbing (engine) command, nor truly porcelain (UI) command.

You should rather use git-pull, than run git-merge by hand. git-pull uses
git-merge, with FETCH_HEAD as one of arguments.
 
>>> Then we come to "the index file 
>>> must exactly match the tree HEAD commit", sorry but my question is how
>>> could it not match? 
>> 
>> For example if you git-add'ed some files, but not committed the addition.

Or git-update-index some file, or you are in the middle of resolving
merge conflict, or you removed some files...
 
> But if I've added some files, it would seem perfectly reasonable that 
> git could still "merge" unless the new files conflicted with new files 
> in the fetch.

In which case it would be too late. Git detects possibility of conflict
(not clean index), and aborts early.

>>> It then goes onto say "it may fetch the objects from remote" I thought
>>> that is what "fetch" does. 
>> 
>> IIRC this explanation is in git-pull(1). Pull in git is _fetch_ + merge.
>>  
> 
> So a source of confusion is fetch also does merging/fast-forwarding, 
> this is confusing. Fetch should fetch, merge should merge, pull should 
> do both.

Fetch without updating refs would mean no access to downloaded objects.
Refs updating happend only (unless forced) in fast-forward case, i.e.
in the case of merge which is not a merge.

> Another source of confusion is we start out with two branches after 
> cloning _master_ & _origin_. Now if I create my own branch and check it 
> out and then do a pull, what is going to be merged where and when?

Use --use-separate-remotes if master/origin confuses you. In short:
 
without --use-separate-remotes:

   local branch    | remote branch   | can commit  | should commit
   ----------------------------------------------------------------
   master          | ----            | Yes         | Yes
   origin          | master          | Yes         | No
   next            | next            | Yes         | No

Master branch is for _your_ work. When you are on master branch, and do
'git pull', git does fetching and the merges _topmost_ branch in remotes
file ('origin') into current branch ('master').

with --use-separate-remotes

   local branch          | remote branch | can commit | should commit
   ------------------------------------------------------------------
   master                | ----          | Yes        | Yes
   remotes/origin/master | master        | No         | No
   remotes/origin/next   | next          | No         | No

> I need to read, re-read and actually understand git-merge the "Grand 
> Unified Merge Driver", I can see it's very powerful but with that power 
> comes confusion.

Don't use git-merge. Use git-pull. If you want merge local branches, use
'.' as the name of repository (means here: local repository).
 
Yes, this is confusing. Historical reasons, most probably.

[...]
-- 
Jakub Narebski