From 34df4816d905d9d482cad37393cf68b92e96dbe6 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Thu, 5 Feb 2026 15:28:01 +0700 Subject: [PATCH] docs(website): add git worktrees documentation page --- packages/website/src/routes/docs.tsx | 1 + .../website/src/routes/docs/worktrees.tsx | 235 ++++++++++++++++++ 2 files changed, 236 insertions(+) create mode 100644 packages/website/src/routes/docs/worktrees.tsx diff --git a/packages/website/src/routes/docs.tsx b/packages/website/src/routes/docs.tsx index 28c68130b..03be4a85e 100644 --- a/packages/website/src/routes/docs.tsx +++ b/packages/website/src/routes/docs.tsx @@ -7,6 +7,7 @@ export const Route = createFileRoute('/docs')({ const navigation = [ { name: 'Getting started', href: '/docs' }, + { name: 'Git worktrees', href: '/docs/worktrees' }, { name: 'CLI', href: '/docs/cli' }, { name: 'Configuration', href: '/docs/configuration' }, { name: 'Security', href: '/docs/security' }, diff --git a/packages/website/src/routes/docs/worktrees.tsx b/packages/website/src/routes/docs/worktrees.tsx new file mode 100644 index 000000000..dac603ba1 --- /dev/null +++ b/packages/website/src/routes/docs/worktrees.tsx @@ -0,0 +1,235 @@ +import { createFileRoute } from '@tanstack/react-router' + +export const Route = createFileRoute('/docs/worktrees')({ + head: () => ({ + meta: [ + { title: 'Git Worktrees - Paseo Docs' }, + { + name: 'description', + content: 'Run agents in isolated git worktrees for parallel feature development.', + }, + ], + }), + component: Worktrees, +}) + +function Code({ children }: { children: React.ReactNode }) { + return ( +
+ {children} +
+ ) +} + +function Worktrees() { + return ( +
+
+

Git Worktrees

+

+ Git worktrees let you have multiple working directories from the same repository. + Paseo uses them to run agents in isolated branches without switching contexts. +

+
+ + {/* Why worktrees */} +
+

Why worktrees?

+

+ Without worktrees, running multiple agents on the same repo means they share the + working directory. One agent's changes interfere with another's. You can't safely + run parallel tasks. +

+

+ With worktrees, each agent gets its own directory and branch. They can work + simultaneously without conflict. When an agent finishes, you review the diff, + merge the branch, and archive the worktree. +

+
+ + {/* Directory structure */} +
+

Directory structure

+

+ Paseo creates worktrees under $PASEO_HOME/worktrees/, + organized by project: +

+ + 
{`~/.paseo/worktrees/
+├── my-project/
+│   ├── feature-auth/        # worktree for feature-auth branch
+│   └── fix-login-bug/       # worktree for fix-login-bug branch
+└── another-repo/
+    └── refactor-api/        # worktree for refactor-api branch`}
+ +

+ The project name is derived from your git remote URL or repository directory name. + Worktree names map to branch names. +

+
+ + {/* paseo.json */} +
+

Setup with paseo.json

+

+ When Paseo creates a worktree, it's a fresh checkout. Dependencies aren't installed, + config files aren't copied. You can automate setup by creating a{' '} + paseo.json file in your repository root: +

+ + 
{`{
+  "worktree": {
+    "setup": [
+      "npm ci",
+      "cp \\"$PASEO_ROOT_PATH/.env\\" \\"$PASEO_WORKTREE_PATH/.env\\""
+    ]
+  }
+}`}
+ +

+ The setup array contains shell commands that run + after the worktree is created. Use it to install dependencies, copy local config + files, or run any other initialization. +

+
+ + {/* Environment variables */} +
+

Environment variables

+

+ Setup commands have access to these environment variables: +

+
    +
  • + $PASEO_ROOT_PATH — your original repository root +
    • +
  • + $PASEO_WORKTREE_PATH — the new worktree directory +
    • +
  • + $PASEO_BRANCH_NAME — the branch name created +
    • +
+

+ Use $PASEO_ROOT_PATH to copy files that shouldn't + be in git (like .env) from your main checkout to + the worktree. +

+
+ + {/* Common patterns */} +
+

Common patterns

+ +

Node.js / npm

+ + 
{`{
+  "worktree": {
+    "setup": ["npm ci"]
+  }
+}`}
+ + +

Python / Poetry

+ + 
{`{
+  "worktree": {
+    "setup": ["poetry install"]
+  }
+}`}
+ + +

Copy environment files

+ + 
{`{
+  "worktree": {
+    "setup": [
+      "npm ci",
+      "cp \\"$PASEO_ROOT_PATH/.env\\" \\"$PASEO_WORKTREE_PATH/.env\\"",
+      "cp \\"$PASEO_ROOT_PATH/.env.local\\" \\"$PASEO_WORKTREE_PATH/.env.local\\""
+    ]
+  }
+}`}
+ + +

Run database migrations

+ + 
{`{
+  "worktree": {
+    "setup": [
+      "npm ci",
+      "cp \\"$PASEO_ROOT_PATH/.env\\" \\"$PASEO_WORKTREE_PATH/.env\\"",
+      "npm run db:migrate"
+    ]
+  }
+}`}
+ +
+ + {/* Workflow */} +
+

Workflow

+

+ The typical workflow is: +

+
    +
  1. + Start an agent with a worktree — Paseo creates the branch and runs setup +
    2. +
  2. + Agent works in isolation — changes stay in its worktree +
    3. +
  3. + Review the diff — compare against the base branch +
    4. +
  4. + Merge or discard — if approved, merge the branch; otherwise archive +
    5. +
  5. + Archive the worktree — cleans up the directory and optionally the branch +
    6. +
+

+ You can run multiple agents in different worktrees simultaneously. Each has its + own branch and working directory. +

+
+ + {/* CLI reference */} +
+

CLI reference

+

+ Create an agent in a new worktree: +

+ + 
{`paseo run --worktree feature-auth --base main "implement auth"`}
+ +

+ List all worktrees: +

+ + 
{`paseo worktree ls`}
+ +

+ Archive a worktree (stops agents, removes directory): +

+ + 
{`paseo worktree archive feature-auth`}
+ +
+ + {/* Metadata */} +
+

Metadata

+

+ Paseo stores metadata in each worktree's git directory to track the base branch. + This is used for diff operations and to know what branch to merge into. +

+

+ You don't need to manage this manually — Paseo handles it when creating and + archiving worktrees. +

+
+
+ ) +}