about_posh-git.help.txt

TOPIC
    Posh-Git

SHORT DESCRIPTION
    A set of PowerShell scripts which provide Git/PowerShell integration.

LONG DESCRIPTION
    posh-git enables better Git/PowerShell integration via two primary
    features: a Git prompt that displays Git repository status information as
    part of your PowerShell prompt and tab completion for git.exe commands
    and branch names.

GIT TAB COMPLETION
    You can tab complete most common Git commands e.g.:

    C:\GitHub\posh-git> git ch<tab> --> git checkout

    You can also tab complete branch names.  Assume you are current on the
    develop branch and want to checkout master e.g.:

    C:\GitHub\posh-git> git checkout ma<tab> --> git checkout master

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`)

      * 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/