Re: [9front] [PATCH] git: add missing usages for subcommands

[unobe@cpan.org]

Quoth ori@eigenstate.org:
> Quoth unobe@cpan.org:
> > Quoth ori@eigenstate.org:
> > > these were intentionally ommitted; you shouldn't need to use
> > > them. They exist for scripts like 'git/commit', 'git/push', and
> > > 'git/pull'.
> > 
> > Thanks, Ori.  I didn't realize that programs existing in the
> > distribution shouldn't be documented.
> >
> > Two follow-ups:
> > 
> > 1) Is that something that is standard and I've just never realized it?
> 
> Not sure about 'standard'; it's a judgement call.
> 
> I wouldn't mind having some form of documentation, but
> putting them in the main git manpage just confuses the
> user on how to do things, IMO.

What if, in the long-form area that expanded on the different git
programs, the ones which aren't meant to be used directly are
mentioned as such?  For me, some documentation of all programs is more
useful than none, even ones meant for internal-use only?  Something
like this at the end:
"Git/get, git/repack, git/save, and git/send are primarily internal
commands, and therefore not documented beyond their usage lines above
and their own code."

> It's the same reason that debug flags are typically not
> documented; if you're interacting with them, you're
> typically already in the code.

Do you mean the debug flag isn't documented in the 'usage:' output, or
in the man page?  I know debug flags are documented in quite a few
programs (viz., mothra, doc2txt, gzip, proof, and ssh come to mind) so
just trying to understand what is typical and what is not.  I don't
think its a foolish consistency to document them where they're
available, particularly if all they're doing is providing output to
stderr or what-not: without even looking at the code, some debug
output is useful to a passerby.
> 
> > 2) I didn't include git/hist in the doc patch: that's a "shouldn't
> >    need to use" program as well?
> 
> No, that's one that's quite useful; it's basically
> git blame on a budget (because it's honesty a pain
> in the ass to implement 'blame'.
> 

Ah, okay, good to know!  I had been wondering what the
(semi-)corollary to git/blame was!