Re: First stab at glossary

[Junio C Hamano <junkio@cox.net>]

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.

>> > 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)?

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

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