Skip to content

Commit d76f54b

Browse files
X-GuardianX-Guardian
authored
GitHubBranches: Add New/Remove-GitHubRepositoryBranch Functions (#256)
Adds the following functions to the `GitHubBranches` module: * `New-GitHubRepositoryBranch` * `Remove-GitHubRepositoryBranch` #### References [GitHub Refs API](https://developer.github.com/v3/git/refs/)
1 parent fcfe0c7 commit d76f54b

File tree

4 files changed

+616
-8
lines changed

4 files changed

+616
-8
lines changed

‎GitHubBranches.ps1‎

Lines changed: 362 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,352 @@ filter Get-GitHubRepositoryBranch
154154
return (Invoke-GHRestMethodMultipleResult @params | Add-GitHubBranchAdditionalProperties)
155155
}
156156

157+
filter New-GitHubRepositoryBranch
158+
{
159+
<#
160+
.SYNOPSIS
161+
Creates a new branch for a given GitHub repository.
162+
163+
.DESCRIPTION
164+
Creates a new branch for a given GitHub repository.
165+
166+
The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
167+
168+
.PARAMETER OwnerName
169+
Owner of the repository.
170+
If not supplied here, the DefaultOwnerName configuration property value will be used.
171+
172+
.PARAMETER RepositoryName
173+
Name of the repository.
174+
If not supplied here, the DefaultRepositoryName configuration property value will be used.
175+
176+
.PARAMETER Uri
177+
Uri for the repository.
178+
The OwnerName and RepositoryName will be extracted from here instead of needing to provide
179+
them individually.
180+
181+
.PARAMETER BranchName
182+
The name of the origin branch to create the new branch from.
183+
184+
.PARAMETER TargetBranchName
185+
Name of the branch to be created.
186+
187+
.PARAMETER AccessToken
188+
If provided, this will be used as the AccessToken for authentication with the
189+
REST Api. Otherwise, will attempt to use the configured value or will run unauthenticated.
190+
191+
.PARAMETER NoStatus
192+
If this switch is specified, long-running commands will run on the main thread
193+
with no commandline status update. When not specified, those commands run in
194+
the background, enabling the command prompt to provide status information.
195+
If not supplied here, the DefaultNoStatus configuration property value will be used.
196+
197+
.INPUTS
198+
GitHub.Branch
199+
GitHub.Content
200+
GitHub.Event
201+
GitHub.Issue
202+
GitHub.IssueComment
203+
GitHub.Label
204+
GitHub.Milestone
205+
GitHub.PullRequest
206+
GitHub.Project
207+
GitHub.ProjectCard
208+
GitHub.ProjectColumn
209+
GitHub.Release
210+
GitHub.Repository
211+
212+
.OUTPUTS
213+
GitHub.Branch
214+
215+
.EXAMPLE
216+
New-GitHubRepositoryBranch -OwnerName microsoft -RepositoryName PowerShellForGitHub -TargetBranchName new-branch
217+
218+
Creates a new branch in the specified repository from the master branch.
219+
220+
.EXAMPLE
221+
New-GitHubRepositoryBranch -Uri 'https://github.com/microsoft/PowerShellForGitHub' -BranchName develop -TargetBranchName new-branch
222+
223+
Creates a new branch in the specified repository from the 'develop' origin branch.
224+
225+
.EXAMPLE
226+
$repo = Get-GithubRepository -Uri https://github.com/You/YourRepo
227+
$repo | New-GitHubRepositoryBranch -TargetBranchName new-branch
228+
229+
You can also pipe in a repo that was returned from a previous command.
230+
#>
231+
[CmdletBinding(
232+
SupportsShouldProcess,
233+
DefaultParameterSetName = 'Elements',
234+
PositionalBinding = $false
235+
)]
236+
[OutputType({$script:GitHubBranchTypeName})]
237+
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '',
238+
Justification = 'Methods called within here make use of PSShouldProcess, and the switch is
239+
passed on to them inherently.')]
240+
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '',
241+
Justification = 'One or more parameters (like NoStatus) are only referenced by helper
242+
methods which get access to it from the stack via Get-Variable -Scope 1.')]
243+
[Alias('New-GitHubBranch')]
244+
param(
245+
[Parameter(ParameterSetName = 'Elements')]
246+
[string] $OwnerName,
247+
248+
[Parameter(ParameterSetName = 'Elements')]
249+
[string] $RepositoryName,
250+
251+
[Parameter(
252+
Mandatory,
253+
ValueFromPipelineByPropertyName,
254+
Position = 1,
255+
ParameterSetName = 'Uri')]
256+
[Alias('RepositoryUrl')]
257+
[string] $Uri,
258+
259+
[string] $BranchName = 'master',
260+
261+
[Parameter(
262+
Mandatory,
263+
ValueFromPipeline,
264+
Position = 2)]
265+
[string] $TargetBranchName,
266+
267+
[string] $AccessToken,
268+
269+
[switch] $NoStatus
270+
)
271+
272+
Write-InvocationLog
273+
274+
$elements = Resolve-RepositoryElements
275+
$OwnerName = $elements.ownerName
276+
$RepositoryName = $elements.repositoryName
277+
278+
$telemetryProperties = @{
279+
'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
280+
'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
281+
}
282+
283+
$originBranch = $null
284+
285+
try
286+
{
287+
$getGitHubRepositoryBranchParms = @{
288+
OwnerName = $OwnerName
289+
RepositoryName = $RepositoryName
290+
BranchName = $BranchName
291+
Whatif = $false
292+
Confirm = $false
293+
}
294+
if ($PSBoundParameters.ContainsKey('AccessToken'))
295+
{
296+
$getGitHubRepositoryBranchParms['AccessToken'] = $AccessToken
297+
}
298+
if ($PSBoundParameters.ContainsKey('NoStatus'))
299+
{
300+
$getGitHubRepositoryBranchParms['NoStatus'] = $NoStatus
301+
}
302+
303+
Write-Log -Level Verbose "Getting $BranchName branch for sha reference"
304+
$originBranch = Get-GitHubRepositoryBranch @getGitHubRepositoryBranchParms
305+
}
306+
catch
307+
{
308+
# Temporary code to handle current differences in exception object between PS5 and PS7
309+
$throwObject = $_
310+
311+
if ($PSVersionTable.PSedition -eq 'Core')
312+
{
313+
if ($_.Exception -is [Microsoft.PowerShell.Commands.HttpResponseException] -and
314+
($_.ErrorDetails.Message | ConvertFrom-Json).message -eq 'Branch not found')
315+
{
316+
$throwObject = "Origin branch $BranchName not found"
317+
}
318+
}
319+
else
320+
{
321+
if ($_.Exception.Message -like '*Not Found*')
322+
{
323+
$throwObject = "Origin branch $BranchName not found"
324+
}
325+
}
326+
327+
Write-Log -Message $throwObject -Level Error
328+
throw $throwObject
329+
}
330+
331+
$uriFragment = "repos/$OwnerName/$RepositoryName/git/refs"
332+
333+
$hashBody = @{
334+
ref = "refs/heads/$TargetBranchName"
335+
sha = $originBranch.commit.sha
336+
}
337+
338+
$params = @{
339+
'UriFragment' = $uriFragment
340+
'Body' = (ConvertTo-Json -InputObject $hashBody)
341+
'Method' = 'Post'
342+
'Description' = "Creating branch $TargetBranchName for $RepositoryName"
343+
'AccessToken' = $AccessToken
344+
'TelemetryEventName' = $MyInvocation.MyCommand.Name
345+
'TelemetryProperties' = $telemetryProperties
346+
'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus)
347+
}
348+
349+
return (Invoke-GHRestMethod @params | Add-GitHubBranchAdditionalProperties)
350+
}
351+
352+
filter Remove-GitHubRepositoryBranch
353+
{
354+
<#
355+
.SYNOPSIS
356+
Removes a branch from a given GitHub repository.
357+
358+
.DESCRIPTION
359+
Removes a branch from a given GitHub repository.
360+
361+
The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub
362+
363+
.PARAMETER OwnerName
364+
Owner of the repository.
365+
If not supplied here, the DefaultOwnerName configuration property value will be used.
366+
367+
.PARAMETER RepositoryName
368+
Name of the repository.
369+
If not supplied here, the DefaultRepositoryName configuration property value will be used.
370+
371+
.PARAMETER Uri
372+
Uri for the repository.
373+
The OwnerName and RepositoryName will be extracted from here instead of needing to provide
374+
them individually.
375+
376+
.PARAMETER BranchName
377+
Name of the branch to be removed.
378+
379+
.PARAMETER Force
380+
If this switch is specified, you will not be prompted for confirmation of command execution.
381+
382+
.PARAMETER AccessToken
383+
If provided, this will be used as the AccessToken for authentication with the
384+
REST Api. Otherwise, will attempt to use the configured value or will run unauthenticated.
385+
386+
.PARAMETER NoStatus
387+
If this switch is specified, long-running commands will run on the main thread
388+
with no commandline status update. When not specified, those commands run in
389+
the background, enabling the command prompt to provide status information.
390+
If not supplied here, the DefaultNoStatus configuration property value will be used.
391+
392+
.INPUTS
393+
GitHub.Branch
394+
GitHub.Content
395+
GitHub.Event
396+
GitHub.Issue
397+
GitHub.IssueComment
398+
GitHub.Label
399+
GitHub.Milestone
400+
GitHub.PullRequest
401+
GitHub.Project
402+
GitHub.ProjectCard
403+
GitHub.ProjectColumn
404+
GitHub.Release
405+
GitHub.Repository
406+
407+
.OUTPUTS
408+
None
409+
410+
.EXAMPLE
411+
Remove-GitHubRepositoryBranch -OwnerName microsoft -RepositoryName PowerShellForGitHub -BranchName develop
412+
413+
Removes the 'develop' branch from the specified repository.
414+
415+
.EXAMPLE
416+
Remove-GitHubRepositoryBranch -OwnerName microsoft -RepositoryName PowerShellForGitHub -BranchName develop -Force
417+
418+
Removes the 'develop' branch from the specified repository without prompting for confirmation.
419+
420+
.EXAMPLE
421+
$branch = Get-GitHubRepositoryBranch -Uri https://github.com/You/YourRepo -BranchName BranchToDelete
422+
$branch | Remove-GitHubRepositoryBranch -Force
423+
424+
You can also pipe in a repo that was returned from a previous command.
425+
#>
426+
[CmdletBinding(
427+
SupportsShouldProcess,
428+
DefaultParameterSetName = 'Elements',
429+
PositionalBinding = $false,
430+
ConfirmImpact = 'High')]
431+
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "",
432+
Justification = "Methods called within here make use of PSShouldProcess, and the switch is
433+
passed on to them inherently.")]
434+
[Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "",
435+
Justification = "One or more parameters (like NoStatus) are only referenced by helper
436+
methods which get access to it from the stack via Get-Variable -Scope 1.")]
437+
[Alias('Remove-GitHubBranch')]
438+
[Alias('Delete-GitHubRepositoryBranch')]
439+
[Alias('Delete-GitHubBranch')]
440+
param(
441+
[Parameter(ParameterSetName = 'Elements')]
442+
[string] $OwnerName,
443+
444+
[Parameter(ParameterSetName = 'Elements')]
445+
[string] $RepositoryName,
446+
447+
[Parameter(
448+
Mandatory,
449+
ValueFromPipelineByPropertyName,
450+
Position = 1,
451+
ParameterSetName = 'Uri')]
452+
[Alias('RepositoryUrl')]
453+
[string] $Uri,
454+
455+
[Parameter(
456+
Mandatory,
457+
ValueFromPipelineByPropertyName,
458+
Position = 2)]
459+
[string] $BranchName,
460+
461+
[switch] $Force,
462+
463+
[string] $AccessToken,
464+
465+
[switch] $NoStatus
466+
)
467+
468+
$elements = Resolve-RepositoryElements
469+
$OwnerName = $elements.ownerName
470+
$RepositoryName = $elements.repositoryName
471+
472+
$telemetryProperties = @{
473+
'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName)
474+
'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName)
475+
}
476+
477+
$uriFragment = "repos/$OwnerName/$RepositoryName/git/refs/heads/$BranchName"
478+
479+
if ($Force -and (-not $Confirm))
480+
{
481+
$ConfirmPreference = 'None'
482+
}
483+
484+
if ($PSCmdlet.ShouldProcess($BranchName, "Remove Repository Branch"))
485+
{
486+
Write-InvocationLog
487+
488+
$params = @{
489+
'UriFragment' = $uriFragment
490+
'Method' = 'Delete'
491+
'Description' = "Deleting branch $BranchName from $RepositoryName"
492+
'AccessToken' = $AccessToken
493+
'TelemetryEventName' = $MyInvocation.MyCommand.Name
494+
'TelemetryProperties' = $telemetryProperties
495+
'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue `
496+
-Name NoStatus -ConfigValueName DefaultNoStatus)
497+
}
498+
499+
Invoke-GHRestMethod @params | Out-Null
500+
}
501+
}
502+
157503
filter Add-GitHubBranchAdditionalProperties
158504
{
159505
<#
@@ -192,11 +538,25 @@ filter Add-GitHubBranchAdditionalProperties
192538

193539
if (-not (Get-GitHubConfiguration -Name DisablePipelineSupport))
194540
{
195-
$elements = Split-GitHubUri -Uri $item.commit.url
541+
if ($null -ne $item.url)
542+
{
543+
$elements = Split-GitHubUri -Uri $item.url
544+
}
545+
else
546+
{
547+
$elements = Split-GitHubUri -Uri $item.commit.url
548+
}
196549
$repositoryUrl = Join-GitHubUri @elements
550+
197551
Add-Member -InputObject $item -Name 'RepositoryUrl' -Value $repositoryUrl -MemberType NoteProperty -Force
198552

199-
Add-Member -InputObject $item -Name 'BranchName' -Value $item.name -MemberType NoteProperty -Force
553+
$branchName = $item.name
554+
if ($null -eq $branchName)
555+
{
556+
$branchName = $item.ref -replace ('refs/heads/', '')
557+
}
558+
559+
Add-Member -InputObject $item -Name 'BranchName' -Value $branchName -MemberType NoteProperty -Force
200560
}
201561

202562
Write-Output $item

0 commit comments

Comments
 (0)