/
about_posh-git.help.txt
136 lines (111 loc) · 5.83 KB
/
about_posh-git.help.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
TOPIC
posh-git
SHORT DESCRIPTION
posh-git integrates Git and PowerShell with tab completion and Git
status summary information displayed in the PowerShell prompt.
LONG DESCRIPTION
posh-git integrates Git and PowerShell. Tab completion is supported for
Git subcommands, branch and remote names. Git also provides commands to
display colored Git status summary information. If you would like fine
grained control over how the Git status summary information is displayed
in your prompt function, you can get the raw status summary information
via the Get-GitStatus command. Then you can display the information in
your prompt however you would like.
GIT TAB COMPLETION
You can tab complete most common Git subcommands e.g.:
C:\GitHub\posh-git> git ch<tab> --> git checkout
You can also tab complete branch names and even remote names such as
origin and upstream. For instance, type the following inside of a Git
repo to see tab completion in action:
C:\GitHub\posh-git> git fe<tab> or<tab> ma<tab>
The above will expand to:
C:\GitHub\posh-git> git fetch origin master
And like tab completion in other parts of PowerShell, you can press tab
multiple times to cycle through all matches. For instance, type
"git ch" and press the tab key multiple times to cycle through "checkout",
"cherry" and "cherry-pick".
GIT STATUS PROMPT
PowerShell generates its prompt by executing a prompt function, if one
exists. posh-git defines such a function in the included
profile.example.ps1 script file that outputs the current working directory
followed by an abbreviated git status summary e.g.:
C:\GitHub\posh-git [master ≡]>
[{HEAD-name} S +A ~B -C !D | +E ~F -G !H W]
* [ (BeforeText)
* {HEAD-name} is the current branch, or the SHA of a detached HEAD
* Cyan means the branch matches its remote
* Green means the branch is ahead of its remote (green light to push)
* Red means the branch is behind its remote
* Yellow means the branch is both ahead of and behind its remote
* S represents the branch status in relation to remote (tracked origin) branch
* ≡ = Local branch is at the same commit level as the remote branch
(BranchIdenticalStatus)
* ↑ = Local branch is ahead of the remote branch; a 'git push' is
required to update the remote branch (BranchAheadStatus)
* ↓ = Local branch is behind the remote branch; a 'git pull' is
required to update the local branch (BranchBehindStatus)
* ↕ = Local branch is both ahead and behind the remote branch; a
rebase of the local branch is required before pushing local
changes to the remote branch (BranchBehindAndAheadStatus)
* × = The local branch is tracking a branch that is gone from the remote
(BranchGoneStatus)
* ABCD represents the index | EFGH represents the working directory
* + = Added files
* ~ = Modified files
* - = Removed files
* ! = Conflicted files
* Index status is dark green and working directory status is dark red
reflecting the colors used by 'git status'.
* W represents the status of the working directory
* ! = There are untracked changes (LocalStagedStatus)
* ~ = There are staged changes waiting to be committed (LocalWorkingStatus)
* None = There are no uncommitted or unstaged changes (LocalDefault)
* ] (AfterText)
The (symbols) and surrounding text can be customized by the corresponding
properties of the global variable $GitPromptSettings.
For example, a status summary of [master ≡ +0 ~2 -1 | +1 ~1 -0 !]
corresponds to the following 'git status':
# On branch master
#
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: this-changed.txt
# modified: this-too.txt
# deleted: gone.ps1
#
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: not-staged.ps1
#
# Untracked files:
# (use "git add <file>..." to include in what will be committed)
#
# new.file
USAGE AND CUSTOMIZATION
See profile.example.ps1 for an example of how you can integrate the tab
completion and/or git prompt into your own profile. Prompt formatting,
among other things, can be customized using the global variables
$GitPromptSettings, $GitTabSettings and $TortoiseGitSettings.
PERFORMANCE
Displaying Git status in your prompt for a very large repository can
be prohibitively slow. Rather than turn off Git status entirely, you can
disable it on a repo-by-repo basis by adding individual repository paths
to $GitPromptSettings.RepositoriesInWhichToDisableFileStatus.
PRIMARY COMMANDS
Get-GitStatus:
Returns information about the current Git repository as
well as the index and working directory.
Write-GitStatus:
Writes directly to host the formatted text, as described above in the
GIT STATUS PROMPT section, when passed in the repository information
returned by Get-GitStatus e.g. Write-GitStatus (Get-GitStatus)
Write-VcsStatus:
Gets the Git repository information and writes it formatted, as described
above in the GIT STATUS PROMPT section, directly to the host.
BASED ON WORK BY:
Keith Dahlby, http://solutionizing.net/
Mark Embling, http://www.markembling.info/
Jeremy Skinner, http://www.jeremyskinner.co.uk/