Re: [PATCH] Document git-runstatus

From: Petr Baudis <pasky@suse.cz>
Date: Nov 19, 2006, 18:13 UTC
Message-ID: <20061119181307.GY7201@pasky.or.cz>
In-Reply-To: <20061118150431.81076072.seanlkml@sympatico.ca>

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

Show 9 quoted lines

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

Show 19 quoted lines

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