| Message ID | 20211203034420.47447-3-sunshine@sunshineco.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | b50252484f7e106e19e4feeb714ae88336295e5e |
| Headers | show |
| Series | worktree: fix incorrectly-ordered messages on Windows | expand |
On Thu, Dec 02 2021, Eric Sunshine wrote: > When verbose mode was added to `git worktree list` by 076b444a62 > (worktree: teach `list` verbose mode, 2021-01-27), although the > documentation was updated to reflect the new functionality, the > synopsis was overlooked. Correct this minor oversight. > > Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> > --- > Documentation/git-worktree.txt | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt > index 8a7cbdd19c..9e862fbcf7 100644 > --- a/Documentation/git-worktree.txt > +++ b/Documentation/git-worktree.txt > @@ -10,7 +10,7 @@ SYNOPSIS > -------- > [verse] > 'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>] > -'git worktree list' [--porcelain] > +'git worktree list' [-v | --porcelain] > 'git worktree lock' [--reason <string>] <worktree> > 'git worktree move' <worktree> <new-path> > 'git worktree prune' [-n] [-v] [--expire <expire>] Looks good! Aside: I've been thinking of hacking something up to just change all these "[verse]" bits in the *.txt source to: [verse] $(git worktree -h) And then have the doc build process pick that up, run 'git $name -h', do some light search/replacement (e.g. "$cmd" to "'$cmd'") and build the docs like that. Seems far preferrable to dual-maintaining all of these forever. But in the meantime this small fix is obviously correct.
On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote: > On Thu, Dec 02 2021, Eric Sunshine wrote: > > -'git worktree list' [--porcelain] > > +'git worktree list' [-v | --porcelain] > > Aside: I've been thinking of hacking something up to just change all > these "[verse]" bits in the *.txt source to: > > [verse] > $(git worktree -h) > > And then have the doc build process pick that up, run 'git $name -h', do > some light search/replacement (e.g. "$cmd" to "'$cmd'") and build the > docs like that. > > Seems far preferrable to dual-maintaining all of these forever. > > But in the meantime this small fix is obviously correct. One caution that springs to mind is that there may be external tooling which processes these documentation files directly, and such a change might break them. (The one which popped to mind immediately was the git-scm.{org,com} website, though I don't know what their tooling looks like.)
On Fri, Dec 03 2021, Eric Sunshine wrote: > On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote: >> On Thu, Dec 02 2021, Eric Sunshine wrote: >> > -'git worktree list' [--porcelain] >> > +'git worktree list' [-v | --porcelain] >> >> Aside: I've been thinking of hacking something up to just change all >> these "[verse]" bits in the *.txt source to: >> >> [verse] >> $(git worktree -h) >> >> And then have the doc build process pick that up, run 'git $name -h', do >> some light search/replacement (e.g. "$cmd" to "'$cmd'") and build the >> docs like that. >> >> Seems far preferrable to dual-maintaining all of these forever. >> >> But in the meantime this small fix is obviously correct. > > One caution that springs to mind is that there may be external tooling > which processes these documentation files directly, and such a change > might break them. (The one which popped to mind immediately was the > git-scm.{org,com} website, though I don't know what their tooling > looks like.) True, I hadn't looked into how that worked before, but behold! https://github.com/git/git-scm.com/blob/main/lib/tasks/index.rake It seems to be a re-implementation of a non-trivial part of the doc building process. In any case, if we do end up generating more of the documentation ourselves presumably any such concerns will be brought up then.
On Fri, Dec 03, 2021 at 03:57:41PM +0100, Ævar Arnfjörð Bjarmason wrote: > > One caution that springs to mind is that there may be external tooling > > which processes these documentation files directly, and such a change > > might break them. (The one which popped to mind immediately was the > > git-scm.{org,com} website, though I don't know what their tooling > > looks like.) > > True, I hadn't looked into how that worked before, but behold! > https://github.com/git/git-scm.com/blob/main/lib/tasks/index.rake > > It seems to be a re-implementation of a non-trivial part of the doc > building process. Yeah. It's kind of ugly, but the complication there is that the docs are updated on a running heroku dyno which does not actually have a clone of the new version of Git, let alone an actual build. It's also hard for it to just use the output of our "make" anyway, since there's some munging that happens to fit the page content inside the rest of the site, changing links, etc. We could in theory operate on the result of "make html" more directly, but it would definitely require some changes. IMHO the way the site operates now (with "live" updates by extracting content from git.git and shoving it into a database) is not ideal. It's not like we're importing new Git versions once per minute. It would be easier to reason about as a "static site" which is built by a process which actually has a clone of git.git and invokes "make html" there, post-processes the pages, and saves the whole thing as a Git tree. And then run that build occasionally (at new releases, or changes to the source, but also periodically via GitHub Actions or similar to pick up changed book content). It's just a big enough change (and there are some gotcha around things like site search) that I've never gotten around to it. -Peff
Eric Sunshine <sunshine@sunshineco.com> writes: > On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote: >> On Thu, Dec 02 2021, Eric Sunshine wrote: >> > -'git worktree list' [--porcelain] >> > +'git worktree list' [-v | --porcelain] >> >> Aside: I've been thinking of hacking something up to just change all >> these "[verse]" bits in the *.txt source to: >> >> [verse] >> $(git worktree -h) >> >> And then have the doc build process pick that up, run 'git $name -h', do >> some light search/replacement (e.g. "$cmd" to "'$cmd'") and build the >> docs like that. >> >> Seems far preferrable to dual-maintaining all of these forever. >> >> But in the meantime this small fix is obviously correct. > > One caution that springs to mind is that there may be external tooling > which processes these documentation files directly, and such a change > might break them. (The one which popped to mind immediately was the > git-scm.{org,com} website, though I don't know what their tooling > looks like.) Also it would slow us down by making the .txt variant we see in the source tree harder to read (or in this case, impossible to see without building the documentation).
On Sun, Dec 5, 2021 at 4:12 AM Junio C Hamano <gitster@pobox.com> wrote: > Eric Sunshine <sunshine@sunshineco.com> writes: > > On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote: > >> Aside: I've been thinking of hacking something up to just change all > >> these "[verse]" bits in the *.txt source to: > >> > >> [verse] > >> $(git worktree -h) > >> > >> And then have the doc build process pick that up, run 'git $name -h', do > >> some light search/replacement (e.g. "$cmd" to "'$cmd'") and build the > >> docs like that. > > > > One caution that springs to mind is that there may be external tooling > > which processes these documentation files directly, and such a change > > might break them. (The one which popped to mind immediately was the > > git-scm.{org,com} website, though I don't know what their tooling > > looks like.) > > Also it would slow us down by making the .txt variant we see in the > source tree harder to read (or in this case, impossible to see without > building the documentation). Taking this point into consideration, a middle-ground alternative to Ævar's idea would be to add tooling which only compares (by some definition of "compare") the output of `git blah -h` with the synopsis in `git-blah.txt` and complains if there are significant differences (by some definition "significant" and "difference"). It doesn't automate-away the work of keeping the synopsis up-to-date, but at least would flag inconsistencies.
On Mon, Dec 06 2021, Eric Sunshine wrote: > On Sun, Dec 5, 2021 at 4:12 AM Junio C Hamano <gitster@pobox.com> wrote: >> Eric Sunshine <sunshine@sunshineco.com> writes: >> > On Fri, Dec 3, 2021 at 4:15 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote: >> >> Aside: I've been thinking of hacking something up to just change all >> >> these "[verse]" bits in the *.txt source to: >> >> >> >> [verse] >> >> $(git worktree -h) >> >> >> >> And then have the doc build process pick that up, run 'git $name -h', do >> >> some light search/replacement (e.g. "$cmd" to "'$cmd'") and build the >> >> docs like that. >> > >> > One caution that springs to mind is that there may be external tooling >> > which processes these documentation files directly, and such a change >> > might break them. (The one which popped to mind immediately was the >> > git-scm.{org,com} website, though I don't know what their tooling >> > looks like.) >> >> Also it would slow us down by making the .txt variant we see in the >> source tree harder to read (or in this case, impossible to see without >> building the documentation). > > Taking this point into consideration, a middle-ground alternative to > Ævar's idea would be to add tooling which only compares (by some > definition of "compare") the output of `git blah -h` with the synopsis > in `git-blah.txt` and complains if there are significant differences > (by some definition "significant" and "difference"). It doesn't > automate-away the work of keeping the synopsis up-to-date, but at > least would flag inconsistencies. Or we could do the reverse and move the source code version of it to be generated from the [verse] sections in the documentation. Anyway, it's not something I was planning to work on any time soon, just something I'd thought was a good idea for a while, especially given the differences and divergenge. That can be viewed with: parallel -k ' git {} -h 2>&1 | grep -e "^usage" -e "^ or"; git help {} 2>&1 | grep -A20 SYNOPSIS | grep -B20 DESCRIPTION ' ::: $(git --list-cmds=builtins) | less It's a long-standing UX issue, and we keep re-introducing divergence between the two. If we're going to insist that the version in the *.txt file isn't generated that categorically closes the door to some logical follow-ups. E.g. having parse-options automatically generate alternates in cases where options are mutually exclusive, or adding color output to this where we color short/long options differently than arguments etc. That and e.g. translators needing to do less work for the translated manpages (we already have the translated output in the C code). Well, I suppose we could have a generating step and then commit the equivalent of the compiled file (or section) into git.git every time we add/change an option. In general I don't think it's a worthwhile goal to keep the .txt versions of the docs as some human-readable 1=1 mapping to what you'd get if you generated them. That's already not the case due to includes, and e.g. in this case accepting some reasonable amount of auto-generation would make them easier to maintain.
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes: >> Taking this point into consideration, a middle-ground alternative to >> Ævar's idea would be to add tooling which only compares (by some >> definition of "compare") the output of `git blah -h` with the synopsis >> in `git-blah.txt` and complains if there are significant differences >> (by some definition "significant" and "difference"). It doesn't >> automate-away the work of keeping the synopsis up-to-date, but at >> least would flag inconsistencies. > > Or we could do the reverse and move the source code version of it to be > generated from the [verse] sections in the documentation. Either would be far more preferrable than committing generated files, or committing us to work on unreadable sources. Thanks.
Eric Sunshine <sunshine@sunshineco.com> writes: > When verbose mode was added to `git worktree list` by 076b444a62 > (worktree: teach `list` verbose mode, 2021-01-27), although the > documentation was updated to reflect the new functionality, the > synopsis was overlooked. Correct this minor oversight. > > Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> > --- > Documentation/git-worktree.txt | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt > index 8a7cbdd19c..9e862fbcf7 100644 > --- a/Documentation/git-worktree.txt > +++ b/Documentation/git-worktree.txt > @@ -10,7 +10,7 @@ SYNOPSIS > -------- > [verse] > 'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>] > -'git worktree list' [--porcelain] > +'git worktree list' [-v | --porcelain] > 'git worktree lock' [--reason <string>] <worktree> > 'git worktree move' <worktree> <new-path> > 'git worktree prune' [-n] [-v] [--expire <expire>] Oops! Thanks for cleaning up after me.
diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt index 8a7cbdd19c..9e862fbcf7 100644 --- a/Documentation/git-worktree.txt +++ b/Documentation/git-worktree.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git worktree add' [-f] [--detach] [--checkout] [--lock [--reason <string>]] [-b <new-branch>] <path> [<commit-ish>] -'git worktree list' [--porcelain] +'git worktree list' [-v | --porcelain] 'git worktree lock' [--reason <string>] <worktree> 'git worktree move' <worktree> <new-path> 'git worktree prune' [-n] [-v] [--expire <expire>]
When verbose mode was added to `git worktree list` by 076b444a62 (worktree: teach `list` verbose mode, 2021-01-27), although the documentation was updated to reflect the new functionality, the synopsis was overlooked. Correct this minor oversight. Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> --- Documentation/git-worktree.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)