branch: advise about ref syntax rules
git-branch(1) will error out if you give it a bad ref name. But the user might not understand why or what part of the name is illegal. The user might know that there are some limitations based on the *loose ref* format (filenames), but there are also further rules for easier integration with shell-based tools, pathname expansion, and playing well with reference name expressions. The man page for git-check-ref-format(1) contains these rules. Let’s advise about it since that is not a command that you just happen upon. Also make this advise configurable since you might not want to be reminded every time you make a little typo. Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Kristoffer Haugsbakk committed
Mar 5, 2024 at 21:29 UTC
8fbd903e58503cbdd1f1c816dd0c6c3c4d591b13
6 files changed
+27
-4
Documentation/config/advice.txt
+3
@@ -94,6 +94,9 @@ advice.*::
94
`pushNonFFCurrent`, `pushNonFFMatching`, `pushAlreadyExists`,
95
`pushFetchFirst`, `pushNeedsForce`, and `pushRefNeedsUpdate`
96
simultaneously.
97
+ refSyntax::
98
+ Shown when the user provides an illegal ref name, to
99
+ tell the user about the ref syntax documentation.
100
resetNoRefresh::
101
Shown when linkgit:git-reset[1] takes more than 2
102
seconds to refresh the index after reset, to tell the user
advice.c
+1
@@ -68,6 +68,7 @@ static struct {
68
[ADVICE_PUSH_UNQUALIFIED_REF_NAME] = { "pushUnqualifiedRefName" },
69
[ADVICE_PUSH_UPDATE_REJECTED] = { "pushUpdateRejected" },
70
[ADVICE_PUSH_UPDATE_REJECTED_ALIAS] = { "pushNonFastForward" }, /* backwards compatibility */
71
+ [ADVICE_REF_SYNTAX] = { "refSyntax" },
72
[ADVICE_RESET_NO_REFRESH_WARNING] = { "resetNoRefresh" },
73
[ADVICE_RESOLVE_CONFLICT] = { "resolveConflict" },
74
[ADVICE_RM_HINTS] = { "rmHints" },
advice.h
+1
@@ -36,6 +36,7 @@ enum advice_type {
36
ADVICE_PUSH_UNQUALIFIED_REF_NAME,
37
ADVICE_PUSH_UPDATE_REJECTED,
38
ADVICE_PUSH_UPDATE_REJECTED_ALIAS,
39
+ ADVICE_REF_SYNTAX,
40
ADVICE_RESET_NO_REFRESH_WARNING,
41
ADVICE_RESOLVE_CONFLICT,
42
ADVICE_RM_HINTS,
branch.c
+6
-2
@@ -370,8 +370,12 @@ int read_branch_desc(struct strbuf *buf, const char *branch_name)
370
*/
371
int validate_branchname(const char *name, struct strbuf *ref)
372
{
373
- if (strbuf_check_branch_ref(ref, name))
374
- die(_("'%s' is not a valid branch name"), name);
373
+ if (strbuf_check_branch_ref(ref, name)) {
374
+ int code = die_message(_("'%s' is not a valid branch name"), name);
375
+ advise_if_enabled(ADVICE_REF_SYNTAX,
376
+ _("See `man git check-ref-format`"));
377
+ exit(code);
378
+ }
379
380
return ref_exists(ref->buf);
381
}
builtin/branch.c
+6
-2
@@ -576,8 +576,12 @@ static void copy_or_rename_branch(const char *oldname, const char *newname, int
576
*/
577
if (ref_exists(oldref.buf))
578
recovery = 1;
579
- else
580
- die(_("invalid branch name: '%s'"), oldname);
579
+ else {
580
+ int code = die_message(_("invalid branch name: '%s'"), oldname);
581
+ advise_if_enabled(ADVICE_REF_SYNTAX,
582
+ _("See `man git check-ref-format`"));
583
+ exit(code);
584
+ }
585
}
586
587
for (int i = 0; worktrees[i]; i++) {
t/t3200-branch.sh
+10
@@ -1722,4 +1722,14 @@ test_expect_success '--track overrides branch.autoSetupMerge' '
1722
test_cmp_config "" --default "" branch.foo5.merge
1723
'
1724
1725
+test_expect_success 'errors if given a bad branch name' '
1726
+ cat <<-\EOF >expect &&
1727
+ fatal: '\''foo..bar'\'' is not a valid branch name
1728
+ hint: See `man git check-ref-format`
1729
+ hint: Disable this message with "git config advice.refSyntax false"
1730
+ EOF
1731
+ test_must_fail git branch foo..bar >actual 2>&1 &&
1732
+ test_cmp expect actual
1733
+'
1734
+
1735
test_done