Add self-update mechanism or update command

[echarrod]

Summary

There is currently no way to update git gtr from within the tool itself. Users must manually pull the latest version or re-run the installation steps.

Suggestion

Consider adding a git gtr update command that pulls the latest release, or at minimum documents the recommended update workflow.

Relationship to #92

If a Homebrew tap is implemented (#92), users would be able to update via brew upgrade git-gtr, which may make a built-in update command unnecessary. Rather than investing in a custom auto-update mechanism, it may be better to prioritize the Homebrew tap and document brew upgrade as the recommended update path.

Current workaround

Users who installed via git clone can update manually:

cd /path/to/git-worktree-runner
git pull origin main

[traycerai]

Plan

Observations

The git gtr tool is currently installed via git clone and symlink creation through file:install.sh. The version is hardcoded in file:bin/gtr as GTR_VERSION="2.1.0". Issue #92 proposes a Homebrew tap which would provide brew upgrade functionality. The current workaround requires users to manually navigate to the cloned repository and run git pull origin main. The tool has a modular architecture with commands dispatched through a case statement in the main() function, making it straightforward to add new commands.

Approach

Given the relationship with issue #92 (Homebrew tap), the implementation should provide a dual-path strategy: a built-in git gtr update command for git-clone installations, while documenting that Homebrew users should use brew upgrade git-gtr once the tap is available. The update command will detect the installation method and guide users accordingly. For git-clone installations, it will perform a safe git pull in the installation directory with proper error handling and version verification. This approach provides immediate value while remaining compatible with future Homebrew distribution.

Implementation Steps

1. Add Update Command Handler

Location: file:bin/gtr in the main command dispatcher (around line 66-124 based on file summary)

Add a new case in the command dispatcher's case statement:

update)
  cmd_update
  ;;

2. Implement cmd_update() Function

Location: file:bin/gtr after existing command functions (suggested placement after cmd_version or other utility commands)

Create the update command function with the following logic:

• Detect installation method by checking if $SCRIPT_DIR is within a git repository
• If installed via git clone:
  • Store current version for comparison
  • Navigate to the repository root (parent of bin/ directory)
  • Verify it's the correct git repository (check remote URL contains coderabbitai/git-worktree-runner)
  • Check for uncommitted changes in the installation directory
  • Fetch latest changes from origin
  • Compare local and remote versions
  • If update available, prompt user for confirmation (unless --yes flag provided)
  • Perform git pull origin main (or current branch)
  • Display old vs new version
  • Suggest running git gtr doctor to verify installation
• If installed via Homebrew (detect by checking if symlink points to Homebrew cellar):
  • Display message: "Detected Homebrew installation. Please use: brew upgrade git-gtr"
  • Exit with code 0
• If installation method unknown:
  • Display manual update instructions
  • Show the current workaround from the issue

Error Handling:

• Network connectivity issues when fetching
• Merge conflicts during pull
• Permission issues
• Detached HEAD state
• Modified files in installation directory

Flags to support:

• --yes / -y: Skip confirmation prompt
• --check: Only check for updates without installing
• --dry-run / -n: Show what would be updated without making changes

3. Add Version Comparison Helper

Location: file:bin/gtr in the helper functions section (around line 1427-1513)

Create a compare_versions() function to compare semantic version strings:

# Returns: 0 if v1 == v2, 1 if v1 > v2, 2 if v1 < v2
compare_versions(version1, version2)

This function should handle semantic versioning format (MAJOR.MINOR.PATCH) and properly compare each component numerically.

4. Update Help Documentation

Location: file:bin/gtr in the cmd_help() function (around line 1514-1715)

Add documentation for the new update command in the help text:

• Command syntax: git gtr update [options]
• Description: "Check for and install updates to git gtr"
• Options: --yes, --check, --dry-run
• Examples:
  • git gtr update - Check and install updates interactively
  • git gtr update --check - Only check if updates are available
  • git gtr update --yes - Update without confirmation
• Note about Homebrew installations

5. Update Shell Completions

Files to update:

• file:completions/gtr.bash - Add update to command list and its flags
• file:completions/_git-gtr - Add update command with flag completions
• file:completions/git-gtr.fish - Add update command completion

Each completion file should include:

• update in the main command list
• Flag completions: --yes, -y, --check, --dry-run, -n

6. Update Documentation

Files to update:

file:README.md:

• Add git gtr update to the Commands section
• Add update workflow documentation
• Include note about Homebrew tap (when available)
• Update "Quick Start" section to mention update command

file:CHANGELOG.md:

• Add entry under [Unreleased] → ### Added:
  • "update command for self-updating git-clone installations (Add self-update mechanism or update command #94)"

file:CLAUDE.md:

• Add update command to the manual testing checklist
• Document the update mechanism in the "Common Development Tasks" section

7. Add Update Check to Doctor Command (Optional Enhancement)

Location: file:bin/gtr in cmd_doctor() function (around line 1085-1177)

Enhance the doctor command to check if updates are available:

• Add a new check: "Checking for updates..."
• Display current version and latest available version
• If outdated, suggest running git gtr update
• This should be a non-blocking informational check

8. Manual Testing Checklist

Since the project has no automated tests, thoroughly test:

Git Clone Installation:

• Install via git clone on a test system
• Run git gtr update --check to verify update detection
• Run git gtr update --dry-run to preview changes
• Run git gtr update and verify successful update
• Test with --yes flag for non-interactive mode
• Test when already on latest version
• Test with uncommitted changes in installation directory
• Test with network connectivity issues
• Test with invalid git repository state

Homebrew Installation (when tap is available):

• Verify detection of Homebrew installation
• Verify appropriate message is displayed

Edge Cases:

• Installation directory is not a git repository
• Remote URL doesn't match expected repository
• Detached HEAD state
• Modified files in installation directory
• Permission issues during git pull

Cross-Platform:

• Test on macOS
• Test on Linux
• Test on Windows Git Bash

9. Documentation for Issue #92 Integration

Location: Create or update documentation

When Homebrew tap is implemented (issue #92), update:

• file:README.md - Add Homebrew installation and update instructions
• file:install.sh - Add detection and messaging for Homebrew installations
• Update command - Ensure proper detection of Homebrew vs git-clone installations

Architecture Diagram

sequenceDiagram
    participant User
    participant git gtr update
    participant Installation Detector
    participant Git Repository
    participant Remote (GitHub)
    
    User->>git gtr update: git gtr update
    git gtr update->>Installation Detector: Detect installation method
    
    alt Git Clone Installation
        Installation Detector->>Git Repository: Check if in git repo
        Git Repository-->>Installation Detector: Yes, valid repo
        Installation Detector->>Remote (GitHub): Fetch latest version
        Remote (GitHub)-->>Installation Detector: Latest version info
        Installation Detector->>git gtr update: Compare versions
        
        alt Update Available
            git gtr update->>User: Prompt for confirmation
            User->>git gtr update: Confirm
            git gtr update->>Git Repository: git pull origin main
            Git Repository-->>git gtr update: Success
            git gtr update->>User: Display updated version
        else Already Latest
            git gtr update->>User: Already on latest version
        end
        
    else Homebrew Installation
        Installation Detector->>git gtr update: Homebrew detected
        git gtr update->>User: Use 'brew upgrade git-gtr'
        
    else Unknown Installation
        Installation Detector->>git gtr update: Unknown method
        git gtr update->>User: Display manual instructions
    end

Loading

Implementation Flow

Step	Component	Action
1	Command Dispatcher	Add update case to route to cmd_update()
2	cmd_update()	Implement main update logic with installation detection
3	Helper Functions	Add compare_versions() for semantic version comparison
4	Help System	Document update command usage and options
5	Completions	Add update command to all three shell completion files
6	Documentation	Update README, CHANGELOG, and CLAUDE.md
7	Doctor Command	Optionally add update check to health diagnostics
8	Testing	Perform comprehensive manual testing across platforms

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `git gtr` tool is currently installed via git clone and symlink creation through `file:install.sh`. The version is hardcoded in `file:bin/gtr` as `GTR_VERSION="2.1.0"`. Issue #92 proposes a Homebrew tap which would provide `brew upgrade` functionality. The current workaround requires users to manually navigate to the cloned repository and run `git pull origin main`. The tool has a modular architecture with commands dispatched through a case statement in the `main()` function, making it straightforward to add new commands.

## Approach

Given the relationship with issue #92 (Homebrew tap), the implementation should provide a **dual-path strategy**: a built-in `git gtr update` command for git-clone installations, while documenting that Homebrew users should use `brew upgrade git-gtr` once the tap is available. The update command will detect the installation method and guide users accordingly. For git-clone installations, it will perform a safe `git pull` in the installation directory with proper error handling and version verification. This approach provides immediate value while remaining compatible with future Homebrew distribution.

## Implementation Steps

### 1. Add Update Command Handler

**Location:** `file:bin/gtr` in the main command dispatcher (around line 66-124 based on file summary)

Add a new case in the command dispatcher's case statement:

```bash
update)
  cmd_update
  ;;
```

### 2. Implement `cmd_update()` Function

**Location:** `file:bin/gtr` after existing command functions (suggested placement after `cmd_version` or other utility commands)

Create the update command function with the following logic:

- Detect installation method by checking if `$SCRIPT_DIR` is within a git repository
- If installed via git clone:
  - Store current version for comparison
  - Navigate to the repository root (parent of `bin/` directory)
  - Verify it's the correct git repository (check remote URL contains `coderabbitai/git-worktree-runner`)
  - Check for uncommitted changes in the installation directory
  - Fetch latest changes from origin
  - Compare local and remote versions
  - If update available, prompt user for confirmation (unless `--yes` flag provided)
  - Perform `git pull origin main` (or current branch)
  - Display old vs new version
  - Suggest running `git gtr doctor` to verify installation
- If installed via Homebrew (detect by checking if symlink points to Homebrew cellar):
  - Display message: "Detected Homebrew installation. Please use: brew upgrade git-gtr"
  - Exit with code 0
- If installation method unknown:
  - Display manual update instructions
  - Show the current workaround from the issue

**Error Handling:**
- Network connectivity issues when fetching
- Merge conflicts during pull
- Permission issues
- Detached HEAD state
- Modified files in installation directory

**Flags to support:**
- `--yes` / `-y`: Skip confirmation prompt
- `--check`: Only check for updates without installing
- `--dry-run` / `-n`: Show what would be updated without making changes

### 3. Add Version Comparison Helper

**Location:** `file:bin/gtr` in the helper functions section (around line 1427-1513)

Create a `compare_versions()` function to compare semantic version strings:

```bash
# Returns: 0 if v1 == v2, 1 if v1 > v2, 2 if v1 < v2
compare_versions(version1, version2)
```

This function should handle semantic versioning format (MAJOR.MINOR.PATCH) and properly compare each component numerically.

### 4. Update Help Documentation

**Location:** `file:bin/gtr` in the `cmd_help()` function (around line 1514-1715)

Add documentation for the new `update` command in the help text:

- Command syntax: `git gtr update [options]`
- Description: "Check for and install updates to git gtr"
- Options: `--yes`, `--check`, `--dry-run`
- Examples:
  - `git gtr update` - Check and install updates interactively
  - `git gtr update --check` - Only check if updates are available
  - `git gtr update --yes` - Update without confirmation
- Note about Homebrew installations

### 5. Update Shell Completions

**Files to update:**
- `file:completions/gtr.bash` - Add `update` to command list and its flags
- `file:completions/_git-gtr` - Add `update` command with flag completions
- `file:completions/git-gtr.fish` - Add `update` command completion

Each completion file should include:
- `update` in the main command list
- Flag completions: `--yes`, `-y`, `--check`, `--dry-run`, `-n`

### 6. Update Documentation

**Files to update:**

**`file:README.md`:**
- Add `git gtr update` to the Commands section
- Add update workflow documentation
- Include note about Homebrew tap (when available)
- Update "Quick Start" section to mention update command

**`file:CHANGELOG.md`:**
- Add entry under `[Unreleased]` → `### Added`:
  - "`update` command for self-updating git-clone installations (#94)"

**`file:CLAUDE.md`:**
- Add update command to the manual testing checklist
- Document the update mechanism in the "Common Development Tasks" section

### 7. Add Update Check to Doctor Command (Optional Enhancement)

**Location:** `file:bin/gtr` in `cmd_doctor()` function (around line 1085-1177)

Enhance the doctor command to check if updates are available:

- Add a new check: "Checking for updates..."
- Display current version and latest available version
- If outdated, suggest running `git gtr update`
- This should be a non-blocking informational check

### 8. Manual Testing Checklist

Since the project has no automated tests, thoroughly test:

**Git Clone Installation:**
- Install via git clone on a test system
- Run `git gtr update --check` to verify update detection
- Run `git gtr update --dry-run` to preview changes
- Run `git gtr update` and verify successful update
- Test with `--yes` flag for non-interactive mode
- Test when already on latest version
- Test with uncommitted changes in installation directory
- Test with network connectivity issues
- Test with invalid git repository state

**Homebrew Installation (when tap is available):**
- Verify detection of Homebrew installation
- Verify appropriate message is displayed

**Edge Cases:**
- Installation directory is not a git repository
- Remote URL doesn't match expected repository
- Detached HEAD state
- Modified files in installation directory
- Permission issues during git pull

**Cross-Platform:**
- Test on macOS
- Test on Linux
- Test on Windows Git Bash

### 9. Documentation for Issue #92 Integration

**Location:** Create or update documentation

When Homebrew tap is implemented (issue #92), update:

- `file:README.md` - Add Homebrew installation and update instructions
- `file:install.sh` - Add detection and messaging for Homebrew installations
- Update command - Ensure proper detection of Homebrew vs git-clone installations

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant git gtr update
    participant Installation Detector
    participant Git Repository
    participant Remote (GitHub)
    
    User->>git gtr update: git gtr update
    git gtr update->>Installation Detector: Detect installation method
    
    alt Git Clone Installation
        Installation Detector->>Git Repository: Check if in git repo
        Git Repository-->>Installation Detector: Yes, valid repo
        Installation Detector->>Remote (GitHub): Fetch latest version
        Remote (GitHub)-->>Installation Detector: Latest version info
        Installation Detector->>git gtr update: Compare versions
        
        alt Update Available
            git gtr update->>User: Prompt for confirmation
            User->>git gtr update: Confirm
            git gtr update->>Git Repository: git pull origin main
            Git Repository-->>git gtr update: Success
            git gtr update->>User: Display updated version
        else Already Latest
            git gtr update->>User: Already on latest version
        end
        
    else Homebrew Installation
        Installation Detector->>git gtr update: Homebrew detected
        git gtr update->>User: Use 'brew upgrade git-gtr'
        
    else Unknown Installation
        Installation Detector->>git gtr update: Unknown method
        git gtr update->>User: Display manual instructions
    end
```

## Implementation Flow

| Step | Component | Action |
|------|-----------|--------|
| 1 | Command Dispatcher | Add `update` case to route to `cmd_update()` |
| 2 | `cmd_update()` | Implement main update logic with installation detection |
| 3 | Helper Functions | Add `compare_versions()` for semantic version comparison |
| 4 | Help System | Document update command usage and options |
| 5 | Completions | Add update command to all three shell completion files |
| 6 | Documentation | Update README, CHANGELOG, and CLAUDE.md |
| 7 | Doctor Command | Optionally add update check to health diagnostics |
| 8 | Testing | Perform comprehensive manual testing across platforms |

---

Execution Information

Branch: main
Commit: dbfbb6f

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.