# Workspaces

_How Treq isolates parallel work with managed workspaces inside a Git repository._

Treq creates managed workspaces inside your Git repository. Each one has its own working copy and its own line of commit history. Workspace files and repository-local metadata live under `.treq`.

You stay on Git for remotes and for day-to-day version control. Under the hood, Treq puts [Jujutsu](https://jj-vcs.github.io/jj/latest/) beside Git in the same repo so it can rebase workspace branches when their targets move. That automatic rebase is the whole reason Jujutsu is there, and [Git worktrees](/learn/concepts/git/git-worktrees) cannot do it. You never have to learn Jujutsu to use workspaces. Dropping to the `jj` CLI is a power-user option, not the normal path.

## Workspace Layout

A managed workspace is an additional working copy linked to the same repository:

```
.git/                       # Git data (native VCS and remotes)
.jj/                        # Colocated Jujutsu state (managed by Treq)
.treq/workspaces/
  ├── treq-feature-1/        # Workspace for treq/feature-1
  ├── treq-bugfix-2/         # Workspace for treq/bugfix-2
  └── ...
```

Each workspace has its own working copy, and they all share commit history through the colocated repository. The Git store is what keeps remotes and any tooling that expects `.git` working. An uncommitted change in one workspace never shows up in another.

## Visual Management

The dashboard shows each workspace's name, what it targets, how far it has drifted, what is uncommitted, and any conflicts. From there you can open, merge, or delete a workspace.

## Automated Workflows

**Bookmark naming patterns** decide the names Treq creates. The default, `treq/{name}`, puts a prefix on every workspace bookmark. Treq cleans up the directory name before creating it under `.treq/workspaces`.

**Parallel agent terminals** let you run a separate shell and agent process in each workspace. Treq saves the session metadata, but live processes and scrollback stay in memory.

## Storage Structure

```
{repo}/
├── .git/                    # Shared git data
├── .treq/
│   ├── workspaces/
│   │   └── {branch-name}/   # Workspace directories
│   ├── local.db             # Workspace and review metadata
│   └── .gitignore           # Ignore .treq folder
├── src/                     # Main repo files
└── ...
```

## Lifecycle Management

**Creation flow**: Treq checks the name, creates the workspace and its bookmark, records what it targets, and refreshes the dashboard. You can then open a shell or agent session in the new working copy.

**Update flow**: File watching and repeated queries refresh what is uncommitted, how far the workspace has drifted, its commit history, and any conflict markers.

**Deletion flow**: Treq drops the workspace, its directory, and its local metadata, then refreshes the dashboard.

## Stacks and Rebasing

Stacked workspaces are how Treq handles changes that depend on each other. One workspace points at another workspace's bookmark instead of the default branch. Treq stores that as `target_branch` and uses it to decide the order of updates.

Say a database workspace targets the default branch, an API workspace targets the database one, and a UI workspace targets the API one. Each holds one reviewable slice of the larger change.

When a lower workspace changes, Treq rebases the ones above it onto the new target. A commit can set this off for any workspace pointing at its bookmark, and you can also ask for an update from the workspace interface.

| Behavior | Detail |
|---|---|
| Already current | Treq skips a rebase when the workspace already descends from the target |
| Pending changes affect synchronization | Treq can skip working-copy synchronization after a rebase when the working copy contains changes |
| Stack order matters | Updating a lower branch affects every workspace above it. Resolve lower conflicts before reviewing higher workspaces. |

Treq remembers the target commit behind each rebase. That is how it spots a target that has moved and a workspace that needs updating again.

This is why colocated Jujutsu is there at all. Rebasing a whole stack of workspace branches automatically is not something Git worktrees can do.

## Bookmark Conflicts

A Git remote update can leave a local bookmark pointing more than one way. Treq calls that a bookmark conflict and reports it before it touches the stack.

Resolving it points the local bookmark at the remote target you chose, and Treq replays your local-only commits on top. Work from the bottom of a stack upward, because each target feeds the ones above it.

## Merging Workspaces

Merging folds a workspace into its target and then removes the workspace. Treq drops any empty commits, applies the history strategy you picked, and moves the target bookmark to the result.

| Strategy | Result |
|---|---|
| Merge | Creates a two-parent merge commit |
| Squash and merge | Combines the workspace commits into one commit on the target |
| Rebase and merge | Rebases the workspace commits onto the target for linear history |

After a clean merge, Treq syncs the target working copy if it has to. It then drops the workspace, deletes its directory, and clears its local metadata.

Treq blocks a merge while the workspace still has unresolved conflicts. Uncommitted changes also make history operations hard to follow, so commit, move, or discard them first.

## Cached Data

Treq caches workspace file lists and commit diff counts in the repository-local database. File events and finished repository operations mark the matching queries stale so the interface can refresh.

Diffs load when you open them, and terminals start when you create a session. An idle workspace does not pay for views and processes nobody is using.

## Settings and Configuration

**Repository settings** include the bookmark naming pattern, files copied into new workspaces, and the default agent and model.

**Application settings** include the theme, terminal font size, default agent and model, and conflict marker style.

## Limitations and Constraints

Each window holds one repository at a time. Treq puts managed workspaces under `.treq/workspaces/`, and it needs a Git repository it can open in colocated mode.

## Best Practices

Commit your changes before you rebase or delete a workspace, and fix stack conflicts from the lowest workspace upward. Only remove a workspace once its changes are merged or you have decided to throw them away. Stay in Treq's interface for repository operations, and keep the `jj` CLI for debugging.

## Learn More

- [Installation and Quickstart](/docs/getting-started/installation)
- [Managing Workspaces](/docs/tutorials/managing-workspaces)
- [Merging Workspaces](/docs/tutorials/merging-workspaces)
- [Using with Git Repo](/docs/tutorials/using-treq-with-git-repo)
- [Under the Hood](/docs/under-the-hood)