List all guides in git(1) #691

phil-blain · 2020-08-02T15:15:33Z

Changes since v2:

Split the third commit following Junio's suggestion

Question for Junio:
Since the new commit 3/4 comes entirely from your suggestion,
I've attributed authorship to you, but I've added my own sign-off because
Gitgitgadget requires sign-off on each commit. Please let me know
if I should have proceeded differently.

v2:

Incorporated Junio's suggestion to reduce duplication.

v1:
This series adds a list of the guides to git(1).

The first commit adds the misssing guides 'gitcredentials' and
'gitremote-helpers' to command-list.txt. The only missing guide after this
change is 'gitweb.conf', but I think this one is obscure anough, and already
linked to in 'gitweb.txt', that it does not matter much.

The second commit drops the usage of 'common' and 'useful' for guides. This was
suggested as one of two ways forward by Duy in [1] but was not commented on.
I'm CC'ing the people that were CC'ed on that message.

The third commit tweaks 'Documentation/cmd-list.perl' so that it also generates
a list of the guides, which gets included in 'git.txt'. I chose to put this
list just after the end of the list of commands.

[1] https://lore.kernel.org/git/CACsJy8ADj-bTMYDHxRNLOMppOEdPbVwL49u3XCfNBCmoLLZo+A@mail.gmail.com/

CC: Nguyễn Thái Ngọc Duy [email protected], Philip Oakley [email protected], "Eric Sunshine" [email protected], "SZEDER Gábor" [email protected]

The guides 'gitcredentials' and 'gitremote-helpers' do not currently appear in command-list.txt. 'gitcredentials' was forgotten back when guides were added to command-list.txt in 1b81d8c (help: use command-list.txt for the source of guides, 2018-05-20). 'gitremote-helpers' was moved to section 7 in 439cc74 (docs: move gitremote-helpers into section 7, 2019-03-25), but command-list.txt was not updated at the time. Add these two guides to the list of guides in 'command-list.txt', so that they appear in the output of 'git help --guides', and capitalize the first word of the description of 'gitcredentials', as was done in 1b81d8c (help: use command-list.txt for the source of guides, 2018-05-20) for the other guides. While at it, add a comment in Documentation/Makefile to remind developers to update command-list.txt if they add a new guide. Signed-off-by: Philippe Blain <[email protected]>

Since 1b81d8c (help: use command-list.txt for the source of guides, 2018-05-20), all man5/man7 guides listed in command-list.txt appear in the output of 'git help -g'. However, 'git help -g' still prefixes this list with "The common Git guides are:", which makes one wonder if there are others! In the same spirit, the man page for 'git help' describes the '--guides' option as listing 'useful' guides, which is not false per se but can also be taken to mean that there are other guides that exist but are not useful. Instead of 'common' and 'useful', use 'Git concept guides' in both places. To keep the code in line with this change, rename help.c::list_common_guides_help to list_guides_help. Signed-off-by: Philippe Blain <[email protected]>

phil-blain · 2020-08-02T15:20:01Z

/submit

gitgitgadget · 2020-08-02T15:21:00Z

Submitted as [email protected]

gitgitgadget · 2020-08-02T21:45:59Z

This branch is now known as pb/guide-docs.

gitgitgadget · 2020-08-02T21:46:00Z

This patch series was integrated into seen via git@e01a34b.

gitgitgadget · 2020-08-02T21:48:19Z

Documentation/cmd-list.perl

@@ -6,9 +6,14 @@ sub format_one {
 	my ($out, $nameattr) = @_;


On the Git mailing list, Junio C Hamano wrote (reply to this):

"Philippe Blain via GitGitGadget" <[email protected]> writes: > From: Philippe Blain <[email protected]> > > Not all guides are mentioned in the 'git(1)' documentation, > which makes the missing ones somewhat hard to find. > > Add a list of the guides to git(1). > > Tweak `Documentation/cmd-list.perl` so that it also generates > a file `cmds-guide.txt` which gets included in git.txt. Who cleans this? Do we need a change to Makefile?

On the Git mailing list, Junio C Hamano wrote (reply to this):

Junio C Hamano <[email protected]> writes: > "Philippe Blain via GitGitGadget" <[email protected]> writes: > >> From: Philippe Blain <[email protected]> >> >> Not all guides are mentioned in the 'git(1)' documentation, >> which makes the missing ones somewhat hard to find. >> >> Add a list of the guides to git(1). >> >> Tweak `Documentation/cmd-list.perl` so that it also generates >> a file `cmds-guide.txt` which gets included in git.txt. > > Who cleans this? Do we need a change to Makefile? A band-aid patch would look like this, BUT. diff --git a/Documentation/Makefile b/Documentation/Makefile index 39f6fc8de7..616449da88 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -295,6 +295,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-plumbingmanipulators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ + cmds-guide.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt I think with a bit more work, we can be at a lot better place. How about something along the following line (untested)? Documentation/Makefile | 3 ++- Documentation/cmd-list.perl | 21 ++++++++------------- 2 files changed, 10 insertions(+), 14 deletions(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index 39f6fc8de7..80d1908a44 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -295,6 +295,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ cmds-plumbingmanipulators.txt \ cmds-synchingrepositories.txt \ cmds-synchelpers.txt \ + cmds-guide.txt \ cmds-purehelpers.txt \ cmds-foreignscminterface.txt @@ -302,7 +303,7 @@ $(cmds_txt): cmd-list.made cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) $(QUIET_GEN)$(RM) $@ && \ - $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \ + $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \ date >$@ mergetools_txt = mergetools-diff.txt mergetools-merge.txt diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl index 99f01a0910..af5da45d28 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -43,12 +43,15 @@ sub format_one { } } -while (<>) { +my ($input, @categories) = @ARGV; + +open IN, "<$input"; +while (<IN>) { last if /^### command list/; } my %cmds = (); -for (sort <>) { +for (sort <IN>) { next if /^#/; chomp; @@ -56,18 +59,10 @@ sub format_one { $attr = '' unless defined $attr; push @{$cmds{$cat}}, [$name, " $attr "]; } +close IN; -for my $cat (qw(ancillaryinterrogators - ancillarymanipulators - mainporcelain - plumbinginterrogators - plumbingmanipulators - synchingrepositories - foreignscminterface - purehelpers - synchelpers - guide)) { - my $out = "cmds-$cat.txt"; +for my $out (@categories) { + my ($cat) = $out =~ /^cmds-(.*)\.txt$/; open O, '>', "$out+" or die "Cannot open output file $out+"; for (@{$cmds{$cat}}) { format_one(\*O, $_);

On the Git mailing list, Philippe Blain wrote (reply to this):

Hi Junio, > Le 2 août 2020 à 18:05, Junio C Hamano <[email protected]> a écrit : > > Junio C Hamano <[email protected]> writes: > >> "Philippe Blain via GitGitGadget" <[email protected]> writes: >> >>> From: Philippe Blain <[email protected]> >>> >>> Not all guides are mentioned in the 'git(1)' documentation, >>> which makes the missing ones somewhat hard to find. >>> >>> Add a list of the guides to git(1). >>> >>> Tweak `Documentation/cmd-list.perl` so that it also generates >>> a file `cmds-guide.txt` which gets included in git.txt. >> >> Who cleans this? Do we need a change to Makefile? Oups! I checked /.gitignore, but forgot to thoroughly check the Makefile. > > A band-aid patch would look like this, BUT. > > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 39f6fc8de7..616449da88 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -295,6 +295,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ > cmds-plumbingmanipulators.txt \ > cmds-synchingrepositories.txt \ > cmds-synchelpers.txt \ > + cmds-guide.txt \ > cmds-purehelpers.txt \ > cmds-foreignscminterface.txt > > I think with a bit more work, we can be at a lot better place. How > about something along the following line (untested)? > > Documentation/Makefile | 3 ++- > Documentation/cmd-list.perl | 21 ++++++++------------- > 2 files changed, 10 insertions(+), 14 deletions(-) > > diff --git a/Documentation/Makefile b/Documentation/Makefile > index 39f6fc8de7..80d1908a44 100644 > --- a/Documentation/Makefile > +++ b/Documentation/Makefile > @@ -295,6 +295,7 @@ cmds_txt = cmds-ancillaryinterrogators.txt \ > cmds-plumbingmanipulators.txt \ > cmds-synchingrepositories.txt \ > cmds-synchelpers.txt \ > + cmds-guide.txt \ > cmds-purehelpers.txt \ > cmds-foreignscminterface.txt > > @@ -302,7 +303,7 @@ $(cmds_txt): cmd-list.made > > cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT) > $(QUIET_GEN)$(RM) $@ && \ > - $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \ > + $(PERL_PATH) ./cmd-list.perl ../command-list.txt $(cmds_txt) $(QUIET_STDERR) && \ > date >$@ > > mergetools_txt = mergetools-diff.txt mergetools-merge.txt > diff --git a/Documentation/cmd-list.perl b/Documentation/cmd-list.perl > index 99f01a0910..af5da45d28 100755 > --- a/Documentation/cmd-list.perl > +++ b/Documentation/cmd-list.perl > @@ -43,12 +43,15 @@ sub format_one { > } > } > > -while (<>) { > +my ($input, @categories) = @ARGV; > + > +open IN, "<$input"; > +while (<IN>) { > last if /^### command list/; > } > > my %cmds = (); > -for (sort <>) { > +for (sort <IN>) { > next if /^#/; > > chomp; > @@ -56,18 +59,10 @@ sub format_one { > $attr = '' unless defined $attr; > push @{$cmds{$cat}}, [$name, " $attr "]; > } > +close IN; > > -for my $cat (qw(ancillaryinterrogators > - ancillarymanipulators > - mainporcelain > - plumbinginterrogators > - plumbingmanipulators > - synchingrepositories > - foreignscminterface > - purehelpers > - synchelpers > - guide)) { > - my $out = "cmds-$cat.txt"; > +for my $out (@categories) { > + my ($cat) = $out =~ /^cmds-(.*)\.txt$/; > open O, '>', "$out+" or die "Cannot open output file $out+"; > for (@{$cmds{$cat}}) { > format_one(\*O, $_); Thanks for the suggestion. I tested it and it works correctly. I've incorporated it to v2. Philippe.

gitgitgadget · 2020-08-02T22:24:37Z

This patch series was integrated into seen via git@a4f4416.

gitgitgadget · 2020-08-03T18:02:42Z

This patch series was integrated into seen via git@fd968a1.

gitgitgadget · 2020-08-03T21:23:04Z

This patch series was integrated into seen via git@eca3567.

phil-blain · 2020-08-04T00:18:37Z

/submit

gitgitgadget · 2020-08-04T00:21:13Z

Submitted as [email protected]

gitgitgadget · 2020-08-04T00:27:30Z

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Philippe Blain via GitGitGadget" <[email protected]> writes:

> Changes since v1:
>
>  * Incorporated Junio's suggestion to reduce duplication.
>
> v1: This series adds a list of the guides to git(1).
>
> The first commit adds the misssing guides 'gitcredentials' and
> 'gitremote-helpers' to command-list.txt. The only missing guide after this
> change is 'gitweb.conf', but I think this one is obscure anough, and already
> linked to in 'gitweb.txt', that it does not matter much.
>
> The second commit drops the usage of 'common' and 'useful' for guides. This
> was suggested as one of two ways forward by Duy in [1] but was not commented
> on. I'm CC'ing the people that were CC'ed on that message.
>
> The third commit tweaks 'Documentation/cmd-list.perl' so that it also
> generates a list of the guides, which gets included in 'git.txt'. I chose to
> put this list just after the end of the list of commands.
>
> [1] 
> https://lore.kernel.org/git/CACsJy8ADj-bTMYDHxRNLOMppOEdPbVwL49u3XCfNBCmoLLZo+A@mail.gmail.com/
>
> Philippe Blain (3):
>   command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers'
>   help: drop usage of 'common' and 'useful' for guides
>   git.txt: add list of guides

I think the "dedup the list of cmds-$category.txt" is logically a
separate step from "we forgot to add guide category so add it", so
either (1) "add guide twice, and then refactor" or (2) "refactor
before adding guide, and then add guide only in one place" would be
more appropriate than (3) "add guide while refactoring".  IMHO, (2)
would make the most sense.

Thanks.

gitgitgadget · 2020-08-04T04:57:49Z

This patch series was integrated into seen via git@0a0169b.

Instead of hard-coding the list of command categories in both `Documentation/Makefile` and `Documentation/cmd-list.perl`, make the Makefile the authoritative source and tweak `cmd-list.perl` so that it receives the list of command categories as argument. Signed-off-by: Philippe Blain <[email protected]>

Not all man5/man7 guides are mentioned in the 'git(1)' documentation, which makes the missing ones somewhat hard to find. Add a list of the guides to git(1) by leveraging the existing `Documentation/cmd-list.perl` script to generate a file `cmds-guide.txt` which gets included in git.txt. Also, do not hard-code the manual section '1'. Instead, use a regex so that the manual section is discovered from the first line of each `git*.txt` file. This addition was hinted at in 1b81d8c (help: use command-list.txt for the source of guides, 2018-05-20). Helped-by: Junio C Hamano <[email protected]> Signed-off-by: Philippe Blain <[email protected]>

gitgitgadget · 2020-08-04T13:46:25Z

On the Git mailing list, Philippe Blain wrote (reply to this):


> Le 3 août 2020 à 20:26, Junio C Hamano <[email protected]> a écrit :
> 
> "Philippe Blain via GitGitGadget" <[email protected]> writes:
> 
>> Changes since v1:
>> 
>> * Incorporated Junio's suggestion to reduce duplication.
>> 
>> v1: This series adds a list of the guides to git(1).
>> 
>> The first commit adds the misssing guides 'gitcredentials' and
>> 'gitremote-helpers' to command-list.txt. The only missing guide after this
>> change is 'gitweb.conf', but I think this one is obscure anough, and already
>> linked to in 'gitweb.txt', that it does not matter much.
>> 
>> The second commit drops the usage of 'common' and 'useful' for guides. This
>> was suggested as one of two ways forward by Duy in [1] but was not commented
>> on. I'm CC'ing the people that were CC'ed on that message.
>> 
>> The third commit tweaks 'Documentation/cmd-list.perl' so that it also
>> generates a list of the guides, which gets included in 'git.txt'. I chose to
>> put this list just after the end of the list of commands.
>> 
>> [1] 
>> https://lore.kernel.org/git/CACsJy8ADj-bTMYDHxRNLOMppOEdPbVwL49u3XCfNBCmoLLZo+A@mail.gmail.com/
>> 
>> Philippe Blain (3):
>>  command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers'
>>  help: drop usage of 'common' and 'useful' for guides
>>  git.txt: add list of guides
> 
> I think the "dedup the list of cmds-$category.txt" is logically a
> separate step from "we forgot to add guide category so add it", so
> either (1) "add guide twice, and then refactor" or (2) "refactor
> before adding guide, and then add guide only in one place" would be
> more appropriate than (3) "add guide while refactoring".  IMHO, (2)
> would make the most sense.
> 

I agree that (2) makes the most sense, I've split it for v3. (Your "SQUASH???" message on pb/guide-docs 
may have mislead me :)

Philippe.

gitgitgadget · 2020-08-04T21:58:36Z

This patch series was integrated into seen via git@1359fd8.

gitgitgadget · 2020-08-05T00:33:47Z

This patch series was integrated into seen via git@4afb47c.

phil-blain · 2020-08-05T01:18:14Z

/submit

gitgitgadget · 2020-08-05T01:19:28Z

Submitted as [email protected]

phil-blain · 2020-08-05T01:57:34Z

Hi @dscho, since GitHub actions were introduced in git.git I'm really confused with all the CI jobs (especially all the Windows ones)... is there somewhere where the purpose of the different jobs is documented ? Also I find it weird that most Azure jobs succeed but in under a minute, it seems unlikely the whole test suite runs in such a short time :P

Also, I'm having failures in the Windows job, related to downloading artifacts it seems, I have the feeling this part of the CI scripts is not very robust.. is there a way that could be improved ?

gitgitgadget · 2020-08-05T21:09:51Z

This patch series was integrated into seen via git@f64fdc9.

gitgitgadget · 2020-08-05T22:38:25Z

This patch series was integrated into seen via git@d281bad.

gitgitgadget · 2020-08-05T22:38:26Z

This patch series was integrated into next via git@031cab2.

gitgitgadget · 2020-08-07T21:48:54Z

This patch series was integrated into seen via git@7ca906b.

gitgitgadget · 2020-08-10T18:37:45Z

This patch series was integrated into seen via git@995c719.

gitgitgadget · 2020-08-10T18:37:46Z

This patch series was integrated into next via git@995c719.

gitgitgadget · 2020-08-10T18:37:46Z

This patch series was integrated into master via git@995c719.

gitgitgadget · 2020-08-10T18:37:49Z

Closed via 995c719.

dscho · 2020-08-11T09:48:38Z

since GitHub actions were introduced in git.git I'm really confused with all the CI jobs (especially all the Windows ones)... is there somewhere where the purpose of the different jobs is documented ?

Unfortunately not.

Also I find it weird that most Azure jobs succeed but in under a minute, it seems unlikely the whole test suite runs in such a short time :P

The problem is that I cannot disable the Azure Pipeline just for branches containing .github/workflows/main.yml. (Maybe there is a way, if there is, I haven't found it.) So the Azure Pipeline itself looks for the presence of that file, and just skips everything if it is found.

Also, I'm having failures in the Windows job, related to downloading artifacts it seems, I have the feeling this part of the CI scripts is not very robust.. is there a way that could be improved ?

Yes, I noticed that, too. There is unfortunately nothing on our side that we can do about it, I don't think. I did notice that it has become more robust, though, in the last couple weeks (with occasional hiccups).

phil-blain · 2020-08-11T12:37:08Z

Thanks for getting back to me. So the Azure pipelines are kept for people submitting PRs based on old versions of the repo, before the Github actions were introduced?

dscho · 2020-08-12T12:52:48Z

Yes.

phil-blain added 2 commits August 1, 2020 14:55

gitgitgadget bot added the seen label Aug 2, 2020

gitgitgadget bot reviewed Aug 2, 2020

View reviewed changes

phil-blain force-pushed the list-guides-in-git.1 branch from 9374d80 to 4394bb3 Compare August 3, 2020 14:03

phil-blain changed the title ~~[RFC] List all guides in git(1)~~ List all guides in git(1) Aug 3, 2020

phil-blain mentioned this pull request Aug 3, 2020

Warn if email in CC list is unreachable gitgitgadget/gitgitgadget#289

Closed

gitster and others added 2 commits August 4, 2020 09:27

phil-blain force-pushed the list-guides-in-git.1 branch from 4394bb3 to 840371f Compare August 4, 2020 13:35

gitgitgadget bot added the next label Aug 5, 2020

weekly-digest bot mentioned this pull request Aug 9, 2020

Weekly Digest (2 August, 2020 - 9 August, 2020) #697

Closed

gitgitgadget bot added the master label Aug 10, 2020

gitgitgadget bot closed this Aug 10, 2020

phil-blain deleted the list-guides-in-git.1 branch August 17, 2021 21:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

List all guides in git(1) #691

List all guides in git(1) #691

phil-blain commented Aug 2, 2020 •

edited

Loading

phil-blain commented Aug 2, 2020

gitgitgadget bot commented Aug 2, 2020

gitgitgadget bot commented Aug 2, 2020

gitgitgadget bot commented Aug 2, 2020

gitgitgadget bot Aug 2, 2020

gitgitgadget bot Aug 2, 2020

gitgitgadget bot Aug 3, 2020

gitgitgadget bot commented Aug 2, 2020

gitgitgadget bot commented Aug 3, 2020

gitgitgadget bot commented Aug 3, 2020

phil-blain commented Aug 4, 2020

gitgitgadget bot commented Aug 4, 2020

gitgitgadget bot commented Aug 4, 2020

gitgitgadget bot commented Aug 4, 2020

gitgitgadget bot commented Aug 4, 2020

gitgitgadget bot commented Aug 4, 2020

gitgitgadget bot commented Aug 5, 2020

phil-blain commented Aug 5, 2020

gitgitgadget bot commented Aug 5, 2020

phil-blain commented Aug 5, 2020

gitgitgadget bot commented Aug 5, 2020

gitgitgadget bot commented Aug 5, 2020

gitgitgadget bot commented Aug 5, 2020

gitgitgadget bot commented Aug 7, 2020

gitgitgadget bot commented Aug 10, 2020

gitgitgadget bot commented Aug 10, 2020

gitgitgadget bot commented Aug 10, 2020

gitgitgadget bot commented Aug 10, 2020

dscho commented Aug 11, 2020

phil-blain commented Aug 11, 2020

dscho commented Aug 12, 2020

List all guides in git(1) #691

List all guides in git(1) #691

Conversation

phil-blain commented Aug 2, 2020 • edited Loading

phil-blain commented Aug 2, 2020

gitgitgadget bot commented Aug 2, 2020

gitgitgadget bot commented Aug 2, 2020

gitgitgadget bot commented Aug 2, 2020

gitgitgadget bot Aug 2, 2020

Choose a reason for hiding this comment

gitgitgadget bot Aug 2, 2020

Choose a reason for hiding this comment

gitgitgadget bot Aug 3, 2020

Choose a reason for hiding this comment

gitgitgadget bot commented Aug 2, 2020

gitgitgadget bot commented Aug 3, 2020

gitgitgadget bot commented Aug 3, 2020

phil-blain commented Aug 4, 2020

gitgitgadget bot commented Aug 4, 2020

gitgitgadget bot commented Aug 4, 2020

gitgitgadget bot commented Aug 4, 2020

gitgitgadget bot commented Aug 4, 2020

gitgitgadget bot commented Aug 4, 2020

gitgitgadget bot commented Aug 5, 2020

phil-blain commented Aug 5, 2020

gitgitgadget bot commented Aug 5, 2020

phil-blain commented Aug 5, 2020

gitgitgadget bot commented Aug 5, 2020

gitgitgadget bot commented Aug 5, 2020

gitgitgadget bot commented Aug 5, 2020

gitgitgadget bot commented Aug 7, 2020

gitgitgadget bot commented Aug 10, 2020

gitgitgadget bot commented Aug 10, 2020

gitgitgadget bot commented Aug 10, 2020

gitgitgadget bot commented Aug 10, 2020

dscho commented Aug 11, 2020

phil-blain commented Aug 11, 2020

dscho commented Aug 12, 2020

phil-blain commented Aug 2, 2020 •

edited

Loading