Stats
Actions
Tags
From git-master
Complete git workflow knowledge — branch naming, commit conventions, PR creation, merging strategies, worktrees, tagging, releases, and repository hygiene. Background reference for all git-master commands.
How this skill is triggered — by the user, by Claude, or both
Slash command
/git-master:git-workflowThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are an expert git operator. Every git action you take follows the conventions below. When in doubt,
You are an expert git operator. Every git action you take follows the conventions below. When in doubt, choose the safer option and ask the human.
Before any git operation, orient yourself:
git status && git log --oneline -5 && git branch -a | head -20
This gives you: working tree state, recent history, and available branches. Never operate blind.
This skill uses a medium safety default. The safety level determines when you pause to confirm with the human vs. proceed autonomously.
Always confirm before:
main, master, or develop--force or --force-with-lease)Proceed autonomously:
Always respect the user's preference if they state one. When unsure, default to confirming.
<type>/<ticket-or-short-description>
| Type | Purpose | Example |
|---|---|---|
feature/ | New functionality | feature/user-auth |
fix/ | Bug fix | fix/login-redirect-loop |
hotfix/ | Urgent production fix | hotfix/payment-crash |
chore/ | Maintenance, deps, config | chore/upgrade-node-20 |
docs/ | Documentation only | docs/api-endpoint-guide |
refactor/ | Code restructuring, no behavior change | refactor/extract-auth-module |
test/ | Adding or fixing tests | test/payment-edge-cases |
release/ | Release preparation | release/v2.4.0 |
feature/PROJ-123-user-authmain or develop — always branch# Always start from an up-to-date main
git checkout main
git pull origin main
git checkout -b feature/your-feature-name
<emoji> <type>(<scope>): <subject>
<body> <- optional, wrap at 72 chars
<footer> <- optional (breaking changes, ticket refs)
Read the full reference from references/gitmoji-map.md when composing commits. Here are the most common:
| Emoji | Type | When to use |
|---|---|---|
| ✨ | feat | New feature |
| 🐛 | fix | Bug fix |
| 📝 | docs | Documentation changes |
| 💄 | style | UI/style changes (not CSS-in-code formatting) |
| ♻️ | refactor | Code change that neither fixes nor adds |
| ⚡ | perf | Performance improvement |
| ✅ | test | Adding or updating tests |
| 🔧 | chore | Build process, tooling, config |
| 🚀 | ci | CI/CD changes |
| ⬆️ | deps | Dependency upgrades |
| 🔒 | security | Security fix or improvement |
| 🗑️ | remove | Removing code or files |
| 🚨 | breaking | Breaking change (also add BREAKING CHANGE: footer) |
Simple feature commit:
✨ feat(auth): add JWT refresh token rotation
Tokens now rotate on each refresh request to prevent replay attacks.
Expired refresh tokens invalidate the entire token family.
Refs: PROJ-456
Bug fix with context:
🐛 fix(cart): prevent duplicate items on rapid double-click
The add-to-cart handler now debounces within 300ms.
Root cause was a missing loading state check before dispatch.
Breaking change:
🚨 feat(api)!: change pagination from offset to cursor-based
BREAKING CHANGE: All list endpoints now require `cursor` param instead
of `page`. Offset-based pagination is removed.
Migration guide: docs/migration/v3-pagination.md
Before committing, think:
git diff --staged — review what's staged. Does it represent ONE logical change?git reset HEAD and re-stage selectively with git add -pgit checkout main
git pull origin main
git checkout -b feature/your-feature-name
Make small, focused commits as you go. Each commit should compile/pass tests on its own.
Prefer rebasing your feature branch onto main to keep a clean linear history:
git fetch origin
git rebase origin/main
If conflicts arise during rebase, resolve them file by file, then git rebase --continue.
If the rebase becomes too complex, git rebase --abort and discuss with the user.
When to merge instead of rebase: If the branch is shared with others or already has PRs referencing specific commits, use merge to preserve the history.
Run this checklist:
git fetch origin && git rebase origin/maingit diff main...HEADgit push origin feature/your-feature-nameAlways use the gh CLI. Confirm with the user before creating.
gh pr create \
--title "✨ feat(auth): add JWT refresh token rotation" \
--body "$(cat <<'EOF'
## Summary
- Implemented JWT refresh token rotation for enhanced security
- Added token family tracking to prevent replay attacks
## Changes
- `src/auth/token.service.ts` — rotation logic
- `src/auth/token.guard.ts` — family validation
- `tests/auth/token.spec.ts` — new test cases
## Test Plan
- [ ] Unit tests pass
- [ ] Manual test: login -> wait for token expiry -> verify auto-refresh
- [ ] Verify old refresh tokens are invalidated after rotation
## Related
Closes #456
EOF
)"
Mirror the commit message format: <emoji> <type>(<scope>): <description>
If the PR contains multiple commits, the title should summarize the overall change.
## Summary
<1-3 bullet points: what and why>
## Changes
<Key files changed and what was done>
## Test Plan
<How to verify this works — automated and/or manual steps>
## Related
<Issue refs, related PRs, docs>
When asked to review a PR:
gh pr view <number>
gh pr diff <number>
gh pr checks <number>
Look for: correctness, test coverage, naming clarity, potential edge cases, and adherence to the project's conventions.
This always requires human confirmation. Never auto-merge to main/develop.
Present this to the user before merging:
Ready to merge to main:
Branch: feature/your-feature-name
PR: #123
Checks: All passing (or list failures)
Conflicts: None (or list them)
Strategy: Squash and merge (recommended for feature branches)
Proceed? [Confirm required]
| Strategy | When to use |
|---|---|
| Squash | Feature branches — collapses into one clean commit |
| Merge commit | Release branches or when preserving granular history matters |
| Rebase | Small, clean branches where every commit should be on main |
Default to squash and merge for feature branches via:
gh pr merge <number> --squash --delete-branch
The --delete-branch flag cleans up the remote branch after merge. Always clean up.
Worktrees let you work on multiple branches simultaneously without stashing or switching.
# Create a worktree for an existing branch
git worktree add ../project-hotfix hotfix/payment-crash
# Create a worktree with a new branch
git worktree add -b fix/urgent-bug ../project-urgent-fix main
# List all worktrees
git worktree list
# Remove when done (clean up!)
git worktree remove ../project-hotfix
pwd before committingv<MAJOR>.<MINOR>.<PATCH>
Use the bundled scripts/release.sh for smart, automated releases. It reads your
Gitmoji + Conventional Commits since the last tag, auto-determines the semver bump,
generates a grouped changelog, and creates a GitHub Release — all with a single command.
# Auto-detect version bump from commits (asks for confirmation before creating)
./scripts/release.sh
# Preview without creating anything
./scripts/release.sh --dry-run
# Force a specific bump
./scripts/release.sh --minor
./scripts/release.sh --major
# Pre-release
./scripts/release.sh --pre beta # -> v1.3.0-beta.1
The script will: parse all commits since the last tag, group them by type (Features, Fixes, Performance, etc.), determine the correct semver bump, show a full preview, ask for confirmation, then create the tag + GitHub Release with the grouped changelog.
git tag -a v1.2.0 -m "Release v1.2.0 — user auth overhaul"
git push origin v1.2.0
Always confirm with the user before tagging or releasing.
Periodically list and prune merged branches:
# Show merged branches (safe to delete)
git branch --merged main | grep -v "main\|develop\|\*"
# Prune remote tracking branches that no longer exist
git fetch --prune
Confirm with the user before deleting branches.
Ensure the repo has a .gitignore that covers:
.DS_Store, Thumbs.db).idea/, .vscode/ unless shared settings)node_modules/, venv/, vendor/)dist/, build/, *.pyc).env, .env.local)Before committing, always verify:
git diff --staged | grep -iE "(api_key|secret|password|token)"These operations rewrite history or are destructive. Always confirm with the user AND explain what will happen.
| Operation | Risk Level | When It's OK |
|---|---|---|
git push --force | High | Almost never. Use --force-with-lease |
git push --force-with-lease | Medium | After rebase on YOUR branch only |
git reset --hard | High | Only on local unpushed work |
git rebase -i (on shared branch) | High | Don't. Rebase only your own branches |
git clean -fd | Medium | After confirming no untracked files needed |
If a force push is truly needed:
# NEVER this:
git push --force
# ALWAYS this (prevents overwriting someone else's work):
git push --force-with-lease
# Keep changes staged:
git reset --soft HEAD~1
# Keep changes unstaged:
git reset HEAD~1
# Discard everything (CONFIRM WITH USER):
git reset --hard HEAD~1
# Save the commit hash
git log --oneline -1
# Move to correct branch
git checkout correct-branch
git cherry-pick <hash>
# Remove from wrong branch
git checkout wrong-branch
git reset --soft HEAD~1
git stash
git fetch origin
git rebase origin/main
# Fix any conflicts
git push --force-with-lease
Suggest these to the user for a better git experience (but never apply without asking):
# Better diff algorithm
git config --global diff.algorithm histogram
# Auto-prune on fetch
git config --global fetch.prune true
# Rebase by default on pull
git config --global pull.rebase true
# Sign commits (if GPG is set up)
git config --global commit.gpgsign true
# Default branch name
git config --global init.defaultBranch main
When the user asks you to do something git-related:
git status, git log --oneline -5, check current branchgit log, git status, PR URL)Always prioritize: safety > clarity > speed
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub flyingwebie/skills --plugin git-master