Improving Branch Name Generation in Jujutsu with Custom Templates

The jj version control system, also known as Jujutsu, represents an interesting evolution in version control tools, offering a Git-compatible alternative with its own philosophical approach to branching and merging. While many users appreciate jj's design choices, particularly its emphasis on anonymous branches, the default branch name generation when pushing to Git repositories leaves something to be desired. The default format of push-xyz, where xyz represents a change ID, prioritizes technical precision over human readability, creating challenges when browsing branches on platforms like GitHub.

The core issue lies in the tension between jj's internal representation of changes and the external naming conventions required by Git. When working with jj locally, change IDs serve as precise references for operations. However, when pushing to a shared Git repository, these identifiers become less meaningful to collaborators who may not be familiar with the specific changes or their context. The resulting branch names become opaque references rather than self-documenting descriptions of work.

The solution presented involves creating a custom template alias called slugify() that transforms a change's description into a more readable format. This approach leverages jj's powerful templating system to generate branch names that balance human readability with technical utility. The implementation involves several text processing steps:

1. Extracting the first line of the change description
2. Replacing special characters with hyphens
3. Normalizing consecutive hyphens and periods
4. Trimming hyphens from the beginning and end
5. Converting to lowercase
6. Truncating to 65 characters to maintain reasonable length

The resulting template combines this slugified description with the shortened change ID, creating branch names like add-note-about-jj-bookmark-templates/ozkspkuyzpwu. This format preserves the link back to the revision ID that appears in the jj command-line interface while providing immediate context about the nature of the change.

For collaborative environments, the template can be further customized to include a personal namespace, prefixing branch names with something like ddbeck/ to clearly indicate ownership. This simple addition prevents namespace conflicts when multiple team members use similar naming conventions.

The technical implementation showcases jj's extensibility through its template system. The slugify() function demonstrates how complex text transformations can be encapsulated in reusable components, making it straightforward to apply consistent formatting across different contexts. The template system represents one of jj's most powerful features, allowing users to customize various aspects of the tool's output and behavior to match their specific workflows and preferences.

This improvement in branch name generation addresses a significant usability gap in jj's workflow. By making branch names more descriptive and self-documenting, the tool becomes more accessible to team members who may not be deeply familiar with every change. The approach maintains jj's commitment to precise change tracking while bridging the gap between the internal representation of changes and the external naming conventions required for collaboration.

However, the solution as presented doesn't address Git's complex rules for valid branch names. Git imposes certain restrictions on branch names, such as prohibiting certain characters and requiring that names don't start with a dot or contain consecutive dots. The current template might generate invalid branch names in some cases, potentially requiring manual intervention to create bookmarks when conflicts arise.

A more robust implementation might include additional validation or sanitization steps to ensure compatibility with Git's naming requirements. This could involve checking for reserved names, handling edge cases with special characters, or providing fallback mechanisms when the slugified result would be invalid.

Beyond the specific technical solution, this example highlights an important aspect of modern version control tools: the increasing emphasis on configurability and extensibility. As development workflows become more diverse, tools that can adapt to different team preferences and processes gain a significant advantage. jj's template system represents one approach to this flexibility, allowing users to mold the tool to their specific needs rather than forcing users to adapt to the tool's rigid design.

For teams considering adopting jj or similar version control systems, this example serves as an instructive case study in tool customization. It demonstrates how even small improvements in user experience can have significant impacts on day-to-day productivity and collaboration effectiveness. The ability to transform opaque technical identifiers into meaningful, human-readable labels represents a valuable enhancement to any version control workflow.

The broader implications of this customization extend beyond branch naming. They touch on fundamental questions about how version control systems can balance technical precision with human usability. As these tools continue to evolve, we may see more sophisticated approaches to bridging the gap between machine-readable identifiers and human-understandable descriptions of changes.

For those interested in implementing this solution themselves, the complete configuration snippet is available in the original article, along with detailed explanations of each component of the template. The jj project's documentation provides additional context on its templating system and configuration options, making it accessible for users who wish to customize their own workflows.

As version control continues to be a critical component of software development, innovations like jj's template system suggest a future where tools become more adaptable to human needs rather than requiring humans to adapt to the tools' limitations. This particular improvement in branch name generation represents a small but meaningful step in that direction.