blocklet-branch

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

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "blocklet-branch" with this command: npx skills add arcblock/agent-skills/arcblock-agent-skills-blocklet-branch

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"

  1. 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"

  1. 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 -

  1. 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

  1. 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

  1. 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

  1. 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

  1. Usage Scenarios

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

  • Detect main iteration branch

  • Handle uncommitted changes

  • Switch to main iteration branch and update

  • (Optional) Create working branch

Scenario B: Submit PR (blocklet-pr)

  • Detect main iteration branch

  • Detect branch naming conventions

  • Check current branch

  • If on main iteration branch → Must create working branch

  • If on working branch → Check naming convention compliance

Scenario C: Switch Tasks

  • Handle uncommitted changes (stash/commit/discard)

  • Switch to target branch

  • Restore previous changes (if needed)

  1. 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

  1. 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

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

Automation

simple-skills-manager

No summary provided by upstream source.

Repository SourceNeeds Review
8-arcblock
Automation

pull-request

No summary provided by upstream source.

Repository SourceNeeds Review
7-arcblock
Automation

diff-review-doc

No summary provided by upstream source.

Repository SourceNeeds Review
4-arcblock
Automation

interview-writer

No summary provided by upstream source.

Repository SourceNeeds Review
4-arcblock