* [9front] [PATCH] git: add missing usages for subcommands @ 2023-10-01 6:18 Romano 2023-10-01 14:48 ` ori 0 siblings, 1 reply; 7+ messages in thread From: Romano @ 2023-10-01 6:18 UTC (permalink / raw) To: 9front --- 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 [ ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [9front] [PATCH] git: add missing usages for subcommands 2023-10-01 6:18 [9front] [PATCH] git: add missing usages for subcommands Romano @ 2023-10-01 14:48 ` ori 2023-10-01 15:49 ` unobe 0 siblings, 1 reply; 7+ messages in thread From: ori @ 2023-10-01 14:48 UTC (permalink / raw) To: 9front 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 > [ > ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [9front] [PATCH] git: add missing usages for subcommands 2023-10-01 14:48 ` ori @ 2023-10-01 15:49 ` unobe 2023-10-01 16:42 ` ori 0 siblings, 1 reply; 7+ messages in thread From: unobe @ 2023-10-01 15:49 UTC (permalink / raw) To: 9front 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 > > [ > > > ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [9front] [PATCH] git: add missing usages for subcommands 2023-10-01 15:49 ` unobe @ 2023-10-01 16:42 ` ori 2023-10-01 20:14 ` ori 2023-10-01 23:34 ` unobe 0 siblings, 2 replies; 7+ messages in thread From: ori @ 2023-10-01 16:42 UTC (permalink / raw) To: 9front 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'. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [9front] [PATCH] git: add missing usages for subcommands 2023-10-01 16:42 ` ori @ 2023-10-01 20:14 ` ori 2023-10-01 23:34 ` unobe 1 sibling, 0 replies; 7+ messages in thread From: ori @ 2023-10-01 20:14 UTC (permalink / raw) To: 9front 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. ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [9front] [PATCH] git: add missing usages for subcommands 2023-10-01 16:42 ` ori 2023-10-01 20:14 ` ori @ 2023-10-01 23:34 ` unobe 2023-10-02 3:40 ` Kurt H Maier 1 sibling, 1 reply; 7+ messages in thread From: unobe @ 2023-10-01 23:34 UTC (permalink / raw) To: 9front 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! ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [9front] [PATCH] git: add missing usages for subcommands 2023-10-01 23:34 ` unobe @ 2023-10-02 3:40 ` Kurt H Maier 0 siblings, 0 replies; 7+ messages in thread From: Kurt H Maier @ 2023-10-02 3:40 UTC (permalink / raw) To: 9front 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2023-10-02 3:47 UTC | newest] Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2023-10-01 6:18 [9front] [PATCH] git: add missing usages for subcommands Romano 2023-10-01 14:48 ` ori 2023-10-01 15:49 ` unobe 2023-10-01 16:42 ` ori 2023-10-01 20:14 ` ori 2023-10-01 23:34 ` unobe 2023-10-02 3:40 ` Kurt H Maier
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).