Re: [doc] User Manual Suggestion

From: Michael Witten <mfwitten@gmail.com>
Date: Apr 25, 2009, 00:01 UTC
Message-ID: <b4087cc50904241701jb78ce50m122fef475b0f1de7@mail.gmail.com>
In-Reply-To: <20090424231632.GB10155@atjola.homenet>

2009/4/24 Björn Steinbrink <B.Steinbrink@gmx.de>:

Show 13 quoted lines

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

Show 12 quoted lines

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

I will admit that I used this term wrongly then, and that git has a set of terminologies much closer to what I proposed:

    * object addresses: object names
    * pointers: references
    * handle: symbolic reference (I don't know, I just now made that one up)

I was under the impression that object names were in fact called references and that things like '[refs/heads/]master' were just considered conveniences. I'm glad to have been disabused; though I like my terms better ;-D

Show 6 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"?

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

> are something different, and the above "master:Makefile" is yet a
> different thing, using the "extended SHA1" syntax to identify an object.

It is certainly something different. It's an interface between theories of content storage.

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