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

Got: A clear picture of all modified, staged, and untracked files.

If fail: 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

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

If fail: Unstage accidentally added files with git reset HEAD <file>. If sensitive data was staged, unstage 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 <[email protected]>
EOF
)"

Conventional commit types:

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

If fail: 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

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

If fail: 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

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

If fail: 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

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