Commit Changes

Stage selective → clear msg → verify history.

Use When

• Save logical unit → version control
• Write conventional msg
• Amend last commit (msg or content)
• Review before commit

In

• Required: Changed files
• Optional: Commit msg (drafted if none)
• Optional: Amend prev?
• Optional: Co-author

Do

Step 1: Review

Check tree + diffs:

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

# See unstaged changes
git diff

# See staged changes
git diff --staged

→ Clear view all modified, staged, untracked.

If err: git status fails → verify inside repo (git rev-parse --is-inside-work-tree).

Step 2: Stage Selective

Stage specific files, not git add . or -A → avoids secrets + 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

→ Only intended files. No .env, creds, big binaries.

If err: accidental stage → git reset HEAD <file>. Secret staged → unstage immediately before commit.

Step 3: Write Msg

Conventional format. Always HEREDOC → 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 types:

→ Commit created w/ msg explaining why, not what.

If err: pre-commit hook fails → fix, re-stage, create new commit (no --amend → failed commit never existed).

Step 4: Amend Last (Optional)

Amend only if not pushed:

# 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

→ Prev commit updated in-place. git log -1 shows amended.

If err: already pushed → no amend. New commit instead. Force-push → history divergence.

Step 5: Verify

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

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

# Verify the commit content
git show HEAD

→ Commit in history w/ correct msg, author, files.

If err: wrong files → git reset --soft HEAD~1 (undo, keep staged), re-commit.

Check

• Only intended files committed
• No secrets (tokens, passwords, .env)
• Msg conventional
• Body explains why
• git log shows correct metadata
• Pre-commit hooks passed

Traps

• Too much at once: One commit = one logical change. Split unrelated.
• git add . blind: Always git status first. Stage by name.
• Amend pushed: Never amend pushed commits → rewrites history, breaks collaborators.
• Vague msgs: "fix bug" tells nothing. Say what + why.
• Forget --no-edit: Content amend → use --no-edit → keeps msg.
• Hook fail → --amend: Hook fail = no commit. --amend hits prev commit. Always new commit after hook fix.

→

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