From: David Abrahams <dave@boostpro.com>
Date: Sat, 25 Apr 2009 00:39:12 GMT
Subject: Re: [doc] User Manual Suggestion
Message-ID: <78D97574-74AB-4A4D-AEB2-874BFBB4345E@boostpro.com>
In-Reply-To: <20090424224517.GA10155@atjola.homenet>


On Apr 24, 2009, at 6:45 PM, Björn Steinbrink wrote:

>> I think UI/API works way better than porcelain/plumbing. We are,  
>> after
>> all, programmers.
>
> We are programmers, but not all git users are programmers.

I'm sure you will admit that the vast majority are programmers.  This  
is about speaking effectively to your primary audience.

>> It would also be good to link to a definition any time you use a term
>> of art in the docs. I would even do that in the case of UI/API since
>> the distinction could appear to be subtle.
>>
>> I should also say, most of the docs and interfaces I see in Git (and
>> its wrappers, web interfaces, etc.) give the SHA1 hashes way too much
>> exposure. The times when it's actually more convenient to use a hash
>> instead of one of the other notations are rare,
>
> How often do you need a name for a commit shown by a command and can
> accept that it is not stable?

I can accept it as long as it's stable inside my own repo.  Maybe I  
need the SHA1 to talk about it wherever it may roam.  I think you  
could count in the other direction (i.e. from the roots instead of the  
leaves) to get fairly stable symbolic names.

Also, I don't think I need to see the hashes for trees and blobs most  
of the time.

> I usually need a name because I
> want to reference that commit later on, either because I need to  
> talk to
> other users, or because I'm working on something and might need to  
> look
> at that commit now and then, regardless on my current state of things.
> One big exception in my workflow is when I use "git blame", then I
> usually just need the name once to look at the full commit. But then I
> prefer a 7-8 characters long sha-1 prefix to something like
> improve_foo_speed~132^12~1^3. And "pseudo-stable" numbers have been
> discussed to death.

Okay, I "say uncle."

>> and if hashes weren't so exposed I bet most interfaces would make
>> those other names more available. One reason I think hashes retain
>> their prominent exposure is that you have no other reasonably stable
>> way of referring to commits, since branch~NN counts backward from
>> HEAD. Adding such a thing would help.
>
> It counts backwards from "branch".

Right, thanks.

>> Oh, one other specific issue: the rev-parse manpage uses $GIT_DIR
>> without saying what it is. I *think* that means the root of the
>> working copy and has nothing to do with environment variables, but
>> it's hard to be sure, and if I'm right about that, it's misleading
>> notation.
>
> $GIT_DIR means the .git directory of a non-bare repo.


Thanks for clarifying.  But don't neglect to fix the docs so the next  
guy doesn't have to ask ;-)

BTW, "[non-]bare repo" is yet another Git-specific jargon.  I know  
what it means... again, only because I asked someone.

--
David Abrahams
BoostPro Computing
http://boostpro.com