| Message ID | pull.719.git.git.1583220197856.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | doc: use 'ref' instead of 'commit' for merge-base arguments | expand |
On Tue, Mar 3, 2020 at 12:23 AM Takuya N via GitGitGadget <gitgitgadget@gmail.com> wrote: > > From: Takuya Noguchi <takninnovationresearch@gmail.com> > > The notation <commit> can be misunderstandable only for commit SHA1, > but merge-base accepts any commit references. Like reflog, the name of > arguments should be <ref> instead of <commit>. To me, this change goes too far in the opposite direction: Now it sounds like the command only accepts refs, when it actually accepts any "commit-ish"--i.e., anything that can be coerced to a commit. ("git worktree" uses this term in its usage for "add", for example.) At the same time, it doesn't seem like this change goes far enough. "git merge"'s documentation, for example, is still using "<commit>". Why is it important that "git merge-base" mention refs, but not that "git merge" do so? (Pardon the outburst from the peanut gallery) > > Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com> > --- > doc: use 'ref' instead of 'commit' for merge-base arguments > > The notation <commit> can be misunderstandable only for commit SHA1, but > merge-base accepts any commit references. Like reflog, the name of > arguments should be <ref> rather than <commit>. > > Signed-off-by: Takuya Noguchi takninnovationresearch@gmail.com > [takninnovationresearch@gmail.com] > > Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-719%2Ftnir%2Fmerge-base-supporting-refs-v1 > Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-719/tnir/merge-base-supporting-refs-v1 > Pull-Request: https://github.com/git/git/pull/719 > > Documentation/git-merge-base.txt | 10 +++++----- > builtin/merge-base.c | 12 ++++++------ > 2 files changed, 11 insertions(+), 11 deletions(-) > > diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt > index 2d944e0851f..b87528ef269 100644 > --- a/Documentation/git-merge-base.txt > +++ b/Documentation/git-merge-base.txt > @@ -9,11 +9,11 @@ git-merge-base - Find as good common ancestors as possible for a merge > SYNOPSIS > -------- > [verse] > -'git merge-base' [-a|--all] <commit> <commit>... > -'git merge-base' [-a|--all] --octopus <commit>... > -'git merge-base' --is-ancestor <commit> <commit> > -'git merge-base' --independent <commit>... > -'git merge-base' --fork-point <ref> [<commit>] > +'git merge-base' [-a|--all] <ref> <ref>... > +'git merge-base' [-a|--all] --octopus <ref>... > +'git merge-base' --is-ancestor <ref> <ref> > +'git merge-base' --independent <ref>... > +'git merge-base' --fork-point <ref> [<ref>] > > DESCRIPTION > ----------- > diff --git a/builtin/merge-base.c b/builtin/merge-base.c > index e3f8da13b69..910916ae0ec 100644 > --- a/builtin/merge-base.c > +++ b/builtin/merge-base.c > @@ -29,11 +29,11 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all) > } > > static const char * const merge_base_usage[] = { > - N_("git merge-base [-a | --all] <commit> <commit>..."), > - N_("git merge-base [-a | --all] --octopus <commit>..."), > - N_("git merge-base --independent <commit>..."), > - N_("git merge-base --is-ancestor <commit> <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 --independent <ref>..."), > + N_("git merge-base --is-ancestor <ref> <ref>"), > + N_("git merge-base --fork-point <ref1> [<ref2>]"), > NULL > }; > > @@ -158,7 +158,7 @@ int cmd_merge_base(int argc, const char **argv, const char *prefix) > OPT_CMDMODE(0, "is-ancestor", &cmdmode, > N_("is the first one ancestor of the other?"), 'a'), > OPT_CMDMODE(0, "fork-point", &cmdmode, > - N_("find where <commit> forked from reflog of <ref>"), 'f'), > + N_("find where <ref2> forked from reflog of <ref1>"), 'f'), > OPT_END() > }; > > > base-commit: 2d2118b814c11f509e1aa76cb07110f7231668dc > -- > gitgitgadget
Hi, On Tue, 3 Mar 2020, Bryan Turner wrote: > On Tue, Mar 3, 2020 at 12:23 AM Takuya N via GitGitGadget > <gitgitgadget@gmail.com> wrote: > > > > From: Takuya Noguchi <takninnovationresearch@gmail.com> > > > > The notation <commit> can be misunderstandable only for commit SHA1, > > but merge-base accepts any commit references. Like reflog, the name of > > arguments should be <ref> instead of <commit>. > > To me, this change goes too far in the opposite direction: Now it > sounds like the command only accepts refs, when it actually accepts > any "commit-ish"--i.e., anything that can be coerced to a commit. > ("git worktree" uses this term in its usage for "add", for example.) Maybe we can go for `rev` instead of `ref`? Ciao, Dscho
Johannes Schindelin <Johannes.Schindelin@gmx.de> writes: >> > The notation <commit> can be misunderstandable only for commit SHA1, >> > but merge-base accepts any commit references. Like reflog, the name of >> > arguments should be <ref> instead of <commit>. >> >> To me, this change goes too far in the opposite direction: Now it >> sounds like the command only accepts refs, when it actually accepts >> any "commit-ish"--i.e., anything that can be coerced to a commit. >> ("git worktree" uses this term in its usage for "add", for example.) > > Maybe we can go for `rev` instead of `ref`? That's much better than 'ref', but I do not see why 'commit' is wrong in the first place. There are many ways to name an object, and `rev` is an old colloquial way to say "object name". Here, however, we want only commit objects, no?
Hi, On Tue, 3 Mar 2020, Junio C Hamano wrote: > Johannes Schindelin <Johannes.Schindelin@gmx.de> writes: > > >> > The notation <commit> can be misunderstandable only for commit SHA1, > >> > but merge-base accepts any commit references. Like reflog, the name of > >> > arguments should be <ref> instead of <commit>. > >> > >> To me, this change goes too far in the opposite direction: Now it > >> sounds like the command only accepts refs, when it actually accepts > >> any "commit-ish"--i.e., anything that can be coerced to a commit. > >> ("git worktree" uses this term in its usage for "add", for example.) > > > > Maybe we can go for `rev` instead of `ref`? > > That's much better than 'ref', but I do not see why 'commit' is > wrong in the first place. There are many ways to name an object, > and `rev` is an old colloquial way to say "object name". Here, > however, we want only commit objects, no? We do not only want commit objects. It is totally legitimate to ask git merge-base HEAD v2.25.0 (v2.25.0 is of course not a commit, it is a tag that _refers_ to a commit.) Earlier, we would probably have called this a "commit-ish", but since users got so confused by this instance of Git Speak (is my interpretation of the reason, at least), we tend to call them "revs" these days. I do think that the idea of the patch has merit, even if I agree with Bryan that we can probably improve on using "ref" instead of "commit". Ciao, Dscho
Johannes Schindelin <Johannes.Schindelin@gmx.de> writes: > > We do not only want commit objects. It is totally legitimate to ask > > git merge-base HEAD v2.25.0 > > (v2.25.0 is of course not a commit, it is a tag that _refers_ to a > commit.) I meant to say (and was expecting those who know to know) committish, of course. > Earlier, we would probably have called this a "commit-ish", but since > users got so confused by this instance of Git Speak (is my interpretation > of the reason, at least), we tend to call them "revs" these days. I am not among that "we". "rev" is an older and even more nerdy Git speak that was invented back when Linus was active, and as you can see, we used the word to mean not just commit or commit-ish, but anything that can be turned into an object name (you'd realize that you know it already, when you think about what 'rev' means in "git rev-parse"). The phrase *-ish came much later (I think I was among those who started it).
diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index 2d944e0851f..b87528ef269 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -9,11 +9,11 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- [verse] -'git merge-base' [-a|--all] <commit> <commit>... -'git merge-base' [-a|--all] --octopus <commit>... -'git merge-base' --is-ancestor <commit> <commit> -'git merge-base' --independent <commit>... -'git merge-base' --fork-point <ref> [<commit>] +'git merge-base' [-a|--all] <ref> <ref>... +'git merge-base' [-a|--all] --octopus <ref>... +'git merge-base' --is-ancestor <ref> <ref> +'git merge-base' --independent <ref>... +'git merge-base' --fork-point <ref> [<ref>] DESCRIPTION ----------- diff --git a/builtin/merge-base.c b/builtin/merge-base.c index e3f8da13b69..910916ae0ec 100644 --- a/builtin/merge-base.c +++ b/builtin/merge-base.c @@ -29,11 +29,11 @@ static int show_merge_base(struct commit **rev, int rev_nr, int show_all) } static const char * const merge_base_usage[] = { - N_("git merge-base [-a | --all] <commit> <commit>..."), - N_("git merge-base [-a | --all] --octopus <commit>..."), - N_("git merge-base --independent <commit>..."), - N_("git merge-base --is-ancestor <commit> <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 --independent <ref>..."), + N_("git merge-base --is-ancestor <ref> <ref>"), + N_("git merge-base --fork-point <ref1> [<ref2>]"), NULL }; @@ -158,7 +158,7 @@ int cmd_merge_base(int argc, const char **argv, const char *prefix) OPT_CMDMODE(0, "is-ancestor", &cmdmode, N_("is the first one ancestor of the other?"), 'a'), OPT_CMDMODE(0, "fork-point", &cmdmode, - N_("find where <commit> forked from reflog of <ref>"), 'f'), + N_("find where <ref2> forked from reflog of <ref1>"), 'f'), OPT_END() };