jj-starship

Unified Starship prompt module for Git and Jujutsu repositories that is optimized for latency.

Installation

Homebrew (macOS)

brew install dmmulroy/tap/jj-starship

Cargo

cargo install jj-starship

Build from source

git clone https://github.com/dmmulroy/jj-starship
cd jj-starship
cargo install --path .

Nix

# Try it
nix run github:dmmulroy/jj-starship

# Install to profile
nix profile install github:dmmulroy/jj-starship

# Minimal build (no git support, smaller closure)
nix run github:dmmulroy/jj-starship#jj-starship-no-git

Or add to your flake inputs:

{
  inputs.jj-starship.url = "github:dmmulroy/jj-starship";

  outputs = { self, nixpkgs, jj-starship, ... }: {
    # Use the overlay
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [{
        nixpkgs.overlays = [ jj-starship.overlays.default ];
        environment.systemPackages = [ pkgs.jj-starship ];
      }];
    };
  };
}

Feature Flags

The git feature is enabled by default. Disable to compile out the git backend:

# JJ only (excludes git2 dependency)
cargo install --no-default-features jj-starship

Starship Configuration

Add to ~/.config/starship.toml:

[custom.jj]
when = "jj-starship detect"
shell = ["jj-starship"]
format = "$output "

Why these settings:

• when = "jj-starship detect" - Walks up directory tree to find .jj or .git, works from any subdirectory
• shell = ["jj-starship"] - Executes jj-starship directly without shell wrapper overhead (cross-platform)
• format = "$output " - Passes through jj-starship's ANSI colors directly

To hide built-in modules when in a JJ repo:

[git_branch]
disabled = true

[git_status]
disabled = true

Output Format

JJ Format

on {symbol}{change_id} ({bookmarks}) [{status}]

• {change_id} - Short change ID (hide with --no-jj-id)
• {bookmarks} - Comma-separated bookmarks with distance, sorted by proximity (hide with --no-jj-name)
  • Distance 0 (bookmark on WC): main
  • Ancestor bookmark: main~3 (3 commits behind)
  • Overflow indicator: …+N when bookmarks exceed display limit
• {status} - Sync status based on first/closest bookmark only

Examples:

• on 󱗆 yzxv1234 [?] - No bookmarks
• on 󱗆 yzxv1234 (main) [?] - On bookmark main
• on 󱗆 yzxv1234 (main~3) [?] - 3 commits ahead of main
• on 󱗆 yzxv1234 (pr-3, pr-2~1, main~5) - Direct + ancestor bookmarks
• on 󱗆 yzxv1234 (main, feat~1, …+3) - 5 bookmarks, limit 2
• on 󱗆 yzxv1234 (feat-x, fix-y~1) - with --strip-bookmark-prefix "dmmulroy/"

Git Format

on {symbol}{branch} ({commit}) [{status}]

JJ Status Symbols

Git Status Symbols

CLI Options

Environment Variables

All options can be set via environment variables (CLI args take precedence):

• JJ_STARSHIP_TRUNCATE_NAME
• JJ_STARSHIP_ID_LENGTH
• JJ_STARSHIP_ANCESTOR_BOOKMARK_DEPTH
• JJ_STARSHIP_BOOKMARKS_DISPLAY_LIMIT
• JJ_STARSHIP_STRIP_BOOKMARK_PREFIX
• JJ_STARSHIP_JJ_SYMBOL
• JJ_STARSHIP_GIT_SYMBOL
• JJ_STARSHIP_NO_JJ_PREFIX
• JJ_STARSHIP_NO_JJ_COLOR
• JJ_STARSHIP_NO_JJ_NAME
• JJ_STARSHIP_NO_JJ_ID
• JJ_STARSHIP_NO_JJ_STATUS
• JJ_STARSHIP_NO_GIT_PREFIX
• JJ_STARSHIP_NO_GIT_COLOR
• JJ_STARSHIP_NO_GIT_NAME
• JJ_STARSHIP_NO_GIT_ID
• JJ_STARSHIP_NO_GIT_STATUS

Powerline Prompt

Example configuration in a powerline prompt, for instance Gruvbox Rainbow:

format = """
[](color_orange)\
$os\
$username\
[](bg:color_yellow fg:color_orange)\
$directory\
[](fg:color_yellow bg:color_aqua)\
${custom.jj}\ # <- replace $git_branch $git_status here
[](fg:color_aqua bg:color_blue)\

...
"""

[git_branch]
disabled = true

[git_status]
disabled = true

[custom.jj]
symbol = ""
style = "bg:color_aqua"
format = '[[ $symbol $output ](fg:color_fg0 bg:color_aqua)]($style)'
when = "jj-starship detect"
shell = ["jj-starship", "--no-color", "--no-symbol", "--no-jj-prefix", "--no-git-prefix"]

License

MIT