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

[Junio C Hamano <gitster@pobox.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

> 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.

> 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.