[PATCH v2] branch: advice using git-help(1) instead of man(1)

From

Kkristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>

Date

Dec 2, 2025, 15:56 UTC

Message-ID

<V2_advice_git-help.53@msgid.xyz>

In-Reply-To

<advice_git-help.64@msgid.xyz>

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    
    Improve commit message by expanding on why we want git-help(1) over man(1)
    according to feedback from <xmqq345yjejo.fsf@gitster.g>.
    
    See this part:
    
    > But git(1) is a multi-platform tool and man(1) may not be available on
    > some platforms.
    
    This is according to the feedback from that email. But is that really true
    when e.g. Git For Windows bundles a Linux subsystem with Git Bash?

 branch.c          | 2 +-
 builtin/branch.c  | 2 +-
 t/t3200-branch.sh | 6 +++---
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/branch.c b/branch.c
index 26be3583471..243db7d0fc0 100644
--- a/branch.c
+++ b/branch.c
@@ -375,7 +375,7 @@ int validate_branchname(const char *name, struct strbuf *ref)
 	if (check_branch_ref(ref, name)) {
 		int code = die_message(_("'%s' is not a valid branch name"), name);
 		advise_if_enabled(ADVICE_REF_SYNTAX,
-				  _("See `man git check-ref-format`"));
+				  _("See 'git help check-ref-format'"));
 		exit(code);
 	}
 
diff --git a/builtin/branch.c b/builtin/branch.c
index 9fcf04bebb2..c577b5d20f2 100644
--- a/builtin/branch.c
+++ b/builtin/branch.c
@@ -591,7 +591,7 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
 		else {
 			int code = die_message(_("invalid branch name: '%s'"), oldname);
 			advise_if_enabled(ADVICE_REF_SYNTAX,
-					  _("See `man git check-ref-format`"));
+					  _("See 'git help check-ref-format'"));
 			exit(code);
 		}
 	}
diff --git a/t/t3200-branch.sh b/t/t3200-branch.sh
index f3e720dc10d..c58e505c43f 100755
--- a/t/t3200-branch.sh
+++ b/t/t3200-branch.sh
@@ -1707,9 +1707,9 @@ test_expect_success '--track overrides branch.autoSetupMerge' '
 '
 
 test_expect_success 'errors if given a bad branch name' '
-	cat <<-\EOF >expect &&
-	fatal: '\''foo..bar'\'' is not a valid branch name
-	hint: See `man git check-ref-format`
+	cat <<-EOF >expect &&
+	fatal: ${SQ}foo..bar${SQ} is not a valid branch name
+	hint: See ${SQ}git help check-ref-format${SQ}
 	hint: Disable this message with "git config set advice.refSyntax false"
 	EOF
 	test_must_fail git branch foo..bar >actual 2>&1 &&

Interdiff against v1:

Range-diff against v1:
1:  057269c683b ! 1:  8904bb016de branch: advice using git-help(1) instead of man(1)
    @@ Commit message
     
         8fbd903e (branch: advise about ref syntax rules, 2024-03-05) added
         an advice about checking git-check-ref-format(1) for the ref syntax
    -    rules. The advice uses man(1). It’s better to use Git’s own git-help(1)
    -    instead of an external command.
    +    rules. The advice uses man(1). But git(1) is a multi-platform tool and
    +    man(1) may not be available on some platforms. It might also be slightly
    +    jarring to see a suggestion for running a command which is not from
    +    the Git suite.
    +
    +    Let’s instead use git-help(1) in order to stay inside the land of
    +    git(1). This also means that `help.format` (for `man`, `html` or other
    +    formats) will be used if set.
     
         Also change to using single quotes (') to quote the command since that
         is more conventional.
    @@ Commit message
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +
    +    Improve commit message by expanding on why we want git-help(1) over man(1)
    +    according to feedback from <xmqq345yjejo.fsf@gitster.g>.
    +
    +    See this part:
    +
    +    > But git(1) is a multi-platform tool and man(1) may not be available on
    +    > some platforms.
    +
    +    This is according to the feedback from that email. But is that really true
    +    when e.g. Git For Windows bundles a Linux subsystem with Git Bash?
    +
      ## branch.c ##
     @@ branch.c: int validate_branchname(const char *name, struct strbuf *ref)
      	if (check_branch_ref(ref, name)) {

base-commit: 9a2fb147f2c61d0cab52c883e7e26f5b7948e3ed

-- 
2.52.0.10.g08704017180