Re: [doc] User Manual Suggestion

From: Björn Steinbrink <b.steinbrink@gmx.de>
Date: May 2, 2009, 15:53 UTC
Message-ID: <20090502155348.GB6135@atjola.homenet>
In-Reply-To: <b4087cc50904241701jb78ce50m122fef475b0f1de7@mail.gmail.com>

On 2009.04.24 19:01:48 -0500, Michael Witten wrote:

Show 21 quoted lines

> 2009/4/24 Björn Steinbrink <B.Steinbrink@gmx.de>:
> >> 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".
> 
> Firstly, your head is too bound to low-level implementation.
> 
> Secondly, you've basically just expounded upon what I said. The
> Makefile part is for humans to write using a filesystem path (address)
> that is mapped into what I call a git address. The point is that the
> user is interfacing between two theories of content storage.

Sorry, that part missed a few sentences I thought I had written. It was meant to show where the term "reference" is used. I just walked along your example, as that was right there, and I didn't have to come up with something else ;-)

Of course there are two "parts", just like scp uses <host>:<path>.

Show 8 quoted lines

> >> 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"?
> 
> What's wrong with calling the object address "object address"?

The term "object name" is already used in the docs, so you'll have to prove that it's bad and needs to be replaced.

> As I've stated: "address", "pointer", and "handle" are an analogy to
> terminology that has been around for ages. In fact, another name for
> "pointer" is "reference".

AFAIK a pointer is just one kind of reference. C++ references are another kind, file descriptors are yet another. A reference is one piece of data that lets me access a different piece of data.

And there are probably plenty of examples where you could apply that analogy, yet nobody (I know) does. Arrays, database tables, ...

And "memory" usually means "RAM" to me, not "WORM"-memory (well, actually, you can also delete and then rewrite, but not modify). So the analogy would even hurt my mental model (just like the "commit --amend" command might be consider harmful, because it actually creates a new commit, but some users actually think the original commit is modified).

Show 8 quoted lines

> >> 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.
> 
> We call those handles.

Isn't a handle basically an opaque/abstract reference, at least in "modern" usage? Symvolic references aren't. The user is free to create and manipulate them, and gets full access to the things referenced by them. And saying that HEAD is a reference, that might be symbolic is IMHO by far easier to understand than saying that HEAD might be a pointer or a handle.

Björn