From git-workflow-best-practices
Git workflow best practices — branch management with `feature/` / `bugfix/` / `hotfix/` / `release/` prefixes (Vincent Driessen's Git Flow), Conventional Commits format (`type(scope): subject` with `feat` / `fix` / `docs` / `style` / `refactor` / `test` / `chore` types), atomic commits with imperative mood, pre-commit hygiene (run tests, review diff, no debug code, no secrets, no `git add .` without per-file review), remote workflow (`git pull --rebase` before push, no force push to shared branches, resolve conflicts locally, push only feature-complete code), and code review process (PR creation required, max ~400 lines per PR, self-review first, squash on merge for clean main history). Use this skill whenever the user is about to commit, push, create a branch, open or merge a pull request, write a commit message, or asks about git workflow conventions — including staging files, splitting commits, choosing a branch name, formatting a commit message, deciding whether to rebase or merge, sizing a PR, or handling conflicts. Trigger on `git commit`, `git push`, `git checkout -b`, `git rebase`, `gh pr create`, `git merge`, `git stash`, or when the user shows uncommitted/staged changes via `git status` / `git diff` and is preparing to commit. Do NOT use for pure read-only git history exploration (`git log`, `git show`, `git blame` for context), Mercurial, SVN, Perforce, or generic version-control conceptual questions unrelated to a real workflow decision.
How this skill is triggered — by the user, by Claude, or both
Slash command
/git-workflow-best-practices:git-workflow-best-practicesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill captures workflow and style conventions for git work. **It does NOT cover safety rules** — those are in Claude Code's built-in system prompt and always apply (never `--force` on `main`/`master`, never bypass hooks with `--no-verify` unless explicitly requested, never amend after a failed pre-commit hook, never commit unless asked, prefer specific file paths over `git add -A`/`git add...
This skill captures workflow and style conventions for git work. It does NOT cover safety rules — those are in Claude Code's built-in system prompt and always apply (never --force on main/master, never bypass hooks with --no-verify unless explicitly requested, never amend after a failed pre-commit hook, never commit unless asked, prefer specific file paths over git add -A/git add .). This skill adds the style layer on top.
Two-line summary the skill enforces: commits are small, named, intentional; branches and PRs are scoped to one purpose, reviewed before merge, and leave a clean history on main.
main / master. Always create a feature branch first. The system prompt's safety rules forbid force-push to main; this rule prevents the situation where you'd want to.feature/<short-slug> — new functionalitybugfix/<short-slug> — non-critical bug fixeshotfix/<short-slug> — urgent production fixesrelease/<version> — release preparation
The prefix tells anyone glancing at git branch what the branch is for without reading the slug.feature/* and bugfix/* branch from develop, merge back to develop.hotfix/* branches from main, merges to both main AND develop (so develop doesn't lose the fix).release/* branches from develop, merges to main (and back to develop if any release fixes happened).
Projects without a develop branch (trunk-based) treat main as the integration target — feature branches still merge through PRs, just into main.git revert surgical (revert one bug fix without losing the unrelated refactor that came in the same session), git bisect precise (the failing commit pinpoints one change), and code review readable (reviewer reads one intent at a time, not five interleaved).type(scope): subject
feat (new feature), fix (bug fix), docs (documentation), style (formatting, no logic change), refactor (code restructure, no behavior change), test (adding/fixing tests), chore (build, deps, tooling).feat(auth): add JWT validation, fix(api): handle null user in /me.standard-version, semantic-release, git-cliff derive changelogs and version bumps automatically from these prefixes. Even without automation, scanning git log --oneline for feat: vs fix: is faster than reading prose.git bisect lie. Even if CI will catch it, a green local run prevents wasted PR cycles.git diff --cached (the staged set) before running git commit. Catches: forgotten debug prints, accidentally-included unrelated files, secrets, leftover TODO comments meant for another commit.print(), console.log(), debugger, breakpoint(), commented-out experiments, dead code from refactors. If it's intentional logging, route it through the project's logger; if it's debugging, remove it..env files with real credentials. Use a secrets manager + .env.example placeholder. If a secret slips in, treat it as compromised — rotate it, then git filter-repo to scrub history (and force-push with explicit team coordination).git pull --rebase origin <branch>. Or set git config pull.rebase true once.
git stash or commit-and-amend-locally for in-progress work.--force-with-lease (which fails if someone else pushed in the meantime) over --force. Never force-push to main, develop, release/*, or any branch shared with others.
--force overwrites the remote's history with yours. Anyone with commits on top of what you overwrote loses them silently. The system prompt's safety rule already blocks force-push to main; this rule extends "shared" to release/develop branches.develop/main, and the rebase to catch up gets harder the longer you wait. Daily git pull --rebase origin develop keeps conflicts small.<<<<<<< HEAD markers; PRs in that state confuse reviewers and break CI. If a rebase conflict is too large to resolve, ask for help before continuing.main's history one commit per feature, readable in git log --oneline. The branch's intermediate "wip", "fix typo", "address review" commits don't pollute the canonical history. Long-running branches with intentionally-curated commits (e.g., a refactor done in 5 atomic steps) can use rebase-merge instead — but the default for typical feature branches is squash.develop + main separation. Trunk-based workflows merge directly to main; feature branches are still scoped, just shorter-lived. Match the project's convention; don't impose Git Flow on a trunk-based repo.CONTRIBUTING.md, a .github/pull_request_template.md, or visibly enforced commit format in git log, conform to it rather than introducing this skill's defaults wholesale.pytest-best-practices, sqlalchemy-best-practices, etc.) handle the what changed; this skill handles the how it lands in git.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 mvolkov83/skills --plugin git-workflow-best-practices