[v2,0/1] advise about ref syntax rules

Message

Kristoffer Haugsbakk March 3, 2024, 6:58 p.m. UTC

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

§ git-replace(1)

I did not add a hint for a similar message in `builtin/replace.c`.

`builtin/replace.c` has an error message in `check_ref_valid` for an
invalid ref name:

```
return error(_("'%s' is not a valid ref name"), ref->buf);
```

But there doesn’t seem to be a point to placing a hint here.

The preceding calls to `repo_get_oid` will catch both missing refs and
existing refs with invalid names:

```
 if (repo_get_oid(r, refname, &object))
	 return error(_("failed to resolve '%s' as a valid ref"), refname);
```

Like for example this:

```
$ printf $(git rev-parse @~) > .git/refs/heads/hello..goodbye
$ git replace @ hello..goodbye
error: failed to resolve 'hello..goodbye' as a valid ref
[…]
$ git replace @ non-existing
error: failed to resolve 'non-existing' as a valid ref
```

§ 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.

§ Changes in v2

• Make the advise optional via configuration
  • At first I thought that this wasn’t needed but I imagine the advice
    could get repetitive for typos and such
• Propagate error properly with `die_message(…)` instead of `exit(1)`
• Flesh out commit message a bit

Kristoffer Haugsbakk (1):
  branch: advise about ref syntax rules

 Documentation/config/advice.txt |  3 +++
 advice.c                        |  1 +
 advice.h                        |  1 +
 branch.c                        |  8 ++++++--
 builtin/branch.c                |  8 ++++++--
 t/t3200-branch.sh               | 11 +++++++++++
 6 files changed, 28 insertions(+), 4 deletions(-)

Comments

Kristoffer Haugsbakk March 3, 2024, 7:10 p.m. UTC | #1

I forgot the range-diff. But turns out it’s empty.