doc: fix accidental literal blocks
Make sure that normal paragraphs in most user-facing docs[1] don’t use literal blocks. This can easily happen if you try to maintain indentation in order to continue a block; that might work in e.g. Markdown variants, but not in AsciiDoc. The fixes are straightforward, i.e. just deindent the block and maybe add line continuations. The only exception is git-sparse-checkout(1) where we also replace indentation used for *intended* literal blocks with `----`. † 1: These have not been considered: • `Documentation/howto/` • `Documentation/technical/` • `Documentation/gitprotocol*` Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> Acked-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Kristoffer Haugsbakk committed
Oct 8, 2025 at 13:48 UTC
b3ac6e737db8635aaed0c355ebaf291b63fb0461
5 files changed
+64
-48
Documentation/config/core.adoc
+2
-2
@@ -75,8 +75,8 @@ The built-in file system monitor is currently available only on a
75
limited set of supported platforms. Currently, this includes Windows
76
and MacOS.
77
+
78
- Otherwise, this variable contains the pathname of the "fsmonitor"
79
- hook command.
78
+Otherwise, this variable contains the pathname of the "fsmonitor"
79
+hook command.
80
+
81
This hook command is used to identify all files that may have changed
82
since the requested date/time. This information is used to speed up
Documentation/git-config.adoc
+9
-9
@@ -117,15 +117,15 @@ OPTIONS
117
118
--comment <message>::
119
Append a comment at the end of new or modified lines.
120
-
121
- If _<message>_ begins with one or more whitespaces followed
122
- by "#", it is used as-is. If it begins with "#", a space is
123
- prepended before it is used. Otherwise, a string " # " (a
124
- space followed by a hash followed by a space) is prepended
125
- to it. And the resulting string is placed immediately after
126
- the value defined for the variable. The _<message>_ must
127
- not contain linefeed characters (no multi-line comments are
128
- permitted).
120
++
121
+If _<message>_ begins with one or more whitespaces followed
122
+by "#", it is used as-is. If it begins with "#", a space is
123
+prepended before it is used. Otherwise, a string " # " (a
124
+space followed by a hash followed by a space) is prepended
125
+to it. And the resulting string is placed immediately after
126
+the value defined for the variable. The _<message>_ must
127
+not contain linefeed characters (no multi-line comments are
128
+permitted).
129
130
--all::
131
With `get`, return all values for a multi-valued key.
Documentation/git-rev-parse.adoc
+7
-7
@@ -174,13 +174,13 @@ for another option.
174
175
Allow oids to be input from any object format that the current
176
repository supports.
177
-
178
- Specifying "sha1" translates if necessary and returns a sha1 oid.
179
-
180
- Specifying "sha256" translates if necessary and returns a sha256 oid.
181
-
182
- Specifying "storage" translates if necessary and returns an oid in
183
- encoded in the storage hash algorithm.
177
++
178
+Specifying "sha1" translates if necessary and returns a sha1 oid.
179
++
180
+Specifying "sha256" translates if necessary and returns a sha256 oid.
181
++
182
+Specifying "storage" translates if necessary and returns an oid in
183
+encoded in the storage hash algorithm.
184
185
Options for Objects
186
~~~~~~~~~~~~~~~~~~~
Documentation/git-shortlog.adoc
+2
-2
@@ -44,8 +44,8 @@ OPTIONS
44
describe each commit. '<format>' can be any string accepted
45
by the `--format` option of 'git log', such as '* [%h] %s'.
46
(See the "PRETTY FORMATS" section of linkgit:git-log[1].)
47
-
48
- Each pretty-printed commit will be rewrapped before it is shown.
47
++
48
+Each pretty-printed commit will be rewrapped before it is shown.
49
50
--date=<format>::
51
Show dates formatted according to the given date string. (See
Documentation/git-sparse-checkout.adoc
+44
-28
@@ -264,34 +264,50 @@ patterns in non-cone mode has a number of shortcomings:
264
inconsistent.
265
266
* It has edge cases where the "right" behavior is unclear. Two examples:
267
-
268
- First, two users are in a subdirectory, and the first runs
269
- git sparse-checkout set '/toplevel-dir/*.c'
270
- while the second runs
271
- git sparse-checkout set relative-dir
272
- Should those arguments be transliterated into
273
- current/subdirectory/toplevel-dir/*.c
274
- and
275
- current/subdirectory/relative-dir
276
- before inserting into the sparse-checkout file? The user who typed
277
- the first command is probably aware that arguments to set/add are
278
- supposed to be patterns in non-cone mode, and probably would not be
279
- happy with such a transliteration. However, many gitignore-style
280
- patterns are just paths, which might be what the user who typed the
281
- second command was thinking, and they'd be upset if their argument
282
- wasn't transliterated.
283
-
284
- Second, what should bash-completion complete on for set/add commands
285
- for non-cone users? If it suggests paths, is it exacerbating the
286
- problem above? Also, if it suggests paths, what if the user has a
287
- file or directory that begins with either a '!' or '#' or has a '*',
288
- '\', '?', '[', or ']' in its name? And if it suggests paths, will
289
- it complete "/pro" to "/proc" (in the root filesystem) rather than to
290
- "/progress.txt" in the current directory? (Note that users are
291
- likely to want to start paths with a leading '/' in non-cone mode,
292
- for the same reason that .gitignore files often have one.)
293
- Completing on files or directories might give nasty surprises in
294
- all these cases.
267
++
268
+First, two users are in a subdirectory, and the first runs
269
++
270
+----
271
+git sparse-checkout set '/toplevel-dir/*.c'
272
+----
273
++
274
+while the second runs
275
++
276
+----
277
+git sparse-checkout set relative-dir
278
+----
279
++
280
+Should those arguments be transliterated into
281
++
282
+----
283
+current/subdirectory/toplevel-dir/*.c
284
+----
285
++
286
+and
287
++
288
+----
289
+current/subdirectory/relative-dir
290
+----
291
++
292
+before inserting into the sparse-checkout file? The user who typed
293
+the first command is probably aware that arguments to set/add are
294
+supposed to be patterns in non-cone mode, and probably would not be
295
+happy with such a transliteration. However, many gitignore-style
296
+patterns are just paths, which might be what the user who typed the
297
+second command was thinking, and they'd be upset if their argument
298
+wasn't transliterated.
299
++
300
+Second, what should bash-completion complete on for set/add commands
301
+for non-cone users? If it suggests paths, is it exacerbating the
302
+problem above? Also, if it suggests paths, what if the user has a
303
+file or directory that begins with either a '!' or '#' or has a '*',
304
+'\', '?', '[', or ']' in its name? And if it suggests paths, will
305
+it complete "/pro" to "/proc" (in the root filesystem) rather than to
306
+"/progress.txt" in the current directory? (Note that users are
307
+likely to want to start paths with a leading '/' in non-cone mode,
308
+for the same reason that .gitignore files often have one.)
309
+Completing on files or directories might give nasty surprises in
310
+all these cases.
311
312
* The excessive flexibility made other extensions essentially
313
impractical. `--sparse-index` is likely impossible in non-cone