🌳 Branchlet

An interactive CLI tool for creating and managing Git worktrees with an easy to use interface.

Features

• Interactive TUI: Full terminal UI with searchable/filterable branch picker
• Non-Interactive CLI: Script worktree operations with --name, --source, --branch flags
• Remote Branch Support: Browse and create worktrees from remote-only branches
• Custom Refs: Use any SHA, tag, or ref as a source for new worktrees
• Smart Configuration: Project-specific and global configuration support
• File Management: Automatically copy configuration files to new worktrees
• Post-Create Actions: Run custom commands after worktree creation

Installation

npm install -g @ntindle/branchlet

Quick Start

Run Branchlet in any Git repository:

branchlet

This opens an interactive menu where you can:

• Create new worktrees
• List existing worktrees
• Delete worktrees
• Configure settings

Commands

Interactive Menu (Default)

branchlet

Opens the main menu with all available options.

Direct Commands

branchlet create    # Go directly to worktree creation
branchlet list      # List all worktrees
branchlet delete    # Go directly to worktree deletion
branchlet settings  # Open settings menu

Non-Interactive CLI

# Create a worktree (outputs the path on success)
branchlet create --name my-feature --source main --branch feat/my-feature

# Create from a remote branch
branchlet create -n hotfix -s origin/release/2.0 -b fix/bug-123

# List worktrees as JSON
branchlet list --json

# Delete a worktree by name
branchlet delete --name my-feature
branchlet delete --name my-feature --force

# Delete by path
branchlet delete --path /absolute/path/to/worktree

Options

branchlet --help     # Show help information
branchlet --version  # Show version number
branchlet -m create  # Set initial mode

Configuration

Branchlet looks for configuration files in this order:

1. .branchlet.json in your repo's root (project-specific)
2. ~/.branchlet/settings.json (global configuration)

Schema Validation

Add $schema to your .branchlet.json for autocompletion and validation in VSCode:

{
  "$schema": "https://raw.githubusercontent.com/ntindle/branchlet/main/schema.json",
  "postCreateCmd": ["npm install"]
}

Configuration Options

Create a .branchlet.json file in your project root or configure global settings:

{
  "worktreeCopyPatterns": [".env*", ".vscode/**"],
  "worktreeCopyIgnores": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
  "worktreePathTemplate": "$BASE_PATH.worktree",
  "postCreateCmd": ["npm install", "npm run db:generate"],
  "terminalCommand": "code .",
  "deleteBranchWithWorktree": true,
  "showRemoteBranches": true
}

Configuration Fields

• worktreeCopyPatterns: Files/directories to copy to new worktrees (supports glob patterns)

  • Default: [".env*", ".vscode/**"]
  • Examples: ["*.json", "config/**", ".env.local"]

• worktreeCopyIgnores: Files/directories to exclude when copying (supports glob patterns)

  • Default: ["**/node_modules/**", "**/dist/**", "**/.git/**", "**/Thumbs.db", "**/.DS_Store"]

• worktreePathTemplate: Template for worktree directory names

  • Default: "$BASE_PATH.worktree"
  • Variables: $BASE_PATH, $WORKTREE_PATH, $BRANCH_NAME, $SOURCE_BRANCH
  • Examples: "worktrees/$BRANCH_NAME", "$BASE_PATH-branches/$BRANCH_NAME"

• postCreateCmd: Commands to run after creating a worktree. Runs in the new worktree directory.

  • Default: []
  • Examples: ["npm install"], ["pnpm install", "pnpm build"]
  • Variables supported in commands: $BASE_PATH, $WORKTREE_PATH, $BRANCH_NAME, $SOURCE_BRANCH

• terminalCommand: Command to open terminal/editor in the new worktree. Runs in the new worktree directory.

  • Default: ""
  • Examples: "code .", "cursor .", "zed ."

• deleteBranchWithWorktree: Whether to also delete the associated git branch when deleting a worktree

  • Default: false
  • When enabled, deleting a worktree will also delete its branch (with safety checks)
  • Shows warnings for branches with unpushed commits or uncommitted changes

• showRemoteBranches: Show remote-only branches in the source branch picker

  • Default: true
  • Remote branches that already have a local counterpart are deduplicated

Template Variables

Available in worktreePathTemplate, postCreateCmd, and terminalCommand:

• $BASE_PATH: Base name of your repository
• $WORKTREE_PATH: Full path to the new worktree
• $BRANCH_NAME: Name of the new branch
• $SOURCE_BRANCH: Name of the source branch

Usage Examples

Basic Workflow

1. Navigate to your Git repository

   cd my-project

2. Start Branchlet

   branchlet

3. Create a worktree

   • Select "Create new worktree"
   • Enter directory name (e.g., feature-auth)
   • Choose source branch (e.g., main)
   • Enter new branch name (e.g., feature/authentication)
   • Confirm creation

Project-Specific Configuration

Create .branchlet.json in your project:

{
  "worktreeCopyPatterns": [
    ".env.local",
    ".vscode/**",
    "package.json",
    "tsconfig.json"
  ],
  "worktreePathTemplate": "worktrees/$BRANCH_NAME",
  "postCreateCmd": [
    "npm install",
    "npm run db:populate"
  ],
  "terminalCommand": "code .",
  "deleteBranchWithWorktree": true
}

Requirements

• Node.js 20.0.0 or higher
• Git installed and available in PATH
• Operating system: macOS, Linux, or Windows

License

MIT