BranchCraft 🌳

Automatically create git worktrees from GitHub issue webhooks. Each issue gets its own isolated workspace!

What is BranchCraft?

BranchCraft is a lightweight Python utility that integrates with GitHub webhooks to automatically create git worktrees whenever a new issue is opened. This allows developers to work on multiple issues simultaneously without the hassle of switching branches in their main repository.

Features

• 🎯 Automatic Worktree Creation: Creates a new git worktree for each GitHub issue
• 🏷️ Smart Branch Naming: Generates branches like 123-fix-login-bug from issue numbers and titles
• 📁 Organized Structure: Keeps worktrees in a clean issues/{org/repo}/{branch} structure
• 🚀 Zero Dependencies: Uses only Python standard library
• 🔄 Webhook Integration: Works seamlessly with GitHub webhook events

Installation

1. Clone this repository:

git clone https://github.com/clidecoder/branchcraft.git
cd branchcraft

2. Make the script executable:

chmod +x branchcraft.py

Usage

Manual Usage

Run BranchCraft with a GitHub webhook payload:

python branchcraft.py '{"action":"opened","issue":{"number":123,"title":"Fix login bug"},"repository":{"full_name":"myorg/myapp","name":"myapp"}}'

This will:

1. Clone the repository (if not already present)
2. Create a new branch: 123-fix-login-bug
3. Create a worktree at: issues/myorg/myapp/123-fix-login-bug/

GitHub Webhook Integration

1. Set up a webhook in your GitHub repository settings
2. Point it to your webhook handler endpoint
3. Configure it to trigger on "Issues" events
4. Have your webhook handler execute BranchCraft with the payload

Example webhook handler (Flask):

from flask import Flask, request
import subprocess
import json

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    payload = request.json
    if payload.get('action') == 'opened' and 'issue' in payload:
        subprocess.run(['python', 'branchcraft.py', json.dumps(payload)])
    return '', 200

Directory Structure

your-workspace/
├── myorg/
│   └── myapp/              # Main repository
└── issues/
    └── myorg/
        └── myapp/
            ├── 123-fix-login-bug/      # Worktree for issue #123
            ├── 124-add-user-profile/   # Worktree for issue #124
            └── 125-update-docs/        # Worktree for issue #125

How It Works

1. Webhook Reception: GitHub sends a webhook when an issue is opened
2. Branch Creation: BranchCraft creates a branch name from the issue number and title
3. Repository Setup: Clones the repository if needed
4. Worktree Creation: Creates a new git worktree for the issue branch
5. Ready to Code: Developer can immediately start working in the isolated worktree

Requirements

• Python 3.6+
• Git command-line tool
• Access to the repository you want to create worktrees for

Benefits

• Parallel Development: Work on multiple issues without branch switching
• Clean Workspace: Each issue has its own isolated environment
• Fast Context Switching: Jump between issues instantly
• Automatic Setup: No manual branch creation or cloning needed

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Author

Created with ❤️ for developers who juggle multiple issues

---