1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# wt
8
9[](https://api.reuse.software/info/git.secluded.site/wt)
10[](https://liberapay.com/Amolith/)
11
12Git worktree manager using a bare repository pattern. Clone once, check
13out many.
14
15## tl;dr
16
17```
18wt c git@git.host:user/project.git # Clone into bare structure
19cd project/{canonical-branch}
20wt a feature/auth -b # Create worktree + branch
21cd ../feaTABTAB # Use cd + shell completions
22 # to navigate branches
23wt l # List worktrees
24wt r feature/auth -b # Remove worktree + branch
25```
26
27## Features
28
29- **Templated remote automation** — configure URL templates, select remotes on
30 clone, supports both contributing and own-project workflows
31- **Hooks** — copy files, create symlinks, run commands when adding worktrees
32- **Optional path styles** — nested (`feature/auth`) or flat (`feature_auth`)
33 worktree paths, schemes like `847-do-a-thing` work just fine too
34- **Bare repo structure** where `.bare/` holds the repository and worktrees live
35 as sibling directories
36- **Convert existing repos** — `wt init` migrates a normal clone to bare
37 structure
38
39## Installation
40
41Requires Lua 5.2 or later and
42[gum](https://github.com/charmbracelet/gum) for interactive prompts
43
44```
45curl -o ~/.local/bin/wt https://git.secluded.site/wt/blob/main/dist/wt?raw=1
46chmod +x ~/.local/bin/wt
47```
48
49## Usage
50
51### Commands
52
53| Command | Description |
54| --- | --- |
55| `wt c <url> [--remote name]... [--own]` | Clone into bare worktree structure |
56| `wt n <name> [--remote name]...` | Initialize fresh project |
57| `wt a <branch> [-b [<start-point>]]` | Add worktree, optionally create branch |
58| `wt r <branch> [-b] [-f]` | Remove worktree, optionally delete branch |
59| `wt l` | List worktrees with status |
60| `wt f` | Fetch all remotes |
61| `wt init [--dry-run] [-y]` | Convert existing repo to bare structure |
62
63### Clone workflows
64
65**Contributing to others' projects:**
66
67```
68wt c https://github.com/org/repo.git
69# origin → upstream, your remotes added from config
70```
71
72**Your own projects:**
73
74```
75wt c git@github.com:you/repo.git --own
76# First configured remote becomes origin
77```
78
79### Adding worktrees
80
81From inside an existing worktree, hooks from `.wt.lua` run automatically:
82
83```
84cd project/main
85wt a feature/new-thing -b # New branch from current HEAD
86wt a bugfix/issue-123 -b origin/main # New branch from specific start point
87wt a existing-branch # Checkout existing branch
88```
89
90## Configuration
91
92### Global config (`~/.config/wt/config.lua`)
93
94```lua
95return {
96 branch_path_style = "nested", -- or "flat"
97 flat_separator = "_", -- separator for flat style
98
99 remotes = {
100 github = "git@github.com:myuser/${project}.git",
101 gitlab = "git@gitlab.com:myuser/${project}.git",
102 },
103
104 default_remotes = "prompt", -- or {"github", "gitlab"}
105}
106```
107
108### Project config (`.wt.lua` in project root)
109
110```lua
111return {
112 hooks = {
113 copy = {".env.example", "Makefile.local"},
114 symlink = {".env", "node_modules"},
115 run = {"make setup", "npm install"},
116 }
117}
118```
119
120Hooks only run when `wt a` is executed from inside an existing worktree.
121You'll be prompted once per project to allow hooks; permissions are stored in
122`~/.local/share/wt/hook-dirs.lua`.
123
124## Contributions
125
126Patch requests are in
127[amolith/catchall](https://pr.pico.sh/r/amolith/catchall) on
128[pr.pico.sh](https://pr.pico.sh). You don't need a new account to
129contribute, you don't need to fork this repo, you don't need to fiddle
130with `git send-email`, you don't need to faff with your email client to
131get `git request-pull` working...
132
133You just need:
134
135- Git
136- SSH
137- An SSH key
138
139```
140# Clone this repo, make your changes, and commit them
141# Create a new patch request with
142git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/catchall
143# After potential feedback, submit a revision to an existing patch request with
144git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
145# List patch requests
146ssh pr.pico.sh pr ls amolith/catchall
147```
148
149See "How do Patch Requests work?" on [pr.pico.sh](https://pr.pico.sh)'s home
150page for a more complete example workflow.
151
152---
153
154Some other tools if this one interested you
155
156- [agent-skills](https://git.secluded.site/agent-skills) - collection of Agent Skills for extending LLM capabilities
157- [garble](https://git.secluded.site/garble) - transform stdin with an LLM (fix typos, translate, reformat)
158- [formatted-commit](https://git.secluded.site/formatted-commit) - CLI that turns LLM input into well-formatted Conventional Commits