diff --git a/en-US/about_posh-git.help.txt b/en-US/about_posh-git.help.txt new file mode 100644 index 000000000..66e4b2b89 --- /dev/null +++ b/en-US/about_posh-git.help.txt @@ -0,0 +1,120 @@ +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 --> 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 --> 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 ..." to unstage) + # + # modified: this-changed.txt + # modified: this-too.txt + # deleted: gone.ps1 + # + # Changed but not updated: + # (use "git add ..." to update what will be committed) + # (use "git checkout -- ..." to discard changes in working directory) + # + # modified: not-staged.ps1 + # + # Untracked files: + # (use "git add ..." 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/