* Re: [PATCH] bash-completions: add --max-count-oldest
From: Junio C Hamano @ 2026-06-10 17:08 UTC (permalink / raw)
To: Mirko Faina; +Cc: git
In-Reply-To: <a804828a046d8f12ef0d03eaf014807b079bb707.1781102091.git.mroik@delayed.space>
Mirko Faina <mroik@delayed.space> writes:
> Add missing completion for log --max-count-oldest
>
> Signed-off-by: Mirko Faina <mroik@delayed.space>
> ---
> Unfortunately I forgot to add bash completions.
That's fine. I think it is OK to add a new patch on top of that
series.
^ permalink raw reply
* Re: [PATCH 3/9] setup: don't apply "GIT_REFERENCE_BACKEND" without a repository
From: Junio C Hamano @ 2026-06-10 17:32 UTC (permalink / raw)
To: Patrick Steinhardt; +Cc: git, Karthik Nayak
In-Reply-To: <20260610-b4-pks-refs-avoid-chdir-notify-reparent-v1-3-56c864b01c43@pks.im>
Patrick Steinhardt <ps@pks.im> writes:
> When discovering a repository we eventually also apply the
> "GIT_REFERENCE_BACKEND" environment variable to the repository. There's
> two problems with that:
>
> - We do this unconditionally, which is rather pointless: we really
> only have to configure the repository when we have found one.
>
> - We have already applied the repository format at that point in time,
> so we need to manually reapply it.
Does the second point have a small typo, i.e., "if we have a
repository, we have already applied the ref backend to it when we
discovered it, so NO need to manually reapply"?
> Move the logic around so that we only apply the environment variable
> when a repository was discovered. This also allows us to drop the
> explcit call to `repo_set_ref_storage_format()` because we now adjust
> the format before we apply it via `apply_repository_format()`.
Makes sense.
^ permalink raw reply
* Re: [PATCH v4] remote: qualify "git pull" advice for non-upstream compareBranches
From: Harald Nordgren @ 2026-06-10 17:35 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Harald Nordgren via GitGitGadget, git
In-Reply-To: <xmqq7bo6xuok.fsf@gitster.g>
> > remote: qualify "git pull" advice for non-upstream branches
> >
> > * Don't suggest git pull when we have no good command to suggest.
> > * New test for this. Asserts the behind line shows with no follow-up
> > advice.
>
> Very well written.
>
> What does not happen in the "punt" case (the first bullet point
> above) may deserve to be given in the commit log message, but
> otherwise it is very clear what the change wanted to do to the
> future readers of "git log".
Thanks. It's a good point, but maybe it's implicit that nothing
happens when nothing can happen?
> Shall we mark it for 'next' now?
>
> Thanks for working on this.
Yes please, thanks for all the help!
Harald
^ permalink raw reply
* Re: [PATCH v2] describe: limit default ref iteration to tags
From: Junio C Hamano @ 2026-06-10 17:43 UTC (permalink / raw)
To: Patrick Steinhardt; +Cc: Jeff King, Tamir Duberstein, git
In-Reply-To: <aika_Q0rWhcI6eXR@pks.im>
Patrick Steinhardt <ps@pks.im> writes:
> I very much think that we should and even have to expect that
> contributors adapt, because if we don't we will basically reinforce
> whatever AI is doing right now and increase the load on reviewers even
> more.
>
> I also think that we should reserve the right to reject a patch series
> completely in case we notice that we're basically just talking to a
> middleman that sits between an AI prompt and us (please note that I
> don't refer to this patch series specifically, this is more of a general
> statement).
Sounds sensible. Something like this may make a good starting
point.
diff --git c/Documentation/SubmittingPatches w/Documentation/SubmittingPatches
index 176567738d..2fd7f6f9e6 100644
--- c/Documentation/SubmittingPatches
+++ w/Documentation/SubmittingPatches
@@ -499,6 +499,12 @@ checking for obvious mistakes, things that can be improved, things
that don’t match our style, guidelines or our feedback, before sending
it to us.
+We reserve the right to reject a patch series completely when we
+notice that we are basically just talking to a middleman that sits
+between an AI prompt and us, without having a better understanding of
+the subject matter than the AI agent being used.
+
+
[[git-tools]]
=== Generate your patch using Git tools out of your commits.
^ permalink raw reply related
* Re: [PATCH v2] describe: limit default ref iteration to tags
From: Junio C Hamano @ 2026-06-10 17:45 UTC (permalink / raw)
To: Tamir Duberstein; +Cc: Jeff King, git, Patrick Steinhardt
In-Reply-To: <CAJ-ks9kz5JGFSF21aOhuXfgsJ+5aa5xE69RPT2Vhn-CRGyHZ6A@mail.gmail.com>
Tamir Duberstein <tamird@gmail.com> writes:
> On Tue, Jun 9, 2026 at 4:09 AM Jeff King <peff@peff.net> wrote:
>>
>> Probably not worth re-rolling on its own, though.
>
> The suggested changes seem reasonable to me. Certainly I am happy to
> make them, and re-rolls are cheap. Do let me know explicitly if you'd
> like that done.
Let's see how much more pleasant to read such an updated version ;-)
Thanks.
^ permalink raw reply
* Re: [PATCH] commit-reach: remove get_reachable_subset()
From: Kristofer Karlsson @ 2026-06-10 18:25 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Kristofer Karlsson via GitGitGadget, git, Derrick Stolee
In-Reply-To: <xmqqbjdixupc.fsf@gitster.g>
Junio C Hamano <gitster@pobox.com> writes:
> "should not matter in practice" because...?
>
> And of course the worst case scenario is by definition not a typical
> case that appear in practice, so it does not make a good explanation
> for "should not matter in practice".
You are right, that was hand-wavy. I started with writing a somewhat
long analysis but after finding a clean way of supporting both DFS
and priority queue modes it feels somewhat unnecessary - I will
still include it here, but the short summary is that it's fixable.
Since the prio_queue struct supports both LIFO and heap mode,
it's actually quite easy to plug this into
tips_reachable_from_bases. I just need to switch away from using
the stack structure and pass a mode to choose between LIFO
and heap. This preserves the old behavior while still reducing
the code size and unifying the code more.
I will submit a v2 of the patch shortly.
I will also include the original analysis I wrote before finding
the simple fix.
Thanks for the review!
Kristofer
---
I will refer to the prio_queue approach in get_reachable_subset
as PQ for brevity, and the DFS in tips_reachable_from_bases as
simply DFS.
tips_reachable_from_bases() was designed for --merged queries where
the targets (branches/tags) can be deep ancestors of the base. DFS
is a natural fit there: it dives deep along first-parent quickly,
and with generation numbers the dynamic floor raising prunes
aggressively.
add_missing_tags() has the opposite shape: the bases are branch
tips being pushed (near the top) and the targets are tag commits
the remote does not have yet, which tend to be relatively close
to those tips. PQ ordered by commit date is a better fit here
because it sweeps down from the top and finds nearby targets early,
while DFS might take a long detour down a side branch before
coming back.
With a commit-graph this difference mostly disappears since the
generation floor keeps DFS from going too far off track. Without a
commit-graph, neither approach prunes anything (generation is
GENERATION_NUMBER_INFINITY for all commits) so the traversal order
is the only thing that matters, and PQ has the edge for shallow
targets.
So the current code actually has each caller matched to the
traversal strategy that fits its typical workload. My patch traded
that away for code reduction.
That said, in practice the difference is limited: repositories
large enough for this to matter typically have a commit-graph,
and small repositories are fast either way.
---
^ permalink raw reply
* [PATCH v3] describe: limit default ref iteration to tags
From: Tamir Duberstein @ 2026-06-10 18:50 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano, Jeff King, Patrick Steinhardt, Tamir Duberstein
In-Reply-To: <20260608-describe-tag-ref-scope-v2-1-256fd36dca32@gmail.com>
Without --all, git describe ignores refs outside refs/tags/. Commit
8a5a1884e9 (Avoid accessing non-tag refs in git-describe unless --all is
requested, 2008-02-24) moved this check ahead of object lookup. That
avoided loading objects for irrelevant refs, but the backend still has
to yield every ref before get_name() can reject it.
Pass refs/tags/ to the iterator so the backend can avoid visiting those
refs in the first place.
The new perf test creates 10,000 unrelated packed refs. It measures:
git describe --exact-match HEAD
The runtime drops from 0.03(0.01+0.01) to 0.02(0.00+0.00). In a
repository with 120,532 refs but only 330 tags, the same command went
from 171.7 ms to 9.9 ms.
Signed-off-by: Tamir Duberstein <tamird@gmail.com>
---
Changes in v3:
- Pack the synthetic refs to better match repositories with many refs.
- Generate update-ref input with test_seq -f.
- Shorten the commit message and report the p6100.6 result.
- Link to v2: https://patch.msgid.link/20260608-describe-tag-ref-scope-v2-1-256fd36dca32@gmail.com
Changes in v2:
- Exercise the performance test with both ref backends.
- Keep the ref count local to its setup test.
- Report native hyperfine output for an exact-tag lookup.
- Link to v1: https://patch.msgid.link/20260607-describe-tag-ref-scope-v1-1-653d232b86b5@gmail.com
---
builtin/describe.c | 3 +++
t/perf/p6100-describe.sh | 12 ++++++++++++
2 files changed, 15 insertions(+)
diff --git a/builtin/describe.c b/builtin/describe.c
index 1c47d7c0b7..3532c8ff22 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -740,6 +740,9 @@ int cmd_describe(int argc,
return ret;
}
+ if (!all)
+ for_each_ref_opts.prefix = "refs/tags/";
+
hashmap_init(&names, commit_name_neq, NULL, 0);
refs_for_each_ref_ext(get_main_ref_store(the_repository),
get_name, NULL, &for_each_ref_opts);
diff --git a/t/perf/p6100-describe.sh b/t/perf/p6100-describe.sh
index 069f91ce49..b1c61529bb 100755
--- a/t/perf/p6100-describe.sh
+++ b/t/perf/p6100-describe.sh
@@ -27,4 +27,16 @@ test_perf 'describe HEAD with one tag' '
git describe --match=new HEAD
'
+test_expect_success 'set up many unrelated refs' '
+ ref_count=10000 &&
+ git tag -m tip tip HEAD &&
+ test_seq -f "create refs/heads/describe-perf/%05d HEAD" $ref_count |
+ git update-ref --stdin &&
+ git pack-refs --all
+'
+
+test_perf 'describe exact tag with many unrelated refs' '
+ git describe --exact-match HEAD
+'
+
test_done
---
base-commit: 9ac3f193c05c2237e2b14ebaa1149e9fc8a1abe0
change-id: 20260607-describe-tag-ref-scope-7d00ae140a58
Best regards,
--
Tamir Duberstein <tamird@gmail.com>
^ permalink raw reply related
* [PATCH 2/3] doc: config/sideband: fix typo in adoc markup
From: Tuomas Ahola @ 2026-06-10 18:51 UTC (permalink / raw)
To: git; +Cc: Tuomas Ahola
In-Reply-To: <20260610185148.23920-1-taahol@utu.fi>
Fix a simple typo in AsciiDoc markup.
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
Documentation/config/sideband.adoc | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/config/sideband.adoc b/Documentation/config/sideband.adoc
index 96fade7f5f..06de0d5c07 100644
--- a/Documentation/config/sideband.adoc
+++ b/Documentation/config/sideband.adoc
@@ -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`::
Allow control sequences that move the cursor. This is
disabled by default.
`erase`::
--
2.30.2
^ permalink raw reply related
* [PATCH 3/3] doc: git-config: escape erroneous adoc markup
From: Tuomas Ahola @ 2026-06-10 18:51 UTC (permalink / raw)
To: git; +Cc: Tuomas Ahola
In-Reply-To: <20260610185148.23920-1-taahol@utu.fi>
Paired octothorpes are used in AsciiDoc to mark highlighted text,
<mark> being the equivalent HTML tag. To use the symbol as a literal
character, it can be escaped with a backslash.
Do so in git-config.adoc.
While at it, tweak the text slightly to make it scan better.
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
Documentation/git-config.adoc | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 8439ce97df..708e88cdeb 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -119,10 +119,10 @@ OPTIONS
Append a comment at the end of new or modified lines.
+
If _<message>_ begins with one or more whitespaces followed
-by "#", it is used as-is. If it begins with "#", a space is
+by "\#", it is used as-is. If it begins with "#", a space is
prepended before it is used. Otherwise, a string " # " (a
space followed by a hash followed by a space) is prepended
-to it. And the resulting string is placed immediately after
+to it. The resulting string is placed immediately after
the value defined for the variable. The _<message>_ must
not contain linefeed characters (no multi-line comments are
permitted).
--
2.30.2
^ permalink raw reply related
* [PATCH 0/3] doc: config: fix AsciiDoc glitches
From: Tuomas Ahola @ 2026-06-10 18:51 UTC (permalink / raw)
To: git; +Cc: Tuomas Ahola
Fix various markup shortcomings in git-config(1).
Based on 29bd7ed512 (The second batch, 2026-05-12).
Tuomas Ahola (3):
doc: config: terminate runaway lists
doc: config/sideband: fix typo in adoc markup
doc: git-config: escape erroneous adoc markup
Documentation/config.adoc | 4 +++-
Documentation/config/promisor.adoc | 2 ++
Documentation/config/safe.adoc | 2 ++
Documentation/config/sideband.adoc | 2 +-
Documentation/git-config.adoc | 6 ++++--
5 files changed, 12 insertions(+), 4 deletions(-)
base-commit: 29bd7ed5127255713c1ac2f43b7c6f257d7b4594
--
2.30.2
^ permalink raw reply
* [PATCH 1/3] doc: config: terminate runaway lists
From: Tuomas Ahola @ 2026-06-10 18:51 UTC (permalink / raw)
To: git; +Cc: Tuomas Ahola
In-Reply-To: <20260610185148.23920-1-taahol@utu.fi>
There are many places in git-config(1) where paragraphs that should
logically come after a list are instead appended to the last item of
the list. This is a well-documented quirk of AsciiDoc, and can be
mitigated by enclosing the list in an open block:
--
* first item
* last item
--
+
New paragraph after the list.
Fix the issue accordingly.
Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
Documentation/config.adoc | 4 +++-
Documentation/config/promisor.adoc | 2 ++
Documentation/config/safe.adoc | 2 ++
Documentation/git-config.adoc | 2 ++
4 files changed, 9 insertions(+), 1 deletion(-)
diff --git a/Documentation/config.adoc b/Documentation/config.adoc
index dcea3c0c15..fc48c1c461 100644
--- a/Documentation/config.adoc
+++ b/Documentation/config.adoc
@@ -276,13 +276,15 @@ boolean::
When a variable is said to take a boolean value, many
synonyms are accepted for 'true' and 'false'; these are all
case-insensitive.
-
++
+--
true;; Boolean true literals are `yes`, `on`, `true`,
and `1`. Also, a variable defined without `= <value>`
is taken as true.
false;; Boolean false literals are `no`, `off`, `false`,
`0` and the empty string.
+--
+
When converting a value to its canonical form using the `--type=bool` type
specifier, 'git config' will ensure that the output is "true" or
diff --git a/Documentation/config/promisor.adoc b/Documentation/config/promisor.adoc
index b0fa43b839..39af63dcb8 100644
--- a/Documentation/config/promisor.adoc
+++ b/Documentation/config/promisor.adoc
@@ -63,11 +63,13 @@ If one of these field names (e.g., "token") is being checked for an
advertised promisor remote (e.g., "foo"), three conditions must be met
for the check of this specific field to pass:
+
+--
1. The corresponding local configuration (e.g., `remote.foo.token`)
must be set.
2. The server must advertise the "token" field for remote "foo".
3. The value of the locally configured `remote.foo.token` must exactly
match the value advertised by the server for the "token" field.
+--
+
If any of these conditions is not met for any field name listed in
`promisor.checkFields`, the advertised remote "foo" is rejected.
diff --git a/Documentation/config/safe.adoc b/Documentation/config/safe.adoc
index 2d45c98b12..5ae4476b24 100644
--- a/Documentation/config/safe.adoc
+++ b/Documentation/config/safe.adoc
@@ -2,10 +2,12 @@ safe.bareRepository::
Specifies which bare repositories Git will work with. The currently
supported values are:
+
+--
* `all`: Git works with all bare repositories. This is the default.
* `explicit`: Git only works with bare repositories specified via
the top-level `--git-dir` command-line option, or the `GIT_DIR`
environment variable (see linkgit:git[1]).
+--
+
If you do not use bare repositories in your workflow, then it may be
beneficial to set `safe.bareRepository` to `explicit` in your global
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 00545b2054..8439ce97df 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -221,6 +221,7 @@ Use `--no-value` to unset _<pattern>_.
+
Valid `<type>`'s include:
+
+--
- 'bool': canonicalize values `true`, `yes`, `on`, and positive
numbers as "true", and values `false`, `no`, `off` and `0` as
"false".
@@ -239,6 +240,7 @@ Valid `<type>`'s include:
escape sequence. When setting a value, a sanity-check is performed to ensure
that the given value is canonicalize-able as an ANSI color, but it is written
as-is.
+--
+
If the command is in `list` mode, then the `--type <type>` argument will apply
to each listed config value. If the value does not successfully parse in that
--
2.30.2
^ permalink raw reply related
* Re: [PATCH v2] completion: hide dotfiles for selected path completion
From: Junio C Hamano @ 2026-06-10 18:56 UTC (permalink / raw)
To: Zakariyah Ali via GitGitGadget; +Cc: git, Zakariyah Ali
In-Reply-To: <pull.2311.v2.git.git.1779808987825.gitgitgadget@gmail.com>
"Zakariyah Ali via GitGitGadget" <gitgitgadget@gmail.com> writes:
> -# __git_index_files accepts 1 or 2 arguments:
> +# __git_index_files accepts 1 to 4 arguments:
> # 1: Options to pass to ls-files (required).
> # 2: A directory path (optional).
> # If provided, only files within the specified directory are listed.
> # Sub directories are never recursed. Path must have a trailing
> # slash.
> # 3: List only paths matching this path component (optional).
> +# 4: Hide paths whose first component starts with a dot if this is
> +# "hide-dotfiles" and the third argument is empty (optional).
> __git_index_files ()
> {
> - local root="$2" match="$3"
> + local root="$2" match="$3" hide_dotfiles="${4-}"
> + local hide_dotfiles_awk=0
> + if [ "$hide_dotfiles" = "hide-dotfiles" ] && [ -z "$match" ]; then
> + hide_dotfiles_awk=1
> + fi
>
> __git_ls_files_helper "$root" "$1" "${match:-?}" |
> - awk -F / -v pfx="${2//\\/\\\\}" '{
> + awk -F / -v pfx="${2//\\/\\\\}" -v hide_dotfiles="$hide_dotfiles_awk" '{
> paths[$1] = 1
> }
> END {
> for (p in paths) {
> if (substr(p, 1, 1) != "\"") {
> # No special characters, easy!
> + if (hide_dotfiles == 1 && substr(p, 1, 1) == ".")
> + continue
> print pfx p
> continue
> }
> @@ -675,8 +683,10 @@ __git_index_files ()
> # We have seen the same directory unquoted,
> # skip it.
> continue
> - else
> - print pfx p
> +
> + if (hide_dotfiles == 1 && substr(p, 1, 1) == ".")
> + continue
> + print pfx p
> }
> }
Having to repeat the same thing twice here is a bit unsatisfying,
but that is not a fault of this addition. I suspect that it would
have been simpler to patch if the original were first simplified
into something like:
for (p in paths) {
if (substr(p, 1, 1) == "\"") {
p = dequote(p);
if ((p == "") || (p in paths))
continue
}
print pfx p
}
Then the new "ah, that thing begins with a dot" logic can be added
only once and at an obvious place.
> @@ -2164,7 +2176,7 @@ _git_ls_files ()
>
> # XXX ignore options like --modified and always suggest all cached
> # files.
> - __git_complete_index_file "--cached"
> + __git_complete_index_file "--cached" hide-dotfiles
> }
In this patch, it is hard to tell from the patch what _other_ calls
to the __git_complete_index_file helper lack hide-dotfiles flag
(i.e., they are to show everything including the path that begins
with a dot). I will not try to be exhaustive, but for example
_git_add does not get hide-dotfiles but it is unclear why. The same
for _clean, _commit. But _mv does hide them. The choice seems
arbitrary and incoherent.
A few ideas (some of them may be mutually incompatible)
* Instead of "empty vs hide-dotfiles", perhaps make the 2nd option
mandatory for __git_complete_index_file, e.g., "hide-" vs
"include-" dotfiles, to make it easier to see in the patch which
ones exclude and which ones include dotfiles.
* Extend comments like we saw in the above hunk to say why we treat
files that begin with dot specially.
* Make __git_complete_index_file unconditionally hide the dotfiles
when there is no match pattern for consistency (getting rid of
the need to explay why).
^ permalink raw reply
* Re: [PATCH] commit-reach: remove get_reachable_subset()
From: Derrick Stolee @ 2026-06-10 19:29 UTC (permalink / raw)
To: Junio C Hamano, Kristofer Karlsson via GitGitGadget
Cc: git, Kristofer Karlsson
In-Reply-To: <xmqqbjdixupc.fsf@gitster.g>
On 6/10/2026 11:48 AM, Junio C Hamano wrote:
> "Kristofer Karlsson via GitGitGadget" <gitgitgadget@gmail.com>
> writes:
>
>> get_reachable_subset() was introduced in fcb2c0769d (2018-11-02)
>> for add_missing_tags() in remote.c. tips_reachable_from_bases()
>> was added in cbfe360b14 (2023-03-20) as part of the ahead-behind
>> series. The two were never consolidated.
>
> Good finding. It is curious to see that these were from the same
> author.
I agree. In my defense, these commits are five years apart. I still
should have looked for similar code that could be reused instead of
rolling new code. (But the new code is better when a commit-graph
exists.)
The other thing that I should have done in the later commit was add
the method to the test-tool, which you do here.
>> ... Without generation numbers, some edge cases
>> may be slower with DFS instead of BFS since the date-ordered
>> prio_queue naturally stays near the top of the graph, but this
>> should not matter in practice
>
> "should not matter in practice" because...?
>
>> -- worst case both visit the full
>> graph down from the bases.
>
> And of course the worst case scenario is by definition not a typical
> case that appear in practice, so it does not make a good explanation
> for "should not matter in practice".
It's important to recognize the use cases that call each method and
to understand if it is appropriate to take these performance changes.
Both methods terminate in the case that all potential targets are
found. And that's the only case that matters, as we will walk all
reachable commits in the case of any one commit not being reachable.
Both methods avoid walking below the "minimum generation" among the
target commits.
The key opportunity here is that tips_reachable_from_bases() will
"increase" the minimum generation when it finds the current-minimum
target commit. That's a big reason why the DFS approach wins: it
has the opportunity to find those lower commits without needing to
walk _every_ commit with higher generation.
The one downside to this approach is that the DFS approach does not
take into account the commit date as a fallback when there is no
commit-graph file with computed generation numbers. When there is
no commit-graph file, then the fallback to commit date to break ties
among "generation number infinity" commits can't be used to help the
BFS search in get_reachable_subset().
And perhaps that is the critical reason for the different algorithms:
in 2018 we didn't have the commit-graph for very long so it wasn't a
reasonable expectation that we'd have one, even for large repositories.
Now? The feature is quite stable and it's easy for users to create
and maintain one. All servers are expected to use it for performance
needs. It's probably reasonable to expect that any repos where this
would matter would have one.
Thanks,
-Stolee
^ permalink raw reply
* Re: [PATCH 3/3] doc: git-config: escape erroneous adoc markup
From: Junio C Hamano @ 2026-06-10 19:50 UTC (permalink / raw)
To: Tuomas Ahola; +Cc: git
In-Reply-To: <20260610185148.23920-4-taahol@utu.fi>
Tuomas Ahola <taahol@utu.fi> writes:
> Paired octothorpes are used in AsciiDoc to mark highlighted text,
> <mark> being the equivalent HTML tag. To use the symbol as a literal
> character, it can be escaped with a backslash.
>
> Do so in git-config.adoc.
>
> While at it, tweak the text slightly to make it scan better.
>
> Signed-off-by: Tuomas Ahola <taahol@utu.fi>
> ---
> Documentation/git-config.adoc | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
Thanks.
What we see in
https://git-scm.com/docs/git-config#Documentation/git-config.txt---commentmessage
is rather embarrasing. This would be a vast improvement ;-)
> diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
> index 8439ce97df..708e88cdeb 100644
> --- a/Documentation/git-config.adoc
> +++ b/Documentation/git-config.adoc
> @@ -119,10 +119,10 @@ OPTIONS
> Append a comment at the end of new or modified lines.
> +
> If _<message>_ begins with one or more whitespaces followed
> -by "#", it is used as-is. If it begins with "#", a space is
> +by "\#", it is used as-is. If it begins with "#", a space is
> prepended before it is used. Otherwise, a string " # " (a
> space followed by a hash followed by a space) is prepended
> -to it. And the resulting string is placed immediately after
> +to it. The resulting string is placed immediately after
> the value defined for the variable. The _<message>_ must
> not contain linefeed characters (no multi-line comments are
> permitted).
^ permalink raw reply
* Re: [PATCH 3/3] doc: git-config: escape erroneous adoc markup
From: Junio C Hamano @ 2026-06-10 20:07 UTC (permalink / raw)
To: Tuomas Ahola; +Cc: git
In-Reply-To: <xmqqecieuqdm.fsf@gitster.g>
Junio C Hamano <gitster@pobox.com> writes:
> Thanks.
>
> What we see in
> https://git-scm.com/docs/git-config#Documentation/git-config.txt---commentmessage
> is rather embarrasing. This would be a vast improvement ;-)
>
>> diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
>> index 8439ce97df..708e88cdeb 100644
>> --- a/Documentation/git-config.adoc
>> +++ b/Documentation/git-config.adoc
>> @@ -119,10 +119,10 @@ OPTIONS
>> Append a comment at the end of new or modified lines.
>> +
>> If _<message>_ begins with one or more whitespaces followed
>> -by "#", it is used as-is. If it begins with "#", a space is
>> +by "\#", it is used as-is. If it begins with "#", a space is
>> prepended before it is used. Otherwise, a string " # " (a
With this change, I wonder if this '#' on the next line gets paired
as the closing element that corresponds to the second one on the
previous line, which is not quoted hence can be taken as the opening
element? Even if the one on the second line does not get taken as a
closing element now, if a future change adds some word with '#' that
does, the second "#" on the line left unquoted by this patch would
then require quoting, no? IOW, would it be better to do this
>> -by "#", it is used as-is. If it begins with "#", a space is
>> +by "\#", it is used as-is. If it begins with "\#", a space is
so that we do not have to worry about "special cases" where it
becomes unnecessary to quote "#"s?
>> space followed by a hash followed by a space) is prepended
>> -to it. And the resulting string is placed immediately after
>> +to it. The resulting string is placed immediately after
>> the value defined for the variable. The _<message>_ must
>> not contain linefeed characters (no multi-line comments are
>> permitted).
^ permalink raw reply
* 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
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