{"thread":{"id":"52928","subject":"[PATCH] doc: use 'ref' instead of 'commit' for merge-base arguments","startedAt":"2020-03-03T07:23:23Z","lastAt":"2020-03-04T17:26:07Z","messageCount":9,"participants":["Takuya N via GitGitGadget","Bryan Turner","Johannes Schindelin","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"392773","messageId":"pull.719.git.git.1583220197856.gitgitgadget@gmail.com","threadId":"52928","inReplyTo":null,"subject":"[PATCH] doc: use 'ref' instead of 'commit' for merge-base arguments","fromName":"Takuya N via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-03-03T07:23:17Z","receivedAt":"2020-03-03T07:23:23Z","isPatch":true,"sender":{"key":"name:Takuya N","avatar":null},"body":"From: Takuya Noguchi <takninnovationresearch@gmail.com>\n\nThe notation <commit> can be misunderstandable only for commit SHA1,\nbut merge-base accepts any commit references. Like reflog, the name of\narguments should be <ref> instead of <commit>.\n\nSigned-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>\n---\n    doc: use 'ref' instead of 'commit' for merge-base arguments\n    \n    The notation <commit> can be misunderstandable only for commit SHA1, but \n    merge-base accepts any commit references. Like reflog, the name of\n    arguments should be <ref> rather than <commit>.\n    \n    Signed-off-by: Takuya Noguchi takninnovationresearch@gmail.com\n    [takninnovationresearch@gmail.com]\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-719%2Ftnir%2Fmerge-base-supporting-refs-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-719/tnir/merge-base-supporting-refs-v1\nPull-Request: https://github.com/git/git/pull/719\n\n Documentation/git-merge-base.txt | 10 +++++-----\n builtin/merge-base.c             | 12 ++++++------\n 2 files changed, 11 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt\nindex 2d944e0851f..b87528ef269 100644\n--- a/Documentation/git-merge-base.txt\n+++ b/Documentation/git-merge-base.txt\n@@ -9,11 +9,11 @@ git-merge-base - Find as good common ancestors as possible for a merge\n SYNOPSIS\n --------\n [verse]\n-'git merge-base' [-a|--all] <commit> <commit>...\n-'git merge-base' [-a|--all] --octopus <commit>...\n-'git merge-base' --is-ancestor <commit> <commit>\n-'git merge-base' --independent <commit>...\n-'git merge-base' --fork-point <ref> [<commit>]\n+'git merge-base' [-a|--all] <ref> <ref>...\n+'git merge-base' [-a|--all] --octopus <ref>...\n+'git merge-base' --is-ancestor <ref> <ref>\n+'git merge-base' --independent <ref>...\n+'git merge-base' --fork-point <ref> [<ref>]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/merge-base.c b/builtin/merge-base.c\nindex e3f8da13b69..910916ae0ec 100644\n--- a/builtin/merge-base.c\n+++ b/builtin/merge-base.c\n@@ -29,11 +29,11 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)\n }\n \n static const char * const merge_base_usage[] = {\n-\tN_(\"git merge-base [-a | --all] <commit> <commit>...\"),\n-\tN_(\"git merge-base [-a | --all] --octopus <commit>...\"),\n-\tN_(\"git merge-base --independent <commit>...\"),\n-\tN_(\"git merge-base --is-ancestor <commit> <commit>\"),\n-\tN_(\"git merge-base --fork-point <ref> [<commit>]\"),\n+\tN_(\"git merge-base [-a | --all] <ref> <ref>...\"),\n+\tN_(\"git merge-base [-a | --all] --octopus <ref>...\"),\n+\tN_(\"git merge-base --independent <ref>...\"),\n+\tN_(\"git merge-base --is-ancestor <ref> <ref>\"),\n+\tN_(\"git merge-base --fork-point <ref1> [<ref2>]\"),\n \tNULL\n };\n \n@@ -158,7 +158,7 @@ int cmd_merge_base(int argc, const char **argv, const char *prefix)\n \t\tOPT_CMDMODE(0, \"is-ancestor\", &cmdmode,\n \t\t\t    N_(\"is the first one ancestor of the other?\"), 'a'),\n \t\tOPT_CMDMODE(0, \"fork-point\", &cmdmode,\n-\t\t\t    N_(\"find where <commit> forked from reflog of <ref>\"), 'f'),\n+\t\t\t    N_(\"find where <ref2> forked from reflog of <ref1>\"), 'f'),\n \t\tOPT_END()\n \t};\n \n\nbase-commit: 2d2118b814c11f509e1aa76cb07110f7231668dc\n-- \ngitgitgadget\n"},{"id":"392774","messageId":"CAGyf7-Ez1Fx-VUVmDWxRxLaZcU+Tu4kZ+F2+0uNKkx2oftjEJQ@mail.gmail.com","threadId":"52928","inReplyTo":"pull.719.git.git.1583220197856.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: use 'ref' instead of 'commit' for merge-base arguments","fromName":"Bryan Turner","fromEmail":"bturner@atlassian.com","sentAt":"2020-03-03T07:32:02Z","receivedAt":"2020-03-03T07:32:15Z","isPatch":true,"sender":{"key":"bturner@atlassian.com","avatar":"https://gravatar.com/avatar/16bcf3167981c1ef7c804e502642366d888a35b0d0b0a4ca01fdc442aa1acb1e?d=mp&s=160"},"body":"On Tue, Mar 3, 2020 at 12:23 AM Takuya N via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n>\n> From: Takuya Noguchi <takninnovationresearch@gmail.com>\n>\n> The notation <commit> can be misunderstandable only for commit SHA1,\n> but merge-base accepts any commit references. Like reflog, the name of\n> arguments should be <ref> instead of <commit>.\n\nTo me, this change goes too far in the opposite direction: Now it\nsounds like the command only accepts refs, when it actually accepts\nany \"commit-ish\"--i.e., anything that can be coerced to a commit.\n(\"git worktree\" uses this term in its usage for \"add\", for example.)\n\nAt the same time, it doesn't seem like this change goes far enough.\n\"git merge\"'s documentation, for example, is still using \"<commit>\".\nWhy is it important that \"git merge-base\" mention refs, but not that\n\"git merge\" do so?\n\n(Pardon the outburst from the peanut gallery)\n\n>\n> Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>\n> ---\n>     doc: use 'ref' instead of 'commit' for merge-base arguments\n>\n>     The notation <commit> can be misunderstandable only for commit SHA1, but\n>     merge-base accepts any commit references. Like reflog, the name of\n>     arguments should be <ref> rather than <commit>.\n>\n>     Signed-off-by: Takuya Noguchi takninnovationresearch@gmail.com\n>     [takninnovationresearch@gmail.com]\n>\n> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-719%2Ftnir%2Fmerge-base-supporting-refs-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-719/tnir/merge-base-supporting-refs-v1\n> Pull-Request: https://github.com/git/git/pull/719\n>\n>  Documentation/git-merge-base.txt | 10 +++++-----\n>  builtin/merge-base.c             | 12 ++++++------\n>  2 files changed, 11 insertions(+), 11 deletions(-)\n>\n> diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt\n> index 2d944e0851f..b87528ef269 100644\n> --- a/Documentation/git-merge-base.txt\n> +++ b/Documentation/git-merge-base.txt\n> @@ -9,11 +9,11 @@ git-merge-base - Find as good common ancestors as possible for a merge\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git merge-base' [-a|--all] <commit> <commit>...\n> -'git merge-base' [-a|--all] --octopus <commit>...\n> -'git merge-base' --is-ancestor <commit> <commit>\n> -'git merge-base' --independent <commit>...\n> -'git merge-base' --fork-point <ref> [<commit>]\n> +'git merge-base' [-a|--all] <ref> <ref>...\n> +'git merge-base' [-a|--all] --octopus <ref>...\n> +'git merge-base' --is-ancestor <ref> <ref>\n> +'git merge-base' --independent <ref>...\n> +'git merge-base' --fork-point <ref> [<ref>]\n>\n>  DESCRIPTION\n>  -----------\n> diff --git a/builtin/merge-base.c b/builtin/merge-base.c\n> index e3f8da13b69..910916ae0ec 100644\n> --- a/builtin/merge-base.c\n> +++ b/builtin/merge-base.c\n> @@ -29,11 +29,11 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)\n>  }\n>\n>  static const char * const merge_base_usage[] = {\n> -       N_(\"git merge-base [-a | --all] <commit> <commit>...\"),\n> -       N_(\"git merge-base [-a | --all] --octopus <commit>...\"),\n> -       N_(\"git merge-base --independent <commit>...\"),\n> -       N_(\"git merge-base --is-ancestor <commit> <commit>\"),\n> -       N_(\"git merge-base --fork-point <ref> [<commit>]\"),\n> +       N_(\"git merge-base [-a | --all] <ref> <ref>...\"),\n> +       N_(\"git merge-base [-a | --all] --octopus <ref>...\"),\n> +       N_(\"git merge-base --independent <ref>...\"),\n> +       N_(\"git merge-base --is-ancestor <ref> <ref>\"),\n> +       N_(\"git merge-base --fork-point <ref1> [<ref2>]\"),\n>         NULL\n>  };\n>\n> @@ -158,7 +158,7 @@ int cmd_merge_base(int argc, const char **argv, const char *prefix)\n>                 OPT_CMDMODE(0, \"is-ancestor\", &cmdmode,\n>                             N_(\"is the first one ancestor of the other?\"), 'a'),\n>                 OPT_CMDMODE(0, \"fork-point\", &cmdmode,\n> -                           N_(\"find where <commit> forked from reflog of <ref>\"), 'f'),\n> +                           N_(\"find where <ref2> forked from reflog of <ref1>\"), 'f'),\n>                 OPT_END()\n>         };\n>\n>\n> base-commit: 2d2118b814c11f509e1aa76cb07110f7231668dc\n> --\n> gitgitgadget\n"},{"id":"392780","messageId":"nycvar.QRO.7.76.6.2003031507500.46@tvgsbejvaqbjf.bet","threadId":"52928","inReplyTo":"CAGyf7-Ez1Fx-VUVmDWxRxLaZcU+Tu4kZ+F2+0uNKkx2oftjEJQ@mail.gmail.com","subject":"Re: [PATCH] doc: use 'ref' instead of 'commit' for merge-base arguments","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2020-03-03T14:08:08Z","receivedAt":"2020-03-03T14:08:17Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Tue, 3 Mar 2020, Bryan Turner wrote:\n\n> On Tue, Mar 3, 2020 at 12:23 AM Takuya N via GitGitGadget\n> <gitgitgadget@gmail.com> wrote:\n> >\n> > From: Takuya Noguchi <takninnovationresearch@gmail.com>\n> >\n> > The notation <commit> can be misunderstandable only for commit SHA1,\n> > but merge-base accepts any commit references. Like reflog, the name of\n> > arguments should be <ref> instead of <commit>.\n>\n> To me, this change goes too far in the opposite direction: Now it\n> sounds like the command only accepts refs, when it actually accepts\n> any \"commit-ish\"--i.e., anything that can be coerced to a commit.\n> (\"git worktree\" uses this term in its usage for \"add\", for example.)\n\nMaybe we can go for `rev` instead of `ref`?\n\nCiao,\nDscho\n"},{"id":"392785","messageId":"xmqqd09ta4tn.fsf@gitster-ct.c.googlers.com","threadId":"52928","inReplyTo":"nycvar.QRO.7.76.6.2003031507500.46@tvgsbejvaqbjf.bet","subject":"Re: [PATCH] doc: use 'ref' instead of 'commit' for merge-base arguments","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-03T14:30:44Z","receivedAt":"2020-03-03T14:30:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n>> > The notation <commit> can be misunderstandable only for commit SHA1,\n>> > but merge-base accepts any commit references. Like reflog, the name of\n>> > arguments should be <ref> instead of <commit>.\n>>\n>> To me, this change goes too far in the opposite direction: Now it\n>> sounds like the command only accepts refs, when it actually accepts\n>> any \"commit-ish\"--i.e., anything that can be coerced to a commit.\n>> (\"git worktree\" uses this term in its usage for \"add\", for example.)\n>\n> Maybe we can go for `rev` instead of `ref`?\n\nThat's much better than 'ref', but I do not see why 'commit' is\nwrong in the first place.  There are many ways to name an object,\nand `rev` is an old colloquial way to say \"object name\".  Here,\nhowever, we want only commit objects, no?\n"},{"id":"392811","messageId":"nycvar.QRO.7.76.6.2003032035510.46@tvgsbejvaqbjf.bet","threadId":"52928","inReplyTo":"xmqqd09ta4tn.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH] doc: use 'ref' instead of 'commit' for merge-base arguments","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2020-03-03T19:38:19Z","receivedAt":"2020-03-03T19:38:32Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Tue, 3 Mar 2020, Junio C Hamano wrote:\n\n> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n>\n> >> > The notation <commit> can be misunderstandable only for commit SHA1,\n> >> > but merge-base accepts any commit references. Like reflog, the name of\n> >> > arguments should be <ref> instead of <commit>.\n> >>\n> >> To me, this change goes too far in the opposite direction: Now it\n> >> sounds like the command only accepts refs, when it actually accepts\n> >> any \"commit-ish\"--i.e., anything that can be coerced to a commit.\n> >> (\"git worktree\" uses this term in its usage for \"add\", for example.)\n> >\n> > Maybe we can go for `rev` instead of `ref`?\n>\n> That's much better than 'ref', but I do not see why 'commit' is\n> wrong in the first place.  There are many ways to name an object,\n> and `rev` is an old colloquial way to say \"object name\".  Here,\n> however, we want only commit objects, no?\n\nWe do not only want commit objects. It is totally legitimate to ask\n\n\tgit merge-base HEAD v2.25.0\n\n(v2.25.0 is of course not a commit, it is a tag that _refers_ to a\ncommit.)\n\nEarlier, we would probably have called this a \"commit-ish\", but since\nusers got so confused by this instance of Git Speak (is my interpretation\nof the reason, at least), we tend to call them \"revs\" these days.\n\nI do think that the idea of the patch has merit, even if I agree with\nBryan that we can probably improve on using \"ref\" instead of \"commit\".\n\nCiao,\nDscho\n"},{"id":"392812","messageId":"xmqq5zfl8alw.fsf@gitster-ct.c.googlers.com","threadId":"52928","inReplyTo":"nycvar.QRO.7.76.6.2003032035510.46@tvgsbejvaqbjf.bet","subject":"Re: [PATCH] doc: use 'ref' instead of 'commit' for merge-base arguments","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-03T20:08:43Z","receivedAt":"2020-03-03T20:08:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:\n\n>\n> We do not only want commit objects. It is totally legitimate to ask\n>\n> \tgit merge-base HEAD v2.25.0\n>\n> (v2.25.0 is of course not a commit, it is a tag that _refers_ to a\n> commit.)\n\nI meant to say (and was expecting those who know to know)\ncommittish, of course.\n\n> Earlier, we would probably have called this a \"commit-ish\", but since\n> users got so confused by this instance of Git Speak (is my interpretation\n> of the reason, at least), we tend to call them \"revs\" these days.\n\nI am not among that \"we\".  \"rev\" is an older and even more nerdy Git\nspeak that was invented back when Linus was active, and as you can\nsee, we used the word to mean not just commit or commit-ish, but\nanything that can be turned into an object name (you'd realize that\nyou know it already, when you think about what 'rev' means in \"git\nrev-parse\").  The phrase *-ish came much later (I think I was among\nthose who started it).\n\n"},{"id":"392855","messageId":"pull.719.v2.git.git.1583325514607.gitgitgadget@gmail.com","threadId":"52928","inReplyTo":"pull.719.git.git.1583220197856.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: use 'rev' instead of 'commit' for merge-base arguments","fromName":"Takuya N via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2020-03-04T12:38:34Z","receivedAt":"2020-03-04T12:38:40Z","isPatch":true,"sender":{"key":"name:Takuya N","avatar":null},"body":"From: Takuya Noguchi <takninnovationresearch@gmail.com>\n\nThe notation <commit> can be misunderstandable only for commit SHA1,\nbut merge-base accepts any commit references. Like rev-parse, the name\nof arguments should be <rev> instead of <commit>.\n\nSigned-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>\n---\n    doc: use 'rev' instead of 'commit' for merge-base arguments\n    \n    The notation can be misunderstandable only for commit SHA1, but\n    merge-base accepts any commit references. Like rev-parse, the name of\n    arguments should be instead of .\n    \n    Changes since v1:\n    \n     * Use rev instead of ref, not commit-ish which is less used than rev\n       through the document.\n    \n    Signed-off-by: Takuya Noguchi takninnovationresearch@gmail.com\n    [takninnovationresearch@gmail.com]\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-719%2Ftnir%2Fmerge-base-supporting-refs-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-719/tnir/merge-base-supporting-refs-v2\nPull-Request: https://github.com/git/git/pull/719\n\nRange-diff vs v1:\n\n 1:  9c83cf1c620 ! 1:  6e2157da4b1 doc: use 'ref' instead of 'commit' for merge-base arguments\n     @@ -1,10 +1,10 @@\n      Author: Takuya Noguchi <takninnovationresearch@gmail.com>\n      \n     -    doc: use 'ref' instead of 'commit' for merge-base arguments\n     +    doc: use 'rev' instead of 'commit' for merge-base arguments\n      \n          The notation <commit> can be misunderstandable only for commit SHA1,\n     -    but merge-base accepts any commit references. Like reflog, the name of\n     -    arguments should be <ref> instead of <commit>.\n     +    but merge-base accepts any commit references. Like rev-parse, the name\n     +    of arguments should be <rev> instead of <commit>.\n      \n          Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>\n      \n     @@ -20,11 +20,11 @@\n      -'git merge-base' --is-ancestor <commit> <commit>\n      -'git merge-base' --independent <commit>...\n      -'git merge-base' --fork-point <ref> [<commit>]\n     -+'git merge-base' [-a|--all] <ref> <ref>...\n     -+'git merge-base' [-a|--all] --octopus <ref>...\n     -+'git merge-base' --is-ancestor <ref> <ref>\n     -+'git merge-base' --independent <ref>...\n     -+'git merge-base' --fork-point <ref> [<ref>]\n     ++'git merge-base' [-a|--all] <rev> <rev>...\n     ++'git merge-base' [-a|--all] --octopus <rev>...\n     ++'git merge-base' --is-ancestor <rev> <rev>\n     ++'git merge-base' --independent <rev>...\n     ++'git merge-base' --fork-point <ref> [<rev>]\n       \n       DESCRIPTION\n       -----------\n     @@ -41,11 +41,11 @@\n      -\tN_(\"git merge-base --independent <commit>...\"),\n      -\tN_(\"git merge-base --is-ancestor <commit> <commit>\"),\n      -\tN_(\"git merge-base --fork-point <ref> [<commit>]\"),\n     -+\tN_(\"git merge-base [-a | --all] <ref> <ref>...\"),\n     -+\tN_(\"git merge-base [-a | --all] --octopus <ref>...\"),\n     -+\tN_(\"git merge-base --independent <ref>...\"),\n     -+\tN_(\"git merge-base --is-ancestor <ref> <ref>\"),\n     -+\tN_(\"git merge-base --fork-point <ref1> [<ref2>]\"),\n     ++\tN_(\"git merge-base [-a | --all] <rev> <rev>...\"),\n     ++\tN_(\"git merge-base [-a | --all] --octopus <rev>...\"),\n     ++\tN_(\"git merge-base --independent <rev>...\"),\n     ++\tN_(\"git merge-base --is-ancestor <rev> <rev>\"),\n     ++\tN_(\"git merge-base --fork-point <ref> [<rev>]\"),\n       \tNULL\n       };\n       \n     @@ -54,7 +54,7 @@\n       \t\t\t    N_(\"is the first one ancestor of the other?\"), 'a'),\n       \t\tOPT_CMDMODE(0, \"fork-point\", &cmdmode,\n      -\t\t\t    N_(\"find where <commit> forked from reflog of <ref>\"), 'f'),\n     -+\t\t\t    N_(\"find where <ref2> forked from reflog of <ref1>\"), 'f'),\n     ++\t\t\t    N_(\"find where <rev> forked from reflog of <ref>\"), 'f'),\n       \t\tOPT_END()\n       \t};\n       \n\n\n Documentation/git-merge-base.txt | 10 +++++-----\n builtin/merge-base.c             | 12 ++++++------\n 2 files changed, 11 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt\nindex 2d944e0851f..60438a00871 100644\n--- a/Documentation/git-merge-base.txt\n+++ b/Documentation/git-merge-base.txt\n@@ -9,11 +9,11 @@ git-merge-base - Find as good common ancestors as possible for a merge\n SYNOPSIS\n --------\n [verse]\n-'git merge-base' [-a|--all] <commit> <commit>...\n-'git merge-base' [-a|--all] --octopus <commit>...\n-'git merge-base' --is-ancestor <commit> <commit>\n-'git merge-base' --independent <commit>...\n-'git merge-base' --fork-point <ref> [<commit>]\n+'git merge-base' [-a|--all] <rev> <rev>...\n+'git merge-base' [-a|--all] --octopus <rev>...\n+'git merge-base' --is-ancestor <rev> <rev>\n+'git merge-base' --independent <rev>...\n+'git merge-base' --fork-point <ref> [<rev>]\n \n DESCRIPTION\n -----------\ndiff --git a/builtin/merge-base.c b/builtin/merge-base.c\nindex e3f8da13b69..e03f2269e88 100644\n--- a/builtin/merge-base.c\n+++ b/builtin/merge-base.c\n@@ -29,11 +29,11 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all)\n }\n \n static const char * const merge_base_usage[] = {\n-\tN_(\"git merge-base [-a | --all] <commit> <commit>...\"),\n-\tN_(\"git merge-base [-a | --all] --octopus <commit>...\"),\n-\tN_(\"git merge-base --independent <commit>...\"),\n-\tN_(\"git merge-base --is-ancestor <commit> <commit>\"),\n-\tN_(\"git merge-base --fork-point <ref> [<commit>]\"),\n+\tN_(\"git merge-base [-a | --all] <rev> <rev>...\"),\n+\tN_(\"git merge-base [-a | --all] --octopus <rev>...\"),\n+\tN_(\"git merge-base --independent <rev>...\"),\n+\tN_(\"git merge-base --is-ancestor <rev> <rev>\"),\n+\tN_(\"git merge-base --fork-point <ref> [<rev>]\"),\n \tNULL\n };\n \n@@ -158,7 +158,7 @@ int cmd_merge_base(int argc, const char **argv, const char *prefix)\n \t\tOPT_CMDMODE(0, \"is-ancestor\", &cmdmode,\n \t\t\t    N_(\"is the first one ancestor of the other?\"), 'a'),\n \t\tOPT_CMDMODE(0, \"fork-point\", &cmdmode,\n-\t\t\t    N_(\"find where <commit> forked from reflog of <ref>\"), 'f'),\n+\t\t\t    N_(\"find where <rev> forked from reflog of <ref>\"), 'f'),\n \t\tOPT_END()\n \t};\n \n\nbase-commit: 2f268890c2cd2f115424936bbee27f8269080e5e\n-- \ngitgitgadget\n"},{"id":"392864","messageId":"xmqqd09s5atg.fsf@gitster-ct.c.googlers.com","threadId":"52928","inReplyTo":"pull.719.v2.git.git.1583325514607.gitgitgadget@gmail.com","subject":"Re: [PATCH v2] doc: use 'rev' instead of 'commit' for merge-base arguments","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-04T16:44:43Z","receivedAt":"2020-03-04T16:44:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Takuya N via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: Takuya Noguchi <takninnovationresearch@gmail.com>\n>\n> The notation <commit> can be misunderstandable only for commit SHA1,\n\nLet's step back a bit.  When our documentation says\n\n    $ git log <commit>\n\nwe expect that the readers to understand that all of the following\nare accepted:\n\n    $ git log master\n    $ git log master~10\n    $ git log 3868ac720f\n    $ git log 3868ac720f7a26f3241f43764d0dc790ec55238f\n\nWhat gave you the impression that only the last one is valid?  We\nneed to fix _that_.\n\nThe side discussion we had with Dscho touched another important\npoint (i.e. when a command wants to take a commit but a user gives\nit a tag that points at a commit, the command almost always accepts\nthe tag, finds the commit the tag points at, and uses that commit\ninstead of the tag---we often mark such a parameter that expects\ncommit but does not have to name a commit object <commit-ish>), but\nit is more or less orthogonal.  All of these are accepted,\n\n    $ git log v2.25.0\n    $ git log 61e952148\n    $ git log 61e9521487999585dc2b8f27c2a65226fb531a07\n\nnot just the last one.\n\n> but merge-base accepts any commit references. Like rev-parse, the name\n> of arguments should be <rev> instead of <commit>.\n\nAnd \"like rev-parse\" is a poor justification.  It is a lowest-level\ncommand that was written in dark ages, and the language used in the\ndocumentation hasn't been updated to more modern terms.  Back then,\nwe said \"revision\" (and \"rev\" is a short for it) and the term was\ninvented to mean commit (see \"$ git help glossary\") but was used\nloosely and more-or-less interchangeably with \"object name\" (in\nother words, when the speaker who said \"rev\" did not necessarily\nmean to limit the reference to commits, the word did not limit\nitself to commit-ish but also covered trees and blobs).\n\nNow, in the context of \"git rev-parse\",\n\n    $ git rev-parse eacd13fab7e3\n\ndoes make sense.  It is OK to give it a short version of a tree\nobject name (it is the tree of the commit pointed by the v2.25.0\nrelease), so \"git rev-parse <object-name>\" (or \"git rev-parse <rev>\")\nwould be OK.\n\nIt is however a poor example to base our decision on how to explain\nmerge-base.  The command wants to _use_ two (or more) commits to\nwork on, so like many other commands, when it is fed a tag, it tries\nto see if it points at a commit (and barfs if it does not) and use\nthat commit instead.  In other words, it takes commit-ish.\n\nSaying that it takes <commit> is *not* so bad, but changing it to\n<rev> is a move backwards, I'd have to say.\n\nThanks for working on it, but s/ref/rev/ is not a good change.\n"},{"id":"392867","messageId":"xmqqzhcw3uc7.fsf@gitster-ct.c.googlers.com","threadId":"52928","inReplyTo":"xmqqd09s5atg.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH v2] doc: use 'rev' instead of 'commit' for merge-base arguments","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-03-04T17:26:00Z","receivedAt":"2020-03-04T17:26:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> ... another important\n> point (i.e. when a command wants to take a commit but a user gives\n> it a tag that points at a commit, the command almost always accepts\n> the tag, finds the commit the tag points at, and uses that commit\n> instead of the tag ...\n\nA side note I forgot to add.  A few commands take both commit and\ntag but want to do different things depending on the kind of object\nthey get, and for them, <commit> and <commit-ish> should be used\ncarefully in the documentation.\n\nFor example, \"git cat-file commit v2.25.0\" and \"git cat-file tag v2.25.0\"\ndo two different things.  They should be described as\n\n\t$ git cat-file commit <commit-ish>\n\t$ git cat-file tag <tag>\n\n\"git merge <commit>\" and \"git merge <tag>\" do different\nthings, even though <tag> must be a <commit-ish>.\n\nBut most of the Git subcommands (including the \"cat-file commit\"\ncase) peel a tag as needed, so these special cases are minority.\n"}]}