"Matthias Andree" <matthias.andree@xxxxxx> 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? -- 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