feat: color output, per-command help, and 62 new tests

.github/workflows/homebrew.yml

@@ -0,0 +1,25 @@
+name: Update Homebrew Formula
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  homebrew:
+    name: Bump Homebrew formula
+    runs-on: ubuntu-latest
+    if: ${{ !github.event.release.prerelease }}
+    steps:
+      - uses: mislav/bump-homebrew-formula-action@v3
+        with:
+          formula-name: git-gtr
+          formula-path: Formula/git-gtr.rb
+          homebrew-tap: coderabbitai/homebrew-tap
+          tag-name: ${{ github.event.release.tag_name }}
+          create-pullrequest: false
+          commit-message: |
+            {{formulaName}} {{version}}
+
+            Automated update from https://github.com/coderabbitai/git-worktree-runner
+        env:
+          COMMITTER_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}

README.md

@@ -42,7 +42,14 @@
 
 ## Quick Start
 
-**Install:**
+**Homebrew (macOS):**
+
+```bash
+brew tap coderabbitai/tap
+brew install git-gtr
+```
+
+**Script installer (macOS / Linux):**
 
 ```bash
 git clone https://github.com/coderabbitai/git-worktree-runner.git
@@ -51,13 +58,7 @@ cd git-worktree-runner
 ```
 
 <details>
-<summary><b>Manual installation options</b></summary>
-
-**macOS (Apple Silicon with Homebrew):**
-
-```bash
-ln -s "$(pwd)/bin/git-gtr" "$(brew --prefix)/bin/git-gtr"
-```
+<summary><b>Other installation options</b></summary>
 
 **macOS (Intel) / Linux:**
 
@@ -336,6 +337,9 @@ git gtr config add gtr.hook.postCreate "npm install"
 
 # Re-source environment after gtr cd (runs in current shell)
 git gtr config add gtr.hook.postCd "source ./vars.sh"
+
+# Disable color output (or use "always" to force it)
+git gtr config set gtr.ui.color never
 ```
 
 ### Team Configuration (.gtrconfig)

bin/gtr

@@ -4,6 +4,11 @@
 
 set -e
 
+# Debug: show file:line:function on set -e failures
+if [ -n "${GTR_DEBUG:-}" ]; then
+  trap 'printf "ERROR at %s:%s in %s()\n" "${BASH_SOURCE[0]}" "$LINENO" "${FUNCNAME[0]:-main}" >&2' ERR
+fi
+
 # Version
 GTR_VERSION="2.2.0"
 
@@ -24,6 +29,7 @@ resolve_script_dir() {
 . "$GTR_DIR/lib/ui.sh"
 . "$GTR_DIR/lib/args.sh"
 . "$GTR_DIR/lib/config.sh"
+_ui_apply_color_config
 . "$GTR_DIR/lib/platform.sh"
 . "$GTR_DIR/lib/core.sh"
 . "$GTR_DIR/lib/copy.sh"
@@ -44,6 +50,9 @@ main() {
   local cmd="${1:-help}"
   shift 2>/dev/null || true
 
+  # Set for per-command help (used by show_command_help in ui.sh)
+  _GTR_CURRENT_COMMAND="$cmd"
+
   case "$cmd" in
     new)
       cmd_create "$@"
@@ -94,7 +103,7 @@ main() {
       echo "git gtr version $GTR_VERSION"
       ;;
     help|--help|-h)
-      cmd_help
+      cmd_help "$@"
       ;;
     *)
       log_error "Unknown command: $cmd"

completions/_git-gtr

@@ -174,15 +174,15 @@ _git-gtr() {
                 '--local[Use local git config]' \
                 '--global[Use global git config]' \
                 '--system[Use system git config]' \
-                '*:config key:(gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider)'
+                '*:config key:(gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider gtr.ui.color)'
               ;;
             set|add|unset)
               # Write operations only support --local and --global
               # (--system may require root or appropriate file permissions)
               _arguments \
                 '--local[Use local git config]' \
                 '--global[Use global git config]' \
-                '*:config key:(gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider)'
+                '*:config key:(gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider gtr.ui.color)'
               ;;
           esac
         fi

completions/git-gtr.fish

@@ -139,6 +139,7 @@ complete -f -c git -n '__fish_git_gtr_using_command config' -a "
   gtr.worktrees.prefix	'Worktree folder prefix'
   gtr.defaultBranch	'Default branch'
   gtr.provider	'Hosting provider (github, gitlab)'
+  gtr.ui.color	'Color output mode (auto, always, never)'
 "
 
 # Helper function to get branch names and special '1' for main repo

completions/gtr.bash

@@ -131,15 +131,15 @@ _git_gtr() {
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "--local --global --system" -- "$cur"))
             else
-              COMPREPLY=($(compgen -W "gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider" -- "$cur"))
+              COMPREPLY=($(compgen -W "gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider gtr.ui.color" -- "$cur"))
             fi
             ;;
           set|add|unset)
             # Write operations only support --local and --global (--system requires root)
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "--local --global" -- "$cur"))
             else
-              COMPREPLY=($(compgen -W "gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider" -- "$cur"))
+              COMPREPLY=($(compgen -W "gtr.copy.include gtr.copy.exclude gtr.copy.includeDirs gtr.copy.excludeDirs gtr.hook.postCreate gtr.hook.preRemove gtr.hook.postRemove gtr.hook.postCd gtr.editor.default gtr.editor.workspace gtr.ai.default gtr.worktrees.dir gtr.worktrees.prefix gtr.defaultBranch gtr.provider gtr.ui.color" -- "$cur"))
             fi
             ;;
         esac

docs/configuration.md

@@ -17,6 +17,7 @@
 - [File Copying](#file-copying)
 - [Directory Copying](#directory-copying)
 - [Hooks](#hooks)
+- [UI Settings](#ui-settings)
 - [Shell Completions](#shell-completions)
 - [Configuration Examples](#configuration-examples)
 - [Environment Variables](#environment-variables)
@@ -337,6 +338,28 @@ git gtr config add gtr.hook.postCreate "cargo build"
 
 ---
 
+## UI Settings
+
+Control color output behavior.
+
+| Git Config Key | `.gtrconfig` Key | Description       | Values                              |
+| -------------- | ---------------- | ----------------- | ----------------------------------- |
+| `gtr.ui.color` | `ui.color`       | Color output mode | `auto` (default), `always`, `never` |
+
+```bash
+# Disable color output
+git gtr config set gtr.ui.color never
+
+# Force color output (e.g., when piping to a pager)
+git gtr config set gtr.ui.color always
+```
+
+**Precedence**: `NO_COLOR` env (highest) > `GTR_COLOR` env > `gtr.ui.color` config > auto-detect (TTY).
+
+The `NO_COLOR` environment variable ([no-color.org](https://no-color.org)) always wins regardless of other settings.
+
+---
+
 ## Shell Completions
 
 Enable tab completion using the built-in `completion` command.
@@ -420,15 +443,17 @@ git gtr config set gtr.ai.default claude --global
 
 ## Environment Variables
 
-| Variable              | Description                                            | Default                    |
-| --------------------- | ------------------------------------------------------ | -------------------------- |
-| `GTR_DIR`             | Override script directory location                     | Auto-detected              |
-| `GTR_WORKTREES_DIR`   | Override base worktrees directory                      | `gtr.worktrees.dir` config |
-| `GTR_EDITOR_CMD`      | Custom editor command (e.g., `emacs`)                  | None                       |
-| `GTR_EDITOR_CMD_NAME` | First word of `GTR_EDITOR_CMD` for availability checks | None                       |
-| `GTR_AI_CMD`          | Custom AI tool command (e.g., `copilot`)               | None                       |
-| `GTR_AI_CMD_NAME`     | First word of `GTR_AI_CMD` for availability checks     | None                       |
-| `GTR_PROVIDER`        | Override hosting provider (`github` or `gitlab`)       | Auto-detected from URL     |
+| Variable              | Description                                                          | Default                    |
+| --------------------- | -------------------------------------------------------------------- | -------------------------- |
+| `GTR_DIR`             | Override script directory location                                   | Auto-detected              |
+| `GTR_WORKTREES_DIR`   | Override base worktrees directory                                    | `gtr.worktrees.dir` config |
+| `GTR_EDITOR_CMD`      | Custom editor command (e.g., `emacs`)                                | None                       |
+| `GTR_EDITOR_CMD_NAME` | First word of `GTR_EDITOR_CMD` for availability checks               | None                       |
+| `GTR_AI_CMD`          | Custom AI tool command (e.g., `copilot`)                             | None                       |
+| `GTR_AI_CMD_NAME`     | First word of `GTR_AI_CMD` for availability checks                   | None                       |
+| `GTR_COLOR`           | Override color output (`always`, `never`, `auto`)                    | `auto`                     |
+| `GTR_PROVIDER`        | Override hosting provider (`github` or `gitlab`)                     | Auto-detected from URL     |
+| `NO_COLOR`            | Disable color output when set ([no-color.org](https://no-color.org)) | Unset                      |
 
 **Hook environment variables** (available in hook scripts):