mudhorn/oh-my-posh
1
0
Fork 0
mirror of https://github.com/JanDeDobbeleer/oh-my-posh.git synced 2024-11-15 07:24:04 -08:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity
oh-my-posh/website/docs/segments/git.mdx

156 lines
13 KiB
Plaintext
Raw Normal View History

feat: add docs
2020-10-05 02:33:12 -07:00
---
id: git
title: Git
sidebar_label: Git
---
## What
docs: add git executable version info relates to #753
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).
docs: add wsl executable info
2021-09-01 04:45:33 -07:00
:::tip
feat(posh-git): parse environment variable BREAKING CHANGE: this removes the posh-git segment. To mitigate, rename the posh-git segment to git. In case you had a custom template, make sure to migrate to the git segment's template. You can now also leverage the same logic and properties as the git segment in both the text template and/or color templates.
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.
To enable this, set `$env:POSH_GIT_ENABLED = $true` in your `$PROFILE`. This will also make use of the
[posh-git][poshgit] output rather than do additional work to get the git status.
docs: display_status warning in git segment doc + issue template updated
2021-05-28 04:28:00 -07:00
:::
feat: add docs
2020-10-05 02:33:12 -07:00
## Sample Configuration
```json
{
"type": "git",
"style": "powerline",
refactor: replace powerline icon
2020-10-15 23:37:43 -07:00
"powerline_symbol": "\uE0B0",
feat: add docs
2020-10-05 02:33:12 -07:00
"foreground": "#193549",
"background": "#ffeb3b",
docs(git): correct property definitions
2021-11-06 12:33:11 -07:00
"background_templates": [
fix(git): remove Repo struct
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 }}"
docs(git): correct property definitions
2021-11-06 12:33:11 -07:00
],
refactor(git): no leading space on branch status
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 }}",
feat: add docs
2020-10-05 02:33:12 -07:00
"properties": {
docs(git): correct property definitions
2021-11-06 12:33:11 -07:00
"fetch_status": true,
"fetch_stash_count": true,
feat(git): set untracked files mode resolves #2117
2022-04-21 23:11:20 -07:00
"fetch_upstream_icon": true,
"untracked_modes": {
"/Users/user/Projects/oh-my-posh/": "no"
}
feat: add docs
2020-10-05 02:33:12 -07:00
}
}
```
## Properties
docs(git): correct property definitions
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).
docs: tables for data this look a lot better
2022-09-16 07:32:48 -07:00
| Name | Type | Description |
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fetch_status` | `boolean` | fetch the local changes - defaults to `false` |
| `fetch_stash_count` | `boolean` | fetch stash count - defaults to `false` |
| `fetch_worktree_count` | `boolean` | fetch worktree count - defaults to `false` |
| `fetch_upstream_icon` | `boolean` | fetch upstream icon - 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` |
docs(git): correct property definitions
2021-11-06 12:33:11 -07:00
### Icons
#### Branch
feat(git): add upstream icons resolves #7
2020-10-11 10:28:29 -07:00
docs: tables for data this look a lot better
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 |
feat(git): add upstream icons resolves #7
2020-10-11 10:28:29 -07:00
docs(git): correct property definitions
2021-11-06 12:33:11 -07:00
#### HEAD
feat(git): add upstream icons resolves #7
2020-10-11 10:28:29 -07:00
docs: tables for data this look a lot better
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 ` |
feat(git): add upstream icons resolves #7
2020-10-11 10:28:29 -07:00
docs(git): correct property definitions
2021-11-06 12:33:11 -07:00
#### Upstream
feat(git): add upstream icons resolves #7
2020-10-11 10:28:29 -07:00
docs: tables for data this look a lot better
2022-09-16 07:32:48 -07: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 ` |
| `azure_devops_icon` | `string` | icon/text to display when the upstream is Azure DevOps - defaults to `\uFD03 ` |
| `git_icon` | `string` | icon/text to display when the upstream is not known/mapped - defaults to `\uE5FB ` |
feat: git area colors resolves #4
2020-10-18 03:30:27 -07:00
docs: add template information
2022-02-01 03:10:46 -08:00
## Template ([info][templates])
:::note default template
docs: tables for data this look a lot better
2022-09-16 07:32:48 -07:00
```template
refactor(git): no leading space on branch status
2022-09-06 22:01:52 -07: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 }}{{ if gt .StashCount 0}} \uF692 {{ .StashCount }}{{ end }}{{ if gt .WorktreeCount 0}} \uf1bb {{ .WorktreeCount }}{{ end }}
docs: add template information
2022-02-01 03:10:46 -08:00
```
:::
### Properties
docs(git): correct property definitions
2021-11-06 12:33:11 -07:00
docs: tables for data this look a lot better
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 |
| `.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 }}` |
docs(git): correct property definitions
2021-11-06 12:33:11 -07:00
### GitStatus
docs: tables for data this look a lot better
2022-09-16 07:32:48 -07: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 |
| `.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 |
| ---- | ----------- |
| `+` | added |
| `~` | modified |
| `-` | deleted |
| `?` | untracked |
docs(git): correct property definitions
2021-11-06 12:33:11 -07:00
fix: fix path to Posh-Git segment
2022-06-01 14:37:19 -07:00
[poshgit]: /docs/segments/poshgit
docs: move sections into folders
2022-04-20 09:43:59 -07:00
[templates]: /docs/configuration/templates
[hyperlinks]: /docs/configuration/templates#helper-functions
feat(git): set ignore-submodules flag resolves #2455
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
feat(git): add link to GitKraken
2022-09-01 10:49:17 -07:00
[kraken-ref]: https://www.gitkraken.com/invite/nQmDPR9D
Reference in a new issue Copy permalink