git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH] gitglossary: fix indentation of sub-lists

From
Jeff King <peff@peff.net>
Date
Apr 11, 2026, 19:06 UTC
Message-ID
<20260411190625.GA754966@coredump.intra.peff.net>

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 <peff@peff.net>
---
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
Next: Kristoffer Haugsbakk
Message 1 of 7 in “gitglossary: fix indentation of sub-lists”
  1. gitglossary: fix indentation of sub-listsJeff King, Apr 11, 2026
  2. Kristoffer HaugsbakkApr 11, 2026
  3. Kristoffer HaugsbakkApr 11, 2026
  4. Jeff KingApr 11, 2026
  5. gitglossary: fix indentation of sub-listsJeff King, Apr 11, 2026
  6. Kristoffer HaugsbakkApr 12, 2026
  7. Jeff KingApr 12, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.