VisualJJ

Configuration

VisualJJ's mental model is simple: main is the shared code, and everything on top of it is work in progress. To make that model work, VisualJJ needs to know which branch (or branches) count as "shipped" for your repository. Most repos just have main or master and need no configuration. If yours is different — or if you have more than one shipped branch — this page is for you.

Main branch

By default, VisualJJ auto-detects branches named main or master. If your primary branch has a different name, set it explicitly:

jj config set --repo "revset-aliases.'trunk()'" 'YOUR_BRANCH_NAME@origin'

For example, if your team ships to develop:

jj config set --repo "revset-aliases.'trunk()'" 'develop@origin'

Why this matters

VisualJJ uses the main branch to determine which changes have been shipped and which are still in progress. If it points to the wrong branch, you may see:

  • A warning about deep branches — VisualJJ detects unusually deep subtrees, which typically means the main branch is misconfigured
  • Shipped changes still appearing in the tree instead of being hidden
  • Slow loading times because VisualJJ is traversing more history than necessary

Multiple shipped branches

Some repositories ship work to more than one long-lived branch. Common examples:

  • A develop branch for ongoing work plus a release/* branch for stable versions
  • A main branch for the app plus a gh-pages branch for the docs site
  • Multiple active release lines (release/v1, release/v2) maintained in parallel

Any change that's an ancestor of a shipped branch is treated as "done" — VisualJJ hides it from your work-in-progress view so you see only what's still being worked on. If you ship to multiple branches, tell VisualJJ about all of them:

jj config set --repo "revset-aliases.'trunks()'" 'release@origin'

You can list as many branches as needed, separated by |:

jj config set --repo "revset-aliases.'trunks()'" 'gh-pages@origin | dev@origin | release/v2@origin'

Changes that are ancestors of any shipped branch are treated as shipped — they'll be hidden from the tree and won't affect performance.

Options

VisualJJ reads settings from JJ's config system. All options use the visualjj.* namespace:

# Per-repo (recommended)
jj config set --repo visualjj.option-name value
 
# Global (applies to all repos)
jj config set --user visualjj.option-name value

Auto-initialize JJ in Git repos

When you open a Git repository in VSCode, VisualJJ automatically runs jj git init --colocate so you can start using it right away. To disable this and initialize manually:

jj config set --user visualjj.auto-init false

Background snapshotting

By default, VisualJJ snapshots your working copy once a second so the tree reflects your edits as you type. If that polling is too aggressive for your setup, you have three options, in order of preference:

Use Watchman. JJ's fsmonitor watches the filesystem via Watchman and snapshots only when files actually change — no polling. When it's enabled, VisualJJ detects this and turns off its own snapshot loop automatically, so you get fresh state at zero idle cost. See the JJ docs on Watchman for setup.

Adjust the interval. Keep polling but make it less frequent:

jj config set --repo visualjj.snapshot-interval 5

Disable it entirely. If you'd rather drive JJ from the terminal and only want VisualJJ to react to commands you run yourself:

jj config set --repo visualjj.snapshot-enabled false

The tree still updates when the repository changes on disk (commits, operations from the CLI, etc.). To capture working-copy edits on demand, click Refresh in the toolbar — it snapshots regardless of these settings.

Show immutable changes

By default the tree shows immutable changes on remote branches — work started by teammates, agents, or on another computer. Setting this to false hides branches and stacks that are completely immutable, so you see only in-progress work:

jj config set --repo visualjj.show-immutable false

Change ID length

Each change shows a short ID prefix in the tree. You can control how many characters are displayed (0–5, default 3). Setting to 0 hides change IDs entirely; higher values make it easier to distinguish changes at a glance.

# Hide change IDs
jj config set --repo visualjj.change-id-length 0
 
# Show longer IDs
jj config set --repo visualjj.change-id-length 5

Contact support

If you're seeing performance issues or aren't sure how to configure your repository, email support@visualjj.com. Include your OS, VisualJJ version, and a description of the issue.