David Kong
dd2202f54c
## Summary Register all four git worktree tools with correct TypeBox schemas and placeholder implementations. ## Changes - Added `.pi/extensions/pi-worktree.ts` with four tool registrations: - `git_worktree_list` — no params, lists linked worktrees - `git_worktree_create` — path, branch?, create_branch? params - `git_worktree_switch` — target param for switching cwd - `git_worktree_remove` — path param for removing worktrees - Each tool returns "Not implemented yet." placeholder response ## Testing - [x] All four tools registered with correct TypeBox schemas - [x] Calling each tool returns a response (placeholder) - [ ] Extension loads without errors when pi starts (manual verification needed) ## Checklist - [ ] Self-reviewed the diff - [ ] Code follows project conventions - [ ] Descriptive naming (no single-character variables) Co-authored-by: David Kong <davkon@gmail.com> Reviewed-on: #15
67 lines
3.2 KiB
Markdown
67 lines
3.2 KiB
Markdown
# DOMAIN.md — Git Worktree Concepts
|
|
|
|
## Git Worktrees
|
|
|
|
A git worktree is a linked working directory that shares the same repository but checks out a different branch. Multiple worktrees can exist simultaneously, each on its own branch, without switching branches in any of them.
|
|
|
|
### Key Commands
|
|
|
|
- `git worktree list` — show all linked worktrees with paths and branches
|
|
- `git worktree add <path> [branch]` — create a new linked worktree
|
|
- `git worktree add -b <new-branch> <path>` — create with a new branch
|
|
- `git worktree remove <path>` — remove a linked worktree (refuses if uncommitted changes)
|
|
- `git worktree prune` — clean up stale entries for deleted worktrees
|
|
|
|
### Terminology
|
|
|
|
| Term | Definition |
|
|
|------|-----------|
|
|
| **Main repo** | The original repository directory (where `.git/` lives for non-bare repos) |
|
|
| **Linked worktree** | An additional working directory linked to the same repo via `git worktree add` |
|
|
| **Bare repo** | A `.git/` without a working tree — used as the central store when all worktrees are linked |
|
|
| **Detached HEAD** | When a worktree checks out a commit directly instead of a branch |
|
|
|
|
### Raw Output Format — `git worktree list`
|
|
|
|
The parser should expect this exact pipe-separated format from `git worktree list`:
|
|
|
|
```
|
|
/home/user/project abc1234 [main] # main repo (current)
|
|
/tmp/feature-x def5678 [feature-x] # linked worktree on a branch
|
|
/tmp/detached fedcba HEAD # detached HEAD (no branch name)
|
|
```
|
|
|
|
| Field | Position | Description |
|
|
|-------|----------|-------------|
|
|
| **Path** | Column 1 | Absolute path to the working tree directory |
|
|
| **Hash** | Column 2 | Short commit hash (HEAD) for this worktree |
|
|
| **Branch** | Column 3+ | Branch name in `[brackets]`, or `HEAD` if detached |
|
|
|
|
**Parsing rules:**
|
|
- Lines with `[branch-name]` → the branch is identified by what's inside the brackets.
|
|
- Lines with `HEAD` (no brackets) → detached HEAD; identify this worktree by path only.
|
|
- The first entry in the output is always the main repo — mark it as `isCurrent: true`.
|
|
- Worktrees listed after the first entry are linked worktrees (`isCurrent: false`).
|
|
|
|
### Constraints (from git itself)
|
|
|
|
- You cannot create a nested worktree (worktree inside a worktree).
|
|
- Multiple worktrees on the same branch is possible with `-f` but dangerous and not recommended.
|
|
- `git worktree remove` refuses if there are uncommitted or untracked changes.
|
|
- The main repo counts as a "worktree" in `git worktree list`.
|
|
|
|
## pi Session Concepts
|
|
|
|
| Term | Definition |
|
|
|------|-----------|
|
|
| **Session** | A conversation context within pi, tied to a specific cwd/branch |
|
|
| **Cwd change** | When pi changes its working directory (e.g., switching worktrees) |
|
|
| **Branch display** | The footer indicator showing which git branch pi is tracking |
|
|
| **Back-switching** | Restoring the previous session when returning to the main repo from a worktree |
|
|
|
|
### How Sessions Relate to Worktrees
|
|
|
|
- Each worktree can have its own session for focused context.
|
|
- Switching worktrees updates the branch display automatically (pi reads HEAD from the new cwd).
|
|
- Users are offered a choice: create a fresh session or keep the current one.
|
|
- Back-switching restores the session that was active before leaving the main repo.
|