{"thread":{"id":"14752","subject":"[RFC/PATCH v4 2/2] documentation: merge-base: explain \"git merge-base\" with more than 2 args","startedAt":"2008-07-30T05:04:43Z","lastAt":"2008-07-30T05:04:43Z","messageCount":1,"participants":["Christian Couder"],"isPatch":true,"patchVersion":4,"patchTotal":2},"messages":[{"id":"85572","messageId":"20080730070443.f137efd1.chriscool@tuxfamily.org","threadId":"14752","inReplyTo":null,"subject":"[RFC/PATCH v4 2/2] documentation: merge-base: explain \"git merge-base\" with more than 2 args","fromName":"Christian Couder","fromEmail":"chriscool@tuxfamily.org","sentAt":"2008-07-30T05:04:43Z","receivedAt":"2008-07-30T05:04:43Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"From: Junio C Hamano <gitster@pobox.com>\n\nSigned-off-by: Christian Couder <chriscool@tuxfamily.org>\n---\n Documentation/git-merge-base.txt |   77 ++++++++++++++++++++++++++++++++-----\n 1 files changed, 66 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt\nindex 1a7ecbf..fd4b5c9 100644\n--- a/Documentation/git-merge-base.txt\n+++ b/Documentation/git-merge-base.txt\n@@ -8,26 +8,81 @@ git-merge-base - Find as good common ancestors as possible for a merge\n \n SYNOPSIS\n --------\n-'git merge-base' [--all] <commit> <commit>\n+'git merge-base' [--all] <commit> <commit>...\n \n DESCRIPTION\n -----------\n \n-'git-merge-base' finds as good a common ancestor as possible between\n-the two commits. That is, given two commits A and B, `git merge-base A\n-B` will output a commit which is reachable from both A and B through\n-the parent relationship.\n+'git-merge-base' finds best common ancestor(s) between two commits to use\n+in a three-way merge.  One common ancestor is 'better' than another common\n+ancestor if the latter is an ancestor of the former.  A common ancestor\n+that does not have any better common ancestor than it is a 'best common\n+ancestor', i.e. a 'merge base'.  Note that there can be more than one\n+merge bases between two commits.\n \n-Given a selection of equally good common ancestors it should not be\n-relied on to decide in any particular way.\n-\n-The 'git-merge-base' algorithm is still in flux - use the source...\n+Among the two commits to compute their merge bases, one is specified by\n+the first commit argument on the command line; the other commit is a\n+(possibly hypothetical) commit that is a merge across all the remaining\n+commits on the command line.  As the most common special case, giving only\n+two commits from the command line means computing the merge base between\n+the given two commits.\n \n OPTIONS\n -------\n --all::\n-\tOutput all common ancestors for the two commits instead of\n-\tjust one.\n+\tOutput all merge bases for the commits, instead of just one.\n+\n+DISCUSSION\n+----------\n+\n+Given two commits 'A' and 'B', `git merge-base A B` will output a commit\n+which is reachable from both 'A' and 'B' through the parent relationship.\n+\n+For example, with this topology:\n+\n+                 o---o---o---B\n+                /\n+        ---o---1---o---o---o---A\n+\n+the merge base between 'A' and 'B' is '1'.\n+\n+Given three commits 'A', 'B' and 'C', `git merge-base A B C` will compute the\n+merge base between 'A' and an hypothetical commit 'M', which is a merge\n+between 'B' and 'C'.  For example, with this topology:\n+\n+               o---o---o---o---C\n+              /\n+             /   o---o---o---B\n+            /   /\n+        ---2---1---o---o---o---A\n+\n+the result of `git merge-base A B C` is '1'.  This is because the\n+equivalent topology with a merge commit 'M' between 'B' and 'C' is:\n+\n+\n+               o---o---o---o---o\n+              /                 \\\n+             /   o---o---o---o---M\n+            /   /\n+        ---2---1---o---o---o---A\n+\n+and the result of `git merge-base A M` is '1'.  Commit '2' is also a\n+common ancestor between 'A' and 'M', but '1' is a better common ancestor,\n+because '2' is an ancestor of '1'.  Hence, '2' is not a merge base.\n+\n+When the history involves criss-cross merges, there can be more than one\n+'best' common ancestors between two commits.  For example, with this\n+topology:\n+\n+       ---1---o---A\n+\t   \\ /\n+\t    X\n+\t   / \\\n+       ---2---o---o---B\n+\n+both '1' and '2' are merge-base of A and B.  Neither one is better than\n+the other (both are 'best' merge base).  When `--all` option is not given,\n+it is unspecified which best one is output.\n \n Author\n ------\n-- \n1.6.0.rc0.42.g186458.dirty\n"}]}