blocklet-branch

name	blocklet-branch
description	Git branch management tool. Detects main iteration branch and branch naming conventions, handles branch creation and switching. Referenced by blocklet-dev-setup, blocklet-pr, and other skills.

Blocklet Branch

Unified Git branch management tool providing branch detection, creation, and switching capabilities.

Core Philosophy

"Detect dynamically, never assume."

Branch management must not hardcode main or master. Different ArcBlock repositories follow different branch conventions. By analyzing PR history dynamically, branch operations adapt to each repository automatically.

Design Principles

• Never assume the main branch is main or master; detect dynamically through merged PR history
• Learn branch naming conventions from project history
• Must handle uncommitted changes before switching branches

---

1. Repository Information Retrieval

1.1 Parse Remote Repository

REMOTE_URL=$(git remote get-url origin)

# Parse org/repo
ORG=$(echo $REMOTE_URL | sed -E 's/.*[:/]([^/]+)\/([^/]+)(\.git)?$/\1/')
REPO=$(echo $REMOTE_URL | sed -E 's/.*[:/]([^/]+)\/([^/]+)(\.git)?$/\2/' | sed 's/\.git$//')

echo "Repository: $ORG/$REPO"

1.2 Get Current Branch

CURRENT_BRANCH=$(git branch --show-current)
echo "Current branch: $CURRENT_BRANCH"

---

2. Main Iteration Branch Detection

Important: Must determine the main iteration branch by analyzing the last 10 merged PRs, rather than simply assuming it is main or master.

2.1 Detect Main Iteration Branch

# Get target branches of the last 10 merged PRs, count occurrences to find the main iteration branch
MAIN_BRANCH=$(gh pr list --repo $ORG/$REPO --state merged --limit 10 --json baseRefName \
  | jq -r '.[].baseRefName' | sort | uniq -c | sort -rn | head -1 | awk '{print $2}')

# Get detection rationale
BRANCH_STATS=$(gh pr list --repo $ORG/$REPO --state merged --limit 10 --json baseRefName \
  | jq -r '.[].baseRefName' | sort | uniq -c | sort -rn)

echo "Main iteration branch: $MAIN_BRANCH"
echo "Detection rationale (target branch statistics from last 10 merged PRs):"
echo "$BRANCH_STATS"

2.2 Output Variables

Variable	Description	Example
MAIN_BRANCH	Detected main iteration branch	main, develop, master
MAIN_BRANCH_REASON	Detection rationale	"8 out of 10 recent merged PRs targeted main"

---

3. Branch Naming Convention Detection

Important: Determine branch naming prefix conventions by analyzing the last 10 merged PRs.

3.1 Analyze Historical Branch Naming

# Get source branch names from the last 10 merged PRs, analyze naming conventions
BRANCH_NAMES=$(gh pr list --repo $ORG/$REPO --state merged --limit 10 --json headRefName \
  | jq -r '.[].headRefName')

# Extract prefixes (supports both / and - separators)
BRANCH_PREFIXES=$(echo "$BRANCH_NAMES" | sed -E 's/^([a-zA-Z]+)[\/\-].*/\1/' | sort | uniq -c | sort -rn)

echo "Branch naming prefix statistics (from last 10 merged PRs):"
echo "$BRANCH_PREFIXES"

# Detect separator style (/ or -)
if echo "$BRANCH_NAMES" | grep -q '/'; then
    SEPARATOR="/"
else
    SEPARATOR="-"
fi
echo "Separator style: $SEPARATOR"

3.2 Common Branch Prefixes

Prefix	Purpose	Example
feat / feature	New feature	feat/add-login, feature/user-profile
fix / bugfix	Bug fix	fix/login-error, bugfix/issue-123
chore	Routine maintenance	chore/update-deps
refactor	Code refactoring	refactor/auth-module
docs	Documentation update	docs/api-guide
test	Test-related	test/add-unit-tests
style	Code style	style/format-code
perf	Performance optimization	perf/optimize-query

3.3 Output Variables

Variable	Description	Example
BRANCH_PREFIX_CONVENTION	Primary prefix convention	feat, fix
BRANCH_SEPARATOR	Separator style	/ or -

---

4. Uncommitted Changes Handling

Important: Before switching branches, uncommitted changes must be handled first.

4.1 Check Change Status

UNCOMMITTED_CHANGES=$(git status --porcelain)

if [ -n "$UNCOMMITTED_CHANGES" ]; then
    echo "⚠️ Uncommitted changes detected:"
    git status --short
fi

4.2 Handle Changes

If there are uncommitted changes, use AskUserQuestion to ask the user:

Uncommitted changes detected. Please choose how to proceed:

Options:
A. Stash changes (git stash) - can be restored later (Recommended)
B. Commit changes - create a temporary commit
C. Discard changes (git checkout .) - ⚠️ cannot be undone
D. Cancel operation

Execute handling:

# Option A: Stash
git stash push -m "Auto stash before branch switch"

# Option B: Commit
git add -A && git commit -m "WIP: auto commit before branch switch"

# Option C: Discard
git checkout . && git clean -fd

---

5. Branch Switching

5.1 Switch to Main Iteration Branch

# Ensure local has latest remote branch info
git fetch origin

# Switch to main iteration branch and update
git checkout $MAIN_BRANCH
git pull origin $MAIN_BRANCH

echo "✅ Switched to main iteration branch: $MAIN_BRANCH"

5.2 Switch to Specified Branch

TARGET_BRANCH="feat/my-feature"

# Check if branch exists
if git show-ref --verify --quiet refs/heads/$TARGET_BRANCH; then
    # Local branch exists
    git checkout $TARGET_BRANCH
elif git show-ref --verify --quiet refs/remotes/origin/$TARGET_BRANCH; then
    # Remote branch exists, create local tracking branch
    git checkout -b $TARGET_BRANCH origin/$TARGET_BRANCH
else
    echo "❌ Branch $TARGET_BRANCH does not exist"
fi

---

6. Working Branch Creation

6.1 Generate Branch Name Suggestion

Generate suggested branch name based on task type and repository naming conventions:

# Input parameters
TASK_TYPE="fix"           # feat, fix, chore, refactor, docs, test
TASK_DESCRIPTION="login"  # Brief description
ISSUE_NUMBER=""           # Optional issue number

# Generate branch name
if [ -n "$ISSUE_NUMBER" ]; then
    SUGGESTED_BRANCH="${TASK_TYPE}${BRANCH_SEPARATOR}issue-${ISSUE_NUMBER}-${TASK_DESCRIPTION}"
else
    SUGGESTED_BRANCH="${TASK_TYPE}${BRANCH_SEPARATOR}${TASK_DESCRIPTION}"
fi

echo "Suggested branch name: $SUGGESTED_BRANCH"

6.2 Create Working Branch

Prerequisite: Must be created based on the latest main iteration branch.

# 1. Ensure main iteration branch is up to date
git fetch origin $MAIN_BRANCH
git checkout $MAIN_BRANCH
git pull origin $MAIN_BRANCH

# 2. Create and switch to new branch
NEW_BRANCH="feat/my-new-feature"
git checkout -b $NEW_BRANCH

echo "✅ Created and switched to branch: $NEW_BRANCH (based on $MAIN_BRANCH)"

6.3 User Confirmation Flow

Use AskUserQuestion to confirm branch name:

Will create new branch based on {MAIN_BRANCH}.

Please select branch name:

Options:
A. {SUGGESTED_BRANCH} (Recommended)
B. Enter custom branch name
C. Cancel operation

---

7. Branch Status Check

7.1 Check If on Main Iteration Branch

if [ "$CURRENT_BRANCH" = "$MAIN_BRANCH" ]; then
    echo "⚠️ Currently on main iteration branch"
    ON_MAIN_BRANCH=true
else
    ON_MAIN_BRANCH=false
fi

7.2 Check Branch Naming Convention Compliance

# Check if branch name follows common prefix conventions
if echo "$CURRENT_BRANCH" | grep -qE "^(feat|fix|chore|refactor|docs|test|style|perf|hotfix|release)[/\-]"; then
    echo "✅ Branch naming follows convention"
    BRANCH_NAME_VALID=true
else
    echo "⚠️ Branch naming does not follow common conventions: $CURRENT_BRANCH"
    BRANCH_NAME_VALID=false
fi

7.3 Check Branch Sync Status with Remote

# Get local and remote differences
git fetch origin

LOCAL_COMMIT=$(git rev-parse HEAD)
REMOTE_COMMIT=$(git rev-parse origin/$CURRENT_BRANCH 2>/dev/null || echo "")

if [ -z "$REMOTE_COMMIT" ]; then
    echo "📤 Branch not yet pushed to remote"
    SYNC_STATUS="not_pushed"
elif [ "$LOCAL_COMMIT" = "$REMOTE_COMMIT" ]; then
    echo "✅ Branch is in sync with remote"
    SYNC_STATUS="synced"
else
    AHEAD=$(git rev-list origin/$CURRENT_BRANCH..HEAD --count)
    BEHIND=$(git rev-list HEAD..origin/$CURRENT_BRANCH --count)
    echo "📊 Local is $AHEAD commits ahead, $BEHIND commits behind"
    SYNC_STATUS="diverged"
fi

---

8. Usage Scenarios

Scenario A: Development Environment Setup (blocklet-dev-setup)

1. Detect main iteration branch
2. Handle uncommitted changes
3. Switch to main iteration branch and update
4. (Optional) Create working branch

Scenario B: Submit PR (blocklet-pr)

1. Detect main iteration branch
2. Detect branch naming conventions
3. Check current branch
   • If on main iteration branch → Must create working branch
   • If on working branch → Check naming convention compliance

Scenario C: Switch Tasks

1. Handle uncommitted changes (stash/commit/discard)
2. Switch to target branch
3. Restore previous changes (if needed)

---

9. Referenced by Other Skills

This skill is referenced by the following skills:

Skill	Features Used
blocklet-dev-setup	Detect main iteration branch, handle uncommitted changes, switch branches, create working branch
blocklet-pr	Detect main iteration branch, branch naming conventions, enforce working branch creation

How to reference:

Refer to blocklet-branch skill for branch operations.
Skill location: `blocklet-branch/SKILL.md`

---

10. Error Handling

Error	Cause	Solution
Cannot get PR history	gh not authenticated or network issue	Run gh auth status to check authentication
Branch switch failed	Conflicting uncommitted changes	Handle uncommitted changes first
Branch creation failed	Branch name already exists	Use different branch name or switch to existing branch
Cannot detect main iteration branch	Repository has no merged PRs	Fall back to default branch gh repo view --json defaultBranchRef