https://github.com/raghavpillai/branchlet
Branchlet: A simple CLI Git worktree manager
https://github.com/raghavpillai/branchlet
claude-code codegen cursor git vibe-coding worktrees
Last synced: about 2 months ago
JSON representation
Branchlet: A simple CLI Git worktree manager
- Host: GitHub
- URL: https://github.com/raghavpillai/branchlet
- Owner: raghavpillai
- License: mit
- Created: 2025-08-20T21:52:26.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2025-08-22T04:03:27.000Z (2 months ago)
- Last Synced: 2025-08-22T04:32:29.476Z (2 months ago)
- Topics: claude-code, codegen, cursor, git, vibe-coding, worktrees
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/branchlet
- Size: 259 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome - raghavpillai/branchlet - Branchlet: A simple CLI Git worktree manager (TypeScript)
README
# 🌳 Branchlet
[](https://www.npmjs.com/package/branchlet)
[](https://www.npmjs.com/package/branchlet)
A interactive CLI tool for creating and managing Git worktrees with an easy to use interface.
## Features
- **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
## Installation
```bash
npm install -g branchlet
```
## Quick Start
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
## Commands
### Interactive Menu (Default)
```bash
branchlet
```
Opens the main menu with all available options.
### Direct Commands
```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
```
### Options
```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)
### Configuration Options
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 ."
}
```
#### 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 ."`
### 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**
```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
### Project-Specific Configuration
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 ."
}
```
## Requirements
- Node.js 18.0.0 or higher
- Git installed and available in PATH
- Operating system: macOS, Linux, or Windows
## License
MIT