Working with Worktrees

Creating a new worktree

To actually work, you'll first have to create a new worktree checkout. All worktree-related commands are available as subcommands of grm worktree (or grm wt for short):

$ grm wt add mybranch
[✔] Worktree mybranch created

You'll see that there is now a directory called mybranch that contains a checkout of your repository, using the branch mybranch

$ cd ./mybranch && git status
On branch mybranch
nothing to commit, working tree clean

You can work in this repository as usual. Make changes, commit them, revert them, whatever you're up to :)

Just note that you should not change the branch inside the worktree directory. There is nothing preventing you from doing so, but you will notice that you'll run into problems when trying to remove a worktree (more on that later). It may also lead to confusing behavior, as there can be no two worktrees that have the same branch checked out. So if you decide to use the worktree setup, go all in, let grm manage your branches and bury git branch (and git checkout -b).

You will notice that there is no tracking branch set up for the new branch. You can of course set up one manually after creating the worktree, but there is an easier way, using the --track flag during creation. Let's create another worktree. Go back to the root of the repository, and run:

$ grm wt add mybranch2 --track origin/mybranch2
[✔] Worktree mybranch2 created

You'll see that this branch is now tracking mybranch on the origin remote:

$ cd ./mybranch2 && git status
On branch mybranch

Your branch is up to date with 'origin/mybranch2'.
nothing to commit, working tree clean

The behavior of --track differs depending on the existence of the remote branch:

• If the remote branch already exists, grm uses it as the base of the new local branch.
• If the remote branch does not exist (as in our example), grm will create a new remote tracking branch, using the default branch (either main or master) as the base

Often, you'll have a workflow that uses tracking branches by default. It would be quite tedious to add --track every single time. Luckily, the grm.toml file supports defaults for the tracking behavior. See this for an example:

[track]
default = true
default_remote = "origin"

This will set up a tracking branch on origin that has the same name as the local branch.

Sometimes, you might want to have a certain prefix for all your tracking branches. Maybe to prevent collisions with other contributors. You can simply set default_remote_prefix in grm.toml:

[track]
default = true
default_remote = "origin"
default_remote_prefix = "myname"

When using branch my-feature-branch, the remote tracking branch would be origin/myname/my-feature-branch in this case.

Note that --track overrides any configuration in grm.toml. If you want to disable tracking, use --no-track.

Showing the status of your worktrees

There is a handy little command that will show your an overview over all worktrees in a repository, including their status (i.e. changes files). Just run the following in the root of your repository:

$ grm wt status
╭───────────┬────────┬──────────┬──────────────────╮
│ Worktree  ┆ Status ┆ Branch   ┆ Remote branch    │
╞═══════════╪════════╪══════════╪══════════════════╡
│ mybranch  ┆ ✔      ┆ mybranch ┆                  │
│ mybranch2 ┆ ✔      ┆ mybranch ┆ origin/mybranch2 │
╰───────────┴────────┴──────────┴──────────────────╯

The "Status" column would show any uncommitted changes (new / modified / deleted files) and the "Remote branch" would show differences to the remote branch (e.g. if there are new pushes to the remote branch that are not yet incorporated into your local branch).

Deleting worktrees

If you're done with your worktrees, use grm wt delete to delete them. Let's start with mybranch2:

$ grm wt delete mybranch2
[✔] Worktree mybranch2 deleted

Easy. On to mybranch:

$ grm wt delete mybranch
[!] Changes in worktree: No remote tracking branch for branch mybranch found. Refusing to delete

Hmmm. grm tells you:

"Hey, there is no remote branch that you could have pushed your changes to. I'd rather not delete work that you cannot recover."

Note that grm is very cautious here. As your repository will not be deleted, you could still recover the commits via git-reflog. But better safe than sorry! Note that you'd get a similar error message if your worktree had any uncommitted files, for the same reason. Now you can either commit & push your changes, or your tell grm that you know what you're doing:

$ grm wt delete mybranch --force
[✔] Worktree mybranch deleted

If you just want to delete all worktrees that do not contain any changes, you can also use the following:

$ grm wt clean

Note that this will not delete the default branch of the repository. It can of course still be delete with grm wt delete if necessary.

Converting an existing repository

It is possible to convert an existing directory to a worktree setup, using grm wt convert. This command has to be run in the root of the repository you want to convert:

$ grm wt convert
[✔] Conversion successful

This command will refuse to run if you have any changes in your repository. Commit them and try again!

Afterwards, the directory is empty, as there are no worktrees checked out yet. Now you can use the usual commands to set up worktrees.