git-workflows

Git and GitHub workflow patterns.

how to use

• /git-workflows Apply these conventions to all git operations in this conversation.

• /git-workflows <context> Review the context against rules below and suggest improvements.

when to apply

Reference these guidelines when:

• writing commit messages
• creating or naming branches
• opening or reviewing pull requests
• resolving merge conflicts
• deciding between rebase and merge
• running destructive git commands

rule categories by priority

priority	category	impact
1	commit conventions	critical
2	branching strategy	critical
3	PR best practices	high
4	conflict resolution	high
5	destructive commands	critical
6	repository hygiene	medium

quick reference

1. commit conventions (critical)

• follow Conventional Commits: type(scope): description
• valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
• scope is optional but encouraged for multi-module repos
• description must be imperative mood, lowercase, no period
• body explains WHY, not WHAT (the diff shows what)
• breaking changes: add ! after type/scope and BREAKING CHANGE: in footer
• keep subject line under 72 characters
• one logical change per commit; split unrelated changes

2. branching strategy (critical)

• main/master: always deployable, protected
• feature branches: feature/<ticket>-<short-description>
• bug fixes: fix/<ticket>-<short-description>
• hotfixes: hotfix/<description> (branch from main, merge to main + develop)
• release branches: release/<version> when applicable
• delete branches after merge
• never commit directly to main/master

Decision tree:

• Single developer, simple project: trunk-based with short-lived branches
• Team with CI/CD: GitHub Flow (main + feature branches)
• Multiple release versions: Git Flow (main + develop + feature/release/hotfix)

3. PR best practices (high)

• title: concise, under 70 chars, describes the change
• description: include Summary (what + why), Test Plan, and Breaking Changes
• keep PRs focused: one concern per PR
• prefer small PRs (< 400 lines changed)
• link related issues with Closes #123 or Fixes #123
• request reviewers explicitly
• address all review comments before merging
• use draft PRs for work-in-progress

4. conflict resolution (high)

• pull/rebase frequently to minimize conflicts
• understand both sides before resolving; never blindly accept one side
• test after resolving conflicts
• for complex conflicts, discuss with the other author
• prefer git rebase for local-only branches to maintain linear history
• prefer git merge for shared branches to preserve context

5. destructive commands (critical)

• never force-push to main/master or shared branches
• always confirm before: git reset --hard, git clean -f, git checkout ., git push --force
• prefer --force-with-lease over --force when force-pushing
• back up work before destructive operations: git stash or create a backup branch
• git reflog is your safety net for recovering lost commits
• never use --no-verify to skip hooks without explicit user request

6. repository hygiene (medium)

• keep .gitignore up to date; never commit generated files, build artifacts, or secrets
• use .gitattributes for line ending consistency
• tag releases with semantic versioning: v1.2.3
• write meaningful branch descriptions for long-lived branches
• prune stale remote branches periodically: git remote prune origin
• keep commit history clean; squash fixup commits before merge

common fixes

problem	fix
wrong commit message	git commit --amend (if not pushed)
committed to wrong branch	git stash, switch branch, git stash pop
need to undo last commit	git reset --soft HEAD~1 (keeps changes staged)
accidentally committed secrets	remove file, add to .gitignore, use git filter-repo to purge history, rotate credentials immediately
merge conflict in lockfile	delete lockfile, regenerate, commit
diverged from remote	git pull --rebase for linear history