* Re: [PATCH 2/3] doc: config/sideband: fix typo in adoc markup
From: Kristoffer Haugsbakk @ 2026-06-10 20:13 UTC (permalink / raw)
To: Tuomas Ahola, git
In-Reply-To: <20260610185148.23920-3-taahol@utu.fi>
> doc: config/sideband: fix typo in adoc markup
You might be able to be more precise while using the same amount of
words or less. Like:
_: fix description list delimiter
On Wed, Jun 10, 2026, at 20:51, Tuomas Ahola wrote:
> Fix a simple typo in AsciiDoc markup.
The subject of the commit might be enough here.
>
> Signed-off-by: Tuomas Ahola <taahol@utu.fi>
> ---
> Documentation/config/sideband.adoc | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>[snip]
> @@ -9,7 +9,7 @@ sideband.allowControlCharacters::
> `color`::
> Allow ANSI color sequences, line feeds and horizontal tabs,
> but mask all other control characters. This is the default.
> - `cursor:`:
> + `cursor`::
Nice find!
> Allow control sequences that move the cursor. This is
> disabled by default.
> `erase`::
> --
> 2.30.2
^ permalink raw reply
* Re: [PATCH 1/7] builtin/init: stop modifying global `git_work_tree_cfg` variable
From: Justin Tobler @ 2026-06-10 21:15 UTC (permalink / raw)
To: Patrick Steinhardt; +Cc: git
In-Reply-To: <20260610-b4-pks-setup-drop-global-state-v1-1-5dff3eec8f06@pks.im>
On 26/06/10 08:56AM, Patrick Steinhardt wrote:
> When executing git-init(1) we need to figure out the final location of
> the worktree. This location can be configured in a couple of ways: via
> an environment variable, via the preexisting "core.worktree" config in
> case we're reinitializing, or implicitly when reinitializing a non-bare
> repository.
>
> When checking for the worktree location in "builtin/init-db.c" we
> populate any potentially-discovered value both by setting the global
> `git_work_tree_cfg` variable and via `set_git_work_tree()`, which
> ultimately ends up modifying `struct repository::worktree`.
Does `git_work_tree_cfg` have any bearing on the worktree value that
ends up in `struct repository`? Or is it just `set_git_work_tree()`?
> Modifying `git_work_tree_cfg` is unnecessary though: we configure the
> worktree in `create_default_files()`, and that function derives the
> worktree location via `repo_get_work_tree()`. Consequently, propagating
> the worktree via `set_git_work_tree()` is sufficient.
Ok, so IIUC there is really no reason to globally store the
`git_work_tree_cfg` value derived during `cmd_init_db()`. We only care
about the worktree written to `struct repository`.
> Stop munging `git_work_tree_cfg` and make it file-local to "setup.c" and
> function-local to `cmd_init_db()`.
Makes sense.
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
> builtin/init-db.c | 4 ++++
> environment.c | 3 ---
> environment.h | 1 -
> setup.c | 3 +++
> 4 files changed, 7 insertions(+), 4 deletions(-)
>
> diff --git a/builtin/init-db.c b/builtin/init-db.c
> index c55517ad94..01bc27904e 100644
> --- a/builtin/init-db.c
> +++ b/builtin/init-db.c
> @@ -229,6 +229,8 @@ int cmd_init_db(int argc,
>
> if (!is_bare_repository_cfg) {
> const char *git_dir_parent = strrchr(git_dir, '/');
> + char *git_work_tree_cfg = NULL;
We figure out the worktree locally and continue to set it via
`set_git_work_tree()` without updating a global worktree config value.
> +
> if (git_dir_parent) {
> char *rel = xstrndup(git_dir, git_dir_parent - git_dir);
> git_work_tree_cfg = real_pathdup(rel, 1);
> @@ -243,6 +245,8 @@ int cmd_init_db(int argc,
> if (access(repo_get_work_tree(the_repository), X_OK))
> die_errno (_("Cannot access work tree '%s'"),
> repo_get_work_tree(the_repository));
> +
> + free(git_work_tree_cfg);
> }
> else {
> if (real_git_dir)
> diff --git a/environment.c b/environment.c
> index fc3ed8bb1c..4e86335f25 100644
> --- a/environment.c
> +++ b/environment.c
> @@ -100,9 +100,6 @@ int auto_comment_line_char;
> bool warn_on_auto_comment_char;
> #endif /* !WITH_BREAKING_CHANGES */
>
> -/* This is set by setup_git_directory_gently() and/or git_default_config() */
> -char *git_work_tree_cfg;
> -
> /*
> * Repository-local GIT_* environment variables; see environment.h for details.
> */
> diff --git a/environment.h b/environment.h
> index ccfcf37bfb..5d6e4e6c1b 100644
> --- a/environment.h
> +++ b/environment.h
> @@ -149,7 +149,6 @@ int have_git_dir(void);
>
> extern int is_bare_repository_cfg;
> int is_bare_repository(void);
> -extern char *git_work_tree_cfg;
>
> /* Environment bits from configuration mechanism */
> extern int trust_executable_bit;
> diff --git a/setup.c b/setup.c
> index b4652651df..52228b42a1 100644
> --- a/setup.c
> +++ b/setup.c
> @@ -31,6 +31,9 @@ enum allowed_bare_repo {
> ALLOWED_BARE_REPO_ALL,
> };
>
> +/* This is set by setup_git_directory_gently() and/or git_default_config() */
> +static char *git_work_tree_cfg;
Ok, now `git_work_tree_cfg` is only referenced from "setup.c".
-Justin
^ permalink raw reply
* [PATCH v3 00/11] doc: interpret-trailers: explain key format
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble
In-Reply-To: <CV_doc_int-tr_key_format.533@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Topic name (applied): kh/doc-trailers
Topic summary: Explain the format of trailer keys (alphanum and
hyphens). This is important to keep in mind so that metadata is not
lost to simple syntax errors. Also replace some terms and define the
important ones upfront.
To that end, an overview of the changes:
• Patches 1–3: remove RFC 822 mentions, “metadata” term
• Patch 4: This command is not just for commit messages
• Patches 5–7: Explain the format in the simplest case, explain
the “key” format, and add a new example
• Patch 8 [new]: join some existing paragraphs that are about the same theme
since that makes the text flow better
• Patch 9: Also use the “trailer block” term introduced to the doc in
patch 5 later in the doc
• Patch 10 [new]: Rewrite new-trailer paragraphs (relates to patch 8)
• Patch 11: document line comment behavior
§ Changes in v3
I followed up on D. Ben’s suggestion about thematic paragraphs (patch 8).
I also made a new change as a knock-on to patch 8. That’s patch 10.
I also changed patch 11 (formerly 10): moved it out into its own section.
See the patches for details. Look for “v3” in the patch Notes.
§ Apologies for very cross-referenced commit messages
Like I wrote on v2.
Here one thing lead to another,
And in the process I had to make changes that necessitated *other changes*
as a knock-on effect. Shuffle some text, need to reshuffle three paragraphs
later for consistency. And rather than piling on “While at it”/“Also”, I
chose to try to make focused commits. (Which is how an idea to explain that
trailer keys are alphanum/hyhens-only became eleven patches.)
But in order to follow up on related items I needed to refer to both future
and previous commits. And in the process I abandoned the usual “in an
upcoming commit”/“in a previous commit” in favor of perhaps a gratingly
precise “commit <subject without area>”, e.g.:
The format in its simplest form is easy to describe directly without
comparing it to anything else; we will do that in the upcoming
commit “explain the format after the intro”.
and,
This also makes the introduction more consistent with how I chose
to define trailers in the glossary:[1] “Key-value metadata”. (We will
introduce “key–value” in the upcoming commit “explain the format after
the intro”.)
§ Cc
(see v2)
§ In-reply-to: v1
§ Link to v2
https://lore.kernel.org/git/V2_CV_doc_int-tr_key_format.613@msgid.xyz/
[01/11] doc: interpret-trailers: stop fixating on RFC 822
[02/11] doc: interpret-trailers: replace “lines” with “metadata”
[03/11] doc: interpret-trailers: use “metadata” in Name as well
[04/11] doc: interpret-trailers: not just for commit messages
[05/11] doc: interpret-trailers: explain the format after the intro
[06/11] doc: interpret-trailers: explain key format
[07/11] doc: interpret-trailers: add key format example
[08/11] doc: interpret-trailers: join new-trailers again
[09/11] doc: interpret-trailers: commit to “trailer block” term
[10/11] doc: interpret-trailers: rewrite new-trailers paragraphs
[11/11] doc: interpret-trailers: document comment line treatment
Documentation/git-interpret-trailers.adoc | 92 ++++++++++++++++-------
1 file changed, 66 insertions(+), 26 deletions(-)
Interdiff against v2:
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index b42f957d666..d5e856f5d68 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -60,12 +60,20 @@ are applied to each input and the way any existing trailer in
the input is changed. They also make it possible to
automatically add some trailers.
-By default, a `<key>=<value>` or `<key>:<value>` argument given
-using `--trailer` will be appended after the existing trailers only if
-the last trailer has a different (_<key>_, _<value>_) pair (or if there
-is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed
-to remove starting and trailing whitespace, and the resulting trimmed
-_<key>_ and _<value>_ will appear in the output like this:
+Let's consider new trailers added with `--trailer`.
+By default, the new trailer will appear at the end of the trailer block.
+Also by default, this new trailer will only be added
+if the last trailer is different to it.
+A trailer block will be created with only that trailer if a trailer
+block does not already exist. Recall that a trailer block needs to be
+preceded by a blank line, so a blank line (specifically an empty line)
+will be inserted before the new trailer block in that case.
+
+More concretely, this is how the new trailer is added: a `<key>=<value>`
+or `<key>:<value>` argument given using `--trailer` will be appended
+after the existing trailers. The _<key>_ and _<value>_ parts will be
+trimmed to remove starting and trailing whitespace, and the resulting
+trimmed _<key>_ and _<value>_ will appear in the output like this:
------------------------------------------------
key: value
@@ -74,6 +82,16 @@ key: value
This means that the trimmed _<key>_ and _<value>_ will be separated by
"`:`{nbsp}" (one colon followed by one space).
+Existing trailers are extracted from the input by looking for the
+trailer block. Concretely, that is a group of one or more lines that (i)
+is all trailers, or (ii) contains at least one Git-generated or
+user-configured trailer and consists of at
+least 25% trailers.
+The trailer block is by definition at the end the the message. The end
+of the message in turn is either (i) at the end of the input, or (ii)
+the last non-whitespace lines before a line that starts with `---`
+(followed by a space or the end of the line).
+
For convenience, a _<key-alias>_ can be configured to make using `--trailer`
shorter to type on the command line. This can be configured using the
`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix
@@ -87,26 +105,6 @@ trailer.sign.key "Signed-off-by: "
in your configuration, you only need to specify `--trailer="sign: foo"`
on the command line instead of `--trailer="Signed-off-by: foo"`.
-By default the new trailer will appear at the end of the trailer block.
-A trailer block will be created with only that trailer if a trailer
-block does not already exist. Recall that a trailer block needs to be
-preceded by a blank line, so a blank line (specifically an empty line)
-will be inserted before the new trailer block in that case.
-
-Existing trailers are extracted from the input by looking for the
-trailer block. Concretely, that is a group of one or more lines that (i)
-is all trailers, or (ii) contains at least one Git-generated or
-user-configured trailer and consists of at
-least 25% trailers.
-The trailer block is by definition at the end the the message. The end
-of the message in turn is either (i) at the end of the input, or (ii)
-the last non-whitespace lines before a line that starts with `---`
-(followed by a space or the end of the line).
-
-This command ignores comment lines (see `core.commentString` in
-linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
-and `commit-msg` hooks.
-
When reading trailers, there can be no whitespace before or inside the
_<key>_, but any number of regular space and tab characters are allowed
between the _<key>_ and the separator. There can be whitespaces before,
@@ -119,6 +117,16 @@ key: This is a very long value, with spaces and
newlines in it.
------------------------------------------------
+OTHER RULES
+-----------
+
+What was covered in the previous section are the rules that are relevant
+for regular use. The following points are included for completeness.
+
+This command ignores comment lines (see `core.commentString` in
+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
+and `commit-msg` hooks.
+
OPTIONS
-------
`--in-place`::
Range-diff against v2:
1: e5d58237bc2 = 1: e5d58237bc2 doc: interpret-trailers: stop fixating on RFC 822
2: 5ddd39bf157 = 2: 5ddd39bf157 doc: interpret-trailers: replace “lines” with “metadata”
3: 9f0227a1978 = 3: 9f0227a1978 doc: interpret-trailers: use “metadata” in Name as well
4: 4cb26810d4e = 4: 4cb26810d4e doc: interpret-trailers: not just for commit messages
5: 196c91bebe3 = 5: 196c91bebe3 doc: interpret-trailers: explain the format after the intro
6: 688ea55599a = 6: 688ea55599a doc: interpret-trailers: explain key format
7: e6eafbd641f = 7: e6eafbd641f doc: interpret-trailers: add key format example
-: ----------- > 8: 8849ace33e6 doc: interpret-trailers: join new-trailers again
8: f14d641309c ! 9: 8323b84e134 doc: interpret-trailers: commit to “trailer block” term
@@ Commit message
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
## Documentation/git-interpret-trailers.adoc ##
-@@ Documentation/git-interpret-trailers.adoc: trailer.sign.key "Signed-off-by: "
- in your configuration, you only need to specify `--trailer="sign: foo"`
- on the command line instead of `--trailer="Signed-off-by: foo"`.
+@@ Documentation/git-interpret-trailers.adoc: key: value
+ This means that the trimmed _<key>_ and _<value>_ will be separated by
+ "`:`{nbsp}" (one colon followed by one space).
-By default the new trailer will appear at the end of all the existing
-trailers. If there is no existing trailer, the new trailer will appear
@@ Documentation/git-interpret-trailers.adoc: trailer.sign.key "Signed-off-by: "
+the last non-whitespace lines before a line that starts with `---`
+(followed by a space or the end of the line).
- When reading trailers, there can be no whitespace before or inside the
- _<key>_, but any number of regular space and tab characters are allowed
+ For convenience, a _<key-alias>_ can be configured to make using `--trailer`
+ shorter to type on the command line. This can be configured using the
-: ----------- > 10: c7495c3b39e doc: interpret-trailers: rewrite new-trailers paragraphs
9: 78125ab39f1 ! 11: fc38e8660f0 doc: intepret-trailers: document comment line treatment
@@ Metadata
Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
## Commit message ##
- doc: intepret-trailers: document comment line treatment
+ doc: interpret-trailers: document comment line treatment
Comment lines have always been ignored but this is not documented.
@@ Commit message
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
## Documentation/git-interpret-trailers.adoc ##
-@@ Documentation/git-interpret-trailers.adoc: of the message in turn is either (i) at the end of the input, or (ii)
- the last non-whitespace lines before a line that starts with `---`
- (followed by a space or the end of the line).
+@@ Documentation/git-interpret-trailers.adoc: key: This is a very long value, with spaces and
+ newlines in it.
+ ------------------------------------------------
++OTHER RULES
++-----------
++
++What was covered in the previous section are the rules that are relevant
++for regular use. The following points are included for completeness.
++
+This command ignores comment lines (see `core.commentString` in
+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
+and `commit-msg` hooks.
+
- When reading trailers, there can be no whitespace before or inside the
- _<key>_, but any number of regular space and tab characters are allowed
- between the _<key>_ and the separator. There can be whitespaces before,
+ OPTIONS
+ -------
+ `--in-place`::
base-commit: 5361983c075154725be47b65cca9a2421789e410
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 01/11] doc: interpret-trailers: stop fixating on RFC 822
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
This command handles the trailers metadata format. But the command
isn’t introduced as such; it is instead introduced by stating that
these trailer lines look similar to RFC 822 email headers.
This is overwrought; most people do not deal directly with email
headers, and certainly not email RFCs.
Trailers are just key–value pairs that, like email headers, use colon
as the separator. The format in its simplest form is easy to describe
directly without comparing it to anything else; we will do that in the
upcoming commit “explain the format after the intro”.
For now, let’s:
• remove the first mention of email headers;
• keep the second, innocuous comparison with email line folding in the
middle; and
• remove the now-unneeded disclaimer that trailers do not share many of
the features of RFC 822 email headers—there is no invitation to
speculate that trailers would follow any other email format rules
since we do not compare them directly any more.
***
Talking about trailers as an RFC 822/2822-like format seems to go back
to the `--fixes`/`Fixes:` trailer topic,[1] the thread that precipitated
this command and in turn the first trailer support in git(1) beyond
adding s-o-b lines.
† 1: https://lore.kernel.org/all/20131027071407.GA11683@leaf/
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• Use `***` as a thematic break instead of `❦`
• Change to “metadata” instead of “key–value pairs” since this series
version adds a paragraph after this one where we dig into this
term. And “metadata” describes the purpose of this format.
Documentation/git-interpret-trailers.adoc | 9 +++------
1 file changed, 3 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 77b4f63b05c..1878848ad2a 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -14,9 +14,9 @@ git interpret-trailers [--in-place] [--trim-empty]
DESCRIPTION
-----------
-Add or parse _trailer_ lines that look similar to RFC 822 e-mail
-headers, at the end of the otherwise free-form part of a commit
-message. For example, in the following commit message
+Add or parse _trailer_ lines at the end of the otherwise
+free-form part of a commit message. For example, in the following commit
+message
------------------------------------------------
subject
@@ -107,9 +107,6 @@ key: This is a very long value, with spaces and
newlines in it.
------------------------------------------------
-Note that trailers do not follow (nor are they intended to follow) many of the
-rules for RFC 822 headers. For example they do not follow the encoding rule.
-
OPTIONS
-------
`--in-place`::
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 02/11] doc: interpret-trailers: replace “lines” with “metadata”
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
We removed the initial comparison to email headers in the previous
commit. Now the introduction paragraph just says “trailer lines”, and
the only hint that this is metadata/structured information is the
“otherwise free-form” phrase.
Let’s replace “lines” with “metadata” since that is their purpose.
This also makes the introduction more consistent with how I chose
to define trailers in the glossary:[1] “Key-value metadata”. (We will
introduce “key–value” in the upcoming commit “explain the format after
the intro”.)
† 1: 68e3c69e (Documentation/glossary: describe "trailer", 2024-11-17)
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 1878848ad2a..3f60fd9b720 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -14,7 +14,7 @@ git interpret-trailers [--in-place] [--trim-empty]
DESCRIPTION
-----------
-Add or parse _trailer_ lines at the end of the otherwise
+Add or parse trailers metadata at the end of the otherwise
free-form part of a commit message. For example, in the following commit
message
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 03/11] doc: interpret-trailers: use “metadata” in Name as well
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
We now since the previous commit introduce the format as “trailers
metadata”. We can replace “structured information” with “metadata”
in the “Name” section to be consistent.
While “structured information” does emphasize that the data is not
loosely structured, we also say that this command adds to or parses
this format. I don’t think that we need to emphasize that it is
structured since clearly there is some structure there.
Both “metadata” and “structured information” can convey the same
information. But “metadata” is shorter and easier to deploy since
it’s just one word.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 3f60fd9b720..4e92c8299bb 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -3,7 +3,7 @@ git-interpret-trailers(1)
NAME
----
-git-interpret-trailers - Add or parse structured information in commit messages
+git-interpret-trailers - Add or parse metadata in commit messages
SYNOPSIS
--------
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 04/11] doc: interpret-trailers: not just for commit messages
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
This command doesn’t interface with commits directly. You can
interpret or modify any kind of text, even though commit messages
are the most relevant.
The git(1) suite also isn’t restricted to only direct commit support
since git-tag(1) learned `--trailer` in 066cef77 (builtin/tag: add
--trailer option, 2024-05-05)
Now, we already introduce the command in the “Name” section as dealing
with commit messages as well. That is fine since that intro line needs
to remain pretty short.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 4e92c8299bb..7329e710e1a 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -15,8 +15,8 @@ git interpret-trailers [--in-place] [--trim-empty]
DESCRIPTION
-----------
Add or parse trailers metadata at the end of the otherwise
-free-form part of a commit message. For example, in the following commit
-message
+free-form part of a commit message, or any other kind of text.
+For example, in the following commit message
------------------------------------------------
subject
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 05/11] doc: interpret-trailers: explain the format after the intro
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble, D. Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
You need to read the entire “Description” section in order to understand
the full trailer format. But there are many nuances, so that’s fine.
As a starter though we have an introductory example.[1] That turns out
to be crucial; the rest of this section talks about the mechanics of the
command and only incidentally the format itself.
Now, although the example might arguably be self-explanatory, we can
add a little preamble which defines the format in its simplest form as
well as define the most important terms.
Note that we name the “blank line” rule since I want to use that term
every time it comes up. It gets very mildly obfuscated if you call it a
“blank line” in one place[2] and “empty (or whitespace-only) ...” in
another one.[3]
We will define the format of the *key* in the next commit.
† 1: from d57fa7fc (doc: trailer: add more examples in DESCRIPTION,
2023-06-15)
† 2: `Documentation/git-interpret-trailers.adoc:86` in
5361983c (The 22nd batch, 2026-03-27)
† 3: `Documentation/git-interpret-trailers.adoc:93` in
5361983c (The 22nd batch, 2026-03-27)
Suggested-by: D. Ben Knoble <ben.knoble+github@gmail.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2: [new]
• PS: Suggested here: https://lore.kernel.org/git/8E736B70-424E-48AC-A6D0-9A8B091D21F6@gmail.com/#t
• (My tardiness on this topic has made these reminders necessary,
if only for my own reference)
Documentation/git-interpret-trailers.adoc | 7 ++++++-
1 file changed, 6 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 7329e710e1a..bcd79b19bd7 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -16,7 +16,12 @@ DESCRIPTION
-----------
Add or parse trailers metadata at the end of the otherwise
free-form part of a commit message, or any other kind of text.
-For example, in the following commit message
+
+A _trailer_ in its simplest form is a key-value pair with a colon as a
+separator. A _trailer block_ consists of one or more trailers. The
+trailer block needs to be preceded by a blank line, where a _blank line_
+is either an empty or a whitespace-only line. For example, in the
+following commit message
------------------------------------------------
subject
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 06/11] doc: interpret-trailers: explain key format
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
A trailer key must consist of ASCII alphanumeric characters and
hyphens *only*. Let’s document it explicitly instead of relying on
readers being conservative and only basing their trailer keys on the
documentation examples.[1]
The previous commit provided us with an appropriate paragraph to
describe the key format.
† 1: Technically they would then miss out on using digits in them since
all of the example keys just use letters and hyphens
Reported-by: Brendan Jackman <jackmanb@google.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2:
• PS: Reported in https://lore.kernel.org/git/CA+i-1C1DM0CHoFJ0A5CchQg=qDVLi_SSiZqcd0dxsay-Y94WTQ@mail.gmail.com/
• Remove the “paint by numbers” reference after review (unclear)
• Add apropos footnote
• Tweak the paragraph about how we now have a context to describe
this format
v1: [had a note about code spelunking (isalnum(3))]
Documentation/git-interpret-trailers.adoc | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index bcd79b19bd7..c35fa9c688d 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -18,7 +18,8 @@ Add or parse trailers metadata at the end of the otherwise
free-form part of a commit message, or any other kind of text.
A _trailer_ in its simplest form is a key-value pair with a colon as a
-separator. A _trailer block_ consists of one or more trailers. The
+separator. The _key_ consists of ASCII alphanumeric characters and
+hyphens (`-`). A _trailer block_ consists of one or more trailers. The
trailer block needs to be preceded by a blank line, where a _blank line_
is either an empty or a whitespace-only line. For example, in the
following commit message
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 07/11] doc: interpret-trailers: add key format example
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
All of the examples speak of the Happy Path where everything works
as intended. But failure examples can also be instructive. Especially
for explaining again, by example, the key format (see previous commit).
This also allows us to demonstrate trailer block detection with a
concrete example.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index c35fa9c688d..f215cba4bf0 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -405,6 +405,29 @@ mv "\$1.new" "\$1"
$ chmod +x .git/hooks/commit-msg
------------
+* Here we try to to use three different trailer keys. But it fails
+ because two of them are not recognized as trailer keys.
++
+----
+$ cat msg.txt
+subject
+
+Skapad-på: some-branch
+Hash-in-v6.11: 45c12d3269fe48f22834320c782ffe86c3560f2c
+Reviewed-by: Alice <alice@example.com>
+$ git interpret-trailers --only-trailers <msg.txt
+$
+----
++
+Recall that a trailer key has to consist of only ASCII alphanumeric
+characters and hyphens, and this does not hold for the two first
+supposed trailer keys. And now none are recognized as trailers because
+the candidate trailer block has at least one non-trailer line, even
+though `Reviewed-by` is a valid trailer key. Recall that a trailer block
+has to either (i) be all trailers, or (ii) consist of at least one
+Git-generated or user-configured trailer (and some other conditions).
+And (ii) is not satisfied since we have not configured any trailer keys.
+
SEE ALSO
--------
linkgit:git-commit[1], linkgit:git-format-patch[1], linkgit:git-config[1]
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 08/11] doc: interpret-trailers: join new-trailers again
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble, D. Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
There are three trailers that talk about how a new trailer is added.
But the first one is separated from the other two by two paragraphs
about how `key-alias` can make using `--trailer` more convenient. This
short how-to does not follow thematically from the previous paragraph,
and can wait until we have fully described how a new trailer is
added. So let’s move the three paragraphs about the new-trailer topic
together and move the how-to paragraphs after that.
***
Let’s now review the history of the document. Even if the document
is not quite correct in its current state, just doing the apparently
obvious edit without considering the history does not respect the
effort that went into changing the document in the past.
These three paragraphs were originally next to each other, in the first
version of the doc.[1] But extra sentences about this how-to topic was
added to the first paragraph nine years later:[2]
[...]
`': '` (one colon followed by one space). For convenience, the
<token> can be a shortened string key (e.g., "sign") instead of the
full string which should [...]
And then it was split into it’s own paragraph a little later.[3]
This evolution shows, in my opinion, that this how-to never followed
thematically from the existing topic. Which means that there is nothing
that was potentially lost to time that we need to restore or respect.
† 1: dfd66ddf (Documentation: add documentation for 'git
interpret-trailers', 2014-10-13)
† 2: eda2c44c (doc: trailer: mention 'key' in DESCRIPTION, 2023-06-15)
† 3: 6ccbc667 (trailer doc: <token> is a <key> or <keyAlias>, not both,
2023-09-07)
Suggested-by: D. Ben Knoble <ben.knoble+github@gmail.com>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v3: [new]
• Suggested here: https://lore.kernel.org/git/CALnO6CBiRefHNT6tjskCQRUOj5Y--K3okR_RFPmth6O7s1_VKQ@mail.gmail.com/
• Msg: Now *this* might definitely make for an *overly verbose* cmt msg[1]
🔗 1: https://lore.kernel.org/git/xmqqpl1zsv8s.fsf@gitster.g/
Documentation/git-interpret-trailers.adoc | 26 +++++++++++------------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index f215cba4bf0..759cdb6e18e 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -74,19 +74,6 @@ key: value
This means that the trimmed _<key>_ and _<value>_ will be separated by
"`:`{nbsp}" (one colon followed by one space).
-For convenience, a _<key-alias>_ can be configured to make using `--trailer`
-shorter to type on the command line. This can be configured using the
-`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix
-of the full _<key>_ string, although case sensitivity does not matter. For
-example, if you have
-
-------------------------------------------------
-trailer.sign.key "Signed-off-by: "
-------------------------------------------------
-
-in your configuration, you only need to specify `--trailer="sign: foo"`
-on the command line instead of `--trailer="Signed-off-by: foo"`.
-
By default the new trailer will appear at the end of all the existing
trailers. If there is no existing trailer, the new trailer will appear
at the end of the input. A blank line will be added before the new
@@ -101,6 +88,19 @@ The group must either be at the end of the input or be the last
non-whitespace lines before a line that starts with `---` (followed by a
space or the end of the line).
+For convenience, a _<key-alias>_ can be configured to make using `--trailer`
+shorter to type on the command line. This can be configured using the
+`trailer.<key-alias>.key` configuration variable. The _<key-alias>_ must be a prefix
+of the full _<key>_ string, although case sensitivity does not matter. For
+example, if you have
+
+------------------------------------------------
+trailer.sign.key "Signed-off-by: "
+------------------------------------------------
+
+in your configuration, you only need to specify `--trailer="sign: foo"`
+on the command line instead of `--trailer="Signed-off-by: foo"`.
+
When reading trailers, there can be no whitespace before or inside the
_<key>_, but any number of regular space and tab characters are allowed
between the _<key>_ and the separator. There can be whitespaces before,
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 09/11] doc: interpret-trailers: commit to “trailer block” term
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
We chose to introduce the term “trailer block” into the documentation a
few commits ago.[1] It is used in the code though, so it is not a newly
invented term.
That term was useful to explain where the trailers are found (they
*trail* the message). But it is also useful here, where we explain how
trailers are added to existing messages, how trailer blocks are
found (beyond the simple case in the introduction), and how the end of
the message is found.
† 1: in commit “explain the format after the intro”
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v2: [new]
Documentation/git-interpret-trailers.adoc | 26 ++++++++++++-----------
1 file changed, 14 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 759cdb6e18e..9f4c84abfd9 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -74,19 +74,21 @@ key: value
This means that the trimmed _<key>_ and _<value>_ will be separated by
"`:`{nbsp}" (one colon followed by one space).
-By default the new trailer will appear at the end of all the existing
-trailers. If there is no existing trailer, the new trailer will appear
-at the end of the input. A blank line will be added before the new
-trailer if there isn't one already.
-
-Existing trailers are extracted from the input by looking for
-a group of one or more lines that (i) is all trailers, or (ii) contains at
-least one Git-generated or user-configured trailer and consists of at
+By default the new trailer will appear at the end of the trailer block.
+A trailer block will be created with only that trailer if a trailer
+block does not already exist. Recall that a trailer block needs to be
+preceded by a blank line, so a blank line (specifically an empty line)
+will be inserted before the new trailer block in that case.
+
+Existing trailers are extracted from the input by looking for the
+trailer block. Concretely, that is a group of one or more lines that (i)
+is all trailers, or (ii) contains at least one Git-generated or
+user-configured trailer and consists of at
least 25% trailers.
-The group must be preceded by one or more empty (or whitespace-only) lines.
-The group must either be at the end of the input or be the last
-non-whitespace lines before a line that starts with `---` (followed by a
-space or the end of the line).
+The trailer block is by definition at the end the the message. The end
+of the message in turn is either (i) at the end of the input, or (ii)
+the last non-whitespace lines before a line that starts with `---`
+(followed by a space or the end of the line).
For convenience, a _<key-alias>_ can be configured to make using `--trailer`
shorter to type on the command line. This can be configured using the
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 10/11] doc: interpret-trailers: rewrite new-trailers paragraphs
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Two commits ago we moved new-trailers paragraph next to each other.
But there is something curious about two of them:
By default the new trailer will appear at the end of the trailer
block. [...]
Then a source block and a paragraph later:
By default, a `<key>=<value>` or `<key>:<value>` argument given
using `--trailer` will be appended after the existing trailers only
if [...]
Why are there two paragraphs that talk about how “By default” a trailer
will be appended?
We can make these paragraphs flow better, and with a more distinct
character each, by dividing the flow like this:
1. Declare that we are about to talk about `--trailer` appending
2. Explain the default behavior
3. Explain how this affects the trailer block
4. Then state the same thing (“More concretely”) in concrete terms with
placeholders
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v3: [new]
• Based on draft: https://lore.kernel.org/git/fc1f8149-98c2-48e5-9725-08cc21696cb2@app.fastmail.com/
• See msg:
Two commits ago we moved new-trailers paragraph next to
each other.
This commit here might fit better one step back. So that it
becomes the commit right after. But I can deal with that commit
movement if this change is accepted. For now I didn’t bother.
Documentation/git-interpret-trailers.adoc | 26 ++++++++++++-----------
1 file changed, 14 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index 9f4c84abfd9..fb9b1e94dd7 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -60,12 +60,20 @@ are applied to each input and the way any existing trailer in
the input is changed. They also make it possible to
automatically add some trailers.
-By default, a `<key>=<value>` or `<key>:<value>` argument given
-using `--trailer` will be appended after the existing trailers only if
-the last trailer has a different (_<key>_, _<value>_) pair (or if there
-is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed
-to remove starting and trailing whitespace, and the resulting trimmed
-_<key>_ and _<value>_ will appear in the output like this:
+Let's consider new trailers added with `--trailer`.
+By default, the new trailer will appear at the end of the trailer block.
+Also by default, this new trailer will only be added
+if the last trailer is different to it.
+A trailer block will be created with only that trailer if a trailer
+block does not already exist. Recall that a trailer block needs to be
+preceded by a blank line, so a blank line (specifically an empty line)
+will be inserted before the new trailer block in that case.
+
+More concretely, this is how the new trailer is added: a `<key>=<value>`
+or `<key>:<value>` argument given using `--trailer` will be appended
+after the existing trailers. The _<key>_ and _<value>_ parts will be
+trimmed to remove starting and trailing whitespace, and the resulting
+trimmed _<key>_ and _<value>_ will appear in the output like this:
------------------------------------------------
key: value
@@ -74,12 +82,6 @@ key: value
This means that the trimmed _<key>_ and _<value>_ will be separated by
"`:`{nbsp}" (one colon followed by one space).
-By default the new trailer will appear at the end of the trailer block.
-A trailer block will be created with only that trailer if a trailer
-block does not already exist. Recall that a trailer block needs to be
-preceded by a blank line, so a blank line (specifically an empty line)
-will be inserted before the new trailer block in that case.
-
Existing trailers are extracted from the input by looking for the
trailer block. Concretely, that is a group of one or more lines that (i)
is all trailers, or (ii) contains at least one Git-generated or
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v3 11/11] doc: interpret-trailers: document comment line treatment
From: kristofferhaugsbakk @ 2026-06-10 21:21 UTC (permalink / raw)
To: git
Cc: Kristoffer Haugsbakk, christian.couder, jackmanb, Linus Arver,
D . Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Comment lines have always been ignored but this is not documented.
This is mostly for completeness since this is unlikely to catch anyone
by surprise. But we really ought to be reasonably complete here since
it’s the only documentation page that documents trailers.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Notes (series):
v3:
• Msg: finally fix area
• Demote this point to its own “other rules” section, out of the main
running text. It is not important enough for the main text.
• Since writing this I have realized that we can go into that long
# ----- >8 ----
Commit message separator scissor line, maybe other things. But I stop
short here. These things are even less likely to become a problem for
anyone. And maybe we’ll add them later?
v2: [new]
| 10 ++++++++++
1 file changed, 10 insertions(+)
--git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
index fb9b1e94dd7..d5e856f5d68 100644
--- a/Documentation/git-interpret-trailers.adoc
+++ b/Documentation/git-interpret-trailers.adoc
@@ -117,6 +117,16 @@ key: This is a very long value, with spaces and
newlines in it.
------------------------------------------------
+OTHER RULES
+-----------
+
+What was covered in the previous section are the rules that are relevant
+for regular use. The following points are included for completeness.
+
+This command ignores comment lines (see `core.commentString` in
+linkgit:git-config[1]). This is for use with the `prepare-commit-msg`
+and `commit-msg` hooks.
+
OPTIONS
-------
`--in-place`::
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH v2] update-ref: add --rename option
From: Junio C Hamano @ 2026-06-10 21:28 UTC (permalink / raw)
To: git
In-Reply-To: <xmqqv7brz9ba.fsf@gitster.g>
Add a "--rename" option to "git update-ref" with the syntax:
$ git update-ref --rename <old-refname> <new-refname>
It renames <old-refname> together with its reflog to <new-refname>
(even when used on a local branch ref, the current value and the
reflog of the ref are the only things that are renamed). As the
command is a low-level plumbing command, attempts to rename branches
are not warned, but we document it to draw attention of unsuspecting
users and protect them from burning themselves.
Because the "--stdin" mode wants to operate on its refs in a
reference transaction, and the API function refs_rename_ref() does
not work well as part of a transaction, it is currently not possible
to add a corresponding "rename" verb to the "--stdin" mode before
the underlying API learns to rename refs atomically inside a
transaction. It hence is left for a future refactoring.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
* The initial draft I sent had a warning when the command is used
to rename local branches, but that is unusual for plumbing
commands that should do one thing it is designed for consistently
well without being chatty. This version only has words of warning
in the documentation.
Documentation/git-update-ref.adoc | 9 +++++++++
builtin/update-ref.c | 32 +++++++++++++++++++++++++++++--
t/t1400-update-ref.sh | 24 +++++++++++++++++++++++
3 files changed, 63 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-update-ref.adoc b/Documentation/git-update-ref.adoc
index 37a5019a8b..0c27efaa52 100644
--- a/Documentation/git-update-ref.adoc
+++ b/Documentation/git-update-ref.adoc
@@ -9,6 +9,7 @@ SYNOPSIS
--------
[synopsis]
git update-ref [-m <reason>] [--no-deref] -d <ref> [<old-oid>]
+git update-ref [-m <reason>] [--no-deref] --rename <old-refname> <new-refname>
git update-ref [-m <reason>] [--no-deref] [--create-reflog] <ref> <new-oid> [<old-oid>]
git update-ref [-m <reason>] [--no-deref] --stdin [-z] [--batch-updates]
@@ -39,6 +40,14 @@ the result of following the symbolic pointers.
With `-d`, it deletes the named <ref> after verifying that it
still contains <old-oid>.
+With `--rename`, it renames <old-refname> together with its reflog to
+<new-refname>. The command fails if <old-refname> does not exist, or
+if <new-refname> already exists. Because `git update-ref` does not
+update active worktree `HEAD` symbolic references or `.git/config`
+tracking settings when you rename a local branch in the `refs/heads/`
+hierarchy, think twice before using this command to rename a local
+branch (use `git branch -m` instead).
+
With `--stdin`, update-ref reads instructions from standard input and
performs all modifications together. Specify commands of the form:
diff --git a/builtin/update-ref.c b/builtin/update-ref.c
index 2d68c40ecb..65ee8af08c 100644
--- a/builtin/update-ref.c
+++ b/builtin/update-ref.c
@@ -15,6 +15,7 @@
static const char * const git_update_ref_usage[] = {
N_("git update-ref [<options>] -d <refname> [<old-oid>]"),
N_("git update-ref [<options>] <refname> <new-oid> [<old-oid>]"),
+ N_("git update-ref [<options>] --rename <old-refname> <new-refname>"),
N_("git update-ref [<options>] --stdin [-z] [--batch-updates]"),
NULL
};
@@ -756,13 +757,14 @@ int cmd_update_ref(int argc,
{
const char *refname, *oldval;
struct object_id oid, oldoid;
- int delete = 0, no_deref = 0, read_stdin = 0, end_null = 0;
+ int delete = 0, rename = 0, no_deref = 0, read_stdin = 0, end_null = 0;
int create_reflog = 0;
unsigned int flags = 0;
struct option options[] = {
OPT_STRING( 'm', NULL, &msg, N_("reason"), N_("reason of the update")),
OPT_BOOL('d', NULL, &delete, N_("delete the reference")),
+ OPT_BOOL( 0 , "rename", &rename, N_("rename the reference")),
OPT_BOOL( 0 , "no-deref", &no_deref,
N_("update <refname> not the one it points to")),
OPT_BOOL('z', NULL, &end_null, N_("stdin has NUL-terminated arguments")),
@@ -787,7 +789,7 @@ int cmd_update_ref(int argc,
}
if (read_stdin) {
- if (delete || argc > 0)
+ if (delete || rename || argc > 0)
usage_with_options(git_update_ref_usage, options);
if (end_null)
line_termination = '\0';
@@ -800,6 +802,32 @@ int cmd_update_ref(int argc,
if (end_null)
usage_with_options(git_update_ref_usage, options);
+ if (rename) {
+ const char *oldref, *newref;
+
+ if (delete || argc != 2)
+ usage_with_options(git_update_ref_usage, options);
+
+ oldref = argv[0];
+ newref = argv[1];
+
+ if (check_refname_format(oldref, 0))
+ die("invalid ref format: %s", oldref);
+ if (check_refname_format(newref, 0))
+ die("invalid ref format: %s", newref);
+
+ if (!refs_ref_exists(get_main_ref_store(the_repository), oldref))
+ die("no ref named '%s'", oldref);
+
+ if (refs_ref_exists(get_main_ref_store(the_repository), newref))
+ die("ref '%s' already exists", newref);
+
+ if (refs_rename_ref(get_main_ref_store(the_repository),
+ oldref, newref, msg))
+ die("rename failed");
+ return 0;
+ }
+
if (delete) {
if (argc < 1 || argc > 2)
usage_with_options(git_update_ref_usage, options);
diff --git a/t/t1400-update-ref.sh b/t/t1400-update-ref.sh
index b2858a9061..4330cad282 100755
--- a/t/t1400-update-ref.sh
+++ b/t/t1400-update-ref.sh
@@ -2455,4 +2455,28 @@ test_expect_success 'dangling symref overwritten without old oid' '
test_must_fail git rev-parse --verify refs/heads/does-not-exist
'
+test_expect_success '--rename fails if old-refname does not exist' '
+ test_must_fail git update-ref --rename refs/tags/no-such-ref refs/tags/new-ref 2>err &&
+ test_grep "no ref named .refs/tags/no-such-ref." err
+'
+
+test_expect_success '--rename fails if new-refname does exist' '
+ git update-ref refs/tags/existing HEAD &&
+ git update-ref refs/tags/old-ref HEAD &&
+ test_must_fail git update-ref --rename refs/tags/old-ref refs/tags/existing 2>err &&
+ test_grep "ref .refs/tags/existing. already exists" err
+'
+
+test_expect_success '--rename moves old-refname and its reflog to new-refname' '
+ test_config core.logallrefupdates always &&
+ git update-ref -m "old tag" refs/tags/old-tag HEAD &&
+ git update-ref -m "to new" --rename refs/tags/old-tag refs/tags/new-tag 2>err &&
+ test_must_be_empty err &&
+ git show-ref --exists refs/tags/new-tag &&
+ test_must_fail git show-ref --exists refs/tags/old-tag &&
+ git log -g refs/tags/new-tag >output &&
+ test_grep "old tag" output &&
+ test_grep "to new" output
+'
+
test_done
Range-diff against v1:
1: 79af0ef7d1 ! 1: 00cd13fda7 update-ref: add --rename option
@@ Commit message
$ git update-ref --rename <old-refname> <new-refname>
- It renames <old-refname> together with its reflog to <new-refname>.
+ It renames <old-refname> together with its reflog to <new-refname>
+ (even when used on a local branch ref, the current value and the
+ reflog of the ref are the only things that are renamed). As the
+ command is a low-level plumbing command, attempts to rename branches
+ are not warned, but we document it to draw attention of unsuspecting
+ users and protect them from burning themselves.
- The command warns to use "git branch --rename" instead if old or new
- refname falls inside refs/heads/. We issue this warning (but perform
- the rename anyway) because "git update-ref" acts as a low-level
- plumbing utility: unlike "git branch", it does not update active
- worktree "HEAD" symbolic references or ".git/config" branch tracking
- configuration.
-
- Note that we do not add a corresponding "rename" verb to the "--stdin"
- mode in this commit. While adding a "rename SP <oldref> SP <newref> LF"
- command to the batch stream would be useful, operations in "--stdin"
- mode are executed within an atomic "ref_transaction". Reference renaming
- is currently implemented at the backend level via standalone, non-transactional
- calls (e.g. "refs_rename_ref()"). Supporting renames in a batch transaction
- would require extending "struct ref_transaction" and the reference storage
- backend APIs to coordinate ref and reflog moves atomically, which is
- left for a future refactoring.
+ Because the "--stdin" mode wants to operate on its refs in a
+ reference transaction, and the API function refs_rename_ref() does
+ not work well as part of a transaction, it is currently not possible
+ to add a corresponding "rename" verb to the "--stdin" mode before
+ the underlying API learns to rename refs atomically inside a
+ transaction. It hence is left for a future refactoring.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
@@ Documentation/git-update-ref.adoc: the result of following the symbolic pointers
still contains <old-oid>.
+With `--rename`, it renames <old-refname> together with its reflog to
-+<new-refname>. If either <old-refname> or <new-refname> falls inside
-+`refs/heads/`, a warning will be issued to use `git branch --rename`
-+instead, because `git update-ref` does not update active worktree
-+`HEAD` symbolic references or `.git/config` tracking settings. It
-+fails if <old-refname> does not exist, or if <new-refname> already
-+exists.
++<new-refname>. The command fails if <old-refname> does not exist, or
++if <new-refname> already exists. Because `git update-ref` does not
++update active worktree `HEAD` symbolic references or `.git/config`
++tracking settings when you rename a local branch in the `refs/heads/`
++hierarchy, think twice before using this command to rename a local
++branch (use `git branch -m` instead).
+
With `--stdin`, update-ref reads instructions from standard input and
performs all modifications together. Specify commands of the form:
@@ builtin/update-ref.c: int cmd_update_ref(int argc,
+ if (check_refname_format(newref, 0))
+ die("invalid ref format: %s", newref);
+
-+ if (starts_with(oldref, "refs/heads/") ||
-+ starts_with(newref, "refs/heads/"))
-+ warning(_("You may want 'git branch --rename' instead?"));
-+
+ if (!refs_ref_exists(get_main_ref_store(the_repository), oldref))
+ die("no ref named '%s'", oldref);
+
@@ t/t1400-update-ref.sh: test_expect_success 'dangling symref overwritten without
+ test_grep "ref .refs/tags/existing. already exists" err
+'
+
-+test_expect_success '--rename warns if old or new refname falls inside refs/heads/' '
-+ git update-ref refs/heads/old-branch HEAD &&
-+ git update-ref --rename refs/heads/old-branch refs/heads/new-branch 2>err &&
-+ test_grep "branch --rename. instead" err &&
-+ git rev-parse --verify refs/heads/new-branch &&
-+ test_must_fail git rev-parse --verify refs/heads/old-branch
-+'
-+
+test_expect_success '--rename moves old-refname and its reflog to new-refname' '
-+ git update-ref -m "initial tag" refs/tags/old-tag HEAD &&
-+ git update-ref --rename refs/tags/old-tag refs/tags/new-tag 2>err &&
++ test_config core.logallrefupdates always &&
++ git update-ref -m "old tag" refs/tags/old-tag HEAD &&
++ git update-ref -m "to new" --rename refs/tags/old-tag refs/tags/new-tag 2>err &&
+ test_must_be_empty err &&
-+ git rev-parse --verify refs/tags/new-tag &&
-+ test_must_fail git rev-parse --verify refs/tags/old-tag &&
-+ git log -g refs/tags/new-tag
++ git show-ref --exists refs/tags/new-tag &&
++ test_must_fail git show-ref --exists refs/tags/old-tag &&
++ git log -g refs/tags/new-tag >output &&
++ test_grep "old tag" output &&
++ test_grep "to new" output
+'
+
test_done
--
2.54.0-615-g639a4a7340
^ permalink raw reply related
* Re: [PATCH 2/7] builtin/init: simplify logic to configure worktree
From: Justin Tobler @ 2026-06-10 21:29 UTC (permalink / raw)
To: Patrick Steinhardt; +Cc: git
In-Reply-To: <20260610-b4-pks-setup-drop-global-state-v1-2-5dff3eec8f06@pks.im>
On 26/06/10 08:56AM, Patrick Steinhardt wrote:
> In the preceding commit we have stopped modifying the global
> `git_work_tree_cfg` variable. With this change there's now some code
> paths where we end up setting the local `git_work_tree_cfg` variable,
> but without actually using the value for anything.
>
> Refactor the code a bit so that we only set the worktree configuration
> in case it's actually needed. Furthermore, reflow it a bit to make the
> code easier to follow.
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
> builtin/init-db.c | 31 ++++++++++++++++++-------------
> 1 file changed, 18 insertions(+), 13 deletions(-)
>
> diff --git a/builtin/init-db.c b/builtin/init-db.c
> index 01bc27904e..b4343c2804 100644
> --- a/builtin/init-db.c
> +++ b/builtin/init-db.c
> @@ -229,24 +229,29 @@ int cmd_init_db(int argc,
>
> if (!is_bare_repository_cfg) {
> const char *git_dir_parent = strrchr(git_dir, '/');
> - char *git_work_tree_cfg = NULL;
>
> - if (git_dir_parent) {
> - char *rel = xstrndup(git_dir, git_dir_parent - git_dir);
> - git_work_tree_cfg = real_pathdup(rel, 1);
> - free(rel);
> - }
> - if (!git_work_tree_cfg)
> - git_work_tree_cfg = xgetcwd();
> - if (work_tree)
> + if (work_tree) {
> set_git_work_tree(the_repository, work_tree);
Ok, if the worktree is already set via the GIT_WORK_TREE environment
variable, we can just apply it skip everything else.
> - else
> - set_git_work_tree(the_repository, git_work_tree_cfg);
> + } else {
> + char *work_tree_cfg = NULL;
> +
> + if (git_dir_parent) {
> + char *rel = xstrndup(git_dir, git_dir_parent - git_dir);
> + work_tree_cfg = real_pathdup(rel, 1);
> + free(rel);
> + }
> +
> + if (!work_tree_cfg)
> + work_tree_cfg = xgetcwd();
When the environment variable is not set, we try to derive the worktree
from the parent directory of the gitdir. If that doesn't work we
fallback to the current working directory.
This matches previous the previous behavior.
> +
> + set_git_work_tree(the_repository, work_tree_cfg);
> +
> + free(work_tree_cfg);
> + }
Good cleanup. I think this is a bit easier to read too.
-Justin
^ permalink raw reply
* [PATCH] t1400: have fifo test clean after itself
From: Junio C Hamano @ 2026-06-10 21:39 UTC (permalink / raw)
To: git
One test in this script creates a pair of FIFOs, "in" and "out",
that are named so generically that later tests may be tempted to use
them. By the time those later tests run a command with its output
redirected to the file (e.g., "git foobar >out"), however, nobody is
reading from the lingering FIFO, and the test gets blocked forever.
Clean them up when the test finishes.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
t/t1400-update-ref.sh | 1 +
1 file changed, 1 insertion(+)
diff --git a/t/t1400-update-ref.sh b/t/t1400-update-ref.sh
index db7f5444da..477af544bc 100755
--- a/t/t1400-update-ref.sh
+++ b/t/t1400-update-ref.sh
@@ -1610,6 +1610,7 @@ test_expect_success 'transaction cannot restart ongoing transaction' '
'
test_expect_success PIPE 'transaction flushes status updates' '
+ test_when_finished "rm -f in out" &&
mkfifo in out &&
(git update-ref --stdin <in >out &) &&
--
2.54.0-615-g639a4a7340
^ permalink raw reply related
* Re: [PATCH 3/7] setup: remove global `git_work_tree_cfg` variable
From: Justin Tobler @ 2026-06-10 21:52 UTC (permalink / raw)
To: Patrick Steinhardt; +Cc: git
In-Reply-To: <20260610-b4-pks-setup-drop-global-state-v1-3-5dff3eec8f06@pks.im>
On 26/06/10 08:56AM, Patrick Steinhardt wrote:
> The global `git_work_tree_cfg` variable used to be modified by both
> "setup.c" and by "builtin/init-db.c". We have refactored the latter user
> to not use that variable at all anymore in a preceding commit, which
> makes "setup.c" the only remaining user.
>
> Even for "setup.c" it is unnecessary though, as we only ever set it to
> the value we have stored in the discovered repository format. The
> consequence is that we only ever set it in case we already have it set
> to the same value in our discovered repository format, which makes it
> redundant.
Nice. I was wondering in the first patch if there would really be any
need to keep `git_work_tree_cfg` around here at all. Makes sense to me
to just set the repository worktree directly.
> Refactor the code so that we instead use the worktree configuration as
> discovered via the repository format. Drop the global variable.
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
> setup.c | 28 +++++++++++-----------------
> 1 file changed, 11 insertions(+), 17 deletions(-)
>
> diff --git a/setup.c b/setup.c
> index 52228b42a1..71fc6b33da 100644
> --- a/setup.c
> +++ b/setup.c
> @@ -31,9 +31,6 @@ enum allowed_bare_repo {
> ALLOWED_BARE_REPO_ALL,
> };
>
> -/* This is set by setup_git_directory_gently() and/or git_default_config() */
> -static char *git_work_tree_cfg;
> -
> static struct startup_info the_startup_info;
> struct startup_info *startup_info = &the_startup_info;
> const char *tmp_original_cwd;
> @@ -799,13 +796,10 @@ static int check_repository_format_gently(const char *gitdir,
> }
>
> if (!has_common) {
> - if (candidate->is_bare != -1) {
> + if (candidate->is_bare != -1)
> is_bare_repository_cfg = candidate->is_bare;
> - }
> - if (candidate->work_tree) {
> - free(git_work_tree_cfg);
> - git_work_tree_cfg = xstrdup(candidate->work_tree);
Ok, we no longer set `git_work_tree_cfg` in favor of just relying on the
worktree specified in the repository format.
> - }
> + } else {
> + FREE_AND_NULL(candidate->work_tree);
Huh, we were not previously freeing the worktree here, but I assume this
to avoid a resource leak?
The remainder of this patch replaces `git_work_tree_cfg` usage with the
repository format worktree and looks good.
-Justin
^ permalink raw reply
* Re: [PATCH v3 08/11] doc: interpret-trailers: join new-trailers again
From: D. Ben Knoble @ 2026-06-10 22:00 UTC (permalink / raw)
To: kristofferhaugsbakk
Cc: git, Kristoffer Haugsbakk, christian.couder, jackmanb,
Linus Arver
In-Reply-To: <V3_join_paragraphs.8ab@msgid.xyz>
On Wed, Jun 10, 2026 at 5:24 PM <kristofferhaugsbakk@fastmail.com> wrote:
>
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> There are three trailers that talk about how a new trailer is added.
3 "paragraphs"? :)
> But the first one is separated from the other two by two paragraphs
> about how `key-alias` can make using `--trailer` more convenient. This
> short how-to does not follow thematically from the previous paragraph,
> and can wait until we have fully described how a new trailer is
> added. So let’s move the three paragraphs about the new-trailer topic
> together and move the how-to paragraphs after that.
[snip]
^ permalink raw reply
* Re: [PATCH v3 08/11] doc: interpret-trailers: join new-trailers again
From: Kristoffer Haugsbakk @ 2026-06-10 22:13 UTC (permalink / raw)
To: D. Ben Knoble; +Cc: git, Christian Couder, jackmanb, Linus Arver
In-Reply-To: <CALnO6CCg4ubVz_VJuFjn7tvXqADR40AdjCFJ6xfRcms9a+GQWA@mail.gmail.com>
On Thu, Jun 11, 2026, at 00:00, D. Ben Knoble wrote:
> On Wed, Jun 10, 2026 at 5:24 PM <kristofferhaugsbakk@fastmail.com> wrote:
>>
>> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>>
>> There are three trailers that talk about how a new trailer is added.
>
> 3 "paragraphs"? :)
Oh doh! Thanks. ;)
>[snip]
^ permalink raw reply
* Re: [PATCH 5/7] environment: split up concerns of `is_bare_repository_cfg`
From: Justin Tobler @ 2026-06-10 22:22 UTC (permalink / raw)
To: Patrick Steinhardt; +Cc: git
In-Reply-To: <20260610-b4-pks-setup-drop-global-state-v1-5-5dff3eec8f06@pks.im>
On 26/06/10 08:56AM, Patrick Steinhardt wrote:
> The `is_bare_repository_cfg` variable tracks two different pieces of
> information:
>
> - It tracks whether the user has invoked git with the "--bare" flag,
> which makes us treat any discovered Git repository as if it was a
> bare repository.
>
> - Otherwise it tracks whether the discovered `the_repository` is bare.
>
> This makes the flag extremely confusing and creates a bit of a challenge
> when handling multiple repositories in the same process.
Indeed, this does seem rather confusing.
> Split up the concerns of this variable into two pieces:
>
> - `startup_info.force_bare_repository` tracks whether the user has
> passed the "--bare" flag. This is used as a hint to treat newly set
> up repositories as bare regardless of whether or not they have a
> worktree.
>
> - `struct repository::bare_cfg` tracks whether or not a repository is
> considered bare. This takes into account both whether the user has
> passed "--bare" and the discovered state of the repository itself.
>
> Whether or not a repository is bare is now resolved when checking the
> repository's format, and is then later applied to the repository itself
> via `apply_repository_format()`.
Nice. These seem like they should be tracked separately, so splitting
them up sounds like a good idea.
> This enables a subsequent change where we make `is_bare_repository()`
> not depend on global state anymore.
>
> Signed-off-by: Patrick Steinhardt <ps@pks.im>
> ---
> builtin/init-db.c | 2 +-
> environment.c | 5 ++---
> environment.h | 1 -
> git.c | 2 +-
> repository.c | 1 +
> repository.h | 7 +++++++
> setup.c | 21 ++++++++++++++-------
> setup.h | 6 ++++++
> worktree.c | 2 +-
> 9 files changed, 33 insertions(+), 14 deletions(-)
>
> diff --git a/builtin/init-db.c b/builtin/init-db.c
> index 52aa92fb0a..566732c9f4 100644
> --- a/builtin/init-db.c
> +++ b/builtin/init-db.c
> @@ -81,7 +81,7 @@ int cmd_init_db(int argc,
> const char *template_dir = NULL;
> char *template_dir_to_free = NULL;
> unsigned int flags = 0;
> - int bare = is_bare_repository_cfg;
> + int bare = startup_info->force_bare_repository ? 1 : -1;
Any particular reason to continue mapping `force_bare_repository=false`
to -1? Or was this to just minimize changes?
> const char *object_format = NULL;
> const char *ref_format = NULL;
> const char *initial_branch = NULL;
[snip]
> diff --git a/repository.h b/repository.h
> index 36e2db2633..7d649e32e7 100644
> --- a/repository.h
> +++ b/repository.h
> @@ -117,6 +117,13 @@ struct repository {
> bool worktree_initialized;
> bool worktree_config_is_bogus;
>
> + /*
> + * Whether the repository is bare, as set by "core.bare" config or
> + * inferred during repository discovery. -1 means unset/unknown, 0
> + * means non-bare, 1 means bare.
> + */
> + int bare_cfg;
Now we track whether a repository is bare in `struct repository` and
removes the need to a separate global to track this state.
> +
> /*
> * Path from the root of the top-level superproject down to this
> * repository. This is only non-NULL if the repository is initialized
> diff --git a/setup.c b/setup.c
> index 71fc6b33da..2b690da8ca 100644
> --- a/setup.c
> +++ b/setup.c
> @@ -795,10 +795,16 @@ static int check_repository_format_gently(const char *gitdir,
> has_common = 0;
> }
>
> - if (!has_common) {
> - if (candidate->is_bare != -1)
> - is_bare_repository_cfg = candidate->is_bare;
> - } else {
> + if (startup_info->force_bare_repository) {
> + candidate->is_bare = 1;
> + FREE_AND_NULL(candidate->work_tree);
> + } else if (has_common) {
> + /*
> + * When sharing a common dir with another repository (e.g. a
> + * linked worktree), do not let this repository's config
> + * dictate bareness; it is inherited from the main worktree.
> + */
> + candidate->is_bare = -1;
> FREE_AND_NULL(candidate->work_tree);
Previously, when there was a common dir, `candidate->work_tree` was left
untouched, but now we are expclicitly setting it. I'm not sure I fully
understand this change.
-Justin
^ permalink raw reply
* [PATCH 0/6] SubmittingPatches: update and flesh out trailer sections
From: kristofferhaugsbakk @ 2026-06-10 22:22 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Topic name: kh/submitting-patches-trailers
Topic summary: Flesh out and update the trailer sections.
All of these points have come up on the mailing list. At least for me.
And `Based-on-patch-by` is a nice-to-have documented kind of thing.
I have had these lying around since January since I got distracted. I just
wrote this cover letter today. But I think this still makes sense.
[1/6] SubmittingPatches: encourage trailer use for substantial help
[2/6] SubmittingPatches: discuss non-ident trailers
[3/6] SubmittingPatches: discourage common Linux trailers
[4/6] SubmittingPatches: document Based-on-patch-by trailer
[5/6] SubmittingPatches: be consistent with trailer markup
[6/6] SubmittingPatches: note that trailer order matters
Documentation/SubmittingPatches | 46 +++++++++++++++++++++++++--------
1 file changed, 35 insertions(+), 11 deletions(-)
base-commit: 1ff279f3404a482a83fb04c7457e41ab26884aea
--
2.54.0.22.g9e26862b904
^ permalink raw reply
* [PATCH 1/6] SubmittingPatches: encourage trailer use for substantial help
From: kristofferhaugsbakk @ 2026-06-10 22:22 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk
In-Reply-To: <CV_SubPatches_trailers.8f3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Trailers beyond the mandatory s-o-b are regularly used based on my
last two years of reading the mailing list. Moreover, reviewers might
encourage it.[1]
This is also in line with the project crediting both commit authors and
people mentioned in trailers each release; “Nobody is THE one making
contribution”.[2]
Adding trailers is already encouraged, but in the section `send-patches`.
Let’s replace “If you like” with outright encouragment in this section
so that all trailer discussion (except s-o-b; see `sign-off` section) is
contained in this section; a link to from `send-patches` makes this
information equally visible.
Now we need to make a heading for `commit-trailers` in order for the
HTML output to make sense.
At the same, it is important to temper this recommendation to a sign-
ificant enough contribution; in my experience beginners can be eager
to add a trailer for everyone who replies with an action point that is
followed up on.
Let’s also spell out that these trailers should follow the Git author/
committer format. One might naturally just write the name, but in that
case it will not be picked up by:
git shortlog --group=trailer:<key>
and normalization via `.mailmap` will not work.
Also introduce the list of common trailers as such. Granted, this is
already implied by the later paragraph about “create your own trailer”,
so this just frontloads this information.
† 1: https://lore.kernel.org/git/CAP8UFD0POvYDgGtEx8GBhvKkd8XzzWQsy8XxAKL9M3+uz3ka+w@mail.gmail.com/#:~:text=for%20at%20least
† 2: https://lore.kernel.org/git/xmqqzh248sy0.fsf@gitster.c.googlers.com/
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Documentation/SubmittingPatches | 14 +++++++++++---
1 file changed, 11 insertions(+), 3 deletions(-)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 176567738d4..0b12badf86d 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -443,8 +443,16 @@ identifying, and not misleading.
The goal of this policy is to allow us to have sufficient information to contact
you if questions arise about your contribution.
+=== Commit trailers
[[commit-trailers]]
-If you like, you can put extra trailers at the end:
+It is polite to credit people who have helped with your work to a
+substantial enough degree. This project uses commit trailers for that,
+where the credited person is written out like a Git author, i.e. with
+both their name and their email address. Note that the threshold to
+credit someone is a judgement call, and crediting someone for simple
+review work is certainly not necessary.
+
+These are the common trailers in use:
. `Reported-by:` is used to credit someone who found the bug that
the patch attempts to fix.
@@ -562,8 +570,8 @@ when the maintainer did not heavily participate in the discussion and
instead left the review to trusted others.
Do not forget to add trailers such as `Acked-by:`, `Reviewed-by:` and
-`Tested-by:` lines as necessary to credit people who helped your
-patch, and "cc:" them when sending such a final version for inclusion.
+`Tested-by:` (see <<commit-trailers,Commit trailers>>), and "cc:" them
+when sending such a final version for inclusion.
==== `format-patch` and `send-email`
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* [PATCH 2/6] SubmittingPatches: discuss non-ident trailers
From: kristofferhaugsbakk @ 2026-06-10 22:22 UTC (permalink / raw)
To: git; +Cc: Kristoffer Haugsbakk
In-Reply-To: <CV_SubPatches_trailers.8f3@msgid.xyz>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Briefly discuss trailers that do not credit people. This continues the
discussion from the previous commit about using trailers for *people*.
Using non-ident trailers can be relevant. The contributor should just be
encouraged to consider whether it is useful or not.
The larger trend here is to discourage using trailers as a dumping
ground for any kind of metadata in the spirit of “it doesn’t hurt”.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
Documentation/SubmittingPatches | 5 ++++-
1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 0b12badf86d..51c308a89a8 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -474,7 +474,10 @@ These are the common trailers in use:
While you can also create your own trailer if the situation warrants it, we
encourage you to instead use one of the common trailers in this project
-highlighted above.
+highlighted above. A trailer that credits someone might be more likely
+to be accepted since these are the most common ones. But another kind of
+trailer might be relevant, for example to link to an issue tracker
+belonging to a downstream project that is affected by a bug in Git.
Only capitalize the very first letter of the trailer, i.e. favor
"Signed-off-by" over "Signed-Off-By" and "Acked-by:" over "Acked-By".
--
2.54.0.22.g9e26862b904
^ permalink raw reply related
* Re: [PATCH v3 00/11] doc: interpret-trailers: explain key format
From: Junio C Hamano @ 2026-06-10 22:24 UTC (permalink / raw)
To: kristofferhaugsbakk
Cc: git, Kristoffer Haugsbakk, christian.couder, jackmanb,
Linus Arver, D . Ben Knoble
In-Reply-To: <V3_CV_doc_int-tr_key_format.8a3@msgid.xyz>
kristofferhaugsbakk@fastmail.com writes:
> Interdiff against v2:
> diff --git a/Documentation/git-interpret-trailers.adoc b/Documentation/git-interpret-trailers.adoc
> index b42f957d666..d5e856f5d68 100644
> --- a/Documentation/git-interpret-trailers.adoc
> +++ b/Documentation/git-interpret-trailers.adoc
> @@ -60,12 +60,20 @@ are applied to each input and the way any existing trailer in
> the input is changed. They also make it possible to
> automatically add some trailers.
>
> -By default, a `<key>=<value>` or `<key>:<value>` argument given
> -using `--trailer` will be appended after the existing trailers only if
> -the last trailer has a different (_<key>_, _<value>_) pair (or if there
> -is no existing trailer). The _<key>_ and _<value>_ parts will be trimmed
> -to remove starting and trailing whitespace, and the resulting trimmed
> -_<key>_ and _<value>_ will appear in the output like this:
> +Let's consider new trailers added with `--trailer`.
> +By default, the new trailer will appear at the end of the trailer block.
> +Also by default, this new trailer will only be added
> +if the last trailer is different to it.
The new text is more succinct here.
> +A trailer block will be created with only that trailer if a trailer
> +block does not already exist. Recall that a trailer block needs to be
> +preceded by a blank line, so a blank line (specifically an empty line)
> +will be inserted before the new trailer block in that case.
If you want to stress that a line with only whitespaces on it does
not count as a blank line for the purpose of this paragraph, you can
consistently say "an empty line" withotu saying "a blank line", and
you do not need to have "(specifically an empty lline)" there.
> +More concretely, this is how the new trailer is added: a `<key>=<value>`
> +or `<key>:<value>` argument given using `--trailer` will be appended
> +after the existing trailers. The _<key>_ and _<value>_ parts will be
> +trimmed to remove starting and trailing whitespace, and the resulting
> +trimmed _<key>_ and _<value>_ will appear in the output like this:
"More concretely" here feels a bit out of place, as the three paragraphs
we saw so far aren't really progression of the same thing. First we
saw when a new trailer line is added, second we learned that an
extra empty line may be added in addition to the new trailer line.
What we are about to mention is orthogonal: how each trailer line
would look like. There is no more or less concrete about it.
> ------------------------------------------------
> key: value
> @@ -74,6 +82,16 @@ key: value
> This means that the trimmed _<key>_ and _<value>_ will be separated by
> "`:`{nbsp}" (one colon followed by one space).
>
> +Existing trailers are extracted from the input by looking for the
> +trailer block. Concretely, that is a group of one or more lines that (i)
"Concretely, that is a" -> "A trailer block is a".
> +is all trailers, or (ii) contains at least one Git-generated or
> +user-configured trailer and consists of at
> +least 25% trailers.
Hmph, isn't (i) a narrow subset of (ii)?
> +The trailer block is by definition at the end the the message. The end
> +of the message in turn is either (i) at the end of the input, or (ii)
"at the end the the message" -> "at the end of the commit log
message", and "the input" -> "the message", probably.
The latter is because not everybody is "parsing" the message to futz
with trailers, using the message as "input", and some are "writing
out" the message, using it as "output".
> +the last non-whitespace lines before a line that starts with `---`
> +(followed by a space or the end of the line).
OK.
^ permalink raw reply
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox