Add GitLab support for `git gtr clean --merged`

[echarrod]

Summary

The clean --merged command currently only supports GitHub repositories via the gh CLI. It should also support GitLab repositories using the glab CLI.

Current Behavior

• clean --merged requires the GitHub CLI (gh) and uses gh pr list --head <branch> --state merged to detect merged PRs
• Running against a GitLab-hosted repo fails with: "Not authenticated with GitHub or not a GitHub repository"

Proposed Behavior

Auto-detect the remote hosting provider and use the appropriate CLI:

• GitHub → gh pr list --head <branch> --state merged ...
• GitLab → glab mr list --source-branch <branch> --merged ... (or equivalent)

Detection approach

Inspect the origin remote URL to determine the provider:

• URLs containing github.com → use gh
• URLs containing gitlab.com (or self-hosted GitLab instances) → use glab

Implementation notes

• The glab CLI equivalent for checking merged MRs would be something like:
  glab mr list --source-branch "$branch" --merged --output json
• glab auth check: glab auth status
• Should fail gracefully if neither gh nor glab is installed, with a clear error message
• Consider supporting self-hosted GitLab instances (glab handles this via glab auth login --hostname)
• Could be extended to other providers (e.g., Bitbucket) in the future

Affected Code

• bin/gtr lines ~1114-1210 (cmd_clean merged mode)

References

• glab CLI
• glab mr list docs

[traycerai]

Plan

Observations

The clean --merged command in file:bin/gtr (lines 1114-1213) currently only supports GitHub repositories via the gh CLI. It checks for gh availability, validates GitHub authentication using gh repo view, and queries merged PRs with gh pr list --head "$branch" --state merged. The codebase uses a library structure with file:lib/platform.sh for OS detection, but lacks git hosting provider detection. No GitLab or glab CLI support exists currently.

Approach

Implement multi-provider support by adding a git hosting provider detection function in file:lib/platform.sh that inspects the origin remote URL to identify GitHub vs GitLab. Refactor the cmd_clean merged mode logic in file:bin/gtr to conditionally use either gh or glab CLI based on the detected provider. This maintains backward compatibility with existing GitHub workflows while enabling GitLab support through parallel code paths.

Implementation Steps

1. Add Git Hosting Provider Detection to file:lib/platform.sh

Add a new function detect_git_provider() after the existing detect_os() function:

Function responsibilities:

• Execute git remote get-url origin to retrieve the remote URL
• Parse the URL to identify the hosting provider:
  • URLs containing github.com → return github
  • URLs containing gitlab.com or matching GitLab self-hosted patterns → return gitlab
  • Unknown/missing remote → return unknown
• Handle both HTTPS (https://github.com/...) and SSH (git@github.com:...) URL formats
• Support self-hosted GitLab instances by checking for common GitLab URL patterns

Error handling:

• Return unknown if git remote get-url origin fails
• Handle cases where no remote named origin exists

2. Refactor cmd_clean Function in file:bin/gtr

Modify the --merged mode section (lines 1114-1213) to support both GitHub and GitLab:

2.1 Provider Detection and CLI Validation

Replace the current GitHub-only checks (lines 1118-1129) with provider-aware logic:

Steps:

• Call detect_git_provider to determine the hosting provider
• Based on the provider, check for the appropriate CLI tool:
  • GitHub: Check for gh CLI availability using command -v gh
  • GitLab: Check for glab CLI availability using command -v glab
  • Unknown: Display error message indicating unsupported provider
• Validate authentication for the detected provider:
  • GitHub: Use gh repo view (existing logic)
  • GitLab: Use glab auth status
• Provide clear error messages with installation/authentication instructions specific to each provider

2.2 Provider-Specific Merged Check Logic

Refactor the merged PR/MR check (line 1175-1177) into provider-specific branches:

GitHub branch (existing logic):

• Command: gh pr list --head "$branch" --state merged --json state --jq '.[0].state'
• Check if result equals MERGED

GitLab branch (new logic):

• Command: glab mr list --source-branch "$branch" --merged --output json
• Parse JSON output to check if any merged MRs exist for the branch
• Use jq or shell-based JSON parsing to extract merge status
• Alternative simpler approach: glab mr list -s "$branch" -M and check if output is non-empty

Implementation pattern:

case "$provider" in
  github)
    # GitHub logic using gh CLI
    ;;
  gitlab)
    # GitLab logic using glab CLI
    ;;
  *)
    # Error: unsupported provider
    ;;
esac

3. Update Error Messages and User Feedback

Enhance error messages throughout the cmd_clean function to be provider-aware:

CLI not found errors:

• GitHub: "GitHub CLI (gh) not found. Install from: https://cli.github.com/"
• GitLab: "GitLab CLI (glab) not found. Install from: https://gitlab.com/gitlab-org/cli"
• Unknown provider: "Git hosting provider not supported. Only GitHub and GitLab are supported for --merged mode"

Authentication errors:

• GitHub: "Not authenticated with GitHub or not a GitHub repository. Run: gh auth login"
• GitLab: "Not authenticated with GitLab or not a GitLab repository. Run: glab auth login"

Log messages:

• Update log_step "Checking for worktrees with merged PRs..." to be generic: "Checking for worktrees with merged PRs/MRs..."

4. Update Documentation in file:README.md

Modify the clean --merged command documentation (lines 281-298):

Update the description:

• Change "GitHub CLI required" to "GitHub CLI (gh) or GitLab CLI (glab) required"
• Update the note to mention both providers: "The --merged mode requires either the GitHub CLI (gh) or GitLab CLI (glab) to be installed and authenticated, depending on your repository's remote hosting provider."

Add provider detection information:

• Document that the command auto-detects the provider based on the origin remote URL
• Mention support for both GitHub.com and GitLab.com (including self-hosted GitLab instances)

5. Testing Considerations

Manual testing scenarios:

• GitHub repository with merged PRs
• GitLab repository with merged MRs
• Repository with no remote named origin
• Repository with unsupported hosting provider (e.g., Bitbucket)
• Self-hosted GitLab instance
• Mixed scenarios: branches with and without merged PRs/MRs
• Dry-run mode with both providers
• Authentication failures for both providers

Edge cases to handle:

• Branch names with special characters
• Multiple remotes (ensure origin is used)
• Detached HEAD states (already handled)
• Uncommitted changes (already handled)

6. Optional Enhancements

Future extensibility:

• The provider detection pattern in file:lib/platform.sh can be extended to support additional providers (Bitbucket, Azure DevOps, etc.)
• Consider adding a configuration option gtr.provider to override auto-detection
• Add provider information to git gtr doctor health check output

Architecture Diagram

sequenceDiagram
    participant User
    participant cmd_clean
    participant detect_git_provider
    participant gh/glab CLI
    
    User->>cmd_clean: git gtr clean --merged
    cmd_clean->>detect_git_provider: Detect hosting provider
    detect_git_provider->>detect_git_provider: git remote get-url origin
    detect_git_provider->>detect_git_provider: Parse URL (github.com/gitlab.com)
    detect_git_provider-->>cmd_clean: Return provider (github/gitlab/unknown)
    
    alt Provider is GitHub
        cmd_clean->>gh/glab CLI: Check gh availability
        cmd_clean->>gh/glab CLI: gh repo view (auth check)
        cmd_clean->>gh/glab CLI: gh pr list --head <branch> --state merged
        gh/glab CLI-->>cmd_clean: PR merge status
    else Provider is GitLab
        cmd_clean->>gh/glab CLI: Check glab availability
        cmd_clean->>gh/glab CLI: glab auth status
        cmd_clean->>gh/glab CLI: glab mr list -s <branch> -M -F json
        gh/glab CLI-->>cmd_clean: MR merge status
    else Provider is unknown
        cmd_clean-->>User: Error: Unsupported provider
    end
    
    cmd_clean->>cmd_clean: Process worktrees based on merge status
    cmd_clean-->>User: Summary (removed/skipped counts)

Loading

Files to Modify

File	Lines	Changes
file:lib/platform.sh	After line 35	Add detect_git_provider() function
file:bin/gtr	1114-1213	Refactor cmd_clean merged mode for multi-provider support
file:README.md	281-298	Update documentation for GitLab support

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `clean --merged` command in `file:bin/gtr` (lines 1114-1213) currently only supports GitHub repositories via the `gh` CLI. It checks for `gh` availability, validates GitHub authentication using `gh repo view`, and queries merged PRs with `gh pr list --head "$branch" --state merged`. The codebase uses a library structure with `file:lib/platform.sh` for OS detection, but lacks git hosting provider detection. No GitLab or `glab` CLI support exists currently.

## Approach

Implement multi-provider support by adding a git hosting provider detection function in `file:lib/platform.sh` that inspects the `origin` remote URL to identify GitHub vs GitLab. Refactor the `cmd_clean` merged mode logic in `file:bin/gtr` to conditionally use either `gh` or `glab` CLI based on the detected provider. This maintains backward compatibility with existing GitHub workflows while enabling GitLab support through parallel code paths.

## Implementation Steps

### 1. Add Git Hosting Provider Detection to `file:lib/platform.sh`

Add a new function `detect_git_provider()` after the existing `detect_os()` function:

**Function responsibilities:**
- Execute `git remote get-url origin` to retrieve the remote URL
- Parse the URL to identify the hosting provider:
  - URLs containing `github.com` → return `github`
  - URLs containing `gitlab.com` or matching GitLab self-hosted patterns → return `gitlab`
  - Unknown/missing remote → return `unknown`
- Handle both HTTPS (`https://github.com/...`) and SSH (`git@github.com:...`) URL formats
- Support self-hosted GitLab instances by checking for common GitLab URL patterns

**Error handling:**
- Return `unknown` if `git remote get-url origin` fails
- Handle cases where no remote named `origin` exists

### 2. Refactor `cmd_clean` Function in `file:bin/gtr`

Modify the `--merged` mode section (lines 1114-1213) to support both GitHub and GitLab:

#### 2.1 Provider Detection and CLI Validation

Replace the current GitHub-only checks (lines 1118-1129) with provider-aware logic:

**Steps:**
- Call `detect_git_provider` to determine the hosting provider
- Based on the provider, check for the appropriate CLI tool:
  - **GitHub**: Check for `gh` CLI availability using `command -v gh`
  - **GitLab**: Check for `glab` CLI availability using `command -v glab`
  - **Unknown**: Display error message indicating unsupported provider
- Validate authentication for the detected provider:
  - **GitHub**: Use `gh repo view` (existing logic)
  - **GitLab**: Use `glab auth status`
- Provide clear error messages with installation/authentication instructions specific to each provider

#### 2.2 Provider-Specific Merged Check Logic

Refactor the merged PR/MR check (line 1175-1177) into provider-specific branches:

**GitHub branch (existing logic):**
- Command: `gh pr list --head "$branch" --state merged --json state --jq '.[0].state'`
- Check if result equals `MERGED`

**GitLab branch (new logic):**
- Command: `glab mr list --source-branch "$branch" --merged --output json`
- Parse JSON output to check if any merged MRs exist for the branch
- Use `jq` or shell-based JSON parsing to extract merge status
- Alternative simpler approach: `glab mr list -s "$branch" -M` and check if output is non-empty

**Implementation pattern:**
```
case "$provider" in
  github)
    # GitHub logic using gh CLI
    ;;
  gitlab)
    # GitLab logic using glab CLI
    ;;
  *)
    # Error: unsupported provider
    ;;
esac
```

### 3. Update Error Messages and User Feedback

Enhance error messages throughout the `cmd_clean` function to be provider-aware:

**CLI not found errors:**
- GitHub: `"GitHub CLI (gh) not found. Install from: https://cli.github.com/"`
- GitLab: `"GitLab CLI (glab) not found. Install from: https://gitlab.com/gitlab-org/cli"`
- Unknown provider: `"Git hosting provider not supported. Only GitHub and GitLab are supported for --merged mode"`

**Authentication errors:**
- GitHub: `"Not authenticated with GitHub or not a GitHub repository. Run: gh auth login"`
- GitLab: `"Not authenticated with GitLab or not a GitLab repository. Run: glab auth login"`

**Log messages:**
- Update `log_step "Checking for worktrees with merged PRs..."` to be generic: `"Checking for worktrees with merged PRs/MRs..."`

### 4. Update Documentation in `file:README.md`

Modify the `clean --merged` command documentation (lines 281-298):

**Update the description:**
- Change "GitHub CLI required" to "GitHub CLI (gh) or GitLab CLI (glab) required"
- Update the note to mention both providers: "The `--merged` mode requires either the GitHub CLI (`gh`) or GitLab CLI (`glab`) to be installed and authenticated, depending on your repository's remote hosting provider."

**Add provider detection information:**
- Document that the command auto-detects the provider based on the `origin` remote URL
- Mention support for both GitHub.com and GitLab.com (including self-hosted GitLab instances)

### 5. Testing Considerations

**Manual testing scenarios:**
- GitHub repository with merged PRs
- GitLab repository with merged MRs
- Repository with no remote named `origin`
- Repository with unsupported hosting provider (e.g., Bitbucket)
- Self-hosted GitLab instance
- Mixed scenarios: branches with and without merged PRs/MRs
- Dry-run mode with both providers
- Authentication failures for both providers

**Edge cases to handle:**
- Branch names with special characters
- Multiple remotes (ensure `origin` is used)
- Detached HEAD states (already handled)
- Uncommitted changes (already handled)

### 6. Optional Enhancements

**Future extensibility:**
- The provider detection pattern in `file:lib/platform.sh` can be extended to support additional providers (Bitbucket, Azure DevOps, etc.)
- Consider adding a configuration option `gtr.provider` to override auto-detection
- Add provider information to `git gtr doctor` health check output

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant cmd_clean
    participant detect_git_provider
    participant gh/glab CLI
    
    User->>cmd_clean: git gtr clean --merged
    cmd_clean->>detect_git_provider: Detect hosting provider
    detect_git_provider->>detect_git_provider: git remote get-url origin
    detect_git_provider->>detect_git_provider: Parse URL (github.com/gitlab.com)
    detect_git_provider-->>cmd_clean: Return provider (github/gitlab/unknown)
    
    alt Provider is GitHub
        cmd_clean->>gh/glab CLI: Check gh availability
        cmd_clean->>gh/glab CLI: gh repo view (auth check)
        cmd_clean->>gh/glab CLI: gh pr list --head <branch> --state merged
        gh/glab CLI-->>cmd_clean: PR merge status
    else Provider is GitLab
        cmd_clean->>gh/glab CLI: Check glab availability
        cmd_clean->>gh/glab CLI: glab auth status
        cmd_clean->>gh/glab CLI: glab mr list -s <branch> -M -F json
        gh/glab CLI-->>cmd_clean: MR merge status
    else Provider is unknown
        cmd_clean-->>User: Error: Unsupported provider
    end
    
    cmd_clean->>cmd_clean: Process worktrees based on merge status
    cmd_clean-->>User: Summary (removed/skipped counts)
```

## Files to Modify

| File | Lines | Changes |
|------|-------|---------|
| `file:lib/platform.sh` | After line 35 | Add `detect_git_provider()` function |
| `file:bin/gtr` | 1114-1213 | Refactor `cmd_clean` merged mode for multi-provider support |
| `file:README.md` | 281-298 | Update documentation for GitLab support |

---

Execution Information

Branch: main
Commit: 923f580

---

💡 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.

[echarrod]

Let me know if you think this is a good idea, if so I can have a go at implementing 👍