Merge pull request dahlbyk#663 from dahlbyk/rkeithhill/impl-remove-me…

…rgedbranch

Fix dahlbyk#79 - add Remove-MergedGitBranch command

CHANGELOG.md

@@ -7,11 +7,16 @@
 - BREAKING: Removed SSH agent functionality from `posh-git` and put into another module focused solely on
   Git SSH support. See [posh-sshell](https://github.com/dahlbyk/posh-sshell).
 - BREAKING: Removed `PoshGitTextSpan.CustomAnsi` property - now just put your custom VT sequences in the
-  `PoshGitTextSpan.Text` property. Be sure to terminate your VT sequences with `"$([char]27)[0m"`
+  `PoshGitTextSpan.Text` property. Be sure to terminate your VT sequences with `"$([char]27)[0m"` or
+  ``` "`e[0m" ``` on PowerShell Core.
 
 ### Added
 
-- Add support for vsts-cli Git integration.
+- Added `Remove-GitBranch` command. Partially addresses #79.
+  These commands currently only delete local branches.
+  ([#79](https://github.com/dahlbyk/posh-git/issues/79))
+  ([PR #663](https://github.com/dahlbyk/posh-git/pull/663))
+- Added support for vsts-cli Git integration.
   ([#549](https://github.com/dahlbyk/posh-git/issues/549))
   ([PR #581](https://github.com/dahlbyk/posh-git/pull/581))
   Thanks David Gardiner (@flcdrg)

src/GitUtils.ps1

@@ -407,6 +407,161 @@ function Get-AliasPattern($exe) {
    "($($aliases -join '|'))"
 }
 
+<#
+.SYNOPSIS
+    Deletes the specified Git branches.
+.DESCRIPTION
+    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.
+
+    The following branches are always excluded from deletion:
+
+    * The current branch
+    * develop
+    * master
+
+    The default set of excluded branches can be overridden with the ExcludePattern parameter.
+
+    Consider always running this command FIRST with the WhatIf parameter. This will show you which branches will be deleted. This gives you a chance to adjust your branch name wildcard pattern or regular expression if you are using the Pattern parameter.
+
+    IMPORTANT: Be careful using this command. Even though by default this command deletes only merged branches, most, if not all, of your historical branches have been merged. But that doesn't mean you want to delete them. That is why this command excludes `develop` and `master` by default. But you may use different names e.g. `development` or have other historical branches you don't want to delete. In these cases, you can either:
+
+    * Specify a narrower branch name wildcard such as "user/$env:USERNAME/*".
+    * Specify an updated ExcludeParameter e.g. '(^\*)|(^. (develop|master|v\d+)$)' which adds any branch matching the pattern 'v\d+' to the exclusion list.
+
+    If necessary, you can delete the specified branches REGARDLESS of their merge status by using the IncludeUnmerged parameter. BE VERY CAREFUL using the IncludeUnmerged parameter together with the Force parameter, since you will not be given the opportunity to confirm each branch deletion.
+
+    The following Git commands are executed by this command:
+
+        git branch --merged $Commit |
+            Where-Object { $_ -notmatch $ExcludePattern } |
+            Where-Object { $_.Trim() -like $Name } |
+            Foreach-Object { git branch --delete $_.Trim() }
+
+    If the IncludeUnmerged parameter is specified, execution changes to:
+
+        git branch |
+            Where-Object { $_ -notmatch $ExcludePattern } |
+            Where-Object { $_.Trim() -like $Name } |
+            Foreach-Object { git branch --delete $_.Trim() }
+
+    If the DeleteForce parameter is specified, the Foreach-Object changes to:
+
+        Foreach-Object { git branch --delete --force $_.Trim() }
+
+    If the Pattern parameter is used instead of the Name parameter, the second Where-Object changes to:
+
+        Where-Object { $_ -match $Pattern }
+
+    ## Recovering Deleted Branches
+
+    If you wind up deleting a branch you didn't intend to, you can easily recover it with the info provided by Git during the delete. For instance, let's say you realized you didn't want to delete the branch 'feature/exp1'. In the output of this command, you should see a deletion entry for this branch that looks like:
+
+        Deleted branch feature/exp1 (was 08f9000).
+
+    To recover this branch, execute the following Git command:
+
+        # git branch <branch-name> <sha1>
+        git branch feature/exp1 08f9000
+.EXAMPLE
+    PS> Remove-GitBranch -Name "user/${env:USERNAME}/*" -WhatIf
+    Shows the merged branches that would be deleted by the specified branch name without actually deleting. Remove the WhatIf parameter when you are happy with the list of branches that will be deleted.
+.EXAMPLE
+    PS> Remove-GitBranch "feature/*" -Force
+    Deletes the merged branches that match the specified wildcard. Using the Force parameter skips all confirmation prompts. Name is a positional parameter. The first argument is assumed to be the value of the Name parameter.
+.EXAMPLE
+    PS> Remove-GitBranch "bugfix/*" -Force -DeleteForce
+    Deletes the merged branches that match the specified wildcard. Using the Force parameter skips all confirmation prompts while the DeleteForce parameter uses the --force option in the underlying Git command.
+.EXAMPLE
+    PS> Remove-GitBranch -Pattern 'user/(dahlbyk|hillr)/.*'
+    Deletes the merged branches that match the specified regular expression.
+.EXAMPLE
+    PS> Remove-GitBranch -Name * -ExcludePattern '(^\*)|(^. (develop|master|v\d+)$)'
+    Deletes merged branches except the current branch, develop, master and branches that also match the pattern 'v\d+' e.g. v1, v1.0, v1.x. BE VERY CAREFUL SPECIYING SUCH A BROAD BRANCH NAME WILDCARD!
+.EXAMPLE
+    PS> Remove-GitBranch "feature/*" -IncludeUnmerged -WhatIf
+    Shows the branches, both merged and unmerged, that match the specified wildcard that would be deleted without actually deleting them. Once you've verified the list of branches looks correct, remove the WhatIf parameter to actually delete the branches.
+#>
+function Remove-GitBranch {
+    [CmdletBinding(DefaultParameterSetName="Wildcard", SupportsShouldProcess, ConfirmImpact="Medium")]
+    param(
+        # Specifies a regular expression pattern for the branches that will be deleted. Certain branches are always excluded from deletion e.g. the current branch as well as the develop and master branches. See the ExcludePattern parameter to modify that pattern.
+        [Parameter(Position=0, Mandatory, ParameterSetName="Wildcard")]
+        [ValidateNotNullOrEmpty()]
+        [string]
+        $Name,
+
+        # Specifies a regular expression for the branches that will be deleted. Certain branches are always excluded from deletion e.g. the current branch as well as the develop and master branches. See the ExcludePattern parameter to modify that pattern.
+        [Parameter(Position=0, Mandatory, ParameterSetName="Pattern")]
+        [ValidateNotNull()]
+        [string]
+        $Pattern,
+
+        # Specifies a regular expression used to exclude merged branches from being deleted. The default pattern excludes the current branch, develop and master branches.
+        [Parameter()]
+        [ValidateNotNull()]
+        [string]
+        $ExcludePattern = '(^\*)|(^. (develop|master)$)',
+
+        # Branches whose tips are reachable from the specified commit will be deleted. The default commit is HEAD. This parameter is ignored if the IncludeUnmerged parameter is specified.
+        [Parameter()]
+        [string]
+        $Commit = "HEAD",
+
+        # Specifies that unmerged branches are also eligible to be deleted.
+        [Parameter()]
+        [switch]
+        $IncludeUnmerged,
+
+        # Deletes the specified branches without prompting for confirmation. By default, Remove-GitBranch prompts for confirmation before deleting branches.
+        [Parameter()]
+        [switch]
+        $Force,
+
+        # Deletes the specified branches by adding the --force parameter to the git branch --delete command e.g. git branch --delete --force <branch-name>. This is also the equivalent of using the -D parameter on the git branch command.
+        [Parameter()]
+        [switch]
+        $DeleteForce
+    )
+
+    if ($IncludeUnmerged) {
+        $branches = git branch
+    }
+    else {
+        $branches = git branch --merged $Commit
+    }
+
+    $filteredBranches = $branches | Where-Object {$_ -notmatch $ExcludePattern }
+
+    if ($PSCmdlet.ParameterSetName -eq "Wildcard") {
+        $branchesToDelete = $filteredBranches | Where-Object { $_.Trim() -like $Name }
+    }
+    else {
+        $branchesToDelete = $filteredBranches | Where-Object { $_ -match $Pattern }
+    }
+
+    $action = if ($DeleteForce) { "delete with force"} else { "delete" }
+    $yesToAll = $noToAll = $false
+
+    foreach ($branch in $branchesToDelete) {
+        $targetBranch = $branch.Trim()
+        if ($PSCmdlet.ShouldProcess($targetBranch, $action)) {
+            if ($Force -or $yesToAll -or
+                $PSCmdlet.ShouldContinue("Are you REALLY sure you want to $action `"$targetBranch`"?",
+                                         "Confirm branch deletion", [ref]$yesToAll, [ref]$noToAll)) {
+
+                if ($noToAll) { return }
+
+                if ($DeleteForce) {
+                    Invoke-Utf8ConsoleCommand { git branch --delete --force $targetBranch }
+                }
+                else {
+                    Invoke-Utf8ConsoleCommand { git branch --delete $targetBranch }
+                }
+            }
+        }
+    }
+}
+
 function Update-AllBranches($Upstream = 'master', [switch]$Quiet) {
     $head = git rev-parse --abbrev-ref HEAD
     git checkout -q $Upstream

src/en-US/about_posh-git.help.txt

@@ -164,6 +164,13 @@ PRIMARY COMMANDS
     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

src/posh-git.psd1

@@ -32,6 +32,7 @@ FunctionsToExport = @(
     'Get-PromptConnectionInfo',
     'Get-PromptPath',
     'New-GitPromptSettings',
+    'Remove-GitBranch',
     'Update-AllBranches',
     'Write-GitStatus',
     'Write-GitBranchName',

src/posh-git.psm1

@@ -155,6 +155,7 @@ $exportModuleMemberParams = @{
         'Get-PromptConnectionInfo',
         'Get-PromptPath',
         'New-GitPromptSettings',
+        'Remove-GitBranch',
         'Update-AllBranches',
         'Write-GitStatus',
         'Write-GitBranchName',