166 lines
5.2 KiB
Markdown
166 lines
5.2 KiB
Markdown
---
|
|
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.
|