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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html