mirror of
https://github.com/JanDeDobbeleer/oh-my-posh.git
synced 2024-11-16 07:54:05 -08:00
228 lines
19 KiB
Plaintext
228 lines
19 KiB
Plaintext
---
|
|
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).
|
|
|
|
## 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 }} \uf0c7 {{ .StashCount }}{{ end }}",
|
|
properties: {
|
|
fetch_status: true,
|
|
fetch_upstream_icon: true,
|
|
untracked_modes: {
|
|
"/Users/user/Projects/oh-my-posh/": "no",
|
|
},
|
|
source: "cli",
|
|
mapped_branches: {
|
|
"feat/*": "🚀 ",
|
|
"bug/*": "🐛 ",
|
|
},
|
|
},
|
|
}}
|
|
/>
|
|
|
|
## 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 | Default | Description |
|
|
| --------------------- | :-----------------: | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `fetch_status` | `boolean` | `false` | fetch the local changes |
|
|
| `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` | `false` | fetch upstream icon |
|
|
| `fetch_bare_info` | `boolean` | `false` | fetch bare repo info |
|
|
| `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` | `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 |
|
|
| `fetch_user` | [`User`](#user) | `false` | fetch the current configured user for the repository |
|
|
| `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. |
|
|
| `source` | `string` | `cli` | <ul><li>`cli`: fetch the information using the git CLI</li><li>`pwsh`: fetch the information from the [posh-git][poshgit] PowerShell Module</li></ul> |
|
|
| `mapped_branches` | `object` | | custom glyph/text for specific branches. You can use `*` at the end as a wildcard character for matching |
|
|
| `full_branch_path` | `bool` | `true` | display the full branch path instead of only the last part (e.g. `feature/branch` instead of `branch`) |
|
|
|
|
### Icons
|
|
|
|
#### Branch
|
|
|
|
| Name | Type | Default | Description |
|
|
| ----------------------- | :------: | :------: | -------------------------------------------------------------------------- |
|
|
| `branch_icon` | `string` | `\uE0A0` | the icon to use in front of the git branch name |
|
|
| `branch_identical_icon` | `string` | `\u2261` | the icon to display when remote and local are identical |
|
|
| `branch_ahead_icon` | `string` | `\u2191` | the icon to display when the local branch is ahead of its remote |
|
|
| `branch_behind_icon` | `string` | `\u2193` | the icon to display when the local branch is behind its remote |
|
|
| `branch_gone_icon` | `string` | `\u2262` | the icon to display when there's no remote branch |
|
|
| `branch_max_length` | `int` | `0` | the max length for the displayed branch name where `0` implies full length |
|
|
| `truncate_symbol` | `string` | | the icon to display when a branch name is truncated |
|
|
|
|
#### HEAD
|
|
|
|
| Name | Type | Default | Description |
|
|
| ------------------ | :------: | :------: | ---------------------------------------------------------------- |
|
|
| `commit_icon` | `string` | `\uF417` | icon/text to display before the commit context (detached HEAD) |
|
|
| `tag_icon` | `string` | `\uF412` | icon/text to display before the tag context |
|
|
| `rebase_icon` | `string` | `\uE728` | icon/text to display before the context when in a rebase |
|
|
| `cherry_pick_icon` | `string` | `\uE29B` | icon/text to display before the context when doing a cherry-pick |
|
|
| `revert_icon` | `string` | `\uF0E2` | icon/text to display before the context when doing a revert |
|
|
| `merge_icon` | `string` | `\uE727` | icon/text to display before the merge context |
|
|
| `no_commits_icon` | `string` | `\uF594` | icon/text to display when there are no commits in the repo |
|
|
|
|
#### Upstream
|
|
|
|
| Name | Type | Default | Description |
|
|
| ------------------- | :-----------------: | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `github_icon` | `string` | `\uF408` | icon/text to display when the upstream is Github |
|
|
| `gitlab_icon` | `string` | `\uF296` | icon/text to display when the upstream is Gitlab |
|
|
| `bitbucket_icon` | `string` | `\uF171` | 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 |
|
|
|
|
## 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) |
|
|
| `.Detached` | `boolean` | true when the head is detached |
|
|
| `.Merge` | `boolean` | true when in a merge |
|
|
| `.Rebase` | `boolean` | true when in a rebase |
|
|
| `.CherryPick` | `boolean` | true when in a cherry pick |
|
|
| `.Revert` | `boolean` | true when in a revert |
|
|
| `.LatestTag` | `string` | the latest tag name |
|
|
|
|
### 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 committer of the commit (see below) |
|
|
| `.Subject` | `string` | the commit subject |
|
|
| `.Timestamp` | `time.Time` | the commit timestamp |
|
|
| `.Sha` | `string` | the commit SHA1 |
|
|
| `.Refs` | `Refs` | the commit references |
|
|
|
|
### User
|
|
|
|
| Name | Type | Description |
|
|
| -------- | -------- | ---------------- |
|
|
| `.Name` | `string` | the user's name |
|
|
| `.Email` | `string` | the user's email |
|
|
|
|
### Refs
|
|
|
|
| Name | Type | Description |
|
|
| ---------- | ---------- | ----------------- |
|
|
| `.Heads` | `[]string` | branches |
|
|
| `.Tags` | `[]string` | commit's tags |
|
|
| `.Remotes` | `[]string` | remote references |
|
|
|
|
As these are arrays of strings, you can join them using the `join` function:
|
|
|
|
```template
|
|
{{ join ", " .Commit.Refs.Tags }}
|
|
```
|
|
|
|
## posh-git
|
|
|
|
If you want to display the default [posh-git][poshgit] output, **do not** use this segment
|
|
but 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 }}"
|
|
```
|
|
|
|
[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]: /docs/segments/system/text
|
|
[exclude_folders]: /docs/configuration/segment#include--exclude-folders
|