Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(CLAUDE.md): streamline and add Quick Start section (#886)
Maximilian Roosf429f6329fff
diff --git a/CLAUDE.md b/CLAUDE.mdindex 70d9b0e05..78dce5c46 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,6 +1,12 @@# Worktrunk Development Guidelines-> **Note**: This CLAUDE.md is just getting started. More guidelines will be added as patterns emerge.+## Quick Start++```bash+cargo run -- hook pre-merge --yes # run all tests + lints (do this before committing)+```++For Claude Code web environments, run `task setup-web` first. See [Testing](#testing) for more commands.## Project Status@@ -50,40 +56,33 @@ Key skills:### Running Tests```bash-# Run all tests + lints (recommended before committing)+# All tests + lints (recommended before committing)cargo run -- hook pre-merge --yes++# Tests with coverage report → target/llvm-cov/html/index.html+task coverage```**For faster iteration:**```bash-# Lints only-pre-commit run --all-files--# Unit tests only-cargo test --lib --bins--# Integration tests (no shell tests)-cargo test --test integration--# Integration tests with shell tests (requires bash/zsh/fish)-cargo test --test integration --features shell-integration-tests+pre-commit run --all-files # lints only+cargo test --lib --bins # unit tests only+cargo test --test integration # integration tests (no shell tests)+cargo test --test integration --features shell-integration-tests # with shell tests```### Claude Code Web Environment-When working in Claude Code web, install the task runner and run setup:+Run `task setup-web` to install required shells (zsh, fish), `gh`, and other dev tools. Install `task` first if needed:```bash-# Install task (go-task) - https://taskfile.devsh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/binexport PATH="$HOME/bin:$PATH"--# Run setuptask setup-web```-This installs required shells (zsh, fish) for shell integration tests and builds the project. Also installs `gh` and other dev tools—run this if any command is not found. The permission tests (`test_permission_error_prevents_save`, `test_approval_prompt_permission_error`) automatically skip when running as root, which is common in containerized environments.+The permission tests (`test_permission_error_prevents_save`, `test_approval_prompt_permission_error`) skip automatically when running as root.### Shell/PTY Integration Tests@@ -254,59 +253,27 @@ Examples: `feature-user-post-start-npm.log`, `feature-project-post-start-build.lThe `codecov/patch` CI check enforces coverage on changed lines — respond to failures by writing tests, not by ignoring them. If code is unused, remove it. This includes specialized error handlers for rare cases when falling through to a more general handler is sufficient.-### Running Coverage Locally--```bash-task coverage # includes --features shell-integration-tests-# Report: target/llvm-cov/html/index.html-```--Install once: `cargo install cargo-llvm-cov`-### Investigating codecov/patch Failures-When CI shows a codecov/patch failure, investigate before declaring "ready to merge" — even if the check is marked "not required":+When CI shows a codecov/patch failure, investigate before declaring "ready to merge":-1. Identify uncovered lines in your changes:- ```bash- task coverage # run tests, generate coverage- cargo llvm-cov report --show-missing-lines | grep <file> # query the report- git diff main...HEAD -- path/to/file.rs- ```--2. For each uncovered function/method you added, either:- - Write a test that exercises it, or- - Document why it's intentionally untested (e.g., error paths requiring external system mocks)--### How Coverage Works with Integration Tests--Coverage is collected via `cargo llvm-cov` which instruments the binary. **Subprocess execution IS captured** — when tests spawn `wt` via `assert_cmd_snapshot!`, the instrumented binary writes coverage data to profile files that get merged into the report.--When investigating uncovered lines:--1. Run `task coverage` first to see actual coverage % (~92% is normal)-2. Use `cargo llvm-cov report --show-missing-lines | grep <file>` to find specific uncovered lines-3. **Check if tests already exist** for that functionality before writing new ones-4. Remaining uncovered lines are typically:- - Error handling paths requiring mocked git failures- - Edge cases in shell integration states (e.g., running as `git wt`)- - Test assertion code (only executes when tests fail)+```bash+task coverage # run tests, generate coverage+cargo llvm-cov report --show-missing-lines | grep <file> # find uncovered lines+```-Code that only runs on test failure (assertion messages, custom panic handlers) shows as uncovered since tests pass. Keep this code minimal — useful for debugging but a rarely-traveled path.+For each uncovered function/method, either write a test or document why it's intentionally untested. Integration tests (via `assert_cmd_snapshot!`) do capture subprocess coverage.## Benchmarks-See `benches/CLAUDE.md` for details.+Benchmarks measure `wt list` performance across worktree counts and repository sizes.```bash-# Fast synthetic benchmarks (skip slow ones)-cargo bench --bench list -- --skip cold --skip real--# Specific benchmark-cargo bench --bench list bench_list_by_worktree_count+cargo bench --bench list -- --skip cold --skip real # fast synthetic benchmarks+cargo bench --bench list bench_list_by_worktree_count # specific benchmark```-Real repo benchmarks clone rust-lang/rust (~2-5 min first run, cached thereafter). Skip with `--skip real`.+Real repo benchmarks clone rust-lang/rust (~2-5 min first run, cached thereafter). Skip with `--skip real`. See `benches/CLAUDE.md` for methodology and adding new benchmarks.## JSON Output Format@@ -343,6 +310,44 @@ fn validate_config() { ... }Never use `#[cfg(test)]` to add test-only convenience methods to library code. Tests should call the real API directly. If tests need helpers, define them in the test module.+## Error Handling++Use `anyhow` for error propagation with context:++```rust+use anyhow::{bail, Context, Result};++// Prefer .context() for adding helpful error messages+let data = std::fs::read_to_string(path)+ .context("Failed to read config file")?;++// Use bail! for early returns with formatted errors+if worktree.is_dirty() {+ bail!("worktree has uncommitted changes");+}+```++**Patterns:**++- **Use `bail!`** for business logic errors (dirty worktree, missing branch, invalid state)+- **Use `.context()`** for wrapping I/O and external command failures+- **Don't `logger.error` before raising** — include context in the error message itself+- **Let errors propagate** — don't catch and re-raise without adding information++## Adding CLI Commands++CLI commands live in `src/cli/` with implementations in `src/commands/`.++1. **Add subcommand** to `Cli` enum in `src/cli/mod.rs`+2. **Create command module** in `src/commands/` (e.g., `src/commands/mycommand.rs`)+3. **Add `after_long_help`** attribute for extended help that syncs to docs+4. **Run doc sync** after adding help text:+ ```bash+ cargo test --test integration test_command_pages_and_skill_files_are_in_sync+ ```++Help text in `after_long_help` is the source of truth for `docs/content/{command}.md`.+## Accessor Function Naming ConventionsFunction prefixes signal return behavior and side effects.@@ -370,69 +375,16 @@ Function prefixes signal return behavior and side effects.- Don't use `load_*` for computed values (use bare nouns)- Don't use `get_*` prefix — use bare nouns instead (Rust convention)-## Repository Caching Strategy--Most data is stable for the duration of a command. The only things worktrunk modifies are:+## Repository Caching-- **Worktree list** — `wt switch --create`, `wt remove` create/remove worktrees-- **Working tree state** — `wt merge` commits, stages files-- **Git config** — `wt config` modifies settings--Everything else (remote URLs, project config, branch metadata) is read-only.--### Caching Implementation--`Repository` holds its cache directly via `Arc<RepoCache>`. Cloning a Repository shares the cache — all clones see the same cached values.--**Key patterns:**--- **Command entry points** create Repository via `Repository::current()` or `Repository::at(path)`-- **Parallel tasks** (e.g., `wt list`) clone the Repository, sharing the cache-- **Tests** naturally get isolation since each test creates its own Repository--**Currently cached:**--- `git_common_dir` — computed at construction, stored on struct-- `worktree_root()` — per-worktree, keyed by path-- `repo_path()` — derived from git_common_dir and is_bare-- `is_bare()` — git config, doesn't change-- `current_branch()` — per-worktree, keyed by path-- `project_identifier()` — derived from remote URL-- `primary_remote()` — git config, doesn't change-- `primary_remote_url()` — derived from primary_remote, doesn't change-- `default_branch()` — from git config or detection, doesn't change-- `integration_target()` — effective target for integration checks (local default or upstream if ahead)-- `merge_base()` — keyed by (commit1, commit2) pair-- `ahead_behind` — keyed by (base_ref, branch_name), populated by `batch_ahead_behind()`-- `project_config` — loaded from .config/wt.toml--**Not cached (intentionally):**+Most data is stable for the duration of a command. `Repository` caches read-only values (remote URLs, config, branch metadata) via `Arc<RepoCache>` — cloning a Repository shares the cache.+**Not cached (changes during command execution):**- `is_dirty()` — changes as we stage/commit- `list_worktrees()` — changes as we create/remove worktrees-### Adding New Cached Methods--1. Add field to `RepoCache` struct: `field_name: OnceCell<T>`-2. Access via `self.cache.field_name`-3. Return owned values (String, PathBuf, bool)+When adding new cached methods, see `RepoCache` in `src/git/repository/mod.rs` for patterns (repo-wide via `OnceCell`, per-worktree via `DashMap`).-```rust-// For repo-wide values (same for all clones)-pub fn cached_value(&self) -> anyhow::Result<String> {- self.cache- .field_name- .get_or_init(|| { /* compute value */ })- .clone()-}+## Releases-// For per-worktree values (different per worktree path)-// Use DashMap for concurrent access-pub fn cached_per_worktree(&self, path: &Path) -> String {- self.cache- .field_name- .entry(path.to_path_buf())- .or_insert_with(|| { /* compute value */ })- .clone()-}-```+Use the `release` skill for cutting releases. It handles version bumping, changelog generation, crates.io publishing, and GitHub releases.