{"thread":{"id":"64544","subject":"[PATCH] branch: advice using git-help(1) instead of man(1)","startedAt":"2025-11-28T12:54:52Z","lastAt":"2025-12-02T15:57:18Z","messageCount":5,"participants":["kristofferhaugsbakk@fastmail.com","Junio C Hamano","Kristoffer Haugsbakk"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"531397","messageId":"advice_git-help.64@msgid.xyz","threadId":"64544","inReplyTo":null,"subject":"[PATCH] branch: advice using git-help(1) instead of man(1)","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-11-28T12:54:29Z","receivedAt":"2025-11-28T12:54:52Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\n8fbd903e (branch: advise about ref syntax rules, 2024-03-05) added\nan advice about checking git-check-ref-format(1) for the ref syntax\nrules. The advice uses man(1). It’s better to use Git’s own git-help(1)\ninstead of an external command.\n\nAlso change to using single quotes (') to quote the command since that\nis more conventional.\n\nWhile here let’s also update the test to use `{SQ}`, which is more\nreadable and easier to edit.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n branch.c | 2 +-\n builtin/branch.c | 2 +-\n t/t3200-branch.sh | 6 +++---\n 3 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/branch.c b/branch.c\nindex 26be3583471..243db7d0fc0 100644\n--- a/branch.c\n+++ b/branch.c\n@@ -375,7 +375,7 @@ int validate_branchname(const char *name, struct strbuf *ref)\n \tif (check_branch_ref(ref, name)) {\n \t\tint code = die_message(_(\"'%s' is not a valid branch name\"), name);\n \t\tadvise_if_enabled(ADVICE_REF_SYNTAX,\n-\t\t\t\t _(\"See `man git check-ref-format`\"));\n+\t\t\t\t _(\"See 'git help check-ref-format'\"));\n \t\texit(code);\n \t}\n \ndiff --git a/builtin/branch.c b/builtin/branch.c\nindex 9fcf04bebb2..c577b5d20f2 100644\n--- a/builtin/branch.c\n+++ b/builtin/branch.c\n@@ -591,7 +591,7 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int\n \t\telse {\n \t\t\tint code = die_message(_(\"invalid branch name: '%s'\"), oldname);\n \t\t\tadvise_if_enabled(ADVICE_REF_SYNTAX,\n-\t\t\t\t\t _(\"See `man git check-ref-format`\"));\n+\t\t\t\t\t _(\"See 'git help check-ref-format'\"));\n \t\t\texit(code);\n \t\t}\n \t}\ndiff --git a/t/t3200-branch.sh b/t/t3200-branch.sh\nindex f3e720dc10d..c58e505c43f 100755\n--- a/t/t3200-branch.sh\n+++ b/t/t3200-branch.sh\n@@ -1707,9 +1707,9 @@ test_expect_success '--track overrides branch.autoSetupMerge' '\n '\n \n test_expect_success 'errors if given a bad branch name' '\n-\tcat <<-\\EOF >expect &&\n-\tfatal: '\\''foo..bar'\\'' is not a valid branch name\n-\thint: See `man git check-ref-format`\n+\tcat <<-EOF >expect &&\n+\tfatal: ${SQ}foo..bar${SQ} is not a valid branch name\n+\thint: See ${SQ}git help check-ref-format${SQ}\n \thint: Disable this message with \"git config set advice.refSyntax false\"\n \tEOF\n \ttest_must_fail git branch foo..bar >actual 2>&1 &&\n\nbase-commit: 9a2fb147f2c61d0cab52c883e7e26f5b7948e3ed\n-- \n2.52.0.10.g08704017180\n\n"},{"id":"531403","messageId":"xmqq345yjejo.fsf@gitster.g","threadId":"64544","inReplyTo":"advice_git-help.64@msgid.xyz","subject":"Re: [PATCH] branch: advice using git-help(1) instead of man(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-11-28T16:40:59Z","receivedAt":"2025-11-28T16:41:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"kristofferhaugsbakk@fastmail.com writes:\n\n> From: Kristoffer Haugsbakk \n>\n> 8fbd903e (branch: advise about ref syntax rules, 2024-03-05) added\n> an advice about checking git-check-ref-format(1) for the ref syntax\n> rules. The advice uses man(1). It’s better to use Git’s own git-help(1)\n> instead of an external command.\n\nSubstatiate \"better\" a bit better? If there were a universal help\nfacility, we wouldn't have had to invent our own, and that would\nhave been even better, but since we do not live in such an ideal\nworld, we cater to people who live in a man-less land by having our\nown.\n\nIn other words, \"An external command\" is not the issue. Some people\nliving in a man-less land is.\n\n ... for the ref syntax rules and refers to the man(1) command,\n which may not be available on some platforms. Refer to 'git\n help' instead.\n\n> Also change to using single quotes (') to quote the command since that\n> is more conventional.\n\nYup. We haven't added markdown or asciidoc interpreter to our\nadvise() machinery ;-)\n\n"},{"id":"531419","messageId":"xmqqcy51iotc.fsf@gitster.g","threadId":"64544","inReplyTo":"xmqq345yjejo.fsf@gitster.g","subject":"Re: [PATCH] branch: advice using git-help(1) instead of man(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-11-29T01:56:47Z","receivedAt":"2025-11-29T01:56:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> In other words, \"An external command\" is not the issue. Some people\n> living in a man-less land is.\n\nAnother is that a user with access to \"man\" may prefer \"html\" (with\n\"git help -w\" or \"help.format\"). So this is only ...\n\n> ... for the ref syntax rules and refers to the man(1) command,\n> which may not be available on some platforms. Refer to 'git\n> help' instead.\n\n... half a story.\n\n ... which may not be available on some platforms, or which the\n user may prefer less. Refer to 'git help' instead.\n"},{"id":"531561","messageId":"de40b6b8-c110-43ae-aff2-84abbc2948dd@app.fastmail.com","threadId":"64544","inReplyTo":"xmqq345yjejo.fsf@gitster.g","subject":"Re: [PATCH] branch: advice using git-help(1) instead of man(1)","fromName":"Kristoffer Haugsbakk","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-02T15:28:23Z","receivedAt":"2025-12-02T15:28:44Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"On Fri, Nov 28, 2025, at 17:40, Junio C Hamano wrote:\n> kristofferhaugsbakk@fastmail.com writes:\n>\n>> From: Kristoffer Haugsbakk \n>>\n>> 8fbd903e (branch: advise about ref syntax rules, 2024-03-05) added\n>> an advice about checking git-check-ref-format(1) for the ref syntax\n>> rules. The advice uses man(1). It’s better to use Git’s own git-help(1)\n>> instead of an external command.\n>\n> Substatiate \"better\" a bit better? If there were a universal help\n> facility, we wouldn't have had to invent our own, and that would\n> have been even better, but since we do not live in such an ideal\n> world, we cater to people who live in a man-less land by having our\n> own.\n>\n> In other words, \"An external command\" is not the issue. Some people\n> living in a man-less land is.\n>\n> ... for the ref syntax rules and refers to the man(1) command,\n> which may not be available on some platforms. Refer to 'git\n> help' instead.\n\nI thought that’s what I did. This is output from git(1), not from a\nDebian/Ubuntu/Arch Linux distribution.\n\nBut people who only use Mac/Linux/(BSDs?) might not necessarily consider\nthis point. So I’ll make it clearer.\n"},{"id":"531564","messageId":"V2_advice_git-help.53@msgid.xyz","threadId":"64544","inReplyTo":"advice_git-help.64@msgid.xyz","subject":"[PATCH v2] branch: advice using git-help(1) instead of man(1)","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-12-02T15:56:51Z","receivedAt":"2025-12-02T15:57:18Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk \n\n8fbd903e (branch: advise about ref syntax rules, 2024-03-05) added\nan advice about checking git-check-ref-format(1) for the ref syntax\nrules. The advice uses man(1). But git(1) is a multi-platform tool and\nman(1) may not be available on some platforms. It might also be slightly\njarring to see a suggestion for running a command which is not from\nthe Git suite.\n\nLet’s instead use git-help(1) in order to stay inside the land of\ngit(1). This also means that `help.format` (for `man`, `html` or other\nformats) will be used if set.\n\nAlso change to using single quotes (') to quote the command since that\nis more conventional.\n\nWhile here let’s also update the test to use `{SQ}`, which is more\nreadable and easier to edit.\n\nSigned-off-by: Kristoffer Haugsbakk \n---\n\nNotes (series):\n v2:\n \n Improve commit message by expanding on why we want git-help(1) over man(1)\n according to feedback from .\n \n See this part:\n \n > But git(1) is a multi-platform tool and man(1) may not be available on\n > some platforms.\n \n This is according to the feedback from that email. But is that really true\n when e.g. Git For Windows bundles a Linux subsystem with Git Bash?\n\n branch.c | 2 +-\n builtin/branch.c | 2 +-\n t/t3200-branch.sh | 6 +++---\n 3 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/branch.c b/branch.c\nindex 26be3583471..243db7d0fc0 100644\n--- a/branch.c\n+++ b/branch.c\n@@ -375,7 +375,7 @@ int validate_branchname(const char *name, struct strbuf *ref)\n \tif (check_branch_ref(ref, name)) {\n \t\tint code = die_message(_(\"'%s' is not a valid branch name\"), name);\n \t\tadvise_if_enabled(ADVICE_REF_SYNTAX,\n-\t\t\t\t _(\"See `man git check-ref-format`\"));\n+\t\t\t\t _(\"See 'git help check-ref-format'\"));\n \t\texit(code);\n \t}\n \ndiff --git a/builtin/branch.c b/builtin/branch.c\nindex 9fcf04bebb2..c577b5d20f2 100644\n--- a/builtin/branch.c\n+++ b/builtin/branch.c\n@@ -591,7 +591,7 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int\n \t\telse {\n \t\t\tint code = die_message(_(\"invalid branch name: '%s'\"), oldname);\n \t\t\tadvise_if_enabled(ADVICE_REF_SYNTAX,\n-\t\t\t\t\t _(\"See `man git check-ref-format`\"));\n+\t\t\t\t\t _(\"See 'git help check-ref-format'\"));\n \t\t\texit(code);\n \t\t}\n \t}\ndiff --git a/t/t3200-branch.sh b/t/t3200-branch.sh\nindex f3e720dc10d..c58e505c43f 100755\n--- a/t/t3200-branch.sh\n+++ b/t/t3200-branch.sh\n@@ -1707,9 +1707,9 @@ test_expect_success '--track overrides branch.autoSetupMerge' '\n '\n \n test_expect_success 'errors if given a bad branch name' '\n-\tcat <<-\\EOF >expect &&\n-\tfatal: '\\''foo..bar'\\'' is not a valid branch name\n-\thint: See `man git check-ref-format`\n+\tcat <<-EOF >expect &&\n+\tfatal: ${SQ}foo..bar${SQ} is not a valid branch name\n+\thint: See ${SQ}git help check-ref-format${SQ}\n \thint: Disable this message with \"git config set advice.refSyntax false\"\n \tEOF\n \ttest_must_fail git branch foo..bar >actual 2>&1 &&\n\nInterdiff against v1:\n\nRange-diff against v1:\n1: 057269c683b ! 1: 8904bb016de branch: advice using git-help(1) instead of man(1)\n @@ Commit message\n \n 8fbd903e (branch: advise about ref syntax rules, 2024-03-05) added\n an advice about checking git-check-ref-format(1) for the ref syntax\n - rules. The advice uses man(1). It’s better to use Git’s own git-help(1)\n - instead of an external command.\n + rules. The advice uses man(1). But git(1) is a multi-platform tool and\n + man(1) may not be available on some platforms. It might also be slightly\n + jarring to see a suggestion for running a command which is not from\n + the Git suite.\n +\n + Let’s instead use git-help(1) in order to stay inside the land of\n + git(1). This also means that `help.format` (for `man`, `html` or other\n + formats) will be used if set.\n \n Also change to using single quotes (') to quote the command since that\n is more conventional.\n @@ Commit message\n \n Signed-off-by: Kristoffer Haugsbakk \n \n +\n + ## Notes (series) ##\n + v2:\n +\n + Improve commit message by expanding on why we want git-help(1) over man(1)\n + according to feedback from .\n +\n + See this part:\n +\n + > But git(1) is a multi-platform tool and man(1) may not be available on\n + > some platforms.\n +\n + This is according to the feedback from that email. But is that really true\n + when e.g. Git For Windows bundles a Linux subsystem with Git Bash?\n +\n ## branch.c ##\n @@ branch.c: int validate_branchname(const char *name, struct strbuf *ref)\n \tif (check_branch_ref(ref, name)) {\n\nbase-commit: 9a2fb147f2c61d0cab52c883e7e26f5b7948e3ed\n-- \n2.52.0.10.g08704017180\n\n"}]}