Re: First stab at glossary

From: Junio C Hamano <junkio@cox.net>
Date: Aug 17, 2005, 20:57 UTC
Message-ID: <7vwtmks2m1.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <Pine.LNX.4.63.0508172156090.17234@wgmdd8.biozentrum.uni-wuerzburg.de>

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

> Okay for "hash". What is the consensus on "object name" being more 
> standard than "SHA1"?

The tutorial uses the term "object name", so does README (implicitly, by saying "All objects are named by their content, which is approximated by the SHA1 hash of the object itself"). I think it is pretty safe to assume the list agrees with this term.

> For me, "index" is just the file named "index" (holding stat data and a 
> ref for each cache entry). That is why I say an "index" contains "cache 
> entries", not "index entries" (wee, that sounds wrong :-).

I think Linus already commented on using "index file" and "index entries" as the canonical terms. It would be a good idea to mention "cache" as a historical synonym in the documentation, so that we do not have to rename the symbols in the code.

> Ultimately, the glossary terms will be sorted alphabetically. If you look 
> at the file attached to my original mail, this is already sorted and 
> marked up using asciidoc. However, I wanted you and the list to understand 
> how I grouped terms. The asciidoc'ed file is generated by a perl script.

Then we should put the text version under Documentation, along with that script and a Makefile entry to do asciidoc and another to go to html. No rush for the script and Makefile entries, but it would make things easier to manage if we put the text version in the tree soonish. I've pushed out the one from your original "First stab" message.

Show 5 quoted lines

>> > branch::
>> > 	A non-cyclical graph of revisions, i.e. the complete history of
>> > 	a particular revision, which does not (yet) have children, which
>> > 	is called the branch head. The branch heads are stored in
>> > 	$GIT_DIR/refs/heads/.

I wonder if there is a math term for a non-cyclical graph that has a single "greater than anything else in the graph" node (but not necessarily a single but possibly more "lesser than anything else in the graph" nodes)?

Show 5 quoted lines

>> > tag::
>> > 	A ref pointing to a tag or commit object. In contrast to a head,
>> > 	a tag is not changed by a commit. Tags (not tag objects) are
>> > 	stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with
>> > 	a Lisp tag (which is called object type in git's context).

I think this is good already, but maybe mention why you would use a tag in a sentence? "Most typically used to mark a particular point in the commit ancestry chain," or something.

Show 11 quoted lines

>> > resolve::
>> > 	The action of fixing up manually what a failed automatic merge
>> > 	left behind.
>> 
>> "Resolve" is also used for the automatic case (e.g., in
>> "git-resolve-script", which goes from having two commits and a message to
>> having a new commit). I'm not sure what the distinction is supposed to be.
>
> I did not like that naming anyway. In reality, git-resolve-script does not 
> resolve anything, but it merges two revisions, possibly leaving something 
> to resolve.

I am sure this would break people's script, but I am not against renaming git-resolve-script to say git-merge-script.

Anyway, thanks for doing this less-fun and not-so-glorious job.