git-worktree-runner AGENTS.md

AGENTS.md

This file provides guidance to Codex (Codex.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: adapters, config, copy_safety, integration_lifecycle, parse_args, provider, resolve_base_dir, sanitize_branch_name (all in tests/). Shared fixtures in tests/test_helper.bash.

Tip: Use a disposable repo for testing to avoid polluting your working tree:

mkdir -p /tmp/gtr-test && cd /tmp/gtr-test && git init && git commit --allow-empty -m "init"
/path/to/git-worktree-runner/bin/gtr new test-feature