Re: [PATCH] doc: use 'ref' instead of 'commit' for merge-base arguments

From: Johannes Schindelin <Johannes.Schindelin@gmx.de>
To: Junio C Hamano <gitster@pobox.com>
Cc: Bryan Turner <bturner@atlassian.com>,
	Takuya N via GitGitGadget <gitgitgadget@gmail.com>,
	Git Users <git@vger.kernel.org>,
	Takuya Noguchi <takninnovationresearch@gmail.com>
Subject: Re: [PATCH] doc: use 'ref' instead of 'commit' for merge-base arguments
Date: Tue, 3 Mar 2020 20:38:19 +0100 (CET)	[thread overview]
Message-ID: <nycvar.QRO.7.76.6.2003032035510.46@tvgsbejvaqbjf.bet> (raw)
In-Reply-To: <xmqqd09ta4tn.fsf@gitster-ct.c.googlers.com>

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