gitpro

name: gitpro description: ALWAYS use this skill for ALL git operations. NEVER run git commit, git add, git push, git merge, git checkout -b, or git branch -m directly. This skill automates git workflows with conventional commits, automatic changelog updates, semantic version bumping, and consistent formatting. Use when user requests checkpoint, commit, rename branch, merge, sync, pull, refresh, or create new branch operations. hooks: PreToolUse: - matcher: Bash hooks: - type: command command: ~/.claude/skills/gitpro/scripts/create-token.sh timeout: 5

GitPro

Git workflow automation using scripts for atomic, efficient operations.

Supports: Node.js (package.json) and Python (pyproject.toml)

Architecture

┌─────────────────────────────────────────┐
│ Claude Code PreToolUse hook (Skill)     │
│ - Validates TS, TODOs before gitpro     │
│ - Checkpoint operations skip validation │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│ GitPro Skill (this file)                │
│ - AI analyzes changes                   │
│ - AI determines parameters              │
│ - AI calls script with parameters       │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│ Bash Scripts (atomic execution)         │
│ - Handle beads sync                     │
│ - Use --no-verify (validation done)     │
│ - Single script = single operation      │
└─────────────────────────────────────────┘

Quick Start

Core Operations

Checkpoint

Fast timestamped commit without full analysis.

AI Steps:

1. Determine if user provided a custom message prefix
2. Call script

Script Call:

~/.claude/skills/gitpro/scripts/gitpro-checkpoint.sh [optional-message]

Examples:

• User: "checkpoint" → gitpro-checkpoint.sh
• User: "checkpoint with message Phase 1 complete" → gitpro-checkpoint.sh "Phase 1 complete"
• AI completing work: → gitpro-checkpoint.sh "Refactored auth module"

Commit

Full conventional commit with changelog and optional branch rename.

AI Steps:

1. Run git status to see all changed/untracked files
2. Run git diff --stat to see actual changes per file (insertions/deletions)
3. Categorize changes by feature/purpose:
   • Group related files (e.g., all files for "image processing" vs "AI descriptions")
   • Identify distinct features/fixes being committed
   • Note: Changes may span multiple sessions - analyze ALL diffs, not just session memory
4. Load reference files:
   • ~/.claude/skills/gitpro/references/commit-types.md - emoji/type mapping
   • ~/.claude/skills/gitpro/references/changelog-rules.md - what goes in changelog
5. Build commit message:
   • If single feature: <emoji> <type>: <description>
   • If multiple features: Multi-line with primary type, then bullet list
6. Build changelog entry:
   • List ALL user-facing features/fixes (see changelog-rules.md)
   • Exclude refactors, tests, docs, style changes
7. Determine branch rename if current is wt-*
8. Call script with parameters

Script Call:

~/.claude/skills/gitpro/scripts/gitpro-commit.sh \
  --message "✨ feat: add user authentication" \
  --old-branch "wt-petehalsted" \
  --new-branch "add-user-auth" \
  --changelog "- **✨ Add User Authentication** - JWT-based auth with refresh tokens"

Parameters:

What Script Does:

• Beads sync (pre-commit)
• Stage all changes
• Rename branch (if --old-branch/--new-branch provided)
• Update changelog (if --changelog provided)
• Commit with --no-verify
• Beads sync (post-commit)
• Push to remote (non-main branches)

CRITICAL: Analyze ALL Changes

• Do NOT rely on what you remember working on in this session
• Uncommitted changes may include work from previous sessions
• Always use git diff --stat to see the actual scope of changes
• If you see changes you don't recognize, they still need to be in the commit message/changelog

Merge to Main

Full merge workflow with version bump and cleanup.

AI Steps:

1. Check for uncommitted changes - if any, do Commit workflow first
2. Get current branch name: git branch --show-current
3. Analyze commits to determine version bump type:

   git log --oneline main..HEAD
   

   • major: BREAKING CHANGE, ! after type
   • minor: feat:, ✨
   • patch: everything else
4. Get username via whoami command
5. Call script with parameters

Script Call:

~/.claude/skills/gitpro/scripts/gitpro-merge.sh \
  --source-branch "add-user-auth" \
  --bump-type "minor" \
  --username "petehalsted"

Parameters:

What Script Does:

• Push source branch
• Checkout main, pull
• Merge source branch
• Bump version, commit, tag (if package.json or pyproject.toml exists)
• Push main and tags
• Delete merged source branch
• Create fresh wt-{username} branch

Sync

Safe fast-forward from remote. Use when another machine pushed changes and local needs to catch up.

AI Steps:

1. Call script (optionally with --branch if not main)

Script Call:

~/.claude/skills/gitpro/scripts/gitpro-sync.sh [--branch name]

Parameters:

What Script Does:

• Checks for uncommitted changes → aborts if dirty
• Warns about untracked files (informational only)
• Switches to target branch if not current
• Fetches from origin
• Checks for unpushed local commits → aborts if diverged
• Shows incoming commits
• Fast-forwards with --ff-only (refuses if not a clean fast-forward)
• Switches back to original branch if it changed

Safety Guarantees:

• Will NOT overwrite uncommitted changes
• Will NOT overwrite unpushed local commits
• Will NOT create merge commits (ff-only)
• Will NOT modify any branch other than the target

Trigger Words: "sync", "pull", "refresh", "get updates", "get updates from repo"

Merge from Branch

Pull changes from another branch into current.

AI Steps (no script needed):

1. git fetch origin
2. git merge origin/{branch} or git merge {branch}
3. If conflicts: report and exit
4. If not main/master: ask user about deleting source branch

New Branch

Create new working branch.

AI Steps (no script needed):

1. Check for uncommitted changes - offer to commit/checkpoint
2. git checkout -b {name} (default: wt-$(whoami))
3. git push -u origin {name}

Commit Types Reference

Validation

Validation happens in Claude Code PreToolUse hook BEFORE this skill runs:

• TypeScript errors (Node) → blocks gitpro (except checkpoint)
• Python lint/type errors (Python) → blocks gitpro (except checkpoint)
• Invalid TODOs → blocks gitpro (except checkpoint)
• Toast usage → warning only

Scripts use --no-verify because validation already passed.

Scripts Location

All scripts in: ~/.claude/skills/gitpro/scripts/

Project Type Detection

Merge script auto-detects project type:

• Node.js: package.json exists → uses npm version
• Python: pyproject.toml exists → uses gitpro-bump-python.py

Version format follows semver: vX.Y.Z