gwt is a set of Nushell commands for git worktree that return tables and records instead of text. They complete worktree names, branches, and tags. Read-only commands get short aliases, and commands that change worktrees get abbreviations.
> gwt list
╭───┬────────────┬────────────┬─────────┬─────────────┬─────────┬───────┬────────┬──────────╮
│ # │ name │ branch │ head │ committed │ current │ main │ locked │ prunable │
├───┼────────────┼────────────┼─────────┼─────────────┼─────────┼───────┼────────┼──────────┤
│ 0 │ nushell │ main │ 451387b │ 2 days ago │ false │ true │ false │ false │
│ 1 │ 0.116.0 │ │ 8bcb11f │ 3 weeks ago │ false │ false │ false │ false │
│ 2 │ backport │ backport │ 8bcb11f │ 3 weeks ago │ false │ false │ true │ false │
│ 3 │ fix_parser │ fix_parser │ 7d07c61 │ 3 hours ago │ true │ false │ false │ false │
╰───┴────────────┴────────────┴─────────┴─────────────┴─────────┴───────┴────────┴──────────╯Each command passes its arguments to git one at a time, checks git's exit code, and parses git's porcelain output into Nushell values. You filter and pipe the results like any other table:
gwt status | where not clean
gwt list | where not main and committed < ((date now) - 4wk) | gwt remove- Nushell 0.116.2 or newer. The tests pass on 0.117.0. Everything except
gwt prwas also tested on 0.116.2. The abbreviations need 0.113 or newer. - git 2.36 or newer, for
git worktree list --porcelain -z. Tested with git 2.56.gwt add --orphanneeds git 2.42. - The GitHub CLI,
gh, logged in, forgwt pronly. Tested with gh 2.103.
Clone this repository and add one line to config.nu:
use ~/src/nu-git-worktree/gwt.nu *Put that line below any $env.config = { ... } assignment. The module adds its abbreviations to $env.config.abbreviations when it loads, and a later assignment of a whole new $env.config throws them away.
Import it with *. Every command is gwt or gwt <subcommand>, so * can't shadow a builtin such as move. Without *, Nushell prefixes the aliases with the module name, as in gwt gwtl.
| Command | Alias | Abbreviation | Returns |
|---|---|---|---|
gwt list [--long] |
gwtl, gwtll (--long) |
table of worktrees | |
gwt status [...worktrees] |
gwts |
table of upstream, ahead/behind, and change counts | |
gwt pr [--long] [...worktrees] |
gwtpr |
table of each worktree's PR number, state, and URL | |
gwt cd [worktree] [--main] |
gwtcd |
nothing; changes directory | |
gwt add <branch> [path] |
gwta, gwtac (--cd) |
record of the new worktree | |
gwt remove ...worktrees |
gwtrm |
table of removed worktrees | |
gwt move <worktree> <new_path> |
gwtmv |
record of the moved worktree | |
gwt lock <worktree> [--reason] |
gwtlk |
record of the locked worktree | |
gwt unlock <worktree> |
gwtul |
record of the unlocked worktree | |
gwt prune [--dry-run] [--expire] |
gwtp |
table of pruned worktrees | |
gwt repair [...paths] |
table of repairs | ||
gwt |
table of these commands with their aliases and abbreviations |
An alias runs as soon as you press enter. An abbreviation first expands into the full command in the line editor. Aliases and abbreviations explains why each command got the one it did.
help gwt <subcommand> shows each command's flags and examples. gwt on its own lists the commands:
> gwt
╭────┬────────────┬─────────────┬───────────────┬───────────────────────────────────────────────────────────────────────────────────────╮
│ # │ command │ aliases │ abbreviations │ description │
├────┼────────────┼─────────────┼───────────────┼───────────────────────────────────────────────────────────────────────────────────────┤
│ 0 │ gwt add │ │ gwta, gwtac │ Create a worktree for a branch and return its row from `gwt list --long`. │
│ 1 │ gwt cd │ gwtcd │ │ Change to a worktree, picked interactively when none is named. │
│ 2 │ gwt list │ gwtl, gwtll │ │ List the repository's worktrees, main worktree first. │
│ 3 │ gwt lock │ │ gwtlk │ Lock a worktree against prune, move, and remove, and return its updated row. │
│ 4 │ gwt move │ │ gwtmv │ Move a linked worktree to a new directory and return its new row. │
│ 5 │ gwt pr │ gwtpr │ │ Show the GitHub pull request for each worktree's branch. │
│ 6 │ gwt prune │ │ gwtp │ Delete git's records of worktrees whose directories are gone, and return them. │
│ 7 │ gwt remove │ │ gwtrm │ Remove worktrees, optionally deleting their branches, and return what was removed. │
│ 8 │ gwt repair │ │ │ Reconnect worktrees moved by hand, and return each repair git made or could not make. │
│ 9 │ gwt status │ gwts │ │ Show each worktree's branch, upstream, ahead/behind counts, and changes. │
│ 10 │ gwt unlock │ │ gwtul │ Unlock a worktree and return its updated row. │
╰────┴────────────┴─────────────┴───────────────┴───────────────────────────────────────────────────────────────────────────────────────╯Any command that takes a worktree accepts its path, its directory name, or the branch it has checked out. A relative path starts from the current directory. If a name matches more than one worktree, the error lists their paths so you can pick one.
Columns are name, branch, head, committed, current, main, locked, and prunable. branch is null for a detached HEAD, head is the abbreviated commit, committed is its commit date, and current marks the worktree that contains the current directory. The path stays out to keep the table narrow. --long, or the alias gwtll, adds path, commit with the full id, subject, bare, detached, lock_reason, and prune_reason.
gwt list runs three git processes however many worktrees there are: git worktree list --porcelain -z, git rev-parse to find the current worktree, and one git log --no-walk for every HEAD's date and subject.
Runs git status --porcelain=v2 --branch in every worktree in parallel. It passes --no-optional-locks, so a status check never rewrites a worktree's index. It skips bare and prunable worktrees, since they have no files to check.
> gwt status | reject path
╭───┬────────────┬────────────┬───────────────────┬───────┬────────┬────────┬──────────┬───────────┬───────────┬───────╮
│ # │ name │ branch │ upstream │ ahead │ behind │ staged │ modified │ untracked │ conflicts │ clean │
├───┼────────────┼────────────┼───────────────────┼───────┼────────┼────────┼──────────┼───────────┼───────────┼───────┤
│ 0 │ nushell │ main │ origin/main │ 0 │ 0 │ 0 │ 0 │ 0 │ 0 │ true │
│ 1 │ 0.116.0 │ │ │ │ │ 0 │ 0 │ 0 │ 0 │ true │
│ 2 │ backport │ backport │ │ │ │ 0 │ 0 │ 0 │ 0 │ true │
│ 3 │ fix_parser │ fix_parser │ origin/fix_parser │ 1 │ 0 │ 0 │ 1 │ 1 │ 0 │ false │
╰───┴────────────┴────────────┴───────────────────┴───────┴────────┴────────┴──────────┴───────────┴───────────┴───────╯ahead and behind are null for a branch with no upstream.
Asks gh for the pull request of each worktree's branch, all worktrees at once. It searches the repository of the upstream remote, or of origin when there is no upstream. In a fork, with origin as your fork and upstream as the project, that means the project's PRs.
> gwt pr | reject url
╭───┬────────────┬────────────┬───────┬────────╮
│ # │ name │ branch │ pr │ state │
├───┼────────────┼────────────┼───────┼────────┤
│ 0 │ nushell │ main │ │ │
│ 1 │ 0.116.0 │ │ │ │
│ 2 │ backport │ backport │ 19388 │ merged │
│ 3 │ fix_parser │ fix_parser │ 19412 │ draft │
╰───┴────────────┴────────────┴───────┴────────╯Columns are name, branch, pr, state, and url. state is open, draft, closed, or merged. --long adds title, note, and path. A worktree with no PR gets nulls.
A branch matches a PR when the PR's head is one of these:
- the remote branch it tracks, such as
upstream/dependabot/cargo/uuid-1.28.0 - the branch of the same name on
origin, for branches you pushed without setting an upstream
PRs from other forks with the same branch name don't count. A branch named pr<N> or pr<N>_... also matches PR #N, which suits a worktree for reviewing someone else's PR. A branch named like the remote's default branch, usually main, never matches, even when it tracks one.
When a branch has more than one PR, the newest fills the row and note lists the rest. If gh fails for a worktree, that row gets no PR and gwt prints gh's error to stderr, with or without --long. The other worktrees still get their PRs, and --long keeps the error in note.
Pipe the rows into gwt remove to clean up after a merge:
gwt pr | where state == merged | gwt removePlain gwt pr rows have no path, so gwt remove finds each worktree by its name. If two worktrees share a directory name, pipe gwt pr --long instead.
What gwt add checks out depends on branch:
- An existing local branch gets checked out as it is.
- A branch that only a remote has becomes a local branch that tracks it. Write
topicwhen one remote has it, ororigin/topicto pick the remote. - Any other name becomes a new branch, started from
--base, or from HEAD of the worktree you run the command in.
--detach checks out any commit, branch, or tag as a detached HEAD, and --orphan creates an unborn branch. --lock and --reason lock the worktree as git creates it. --cd moves the shell into it.
Without a path, the worktree goes in <root>/<repo>/<branch>. <root> is ~/src/worktrees unless you set $env.GWT_ROOT, and <repo> is the main worktree's directory name. Where the main worktree lives doesn't matter:
| Main worktree | Branch | New worktree |
|---|---|---|
~/src/nushell |
abc |
~/src/worktrees/nushell/abc |
~/src/nushell |
feature/tables |
~/src/worktrees/nushell/feature-tables |
~/work/clients/api |
fix_auth |
~/src/worktrees/api/fix_auth |
A / in the branch name becomes -, which keeps every worktree one directory deep.
To use a different root for every repository, set GWT_ROOT in env.nu or config.nu. A leading ~ works:
$env.GWT_ROOT = '~/worktrees'To put one worktree somewhere else, pass its path as the second argument:
gwt add abc /tmp/abcBefore git touches the disk, gwt add checks a new branch name with git check-ref-format. It rejects --base for a branch that already exists instead of ignoring it. It returns the new worktree's gwt list --long row with one more column, new_branch. More examples:
gwt add backport --base 0.116.0 --cd
gwt add origin/feature
gwt add 0.116.0 --detachTakes worktrees as arguments or as rows from pipeline input, so you can pipe in the output of gwt list, gwt list --long, gwt status, or gwt pr. A row names its worktree by path, or by name when it has no path column, as with plain gwt list. If two worktrees share a directory name, pipe gwt list --long instead so the paths tell them apart.
- git refuses to remove a worktree with modified or untracked files.
--forceoverrides that. - gwt always refuses the main worktree and locked worktrees. git removes a locked worktree when you pass
--forcetwice, but gwt makes you rungwt unlockfirst, so a lock still protects the worktree when you add--forcefor local changes. --delete-branch(-d) also deletes the branch withgit branch -d, which refuses unmerged branches.--force-delete-branch(-D) usesgit branch -D.- If the shell is inside a worktree that gets removed, gwt moves it to the main worktree first.
gwt move follows git worktree move, so when the destination is an existing directory, the worktree moves inside it. If the shell is inside the worktree, it follows to the same subdirectory at the new location. Like remove, move refuses locked worktrees and the main worktree.
gwt lock and gwt unlock return the worktree's updated row. gwt list --long shows the lock reason.
Runs git's dry run first, reads each stale worktree's old path from git's records, and then prunes. --dry-run stops after the report. --expire 1.week.ago prunes only worktrees missing for longer than that. The table has name, which is git's id for the worktree, path, and reason.
Wraps git worktree repair and turns its repair: and error: lines into a table with status, problem, and path. status is repaired or failed. Pass the new location of a worktree you moved with mv to reconnect it.
gwt cd fix_parser changes to that worktree, and gwt cd --main to the main one. With no argument it opens a fuzzy picker.
Commands that only read or navigate are aliases. They run as typed and work in pipelines.
| Alias (runs on enter) | Runs |
|---|---|
gwtl |
gwt list |
gwtll |
gwt list --long |
gwts |
gwt status |
gwtpr |
gwt pr |
gwtcd |
gwt cd |
Commands that create, change, or delete worktrees are abbreviations. Nushell expands an abbreviation in the line editor when you press space or enter. You see the full command before it runs and can add flags to it, and history records the full command instead of the abbreviation.
| Abbreviation (expands first) | Expands to |
|---|---|
gwta |
gwt add |
gwtac |
gwt add --cd |
gwtrm |
gwt remove |
gwtmv |
gwt move |
gwtlk |
gwt lock |
gwtul |
gwt unlock |
gwtp |
gwt prune |
abbr list shows them. If you already have an abbreviation with one of these names, yours wins. To drop one, remove it below the use line:
$env.config.abbreviations = $env.config.abbreviations | reject gwtp- Worktree arguments complete worktree names, each described by its branch, state, and path.
removeandmoveoffer only linked worktrees,lockoffers unlocked ones, andunlockoffers locked ones. gwt add <branch>completes local branches that no worktree has checked out, newest first, then remote branches with no local branch of the same name.--basecompletes local branches, remote branches, and tags.
The module also defines extern signatures for the raw git worktree subcommands add, list, lock, move, prune, remove, repair, and unlock, so git worktree remove <Tab> completes too. Nushell hands any flag those signatures leave out to git unchanged. If another module defines the same externs, the one you import last wins.
nu --no-config-file test.nuThe script builds a throwaway repository with two bare remotes under mktemp, points GWT_ROOT inside it, and ignores your global and system git config. Then it runs every command against that repository, error cases included. gwt pr talks to a fake gh, a shell script that answers from canned JSON, so the tests need neither gh nor the network. The script deletes the fixture once every check passes.
MIT. See LICENSE.