git/Documentation/git-notes.adoc, branch jch

doc: notes: use stuck form throughout

2025-05-27T22:31:08Z

gitcli(7) recommends the *stuck form*. `--ref` is the only one which does not use it. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: notes: treat --stdin equally between copy/remove

2025-05-27T22:31:07Z

46538012d94 (notes remove: --stdin reads from the standard input, 2011-05-18) added `--stdin` for the `remove` subcommand, documenting it in the “Options” section. But `copy --stdin` was added before that, in 160baa0d9cb (notes: implement 'git notes copy --stdin', 2010-03-12). Treat this option equally between the two subcommands: • remove: mention `--stdin` on the subcommand as well, like for `copy` • copy: mention it as well under the option documentation Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: notes: point out copy --stdin use with argv

2025-05-27T22:31:07Z

Unlike `remove --stdin`, this option cannot be combined with object names given via the command line. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: notes: clearly state that --stripspace is the default

2025-05-27T22:31:07Z

Clearly state when which of the regular and negated form of the option take effect.[1] Also mention the subtle behavior that occurs when you mix options like `-m` and `-C`, including a note that it might be fixed in the future. The topic was brought up on v8 of the `--separator` series.[2][3] [1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/ [2]: https://lore.kernel.org/git/xmqq4jp326oj.fsf@gitster.g/ † 3: v11 was the version that landed Helped-by: Junio C Hamano Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: notes: remove stripspace discussion from other options

2025-05-27T22:31:06Z

Cleaning up whitespace in metadata is typical porcelain behavior and this default does not need to be pointed out.[1] Only speak up when the default `--stripspace` is not used. Also remove all misleading mentions of comment lines in the process; see the previous commit. Also remove the period that trails the parenthetical here. † 1: See `-F` in git-commit(1) which has nothing to say about whitespace cleanup. The cleanup discussion is on `--cleanup`. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: notes: rework --[no-]stripspace

2025-05-27T22:31:06Z

Document this option by copying the bullet list from git-stripspace(1). A bullet list is cleaner when there are this many points to consider. We also get a more standardized description of the multiple-blank-lines behavior. Compare the repeating (git-notes(1)): empty lines other than a single line between paragraphs With (git-stripspace(1)): multiple consecutive empty lines And: leading [...] whitespace With: empty lines from the beginning Leading whitespace in the form of spaces (indentation) are not removed. However, empty lines at the start of the message are removed. Note that we drop the mentions of comment line handling because they are wrong; this option does not control how lines which can be recognized as comment lines are handled. Only interactivity controls that: • Comment lines are stripped after editing interactively • Lines which could be recognized as comment lines are left alone when the message is given non-interactively So it is misleading to document the comment line behavior on this option. Further, the text is wrong: Lines starting with `#` will be stripped out in non-editor cases like `-m`, [...] Comment lines are still indirectly discussed on other options. We will deal with them in the next commit. Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

doc: notes: split out options with negated forms

2025-05-27T22:31:06Z

Split these out so that they are easier to search for.[1] [1]: https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/ Signed-off-by: Kristoffer Haugsbakk Signed-off-by: Junio C Hamano

Merge branch 'bc/doc-adoc-not-txt'

2025-02-15T01:53:47Z

All the documentation .txt files have been renamed to .adoc to help content aware editors. * bc/doc-adoc-not-txt: Remove obsolete ".txt" extensions for AsciiDoc files doc: use .adoc extension for AsciiDoc files gitattributes: mark AsciiDoc files as LF-only editorconfig: add .adoc extension doc: update gitignore for .adoc extension

doc: use .adoc extension for AsciiDoc files

2025-01-21T20:56:06Z

We presently use the ".txt" extension for our AsciiDoc files. While not wrong, most editors do not associate this extension with AsciiDoc, meaning that contributors don't get automatic editor functionality that could be useful, such as syntax highlighting and prose linting. It is much more common to use the ".adoc" extension for AsciiDoc files, since this helps editors automatically detect files and also allows various forges to provide rich (HTML-like) rendering. Let's do that here, renaming all of the files and updating the includes where relevant. Adjust the various build scripts and makefiles to use the new extension as well. Note that this should not result in any user-visible changes to the documentation. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano