Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/romkatv/powerlevel10k/llms.txt

Use this file to discover all available pages before exploring further.

Powerlevel10k’s vcs segment displays rich, real-time Git repository status directly in your prompt. It is powered by gitstatus, which spawns a native gitstatusd daemon in the background. Because gitstatusd uses libgit2 rather than shelling out to the git binary, it can inspect even very large repositories with virtually zero perceptible latency.

​
Reading the Git status line

When using Lean, Classic, or Rainbow style, Git status may look like this: 
feature:master wip ⇣42⇡42 ⇠42⇢42 *42 merge ~42 +42 !42 ?42
Each part of this string has a specific meaning:
SymbolMeaningSource
featurecurrent branch; replaced with #tag or @commit if not on a branchgit status --ignore-submodules=dirty
masterremote tracking branch; only shown if different from local branchgit rev-parse --abbrev-ref --symbolic-full-name @{upstream}
wipthe latest commit’s summary contains “wip” or “WIP”git show --pretty=%s --no-patch HEAD
=up to date with the remote (neither ahead nor behind)git rev-list --count HEAD...@{upstream}
⇣42this many commits behind the remotegit rev-list --right-only --count HEAD...@{upstream}
⇡42this many commits ahead of the remotegit rev-list --left-only --count HEAD...@{upstream}
⇠42this many commits behind the push remotegit rev-list --right-only --count HEAD...@{push}
⇢42this many commits ahead of the push remotegit rev-list --left-only --count HEAD...@{push}
*42this many stashesgit stash list
mergerepository stategit status --ignore-submodules=dirty
~42this many merge conflictsgit status --ignore-submodules=dirty
+42this many staged changesgit status --ignore-submodules=dirty
!42this many unstaged changesgit status --ignore-submodules=dirty
?42this many untracked filesgit status --ignore-submodules=dirty
─the number of staged, unstaged or untracked files is unknownecho $POWERLEVEL9K_VCS_MAX_INDEX_SIZE_DIRTY or git config --get bash.showDirtyState

​
Asynchronous updates and the loading colour

Because computing a complete Git status for a large repository can take more than a few milliseconds, Powerlevel10k uses an async model: it shows the last known Git status immediately (in a greyed-out colour) and refreshes the prompt automatically once the background computation finishes. If the computation completes in under 10 milliseconds (the default threshold), the prompt shows the coloured status right away and no grey flash is visible. You can control both of these behaviours: 
# Time in seconds (fractional values allowed). If Git status computation takes longer than
# this, show the last known status in a loading colour while the update runs in background.
# Default: 0.01 (10 ms). Set to 0 to always compute synchronously (may slow prompt).
# typeset -g POWERLEVEL9K_VCS_MAX_SYNC_LATENCY_SECONDS=0.01

# Background colour used while Git status is being computed.
# In Rainbow style this defaults to colour 8 (dark grey).
typeset -g POWERLEVEL9K_VCS_LOADING_BACKGROUND=8
To change POWERLEVEL9K_VCS_LOADING_BACKGROUND, open ~/.p10k.zsh, search for the parameter, uncomment it if it is commented out, and set it to your preferred colour number.

​
Ignoring $HOME/.git

By default, configs generated by p10k configure include the following parameter: 
# Don't show Git status in prompt for repositories whose workdir matches this pattern.
# For example, if set to '~', the Git repository at $HOME/.git will be ignored.
# Multiple patterns can be combined with '|': '~(|/foo)|/bar/baz/*'.
typeset -g POWERLEVEL9K_VCS_DISABLED_WORKDIR_PATTERN='~'
Many users keep a bare or dotfiles Git repository rooted at $HOME. Showing its status all the time would make the prompt noisy regardless of what you are working on, so it is suppressed by default. To display Git status for $HOME/.git, open ~/.p10k.zsh and remove or comment out the POWERLEVEL9K_VCS_DISABLED_WORKDIR_PATTERN line.

​
Customising the Git status format

The exact text rendered by the vcs segment is produced by the my_git_formatter function in ~/.p10k.zsh. To change which symbols are used, their order, or the colours applied to each part, open ~/.p10k.zsh and search for my_git_formatter. The function is fully annotated and straightforward to edit.

​
SVN and Mercurial backends

By default, only the git VCS backend is enabled in Powerlevel10k. If you need svn or hg support, add them to POWERLEVEL9K_VCS_BACKENDS. Be aware that these backends are not yet optimised in Powerlevel10k and will make the prompt noticeably slower.

​
Incorrect Git status and libgit2 limitations

Powerlevel10k relies on gitstatus, which uses the libgit2 library internally. libgit2 has some gaps in its implementation that can cause discrepancies between what git status reports and what appears in your prompt. The most common known issue is that libgit2 does not support skipHash. If you notice incorrect Git status in your prompt, run git config -l and check whether skipHash is enabled. If it is, consider disabling it. Keep in mind that skipHash may be implicitly enabled when activating certain Git features such as manyFiles.

Build docs developers (and LLMs) love

Get started for freeTalk to us