1---
2name: managing-and-navigating-worktrees
3description: Manages git worktrees and repos using the wt CLI. Use when cloning or creating new repos, adding worktrees, switching branches or branches, when the user mentions wt or worktrees. If you need to clone and whether to use worktrees/this skill is unclear, ask the user.
4compatibility: Requires wt CLI, git, and gum
5license: GPL-3.0-or-later
6metadata:
7 author: Amolith <amolith@secluded.site>
8---
9
10# Managing Git Worktrees with wt
11
12`wt` manages git repositories using a bare repository structure:
13
14- `.bare/` contains the actual git repository
15- `.git` is a file pointing to `.bare/`
16- Each branch lives in its own directory as sibling worktrees
17
18## Quick Reference
19
20| Command | Purpose |
21| --------------- | --------------------------------------- |
22| `wt c <url>` | Clone repo into bare structure |
23| `wt n <name>` | Create new project |
24| `wt a <branch>` | Add worktree for branch |
25| `wt r <branch>` | Remove worktree |
26| `wt l` | List worktrees with status |
27| `wt f` | Fetch all remotes |
28| `wt init` | Convert existing repo to bare structure |
29
30## Common Workflows
31
32### Start a new project
33
34```bash
35wt n my-project --remote github
36cd my-project/main
37```
38
39### Clone and start working
40
41```bash
42wt c https://github.com/user/repo.git
43cd repo/main
44```
45
46### Create feature branch
47
48From inside any worktree:
49
50```bash
51wt a feature/new-thing -b main
52cd ../feature/new-thing
53```
54
55### Switch between branches
56
57Just `cd` to the worktree directory—no checkout needed:
58
59```bash
60cd ../main # switch to main
61cd ../feature/x # switch to feature branch
62```
63
64If the branch already exists in a remote, but doesn't yet have a local worktree, use `wt a branch` to fetch and create it.
65
66### Clean up finished work
67
68```bash
69wt r feature/old -b # remove worktree AND delete branch
70```
71
72### Convert existing repo
73
74```bash
75cd existing-repo
76wt init # --dry-run to preview, -y to skip prompt
77```
78
79## Command Details
80
81- **New project**: See [refs/new-project.md](refs/new-project.md) for remote templates
82- **Cloning**: See [refs/cloning.md](refs/cloning.md) for remote configuration and own vs contributor mode
83- **Adding worktrees**: See [refs/adding.md](refs/adding.md) for hooks and branch creation
84- **Converting repos**: See [refs/converting.md](refs/converting.md) for `wt init` details
85- **Config files**: See [refs/config.md](refs/config.md) for `.wt.lua` and global config
86
87If you lack context, READ THESE instead of immediately trying to use `wt` or relying on `-h` output. The refs might just give you the answer without you needing to fumble and find them.
88
89## Working Directory
90
91`wt` works from either the project root or any worktree. Run `wt l` to determine context:
92
93- **In a worktree**: Current worktree shows `./` in the Path column
94- **At project root**: All paths are relative names (e.g., `main`, `feature/foo`)
95
96From project root, `wt a` skips hooks. From a worktree, hooks trigger.
97
98## Key Behaviors
99
1001. **Hooks only trigger from worktrees**: Running `wt a` from project root skips hooks
1012. **Branch paths**: `feature/foo` becomes `project/feature/foo` (nested) or `project_feature_foo` (flat, if configured)
102
103---
104
105See [refs/installation.md](refs/installation.md) if you try to use `wt` and it's not available. Do not reference this file until and unless you invoke `wt` and get some kind of command not found error.