Re: [doc] User Manual Suggestion

[Michael Witten <mfwitten@gmail.com>]

On Fri, Apr 24, 2009 at 18:11, Daniel Barkalow <barkalow@iabervon.org> wrote:
> On Fri, 24 Apr 2009, Michael Witten wrote:
>
>> On Fri, Apr 24, 2009 at 17:18, Michael Witten <mfwitten@gmail.com> wrote:
>> > In fact, I think masking this kind of thing with a catch-all word
>> > 'reference' is a bad idea. 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.
>> >
>> > 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.
>>
>> In fact, it's not particularly important that SHA-1 is used to compute
>> the address into git memory. The only thing that's important is that
>> the address is determined by content alone (I'm not even sure that
>> specifying that the address is a cryptographically sound hash of the
>> content is important; shouldn't that follow from the declaration that
>> it must be uniquely based on content alone?); the fact that's a SHA-1
>> is purely an implementation detail, and so it shouldn't appear
>> prominently in the documentation.
>>
>> So, what do you say?
>>
>> Let's start a reformation of the git terminology to use analogies that
>> have been around since the dawn of computing: 'memory', 'address', and
>> 'pointer'.
>
> I actually think calling them "sha1s" is better, simply because this bit
> of jargon doesn't mean anything else (git deals with email, so "address"
> is overloaded).

I don't know if I buy that reason; the human brain is pretty good with context.

I would at least like 'location' better.

> And the term is already in use for this particular case,
> and it doesn't mean anything else at all (since, of course, the crypto
> thing is "SHA-1", not "sha1"), and it's short (which is important for
> making it easy to look at usage help).

What happens when SHA-1 is shown to be broken or there is a better
alternative? Then we'll see "sha1 for historical reasons"... bleh!