Skip to content

Commit 660a122

Browse files
jorgensandhaugclaude
authored and
Test User
committed
feat: wt-cli v1.0.0 - Git worktree management CLI
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
0 parents  commit 660a122

17 files changed

Lines changed: 1975 additions & 0 deletions

‎.github/workflows/test.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: Tests
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
runs-on: ${{ matrix.os }}
12+
strategy:
13+
matrix:
14+
os: [ubuntu-latest, macos-latest]
15+
16+
steps:
17+
- uses: actions/checkout@v4
18+
19+
- name: Install dependencies (Ubuntu)
20+
if: runner.os == 'Linux'
21+
run: sudo apt-get update && sudo apt-get install -y jq
22+
23+
- name: Install dependencies (macOS)
24+
if: runner.os == 'macOS'
25+
run: brew install jq
26+
27+
- name: Configure git
28+
run: |
29+
git config --global init.defaultBranch main
30+
git config --global user.email "test@test.com"
31+
git config --global user.name "Test User"
32+
33+
- name: Run tests
34+
run: bash tests/test_runner.sh

‎CHANGELOG.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.0.0] - 2025-01-06
9+
10+
### Added
11+
- Initial release
12+
- `wt new <branch>` - Create new worktree with new branch
13+
- `wt new -b <branch>` - Create worktree from existing branch (auto-fetches)
14+
- `wt new -p <pr>` - Create worktree from GitHub PR (requires gh CLI)
15+
- `wt new -u <branch>` - Create worktree and run 'up' commands
16+
- `wt ls` - List worktrees with colored status indicators
17+
- `wt cd [name]` - Change directory to worktree (main if no name)
18+
- `wt up` - Spin up dev environment (run 'up' commands from config)
19+
- `wt down` - Spin down dev environment (run 'down' commands from config)
20+
- `wt rm [-f] [name]` - Remove worktree (current if no name given)
21+
- `wt purge` - Interactive cleanup of merged worktrees
22+
- `wt prune` - Clean stale worktree references
23+
- `wt config` - Show config file path
24+
- `wt update` - Self-update from GitHub
25+
- `wt version` - Show version
26+
- Support for project-specific scripts via `.cursor/worktrees.json`:
27+
- `setup-worktree`: runs on worktree creation
28+
- `up`: runs with `wt up` or `wt new -u`
29+
- `down`: runs with `wt down`
30+
- `cleanup-worktree`: runs before worktree removal
31+
- Colored output with NO_COLOR support
32+
- Unknown command error message with help
33+
- One-line installer: `curl -sSL ... | bash`

‎CLAUDE.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# wt-cli Development Guide
2+
3+
## Overview
4+
5+
Git worktree management CLI. Single file shell script (`wt.sh`) that works in bash/zsh.
6+
7+
## Testing
8+
9+
```bash
10+
# Run full test suite (33 tests)
11+
bash tests/test_runner.sh
12+
13+
# Manual testing - use the dummy repo
14+
cd /Users/jorgensandhaug/Documents/wt-test-dummy
15+
source /Users/jorgensandhaug/Documents/wt-cli/wt.sh
16+
wt new test-branch
17+
wt ls
18+
wt rm test-branch
19+
```
20+
21+
22+
## Directory Structure
23+
24+
Worktrees are created at `../.worktrees/reponame/branchname/`:
25+
```
26+
parent/
27+
myrepo/
28+
.worktrees/
29+
myrepo/
30+
feature-x/
31+
bugfix/auth/
32+
```
33+
34+
## Key Functions in wt.sh
35+
36+
- `_wt_new()` - Creates worktrees, handles -b (existing branch), -p (PR), -u (run up commands)
37+
- `_wt_find_worktree()` - Resolves worktree name or path to full path
38+
- `_wt_get_status()` - Single git command for dirty/unpushed check (performance optimized)
39+
- `_wt_ls()` - Lists worktrees with status
40+
- `_wt_rm()` - Removes worktree with safety checks
41+
42+
## Shell Quirks
43+
44+
zsh has issues with `local` variable declaration in pipelines. Use:
45+
```bash
46+
local var=""
47+
var="$(command)"
48+
```
49+
50+
Not:
51+
```bash
52+
local var="$(command)" # Can leak debug output in zsh
53+
```
54+
55+
## After Making Changes
56+
57+
1. Run tests: `bash tests/test_runner.sh`
58+
2. Test manually in dummy repo
59+
3. Update local install: `cp wt.sh ~/.wt/wt.sh`
60+
61+
## Style
62+
63+
- Keep documentation clean and professional
64+
- No unnecessary comments in code
65+
- No tab completion (Warp terminal overrides it)
66+
- Status indicators: `[ok]`, `[dirty]`, `[unpushed]`

‎CONTRIBUTING.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Contributing to wt-cli
2+
3+
Thank you for your interest in contributing to wt-cli!
4+
5+
## Development Setup
6+
7+
1. Clone the repository:
8+
```bash
9+
git clone https://github.com/jorgensandhaug/wt-cli.git
10+
cd wt-cli
11+
```
12+
13+
2. Source the script for local development:
14+
```bash
15+
source ./wt.sh
16+
```
17+
18+
3. Run tests:
19+
```bash
20+
bash tests/test_runner.sh
21+
```
22+
23+
## Making Changes
24+
25+
1. Create a feature branch:
26+
```bash
27+
git checkout -b feature/your-feature
28+
```
29+
30+
2. Make your changes to `wt.sh`
31+
32+
3. Add tests in `tests/test_*.sh`
33+
34+
4. Run the test suite to verify:
35+
```bash
36+
bash tests/test_runner.sh
37+
```
38+
39+
5. Test in both bash and zsh if possible
40+
41+
## Code Style
42+
43+
- Use `_wt_` prefix for internal functions
44+
- Use lowercase with underscores for variable names
45+
- Avoid zsh reserved words as variable names (`status`, `path`, etc.)
46+
- Support both bash and zsh
47+
- Respect `NO_COLOR` environment variable
48+
49+
## Pull Request Process
50+
51+
1. Update documentation if adding features
52+
2. Add tests for new functionality
53+
3. Ensure all tests pass
54+
4. Update CHANGELOG.md with your changes
55+
56+
## Reporting Issues
57+
58+
When reporting issues, please include:
59+
- Your shell (bash/zsh) and version
60+
- Your OS (macOS/Linux)
61+
- Steps to reproduce
62+
- Expected vs actual behavior

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Jorgen Sandhaug
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# wt-cli
2+
3+
Git worktree management CLI with colored status and Claude integration.
4+
5+
[![Tests](https://github.com/jorgensandhaug/wt-cli/actions/workflows/test.yml/badge.svg)](https://github.com/jorgensandhaug/wt-cli/actions/workflows/test.yml)
6+
7+
## Install
8+
9+
```bash
10+
curl -sSL https://raw.githubusercontent.com/jorgensandhaug/wt-cli/main/install.sh | bash
11+
```
12+
13+
### Requirements
14+
15+
- `git`
16+
- `jq` (`brew install jq` on macOS, `apt install jq` on Ubuntu)
17+
- bash or zsh
18+
19+
### Uninstall
20+
21+
```bash
22+
curl -sSL https://raw.githubusercontent.com/jorgensandhaug/wt-cli/main/uninstall.sh | bash
23+
```
24+
25+
## Commands
26+
27+
| Command | Description |
28+
|---------|-------------|
29+
| `wt new <branch>` | Create new worktree with new branch |
30+
| `wt new -b <branch>` | Create worktree from existing branch (auto-fetches) |
31+
| `wt new -p <pr>` | Create worktree from GitHub PR (requires gh CLI) |
32+
| `wt new -u <branch>` | Create worktree and run 'up' commands |
33+
| `wt ls` | List all worktrees with colored status |
34+
| `wt cd [name]` | cd to worktree (main if no name) |
35+
| `wt up` | Spin up dev environment (run 'up' commands) |
36+
| `wt down` | Spin down dev environment (run 'down' commands) |
37+
| `wt rm [name]` | Remove worktree (current if no name given) |
38+
| `wt rm -f [name]` | Force remove (ignores dirty/unpushed warnings) |
39+
| `wt purge` | Interactive cleanup of clean worktrees |
40+
| `wt prune` | Clean stale worktree references |
41+
| `wt config` | Show config file path |
42+
| `wt update` | Self-update to latest version |
43+
| `wt version` | Show version |
44+
45+
## Directory Structure
46+
47+
```
48+
parent/
49+
myrepo/
50+
.worktrees/
51+
myrepo/
52+
feature-x/
53+
bugfix/login/
54+
```
55+
56+
## Status Indicators
57+
58+
`wt ls` shows status:
59+
60+
- `[ok]` - Clean and pushed
61+
- `[unpushed]` - Has unpushed commits
62+
- `[dirty]` - Has uncommitted changes
63+
64+
## Configuration
65+
66+
### User Config
67+
68+
`~/.config/wt/config.json`:
69+
70+
```json
71+
{
72+
"command": "claude --dangerously-skip-permissions"
73+
}
74+
```
75+
76+
The `command` runs after creating a new worktree.
77+
78+
### Project Config
79+
80+
`.cursor/worktrees.json`:
81+
82+
```json
83+
{
84+
"setup-worktree": ["npm install", "cp .env.example .env"],
85+
"up": ["docker-compose up -d", "npm run dev &"],
86+
"down": ["docker-compose down"],
87+
"cleanup-worktree": ["rm -rf node_modules"]
88+
}
89+
```
90+
91+
- `setup-worktree`: Runs after creating worktree (always)
92+
- `up`: Runs with `wt up` or `wt new -u` (spin up services)
93+
- `down`: Runs with `wt down` (spin down services)
94+
- `cleanup-worktree`: Runs before removing worktree (always)
95+
96+
See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for details.
97+
98+
## Example Workflow
99+
100+
```bash
101+
# Start a new feature
102+
wt new auth-refactor
103+
104+
# Start a feature and spin up dev environment
105+
wt new -u auth-refactor
106+
107+
# Work on an existing remote branch
108+
wt new -b origin/feature-api
109+
110+
# Review a PR
111+
wt new -p 123
112+
113+
# See all worktrees
114+
wt ls
115+
116+
# Switch worktrees
117+
wt cd feature-api
118+
119+
# Go back to main
120+
wt cd
121+
122+
# Spin up dev environment
123+
wt up
124+
125+
# Spin down dev environment
126+
wt down
127+
128+
# Done with feature - remove current worktree
129+
wt rm
130+
131+
# Clean up all finished worktrees
132+
wt purge
133+
134+
# Update wt-cli
135+
wt update
136+
```
137+
138+
See [docs/EXAMPLES.md](docs/EXAMPLES.md) for more examples.
139+
140+
## Contributing
141+
142+
See [CONTRIBUTING.md](CONTRIBUTING.md).
143+
144+
## License
145+
146+
[MIT](LICENSE)

0 commit comments

Comments
 (0)