Display git information when in a Git repository. Also works for subfolders. For maximum compatibility,
make sure your git executable is up-to-date (when branch or status information is incorrect for example).
As doing multiple git calls can slow down the prompt experience, we do not fetch information by default.
You can set the following options to true to enable fetching additional information (and populate the template).
Name
Type
Default
Description
fetch_status
boolean
false
fetch the local changes
native_status
boolean
false
fetch the status information using the built-in engine instead of the git CLI (experimental, falls back to git automatically). Falls back to the git CLI for sparse/split index, reftables, and submodule repositories
fetch_push_status
boolean
false
fetch the push-remote ahead/behind information. Requires fetch_status to be enabled
ignore_status
[]string
do not fetch status for these repo's. Uses the repo's root folder and same logic as the exclude_folders property
For example "untracked_modes": { "/Users/me/repos/repo1": "no" } - defaults to normal for all repo's. If you want to override for all repo's, use * to set the mode instead of the repo path
ignore_submodules
map[string]string
map of repo's where to change the --ignore-submodules flag (none, untracked, dirty or all). For example "ignore_submodules": { "/Users/me/repos/repo1": "all" }. If you want to override for all repo's, use * to set the mode instead of the repo path
native_fallback
boolean
false
when set to true and git.exe is not available when inside a WSL2 shared Windows drive, we will fallback to the native git executable to fetch data. Not all information can be displayed in this case
status_formats
map[string]string
a key, value map allowing to override how individual status items are displayed. For example, "status_formats": { "Added": "Added: %d" } will display the added count as Added: 1 instead of +1. See the Status section for available overrides.
source
string
cli
cli: fetch the information using the git CLI
pwsh: fetch the information from the posh-git PowerShell Module
mapped_branches
object
custom glyph/text for specific branches. You can use * at the end as a wildcard character for matching
branch_template
string
a template to format that branch name. You can use {{ .Branch }} as reference to the original branch name and {{ .Upstream }} as reference to the upstream name
disable_with_jj
boolean
false
disable the git segment in case of a Jujutsu collocated repository
icon/text to display when the upstream is Bitbucket
azure_devops_icon
string
\uEBE8
icon/text to display when the upstream is Azure DevOps
codecommit_icon
string
\uF270
icon/text to display when the upstream is AWS CodeCommit
codeberg_icon
string
\uF330
icon/text to display when the upstream is Codeberg
git_icon
string
\uE5FB
icon/text to display when the upstream is not known/mapped
upstream_icons
map[string]string
a key, value map representing the remote URL (or a part of that URL) and icon to use in case the upstream URL contains the key. These get precedence over the standard icons
{{ .HEAD }}{{if .BranchStatus }} {{ .BranchStatus }}{{ end }}{{ if .Working.Changed }} \uF044 {{ .Working.String }}{{ end }}{{ if and (.Staging.Changed) (.Working.Changed) }} |{{ end }}{{ if .Staging.Changed }} \uF046 {{ .Staging.String }}{{ end }}
the current HEAD context (branch/rebase/merge/...)
.Ref
string
the current HEAD reference (branch/tag/...)
.Behind
int
commits behind of upstream
.Ahead
int
commits ahead of upstream
.PushBehind
int
commits behind of push remote
.PushAhead
int
commits ahead of push remote
.BranchStatus
string
the current branch context (ahead/behind string representation)
.Upstream
string
the upstream name (remote)
.UpstreamGone
boolean
whether the upstream is gone (no remote)
.UpstreamIcon
string
the upstream icon (based on the icons above)
.UpstreamURL
string
the upstream URL for use in hyperlinks in templates: {{ url .UpstreamIcon .UpstreamURL }}
.RawUpstreamURL
string
the raw upstream URL (not cleaned up for display)
.Hash
string
the full commit hash
.ShortHash
string
the short commit hash (7 characters)
.StashCount
int
the stash count
.WorktreeCount
int
the worktree count
.IsWorkTree
boolean
if in a worktree repo or not
.MainWorktree
string
the absolute path to the main worktree; empty unless the current repository is a linked worktree
.IsBare
boolean
if in a bare repo or not, only set when fetch_bare_info is set to true
.Dir
string
the repository's root directory
.RelativeDir
string
the current directory relative to the root directory
.Kraken
string
a link to the current HEAD in GitKraken for use in hyperlinks in templates {{ url .HEAD .Kraken }}
.Commit
Commit
HEAD commit information (see below)
.Detached
boolean
true when the head is detached
.Merge
boolean
true when in a merge
.Rebase
Rebase
contains the relevant information when in a rebase
.CherryPick
boolean
true when in a cherry pick
.Revert
boolean
true when in a revert
.User
User
the current configured user (requires fetch_user to be enabled)
.Remotes
map[string]string
a map of remote names to their URLs
.LatestTag
string
the latest tag name
.MainWorktree requires Git 2.36 or newer. It is resolved lazily, so no additional command runs
unless the property is referenced. Its first use in a linked worktree runs
git worktree list --porcelain -z; the result is cached for the shell session and shared by
sibling worktrees of the repository.
The property is empty in the main worktree and when the main repository is bare. It also remains
empty when Git does not support the command, the command fails, or its output cannot be parsed.
Use the source: pwsh option to fetch status information from the posh-git PowerShell
module instead of the git CLI. This populates the same template properties as above, so you're
not limited to what Write-GitStatus prints, and nothing relies on ANSI escape sequences.
json
yaml
toml
{
"type":"git",
"style":"plain",
"template":"[{{ .HEAD }}{{ if .BranchStatus }} {{ .BranchStatus }}{{ end }}{{ if .Staging.Changed }} +{{ .Staging.Added }} ~{{ .Staging.Modified }} -{{ .Staging.Deleted }}{{ if gt .Staging.Unmerged 0 }} !{{ .Staging.Unmerged }}{{ end }}{{ end }}{{ if and .Staging.Changed .Working.Changed }} |{{ end }}{{ if .Working.Changed }} +{{ add .Working.Added .Working.Untracked }} ~{{ .Working.Modified }} -{{ .Working.Deleted }}{{ if gt .Working.Unmerged 0 }} !{{ .Working.Unmerged }}{{ end }}{{ end }}{{ if .Working.Changed }} !{{ else if .Staging.Changed }} ~{{ end }}]",
"options":{
"fetch_status":true,
"source":"pwsh"
}
}
type: git
style: plain
template: "[{{ .HEAD }}{{ if .BranchStatus }}{{ .BranchStatus }}{{ end }}{{ if
.Working.Modified }}-{{ .Working.Deleted }}{{ if gt .Working.Unmerged 0 }}
!{{ .Working.Unmerged }}{{ end }}{{ end }}{{ if .Working.Changed }}!{{ else
if .Staging.Changed }} ~{{ end }}]"
options:
fetch_status:true
source: pwsh
type="git"
style="plain"
template="[{{ .HEAD }}{{ if .BranchStatus }} {{ .BranchStatus }}{{ end }}{{ if .Staging.Changed }} +{{ .Staging.Added }} ~{{ .Staging.Modified }} -{{ .Staging.Deleted }}{{ if gt .Staging.Unmerged 0 }} !{{ .Staging.Unmerged }}{{ end }}{{ end }}{{ if and .Staging.Changed .Working.Changed }} |{{ end }}{{ if .Working.Changed }} +{{ add .Working.Added .Working.Untracked }} ~{{ .Working.Modified }} -{{ .Working.Deleted }}{{ if gt .Working.Unmerged 0 }} !{{ .Working.Unmerged }}{{ end }}{{ end }}{{ if .Working.Changed }} !{{ else if .Staging.Changed }} ~{{ end }}]"
[options]
fetch_status=true
source="pwsh"
The template above reproduces posh-git's default [branch status | staged changes | working changes] format,
counting untracked files as added in the working tree, the same way posh-git does. Adjust icons, order, or
gating to taste, it's a regular template now.