Re: First stab at glossary

[Daniel Barkalow <barkalow@iabervon.org>]

On Wed, 17 Aug 2005, Johannes Schindelin wrote:

> Hi,
>
> On Wed, 17 Aug 2005, Daniel Barkalow wrote:
>
> > On Wed, 17 Aug 2005, Johannes Schindelin wrote:
> >
> > > 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".

I think we only need at most two names for this, so this is more a matter
of fixing old usage than documenting it.

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

Well, it often contains information not present anywhere else (the status
of a merge; the set of files being committed, added, or removed), so it
isn't really a cache at all.

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

You probably don't need to mention that tree objects and index files can
be thought of as filesystems, but you should specify that the working tree
really is in the Unix filesystem, in case people have heard of the idea.

It should be clear to say 'You can "cd" there and "ls" to list your
files.', rather than 'Think "ls -laR"' which makes my think of the output,
which is like the output from git-ls-files.

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

Ah, okay.

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

Right; I think we should change the name of the script.

	-Daniel
*This .sig left intentionally blank*