From 8051d315b75a42524e52ff7f870908556bd6325d Mon Sep 17 00:00:00 2001 From: aryan <48391385+thearyanag@users.noreply.github.com> Date: Fri, 6 Feb 2026 18:09:42 +0530 Subject: [PATCH] feat: add skill (#1) * feat: add skill * refactor: rename skill/ to skills/ for npx skills compatibility The `npx skills add` CLI searches `skills/` as a priority directory. Renamed to follow the standard convention so the skill is discoverable without relying on recursive fallback search. Co-Authored-By: Claude Opus 4.6 --------- Co-authored-by: Claude Opus 4.6 --- skills/git-worktree-runner/SKILL.md | 119 +++++++++++ .../references/configuration.md | 188 ++++++++++++++++++ 2 files changed, 307 insertions(+) create mode 100644 skills/git-worktree-runner/SKILL.md create mode 100644 skills/git-worktree-runner/references/configuration.md diff --git a/skills/git-worktree-runner/SKILL.md b/skills/git-worktree-runner/SKILL.md new file mode 100644 index 0000000..c499624 --- /dev/null +++ b/skills/git-worktree-runner/SKILL.md @@ -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 [opts]` | Create worktree. Options: `--from `, `--from-current`, `--track`, `--no-copy`, `--no-fetch`, `--force` (requires `--name`), `--name `, `--yes` | +| `git gtr editor ` | Open in configured editor. Override: `--editor ` | +| `git gtr ai [-- args]` | Start AI tool. Override: `--ai `. Pass args after `--` | +| `git gtr go ` | Print path. Use: `cd "$(git gtr go my-feature)"` | +| `git gtr run ` | Execute command in worktree directory | +| `git gtr rm ... [opts]` | Remove worktree(s). Options: `--delete-branch`, `--force`, `--yes` | +| `git gtr list [--porcelain]` | List all worktrees | +| `git gtr config {get\|set\|add\|unset} [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: -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 `. 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 ""`. +- **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 diff --git a/skills/git-worktree-runner/references/configuration.md b/skills/git-worktree-runner/references/configuration.md new file mode 100644 index 0000000..8670009 --- /dev/null +++ b/skills/git-worktree-runner/references/configuration.md @@ -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: -worktrees as sibling to repo) +gtr.worktrees.dir = + +# 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/`