Git

Git

Clear, repeatable git workflow with a bias toward safety.

Router

Use the smallest workflow that matches the user intent.

Config (Edit Here)

Worktree working directories (the folders you cd into) live outside .git/.

Set this once and use it everywhere:

WORKTREES_DIR=./.worktrees
WORKTREE_PATH=$WORKTREES_DIR/<topic>

If you want a different location (e.g. ../.worktrees or ~/worktrees/<repo>), update WORKTREES_DIR above and follow the same shape in references/worktree-workflow.md.

Resilience Rules (Worktrees)

• If multiple worktree root folders are detected (example: both ./.worktrees/ and ../repo-feature-x/ exist), do not delete anything by default.
• Prefer consolidating into WORKTREES_DIR using git worktree move (when possible) or a remove+re-add plan.
• If stale metadata exists, propose a cleanup plan: git worktree prune + remove/quarantine orphan directories (with confirmation).

Global Safety Rules (Never Violate)

• Never force push to main/master.
• Never commit secrets (env files, keys, credentials).
• Never rewrite history that is already pushed unless explicitly requested.
• Always show what will change before an irreversible action.

Confirmation Policy

Read-only commands are always OK.

Everything that changes state/history/remote requires explicit user confirmation:

• git add, git commit, git push
• git merge, git rebase, git reset, git revert
• git worktree add, git worktree remove
• git tag (create/delete)
• git branch -d/-D

Quick Start

# Read-only
git status
git diff

# Commit
git diff --cached
git commit -m "feat(scope): why"

# Worktrees
git worktree list

Git

Unified git workflow skill: branch-first development, security-first commits, worktree workflows, and PR creation/review via gh.

Quick Start

• Home/router: git/SKILL.md

Common workflows:

• Read-only inspection: git/references/read-only.md
• Commit flow + best practices: git/references/commit-workflow.md
• Branch flow: git/references/branch-workflow.md
• Worktrees (configurable root): git/references/worktree-workflow.md
• Worktree maintenance (cleanup + consolidation): git/references/worktree-maintenance.md
• PR create: git/references/pr-workflow.md
• PR review/fix: git/references/pr-review-workflow.md
• Tags: git/references/tag-workflow.md
• Advanced/recovery: git/references/advanced-workflows.md

Worktree Path Config

Edit WORKTREES_DIR in git/SKILL.md.

Install

npx skills add bntvllnt/agent-skills --skill git

Manual install (download this folder only):

• Copy the git/ folder into your agent's skills directory.
• Ensure the folder name is git and includes SKILL.md.

Requirements

• git
• gh is recommended for PR workflows (optional)

Advanced / Recovery Workflows

These are easy to misuse; confirm intent and show consequences before running.

Undo staging (safe)

git restore --staged <path>

Revert a commit (safe history)

git revert <sha>

Reset (local history rewrite; dangerous)

Only when commits are not pushed and user explicitly wants it.

git reset --soft <sha>

Rebase (history rewrite)

Only when branch state is understood and user explicitly requests.

Worktree maintenance

Prune stale metadata (confirm first):

git worktree prune

Branch Workflow

Goal: branch-first development; keep base branch clean.

Requires confirmation for branch creation/deletion/switching if it changes state.

Conventions

• Names: feat/<topic>, fix/<topic>, chore/<topic>
• Base branch: main or master (detect from repo)

Flow

1. Update base

git fetch --all --prune
git switch <base>
git pull --ff-only

2. Create a feature branch

git switch -c <type>/<topic>

3. Verify

git status
git branch --show-current

CLI Help (git / gh)

Goal: show the official CLI help for a command.

These commands are read-only.

git help

git help
git help -a
git help <command>
git <command> -h

Examples:

git help worktree
git help tag
git worktree -h

gh help (optional)

If gh is installed:

gh help
gh help release
gh release create --help

Commit Workflow

Goal: one intent per commit, no secrets, staged diff reviewed.

Requires confirmation before any git add/git commit.

Flow

1. Inspect

git status
git diff

2. Stage intentionally (preferred: path-based)

git add <paths...>

3. Review staged

git diff --cached

4. Write message

Format: <type>(<scope>): <why>

Types: feat, fix, refactor, chore, docs, test, perf, ci

5. Commit

git commit -m "<type>(<scope>): <why>"

6. Verify

git status

Notes

• Avoid git add . unless user explicitly asks.
• If hooks modify files after commit, stage the changes and create a follow-up commit (no amend unless requested).

Commit Best Practices

• Atomic: one intent per commit; avoid mixing refactors + features.
• Explain why: the title states reason/impact, not a file list.
• Review what you ship: always read git diff --cached before committing.
• Prefer small commits: easier review and safer rollback.
• No WIP on shared branches: avoid wip: unless explicitly requested.
• Tests: if behavior changes, add/update tests in the same PR (ideally same commit or adjacent).
• Sensitive files: do not commit .env*, keys, credentials, or generated secrets.

Message Examples

feat(auth): add password reset flow
fix(api): handle nil token on refresh
refactor(db): extract query builder for reuse
docs(readme): clarify install instructions

PR Review Workflow

Goal: see PR feedback, apply fixes on the same branch, keep commits intentional.

Flow

1. Sync

git fetch origin

2. Review PR

gh pr view --comments
gh pr checks

3. Fix

• Make code changes
• Use commit workflow for each coherent fix
• Push updates

git push

Threads

If you need to resolve threads / request reviews, use gh subcommands when possible.

PR Workflow (gh)

Goal: push branches and open PRs with a clear title/body.

Requires confirmation before push.

Flow

1. Confirm state

git status
git branch --show-current

2. Push branch

git push -u origin HEAD

3. Create PR

gh pr create --title "<title>" --body "<body>" --base <base>

If gh is not installed, push the branch and open a PR in your Git hosting UI.

4. Check CI

gh pr checks

Read-Only Inspection

These are safe to run without confirmation.

git status
git diff
git diff --cached
git log --oneline -n 20
git show
git tag -l
git describe --tags --always
git branch --show-current
git remote -v
git fetch --all --prune
git worktree list

If you need to understand "what changed" quickly:

git status
git diff
git diff --cached
git log --oneline -n 10

Tags Workflow

Goal: create consistent version tags safely.

Requires confirmation for any tag creation/deletion.

Best Practices

• Prefer SemVer tags: vMAJOR.MINOR.PATCH (example: v1.2.3).
• Use annotated tags for releases (not lightweight tags).
• Tag the exact commit you want to release (usually the merge commit to the base branch).
• Do not move/retag public tags unless explicitly requested.

Read-Only Checks

git status
git log --oneline -n 10
git tag -l
git describe --tags --always

Create a Release Tag (Annotated)

1. Ensure you're on the intended branch/commit and the working tree is clean. 2. Choose the next version tag.

git tag -a vX.Y.Z -m "vX.Y.Z"

3. Push the tag:

git push origin vX.Y.Z

Verify

git show vX.Y.Z

Fixes / Recovery (Confirm First)

Delete a local tag

git tag -d vX.Y.Z

Delete a remote tag

Only if you understand consumers may already be using it.

git push --delete origin vX.Y.Z

Move a tag (rewriting public history)

Avoid. Only do this if explicitly requested and after explaining impact.

Worktree Maintenance (Auto-Clean + Consolidate)

This workflow makes worktrees resilient:

• auto-clean stale metadata
• detect multiple worktree root folders
• propose consolidation into WORKTREES_DIR (from git/SKILL.md)

Requires confirmation before any state-changing command.

Step 1: Inventory

git worktree list
git branch --show-current
git status

Step 2: Detect Problems

Look for:

• Worktree paths spread across multiple root folders (example: both ./.worktrees/ and ../repo-foo/).
• Registered worktree paths that no longer exist on disk.
• Orphan directories that look like old worktrees but are not registered.

Step 3: Safe Auto-Clean Plan

A) Prune stale metadata (registered but missing)

Propose (confirm first):

git worktree prune

Then re-run:

git worktree list

B) Consolidate multiple roots into WORKTREES_DIR

Rule: do not delete anything by default.

For each worktree whose working directory is outside WORKTREES_DIR, propose one of:

1) Move (preferred):

git worktree move <old-path> <worktrees-dir>/<topic>

2) Remove + re-add (fallback):

git worktree remove <old-path>
git worktree add <worktrees-dir>/<topic> <branch>

Block consolidation if the worktree has uncommitted changes.

C) Orphan directories (not registered)

If a directory looks like an old worktree but is not in git worktree list, propose:

• verify what's inside (read-only)
• either delete it (confirm) or move it to a quarantine folder

Never delete directories automatically.

Worktree Summary (Proactive Analysis)

Goal: show all worktrees with branch, PR status, change analysis, and safe-to-delete verdicts.

Read-only — no confirmation needed. Uses WORKTREES_DIR from git/SKILL.md.

Triggers

worktree summary, worktree status, worktree overview, show worktrees

Step 1: Inventory

git worktree list --porcelain
git branch --show-current

Parse each worktree entry: path, branch, HEAD commit.

Detect base branch: main or master (whichever exists).

If no worktrees besides main repo: output "No worktrees. Main repo only." and stop.

Step 2: Per-Worktree Analysis

For each worktree (cap at 10, show "N more..." if exceeded):

2a. Branch + Commit Status

# From inside worktree path
git -C <worktree-path> status --porcelain
git -C <worktree-path> log --oneline <base>..HEAD
git -C <worktree-path> log --oneline HEAD..<base>

Derive:

• Committed ahead: N commits ahead of base (unpushed work)
• Committed behind: N commits behind base
• Uncommitted: count of modified/untracked files
• Clean: no uncommitted changes (working tree matches HEAD)
• Fully merged: branch HEAD is reachable from base (0 unique commits ahead)

2b. PR Lookup

gh pr list --head <branch-name> --state all --json number,state,title,url --limit 1

If gh unavailable: mark PR as "unknown (no gh)".

Derive:

• PR merged: branch work is in base
• PR open: work in progress, not merged
• No PR: no PR created for this branch

2c. Change Analysis (uncommitted + unpushed vs base)

Only runs when worktree has uncommitted or unpushed changes.

For each changed file (cap at 20 files, summarize rest):

# Get list of changed files (uncommitted)
git -C <worktree-path> diff --name-only
git -C <worktree-path> diff --cached --name-only
git -C <worktree-path> ls-files --others --exclude-standard

# Get list of changed files (unpushed commits)
git -C <worktree-path> diff --name-only <base>..HEAD

For each changed file, classify:

COVERED (safe to discard)

The same change exists in base branch. Check:

# Does base branch have equivalent changes to this file?
git log <base> --oneline -5 -- <file>
# Compare: does current base version already include the worktree's changes?
git -C <worktree-path> diff <base> HEAD -- <file>

If diff is empty or minimal (cosmetic only — whitespace, imports, formatting): COVERED. If remaining diff is semantic (logic, behavior), classify as UNIQUE instead. Note which commit in base covers it: "same change in <base>@<short-sha> (<commit-msg>)".

OBSOLETE (safe to discard)

The changed file/code was removed or rewritten in base:

# Does the file still exist in base?
git show <base>:<file> 2>/dev/null

If file doesn't exist in base: check if it was intentionally deleted (git log). If the specific code block was rewritten: OBSOLETE. Note: "file removed in <base>@<short-sha> (<commit-msg>)" or "code rewritten in <base>@<short-sha>".

UNIQUE (will lose work)

No match found in base branch or any open PR. This is original work.

Report: file path, line count of changes, brief description of what changed.

Mark: "NOT in <base> or any open PR — WILL LOSE WORK if deleted".

2d. Verdict

Step 3: Output

┌─────────────────────────────────────────────────────────────────┐
│                       WORKTREE SUMMARY                          │
├─────────────────────────────────────────────────────────────────┤
│ Main: <main-repo-path> (<base-branch>)                          │
│ Dir:  <WORKTREES_DIR>                                           │
│ Total: N worktrees (N safe, N caution, N blocked)               │
└─────────────────────────────────────────────────────────────────┘

 #  Worktree           Branch              PR         Verdict
─── ─────────────────── ─────────────────── ────────── ──────────────
 1  <path>              <branch>            #N merged  SAFE TO DELETE
 2  <path>              <branch>            #N open    CAUTION
 3  <path>              <branch>            —          BLOCKED

Detailed Analysis (per worktree with changes)

Only shown for CAUTION and BLOCKED worktrees:

## N. <path> — <branch> -> <VERDICT>

  PR:          #N <state> | — (none)
  Committed:   N ahead, N behind base
  Uncommitted: N files modified

  ┌─ Change Analysis (vs <base>) ───────────────────────────────┐
  │                                                              │
  │ COVERED  <file>                                              │
  │          <description of what changed>                       │
  │          Same change in <base>@<sha> (<msg>)                 │
  │                                                              │
  │ OBSOLETE <file>                                              │
  │          <description>                                       │
  │          File removed in <base>@<sha> (<msg>)                │
  │                                                              │
  │ UNIQUE   <file>                                              │
  │          N lines changed (<brief description>)               │
  │          NOT in <base> or any open PR                        │
  │          !! WILL LOSE WORK if deleted                        │
  │                                                              │
  └──────────────────────────────────────────────────────────────┘

  Verdict: N covered, N obsolete, N unique
  Action:  <recommended next step>

Recommendations

  Recommendations:
    DELETE  #1 <path> -> `git worktree remove <path>`
    REVIEW  #2 <path> -> commit <unique-files> first
    BLOCKED #3 <path> -> rescue <unique-files> first

Legend (always shown)

  Change Classifications:
    COVERED  — same change exists in base branch (safe to discard)
    OBSOLETE — targets code removed/rewritten in base (safe to discard)
    UNIQUE   — not found elsewhere (WILL LOSE WORK)

  Verdicts:
    SAFE TO DELETE — all work merged/covered, no unique changes
    CAUTION        — PR still open or unpushed commits (no data loss)
    BLOCKED        — has unique uncommitted/unpushed work (data loss risk)

Limits

• Max 10 worktrees in summary (show "and N more..." for the rest)
• Max 20 files per worktree in change analysis (show "and N more files..." for the rest)
• If gh CLI unavailable: skip PR lookup, note "PR: unknown (gh unavailable)"

Worktree Workflow

Goal: parallel work without stashing.

Important fact: .git/worktrees/ is git's internal metadata directory.

• You do NOT put a worktree working directory inside .git/worktrees/.
• Git automatically creates/updates .git/worktrees/<name>/ metadata when you add a worktree.

Recommended working directory target (repo-local): ./.worktrees/<topic>.

Config: use WORKTREES_DIR from git/SKILL.md.

• Default: WORKTREES_DIR=./.worktrees
• Worktree path shape: $WORKTREES_DIR/<topic>

Requires confirmation for git worktree add/remove.

Worktree Health Check (Resilience)

Run these first when anything looks off:

git worktree list
git status

If the repo has worktree folders outside WORKTREES_DIR (for example ../repo-feature-x/), do not delete them. Instead, consolidate into WORKTREES_DIR (see below).

Create worktree

From the main repo worktree:

mkdir -p <worktrees-dir>
git worktree add -b <type>/<topic> <worktrees-dir>/<topic> <base>

If the branch already exists:

git worktree add <worktrees-dir>/<topic> <type>/<topic>

Env file carry-over

When creating a new worktree for active development, copy the repo's existing local env files from the source checkout into the new worktree before starting app work.

Default rule:

• source checkout = the main repo working directory you launched the worktree from
• copy project-local .env* files that represent active local runtime config
• preserve relative paths inside the repo
• do not invent new env values in the worktree

Typical monorepo examples:

• apps/mobile/.env.local
• apps/web/.env.local
• packages/backend/.env.local

Recommended flow after git worktree add:

# example pattern — copy existing local env files into the new worktree
rsync -a --relative \
  apps/mobile/.env.local \
  apps/web/.env.local \
  packages/backend/.env.local \
  <worktree-path>/

If a repo has many env files, discover them first from the source checkout and copy the relevant local env files into the worktree before running app commands.

List worktrees

git worktree list

Remove worktree

git worktree remove <worktrees-dir>/<topic>

Optionally delete branch (only if merged / no longer needed):

git branch -d <type>/<topic>

Troubleshooting

• If removal fails due to modifications: commit/stash inside that worktree first.
• If a worktree is missing on disk but still registered: git worktree prune (confirm first).

Consolidate Into WORKTREES_DIR

Goal: keep worktree working directories under one root (WORKTREES_DIR) while letting git manage internal metadata under .git/worktrees/.

Detect multiple worktree roots

If git worktree list shows worktrees under different parent folders, treat that as "multiple roots".

Preferred: move an existing worktree

When supported, use git's built-in move (keeps registration intact):

git worktree move <old-path> <worktrees-dir>/<topic>

Fallback: remove + re-add

If move isn't possible (or user wants a clean reattach):

git worktree remove <old-path>
git worktree add <worktrees-dir>/<topic> <branch>

Never remove a worktree that has uncommitted changes.