On Mon, Aug 14, 2023 at 04:51:15PM +0200, Christian Weisgerber wrote:
> What's the suggested way to "bookmark" a commit, so I can refer to it
> symbolically?  In Git terms, a lightweight tag?
> 
> Got tag only supports annotated tags.
> 
> Obviously I want to use "ref" to create a reference.  But in which
> namespace?  ref/tags/?

The namespace is entirely up to you.
You can use an arbitrary namespace, such as refs/bookmarks/.

There are some conventions which Got is using, such as refs/heads/ for
branch tips, refs/tags/ for refs pointing at tag objects, refs/got/ for
internal use, and so on. Just avoid clashes with those and it should
be fine.

> While I'm here... The man page says:
>   When creating, deleting, or changing a reference the specified
>   name must be an absolute reference name, i.e. it must begin with
>   "refs/".
> 
> That's not true for creation:
> 
> $ got ref -c 1fa342e146 tags/test
> $ got ref -l | grep test
> refs/tags/test: 1fa342e146980bc77bb33395ec4479ec0476a41c
> $ got ref -d tags/test            
> got: reference tags/test not found
> $ got ref -d refs/tags/test
> Deleted refs/tags/test: 1fa342e146980bc77bb33395ec4479ec0476a41c
> 
> Actually, it's not quite true for deletion either:
> 
> $ got ref -c 270e791 tags/good-ssh
> $ got ref -l | fgrep good-ssh
> refs/tags/good-ssh: 270e7910b4a1ddab7cd96da8494e4279dc41aaff
> $ got ref -d good-ssh         
> Deleted refs/tags/good-ssh: 270e7910b4a1ddab7cd96da8494e4279dc41aaff

The man page is outdated. Or maybe it has always been wrong.
There is some magic at the beginning of got_ref_write() (creation) and
got_ref_open() (deletion) involving get_refs_dir_path(). Which normalizes
the reference name, prepending a "refs/" prefix if it doesn't exist yet.