Re: Could this be done simpler?

"Matthias Andree" [off-list ref] writes:

Neither am I a native writer, why bother… it's more important to write
things clearly than to polish things,...

Hey, calm down.

The current documentation was written back when everybody knew what git
fetch internally did (e.g. left state in .git/FETCH_HEAD) and describing
things from the perspective of what is done internally was "accepted" back
when the alternative was not describing anything in any form ;-)

I took your two questions literally as they were.  That is, 

 * You, like other people, realize that times have changed since then, and
   noticed that even with the correct rendition (it appears the problem
   Merlyn saw was primarily caused by Asciidoc toolchain), the bottom-up
   description based on what is done internally is not sufficient.

 * You are volunteering to make things better, but you first need input to
   make sure the result is not just readable but technically correct.

 * And I was among the few people who were around when .git/FETCH_HEAD and
   "git fetch --append" were invented to give precise answers to these
   questions.

No way I meant that these two answers should replace the current
documentation.

Let's change roles (or perspective) for a moment, for the sake of
clarity  and usability: I am just a Git user. I don't want to hack
Git. I couldn't  care less about implementation details such as
FETCH_HEAD, I only need to  know how I can tell Git to merge branches
foo, bar, baz into master in one  single merge.

Yes, that is the good starting point.

"git pull" (at bird eye's view) is just a short-cut for "git fetch
something" and "git merge with somehow configured branch" (somehow =
implicitly through setting up tracking branches, or clone)

Actually the latter is "with information somehow left by git-fetch".

FETCH_HEAD(5)
-------------------------------------------------
This file in the git directory records which heads have been
downloaded,  from where, and for what purpose. Each line in this file
is one  TAB-delimited record with three fields. From left to right,
these fields  contain:

1 - the commit of the remote head
2 - "not-for-merge" if the branch is not meant to be merged,
otherwise,  this field remains empty
3 - branch 'xxx' of UUU, where xxx and UUU are the remote repository's
refname and base URL, respectively.

This file is written by git-fetch and used by git-merge.
-------------------------------------------------

It is true that git-merge does use it, but not under its normal mode of
operation.  Unless the reader of this paragraph is hacking git, I do not
think s/he needs to (nor wants to) know about it.  IIRC, it only triggers
if you do

	$ git merge FETCH_HEAD

The more prominent user is git-pull.  git-fetch leaves the instructions to
git-pull so that the latter knows what to use when it drives git-merge in
this file.

git-fetch(1)
-------------------------------------------------
...
     -a::
     --append::
	This option allows you to fetch and accumulate multiple remote
refs for  future merging.  Normally, git-fetch records the latest
fetch for a later  merge, by writing them to .git/FETCH_HEAD (there
can be multiple recorded  heads in FETCH_HEAD although the name
suggests there were just one).

I personally find the parenthesized comment at the end just distracting
and confusing.  You are explicitly saying "by writing THEM" so it is clear
that the file can and does record more than one when the user instructs
the command to.

....  The  --append option lets git-fetch
keep, rather than delete, prior contents of  the file.  This can be
ueful when consolidating multiple topic branches in  one single merge
(a so-called octopus merge, see git-merge(1)). Example:

The description lacks one important point.  It can be useful only when
consolidating multiple topic branches _that come from more than one remote
repositories_

Other than that, the above paragraph is perfect.

NOTE: git-fetch accepts command lines without refspec. These mark
fetched  heads as "not-for-merge". IOW, a refspec is needed that heads
are marked  as for-merge. I haven't found this documented in
git-fetch.

Sorry, I have no idea what you are talking about in these four lines.

Perhaps "DEFAULT BEHAVIOUR" section in Documentation/git-pull.txt, the
paragraph that begins with "The rule to determine which remote branch to
merge ..." may be what you are looking for?