diff --git a/GitHubContents.ps1 b/GitHubContents.ps1 new file mode 100644 index 00000000..526ad9e9 --- /dev/null +++ b/GitHubContents.ps1 @@ -0,0 +1,104 @@ +function Get-GitHubContent { + <# + .SYNOPSIS + Retrieve the contents of a file or directory in a repository on GitHub. + .DESCRIPTION + Retrieve content from files on GitHub. + The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub + .PARAMETER OwnerName + Owner of the repository. + If not supplied here, the DefaultOwnerName configuration property value will be used. + .PARAMETER RepositoryName + Name of the repository. + If not supplied here, the DefaultRepositoryName configuration property value will be used. + .PARAMETER Path + The file path for which to retrieve contents + .PARAMETER MediaType + The format in which the API will return the body of the issue. + Raw - Use the Raw media type to retrieve the contents of the file. + Html - For markup files such as Markdown or AsciiDoc, you can retrieve the rendered HTML using the Html media type. + .PARAMETER AccessToken + If provided, this will be used as the AccessToken for authentication with the + REST Api. Otherwise, will attempt to use the configured value or will run unauthenticated. + .PARAMETER NoStatus + If this switch is specified, long-running commands will run on the main thread + with no commandline status update. When not specified, those commands run in + the background, enabling the command prompt to provide status information. + If not supplied here, the DefaultNoStatus configuration property value will be used. + + .EXAMPLE + Get-GitHubContent -OwnerName microsoft -RepositoryName PowerShellForGitHub -Path README.md -MediaType Html + + Get the Html output for the README.md file + + .EXAMPLE + Get-GitHubContent -OwnerName microsoft -RepositoryName PowerShellForGitHub -Path LICENSE + + Get the Binary file output for the LICENSE file + + .EXAMPLE + Get-GitHubContent -OwnerName microsoft -RepositoryName PowerShellForGitHub -Path Tests + + List the files within the "Tests" path of the repository +#> + [CmdletBinding( + SupportsShouldProcess, + DefaultParametersetName = 'Elements')] + [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSShouldProcess", "", Justification = "Methods called within here make use of PSShouldProcess, and the switch is passed on to them inherently.")] + param( + [Parameter(Mandatory, ParameterSetName = 'Elements')] + [string] $OwnerName, + + [Parameter(Mandatory, ParameterSetName = 'Elements')] + [string] $RepositoryName, + + [string] $Path, + + [ValidateSet('Raw', 'Html')] + [string] $MediaType = 'Raw', + + [string] $AccessToken, + + [switch] $NoStatus + ) + + Write-InvocationLog + + $elements = Resolve-RepositoryElements -DisableValidation + $OwnerName = $elements.ownerName + $RepositoryName = $elements.repositoryName + + $telemetryProperties = @{ + 'OwnerName' = (Get-PiiSafeString -PlainText $OwnerName) + 'RepositoryName' = (Get-PiiSafeString -PlainText $RepositoryName) + 'Path' = $PSBoundParameters.ContainsKey('Path') + } + + $uriFragment = [String]::Empty + $description = [String]::Empty + + $uriFragment = "/repos/$OwnerName/$RepositoryName/contents" + + if ($PSBoundParameters.ContainsKey('Path')) { + $Path = $Path.TrimStart("\\", "/") + $uriFragment += "/$Path" + $description = "Getting content for $Path in $RepositoryName" + } + else { + $description = "Getting all content for in $RepositoryName" + } + + $params = @{ + 'UriFragment' = $uriFragment + 'Description' = $description + 'AcceptHeader' = (Get-ContentMediaType -MediaType $MediaType) + 'AccessToken' = $AccessToken + 'TelemetryEventName' = $MyInvocation.MyCommand.Name + 'TelemetryProperties' = $telemetryProperties + 'NoStatus' = (Resolve-ParameterWithDefaultConfigurationValue -Name NoStatus -ConfigValueName DefaultNoStatus) + } + + $result = Invoke-GHRestMethodMultipleResult @params + + return $result +} diff --git a/GitHubCore.ps1 b/GitHubCore.ps1 index ea61d95d..577a5f99 100644 --- a/GitHubCore.ps1 +++ b/GitHubCore.ps1 @@ -973,3 +973,34 @@ function Get-MediaAcceptHeader return ($acceptHeaders -join ',') } + +function Get-ContentMediaType +{ +<# + .DESCRIPTION + Returns a formatted AcceptHeader based on the requested MediaType for working with GitHub Content, + + The Git repo for this module can be found here: http://aka.ms/PowerShellForGitHub + + .PARAMETER MediaType + The format in which the API will return the body of the comment or issue. + + Raw - Return the raw contents of a file. This is the default if you do not pass any specific media type. + Html - For markup files such as Markdown or AsciiDoc, you can retrieve the rendered HTML using the Html media type. + + .PARAMETER AcceptHeader + The accept header that should be included with the MediaType accept header. + + .EXAMPLE + Get-ContentMediaType -MediaType Raw + + Returns a formatted AcceptHeader for v3 of the response object +#> + [CmdletBinding()] + param( + [ValidateSet('Raw', 'Html')] + [string] $MediaType = 'Raw' + ) + + return "application/vnd.github.$mediaTypeVersion.$($MediaType.ToLower())" +} diff --git a/PowerShellForGitHub.psd1 b/PowerShellForGitHub.psd1 index c12a0081..885d3e40 100644 --- a/PowerShellForGitHub.psd1 +++ b/PowerShellForGitHub.psd1 @@ -25,6 +25,7 @@ 'GitHubBranches.ps1', 'GitHubCore.ps1', 'GitHubComments.ps1', + 'GitHubContents.ps1', 'GitHubEvents.ps1', 'GitHubIssues.ps1', 'GitHubLabels.ps1', @@ -53,8 +54,9 @@ 'Get-GitHubAssignee', 'Get-GitHubCloneTraffic', 'Get-GitHubCodeOfConduct', - 'Get-GitHubComment', + 'Get-GitHubComment', 'Get-GitHubConfiguration', + 'Get-GitHubContent', 'Get-GitHubEmoji', 'Get-GitHubEvent', 'Get-GitHubGitIgnore',