Shu

A small, personal library for your Git repositories.

Shu remembers the projects you care about, puts new clones in predictable places, and lets you jump to them quickly. Its catalog is a readable shu.toml file—your repositories stay normal Git repositories under your control.

Download a release for macOS, Windows, or Linux from GitHub Releases, or install it with:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/wiedymi/shu/releases/latest/download/shu-installer.sh | sh

irm https://github.com/wiedymi/shu/releases/latest/download/shu-installer.ps1 | iex

The installers verify the download against the release checksums. To build from source instead:

cargo install --git https://github.com/wiedymi/shu

Add a project you already have, or clone one you want. Shu creates its local catalog automatically and uses ~/shu as the default library root.

# From inside an existing Git repository
shu add .

# Clone and remember a repository
shu add github.com/example-org/api
# `shu clone github.com/example-org/api` means the same thing.

Now find it whenever you need it:

shu list
shu path api
shu pick

shu path prints the preferred local checkout. shu pick opens the fuzzy picker and returns the selected path. The shell integration below makes plain shu open that picker and change your current directory.

Repository names can be the full identity (github.com/you/project), a unique suffix, or a unique name such as project.

Install the tiny shell wrapper once:

# Pick the shell you use: bash, zsh, fish, nushell, or posix.
shu shell init zsh

shu shell init pwsh

Open a new terminal afterwards. Then plain shu shows the fuzzy picker; choose a repository or one of its Git worktrees and your shell changes into it. shu pick remains useful when you only need the selected path.

Adding . records an existing checkout where it already lives. Adding a remote identity clones it below the library root:

~/shu/github.com/you/project

Mark projects for later without moving or deleting anything:

shu edit project --state parked --note "Waiting for the next release"
shu edit project --state reference
shu archive project

The available states are active, parked, reference, and archived. Shu never deletes repositories or resets working trees.

Tags describe repositories; collections are portable named queries over those tags. They do not duplicate membership or change clone paths. A collection with multiple tags requires every tag.

[collections]
work = { tags = ["work"] }
platform = { tags = ["platform", "rust"] }

Use a collection anywhere Shu accepts repository filters:

shu list --collection work
shu pick --collection platform
shu restore --collection work

Repeat --tag for the same one-off all-tags match:

shu restore --tag work --tag rust

When restoring a newly supplied catalog source, Shu first asks whether to select named collections or individual repositories. Entering a selection only previews it; type yes to start cloning. Use --yes for an unattended restore of every matching repository.

If you want to bring a clean existing checkout into Shu's managed layout, preview the move first:

shu add . --migrate --dry-run
shu add . --migrate

Create a new local Git repository in Shu's library:

shu new github.com/you/new-project --tag experiment

To also create a private GitHub repository and set it as origin, use the authenticated GitHub CLI:

shu doctor --check-github
shu new github.com/you/private-project --github

Pass --public only when you explicitly want a public repository. If GitHub CLI is unavailable, create the remote yourself and add it with Git as usual.

Sync is optional. It stores your catalog in a normal private Git repository, using the credentials you already use for Git. Shu does not store tokens or create extra state files.

Create a private catalog repository automatically with GitHub CLI:

shu sync init github.com/you/shu-catalog --github

Or create an empty private repository with any Git host first, then point Shu at it:

shu sync init git@github.com:you/shu-catalog.git

After you change your catalog, publish it:

shu sync

On another machine, restore the catalog and its missing projects:

shu restore git@github.com:you/shu-catalog.git

The synced catalog contains repository identities, Git remotes, states, tags, and notes. Your local root and local checkout paths stay private to each machine, so restore places managed projects below that machine's root. The catalog repository itself is a normal checkout below the root, but it is not shown in Shu's repository list or picker.

shu.toml is the only configuration file Shu creates. You can edit it by hand or use the commands above.

version = 1
root = "~/shu"

[[repos]]
source = "github.com/your-name/project"
state = "active"
tags = ["personal", "rust"]
note = "A project I work on regularly"
paths = ["github.com/your-name/project"]
primary = "github.com/your-name/project"

[sync]
remote = "git@github.com:you/shu-catalog.git"
file = "shu.toml"
ref = "main"

Paths below root are stored relative to it. A checkout at github.com/your-name/project therefore resolves to ~/shu/github.com/your-name/project with the default root. Paths outside the root are absolute and stay on the machine where they were recorded. Git worktrees are discovered when needed rather than stored in the catalog.

For scripts and coding agents, use ensure when a checkout may be missing:

repo_path="$(shu ensure github.com/example-org/project --path-only)"

shu --help
shu <command> --help
shu doctor --check-source

Please read SECURITY.md before reporting a vulnerability.

MIT