Skip to content

jj.md

Latest commit

 

History

History
144 lines (102 loc) · 4.52 KB

jj.md

File metadata and controls

144 lines (102 loc) · 4.52 KB

jj

Flow wraps common Jujutsu (jj) workflows so you can stay in jj while remaining fully Git-compatible.

Quick start

# Inspect workspace + home-branch state
f status

# Initialize jj (colocated with git when .git exists)
f jj init

# Create a feature bookmark and track origin
f jj bookmark create feature-x --track

# Fetch + rebase onto main + push bookmark
f jj sync --bookmark feature-x

Commands

  • f status — Show workflow-aware JJ status (workspace, home branch, leaf branches, working-copy summary, and next-step hints)
  • f jj status — Show raw jj st
  • f jj fetch — jj git fetch
  • f jj rebase --dest <branch> — Rebase onto jj.default_branch (or main/master)
  • f jj push --bookmark <name> — Push a single bookmark
  • f jj push --all — Push all bookmarks
  • f jj sync --bookmark <name> — Fetch, rebase, then push bookmark
  • f jj workspace add <name> [--path <dir>] [--rev <rev>] — Create a workspace (optionally anchored to a revision)
  • f jj workspace lane <name> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch] — Create an isolated parallel lane from trunk defaults
  • f jj workspace review <branch> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch] — Create or reuse a stable JJ review workspace for a branch without touching the current checkout
  • f jj workspace list — List workspaces
  • f jj bookmark create <name> [--rev <rev>] [--track] — Create bookmark
  • f jj bookmark track <name> [--remote <remote>] — Track remote bookmark

Status-first workflow

Use f status before branch, workspace, commit, or publish operations.

It is the fast way to answer:

  • which workspace am I in?
  • am I on the long-lived home branch or a branch-specific leaf?
  • what review or codex branches currently sit on top of the home branch?
  • is the working copy clean enough to mutate safely?

Example:

cd ~/code/org/project
f status

Use f jj status only when you want the raw Jujutsu working-copy view.

Parallel lanes (no interleaving)

Use lanes when you want multiple active tasks in one repo without stash/pop churn:

# In your current repo, create isolated lanes anchored from trunk
f jj workspace lane fix-otp
f jj workspace lane testflight

# Work each lane independently
cd ~/.jj/workspaces/<repo>/fix-otp
jj st

f jj workspace lane does:

  1. jj git fetch (unless --no-fetch)
  2. chooses base as <default_branch>@<remote> when tracked (fallback: <default_branch>)
  3. creates a dedicated workspace with its own @ working-copy commit

Review workspaces

Use a review workspace when you want an isolated JJ working copy for a review branch without touching the current repo checkout:

f jj workspace review review/alice-feature
cd ~/.jj/workspaces/<repo>/review-alice-feature
jj st

f jj workspace review does:

  1. jj git fetch (unless --no-fetch)
  2. reuses the existing review workspace when present
  3. otherwise anchors the workspace at the local branch commit, then the remote branch commit, then trunk
  4. prints the stable workspace path plus the JJ bookmark command to publish later

Important:

  • The review workspace is JJ-native. Use jj or f jj inside it.
  • In colocated repos, plain git still points at the main checkout, so this command intentionally does not run flow switch for you.

Config

Add to flow.toml:

[git]
remote = "myflow-i"  # optional preferred writable remote

[jj]
default_branch = "main"
home_branch = "alice" # optional long-lived personal integration branch
remote = "origin"     # optional legacy fallback if [git].remote is unset
auto_track = true

This keeps jj aligned with Git remotes while you work locally in jj.

Home-branch model

If you keep a long-lived personal branch on top of trunk, set jj.home_branch and treat it as your integration branch.

When the current branch matches that home branch, plain f sync also switches into home-branch mode and syncs origin/<default-branch> into it instead of using the normal tracking pull.

Then use short-lived review/* or codex/* branches on top of that home branch for task-specific work. f status is optimized to make that shape visible.

Recommended flow:

# Default checkout stays on your home branch
cd ~/code/org/project
f status

# Branch-specific work happens in isolated workspaces
f jj workspace review review/alice-feature
cd ~/.jj/workspaces/project/review-alice-feature
f status

See also: