Skip to content

About

A git worktree nushell module

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

gwt

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

Requirements

  • Nushell 0.116.2 or newer. The tests pass on 0.117.0. Everything except gwt pr was 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 --orphan needs git 2.42.
  • The GitHub CLI, gh, logged in, for gwt pr only. Tested with gh 2.103.

Install

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.

Commands

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.

gwt list

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.

gwt status

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.

gwt pr

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 remove

Plain 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.

gwt add

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 topic when one remote has it, or origin/topic to 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/abc

Before 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 --detach

gwt remove

Takes 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. --force overrides that.
  • gwt always refuses the main worktree and locked worktrees. git removes a locked worktree when you pass --force twice, but gwt makes you run gwt unlock first, so a lock still protects the worktree when you add --force for local changes.
  • --delete-branch (-d) also deletes the branch with git branch -d, which refuses unmerged branches. --force-delete-branch (-D) uses git branch -D.
  • If the shell is inside a worktree that gets removed, gwt moves it to the main worktree first.

gwt move, lock, unlock

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.

gwt prune

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.

gwt repair

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

gwt cd fix_parser changes to that worktree, and gwt cd --main to the main one. With no argument it opens a fuzzy picker.

Aliases and abbreviations

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

Completions

  • Worktree arguments complete worktree names, each described by its branch, state, and path. remove and move offer only linked worktrees, lock offers unlocked ones, and unlock offers 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.
  • --base completes 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.

Tests

nu --no-config-file test.nu

The 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.

License

MIT. See LICENSE.

About

A git worktree nushell module

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages