Git Operations

Activate when creating commits, managing branches, creating pull requests, resolving conflicts, or following Git workflows.

Commit Format

Follow the Conventional Commits specification:

type(scope): description

optional body

optional footer

Types: feat , fix , docs , style , refactor , perf , test , build , ci , chore , revert

Subject line rules:

• Keep under 50 characters

• Lowercase after type prefix

• No period at the end

• Use imperative mood ("add" not "added" or "adds")

Body (optional): Wrap at 72 characters. Focus on the what and how — never describe the changes themselves, as the git diff handles that.

Footer (optional): Reference issues (Closes #123 ), note breaking changes (BREAKING CHANGE: ... ).

NEVER include attribution — no Co-Authored-By , Signed-off-by , or similar footers. This rule has no exceptions.

Examples:

Single-line (preferred for most commits)

feat(auth): add JWT authentication fix(api): handle null values in user response docs(readme): add installation instructions chore(deps): bump plugin versions

With body and footer

feat(api): add user search endpoint

Implement full-text search across user names and emails using PostgreSQL's full-text search capabilities.

BREAKING CHANGE: API now requires PostgreSQL 12+ Closes #789

PR Format

Title matches commit format. Body is a bullet list of changes only.

gh pr create --title "feat(auth): add JWT authentication" --body "- Add JWT generation and validation

• Implement refresh token rotation
• Add authentication middleware"

Rules:

• No attribution (no "Generated with Claude Code" or similar)

• No PR templates or boilerplate sections

• No "Summary", "Test Plan", or other headers

• Just the changes as bullet points

• Keep it minimal and scannable

PR Workflow

• Push: git push -u origin <branch>

• Create PR: gh pr create with minimal format (title + bullets)

• Watch CI: gh pr checks --watch (wait for CI to complete)

• After CI passes (if using beads):

• bd close <task-id>

• git add .beads/ && git commit -m "chore(beads): close <task-id>"

• git push

• Notify user: "CI passed, PR ready for merge review"

• Cleanup (after user merges):

• git checkout main && git pull

• git branch -d <branch>

• Continue: bd ready for next task

Merge Strategy

Always squash merge PRs:

gh pr merge <number> --squash

Never use regular merge or rebase merge for PRs. Squash merge keeps main history clean with one commit per PR.

Branch Naming

<type>/<description> <type>/<issue-number>-<description>

Examples: feature/user-authentication , fix/456-null-pointer-error , chore/update-dependencies

GitHub PR Commands

gh pr create --title "type(scope): description" --body "- change 1" gh pr create --draft # Draft PR gh pr list # List PRs gh pr view 123 # View PR gh pr checkout 123 # Checkout PR locally gh pr merge 123 --squash # Squash merge PR

Key Rules

• No attribution: Never add Co-Authored-By , Signed-off-by , or similar to commits. No "Generated with Claude Code" or similar in PRs

• Squash merge PRs: Always use gh pr merge --squash

• Single-line commits preferred: Use body only when explanation is needed

• Never merge without approval: Always wait for user to approve PR merges

• Clean up after merge: Delete branches locally and remotely

• Use gcms: Generate commit messages with /core:gcms skill

References

For detailed command references and advanced topics, see:

• commands.md — Branch management, staging, committing, viewing changes, stashing, remote operations, tags, aliases

• advanced.md — Rebasing, merge strategies, conflict resolution, interactive rebase, history management, cherry-picking, bisect, submodules

• troubleshooting.md — Common issues (wrong branch, sensitive data, recover deleted branch, bad merge) and best practices