I’ve been using git worktree a lot more recently in my work, and I always find the commands verbose and, in the case of creating worktrees for new or existing branches, frustrating in their parameter expectations. So I decided to do something about it. I wrote gwt.

gwt is a CLI tool written in zsh that wraps the most frequent git worktree commands I run with what I think are sane defaults and bonuses.

It doesn’t want to be a replacement, so for anything not covered by it right now, I’ll just keep falling back to git worktree <subcommand> [args]. Though I’m sure I’ll update, especially for things like shallow checkouts etc in larger projects.

How/why/usage/whatever

The main frustration I wanted to solve with gwt is the inconsistency in git worktree add when you do or don’t set the -b flag, which makes scripting it kind of a pain in the ass:

• git worktree add <path> <branch>
• git worktree add -b <branch> <path>

Like… why? Really? That’s so… asinine.

Instead gwt add accepts just a single parameter, <branch>, and then does some magic:

• looks up the current repository’s name in the local fs (e.g. ~/src/project => 'project')
• constructs a path for the new worktree at ~/worktrees/<repository>/<branch>
• runs git worktree add [-b] with the branch and path args in the right order

and now you have a worktree at ~/worktrees/<repository>/<branch>!

It also has some other useful flags on add:

• --cd: moves you to the new worktree after creation
• --path|-p: if you want to set a custom path instead of using the default generated one
• --dry-run: started as a testing tool for me, but might still be helpful, since it’ll prefix any destructive commands with echo so you can see them before actually running

And there are some other commands:

• gwt cd [branch] moves to the worktree, or if run from without a branch back to to the “main” repo
• gwt rm <branch|path> [--force] removes the worktree. If you run it with gwt rm . it’ll do gwt cd to the main repo first
• gwt status [--with-main] [--porcelain] print the status of the worktrees, including git/commit state like dirty,unpushed so you can check at a glance what the status of your workstreams is

And then there’s gwt init that’ll set up some custom config in ~/.config/gwt/settings.json:

• autoCd will do the equivalent of gwt add --cd every time you create a worktree
• wortkreeLocation overrides the default base path of ~/worktrees
• deleteBranchWithTree will run git branch -d (or -D if you use -f) after gwt rm is run, to clean up local branches at the same time as their trees

It’s packaged as a nix flake since I can’t help myself, but you can just as easily the function somewhere zsh will source it for you when your shell loads.

Feel free to use, or even better open issues/PRs.