---
name: step-finish
description: Finalize branch - tag, merge back, cleanup
next_step: null
---

# Step: FINISH - Finalize Branch

## YOUR TASK:

Create tags for releases/hotfixes, merge back to develop, clean up worktree and branch.

**ULTRA THINK about version tagging.**

---

## EXECUTION SEQUENCE:

### 1. Load Config and Determine Branch Context

```bash
# Load GitFlow config (sets GF_* variables)
read_gitflow_config || { echo "❌ Run /gitflow init first."; exit 1; }

# Get current or specified branch
BRANCH=${1:-$(git rev-parse --abbrev-ref HEAD)}
BRANCH_TYPE=$(echo $BRANCH | cut -d'/' -f1)
BRANCH_NAME=$(echo $BRANCH | cut -d'/' -f2)

# Validate branch type
case "$BRANCH_TYPE" in
  feature|release|hotfix) ;;
  $GF_MAIN_BRANCH|$GF_DEVELOP_BRANCH)
    echo "❌ Cannot finish $GF_MAIN_BRANCH or $GF_DEVELOP_BRANCH branch"
    STOP
    ;;
  *)
    echo "❌ Unknown branch type: $BRANCH_TYPE"
    STOP
    ;;
esac
```

### 2. Verify Merge Status

```bash
git fetch origin

# Check if branch was merged
case "$BRANCH_TYPE" in
  feature)
    MERGED=$(git branch -r --merged origin/$GF_DEVELOP_BRANCH | grep "$BRANCH" | wc -l)
    TARGET="$GF_DEVELOP_BRANCH"
    ;;
  release|hotfix)
    MERGED=$(git branch -r --merged origin/$GF_MAIN_BRANCH | grep "$BRANCH" | wc -l)
    TARGET="$GF_MAIN_BRANCH"
    ;;
esac

[ "$MERGED" -eq 0 ] && {
  echo "⚠️ Branch $BRANCH not yet merged to $TARGET"
  echo "→ Run /gitflow merge first"

  if [ "$auto_mode" != true ]; then
    AskUserQuestion:
      header: "Continue"
      question: "Branch not merged. Continue anyway?"
      options:
        - label: "No, merge first"
        - label: "Yes, finish anyway"
  fi
}
```

### 3-4. Create Tag and Merge Back to Develop

**For release/hotfix only:**
- Create annotated tag on main branch (format: v{VERSION})
- Merge main back to develop with merge commit
- Handle merge conflicts
- Push and verify sync

### 5. Update Version (Release and Hotfix)

See [references/finish-version-bumping.md](../references/finish-version-bumping.md) for:
- Version increment logic (release: minor+1.0, hotfix: patch+2)
- Config and source file updates
- Push verification

### 6-8. Clean Up Worktree, Delete Branches, Archive Plan

See [references/finish-cleanup.md](../references/finish-cleanup.md) for:
- Worktree removal with fallback
- Remote and local branch deletion
- Plan file archival

### 9. Summary

```
╔══════════════════════════════════════════════════════════════════╗
║                    BRANCH FINALIZED                               ║
╠══════════════════════════════════════════════════════════════════╣
║  Branch: {BRANCH}                                                 ║
║  Type:   {BRANCH_TYPE}                                            ║
╠══════════════════════════════════════════════════════════════════╣
║  Actions:                                                         ║
{if release or hotfix}
║  ✅ Tag created: {TAG_NAME}                                       ║
║  ✅ Merged back to develop                                        ║
{endif}
{if release}
║  ✅ Version bumped to {NEXT_VERSION}                              ║
{endif}
║  ✅ Worktree removed                                              ║
║  ✅ Branch deleted (local + remote)                               ║
╠══════════════════════════════════════════════════════════════════╣
║  Current branch: {main|develop}                                   ║
╠══════════════════════════════════════════════════════════════════╣
║  Ready for next: /gitflow start feature <name>                    ║
╚══════════════════════════════════════════════════════════════════╝
```

---

## ERROR HANDLING:

| Error | Solution |
|-------|----------|
| Branch not merged | Merge first or force finish |
| Tag exists | Overwrite or use different version |
| Merge back conflicts | Resolve manually |
| Worktree in use | Exit worktree first |

---

## SUCCESS CRITERIA:

- Tag created (for release/hotfix)
- Merged back to develop (for release/hotfix)
- Worktree removed
- Branch deleted
- Plan archived

## COMPLETION:

GitFlow cycle complete. Ready for next feature/release/hotfix.
