{"thread":{"id":"23433","subject":"[PATCH] Docs: Add -X option to git-merge's synopsis.","startedAt":"2010-04-12T16:28:13Z","lastAt":"2010-04-12T17:11:37Z","messageCount":3,"participants":["Marc Branchaud","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"139356","messageId":"1271089693-21365-1-git-send-email-marcnarc@xiplink.com","threadId":"23433","inReplyTo":null,"subject":"[PATCH] Docs: Add -X option to git-merge's synopsis.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2010-04-12T16:28:13Z","receivedAt":"2010-04-12T16:28:13Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"Also move -X's description next to -s's in merge-options.txt.\n\nThis makes it easier to learn how to specify merge strategy options.\n---\n\nHad to specify a merge strategy option today, and it took a little too\nmuch work to figure out how.\n\n Documentation/git-merge.txt     |    3 ++-\n Documentation/merge-options.txt |   10 +++++-----\n 2 files changed, 7 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 9c9618c..ceec787 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -9,7 +9,8 @@ git-merge - Join two or more development histories together\n SYNOPSIS\n --------\n [verse]\n-'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...\n+'git merge' [-n] [--stat] [--no-commit] [--squash]...\n+\t[-s <strategy>] [-X <strategy-option>]...\n \t[--[no-]rerere-autoupdate] [-m <msg>] <commit>...\n 'git merge' <msg> HEAD <commit>...\n \ndiff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt\nindex 37ce9a1..722d704 100644\n--- a/Documentation/merge-options.txt\n+++ b/Documentation/merge-options.txt\n@@ -62,6 +62,11 @@ option can be used to override --squash.\n \tis used instead ('git merge-recursive' when merging a single\n \thead, 'git merge-octopus' otherwise).\n \n+-X <option>::\n+--strategy-option=<option>::\n+\tPass merge strategy specific option through to the merge\n+\tstrategy.\n+\n --summary::\n --no-summary::\n \tSynonyms to --stat and --no-stat; these are deprecated and will be\n@@ -76,8 +81,3 @@ ifndef::git-pull[]\n --verbose::\n \tBe verbose.\n endif::git-pull[]\n-\n--X <option>::\n---strategy-option=<option>::\n-\tPass merge strategy specific option through to the merge\n-\tstrategy.\n-- \n1.7.1.rc0\n"},{"id":"139358","messageId":"7v39z0livd.fsf@alter.siamese.dyndns.org","threadId":"23433","inReplyTo":"1271089693-21365-1-git-send-email-marcnarc@xiplink.com","subject":"Re: [PATCH] Docs: Add -X option to git-merge's synopsis.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-12T16:45:42Z","receivedAt":"2010-04-12T16:45:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Marc Branchaud <marcnarc@xiplink.com> writes:\n\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index 9c9618c..ceec787 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -9,7 +9,8 @@ git-merge - Join two or more development histories together\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git merge' [-n] [--stat] [--no-commit] [--squash] [-s <strategy>]...\n> +'git merge' [-n] [--stat] [--no-commit] [--squash]...\n> +\t[-s <strategy>] [-X <strategy-option>]...\n>  \t[--[no-]rerere-autoupdate] [-m <msg>] <commit>...\n>  'git merge' <msg> HEAD <commit>...\n\nGood.\n\n> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt\n> index 37ce9a1..722d704 100644\n> --- a/Documentation/merge-options.txt\n> +++ b/Documentation/merge-options.txt\n> @@ -62,6 +62,11 @@ option can be used to override --squash.\n>  \tis used instead ('git merge-recursive' when merging a single\n>  \thead, 'git merge-octopus' otherwise).\n>  \n> +-X <option>::\n> +--strategy-option=<option>::\n> +\tPass merge strategy specific option through to the merge\n> +\tstrategy.\n> +\n>  --summary::\n>  --no-summary::\n>  \tSynonyms to --stat and --no-stat; these are deprecated and will be\n> @@ -76,8 +81,3 @@ ifndef::git-pull[]\n>  --verbose::\n>  \tBe verbose.\n>  endif::git-pull[]\n> -\n> --X <option>::\n> ---strategy-option=<option>::\n> -\tPass merge strategy specific option through to the merge\n> -\tstrategy.\n> -- \n\nThis is somewhat imcomplete; the current merge-options.txt seems to be\norganized more-or-less alphabetically (begins with \"commit\", ascends to\n\"ff\", \"log\", \"s-something\", and ends with \"X\"), but it has acquired\nadditions at random places (e.g. \"ff-only\").\n\nI do not think reorganizing the option descriptions in functional groups\nis a bad idea, and if we make that an overall goal of our documentation\nset, the patch is certainly going in the right direction.\n\nI used to prefer alphabetical order slightly over functional grouping\nbecause it would make things easier to find in printed pages, but these\ndays people read on paper a lot less often, so I am personally fine with\n\"do not list options in alphabetical order; group them with related\nfeatures, and do so consistently across all manual pages\".\n\nSo I'll take the patch as is, but before going further I would like to\nfirst see list concensus to such a reorganization.\n\nThanks.\n"},{"id":"139360","messageId":"4BC35449.4020706@xiplink.com","threadId":"23433","inReplyTo":"7v39z0livd.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Docs: Add -X option to git-merge's synopsis.","fromName":"Marc Branchaud","fromEmail":"marcnarc@xiplink.com","sentAt":"2010-04-12T17:11:37Z","receivedAt":"2010-04-12T17:11:37Z","isPatch":true,"sender":{"key":"marcnarc@xiplink.com","avatar":"https://avatars.githubusercontent.com/u/14980203?v=4"},"body":"Junio C Hamano wrote:\n> \n> This is somewhat imcomplete; the current merge-options.txt seems to be\n> organized more-or-less alphabetically (begins with \"commit\", ascends to\n> \"ff\", \"log\", \"s-something\", and ends with \"X\"), but it has acquired\n> additions at random places (e.g. \"ff-only\").\n> \n> I do not think reorganizing the option descriptions in functional groups\n> is a bad idea, and if we make that an overall goal of our documentation\n> set, the patch is certainly going in the right direction.\n> \n> I used to prefer alphabetical order slightly over functional grouping\n> because it would make things easier to find in printed pages, but these\n> days people read on paper a lot less often, so I am personally fine with\n> \"do not list options in alphabetical order; group them with related\n> features, and do so consistently across all manual pages\".\n> \n> So I'll take the patch as is, but before going further I would like to\n> first see list concensus to such a reorganization.\n\nI noticed the alphabetical sorting when I made the patch, so I guess my\nopinion on functional grouping is pretty obvious.  FWIW, I find functional\ngroupings make it easier to find unknown options.  An alphabetical sorting is\nreally only helpful if you already know what you're looking for.  And in that\ncase, like you say, these docs are usually read in an electronic form, where\nit's easy enough to just do a search for whatever's desired.\n\nIn any case, regardless of the consensus on this issue, alphabetical sorting\ndoesn't seem to make much sense for merge-options.txt given the way it's\nincluded in git-merge.txt and git-pull.txt.\n\n\t\tM.\n"}]}