Re: [PATCH/RFC] glossary: a revision is just a commit

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 21, 2013, 19:00 UTC
Message-ID: <7vy5cbso82.fsf@alter.siamese.dyndns.org>
In-Reply-To: <20130421081705.GG10429@elie.Belkin>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 10 quoted lines

> The current definition of 'revision' sounds like it is saying that a
> revision is a tree object.  In reality it is just a commit.
>
> This should be especially useful for people used to other revision
> control systems trying to see how familiar concepts translate into git
> terms.
>
> Reported-by: Ramkumar Ramachandra <artagnon@gmail.com>
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> ---

I think the existing glossary text is just confusing (it does wants to refer to a commit (noun) as a concept, as opposed to its concrete realization, i.e. a commit object, and tries to do so but does a bad job).

Your update is an improvement, but there may need a note that says that various web pages and documents, especially historical ones [*1*], may loosely use this word to refer to any single object that is not necessarily a commit at times.

Show 15 quoted lines

> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> index eb7ba84f..521fceeb 100644
> --- a/Documentation/glossary-content.txt
> +++ b/Documentation/glossary-content.txt
> @@ -430,9 +430,7 @@ should not be combined with other pathspec.
>  	<<def_merge,merge>> left behind.
>  
>  [[def_revision]]revision::
> -	A particular state of files and directories which was stored in the
> -	<<def_object_database,object database>>. It is referenced by a
> -	<<def_commit_object,commit object>>.
> +	Synonym for <<def_commit,commit>> (the noun).
>  
>  [[def_rewind]]rewind::
>  	To throw away part of the development, i.e. to assign the

[Footnote]

*1* The "rev-parse" command started as a tool to parse "revisions" aka "commit", "revision range" e.g. "A..B" and non-revisions (pathspecs) and flags. It was primarily designed as a way to sift arguments given to "git mylog -p A..B Makefile", so that a scripted "mylog" can turn it into a pipeline that feeds "git rev-list A..B Makefile" output as the input to "git diff-tree -p --stdin Makefile".

This was back when we did not even have non-committish extended SHA-1 object name notation. From the very start, "rev" in the name "rev-parse" did not even mean that it is limited to "revision" aka "commit". Later we added tree:path form of extended SHA-1 notation and "rev-parse --verify $it" has become its primary usage, while its role as argument sifter has diminished as we made "log" a built-in, not a pipeline. Around that time, we loosely started calling anything that get_sha1() can turn into an object name a "revision".

Also 99.9% of the time people use it to parse committish in real life.

For these reasons, I do not think it is wise to rename "rev-parse" to "object-name-parse". "rev" in "rev-parse" may be related to "revisions", and while it technically can operate on "revisions" (in the colloquial "object name" sense), it is not limited to revisions. And when it is used for revisions it mostly is used for "revisions" (in the "nothing but committish" sense). The name that most faithfully reflects the use of the command is "git kitchen-sink" these days.

The user still needs to know that in some context, "revision" may loosely refer to "object name" when talking about a single object, if only to understand the name of that command, let alone various tutorials, screencasts and web resources people made over time.