[PATCH/resend] Documentation: update to git-merge-base --octopus

[PATCH/resend] Documentation: update to git-merge-base --octopus

[Vincent van Ravesteijn]

1) Make it clear that when the --octopus parameter is given to 'git merge-base',
only a set of commits is expected as the parameter. On the other hand, in the
case without the --octopus parameter, it is necessary to supply a single commit
and a set. Moreover, in the case of --octopus merging, a single commit is also valid,
which is not the case otherwise.

2) Add a sentence to the discussion that when --octopus is used, we do expect '2'
as the result.

Signed-off-by: Vincent van Ravesteijn <vfr@lyx.org>
---
Sorry for the noise caused by the previous attempt(s). Apparently my attempts
to let Thunderbird _not wrap_ the lines were counterproductive.

Here is the patch again.

 Documentation/git-merge-base.txt |    6 +++++-
 builtin/merge-base.c             |    3 ++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index eedef1b..1bac04f 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -9,7 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge
 SYNOPSIS
 --------
 [verse]
-'git merge-base' [-a|--all] [--octopus] <commit> <commit>...
+'git merge-base' [-a|--all] <commit> <commit>...
+'git merge-base' [-a|--all] --octopus <commit>...
 'git merge-base' --independent <commit>...

 DESCRIPTION
@@ -89,6 +90,9 @@ and the result of `git merge-base A M` is '1'.  Commit '2' is also a
 common ancestor between 'A' and 'M', but '1' is a better common ancestor,
 because '2' is an ancestor of '1'.  Hence, '2' is not a merge base.

+When the option `--octopus` is given, the result of `git merge-base A B C`
+will be '2', because '2' is the common ancestor of all branches.
+
 When the history involves criss-cross merges, there can be more than one
 'best' common ancestor for two commits.  For example, with this topology:

diff --git a/builtin/merge-base.c b/builtin/merge-base.c
index 96dd160..4f30f1b 100644
--- a/builtin/merge-base.c
+++ b/builtin/merge-base.c
@@ -23,7 +23,8 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)
 }

 static const char * const merge_base_usage[] = {
-	"git merge-base [-a|--all] [--octopus] <commit> <commit>...",
+	"git merge-base [-a|--all] <commit> <commit>...",
+	"git merge-base [-a|--all] --octopus <commit>...",
 	"git merge-base --independent <commit>...",
 	NULL
 };
-- 
1.7.3.1.msysgit.0

Re: [PATCH/resend] Documentation: update to git-merge-base --octopus

[Junio C Hamano]

Vincent van Ravesteijn <vfr@lyx.org> writes:

> Sorry for the noise caused by the previous attempt(s). Apparently my attempts
> to let Thunderbird _not wrap_ the lines were counterproductive.

I was wondering what that was about.

> +When the option `--octopus` is given, the result of `git merge-base A B C`
> +will be '2', because '2' is the common ancestor of all branches.

Wouldn't it be easier to read if you had the option in the command line, i.e.

    The result of `git merge-base --octopus A B C` is '2' because...

without "When ... given" that now become noisewords?

Re: [PATCH/resend] Documentation: update to git-merge-base --octopus

[Jonathan Nieder]

Hi Vincent,

Vincent van Ravesteijn wrote:

> On the other hand, in the
> case without the --octopus parameter, it is necessary to supply a single commit
> and a set. Moreover, in the case of --octopus merging, a single commit is also valid,
> which is not the case otherwise.

So to summarize: unlike plain merge-base, merge-base --octopus only
requires at least one commit argument, and this patch updates the
synopsis to reflect that.  Good catch.

> 2) Add a sentence to the discussion that when --octopus is used, we do expect '2'
> as the result.

Adding an example use of --octopus to the DISCUSSION section makes a
lot of sense.  At first I thought this was being added to the
DESCRIPTION section, which led me to suggest something like the
following:

 DESCRIPTION
 -----------
 'git merge-base' finds best common ancestors between two commits to
 use in a three-way merge.  [... etc etc ...] can be more than one merge
 base for a pair of commits.

 OPERATION MODE
 --------------
 As the most common special case, specifying only two commits on the
 command line means computing the merge base between the given two
 commits.

 More generally, among the two commits to compute the merge base from,
 one is specified by the first commit argument on the command line;
 the other commit is a (possibly hypothetical) commit that is a merge
 across all the remaining commits on the command line.

 As a consequence, the merge base is not necessarily contained in each
 of the commit arguments if more than two commits are specified.
 This is different from git-show-branch(1) when used with
 the --merge-base option.

 --octopus::
	Compute the best common ancestors of all supplied commits, in
	preparation for an n-way merge.
	This mimics the behavior of 'git show-branch --merge-base'.

 --independent::
	Instead of ...

 OPTIONS
 -------
 -a::
 --all::
	...

 DISCUSSION
 ----------

What do you think?

> --- a/Documentation/git-merge-base.txt
> +++ b/Documentation/git-merge-base.txt
> @@ -9,7 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge
[...]
> +When the option `--octopus` is given, the result of `git merge-base A B C`
> +will be '2', because '2' is the common ancestor of all branches.
> +

For what it's worth, except for Junio's wording nitpick and the log message,
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Thanks.

[PATCH v2 1/2] Documentation: update to git-merge-base --octopus

[Vincent van Ravesteijn]

1) Unlike plain merge-base, merge-base --octopus only requires at least one commit
argument, and this patch updates the synopsis to reflect that.

2) Add a sentence to the discussion that when --octopus is used, we do expect '2'
as the result.

Signed-off-by: Vincent van Ravesteijn <vfr@lyx.org>
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-merge-base.txt |    6 +++++-
 builtin/merge-base.c             |    3 ++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index eedef1b..a9f677b 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -9,7 +9,8 @@ git-merge-base - Find as good common ancestors as possible for a merge
 SYNOPSIS
 --------
 [verse]
-'git merge-base' [-a|--all] [--octopus] <commit> <commit>...
+'git merge-base' [-a|--all] <commit> <commit>...
+'git merge-base' [-a|--all] --octopus <commit>...
 'git merge-base' --independent <commit>...

 DESCRIPTION
@@ -89,6 +90,9 @@ and the result of `git merge-base A M` is '1'.  Commit '2' is also a
 common ancestor between 'A' and 'M', but '1' is a better common ancestor,
 because '2' is an ancestor of '1'.  Hence, '2' is not a merge base.

+The result of `git merge-base --octopus A B C` is '2', because '2' is
+the best common ancestor of all commits.
+
 When the history involves criss-cross merges, there can be more than one
 'best' common ancestor for two commits.  For example, with this topology:

diff --git a/builtin/merge-base.c b/builtin/merge-base.c
index 96dd160..4f30f1b 100644
--- a/builtin/merge-base.c
+++ b/builtin/merge-base.c
@@ -23,7 +23,8 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)
 }

 static const char * const merge_base_usage[] = {
-	"git merge-base [-a|--all] [--octopus] <commit> <commit>...",
+	"git merge-base [-a|--all] <commit> <commit>...",
+	"git merge-base [-a|--all] --octopus <commit>...",
 	"git merge-base --independent <commit>...",
 	NULL
 };
-- 
1.7.3.1.msysgit.0

[PATCH 2/2] Restructure documentation for git-merge-base.

[Vincent van Ravesteijn]

From: Jonathan Nieder <jrnieder@gmail.com>

Restructure the text of git-merge-base to better explain more clearly
the different modes of operation.

Signed-off-by: Vincent van Ravesteijn <vfr@lyx.org>

---
 Documentation/git-merge-base.txt |   28 ++++++++++++++++------------
 1 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt
index a9f677b..ca5ed31 100644
--- a/Documentation/git-merge-base.txt
+++ b/Documentation/git-merge-base.txt
@@ -23,23 +23,21 @@ that does not have any better common ancestor is a 'best common
 ancestor', i.e. a 'merge base'.  Note that there can be more than one
 merge base for a pair of commits.

-Unless `--octopus` is given, among the two commits to compute the merge
-base from, one is specified by the first commit argument on the command
-line; the other commit is a (possibly hypothetical) commit that is a merge
-across all the remaining commits on the command line.  As the most common
-special case, specifying only two commits on the command line means
-computing the merge base between the given two commits.
+OPERATION MODE
+--------------
+
+As the most common special case, specifying only two commits on the
+command line means computing the merge base between the given two commits.
+
+More generally, among the two commits to compute the merge base from,
+one is specified by the first commit argument on the command line;
+the other commit is a (possibly hypothetical) commit that is a merge
+across all the remaining commits on the command line.

 As a consequence, the 'merge base' is not necessarily contained in each of the
 commit arguments if more than two commits are specified. This is different
 from linkgit:git-show-branch[1] when used with the `--merge-base` option.

-OPTIONS
--------
--a::
---all::
-	Output all merge bases for the commits, instead of just one.
-
 --octopus::
 	Compute the best common ancestors of all supplied commits,
 	in preparation for an n-way merge.  This mimics the behavior
@@ -52,6 +50,12 @@ OPTIONS
 	from any other.  This mimics the behavior of 'git show-branch
 	--independent'.

+OPTIONS
+-------
+-a::
+--all::
+	Output all merge bases for the commits, instead of just one.
+
 DISCUSSION
 ----------

-- 
1.7.3.1.msysgit.0

Re: [PATCH/resend] Documentation: update to git-merge-base --octopus

[Vincent van Ravesteijn]

>> +When the option `--octopus` is given, the result of `git merge-base A B C`
>> > +will be '2', because '2' is the common ancestor of all branches.
> 
> Wouldn't it be easier to read if you had the option in the command line, i.e.
> 
>     The result of `git merge-base --octopus A B C` is '2' because...
> 
> without "When ... given" that now become noisewords?

Yes, that's much better. I included it in the rerolled patch series.

> Adding an example use of --octopus to the DISCUSSION section makes a
> lot of sense.  At first I thought this was being added to the
> DESCRIPTION section, which led me to suggest something like the
> following:
> 
> [..]
> 
> What do you think?

I like it, so I made a patch out of it and sent it to the list.

> For what it's worth, except for Junio's wording nitpick and the log message,
> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Thanks,

Vincent

Re: [PATCH/resend] Documentation: update to git-merge-base --octopus

[Junio C Hamano]

Vincent van Ravesteijn <vfr@lyx.org> writes:

>>> +When the option `--octopus` is given, the result of `git merge-base A B C`
>>> > +will be '2', because '2' is the common ancestor of all branches.
>> 
>> Wouldn't it be easier to read if you had the option in the command line, i.e.
>> 
>>     The result of `git merge-base --octopus A B C` is '2' because...
>> 
>> without "When ... given" that now become noisewords?
>
> Yes, that's much better. I included it in the rerolled patch series.

Makes sense.  Will queue both patches.

Thanks, both.