gh-dhofheinz-open-plugins-plugins-git-commit-assistant/commands/commit-best-practices/revert-guidance.md

# Operation: Commit Revert Guidance

Guide users through safely reverting commits with proper formatting and workflow.

## Parameters from $ARGUMENTS

- **commit** (required): Commit SHA to revert

Parse as: `revert-guidance commit:abc123`

## Revert Workflow

### Step 1: Validate Commit

Verify commit exists and get details:

```bash
# Check if commit exists
if ! git rev-parse --verify ${commit} >/dev/null 2>&1; then
    ERROR: "Commit not found: ${commit}"
    exit 1
fi

# Get commit details
commit_sha=$(git rev-parse ${commit})
commit_subject=$(git log -1 --format='%s' ${commit_sha})
commit_author=$(git log -1 --format='%an <%ae>' ${commit_sha})
commit_date=$(git log -1 --format='%ad' ${commit_sha})
```

### Step 2: Run Revert Helper Script

Generate proper revert commit message:

```bash
./.claude/commands/commit-best-practices/.scripts/revert-helper.sh "${commit_sha}"
```

Returns:
```json
{
  "commit": "abc123...",
  "original_message": "feat(auth): add OAuth authentication",
  "revert_message": "revert: feat(auth): add OAuth authentication\n\nThis reverts commit abc123.\n\nReason: OAuth implementation incompatible with current auth system",
  "type": "feat",
  "scope": "auth",
  "files_affected": 5,
  "safe_to_revert": true,
  "warnings": []
}
```

### Step 3: Analyze Revert Safety

Check if revert will cause issues:

**Safe to revert:**
```
✅ Safe to revert

Commit: abc123
Original: feat(auth): add OAuth authentication
Author: John Doe
Date: 2025-10-10

Analysis:
  ✅ No dependent commits found
  ✅ No merge conflicts expected
  ✅ Files still exist
  ✅ Clean revert possible

This commit can be safely reverted.
```

**Potential issues:**
```
⚠️  Revert with caution

Commit: abc123
Original: feat(auth): add OAuth authentication
Author: John Doe
Date: 2025-10-10

Warnings:
  ⚠️  3 commits depend on this change
      - def456: feat(auth): add OAuth providers
      - ghi789: fix(auth): OAuth token refresh
      - jkl012: docs: OAuth setup guide

  ⚠️  Potential merge conflicts
      - src/auth/oauth.js: modified in later commits
      - src/config/auth.js: modified in later commits

Reverting will require:
  1. Resolving merge conflicts
  2. Possibly reverting dependent commits first
  3. Updating or removing affected features

Consider: Revert dependent commits in reverse order.
```

### Step 4: Generate Revert Message

Follow proper revert commit message format:

```
Conventional Commits Revert Format:
-----------------------------------
revert: <original-type>(<original-scope>): <original-subject>

This reverts commit <sha>.

Reason: <explanation-of-why>

[Optional: Additional context]
[Optional: BREAKING CHANGE if revert breaks functionality]
[Optional: Issue references]

Example:
-----------------------------------
revert: feat(auth): add OAuth authentication

This reverts commit abc123def456789.

Reason: OAuth implementation incompatible with existing SAML
authentication system. Caused authentication failures for
enterprise users.

Need to redesign OAuth to work alongside SAML before
reintroducing.

BREAKING CHANGE: OAuth authentication temporarily removed.
Users must use username/password authentication.

Refs: #456
```

### Step 5: Provide Revert Instructions

**Simple revert (no conflicts):**

```
How to Revert Commit
====================

Commit to revert: abc123
Original message: feat(auth): add OAuth authentication

Generated revert message:
---
revert: feat(auth): add OAuth authentication

This reverts commit abc123.

Reason: [Provide reason here]
---

Option 1: Auto-revert with Git (Recommended)
---------------------------------------------
git revert abc123

This will:
  1. Create revert commit automatically
  2. Open editor for message (pre-filled)
  3. Add reason for revert
  4. Save and close

Option 2: Manual revert
-----------------------
1. git revert --no-commit abc123
2. Review changes: git diff --cached
3. Adjust if needed
4. git commit (use message above)

After reverting:
----------------
1. Test that functionality is restored
2. Verify no broken dependencies
3. Push: git push origin <branch>

The revert commit preserves history while undoing changes.
```

**Complex revert (conflicts or dependencies):**

```
Complex Revert Required
=======================

Commit to revert: abc123
Original: feat(auth): add OAuth authentication
Dependencies: 3 commits depend on this

Revert Strategy:
----------------

Step 1: Revert dependent commits FIRST (newest to oldest)
  git revert jkl012  # docs: OAuth setup guide
  git revert ghi789  # fix(auth): OAuth token refresh
  git revert def456  # feat(auth): add OAuth providers

Step 2: Revert original commit
  git revert abc123  # feat(auth): add OAuth authentication

Step 3: Handle conflicts
  If conflicts occur:
    1. git status (see conflicted files)
    2. Edit files to resolve conflicts
    3. git add <resolved-files>
    4. git revert --continue

Step 4: Test thoroughly
  - Run full test suite
  - Verify auth system works
  - Check for broken functionality

Alternative: Revert in single commit
-------------------------------------
If you want one revert commit for all:

1. git revert --no-commit jkl012
2. git revert --no-commit ghi789
3. git revert --no-commit def456
4. git revert --no-commit abc123
5. Resolve any conflicts
6. git commit -m "revert: OAuth authentication feature

This reverts commits abc123, def456, ghi789, jkl012.

Reason: OAuth incompatible with SAML system."

This creates a single revert commit for multiple changes.
```

### Step 6: Post-Revert Checklist

After reverting, verify:

```
Post-Revert Checklist
=====================

□ Revert commit created successfully
  git log -1 (verify revert commit exists)

□ Changes actually reverted
  git diff <commit>^..<commit> (should be inverse of original)

□ Tests pass
  npm test (or your test command)

□ No broken functionality
  Test affected features manually

□ Documentation updated
  Update docs if feature was documented

□ Team notified
  Inform team of revert and reason

□ Issue tracker updated
  Comment on related issues

□ Ready to push
  git push origin <branch>
```

## Revert vs Reset vs Amend

**Use `git revert` when:**
- ✅ Commit already pushed to remote
- ✅ Working on shared branch
- ✅ Need to preserve history
- ✅ Undoing specific commit in middle of history

**Use `git reset` when:**
- ⚠️ Commit not yet pushed (local only)
- ⚠️ Want to completely remove commit
- ⚠️ Rewriting personal branch history
- ⚠️ No one else has the commit

**Use `git commit --amend` when:**
- ⚠️ Fixing most recent commit only
- ⚠️ Commit not yet pushed
- ⚠️ Small typo or forgotten file

**Decision tree:**
```
Has commit been pushed?
├─ Yes → Use git revert (safe for shared history)
└─ No → Is it the most recent commit?
    ├─ Yes → Use git commit --amend (if minor fix)
    └─ No → Use git reset (if complete removal needed)
```

## Revert Message Examples

**Example 1: Bug found**
```
revert: fix(api): add null check in user endpoint

This reverts commit abc123.

Reason: Fix introduced regression causing authentication
failures for legacy clients. Null check logic incorrect.

Will reimplement with proper validation after adding tests.

Fixes: #789
```

**Example 2: Performance issue**
```
revert: perf(search): implement new search algorithm

This reverts commit def456.

Reason: New algorithm causes 300% increase in database
load under production traffic. Needs optimization before
redeployment.

Keeping old algorithm until performance issues resolved.
```

**Example 3: Breaking change**
```
revert: feat(api): change authentication endpoint format

This reverts commit ghi789.

Reason: Breaking change deployed without proper migration
period. Mobile app version 1.x incompatible with new format.

BREAKING CHANGE: Reverting API format to v1 for backwards
compatibility. Will reintroduce in v2 with migration path.

Refs: #234, #235, #236 (user reports)
```

## Output Format

```
Revert Guidance Report
======================

Commit to Revert: <sha>
Original Message: <message>
Author: <name>
Date: <date>

REVERT SAFETY:
  [✅|⚠️] No dependent commits
  [✅|⚠️] No merge conflicts expected
  [✅|⚠️] Files still exist

GENERATED REVERT MESSAGE:
---
<revert-message-content>
---

REVERT INSTRUCTIONS:
[Step-by-step instructions]

POST-REVERT CHECKLIST:
[Verification steps]
```

## Error Handling

**Commit not found:**
```
ERROR: Commit not found: abc123
Check: git log (to see available commits)
Verify: Commit hash is correct (7+ characters)
```

**Already reverted:**
```
WARNING: This commit may already be reverted

Found revert commit: xyz789
Message: "revert: feat(auth): add OAuth authentication"

If this is a duplicate revert, it may cause issues.
Check: git log (to verify)
```

**Merge commit:**
```
WARNING: This is a merge commit

Merge commits require special handling:
git revert -m 1 abc123

-m 1: Keep changes from first parent
-m 2: Keep changes from second parent

Determine which parent to keep based on your branch strategy.
```

## Integration with Agent

When user says "revert my commit" or "undo commit abc123":
1. Agent identifies commit to revert
2. Runs safety analysis
3. Generates proper revert message
4. Provides step-by-step instructions
5. Offers post-revert verification checklist

## Best Practices

1. **Always provide reason**: Explain WHY reverting in message
2. **Reference original commit**: Include SHA in revert message
3. **Test after revert**: Ensure functionality restored
4. **Notify team**: Communicate reverts to collaborators
5. **Update issues**: Comment on related issue tracker items
6. **Preserve history**: Use revert, not reset, for shared branches

Proper reverts maintain clear history and facilitate collaboration.