Mercurial's branching model is more complex than Git's; it allows for multiple heads per branch, closed heads and bookmarks. Since the current snapshot model is Git-centric and would require a large re-work (that we may not have the necessary perspective for yet), we need to define a naming scheme to map Mercurial "pointers" to Git refs.
I propose the following [updated 2021-06-03]:
- HEAD [required] either the node pointed by the @ bookmark or the tip of default branch
- branch-tip/<branch-name> [required] the tipmost head of each open branch
- bookmarks/<bookmark_name> [optional] hold the bookmark mapping if any
- branch-heads/<branch_name>/0..n [optional] for any branch with multiple open head, list all open heads
- branch-closed-heads/<branch_name>/0..n [optional] for any branch with at least one closed head, list all closed heads
- tags/<tag-name> [optional] record tags
The format is not ambiguous regardless of branch name since we know it ends with a /<index>, as long as we have a stable sorting of the heads.
There may be some overlap between the refs, but it's simpler not to try to figure out de-duplication (and frankly I don't really see the point of trying). However, we want to optimize for simplicity in the most common case : only tip is required, since it's always present in a repository. We will not store branch heads for repositories with only one branch (since its head is tip), and bookmarks or closed heads will of course be populated only if they exist within that repository.