Workrooms

A workroom is a branch of your project with its own working copy and its own terminals. On your Mac it is a Git worktree. This page covers everything you do with workrooms in the app, from creating one to deleting it.

Create a workroom

Each workroom gets a generated name such as swift-meadow, and a branch called workroom/swift-meadow. New workrooms start from origin's default branch unless you set a base branch. Workrooms live under ~/workrooms by default.

You can start a create in three ways:

• Click the + on a project's row in the sidebar.
• Right-click a project and choose New Workroom.
• Press ⌘N (File ▸ New Workroom…) and pick a project.

The picker for ⌘N has a Filter projects field. Type to narrow the list, use ↑ and ↓ to move, and press Return to pick. Press ⌥Return to open the new workroom beside the current one as a split. ⌥⌘N (File ▸ New Workroom (split right)) opens the picker already in split mode.

The workroom opens with a terminal in its directory when the create finishes. If the project has a run command set to run automatically, it starts then.

Choose where it runsNightly

After you pick a project, Workroom asks where the workroom goes: This Mac, a local container, a remote provider, or an SSH host. The sidebar + and New Workroom menus offer the same choices. Press ← or click the back arrow to return to the project list.

Anything other than This Mac is a remote workroom. See Remote workrooms.

Watch the stepsNightly

A new workroom opens a creation pane at once, with a checklist of the steps. For a workroom on your Mac they are:

1. Fetch base branch
2. Create worktree
3. Copy your changes, only when you chose to include them (see Include work you haven't pushed)
4. Copy local files, which copies the files listed in your project's .worktreeinclude
5. Run setup script, which runs your project's scripts/workroom_setup

The last two rows appear only when your project has a .worktreeinclude or a setup script.

Each row shows how long its step took. Click a row, or press Space on it, to open its log. ↑ and ↓ move between rows, → opens a log and ← closes it. A row says Waiting for you while it needs an answer from you.

When every step is done, click Done or press Return to open the terminal. Turn on Close automatically when done at the bottom left of the pane, and the pane closes itself a few seconds after the workroom is ready. The same switch is in Settings ▸ General as Close the checklist automatically when done.

If a step fails, the pane shows the reason under that step's row, with two buttons below it:

Open Anyway opens the workroom's terminal even though setup failed. The run command does not start automatically.

When the setup script needs your approval, a sheet shows it before anything is created, with Continue Without Script…, Cancel Creation and Approve. Continue Without Script asks first, then creates the workroom without running the script, and leaves it unapproved. Review Script… in the pane opens the sheet again. See Prepare a project for setup scripts and the approval step.

Include work you haven't pushedNightly

New workrooms start from what you've pushed, so they don't have commits you haven't pushed yet, or changes you haven't committed. When you have either on the base branch, Workroom asks before it creates anything, and offers only what applies:

• Include My Commits and Changes starts from your commits and copies your changes in, new files included. Your changes stay in your project too.
• Include My Commits (or Include My Commits Only) starts from your commits, without the changes.
• Include My Changes copies your changes in, when you have changes but no unpushed commits.
• Leave It Out starts from what you've pushed, as before.

If you haven't pulled the latest changes, including your work starts from your older copy, without what others have pushed since, and Workroom says so in the question. Pull first if you want both.

Cancel Creation stops the create. Choose… in the pane asks again. Files your .gitignore lists are never copied this way; list them in .worktreeinclude instead (see Prepare a project). A new folder that is a git repository of its own isn't copied either; the Copy your changes step says which. Changes on a different branch don't count. When Workroom can't reach origin, it doesn't ask.

A remote workroom can only start from what you've pushed. It is created without your other work, and a notice says what it left out.

From the command line, workroom create asks the same question in a terminal, or takes --start local-with-changes, local or origin. See workroom create.

Open a workroom

Click a workroom in the sidebar to open it. Workroom shows its terminals, and your other workrooms keep running in the background.

To open one by name, press ⌘O (File ▸ Open Workroom…). Type in Filter workrooms, pick a row and press Return. Rows are grouped by project, and each project's root comes first. Press ⌥Return, or use ⌥⌘O (File ▸ Open Workroom (split right)), to open it as a split instead. See Splits and windows.

You can also right-click a workroom in the sidebar and choose Open (split right).

Switch between workrooms

Open workrooms also appear as tabs in a bar across the top of the window. Drag a tab to reorder it.

The workroom switcher

Hold ⌥ and press Tab. A quick tap flips to the workroom you were in before. If you keep the key held, or press Tab again, a rail of cards appears, ordered by how recently you used each workroom. Press Tab or the arrow keys to move along the rail, and release ⌥ to switch. You can also click a card. Esc cancels.

The switcher steps through workrooms in every window. ⌃Tab does the same for the panes of the current workroom.

Label a workroom

A label is a name that shows in place of the workroom's own name. The workroom and its branch keep their names.

1. Right-click the workroom, in the sidebar or on its tab, and choose Set Label…. The Room menu has it too, except in Workroom 2.1.0.
2. Type the label and click Save.

Choose Edit Label… to change it, or Remove Label to go back to the real name. A label cannot match the name or label another workroom in the same project already shows.

Close a workroom

Right-click a workroom's tab and choose Close to close all of its terminals and take it out of the tab bar. The workroom itself and its files stay, and you can open it again. Workroom asks you to confirm.

Move a workroom to another windowNightly

You can give a workroom a window of its own, or move it into another Workroom window. Its terminals keep running.

• Drag its tab, or its title bar, out of the window. It opens in a new window at the drop point.
• Drop it on another Workroom window to join that window. It lands at the slot under your cursor on that window's tab bar, or at the end.
• Right-click the workroom, in the sidebar or on its tab, and choose Move to New Window.
• Use Room ▸ Move Workroom into New Window for the selected workroom.

A window's only workroom cannot move, because that would leave an empty window. The items are also off while the workroom is still being created.

Delete a workroom

Deleting removes the workroom's directory. For a workroom on your Mac, Workroom keeps the workroom/<name> branch in your repository.

1. Hover the workroom in the sidebar and click the trash button, right-click it and choose Delete Workroom…, or choose Room ▸ Delete Workroom… (not in Workroom 2.1.0).
2. Confirm in the Delete 'name'? dialog.

The row leaves the sidebar at once. Workroom runs your project's scripts/workroom_teardown script in the background, then removes the directory. You cannot delete a workroom while its setup is still running.

When the teardown fails

If the teardown script fails or can't start, the delete stops. The workroom comes back in the sidebar with its folder and branch, but its terminals were closed before the script ran, so open new ones if you keep it. A sheet titled Teardown of ‘name’ failed shows why, with the script's output. Fix the script and delete again. If the script has not been approved on this Mac, the sheet is titled Approve the teardown script? instead, says which workroom and project it's for, and shows the script.

Delete AnywayNightly

The sheet has a Delete Anyway button that deletes the workroom without running the teardown script. If the script has not been approved on this Mac, the sheet shows it with an Approve button, which runs it and deletes the workroom. See Prepare a project.