wt-core 0.1.0

Portable Git worktree lifecycle manager
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

# wt-core

Portable Git worktree lifecycle manager — a Rust CLI core with thin shell bindings for **Nushell**, **Bash**, **Zsh**, and **Fish**.

## Why

Git worktrees are powerful but clunky. `wt-core` gives you a fast, consistent interface for creating, navigating, listing, and removing worktrees across every shell you use — without duplicating logic per shell.

All worktree/branch operations live in a single Rust binary. Shell bindings handle only what a subprocess can't: `cd` in the parent shell.

## Commands

```
wt add <branch> [--base <rev>]   Create a worktree and branch
wt go <branch>                   Switch to an existing worktree
wt list                          List all worktrees
wt remove [<branch>] [--force]   Remove a worktree and its local branch
wt doctor                        Diagnose worktree/repo health
```

## Path Convention

Worktrees are placed under `<repo>/.worktrees/` with collision-safe directory names:

```
<slug>--<8hex>
```

Example: branch `feature/auth` → `.worktrees/feature-auth--a1b2c3d4/`

## Output Modes

| Flag              | Behavior                                     |
|-------------------|----------------------------------------------|
| *(default)*       | Human-readable text                          |
| `--json`          | Structured JSON envelope on stdout           |
| `--print-cd-path` | Bare absolute path on stdout (for wrappers)  |

JSON envelope:

```json
{
  "ok": true,
  "message": "created worktree",
  "repo_root": "/abs/repo",
  "worktree_path": "/abs/repo/.worktrees/feature-auth--a1b2c3d4",
  "cd_path": "/abs/repo/.worktrees/feature-auth--a1b2c3d4"
}
```

## Exit Codes

| Code | Meaning                                           |
|------|---------------------------------------------------|
| 0    | Success                                           |
| 1    | Usage / argument error                            |
| 2    | Git invocation error                              |
| 3    | Not a git repository / repo resolution failure    |
| 4    | Invariant violation (e.g. removing main worktree) |
| 5    | State conflict (dirty tree, branch exists, etc.)  |

## Shell Integration

Each binding wraps the binary and handles `cd` in the parent shell.

You can either source files from `bindings/` directly, or generate them with
`wt-core init <shell>`.

<details>
<summary><strong>Nushell</strong></summary>

```bash
wt-core init nu > ~/.config/nushell/wt.nu
```

```nu
# ~/.config/nushell/config.nu
source ~/.config/nushell/wt.nu
```
</details>

<details>
<summary><strong>Bash</strong></summary>

```bash
wt-core init bash > ~/.config/wt/wt.bash
echo 'source ~/.config/wt/wt.bash' >> ~/.bashrc
```
</details>

<details>
<summary><strong>Zsh</strong></summary>

```zsh
wt-core init zsh > ~/.config/wt/wt.zsh
echo 'source ~/.config/wt/wt.zsh' >> ~/.zshrc
```
</details>

<details>
<summary><strong>Fish</strong></summary>

```fish
wt-core init fish > ~/.config/fish/conf.d/wt.fish
```
</details>

## Install

```bash
cargo install --path .
```

Then source the appropriate shell binding.

## Compatibility

| Dependency | Minimum Version |
|------------|-----------------|
| Git        | 2.39            |
| Rust       | stable (MSRV pinned in `Cargo.toml`) |
| Nushell    | 0.109           |
| Bash       | 4.4             |
| Zsh        | 5.8             |
| Fish       | 3.6             |

## License

[MIT](LICENSE)