# Workspaces

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

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

You stay on Git for remotes and day-to-day VCS identity. Under the hood, Treq places [Jujutsu](https://jj-vcs.github.io/jj/latest/) beside Git in the same repo so it can rebase workspace branches when targets move. That automatic rebase is the reason Treq uses Jujutsu. Git worktrees cannot do it. You do not need to learn Jujutsu to use workspaces. Dropping to the `jj` CLI is a power-user option and is not recommended for normal use.

## 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 an independent working copy. They share commit history through the colocated repository. The Git store keeps remote compatibility and tooling that expects `.git`. A pending file change in one workspace does not appear in another workspace.

## Visual Management

The dashboard shows workspace names, target relationships, divergence, pending changes, and conflicts. From the dashboard, you can open, merge, or delete a workspace.

## Automated Workflows

**Bookmark naming patterns** control names created through Treq. The default pattern, `treq/{name}`, prefixes each workspace bookmark. Treq sanitizes the workspace directory name before creating it under `.treq/workspaces`.

**Parallel agent terminals** let you run independent shell and agent processes in each workspace. Treq persists agent session metadata, while live terminal processes and scrollback remain 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 validates the name, creates a workspace and branch-like bookmark, records its target, and refreshes the dashboard. You can then open a shell or agent session in the new working copy.

**Update flow**: File watching and periodic queries refresh pending changes, divergence, commit history, and conflict indicators.

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

## Stacks and Rebasing

Stacked workspaces model dependent changes. One workspace targets another workspace's bookmark instead of the repository's default branch. Treq records this relationship as `target_branch` and uses it to order stack updates.

For example, a database workspace can target the default branch while an API workspace targets the database workspace. A UI workspace can then target the API workspace. Each workspace contains one reviewable part of the larger change.

When a lower workspace changes, Treq rebases its dependents onto the updated target. A commit can trigger this update for workspaces that target its bookmark. You can also request 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 records the last target commit used for each rebase. This lets it detect when a target moved and the dependent workspace needs another update.

This is the product reason for colocated Jujutsu. Automatic rebasing of workspace branches across a stack is not something Git worktrees can provide.

## Bookmark Conflicts

Git remote updates can leave a local bookmark with multiple possible targets. Treq reports this as a bookmark conflict before it updates the stack.

Resolving the conflict points the local bookmark at the chosen remote target. Treq then rebases local-only commits onto that target. Resolve bookmark conflicts from the bottom of a stack upward because each target affects its dependents.

## Merging Workspaces

Merging integrates a workspace into its target and removes the managed workspace. Treq first abandons empty commits, applies the selected history strategy, 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 successful merge, Treq synchronizes the target working copy when needed. It then removes the managed workspace, deletes the workspace directory, and removes its local metadata.

Treq blocks the merge when the workspace contains unresolved conflicts. Pending working-copy changes also make history operations harder to reason about. Commit, move, or discard them before merging.

## Cached Data

Treq caches workspace file lists and commit diff statistics in the repository-local database. File events and completed repository operations invalidate affected queries so the interface can refresh derived state.

Diffs load when you open them, and terminal processes start when you create a session. This keeps inactive workspaces from paying the full cost of active views and processes.

## 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 opens one repository at a time. Treq creates managed workspaces under `.treq/workspaces/` and requires a Git repository it can open in colocated mode.

## Best Practices

Commit pending changes before rebasing or deleting a workspace. Resolve stack conflicts from the lowest workspace upward. Remove workspaces only after their changes have been merged or intentionally discarded. Prefer Treq's UI for repository operations. Treat the `jj` CLI as optional debugging, not the primary workflow.

## 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)