{"thread":{"id":"64630","subject":"[PATCH] doc: flock of small fixes to various documentation files","startedAt":"2025-12-15T20:23:52Z","lastAt":"2025-12-22T04:42:40Z","messageCount":12,"participants":["Jean-Noël Avila via GitGitGadget","Kristoffer Haugsbakk","Jean-Noël Avila","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"532200","messageId":"pull.2016.git.1765830229824.gitgitgadget@gmail.com","threadId":"64630","inReplyTo":null,"subject":"[PATCH] doc: flock of small fixes to various documentation files","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-12-15T20:23:49Z","receivedAt":"2025-12-15T20:23:52Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nWhile translating the Git documentation into French, I noticed several small\nissues in various files. This commit addresses these issues to improve the\noverall quality and consistency of the documentation.\n\n * enforce consistent imperative mood in option descriptions\n * lighten wording in several places for clarity\n * add missing parameters\n * fix minor asciidoc markup issues\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n    doc: flock of small fixes to various documentation files\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2016%2Fjnavila%2Fdoc_small_fixups-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2016/jnavila/doc_small_fixups-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/2016\n\n Documentation/git-checkout.adoc   |  2 +-\n Documentation/git-rebase.adoc     |  2 +-\n Documentation/git-repack.adoc     |  6 +++---\n Documentation/git-send-email.adoc | 26 +++++++++++++-------------\n Documentation/git-worktree.adoc   |  2 +-\n 5 files changed, 19 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 6f281b298e..43ccf47cf6 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -509,7 +509,7 @@ ARGUMENT DISAMBIGUATION\n -----------------------\n \n When you run `git checkout <something>`, Git tries to guess whether\n-`<something>` is intended to be a branch, a commit, or a set of file(s),\n+_<something>_ is intended to be a branch, a commit, or a set of file(s),\n and then either switches to that branch or commit, or restores the\n specified files.\n \ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex 9742833ebe..e177808004 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -87,7 +87,7 @@ of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still\n point to that commit at the end of the rebase if other commands that change\n `ORIG_HEAD` (like `git reset`) are used during the rebase. The previous branch\n tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`,\n-see linkgit:gitrevisions[7].\n+see linkgit:gitrevisions[7]).\n \n TRANSPLANTING A TOPIC BRANCH WITH --ONTO\n ----------------------------------------\ndiff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc\nindex d12c4985f6..673ce91083 100644\n--- a/Documentation/git-repack.adoc\n+++ b/Documentation/git-repack.adoc\n@@ -77,14 +77,14 @@ to the new separate pack will be written.\n \tOnly useful with `--cruft -d`.\n \n --max-cruft-size=<n>::\n-\tOverrides `--max-pack-size` for cruft packs. Inherits the value of\n+\tOverride `--max-pack-size` for cruft packs. Inherits the value of\n \t`--max-pack-size` (if any) by default. See the documentation for\n \t`--max-pack-size` for more details.\n \n --combine-cruft-below-size=<n>::\n \tWhen generating cruft packs without pruning, only repack\n-\texisting cruft packs whose size is strictly less than `<n>`,\n-\twhere `<n>` represents a number of bytes, which can optionally\n+\texisting cruft packs whose size is strictly less than `<n>`\n+\tbytes, which can optionally\n \tbe suffixed with \"k\", \"m\", or \"g\". Cruft packs whose size is\n \tgreater than or equal to `<n>` are left as-is and not repacked.\n \tUseful when you want to avoid repacking large cruft pack(s) in\ndiff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc\nindex 263b977353..cdaf421cda 100644\n--- a/Documentation/git-send-email.adoc\n+++ b/Documentation/git-send-email.adoc\n@@ -208,7 +208,7 @@ Sending\n \tfor your own case. Default is the value of `sendemail.smtpEncryption`.\n \n --smtp-domain=<FQDN>::\n-\tSpecifies the Fully Qualified Domain Name (FQDN) used in the\n+\tSpecify the Fully Qualified Domain Name (FQDN) used in the\n \tHELO/EHLO command to the SMTP server.  Some servers require the\n \tFQDN to match your IP address.  If not set, `git send-email` attempts\n \tto determine your FQDN automatically.  Default is the value of\n@@ -245,7 +245,7 @@ a password is obtained using linkgit:git-credential[1].\n \tDisable SMTP authentication. Short hand for `--smtp-auth=none`.\n \n --smtp-server=<host>::\n-\tIf set, specifies the outgoing SMTP server to use (e.g.\n+\tSpecify the outgoing SMTP server to use (e.g.\n \t`smtp.example.com` or a raw IP address).  If unspecified, and if\n \t`--sendmail-cmd` is also unspecified, the default is to search\n \tfor `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a\n@@ -258,7 +258,7 @@ command names.  For those use cases, consider using `--sendmail-cmd`\n instead.\n \n --smtp-server-port=<port>::\n-\tSpecifies a port different from the default port (SMTP\n+\tSpecify a port different from the default port (SMTP\n \tservers typically listen to smtp port 25, but may also listen to\n \tsubmission port 587, or the common SSL smtp port 465);\n \tsymbolic port names (e.g. `submission` instead of 587)\n@@ -266,7 +266,7 @@ instead.\n \t`sendemail.smtpServerPort` configuration variable.\n \n --smtp-server-option=<option>::\n-\tIf set, specifies the outgoing SMTP server option to use.\n+\tSpecify the outgoing SMTP server option to use.\n \tDefault value can be specified by the `sendemail.smtpServerOption`\n \tconfiguration option.\n +\n@@ -277,7 +277,7 @@ must be used for each option.\n --smtp-ssl::\n \tLegacy alias for `--smtp-encryption ssl`.\n \n---smtp-ssl-cert-path::\n+--smtp-ssl-cert-path <path>::\n \tPath to a store of trusted CA certificates for SMTP SSL/TLS\n \tcertificate validation (either a directory that has been processed\n \tby `c_rehash`, or a single file containing one or more PEM format\n@@ -347,11 +347,11 @@ Automating\n --no-to::\n --no-cc::\n --no-bcc::\n-\tClears any list of `To:`, `Cc:`, `Bcc:` addresses previously\n+\tClear any list of `To:`, `Cc:`, `Bcc:` addresses previously\n \tset via config.\n \n --no-identity::\n-\tClears the previously read value of `sendemail.identity` set\n+\tClear the previously read value of `sendemail.identity` set\n \tvia config, if any.\n \n --to-cmd=<command>::\n@@ -510,12 +510,12 @@ have been specified, in which case default to `compose`.\n \tCurrently, validation means the following:\n +\n --\n-\t\t*\tInvoke the sendemail-validate hook if present (see linkgit:githooks[5]).\n-\t\t*\tWarn of patches that contain lines longer than\n-\t\t\t998 characters unless a suitable transfer encoding\n-\t\t\t(`auto`, `base64`, or `quoted-printable`) is used;\n-\t\t\tthis is due to SMTP limits as described by\n-\t\t\thttps://www.ietf.org/rfc/rfc5322.txt.\n+* Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).\n+* Warn of patches that contain lines longer than\n+  998 characters unless a suitable transfer encoding\n+  (`auto`, `base64`, or `quoted-printable`) is used;\n+  this is due to SMTP limits as described by\n+  https://www.ietf.org/rfc/rfc5322.txt.\n --\n +\n Default is the value of `sendemail.validate`; if this is not set,\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex f272f79783..d74ad7b0e9 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -104,7 +104,7 @@ associated with a new unborn branch named _<branch>_ (after\n passed to the command. In the event the repository has a remote and\n `--guess-remote` is used, but no remote or local branches exist, then the\n command fails with a warning reminding the user to fetch from their remote\n-first (or override by using `-f/--force`).\n+first (or override by using `-f`/`--force`).\n \n `list`::\n \n\nbase-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b\n-- \ngitgitgadget\n"},{"id":"532217","messageId":"031d7b41-b6d3-450c-925e-cddaf2e7aa85@app.fastmail.com","threadId":"64630","inReplyTo":"pull.2016.git.1765830229824.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: flock of small fixes to various documentation files","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-15T22:50:20Z","receivedAt":"2025-12-15T22:51:14Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"> [PATCH] doc: flock of small fixes to various documentation files\n\nThis doesn’t say much.\n\nOn Mon, Dec 15, 2025, at 21:23, Jean-Noël Avila via GitGitGadget wrote:\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n>\n> While translating the Git documentation into French, I noticed several small\n> issues in various files. This commit addresses these issues to improve the\n> overall quality and consistency of the documentation.\n\nThis paragraph doesn’t add any relevant information. The following\nbullet list would be fine on its own. That it was stumbled upon while\ndoing X is typical below the three-dash/hyphen line info.\n\nAny code/doc change aims to improve the overall quality.\n\n>  * enforce consistent imperative mood in option descriptions\n>  * lighten wording in several places for clarity\n>  * add missing parameters\n>  * fix minor asciidoc markup issues\n\nI also use bullet-list commits sometimes. (And it’s cousin: “Let’s\nalso...”) But this commit does two things:\n\n• Change prose: imperative mood, lighten wording\n• Fix mistakes source formatting:\n  • Correct markup\n  • Add missing paren\n  • Split up markup of options: `-f`/`--force`\n  • Weird indent\n\nCould this fruitfully be split into at least two commits?\n\nI just think these are two different categories.\n\nIs that just an academic concern? Well, in my experience it is very\npleasant to pickaxe through a snippet of text, stumble upon clearly\nmarked commits like\n\n• Use USA spelling\n• Fix articles (the/a/an)\n• *: typos\n\nand just race past them. Because I am looking for the original\nmotivation for some phrasing (say), typos and missing articles and all,\nand these commits are simple to bunny hop. But here, fixing a missing\nparentheses is mixed together with\n\n    Replace: less than `<n>`, where `<n>` represents a number of bytes,\n    With: less than `<n>` bytes\n\nAnd now I might have to pause and think which implicated change this is\nabout for my purposes; a subjective-but-good change or a\nfix-objective-mistake change. Because that matters when I want to know\nwhy the text is phrased in a certain way.\n\n>\n> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n> ---\n>     doc: flock of small fixes to various documentation files\n>\n> Published-As:\n> https://github.com/gitgitgadget/git/releases/tag/pr-2016%2Fjnavila%2Fdoc_small_fixups-v1\n> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git\n> pr-2016/jnavila/doc_small_fixups-v1\n> Pull-Request: https://github.com/gitgitgadget/git/pull/2016\n>\n>  Documentation/git-checkout.adoc   |  2 +-\n>  Documentation/git-rebase.adoc     |  2 +-\n>  Documentation/git-repack.adoc     |  6 +++---\n>  Documentation/git-send-email.adoc | 26 +++++++++++++-------------\n>  Documentation/git-worktree.adoc   |  2 +-\n>  5 files changed, 19 insertions(+), 19 deletions(-)\n>\n> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n> index 6f281b298e..43ccf47cf6 100644\n> --- a/Documentation/git-checkout.adoc\n> +++ b/Documentation/git-checkout.adoc\n> @@ -509,7 +509,7 @@ ARGUMENT DISAMBIGUATION\n>  -----------------------\n>\n>  When you run `git checkout <something>`, Git tries to guess whether\n> -`<something>` is intended to be a branch, a commit, or a set of file(s),\n> +_<something>_ is intended to be a branch, a commit, or a set of file(s),\n>  and then either switches to that branch or commit, or restores the\n>  specified files.\n\nCorrect markup since this is a `synopsis` document. Good.\n\n>\n> diff --git a/Documentation/git-rebase.adoc\n> b/Documentation/git-rebase.adoc\n> index 9742833ebe..e177808004 100644\n> --- a/Documentation/git-rebase.adoc\n> +++ b/Documentation/git-rebase.adoc\n> @@ -87,7 +87,7 @@ of the to-be-rebased branch. However, `ORIG_HEAD` is\n> not guaranteed to still\n>  point to that commit at the end of the rebase if other commands that\n> change\n>  `ORIG_HEAD` (like `git reset`) are used during the rebase. The\n> previous branch\n>  tip, however, is accessible using the reflog of the current branch\n> (i.e. `@{1}`,\n> -see linkgit:gitrevisions[7].\n> +see linkgit:gitrevisions[7]).\n\nAdd missing end-paren. Good.\n\n*Could* maybe also replace the comma with a semicolon?\n\n    i.e. `@{1}`; see ...\n\n>\n>  TRANSPLANTING A TOPIC BRANCH WITH --ONTO\n>  ----------------------------------------\n> diff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc\n> index d12c4985f6..673ce91083 100644\n> --- a/Documentation/git-repack.adoc\n> +++ b/Documentation/git-repack.adoc\n> @@ -77,14 +77,14 @@ to the new separate pack will be written.\n>  \tOnly useful with `--cruft -d`.\n>\n>  --max-cruft-size=<n>::\n> -\tOverrides `--max-pack-size` for cruft packs. Inherits the value of\n> +\tOverride `--max-pack-size` for cruft packs. Inherits the value of\n>  \t`--max-pack-size` (if any) by default. See the documentation for\n>  \t`--max-pack-size` for more details.\n\nImperative mood.\n\n>\n>  --combine-cruft-below-size=<n>::\n>  \tWhen generating cruft packs without pruning, only repack\n> -\texisting cruft packs whose size is strictly less than `<n>`,\n> -\twhere `<n>` represents a number of bytes, which can optionally\n> +\texisting cruft packs whose size is strictly less than `<n>`\n> +\tbytes, which can optionally\n>  \tbe suffixed with \"k\", \"m\", or \"g\". Cruft packs whose size is\n>  \tgreater than or equal to `<n>` are left as-is and not repacked.\n>  \tUseful when you want to avoid repacking large cruft pack(s) in\n\nHere drop a wordy “where `<n>` represents a number of bytes” clause in\nfavor of just “<n> bytes”.\n\n> diff --git a/Documentation/git-send-email.adoc\n> b/Documentation/git-send-email.adoc\n> index 263b977353..cdaf421cda 100644\n> --- a/Documentation/git-send-email.adoc\n> +++ b/Documentation/git-send-email.adoc\n> @@ -208,7 +208,7 @@ Sending\n>  \tfor your own case. Default is the value of `sendemail.smtpEncryption`.\n>\n>  --smtp-domain=<FQDN>::\n> -\tSpecifies the Fully Qualified Domain Name (FQDN) used in the\n> +\tSpecify the Fully Qualified Domain Name (FQDN) used in the\n>  \tHELO/EHLO command to the SMTP server.  Some servers require the\n>  \tFQDN to match your IP address.  If not set, `git send-email` attempts\n>  \tto determine your FQDN automatically.  Default is the value of\n\nImperative mood.\n\n> @@ -245,7 +245,7 @@ a password is obtained using linkgit:git-credential[1].\n>  \tDisable SMTP authentication. Short hand for `--smtp-auth=none`.\n>\n>  --smtp-server=<host>::\n> -\tIf set, specifies the outgoing SMTP server to use (e.g.\n> +\tSpecify the outgoing SMTP server to use (e.g.\n>  \t`smtp.example.com` or a raw IP address).  If unspecified, and if\n>  \t`--sendmail-cmd` is also unspecified, the default is to search\n>  \tfor `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a\n> @@ -258,7 +258,7 @@ command names.  For those use cases, consider using\n\nImperative mood and drop “If set”.\n\nWe can see in the resulting file that many commands use this “Specify”\nstart. Not a mix of “Specify” and “If set, ...”.\n\nAlthough see also the positive/negative options that start with “If this\nis set,”. Maybe unrelated to this change, but maybe they could be\nrephrased with less “if set” ceremony. Relevant:\n\nhttps://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n\n> `--sendmail-cmd`\n>  instead.\n>\n>  --smtp-server-port=<port>::\n> -\tSpecifies a port different from the default port (SMTP\n> +\tSpecify a port different from the default port (SMTP\n\nSame.\n\n>  \tservers typically listen to smtp port 25, but may also listen to\n>  \tsubmission port 587, or the common SSL smtp port 465);\n>  \tsymbolic port names (e.g. `submission` instead of 587)\n> @@ -266,7 +266,7 @@ instead.\n>  \t`sendemail.smtpServerPort` configuration variable.\n>\n>  --smtp-server-option=<option>::\n> -\tIf set, specifies the outgoing SMTP server option to use.\n> +\tSpecify the outgoing SMTP server option to use.\n\nSame.\n\n>  \tDefault value can be specified by the `sendemail.smtpServerOption`\n>  \tconfiguration option.\n>  +\n> @@ -277,7 +277,7 @@ must be used for each option.\n>  --smtp-ssl::\n>  \tLegacy alias for `--smtp-encryption ssl`.\n>\n> ---smtp-ssl-cert-path::\n> +--smtp-ssl-cert-path <path>::\n>  \tPath to a store of trusted CA certificates for SMTP SSL/TLS\n>  \tcertificate validation (either a directory that has been processed\n>  \tby `c_rehash`, or a single file containing one or more PEM format\n\nAdd parameter. Makes sense.\n\n> @@ -347,11 +347,11 @@ Automating\n>  --no-to::\n>  --no-cc::\n>  --no-bcc::\n> -\tClears any list of `To:`, `Cc:`, `Bcc:` addresses previously\n> +\tClear any list of `To:`, `Cc:`, `Bcc:` addresses previously\n>  \tset via config.\n\nImperative mood.\n\n>\n>  --no-identity::\n> -\tClears the previously read value of `sendemail.identity` set\n> +\tClear the previously read value of `sendemail.identity` set\n\nDitto. And these two look like the only relevant `--no` options. So this\nlooks consistent.\n\n>  \tvia config, if any.\n>\n>  --to-cmd=<command>::\n> @@ -510,12 +510,12 @@ have been specified, in which case default to `compose`.\n>  \tCurrently, validation means the following:\n>  +\n>  --\n> -\t\t*\tInvoke the sendemail-validate hook if present (see linkgit:githooks[5]).\n> -\t\t*\tWarn of patches that contain lines longer than\n> -\t\t\t998 characters unless a suitable transfer encoding\n> -\t\t\t(`auto`, `base64`, or `quoted-printable`) is used;\n> -\t\t\tthis is due to SMTP limits as described by\n> -\t\t\thttps://www.ietf.org/rfc/rfc5322.txt.\n> +* Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).\n> +* Warn of patches that contain lines longer than\n> +  998 characters unless a suitable transfer encoding\n> +  (`auto`, `base64`, or `quoted-printable`) is used;\n> +  this is due to SMTP limits as described by\n> +  https://www.ietf.org/rfc/rfc5322.txt.\n>  --\n\nNon-functional change it seems. This looks better in the source. 2–3\ntabs were not needed here.\n\n>  +\n>  Default is the value of `sendemail.validate`; if this is not set,\n> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n> index f272f79783..d74ad7b0e9 100644\n> --- a/Documentation/git-worktree.adoc\n> +++ b/Documentation/git-worktree.adoc\n> @@ -104,7 +104,7 @@ associated with a new unborn branch named _<branch>_ (after\n>  passed to the command. In the event the repository has a remote and\n>  `--guess-remote` is used, but no remote or local branches exist, then the\n>  command fails with a warning reminding the user to fetch from their remote\n> -first (or override by using `-f/--force`).\n> +first (or override by using `-f`/`--force`).\n\nFix inline-verbatim since you are quoting two options/switches. So the\n`/` does not go inside the (`). Good.\n\n>\n>  `list`::\n>\n>\n> base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b\n> --\n> gitgitgadget\n\n`doc-diff` also looks good.\n"},{"id":"532350","messageId":"876ee36d-610b-4df6-9297-96b38f106c6c@scantech.com","threadId":"64630","inReplyTo":"031d7b41-b6d3-450c-925e-cddaf2e7aa85@app.fastmail.com","subject":"Re: [PATCH] doc: flock of small fixes to various documentation files","fromName":"Jean-Noël Avila","fromEmail":"jean-noel.avila@scantech.com","sentAt":"2025-12-17T13:45:38Z","receivedAt":"2025-12-17T14:10:33Z","isPatch":true,"sender":{"key":"jean-noel.avila@scantech.com","avatar":null},"body":"Le 15/12/2025 à 23:50, Kristoffer Haugsbakk a écrit :\n>> [PATCH] doc: flock of small fixes to various documentation files\n> \n> This doesn’t say much.\n> \n\nYes, this is a set of disparate changes, except that they all relate to\ndocumentation.\n\n> On Mon, Dec 15, 2025, at 21:23, Jean-Noël Avila via GitGitGadget wrote:\n>> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n>>\n>> While translating the Git documentation into French, I noticed several small\n>> issues in various files. This commit addresses these issues to improve the\n>> overall quality and consistency of the documentation.\n> \n> This paragraph doesn’t add any relevant information. The following\n> bullet list would be fine on its own. That it was stumbled upon while\n> doing X is typical below the three-dash/hyphen line info.\n\nTrue, will remove.\n\n> \n> Any code/doc change aims to improve the overall quality.\n> \n>>  * enforce consistent imperative mood in option descriptions\n>>  * lighten wording in several places for clarity\n>>  * add missing parameters\n>>  * fix minor asciidoc markup issues\n> \n> I also use bullet-list commits sometimes. (And it’s cousin: “Let’s\n> also...”) But this commit does two things:\n> \n> • Change prose: imperative mood, lighten wording\n> • Fix mistakes source formatting:\n>   • Correct markup\n>   • Add missing paren\n>   • Split up markup of options: `-f`/`--force`\n>   • Weird indent\n> \n> Could this fruitfully be split into at least two commits?\n> \n> I just think these are two different categories.\n\nFor me these changes are so straightforward that splitting/grouping\nseemed overkill. But, I understand your point. Style vs. pure formatting\nis a good approach, even if here the style is not about the approach to\nwriting the documentation.\n\n> \n> Is that just an academic concern? Well, in my experience it is very\n> pleasant to pickaxe through a snippet of text, stumble upon clearly\n> marked commits like\n> \n> • Use USA spelling\n> • Fix articles (the/a/an)\n> • *: typos\n> \n> and just race past them. Because I am looking for the original\n> motivation for some phrasing (say), typos and missing articles and all,\n> and these commits are simple to bunny hop. But here, fixing a missing\n> parentheses is mixed together with\n> \n>     Replace: less than `<n>`, where `<n>` represents a number of bytes,\n>     With: less than `<n>` bytes\n> \n> And now I might have to pause and think which implicated change this is\n> about for my purposes; a subjective-but-good change or a\n> fix-objective-mistake change. Because that matters when I want to know\n> why the text is phrased in a certain way.\n> \n\nOK, will split in two.\n\n>>\n>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n>> ---\n>>     doc: flock of small fixes to various documentation files\n>>\n>> Published-As:\n>> https://github.com/gitgitgadget/git/releases/tag/pr-2016%2Fjnavila%2Fdoc_small_fixups-v1\n>> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git\n>> pr-2016/jnavila/doc_small_fixups-v1\n>> Pull-Request: https://github.com/gitgitgadget/git/pull/2016\n>>\n>>  Documentation/git-checkout.adoc   |  2 +-\n>>  Documentation/git-rebase.adoc     |  2 +-\n>>  Documentation/git-repack.adoc     |  6 +++---\n>>  Documentation/git-send-email.adoc | 26 +++++++++++++-------------\n>>  Documentation/git-worktree.adoc   |  2 +-\n>>  5 files changed, 19 insertions(+), 19 deletions(-)\n>>\n>> diff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\n>> index 6f281b298e..43ccf47cf6 100644\n>> --- a/Documentation/git-checkout.adoc\n>> +++ b/Documentation/git-checkout.adoc\n>> @@ -509,7 +509,7 @@ ARGUMENT DISAMBIGUATION\n>>  -----------------------\n>>\n>>  When you run `git checkout <something>`, Git tries to guess whether\n>> -`<something>` is intended to be a branch, a commit, or a set of file(s),\n>> +_<something>_ is intended to be a branch, a commit, or a set of file(s),\n>>  and then either switches to that branch or commit, or restores the\n>>  specified files.\n> \n> Correct markup since this is a `synopsis` document. Good.\n> \n>>\n>> diff --git a/Documentation/git-rebase.adoc\n>> b/Documentation/git-rebase.adoc\n>> index 9742833ebe..e177808004 100644\n>> --- a/Documentation/git-rebase.adoc\n>> +++ b/Documentation/git-rebase.adoc\n>> @@ -87,7 +87,7 @@ of the to-be-rebased branch. However, `ORIG_HEAD` is\n>> not guaranteed to still\n>>  point to that commit at the end of the rebase if other commands that\n>> change\n>>  `ORIG_HEAD` (like `git reset`) are used during the rebase. The\n>> previous branch\n>>  tip, however, is accessible using the reflog of the current branch\n>> (i.e. `@{1}`,\n>> -see linkgit:gitrevisions[7].\n>> +see linkgit:gitrevisions[7]).\n> \n> Add missing end-paren. Good.\n> \n> *Could* maybe also replace the comma with a semicolon?\n> \n>     i.e. `@{1}`; see ...\n> \n>>\n>>  TRANSPLANTING A TOPIC BRANCH WITH --ONTO\n>>  ----------------------------------------\n>> diff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc\n>> index d12c4985f6..673ce91083 100644\n>> --- a/Documentation/git-repack.adoc\n>> +++ b/Documentation/git-repack.adoc\n>> @@ -77,14 +77,14 @@ to the new separate pack will be written.\n>>  \tOnly useful with `--cruft -d`.\n>>\n>>  --max-cruft-size=<n>::\n>> -\tOverrides `--max-pack-size` for cruft packs. Inherits the value of\n>> +\tOverride `--max-pack-size` for cruft packs. Inherits the value of\n>>  \t`--max-pack-size` (if any) by default. See the documentation for\n>>  \t`--max-pack-size` for more details.\n> \n> Imperative mood.\n> \n>>\n>>  --combine-cruft-below-size=<n>::\n>>  \tWhen generating cruft packs without pruning, only repack\n>> -\texisting cruft packs whose size is strictly less than `<n>`,\n>> -\twhere `<n>` represents a number of bytes, which can optionally\n>> +\texisting cruft packs whose size is strictly less than `<n>`\n>> +\tbytes, which can optionally\n>>  \tbe suffixed with \"k\", \"m\", or \"g\". Cruft packs whose size is\n>>  \tgreater than or equal to `<n>` are left as-is and not repacked.\n>>  \tUseful when you want to avoid repacking large cruft pack(s) in\n> \n> Here drop a wordy “where `<n>` represents a number of bytes” clause in\n> favor of just “<n> bytes”.\n> \n>> diff --git a/Documentation/git-send-email.adoc\n>> b/Documentation/git-send-email.adoc\n>> index 263b977353..cdaf421cda 100644\n>> --- a/Documentation/git-send-email.adoc\n>> +++ b/Documentation/git-send-email.adoc\n>> @@ -208,7 +208,7 @@ Sending\n>>  \tfor your own case. Default is the value of `sendemail.smtpEncryption`.\n>>\n>>  --smtp-domain=<FQDN>::\n>> -\tSpecifies the Fully Qualified Domain Name (FQDN) used in the\n>> +\tSpecify the Fully Qualified Domain Name (FQDN) used in the\n>>  \tHELO/EHLO command to the SMTP server.  Some servers require the\n>>  \tFQDN to match your IP address.  If not set, `git send-email` attempts\n>>  \tto determine your FQDN automatically.  Default is the value of\n> \n> Imperative mood.\n> \n>> @@ -245,7 +245,7 @@ a password is obtained using linkgit:git-credential[1].\n>>  \tDisable SMTP authentication. Short hand for `--smtp-auth=none`.\n>>\n>>  --smtp-server=<host>::\n>> -\tIf set, specifies the outgoing SMTP server to use (e.g.\n>> +\tSpecify the outgoing SMTP server to use (e.g.\n>>  \t`smtp.example.com` or a raw IP address).  If unspecified, and if\n>>  \t`--sendmail-cmd` is also unspecified, the default is to search\n>>  \tfor `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a\n>> @@ -258,7 +258,7 @@ command names.  For those use cases, consider using\n> \n> Imperative mood and drop “If set”.\n> \n> We can see in the resulting file that many commands use this “Specify”\n> start. Not a mix of “Specify” and “If set, ...”.\n> \n> Although see also the positive/negative options that start with “If this\n> is set,”. Maybe unrelated to this change, but maybe they could be\n> rephrased with less “if set” ceremony. Relevant:\n> \n> https://lore.kernel.org/git/xmqqcyct1mtq.fsf@gitster.g/\n> \n\nNot the purpose of this commit, but maybe, it would make sense to stress\nout that the first sentence for explaining an option should describe\nbluntly its positive action expressed in imperative mood, with no\nceremony. After this first sentence, the negative equivalient, more\ncontext, more precision or use cases can be described.\n\n>> `--sendmail-cmd`\n>>  instead.\n>>\n>>  --smtp-server-port=<port>::\n>> -\tSpecifies a port different from the default port (SMTP\n>> +\tSpecify a port different from the default port (SMTP\n> \n> Same.\n> \n>>  \tservers typically listen to smtp port 25, but may also listen to\n>>  \tsubmission port 587, or the common SSL smtp port 465);\n>>  \tsymbolic port names (e.g. `submission` instead of 587)\n>> @@ -266,7 +266,7 @@ instead.\n>>  \t`sendemail.smtpServerPort` configuration variable.\n>>\n>>  --smtp-server-option=<option>::\n>> -\tIf set, specifies the outgoing SMTP server option to use.\n>> +\tSpecify the outgoing SMTP server option to use.\n> \n> Same.\n> \n>>  \tDefault value can be specified by the `sendemail.smtpServerOption`\n>>  \tconfiguration option.\n>>  +\n>> @@ -277,7 +277,7 @@ must be used for each option.\n>>  --smtp-ssl::\n>>  \tLegacy alias for `--smtp-encryption ssl`.\n>>\n>> ---smtp-ssl-cert-path::\n>> +--smtp-ssl-cert-path <path>::\n>>  \tPath to a store of trusted CA certificates for SMTP SSL/TLS\n>>  \tcertificate validation (either a directory that has been processed\n>>  \tby `c_rehash`, or a single file containing one or more PEM format\n> \n> Add parameter. Makes sense.\n> \n>> @@ -347,11 +347,11 @@ Automating\n>>  --no-to::\n>>  --no-cc::\n>>  --no-bcc::\n>> -\tClears any list of `To:`, `Cc:`, `Bcc:` addresses previously\n>> +\tClear any list of `To:`, `Cc:`, `Bcc:` addresses previously\n>>  \tset via config.\n> \n> Imperative mood.\n> \n>>\n>>  --no-identity::\n>> -\tClears the previously read value of `sendemail.identity` set\n>> +\tClear the previously read value of `sendemail.identity` set\n> \n> Ditto. And these two look like the only relevant `--no` options. So this\n> looks consistent.\n> \n>>  \tvia config, if any.\n>>\n>>  --to-cmd=<command>::\n>> @@ -510,12 +510,12 @@ have been specified, in which case default to `compose`.\n>>  \tCurrently, validation means the following:\n>>  +\n>>  --\n>> -\t\t*\tInvoke the sendemail-validate hook if present (see linkgit:githooks[5]).\n>> -\t\t*\tWarn of patches that contain lines longer than\n>> -\t\t\t998 characters unless a suitable transfer encoding\n>> -\t\t\t(`auto`, `base64`, or `quoted-printable`) is used;\n>> -\t\t\tthis is due to SMTP limits as described by\n>> -\t\t\thttps://www.ietf.org/rfc/rfc5322.txt.\n>> +* Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).\n>> +* Warn of patches that contain lines longer than\n>> +  998 characters unless a suitable transfer encoding\n>> +  (`auto`, `base64`, or `quoted-printable`) is used;\n>> +  this is due to SMTP limits as described by\n>> +  https://www.ietf.org/rfc/rfc5322.txt.\n>>  --\n> \n> Non-functional change it seems. This looks better in the source. 2–3\n> tabs were not needed here.\n> \n\nIt turns out the tool to translate the manpages Po4a also dislikes (i.e.\ndoes not interpret correctly) the tabs.\n\n>>  +\n>>  Default is the value of `sendemail.validate`; if this is not set,\n>> diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\n>> index f272f79783..d74ad7b0e9 100644\n>> --- a/Documentation/git-worktree.adoc\n>> +++ b/Documentation/git-worktree.adoc\n>> @@ -104,7 +104,7 @@ associated with a new unborn branch named _<branch>_ (after\n>>  passed to the command. In the event the repository has a remote and\n>>  `--guess-remote` is used, but no remote or local branches exist, then the\n>>  command fails with a warning reminding the user to fetch from their remote\n>> -first (or override by using `-f/--force`).\n>> +first (or override by using `-f`/`--force`).\n> \n> Fix inline-verbatim since you are quoting two options/switches. So the\n> `/` does not go inside the (`). Good.\n> \n>>\n>>  `list`::\n>>\n>>\n>> base-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b\n>> --\n>> gitgitgadget\n> \n> `doc-diff` also looks good.\n> \n\n\nbegin:vcard\nfn;quoted-printable:Jean-No=C3=ABl Avila\nn;quoted-printable:Avila;Jean-No=C3=ABl\norg:Scantech S.A.\nadr;quoted-printable:Savoie Technolac BP 244;;B=C3=A2timent Androm=C3=A8de - 108 Avenue du Lac L=C3=A9man ; LA MOTTE SERVOLEX;;73290;France\nemail;internet:jean-noel.avila@scantech.com\ntitle:Embedded systems manager\ntel;work:+33 479 25 54 50\ntel;cell:+33 633 04 64 18\nx-mozilla-html:FALSE\nurl:http://www.scantech.com\nversion:2.1\nend:vcard\n\n"},{"id":"532442","messageId":"843711d8-00c5-4747-972e-e705e14d85b4@app.fastmail.com","threadId":"64630","inReplyTo":"876ee36d-610b-4df6-9297-96b38f106c6c@scantech.com","subject":"Re: [PATCH] doc: flock of small fixes to various documentation files","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-18T08:05:44Z","receivedAt":"2025-12-18T08:06:05Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Wed, Dec 17, 2025, at 14:45, Jean-Noël Avila wrote:\n> Le 15/12/2025 à 23:50, Kristoffer Haugsbakk a écrit :\n>>[snip]\n>>\n>> Could this fruitfully be split into at least two commits?\n>>\n>> I just think these are two different categories.\n>\n> For me these changes are so straightforward that splitting/grouping\n> seemed overkill. But, I understand your point. Style vs. pure formatting\n> is a good approach, even if here the style is not about the approach to\n> writing the documentation.\n>\n>>\n>> Is that just an academic concern? Well, in my experience it is very\n>> pleasant to pickaxe through a snippet of text, stumble upon clearly\n>> marked commits like\n>>\n>> • Use USA spelling\n>> • Fix articles (the/a/an)\n>> • *: typos\n>>\n>> and just race past them. Because I am looking for the original\n>> motivation for some phrasing (say), typos and missing articles and all,\n>> and these commits are simple to bunny hop. But here, fixing a missing\n>> parentheses is mixed together with\n>>\n>>     Replace: less than `<n>`, where `<n>` represents a number of bytes,\n>>     With: less than `<n>` bytes\n>>\n>> And now I might have to pause and think which implicated change this is\n>> about for my purposes; a subjective-but-good change or a\n>> fix-objective-mistake change. Because that matters when I want to know\n>> why the text is phrased in a certain way.\n>>\n>\n> OK, will split in two.\n\nThanks. Your consideration of this point is enough for me. Appreciated.\n\n>>[snip]\n>>\n>\n> Not the purpose of this commit, but maybe, it would make sense to stress\n> out that the first sentence for explaining an option should describe\n> bluntly its positive action expressed in imperative mood, with no\n> ceremony. After this first sentence, the negative equivalient, more\n> context, more precision or use cases can be described.\n\nThat sounds excellent.\n\n>[snip]\n"},{"id":"532533","messageId":"9dfb1888-aca9-4ba9-bfca-49dbd1074025@app.fastmail.com","threadId":"64630","inReplyTo":"843711d8-00c5-4747-972e-e705e14d85b4@app.fastmail.com","subject":"Re: [PATCH] doc: flock of small fixes to various documentation files","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-19T09:34:05Z","receivedAt":"2025-12-19T09:34:27Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Thu, Dec 18, 2025, at 09:05, Kristoffer Haugsbakk wrote:\n>>[snip]\n\nThis is in `next` now anyway.\n"},{"id":"532565","messageId":"pull.2016.v2.git.1766170456.gitgitgadget@gmail.com","threadId":"64630","inReplyTo":"pull.2016.git.1765830229824.gitgitgadget@gmail.com","subject":"[PATCH v2 0/2] doc: flock of small fixes to various documentation files","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-12-19T18:54:14Z","receivedAt":"2025-12-19T18:54:19Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"This second version only splits the changes in two commits, one addressing\nasciidoc markup, the other fixing basic style issues.\n\nJean-Noël Avila (2):\n  doc: fix asciidoc markup issues in several files\n  doc: correct minor wording issues\n\n Documentation/git-checkout.adoc   |  2 +-\n Documentation/git-rebase.adoc     |  2 +-\n Documentation/git-repack.adoc     |  6 +++---\n Documentation/git-send-email.adoc | 26 +++++++++++++-------------\n Documentation/git-worktree.adoc   |  2 +-\n 5 files changed, 19 insertions(+), 19 deletions(-)\n\n\nbase-commit: d8af7cadaa79d5837d73ec949e10b57dedb43e9b\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-2016%2Fjnavila%2Fdoc_small_fixups-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2016/jnavila/doc_small_fixups-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/2016\n\nRange-diff vs v1:\n\n -:  ---------- > 1:  31694ab9d3 doc: fix asciidoc markup issues in several files\n 1:  b88126ef60 ! 2:  a3a76d448a doc: flock of small fixes to various documentation files\n     @@ Metadata\n      Author: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Commit message ##\n     -    doc: flock of small fixes to various documentation files\n     +    doc: correct minor wording issues\n      \n     -    While translating the Git documentation into French, I noticed several small\n     -    issues in various files. This commit addresses these issues to improve the\n     -    overall quality and consistency of the documentation.\n     -\n     -     * enforce consistent imperative mood in option descriptions\n     -     * lighten wording in several places for clarity\n     -     * add missing parameters\n     -     * fix minor asciidoc markup issues\n     +    * use imperative mood for consistency in options descriptions\n     +    * add missing parenthesis\n     +    * reword verbose phrase in git-repack.adoc\n      \n          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n      \n     - ## Documentation/git-checkout.adoc ##\n     -@@ Documentation/git-checkout.adoc: ARGUMENT DISAMBIGUATION\n     - -----------------------\n     - \n     - When you run `git checkout <something>`, Git tries to guess whether\n     --`<something>` is intended to be a branch, a commit, or a set of file(s),\n     -+_<something>_ is intended to be a branch, a commit, or a set of file(s),\n     - and then either switches to that branch or commit, or restores the\n     - specified files.\n     - \n     -\n       ## Documentation/git-rebase.adoc ##\n      @@ Documentation/git-rebase.adoc: of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still\n       point to that commit at the end of the rebase if other commands that change\n     @@ Documentation/git-send-email.adoc: instead.\n       \tDefault value can be specified by the `sendemail.smtpServerOption`\n       \tconfiguration option.\n       +\n     -@@ Documentation/git-send-email.adoc: must be used for each option.\n     - --smtp-ssl::\n     - \tLegacy alias for `--smtp-encryption ssl`.\n     - \n     ----smtp-ssl-cert-path::\n     -+--smtp-ssl-cert-path <path>::\n     - \tPath to a store of trusted CA certificates for SMTP SSL/TLS\n     - \tcertificate validation (either a directory that has been processed\n     - \tby `c_rehash`, or a single file containing one or more PEM format\n      @@ Documentation/git-send-email.adoc: Automating\n       --no-to::\n       --no-cc::\n     @@ Documentation/git-send-email.adoc: Automating\n       \tvia config, if any.\n       \n       --to-cmd=<command>::\n     -@@ Documentation/git-send-email.adoc: have been specified, in which case default to `compose`.\n     - \tCurrently, validation means the following:\n     - +\n     - --\n     --\t\t*\tInvoke the sendemail-validate hook if present (see linkgit:githooks[5]).\n     --\t\t*\tWarn of patches that contain lines longer than\n     --\t\t\t998 characters unless a suitable transfer encoding\n     --\t\t\t(`auto`, `base64`, or `quoted-printable`) is used;\n     --\t\t\tthis is due to SMTP limits as described by\n     --\t\t\thttps://www.ietf.org/rfc/rfc5322.txt.\n     -+* Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).\n     -+* Warn of patches that contain lines longer than\n     -+  998 characters unless a suitable transfer encoding\n     -+  (`auto`, `base64`, or `quoted-printable`) is used;\n     -+  this is due to SMTP limits as described by\n     -+  https://www.ietf.org/rfc/rfc5322.txt.\n     - --\n     - +\n     - Default is the value of `sendemail.validate`; if this is not set,\n     -\n     - ## Documentation/git-worktree.adoc ##\n     -@@ Documentation/git-worktree.adoc: associated with a new unborn branch named _<branch>_ (after\n     - passed to the command. In the event the repository has a remote and\n     - `--guess-remote` is used, but no remote or local branches exist, then the\n     - command fails with a warning reminding the user to fetch from their remote\n     --first (or override by using `-f/--force`).\n     -+first (or override by using `-f`/`--force`).\n     - \n     - `list`::\n     - \n\n-- \ngitgitgadget\n"},{"id":"532566","messageId":"31694ab9d337d68294a5710d55fc4f7e1ff6f83a.1766170456.git.gitgitgadget@gmail.com","threadId":"64630","inReplyTo":"pull.2016.v2.git.1766170456.gitgitgadget@gmail.com","subject":"[PATCH v2 1/2] doc: fix asciidoc markup issues in several files","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-12-19T18:54:15Z","receivedAt":"2025-12-19T18:54:20Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n* fix incorrect use of backticks for markup in\n  git-checkout.adoc, git-worktree.adoc\n* switch tabs to spaces\tin git-send-email.adoc list items\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-checkout.adoc   |  2 +-\n Documentation/git-send-email.adoc | 14 +++++++-------\n Documentation/git-worktree.adoc   |  2 +-\n 3 files changed, 9 insertions(+), 9 deletions(-)\n\ndiff --git a/Documentation/git-checkout.adoc b/Documentation/git-checkout.adoc\nindex 6f281b298e..43ccf47cf6 100644\n--- a/Documentation/git-checkout.adoc\n+++ b/Documentation/git-checkout.adoc\n@@ -509,7 +509,7 @@ ARGUMENT DISAMBIGUATION\n -----------------------\n \n When you run `git checkout <something>`, Git tries to guess whether\n-`<something>` is intended to be a branch, a commit, or a set of file(s),\n+_<something>_ is intended to be a branch, a commit, or a set of file(s),\n and then either switches to that branch or commit, or restores the\n specified files.\n \ndiff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc\nindex 263b977353..caf9d693a3 100644\n--- a/Documentation/git-send-email.adoc\n+++ b/Documentation/git-send-email.adoc\n@@ -277,7 +277,7 @@ must be used for each option.\n --smtp-ssl::\n \tLegacy alias for `--smtp-encryption ssl`.\n \n---smtp-ssl-cert-path::\n+--smtp-ssl-cert-path <path>::\n \tPath to a store of trusted CA certificates for SMTP SSL/TLS\n \tcertificate validation (either a directory that has been processed\n \tby `c_rehash`, or a single file containing one or more PEM format\n@@ -510,12 +510,12 @@ have been specified, in which case default to `compose`.\n \tCurrently, validation means the following:\n +\n --\n-\t\t*\tInvoke the sendemail-validate hook if present (see linkgit:githooks[5]).\n-\t\t*\tWarn of patches that contain lines longer than\n-\t\t\t998 characters unless a suitable transfer encoding\n-\t\t\t(`auto`, `base64`, or `quoted-printable`) is used;\n-\t\t\tthis is due to SMTP limits as described by\n-\t\t\thttps://www.ietf.org/rfc/rfc5322.txt.\n+* Invoke the sendemail-validate hook if present (see linkgit:githooks[5]).\n+* Warn of patches that contain lines longer than\n+  998 characters unless a suitable transfer encoding\n+  (`auto`, `base64`, or `quoted-printable`) is used;\n+  this is due to SMTP limits as described by\n+  https://www.ietf.org/rfc/rfc5322.txt.\n --\n +\n Default is the value of `sendemail.validate`; if this is not set,\ndiff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc\nindex f272f79783..d74ad7b0e9 100644\n--- a/Documentation/git-worktree.adoc\n+++ b/Documentation/git-worktree.adoc\n@@ -104,7 +104,7 @@ associated with a new unborn branch named _<branch>_ (after\n passed to the command. In the event the repository has a remote and\n `--guess-remote` is used, but no remote or local branches exist, then the\n command fails with a warning reminding the user to fetch from their remote\n-first (or override by using `-f/--force`).\n+first (or override by using `-f`/`--force`).\n \n `list`::\n \n-- \ngitgitgadget\n\n"},{"id":"532567","messageId":"a3a76d448ac2871834576be6d79e4704aae11f35.1766170456.git.gitgitgadget@gmail.com","threadId":"64630","inReplyTo":"pull.2016.v2.git.1766170456.gitgitgadget@gmail.com","subject":"[PATCH v2 2/2] doc: correct minor wording issues","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-12-19T18:54:16Z","receivedAt":"2025-12-19T18:54:22Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n* use imperative mood for consistency in options descriptions\n* add missing parenthesis\n* reword verbose phrase in git-repack.adoc\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-rebase.adoc     |  2 +-\n Documentation/git-repack.adoc     |  6 +++---\n Documentation/git-send-email.adoc | 12 ++++++------\n 3 files changed, 10 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-rebase.adoc b/Documentation/git-rebase.adoc\nindex 9742833ebe..e177808004 100644\n--- a/Documentation/git-rebase.adoc\n+++ b/Documentation/git-rebase.adoc\n@@ -87,7 +87,7 @@ of the to-be-rebased branch. However, `ORIG_HEAD` is not guaranteed to still\n point to that commit at the end of the rebase if other commands that change\n `ORIG_HEAD` (like `git reset`) are used during the rebase. The previous branch\n tip, however, is accessible using the reflog of the current branch (i.e. `@{1}`,\n-see linkgit:gitrevisions[7].\n+see linkgit:gitrevisions[7]).\n \n TRANSPLANTING A TOPIC BRANCH WITH --ONTO\n ----------------------------------------\ndiff --git a/Documentation/git-repack.adoc b/Documentation/git-repack.adoc\nindex d12c4985f6..673ce91083 100644\n--- a/Documentation/git-repack.adoc\n+++ b/Documentation/git-repack.adoc\n@@ -77,14 +77,14 @@ to the new separate pack will be written.\n \tOnly useful with `--cruft -d`.\n \n --max-cruft-size=<n>::\n-\tOverrides `--max-pack-size` for cruft packs. Inherits the value of\n+\tOverride `--max-pack-size` for cruft packs. Inherits the value of\n \t`--max-pack-size` (if any) by default. See the documentation for\n \t`--max-pack-size` for more details.\n \n --combine-cruft-below-size=<n>::\n \tWhen generating cruft packs without pruning, only repack\n-\texisting cruft packs whose size is strictly less than `<n>`,\n-\twhere `<n>` represents a number of bytes, which can optionally\n+\texisting cruft packs whose size is strictly less than `<n>`\n+\tbytes, which can optionally\n \tbe suffixed with \"k\", \"m\", or \"g\". Cruft packs whose size is\n \tgreater than or equal to `<n>` are left as-is and not repacked.\n \tUseful when you want to avoid repacking large cruft pack(s) in\ndiff --git a/Documentation/git-send-email.adoc b/Documentation/git-send-email.adoc\nindex caf9d693a3..cdaf421cda 100644\n--- a/Documentation/git-send-email.adoc\n+++ b/Documentation/git-send-email.adoc\n@@ -208,7 +208,7 @@ Sending\n \tfor your own case. Default is the value of `sendemail.smtpEncryption`.\n \n --smtp-domain=<FQDN>::\n-\tSpecifies the Fully Qualified Domain Name (FQDN) used in the\n+\tSpecify the Fully Qualified Domain Name (FQDN) used in the\n \tHELO/EHLO command to the SMTP server.  Some servers require the\n \tFQDN to match your IP address.  If not set, `git send-email` attempts\n \tto determine your FQDN automatically.  Default is the value of\n@@ -245,7 +245,7 @@ a password is obtained using linkgit:git-credential[1].\n \tDisable SMTP authentication. Short hand for `--smtp-auth=none`.\n \n --smtp-server=<host>::\n-\tIf set, specifies the outgoing SMTP server to use (e.g.\n+\tSpecify the outgoing SMTP server to use (e.g.\n \t`smtp.example.com` or a raw IP address).  If unspecified, and if\n \t`--sendmail-cmd` is also unspecified, the default is to search\n \tfor `sendmail` in `/usr/sbin`, `/usr/lib` and `$PATH` if such a\n@@ -258,7 +258,7 @@ command names.  For those use cases, consider using `--sendmail-cmd`\n instead.\n \n --smtp-server-port=<port>::\n-\tSpecifies a port different from the default port (SMTP\n+\tSpecify a port different from the default port (SMTP\n \tservers typically listen to smtp port 25, but may also listen to\n \tsubmission port 587, or the common SSL smtp port 465);\n \tsymbolic port names (e.g. `submission` instead of 587)\n@@ -266,7 +266,7 @@ instead.\n \t`sendemail.smtpServerPort` configuration variable.\n \n --smtp-server-option=<option>::\n-\tIf set, specifies the outgoing SMTP server option to use.\n+\tSpecify the outgoing SMTP server option to use.\n \tDefault value can be specified by the `sendemail.smtpServerOption`\n \tconfiguration option.\n +\n@@ -347,11 +347,11 @@ Automating\n --no-to::\n --no-cc::\n --no-bcc::\n-\tClears any list of `To:`, `Cc:`, `Bcc:` addresses previously\n+\tClear any list of `To:`, `Cc:`, `Bcc:` addresses previously\n \tset via config.\n \n --no-identity::\n-\tClears the previously read value of `sendemail.identity` set\n+\tClear the previously read value of `sendemail.identity` set\n \tvia config, if any.\n \n --to-cmd=<command>::\n-- \ngitgitgadget\n"},{"id":"532607","messageId":"2e6759b7-73b3-4098-a0d8-2dfa1b7a3c44@app.fastmail.com","threadId":"64630","inReplyTo":"pull.2016.v2.git.1766170456.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/2] doc: flock of small fixes to various documentation files","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-21T17:12:59Z","receivedAt":"2025-12-21T17:13:21Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Fri, Dec 19, 2025, at 19:54, Jean-Noël Avila via GitGitGadget wrote:\n> This second version only splits the changes in two commits, one addressing\n> asciidoc markup, the other fixing basic style issues.\n>[snip]\n> Range-diff vs v1:\n>\n>  -:  ---------- > 1:  31694ab9d3 doc: fix asciidoc markup issues in \n> several files\n>  1:  b88126ef60 ! 2:  a3a76d448a doc: flock of small fixes to various \n> documentation files\n>      @@ Metadata\n>       Author: Jean-Noël Avila <jn.avila@free.fr>\n>      \n>        ## Commit message ##\n>      -    doc: flock of small fixes to various documentation files\n>      +    doc: correct minor wording issues\n>      \n>      -    While translating the Git documentation into French, I \n> noticed several small\n>      -    issues in various files. This commit addresses these issues \n> to improve the\n>      -    overall quality and consistency of the documentation.\n>      -\n>      -     * enforce consistent imperative mood in option descriptions\n>      -     * lighten wording in several places for clarity\n>      -     * add missing parameters\n>      -     * fix minor asciidoc markup issues\n>      +    * use imperative mood for consistency in options descriptions\n>      +    * add missing parenthesis\n>      +    * reword verbose phrase in git-repack.adoc\n>      \n>           Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n>      \n>      - ## Documentation/git-checkout.adoc ##\n>      -@@ Documentation/git-checkout.adoc: ARGUMENT DISAMBIGUATION\n>      - -----------------------\n>      - \n>      - When you run `git checkout <something>`, Git tries to guess \n> whether\n>      --`<something>` is intended to be a branch, a commit, or a set of \n> file(s),\n>      -+_<something>_ is intended to be a branch, a commit, or a set of \n> file(s),\n>      - and then either switches to that branch or commit, or restores \n> the\n>      - specified files.\n>      - \n>      -\n>        ## Documentation/git-rebase.adoc ##\n>       @@ Documentation/git-rebase.adoc: of the to-be-rebased branch. \n> However, `ORIG_HEAD` is not guaranteed to still\n>        point to that commit at the end of the rebase if other commands \n> that change\n>      @@ Documentation/git-send-email.adoc: instead.\n>        \tDefault value can be specified by the \n> `sendemail.smtpServerOption`\n>        \tconfiguration option.\n>        +\n>      -@@ Documentation/git-send-email.adoc: must be used for each \n> option.\n>      - --smtp-ssl::\n>      - \tLegacy alias for `--smtp-encryption ssl`.\n>      - \n>      ----smtp-ssl-cert-path::\n>      -+--smtp-ssl-cert-path <path>::\n>      - \tPath to a store of trusted CA certificates for SMTP SSL/TLS\n>      - \tcertificate validation (either a directory that has been \n> processed\n>      - \tby `c_rehash`, or a single file containing one or more PEM \n> format\n>       @@ Documentation/git-send-email.adoc: Automating\n>        --no-to::\n>        --no-cc::\n>      @@ Documentation/git-send-email.adoc: Automating\n>        \tvia config, if any.\n>       \n>        --to-cmd=<command>::\n>      -@@ Documentation/git-send-email.adoc: have been specified, in \n> which case default to `compose`.\n>      - \tCurrently, validation means the following:\n>      - +\n>      - --\n>      --\t\t*\tInvoke the sendemail-validate hook if present (see \n> linkgit:githooks[5]).\n>      --\t\t*\tWarn of patches that contain lines longer than\n>      --\t\t\t998 characters unless a suitable transfer encoding\n>      --\t\t\t(`auto`, `base64`, or `quoted-printable`) is used;\n>      --\t\t\tthis is due to SMTP limits as described by\n>      --\t\t\thttps://www.ietf.org/rfc/rfc5322.txt.\n>      -+* Invoke the sendemail-validate hook if present (see \n> linkgit:githooks[5]).\n>      -+* Warn of patches that contain lines longer than\n>      -+  998 characters unless a suitable transfer encoding\n>      -+  (`auto`, `base64`, or `quoted-printable`) is used;\n>      -+  this is due to SMTP limits as described by\n>      -+  https://www.ietf.org/rfc/rfc5322.txt.\n>      - --\n>      - +\n>      - Default is the value of `sendemail.validate`; if this is not set,\n>      -\n>      - ## Documentation/git-worktree.adoc ##\n>      -@@ Documentation/git-worktree.adoc: associated with a new unborn \n> branch named _<branch>_ (after\n>      - passed to the command. In the event the repository has a remote \n> and\n>      - `--guess-remote` is used, but no remote or local branches exist, \n> then the\n>      - command fails with a warning reminding the user to fetch from \n> their remote\n>      --first (or override by using `-f/--force`).\n>      -+first (or override by using `-f`/`--force`).\n>      - \n>      - `list`::\n>      - \n>\n> -- \n> gitgitgadget\n\nNaturally a misleading range-diff. It’s the same change as last\nround but split up into two commits.\n\nThis looks good to me. Thanks!\n"},{"id":"532608","messageId":"80146290-bbe3-4da4-b951-04399bc2fd03@app.fastmail.com","threadId":"64630","inReplyTo":"a3a76d448ac2871834576be6d79e4704aae11f35.1766170456.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 2/2] doc: correct minor wording issues","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-21T17:13:18Z","receivedAt":"2025-12-21T17:13:39Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Fri, Dec 19, 2025, at 19:54, Jean-Noël Avila via GitGitGadget wrote:\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n>\n> * use imperative mood for consistency in options descriptions\n> * add missing parenthesis\n> * reword verbose phrase in git-repack.adoc\n>\n> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n\nI have reviewed these changes in v1 since the changes are the same but\nsplit into two commits instead of one.\n\nAcked-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n"},{"id":"532609","messageId":"ff43e66c-359f-4493-9da5-a089f15d3cf7@app.fastmail.com","threadId":"64630","inReplyTo":"31694ab9d337d68294a5710d55fc4f7e1ff6f83a.1766170456.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 1/2] doc: fix asciidoc markup issues in several files","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-21T17:13:33Z","receivedAt":"2025-12-21T17:13:54Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Fri, Dec 19, 2025, at 19:54, Jean-Noël Avila via GitGitGadget wrote:\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n>\n> * fix incorrect use of backticks for markup in\n>   git-checkout.adoc, git-worktree.adoc\n> * switch tabs to spaces\tin git-send-email.adoc list items\n>\n> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n\nI have reviewed these changes in v1 since the changes are the same but\nsplit into two commits instead of one.\n\nBeyond what the commit message says the only other thing is:\n\n>[snip]\n> ---smtp-ssl-cert-path::\n> +--smtp-ssl-cert-path <path>::\n>  \tPath to a store of trusted CA certificates for SMTP SSL/TLS\n>  \tcertificate validation (either a directory that has been processed\n>  \tby `c_rehash`, or a single file containing one or more PEM format\n\nI only mention this for completeness (of the review).\n\nAcked-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n"},{"id":"532612","messageId":"xmqqms3brutd.fsf@gitster.g","threadId":"64630","inReplyTo":"80146290-bbe3-4da4-b951-04399bc2fd03@app.fastmail.com","subject":"Re: [PATCH v2 2/2] doc: correct minor wording issues","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-12-22T04:42:38Z","receivedAt":"2025-12-22T04:42:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Kristoffer Haugsbakk\" <kristofferhaugsbakk@fastmail.com> writes:\n\n> On Fri, Dec 19, 2025, at 19:54, Jean-Noël Avila via GitGitGadget wrote:\n>> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n>>\n>> * use imperative mood for consistency in options descriptions\n>> * add missing parenthesis\n>> * reword verbose phrase in git-repack.adoc\n>>\n>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n>\n> I have reviewed these changes in v1 since the changes are the same but\n> split into two commits instead of one.\n>\n> Acked-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nThanks for reviewing.\n\nI've also reviewed the v2 hours ago and the patches are now already\nin 'next'.\n"}]}