CLI for creating and managing Git worktrees
npm install branchlet

A interactive CLI tool for creating and managing Git worktrees with an easy to use interface.
- Quick Commands: Jump directly to specific actions via command line
- 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
``bash`
npm install -g branchlet
Run Branchlet in any Git repository:
`bash`
branchlet
This opens an interactive menu where you can:
- Create new worktrees
- List existing worktrees
- Delete worktrees
- Configure settings
bash
branchlet
`
Opens the main menu with all available options.$3
`bash
branchlet create # Go directly to worktree creation
branchlet list # List all worktrees
branchlet delete # Go directly to worktree deletion
branchlet settings # Open settings menu
`$3
`bash
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)$3
Create a
.branchlet.json file in your project root or configure global settings:`json
{
"worktreeCopyPatterns": [".env", ".vscode/*"],
"worktreeCopyIgnores": ["/node_modules/", "/dist/", "/.git/"],
"worktreePathTemplate": "$BASE_PATH.worktree",
"postCreateCmd": ["npm install", "npm run db:generate"],
"terminalCommand": "code .",
"deleteBranchWithWorktree": 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$3
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 branchUsage Examples
$3
1. Navigate to your Git repository
`bash
cd my-project
`2. Start Branchlet
`bash
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$3
Create
.branchlet.json in your project:`json
{
"worktreeCopyPatterns": [
".env.local",
".vscode/**",
"package.json",
"tsconfig.json"
],
"worktreePathTemplate": "worktrees/$BRANCH_NAME",
"postCreateCmd": [
"npm install",
"npm run db:populate"
],
"terminalCommand": "code .",
"deleteBranchWithWorktree": true
}
``- Node.js 20.0.0 or higher
- Git installed and available in PATH
- Operating system: macOS, Linux, or Windows
MIT