Misc. Git Utility Module - Help, Applying Stash by Message, Deleting Merged Branches etc.

My-GitUtilities.psm1

$instructionColor = "green"
$headerColor = "yellow"
$cheatCategories = @("branch", "commit", "diff", "history", "remote", "stage", "stash", "undo")

function Get-GitCheatSheet
{
    [CmdletBinding()]
    [Alias("Git-Cheat")]
    PARAM ( 
        [Parameter(Mandatory=$false, Position=0)]
        [string] $category
    )

    $validCategoriesText = "`n    " + ($cheatCategories -join "`n    ")
   
    if (!$category) {
        
        Write-Host "Specify a category: $validCategoriesText"
        return
    }

    Write-Host

    #TODO: way to map string key to PS function to be called?
    switch  ($category)
    { 
        "branch"    {Get-CheatBranch}
        "commit"    {Get-CheatCommit} 
        "diff"      {Get-CheatDiff}
        "history"   {Get-CheatHistory}
        "remote"    {Get-CheatRemote}
        "stage"     {Get-CheatStage}
        "stash"     {Get-CheatStash}
        "undo"      {Get-CheatUndo}
        Default     {Write-Warning "Specify a valid category: $validCategoriesText"}
    }

    Write-Host
}

function Get-CheatBranch 
{
    Write-CheatHeader "Branching and Merging"

    Write-CheatInstruction "Create a new branch and switch to it"
    "git checkout -b Feature/Name`n"

    Write-CheatInstruction "Switch to another branch"
    "git checkout Feature/Name`n"

    Write-CheatInstruction "Merge sourceBranch into current branch"
    "git merge sourceBranch`n"

    Write-CheatInstruction "Listing all local branches"
    "git branch`n"

    Write-CheatInstruction "Listing specific local branches"
    "git branch --list fix/*`n"

    Write-CheatInstruction "Listing all remote branches"
    "git branch -r`n"

    Write-CheatInstruction "Delete branch"
    "git branch -d branchName`n"

    Write-CheatInstruction "Remove all merged branches (custom function)"
    "Remove-MergedBranches`n"  
}

function Get-CheatCommit
{
    Write-CheatHeader "Commit"

    Write-CheatInstruction "Commit with multi-line message"
    "git commit -m 'Brief summary of change line 1
WC-### More detailed message here'`n"

    Write-CheatInstruction "Commit with adding tracked files"
    "git commit -am 'commit message'`n"

    Write-CheatInstruction "Amend last commit message (ensure no staged files)"
    "git commit --amend -m 'Better commit message'`n"    
}

function Get-CheatDiff{
    Write-CheatHeader "Diff"

    Write-CheatInstruction "View commit details and diff"
    "git show 50994e9`n"

    Write-CheatInstruction "View commit in difftool w/previous commit (alias)"
    "git difftool"
    "git difftool 50994e9~2 50994e9"

    Write-CheatInstruction "Show unstaged changes"
    "git diff`n"

    Write-CheatInstruction "Show staged changes"
    "git diff --cached`n"

    Write-CheatInstruction "Show unstaged and staged changes"
    "git diff HEAD`n"

    Write-CheatInstruction "Show file changed diffs compared to local repo"
    "git diff HEAD *File.ext"
    "git difftool HEAD *File.ext`n"

    Write-CheatInstruction "Directory changes - see all changed files"
    "git difftool HEAD -d`n"
}

function Get-CheatHistory
{
    Write-CheatHeader "History"

    Write-CheatInstruction "Custom history (git log) - All"
    "git history`n"

    Write-CheatInstruction "Custom history (git log) - Last 10 Commits"
    "git history`n"

    Write-CheatInstruction "Custom history (git log) - Recent Commits"
    "git history --after=""2 days ago""`n"

    Write-CheatInstruction "Custom history graph (git log) - Last 10 Commits"
    "git graph`n"
}

function Get-CheatRemote
{
    Write-CheatHeader "Remotes"
	
    Write-CheatInstruction "Show local/remote mapping"
    "git remote show origin`n"

    Write-CheatInstruction "Initial push to remote branch (local/remote mapping)"
    "git push -u origin Feature/Name`n"

    Write-CheatInstruction "Push to explicit remote branch"
    "git push origin Feature/Name"
}

function Get-CheatStage
{
    Write-CheatHeader "Staging"

    Write-CheatInstruction "Stage all/some files"
    "git add .`n"
    "git add *.cs`n"

    Write-CheatInstruction "Remove all untracked files/dir"
    "git clean -df`n"

    Write-CheatInstruction "Unstage certain files"
    "git reset -- *Order*.cs`n"    
}

function Get-CheatStash
{
    Write-CheatHeader "Stashes"

    Write-CheatInstruction "Save work in named stash and undo"
    "git save MyStashName`n"

    Write-CheatInstruction "List stashes"
    "git stash list`n"

    Write-CheatInstruction "Reapply last stash (index 0)"
    "git stash apply 'stash@{0}'`n"

    Write-CheatInstruction "Apply stash with message (custom function)"
    "Apply-Stash MyStashName -drop"
    "Restore-Stash MyStashName`n"
    
    Write-CheatInstruction "Delete stash at index 4"
    "git stash drop 'stash@{4}'`n"
}

function Get-CheatUndo
{
    Write-CheatHeader "Undo"

    Write-CheatInstruction "Undo staging of specified files for next commit"
    "git reset -- *Order*.cs`n"

    Write-CheatInstruction "Revert specified file(s) to last commit (HEAD default)"
    "git checkout HEAD -- /path/file.ext"
    "git checkout -- /path/file.ext"
    "git checkout -- *index.html`n"

    Write-CheatInstruction "Revert specified file(s) to specific commit"
    "git checkout commitId /path/file.ext`n"

    Write-CheatInstruction "Undo last N commits, keep changes staged"
    "git reset --soft HEAD~1"
    "git reset --soft HEAD~2`n"

    Write-CheatInstruction "Undo last N commits, unstage changes (mixed default)"
    "git reset --mixed HEAD~1`n"

    Write-CheatInstruction "Undo last N commits, delete changes (CAUTION!!!)"
    "git reset --hard HEAD~1`n"

    Write-CheatInstruction "Undo specified commit and apply as new commit"
    "git revert commitId"
    "git revert commitId --no-edit`n"

    Write-Host "Favor git reset on unpushed commits, git revert on pushed commits"
}

function Get-GitCommand
{
    [CmdletBinding()]
    [Alias("Git-Command")]
    PARAM ( 
        [Parameter(Mandatory=$true, Position=0)] [string] $command
    )

    $c = ($command -replace "git ", "")
    $url="https://git-scm.com/docs/git-$c"
    Start-Process $url
    "Launched $url"
}

Function New-Underline
{
[CmdletBinding()]
param(
      [Parameter(Mandatory = $true,Position = 0,valueFromPipeline=$true)]
      [string]
      $stringIN,

      [string]
      $char = "_"
 )
  $underLine= $char * $stringIn.length
  $stringIn
  "`n$underLine"
}

function Remove-MergedBranches
{
    git branch --merged | %{$_.trim()} | ?{$_ -notmatch 'develop' -and $_ -notmatch 'master'} | %{git branch -d $_}
}

<#
.SYNOPSIS
Restores (applies) a previously saved stash based on full or partial stash name.

.DESCRIPTION
Restores (applies) a previously saved stash based on full or partial stash name and then optionally drops the stash. Can be used regardless of whether "git stash save" was done or just "git stash". If no stash matches a message is given. If multiple stashes match a message is given along with matching stash info.

.PARAMETER message
A full or partial stash message name (see right side output of "git stash list"). Can also be "@stash{N}" where N is 0 based stash index.

.PARAMETER drop
If -drop is specified, the matching stash is dropped after being applied.

.EXAMPLE
Restore-Stash "Readme change"
Apply-Stash MyStashName
Apply-Stash MyStashName -drop
Apply-Stash "stash@{0}"
#>
function Restore-Stash  {
    [CmdletBinding()]
    [Alias("Apply-Stash")]
    PARAM (
        [Parameter(Mandatory=$true)] $message,         
        [switch]$drop
    )

    $stashId = $null

    if ($message -match "stash@{") {
        $stashId = $message
    }

    if (!$stashId) {
        $matches = git stash list | Where-Object { $_ -match $message }
        
        if (!$matches) {
            Write-Warning "No stashes found with message matching '$message' - check git stash list"
            return
        }

        if ($matches.Count -gt 1) {
            Write-Warning "Found $($matches.Count) matches for '$message'. Refine message or pass 'stash{@N}' to this function or git stash apply"
            return $matches
        }

        $parts = $matches -split ':'
        $stashId = $parts[0]
    }

    git stash apply ''$stashId''

    if ($drop) {
        git stash drop ''$stashId''
    }
}

function Set-Branch
{
    [CmdletBinding()]
    [Alias("Git-Checkout")]
    PARAM ( 
        [Parameter(Mandatory=$true, Position=0)] [string] $pattern
    )

    $branches = @(git branch `
        | Select-Object @{Name = "Name"; Expression = {$_.Replace("*", "").Trim()}} `
        | Where-Object {$_ -match $pattern})

    if ($branches.Length -ne 1) {
        Write-Warning "Expected 1 branch match but found $($branches.Length). Refine pattern."
        $branches
        return
    }

    $branch = $branches[0].Name
    git checkout $branch
}

function Write-CheatHeader ($header)
{
    Write-Host ($header | New-UnderLine) -ForegroundColor $headerColor
    Write-Host
}

function Write-CheatInstruction ($instruction)
{
    Write-Host $instruction -ForegroundColor $instructionColor
}

Export-ModuleMember -Function Get-GitCheatSheet,Get-GitCommand,Remove-MergedBranches,Restore-Stash,Set-Branch -Alias *