docs: fix linting issues due to incorrect relative section order
Re-order the sections of a few manual pages to be consistent with the entirety of the rest of our documentation. This allows us to remove the just-added whitelist of "bad" order from lint-man-section-order.perl. I'm doing that this way around so that code will be easy to dig up if we'll need it in the future. I've intentionally not added some other sections such as EXAMPLES to the list of known sections. If we were to add that we'd find some out of order. Perhaps we'll want to order those consistently as well in the future, at which point whitelisting some of them might become handy again. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Apr 9, 2021 at 17:02 UTC
414abf159f9137ea9e4239f3c34d91310edc817d
6 files changed
+78
-98
Documentation/git-cvsserver.txt
+12
-12
@@ -24,6 +24,18 @@ Usage:
24
[verse]
25
'git-cvsserver' [<options>] [pserver|server] [<directory> ...]
26
27
+DESCRIPTION
28
+-----------
29
+
30
+This application is a CVS emulation layer for Git.
31
+
32
+It is highly functional. However, not all methods are implemented,
33
+and for those methods that are implemented,
34
+not all switches are implemented.
35
+
36
+Testing has been done using both the CLI CVS client, and the Eclipse CVS
37
+plugin. Most functionality works fine with both of these clients.
38
+
39
OPTIONS
40
-------
41
@@ -57,18 +69,6 @@ access still needs to be enabled by the `gitcvs.enabled` config option
69
unless `--export-all` was given, too.
70
71
60
-DESCRIPTION
61
------------
62
-
63
-This application is a CVS emulation layer for Git.
64
-
65
-It is highly functional. However, not all methods are implemented,
66
-and for those methods that are implemented,
67
-not all switches are implemented.
68
-
69
-Testing has been done using both the CLI CVS client, and the Eclipse CVS
70
-plugin. Most functionality works fine with both of these clients.
71
-
72
LIMITATIONS
73
-----------
74
Documentation/git-grep.txt
+32
-32
@@ -38,38 +38,6 @@ are lists of one or more search expressions separated by newline
38
characters. An empty string as search expression matches all lines.
39
40
41
-CONFIGURATION
42
--------------
43
-
44
-grep.lineNumber::
45
- If set to true, enable `-n` option by default.
46
-
47
-grep.column::
48
- If set to true, enable the `--column` option by default.
49
-
50
-grep.patternType::
51
- Set the default matching behavior. Using a value of 'basic', 'extended',
52
- 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
53
- `--fixed-strings`, or `--perl-regexp` option accordingly, while the
54
- value 'default' will return to the default matching behavior.
55
-
56
-grep.extendedRegexp::
57
- If set to true, enable `--extended-regexp` option by default. This
58
- option is ignored when the `grep.patternType` option is set to a value
59
- other than 'default'.
60
-
61
-grep.threads::
62
- Number of grep worker threads to use. If unset (or set to 0), Git will
63
- use as many threads as the number of logical cores available.
64
-
65
-grep.fullName::
66
- If set to true, enable `--full-name` option by default.
67
-
68
-grep.fallbackToNoIndex::
69
- If set to true, fall back to git grep --no-index if git grep
70
- is executed outside of a git repository. Defaults to false.
71
-
72
-
41
OPTIONS
42
-------
43
--cached::
@@ -363,6 +331,38 @@ with multiple threads might perform slower than single threaded if `--textconv`
331
is given and there're too many text conversions. So if you experience low
332
performance in this case, it might be desirable to use `--threads=1`.
333
334
+CONFIGURATION
335
+-------------
336
+
337
+grep.lineNumber::
338
+ If set to true, enable `-n` option by default.
339
+
340
+grep.column::
341
+ If set to true, enable the `--column` option by default.
342
+
343
+grep.patternType::
344
+ Set the default matching behavior. Using a value of 'basic', 'extended',
345
+ 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
346
+ `--fixed-strings`, or `--perl-regexp` option accordingly, while the
347
+ value 'default' will return to the default matching behavior.
348
+
349
+grep.extendedRegexp::
350
+ If set to true, enable `--extended-regexp` option by default. This
351
+ option is ignored when the `grep.patternType` option is set to a value
352
+ other than 'default'.
353
+
354
+grep.threads::
355
+ Number of grep worker threads to use. If unset (or set to 0), Git will
356
+ use as many threads as the number of logical cores available.
357
+
358
+grep.fullName::
359
+ If set to true, enable `--full-name` option by default.
360
+
361
+grep.fallbackToNoIndex::
362
+ If set to true, fall back to git grep --no-index if git grep
363
+ is executed outside of a git repository. Defaults to false.
364
+
365
+
366
GIT
367
---
368
Part of the linkgit:git[1] suite
Documentation/git-mktag.txt
+8
-8
@@ -11,14 +11,6 @@ SYNOPSIS
11
[verse]
12
'git mktag'
13
14
-OPTIONS
15
--------
16
-
17
---strict::
18
- By default mktag turns on the equivalent of
19
- linkgit:git-fsck[1] `--strict` mode. Use `--no-strict` to
20
- disable it.
21
-
14
DESCRIPTION
15
-----------
16
@@ -45,6 +37,14 @@ the appropriate `fsck.<msg-id>` varible:
37
38
git -c fsck.extraHeaderEntry=ignore mktag <my-tag-with-headers
39
40
+OPTIONS
41
+-------
42
+
43
+--strict::
44
+ By default mktag turns on the equivalent of
45
+ linkgit:git-fsck[1] `--strict` mode. Use `--no-strict` to
46
+ disable it.
47
+
48
Tag Format
49
----------
50
A tag signature file, to be fed to this command's standard input,
Documentation/git-rebase.txt
+6
-6
@@ -200,12 +200,6 @@ Alternatively, you can undo the 'git rebase' with
200
201
git rebase --abort
202
203
-CONFIGURATION
204
--------------
205
-
206
-include::config/rebase.txt[]
207
-include::config/sequencer.txt[]
208
-
203
OPTIONS
204
-------
205
--onto <newbase>::
@@ -1266,6 +1260,12 @@ merge tlsv1.3
1260
merge cmake
1261
------------
1262
1263
+CONFIGURATION
1264
+-------------
1265
+
1266
+include::config/rebase.txt[]
1267
+include::config/sequencer.txt[]
1268
+
1269
BUGS
1270
----
1271
The todo list presented by the deprecated `--preserve-merges --interactive`
Documentation/git-svn.txt
+19
-19
@@ -1061,25 +1061,6 @@ with different name spaces. For example:
1061
branches = stable/*:refs/remotes/svn/stable/*
1062
branches = debug/*:refs/remotes/svn/debug/*
1063
1064
-BUGS
1065
-----
1066
-
1067
-We ignore all SVN properties except svn:executable. Any unhandled
1068
-properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
1069
-
1070
-Renamed and copied directories are not detected by Git and hence not
1071
-tracked when committing to SVN. I do not plan on adding support for
1072
-this as it's quite difficult and time-consuming to get working for all
1073
-the possible corner cases (Git doesn't do it, either). Committing
1074
-renamed and copied files is fully supported if they're similar enough
1075
-for Git to detect them.
1076
-
1077
-In SVN, it is possible (though discouraged) to commit changes to a tag
1078
-(because a tag is just a directory copy, thus technically the same as a
1079
-branch). When cloning an SVN repository, 'git svn' cannot know if such a
1080
-commit to a tag will happen in the future. Thus it acts conservatively
1081
-and imports all SVN tags as branches, prefixing the tag name with 'tags/'.
1082
-
1064
CONFIGURATION
1065
-------------
1066
@@ -1166,6 +1147,25 @@ $GIT_DIR/svn/\**/.rev_map.*::
1147
if it is missing or not up to date. 'git svn reset' automatically
1148
rewinds it.
1149
1150
+BUGS
1151
+----
1152
+
1153
+We ignore all SVN properties except svn:executable. Any unhandled
1154
+properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
1155
+
1156
+Renamed and copied directories are not detected by Git and hence not
1157
+tracked when committing to SVN. I do not plan on adding support for
1158
+this as it's quite difficult and time-consuming to get working for all
1159
+the possible corner cases (Git doesn't do it, either). Committing
1160
+renamed and copied files is fully supported if they're similar enough
1161
+for Git to detect them.
1162
+
1163
+In SVN, it is possible (though discouraged) to commit changes to a tag
1164
+(because a tag is just a directory copy, thus technically the same as a
1165
+branch). When cloning an SVN repository, 'git svn' cannot know if such a
1166
+commit to a tag will happen in the future. Thus it acts conservatively
1167
+and imports all SVN tags as branches, prefixing the tag name with 'tags/'.
1168
+
1169
SEE ALSO
1170
--------
1171
linkgit:git-rebase[1]
Documentation/lint-man-section-order.perl
+1
-21
@@ -18,24 +18,13 @@ my %SECTIONS;
18
'DESCRIPTION' => {
19
required => 1,
20
order => $order++,
21
- bad => {
22
- 'git-mktag.txt' => 'OPTIONS',
23
- 'git-cvsserver.txt' => 'OPTIONS',
24
- },
21
},
22
'OPTIONS' => {
23
order => $order++,
24
required => 0,
29
- bad => {
30
- 'git-grep.txt' => 'CONFIGURATION',
31
- 'git-rebase.txt' => 'CONFIGURATION',
32
- },
25
},
26
'CONFIGURATION' => {
27
order => $order++,
36
- bad => {
37
- 'git-svn.txt' => 'BUGS',
38
- },
28
},
29
'BUGS' => {
30
order => $order++,
@@ -77,16 +66,7 @@ while (my $line = <>) {
66
67
my $expected_last = $expected_order[-2];
68
my $actual_last = $actual_order[-2];
80
- my $except_last = $SECTIONS{$line}->{bad}->{$ARGV} || '';
81
- if (($SECTIONS{$line}->{bad}->{$ARGV} || '') eq $actual_last) {
82
- # Either we're whitelisted, or ...
83
- next
84
- } elsif (exists $SECTIONS{$actual_last}->{bad}->{$ARGV}) {
85
- # ... we're complaing about the next section
86
- # which is out of order because this one is,
87
- # don't complain about that one.
88
- next;
89
- } elsif ($actual_last ne $expected_last) {
69
+ if ($actual_last ne $expected_last) {
70
report("section '$line' incorrectly ordered, comes after '$actual_last'");
71
}
72
next;