# Rollback

> Safely undo committed or shipped changes with non-destructive git revert or restore. Use only when the user explicitly asks to roll back, revert, undo, back out, or restore; never reset hard, force-push, or substitute for PR review, monitoring, or issue status work.

- Skill: `harshanandak/rollback` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add harshanandak/rollback`
- Raw SKILL.md: https://api.skillmd.com/api/skills/harshanandak/rollback/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: harshanandak (https://skillmd.com/u/harshanandak)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/harshanandak/rollback

---


Comprehensive rollback system with multiple methods and automatic USER content preservation.

# Rollback

This skill provides safe rollback operations with comprehensive validation and USER section preservation.

## Usage

```bash
bunx forge rollback
```

Interactive menu with 6 options:
1. **Rollback last commit** - Quick undo of most recent change
2. **Rollback specific commit** - Target any commit by hash
3. **Rollback merged PR** - Revert an entire PR merge
4. **Rollback specific files** - Restore only certain files
5. **Rollback entire branch** - Revert multiple commits
6. **Preview rollback** - Dry run mode (shows changes without executing)

## How It Works

### Safety Features

**1. Working Directory Check**
- Requires clean working directory (no uncommitted changes)
- Prevents accidental data loss
- Prompts to commit or stash changes first

**2. Input Validation**
- Commit hashes: Must match `/^[0-9a-f]{4,40}$/i` or be 'HEAD'
- File paths: Validated to be within project (prevents path traversal)
- Methods: Whitelisted to 'commit', 'pr', 'partial', 'branch'
- Shell metacharacters: Rejected (`;`, `|`, `&`, `$`, `` ` ``, `(`, `)`, `<`, `>`, `\n`, `\r`)

**3. USER Section Preservation**
- Automatically extracts USER sections before rollback
- Restores USER sections after rollback
- Preserves custom commands in `.claude/commands/custom/`
- Amends rollback commit to include restored content

**4. Dry Run Mode**
- Preview affected files without executing
- Shows what would change
- No git operations performed

**5. Non-Destructive**
- Uses `git revert` (creates new commit)
- Never uses `git reset --hard` (destructive)
- Preserves full git history
- Can be undone with another rollback

### USER Section Preservation

**What Gets Preserved**:
```markdown
<!-- USER:START -->
Your custom content here
<!-- USER:END -->

<!-- USER:START:custom-name -->
Named USER section
<!-- USER:END:custom-name -->
```

**Process**:
1. Extract all USER sections from AGENTS.md, CLAUDE.md, etc.
2. Backup custom commands from `.claude/commands/custom/`
3. Execute rollback operation
4. Restore USER sections to current file content
5. Restore custom command files
6. Amend rollback commit to include restored content

**Result**: Your customizations survive rollback operations.

## Rollback methods

Six methods, selected interactively. Full step-by-step walkthroughs (commands,
prompts, expected output) are in [references/methods.md](references/methods.md) —
read it when running a specific rollback.

1. **Rollback last commit** — undo the most recent commit.
2. **Rollback specific commit** — revert one commit by hash.
3. **Rollback merged PR** — revert a merge commit.
4. **Rollback specific files** — restore named files from the previous commit.
5. **Rollback entire branch** — reset a range.
6. **Preview (dry run)** — show what a rollback would do, change nothing.

## Integration, issue status & troubleshooting

When to reach for rollback, how it fits the workflow, how revert state is recorded,
and error recovery are in
[references/workflow-integration.md](references/workflow-integration.md).