Commit Changes

Stage files selective. Write clear commit messages. Verify commit history.

When Use

• Save logical unit of work to version control
• Create commit with descriptive, conventional message
• Amend most recent commit (message or content)
• Review what commit before commit

Inputs

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

Steps

Step 1: Review Current Changes

Check working tree status. Inspect diffs.

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

# See unstaged changes
git diff

# See staged changes
git diff --staged

Got: Clear picture of all modified, staged, untracked files.

If fail: git status fail? Verify inside git repo (git rev-parse --is-inside-work-tree).

Step 2: Stage Files Selective

Stage specific files. Avoid git add . or git add -A — may grab 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 staged before commit.

git diff --staged

Got: Only intended files and changes staged. No .env, credentials, large binaries.

If fail: Unstage accidental files with git reset HEAD <file>. Sensitive data staged? Unstage now, before commit.

Step 3: Write Commit Message

Use conventional commits format. Always pass 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 <[email protected]>
EOF
)"

Conventional commit types:

Type	When use
feat	New feature
fix	Bug fix
docs	Documentation only
test	Add or update tests
refactor	Code change — no fix, no new feature
chore	Build, CI, dependency updates
style	Formatting, whitespace (no logic change)

Got: Commit created with descriptive message. Explains why, not just what.

If fail: Pre-commit hook fail? Fix issue, re-stage with git add, create new commit. No --amend — failed commit never created.

Step 4: Amend Last Commit (Optional)

Only amend if commit not pushed to 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

Got: Previous commit updated in-place. git log -1 shows amended content.

If fail: Commit already pushed? No amend. Create new commit. Force-push amended commits to shared branches breaks history.

Step 5: Verify Commit

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

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

# Verify the commit content
git show HEAD

Got: Commit appears in history with correct message, author, file changes.

If fail: Commit has wrong files? Use git reset --soft HEAD~1 to undo commit, keep changes staged. Re-commit correct.

Checks

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

Pitfalls

• Commit too much at once: Each commit = one logical change. Split unrelated changes into separate commits.
• Using git add . blind: Always review git status first. Prefer stage specific files by name.
• Amend pushed commits: Never amend commits pushed to shared branch. Rewrites history. Breaks collaborators.
• Vague commit messages: "fix bug" or "update" tells nothing. Describe what changed and why.
• Forget --no-edit on content amends: Adding forgotten files to last commit? Use --no-edit — keeps existing message.
• Hook fail leading to --amend: Pre-commit hook fail → commit never created. --amend would modify previous commit. Always create new commit after fix hook issues.

See Also

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