VCS modules

Modules that reflect the state of the version-control repository in the current directory. Most use Starship's Context::get_repo() (which returns a gix repository handle) for Git, and shell out to the system hg or fossil for the others.

Active contributors

David Knaack, Matan Kushner, Thomas O'Donnell

Modules

Git

Module	Default	Purpose	File
git_branch	on main	Current branch / detached HEAD / remote tracking	src/modules/git_branch.rs
git_commit	(<hash>)	Short SHA, optional tag	src/modules/git_commit.rs
git_state	(REBASING 2/5)	Rebase / merge / cherry-pick / bisect / revert state	src/modules/git_state.rs
git_metrics	+12/-3	Lines added/deleted between HEAD and worktree	src/modules/git_metrics.rs
git_status	[!?$]	Untracked, modified, staged, stashed, conflicted, ahead/behind	src/modules/git_status.rs (~2.3K lines)

Git access goes through Context::get_repo → Repo::open (a thread-local gix::Repository). The Repo struct is built once per prompt with these fields:

• repo: ThreadSafeRepository
• branch: Option<String>
• workdir: Option<PathBuf>
• path: PathBuf
• state: Option<gix::state::InProgress>
• remote: Option<Remote>
• fs_monitor_value_is_true: bool

Both git_status and git_metrics can be expensive on large repos. They use parking_lot::Mutex for poison-free locks because the global rayon pool may run them concurrently. There are TODOs in git_metrics.rs about not yet using gix for sparse-index trees and detecting staged changes — see src/modules/git_metrics.rs.

For repositories that use the experimental reftables backend, git_branch falls back to invoking the system git binary because gix does not yet read reftables (uses_reftables in git_status.rs).

Mercurial

Module	Purpose	File
hg_branch	Active branch and topic of the hg repo	src/modules/hg_branch.rs
hg_state	Active hg operation (e.g. MERGING)	src/modules/hg_state.rs

The hg modules use Context::begin_ancestor_scan to find a .hg/ directory upwards from the cwd, then either parse files inside it or call hg directly via context.exec_cmd.

Fossil

Module	Purpose	File
fossil_branch	Active branch / check-out name	src/modules/fossil_branch.rs
fossil_metrics	Added/deleted lines in the check-out	src/modules/fossil_metrics.rs

Both shell out to the fossil binary.

Pijul, VCS aggregator, VCSH

Module	Purpose	File
pijul_channel	Current channel of a Pijul repo	src/modules/pijul_channel.rs
vcs	"First VCS that matches" — combines git, hg, fossil, pijul detection	src/modules/vcs.rs
vcsh	Active VCSH repository name	src/modules/vcsh.rs

vcs is a meta-module that asks each VCS in turn whether it applies and renders the first match. It is useful for users who routinely work in non-Git repos.

How git_status works

git_status is the largest module in the codebase by far. The high level:

graph TD
    Module["git_status::module"] --> Wsl["git_status_wsl<br/>(fast path on WSL/Windows)"]
    Module --> Info["GitStatusInfo::load(ctx, repo, cfg)"]
    Info --> Stash["count_stash<br/>(.git/refs/stash)"]
    Info --> Status["gix::status::Platform"]
    Info --> AB["compute_ahead_behind<br/>(gix::merge_base + revwalk)"]
    Status --> Counts["{conflicted, deleted, renamed,<br/>modified, typechanged, staged, untracked}"]
    Module --> Format["StringFormatter with $all_status<br/>$ahead_behind, etc."]

Notable details:

• The platform code (fn git_status_wsl) shells out to git on WSL where gix was historically slower than the system git for status.
• count_stash reads .git/refs/stash directly because gix did not initially support it.
• The format config defaults to a long string that includes every state variable; users can simplify by overriding it.
• Submodules are intentionally ignored unless Submodule::AsConfigured is overridden in gix::status::Platform.

Configuration knobs

Every VCS module supports disabled, a format string, a style, and a symbol. The Git modules additionally support truncation and ignored-bare-repo behavior. The full list lives in src/configs/<name>.rs and is reflected in .github/config-schema.json.

Performance notes

• git_status and git_metrics are the modules most likely to slow a prompt down. They are off the critical path only if your format does not reference them.
• gix is configured with default-features = false plus a curated feature set (see Cargo.toml); the comment there links to issue #4251 explaining why feature creep matters for prompt performance.
• The user can globally bound module compute time via command_timeout (default 500ms) in [StarshipRootConfig].

Entry points for modification

• To change what git_status shows for a state (e.g., add a new symbol), edit the appropriate <X>Config field in src/configs/git_status.rs and the matching variable mapping in git_status::module.
• To change how the branch is detected, edit get_current_branch in src/context.rs.
• To add a new VCS, write a new module and add it to the vcs aggregator in src/modules/vcs.rs.