format-patch: make boolean and mention in diff-options.adoc

PATCH Applied [email protected] 4 participants 16 messages Feb 18 – Mar 2 Documentation

lore

Share & tools

lore

[email protected]

author

2026-02-18 20:26 UTC #0 lore raw

cover format-patch: make boolean and mention in diff-options.adoc

From: Kristoffer Haugsbakk <[email protected]>

See: https://lore.kernel.org/git/[email protected]/

Topic name: kh/format-noprefix-boolean

Topic summary: The config format.noprefix should act like a boolean. But now it is active no matter what the value is. Change it to act like a boolean like diff.noprefix. Also mention it instead of diff.noprefix in git-format-patch(1) doc.

This is a breaking change. But I have opted to die if the config is not a boolean and just hint about the change. See also Peff’s comment on such a breaking change in that link.

I have also asked here about marking breaking changes:

https://lore.kernel.org/git/[email protected]/T/#ma8856238748d0794a0da6c64e1c0c8a4824b996f

Kristoffer Haugsbakk (2):
format-patch: make format.noprefix a boolean
doc: diff-options.adoc: show format.noprefix for format-patch

 Documentation/diff-options.adoc |  4 +++-
 builtin/log.c                   | 13 ++++++++++++-
 t/t4014-format-patch.sh         | 16 ++++++++++++++++
 3 files changed, 31 insertions(+), 2 deletions(-)

base-commit: 67ad42147a7acc2af6074753ebd03d904476118f

Signature · 1 line

2.53.0.26.g2afa8602a26

[email protected]

author

2026-02-18 20:26 UTC #1 lore raw

PATCH 1/2 format-patch: make format.noprefix a boolean

From: Kristoffer Haugsbakk <[email protected]>

The config format.noprefix was added in 8d5213de (format-patch: add format.noprefix option, 2023-03-09) to support no-prefix on paths. That was immediately after making git-format-patch(1) not respect diff.noprefix.[1]

The intent was to mirror diff.noprefix. But this config was unintentionally[2] implemented by enabling no-prefix if any kind of value is set.

† 1: c169af8f (format-patch: do not respect diff.noprefix, 2023-03-09) † 2: https://lore.kernel.org/all/[email protected]/

Let’s indeed mirror diff.noprefix by treating it as a boolean.

This is a breaking change. And as far as breaking changes go it is pretty benign:

• The documentation claims that this config is equivalent to diff.noprefix; this is just a bug fix if the documentation is what defines the application interface
• Only users with non-boolean values will run into problems when we try to parse it as a boolean. But what would (1) make them suspect they could do that in the first place, and (2) have motivated them to do it?
• Users who have set this to false and expect that to mean *enable format.noprefix* (current behavior) will now have the opposite experience. Which is not a reasonable setup.

Let’s only offer a breaking change fig leaf by hinting about the previous behavior before dying.

Signed-off-by Kristoffer Haugsbakk <[email protected]>

---
 builtin/log.c           | 13 ++++++++++++-
 t/t4014-format-patch.sh | 16 ++++++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)

builtin/log.c +12 -1

index 5c9a8ef3632..e56af7465ae 100644
@@ -1096,7 +1096,18 @@ static int git_format_config(const char *var, const char *value,
 		return 0;
 	}
 	if (!strcmp(var, "format.noprefix")) {
-		format_no_prefix = 1;
+		format_no_prefix = git_parse_maybe_bool(value);
+		if (format_no_prefix < 0) {
+			int status = die_message(
+				_("bad boolean config value '%s' for '%s'"),
+				value, var);
+			fprintf(stderr,
+				_("hint: '%s' used to accept any value but "
+				  "now only\n"
+				  "hint: accepts boolean values, like '%s'\n"),
+				var, "diff.noprefix");
+			exit(status);
+		}
 		return 0;
 	}

t/t4014-format-patch.sh +16 -0

index 21d6d0cd9ef..645ac402a19 100755
@@ -2541,10 +2541,26 @@ test_expect_success 'format-patch respects format.noprefix' '
 	grep "^--- blorp" actual
 '
 
+test_expect_success 'format.noprefix=false' '
+	git -c format.noprefix=false format-patch -1 --stdout >actual &&
+	grep "^--- a/blorp" actual
+'
+
 test_expect_success 'format-patch --default-prefix overrides format.noprefix' '
 	git -c format.noprefix \
 		format-patch -1 --default-prefix --stdout >actual &&
 	grep "^--- a/blorp" actual
 '
 
+test_expect_success 'errors on format.noprefix which is not boolean' '
+	cat >expect <<-EOF &&
+	fatal: bad boolean config value ${SQ}not-a-bool${SQ} for ${SQ}format.noprefix${SQ}
+	hint: ${SQ}format.noprefix${SQ} used to accept any value but now only
+	hint: accepts boolean values, like ${SQ}diff.noprefix${SQ}
+	EOF
+	test_must_fail git -c format.noprefix=not-a-bool \
+		format-patch -1 --stdout 2>actual &&
+	test_cmp expect actual
+'
+
 test_done

Signature · 1 line

2.53.0.26.g2afa8602a26

Junio C Hamano

2026-02-19 18:03 UTC #2 lore raw

Re: [PATCH 1/2] format-patch: make format.noprefix a boolean

Quoted 30 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>
The config format.noprefix was added in 8d5213de (format-patch: add format.noprefix option, 2023-03-09) to support no-prefix on paths. That was immediately after making git-format-patch(1) not respect diff.noprefix.[1]
The intent was to mirror diff.noprefix. But this config was unintentionally[2] implemented by enabling no-prefix if any kind of value is set.
† 1: c169af8f (format-patch: do not respect diff.noprefix, 2023-03-09) † 2: https://lore.kernel.org/all/[email protected]/
Let’s indeed mirror diff.noprefix by treating it as a boolean.
This is a breaking change. And as far as breaking changes go it is pretty benign:
• The documentation claims that this config is equivalent to diff.noprefix; this is just a bug fix if the documentation is what defines the application interface
• Only users with non-boolean values will run into problems when we try to parse it as a boolean. But what would (1) make them suspect they could do that in the first place, and (2) have motivated them to do it?
• Users who have set this to false and expect that to mean *enable format.noprefix* (current behavior) will now have the opposite experience. Which is not a reasonable setup.

Quoted 2 lines

Let’s only offer a breaking change fig leaf by hinting about the previous behavior before dying.

One case that is often problematic is what happens to those who use the same set of configuration variables with different versions of Git, before and after such behaviour change. But I do not think this is such a bad thing. The only reason why they had this variable set (to any value, or to a value-less true) with existing versions of Git is because they wanted to omit the prefixes, so when a new version of Git dies with "Heh, 'nothanks' is not a valid boolean value", they can edit the configuration variable to "1".

And from that point of view, I think the hint given together with the "bad boolean" error can and should be phrased a bit more strongly, i.e.,

builtin/log.c static int git_format_config(const char *var, const char *value, · line 1108

Quoted 10 lines

builtin/log.c +10 -0

+		format_no_prefix = git_parse_maybe_bool(value);
+		if (format_no_prefix < 0) {
+			int status = die_message(
+				_("bad boolean config value '%s' for '%s'"),
+				value, var);
+			fprintf(stderr,
+				_("hint: '%s' used to accept any value but "
+				  "now only\n"
+				  "hint: accepts boolean values, like '%s'\n"),
+				var, "diff.noprefix");

The target audience of this (hint) is those who have set this variable to a non-boolean strring from the existing version of Git, and the only thing they meant to express was "I do not want any prefix", so "we used to accept any value as true, but now accepts only valid boolean values", perhaps? That would nudge those who wrote "[format] noprefix = NoThanks" to rewrite it correctly to "true" or "1", and not "no".

This is a related tangent, but shouldn't this use advise() without configuration? There is no need to allocate an advice_type and use advise_if_enabled(), because correcting a malformed configuration is an action enough to squelch the message.

Quoted 4 lines

builtin/log.c +2 -0

+			exit(status);
+		}
 		return 0;
 	}

Kristoffer Haugsbakk

author

2026-02-23 23:25 UTC #3 lore raw

Re: [PATCH 1/2] format-patch: make format.noprefix a boolean

Quoted 4 lines · Junio C Hamano

Quoted 3 lines
[snip]
Let’s only offer a breaking change fig leaf by hinting about the previous behavior before dying.

Quoted 8 lines

One case that is often problematic is what happens to those who use the same set of configuration variables with different versions of Git, before and after such behaviour change. But I do not think this is such a bad thing. The only reason why they had this variable set (to any value, or to a value-less true) with existing versions of Git is because they wanted to omit the prefixes, so when a new version of Git dies with "Heh, 'nothanks' is not a valid boolean value", they can edit the configuration variable to "1".

Yeah.

I like how this was handled for core.commentString: You can set both core.commentChar and the new config and still be able to run on old versions.

Quoted 15 lines

And from that point of view, I think the hint given together with the "bad boolean" error can and should be phrased a bit more strongly, i.e.,
builtin/log.c static int git_format_config(const char *var, const char *value, · line 1108
Quoted 10 lines
builtin/log.c +10 -0
+		format_no_prefix = git_parse_maybe_bool(value);
+		if (format_no_prefix < 0) {
+			int status = die_message(
+				_("bad boolean config value '%s' for '%s'"),
+				value, var);
+			fprintf(stderr,
+				_("hint: '%s' used to accept any value but "
+				  "now only\n"
+				  "hint: accepts boolean values, like '%s'\n"),
+				var, "diff.noprefix");

Quoted 7 lines

The target audience of this (hint) is those who have set this variable to a non-boolean strring from the existing version of Git, and the only thing they meant to express was "I do not want any prefix", so "we used to accept any value as true, but now accepts only valid boolean values", perhaps? That would nudge those who wrote "[format] noprefix = NoThanks" to rewrite it correctly to "true" or "1", and not "no".

Very true. I’ll change to spell out that any value used to be treated as true.

Right now it just says “used to accept any value”. But not what it means to accept any value...

Quoted 4 lines

This is a related tangent, but shouldn't this use advise() without configuration? There is no need to allocate an advice_type and use advise_if_enabled(), because correcting a malformed configuration is an action enough to squelch the message.

Oh, right. That fits well here.

In hindsight I think I should have used that in 5a312527 (whatchanged:
hint about git-log(1) and aliasing, 2025-09-17).

Jeff King

2026-02-20 12:29 UTC #4 lore raw

Re: [PATCH 1/2] format-patch: make format.noprefix a boolean

In reply to [email protected]

Quoted 14 lines · On Wed, Feb 18, 2026 at 09:26:17PM +0100, [email protected]…

This is a breaking change. And as far as breaking changes go it is pretty benign:
• The documentation claims that this config is equivalent to diff.noprefix; this is just a bug fix if the documentation is what defines the application interface
• Only users with non-boolean values will run into problems when we try to parse it as a boolean. But what would (1) make them suspect they could do that in the first place, and (2) have motivated them to do it?
• Users who have set this to false and expect that to mean *enable format.noprefix* (current behavior) will now have the opposite experience. Which is not a reasonable setup.

Quoted 2 lines

Let’s only offer a breaking change fig leaf by hinting about the previous behavior before dying.

Thanks for following through with this. I probably would not have bothered with even the fig leaf, and just considered it a bug fix. But since you bothered to write it, I don't object.

-Peff

[email protected]

author

2026-02-18 20:27 UTC #5 lore raw

PATCH 2/2 doc: diff-options.adoc: show format.noprefix for format-patch

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

git-format-patch(1) uses format.noprefix and ignores diff.noprefix.

The configuration variable format.prefix was added as an “escape hatch” because “it’s unlikely that anybody really wants format. noprefix=true in the first place.”[1] Based on that there doesn’t seem to be a need to widely advertise this configuration variable.

But in any case: the documentation for this option should not claim that it overrides a config that is always ignored.

† 1: 8d5213de (format-patch: add format.noprefix option, 2023-03-09)

Signed-off-by Kristoffer Haugsbakk <[email protected]>

---

Notes (series):
--default-prefix does override format.noprefix. See test format-patch --default-prefix overrides format.noprefix.

 Documentation/diff-options.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

Documentation/diff-options.adoc +3 -1

index 9cdad6f72a0..8f632d5fe1a 100644
@@ -860,7 +860,9 @@ endif::git-format-patch[]
 
 `--default-prefix`::
 	Use the default source and destination prefixes ("a/" and "b/").
-	This overrides configuration variables such as `diff.noprefix`,
+	This overrides configuration variables such as
+ifndef::git-format-patch[`diff.noprefix`,]
+ifdef::git-format-patch[`format.noprefix`,]
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).

Signature · 1 line

2.53.0.26.g2afa8602a26

Junio C Hamano

Applied

2026-02-19 18:11 UTC #6 lore raw

Re: [PATCH 2/2] doc: diff-options.adoc: show format.noprefix for format-patch

Quoted 29 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>
git-format-patch(1) uses format.noprefix and ignores diff.noprefix.
The configuration variable format.prefix was added as an “escape hatch” because “it’s unlikely that anybody really wants format. noprefix=true in the first place.”[1] Based on that there doesn’t seem to be a need to widely advertise this configuration variable.
But in any case: the documentation for this option should not claim that it overrides a config that is always ignored.
† 1: 8d5213de (format-patch: add format.noprefix option, 2023-03-09)
Signed-off-by Kristoffer Haugsbakk <[email protected]>
---
Notes (series):
--default-prefix does override format.noprefix. See test format-patch --default-prefix overrides format.noprefix.
 Documentation/diff-options.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/diff-options.adoc +0 -0
index 9cdad6f72a0..8f632d5fe1a 100644

Documentation/diff-options.adoc endif::git-format-patch[] · line 867

Quoted 9 lines

Documentation/diff-options.adoc +3 -1

@@ -860,7 +860,9 @@ endif::git-format-patch[]
 
 `--default-prefix`::
 	Use the default source and destination prefixes ("a/" and "b/").
-	This overrides configuration variables such as `diff.noprefix`,
+	This overrides configuration variables such as
+ifndef::git-format-patch[`diff.noprefix`,]
+ifdef::git-format-patch[`format.noprefix`,]
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).

The reasoning makes sense. The ifn?def::*[<something>] syntax is new to our documentation set, but we'll see soon enough how AsciiDoc and Asciidoctor renders them.

Queued. Thanks.

[email protected]

author

2026-02-23 23:31 UTC #7 lore raw

v2 cover format-patch: make boolean and mention in diff-options.adoc

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

See: https://lore.kernel.org/git/[email protected]/

Topic name (applied): kh/format-patch-noprefix-is-boolean

§ Changes in v2

Got feedback from Junio.

Copied from note on Patch 1/2:

• Use advise() for the hint; you get the hint: prefix and color
• Rework the hint, or the advise, to say that any value *used to be* treated as true. That better helps people who maybe set nope when they meant, “no, I don’t want any prefix” (for example)

Also a commit message tweak on Patch 2/2.

§ Link to v1

https://lore.kernel.org/git/[email protected]/

§ Breaking change (unchanged since v1)

This is a breaking change. But I have opted to die if the config is not a boolean and just hint about the change. See also Peff’s comment on such a breaking change in that link.

I have also asked here about marking breaking changes:

https://lore.kernel.org/git/[email protected]/T/#ma8856238748d0794a0da6c64e1c0c8a4824b996f

Kristoffer Haugsbakk (2):
format-patch: make format.noprefix a boolean
doc: diff-options.adoc: show format.noprefix for format-patch

 Documentation/diff-options.adoc |  4 +++-
 builtin/log.c                   | 14 +++++++++++++-
 t/t4014-format-patch.sh         | 16 ++++++++++++++++
 3 files changed, 32 insertions(+), 2 deletions(-)

Interdiff against v1:

builtin/log.c +6 -5

index e56af7465ae..275122b807e 100644
@@ -40,6 +40,7 @@
 #include "mailmap.h"
 #include "progress.h"
 #include "commit-slab.h"
+#include "advice.h"
 
 #include "commit-reach.h"
 #include "range-diff.h"

@@ -1101,11 +1102,11 @@ static int git_format_config(const char *var, const char *value,
 			int status = die_message(
 				_("bad boolean config value '%s' for '%s'"),
 				value, var);
-			fprintf(stderr,
-				_("hint: '%s' used to accept any value but "
-				  "now only\n"
-				  "hint: accepts boolean values, like '%s'\n"),
-				var, "diff.noprefix");
+			advise(_("'%s' used to accept any value and "
+				 "treat that as 'true'.\n"
+				 "Now it only accepts boolean values, "
+				 "like what '%s' does.\n"),
+			       var, "diff.noprefix");
 			exit(status);
 		}
 		return 0;

t/t4014-format-patch.sh +2 -2

index 645ac402a19..c20091e36fe 100755
@@ -2555,8 +2555,8 @@ test_expect_success 'format-patch --default-prefix overrides format.noprefix' '
 test_expect_success 'errors on format.noprefix which is not boolean' '
 	cat >expect <<-EOF &&
 	fatal: bad boolean config value ${SQ}not-a-bool${SQ} for ${SQ}format.noprefix${SQ}
-	hint: ${SQ}format.noprefix${SQ} used to accept any value but now only
-	hint: accepts boolean values, like ${SQ}diff.noprefix${SQ}
+	hint: ${SQ}format.noprefix${SQ} used to accept any value and treat that as ${SQ}true${SQ}.
+	hint: Now it only accepts boolean values, like what ${SQ}diff.noprefix${SQ} does.
 	EOF
 	test_must_fail git -c format.noprefix=not-a-bool \
 		format-patch -1 --stdout 2>actual &&

Range-diff against v1:
1: 49fa161a392 ! 1: eee61561eb3 format-patch: make format.noprefix a boolean

    @@ Commit message
           format.noprefix* (current behavior) will now have the opposite
           experience. Which is not a reasonable setup.
     
    -    Let’s only offer a breaking change fig leaf by hinting about the
    +    Let’s only offer a breaking change fig leaf by advising about the
         previous behavior before dying.
     
         Signed-off-by: Kristoffer Haugsbakk <[email protected]>
     
      ## builtin/log.c ##
    +@@
    + #include "mailmap.h"
    + #include "progress.h"
    + #include "commit-slab.h"
    ++#include "advice.h"
    + 
    + #include "commit-reach.h"
    + #include "range-diff.h"
     @@ builtin/log.c: static int git_format_config(const char *var, const char *value,
      		return 0;
      	}
    @@ builtin/log.c: static int git_format_config(const char *var, const char *value,
     +			int status = die_message(
     +				_("bad boolean config value '%s' for '%s'"),
     +				value, var);
    -+			fprintf(stderr,
    -+				_("hint: '%s' used to accept any value but "
    -+				  "now only\n"
    -+				  "hint: accepts boolean values, like '%s'\n"),
    -+				var, "diff.noprefix");
    ++			advise(_("'%s' used to accept any value and "
    ++				 "treat that as 'true'.\n"
    ++				 "Now it only accepts boolean values, "
    ++				 "like what '%s' does.\n"),
    ++			       var, "diff.noprefix");
     +			exit(status);
     +		}
      		return 0;
    @@ t/t4014-format-patch.sh: test_expect_success 'format-patch respects format.nopre
     +test_expect_success 'errors on format.noprefix which is not boolean' '
     +	cat >expect <<-EOF &&
     +	fatal: bad boolean config value ${SQ}not-a-bool${SQ} for ${SQ}format.noprefix${SQ}
    -+	hint: ${SQ}format.noprefix${SQ} used to accept any value but now only
    -+	hint: accepts boolean values, like ${SQ}diff.noprefix${SQ}
    ++	hint: ${SQ}format.noprefix${SQ} used to accept any value and treat that as ${SQ}true${SQ}.
    ++	hint: Now it only accepts boolean values, like what ${SQ}diff.noprefix${SQ} does.
     +	EOF
     +	test_must_fail git -c format.noprefix=not-a-bool \
     +		format-patch -1 --stdout 2>actual &&

2: 0cef1915a9c ! 2: b9b583bd007 doc: diff-options.adoc: show format.noprefix for format-patch
@@ Commit message
git-format-patch(1) uses format.noprefix and ignores diff.noprefix.

The configuration variable format.prefix was added as an “escape
- hatch” because “it’s unlikely that anybody really wants format.
+ hatch”, and “it’s unlikely that anybody really wants format.
noprefix=true in the first place.”[1] Based on that there doesn’t seem to be a need to widely advertise this configuration variable.

base-commit: 67ad42147a7acc2af6074753ebd03d904476118f

Signature · 1 line

2.53.0.26.g2afa8602a26

[email protected]

author

2026-02-23 23:31 UTC #8 lore raw

PATCH v2 1/2 format-patch: make format.noprefix a boolean

From: Kristoffer Haugsbakk <[email protected]>

The intent was to mirror diff.noprefix. But this config was unintentionally[2] implemented by enabling no-prefix if any kind of value is set.

† 1: c169af8f (format-patch: do not respect diff.noprefix, 2023-03-09) † 2: https://lore.kernel.org/all/[email protected]/

Let’s indeed mirror diff.noprefix by treating it as a boolean.

This is a breaking change. And as far as breaking changes go it is pretty benign:

Let’s only offer a breaking change fig leaf by advising about the previous behavior before dying.

Signed-off-by Kristoffer Haugsbakk <[email protected]>

---

Notes (series):
v2:
• Use advise() for the hint; you get the hint: prefix and color
• Rework the hint, or the advise, to say that any value *used to be* treated as true. That better helps people who maybe set nope when they meant, “no, I don’t want any prefix” (for example)

 builtin/log.c           | 14 +++++++++++++-
 t/t4014-format-patch.sh | 16 ++++++++++++++++
 2 files changed, 29 insertions(+), 1 deletion(-)

builtin/log.c +13 -1

index 5c9a8ef3632..275122b807e 100644
@@ -40,6 +40,7 @@
 #include "mailmap.h"
 #include "progress.h"
 #include "commit-slab.h"
+#include "advice.h"
 
 #include "commit-reach.h"
 #include "range-diff.h"

@@ -1096,7 +1097,18 @@ static int git_format_config(const char *var, const char *value,
 		return 0;
 	}
 	if (!strcmp(var, "format.noprefix")) {
-		format_no_prefix = 1;
+		format_no_prefix = git_parse_maybe_bool(value);
+		if (format_no_prefix < 0) {
+			int status = die_message(
+				_("bad boolean config value '%s' for '%s'"),
+				value, var);
+			advise(_("'%s' used to accept any value and "
+				 "treat that as 'true'.\n"
+				 "Now it only accepts boolean values, "
+				 "like what '%s' does.\n"),
+			       var, "diff.noprefix");
+			exit(status);
+		}
 		return 0;
 	}

t/t4014-format-patch.sh +16 -0

index 21d6d0cd9ef..c20091e36fe 100755
@@ -2541,10 +2541,26 @@ test_expect_success 'format-patch respects format.noprefix' '
 	grep "^--- blorp" actual
 '
 
+test_expect_success 'format.noprefix=false' '
+	git -c format.noprefix=false format-patch -1 --stdout >actual &&
+	grep "^--- a/blorp" actual
+'
+
 test_expect_success 'format-patch --default-prefix overrides format.noprefix' '
 	git -c format.noprefix \
 		format-patch -1 --default-prefix --stdout >actual &&
 	grep "^--- a/blorp" actual
 '
 
+test_expect_success 'errors on format.noprefix which is not boolean' '
+	cat >expect <<-EOF &&
+	fatal: bad boolean config value ${SQ}not-a-bool${SQ} for ${SQ}format.noprefix${SQ}
+	hint: ${SQ}format.noprefix${SQ} used to accept any value and treat that as ${SQ}true${SQ}.
+	hint: Now it only accepts boolean values, like what ${SQ}diff.noprefix${SQ} does.
+	EOF
+	test_must_fail git -c format.noprefix=not-a-bool \
+		format-patch -1 --stdout 2>actual &&
+	test_cmp expect actual
+'
+
 test_done

Signature · 1 line

2.53.0.26.g2afa8602a26

[email protected]

author

2026-02-23 23:31 UTC #9 lore raw

PATCH v2 2/2 doc: diff-options.adoc: show format.noprefix for format-patch

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

git-format-patch(1) uses format.noprefix and ignores diff.noprefix.

The configuration variable format.prefix was added as an “escape hatch”, and “it’s unlikely that anybody really wants format. noprefix=true in the first place.”[1] Based on that there doesn’t seem to be a need to widely advertise this configuration variable.

But in any case: the documentation for this option should not claim that it overrides a config that is always ignored.

† 1: 8d5213de (format-patch: add format.noprefix option, 2023-03-09)

Signed-off-by Kristoffer Haugsbakk <[email protected]>

---

Notes (series):
v2:
Change commit message. Don’t use “because”: the two quotes are not causally linked like that.

v1:
--default-prefix does override format.noprefix. See test format-patch --default-prefix overrides format.noprefix.

 Documentation/diff-options.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

Documentation/diff-options.adoc +3 -1

index 9cdad6f72a0..8f632d5fe1a 100644
@@ -860,7 +860,9 @@ endif::git-format-patch[]
 
 `--default-prefix`::
 	Use the default source and destination prefixes ("a/" and "b/").
-	This overrides configuration variables such as `diff.noprefix`,
+	This overrides configuration variables such as
+ifndef::git-format-patch[`diff.noprefix`,]
+ifdef::git-format-patch[`format.noprefix`,]
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).

Signature · 1 line

2.53.0.26.g2afa8602a26

Jean-Noël Avila

2026-02-27 09:58 UTC #10 lore raw

Re: [PATCH v2 2/2] doc: diff-options.adoc: show format.noprefix for format-patch

Le 24/02/2026 à 00:30, [email protected] a écrit :

Quoted 34 lines

From: Kristoffer Haugsbakk <[email protected]>
git-format-patch(1) uses format.noprefix and ignores diff.noprefix.
The configuration variable format.prefix was added as an “escape hatch”, and “it’s unlikely that anybody really wants format. noprefix=true in the first place.”[1] Based on that there doesn’t seem to be a need to widely advertise this configuration variable.
But in any case: the documentation for this option should not claim that it overrides a config that is always ignored.
† 1: 8d5213de (format-patch: add format.noprefix option, 2023-03-09)
Signed-off-by Kristoffer Haugsbakk <[email protected]>
---
Notes (series):
v2:
Change commit message. Don’t use “because”: the two quotes are not causally linked like that.
v1:
--default-prefix does override format.noprefix. See test format-patch --default-prefix overrides format.noprefix.
 Documentation/diff-options.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
Documentation/diff-options.adoc +0 -0
index 9cdad6f72a0..8f632d5fe1a 100644

Documentation/diff-options.adoc endif::git-format-patch[] · line 868

Quoted 10 lines

Documentation/diff-options.adoc +3 -1

@@ -860,7 +860,9 @@ endif::git-format-patch[]
 
 `--default-prefix`::
 	Use the default source and destination prefixes ("a/" and "b/").
-	This overrides configuration variables such as `diff.noprefix`,
+	This overrides configuration variables such as
+ifndef::git-format-patch[`diff.noprefix`,]
+ifdef::git-format-patch[`format.noprefix`,]
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).

Hello,

This kind of sentence assembly does not fit well with translations. Each hunk of the sentence is processed separately and it is a difficulty for translators as they need to understand the surrounding context of a segment when translating it.

It is safer to just write the whole paragraph, or at least a sentence in the ifdef/ifndef sections.

Thanks

Junio C Hamano

2026-02-27 16:51 UTC #11 lore raw

Re: [PATCH v2 2/2] doc: diff-options.adoc: show format.noprefix for format-patch

Quoted 12 lines · Jean-Noël Avila

Documentation/diff-options.adoc endif::git-format-patch[] · line 867

Quoted 9 lines

--default-prefix::

Documentation/diff-options.adoc +3 -1

 	Use the default source and destination prefixes ("a/" and "b/").
-	This overrides configuration variables such as `diff.noprefix`,
+	This overrides configuration variables such as
+ifndef::git-format-patch[`diff.noprefix`,]
+ifdef::git-format-patch[`format.noprefix`,]
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).

Hello,

Quoted 7 lines

This kind of sentence assembly does not fit well with translations. Each hunk of the sentence is processed separately and it is a difficulty for translators as they need to understand the surrounding context of a segment when translating it.
It is safer to just write the whole paragraph, or at least a sentence in the ifdef/ifndef sections.

Thanks, this particular patch in question is already in 'next', though.

[email protected]

author

2026-02-28 12:21 UTC #12 lore raw

Re: [PATCH v2 2/2] doc: diff-options.adoc: show format.noprefix for format-patch

In reply to Jean-Noël Avila

From: Kristoffer Haugsbakk <[email protected]>

Quoted 15 lines · Jean-Noël Avila

Le 24/02/2026 à 00:30, [email protected] a écrit :

Review

Quoted 11 lines

From: Kristoffer Haugsbakk <[email protected]>
[snip]
--default-prefix::

(quoted diff) +3 -1

 	Use the default source and destination prefixes ("a/" and "b/").
-	This overrides configuration variables such as `diff.noprefix`,
+	This overrides configuration variables such as
+ifndef::git-format-patch[`diff.noprefix`,]
+ifdef::git-format-patch[`format.noprefix`,]
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).

Hello,

Quoted 7 lines

This kind of sentence assembly does not fit well with translations. Each hunk of the sentence is processed separately and it is a difficulty for translators as they need to understand the surrounding context of a segment when translating it.
It is safer to just write the whole paragraph, or at least a sentence in the ifdef/ifndef sections.

Thanks for bringing this up. I have never taken doc translations into consideration.

Would the following be the correct approach?

-- 8< --
From: Kristoffer Haugsbakk <[email protected]>
Subject: [PATCH] doc: diff-options.adoc: make *.noprefix split translatable

We cannot split single words like what we did in the previous commit. That is because the doc translations are processed in bigger chunks.

Instead write the two paragraphs with the only variations being this configuration variable.

It’s not easy to spot the difference here. So let’s leave a comment for translators.

Reported-by Jean-Noël Avila <[email protected]>

Signed-off-by Kristoffer Haugsbakk <[email protected]>

---
 Documentation/diff-options.adoc | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

Documentation/diff-options.adoc +10 -3

index 8f632d5fe1a..e4d02cc93a9 100644
@@ -859,12 +859,19 @@ endif::git-format-patch[]
 	Do not show any source or destination prefix.
 
 `--default-prefix`::
+// TRANSLATORS: format.noprefix / diff.noprefix
+ifdef::git-format-patch[]
 	Use the default source and destination prefixes ("a/" and "b/").
-	This overrides configuration variables such as
-ifndef::git-format-patch[`diff.noprefix`,]
-ifdef::git-format-patch[`format.noprefix`,]
+	This overrides configuration variables such as `format.noprefix`,
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).
+endif::git-format-patch[]
+ifndef::git-format-patch[]
+	Use the default source and destination prefixes ("a/" and "b/").
+	This overrides configuration variables such as `diff.noprefix`,
+	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
+	(see linkgit:git-config[1]).
+ifndef::git-format-patch[]
 
 `--line-prefix=<prefix>`::
 	Prepend an additional _<prefix>_ to every line of output.

base-commit: b9b583bd007ca814ebd362bdd6441aac02e9414b

Signature · 1 line

2.53.0.26.g2afa8602a26

Jean-Noël AVILA

2026-02-28 14:09 UTC #13 lore raw

Re: [PATCH v2 2/2] doc: diff-options.adoc: show format.noprefix for format-patch

Documentation/diff-

Quoted 55 lines · On Saturday, 28 February 2026 13:20:33 CET [email protected]…

From: Kristoffer Haugsbakk <[email protected]>
Quoted 18 lines · Jean-Noël Avila
Quoted 5 lines · Le 24/02/2026 à 00:30, [email protected] a écrit :
From: Kristoffer Haugsbakk <[email protected]>
[snip]
--default-prefix::
Review
Quoted 9 lines
(quoted diff) +3 -1
 	Use the default source and destination prefixes ("a/" and "b/").
 
-	This overrides configuration variables such as `diff.noprefix`,
+	This overrides configuration variables such as
+ifndef::git-format-patch[`diff.noprefix`,]
+ifdef::git-format-patch[`format.noprefix`,]
 
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).
Hello,
Quoted 7 lines
This kind of sentence assembly does not fit well with translations. Each hunk of the sentence is processed separately and it is a difficulty for translators as they need to understand the surrounding context of a segment when translating it.
It is safer to just write the whole paragraph, or at least a sentence in the ifdef/ifndef sections.
Thanks for bringing this up. I have never taken doc translations into consideration.
Would the following be the correct approach?
-- 8< --
From: Kristoffer Haugsbakk <[email protected]>
Subject: [PATCH] doc: diff-options.adoc: make *.noprefix split translatable
We cannot split single words like what we did in the previous commit. That is because the doc translations are processed in bigger chunks.
Instead write the two paragraphs with the only variations being this configuration variable.
It’s not easy to spot the difference here. So let’s leave a comment for translators.
Reported-by Jean-Noël Avila <[email protected]>
Signed-off-by Kristoffer Haugsbakk <[email protected]>
---
 Documentation/diff-options.adoc | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)
Documentation/diff- renamed from Documentation/diff-options.adoc +0 -0

options.adoc

Quoted 13 lines

index 8f632d5fe1a..e4d02cc93a9 100644

Documentation/diff-options.adoc +2 -3

@@ -859,12 +859,19 @@ endif::git-format-patch[]
 	Do not show any source or destination prefix.
 
 `--default-prefix`::
+// TRANSLATORS: format.noprefix / diff.noprefix
+ifdef::git-format-patch[]
 	Use the default source and destination prefixes ("a/" and "b/").
-	This overrides configuration variables such as
-ifndef::git-format-patch[`diff.noprefix`,]
-ifdef::git-format-patch[`format.noprefix`,]

Documentation/diff-options.adoc endif::git-format-patch[] · line 874

Quoted 10 lines

Documentation/diff-options.adoc +8 -0

+	This overrides configuration variables such as `format.noprefix`,
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).
+endif::git-format-patch[]
+ifndef::git-format-patch[]
+	Use the default source and destination prefixes ("a/" and "b/").
+	This overrides configuration variables such as `diff.noprefix`,
+	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
+	(see linkgit:git-config[1]).
+ifndef::git-format-patch[]

I think this line should read : endif::git-format-patch[]
I also don't quite understand the addition of the // TRANSLATORS: part. This is not needed as each paragraph will be translated as a standalone segment.

Otherwise, this format of conditional text is fit for translation.

Thanks

[email protected]

author

2026-03-01 19:22 UTC #14 lore raw

PATCH v2 1/1 doc: diff-options.adoc: make *.noprefix split translatable

In reply to [email protected]

From: Kristoffer Haugsbakk <[email protected]>

We cannot split single words like what we did in the previous commit. That is because the doc translations are processed in bigger chunks.

Instead write the two paragraphs with the only variations being this configuration variable.

Reported-by Jean-Noël Avila <[email protected]>

Signed-off-by Kristoffer Haugsbakk <[email protected]>

---

Notes (series):
Notes to the maintainer: based on topic kh/format-patch-noprefix-is-boolean to fix the issue reported in <[email protected]>

v2:
• fix endif
• Don’t use TRANSLATORS callout

 Documentation/diff-options.adoc | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

Documentation/diff-options.adoc +9 -3

index 8f632d5fe1a..fcfcdf0286e 100644
@@ -859,12 +859,18 @@ endif::git-format-patch[]
 	Do not show any source or destination prefix.
 
 `--default-prefix`::
+ifdef::git-format-patch[]
 	Use the default source and destination prefixes ("a/" and "b/").
-	This overrides configuration variables such as
-ifndef::git-format-patch[`diff.noprefix`,]
-ifdef::git-format-patch[`format.noprefix`,]
+	This overrides configuration variables such as `format.noprefix`,
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).
+endif::git-format-patch[]
+ifndef::git-format-patch[]
+	Use the default source and destination prefixes ("a/" and "b/").
+	This overrides configuration variables such as `diff.noprefix`,
+	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
+	(see linkgit:git-config[1]).
+endif::git-format-patch[]
 
 `--line-prefix=<prefix>`::
 	Prepend an additional _<prefix>_ to every line of output.

Interdiff against v1:
diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc index e4d02cc93a9..fcfcdf0286e 100644
--- a/Documentation/diff-options.adoc
+++ b/Documentation/diff-options.adoc
@@ -859,7 +859,6 @@ endif::git-format-patch[]
Do not show any source or destination prefix.

--default-prefix::
-// TRANSLATORS: format.noprefix / diff.noprefix
ifdef::git-format-patch[]
Use the default source and destination prefixes ("a/" and "b/"). This overrides configuration variables such as format.noprefix,
@@ -871,7 +870,7 @@ ifndef::git-format-patch[]
This overrides configuration variables such as diff.noprefix, diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix (see linkgit:git-config[1]).
-ifndef::git-format-patch[]
+endif::git-format-patch[]

--line-prefix=<prefix>::
Prepend an additional _<prefix>_ to every line of output.

Range-diff against v1:
1: 55e56c90959 ! 1: 07acc52c3bc doc: diff-options.adoc: make *.noprefix split translatable
@@ Commit message
Instead write the two paragraphs with the only variations being this configuration variable.

- It’s not easy to spot the difference here. So let’s leave a comment
- for translators.
-

Reported-by Jean-Noël Avila <[email protected]>

Signed-off-by Kristoffer Haugsbakk <[email protected]>

+
+ ## Notes (series) ##
+ Notes to the maintainer: based on topic kh/format-patch-noprefix-is-boolean
+ to fix the issue reported in <[email protected]>
+
+ v2:
+ • fix endif
+ • Don’t use TRANSLATORS callout
+
## Documentation/diff-options.adoc ##
@@ Documentation/diff-options.adoc: endif::git-format-patch[]
Do not show any source or destination prefix.

--default-prefix::
-+// TRANSLATORS: format.noprefix / diff.noprefix
+ifdef::git-format-patch[]
Use the default source and destination prefixes ("a/" and "b/").
- This overrides configuration variables such as
@@ Documentation/diff-options.adoc: endif::git-format-patch[]
+ This overrides configuration variables such as diff.noprefix,
+ diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix
+ (see linkgit:git-config[1]).
-+ifndef::git-format-patch[]
++endif::git-format-patch[]

--line-prefix=<prefix>::
Prepend an additional _<prefix>_ to every line of output.

base-commit: b9b583bd007ca814ebd362bdd6441aac02e9414b

Signature · 1 line

2.53.0.26.g2afa8602a26

Junio C Hamano

2026-03-02 16:53 UTC #15 lore raw

Re: [PATCH v2] doc: diff-options.adoc: make *.noprefix split translatable

Quoted 13 lines · [email protected] writes:

From: Kristoffer Haugsbakk <[email protected]>
We cannot split single words like what we did in the previous commit. That is because the doc translations are processed in bigger chunks.
Instead write the two paragraphs with the only variations being this configuration variable.
Reported-by Jean-Noël Avila <[email protected]>
Signed-off-by Kristoffer Haugsbakk <[email protected]>
---

Quoted 7 lines

Notes (series):
Notes to the maintainer: based on topic kh/format-patch-noprefix-is-boolean to fix the issue reported in <[email protected]>
v2:
• fix endif
• Don’t use TRANSLATORS callout

Thanks. Looking good. Will queue on top.

Quoted 94 lines

 Documentation/diff-options.adoc | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)
Documentation/diff-options.adoc +9 -3
index 8f632d5fe1a..fcfcdf0286e 100644
@@ -859,12 +859,18 @@ endif::git-format-patch[]
 	Do not show any source or destination prefix.
 
 `--default-prefix`::
+ifdef::git-format-patch[]
 	Use the default source and destination prefixes ("a/" and "b/").
-	This overrides configuration variables such as
-ifndef::git-format-patch[`diff.noprefix`,]
-ifdef::git-format-patch[`format.noprefix`,]
+	This overrides configuration variables such as `format.noprefix`,
 	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
 	(see linkgit:git-config[1]).
+endif::git-format-patch[]
+ifndef::git-format-patch[]
+	Use the default source and destination prefixes ("a/" and "b/").
+	This overrides configuration variables such as `diff.noprefix`,
+	`diff.srcPrefix`, `diff.dstPrefix`, and `diff.mnemonicPrefix`
+	(see linkgit:git-config[1]).
+endif::git-format-patch[]
 
 `--line-prefix=<prefix>`::
 	Prepend an additional _<prefix>_ to every line of output.
Interdiff against v1:
diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc index e4d02cc93a9..fcfcdf0286e 100644
--- a/Documentation/diff-options.adoc
+++ b/Documentation/diff-options.adoc
@@ -859,7 +859,6 @@ endif::git-format-patch[]
Do not show any source or destination prefix.
   `--default-prefix`::
-// TRANSLATORS: format.noprefix / diff.noprefix
ifdef::git-format-patch[]
Use the default source and destination prefixes ("a/" and "b/"). This overrides configuration variables such as format.noprefix,
@@ -871,7 +870,7 @@ ifndef::git-format-patch[]
This overrides configuration variables such as diff.noprefix, diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix (see linkgit:git-config[1]).
-ifndef::git-format-patch[]
+endif::git-format-patch[]
--line-prefix=<prefix>::
Prepend an additional _<prefix>_ to every line of output.
Range-diff against v1:
1: 55e56c90959 ! 1: 07acc52c3bc doc: diff-options.adoc: make *.noprefix split translatable
@@ Commit message
Instead write the two paragraphs with the only variations being this configuration variable.
- It’s not easy to spot the difference here. So let’s leave a comment
- for translators.
-
Reported-by Jean-Noël Avila <[email protected]>
Signed-off-by Kristoffer Haugsbakk <[email protected]>
+
+ ## Notes (series) ##
+ Notes to the maintainer: based on topic kh/format-patch-noprefix-is-boolean
+ to fix the issue reported in <[email protected]>
+
+ v2:
+ • fix endif
+ • Don’t use TRANSLATORS callout
+
## Documentation/diff-options.adoc ##
@@ Documentation/diff-options.adoc: endif::git-format-patch[]
Do not show any source or destination prefix.
--default-prefix::
-+// TRANSLATORS: format.noprefix / diff.noprefix
+ifdef::git-format-patch[]
Use the default source and destination prefixes ("a/" and "b/").
- This overrides configuration variables such as
@@ Documentation/diff-options.adoc: endif::git-format-patch[]
+ This overrides configuration variables such as diff.noprefix,
+ diff.srcPrefix, diff.dstPrefix, and diff.mnemonicPrefix
+ (see linkgit:git-config[1]).
-+ifndef::git-format-patch[]
++endif::git-format-patch[]
--line-prefix=<prefix>::
Prepend an additional _<prefix>_ to every line of output.
base-commit: b9b583bd007ca814ebd362bdd6441aac02e9414b