git-worktree-runner: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

git gtr (Git Worktree Runner) is a cross-platform CLI tool written in Bash that simplifies git worktree management. It wraps git worktree with quality-of-life features like editor integration, AI tool support, file copying, and hooks. Installed as a git subcommand: git gtr <command>.

Invocation

• Production: git gtr <command> (git subcommand via bin/git-gtr wrapper)
• Development/testing: ./bin/gtr <command> (direct execution)
• User-facing docs: Always reference git gtr, never ./bin/gtr

Testing

This project uses BATS tests for core functions and manual smoke tests for end-to-end workflows. CI runs ShellCheck + BATS automatically on PRs (.github/workflows/lint.yml).

1. Run automated tests: bats tests/
2. Run a single test file: bats tests/config.bats
3. Run a single test by name: bats tests/config.bats --filter "cfg_map_to_file_key"
4. Run relevant manual smoke tests:

./bin/gtr new test-feature          # Create worktree
./bin/gtr new feature/auth          # Slash branch → folder "feature-auth"
./bin/gtr list                      # Table output
./bin/gtr go test-feature           # Print path
./bin/gtr run test-feature git status
./bin/gtr rm test-feature           # Clean up

For exhaustive manual testing (hooks, copy patterns, adapters, --force, --from-current, etc.), see the full checklist in CONTRIBUTING.md or .github/instructions/testing.instructions.md.

Test files (all in tests/): one cmd_*.bats file per command (cmd_clean, cmd_config, cmd_copy, cmd_create_integration, cmd_go, cmd_help, cmd_list, cmd_pr, cmd_remove, cmd_rename, cmd_run, cmd_trust), library tests (adapters, completion, config, copy_safety, core_create_worktree, core_resolve_target, hooks, init, launch, parse_args, platform, provider, resolve_base_dir, sanitize_branch_name, sparse, ui_color), and integration_lifecycle for end-to-end flows. Shared fixtures in tests/test_helper.bash.