User guide

Workspaces

A workspace brings branches of several repositories together in one folder, so you can change them and test them as one system. Use one when a change touches more than one service: each service has its branch, and the workspace holds them side by side, for you and for your agent.

A workspace is a Git repository of its own. Each repository in it is a submodule, and each submodule is a worktree of the clone you already have. Nothing is cloned again: a workspace shares the .git folder of each of your clones, so it costs little more disk than the files it checks out, and a commit made in a workspace is on the branch in your clone at once.

What a workspace holds#

~/workspaces/checkout-v2/      the workspace repository
  .gitmodules                  one entry per repository
  service-a/                   worktree of ~/src/service-a, on feat/checkout-v2
  service-b/                   worktree of ~/src/service-b, on feat/checkout-v2
  service-c/                   worktree of ~/src/service-c, on feat/new-pricing

The workspace repository is yours to write in. Your service repositories are not touched: GitMaster writes nothing into their working trees, and adds nothing to them but the worktree records Git keeps in their .git folder.

The Workspaces section#

The Workspaces section of the sidebar lists the workspaces under the workspace root, by name, in every window. A here badge marks the workspace the window shows. Click a row to open that workspace in its own window.

The + in the section header opens New Workspace…. The menu of a row has Open Workspace, Reveal in File Manager and Remove Workspace. A × appears when you point at a row: it removes that workspace, as Remove Workspace does. The section starts folded, like Branches and Worktrees: click its header to open it; see Branches.

Create a workspace#

1. Run New Workspace… from the command palette, or click + in the Workspaces section of the sidebar.
2. Name the workspace.
3. Add a member for each repository: choose the repository, then its branch. The repository list offers the repository of the window, your recent repositories and Choose Folder…. The branch button opens the repository's branches, local ones first, then the remote ones that have no local branch, marked as remote. A filter at the top narrows the list as you type, and a name that matches no branch offers Create branch with that name. Branch for all fills the same branch into every member.
4. Check the folder and click Create workspace.

A branch that does not exist yet is created from the repository's base branch, such as main; a branch that exists only on a remote is created to track it. Each member row says which will happen before you create the workspace.

GitMaster suggests the folder <root>/<name>. The root is ~/workspaces unless you set gitmaster.workspace.root (see Configuration).

Every member is checked before anything is created. When one cannot be added, for example because its branch is checked out in another worktree, the dialog says which and where, offers Go to that worktree, and creates nothing. The new workspace opens in its own window.

Work in a workspace#

A workspace opens in its own window, like any repository. The Working Copy shows the workspace repository, with one row per member that says its branch and whether it has changes or commits the workspace does not point to yet. Open a member to see its own Working Copy, history and branches.

• Code navigation searches every member: Quick Open lists the files of all members, and text search looks inside them.
• The diff of a member shows the commits it gained, as a list, and opens each one.
• Each member keeps its branch checked out. When a Git command leaves a member on a detached HEAD, its row is marked detached, and Check Out Branch puts it back on its branch.

When the detached HEAD holds commits that no local or remote branch has, Check Out Branch refuses and says how many, so they are not left behind: put them on a branch first, from the member's own window.

Record a combination#

The workspace repository records the commit of every member. Record the combination you tested, "these commits of A, B and C work together", with Record Combination in the command palette. It stages the new commit of every member that has one, and commits in the workspace repository with a message that lists each member, its branch and its commit:

Record combination

billing   feat/pay-v2  4f2a9c1
checkout  feat/pay-v2  9be03d7

Your own files in the workspace repository, such as notes or scripts, are not staged by it: commit them as in any repository. Record Combination is not available when no member has a new commit, or when a member is on a detached HEAD.

The combinations follow each other on one branch, main. The workspace's History is the list of the combinations you recorded, and each one opens to the commits of each member.

Run an agent in a workspace#

Start the agent in the folder of the workspace, for example in a terminal of the workspace window. The agent sees every member and can change them all.

With the agent integration installed, the session is recorded as a thread of the workspace. The thread is stored once, in the workspace repository, and each edit and each commit in it names the member it was made in. See Threads in a workspace. The MCP tools take the member a call is about by its path, such as billing/src/main.rs.

The local review loop covers the members too: comment on a line of a member's file in the Code page, and GitMaster measures the agent's change to it as for any file.

The local environment the agent sets up, such as containers that run the services, is the agent's and yours: GitMaster does not start or stop it. Its files belong in the workspace repository, so they are versioned with the combination they run.

Remove a workspace#

A workspace stays until you remove it. Remove it from wherever you are:

• the × on its row in the Workspaces section;
• Remove Workspace in the menu of its row, or in the command palette, picking the workspace with Tab;
• Remove Workspace in the workspace's own window: the window closes once the workspace is removed;
• gitmaster workspace remove on the command line; see Command line.

When nothing would be lost, the dialog asks once and Remove workspace removes it. Otherwise the dialog lists what would be lost, following the rules of removing a worktree for each member: a member with changes that are not committed, a member on a detached HEAD with commits that no local or remote branch holds, or changes of the workspace repository's own. Tick the confirmation checkbox, which names what will be discarded, to enable Remove workspace.

GitMaster removes each member's worktree from your clone, then the workspace folder. Commits on a member's branch are never lost: the branches stay in your clones.