Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Reorganize CLAUDE.md: lead with pre-merge, move docs to subdirs (#224)
Maximilian Roosa9d24f6b99d4
diff --git a/CLAUDE.md b/CLAUDE.mdindex caed82035..c3ca99dbf 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -45,22 +45,29 @@ Avoid mixing: "main/default branch worktree" is confusing. Use "main worktree" f### Running Tests```bash-# Unit tests (fast)+# Run all tests + lints (recommended before committing)+cargo run -- hook pre-merge --force+```++The pre-merge hook runs lints and the full test suite.++**For faster iteration during development:**++```bash+# Lints only+pre-commit run --all-files++# Unit tests onlycargo test --lib --bins-# Integration tests without shell tests (no external dependencies)+# Integration tests (no shell tests)cargo test --test integration-# Integration tests WITH shell tests (requires bash/zsh/fish)+# Integration tests with shell tests (requires bash/zsh/fish)cargo test --test integration --features shell-integration-tests--# Run all tests via pre-merge hook (recommended before committing)-cargo run -- hook pre-merge --force```-The pre-merge hook runs the full test suite and is the recommended way to verify changes before committing.--**Shell integration tests** require bash, zsh, and fish. On Linux, run `./dev/setup-claude-code-web.sh` to install them.+**Shell integration tests** require bash, zsh, and fish.### Claude Code Web Environment@@ -70,7 +77,7 @@ When working in Claude Code web, run the setup script first:./dev/setup-claude-code-web.sh```-This installs required shells (zsh, fish) and builds the project. 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.+This installs required shells (zsh, fish) for shell integration tests and builds the project. 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.### Shell/PTY Integration Tests@@ -86,21 +93,6 @@ NEXTEST_NO_INPUT_HANDLER=1 cargo nextest run --features shell-integration-testsThe pre-merge hook already sets `NEXTEST_NO_INPUT_HANDLER=1`.-### CLI Flag Descriptions--Keep the first line of flag and argument descriptions brief—aim for 3-6 words. Use parenthetical defaults sparingly, only when the default isn't obvious from context.--**Good examples:**-- `/// Skip approval prompts`-- `/// Show CI and \`main\` diffstat`-- `/// Target branch (defaults to default branch)`--**Bad examples (too verbose):**-- `/// Auto-approve project commands without saving approvals.`-- `/// Show CI status, conflict detection, and complete diff statistics`--The help text should be scannable. Users reading `wt switch --help` need to quickly understand what each flag does without parsing long sentences.-## Command Execution Principles### Real-time Output Streaming@@ -140,59 +132,6 @@ Examples (where command names are from config):Users can clean up old logs manually or use a git hook. No automatic cleanup is provided.-## Testing Guidelines--### Timing Tests: Long Timeouts with Fast Polling--**Core principle:** Use long timeouts (5+ seconds) for reliability on slow CI, but poll frequently (10-50ms) so tests complete quickly when things work.--This achieves both goals:-- **No flaky failures** on slow machines - generous timeout accommodates worst-case-- **Fast tests** on normal machines - frequent polling means no unnecessary waiting--```rust-// ✅ GOOD: Long timeout, fast polling-let timeout = Duration::from_secs(5);-let poll_interval = Duration::from_millis(10);-let start = Instant::now();-while start.elapsed() < timeout {- if condition_met() { break; }- thread::sleep(poll_interval);-}--// ❌ BAD: Fixed sleep (always slow, might still fail)-thread::sleep(Duration::from_millis(500));-assert!(condition_met());--// ❌ BAD: Short timeout (flaky on slow CI)-let timeout = Duration::from_millis(100);-```--Use the helpers in `tests/common/mod.rs`:--```rust-use crate::common::{wait_for_file, wait_for_file_count};--// ✅ Poll for file existence with 5+ second timeout-wait_for_file(&log_file, Duration::from_secs(5));--// ✅ Poll for multiple files-wait_for_file_count(&log_dir, "log", 3, Duration::from_secs(5));-```--These use exponential backoff (10ms → 500ms cap) for fast initial checks that back off on slow CI.--**Exception - testing absence:** When verifying something did NOT happen, polling doesn't work. Use a fixed 500ms+ sleep:--```rust-thread::sleep(Duration::from_millis(500));-assert!(!marker_file.exists(), "Command should NOT have run");-```--### Testing with --execute Commands--Use `--force` to skip interactive prompts in tests. Don't pipe input to stdin.-## Coverage- Install once: `cargo install cargo-llvm-cov`.diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.mdindex f7d146cd9..106150872 100644--- a/src/commands/CLAUDE.md+++ b/src/commands/CLAUDE.md@@ -93,6 +93,21 @@ branch: Option<String>,**Pattern:** All branch arguments should use `branch_value_completer()` for consistency with commands like `wt merge`, `wt switch --base`, `wt rebase`.+## CLI Flag Descriptions++Keep the first line of flag and argument descriptions brief—aim for 3-6 words. Use parenthetical defaults sparingly, only when the default isn't obvious from context.++**Good examples:**+- `/// Skip approval prompts`+- `/// Show CI and \`main\` diffstat`+- `/// Target branch (defaults to default branch)`++**Bad examples (too verbose):**+- `/// Auto-approve project commands without saving approvals.`+- `/// Show CI status, conflict detection, and complete diff statistics`++The help text should be scannable. Users reading `wt switch --help` need to quickly understand what each flag does without parsing long sentences.+## CLI Help Text PlacementHelp text has three levels:diff --git a/tests/CLAUDE.md b/tests/CLAUDE.mdindex b3eb0cf39..81437c124 100644--- a/tests/CLAUDE.md+++ b/tests/CLAUDE.md@@ -1,5 +1,56 @@# Testing Guidelines+## Timing Tests: Long Timeouts with Fast Polling++**Core principle:** Use long timeouts (5+ seconds) for reliability on slow CI, but poll frequently (10-50ms) so tests complete quickly when things work.++This achieves both goals:+- **No flaky failures** on slow machines - generous timeout accommodates worst-case+- **Fast tests** on normal machines - frequent polling means no unnecessary waiting++```rust+// ✅ GOOD: Long timeout, fast polling+let timeout = Duration::from_secs(5);+let poll_interval = Duration::from_millis(10);+let start = Instant::now();+while start.elapsed() < timeout {+ if condition_met() { break; }+ thread::sleep(poll_interval);+}++// ❌ BAD: Fixed sleep (always slow, might still fail)+thread::sleep(Duration::from_millis(500));+assert!(condition_met());++// ❌ BAD: Short timeout (flaky on slow CI)+let timeout = Duration::from_millis(100);+```++Use the helpers in `tests/common/mod.rs`:++```rust+use crate::common::{wait_for_file, wait_for_file_count};++// ✅ Poll for file existence with 5+ second timeout+wait_for_file(&log_file, Duration::from_secs(5));++// ✅ Poll for multiple files+wait_for_file_count(&log_dir, "log", 3, Duration::from_secs(5));+```++These use exponential backoff (10ms → 500ms cap) for fast initial checks that back off on slow CI.++**Exception - testing absence:** When verifying something did NOT happen, polling doesn't work. Use a fixed 500ms+ sleep:++```rust+thread::sleep(Duration::from_millis(500));+assert!(!marker_file.exists(), "Command should NOT have run");+```++## Testing with --execute Commands++Use `--force` to skip interactive prompts in tests. Don't pipe input to stdin.+## README Examples and Snapshot Testing### Problem: Separated stdout/stderr in Standard Snapshots