Development Branch Completion

A git workflow skill for managing the complete lifecycle of development branches from creation through merge, including rebasing, conflict resolution, PR preparation, and post-merge cleanup.

When to Use

Choose Development Branch Completion when:

• Completing a feature branch and preparing it for merge to main
• Resolving merge conflicts during branch rebasing
• Preparing clean commit history before creating a pull request
• Managing the post-merge cleanup of branches and references

Consider alternatives when:

• Starting a new feature — use branch creation workflows
• Reviewing others' PRs — use code review tools
• Managing releases — use release management workflows

Quick Start

Copy
# Complete branch workflow
# 1. Ensure branch is up to date
git fetch origin
git rebase origin/main

# 2. Clean up commit history
git rebase -i origin/main  # Squash/reword commits

# 3. Verify everything works
npm test && npm run lint && npm run typecheck

# 4. Push and create PR
git push origin feature-branch -u
gh pr create --fill

Copy
#!/bin/bash
# branch-complete.sh - Automated branch completion workflow

set -euo pipefail

BRANCH=$(git branch --show-current)
BASE_BRANCH=${1:-main}

echo "=== Completing branch: $BRANCH ==="

# Step 1: Fetch and rebase
echo "Step 1: Rebasing onto $BASE_BRANCH..."
git fetch origin
if ! git rebase "origin/$BASE_BRANCH"; then
    echo "Rebase conflicts detected. Resolve conflicts, then run:"
    echo "  git rebase --continue"
    echo "  ./branch-complete.sh"
    exit 1
fi

# Step 2: Run quality checks
echo "Step 2: Running quality checks..."
if [ -f "package.json" ]; then
    npm run typecheck 2>/dev/null || echo "Typecheck: skipped"
    npm run lint 2>/dev/null || echo "Lint: skipped"
    npm test -- --run 2>/dev/null || echo "Tests: skipped"
fi

# Step 3: Check commit count
COMMITS=$(git log --oneline "origin/$BASE_BRANCH..HEAD" | wc -l | tr -d ' ')
echo "Step 3: Branch has $COMMITS commits"

if [ "$COMMITS" -gt 10 ]; then
    echo "Consider squashing some commits (current: $COMMITS)"
fi

# Step 4: Push
echo "Step 4: Pushing to origin..."
git push origin "$BRANCH" --force-with-lease -u

# Step 5: Create or update PR
echo "Step 5: Checking PR status..."
PR_URL=$(gh pr view --json url -q '.url' 2>/dev/null || echo "")

if [ -z "$PR_URL" ]; then
    echo "Creating new PR..."
    gh pr create --fill --base "$BASE_BRANCH"
else
    echo "PR already exists: $PR_URL"
fi

echo "=== Branch completion done ==="

Core Concepts

Branch Lifecycle

Phase	Actions	Commands
Create	Branch from main, set upstream	git checkout -b feature
Develop	Commit changes, push regularly	git commit, git push
Sync	Rebase on updated main	git rebase origin/main
Clean	Squash/reword commits	git rebase -i
Review	Create PR, address feedback	gh pr create
Complete	Merge PR, delete branch	gh pr merge, cleanup

Conflict Resolution Strategy

Copy
# Safe rebase with conflict tracking
git rebase origin/main 2>&1 | tee /tmp/rebase-output.txt

if grep -q "CONFLICT" /tmp/rebase-output.txt; then
    echo "Conflicts found in:"
    git diff --name-only --diff-filter=U

    # Show conflict details for each file
    for file in $(git diff --name-only --diff-filter=U); do
        echo "=== $file ==="
        grep -n "^<<<<<<" "$file" | head -5
    done

    echo ""
    echo "Resolution options:"
    echo "  1. Edit files to resolve, then: git add . && git rebase --continue"
    echo "  2. Accept ours: git checkout --ours <file> && git add <file>"
    echo "  3. Accept theirs: git checkout --theirs <file> && git add <file>"
    echo "  4. Abort: git rebase --abort"
fi

Configuration

Option	Description	Default
base_branch	Default branch to merge into	"main"
squash_commits	Auto-squash before PR	false
run_checks	Run lint/test before push	true
force_push_method	Force push: lease, force, none	"lease"
delete_after_merge	Delete branch after PR merge	true
create_pr	Auto-create PR on push	true
pr_template	PR description template path	".github/pull_request_template.md"
max_commit_count	Warn if commits exceed this	10

Best Practices

1. Always use --force-with-lease instead of --force when pushing after a rebase — it prevents overwriting commits that someone else pushed to the same branch while you were rebasing
2. Rebase onto main before creating a PR to ensure your changes apply cleanly on top of the latest main branch and to surface any conflicts before the PR review begins
3. Keep the commit history meaningful by squashing WIP, fixup, and typo-fix commits before the PR, but preserve logically separate changes as distinct commits for reviewability
4. Run the full test suite locally before pushing the final branch to catch issues before CI — failed CI checks slow down the review process and waste CI resources
5. Delete branches after merge both locally and on the remote to keep the repository clean; stale branches accumulate and make it harder to find active work

Common Issues

Force push overwriting teammate's changes: When multiple people work on a branch, force pushing after rebase can overwrite their commits. Use --force-with-lease which fails if the remote has commits you have not seen, and coordinate with teammates before rebasing shared branches.

Rebase conflicts on every sync: Frequently conflicting files indicate the branch has diverged significantly from main. Merge more frequently in smaller increments, break large features into multiple smaller PRs, or consider merging main into the branch temporarily while keeping the branch focused.

Lost commits after interactive rebase: Accidentally dropping commits during interactive rebase seems permanent but is recoverable. Use git reflog to find the pre-rebase commit hash, then git reset --hard to that hash to restore the original state.