averello/git-mirror
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2025-12-12 20:36:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

doc: fix accidental literal blocks

Browse Source 
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>
This commit is contained in:
Kristoffer Haugsbakk
2025-10-08 13:48:46 +02:00
committed by Junio C Hamano
parent c44beea485
commit b3ac6e737d
5 changed files with 64 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
Documentation/config/core.adoc
View File

@@ -75,8 +75,8 @@ The built-in file system monitor is currently available only on a
limited set of supported platforms. Currently, this includes Windows limited set of supported platforms. Currently, this includes Windows
and MacOS. and MacOS.
+ +
Otherwise, this variable contains the pathname of the "fsmonitor" Otherwise, this variable contains the pathname of the "fsmonitor"
hook command. hook command.
+ +
This hook command is used to identify all files that may have changed This hook command is used to identify all files that may have changed
since the requested date/time. This information is used to speed up since the requested date/time. This information is used to speed up

18
Documentation/git-config.adoc
View File

@@ -117,15 +117,15 @@ OPTIONS
--comment <message>:: --comment <message>::
Append a comment at the end of new or modified lines. Append a comment at the end of new or modified lines.
+
If _<message>_ begins with one or more whitespaces followed If _<message>_ begins with one or more whitespaces followed
by "#", it is used as-is. If it begins with "#", a space is by "#", it is used as-is. If it begins with "#", a space is
prepended before it is used. Otherwise, a string " # " (a prepended before it is used. Otherwise, a string " # " (a
space followed by a hash followed by a space) is prepended space followed by a hash followed by a space) is prepended
to it. And the resulting string is placed immediately after to it. And the resulting string is placed immediately after
the value defined for the variable. The _<message>_ must the value defined for the variable. The _<message>_ must
not contain linefeed characters (no multi-line comments are not contain linefeed characters (no multi-line comments are
permitted). permitted).
--all:: --all::
With `get`, return all values for a multi-valued key. With `get`, return all values for a multi-valued key.

14
Documentation/git-rev-parse.adoc
View File

@@ -174,13 +174,13 @@ for another option.
Allow oids to be input from any object format that the current Allow oids to be input from any object format that the current
repository supports. repository supports.
+
Specifying "sha1" translates if necessary and returns a sha1 oid. Specifying "sha1" translates if necessary and returns a sha1 oid.
+
Specifying "sha256" translates if necessary and returns a sha256 oid. Specifying "sha256" translates if necessary and returns a sha256 oid.
+
Specifying "storage" translates if necessary and returns an oid in Specifying "storage" translates if necessary and returns an oid in
encoded in the storage hash algorithm. encoded in the storage hash algorithm.
Options for Objects Options for Objects
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~

4
Documentation/git-shortlog.adoc
View File

@@ -44,8 +44,8 @@ OPTIONS
describe each commit. '<format>' can be any string accepted describe each commit. '<format>' can be any string accepted
by the `--format` option of 'git log', such as '* [%h] %s'. by the `--format` option of 'git log', such as '* [%h] %s'.
(See the "PRETTY FORMATS" section of linkgit:git-log[1].) (See the "PRETTY FORMATS" section of linkgit:git-log[1].)
+
Each pretty-printed commit will be rewrapped before it is shown. Each pretty-printed commit will be rewrapped before it is shown.
--date=<format>:: --date=<format>::
Show dates formatted according to the given date string. (See Show dates formatted according to the given date string. (See

72
Documentation/git-sparse-checkout.adoc
View File

@@ -264,34 +264,50 @@ patterns in non-cone mode has a number of shortcomings:
inconsistent. inconsistent.
* It has edge cases where the "right" behavior is unclear. Two examples: * It has edge cases where the "right" behavior is unclear. Two examples:
+
First, two users are in a subdirectory, and the first runs First, two users are in a subdirectory, and the first runs
git sparse-checkout set '/toplevel-dir/*.c' +
while the second runs ----
git sparse-checkout set relative-dir git sparse-checkout set '/toplevel-dir/*.c'
Should those arguments be transliterated into ----
current/subdirectory/toplevel-dir/*.c +
and while the second runs
current/subdirectory/relative-dir +
before inserting into the sparse-checkout file? The user who typed ----
the first command is probably aware that arguments to set/add are git sparse-checkout set relative-dir
supposed to be patterns in non-cone mode, and probably would not be ----
happy with such a transliteration. However, many gitignore-style +
patterns are just paths, which might be what the user who typed the Should those arguments be transliterated into
second command was thinking, and they'd be upset if their argument +
wasn't transliterated. ----
current/subdirectory/toplevel-dir/*.c
Second, what should bash-completion complete on for set/add commands ----
for non-cone users? If it suggests paths, is it exacerbating the +
problem above? Also, if it suggests paths, what if the user has a and
file or directory that begins with either a '!' or '#' or has a '*', +
'\', '?', '[', or ']' in its name? And if it suggests paths, will ----
it complete "/pro" to "/proc" (in the root filesystem) rather than to current/subdirectory/relative-dir
"/progress.txt" in the current directory? (Note that users are ----
likely to want to start paths with a leading '/' in non-cone mode, +
for the same reason that .gitignore files often have one.) before inserting into the sparse-checkout file? The user who typed
Completing on files or directories might give nasty surprises in the first command is probably aware that arguments to set/add are
all these cases. supposed to be patterns in non-cone mode, and probably would not be
happy with such a transliteration. However, many gitignore-style
patterns are just paths, which might be what the user who typed the
second command was thinking, and they'd be upset if their argument
wasn't transliterated.
+
Second, what should bash-completion complete on for set/add commands
for non-cone users? If it suggests paths, is it exacerbating the
problem above? Also, if it suggests paths, what if the user has a
file or directory that begins with either a '!' or '#' or has a '*',
'\', '?', '[', or ']' in its name? And if it suggests paths, will
it complete "/pro" to "/proc" (in the root filesystem) rather than to
"/progress.txt" in the current directory? (Note that users are
likely to want to start paths with a leading '/' in non-cone mode,
for the same reason that .gitignore files often have one.)
Completing on files or directories might give nasty surprises in
all these cases.
* The excessive flexibility made other extensions essentially * The excessive flexibility made other extensions essentially
impractical. `--sparse-index` is likely impossible in non-cone impractical. `--sparse-index` is likely impossible in non-cone