Re: [doc] User Manual Suggestion

From: Björn Steinbrink <b.steinbrink@gmx.de>
Date: Apr 24, 2009, 22:45 UTC
Message-ID: <20090424224517.GA10155@atjola.homenet>
In-Reply-To: <2B5084A3-9BDB-4463-8530-3C8AB2E09A1F@boostpro.com>

On 2009.04.24 17:06:27 -0400, David Abrahams wrote:

Show 27 quoted lines

> On Apr 24, 2009, at 4:24 PM, Jeff King wrote:
>> On Fri, Apr 24, 2009 at 03:00:19PM -0400, David Abrahams wrote:
>>> It would even help a lot if the plumbing were all spelled "git-xxx"
>>> and the high level stuff were "git xxx."
>>
>> Differentating calling conventions like that was proposed when dashed
>> forms were deprecated and removed from the PATH. But if we had dashed
>> forms for plumbing (i.e., not forwarding them via the "git" wrapper),
>> then you have to do one of:
>>
>>  - put them in the user's PATH. Now tab completion or looking in your
>>    PATH means you see _just_ the plumbing commands, and none of the
>>    high level ones. Which is one of the reasons they were removed
>>    from the PATH in the first place (due to numerous user
>>    complaints).
>>
>>  - put them elsewhere, and force plumbing users to add $GIT_EXEC_PATH
>>    to their PATH. That becomes very annoying for casual plumbing
>>    users. If you come to the mailing list with a problem, I would
>>    have to jump through extra hoops to ask you to show me the output
>>    of "git ls-files".
>
> I see your point.
>
>   llgit xxx
>
> ?

If that was the exclusive way of calling the low-level commands, that would still break existing scripts. And if you keep e.g. "git write-tree" and just add "llgit write-tree" as an alias, that will IMHO just cause more confusion once old and new git users meet. And I agree with Peff, it's not important whether it's "git foo", "llgit foo", "git lowlevel foo" or something else. It's just about how much your users really _need_ to know and how you tell them to use the stuff.

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

Show 8 quoted lines

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

Show 5 quoted lines

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

Show 5 quoted lines

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

Björn