DOCSEARCHbyAlgolia
Submit Docs

posh-git

repository·master·Indexed 27 days ago

https://github.com/dahlbyk/posh-git

A PowerShell module that integrates Git status information into the PowerShell prompt and provides advanced tab completion for Git commands, branches, and remotes. It includes features for customizing the prompt via $GitPromptSettings, managing merged branches with Remove-GitBranch, and retrieving raw repository data using Get-GitStatus. Compatible with Windows PowerShell 5.x and PowerShell Core 6.0+.

Tokens
3K
Snippets
9
Records
22
Agent score
94%

What's inside posh-git

  1. Overview of posh-git

    master

    posh-git is a PowerShell module that integrates Git and PowerShell. It provides:

    1. Git status summary information: Displays Git status directly in the PowerShell prompt.
    2. Tab completion: Provides tab completion for common Git commands (e.g., git checkout), branch names, remote names, and paths.

  2. Prerequisites for installing posh-git v1.x

    master

    Before installing posh-git v1.x, ensure the following requirements are met:

    1. PowerShell: Windows PowerShell 5.x or PowerShell Core 6.0+.
      • Check version with: $PSVersionTable.PSVersion.
    2. Execution Policy (Windows only): Must be set to RemoteSigned or Unrestricted.
      • Check with: Get-ExecutionPolicy.
      • Set with (as Administrator): Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Confirm.
    3. Git: Must be installed and available in your PATH.
      • Check with: git --version.

  3. Configure Git prompt settings via $GitPromptSettings

    master

    You can customize the posh-git prompt by modifying properties on the $GitPromptSettings object in your PowerShell profile. To make changes permanent, place these settings in your profile script after the line that imports the posh-git module.

    Common Customizations

    Add a colored timestamp to the prefix:

    $GitPromptSettings.DefaultPromptPrefix.Text = '$(Get-Date -f "MM-dd HH:mm:ss") '
$GitPromptSettings.DefaultPromptPrefix.ForegroundColor = [ConsoleColor]::Magenta

    Disable home directory abbreviation (~):

    $GitPromptSettings.DefaultPromptAbbreviateHomeDirectory = $false

    Change path color (Windows):

    $GitPromptSettings.DefaultPromptPath.ForegroundColor = 'Orange'

    Change path color (Linux/macOS using RGB):

    $GitPromptSettings.DefaultPromptPath.ForegroundColor = 0xFFA500

    Create a two-line prompt:

    $GitPromptSettings.DefaultPromptBeforeSuffix.Text = '`n'

    Swap path and Git status order:

    $GitPromptSettings.DefaultPromptWriteStatusFirst = $true

    Add delimiters to the path:

    $GitPromptSettings.BeforePath = '{'
$GitPromptSettings.AfterPath = '}'
$GitPromptSettings.BeforePath.ForegroundColor = 'Red'
$GitPromptSettings.AfterPath.ForegroundColor = 'Red'

  4. Optimize performance for large repositories

    master
    Displaying file status in the Git prompt can be slow for very large repositories. Instead of disabling file status globally via $GitPromptSettings.EnableFileStatus = $false, you can disable it for specific repositories by adding their paths to $GitPromptSettings.RepositoriesInWhichToDisableFileStatus.

  5. Use Git tab completion in PowerShell

    master

    posh-git provides tab completion for common Git subcommands, branch names, and remote names (like origin or upstream).

    • Subcommands: Type git ch<tab> to expand to git checkout.
    • Branches/Remotes: Type git fe<tab> or git ma<tab> to expand to git fetch origin master.
    • Cycling: Press the Tab key multiple times to cycle through all available matches (e.g., cycling through checkout, cherry, and cherry-pick).

  7. Install posh-git via PowerShellGet

    master

    You can install posh-git on Linux, macOS, and Windows using the PowerShell Gallery. Run these commands from an elevated PowerShell prompt.

    If you have never installed posh-git before:

    PowerShellGet\Install-Module posh-git -Scope CurrentUser -Force

    If you are updating an existing installation:

    PowerShellGet\Update-Module posh-git
    # (A) You've never installed posh-git from the PowerShell Gallery
PowerShellGet\Install-Module posh-git -Scope CurrentUser -Force

# (B) You've already installed a previous version of posh-git from the PowerShell Gallery
PowerShellGet\Update-Module posh-git

  8. Configure posh-git for your PowerShell session

    master

    After installation, you must import the module and configure your profile so it loads automatically in new sessions.

    1. Import the module

    Run Import-Module posh-git to enable features in the current session.

    2. Automate loading via Profile

    Use the Add-PoshGitToProfile command to add the import command to your profile scripts:

    • Current host only: Add-PoshGitToProfile (modifies $profile.CurrentUserCurrentHost)
    • All hosts (Console, ISE, etc.) for current user: Add-PoshGitToProfile -AllHosts (modifies $profile.CurrentUserAllHosts)
    • All users on the system (requires Admin/sudo): Add-PoshGitToProfile -AllUsers -AllHosts (modifies $profile.AllUsersAllHosts)
    • All users, current host only: Add-PoshGitToProfile -AllUsers (modifies $profile.AllUsersCurrentHost)

  9. Install posh-git manually

    master

    To install without a package manager (useful for testing or debugging), import the module directly from the source path using Import-Module pointing to the .psd1 file.

    Import-Module <path-to-src\posh-git.psd1>
# Example:
Import-Module ~\git\posh-git\src\posh-git.psd1

  11. Install and setup posh-git

    master

    To use posh-git, you must import the module into your current PowerShell session. To ensure it loads automatically every time you start PowerShell, use the Add-PoshGitToProfile command after importing.

    1. Import the module for the current session: Import-Module posh-git
    2. Make the import permanent in your PowerShell profile: Add-PoshGitToProfile
    Import-Module posh-git
Add-PoshGitToProfile