[v3,0/5] advise about ref syntax rules

Message

Kristoffer Haugsbakk March 4, 2024, 10:07 p.m. UTC

Point the user towards the ref/branch name syntax rules if they give an
invalid name.

Also make some spatially-appropriate improvements:

• Test style
• `advice.txt`

§ git-replace(1)

(see previous cover letter)

§ Alternatives (to this change)

While working on this I also thought that it might be nice to have a
man page `gitrefsyntax`. That one could use a lot of the content from
`man git check-ref-format` verbatim. Then the hint could point towards
that man page. And it seems that AsciiDoc supports _includes_ which
means that the rules don’t have to be duplicated between the two man
pages.

§ CC

For changes to `advice.txt`:

Cc: Elijah Newren <[e-mail]>
Cc: Jean-Noël Avila <[e-mail]>

§ Changes in v3

• New preliminary patches 1–4
  • Fix test style
  • Improvements to `advice.txt` (style consistency and other)
• Patch 5/5:
  • Tweak advice doc for the new entry
  • Better test style

Kristoffer Haugsbakk (5):
  t3200: improve test style
  advice: make all entries stylistically consistent
  advice: use backticks for code
  advice: use double quotes for regular quoting
  branch: advise about ref syntax rules

 Documentation/config/advice.txt |  91 ++++++++++++-----------
 advice.c                        |   1 +
 advice.h                        |   1 +
 branch.c                        |   8 +-
 builtin/branch.c                |   8 +-
 t/t3200-branch.sh               | 125 +++++++++++++++++---------------
 6 files changed, 127 insertions(+), 107 deletions(-)

Range-diff against v2:
-:  ----------- > 1:  e6a2628ce57 t3200: improve test style
-:  ----------- > 2:  d48b4719c27 advice: make all entries stylistically consistent
-:  ----------- > 3:  30d662a04c7 advice: use backticks for code
-:  ----------- > 4:  3028713357f advice: use double quotes for regular quoting
1:  4ad5d419064 ! 5:  402b7937951 branch: advise about ref syntax rules
    @@ Commit message
     
     
      ## Notes (series) ##
    +    v3:
    +    • Tweak advice doc for the new entry
    +    • Better test style
         v2:
         • Make the advise optional via configuration
         • Propagate error properly with `die_message(…)` instead of `exit(1)`
    @@ Notes (series)
     
      ## Documentation/config/advice.txt ##
     @@ Documentation/config/advice.txt: advice.*::
    - 		'pushNonFFCurrent', 'pushNonFFMatching', 'pushAlreadyExists',
    - 		'pushFetchFirst', 'pushNeedsForce', and 'pushRefNeedsUpdate'
    + 		`pushNonFFCurrent`, `pushNonFFMatching`, `pushAlreadyExists`,
    + 		`pushFetchFirst`, `pushNeedsForce`, and `pushRefNeedsUpdate`
      		simultaneously.
     +	refSyntax::
    -+		Point the user towards the ref syntax documentation if
    -+		they give an invalid ref name.
    ++		Shown when the user provides an illegal ref name: point
    ++		towards the ref syntax documentation.
      	resetNoRefresh::
    - 		Advice to consider using the `--no-refresh` option to
    - 		linkgit:git-reset[1] when the command takes more than 2 seconds
    + 		Shown when linkgit:git-reset[1] takes more than 2
    + 		seconds to refresh the index after reset: tell the user
     
      ## advice.c ##
     @@ advice.c: static struct {
    @@ t/t3200-branch.sh: test_expect_success '--track overrides branch.autoSetupMerge'
      	test_cmp_config "" --default "" branch.foo5.merge
      '
      
    -+cat <<\EOF >expect
    -+fatal: 'foo..bar' is not a valid branch name
    -+hint: See `man git check-ref-format`
    -+hint: Disable this message with "git config advice.refSyntax false"
    -+EOF
    -+
     +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`
    ++	hint: Disable this message with "git config advice.refSyntax false"
    ++	EOF
     +	test_must_fail git branch foo..bar >actual 2>&1 &&
     +	test_cmp expect actual
     +'