Subject: [PATCH] gitglossary: fix indentation of sub-lists

From: Jeff King <[email-masked]>
Date: Sat, 11 Apr 2026 15:06:25 -0400

The glossary entry is a list of terms and their definitions, so
multi-paragraph definitions need "+" continuation lines to indicate
that they are part of a single entry.

When an entry contains a sub-list (say, a bulleted list), the final "+"
may become ambiguous: is it connecting the next paragraph to the final
entry of the sub-list, or to the original list of definition paragraphs?

Asciidoc generally connects it to the former, even when we mean the
latter, and you end up with the next paragraph indented incorrectly,
like this:

  glob
    ...defines glob...

    Two consecutive asterisks ("**") in patterns matched
    against full pathname may have special meaning:

    - ...some special meaning of **...

    - ...another special meaning of **...

    - Other consecutive asterisks are considered invalid.

      Glob magic is incompatible with literal magic.

That final "Glob magic is incompatible" paragraph is in the wrong spot.
It should be at the same level as "Two consecutive asterisks", as it is
not part of the final "Other consecutive asterisks" bullet point.

The same problem appears in several other spots in the glossary.

We can fix this by using "--" markers, which put the sub-list into its
own block. This should catch all of the unordered lists in the glossary,
which I found by grepping for " -" list markers.

Signed-off-by: Jeff King <[email-masked]>
---
Just happened to notice this while looking at the "ref" entry.

 Documentation/glossary-content.adoc | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc
index 20ba121314..8967e89ece 100644
--- a/Documentation/glossary-content.adoc
+++ b/Documentation/glossary-content.adoc
@@ -415,7 +415,8 @@ glob;;
 +
 Two consecutive asterisks ("`**`") in patterns matched against
 full pathname may have special meaning:
-
++
+--
  - A leading "`**`" followed by a slash means match in all
    directories. For example, "`**/foo`" matches file or directory
    "`foo`" anywhere. "`**/foo/bar`" matches file or directory "`bar`"
@@ -430,6 +431,7 @@ full pathname may have special meaning:
    matches "`a/b`", "`a/x/b`", "`a/x/y/b`" and so on.
 
  - Other consecutive asterisks are considered invalid.
+--
 +
 Glob magic is incompatible with literal magic.
 
@@ -442,7 +444,8 @@ See linkgit:gitattributes[5].
 +
 Each of the attribute requirements for the path takes one of
 these forms:
-
++
+--
 - "`ATTR`" requires that the attribute `ATTR` be set.
 
 - "`-ATTR`" requires that the attribute `ATTR` be unset.
@@ -452,6 +455,7 @@ these forms:
 
 - "`!ATTR`" requires that the attribute `ATTR` be
   unspecified.
+--
 +
 Note that when matching against a tree object, attributes are still
 obtained from working tree, not from the given tree object.
@@ -560,14 +564,17 @@ The ref namespace is hierarchical.
 Ref names must either start with `refs/` or be located in the root of
 the hierarchy. For the latter, their name must follow these rules:
 +
+--
  - The name consists of only upper-case characters or underscores.
 
  - The name ends with "`_HEAD`" or is equal to "`HEAD`".
+--
 +
 There are some irregular refs in the root of the hierarchy that do not
 match these rules. The following list is exhaustive and shall not be
 extended in the future:
 +
+--
  - `AUTO_MERGE`
 
  - `BISECT_EXPECTED_REV`
@@ -577,6 +584,7 @@ extended in the future:
  - `NOTES_MERGE_REF`
 
  - `MERGE_AUTOSTASH`
+--
 +
 Different subhierarchies are used for different purposes. For example,
 the `refs/heads/` hierarchy is used to represent local branches whereas
-- 
2.54.0.rc1.279.g55df28c202