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

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

[Romano]

---
diff db2177614df64fa9ccf3dae30cdf24df1ce0a0be 405b4e7cff97415ef62ed448de0eb33f981a8333
--- a/sys/man/1/git
+++ b/sys/man/1/git
@@ -71,6 +71,25 @@
 .I commits...
 ]
 .PP
+.B git/get
+[
+.B -dl
+]
+[
+.B -b
+.I branch
+]
+[
+.B -u
+.I upstream
+]
+.I remote
+.PP
+.B git/fs
+[
+.B -d
+]
+.PP
 .B git/import
 [
 .B -n
@@ -152,6 +171,11 @@
 ]
 .I query
 .PP
+.B git/repack
+[
+.B -d
+]
+.PP
 .B git/revert
 [
 .B -c
@@ -161,6 +185,61 @@
 .PP
 .B git/rm
 .I path...
+.PP
+.B git/save
+.B -n
+.I name
+.B -e
+.I email
+.B -m
+.I message
+.B -d
+.I date
+[
+.B -N
+.I committer-name
+.B -E
+.I committer-email
+]
+[
+.B -p
+.I parent1
+[
+.B -p
+.I parent2
+]
+…
+]
+[
+.I files…
+]
+.PP
+.B git/send
+[
+.B -adf
+]
+[
+.B -b
+.I branch1
+[
+.B -b
+.I branch2
+]
+…
+]
+[
+.B -r
+.I branch1
+[
+.B -r
+.I branch2
+]
+…
+]
+.I remote
+[
+.I reponame
+]
 .PP
 .B git/serve
 [

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

[ori]

these were intentionally ommitted; you shouldn't need to use
them. They exist for scripts like 'git/commit', 'git/push', and
'git/pull'.

Quoth Romano <unobe@cpan.org>:
> ---
> diff db2177614df64fa9ccf3dae30cdf24df1ce0a0be 405b4e7cff97415ef62ed448de0eb33f981a8333
> --- a/sys/man/1/git
> +++ b/sys/man/1/git
> @@ -71,6 +71,25 @@
>  .I commits...
>  ]
>  .PP
> +.B git/get
> +[
> +.B -dl
> +]
> +[
> +.B -b
> +.I branch
> +]
> +[
> +.B -u
> +.I upstream
> +]
> +.I remote
> +.PP
> +.B git/fs
> +[
> +.B -d
> +]
> +.PP
>  .B git/import
>  [
>  .B -n
> @@ -152,6 +171,11 @@
>  ]
>  .I query
>  .PP
> +.B git/repack
> +[
> +.B -d
> +]
> +.PP
>  .B git/revert
>  [
>  .B -c
> @@ -161,6 +185,61 @@
>  .PP
>  .B git/rm
>  .I path...
> +.PP
> +.B git/save
> +.B -n
> +.I name
> +.B -e
> +.I email
> +.B -m
> +.I message
> +.B -d
> +.I date
> +[
> +.B -N
> +.I committer-name
> +.B -E
> +.I committer-email
> +]
> +[
> +.B -p
> +.I parent1
> +[
> +.B -p
> +.I parent2
> +]
> +…
> +]
> +[
> +.I files…
> +]
> +.PP
> +.B git/send
> +[
> +.B -adf
> +]
> +[
> +.B -b
> +.I branch1
> +[
> +.B -b
> +.I branch2
> +]
> +…
> +]
> +[
> +.B -r
> +.I branch1
> +[
> +.B -r
> +.I branch2
> +]
> +…
> +]
> +.I remote
> +[
> +.I reponame
> +]
>  .PP
>  .B git/serve
>  [
> 

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

[unobe]

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?

2) I didn't include git/hist in the doc patch: that's a "shouldn't
   need to use" program as well?

> 
> Quoth Romano <unobe@cpan.org>:
> > ---
> > diff db2177614df64fa9ccf3dae30cdf24df1ce0a0be 405b4e7cff97415ef62ed448de0eb33f981a8333
> > --- a/sys/man/1/git
> > +++ b/sys/man/1/git
> > @@ -71,6 +71,25 @@
> >  .I commits...
> >  ]
> >  .PP
> > +.B git/get
> > +[
> > +.B -dl
> > +]
> > +[
> > +.B -b
> > +.I branch
> > +]
> > +[
> > +.B -u
> > +.I upstream
> > +]
> > +.I remote
> > +.PP
> > +.B git/fs
> > +[
> > +.B -d
> > +]
> > +.PP
> >  .B git/import
> >  [
> >  .B -n
> > @@ -152,6 +171,11 @@
> >  ]
> >  .I query
> >  .PP
> > +.B git/repack
> > +[
> > +.B -d
> > +]
> > +.PP
> >  .B git/revert
> >  [
> >  .B -c
> > @@ -161,6 +185,61 @@
> >  .PP
> >  .B git/rm
> >  .I path...
> > +.PP
> > +.B git/save
> > +.B -n
> > +.I name
> > +.B -e
> > +.I email
> > +.B -m
> > +.I message
> > +.B -d
> > +.I date
> > +[
> > +.B -N
> > +.I committer-name
> > +.B -E
> > +.I committer-email
> > +]
> > +[
> > +.B -p
> > +.I parent1
> > +[
> > +.B -p
> > +.I parent2
> > +]
> > +…
> > +]
> > +[
> > +.I files…
> > +]
> > +.PP
> > +.B git/send
> > +[
> > +.B -adf
> > +]
> > +[
> > +.B -b
> > +.I branch1
> > +[
> > +.B -b
> > +.I branch2
> > +]
> > +…
> > +]
> > +[
> > +.B -r
> > +.I branch1
> > +[
> > +.B -r
> > +.I branch2
> > +]
> > +…
> > +]
> > +.I remote
> > +[
> > +.I reponame
> > +]
> >  .PP
> >  .B git/serve
> >  [
> > 
> 

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

[ori]

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.

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.

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

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

[ori]

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

git/repack may also make sense to document; it's kind
of rarely needed maintenance, but it *may* make sense
for users to use -- though it's just as much a test
program for the pack generation logic.

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

[unobe]

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!

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

[Kurt H Maier]

On Sun, Oct 01, 2023 at 04:34:00PM -0700, unobe@cpan.org wrote:
> 
> 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."

the traditional approach is for ori, or an intern, to write a paper
about this git implementation, so it can live in /sys/doc.  I assume,
for the sake of argument, that ori has unlimited free time and interns
to accomplish this, and so I look forward to reading the paper when it
is published, for the sake of argument, later today.

khm