git-workspace-init

name	git-workspace-init
description	Initialize a new git worktree and branch for feature development or bug fixes. Use when: (1) Starting work on a new feature, (2) Beginning a bug fix, (3) Creating an isolated workspace for any task, (4) You want to work in parallel on multiple branches. This skill handles branch naming with conventional branch conventions, worktree creation, and remote push setup.

Git Workspace Init

Initialize an isolated git worktree with a properly named branch following conventional branch naming conventions.

When to Use

• Starting a new feature
• Beginning a bug fix
• Creating a hotfix
• Documentation updates
• Refactoring work
• Any task needing an isolated workspace

Prerequisites

• Git repository with a remote configured
• Write access to push branches

Workflow Overview

1. Get task details → Ask for type and description (or accept from command)
2. Generate branch name → Apply conventional branch naming
3. Create worktree → Set up isolated workspace
4. Push to remote → Track branch on origin
5. Navigate → Switch to new workspace

Step 1: Gather Task Information

Ask the user for or accept from command arguments:

Task Type

Type	Use Case	Example
feat	New feature	feat/user-authentication
fix	Bug fix	fix/login-validation-error
hotfix	Urgent production fix	hotfix/security-patch
docs	Documentation	docs/api-reference
refactor	Code restructuring	refactor/extract-service
test	Test additions	test/auth-integration
chore	Maintenance	chore/upgrade-dependencies
perf	Performance improvement	perf/optimize-queries
ci	CI/CD changes	ci/add-deploy-workflow
style	Code style/formatting	style/apply-prettier

Task Description

A brief description that will become the branch name suffix:

• Use lowercase
• Use hyphens for spaces
• Keep it concise but descriptive

Examples:

• "user authentication" → user-authentication
• "fix validation error" → validation-error
• "add dark mode" → dark-mode

Step 2: Generate Branch Name

Format: <type>/<description>

# Examples
feat/user-authentication
fix/null-pointer-exception
hotfix/xss-vulnerability
docs/installation-guide
refactor/extract-user-service

Naming Rules

1. Lowercase only - feat/Add-User → feat/add-user
2. Hyphens for spaces - fix/login error → fix/login-error
3. No special characters - Only a-z, 0-9, -, /
4. Concise - Keep under 50 characters total
5. Descriptive - Should indicate the work being done

Helper Function

import re

def generate_branch_name(task_type: str, description: str) -> str:
    """Generate conventional branch name from type and description."""
    valid_types = ["feat", "fix", "hotfix", "docs", "refactor", "test", "chore", "perf", "ci", "style"]

    if task_type not in valid_types:
        raise ValueError(f"Invalid type '{task_type}'. Must be one of: {', '.join(valid_types)}")

    # Normalize description
    normalized = description.lower().strip()
    # Replace spaces and underscores with hyphens
    normalized = re.sub(r'[\s_]+', '-', normalized)
    # Remove invalid characters
    normalized = re.sub(r'[^a-z0-9-]', '', normalized)
    # Remove consecutive hyphens
    normalized = re.sub(r'-+', '-', normalized)
    # Trim hyphens from ends
    normalized = normalized.strip('-')

    return f"{task_type}/{normalized}"

Step 3: Create Git Worktree

Worktrees allow working on multiple branches simultaneously without stashing or switching.

Default Worktree Location

Worktrees are created in a .worktrees directory at the repository root:

my-project/
├── .worktrees/
│   ├── feat-user-auth/      # Worktree for feat/user-auth
│   └── fix-login-error/     # Worktree for fix/login-error
├── src/
└── ...

Create Worktree Commands

# Get repository root
REPO_ROOT=$(git rev-parse --show-toplevel)

# Define worktree directory (replace / with - for directory name)
BRANCH_NAME="feat/user-authentication"
WORKTREE_DIR="$REPO_ROOT/.worktrees/${BRANCH_NAME//\//-}"

# Ensure .worktrees directory exists
mkdir -p "$REPO_ROOT/.worktrees"

# Create worktree with new branch from main/master
git worktree add -b "$BRANCH_NAME" "$WORKTREE_DIR" origin/main

Workflow

import subprocess
import os

def create_worktree(branch_name: str, base_branch: str = "main") -> str:
    """Create a new worktree for the given branch."""
    # Get repo root
    result = subprocess.run(
        ["git", "rev-parse", "--show-toplevel"],
        capture_output=True, text=True, check=True
    )
    repo_root = result.stdout.strip()

    # Create worktree directory name (replace / with -)
    worktree_dir_name = branch_name.replace("/", "-")
    worktree_path = os.path.join(repo_root, ".worktrees", worktree_dir_name)

    # Ensure .worktrees directory exists
    os.makedirs(os.path.join(repo_root, ".worktrees"), exist_ok=True)

    # Fetch latest from remote
    subprocess.run(["git", "fetch", "origin"], check=True)

    # Create worktree with new branch
    subprocess.run(
        ["git", "worktree", "add", "-b", branch_name, worktree_path, f"origin/{base_branch}"],
        check=True
    )

    return worktree_path

Step 4: Push Branch to Remote

Set up tracking with the remote repository:

# From within the new worktree
cd "$WORKTREE_DIR"

# Push and set upstream
git push -u origin "$BRANCH_NAME"

Workflow

def push_branch(worktree_path: str, branch_name: str):
    """Push the new branch to remote with tracking."""
    subprocess.run(
        ["git", "-C", worktree_path, "push", "-u", "origin", branch_name],
        check=True
    )

Step 5: Navigate to Workspace

After creation, navigate to the new worktree:

cd "$WORKTREE_DIR"
pwd
git status

Important: Inform the user of the new workspace path so they can navigate there in their terminal.

Complete Example

import subprocess
import os
import re

def generate_branch_name(task_type: str, description: str) -> str:
    """Generate conventional branch name."""
    valid_types = ["feat", "fix", "hotfix", "docs", "refactor", "test", "chore", "perf", "ci", "style"]

    if task_type not in valid_types:
        raise ValueError(f"Invalid type. Must be one of: {', '.join(valid_types)}")

    normalized = description.lower().strip()
    normalized = re.sub(r'[\s_]+', '-', normalized)
    normalized = re.sub(r'[^a-z0-9-]', '', normalized)
    normalized = re.sub(r'-+', '-', normalized)
    normalized = normalized.strip('-')

    return f"{task_type}/{normalized}"


def init_workspace(task_type: str, description: str, base_branch: str = "main") -> dict:
    """
    Initialize a new git worktree with conventional branch naming.

    Args:
        task_type: Type of work (feat, fix, hotfix, docs, refactor, test, chore, perf, ci, style)
        description: Brief description of the task
        base_branch: Branch to base the new branch on (default: main)

    Returns:
        dict with branch_name, worktree_path, and success status
    """
    
    branch_name = generate_branch_name(task_type, description)
    ()

    
    result = subprocess.run(
        [, , ],
        capture_output=, text=, check=
    )
    repo_root = result.stdout.strip()

    
    worktree_dir_name = branch_name.replace(, )
    worktree_path = os.path.join(repo_root, , worktree_dir_name)

    
    os.makedirs(os.path.join(repo_root, ), exist_ok=)

    
    ()
    subprocess.run([, , ], check=)

    
    ()
    subprocess.run(
        [, , , , branch_name, worktree_path, ],
        check=
    )

    
    ()
    subprocess.run(
        [, , worktree_path, , , , branch_name],
        check=
    )

    
    ()
    ()
    ()
    ()
    ()

     {
        : branch_name,
        : worktree_path,
        : 
    }

Quick Reference

Branch Type Cheat Sheet

Type	When to Use
feat	Adding new functionality
fix	Fixing a bug
hotfix	Urgent production fix
docs	Documentation only
refactor	Restructuring without behavior change
test	Adding or fixing tests
chore	Build, deps, tooling
perf	Performance improvements
ci	CI/CD pipeline changes
style	Formatting, whitespace

Worktree Commands

# List all worktrees
git worktree list

# Remove a worktree (when done)
git worktree remove <path>

# Prune stale worktrees
git worktree prune

Cleanup After Merge

After your PR is merged:

# Remove the worktree
git worktree remove .worktrees/feat-user-authentication

# Delete the local branch (if not auto-deleted)
git branch -d feat/user-authentication

# Prune remote tracking branches
git fetch --prune

Error Handling

Branch Already Exists

fatal: A branch named 'feat/user-auth' already exists.

Solution: Choose a more specific name or check if work is already in progress.

Worktree Path Already Exists

fatal: '<path>' already exists

Solution: The worktree already exists. Use git worktree list to find it.

No Remote Configured

fatal: No configured push destination.

Solution: Add a remote first: git remote add origin <url>