* Re: [PATCH] doc: don't require a SYNOPSIS in section 7
2026-10-02 16:07 [PATCH] doc: don't require a SYNOPSIS in section 7 Julia Evans via GitGitGadget
@ 2026-10-02 17:33 ` Junio C Hamano
2026-10-02 18:03 ` Junio C Hamano
2026-10-02 18:20 ` Julia Evans
` (2 subsequent siblings)
3 siblings, 1 reply; 15+ messages in thread
From: Junio C Hamano @ 2026-10-02 17:33 UTC (permalink / raw)
To: Julia Evans via GitGitGadget; +Cc: git, Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Julia Evans <julia@jvns.ca>
>
> Remove the SYNOPSIS section from the section 7 man pages where
> appropriate, to avoid having a section that contains no information.
> It's not the norm in section 7 to always require a SYNOPSIS.
Very true.
> diff --git a/Documentation/gitcli.adoc b/Documentation/gitcli.adoc
> index 6815d6bfb7..9c4598e29c 100644
> --- a/Documentation/gitcli.adoc
> +++ b/Documentation/gitcli.adoc
> @@ -5,11 +5,6 @@ NAME
> ----
> gitcli - Git command-line interface and conventions
>
> -SYNOPSIS
> ---------
> -gitcli
> -
> -
> DESCRIPTION
> -----------
>
Yup. Thanks for starting this move. These "we add meaningless
filler only because we need to" were always eyesore.
> diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
> index 02408a0062..e032f6ae53 100755
> --- a/Documentation/lint-man-section-order.perl
> +++ b/Documentation/lint-man-section-order.perl
> @@ -53,6 +53,11 @@ sub report {
> $exit_code = 1;
> }
>
> +# assume the first line is formatted like 'gitglossary(7)'
> +my $firstline = <>;
> +$firstline =~ m/\((\d)\)/;
> +my $man_section_number = $1;
This means that the main loop that has already read all the lines of
the file no longer sees the first line. I do not think it would
immediately break anything (in other words, the current
implementation of the loop only checks the section header and
nothing else), but it may be an unhealthy thing to assume that this
will not change.
It would be very simple to move it inside the loop.
Would it work better to do it this way, I wonder? The idea is to
notice what manual sections we are in, and tweak the %SECTIONS
contents there, to allow us customize behaviour for other sections
later, and keep such customizations out of the actual code.
Documentation/lint-man-section-order.perl | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git c/Documentation/lint-man-section-order.perl w/Documentation/lint-man-section-order.perl
index 02408a0062..ce60c34809 100755
--- c/Documentation/lint-man-section-order.perl
+++ w/Documentation/lint-man-section-order.perl
@@ -55,8 +55,23 @@ sub report {
my $last_was_section;
my @actual_order;
+my $section_tweak_done;
while (my $line = <>) {
chomp $line;
+
+ if (!$section_tweak_done) {
+ # assume the first line is formatted like 'gitglossary(7)'
+ my $firstline = <>;
+ $firstline =~ m/\((\d)\)/;
+ my $man_section_number = $1;
+
+ if ($man_section_number == "7") {
+ # section 7 usually do not have SYNOPSIS
+ $SECTIONS{SYNOPSIS}{required} = 0;
+ }
+ $section_tweak_done = 1;
+ }
+
if ($line =~ $SECTION_RX) {
push @actual_order => $line;
$last_was_section = 1;
^ permalink raw reply related [flat|nested] 15+ messages in thread* Re: [PATCH] doc: don't require a SYNOPSIS in section 7
2026-10-02 17:33 ` Junio C Hamano
@ 2026-10-02 18:03 ` Junio C Hamano
2026-10-02 18:10 ` Julia Evans
0 siblings, 1 reply; 15+ messages in thread
From: Junio C Hamano @ 2026-10-02 18:03 UTC (permalink / raw)
To: Julia Evans via GitGitGadget; +Cc: git, Julia Evans
Junio C Hamano <gitster@pobox.com> writes:
> diff --git c/Documentation/lint-man-section-order.perl w/Documentation/lint-man-section-order.perl
> index 02408a0062..ce60c34809 100755
> --- c/Documentation/lint-man-section-order.perl
> +++ w/Documentation/lint-man-section-order.perl
> @@ -55,8 +55,23 @@ sub report {
>
> my $last_was_section;
> my @actual_order;
> +my $section_tweak_done;
> while (my $line = <>) {
> chomp $line;
> +
> + if (!$section_tweak_done) {
> + # assume the first line is formatted like 'gitglossary(7)'
> + my $firstline = <>;
Ah, this was obviously buggy. Not <>, but we should use $line here.
> + $firstline =~ m/\((\d)\)/;
> + my $man_section_number = $1;
> +
> + if ($man_section_number == "7") {
> + # section 7 usually do not have SYNOPSIS
> + $SECTIONS{SYNOPSIS}{required} = 0;
> + }
> + $section_tweak_done = 1;
> + }
> +
> if ($line =~ $SECTION_RX) {
> push @actual_order => $line;
> $last_was_section = 1;
^ permalink raw reply [flat|nested] 15+ messages in thread* Re: [PATCH] doc: don't require a SYNOPSIS in section 7
2026-10-02 18:03 ` Junio C Hamano
@ 2026-10-02 18:10 ` Julia Evans
0 siblings, 0 replies; 15+ messages in thread
From: Julia Evans @ 2026-10-02 18:10 UTC (permalink / raw)
To: Junio C Hamano, Julia Evans; +Cc: git
On Fri, Oct 2, 2026, at 2:03 PM, Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> diff --git c/Documentation/lint-man-section-order.perl w/Documentation/lint-man-section-order.perl
>> index 02408a0062..ce60c34809 100755
>> --- c/Documentation/lint-man-section-order.perl
>> +++ w/Documentation/lint-man-section-order.perl
>> @@ -55,8 +55,23 @@ sub report {
>>
>> my $last_was_section;
>> my @actual_order;
>> +my $section_tweak_done;
>> while (my $line = <>) {
>> chomp $line;
>> +
>> + if (!$section_tweak_done) {
>> + # assume the first line is formatted like 'gitglossary(7)'
>> + my $firstline = <>;
>
> Ah, this was obviously buggy. Not <>, but we should use $line here.
>
>> + $firstline =~ m/\((\d)\)/;
>> + my $man_section_number = $1;
>> +
>> + if ($man_section_number == "7") {
>> + # section 7 usually do not have SYNOPSIS
>> + $SECTIONS{SYNOPSIS}{required} = 0;
>> + }
>> + $section_tweak_done = 1;
>> + }
>> +
>> if ($line =~ $SECTION_RX) {
>> push @actual_order => $line;
>> $last_was_section = 1;
I'm happy with whichever version of the script you think is easiest to maintain.
I saw that perl also has Tie::File built in which lets you just treat the file as an
array instead of worrying about <>. https://metacpan.org/pod/Tie::File
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH] doc: don't require a SYNOPSIS in section 7
2026-10-02 16:07 [PATCH] doc: don't require a SYNOPSIS in section 7 Julia Evans via GitGitGadget
2026-10-02 17:33 ` Junio C Hamano
@ 2026-10-02 18:20 ` Julia Evans
2026-10-02 21:34 ` Junio C Hamano
2026-10-03 13:10 ` [PATCH v2] " Julia Evans via GitGitGadget
2026-10-06 16:54 ` [PATCH v3] " Julia Evans via GitGitGadget
3 siblings, 1 reply; 15+ messages in thread
From: Julia Evans @ 2026-10-02 18:20 UTC (permalink / raw)
To: Julia Evans, git
> +# assume the first line is formatted like 'gitglossary(7)'
> +my $firstline = <>;
> +$firstline =~ m/\((\d)\)/;
> +my $man_section_number = $1;
> +
> my $last_was_section;
> my @actual_order;
> while (my $line = <>) {
> @@ -93,6 +98,8 @@ while (my $line = <>) {
>
> for my $section (sort keys %SECTIONS) {
> next if !$SECTIONS{$section}->{required} or exists
> $actual_sections{$section};
> + # Synopsis is not required in section 7
> + next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
> report("has no required '$section' section!");
> }
I just realized that this script is actually supposed to be able to process multiple
files as command line arguments, and that this patch won't work for that.
I don't understand how Perl's `<>` works when you pass multiple files as
command line arguments and that might be too much of a can of worms for me to
figure right now :/
^ permalink raw reply [flat|nested] 15+ messages in thread* Re: [PATCH] doc: don't require a SYNOPSIS in section 7
2026-10-02 18:20 ` Julia Evans
@ 2026-10-02 21:34 ` Junio C Hamano
2026-10-03 7:33 ` Tuomas Ahola
0 siblings, 1 reply; 15+ messages in thread
From: Junio C Hamano @ 2026-10-02 21:34 UTC (permalink / raw)
To: Julia Evans; +Cc: Julia Evans, git
"Julia Evans" <julia@jvns.ca> writes:
>> +# assume the first line is formatted like 'gitglossary(7)'
>> +my $firstline = <>;
>> +$firstline =~ m/\((\d)\)/;
>> +my $man_section_number = $1;
>> +
>> my $last_was_section;
>> my @actual_order;
>> while (my $line = <>) {
>> @@ -93,6 +98,8 @@ while (my $line = <>) {
>>
>> for my $section (sort keys %SECTIONS) {
>> next if !$SECTIONS{$section}->{required} or exists
>> $actual_sections{$section};
>> + # Synopsis is not required in section 7
>> + next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
>> report("has no required '$section' section!");
>> }
>
>
> I just realized that this script is actually supposed to be able to process multiple
> files as command line arguments, and that this patch won't work for that.
Yeah, your version would then notice only the first line of the
first file, and my update would also do the same.
You can work from what I gave you and inside the "eof" part of the
loop reset the %SECTIONS back to the original (which means you'd
need to keep a separate copy of the original) and also reset the
"did I tweak the %SECTIONS thing already? have I handled the first
line of the current file?" variable.
> I don't understand how Perl's `<>` works when you pass multiple files as
> command line arguments and that might be too much of a can of worms for me to
> figure right now :/
"man perlfunc" section on "eof" has an example to show what to
detect and reset when you reached the end of each file within a
"while (<>)" loop.
# reset line numbering on each input file
while (<>) {
next if /^\s*#/; # skip comments
print "$.\t$_";
} continue {
close ARGV if eof; # Not eof()!
}
The explicit "close ARGV if eof;" is how the example resets the
$. counter (which by default counts all the lines coming from <>
across multiple files).
^ permalink raw reply [flat|nested] 15+ messages in thread* Re: [PATCH] doc: don't require a SYNOPSIS in section 7
2026-10-02 21:34 ` Junio C Hamano
@ 2026-10-03 7:33 ` Tuomas Ahola
2026-10-03 11:37 ` Julia Evans
0 siblings, 1 reply; 15+ messages in thread
From: Tuomas Ahola @ 2026-10-03 7:33 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Julia Evans, Julia Evans, git
Junio C Hamano <gitster@pobox.com> wrote:
> "Julia Evans" <julia@jvns.ca> writes:
>
> >> +# assume the first line is formatted like 'gitglossary(7)'
> >> +my $firstline = <>;
> >> +$firstline =~ m/\((\d)\)/;
> >> +my $man_section_number = $1;
> >> +
> >> my $last_was_section;
> >> my @actual_order;
> >> while (my $line = <>) {
> >> @@ -93,6 +98,8 @@ while (my $line = <>) {
> >>
> >> for my $section (sort keys %SECTIONS) {
> >> next if !$SECTIONS{$section}->{required} or exists
> >> $actual_sections{$section};
> >> + # Synopsis is not required in section 7
> >> + next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
> >> report("has no required '$section' section!");
> >> }
> >
> >
> > I just realized that this script is actually supposed to be able to process multiple
> > files as command line arguments, and that this patch won't work for that.
>
> Yeah, your version would then notice only the first line of the
> first file, and my update would also do the same.
>
> You can work from what I gave you and inside the "eof" part of the
> loop reset the %SECTIONS back to the original (which means you'd
> need to keep a separate copy of the original) and also reset the
> "did I tweak the %SECTIONS thing already? have I handled the first
> line of the current file?" variable.
>
Something slightly more declarative I managed to hack up:
diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 02408a0062..160c65e1be 100755
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -13,6 +13,9 @@
},
'SYNOPSIS' => {
required => 1,
+ optional_in_man_sections => {
+ '7' => 1,
+ },
order => $order++,
},
'DESCRIPTION' => {
@@ -53,10 +56,18 @@ sub report {
$exit_code = 1;
}
+my $man_section_number;
my $last_was_section;
my @actual_order;
while (my $line = <>) {
chomp $line;
+
+ if ($. == 1) {
+ # assume the first line is formatted like 'gitglossary(7)'
+ $line =~ m/\((\d)\)/;
+ $man_section_number = $1;
+ }
+
if ($line =~ $SECTION_RX) {
push @actual_order => $line;
$last_was_section = 1;
@@ -92,7 +103,9 @@ sub report {
@actual_sections{@actual_order} = ();
for my $section (sort keys %SECTIONS) {
- next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
+ next if !$SECTIONS{$section}->{required} or
+ $SECTIONS{$section}->{optional_in_man_sections}->{$man_section_number} or
+ exists $actual_sections{$section};
report("has no required '$section' section!");
}
^ permalink raw reply related [flat|nested] 15+ messages in thread* Re: [PATCH] doc: don't require a SYNOPSIS in section 7
2026-10-03 7:33 ` Tuomas Ahola
@ 2026-10-03 11:37 ` Julia Evans
2026-10-03 12:55 ` Tuomas Ahola
0 siblings, 1 reply; 15+ messages in thread
From: Julia Evans @ 2026-10-03 11:37 UTC (permalink / raw)
To: Tuomas Ahola, Junio C Hamano; +Cc: Julia Evans, git
> Something slightly more declarative I managed to hack up:
>
> diff --git a/Documentation/lint-man-section-order.perl
> b/Documentation/lint-man-section-order.perl
> index 02408a0062..160c65e1be 100755
> --- a/Documentation/lint-man-section-order.perl
> +++ b/Documentation/lint-man-section-order.perl
> @@ -13,6 +13,9 @@
> },
> 'SYNOPSIS' => {
> required => 1,
> + optional_in_man_sections => {
> + '7' => 1,
> + },
> order => $order++,
> },
> 'DESCRIPTION' => {
> @@ -53,10 +56,18 @@ sub report {
> $exit_code = 1;
> }
>
> +my $man_section_number;
> my $last_was_section;
> my @actual_order;
> while (my $line = <>) {
> chomp $line;
> +
> + if ($. == 1) {
> + # assume the first line is formatted like 'gitglossary(7)'
> + $line =~ m/\((\d)\)/;
> + $man_section_number = $1;
> + }
> +
> if ($line =~ $SECTION_RX) {
> push @actual_order => $line;
> $last_was_section = 1;
> @@ -92,7 +103,9 @@ sub report {
> @actual_sections{@actual_order} = ();
>
> for my $section (sort keys %SECTIONS) {
> - next if !$SECTIONS{$section}->{required} or exists
> $actual_sections{$section};
> + next if !$SECTIONS{$section}->{required} or
> + $SECTIONS{$section}->{optional_in_man_sections}->{$man_section_number}
> or
> + exists $actual_sections{$section};
> report("has no required '$section' section!");
> }
This looks great! Will use for v2 and mark you as a coauthor, thank you :D
(let me know if there's a better way to do that also, still learning the process)
I wasn't sure what `$.` was before but this makes it clear that it's the current
line number (and https://perldoc.perl.org/perlvar agrees). Apparently
`$ARGV` is the name of the current file. (different from @ARGV)
^ permalink raw reply [flat|nested] 15+ messages in thread* Re: [PATCH] doc: don't require a SYNOPSIS in section 7
2026-10-03 11:37 ` Julia Evans
@ 2026-10-03 12:55 ` Tuomas Ahola
0 siblings, 0 replies; 15+ messages in thread
From: Tuomas Ahola @ 2026-10-03 12:55 UTC (permalink / raw)
To: Julia Evans; +Cc: Junio C Hamano, Julia Evans, git
"Julia Evans" <julia@jvns.ca> wrote:
> > Something slightly more declarative I managed to hack up:
> >
>
> This looks great! Will use for v2 and mark you as a coauthor, thank you :D
> (let me know if there's a better way to do that also, still learning the process)
>
Cool! You can add these before your S-o-b line:
Co-authored-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
That seems to be the usual formula for marking coauthors (cf. [1] for a random
example).
> I wasn't sure what `$.` was before but this makes it clear that it's the current
> line number (and https://perldoc.perl.org/perlvar agrees). Apparently
> `$ARGV` is the name of the current file. (different from @ARGV)
Yes, the Perl syntax is... interesting.
Links:
1. https://lore.kernel.org/git/20260711160447.99708-3-marcelomlage@usp.br/
^ permalink raw reply [flat|nested] 15+ messages in thread
* [PATCH v2] doc: don't require a SYNOPSIS in section 7
2026-10-02 16:07 [PATCH] doc: don't require a SYNOPSIS in section 7 Julia Evans via GitGitGadget
2026-10-02 17:33 ` Junio C Hamano
2026-10-02 18:20 ` Julia Evans
@ 2026-10-03 13:10 ` Julia Evans via GitGitGadget
2026-10-04 13:17 ` Junio C Hamano
2026-10-06 16:54 ` [PATCH v3] " Julia Evans via GitGitGadget
3 siblings, 1 reply; 15+ messages in thread
From: Julia Evans via GitGitGadget @ 2026-10-03 13:10 UTC (permalink / raw)
To: git; +Cc: Tuomas Ahola, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
Remove the SYNOPSIS section from the section 7 man pages where
appropriate, to avoid having a section that contains no information.
It's not the norm in section 7 to always require a SYNOPSIS.
Update the perl script with a special case for section 7.
Tested by running `make lint-docs`, and looked at the renaming synopses
with this fish script snippet:
for i in *.7
echo $i; grep SYNOPSIS -A 5 (string replace .7 .adoc $i)
end
Co-authored-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Julia Evans <julia@jvns.ca>
---
doc: don't require a SYNOPSIS in section 7
Changes in v2: Tuomas rewrote the Perl script changes to be both more
declarative and and more correct. Previously it didn't work if there
were multiple files passed on the command line.
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2246%2Fjvns%2Fno-synopsis-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2246/jvns/no-synopsis-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2246
Range-diff vs v1:
1: b6f8878a1f ! 1: d6004e0c6b doc: don't require a SYNOPSIS in section 7
@@ Commit message
echo $i; grep SYNOPSIS -A 5 (string replace .7 .adoc $i)
end
+ Co-authored-by: Tuomas Ahola <taahol@utu.fi>
+ Signed-off-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Julia Evans <julia@jvns.ca>
## Documentation/gitcli.adoc ##
@@ Documentation/gitworkflows.adoc: NAME
## Documentation/lint-man-section-order.perl ##
+@@ Documentation/lint-man-section-order.perl: my %SECTIONS;
+ },
+ 'SYNOPSIS' => {
+ required => 1,
++ optional_in_man_sections => {
++ '7' => 1,
++ },
+ order => $order++,
+ },
+ 'DESCRIPTION' => {
@@ Documentation/lint-man-section-order.perl: sub report {
$exit_code = 1;
}
-+# assume the first line is formatted like 'gitglossary(7)'
-+my $firstline = <>;
-+$firstline =~ m/\((\d)\)/;
-+my $man_section_number = $1;
-+
++my $man_section_number;
my $last_was_section;
my @actual_order;
while (my $line = <>) {
+ chomp $line;
++
++ if ($. == 1) {
++ # assume the first line is formatted like 'gitglossary(7)'
++ $line =~ m/\((\d)\)/;
++ $man_section_number = $1;
++ }
++
+ if ($line =~ $SECTION_RX) {
+ push @actual_order => $line;
+ $last_was_section = 1;
@@ Documentation/lint-man-section-order.perl: while (my $line = <>) {
+ @actual_sections{@actual_order} = ();
for my $section (sort keys %SECTIONS) {
- next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
-+ # Synopsis is not required in section 7
-+ next if ($section eq "SYNOPSIS" && $man_section_number eq "7");
+- next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
++ next if !$SECTIONS{$section}->{required} or
++ $SECTIONS{$section}->{optional_in_man_sections}->{$man_section_number} or
++ exists $actual_sections{$section};
report("has no required '$section' section!");
}
Documentation/gitcli.adoc | 5 -----
Documentation/gitcore-tutorial.adoc | 4 ----
Documentation/gitdatamodel.adoc | 4 ----
Documentation/giteveryday.adoc | 5 -----
Documentation/gitfaq.adoc | 4 ----
Documentation/gitglossary.adoc | 4 ----
Documentation/gitpacking.adoc | 4 ----
Documentation/gitrevisions.adoc | 5 -----
Documentation/gittutorial-2.adoc | 5 -----
Documentation/gittutorial.adoc | 5 -----
Documentation/gitworkflows.adoc | 6 ------
Documentation/lint-man-section-order.perl | 15 ++++++++++++++-
12 files changed, 14 insertions(+), 52 deletions(-)
diff --git a/Documentation/gitcli.adoc b/Documentation/gitcli.adoc
index 6815d6bfb7..9c4598e29c 100644
--- a/Documentation/gitcli.adoc
+++ b/Documentation/gitcli.adoc
@@ -5,11 +5,6 @@ NAME
----
gitcli - Git command-line interface and conventions
-SYNOPSIS
---------
-gitcli
-
-
DESCRIPTION
-----------
diff --git a/Documentation/gitcore-tutorial.adoc b/Documentation/gitcore-tutorial.adoc
index 2122aeb976..71fda63a1c 100644
--- a/Documentation/gitcore-tutorial.adoc
+++ b/Documentation/gitcore-tutorial.adoc
@@ -5,10 +5,6 @@ NAME
----
gitcore-tutorial - A Git core tutorial for developers
-SYNOPSIS
---------
-git *
-
DESCRIPTION
-----------
diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
index 56b7635c19..8d9be02036 100644
--- a/Documentation/gitdatamodel.adoc
+++ b/Documentation/gitdatamodel.adoc
@@ -5,10 +5,6 @@ NAME
----
gitdatamodel - Git's core data model
-SYNOPSIS
---------
-gitdatamodel
-
DESCRIPTION
-----------
diff --git a/Documentation/giteveryday.adoc b/Documentation/giteveryday.adoc
index 6cfdd0e07b..0c9db2f150 100644
--- a/Documentation/giteveryday.adoc
+++ b/Documentation/giteveryday.adoc
@@ -5,11 +5,6 @@ NAME
----
giteveryday - A useful minimum set of commands for Everyday Git
-SYNOPSIS
---------
-
-Everyday Git With 20 Commands Or So
-
DESCRIPTION
-----------
diff --git a/Documentation/gitfaq.adoc b/Documentation/gitfaq.adoc
index f6c9b9d9f7..b26e4e3a09 100644
--- a/Documentation/gitfaq.adoc
+++ b/Documentation/gitfaq.adoc
@@ -5,10 +5,6 @@ NAME
----
gitfaq - Frequently asked questions about using Git
-SYNOPSIS
---------
-gitfaq
-
DESCRIPTION
-----------
diff --git a/Documentation/gitglossary.adoc b/Documentation/gitglossary.adoc
index b046d9cb29..eb1e60832e 100644
--- a/Documentation/gitglossary.adoc
+++ b/Documentation/gitglossary.adoc
@@ -5,10 +5,6 @@ NAME
----
gitglossary - A Git Glossary
-SYNOPSIS
---------
-*
-
DESCRIPTION
-----------
diff --git a/Documentation/gitpacking.adoc b/Documentation/gitpacking.adoc
index e6de6ec824..b0d952c797 100644
--- a/Documentation/gitpacking.adoc
+++ b/Documentation/gitpacking.adoc
@@ -5,10 +5,6 @@ NAME
----
gitpacking - Advanced concepts related to packing in Git
-SYNOPSIS
---------
-gitpacking
-
DESCRIPTION
-----------
diff --git a/Documentation/gitrevisions.adoc b/Documentation/gitrevisions.adoc
index 7146117de5..4412f84d83 100644
--- a/Documentation/gitrevisions.adoc
+++ b/Documentation/gitrevisions.adoc
@@ -5,11 +5,6 @@ NAME
----
gitrevisions - Specifying revisions and ranges for Git
-SYNOPSIS
---------
-gitrevisions
-
-
DESCRIPTION
-----------
diff --git a/Documentation/gittutorial-2.adoc b/Documentation/gittutorial-2.adoc
index 8bdb7d0bd3..6a4d482ed6 100644
--- a/Documentation/gittutorial-2.adoc
+++ b/Documentation/gittutorial-2.adoc
@@ -5,11 +5,6 @@ NAME
----
gittutorial-2 - A tutorial introduction to Git: part two
-SYNOPSIS
---------
-[verse]
-git *
-
DESCRIPTION
-----------
diff --git a/Documentation/gittutorial.adoc b/Documentation/gittutorial.adoc
index 519b8d8be2..03120ba191 100644
--- a/Documentation/gittutorial.adoc
+++ b/Documentation/gittutorial.adoc
@@ -5,11 +5,6 @@ NAME
----
gittutorial - A tutorial introduction to Git
-SYNOPSIS
---------
-[verse]
-git *
-
DESCRIPTION
-----------
diff --git a/Documentation/gitworkflows.adoc b/Documentation/gitworkflows.adoc
index 59305265c5..ad02828bff 100644
--- a/Documentation/gitworkflows.adoc
+++ b/Documentation/gitworkflows.adoc
@@ -5,12 +5,6 @@ NAME
----
gitworkflows - An overview of recommended workflows with Git
-SYNOPSIS
---------
-[verse]
-git *
-
-
DESCRIPTION
-----------
diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 02408a0062..160c65e1be 100755
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -13,6 +13,9 @@ my %SECTIONS;
},
'SYNOPSIS' => {
required => 1,
+ optional_in_man_sections => {
+ '7' => 1,
+ },
order => $order++,
},
'DESCRIPTION' => {
@@ -53,10 +56,18 @@ sub report {
$exit_code = 1;
}
+my $man_section_number;
my $last_was_section;
my @actual_order;
while (my $line = <>) {
chomp $line;
+
+ if ($. == 1) {
+ # assume the first line is formatted like 'gitglossary(7)'
+ $line =~ m/\((\d)\)/;
+ $man_section_number = $1;
+ }
+
if ($line =~ $SECTION_RX) {
push @actual_order => $line;
$last_was_section = 1;
@@ -92,7 +103,9 @@ while (my $line = <>) {
@actual_sections{@actual_order} = ();
for my $section (sort keys %SECTIONS) {
- next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
+ next if !$SECTIONS{$section}->{required} or
+ $SECTIONS{$section}->{optional_in_man_sections}->{$man_section_number} or
+ exists $actual_sections{$section};
report("has no required '$section' section!");
}
base-commit: a018953688f1b10bddf91bff8747068f5f4746a4
--
gitgitgadget
^ permalink raw reply related [flat|nested] 15+ messages in thread* Re: [PATCH v2] doc: don't require a SYNOPSIS in section 7
2026-10-03 13:10 ` [PATCH v2] " Julia Evans via GitGitGadget
@ 2026-10-04 13:17 ` Junio C Hamano
2026-10-06 11:17 ` Julia Evans
0 siblings, 1 reply; 15+ messages in thread
From: Junio C Hamano @ 2026-10-04 13:17 UTC (permalink / raw)
To: Julia Evans via GitGitGadget; +Cc: git, Tuomas Ahola, Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Changes in v2: Tuomas rewrote the Perl script changes to be both more
> declarative and and more correct. Previously it didn't work if there
> were multiple files passed on the command line.
> diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
> index 02408a0062..160c65e1be 100755
> --- a/Documentation/lint-man-section-order.perl
> +++ b/Documentation/lint-man-section-order.perl
> @@ -13,6 +13,9 @@ my %SECTIONS;
> },
> 'SYNOPSIS' => {
> required => 1,
> + optional_in_man_sections => {
> + '7' => 1,
> + },
> order => $order++,
> },
> 'DESCRIPTION' => {
> @@ -53,10 +56,18 @@ sub report {
> $exit_code = 1;
> }
>
> +my $man_section_number;
> my $last_was_section;
> my @actual_order;
> while (my $line = <>) {
> chomp $line;
> +
> + if ($. == 1) {
OK, this, together with the explicit "close ARGV" later in
postcontext upon seeing eof, lets us do a "special" thing on the
first line.
I think for the purpose of "doc lint", this implementation is good
enough, especially with documented "assumption".
If we wanted to shoot for a bit more robustness, on the other hand,
we would want to handle when $1 is left undef ...
> + # assume the first line is formatted like 'gitglossary(7)'
> + $line =~ m/\((\d)\)/;
> + $man_section_number = $1;
... here. Perhaps like
$man_section_number = ($line =~ /\((\d)\)/) ? $1 : "0";
If we left $man_section_number undef, ...
> if ($line =~ $SECTION_RX) {
> push @actual_order => $line;
> $last_was_section = 1;
> @@ -92,7 +103,9 @@ while (my $line = <>) {
> @actual_sections{@actual_order} = ();
>
> for my $section (sort keys %SECTIONS) {
> - next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
> + next if !$SECTIONS{$section}->{required} or
> + $SECTIONS{$section}->{optional_in_man_sections}->{$man_section_number} or
... this will access
$SECTIONS{$section}->{optional_in_man_sections}->{undef}
and may trigger a warning on use of uninitialized value.
Also, this would autovivify $SECTIONS{*}{optional_in_man_sections}
for sections that don't have optional_in_man_sections hash (like
NAME and DESCRIPTION), which may be harmless but needless.
^ permalink raw reply [flat|nested] 15+ messages in thread* Re: [PATCH v2] doc: don't require a SYNOPSIS in section 7
2026-10-04 13:17 ` Junio C Hamano
@ 2026-10-06 11:17 ` Julia Evans
2026-10-06 16:07 ` Junio C Hamano
0 siblings, 1 reply; 15+ messages in thread
From: Julia Evans @ 2026-10-06 11:17 UTC (permalink / raw)
To: Junio C Hamano, Julia Evans; +Cc: git, Tuomas Ahola
On Sun, Oct 4, 2026, at 9:17 AM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> Changes in v2: Tuomas rewrote the Perl script changes to be both more
>> declarative and and more correct. Previously it didn't work if there
>> were multiple files passed on the command line.
>
>> diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
>> index 02408a0062..160c65e1be 100755
>> --- a/Documentation/lint-man-section-order.perl
>> +++ b/Documentation/lint-man-section-order.perl
>> @@ -13,6 +13,9 @@ my %SECTIONS;
>> },
>> 'SYNOPSIS' => {
>> required => 1,
>> + optional_in_man_sections => {
>> + '7' => 1,
>> + },
>> order => $order++,
>> },
>> 'DESCRIPTION' => {
>> @@ -53,10 +56,18 @@ sub report {
>> $exit_code = 1;
>> }
>>
>> +my $man_section_number;
>> my $last_was_section;
>> my @actual_order;
>> while (my $line = <>) {
>> chomp $line;
>> +
>> + if ($. == 1) {
>
> OK, this, together with the explicit "close ARGV" later in
> postcontext upon seeing eof, lets us do a "special" thing on the
> first line.
>
>
> I think for the purpose of "doc lint", this implementation is good
> enough, especially with documented "assumption".
>
> If we wanted to shoot for a bit more robustness, on the other hand,
> we would want to handle when $1 is left undef ...
>
>> + # assume the first line is formatted like 'gitglossary(7)'
>> + $line =~ m/\((\d)\)/;
>> + $man_section_number = $1;
>
> ... here. Perhaps like
>
> $man_section_number = ($line =~ /\((\d)\)/) ? $1 : "0";
Or maybe like
`$line =~ m/\((\d)\)/ or report("first line should look like `somename(1)`");`
or some similar error message
^ permalink raw reply [flat|nested] 15+ messages in thread* Re: [PATCH v2] doc: don't require a SYNOPSIS in section 7
2026-10-06 11:17 ` Julia Evans
@ 2026-10-06 16:07 ` Junio C Hamano
0 siblings, 0 replies; 15+ messages in thread
From: Junio C Hamano @ 2026-10-06 16:07 UTC (permalink / raw)
To: Julia Evans; +Cc: Julia Evans, git, Tuomas Ahola
"Julia Evans" <julia@jvns.ca> writes:
> Or maybe like
>
> `$line =~ m/\((\d)\)/ or report("first line should look like `somename(1)`");`
>
> or some similar error message
Sure, not being totally silent is better but we also need to make
sure that we do not end up using undef when we issue such a warning.
Thanks.
^ permalink raw reply [flat|nested] 15+ messages in thread
* [PATCH v3] doc: don't require a SYNOPSIS in section 7
2026-10-02 16:07 [PATCH] doc: don't require a SYNOPSIS in section 7 Julia Evans via GitGitGadget
` (2 preceding siblings ...)
2026-10-03 13:10 ` [PATCH v2] " Julia Evans via GitGitGadget
@ 2026-10-06 16:54 ` Julia Evans via GitGitGadget
2026-10-06 20:40 ` Junio C Hamano
3 siblings, 1 reply; 15+ messages in thread
From: Julia Evans via GitGitGadget @ 2026-10-06 16:54 UTC (permalink / raw)
To: git; +Cc: Tuomas Ahola, Julia Evans, Julia Evans
From: Julia Evans <julia@jvns.ca>
Remove the SYNOPSIS section from the section 7 man pages where
appropriate, to avoid having a section that contains no information.
It's not the norm in section 7 to always require a SYNOPSIS.
Update the perl script with a special case for section 7.
Tested by running `make lint-docs`, and looked at the renaming synopses
with this fish script snippet:
for i in *.7
echo $i; grep SYNOPSIS -A 5 (string replace .7 .adoc $i)
end
Co-authored-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
Signed-off-by: Julia Evans <julia@jvns.ca>
---
doc: don't require a SYNOPSIS in section 7
Changes in v3: Make sure that $man_section_number doesn't become
undefined if the first line doesn't match the regex
Tested on a file with a first line that isn't well-formatted to make
sure it works and got this output:
gitdatamodel.adoc:1: first line must be formatted like 'gitfaq(7)'
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2246%2Fjvns%2Fno-synopsis-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2246/jvns/no-synopsis-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/2246
Range-diff vs v2:
1: d6004e0c6b ! 1: 6359681fa1 doc: don't require a SYNOPSIS in section 7
@@ Documentation/lint-man-section-order.perl: sub report {
chomp $line;
+
+ if ($. == 1) {
-+ # assume the first line is formatted like 'gitglossary(7)'
+ $line =~ m/\((\d)\)/;
+ $man_section_number = $1;
++ if (!$man_section_number) {
++ report("first line must be formatted like 'gitfaq(7)'");
++ # exit to avoid dealing with $man_section_number being undefined later
++ last;
++ }
+ }
+
if ($line =~ $SECTION_RX) {
Documentation/gitcli.adoc | 5 -----
Documentation/gitcore-tutorial.adoc | 4 ----
Documentation/gitdatamodel.adoc | 4 ----
Documentation/giteveryday.adoc | 5 -----
Documentation/gitfaq.adoc | 4 ----
Documentation/gitglossary.adoc | 4 ----
Documentation/gitpacking.adoc | 4 ----
Documentation/gitrevisions.adoc | 5 -----
Documentation/gittutorial-2.adoc | 5 -----
Documentation/gittutorial.adoc | 5 -----
Documentation/gitworkflows.adoc | 6 ------
Documentation/lint-man-section-order.perl | 19 ++++++++++++++++++-
12 files changed, 18 insertions(+), 52 deletions(-)
diff --git a/Documentation/gitcli.adoc b/Documentation/gitcli.adoc
index 6815d6bfb7..9c4598e29c 100644
--- a/Documentation/gitcli.adoc
+++ b/Documentation/gitcli.adoc
@@ -5,11 +5,6 @@ NAME
----
gitcli - Git command-line interface and conventions
-SYNOPSIS
---------
-gitcli
-
-
DESCRIPTION
-----------
diff --git a/Documentation/gitcore-tutorial.adoc b/Documentation/gitcore-tutorial.adoc
index 2122aeb976..71fda63a1c 100644
--- a/Documentation/gitcore-tutorial.adoc
+++ b/Documentation/gitcore-tutorial.adoc
@@ -5,10 +5,6 @@ NAME
----
gitcore-tutorial - A Git core tutorial for developers
-SYNOPSIS
---------
-git *
-
DESCRIPTION
-----------
diff --git a/Documentation/gitdatamodel.adoc b/Documentation/gitdatamodel.adoc
index 56b7635c19..8d9be02036 100644
--- a/Documentation/gitdatamodel.adoc
+++ b/Documentation/gitdatamodel.adoc
@@ -5,10 +5,6 @@ NAME
----
gitdatamodel - Git's core data model
-SYNOPSIS
---------
-gitdatamodel
-
DESCRIPTION
-----------
diff --git a/Documentation/giteveryday.adoc b/Documentation/giteveryday.adoc
index 6cfdd0e07b..0c9db2f150 100644
--- a/Documentation/giteveryday.adoc
+++ b/Documentation/giteveryday.adoc
@@ -5,11 +5,6 @@ NAME
----
giteveryday - A useful minimum set of commands for Everyday Git
-SYNOPSIS
---------
-
-Everyday Git With 20 Commands Or So
-
DESCRIPTION
-----------
diff --git a/Documentation/gitfaq.adoc b/Documentation/gitfaq.adoc
index f6c9b9d9f7..b26e4e3a09 100644
--- a/Documentation/gitfaq.adoc
+++ b/Documentation/gitfaq.adoc
@@ -5,10 +5,6 @@ NAME
----
gitfaq - Frequently asked questions about using Git
-SYNOPSIS
---------
-gitfaq
-
DESCRIPTION
-----------
diff --git a/Documentation/gitglossary.adoc b/Documentation/gitglossary.adoc
index b046d9cb29..eb1e60832e 100644
--- a/Documentation/gitglossary.adoc
+++ b/Documentation/gitglossary.adoc
@@ -5,10 +5,6 @@ NAME
----
gitglossary - A Git Glossary
-SYNOPSIS
---------
-*
-
DESCRIPTION
-----------
diff --git a/Documentation/gitpacking.adoc b/Documentation/gitpacking.adoc
index e6de6ec824..b0d952c797 100644
--- a/Documentation/gitpacking.adoc
+++ b/Documentation/gitpacking.adoc
@@ -5,10 +5,6 @@ NAME
----
gitpacking - Advanced concepts related to packing in Git
-SYNOPSIS
---------
-gitpacking
-
DESCRIPTION
-----------
diff --git a/Documentation/gitrevisions.adoc b/Documentation/gitrevisions.adoc
index 7146117de5..4412f84d83 100644
--- a/Documentation/gitrevisions.adoc
+++ b/Documentation/gitrevisions.adoc
@@ -5,11 +5,6 @@ NAME
----
gitrevisions - Specifying revisions and ranges for Git
-SYNOPSIS
---------
-gitrevisions
-
-
DESCRIPTION
-----------
diff --git a/Documentation/gittutorial-2.adoc b/Documentation/gittutorial-2.adoc
index 8bdb7d0bd3..6a4d482ed6 100644
--- a/Documentation/gittutorial-2.adoc
+++ b/Documentation/gittutorial-2.adoc
@@ -5,11 +5,6 @@ NAME
----
gittutorial-2 - A tutorial introduction to Git: part two
-SYNOPSIS
---------
-[verse]
-git *
-
DESCRIPTION
-----------
diff --git a/Documentation/gittutorial.adoc b/Documentation/gittutorial.adoc
index 519b8d8be2..03120ba191 100644
--- a/Documentation/gittutorial.adoc
+++ b/Documentation/gittutorial.adoc
@@ -5,11 +5,6 @@ NAME
----
gittutorial - A tutorial introduction to Git
-SYNOPSIS
---------
-[verse]
-git *
-
DESCRIPTION
-----------
diff --git a/Documentation/gitworkflows.adoc b/Documentation/gitworkflows.adoc
index 59305265c5..ad02828bff 100644
--- a/Documentation/gitworkflows.adoc
+++ b/Documentation/gitworkflows.adoc
@@ -5,12 +5,6 @@ NAME
----
gitworkflows - An overview of recommended workflows with Git
-SYNOPSIS
---------
-[verse]
-git *
-
-
DESCRIPTION
-----------
diff --git a/Documentation/lint-man-section-order.perl b/Documentation/lint-man-section-order.perl
index 02408a0062..35af3b8f67 100755
--- a/Documentation/lint-man-section-order.perl
+++ b/Documentation/lint-man-section-order.perl
@@ -13,6 +13,9 @@ my %SECTIONS;
},
'SYNOPSIS' => {
required => 1,
+ optional_in_man_sections => {
+ '7' => 1,
+ },
order => $order++,
},
'DESCRIPTION' => {
@@ -53,10 +56,22 @@ sub report {
$exit_code = 1;
}
+my $man_section_number;
my $last_was_section;
my @actual_order;
while (my $line = <>) {
chomp $line;
+
+ if ($. == 1) {
+ $line =~ m/\((\d)\)/;
+ $man_section_number = $1;
+ if (!$man_section_number) {
+ report("first line must be formatted like 'gitfaq(7)'");
+ # exit to avoid dealing with $man_section_number being undefined later
+ last;
+ }
+ }
+
if ($line =~ $SECTION_RX) {
push @actual_order => $line;
$last_was_section = 1;
@@ -92,7 +107,9 @@ while (my $line = <>) {
@actual_sections{@actual_order} = ();
for my $section (sort keys %SECTIONS) {
- next if !$SECTIONS{$section}->{required} or exists $actual_sections{$section};
+ next if !$SECTIONS{$section}->{required} or
+ $SECTIONS{$section}->{optional_in_man_sections}->{$man_section_number} or
+ exists $actual_sections{$section};
report("has no required '$section' section!");
}
base-commit: a018953688f1b10bddf91bff8747068f5f4746a4
--
gitgitgadget
^ permalink raw reply related [flat|nested] 15+ messages in thread* Re: [PATCH v3] doc: don't require a SYNOPSIS in section 7
2026-10-06 16:54 ` [PATCH v3] " Julia Evans via GitGitGadget
@ 2026-10-06 20:40 ` Junio C Hamano
0 siblings, 0 replies; 15+ messages in thread
From: Junio C Hamano @ 2026-10-06 20:40 UTC (permalink / raw)
To: Julia Evans via GitGitGadget; +Cc: git, Tuomas Ahola, Julia Evans
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Julia Evans <julia@jvns.ca>
>
> Remove the SYNOPSIS section from the section 7 man pages where
> appropriate, to avoid having a section that contains no information.
> It's not the norm in section 7 to always require a SYNOPSIS.
>
> Update the perl script with a special case for section 7.
>
> Tested by running `make lint-docs`, and looked at the renaming synopses
> with this fish script snippet:
>
> for i in *.7
> echo $i; grep SYNOPSIS -A 5 (string replace .7 .adoc $i)
> end
>
> Co-authored-by: Tuomas Ahola <taahol@utu.fi>
> Signed-off-by: Tuomas Ahola <taahol@utu.fi>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
> doc: don't require a SYNOPSIS in section 7
>
> Changes in v3: Make sure that $man_section_number doesn't become
> undefined if the first line doesn't match the regex
>
> Tested on a file with a first line that isn't well-formatted to make
> sure it works and got this output:
>
> gitdatamodel.adoc:1: first line must be formatted like 'gitfaq(7)'
And it aborts the whole thing? That does count as a lint. We are
promoting the "assume the first line is ..." to require the format,
which is probably a good thing to do.
Will replace. Thanks.
^ permalink raw reply [flat|nested] 15+ messages in thread