Git Commit with Conventional Commits

Create standardized, semantic git commits using the Conventional Commits specification. Analyze the actual diff to determine appropriate type, scope, and message.

Commit format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit types

Breaking changes

Exclamation mark after type/scope:

feat!: remove deprecated endpoint

And/or: BREAKING CHANGE footer

feat: allow config to extend other configs

BREAKING CHANGE: `extends` key behavior changed

Workflow

1. Inspect status

git status --porcelain

Default behavior:

• Prefer already staged changes when present.
• If nothing is staged, stage only the coherent logical change.
• Leave unrelated worktree changes untouched.

2. Analyze diff

# If files are staged, use staged diff.
git diff --staged

# If nothing is staged, use working tree diff.
git diff

When staged and unstaged changes coexist, commit only the staged changes by default. If the staged changes appear incomplete, inspect the unstaged diff and decide whether to stage closely related files or ask the user.

3. Stage files (if needed)

If nothing is staged or you want to group changes differently:

# Stage specific files
git add path/to/file1 path/to/file2

# Stage by pattern
git add *.test.*
git add src/components/*

Never commit secrets (.env, credentials.json, private keys).

4. Generate commit message

Analyze the diff to determine:

• Type: What kind of change is this?
• Scope: What area/module is affected?
• Description: One-line summary of what changed. (present tense, imperative mood, <72 chars)

Use the smallest accurate type and scope. Prefer short, single-line commits with no body. Add a body only when the commit is large or nuanced enough that it cannot be summarized clearly in one short sentence. Do not add an explanatory body just because extra context is available.

Use breaking-change syntax only when the diff truly changes a public contract.

5. Execute commit

# Single line
git commit -m "<type>[scope]: <description>"

# Multi-line with body/footer
git commit -m "$(cat <<'EOF'
<type>[scope]: <description>

<optional body>

<optional footer>
EOF
)"

Best practices

• One logical change per commit.
• Present tense: "add" not "added".
• Imperative mood: "fix bug" not "fixes bug".
• Keep description under 72 characters.
• Reference issues with trailers such as Closes #123 or Refs #456 only when the diff or user request provides that context. If there is no body, append after the description instead: feat: add login, closes #123.

Git safety protocol

• Never update git config.
• Never run destructive commands (--force, hard reset) without explicit request.
• Never skip hooks (--no-verify) unless user asks.
• Never force push to main/master.
• If hooks fail before the commit is created, fix the issue and retry
• If a commit was created and later validation fails, do not amend unless requested

Final verification

After committing:

git status --short
git log -1 --oneline

Report the new commit hash and subject. Mention any remaining unstaged or untracked changes.

References

• [Conventional Commits 1.0.0](references/conventional-commits.md)
• Forked from github/awesome-copilot/git-commit