Git worktree support for bare repos #44

New issue

david · 2026-07-29T21:58:26Z

david commented

2026-07-29 21:58:26 +00:00

Git worktree support for bare repos

When pi-loop is executed from a bare git clone, automatically create a git worktree, cd into it, and run the pipeline normally. Enables CI/CD and server environments where only a bare repo exists.

Design decisions

Decision	Choice
Issue fetch timing	Fetch issue early in CLI preflight when worktree needed; reuse context in pipeline
Worktree location	Same parent dir as bare repo — sibling to `<repo>.git`
Worktree cleanup	Keep worktree after run
Non-bare repos	No worktree support for regular repos
Artifacts location	`.pi-loop/runs/` inside the worktree
Resume detection	Store worktree path in bare repo's `.pi-loop/worktrees/<issue-key>`; fallback: scan parent dir
Error handling	Fail-fast on worktree creation failure
Branch naming	uses `feature/` prefix with provider-specific keys
MR stage	No special worktree awareness needed — `git push` works normally

Branch naming convention

Provider	Branch name	Worktree folder
GitHub	`feature/issue-123/title-of-issue`	`issue-123-title-of-issue`
GitLab	`feature/issue-123/title-of-issue`	`issue-123-title-of-issue`
Forgejo	`feature/issue-123/title-of-issue`	`issue-123-title-of-issue`
Jira	`feature/PROJ-123/title-of-jira-ticket`	`PROJ-123-title-of-jira-ticket`

Implementation plan

See IMPLEMENTATION_PLAN.md §M9 (milestones 9.0–9.5).

9.0 — New branch naming convention (global)

Update buildBranchName() to accept provider and issue number
New naming: feature/issue-<number>/<slug> or feature/<KEY>/<slug>
Export buildBranchFolderName() for worktree-safe names

9.1 — Worktree detection and creation module

New src/shared/git/services/gitWorktree.ts
isBareRepository(), createWorktree(), ensureWorktree()
Registry file: .pi-loop/worktrees/<issue-key>

9.2 — CLI integration

Detect bare repo → fetch issue early → create worktree → set cwd

9.3 — Resume with worktrees

Find existing worktree via registry or scan
Detect when running from inside a worktree

9.4 — Pipeline adjustments

Verify all stages work from worktree (diff, push, etc.)

9.5 — Integration testing and documentation

E2E tests for bare repo and resume
docs/design-worktree.md

# Git worktree support for bare repos When pi-loop is executed from a **bare git clone**, automatically create a git worktree, `cd` into it, and run the pipeline normally. Enables CI/CD and server environments where only a bare repo exists. ## Design decisions | Decision | Choice | |----------|--------| | Issue fetch timing | Fetch issue early in CLI preflight when worktree needed; reuse context in pipeline | | Worktree location | Same parent dir as bare repo — sibling to `<repo>.git` | | Worktree cleanup | Keep worktree after run | | Non-bare repos | No worktree support for regular repos | | Artifacts location | `.pi-loop/runs/` inside the worktree | | Resume detection | Store worktree path in bare repo's `.pi-loop/worktrees/<issue-key>`; fallback: scan parent dir | | Error handling | Fail-fast on worktree creation failure | | Branch naming | uses `feature/` prefix with provider-specific keys | | MR stage | No special worktree awareness needed — `git push` works normally | ## Branch naming convention | Provider | Branch name | Worktree folder | |----------|-------------|-----------------| | GitHub | `feature/issue-123/title-of-issue` | `issue-123-title-of-issue` | | GitLab | `feature/issue-123/title-of-issue` | `issue-123-title-of-issue` | | Forgejo | `feature/issue-123/title-of-issue` | `issue-123-title-of-issue` | | Jira | `feature/PROJ-123/title-of-jira-ticket` | `PROJ-123-title-of-jira-ticket` | ## Implementation plan See `IMPLEMENTATION_PLAN.md` §M9 (milestones 9.0–9.5). ### 9.0 — New branch naming convention (global) - Update `buildBranchName()` to accept provider and issue number - New naming: `feature/issue-<number>/<slug>` or `feature/<KEY>/<slug>` - Export `buildBranchFolderName()` for worktree-safe names ### 9.1 — Worktree detection and creation module - New `src/shared/git/services/gitWorktree.ts` - `isBareRepository()`, `createWorktree()`, `ensureWorktree()` - Registry file: `.pi-loop/worktrees/<issue-key>` ### 9.2 — CLI integration - Detect bare repo → fetch issue early → create worktree → set cwd ### 9.3 — Resume with worktrees - Find existing worktree via registry or scan - Detect when running from inside a worktree ### 9.4 — Pipeline adjustments - Verify all stages work from worktree (diff, push, etc.) ### 9.5 — Integration testing and documentation - E2E tests for bare repo and resume - `docs/design-worktree.md`

david referenced this issue

2026-08-01 11:45:46 +00:00

WIP: 44: Git worktree support for bare repos #150

david commented

2026-08-01 11:45:47 +00:00

pi-loop opened a Draft pull request for this issue: #150

pi-loop opened a Draft pull request for this issue: https://git.excelera.net/david/pi-loop/pulls/150

Sign in to join this conversation.