Re: [doc] User Manual Suggestion

["Björn Steinbrink" <B.Steinbrink@gmx.de>]

On 2009.04.24 17:18:44 -0500, Michael Witten wrote:
> On Fri, Apr 24, 2009 at 16:38, Jeff King <peff@peff.net> wrote:
> > On Fri, Apr 24, 2009 at 05:34:00PM -0400, Daniel Barkalow wrote:
> >
> >> I'd say that blobs and trees are an implementation detail of "the full
> >> content of a version of the project", not something conceptually
> >> important. Likewise, the date representation used in commits isn't
> > ...
> > No, that isn't critical for understanding how _commit_ operations work,
> > but I think that is exactly the sort of conceptual knowledge that let
> > people use git more fully.
> 
> I think the key conlusion here is that the main concepts are *objects*
> and references to those objects. One type of object is not necessarily
> more low-level or high-level than another type of object; each type of
> object is the most important type of object for a particular task in
> or view of the git world.
> 
> > I disagree. I think it's important to note that trees and blobs have a
> > name, and you can refer to them. Once you know that, the fact that you
> > can do:
> >
> >  git show master
> >  git show master:Documentation
> >  git show master:Makefile
> >
> > just makes sense. You are always just specifying an object, but the type
> > is different for each (and show "does the right thing" based on object
> > type).
> 
> In fact, I think it's important to note that the notation:
> 
>     git show master:Makefile
> 
> actually involves a translation from a Unix filesystem address to a
> git object address that is then used to find the relevant data.

Hm? Resolving master:Makefile means to first find what master is, most
likely the shortname for refs/heads/master. That usually references a
commit object (by its name). The "<tree-ish>:<path>" syntax then causes
git to lookup the tree referenced by that commit (again, by its name).
And then the tree entry for "Makefile" is looked up, leading to the name
for the object identified by "master:Makefile".

> In fact, I think masking this kind of thing with a catch-all word
> 'reference' is a bad idea.

"master:Makefile" is not a reference. Just "master" is a shortname for a
reference, the full name might be refs/heads/master.

git has:
 - object names (which happen to be SHA-1 hashes).
 - references (which reference objects by their names)
 - symbolic references (which reference other references by their names)

The "<tree-ish>:<path>" syntax is not called "reference".

> Rather than being hidden, it should be exposed: I think it would be
> beneficial to use the word 'address' rather than 'reference' when
> talking about the SHA-1 names. Then HEAD could be called a pointer
> variable, etc.

What's wrong with just calling the object name "object name"? References
are something different, and the above "master:Makefile" is yet a
different thing, using the "extended SHA1" syntax to identify an object.

> So, a pointer variable's value is an object address that is the
> location of an object in git 'memory'. I think using this approach
> would make things significantly more transparent.

But then HEAD would be a pointer pointer variable (symbolic ref), unless
you have a detached HEAD.

Björn