Git Amend on Main — 6 Engineers Got Divergent Histories

# io.thecodeforge — Git Amend Internals

# ─────────────────────────────────────────────────────────────
# SCENARIO: Inspecting what amend does to commit objects.
# ─────────────────────────────────────────────────────────────

# Step 1: Make a commit and record its SHA
git add src/payments/RetryConfig.java
git commit -m "feat: add retry config"
BEFORE_AMEND=$(git rev-parse HEAD)
echo "Before amend: $BEFORE_AMEND"
# Example output: 9f2c4a1b3d5e7f8a9b0c1d2e3f4a5b6c7d8e9f0a

# Step 2: Amend the commit message
git commit --amend -m "feat(payment): add PaymentRetryService with retry config"
AFTER_AMEND=$(git rev-parse HEAD)
echo "After amend:  $AFTER_AMEND"
# Example output: 3a7b9c1d2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a2c
# Different SHA — it's a completely new commit object.

# Step 3: Prove the old commit still exists in the object database
echo "Old commit still exists:"
git cat-file -t $BEFORE_AMEND
# Output: commit — the old commit object is still in the repo.

git log --oneline $BEFORE_AMEND -1
# Output: 9f2c4a1 feat: add retry config
# The old commit with the old message is still there.

# Step 4: Show that no branch points to the old commit
echo "Branches containing old commit:"
git branch --contains $BEFORE_AMEND
# Output: (empty) — no branch references the old commit anymore.
# It's orphaned. Git's gc will delete it after 90 days by default.

# Step 5: The new commit has a different parent chain
echo "New commit's parent:"
git log --oneline -2
# The new commit's parent is the commit BEFORE the old commit.
# Not the old commit itself — the old commit is bypassed entirely.

# ─────────────────────────────────────────────────────────────
# RECOVERING THE OLD COMMIT (if you amended by mistake)
# ─────────────────────────────────────────────────────────────

# ORIG_HEAD points to where HEAD was before the amend.
git show ORIG_HEAD --oneline --no-patch
# Output: 9f2c4a1 feat: add retry config
# This is your escape hatch.

# To undo the amend and go back to the old commit:
git reset --hard ORIG_HEAD
# WARNING: this discards the amended commit. The old commit is restored.

# If ORIG_HEAD is gone (you ran other Git commands since the amend):
git reflog
# Shows every HEAD movement. Find the line with the old commit.
# Then: git reset --hard <old-commit-hash>

# io.thecodeforge — Git Amend Patterns

# ─────────────────────────────────────────────────────────────
# PATTERN 1: Fix commit message (no editor)
# ─────────────────────────────────────────────────────────────
git commit --amend -m "feat(payment): Add PaymentRetryService with exponential backoff"
# Done. New commit with new message. Old commit orphaned.

# ─────────────────────────────────────────────────────────────
# PATTERN 2: Fix commit message (with editor)
# Opens your configured editor (vim, nano, VS Code) with the existing message.
# ─────────────────────────────────────────────────────────────
git commit --amend
# Edit the message, save, close. New commit created.

# ─────────────────────────────────────────────────────────────
# PATTERN 3: Add forgotten file, keep existing message
# The most common 'oops' pattern.
# ─────────────────────────────────────────────────────────────
git add src/main/java/io/thecodeforge/payment/RetryConfig.java
git commit --amend --no-edit

# ─────────────────────────────────────────────────────────────
# PATTERN 4: Add forgotten file AND change message
# ─────────────────────────────────────────────────────────────
git add src/main/java/io/thecodeforge/payment/RetryConfig.java
git commit --amend -m "feat(payment): Add PaymentRetryService with retry config and tests"

# ─────────────────────────────────────────────────────────────
# PATTERN 5: Fix author name/email
# ─────────────────────────────────────────────────────────────
git commit --amend --author="John Doe <john.doe@thecodeforge.io>" --no-edit
# Author changed. Commit hash changes. Message and content unchanged.

# ─────────────────────────────────────────────────────────────
# PATTERN 6: Add DCO sign-off to the last commit
# Required by some open-source projects (Linux kernel, CNCF).
# ─────────────────────────────────────────────────────────────
git commit --amend --signoff --no-edit
# Adds 'Signed-off-by: Name <email>' to the commit message.
# The sign-off certifies you have the right to submit the code.

# ─────────────────────────────────────────────────────────────
# PATTERN 7: Remove a file that shouldn't have been committed
# ─────────────────────────────────────────────────────────────
git rm --cached src/main/resources/application-secrets.yml
git commit --amend --no-edit
# The file is removed from the commit but NOT from your working directory.
# --cached means 'remove from index only, keep the file on disk.'

# ─────────────────────────────────────────────────────────────
# AFTER AMEND: Push to remote (your own branch only)
# ─────────────────────────────────────────────────────────────
git push origin feature/payment-retry --force-with-lease
# --force-with-lease is SAFER than --force. Explained in next section.

# io.thecodeforge — --force-with-lease vs --force

# ─────────────────────────────────────────────────────────────
# WRONG: --force overwrites without checking
git push origin feature/payment-retry --force
# If a teammate pushed commit X after your last fetch:
# Commit X is SILENTLY DESTROYED. No warning. No recovery (except reflog).
# The remote branch now points to your amended commit.
# Your teammate's work is gone from the branch.

# ─────────────────────────────────────────────────────────────
# RIGHT: --force-with-lease checks before overwriting
git push origin feature/payment-retry --force-with-lease
# If the remote has commits your local tracking ref doesn't know about:
# error: failed to push some refs to '...'
# hint: Updates were rejected because the tip of your current branch is behind
# hint: its remote counterpart. Integrate the remote changes before pushing again.
# This means: someone else pushed. Fetch and review before force-pushing.

# ─────────────────────────────────────────────────────────────
# VERIFY SAFETY: Check what the remote has that you don't
# ─────────────────────────────────────────────────────────────

# Before force-pushing, always fetch and check
git fetch origin
git log origin/feature/payment-retry..HEAD --oneline
# Shows commits YOU have that the remote doesn't (your amend).

git log HEAD..origin/feature/payment-retry --oneline
# Shows commits the REMOTE has that you don't.
# If this is empty, safe to force-push.
# If this is NOT empty, someone else pushed. Don't force-push blindly.

# ─────────────────────────────────────────────────────────────
# MAKE --force-with-lease THE DEFAULT:
# ─────────────────────────────────────────────────────────────

# Option 1: Alias
git config --global alias.pushf 'push --force-with-lease'
# Now: git pushf feature/payment-retry

# Option 2: Make ALL force pushes use --force-with-lease
git config --global push.useForceIfIncludes true
# In Git 2.30+, this makes --force behave like --force-with-lease
# by requiring the remote ref to match your tracking ref.

# ─────────────────────────────────────────────────────────────
# WHAT IF --force-with-lease REJECTS YOUR PUSH?
# ─────────────────────────────────────────────────────────────

# Step 1: Fetch to see what the remote has
git fetch origin

# Step 2: See what your teammate pushed
git log HEAD..origin/feature/payment-retry --oneline
# Output:
# b7c8d9e Add error handling for PaymentRetryService
# f1a2b3c Fix null check in RetryConfig

# Step 3: Rebase your amended commit on top of their work
git rebase origin/feature/payment-retry
# Your amended commit is replayed on top of their two commits.

# Step 4: Now force-push is safe (your tracking ref is up to date)
git push origin feature/payment-retry --force-with-lease

# io.thecodeforge — Amending Older Commits with Interactive Rebase

# ─────────────────────────────────────────────────────────────
# SCENARIO: You have 5 commits on feature/payment-retry.
# Commit #3 (counting from HEAD) has a bug in PaymentService.java.
# You need to fix that file IN that commit, not in a new commit.
# ─────────────────────────────────────────────────────────────

# Step 1: See your recent commits
git log --oneline -5
# a1b2c3d (HEAD -> feature/payment-retry) Add integration test
# e4f5g6h Add RetryConfig validation
# i7j8k9l Add PaymentService.retryPayment() method  ← THIS ONE HAS THE BUG
# m0n1o2p Add RetryConfig data class
# q3r4s5t Add PaymentClient interface

# Step 2: Start interactive rebase for the last 5 commits
git rebase -i HEAD~5
# Editor opens with:
#
# pick q3r4s5t Add PaymentClient interface
# pick m0n1o2p Add RetryConfig data class
# pick i7j8k9l Add PaymentService.retryPayment() method  ← change 'pick' to 'edit'
# pick e4f5g6h Add RetryConfig validation
# pick a1b2c3d Add integration test
#
# Save and close.

# Step 3: Git pauses at commit i7j8k9l
git status
# Output: interactive rebase in progress; onto abc1234
# Last command done: edit i7j8k9l Add PaymentService.retryPayment() method
# You are currently editing a commit.

# Step 4: Fix the bug in PaymentService.java
echo '// fixed: null check added' >> src/main/java/io/thecodeforge/payment/PaymentService.java

# Step 5: Stage the fix and amend the commit
git add src/main/java/io/thecodeforge/payment/PaymentService.java
git commit --amend --no-edit
# The fix is now part of commit i7j8k9l (with a new SHA).

# Step 6: Continue the rebase — replay the remaining commits
git rebase --continue
# Git replays e4f5g6h and a1b2c3d on top of the amended commit.
# If there are conflicts during replay, resolve them and run git rebase --continue.

# Step 7: Verify the history is clean
git log --oneline -5
# Shows all 5 commits with the fix baked into commit #3.
# All SHAs are different from before (history was rewritten).

# ─────────────────────────────────────────────────────────────
# ABORT: If things go wrong during interactive rebase
# ─────────────────────────────────────────────────────────────
git rebase --abort
# Resets everything to the state before you started the rebase.
# Safe escape hatch. Use it without hesitation.

# ─────────────────────────────────────────────────────────────
# PUSH AFTER INTERACTIVE REBASE (your own branch only)
# ─────────────────────────────────────────────────────────────
git push origin feature/payment-retry --force-with-lease
# Required because multiple commits were rewritten.

# io.thecodeforge — When to Amend vs When NOT to Amend

# ─────────────────────────────────────────────────────────────
# DECISION: Has the commit been pushed to a shared branch?
# ─────────────────────────────────────────────────────────────

# YES → Do NOT amend. Use one of these instead:

# Option A: Create a fixup commit (clean, trackable)
git add src/payments/RetryConfig.java
git commit --fixup HEAD
# Creates a commit with message 'fixup! <original message>'
# Later, during merge or rebase, Git auto-squashes fixup commits.
# Or: git rebase -i --autosquash (automatically orders fixup commits).

# Option B: Revert the commit (undo its changes, preserve history)
git revert HEAD
# Creates a new commit that undoes the last commit's changes.
# Safe to push. No force push required. History is preserved.

# Option C: Create a new commit with the fix (simplest)
git add src/payments/RetryConfig.java
git commit -m "fix(payment): add missing null check in RetryConfig"
# New commit, new message, no history rewrite. Safe everywhere.

# ─────────────────────────────────────────────────────────────
# DECISION: Is the commit on a branch only you use?
# ─────────────────────────────────────────────────────────────

# YES → Amend freely. Force push with --force-with-lease.
git add src/payments/RetryConfig.java
git commit --amend --no-edit
git push origin feature/payment-retry --force-with-lease

# ─────────────────────────────────────────────────────────────
# DECISION: Is the commit on main/develop/release?
# ─────────────────────────────────────────────────────────────

# NEVER amend on main, develop, or release branches.
# These branches are pulled by every developer on the team.
# Amending here will break everyone's local history.

# If you need to fix something on main:
git revert <commit-hash>  # undo the change safely
# or
git cherry-pick <fix-commit>  # bring a fix from another branch

# ─────────────────────────────────────────────────────────────
# FIXUP COMMITS: The amend alternative for shared branches
# ─────────────────────────────────────────────────────────────

# Create a fixup commit that targets a specific older commit
git commit --fixup abc1234
# Creates: 'fixup! <original message of abc1234>'

# Later, during interactive rebase with autosquash:
git rebase -i --autosquash main
# Git automatically places the fixup commit next to its target
# and marks it as 'fixup' (squash without editing message).
# The result: the fix is baked into the original commit.
# This is how you 'amend' a commit that's already been pushed
# without force-pushing until the final rebase.

# io.thecodeforge — Undoing a Bad Amend

# ─────────────────────────────────────────────────────────────
# SCENARIO 1: You just amended and want to undo immediately.
# ORIG_HEAD is still available.
# ─────────────────────────────────────────────────────────────

# Check what ORIG_HEAD points to
git show ORIG_HEAD --oneline --no-patch
# Output: 9f2c4a1 feat: add retry config
# This is the commit BEFORE your amend.

# Undo the amend — restore the original commit
git reset --hard ORIG_HEAD
# Output: HEAD is now at 9f2c4a1 feat: add retry config
# Your branch is back to the pre-amend state.
# The amended commit is now orphaned (recoverable via reflog for 90 days).

# ─────────────────────────────────────────────────────────────
# SCENARIO 2: You ran other Git commands after amending.
# ORIG_HEAD has been overwritten. Use reflog.
# ─────────────────────────────────────────────────────────────

git reflog
# Output:
# a1b2c3d HEAD@{0}: commit (amend): feat(payment): add PaymentRetryService  ← the amend
# 9f2c4a1 HEAD@{1}: commit: feat: add retry config  ← THIS IS THE ORIGINAL
# 8d1e3f5 HEAD@{2}: checkout: moving from main to feature/payment-retry

# Reset to the original commit
git reset --hard 9f2c4a1
# Output: HEAD is now at 9f2c4a1 feat: add retry config

# ─────────────────────────────────────────────────────────────
# SCENARIO 3: You amended, pushed, and now want to undo the push.
# ─────────────────────────────────────────────────────────────

# Option A: Force-push the original commit
git reset --hard ORIG_HEAD  # or reflog hash
git push origin feature/payment-retry --force-with-lease
# Remote now has the original commit. The amended commit is gone from remote.

# Option B: Revert the amend (safer if others pulled the amended commit)
git revert HEAD
# Creates a new commit that undoes the amended commit's changes.
# Then create another commit with the correct changes.
# No force push required. History is preserved.

# ─────────────────────────────────────────────────────────────
# SCENARIO 4: You amended multiple times and want a specific version.
# ─────────────────────────────────────────────────────────────

git reflog
# Output:
# c3d4e5f HEAD@{0}: commit (amend): feat(payment): third attempt at message
# b2c3d4e HEAD@{1}: commit (amend): feat(payment): second attempt at message
# a1b2c3d HEAD@{2}: commit (amend): feat(payment): first attempt at message
# 9f2c4a1 HEAD@{3}: commit: feat: add retry config  ← the original

# Pick any version and reset to it
git reset --hard HEAD@{2}
# Output: HEAD is now at a1b2c3d feat(payment): first attempt at message
# You're back to the first amended version.

# io.thecodeforge — Amending Merge Commits

# ─────────────────────────────────────────────────────────────
# SCENARIO: You merged a feature branch into main and the merge
# commit message is the default 'Merge branch feature/x into main'.
# You want a more descriptive message.
# ─────────────────────────────────────────────────────────────

# Step 1: Verify the last commit is a merge commit
git log --oneline -1 --merges
# Output: a1b2c3d Merge branch 'feature/payment-retry' into main

# Step 2: Amend the merge commit message
git commit --amend -m "Merge feature/payment-retry: Add PaymentRetryService with exponential backoff"
# New merge commit created with descriptive message.
# The file content is unchanged — only the message changed.

# ─────────────────────────────────────────────────────────────
# SCENARIO: You need to change content in a merge commit.
# ─────────────────────────────────────────────────────────────

# Step 1: Make the changes
echo '// added during merge fix' >> src/payments/MergeNote.java

# Step 2: Stage and amend
git add src/payments/MergeNote.java
git commit --amend --no-edit
# The file is now part of the merge commit.
# The merge commit's SHA changes.

# ─────────────────────────────────────────────────────────────
# WARNING: Amending merge commits on shared branches
# ─────────────────────────────────────────────────────────────

# If the merge commit is on main and teammates have pulled it:
# - Their local main has the old merge commit SHA
# - Your amended main has a new merge commit SHA
# - Histories have diverged
# - Force push required, breaks everyone

# Rule: amend merge commits ONLY before anyone else pulls them.
# If in doubt, create a follow-up commit instead:
git add src/payments/MergeNote.java
git commit -m "fix: add missing MergeNote.java from merge"

# io.thecodeforge — Amend and CI/CD Interaction

# ─────────────────────────────────────────────────────────────
# SCENARIO: You pushed a commit, CI started building.
# You noticed a typo, amended, and force-pushed.
# ─────────────────────────────────────────────────────────────

# Step 1: Original push triggers CI
git push origin feature/payment-retry
# CI build #1042 starts — building commit 9f2c4a1

# Step 2: You notice typo, amend, force-push
git commit --amend -m "feat(payment): Add PaymentRetryService"
git push origin feature/payment-retry --force-with-lease
# CI build #1043 starts — building commit a1b2c3d
# Build #1042 is still running (for the old commit)

# ─────────────────────────────────────────────────────────────
# GITHUB ACTIONS: Auto-cancels previous builds on same branch
# ─────────────────────────────────────────────────────────────
# In your workflow YAML:
# concurrency:
#   group: ${{ github.workflow }}-${{ github.ref }}
#   cancel-in-progress: true
# This ensures only ONE build runs per branch at a time.
# When you force-push, the old build is cancelled automatically.

# ─────────────────────────────────────────────────────────────
# GITLAB CI: Similar behaviour with resource_group
# ─────────────────────────────────────────────────────────────
# In .gitlab-ci.yml:
# deploy:
#   resource_group: production
#   script: ./deploy.sh
# resource_group ensures only one deploy job runs at a time.

# ─────────────────────────────────────────────────────────────
# JENKINS: Manual cancellation required
# ─────────────────────────────────────────────────────────────
# Jenkins does NOT auto-cancel builds on force-push by default.
# You need to manually abort the old build (#1042) from the UI.
# Or install the 'Discard Old Build' plugin with appropriate config.

# ─────────────────────────────────────────────────────────────
# VERIFY: Check that CI ran on the correct SHA
# ─────────────────────────────────────────────────────────────
git rev-parse HEAD
# Output: a1b2c3d  ← this should match the SHA in your CI build logs
# If CI shows 9f2c4a1, it's building the old commit — abort it.

# io.thecodeforge — Git Aliases for Amend Workflows

# ─────────────────────────────────────────────────────────────
# ESSENTIAL ALIASES — add these to your ~/.gitconfig
# ─────────────────────────────────────────────────────────────

# Amend last commit without opening editor
git config --global alias.amend 'commit --amend --no-edit'
# Usage: git amend
# Equivalent to: git commit --amend --no-edit

# Amend last commit WITH editor
git config --global alias.amende 'commit --amend'
# Usage: git amende
# Opens editor to edit the message.

# Amend and force-push with lease in one command
git config --global alias.amendpush '!git commit --amend --no-edit && git push --force-with-lease'
# Usage: git amendpush
# Amends the last commit and force-pushes. Use only on your own branch.

# Amend with signoff
git config --global alias.amendsign 'commit --amend --signoff --no-edit'
# Usage: git amendsign
# Adds DCO sign-off to the last commit.

# Force push with lease (safer alternative to --force)
git config --global alias.pushf 'push --force-with-lease'
# Usage: git pushf origin feature/my-branch

# Undo the last amend (using ORIG_HEAD)
git config --global alias.undoamend 'reset --hard ORIG_HEAD'
# Usage: git undoamend
# WARNING: discards the amended commit. Use immediately after amend.

# Show what the last amend changed
git config --global alias.amenddiff 'diff ORIG_HEAD HEAD'
# Usage: git amenddiff
# Shows the diff between the original commit and the amended commit.
# Useful for verifying your amend did what you expected.

# ─────────────────────────────────────────────────────────────
# SHELL ALTERNATIVE — add to ~/.bashrc or ~/.zshrc
# ─────────────────────────────────────────────────────────────

# One-liner: amend + push (for when you KNOW it's safe)
alias gamend='git commit --amend --no-edit && git push --force-with-lease'

# Quick message fix: amend with new message and push
alias gamendm='git commit --amend && git push --force-with-lease'