Flirt: Building a Native Git Backend for Code Review

In the evolving landscape of code review tools, Flirt emerges with an ambitious vision: a native Git backend that stores review information directly within version control repositories. The project's recent update reveals significant progress on this front, with the basic mechanisms for storing, sending, and receiving review information via Git remotes now functional, though the native backend remains incomplete.

Planned Features and Design Philosophy

The development team has undertaken a thorough analysis of existing code review platforms, including GitHub, Gerrit, and the mailing list approach. This analysis informs Flirt's feature set, which balances innovation with practicality.

A core design principle is encouraging code review on a per-commit basis. Consequently, Flirt discourages commenting on the combined diff of multi-patch Spirits, instead focusing individual reviews on specific commits. This approach raises interesting questions about handling existing comments made on full diffs in platforms like GitHub, with potential solutions including treating them as free-standing comments or associating them with the last patch in the Spirit.

The feature set includes:

• Commenting on ranges of lines (though not individual characters within a line)
• Commenting on commit messages and headers—a capability notably absent from GitHub
• Support for comment threads, with special consideration for how to handle branching threads from mailing list workflows
• Thread resolution with both shared and local toggles, addressing a limitation in GitHub's implementation
• Customizable verdicts for reviews, accommodating different backend approaches

Notably, marking files as viewed was deemed non-essential for initial implementation, as Flirt's incremental review approach should already prevent duplicate work.

Technical Implementation: Beyond git-notes

The most intriguing aspect of Flirt is its technical approach to storing review information. The project initially considered using git-notes, similar to git-appraise, but ultimately rejected this approach due to fundamental issues with commit rewriting.

The critical problem with git-notes emerges during operations like git-rebase, where commit hashes change. Git does not automatically associate notes with the new commit hash after rewriting, creating a significant risk of data loss. The author demonstrated a simple script that could cause review information to disappear during normal Git operations.

Instead, Flirt employs custom refs in .git/refs/flirt/ to store review information. This approach provides several advantages:

• Custom refs prevent associated objects from being garbage-collected
• They offer direct lookup without parsing multiple JSON objects
• They can be pushed and fetched like regular branches
• They integrate naturally with Git's existing object model

The current implementation has the custom ref point to a commit rather than a blob, with the commit containing a tree that holds a "spirit.json" blob containing the actual review data. This design ensures that when a reviewer fetches a Spirit, all previous submissions are automatically downloaded, maintaining the complete history of code changes and associated comments.

Future Directions: Materializing Threads and Thread Relocation

Looking ahead, the project faces several challenges, most notably implementing robust comment thread handling. The author proposes an approach that "materializes" comment threads directly in the local repository, with a specialized syntax that includes thread IDs and spaces for replies.

The most innovative concept is "thread relocation"—the ability to track comments when code is moved. When a code author implements a suggestion from a review and moves the relevant code, they can also move the associated comment thread. Flirt would capture this relocation and communicate it to all collaborators, ensuring that comments appear in their correct locations during subsequent review cycles.

This capability, which would be unique to Flirt's native backend, addresses a common frustration with existing tools like GitHub, which mark threads as "outdated" when commits are rewritten, often losing the semantic connection between comments and code.

Challenges and Roadmap

Despite progress, the project faces significant challenges. The author expresses doubt about meeting the self-imposed deadline of implementing GitHub and mailing list backends by the end of March, citing the incomplete state of the native backend and the expected complexity of the mailing list implementation.

The mailing list backend presents particular difficulties, especially regarding the handling of arbitrarily branching comment threads. The proposed solution for materializing threads in editors is also acknowledged as potentially verbose and could benefit from improved syntax highlighting or alternative approaches.

Flirt represents an ambitious attempt to reimagine code review through the lens of Git's native capabilities. By storing review information directly in repositories and leveraging Git's object model, the project aims to create a more resilient, flexible, and offline-friendly code review experience. The concept of thread relocation, in particular, offers a novel solution to a persistent problem in collaborative code review.

For those interested in following Flirt's development, the project maintains an active presence on Hacker News, Lobsters, and Bluesky, with the author also available in the Jujutsu Discord server as @senekor. The project's GitHub repository and documentation would likely provide more technical details for those wishing to explore the implementation further.

As the code review landscape continues to evolve, Flirt's approach of building directly on Git's foundations rather than abstracting away from version control represents an intriguing alternative to traditional platform-dependent solutions.