Re: [PATCH] Docs: Add -X option to git-merge's synopsis.
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Apr 12, 2010, 16:45 UTC
- Message-ID
- <7v39z0livd.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <1271089693-21365-1-git-send-email-marcnarc@xiplink.com>
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.