TOPIC

posh-git

SHORT DESCRIPTION
posh-git integrates Git and PowerShell providing tab completion of Git
commands, branch names, paths and more. It also provides Git status
summary information that can be 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.

posh-git will install a prompt function if it detects the user does not
have their own, customized prompt. This prompt displays Git status summary
information when the current directory is located in a Git repository.

RELEASE NOTES
See https://github.com/dahlbyk/posh-git/blob/master/CHANGELOG.md

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

POWERSHELL PROMPT
PowerShell generates its prompt by executing a function named "prompt", if
one exists. posh-git will install its prompt function if it detects the
user does not have their own, customized prompt function. The posh-git
prompt displays the current working directory followed by git status
summary information if the current directory is located in a Git
repository, e.g.:

C:\GitHub\posh-git [master ≡]>

You can customize the posh-git prompt using various settings in the
$GitPromptSettings variable. For details see:
https://github.com/dahlbyk/posh-git/blob/master/README.md#customizing-the-posh-
git-prompt
GIT STATUS SUMMARY
[{HEAD-name} S +A ~B -C !D | +E ~F -G !H W]

* [ (BeforeStatus)
* {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.

Note: This status information reflects the state of the remote tracked
branch after the last `git fetch/pull` of the remote. Execute
`git fetch` to update to the latest on the default remote repo. If you
have multiple remotes, execute `git fetch --all`.

* ≡ = Local branch is at the same commit level as the remote

branch (BranchIdenticalStatus).
* ↑<num> = Local branch is ahead of the remote branch by the specified
number of commits; a 'git push' is required to update the
remote branch (BranchAheadStatus).
* ↓<num> = Local branch is behind the remote branch by the specified
number of commits; a 'git pull' is required to update the
local branch (BranchBehindStatus).
* <a>↕<b>= Local branch is both ahead of the remote branch by the
specified number of commits (<a>) and behind by the
specified number of commits (<b>); a rebase of the local
branch is required before pushing local changes to the
remote branch (BranchBehindAndAheadStatus). NOTE: this
status is only available if
$GitPromptSettings.BranchBehindAndAheadDisplay is set to
'Compact'.
* × = 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 overall status of the working directory

* ! = There are unstaged changes (LocalWorkingStatusSymbol)
* ~ = There are uncommitted changes i.e. staged changes waiting to be
committed (LocalStagedStatusSymbol)
* None = There are no unstaged or uncommitted changes
(LocalDefaultStatusSymbol)
* ] (AfterStatus)

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

You need to import the posh-git module into your PowerShell session to
use it. Execute "Import-Module posh-git" to do this. After posh-git has
been imported, you can execute the command "Add-PoshGitToProfile" to have
your PowerShell profile updated to import posh-git whenever PowerShell
starts.

When posh-git is imported it will provide a basic prompt function that

displays Git status summary information, unless you have your own, custom
prompt function. Prompt formatting, among other things, can be customized
using the global variables: $GitPromptSettings, $GitTabSettings and
$TortoiseGitSettings. To see the available settings, simply type the
variable name at the PowerShell prompt (after posh-git has been imported)
and press Enter.

For more information on customizing the posh-git default prompt or creating

your own prompt fuction see:

https://github.com/dahlbyk/posh-git/blob/master/README.md#customizing-the-posh-
git-prompt

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.

Remove-GitBranch:
Deletes the specified Git branches that have been merged into the commit
specified by the Commit parameter (HEAD by default). You must either
specify a branch name via the Name parameter, which accepts wildard
characters, or via the Pattern parameter, which accepts a regular
expression.
 Write-GitStatus:
Given a status object returned by Get-GitStatus, this command formats it
as described above in the GIT STATUS PROMPT section. On a host that
supports virtual terminal sequences and where
$GitPromptSettings.AnsiConsole is set to $true, the prompt text is
returned by the function as a string which may contain ANSI escape
sequences. Otherise, the prompt text is written directly to the host.

Write-VcsStatus:
Gets the Git repository information and formats it, as described
above in the GIT STATUS PROMPT section. On a host that supports virtual
terminal sequences and where $GitPromptSettings.AnsiConsole is set to
$true, the prompt text is returned by the function as a string which
may contain ANSI escape sequences. Otherise, the prompt text is written
directly to the host.

This command can be used with other version control systems that append
a scriptblock, which uses Write-Prompt to supply their prompt text, to
$global:VcsPromptStatuses.

BASED ON WORK BY:

Keith Dahlby, http://solutionizing.net/
Mark Embling, http://www.markembling.info/
Jeremy Skinner, http://www.jeremyskinner.co.uk/