61 lines
1.9 KiB
Markdown
61 lines
1.9 KiB
Markdown
# Physical Git Worktree Isolation
|
|
|
|
Developing directly on primary branches (`main` or `master`) or in a single shared
|
|
working directory creates severe multi-agent concurrency risks:
|
|
- Uncommitted edits from concurrent tasks get overwritten or cross-contaminated.
|
|
- Branch switches abort background compilations or active test suites.
|
|
- Half-finished experiments accidentally leak into tracking branches.
|
|
|
|
Physical Git worktrees resolve concurrency at the filesystem level. Each task or
|
|
agent operates in an independent physical directory linked to the shared `.git`
|
|
repository.
|
|
|
|
## Standard worktree lifecycle
|
|
|
|
### 1. Provision a dedicated worktree
|
|
From the repository root:
|
|
|
|
```sh
|
|
# Create a new feature branch in an isolated worktree directory
|
|
git worktree add -b feat/<task-id> ../worktrees/<task-id> main
|
|
cd ../worktrees/<task-id>
|
|
```
|
|
|
|
### 2. Implement, verify, and commit
|
|
Inside the isolated worktree:
|
|
- Make targeted changes.
|
|
- Run local tests and deterministic formatters.
|
|
- Stage changes and commit using conventional commit format:
|
|
```sh
|
|
git add <files>
|
|
git commit -m "feat(module): implement scoped capability"
|
|
```
|
|
|
|
### 3. Push and generate pull request
|
|
Push the branch to remote origin:
|
|
```sh
|
|
git push -u origin feat/<task-id>
|
|
```
|
|
|
|
Create the pull request via GitHub CLI using the WHAT-WHY-HOW-LEARNINGS template:
|
|
```sh
|
|
gh pr create \
|
|
--title "feat(module): implement scoped capability" \
|
|
--body-file docs/reports/<task-id>-telemetry.md \
|
|
--base main \
|
|
--head feat/<task-id>
|
|
```
|
|
|
|
### 4. Cleanup after merge
|
|
Once the PR is merged or the task is completed:
|
|
```sh
|
|
cd ../main-repo
|
|
git worktree remove ../worktrees/<task-id>
|
|
```
|
|
|
|
## T3 Code managed worktrees
|
|
When operating within the T3 Code control plane, worktree provisioning, branch
|
|
isolation, and diff tracking are handled natively per conversation thread. Use
|
|
T3 Code's built-in PR tools (`link_pull_request`, `list_thread_pull_requests`) to
|
|
associate PRs with the active task.
|