Re: Apologia for bzr

[Tassilo Horn <tsdh@gnu.org>]

Eli Zaretskii <eliz@gnu.org> writes:

>> All the terminology that's referred to in the git command man pages is
>> defined in one central place, the gitglossary(7) man page.
>
> First, there are no references to glossary in these places, and, as
> you know well, references in man pages are a PITA to use (unlike in
> Info).

On my Gentoo system, git installed an info manual.  But honestly, that's
just an index of the man pages but still better to browse than the
normal man pages, e.g., you have `l' to jump back to where you were
previously etc.

> More importantly, the glossary, at least git's glossary, is not going
> to help here.  Let's take this example I showed earlier:
>
>   --reuse-message=<commit> 
>     Take an existing commit object, and reuse the log message and the
>     authorship information (including the timestamp) when creating the
>     commit.
>
> Clearly, what I need to know here, and is never explained, is how do I
> _reference_ a commit object.  Now, here's what the glossary tells me:
>
>   commit object 
>        An object which contains the information about a particular
>        revision, such as parents, committer, author, date and the tree
>        object which corresponds to the top directory of the stored
>        revision.
>
> I hope you will agree with me that after reading this, I'm none the
> wiser.

Yes, true, but the gittutorial(7) does explain that.  And searching for
"git how to reference a commit" brings me to the git book's Revision
Selection chapter which discusses that in utmost details.

So the man pages could be better, but there are tons of additional
resources you can consult that are easy to find and probably better to
grasp.

Bye,
Tassilo