feat(worktree): Add git worktree support

[tony]

Summary

Resolves #507

• Config format: Define worktrees per repository targeting tags, branches, or commits
• New CLI: vcspull worktree list|sync|prune subcommand
• Integration: --include-worktrees flag added to sync, list, status, search, discover
• Safety: Dirty worktrees block sync operations (BLOCKED action)
• Discovery: Worktrees excluded by default (.git file detection)

Changes

File	Description
types.py	Add WorktreeConfigDict, extend ConfigDict
exc.py	Add worktree exceptions
_internal/worktree_sync.py	Core sync/prune/planning logic
config.py	Parse and validate worktrees config
cli/worktree.py	New worktree subcommand
cli/*.py	Add --include-worktrees flag
cli/discover.py	Add is_git_worktree() helper
test_worktree.py	30 comprehensive tests

Example Config

~/repos/:
  myproject:
    repo: 'git+https://github.com/user/project'
    worktrees:
      - dir: ../myproject-v1.2.3
        tag: v1.2.3
      - dir: ../myproject-develop
        branch: develop

Test plan

• All 767 tests pass
• mypy passes
• ruff check/format passes
• Manual testing with real repositories

[codecov]

Codecov Report

❌ Patch coverage is 84.79853% with 83 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.29%. Comparing base (bcfb4bb) to head (7b906d8).

Files with missing lines	Patch %	Lines
src/vcspull/cli/sync.py	14.81%	22 Missing and 1 partial ⚠️
src/vcspull/config.py	56.81%	11 Missing and 8 partials ⚠️
src/vcspull/cli/list.py	26.31%	12 Missing and 2 partials ⚠️
src/vcspull/_internal/worktree_sync.py	96.06%	5 Missing and 5 partials ⚠️
src/vcspull/cli/discover.py	61.90%	6 Missing and 2 partials ⚠️
src/vcspull/exc.py	55.55%	8 Missing ⚠️
src/vcspull/cli/worktree.py	99.30%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #508      +/-   ##
==========================================
+ Coverage   80.52%   81.29%   +0.77%     
==========================================
  Files          16       18       +2     
  Lines        2192     2727     +535     
  Branches      454      552      +98     
==========================================
+ Hits         1765     2217     +452     
- Misses        277      341      +64     
- Partials      150      169      +19     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This pull request adds comprehensive git worktree support to vcspull, enabling users to manage multiple checkouts of the same repository at different branches, tags, or commits. The feature addresses issue #507, which requested the ability to rapidly clone repositories at different refs for LLM context harvesting and parallel work.

Changes:

• Adds new WorktreeConfigDict type for worktree configuration with support for tags, branches, commits, detachment, and locking options
• Introduces comprehensive worktree sync logic including planning, creation, updating, pruning, and dirty state detection
• Adds new vcspull worktree CLI command with list, sync, and prune subcommands
• Integrates --include-worktrees flag across existing commands (sync, list, status, search, discover)
• Implements worktree detection to exclude them from discovery by default
• Adds 30 tests covering config parsing, path resolution, sync planning, execution, and pruning

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/vcspull/types.py	Defines WorktreeConfigDict with fields for dir, tag/branch/commit refs, detach, lock, and lock_reason
src/vcspull/exc.py	Adds worktree-specific exception classes (WorktreeError, WorktreeExistsError, WorktreeRefNotFoundError, WorktreeConfigError, WorktreeDirtyError)
src/vcspull/_internal/worktree_sync.py	Core worktree synchronization logic including planning, creation, update, pruning, and validation functions
src/vcspull/config.py	Adds _validate_worktrees_config function to parse and validate worktree configuration from YAML/JSON
src/vcspull/cli/worktree.py	New CLI command with list/sync/prune subcommands, output formatting, and color-coded status indicators
src/vcspull/cli/__init__.py	Integrates worktree command into main CLI parser and routing
src/vcspull/cli/sync.py	Adds --include-worktrees flag and integrates worktree sync after main repo sync
src/vcspull/cli/list.py	Adds --include-worktrees flag to display worktrees in flat and tree views
src/vcspull/cli/status.py	Adds --include-worktrees flag stub for future status integration
src/vcspull/cli/search.py	Adds --include-worktrees flag stub for future search integration
src/vcspull/cli/discover.py	Adds is_git_worktree() helper and --include-worktrees flag to control worktree discovery
tests/test_worktree.py	Comprehensive test suite with 30 tests covering config parsing, validation, sync, prune, and CLI integration
tests/test_log.py	Updates logger name list to include vcspull.cli.worktree

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tony]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}