Skip to content

feat: add skill #101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
thearyanag wants to merge 1 commit into
base: main
Choose a base branch
from
+307 −0
Open

feat: add skill #101

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 119 additions & 0 deletions skills/git-worktree-runner/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
---
name: git-worktree-runner
description: >
Guide for using gtr (git-worktree-runner), a CLI tool for managing git worktrees
with editor and AI tool integration. Use this skill when the user asks about:
(1) creating, managing, or removing git worktrees,
(2) setting up gtr / git-gtr for a project,
(3) configuring editors (Cursor, VS Code, Zed) or AI tools (Claude Code, Aider, Codex, Gemini) with worktrees,
(4) running parallel development workflows across multiple branches,
(5) copying config/env files to new worktrees,
(6) setting up hooks for worktree creation/removal,
(7) troubleshooting git worktree issues,
(8) any mention of "gtr", "git gtr", "git worktree runner", or "worktree" in context of parallel dev.
Triggers on keywords: gtr, git-gtr, worktree, parallel branches, multi-branch workflow.
---

# git-worktree-runner (gtr)

A portable CLI for managing git worktrees with editor and AI tool integration. Wraps `git worktree` with quality-of-life features for modern parallel development.

## Installation

```bash
git clone https://github.com/coderabbitai/git-worktree-runner.git
cd git-worktree-runner
sudo ln -s "$(pwd)/bin/git-gtr" /usr/local/bin/git-gtr
```

Requires Git 2.5+ and Bash 3.2+. Shell completions available for Bash, Zsh, and Fish.

## Core Workflow

```bash
cd ~/your-repo
git gtr config set gtr.editor.default cursor # one-time
git gtr config set gtr.ai.default claude # one-time

git gtr new my-feature # create worktree
git gtr editor my-feature # open in editor
git gtr ai my-feature # start AI tool
git gtr run my-feature npm test # run commands
git gtr rm my-feature # clean up
```

Use `1` to reference the main repo (e.g., `git gtr ai 1`).

## Commands Reference

| Command | Purpose |
|---|---|
| `git gtr new <branch> [opts]` | Create worktree. Options: `--from <ref>`, `--from-current`, `--track`, `--no-copy`, `--no-fetch`, `--force` (requires `--name`), `--name <suffix>`, `--yes` |
| `git gtr editor <branch>` | Open in configured editor. Override: `--editor <n>` |
| `git gtr ai <branch> [-- args]` | Start AI tool. Override: `--ai <n>`. Pass args after `--` |
| `git gtr go <branch>` | Print path. Use: `cd "$(git gtr go my-feature)"` |
| `git gtr run <branch> <cmd>` | Execute command in worktree directory |
| `git gtr rm <branch>... [opts]` | Remove worktree(s). Options: `--delete-branch`, `--force`, `--yes` |
| `git gtr list [--porcelain]` | List all worktrees |
| `git gtr config {get\|set\|add\|unset} <key> [val]` | Manage config. Add `--global` for global scope |
| `git gtr doctor` | Health check |
| `git gtr adapter` | List available editor & AI adapters |
| `git gtr clean` | Remove stale worktrees |

## Configuration

All config stored via `git config`. For full configuration details including worktree directory settings, file copying patterns, hooks, and advanced usage, read [references/configuration.md](references/configuration.md).

### Key Config Values

```
gtr.worktrees.dir # base directory for worktrees (default: <repo>-worktrees)
gtr.worktrees.prefix # folder prefix (default: "")
gtr.defaultBranch # default branch (default: auto-detect)
gtr.editor.default # editor: cursor, vscode, zed, none
gtr.ai.default # AI tool: claude, aider, codex, continue, cursor, gemini, opencode, none
gtr.copy.include # glob patterns for files to copy (multi-valued)
gtr.copy.exclude # glob patterns to exclude (multi-valued)
gtr.copy.includeDirs # directories to copy (e.g., node_modules)
gtr.copy.excludeDirs # directory patterns to exclude
gtr.hook.postCreate # commands to run after creation (multi-valued)
gtr.hook.postRemove # commands to run after removal (multi-valued)
```

## Common Scenarios

**Parallel AI agents on one feature:**
```bash
git gtr new feature-auth
git gtr new feature-auth --force --name backend
git gtr new feature-auth --force --name frontend
git gtr ai feature-auth-backend -- --message "Implement API"
git gtr ai feature-auth-frontend -- --message "Build UI"
```

**Node.js project setup:**
```bash
git gtr config set gtr.editor.default cursor
git gtr config add gtr.copy.include "**/.env.example"
git gtr config add gtr.hook.postCreate "npm install"
git gtr config add gtr.hook.postCreate "npm run build"
```

**Non-interactive automation (CI/scripts):**
```bash
git gtr new ci-test --yes --no-copy
git gtr rm ci-test --yes --delete-branch
```

## Troubleshooting

- **Worktree creation fails**: Run `git fetch origin` first. Check branch exists with `git branch -a | grep <branch>`. Try `--track remote`.
- **Editor not opening**: Verify command available (`command -v cursor`). Check config: `git gtr config get gtr.editor.default`.
- **File copying issues**: Check patterns: `git gtr config get gtr.copy.include`. Test with `find . -path "<pattern>"`.
- **Health check**: Run `git gtr doctor` to verify git, editors, and AI tools are properly configured.

## Platform Support

- macOS: Full support (Ventura+). GUI: `open`, terminal: iTerm2/Terminal.app
- Linux: Full support. GUI: `xdg-open`, terminal: gnome-terminal/konsole
- Windows: Git Bash or WSL required
188 changes: 188 additions & 0 deletions skills/git-worktree-runner/references/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,188 @@
# gtr Configuration Reference

## Table of Contents
- Worktree Directory Settings
- Editor Settings
- AI Tool Settings
- File Copying (Patterns & Directories)
- .worktreeinclude File
- Hooks
- Configuration Examples
- Advanced Usage: Same-Branch Worktrees
- Shell Completions

## Worktree Directory Settings

```bash
# Base directory (default: <repo-name>-worktrees as sibling to repo)
gtr.worktrees.dir = <path>

# Supports: absolute paths, repo-relative paths, tilde expansion
gtr.worktrees.dir = /Users/you/all-worktrees/my-project # absolute
gtr.worktrees.dir = .worktrees # repo-relative (add to .gitignore)
gtr.worktrees.dir = ~/worktrees/my-project # tilde expansion

# Folder prefix (default: "")
gtr.worktrees.prefix = dev-

# Default branch (default: auto-detect)
gtr.defaultBranch = main
```

If storing worktrees inside the repository, add the directory to `.gitignore`:
```bash
echo "/.worktrees/" >> .gitignore
```

## Editor Settings

```bash
gtr.editor.default = cursor # options: cursor, vscode, zed, none
```

Setup:
- **Cursor**: Install from cursor.com, enable shell command
- **VS Code**: Install from code.visualstudio.com, enable `code` command
- **Zed**: Install from zed.dev, `zed` available automatically

## AI Tool Settings

```bash
gtr.ai.default = none # options: aider, claude, codex, continue, cursor, gemini, opencode, none
```

| Tool | Install | Set Default |
|---|---|---|
| Aider | `pip install aider-chat` | `git gtr config set gtr.ai.default aider` |
| Claude Code | Install from claude.com | `git gtr config set gtr.ai.default claude` |
| Codex CLI | `npm install -g @openai/codex` | `git gtr config set gtr.ai.default codex` |
| Continue | See docs.continue.dev | `git gtr config set gtr.ai.default continue` |
| Cursor | Install from cursor.com | `git gtr config set gtr.ai.default cursor` |
| Gemini | `npm install -g @google/gemini-cli` | `git gtr config set gtr.ai.default gemini` |
| OpenCode | Install from opencode.ai | `git gtr config set gtr.ai.default opencode` |

Pass arguments to AI tools:
```bash
git gtr ai my-feature -- --model gpt-4
git gtr ai my-feature -- --plan "refactor auth"
```

## File Copying

### Glob Patterns (multi-valued via `add`)

```bash
git gtr config add gtr.copy.include "**/.env.example"
git gtr config add gtr.copy.include "**/CLAUDE.md"
git gtr config add gtr.copy.include "*.config.js"

git gtr config add gtr.copy.exclude "**/.env"
git gtr config add gtr.copy.exclude "**/secrets.*"
```

### Directory Copying

Copy entire directories to avoid reinstalling dependencies:

```bash
git gtr config add gtr.copy.includeDirs "node_modules"
git gtr config add gtr.copy.includeDirs ".venv"
git gtr config add gtr.copy.includeDirs "vendor"

# Exclude sensitive subdirs
git gtr config add gtr.copy.excludeDirs "node_modules/.cache"
git gtr config add gtr.copy.excludeDirs "node_modules/.npm"
git gtr config add gtr.copy.excludeDirs "node_modules/.*"
```

Use cases: JS (`node_modules`), Python (`.venv`), PHP (`vendor`), Go (build caches).

## .worktreeinclude File

Create `.worktreeinclude` in repo root as alternative to config:

```
# .worktreeinclude - .gitignore-style syntax
**/.env.example
**/CLAUDE.md
*.config.js
```

Patterns from `.worktreeinclude` merge with `gtr.copy.include` config.

## Hooks

```bash
# Post-create hooks (multi-valued, run in order)
git gtr config add gtr.hook.postCreate "npm install"
git gtr config add gtr.hook.postCreate "npm run build"

# Post-remove hooks
git gtr config add gtr.hook.postRemove "echo 'Cleaned up!'"
```

Environment variables in hooks: `REPO_ROOT`, `WORKTREE_PATH`, `BRANCH`.

Language-specific examples:
```bash
# Node (npm/pnpm): git gtr config add gtr.hook.postCreate "npm install"
# Python: git gtr config add gtr.hook.postCreate "pip install -r requirements.txt"
# Ruby: git gtr config add gtr.hook.postCreate "bundle install"
# Rust: git gtr config add gtr.hook.postCreate "cargo build"
```

## Configuration Examples

### Minimal
```bash
git gtr config set gtr.worktrees.prefix "wt-"
git gtr config set gtr.defaultBranch "main"
```

### Full Node.js Project
```bash
git gtr config set gtr.worktrees.prefix "wt-"
git gtr config set gtr.editor.default cursor
git gtr config add gtr.copy.include "**/.env.example"
git gtr config add gtr.copy.include "**/.env.development"
git gtr config add gtr.copy.exclude "**/.env.local"
git gtr config add gtr.hook.postCreate "pnpm install"
git gtr config add gtr.hook.postCreate "pnpm run build"
```

### Global Defaults
```bash
git gtr config set gtr.editor.default cursor --global
git gtr config set gtr.ai.default claude --global
```

### Project Setup Script (.gtr-setup.sh)
```bash
#!/bin/sh
git gtr config set gtr.worktrees.prefix "dev-"
git gtr config set gtr.editor.default cursor
git gtr config add gtr.copy.include ".env.example"
git gtr config add gtr.copy.include "docker-compose.yml"
git gtr config add gtr.hook.postCreate "docker-compose up -d db"
git gtr config add gtr.hook.postCreate "npm install"
git gtr config add gtr.hook.postCreate "npm run db:migrate"
```

## Advanced: Same-Branch Worktrees

Use `--force` with `--name` to create multiple worktrees on the same branch:

```bash
git gtr new feature-auth
git gtr new feature-auth --force --name backend # feature-auth-backend/
git gtr new feature-auth --force --name frontend # feature-auth-frontend/
git gtr new feature-auth --force --name tests # feature-auth-tests/
```

Risks: concurrent edits can cause conflicts. Best practice: only edit files in one worktree at a time; commit/stash before switching.

## Shell Completions

**Bash**: `source /path/to/completions/gtr.bash` (requires bash-completion v2)
**Zsh**: Copy `completions/_git-gtr` to fpath, source after `compinit`
**Fish**: `ln -s /path/to/completions/gtr.fish ~/.config/fish/completions/`