Junio C Hamanolinux@horizon.com writes:
> 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.
Show 7 quoted lines
> * Git's representation of history >... > And then there are commits which have multiple parents. Two is most > common, but git allows many more. (There's a limit of sixteen in the > source code, and the most anyone's ever used in real life is 12, and > that was generally regarded as overdoing it. Google on "doedecapus" > for discussion of it.)
Dodecapus would find a few, no hits on doedecapus ;-).
Show 5 quoted lines
> * 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.
> * Remote tags > > TODO: Figure out how remote tags work, under what circumstances > they are fetched, and what git does if there are conflicts.
One bug in my previous response is that I said we do this only when the command was invoked with shorthand remote name. Not so. We do this only when we use tracking branches.
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.
Show 16 quoted lines
> * Exchanging work with other repositories, part II: git-push >... > You have to merge the changes locally, and re-try the push when you've > got a new head that includes the most recently pushed work as an ancestor. > > This is exactly like "cvs commit" not working if your recent checkout > wasn't the (current) tip of the branch, but git can upload more than > one commit. > > The simplest way to resolve the conflict is to merge the remote head with > your local head. This is easiest if you have different local branches > for fetching the remote repository and for pushing to it. > > That is, you have one head that just tracks the master repository's > main branch, and another that you add your work to, and push from. > This makes merging simpler when there are conflicts.
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.
Show 9 quoted lines
> * Merging (finally!) > > I went through everything else first because the most common merge case > is local changes with remote changes. Not that you can't merge two > branches of your own, but you don't need to do that nearly as often. > > 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.
Show 7 quoted lines
> 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.
Show 8 quoted lines
> * How merging operates >... > If all three of a given file in O, A, B are different, then the three > versions are pulled into the index file, called "stage 1", "stage 2", > and "stage 3", and a merge strategy driver is called to resolve the mess. > Git then uses the classic line-based three-way merge, looking for isolated > changes and applying the same rules as for files when two of the source > files are the same in some range.
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.
Show 25 quoted lines
> * When merging goes wrong
>...
> and the result of "git diff" is
>
> diff --cc hello.c
> index 4b7f550,948a5f8..0000000
> --- a/hello.c
> +++ b/hello.c
> @@@ -3,5 -3,6 +3,10 @@@
> int
> main(void)
> {
> ++<<<<<<< HEAD/hello.c
> + printf("Goodbye, cruel world!");
> ++=======
> + printf("Hello, world!\n");
> + return 0;
> ++>>>>>>> edadc53fc7a8aef2a672a4fa9d09aa16f4e14706/hello.c
> }
>
> Notice how this is not a standard diff! It has two columns of diff
> symbols, and shows the difference from each of the ancestors to the
> current hello.c contents. I can also use "git diff -1" to compare
> against the common ancestor, or "-2" or "-3" to compare against each of
> the merged copies individually.Another tool to help the user decide how the mess should be sorted out is "git log --merge -- $path". It gives the logs of commits that touched the path while the two branches were forked.
> * Cherry picking >... > You van get the list of commits on a branch with git-log or git-rev-list,
s/van/can/
> * Rebasing >... > 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.
>... > This will find all patches that are in dev and not in dev1, > apply them on top of master, and call the result dev2.
Show 18 quoted lines
> * Experimenting with merging >... > $ git status > Hey, look, lots of interesting stuff. Particularly, see > # Changed but not updated: > # (use git-update-index to mark for commit) > # > # unmerged: Makefile > # modified: Makefile > # unmerged: builtin.h > # modified: builtin.h > # unmerged: git.c > # modified: git.c > > The "unmerged" (a.k.a. "staged") files are ones that need manual resolution. > > (I notice that update-index.c isn't listed, despite being mentioned > as a conflict in the message. Can someone explain that?)
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).