Skip to content

README.md

Latest commit

 

History

History
197 lines (141 loc) · 4.75 KB

README.md

File metadata and controls

197 lines (141 loc) · 4.75 KB

terris

Crates.io Docs.rs CI License

A small, friendly Git worktree manager for everyday use.

What it does

  • Create new worktrees quickly (or jump to existing ones)
  • List existing worktrees
  • Remove worktrees safely
  • Print a worktree path for cd "$(terris <branch>)"
  • Simplify workflows with autonomous agents that work in the terminal in the same repository

Install

From crates.io:

cargo install terris

From source:

git clone https://github.com/mfornet/terris.git
cd terris
cargo install --path .

Usage

# Jump to a worktree.
cd "$(terris feature-a)"

# List worktrees
terris

# List all worktrees (including detached)
terris --all

# Delete a worktree
terris --rm feature-a

How it works

  • terris <branch> creates the worktree and prints the path every time.
  • terris lists worktrees for the current repository.
  • terris --all lists all worktrees, including ones without branches.
  • If the branch exists, it is used directly.
  • If the branch does not exist, behavior depends on your terris config.
  • Default path is ~/.terris-worktrees/<repo-name>/<branch>-<random-key>.

Notes

  • Works from any directory inside a git repo.
  • The tool shells out to git, so git must be installed and available in PATH.

Configuration

terris reads configuration from these files, in this order:

  1. ~/.terris/terris.toml for user-wide defaults
  2. <git-root>/.terris.toml for project-specific overrides

If both files exist, terris merges them and the project-local file overrides the global one. If neither exists, built-in defaults are used.

Create a global config:

mkdir -p ~/.terris
$EDITOR ~/.terris/terris.toml

Create a project-local config:

$EDITOR .terris.toml

Example:

[worktrees]
base_dir = "~/src/worktrees"
use_random_suffix = true
suffix_length = 8

[behavior]
on_missing_branch = "fetch, create"
auto_prune = true

[display]
show_head = true

Available settings

[worktrees]

  • base_dir: Base directory for new worktrees. Supports ~. Default: ~/.terris-worktrees
  • use_random_suffix: Whether to append a random suffix to worktree directory names. Default: true
  • suffix_length: Length of the random suffix when use_random_suffix = true. Default: 8. Valid range: 1..=64

With defaults, terris creates worktrees under:

~/.terris-worktrees/<repo-name>/<branch>-<random-key>

If use_random_suffix = false, the path becomes:

~/.terris-worktrees/<repo-name>/<branch>

[behavior]

  • on_missing_branch: What terris should do when the requested branch does not exist locally. Default: "error"
  • auto_prune: Run git worktree prune before listing worktrees. Default: false

on_missing_branch accepts a comma-separated list of actions tried in order:

  • error: Fail immediately. This cannot be combined with other actions.
  • fetch: Run git fetch origin <branch> and use the remote branch if found.
  • create: Create a new local branch from the current HEAD.

Examples:

[behavior]
on_missing_branch = "error"
[behavior]
on_missing_branch = "fetch"
[behavior]
on_missing_branch = "fetch, create"
[behavior]
on_missing_branch = "create"

[display]

  • show_head: Show the short HEAD commit hash as an extra column when listing worktrees. Default: false

Shell completion

Generate a completion script and source it in your shell:

# Bash
terris --completions bash > /tmp/terris.bash
source /tmp/terris.bash

# Zsh
terris --completions zsh > /tmp/_terris
fpath=(/tmp $fpath)
autoload -U compinit && compinit

# Fish
terris --completions fish > /tmp/terris.fish
source /tmp/terris.fish

Install permanently (recommended):

# Bash (user-level)
mkdir -p ~/.local/share/bash-completion/completions
terris --completions bash > ~/.local/share/bash-completion/completions/terris

# Bash (system-wide)
sudo mkdir -p /etc/bash_completion.d
sudo terris --completions bash > /etc/bash_completion.d/terris

# Zsh
mkdir -p ~/.zsh/completions
terris --completions zsh > ~/.zsh/completions/_terris
fpath=(~/.zsh/completions $fpath)
autoload -U compinit && compinit

# Fish
mkdir -p ~/.config/fish/completions
terris --completions fish > ~/.config/fish/completions/terris.fish

Name

The project is named after the Terris people, responsible for preserving the knowledge of the civilization.

License

MIT
⚡