Coming from tmux or git worktree
How Workroom maps onto the tmux sessions and git worktrees you already use, and what changes.
If you already juggle tasks with git worktree and tmux, Workroom will feel familiar: it is built on the
same ideas. This page maps what you know onto Workroom, so you can switch without relearning.
From git worktree
A workroom is a git worktree. Workroom runs git worktree add for you, with a few choices made up
front:
With git worktree |
In Workroom |
|---|---|
| You pick a folder for each worktree. | Workrooms live in ~/workrooms, one folder each. |
| You name the branch. | A new workroom gets a generated name and the branch workroom/<name>. |
| You fetch and choose where to branch from. | Workroom fetches origin and starts from its default branch, or your base branch. |
| You install dependencies in each one. | A setup script does it for every new workroom. |
You copy .env and other ignored files. |
.worktreeinclude copies them. |
git worktree remove, then tidy up. |
Delete the workroom; a teardown script cleans up after it. |
Your existing worktrees keep working. Workroom only manages the ones it makes, and it never changes your
root checkout. The branches it makes are ordinary branches, so git and every other tool see them as
usual, and deleting a workroom keeps its branch.
To change where workrooms go, set workrooms_dir in your
config file.
From tmux
Workroom does the jobs you use tmux for, with each workroom as the unit instead of a session:
| In tmux | In Workroom |
|---|---|
| A session per project or task | A workroom per task, grouped under its project in the sidebar. |
| Windows | Tabs: ⌘T for a new one, ⌘1–⌘9 to jump. |
| Split panes | ⌘D splits right, ⇧⌘D splits down. |
| Moving between panes | ⌃⌘ and an arrow key. |
| Detach, and the session runs on | Switch workroom, and its terminals keep running. |
| Switching sessions | ⌥⌘1–⌥⌘9, or ⌥⇥ for the last one. |
| Activity and bell monitoring | Busy and needs-you marks on tabs and sidebar rows, with alerts. |
There is no prefix key: shortcuts use ⌘, like any Mac app. See Keyboard shortcuts for all of them.
Terminals that outlive the appNightly
A small background process on each host keeps your terminals running when you quit Workroom, as a tmux server does. When you open Workroom again, each terminal reattaches with its output where you left it. On a remote workroom, the terminals run on the host, so they keep going even when your Mac sleeps.
Running tmux inside Workroom
You can still run tmux in a Workroom terminal, for a remote shell for example. Keep it out of the
shell startup, though. Workroom reads your environment from your login shell, and a .zshrc that ends
in exec tmux stops it doing so, leaving it with only the system's PATH. See
Troubleshooting.