Add additional commands

CHANGELOG.md

@@ -5,6 +5,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Public commands:
+  - `Update-GitBranch`
+
 ## [0.2.0] - 2024-08-25
 
 ### Added
@@ -21,3 +26,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `Remove-PSHistory`
   - `Remove-PSReadLineHistory`
   - `Split-StringAtIndices`
+  - `Update-GitBranch`

source/Public/Assert-GitLocalChanges.ps1

@@ -0,0 +1,35 @@
+<#
+    .SYNOPSIS
+        Asserts that there are no unstaged or staged changes in the local Git branch.
+
+    .DESCRIPTION
+        The Assert-GitLocalChanges command checks whether there are any unstaged
+        or staged changes in the local Git branch. If there are any staged or
+        unstaged changes, it throws a terminating error.
+
+    .EXAMPLE
+        Assert-GitLocalChanges
+
+        This example demonstrates how to use the Assert-GitLocalChanges command
+        to ensure that there are no local changes in the Git repository.
+#>
+function Assert-GitLocalChanges
+{
+    [CmdletBinding()]
+    param ()
+
+    $hasChanges = Test-GitLocalChanges
+
+    if ($hasChanges)
+    {
+        # cSpell:ignore unstaged
+        $PSCmdlet.ThrowTerminatingError(
+            [System.Management.Automation.ErrorRecord]::new(
+                ($script:localizedData.Assert_GitLocalChanges_FailedUnstagedChanges),
+                'AGLC0001', # cspell: disable-line
+                [System.Management.Automation.ErrorCategory]::InvalidResult,
+                'Staged or unstaged changes'
+            )
+        )
+    }
+}

source/Public/Assert-GitRemote.ps1

@@ -0,0 +1,50 @@
+<#
+    .SYNOPSIS
+        Checks if the specified Git remote exists locally and throws an error if it doesn't.
+
+    .DESCRIPTION
+        The `Assert-GitRemote` command checks if the remote specified in the `$RemoteName`
+        parameter exists locally. If the remote doesn't exist, it throws an error.
+
+    .PARAMETER RemoteName
+        Specifies the name of the Git remote to check.
+
+    .EXAMPLE
+        PS> Assert-GitRemote -RemoteName "origin"
+
+        This example checks if the Git remote named "origin" exists locally.
+
+    .INPUTS
+        None.
+
+    .OUTPUTS
+        None.
+#>
+function Assert-GitRemote
+{
+    [CmdletBinding()]
+    param
+    (
+        [Parameter(Mandatory = $true, Position = 0)]
+        [System.String]
+        $RemoteName
+    )
+
+    <#
+        Check if the remote specified in $UpstreamRemoteName exists locally and
+        throw an error if it doesn't.
+    #>
+    $remoteExists = Test-GitRemote -RemoteName $RemoteName
+
+    if (-not $remoteExists)
+    {
+        $PSCmdlet.ThrowTerminatingError(
+            [System.Management.Automation.ErrorRecord]::new(
+                ($script:localizedData.New_SamplerGitHubReleaseTag_RemoteMissing -f $UpstreamRemoteName),
+                'AGR0001', # cspell: disable-line
+                [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+                $DatabaseName
+            )
+        )
+    }
+}

source/Public/Get-GitBranchCommit.ps1

@@ -0,0 +1,148 @@
+<#
+    .SYNOPSIS
+        Retrieves the commit ID(s) for a specified Git branch.
+
+    .DESCRIPTION
+        The Get-GitBranchCommit command retrieves the commit ID(s) for a specified
+        Git branch. It provides options to retrieve the latest commit ID, a specific
+        number of latest commit IDs, or the first X number of commit IDs.
+
+    .PARAMETER BranchName
+        Specifies the name of the Git branch. If not provided, the current branch
+        will be used.
+
+    .PARAMETER Latest
+        Retrieves only the latest commit ID.
+
+    .PARAMETER Last
+        Retrieves the specified number of latest commit IDs. The order will be from
+        the newest to the oldest commit.
+
+    .PARAMETER First
+        Retrieves the first X number of commit IDs. The order will be from the
+        oldest to the newest commit.
+
+    .OUTPUTS
+        System.String
+
+        The commit ID(s) for the specified Git branch.
+
+    .EXAMPLE
+        Get-GitBranchCommit -BranchName 'feature/branch'
+
+        Retrieves all commit IDs for the 'feature/branch' Git branch.
+
+    .EXAMPLE
+        Get-GitBranchCommit -Latest
+
+        Retrieves only the latest commit ID for the current Git branch.
+
+    .EXAMPLE
+        Get-GitBranchCommit -Last 5
+
+        Retrieves the 5 latest commit IDs for the current Git branch.
+
+    .EXAMPLE
+        Get-GitBranchCommit -First 3
+
+        Retrieves the first 3 commit IDs for the current Git branch.
+#>
+function Get-GitBranchCommit
+{
+    [CmdletBinding(DefaultParameterSetName = 'NoParameter')]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter(ParameterSetName = 'NoParameter')]
+        [Parameter(ParameterSetName = 'Latest')]
+        [Parameter(ParameterSetName = 'Last')]
+        [Parameter(ParameterSetName = 'First')]
+        [System.String]
+        $BranchName,
+
+        [Parameter(ParameterSetName = 'Latest')]
+        [System.Management.Automation.SwitchParameter]
+        $Latest,
+
+        [Parameter(ParameterSetName = 'Last')]
+        [System.UInt32]
+        $Last,
+
+        [Parameter(ParameterSetName = 'First')]
+        [System.UInt32]
+        $First
+    )
+
+    $commitId = $null
+
+    $argument = @()
+
+    if ($PSBoundParameters.ContainsKey('BranchName'))
+    {
+        if ($BranchName -eq '.')
+        {
+            $BranchName = Get-GitLocalBranchName -Current
+        }
+
+        $argument += @(
+            $BranchName
+        )
+    }
+
+    if ($Latest.IsPresent)
+    {
+        # Return only the latest commit ID.
+        $commitId = git rev-parse HEAD @argument
+    }
+    elseif ($Last)
+    {
+        # Return the latest X number of commits.
+        $commitId = git log -n $Last --pretty=format:"%H" @argument
+    }
+    elseif ($First)
+    {
+        if (-not $PSBoundParameters.ContainsKey('BranchName'))
+        {
+            $BranchName = Get-GitLocalBranchName -Current
+        }
+
+        # Count the total number of commits in the branch.
+        $totalCommits = git rev-list --count $BranchName
+
+        # Calculate the number of commits to skip.
+        $skipCommits = $totalCommits - $First
+
+        # Return the first X number of commits.
+        $commitId = git log --skip $skipCommits --reverse -n $First --pretty=format:"%H" $BranchName
+    }
+    else
+    {
+        # Return all commit IDs.
+        $commitId = git log --pretty=format:"%H" @argument
+    }
+
+    # TODO: Should handle LASTEXITCODE above too
+
+    if ($LASTEXITCODE -ne 0) # cSpell: ignore LASTEXITCODE
+    {
+        if($PSBoundParameters.ContainsKey('BranchName'))
+        {
+            $errorMessage = $script:localizedData.Get_GitBranchCommit_FailedFromBranch -f $BranchName
+        }
+        else
+        {
+            $errorMessage = $script:localizedData.Get_GitBranchCommit_FailedFromCurrent
+        }
+
+        $PSCmdlet.ThrowTerminatingError(
+            [System.Management.Automation.ErrorRecord]::new(
+                $errorMessage,
+                'GGLBN0001', # cspell: disable-line
+                [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+                $branchName
+            )
+        )
+    }
+
+    return $commitId
+}

source/Public/Get-GitLocalBranchName.ps1

@@ -0,0 +1,70 @@
+<#
+    .SYNOPSIS
+        Retrieves the name of the local Git branch.
+
+    .DESCRIPTION
+        The Get-GitLocalBranchName command is used to retrieve the name of the
+        current local Git branch. It uses the `git rev-parse --abbrev-ref HEAD`
+        command to get the branch name.
+
+    .OUTPUTS
+        [System.String]
+
+        The function returns the name of the current local Git branch as a string.
+
+    .EXAMPLE
+        PS C:\> Get-GitLocalBranchName -Current
+
+        Returns the name of the current local Git branch.
+#>
+function Get-GitLocalBranchName
+{
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSShouldProcess', '', Justification = 'ShouldProcess is implemented without ShouldProcess/ShouldContinue.')]
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Low')]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $Current
+    )
+
+    $branchName = $null
+
+    if ($WhatIfPreference)
+    {
+        if ($Current.IsPresent)
+        {
+            Write-Information -MessageData 'What if: Getting current local branch name' -InformationAction Continue
+        }
+        else
+        {
+            Write-Information -MessageData 'What if: Getting local branch names.' -InformationAction Continue
+        }
+    }
+    else
+    {
+        if ($Current.IsPresent)
+        {
+            $branchName = git rev-parse --abbrev-ref HEAD
+        }
+        else
+        {
+            $branchName = git branch --format='%(refname:short)' --list
+        }
+
+        if ($LASTEXITCODE -ne 0) # cSpell: ignore LASTEXITCODE
+        {
+            $PSCmdlet.ThrowTerminatingError(
+                [System.Management.Automation.ErrorRecord]::new(
+                    $script:localizedData.Get_GitLocalBranchName_Failed,
+                    'GGLBN0001', # cspell: disable-line
+                    [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+                    $branchName
+                )
+            )
+        }
+    }
+
+    return $branchName
+}