2020-10-05 02:33:12 -07:00
---
id: git
title: Git
sidebar_label: Git
---
## What
2021-06-03 10:55:08 -07:00
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).
2021-09-01 04:45:33 -07:00
:::tip
2022-09-06 22:02:23 -07:00
PowerShell offers support for the [posh-git][poshgit] module for autocompletion, but it is disabled by default.
2022-09-25 23:10:33 -07:00
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.
2022-09-25 00:10:40 -07:00
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 }}"
```
2022-10-09 23:55:20 -07:00
2021-05-28 04:28:00 -07:00
:::
2020-10-05 02:33:12 -07:00
## Sample Configuration
```json
{
"type": "git",
"style": "powerline",
2020-10-15 23:37:43 -07:00
"powerline_symbol": "\uE0B0",
2020-10-05 02:33:12 -07:00
"foreground": "#193549",
"background": "#ffeb3b",
2021-11-06 12:33:11 -07:00
"background_templates": [
2021-11-09 08:13:47 -08:00
"{{ 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 }}"
2021-11-06 12:33:11 -07:00
],
2022-09-06 22:01:52 -07:00
"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 }}",
2020-10-05 02:33:12 -07:00
"properties": {
2021-11-06 12:33:11 -07:00
"fetch_status": true,
"fetch_stash_count": true,
2022-04-21 23:11:20 -07:00
"fetch_upstream_icon": true,
"untracked_modes": {
"/Users/user/Projects/oh-my-posh/": "no"
}
2020-10-05 02:33:12 -07:00
}
}
```
## Properties
2021-11-06 12:33:11 -07:00
### 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).
2023-01-05 23:06:34 -08:00
| Name | Type | Description |
| --------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fetch_status` | `boolean` | fetch the local changes - defaults to `false` |
2023-01-26 06:56:47 -08:00
| `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 |
2023-01-05 23:06:34 -08:00
| `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` |
2021-11-06 12:33:11 -07:00
### Icons
#### Branch
2020-10-11 10:28:29 -07:00
2022-09-16 07:32:48 -07:00
| 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 |
2020-10-11 10:28:29 -07:00
2021-11-06 12:33:11 -07:00
#### HEAD
2020-10-11 10:28:29 -07:00
2022-09-16 07:32:48 -07:00
| 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 ` |
2020-10-11 10:28:29 -07:00
2021-11-06 12:33:11 -07:00
#### Upstream
2020-10-11 10:28:29 -07:00
2023-01-05 23:06:34 -08:00
| 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 ` |
2023-01-10 03:37:50 -08:00
| `azure_devops_icon` | `string` | icon/text to display when the upstream is Azure DevOps - defaults to `\uEBE8 ` |
2023-01-05 23:06:34 -08:00
| `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 |
2020-10-18 03:30:27 -07:00
2022-02-01 03:10:46 -08:00
## Template ([info][templates])
:::note default template
2022-09-16 07:32:48 -07:00
```template
2022-12-28 01:13:25 -08:00
{{ .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 }}
2022-02-01 03:10:46 -08:00
```
:::
### Properties
2021-11-06 12:33:11 -07:00
2022-09-16 07:32:48 -07:00
| Name | Type | Description |
| ---------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `.RepoName` | `string` | the repo folder name |
| `.Working` | `GitStatus` | changes in the worktree (see below) |
| `.Staging` | `GitStatus` | 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 |
2022-10-12 11:08:45 -07:00
| `.IsBare` | `boolean` | if in a bare repo or not, only set when `fetch_bare_info` is set to `true` |
2022-09-16 07:32:48 -07:00
| `.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 }}` |
2023-01-08 11:31:44 -08:00
| `.Commit` | `Commit` | HEAD commit information (see below) |
2021-11-06 12:33:11 -07:00
### GitStatus
2022-12-28 01:13:25 -08:00
| 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 |
2022-09-16 07:32:48 -07:00
2023-01-08 11:31:44 -08:00
### Commit
| Name | Type | Description |
| ------------ | ----------- | -------------------------------------- |
2023-02-16 06:18:21 -08:00
| `.Author` | `User` | the author of the commit (see below) |
| `.Committer` | `User` | the comitter of the commit (see below) |
2023-01-08 11:31:44 -08:00
| `.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 |
2022-09-16 07:32:48 -07:00
Local changes use the following syntax:
| Icon | Description |
| ---- | ----------- |
| `+` | added |
| `~` | modified |
| `-` | deleted |
| `?` | untracked |
2021-11-06 12:33:11 -07:00
2022-09-22 23:05:06 -07:00
[poshgit]: https://github.com/dahlbyk/posh-git
2022-04-20 09:43:59 -07:00
[templates]: /docs/configuration/templates
2023-01-17 09:44:05 -08:00
[hyperlinks]: /docs/configuration/templates#custom
2022-06-30 09:01:53 -07:00
[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
2022-09-01 10:49:17 -07:00
[kraken-ref]: https://www.gitkraken.com/invite/nQmDPR9D
2022-09-25 00:10:40 -07:00
[text]: text.mdx
2023-01-26 06:56:47 -08:00
[exclude_folders]: /docs/configuration/segment#include--exclude-folders
