Solving the ‘Anonymous’ Problem: Customizing Branch Names in Jujutsu VCS
Table of Contents
The Friction of Anonymous Workflows
For most developers, the concept of a ‘branch’ is the foundational unit of work. In Git, you name a branch, you commit to it, and you push it. However, Jujutsu (or jj), the Git-compatible version control system gaining traction among power users, operates on a fundamentally different philosophy: the anonymous branch.
By default, jj encourages a workflow where revisions are tracked by unique IDs rather than explicit names. This removes the cognitive overhead of naming every single tiny change. But a friction point emerges the moment that work leaves the local environment. When pushing a change to a remote Git repository—such as GitHub or GitLab—the ‘anonymous’ nature of the work must vanish. Git requires a name. In jj parlance, these are called ‘bookmarks,’ but to the rest of the world, they are simply branches.
The Problem with ‘push-xyz’
The jj command-line interface attempts to solve this transition with a built-in shorthand. When a user runs jj git push --change [ID], the system automatically generates a branch name. By default, this follows a utilitarian pattern: push-xyz, where ‘xyz’ is the revision ID.
While this is technically efficient, it is functionally opaque. For a developer working in a local CLI, the ID is a useful reference. But once that branch lands on a GitHub pull request page, the context is lost. A list of branches named push-a1b2c3d and push-e5f6g7h provides zero insight into the actual content of the work, forcing the developer to jump back and forth between the remote UI and the local terminal to remember which ID corresponds to which feature or bug fix.
Implementing a ‘Slugify’ Template
The solution lies in jj‘s robust configurability. Rather than accepting the default ID-based naming, developers can leverage template aliases to create dynamic, readable branch names based on the commit description. This involves creating a slugify() function that cleans up the commit message—removing special characters, replacing spaces with hyphens, and ensuring lowercase consistency—to create a URL-friendly string.
By modifying the git_push_bookmark template, the system can be instructed to combine this slugified description with the short version of the change ID. Instead of the cryptic push-ozkspkuyzpwu, the system generates something like add-note-about-jj-bookmark-templates/ozkspkuyzpwu.
This hybrid approach provides the best of both worlds: immediate readability for human collaborators reviewing the code on a web interface, and a persistent link back to the exact revision ID for the developer managing the history in jj.
Scaling for Collaborative Repositories
In a professional team environment, the risk of branch name collisions increases. To mitigate this, the template can be further extended to include a personal namespace. By prefixing the branch name with a username—for example, ddbeck/slugified-description/id—developers can ensure their experimental branches do not clash with colleagues’ work while maintaining a clean, organized remote repository.
There is, however, a technical trade-off. Git’s rules for valid branch names are notoriously complex and restrictive. Custom templates that rely on commit descriptions may occasionally produce a string that Git rejects. In these edge cases, the automated system will fail, requiring the developer to manually name the bookmark. For most, this occasional manual intervention is a small price to pay for a remote history that is actually navigable by humans.
