[PATCH] Docs: Add -X option to git-merge's synopsis.

[PATCH] Docs: Add -X option to git-merge's synopsis.

[Marc Branchaud]

Also move -X's description next to -s's in merge-options.txt.

This makes it easier to learn how to specify merge strategy options.
---

Had to specify a merge strategy option today, and it took a little too
much work to figure out how.

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

diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 9c9618c..ceec787 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -9,7 +9,8 @@ git-merge - Join two or more development histories together
 SYNOPSIS
 --------
 [verse]
-'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
+'git merge' [-n] [--stat] [--no-commit] [--squash]...
+	[-s <strategy>] [-X <strategy-option>]...
 	[--[no-]rerere-autoupdate] [-m <msg>] <commit>...
 'git merge' <msg> HEAD <commit>...
 
diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
index 37ce9a1..722d704 100644
--- a/Documentation/merge-options.txt
+++ b/Documentation/merge-options.txt
@@ -62,6 +62,11 @@ option can be used to override --squash.
 	is used instead ('git merge-recursive' when merging a single
 	head, 'git merge-octopus' otherwise).
 
+-X <option>::
+--strategy-option=<option>::
+	Pass merge strategy specific option through to the merge
+	strategy.
+
 --summary::
 --no-summary::
 	Synonyms to --stat and --no-stat; these are deprecated and will be
@@ -76,8 +81,3 @@ ifndef::git-pull[]
 --verbose::
 	Be verbose.
 endif::git-pull[]
-
--X <option>::
---strategy-option=<option>::
-	Pass merge strategy specific option through to the merge
-	strategy.
-- 
1.7.1.rc0

Re: [PATCH] Docs: Add -X option to git-merge's synopsis.

[Junio C Hamano]

Marc Branchaud <marcnarc@xiplink.com> writes:

> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index 9c9618c..ceec787 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -9,7 +9,8 @@ git-merge - Join two or more development histories together
>  SYNOPSIS
>  --------
>  [verse]
> -'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...
> +'git merge' [-n] [--stat] [--no-commit] [--squash]...
> +	[-s <strategy>] [-X <strategy-option>]...
>  	[--[no-]rerere-autoupdate] [-m <msg>] <commit>...
>  'git merge' <msg> HEAD <commit>...

Good.

> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
> index 37ce9a1..722d704 100644
> --- a/Documentation/merge-options.txt
> +++ b/Documentation/merge-options.txt
> @@ -62,6 +62,11 @@ option can be used to override --squash.
>  	is used instead ('git merge-recursive' when merging a single
>  	head, 'git merge-octopus' otherwise).
>  
> +-X <option>::
> +--strategy-option=<option>::
> +	Pass merge strategy specific option through to the merge
> +	strategy.
> +
>  --summary::
>  --no-summary::
>  	Synonyms to --stat and --no-stat; these are deprecated and will be
> @@ -76,8 +81,3 @@ ifndef::git-pull[]
>  --verbose::
>  	Be verbose.
>  endif::git-pull[]
> -
> --X <option>::
> ---strategy-option=<option>::
> -	Pass merge strategy specific option through to the merge
> -	strategy.
> -- 

This is somewhat imcomplete; the current merge-options.txt seems to be
organized more-or-less alphabetically (begins with "commit", ascends to
"ff", "log", "s-something", and ends with "X"), but it has acquired
additions at random places (e.g. "ff-only").

I do not think reorganizing the option descriptions in functional groups
is a bad idea, and if we make that an overall goal of our documentation
set, the patch is certainly going in the right direction.

I used to prefer alphabetical order slightly over functional grouping
because it would make things easier to find in printed pages, but these
days people read on paper a lot less often, so I am personally fine with
"do not list options in alphabetical order; group them with related
features, and do so consistently across all manual pages".

So I'll take the patch as is, but before going further I would like to
first see list concensus to such a reorganization.

Thanks.

Re: [PATCH] Docs: Add -X option to git-merge's synopsis.

[Marc Branchaud]

Junio C Hamano wrote:
> 
> This is somewhat imcomplete; the current merge-options.txt seems to be
> organized more-or-less alphabetically (begins with "commit", ascends to
> "ff", "log", "s-something", and ends with "X"), but it has acquired
> additions at random places (e.g. "ff-only").
> 
> I do not think reorganizing the option descriptions in functional groups
> is a bad idea, and if we make that an overall goal of our documentation
> set, the patch is certainly going in the right direction.
> 
> I used to prefer alphabetical order slightly over functional grouping
> because it would make things easier to find in printed pages, but these
> days people read on paper a lot less often, so I am personally fine with
> "do not list options in alphabetical order; group them with related
> features, and do so consistently across all manual pages".
> 
> So I'll take the patch as is, but before going further I would like to
> first see list concensus to such a reorganization.

I noticed the alphabetical sorting when I made the patch, so I guess my
opinion on functional grouping is pretty obvious.  FWIW, I find functional
groupings make it easier to find unknown options.  An alphabetical sorting is
really only helpful if you already know what you're looking for.  And in that
case, like you say, these docs are usually read in an electronic form, where
it's easy enough to just do a search for whatever's desired.

In any case, regardless of the consensus on this issue, alphabetical sorting
doesn't seem to make much sense for merge-options.txt given the way it's
included in git-merge.txt and git-pull.txt.

		M.