Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Remove TODO.md as it is no longer needed

Maximilian Roos33885733c688
diff --git a/TODO.md b/TODO.md
deleted file mode 100644
index db4389446..000000000
--- a/TODO.md
+++ /dev/null
@@ -1,630 +0,0 @@
-# Worktrunk: Git Worktree Management in Rust
-
-Port of git worktree fish functions to a Rust crate with enhanced capabilities.
-
-## Analysis of Existing Functionality
-
-The fish functions provide:
-- **git-worktree-switch**: Create/switch to worktrees with branch management
-- **git-worktree-finish**: Cleanup and return to primary worktree
-- **git-worktree-push**: Fast-forward push between worktrees with conflict detection
-- **git-worktree-merge**: Rebase, merge, and cleanup with optional squashing
-- **git-worktree-llm**: Convenience wrapper for LLM-assisted development
-
-## Workstreams
-
-### 1. Foundation: Git Primitives
-Core git operations that all other components depend on.
-
-**Key capabilities:**
-- Execute git commands and parse output
-- Detect repository state (current branch, default branch, dirty state)
-- Find git directories (git-dir, common-dir, toplevel)
-- Parse worktree list (porcelain format)
-- Check merge ancestry and fast-forward status
-- Detect operations in progress (merge, rebase, cherry-pick)
-
-**Dependencies:** `std::process::Command` for shelling out to git
-
-### 2. Worktree Core
-Primary worktree management operations.
-
-**Key capabilities:**
-- List existing worktrees with branch associations
-- Create worktrees (with/without new branch, custom base)
-- Switch to existing worktrees (cd integration)
-- Remove worktrees (foreground/background)
-- Validate worktree state and detect missing directories
-
-**Dependencies:** Workstream 1 (Git Primitives)
-
-**Challenges:** Shell integration for `cd` - may need to output shell commands for sourcing
-
-### 3. Advanced Operations
-Complex multi-step operations involving multiple worktrees.
-
-**Key capabilities:**
-- Fast-forward push between worktrees
- - Validate ancestry and fast-forward status
- - Detect and handle merge commits
- - Stash/unstash in target worktree
- - Detect file conflicts between push and working tree
- - Configure `receive.denyCurrentBranch`
-- Merge and cleanup workflow
- - Auto-commit dirty state
- - Squash commits with rebase
- - Fast-forward target branch
- - Finish worktree after merge
-- Branch finishing (commit, cleanup, switch)
-
-**Dependencies:** Workstreams 1, 2, and 4 (for user confirmation)
-
-### 4. CLI and UX
-Command-line interface with rich user experience.
-
-**Key capabilities:**
-- Argument parsing (likely using `clap`)
-- Colored terminal output (similar to fish functions)
-- Progress indicators
-- Error messages with actionable suggestions
-- Subcommand structure (switch, finish, push, merge)
-
-**Dependencies:** `clap` for argument parsing, `anstream`/`anstyle` for terminal colors (from rust-cli ecosystem)
-
-### 5. External Integrations
-Interface with shell and external tools.
-
-**Key capabilities:**
-- Execute shell commands (git-commit-llm, claude, task)
-- Background process management (disown equivalent)
-- Shell function generation (for `cd` integration)
-
-**Dependencies:** Workstream 1
-
-**Design considerations:**
-- How to handle `cd` in a compiled binary? Options:
- - Output shell commands to eval
- - Generate shell wrapper functions
- - Use shell integration (similar to `zoxide`)
-
-### 6. Testing and Validation
-Ensure correctness with real git repositories.
-
-**Key capabilities:**
-- Integration tests with temporary git repos
-- Test multiple worktree scenarios
-- Validate edge cases (conflicts, missing dirs, operations in progress)
-- Test shell integration
-
-**Dependencies:** All workstreams
-
-**Tools:** `tempfile` crate for temporary directories, possibly `insta` for snapshot testing
-
-## Implementation Order
-
-1. **Phase 1: Foundation**
- - Workstream 1: Git Primitives (core library)
- - Workstream 4: Basic CLI (minimal viable interface)
-
-2. **Phase 2: Core Operations**
- - Workstream 2: Worktree Core (switch, list, create, remove)
- - Workstream 6: Basic testing
-
-3. **Phase 3: Advanced Features**
- - Workstream 3: Advanced Operations (push, merge)
- - Workstream 5: External Integrations
- - Workstream 6: Comprehensive testing
-
-## Shell Integration Design
-
-**Decision: Use the "eval init" pattern** (proven by zoxide, starship, direnv, pyenv)
-
-### Architecture
-
-```
-wt (Rust binary)
-├── Core commands (work standalone)
-│ ├── wt list
-│ ├── wt remove
-│ └── wt status
-├── Internal commands (for shell wrapper)
-│ ├── wt switch --internal → outputs __WORKTRUNK_CD__ directives
-│ └── wt finish --internal → outputs __WORKTRUNK_CD__ directives
-└── Shell integration
- └── wt init <shell> → outputs shell wrapper functions
-```
-
-### Implementation Pattern
-
-**User setup (one-time):**
-```bash
-# Add to ~/.bashrc or ~/.config/fish/config.fish
-eval "$(wt init bash)" # or: wt init fish | source
-```
-
-**Generated shell wrapper:**
-```bash
-wt-switch() {
- local output
- output=$(wt switch --internal "$@")
-
- # Parse output for special directives
- while IFS= read -r line; do
- case "$line" in
- __WORKTRUNK_CD__*)
- cd "${line#__WORKTRUNK_CD__}"
- ;;
- *)
- echo "$line"
- ;;
- esac
- done <<< "$output"
-}
-```
-
-### Communication Protocol
-
-- Rust binary outputs special directives mixed with regular output
-- Shell wrapper parses and acts on directives
-- Separation: Rust handles git logic, shell handles `cd`
-
-**Directive format:**
-```
-__WORKTRUNK_CD__/path/to/worktree
-Regular output line
-Another output line
-```
-
-### Key Components
-
-1. **Template Engine**: Use Askama for type-safe shell code generation
-2. **Shell Support**: Start with Bash and Fish, extend to Zsh later
-3. **Customization Flags**:
- - `--cmd <prefix>`: Customize command prefix (default: "wt")
-
-4. **Progressive Enhancement Levels**:
- - Level 0: Just the binary - works but requires manual `cd`
- - Level 1: Shell wrapper - auto-`cd` on switch
-
-### Implementation Phases
-
-**Phase 1: Foundation** (MVP)
-- [ ] Add Askama dependency
-- [ ] Create `Shell` enum (Bash, Fish, Zsh)
-- [ ] Create `ShellInit` struct with template rendering
-- [ ] Implement `wt init <shell>` command
-- [ ] Create Bash template with basic wrapper functions
-- [ ] Create Fish template with basic wrapper functions
-- [ ] Implement `__WORKTRUNK_CD__` directive protocol
-
-**Phase 2: Integration**
-- [ ] Add `--internal` flag to `switch` and `finish` commands
-- [ ] Output directives from internal commands
-- [ ] Test integration across shells
-
-**Phase 3: Enhancement**
-- [ ] Add `--cmd` flag for command prefix customization
-- [ ] Implement shell completion generation
-- [ ] Add Zsh support
-
-### Design Principles (from research)
-
-- **Keep execution fast** (<500ms) - don't block the shell (direnv)
-- **Use Askama** for type-safe templates (zoxide)
-- **Support customizable command prefixes** (zoxide `--cmd`)
-- **Keep binary stateless** (starship)
-- **Make shell integration minimal** (starship)
-
-### Examples from Other Tools
-
-- **zoxide**: `eval "$(zoxide init bash)"` → generates `z` and `zi` functions
-- **starship**: `eval "$(starship init bash)"` → generates prompt customization
-- **direnv**: `eval "$(direnv hook bash)"` → generates `_direnv_hook` function
-- **pyenv**: `eval "$(pyenv init -)"` → sets up shims + shell functions
-
-## Shell Completion (Autocomplete)
-
-**Decision: Two-tier completion system**
-1. **Tier 1 (Static)**: Command and flag completion via `clap_complete`
-2. **Tier 2 (Dynamic)**: Branch and worktree completion via callback protocol
-
-### Architecture
-
-```
-User presses [TAB]
- ↓
-Shell-specific completion script (generated by: wt completion <shell>)
- ↓
-Static path: subcommands/flags (from clap metadata)
- ↓
-Dynamic path: wt __complete <args...>
- ↓
-Rust queries git and returns: branch names, worktree paths, etc.
-```
-
-### Implementation Phases
-
-**Phase 1: Static Completion** (Quick Win - 2-4 hours)
-- [ ] Add `clap_complete` dependency to Cargo.toml
-- [ ] Create `Shell` enum compatible with `clap_complete::Shell`
-- [ ] Add `Completion` subcommand: `wt completion <shell>`
-- [ ] Implement `handle_completion()` using `clap_complete::generate()`
-- [ ] Test completion generation for Fish, Bash, Zsh
-- [ ] Update README with installation instructions
-
-**Phase 2: Git Primitives for Dynamic Completion** (Foundation - 2-3 hours)
-- [ ] Add `get_all_branches()` to `src/git.rs`
- - Uses: `git branch --format='%(refname:short)'`
- - Returns: `Vec<String>` of branch names
-- [ ] Add `get_available_branches()` helper
- - Filters out branches that already have worktrees
- - Used for `wt switch` completion
-- [ ] Add unit tests for branch listing functions
-- [ ] Performance test: ensure <100ms for repos with 100+ branches
-
-**Phase 3: Dynamic Completion Backend** (Core - 4-6 hours)
-- [ ] Add hidden `__complete` command to `Commands` enum
- - Mark with `#[command(hide = true)]`
- - Takes trailing args: `args: Vec<String>`
-- [ ] Implement `CompletionContext` enum:
- - `SwitchBranch` - complete available branches
- - `PushTarget` - complete all branches
- - `MergeTarget` - complete all branches
- - `BaseFlag` - complete all branches for `--base`
- - `Unknown` - no completions
-- [ ] Implement `parse_completion_context()`:
- - Parse command line: `["wt", "switch", "feat"]`
- - Determine what position we're completing
- - Return appropriate `CompletionContext`
-- [ ] Implement context-specific completion functions:
- - `complete_available_branches()` - for `switch`
- - `complete_all_branches()` - for `push`, `merge`, `--base`
-- [ ] Implement `handle_complete()` main dispatcher
-- [ ] Add unit tests for context parsing
-- [ ] Add integration tests for completion output
-
-**Phase 4: Shell Template Enhancement** (Polish - 3-4 hours)
-- [ ] Enhance `templates/fish.fish`:
- - Add `__wt_complete` function that calls `wt __complete`
- - Add `complete -c wt` rules for dynamic completion
- - Test with real Fish shell
-- [ ] Enhance `templates/bash.sh`:
- - Add `_wt_complete()` bash completion function
- - Register with `complete -F _wt_complete wt`
- - Test with real Bash shell
-- [ ] Create `templates/zsh.zsh`:
- - Add `_wt_complete()` zsh completion function
- - Add zsh-specific completion registration
- - Test with real Zsh shell
-- [ ] Update `shell.rs` to include completion code in templates
-- [ ] Test all three shells with various completion scenarios
-
-**Phase 5: Integration & Testing** (Validation - 2-3 hours)
-- [ ] Manual testing checklist:
- - [ ] Fish: `wt sw<TAB>` shows `switch`
- - [ ] Fish: `wt switch <TAB>` shows available branches
- - [ ] Fish: `wt push <TAB>` shows all branches
- - [ ] Bash: same as Fish tests
- - [ ] Zsh: same as Fish tests
-- [ ] Performance testing:
- - [ ] Measure `wt __complete` response time
- - [ ] Target: <100ms for typical repos
- - [ ] Test with repo containing 100+ branches
-- [ ] Edge case testing:
- - [ ] Completion in non-git directory (should fail gracefully)
- - [ ] Completion with no branches
- - [ ] Completion with partial branch names
-- [ ] Documentation:
- - [ ] Update README with completion installation
- - [ ] Add performance notes
- - [ ] Document `wt completion` usage
-
-### Completion Context Logic
-
-```rust
-// Example completion contexts based on command line:
-
-["wt", "switch", "feat"]
-→ CompletionContext::SwitchBranch
-→ Output: branches without worktrees matching "feat*"
-
-["wt", "push", "ma"]
-→ CompletionContext::PushTarget
-→ Output: all branches matching "ma*"
-
-["wt", "switch", "--create", "new", "--base", "dev"]
-→ CompletionContext::BaseFlag
-→ Output: all branches matching "dev*"
-```
-
-### Performance Requirements
-
-- **Target:** <100ms for completion response
-- **Acceptable:** <200ms
-- **Optimization strategies (if needed):**
- - Cache branch list with 5-10 second TTL
- - Read `.git/refs/heads/*` directly instead of `git branch`
- - Stream results instead of collecting to vector
-
-### Shell-Specific Output Formats
-
-**Fish:** Supports descriptions
-```
-main Default branch
-develop Development branch
-```
-
-**Bash/Zsh:** Plain list
-```
-main
-develop
-```
-
-### Installation Instructions (for README)
-
-```bash
-# Fish
-wt completion fish > ~/.config/fish/completions/wt.fish
-
-# Bash (add to ~/.bashrc)
-eval "$(wt completion bash)"
-
-# Zsh (add to ~/.zshrc)
-eval "$(wt completion zsh)"
-```
-
-**Note:** Users must regenerate completion scripts after updating `wt`.
-
-### Testing Strategy
-
-**Unit tests:**
-```rust
-#[test]
-fn test_parse_completion_context_switch() {
- let args = vec!["wt".to_string(), "switch".to_string(), "feat".to_string()];
- assert_eq!(
- parse_completion_context(&args),
- CompletionContext::SwitchBranch
- );
-}
-
-#[test]
-fn test_complete_available_branches() {
- // Create test repo with branches and worktrees
- // Verify only available branches returned
-}
-```
-
-**Integration tests:**
-```bash
-# Test actual shell completion behavior
-# (requires manual testing in real shells)
-```
-
-### Design Decisions
-
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| Static library | `clap_complete` | Official, well-integrated with clap |
-| Dynamic protocol | Callback via `__complete` | Proven by gh, kubectl, git |
-| Performance target | <100ms | Perceived as instant by users |
-| Command name | `wt completion <shell>` | Industry standard convention |
-| Hidden command | `wt __complete` | Prevents accidental user invocation |
-
-## Open Questions
-
-1. ~~**Shell integration approach**: How to handle `cd` in a compiled binary?~~
- - ✅ **RESOLVED**: Use "eval init" pattern with directive protocol
- - Generate shell-specific wrapper functions via Askama templates
- - Binary outputs `__WORKTRUNK_CD__<path>` directives, shell wrapper executes `cd`
-
-2. **External command dependencies**: How to handle git-commit-llm, claude, task?
- - Configurable hooks?
- - Plugin system?
- - Just execute if available?
-
-3. **Cross-platform support**: Focus on Unix-like systems only or support Windows?
- - Fish-specific features may not translate
-
-4. **Git library choice**: ✅ **DECIDED: Shell out to git commands**
- - Use `std::process::Command` directly (no wrapper crates needed)
- - Parse `--porcelain` formats for stability
- - Rationale: libgit2 lags behind git on worktree features, proven approach from vergen-gitcl and PRQL
- - Git is already required for worktrees to exist, so no additional runtime dependency
-
-## Testing Strategy
-
-### Approach: Snapshot Testing with Insta
-
-We'll use `insta` and `insta_cmd` for snapshot-based testing of both library functions and CLI commands.
-
-**Rationale:**
-- Snapshot tests capture actual git behavior, not mocked approximations
-- Easy to review changes to output formats
-- Faster to write comprehensive tests (no manual assertion writing)
-- Tests serve as living documentation of expected behavior
-
-### Test Structure
-
-Following Rust 2018+ conventions:
-
-```
-tests/
- common/
- mod.rs # Shared test helpers (TestRepo, etc.)
- test_list.rs # Integration tests for `wt list`
- test_switch.rs # Integration tests for `wt switch` (future)
- test_finish.rs # Integration tests for `wt finish` (future)
- snapshots/ # Generated by insta
- test_list__*.snap
-```
-
-### Test Helpers (tests/common/mod.rs)
-
-**Core helpers:**
-1. `TestRepo::new()` - Create temp git repo with isolated environment
-2. `TestRepo::add_worktree(name, branch)` - Add worktree, return path, track by name
-3. `TestRepo::commit(message)` - Make commit with fixed author/committer dates
-4. `TestRepo::detach_head()` - Create detached HEAD state
-5. `TestRepo::lock_worktree(name, reason)` - Lock a worktree with optional reason
-6. `TestRepo::root_path()` - Get root repo path for normalization
-7. `TestRepo::worktree_path(name)` - Get worktree path by semantic name
-
-**Environment Isolation (critical for test stability):**
-- Set `GIT_CONFIG_GLOBAL=/dev/null` - Ignore user's global config
-- Set `GIT_CONFIG_SYSTEM=/dev/null` - Ignore system config
-- Set `user.name = "Test User"` and `user.email = "[email protected]"`
-- Set `GIT_AUTHOR_DATE = "2025-01-01T00:00:00Z"` - Fixed commit timestamps
-- Set `GIT_COMMITTER_DATE = "2025-01-01T00:00:00Z"`
-- Set `LC_ALL=C` and `LANG=C` - Force English git messages
-- Set `SOURCE_DATE_EPOCH=1704067200` - Reproducible builds
-
-### Snapshot Normalization Strategy
-
-**Challenge:** Git output contains non-deterministic data:
-- Absolute paths (different per test run, per machine)
-- Git SHAs (different per test run)
-- Path separators (Windows `\` vs Unix `/`)
-
-**Solution:** Use insta's built-in filter system
-
-```rust
-use insta::Settings;
-use std::process::Command;
-
-fn snapshot_cmd(repo: &TestRepo, args: &[&str]) -> String {
- let mut settings = Settings::clone_current();
-
- // Normalize paths - replace absolute paths with semantic names
- settings.add_filter(repo.root_path().to_str().unwrap(), "[REPO]");
- for (name, path) in &repo.worktrees {
- settings.add_filter(path.to_str().unwrap(), &format!("[WORKTREE_{}]", name.to_uppercase()));
- }
-
- // Normalize git SHAs (7-40 hex chars) to [SHA]
- settings.add_regex(r"\b[0-9a-f]{7,40}\b", "[SHA]");
-
- // Normalize Windows paths to Unix style
- settings.add_regex(r"\\", "/");
-
- settings.bind(|| {
- assert_cmd_snapshot!(Command::new(get_cargo_bin("wt")).args(args));
- });
-}
-```
-
-**Key decisions:**
-- ✅ **Use insta filters from the start** (not custom string replacement)
-- ✅ **Track worktrees by semantic name** (not index) for stability
-- ✅ **Normalize path separators** for cross-platform snapshots
-- ✅ **Use regex for SHA normalization** (requires `regex` crate in filters)
-
-### Test Scenarios
-
-**Basic scenarios (Phase 1):**
-1. Single worktree (main only)
-2. Multiple worktrees on different branches
-3. Detached HEAD worktree
-4. Bare repository worktree
-5. Locked worktree (with and without reason)
-6. Prunable worktree (removed directory)
-
-**Edge cases (Phase 2):**
-7. Worktree with dirty state
-8. Worktree with merge in progress
-9. Worktree with rebase in progress
-10. Missing worktree directory
-11. Worktree at repository root
-12. Nested worktree paths
-
-**Advanced scenarios (Phase 3):**
-13. Fast-forward push scenarios
-14. Merge conflict scenarios
-15. Squash merge scenarios
-16. Multiple worktrees with same base commit
-
-**Error cases (all phases):**
-17. Running outside a git repository
-18. Invalid command arguments
-19. Attempting to create worktree with existing name
-20. Permission denied on worktree directory
-21. Corrupted git state (missing refs, invalid objects)
-
-### Dependencies
-
-```toml
-[dev-dependencies]
-insta = { version = "1.40", features = ["yaml", "redactions", "filters"] }
-insta-cmd = "0.6"
-assert_cmd = "2.0" # For get_cargo_bin() helper
-tempfile = "3.14" # For temporary test directories
-```
-
-**Notes:**
-- `yaml` feature for readable snapshots
-- `redactions` and `filters` for path/SHA normalization with regex
-- `assert_cmd` provides `get_cargo_bin()` for locating test binaries
-
-### Workflow
-
-**Development:**
-1. Build binary: `cargo build` (required before insta-cmd tests)
-2. Write test that creates git repo scenario
-3. Run `cargo insta test` - creates initial snapshots
-4. Review snapshots with `cargo insta review`
-5. Accept/reject changes, commit accepted snapshots
-6. Future changes: `cargo insta test` shows diffs, review and accept/reject
-
-**CI:**
-- Run `cargo insta test --check` - fails if snapshots need review
-- Rejects PRs with pending snapshot reviews or missing snapshots
-- Use `--test-threads=1` if global state isolation issues arise
-
-### Implementation Decisions
-
-1. ✅ **Normalization:** Use insta's built-in filters (not custom string replacement)
-2. ✅ **Binary build:** Explicit `cargo build` step documented in workflow
-3. ✅ **Snapshot format:** External files for all tests (easier PR review)
-4. ✅ **Test structure:** Follow Rust 2018+ conventions (`tests/common/`, not `tests/integration/`)
-5. ✅ **Worktree tracking:** Semantic names (not indices) for stable snapshots
-6. ✅ **Git version:** Document minimum required version (2.5+) in tests
-
-## Success Criteria
-
-- [ ] Can create and switch between worktrees from CLI
-- [ ] Can push fast-forward changes between worktrees
-- [ ] Can merge and cleanup worktrees
-- [ ] Provides colored, user-friendly output
-- [ ] Handles edge cases gracefully (dirty state, conflicts, missing directories)
-- [ ] Integrates with shell for directory changes
-- [ ] Passes integration tests with real git repositories
-
-## Future Enhancements
-
-### Table Formatting for Output
-
-Currently using plain text output. Consider adding table formatting for commands like `wt list` to improve readability.
-
-**Options researched:**
-
-1. **tabled** (https://github.com/zhiburt/tabled)
- - Derive-based approach (`#[derive(Tabled)]` on structs)
- - Extensive styling options and themes
- - Well-maintained, active development
- - Best for: Direct struct-to-table rendering
-
-2. **comfy-table** (https://github.com/Nukesor/comfy-table)
- - Manual table building with excellent content wrapping
- - Rock-solid, considered "finished" (minimal breaking changes)
- - Very well tested, no unsafe code
- - Best for: Dynamic tables with manual control
-
-3. **cli-table** (https://github.com/devashishdxt/cli-table)
- - Middle ground between tabled and comfy-table
- - Supports both derive and manual building
-
-**Compatibility:**
-- All three libraries support `anstyle` for colors, integrating well with our existing rust-cli ecosystem dependencies
-- The `rust-cli` organization doesn't have a dedicated table library, so we'd need to use a third-party crate
-
-**Decision:** Deferred until we have clearer requirements for table formatting. Current plain text output is functional.