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