From: Siddh Raman Pant Date: Tue, 19 May 2026 16:30:37 GMT Subject: [PATCH 8/9] Documentation: document external notes command options Message-ID: <12aa52077b4111892d2c966a2bff205d5b4ad170.1779207350.git.siddh.raman.pant@oracle.com> In-Reply-To: Assisted-by: Codex:gpt-5.5-xhigh-fast Signed-off-by: Siddh Raman Pant --- Documentation/config/notes.adoc | 57 ++++++++++++++++++++++++++ Documentation/git-format-patch.adoc | 11 ++++- Documentation/git-range-diff.adoc | 6 +++ Documentation/pretty-options.adoc | 9 ++++ contrib/completion/git-completion.bash | 4 +- 5 files changed, 84 insertions(+), 3 deletions(-) diff --git a/Documentation/config/notes.adoc b/Documentation/config/notes.adoc index b7e536496f51..b3ef3fa52950 100644 --- a/Documentation/config/notes.adoc +++ b/Documentation/config/notes.adoc @@ -34,6 +34,63 @@ The effective value of `core.notesRef` (possibly overridden by `GIT_NOTES_REF`) is also implicitly added to the list of refs to be displayed. +`notes.externalCommand`:: + Command to invoke as a long-lived helper when showing commit messages + with the `git log` family of commands. Git sends one commit object ID + per request on the command's standard input: ++ +------------ + +------------ ++ +For each request, the command must respond on its standard output with either +` missing` followed by a newline, or ` ok ` +followed by a newline and exactly `` bytes of UTF-8 note text followed by a +newline. The command must respond to each request as it is received; Git does +not send all commit object IDs before reading responses. Empty note text is not +displayed. If Git cannot start or communicate with the command, or the command +sends an invalid response, Git warns once and disables it for the rest of the +command. External notes are only used while formatting output by default; see +`notes.externalCommandForGrep` to include them when matching commits. ++ +This setting is only respected in protected configuration (see +linkgit:git-config[1]). This prevents untrusted repositories from running +arbitrary commands when notes are displayed. ++ +This setting does not take effect when: ++ +-- +* the value is empty; +* `--no-notes` is given; +* `--no-external-notes` is given; or +* `--notes=` is given by itself without `--external-notes` or `--notes`. +-- + +`notes.externalCommandName`:: + Name to use in the `Notes ():` header for notes returned by + `notes.externalCommand`. Defaults to `external`. This setting is only + respected in protected configuration. + +`notes.externalCommandTimeoutMs`:: + Number of milliseconds to wait when reading each response from + `notes.externalCommand`. Defaults to `100`. If the command does not + produce the expected response in time, Git warns once and disables it + for the rest of the command. A value of `0` disables timeout handling, + so reads can block until the command writes output or exits. This + setting is only respected in protected configuration. + +`notes.externalCommandForGrep`:: + Boolean indicating whether notes returned by `notes.externalCommand` + are included when matching commits with `--grep`, wherever notes would + normally participate in grep matching. Defaults to false. This does + not make hidden notes searchable in formats such as `--oneline` or + `--pretty=%s`; use `--notes` or `--external-notes` if those formats + should search notes too. When enabled, revision traversal may invoke + the external command for many commits that are not ultimately + displayed, which can be expensive for slow commands. The note output + can also change which commits match. This setting is only respected in + protected configuration. + `notes.rewrite.`:: When rewriting commits with __ (currently `amend` or `rebase`), if this variable is `false`, git will not copy diff --git a/Documentation/git-format-patch.adoc b/Documentation/git-format-patch.adoc index 566238245028..472b37e5237a 100644 --- a/Documentation/git-format-patch.adoc +++ b/Documentation/git-format-patch.adoc @@ -26,7 +26,7 @@ SYNOPSIS [--[no-]cover-letter] [--quiet] [--commit-list-format=] [--[no-]encode-email-headers] - [--no-notes | --notes[=]] + [--no-notes | --notes[=]] [--[no-]external-notes] [--interdiff=] [--range-diff= [--creation-factor=]] [--filename-max-length=] @@ -395,6 +395,15 @@ configuration options in linkgit:git-notes[1] to use this workflow). The default is `--no-notes`, unless the `format.notes` configuration is set. +--external-notes:: +--no-external-notes:: + Invoke or do not invoke `notes.externalCommand` to obtain external + notes. Like `--notes=`, `--external-notes` names an explicit + note source and by itself does not include the default notes refs. + Use `--external-notes --notes` to include the default notes refs + too, or combine `--external-notes` with `--notes=` to include + external notes with specific notes refs. + --signature=:: --no-signature:: Add a signature to each message produced. Per RFC 3676 the signature diff --git a/Documentation/git-range-diff.adoc b/Documentation/git-range-diff.adoc index 5cc5e2ed5673..1de23f300517 100644 --- a/Documentation/git-range-diff.adoc +++ b/Documentation/git-range-diff.adoc @@ -12,6 +12,7 @@ git range-diff [--color=[]] [--no-color] [] [--no-dual-color] [--creation-factor=] [--left-only | --right-only] [--diff-merges=] [--remerge-diff] [--no-notes | --notes[=]] + [--[no-]external-notes] ( | ... | ) [[--] ...] @@ -101,6 +102,11 @@ diff. This flag is passed to the `git log` program (see linkgit:git-log[1]) that generates the patches. +`--external-notes`:: +`--no-external-notes`:: + This flag is passed to the `git log` program + (see linkgit:git-log[1]) that generates the patches. + ` `:: Compare the commits specified by the two ranges, where __ is considered an older version of __. diff --git a/Documentation/pretty-options.adoc b/Documentation/pretty-options.adoc index 658e462b2533..aad851c92cfd 100644 --- a/Documentation/pretty-options.adoc +++ b/Documentation/pretty-options.adoc @@ -93,6 +93,15 @@ being displayed. Examples: "`--notes=foo`" will show only notes from "`--notes --notes=foo --no-notes --notes=bar`" will only show notes from `refs/notes/bar`. +`--external-notes`:: +`--no-external-notes`:: + Invoke or do not invoke `notes.externalCommand` to obtain external + notes. Like `--notes=`, `--external-notes` names an explicit + note source and by itself does not include the default notes refs. + Use `--external-notes --notes` to include the default notes refs + too, or combine `--external-notes` with `--notes=` to include + external notes with specific notes refs. + `--show-notes-by-default`:: Show the default notes unless options for displaying specific notes are given. diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash index a8e7c6ddbfb2..146444e65860 100644 --- a/contrib/completion/git-completion.bash +++ b/contrib/completion/git-completion.bash @@ -2023,7 +2023,7 @@ _git_fetch () __git_format_patch_extra_options=" --full-index --not --all --no-prefix --src-prefix= - --dst-prefix= --notes + --dst-prefix= --notes --external-notes --no-external-notes " _git_format_patch () @@ -2215,7 +2215,7 @@ __git_log_common_options=" __git_log_gitk_options=" --dense --sparse --full-history --simplify-merges --simplify-by-decoration - --left-right --notes --no-notes + --left-right --notes --no-notes --external-notes --no-external-notes " # Options that go well for log and shortlog (not gitk) __git_log_shortlog_options=" -- 2.53.0