global/git
1
0
Fork 0
mirror of https://github.com/git/git.git synced 2026-01-09 17:46:37 +00: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

2
Documentation/git-config.adoc
View File

@@ -117,7 +117,7 @@ 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

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

@@ -174,11 +174,11 @@ 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.

2
Documentation/git-shortlog.adoc
View File

@@ -44,7 +44,7 @@ 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>::

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

@@ -264,15 +264,31 @@ 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' git sparse-checkout set '/toplevel-dir/*.c'
----
+
while the second runs while the second runs
+
----
git sparse-checkout set relative-dir git sparse-checkout set relative-dir
----
+
Should those arguments be transliterated into Should those arguments be transliterated into
+
----
current/subdirectory/toplevel-dir/*.c current/subdirectory/toplevel-dir/*.c
----
+
and and
+
----
current/subdirectory/relative-dir current/subdirectory/relative-dir
----
+
before inserting into the sparse-checkout file? The user who typed before inserting into the sparse-checkout file? The user who typed
the first command is probably aware that arguments to set/add are the first command is probably aware that arguments to set/add are
supposed to be patterns in non-cone mode, and probably would not be supposed to be patterns in non-cone mode, and probably would not be
@@ -280,7 +296,7 @@ patterns in non-cone mode has a number of shortcomings:
patterns are just paths, which might be what the user who typed the 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 second command was thinking, and they'd be upset if their argument
wasn't transliterated. wasn't transliterated.
+
Second, what should bash-completion complete on for set/add commands Second, what should bash-completion complete on for set/add commands
for non-cone users? If it suggests paths, is it exacerbating the 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 problem above? Also, if it suggests paths, what if the user has a