Re: [PATCH] Document git-runstatus

On Sat, Nov 18, 2006 at 09:04:31PM CET, Sean wrote:

On Sat, 18 Nov 2006 11:37:14 -0800
A Large Angry SCM [off-list ref] wrote:

quoted

I disagree. If a command is install on a system, it's man 
pages/documentation should also be installed.

Well this isn't a huge issue.  One point you made though that struck
a chord is that many of the commands should probably not be in
section 1.

The trouble is that there's no other good place where to put them. But
perhaps we can get away with putting them to section 3? After all, Perl
installs documentation for its modules to section 3 as well.

quoted

I'm also not convinced that there are a "large number of commands [...] 
that should only ever be accessed as plumbing". I am convinced, however, 
that there are a number of relatively low level commands with poor user 
interfaces that are useful on their own.

Is there really a reason for a git user to access these from the
command line rather than a script:

commit-tree, diff-files, diff-index, diff-tree, for-each-ref,
hash-object, http-fetch, http-push, index-pack, local-fetch,
merge-base, merge-index, merge-octopus, merge-one-file, merge-ours,
merge-recur, merge-recursive, merge-recursive-old, merge-resolve,
merge-stupid, merge-tree, receive-pack, runstatus, ssh-fetch, ssh-pull,
ssh-push, ssh-upload, symbolic-ref, unpack-file, unpack-objects,
update-ref, upload-archive, upload-pack, upload-tar, write-tree

Not a complete list, and maybe i overlooked something in there
that is needed from the command line, but for the most part 
these could be installed somewhere other than the users path.

There certainly are reasons, but the situations where it is needed is
sufficiently rare; I think that's a reason good enough, when doing
something exotic like recovery of a corrupted repository it's ok to have
to do something slightly special to execute a lowlevel command.

It has been proposed for a long time that we put the "pure plumbing"
commands to /usr/libexec/git/ or somewhere there (some say /usr/libexec/
is obsolete), and I think it would be a great move.  Note that nowadays
the transition needs to be done carefully because of backwards
compatibility.


BTW, I've finally found a fine example of situation parallel to Git:
TeX!  There are the core TeX commands (plumbing) and plain TeX (basic
porcelain) on top of that as well as a bunch of other macro sets (other
porcelains). Now I need to dig out The TeXbook from wherever I've put it
to see how did Knuth deal with it, documentation-wise.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
The meaning of Stonehenge in Traflamadorian, when viewed from above, is:
"Replacement part being rushed with all possible speed."