Re: [doc] User Manual Suggestion

["Björn Steinbrink" <B.Steinbrink@gmx.de>]

On 2009.04.24 20:39:12 -0400, David Abrahams wrote:
>
> 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.

My experience says to at least drop the "vast", but that might be
biased, due to the fact that the non-programmers probably need more time
when you explain things to them.

But thinking about it again, I don't think I like UI/API regardless of
that. High-Level/Low-Level yes, but API? No. The plumbing is meant to be
stable so it can serve as an API, and it also has options that only make
sense when you use it that way (e.g. the parse-opt support in rev-parse)
but I also happen to just use those programs as a UI. For example
ls-files, ls-remote, or apply.

And git(1) also has the sections titled "HIGH-LEVEL COMMANDS
(PORCELAIN)" and "LOW_LEVEL COMMANDS (PLUMBING)". So if we were to get
rid of the porcelain and plumbing terms, then _I_ would go for just
"high-level commands" and "low-level commands".

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

I'm sure this has been discussed in the earlier "stable revision
numbers" threads as well, so you can find more information there, but I
just want to mention that one drawback of this is that those numbers
still have no notion of "commit age". You could have 5000 commits in
your repo, and then you fetch someone elses stuff that might have some
very old stuff that you don't have yet. And that gets high numbers now.
So 5051 might be older than 200. Doesn't exactly help to make those
numbers "useful". Just like the "gaps" you get by using e.g. rebase -i
or other means that cause commits to be garbage collected.

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

OK, I think finally see what you might mean there. I'm almost
exclusively using the CLI and gitk and seldomly see tree/blob object
names in a prominent way unless I ask for them. But I just noticed that
gitweb is at least showing a "daunting" number of object names without
further details when you ask for a "commit", while the "commitdiff" is
closer to what "git show <commit>" would show. And yeah, I think that
could be improved, moving the object name more into the "background" (I
don't think it should be completely removed, just be less prominent).
Any other "high-level" tool that you noticed being noisy about tree/blob
hashes?

>>> 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 ;-)

Hm, I provide the information, you provide the patch? ;-) Hm, maybe I'll
find some time to provide one myself. But my git and general todo lists
already grew beyond all limits...

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

At least "bare repository" appears as an entry in the glossary
(gitglossary(7), also reachable via "git help glossary").

Björn