Jujutsu (jj) Version Control System

Jujutsu is a next-generation version control system that uses Git repositories as storage while providing a fundamentally different and more powerful user experience. This skill includes the complete official documentation from the jj repository.

Quick Start: Read tutorial.md for hands-on introduction. See git-comparison.md for Git users migrating to jj.

What is Jujutsu?

Jujutsu (command: jj) is a VCS designed to be easy to use for both beginners and experienced users. Key innovations include:

• Working-copy-as-a-commit: Changes are automatically recorded as commits and amended on each change
• Operation log & undo: Every operation is recorded and can be undone (like version control for your version control!)
• Automatic rebase: When you modify a commit, descendants are automatically rebased
• First-class conflicts: Conflicts are tracked as objects and can be committed, resolved later, and propagated
• No staging area: Simplified workflow without Git's index/staging complexity
• Git compatible: Works with existing Git repositories and forges like GitHub

Documentation Structure

Getting Started

• README.md - Project overview, key features, and introduction
• index.md - Documentation homepage with useful links
• install-and-setup.md - Installation instructions for all platforms and initial configuration
• tutorial.md - Comprehensive hands-on tutorial (assumes Git knowledge)
• FAQ.md - Frequently asked questions and common issues
• glossary.md - Definitions of jj-specific terminology

Core Concepts

• working-copy.md - How the working copy works as a commit
• operation-log.md - Understanding the operation log and undo functionality
• conflicts.md - How jj handles merge conflicts as first-class objects
• revsets.md - Powerful language for selecting revisions (like Mercurial revsets)
• templates.md - Customizing output formatting with the template language
• bookmarks.md - Working with bookmarks (similar to Git branches)
• filesets.md - Language for selecting files

Configuration

• config.md - Complete configuration reference and options
• config.toml - Example configuration file
• cli-reference.md - Command-line interface reference

Git Integration

• git-compatibility.md - How jj works with Git repositories and Git features
• git-comparison.md - Comparison of jj vs Git workflows and commands
• git-command-table.md - Quick reference table mapping Git commands to jj equivalents
• github.md - Working with GitHub repositories and pull requests
• gerrit.md - Working with Gerrit code review system

Guides

• guides/divergence.md - Understanding and resolving divergent changes
• guides/multiple-remotes.md - Working with multiple remote repositories

Technical Documentation

• technical/architecture.md - High-level architecture and design decisions
• technical/concurrency.md - How jj handles concurrent operations safely
• technical/conflicts.md - Technical details of conflict handling

Development and Contributing

• contributing.md - How to contribute to jj development
• code-of-conduct.md - Community code of conduct
• core_tenets.md - Core principles guiding jj's design
• roadmap.md - Development roadmap and planned features
• community_tools.md - Community-maintained tools and integrations
• releasing.md - Release process documentation
• design_docs.md - Index of design documents
• design_doc_blueprint.md - Template for writing design docs

Comparisons and Context

• sapling-comparison.md - Comparison with Meta's Sapling VCS
• related-work.md - Other related version control systems
• testimonials.md - User testimonials and experiences

Platform-Specific

• windows.md - Windows-specific considerations and setup

Project Information

• CHANGELOG.md - Version history and release notes
• GOVERNANCE.md - Project governance structure
• SECURITY.md - Security policy and reporting

Common Usage Patterns

When the user asks to:

• Get started with jj → Check tutorial.md and install-and-setup.md
• Migrate from Git → Check git-comparison.md and git-command-table.md
• Understand a concept → Check glossary.md and relevant concept docs (working-copy, conflicts, etc.)
• Configure jj → Check config.md
• Work with GitHub → Check github.md
• Select revisions → Check revsets.md
• Customize output → Check templates.md
• Handle conflicts → Check conflicts.md
• Troubleshoot issues → Check FAQ.md
• Undo a mistake → Check operation-log.md
• Understand architecture → Check technical/architecture.md

Quick Command Reference

Basic Operations

# Clone a Git repository
jj git clone <url>

# Check status
jj st  # or jj status

# Create a new change
jj new

# Edit a change description
jj describe

# Show change log
jj log

# Undo last operation
jj undo

# Show operation log
jj op log

Working with Changes

# Abandon a change
jj abandon

# Move changes between commits
jj squash  # move changes into parent
jj move    # move changes to another commit

# Rebase changes
jj rebase -r <revision> -d <destination>

# Resolve conflicts
jj resolve  # interactive conflict resolution

Git Integration

# Fetch from Git remote
jj git fetch

# Push to Git remote
jj git push

# Import Git branches as bookmarks
jj bookmark track <name>@<remote>

Selecting Revisions (Revsets)

# Common revset expressions
@              # working copy commit
@-             # parent of working copy
main@origin    # bookmark from remote
::@            # ancestors of working copy
@::            # descendants of working copy
~empty()       # non-empty changes

Key Concepts to Understand

Working Copy as Commit

• The working copy is always a commit (shown as @)
• Changes are automatically committed as you work
• No explicit commit command needed (use jj describe to add a message)
• Use jj new to start a new change

Revsets

• Powerful language for selecting commits (similar to Mercurial)
• Used in many commands: jj log -r, jj show, jj rebase, etc.
• Supports boolean operations, functions, and composition
• See revsets.md for complete reference

Operation Log

• Every jj operation is recorded (commit, rebase, push, etc.)
• Use jj op log to see operation history
• Use jj undo to undo the last operation
• Use jj op restore to restore to any previous state

Bookmarks vs Branches

• jj uses "bookmarks" which are similar to Git branches but simpler
• Changes can exist without bookmarks (anonymous branches)
• Bookmarks are just pointers, not required for workflow
• Git branches are imported as bookmarks

Conflicts

• Conflicts are stored in commits, not just in working copy
• You can commit conflicted changes and resolve later
• Conflict resolution is propagated through rebases
• Use jj resolve for interactive resolution

File Organization

• README.md - Main project README with overview
• docs/ - All documentation files
  • tutorial.md - Getting started tutorial
  • config.md - Configuration reference
  • revsets.md - Revset language reference
  • templates.md - Template language reference
  • git-*.md - Git integration documentation
  • guides/ - How-to guides for specific workflows
  • technical/ - Technical architecture documentation
  • design/ - Design documents for features

Tips

• Start with the tutorial to understand the jj mental model
• Use jj help <command> for detailed command help
• The operation log is your safety net - don't be afraid to experiment
• Revsets are powerful - learn them to work efficiently
• Conflicts are normal and can be handled gracefully
• jj works best when you embrace its philosophy (working-copy-as-commit, auto-rebase)
• Check the FAQ when you encounter unexpected behavior
• Use templates to customize jj log output to your preferences

Important Notes

• Jujutsu is experimental but actively developed and used daily by its developers
• Git compatibility is stable - safe to use with existing Git workflows
• Some features are experimental (check README warnings)
• Breaking changes may occur but are documented in CHANGELOG
• Community is active on Discord, GitHub Discussions, and IRC (#jujutsu on Libera Chat)

Resources

• Homepage: https://jj-vcs.github.io/jj
• GitHub: https://github.com/jj-vcs/jj
• Discord: https://discord.gg/dkmfj3aGQN
• Documentation: https://jj-vcs.github.io/jj/latest/
• Tutorial by Steve Klabnik: https://steveklabnik.github.io/jujutsu-tutorial/
• Chris Krycho's YouTube series: https://www.youtube.com/playlist?list=PLelyiwKWHHAq01Pvmpf6x7J0y-yQpmtxp