git-worktree-runner: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents (Codex, Copilot, and similar tools) 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.