Skip to content

Installation

Requirements

  • Git 2.36+ — required, not optional. Stack operations use git worktree list -z to see which branches are checked out where, and stackit refuses to run them on older Git rather than guess.
  • GitHub CLI (gh) for PR operations

Check your version with git --version. Some still-supported distributions ship older Git than this — Ubuntu 22.04 has 2.34 and Debian 11 has 2.30 — so you may need to upgrade Git before stackit will work. Run stackit doctor after installing to confirm your environment.

Homebrew (macOS and Linux)

The easiest way to install stackit is via Homebrew:

brew install getstackit/tap/stackit

After installation, you can use either stackit or st (short alias).

Shell integration

Recommended

Enable shell integration to automatically change directories when creating worktrees with stackit create -w.

Add one of the following to your shell configuration:

# ~/.zshrc
eval "$(stackit shell zsh)"

# ~/.bashrc
eval "$(stackit shell bash)"

# ~/.config/fish/config.fish
stackit shell fish | source

This is separate from shell completions. You likely want both:

# zsh example:
eval "$(stackit completion zsh)"
eval "$(stackit shell zsh)"

Shell completions

Enable tab completion for stackit commands:

# ~/.zshrc
eval "$(stackit completion zsh)"

# ~/.bashrc
eval "$(stackit completion bash)"

# ~/.config/fish/config.fish
stackit completion fish | source

Verify installation

Check that stackit is installed correctly:

stackit --version

Initialize your repository

In your Git repository, run:

stackit init

This command:

  1. Detects your trunk branch (usually main or master)
  2. Prepares the repository for stacking
  3. Offers to install optional integrations:
  4. GitHub Actions — CI checks for branch locking
  5. Git hooks — Prevent commits and pushes to locked branches (learn more)
  6. AI agent files — Integration files for Claude Code, Codex, and Cursor

You can skip the interactive prompts with stackit init --skip-integrations or install integrations later using the individual commands (stackit github install, stackit precommit install, stackit prepush install, stackit agent install).

Next steps