threads / patch / 23433

patchDocs: Add -X option to git-merge's synopsis.

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

## tl;dr

3 messages between Apr 12, 2010 and Apr 12, 2010. Diffs are folded; open one to read it.

replies: 2people: 2as markdown or json

Marc Branchaud· Apr 12, 2010, 16:28 UTC · lore

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(-)

Show changes to 2 files +7 −5

Documentation/git-merge.txt, Documentation/merge-options.txt

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

Junio C Hamano· Apr 12, 2010, 16:45 UTC · re: Marc Branchaud · lore

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

Marc Branchaud <marcnarc@xiplink.com> writes:

Show 13 quoted lines

> 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.

Show 26 quoted lines

> 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.

Marc Branchaud· Apr 12, 2010, 17:11 UTC · re: Junio C Hamano · lore

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

Junio C Hamano wrote:

Show 18 quoted lines

> 
> 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.