jj-vcs-comprehensive - SKILL.md Agent Skill

name: jj-vcs-comprehensive description: Complete Jujutsu (jj) version control system for Git replacement. Use when migrating from Git, setting up colocated workspaces, managing commits without staging, working with bookmarks/branches, syncing with GitHub/remotes, resolving conflicts, or any jj command operations.

Jujutsu (JJ) Version Control

Complete Git replacement with automatic commit tracking and simplified workflows.

When to Apply

Migrating from Git to jj while maintaining GitHub sync
Setting up colocated Git/jj workspaces for tool compatibility
Managing commits without staging area complexity
Working with bookmarks (branches) and remote synchronization
Resolving merge conflicts as first-class objects

Critical Rules

Colocated Workspaces: Always use --colocate for Git tool compatibility

# WRONG - Creates separate .jj directory
jj git init myproject

# RIGHT - Shared working copy with Git
jj git init --colocate myproject
jj git clone --colocate https://github.com/user/repo

Working Copy as Commit: Changes automatically tracked without staging

# WRONG - No staging area exists
git add file.rs
git commit -m "message"

# RIGHT - Describe current commit, changes auto-tracked
echo "code" > file.rs
jj describe -m "Add feature"
jj new  # Finalize and start new commit

Bookmarks vs Branches: Use bookmark commands for Git branch equivalents

# WRONG - No branch command
jj branch create feature

# RIGHT - Bookmarks are jj's branch concept
jj bookmark create feature-auth
jj bookmark track main --remote origin

Key Patterns

Repository Setup

# Clone with GitHub sync capability
jj git clone --colocate https://github.com/user/repo
cd repo

# Convert existing Git repo
cd existing-git-repo
jj git init --colocate

# Check colocation status
jj git colocation status

Daily Workflow

# Check status (no staging area)
jj status
jj diff

# Set commit message for current work
jj describe -m "Implement authentication"

# View history with graph
jj log
jj log -r 'main::@'  # Between main and working copy

# Finalize current work, start new commit
jj new

# Create commits on specific revisions
jj new main
jj new -r "trunk()"

Bookmark Management

# Create and track bookmarks
jj bookmark create feature-branch
jj bookmark create ui-update -r <commit-id>
jj bookmark track main --remote origin

# List and manage
jj bookmark list --all-remotes
jj bookmark move feature-branch --to @
jj bookmark delete old-feature
jj bookmark rename old-name new-name

Remote Synchronization

# Add remotes
jj git remote add origin https://github.com/user/repo.git
jj git remote list

# Fetch and push
jj git fetch
jj git fetch --remote upstream
jj git push --bookmark feature-branch --allow-new
jj git push --all

# Sync workflow (no direct pull equivalent)
jj git fetch
jj rebase -b my-feature -d main@origin
jj git push --bookmark my-feature

Conflict Resolution

# Conflicts are first-class objects
jj new main feature-branch  # May create conflict

# View conflicted files
jj status
jj log -r 'conflict()'

# Resolve interactively
jj resolve
jj resolve src/file.rs

# Manual resolution workflow
jj new conflicted-commit  # Work on top of conflict
# Edit files manually
jj squash  # Move resolution into conflicted commit

Advanced Operations

# Rebase operations
jj rebase -s source-commit -d destination-commit
jj rebase -b bookmark-name -d main

# Split and squash (replaces Git staging)
jj split file1.rs file2.rs  # Interactive split
jj squash file3.rs  # Move to parent commit
jj squash -i  # Interactive selection

# Edit historical commits
jj edit <commit-id>  # Change working copy to that commit

# Complex history queries
jj log -r 'author("alice") & committer_date(after:"2024-01")'
jj log -r 'description(glob:"fix*") ~ author("bot")'
jj log -r 'mutable() & empty()'

Git Compatibility

# Use Git commands in colocated workspace
git status  # Works alongside jj
git log     # Git view of history
jj log      # jj view (more powerful)

# Import/export when needed
jj git import  # Import Git refs
jj git export  # Export to Git

# Disable/enable colocation
jj git colocation disable  # Separate .jj directory
jj git colocation enable   # Shared working copy

Common Mistakes

Using Git staging concepts: jj has no staging area - changes are automatically tracked in working copy commit
Forgetting to track remote bookmarks: Use jj bookmark track <name> --remote origin for push/pull workflows
Not using --colocate: Required for Git tool compatibility and GitHub workflows
Expecting git pull equivalent: Use jj git fetch followed by jj rebase -b branch -d main@origin
Creating commits without descriptions: Use jj describe -m "message" to set commit messages
Mixing new and commit: jj new starts a new empty change on top; jj commit is shorthand for jj describe + jj new — it finalizes the current change with a message and starts a new one. Neither is a Git-sync command; use jj git fetch/jj git push for that.