Skip to content
Setting Up Jujutsu Repositories and Tool Integration logo

Setting Up Jujutsu Repositories and Tool Integration

Set up jj repositories including colocation decisions, integrate with development tools like Vite/Vitest, and choose between jj library and CLI for tooling. Use when setting up new repositories, experiencing tool integration issues, or building jj integrations.

SKILL.md

Full skill instructions

Setting Up Jujutsu Repositories and Tool Integration

Overview

Key decisions:

  • Colocation: Should you use jj and git in the same directory?
  • Tool integration: How to configure development tools to work with jj
  • Programmatic access: Library vs CLI for building jj integrations

Understanding these choices helps you set up repositories correctly and avoid common integration issues.

Repository Setup

Colocation Decision

What is colocation?

Using jj and git in the same working directory:

my-repo/
├── .git/     # Git repository
├── .jj/      # Jujutsu repository
└── src/      # Shared working directory

Creating colocated repository:

# Initialize jj in existing git repo
cd my-git-repo
jj git init --colocate

# Or create new colocated repo
jj git init --colocate my-repo
cd my-repo

Creating jj-only repository:

# Pure jj repository (no colocation)
jj git init my-repo
cd my-repo

Should You Colocate?

Advantages:

  • ✅ Use both Git and Jujutsu tools on same repo
  • ✅ Easier transition/​learning (can fall back to git)
  • ✅ Works with git-only tools (IDEs, CI/​CD)
  • ✅ Single working directory

Drawbacks:

  • ❌ Potential bookmark/​branch conflicts
  • ❌ Confusing diffs in conflicted files (shows both tools' markers)
  • ❌ Slight performance overhead in large repos
  • ❌ Can accidentally use git commands (bad practice in jj)

Recommendation:

ScenarioRecommendation
Learning jjColocate (easier transition)
Team migrationColocate (gradual adoption)
New personal projectjj-only (cleaner)
Legacy git projectColocate (tool compatibility)
CI/​CD requirementsColocate (git tooling)

Tool Integration

Vite/​Vitest Issues

Problem: jj commands slow or hang in Vite/​Vitest projects.

Cause: Vite's file watcher monitors .jj directory, causing conflicts and slowdowns.

Solution: Configure Vite to ignore .jj:

// vite.config.js or vite.config.ts
export default {
  server: {
    watch: {
      ignored: ['**/​.jj/​**']
    }
  }
}

For Vitest:

// vitest.config.js or vitest.config.ts
export default {
  test: {
    // ... other config
    watch: {
      ignored: ['**/​.jj/​**']
    }
  }
}

Complete example:

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    watch: {
      ignored: [
        '**/​.jj/​**',      // Ignore jj directory
        '**/​.git/​**',     // Good practice to ignore git too
        '**/​node_modules/​**'
      ]
    }
  }
})

General Tool Integration

Common issues and fixes:

File watchers:

  • Exclude .jj/ from watching
  • Pattern: **/​.jj/​** or .jj

IDEs (VS Code, IntelliJ, etc.):

// .vscode/​settings.json
{
  "files.watcherExclude": {
    "**/​.jj/​**": true
  },
  "search.exclude": {
    "**/​.jj/​**": true
  }
}

Build tools:

  • Add .jj/ to ignore patterns
  • Similar to .git/ configuration

Linters/​formatters:

# .prettierignore or .eslintignore
.jj/

Programmatic Integration

Library vs CLI Trade-offs

Question: Should I use the jj library or parse CLI output?

Answer: Both have trade-offs. Library avoids parsing but isn't stable. CLI is also unstable but more flexible.

Using the Library

Pros:

  • ✅ Native Rust integration
  • ✅ No parsing needed
  • ✅ Direct access to data structures

Cons:

  • ❌ API not stable (frequent breaking changes)
  • ❌ Rust only (no other languages)
  • ❌ Won't detect custom backends
  • ❌ Requires Rust knowledge

When to use:

  • Building Rust tools
  • Need high performance
  • Want type safety
  • Willing to handle API changes

Using the CLI

Pros:

  • ✅ Language-agnostic (any language can run commands)
  • ✅ Works with custom jj binaries
  • ✅ Easier to prototype
  • ✅ Matches user experience

Cons:

  • ❌ Output format can change (also unstable)
  • ❌ Parsing overhead
  • ❌ Process spawning overhead
  • ❌ Need to handle errors/​edge cases

When to use:

  • Building scripts (bash, python, etc.)
  • Need portability
  • Rapid prototyping
  • Want consistency with user commands

Best Practices for CLI Integration

# Use --no-pager for scripting
jj log --no-pager

# Use templates for structured output
jj log --template 'commit_id ++ "\t" ++ description.first_line() ++ "\n"'

# Use revsets for precise queries
jj log -r 'mine() & after("1 week ago")'

# Check exit codes
if jj status &>/​dev/​null; then
  echo "In jj repository"
fi

Example Python integration:

import subprocess
import json

def jj_log(revset="@"):
    result = subprocess.run(
        ["jj", "log", "-r", revset, "--no-pager",
         "--template", "json"],
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)

When to Use This Skill

Use this skill when:

  • ✅ Setting up new jj repositories
  • ✅ Deciding on colocation strategy
  • ✅ Experiencing tool integration issues (Vite, IDEs, watchers)
  • ✅ Building integrations with jj
  • ✅ Choosing between library and CLI approach

Don't use this skill for:

  • ❌ Daily jj operations (see jj-workflow skill)
  • ❌ Commit management (see commit-curation skill)
  • ❌ Understanding jj concepts (see other jj skills)

Progressive Disclosure

For detailed setup guides, configuration examples, and integration patterns:

📚 See detailed docs: faq-reference.md

This includes:

  • Complete colocation analysis
  • Tool-specific integration guides
  • Advanced configuration examples
  • Library API patterns
  • CLI parsing strategies

Quick Reference

# Repository initialization
jj git init --colocate           # Colocated repo (jj + git)
jj git init                      # jj-only repo
jj git init --colocate existing-git-repo  # Add jj to git repo

# Configuration
~/​.jjconfig.toml                 # Global config
.jj/​repo/​config.toml             # Repository config

# Tool integration
# Vite: Add to vite.config.js
server.watch.ignored = ['**/​.jj/​**']

# VS Code: Add to .vscode/​settings.json
"files.watcherExclude": {"**/​.jj/​**": true}

Remember

Colocation is a choice, not a requirement. Use it when you need git compatibility, prefer pure jj otherwise. Always configure development tools to ignore .jj/ directory to avoid conflicts and performance issues.

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View