gittyup

gittyup is a filesystem-driven CLI for managing bare Git repositories and linked worktrees under a shared root such as ~/src.

Install

From npm:

npm install -g @mbluemer_2/gittyup

Or with pnpm:

pnpm add -g @mbluemer_2/gittyup

From a GitHub release tarball:

npm install -g "https://github.com/mbluemer/gittyup/releases/download/vX.Y.Z/gittyup-X.Y.Z.tgz"

Or with pnpm:

pnpm add -g "https://github.com/mbluemer/gittyup/releases/download/vX.Y.Z/gittyup-X.Y.Z.tgz"

That installs the gu binary from the packaged dist/ output attached to each GitHub release. The npm package exposes the same gu binary.

Requirements

• git 2.17+
• tmux for gittyup tmux ...
• fzf for interactive worktree and tmux pickers

Root directory

By default, gittyup manages projects under ~/src.

• Override it per command with --root ~/somewhere
• Or set GITTYUP_ROOT=~/somewhere to make a different default

Layout

Each project is stored as:

~/src/myrepo/
  repo.git/
  main/
  feature-login/

repo.git is the canonical bare repository. Linked worktrees live beside it.

Commands

gittyup project list
gu pl
gittyup project doctor
gu pd
gittyup project init get myrepo
gu pg myrepo
gittyup project init set myrepo "pnpm install"
gu ps myrepo "pnpm install"
gittyup project init clear myrepo
gu px myrepo
gittyup project create myrepo
gu pc myrepo
gittyup project clone [email protected]:owner/myrepo.git
gu pcl [email protected]:owner/myrepo.git
gittyup project import ~/code/existing-repo existing-repo-managed
gu pi ~/code/existing-repo existing-repo-managed
gittyup project rename some-repo-managed some-repo
gu pr some-repo-managed some-repo

gittyup worktree list
gu wl
gittyup worktree list myrepo
gittyup worktree add
gu wa
gittyup worktree add myrepo feature/login --alias feature-login
gittyup worktree add myrepo fix/bug --from main
gittyup worktree remove
gu wr
gittyup worktree remove myrepo feature-login

gittyup status
gu st
gittyup status myrepo
gu s myrepo

gittyup tmux launch myrepo
gu tl myrepo
gittyup tmux launch
gu tl
gittyup tmux switch
gu ts

Shortcuts

gu supports flattened shortcuts for common commands:

p     -> project
pl    -> project list
pd    -> project doctor
pg    -> project init get
ps    -> project init set
px    -> project init clear
pc    -> project create
pcl   -> project clone
pi    -> project import
pr    -> project rename
w     -> worktree
wl    -> worktree list
wa    -> worktree add
wr    -> worktree remove
s/st  -> status
t     -> tmux
tl    -> tmux launch
ts    -> tmux switch

Options

gittyup --root ~/src
gittyup --json

Project diagnostics

gittyup project doctor inspects every directory under the managed root and reports both healthy projects and broken entries that are missing repo.git or have invalid worktree metadata.

Project init commands

You can configure a per-project shell command to run whenever gittyup worktree add creates a new linked worktree.

Example:

gittyup project init set gittyup "pnpm install"
gittyup project init get gittyup
gittyup project init clear gittyup

• The command runs with the new worktree as its working directory.
• If the init command fails, the worktree is kept and gittyup reports the error.
• The command is stored in .gittyup.json inside the managed project root.

Interactive worktree add

gittyup worktree add can run interactively when arguments are omitted.

• With no arguments, it opens fzf to select a project and then prompts for a branch name.
• With only a project name, it prompts for the branch name.
• The worktree alias is still derived automatically unless you pass --alias.

Example:

gittyup worktree add
gittyup worktree add myrepo

Interactive worktree remove

gittyup worktree remove can also run interactively when arguments are omitted.

• With no arguments, it opens a single fzf picker showing worktrees as <project>:<worktree>.
• With only a project name, it opens fzf for that project's worktrees using the same <project>:<worktree> format.
• The canonical main worktree is protected and cannot be removed.

Example:

gittyup worktree remove
gittyup worktree remove myrepo

Interactive tmux launch

gittyup tmux launch can also run interactively when arguments are omitted.

• With no arguments, it opens fzf for all linked worktrees as <project>:<worktree>.
• With only a project name, it opens fzf for that project's worktrees using the same format.

Example:

gittyup tmux launch
gittyup tmux launch myrepo
gu tl
gu tl myrepo

Development

pnpm install
pnpm build
pnpm test
pnpm lint
pnpm dev --help
pnpm dev project list
pnpm dev -- project list

Both pnpm dev project list and pnpm dev -- project list are supported.

Releases

Updating package.json to a new version and merging that change to main automatically runs the release workflow.

• CI runs first on the main push
• Release only runs after that CI run succeeds
• The workflow creates and pushes the matching vX.Y.Z tag
• pnpm pack creates an installable tarball
• GitHub Releases gets the tarball and SHA256SUMS.txt attached automatically
• The same workflow publishes @mbluemer_2/gittyup to npm using the NPM_TOKEN repo secret

You can still create a release manually by pushing a tag like v0.1.0 yourself.

Version bump policy for agents is documented in AGENTS.md.

Local project bootstrap

gittyup project create <name> bootstraps a new local project by:

1. Creating repo.git
2. Seeding an initial empty commit on main
3. Creating the linked main/ worktree

That makes new local projects immediately usable with additional worktrees.

Import existing repos

gittyup project import <source> [name] creates a new managed project from an existing local non-bare Git repository.

Example:

gittyup project import ~/src/some-repo some-repo-managed

This does not rewrite the source repository in place. It creates a new managed project directory under your configured root with repo.git and main/.

Rename managed projects

gittyup project rename <project> <name> renames the managed project folder and repairs the linked worktree metadata for the new paths.