---
id: git
title: Git
sidebar_label: Git
---

## What

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).

:::tip
PowerShell offers support for the [posh-git][poshgit] module for autocompletion, but it is disabled by default.
To enable this, set `$env:POSH_GIT_ENABLED = $true` in your `$PROFILE` after initializing Oh My Posh.
This will also make use of the [posh-git][poshgit] output rather than do additional work to get the git status.

If you want to display the default [posh-git][poshgit] output, **do not** set the above environment variable
and add the following snippet after initializing Oh My Posh in your `$PROFILE`:

```powershell
function Set-PoshGitStatus {
    $global:GitStatus = Get-GitStatus
    $env:POSH_GIT_STRING = Write-GitStatus -Status $global:GitStatus
}
New-Alias -Name 'Set-PoshContext' -Value 'Set-PoshGitStatus' -Scope Global -Force
```

You can then use the `POSH_GIT_STRING` environment variable in a [text segment][text]:

```json
"template": "{{ if .Env.POSH_GIT_STRING }} {{ .Env.POSH_GIT_STRING }} {{ end }}"
```

:::

## Sample Configuration

import Config from "@site/src/components/Config.js";

<Config
  data={{
    type: "git",
    style: "powerline",
    powerline_symbol: "\uE0B0",
    foreground: "#193549",
    background: "#ffeb3b",
    background_templates: [
      "{{ if or (.Working.Changed) (.Staging.Changed) }}#FFEB3B{{ end }}",
      "{{ if and (gt .Ahead 0) (gt .Behind 0) }}#FFCC80{{ end }}",
      "{{ if gt .Ahead 0 }}#B388FF{{ end }}",
      "{{ if gt .Behind 0 }}#B388FB{{ end }}",
    ],
    template:
      "{{ .UpstreamIcon }}{{ .HEAD }}{{if .BranchStatus }} {{ .BranchStatus }}{{ end }}{{ if .Working.Changed }} \uF044 {{ .Working.String }}{{ end }}{{ if and (.Working.Changed) (.Staging.Changed) }} |{{ end }}{{ if .Staging.Changed }} \uF046 {{ .Staging.String }}{{ end }}{{ if gt .StashCount 0 }} \uF692 {{ .StashCount }}{{ end }}",
    properties: {
      fetch_status: true,
      fetch_stash_count: true,
      fetch_upstream_icon: true,
      untracked_modes: {
        "/Users/user/Projects/oh-my-posh/": "no",
      },
    },
  }}
/>

## Properties

### Fetching information

As doing multiple git calls can slow down the prompt experience, we do not fetch information by default.
You can set the following properties to `true` to enable fetching additional information (and populate the template).

| Name                  | Type                | Description                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fetch_status`        | `boolean`           | fetch the local changes - defaults to `false`                                                                                                                                                                                                                                                                                         |
| `ignore_status`       | `[]string`          | do not fetch status for these repo's. Uses the repo's root folder and same logic as the [exclude_folders][exclude_folders] property                                                                                                                                                                                                   |
| `fetch_upstream_icon` | `boolean`           | fetch upstream icon - defaults to `false`                                                                                                                                                                                                                                                                                             |
| `fetch_bare_info`     | `boolean`           | fetch bare repo info - defaults to `false`                                                                                                                                                                                                                                                                                            |
| `untracked_modes`     | `map[string]string` | map of repo's where to override the default [untracked files mode][untracked]:<ul><li>`no`</li><li>`normal`</li><li>`all`</li></ul>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][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`           | 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. Defaults to `false`                                                                                                        |
| `fetch_user`          | [`User`](#user)     | fetch the current configured user for the repository - defaults to `false`                                                                                                                                                                                                                                                            |
| `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](#status) section for available overrides. Defaults to an empty map.                                           |

### Icons

#### Branch

| Name                    | Type     | Description                                                                                  |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------- |
| `branch_icon`           | `string` | the icon to use in front of the git branch name - defaults to `\uE0A0 `                      |
| `branch_identical_icon` | `string` | the icon to display when remote and local are identical - defaults to `\u2261`               |
| `branch_ahead_icon`     | `string` | the icon to display when the local branch is ahead of its remote - defaults to `\u2191`      |
| `branch_behind_icon`    | `string` | the icon to display when the local branch is behind its remote - defaults to `\u2193`        |
| `branch_gone_icon`      | `string` | the icon to display when there's no remote branch - defaults to `\u2262`                     |
| `branch_max_length`     | `int`    | the max length for the displayed branch name where `0` implies full length - defaults to `0` |
| `truncate_symbol`       | `string` | the icon to display when a branch name is truncated - defaults to empty                      |

#### HEAD

| Name               | Type     | Description                                                                              |
| ------------------ | -------- | ---------------------------------------------------------------------------------------- |
| `commit_icon`      | `string` | icon/text to display before the commit context (detached HEAD) - defaults to `\uF417`    |
| `tag_icon`         | `string` | icon/text to display before the tag context - defaults to `\uF412`                       |
| `rebase_icon`      | `string` | icon/text to display before the context when in a rebase - defaults to `\uE728 `         |
| `cherry_pick_icon` | `string` | icon/text to display before the context when doing a cherry-pick - defaults to `\uE29B ` |
| `revert_icon`      | `string` | icon/text to display before the context when doing a revert - defaults to `\uF0E2 `      |
| `merge_icon`       | `string` | icon/text to display before the merge context - defaults to `\uE727 `                    |
| `no_commits_icon`  | `string` | icon/text to display when there are no commits in the repo - defaults to `\uF594 `       |

#### Upstream

| Name                | Type                | Description                                                                                                                                                                  |
| ------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `github_icon`       | `string`            | icon/text to display when the upstream is Github - defaults to `\uF408 `                                                                                                     |
| `gitlab_icon`       | `string`            | icon/text to display when the upstream is Gitlab - defaults to `\uF296 `                                                                                                     |
| `bitbucket_icon`    | `string`            | icon/text to display when the upstream is Bitbucket - defaults to `\uF171 `                                                                                                  |
| `azure_devops_icon` | `string`            | icon/text to display when the upstream is Azure DevOps - defaults to `\uEBE8 `                                                                                               |
| `git_icon`          | `string`            | icon/text to display when the upstream is not known/mapped - defaults to `\uE5FB `                                                                                           |
| `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 |

## Template ([info][templates])

:::note default template

```template
{{ .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 }}
```

:::

### Properties

| Name             | Type      | Description                                                                                                                      |
| ---------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `.RepoName`      | `string`  | the repo folder name                                                                                                             |
| `.Working`       | `Status`  | changes in the worktree (see below)                                                                                              |
| `.Staging`       | `Status`  | staged changes in the work tree (see below)                                                                                      |
| `.HEAD`          | `string`  | 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                                                                                                        |
| `.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][hyperlinks] in templates: `{{ url .UpstreamIcon .UpstreamURL }}`                        |
| `.StashCount`    | `int`     | the stash count                                                                                                                  |
| `.WorktreeCount` | `int`     | the worktree count                                                                                                               |
| `.IsWorkTree`    | `boolean` | if in a worktree repo or not                                                                                                     |
| `.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                                                                                                  |
| `.Kraken`        | `string`  | a link to the current HEAD in [GitKraken][kraken-ref] for use in [hyperlinks][hyperlinks] in templates `{{ url .HEAD .Kraken }}` |
| `.Commit`        | `Commit`  | HEAD commit information (see below)                                                                                              |

### Status

| Name         | Type      | Description                                  |
| ------------ | --------- | -------------------------------------------- |
| `.Unmerged`  | `int`     | number of unmerged changes                   |
| `.Deleted`   | `int`     | number of deleted changes                    |
| `.Added`     | `int`     | number of added changes                      |
| `.Modified`  | `int`     | number of modified changes                   |
| `.Untracked` | `int`     | number of untracked changes                  |
| `.Changed`   | `boolean` | if the status contains changes or not        |
| `.String`    | `string`  | a string representation of the changes above |

Local changes use the following syntax:

| Icon | Description |
| ---- | ----------- |
| `x`  | Unmerged    |
| `-`  | Deleted     |
| `+`  | Added       |
| `~`  | Modified    |
| `?`  | Untracked   |

### Commit

| Name         | Type        | Description                            |
| ------------ | ----------- | -------------------------------------- |
| `.Author`    | `User`      | the author of the commit (see below)   |
| `.Committer` | `User`      | the comitter of the commit (see below) |
| `.Subject`   | `string`    | the commit subject                     |
| `.Timestamp` | `time.Time` | the commit timestamp                   |

### User

| Name     | Type     | Description      |
| -------- | -------- | ---------------- |
| `.Name`  | `string` | the user's name  |
| `.Email` | `string` | the user's email |

[poshgit]: https://github.com/dahlbyk/posh-git
[templates]: /docs/configuration/templates
[hyperlinks]: /docs/configuration/templates#custom
[untracked]: https://git-scm.com/docs/git-status#Documentation/git-status.txt---untracked-filesltmodegt
[submodules]: https://git-scm.com/docs/git-status#Documentation/git-status.txt---ignore-submodulesltwhengt
[kraken-ref]: https://www.gitkraken.com/invite/nQmDPR9D
[text]: text.mdx
[exclude_folders]: /docs/configuration/segment#include--exclude-folders