Re: First stab at glossary

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

Hi,

On Wed, 17 Aug 2005, Daniel Barkalow wrote:

> On Wed, 17 Aug 2005, Johannes Schindelin wrote:
> 
> > SHA1::
> > 	A 20-byte sequence (or 41-byte file containing the hex
> > 	representation and a newline). It is calculated from the
> > 	contents of an object by the Secure Hash Algorithm 1.
> 
> It's also often 40-character string (with whatever termination) in places
> like commit objects, tag objects, command-line arguments, listings, and so
> forth.

Okay.

> > object name::
> > 	Synonym for SHA1.
> 
> Have we killed the use of the third term "hash" for this? I'd say that
> "object name" is the standard term, and "SHA1" is a nickname, if only
> because "object name" is more descriptive of the particular use of the
> term.

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

> > blob object::
> > 	Untyped object, i.e. the contents of a file.
> 
> This "i.e." should be "e.g.", since symlink targets are also stored as
> blobs, and any other bulk data stored by itself would be. (IIRC, Junio has
> a tagged blob to hold his public key, for example)

Agree.

> I think we might want to entirely kill the "cache" term, and talk only
> about the "index" and "index entries". Of course, a bunch of the code will
> have to be renamed to make this completely successful, but we could change
> the glossary and documentation, and mention "cache" and "cache entry" as
> old names for "index" and "index entry" respectively.

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

> > working tree::
> > 	The set of files and directories currently being worked on.
> > 	Think "ls -laR"
> 
> This is where the data is actually in the filesystem, and you can edit and
> compile it (as opposed to a tree object or the index, which semantically
> have the same contents, but aren't presented in the filesystem that way).

Maybe I was too cautious. Linus very new idea was to think of the lowest 
level of an SCM as a file system. But I did not want to mention that. 
Thinking of it again, maybe I should.

> > checkout::
>
> Move after "revision"?

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.

> Move "parent" around here.

See above.

> Move after "tree-ish".

Ditto.

> > 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/.
> 
> A branch head might have children, if they're in another branch. (E.g., I
> pull mainline, make a new branch based on it, and commit a change; the
> head of mainline is still a branch head, even though it's the parent of my
> new commit, because my new commit isn't in mainline.)

Well noted! I'll just delete that part.

> > 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).
> 
> As above, only the head for the branch being committed to is changed by a
> commit. A tag, not being the head of a branch, is therefore never changed
> by a commit.

I tried to say that.

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

Ciao,
Dscho