Re: [doc] User Manual Suggestion

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

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

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

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