kabu

What kabu solves

kabu automates repetitive setup when creating a git worktree / jj workspace.

• Create directories (mkdir)
• Create symlinks (link)
• Copy files (copy)
• Run hooks before/after add/remove (requires trust)

Supported VCS: Git (git worktree), jj (jj workspace), and colocated repositories.

Quick Start

Install (see INSTALL.md for other methods):

cargo install kabu

Create .kabu/config.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/h-michael/kabu/main/schema/kabu.schema.json

on_conflict: backup

mkdir:
  - path: .cache

link:
  - source: .env.local

copy:
  - source: .env.example
    target: .env

Create a worktree/workspace:

kabu add ../feature-x

Validate config if needed:

kabu config validate

Shell Integration

Shell integration is optional, but required for kabu cd.

Bash:

eval "$(kabu init bash)"

Zsh:

eval "$(kabu init zsh)"

Fish:

kabu init fish | source

PowerShell:

Invoke-Expression (& kabu init powershell | Out-String)

Elvish:

eval (kabu init elvish | slurp)

Common Tasks

Add

# Create with setup
kabu add ../feature-x

# Create new branch/bookmark
kabu add -b feature-x ../feature-x

# Preview only
kabu add --dry-run ../feature-x

# Skip setup and run only VCS add
kabu add --no-setup ../feature-x

List

kabu list
kabu ls
kabu list --path-only

Remove

# Safe remove (warns on dirty or unpushed state)
kabu remove ../feature-x

# Remove current worktree/workspace
kabu remove --current

# Preview only
kabu remove --dry-run ../feature-x

# Skip checks and confirmation
kabu remove --force ../feature-x

Jump to another worktree/workspace

# Requires shell integration
kabu cd

# Works without shell integration
cd "$(kabu path)"

Configuration

Config files:

• Repo local: .kabu/config.yaml or .kabu/config.toml
• YAML is used when both exist
• JSON Schema: schema/kabu.schema.json

Use {{...}} placeholders in templates (for example {{branch}}, {{repository}}).

For full config keys and behavior, use CLI help:

kabu config --help
kabu config <subcommand> --help

Safety Model

Hooks are opt-in by trust:

kabu trust
kabu trust --check
kabu untrust

kabu remove warns about:

• Uncommitted changes
• Unpushed commits (git)
• Commits not on remote bookmarks (jj)

Use --force only when you intentionally want to bypass checks.

VCS Behavior (git / jj)

kabu auto-detects VCS and maps commands:

• git: git worktree add/remove/list
• jj: jj workspace add/forget/list
• colocated repo: jj commands are preferred

CLI terminology keeps worktree/workspace together to avoid ambiguity.

Reference Map

• Command overview: kabu --help
• Command details: kabu <subcommand> --help
• Config reference: kabu config --help
• Man page: kabu man
• Task-oriented examples: examples/README.md

View generated man page directly:

kabu man | man -l -

License

This project is licensed under the MIT License. See LICENSE-MIT.