Commit Changes

Stage files selectively, write clear commit messages, and verify commit history.

When to Use

• Saving a logical unit of work to version control
• Creating a commit with a descriptive, conventional message
• Amending the most recent commit (message or content)
• Reviewing what will be committed before committing

Inputs

• Required: One or more changed files to commit
• Optional: Commit message (will be drafted if not provided)
• Optional: Whether to amend the previous commit
• Optional: Co-author attribution

Procedure

Step 1: Review Current Changes

Check working tree status and inspect diffs:

# See which files are modified, staged, or untracked
git status

# See unstaged changes
git diff

# See staged changes
git diff --staged

Expected: Clear picture of all modified, staged, and untracked files.

On failure: If git status fails, verify you are inside a git repository (git rev-parse --is-inside-work-tree).

Step 2: Stage Files Selectively

Stage specific files rather than using git add . or git add -A to avoid accidentally including sensitive files or unrelated changes:

# Stage specific files by name
git add src/feature.R tests/test-feature.R

# Stage all changes in a specific directory
git add src/

# Stage parts of a file interactively (not supported in non-interactive contexts)
# git add -p filename

Review what is staged before committing:

git diff --staged

Expected: Only the intended files and changes are staged. No .env, credentials, or large binaries.

On failure: Unstage accidentally added files with git reset HEAD <file>. If sensitive data was staged, unstage immediately before committing.

Step 3: Write a Commit Message

Use conventional commits format. Always pass the message via HEREDOC for proper formatting:

git commit -m "$(cat <<'EOF'
feat: add weighted mean calculation

Implements weighted_mean() with support for NA handling and
zero-weight filtering. Includes input validation for mismatched
vector lengths.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

Conventional commit types:

Type	When to use
feat	New feature
fix	Bug fix
docs	Documentation only
test	Adding or updating tests
refactor	Code change that neither fixes nor adds
chore	Build, CI, dependency updates
style	Formatting, whitespace (no logic change)

Expected: Commit created with a descriptive message that explains why, not just what.

On failure: If a pre-commit hook fails, fix the issue, re-stage with git add, and create a new commit (do not use --amend since the failed commit was never created).

Step 4: Amend the Last Commit (Optional)

Only amend if the commit has not been pushed to a shared remote:

# Amend message only
git commit --amend -m "$(cat <<'EOF'
fix: correct weighted mean edge case for empty vectors

EOF
)"

# Amend with additional staged changes
git add forgotten-file.R
git commit --amend --no-edit

Expected: The previous commit is updated in-place. git log -1 shows the amended content.

On failure: If the commit was already pushed, do not amend. Create a new commit instead. Force-pushing amended commits to shared branches causes history divergence.

Step 5: Verify the Commit

# View the last commit
git log -1 --stat

# View recent commit history
git log --oneline -5

# Verify the commit content
git show HEAD

Expected: The commit appears in history with the correct message, author, and file changes.

On failure: If the commit contains wrong files, use git reset --soft HEAD~1 to undo the commit while keeping changes staged, then re-commit correctly.

Validation

• Only intended files are included in the commit
• No sensitive data (tokens, passwords, .env files) committed
• Commit message follows conventional commits format
• Message body explains why the change was made
• git log shows the commit with correct metadata
• Pre-commit hooks (if any) passed

Common Pitfalls

• Committing too much at once: Each commit should represent one logical change. Split unrelated changes into separate commits.
• Using git add . blindly: Always review git status first. Prefer staging specific files by name.
• Amending pushed commits: Never amend commits that have been pushed to a shared branch. This rewrites history and causes problems for collaborators.
• Vague commit messages: "fix bug" or "update" tells nothing. Describe what changed and why.
• Forgetting --no-edit on content amends: When adding forgotten files to the last commit, use --no-edit to keep the existing message.
• Hook failure leading to --amend: When a pre-commit hook fails, the commit was never created. Using --amend would modify the previous commit. Always create a new commit after fixing hook issues.

Related Skills

• manage-git-branches - branch workflow before committing
• create-pull-request - next step after committing
• resolve-git-conflicts - handling conflicts during merge/rebase
• configure-git-repository - repository setup and conventions