---
name: finalize_branch
description: squashes all commits on current branch, merges to main and deletes current branch
---

# Finalize Branch Skill

This skill is used to finish work on a feature by squashing all commits on the current branch into a single commit, merging it into main, and deleting the feature branch. It includes comprehensive edge case handling.

## Prerequisites

- Git repository initialized
- Commits made on current feature branch
- Current branch is NOT main
- All work is committed (no uncommitted changes)
- Main branch exists

## Pre-Execution Checks

Before proceeding with the finalization workflow, verify these conditions:

### 1. Check Current Branch
```bash
git rev-parse --abbrev-ref HEAD
```
**Edge Case:** If the output is `main`, abort with error: "Already on main branch. Cannot finalize main branch."

### 2. Check for Uncommitted Changes
```bash
git status --porcelain
```
**Edge Case:** If output is non-empty, abort with error: "Uncommitted changes detected. Commit or stash changes before finalizing branch."

### 3. Check for Commits to Squash
```bash
git rev-list --count main..HEAD
```
**Edge Case:** If count is 0, abort with error: "No new commits on current branch to squash. Nothing to finalize."

### 4. Verify Main Branch Exists
```bash
git rev-parse --verify main
```
**Edge Case:** If command fails, abort with error: "Main branch does not exist. Cannot merge into non-existent branch."

## Finalization Workflow

### Step 1: Fetch Latest Changes
```bash
git fetch origin
```
**Purpose:** Ensure you have the latest main branch from remote
**Edge Case Handling:** If fetch fails, log warning but continue (local merge may still work)

### Step 2: Check for Merge Conflicts
```bash
git merge-base --is-ancestor main HEAD
```
**Edge Case:** If this returns false, main has commits not in current branch:
- Run: `git rebase origin/main`
- If rebase fails with conflicts, abort and inform: "Rebase conflicts detected. Resolve conflicts manually before retrying finalization."

### Step 3: Squash All Commits
```bash
git reset --soft main
```
**Purpose:** Moves all changes to staging area, keeping files intact
**Verification:** Run `git status` to confirm all files are staged

### Step 4: Create Squashed Commit
```bash
git commit -m "<commit-message>"
```
**Edge Cases:**
- If commit fails with "nothing to commit", abort: "No changes to commit after squash operation."
- Use descriptive commit message based on branch name or feature implemented

### Step 5: Switch to Main Branch
```bash
git checkout main
```
**Edge Case:** If checkout fails, abort: "Failed to switch to main branch. Branch may be locked or have other issues."

### Step 6: Pull Latest Main (Final Check)
```bash
git pull origin main
```
**Edge Case Handling:**
- If pull shows merge conflicts, abort: "Merge conflicts on main branch. Resolve manually before retrying."
- If pull is already up-to-date, continue normally

### Step 7: Merge Feature Branch
```bash
git merge <feature-branch-name>
```
**Edge Cases:**
- If merge fails with conflicts: 
  - Abort merge: `git merge --abort`
  - Return error: "Merge conflicts detected. Resolve manually and retry finalization."
- If merge fails with other error, abort and investigate

### Step 8: Push to Remote
```bash
git push origin main
```
**Edge Cases:**
- If push is rejected (force pull needed): Abort and inform: "Main branch has remote changes. Run 'git pull origin main' and retry."
- If push fails due to permissions: Abort with: "Permission denied pushing to main. Check git credentials and permissions."

### Step 9: Delete Local Feature Branch
```bash
git branch -d <feature-branch-name>
```
**Edge Case:** If deletion fails (branch not fully merged), use force deletion:
```bash
git branch -D <feature-branch-name>
```
**Warning:** Only force delete if Step 7 merge succeeded.

### Step 10: Delete Remote Feature Branch (if exists)
```bash
git push origin --delete <feature-branch-name>
```
**Edge Cases:**
- If branch doesn't exist on remote, continue normally
- If deletion fails due to permissions, log warning but consider success (local cleanup done)

## Rollback Procedure

If any step fails, execute rollback:

```bash
# Return to feature branch if on main
git checkout <feature-branch-name>

# Reset to pre-squash state if already squashed
git reset --hard <original-commit-before-squash>
```

**Important:** Save the original branch commit SHA before beginning squash operation for rollback capability.

## Success Criteria

✅ All checks passed
✅ Commits squashed into single commit
✅ Feature branch merged into main
✅ New commit pushed to remote
✅ Feature branch deleted locally and remotely
✅ Currently on main branch with latest changes

## Error Handling Summary

| Error | Action |
|-------|--------|
| Already on main | Abort, inform user |
| Uncommitted changes | Abort, instruct commit/stash |
| No commits to squash | Abort, inform no changes |
| Merge conflicts | Abort, instruct manual resolution |
| Push rejected | Abort, pull latest and retry |
| Permission errors | Abort, check git credentials |
| Remote branch missing | Continue (non-fatal) |

## Logging Requirements

Log all executed commands and their outputs for audit trail and debugging purposes.