Re: [DRAFT] Branching and merging with git

>> One outstanding problem with git's man pages is that often the most detail
>> is in the command page that was written first, not the user-friendly
>> one that you should use.
> 
> This is a very important point to remember not for users but for
> us in git community.  Thanks for writing it down.

>> * Deleting branches
>>
>> "git branch -d <head>" is safe.  It deletes the given <head>, but first
>> it checks that the commit is reachable some other way.  That is, you
>> merged the branch in somewhere, or you never did any edits on that branch.
> 
> It is not "somewhere" but "in the current branch", so in a sense
> it is a bit stricter than that.  While on 'master' "branch -d
> topic" would not remove the topic branch head if it is not fully
> merged to my 'master' so that is a reasonable safety measure,
> but when I am on 'next' it will happily remove it.  It is
> recoverable because it is reachable from 'next', though.

> The reason is because 'git pull $url $branch' (typical Linus's
> use) and 'git pull' (defaulting to 'origin' and using the
> tracking branch mapping stored in .git/remotes/origin prepared
> by git-clone) are sign of very different workflows.  The former
> tends to be a one-shot event while the latter is most often
> synchronizing with either an upstream or a common distribution
> point (i.e. shared central repostiory).  When you are fetching
> from somebody in a one-shot manner, most likely as a part of
> 'pull', you do not want to get the tag the other person has made
> to mark his private work in progress.  But in the latter case,
> the other end is where everybody who works in the same area
> fetches from, and sharing the tags found there among the
> developers by default is desirable, and more importantly there
> is no risk of accidentally getting private tags, since the other
> end is a public distribution point and by definition should not
> have private tags that would clutter your refs/tags hierarchy.

> Here you _might_ want to mention an alternative workflow that
> uses rebase, which seems to be the way Wine folks run their
> project.  Talking about all the different possibilities tends to
> cloud things and may not add value to the document, so I am just
> mentioning it as a possibility but I do not know if talking
> about rebase is useful in the context of this document.

>> The primitive that does the merging is called (guess what?) git-merge.
>> And you can use that if you want.  If you want to create a so-called
>> octopus merge, with more than two parents, you have to.
> 
> This is not true; "git pull . topicA topicB topicC" works as
> expected.  But we probably would not want to even talk about
> Octopus in a document like this.  It is a curosity, and
> sometimes tends to make histories even less cluttered, but
> otherwise it does not add much value.

>> However, it's usually easier to use the git-pull wrapper.  This merges
>> the changes from some other branch into the current HEAD and generates
>> a commit message automatically.
>>
>> git-merge lets you specify the commit message (rather than generating it
>> automatically) and use a non-HEAD destination branch, but those options
>> are usually more annoying than useful.
> 
> I haven't tried for a long time, but I do not think non-HEAD
> destination even works at all.  It might be better not to even
> mention git-merge at this point of the document.

>> * How merging operates
> 
> You might also want to mention that recursive first 3-way merges
> the renames.  If O->A renames a path while O->B keeps it, the
> resulting stages are written under the new name.

>> Git-rebase can also help you divide up work.  Suppose you've mixed up
>> development of two features in the current HEAD, a branch called "dev".
> 
> Ancestry graph before and after this procedure would help the
> reader a lot here.

> They were conflicts during the virtual ancestor computation by
> recursive (the merge between 'a' and 'b' commits in your earlier
> example).  When a virtual ancestor is created, it can textually
> have conflicted merge, but that is recorded along with conflict
> markers without manual resolving for obvious reasons.  If two
> branches that use the virtual ancestor modifies the conflicted
> region the same way (because they needed to resolve that
> conflict in their branch), the final 3-way merge that uses the
> virtual ancestor as the merge-base will replace that conflicted
> region with their changes.  This "even conflict markers can be
> eliminated by a merge resolution" behaviour is what inspired
> git-rerere, by the way.

> If you are using this particular commit as an example, you might
> also want to tell your readers about:
> 
> 	git show -M 3f69d405
> 
> (-M is there to make the output more readable, because this
> merge involved a few renames).