Re: First stab at glossary

[Johannes Schindelin <Johannes.Schindelin@gmx.de>]

Hi,

On Wed, 17 Aug 2005, Junio C Hamano wrote:

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

Okay, I'll give in, then.

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

If the king penguin speaketh, the little blue penguin followeth.

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

Okay. Then I follow the advice of the large and angry Saucer Crunching 
Monster, and shuffle the entries into a more logical order.

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

Yes, there is. Although git itself is an example that there are two 
"greater than almost anything else in the graph" nodes.

Also, let's not be overzealous with our math degrees, okay? :-)

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

Done.

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

I do not mind changing the description if the consensus is to keep 
git-resolve-script.

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

The little blue penguin says: Thanks for all the fish!