# Rollback Procedures > Recovery and undo operations for all scenarios. **Related:** [AGENT_GUARDRAILS.md](../AGENT_GUARDRAILS.md) | [COMMIT_WORKFLOW.md](./COMMIT_WORKFLOW.md) --- ## Overview This document provides comprehensive rollback procedures for recovering from errors at any stage of the development workflow. Know these commands before making changes. **Golden Rule:** Always know your rollback command before editing. --- ## Rollback Decision Tree ``` WHAT NEEDS TO BE UNDONE? │ ├── Uncommitted changes │ └── See: IMMEDIATE ROLLBACK │ ├── Committed but not pushed │ └── See: POST-COMMIT ROLLBACK │ ├── Already pushed │ └── See: POST-PUSH ROLLBACK │ ├── Database changes │ └── See: DATABASE ROLLBACK │ └── Service/deployment issues └── See: SERVICE ROLLBACK ``` --- ## Immediate Rollback (Uncommitted Changes) ### Single File Rollback ```bash # Discard changes to one file git checkout HEAD -- path/to/file.py # Verify file restored git status cat path/to/file.py | head -20 ``` ### Multiple Files Rollback ```bash # Discard changes to specific files git checkout HEAD -- file1.py file2.py # Discard all uncommitted changes (CAUTION) git checkout HEAD -- . ``` ### Staged Changes Rollback ```bash # Unstage file (keep changes in working directory) git reset HEAD path/to/file.py # Unstage all files git reset HEAD # Then discard working changes if needed git checkout HEAD -- . ``` ### New File Rollback ```bash # Remove untracked file rm path/to/new-file.py # Remove all untracked files (CAUTION) git clean -fd ``` --- ## Post-Commit Rollback (Not Pushed) ### Undo Last Commit (Keep Changes) ```bash # Undo commit, keep changes staged git reset --soft HEAD~1 # Undo commit, keep changes unstaged git reset HEAD~1 # Verify git status git log -3 --oneline ``` ### Undo Last Commit (Discard Changes) ```bash # Undo commit AND discard changes (CAUTION) git reset --hard HEAD~1 # Verify git status git log -3 --oneline ``` ### Undo Multiple Commits ```bash # Undo last N commits (keep changes) git reset --soft HEAD~N # Undo last N commits (discard changes) git reset --hard HEAD~N ``` ### Fix Commit Message ```bash # Only if commit not pushed AND you made the commit git commit --amend -m "corrected message" ``` --- ## Post-Push Rollback (Requires Care) ### Safe Rollback (Create Revert Commit) ```bash # Revert the last commit (creates new commit) git revert HEAD # Revert specific commit git revert # Push the revert git push origin ``` ### Revert Multiple Commits ```bash # Revert a range (oldest..newest) git revert --no-commit HEAD~3..HEAD git commit -m "Revert: undo last 3 commits" git push ``` ### Force Push (LAST RESORT - REQUIRES USER APPROVAL) ```bash # DANGER: Only with explicit user permission # DANGER: Only if no one else has pulled # Reset to previous state git reset --hard # Force push (REQUIRES EXPLICIT APPROVAL) git push --force origin ``` **When to consider force push:** - You're the only one on the branch - No one has pulled the bad commits - User explicitly approves - Documented why force push was necessary --- ## Database Rollback Considerations ### Before Making Database Changes ``` ALWAYS: [ ] Create backup/snapshot [ ] Test in non-production first [ ] Have rollback script ready [ ] Know point-in-time recovery options ``` ### General Database Rollback ```sql -- If using transactions ROLLBACK; -- If changes committed, need restore -- Use backup/snapshot created before changes ``` ### Application-Level Database Rollback ``` If application has migrations: 1. Identify the migration to rollback 2. Run down migration 3. Verify data integrity 4. Update application if needed ``` --- ## Service Rollback Procedures ### Container/Docker Rollback ```bash # Rollback to previous image docker stop docker run # Or with docker-compose docker-compose down # Update docker-compose.yml to previous image docker-compose up -d ``` ### Kubernetes Rollback ```bash # Rollback deployment kubectl rollout undo deployment/ # Rollback to specific revision kubectl rollout undo deployment/ --to-revision= # Verify kubectl rollout status deployment/ ``` ### Cloud Function Rollback ```bash # Redeploy previous version # (Platform specific - AWS Lambda, GCP Functions, etc.) # Generally: deploy from previous commit or version ``` --- ## Disaster Recovery Checklist ### When Everything Goes Wrong ``` IMMEDIATE ACTIONS: [ ] 1. STOP - Don't make it worse [ ] 2. ASSESS - What exactly broke? [ ] 3. COMMUNICATE - Inform stakeholders [ ] 4. ISOLATE - Prevent further damage [ ] 5. DOCUMENT - Note what happened [ ] 6. RECOVER - Use appropriate rollback [ ] 7. VERIFY - Confirm recovery worked [ ] 8. POST-MORTEM - Learn from incident ``` ### Recovery Priority ``` PRIORITY ORDER: 1. Data integrity - Is data safe? 2. Service availability - Is system up? 3. Functionality - Does it work correctly? 4. Performance - Is it fast enough? 5. Cosmetics - Does it look right? ``` --- ## Communication Templates ### Incident Notification ``` INCIDENT: [Brief description] TIME: [When detected] IMPACT: [What's affected] STATUS: [Investigating/Mitigating/Resolved] ACTIONS: [What's being done] ETA: [Expected resolution time] ``` ### Rollback Completion ``` ROLLBACK COMPLETE What happened: [Brief description] What was rolled back: [Commits/changes] Current state: [Restored to X] Verification: [How verified] Next steps: [What happens next] ``` --- ## Quick Reference ``` +------------------------------------------------------------------+ | ROLLBACK QUICK REFERENCE | +------------------------------------------------------------------+ | UNCOMMITTED CHANGES: | | git checkout HEAD -- # Single file | | git checkout HEAD -- . # All files | +------------------------------------------------------------------+ | COMMITTED NOT PUSHED: | | git reset --soft HEAD~1 # Undo, keep staged | | git reset HEAD~1 # Undo, keep unstaged | | git reset --hard HEAD~1 # Undo, discard (CAUTION) | +------------------------------------------------------------------+ | ALREADY PUSHED: | | git revert HEAD # Create revert commit (SAFE) | | git push # Push the revert | +------------------------------------------------------------------+ | NEVER WITHOUT APPROVAL: | | git push --force # Destroys history | | git reset --hard on shared # Loses others' work | +------------------------------------------------------------------+ ``` --- ## Prevention Checklist **Before any risky operation:** ``` [ ] Backup exists or can be created [ ] Rollback command identified [ ] Impact scope understood [ ] User informed of risks [ ] Recovery plan ready ``` --- **Last Updated:** 2026-01-14 **Authored by:** TheArchitectit **Document Owner:** Project Maintainers **Line Count:** ~300