Re: [doc] User Manual Suggestion
- From
David Abrahams <dave@boostpro.com>
- Date
- Apr 24, 2009, 19:00 UTC
- Message-ID
- <0FC64949-689C-43A4-B656-9618E808962B@boostpro.com>
- In-Reply-To
- <20090424181539.GB11360@coredump.intra.peff.net>
On Apr 24, 2009, at 2:15 PM, Jeff King wrote:
Show 16 quoted lines
> On Fri, Apr 24, 2009 at 01:28:35PM -0400, David Abrahams wrote: > >>> I think this is a bit better than it used to be. Plumbing commands >>> are >>> mostly hidden outside of the user's PATH. >> >> Huh? >> >> git hash-object >> git cat-file -t ... >> git ls-tree >> git rev-parse >> git write-tree >> git commit-tree > > How did you find out about them?
The first time?
$ man git
> They are not in your PATH, so shell > completion doesn't find them.
Huh? `which git` works. ls-tree is an argument to git as far as I know.
Yes, I know there are aliases like git-ls-tree somewhere, but that only adds to the sense that all commands are equal.
Show 5 quoted lines
> They are not in the programmable bash > completion. They are not in the short command list git gives you when > you type "git help" or "git" without arguments. > > So you must have read about them somewhere..
$ man git
which makes no distinction.
$ xxx [--]help
is usually OK if I already know xxx pretty well and just want a refresher. If know I'll need a little more than that, I use man straight away.
Show 5 quoted lines
>> These are just some of the ones I learned about by reading John >> Wiegley's >> "Git From the Bottom Up." > > ...like here.
That's where I learned *what they do*.
> So if that document gave you the impression that those are > part of an everyday git workflow, then I think the document is at > fault, > not git itself.
It didn't.
> I admit I haven't read "Git From the Bottom Up" carefully, but I think > what Michael is proposing would probably start a little higher from > the > bottom than that document.
Yes, please. "Git for Computer Scientists" is a great foundation. From there add more information about naming things so I know what things like remotes/origin/master mean when I see them in gitk, and I'm off to the races.
Show 6 quoted lines
> You can give the concepts of the object > types, show them in pretty-printed form with "git show", and not worry > about telling the user "this is how 'git commit' could be > implemented in > terms of primitive operations". And then you can avoid most of the > low-level commands entirely.
Yes, that's fine. Although I think there may be some things in GFTBU that are good fundamental concepts. There's a nice list of terms with definitions early in the document.
Show 13 quoted lines
>> Maybe I'm wrong about rev-parse, but for the most part, having all >> these >> low-level commands available through the same executable that's >> used for >> "git add," "git merge," "git commit," et. al. makes the whole >> shebang hard >> to approach. It would be better for users if the low-level stuff was >> accessed some other way. > > Perhaps. The general approach is to make those commands accessible as > "git foo", but not to _advertise_ them in the same way as the > porcelain > commands.
What is "porcelain," please? This is one among many examples of jargon used only (or encountered by me for the first time) in the Git community.
> The idea was to give a uniform calling convention without > unnecessarily confusing users by presenting a large number of > infrequently-used commands.
It's not working, I'm sorry to say.
> At any rate, it is too late to change the calling convention for > plumbing.
I disagree. You can leave the old functionality there in a "deprecated" state and change the way you advertise it. It would even help a lot if the plumbing were all spelled "git-xxx" and the high level stuff were "git xxx."
> The whole point of them is to be a stable interface for > scripting. Changing them to "git low-level rev-parse" (if it was even > something that we wanted to do, which I don't think it is) would break > everyone's scripts.
See above.
Show 6 quoted lines
>> [excuse me, but what the #@&*! is "porcelainish" supposed to mean? >> (http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html)] > > Heh. That one is particularly egregious, because it rests on several > layers of git jargon. The low-level tools are plumbing, like pipes and > valves.
? I use the valves on my kitchen sink all the time.
Show 9 quoted lines
> The high-level commands intended for end users are porcelain, > like sinks and toilets. The -ish suffix is often used in git to > refer to > a type, or something we can convert into a type (like a "tree-ish" > could > be a tree object, or a commit object which points to a tree, or a tag > object which points to a commit which points to a tree). So I think by > saying "porcelain-ish" here, the author meant "not just porcelain, but > other things which take revisions and behave sort of like porcelain".
bah. humbug.
> Which is a truly horrible thing to throw at a new user who just > wants to > see how to specify a revision.
yeeeeah.
Show 7 quoted lines
> So yeah, if you are saying that could be worded better, I absolutely > agree. There are a lot of spots like that. They are getting fixed > slowly > over time. I'm not sure if that is enough, or if somebody > knowledgeable > really needs to take a sledge hammer to the existing documentation and > just reorganize and rewrite a lot of it.
I'm thinking the latter.
-- David Abrahams BoostPro Computing http://boostpro.com