Re: [PATCH] Document git-runstatus

[Petr Baudis <pasky@suse.cz>]

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 <gitzilla@gmail.com> wrote:
> 
> > 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.

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