Workspaces

jj workspaces let you have multiple working copies of the same repository simultaneously. Each workspace is its own directory with its own @ commit, and they all share one history.

The Workspaces panel

Click Workspaces in the icon rail on the left to open the panel. It lists every workspace of the current repository, with tags for the one you are in (current), a working copy that needs updating (●stale) and a workspace whose directory is gone (●missing). The same list is also in the repository dropdown in the top bar.

Adding a workspace

1. In the Workspaces panel, click + Add workspace… at the bottom (or press n while the panel is focused). The repository dropdown in the top bar has the same entry.
2. Fill in the Add workspace form:
   • Name: the workspace name, e.g. feature-auth.
   • Path: where the new directory goes. Use Browse… to pick a folder.
   • Base revision: the commit the new @ starts from. Leave it empty for @, or enter a bookmark or change ID.
   • Open after create: switch to the new workspace once it exists (on by default).
3. Click Create. This runs jj workspace add.

Switching workspaces

Click a workspace in the panel (or select it and press Enter). You can also open its ⋯ menu and choose Switch to workspace, or click a workspace chip such as feature-auth@ on a commit in the log. Wyrm snapshots your current working copy before it switches.

Workspace actions

Click ⋯ on a workspace row to open its menu:

• Switch to workspace: open that workspace (other workspaces only).
• Rename…: rename the workspace (only the current one).
• Open in Finder / Copy path: reveal or copy the workspace directory.
• Update working copy: shown only when the working copy is stale.
• Forget…: remove the workspace from the repository (other workspaces only).

Renaming a workspace

Switch to the workspace, then choose Rename… from its menu (or press r). Enter the New name: and click Rename. This runs jj workspace rename.

Forgetting a workspace

Choose Forget… from the menu of a workspace you are not currently in (or press x). In the confirmation dialog:

• Forget workspace from repo is always on: jj stops tracking the workspace (jj workspace forget).
• Delete files at the workspace path also removes its directory from disk. Untick it to keep the files.

The dialog checks whether the workspace’s @ holds work that nothing else points to. If it does, you have to type the workspace name before Forget is enabled. Nothing is destroyed outright: orphaned commits stay in the operation log and can be recovered with jj op restore.

Stale working copies

When another workspace rewrites the commit your workspace is on, its files fall behind and the row shows ●stale. Click Update WC on the row, choose Update working copy from the menu, or press u. This runs jj workspace update-stale.

Workspace indicators

In the log graph, your own @ has a green halo. A commit that is another workspace’s working copy has a yellow halo and a chip with the workspace name, e.g. feature-auth@. Click the chip to switch to that workspace.