git-prole

A git-worktree(1) manager.

A normal Git checkout looks like this:

my-repo/
  .git/
  README.md
  ...

Worktrees allow you to associate multiple checkouts with one .git directory, like this:

my-repo/
  .git/      # A bare repository
  main/      # A checkout for the main branch
    README.md
  feature1/  # A checkout for work on a feature
    README.md
  ...

This makes it a lot easier to keep a handful of branches ‘in flight’ at the same time, and it’s often handy to be able to compare your work against a local checkout of the main branch without switching branches.

Unfortunately, the built-in git worktree commands don’t make it very easy to set up repositories with this layout. git-prole exists to paper over these deficiencies.

Features

• Clone a repository into a worktree checkout with git prole clone URL [DESTINATION].

• Convert an existing repository into a worktree checkout with git prole convert.

• Add a new worktree with git prole add.

  • git prole add feature1 will create a feature1 directory next to the rest of your worktrees; git worktree add feature1, in contrast, will create a feature1 subdirectory nested under the current worktree.

  • Branches created with git prole add will start at and track the repository’s main branch by default.

  • git prole add will copy untracked files to the new worktree by default, making it easy to start a new worktree with a warm build cache.

  • git prole add can run commands when a new worktree is created, so that you can warm up caches by running a command like direnv allow.

  • git prole add can perform regex substitutions on branch names to compute a directory name, so that you can run git prole add -b myname/team-1234-my-ticket-with-a-very-long-title and get a directory name like my-ticket.

  • git prole add respects the -c/--create option (to match git switch); git worktree add only allows -b (with no long-form option available).

Installation

Nixpkgs

git-prole is available in nixpkgs as git-prole:

nix-env -iA git-prole
nix profile install nixpkgs#git-prole
# Or add to your `/etc/nixos/configuration.nix`.

Statically-linked binaries

Statically-linked binaries for aarch64/x86_64 macOS/Linux can be downloaded from the GitHub releases.

Crates.io

The Rust crate can be downloaded from crates.io:

cargo install git-prole

Configuration

git-prole supports configuration with a file in ~/.config/git-prole/config.toml by default.

Use git prole config init to generate a default configuration file; comments will explain each of the settings and their default values.

To write the default configuration file to your terminal, use git prole config init -.

Default branch/remote

Several parts of git-prole rely on a concept of a “default branch” or “default remote”:

• When using git prole convert to convert an existing repository into a worktree checkout, a worktree is created for the default branch.

• When using git prole add to create a new worktree, the created branch will start at the default branch.

Here’s how a default branch is determined:

1. We attempt to find a default remote:

   1. If a remote matching Git’s checkout.defaultRemote setting is found, we use that.

   2. Otherwise, we attempt to find a default remote by matching against the remote_names configuration setting, which defaults to upstream and origin.

2. If we find a default remote, we use git ls-remote --symref "$REMOTE" HEAD to determine the default branch for that remote.

3. If no default remote is found, we attempt to find a default local branch by matching against the branch_names configuration setting, which defaults to main, master, and trunk.