Documentation and improved Get-GitStatus for powershell script integration

[arberg]

System Details

• posh-git version/path: 0.7.3.1 C:\Tools\poshgit\dahlbyk-posh-git-9bda399\src
• PowerShell version: 5.1.17134.407
• git version 2.20.1.windows.1
• OS: Microsoft Windows NT 10.0.17134.0

Issue Description

I was developing our a powershell script for some simple custom management of our git-submobules, with nice overview status of the state of each submodule, and got tired of parsing git status. In came posh-git in my mind, and its absolute awesome for getting git info using Get-GitStatus. However I noticed it could easily be made even slightly more awesome. The Readme lacks some info for using posh-git as powershell functions and not just prompt-management. The Get-GitStatus could use a boolean for isOnBranch rather that manually having to parse if branchName is on form "(xfz)". The Get-GitStatus could also use some documentation for the different attributes. Like what does 'HasWorkning' mean?

I might be inspired to invest a few hours adding this. Would you be interested in such a pull-request?

[rkeithhill]

Since Get-GitStatus runs every time the PowerShell prompt is processed we try to make sure perf is as good as it can be. Processing the branch name text to determine if we're "on a branch" isn't something we need for processing the prompt string. So it's a bit hard to justify adding this property.

Regarding documentation, yes this command's comment-help could use a lot of, well, help. :-) We'd gladly accept a PR to improve the help. BTW HasWorking indicates whether there are workspace changes and we should display the EFGH W section of the prompt - [{HEAD-name} S +A ~B -C !D | +E ~F -G !H W].

[elsassph]

Could Get-GitStatus accept extra parameters?

I don't like seeing the git status in the prompt, so I set EnableFileStatus=$false, however I would really like to be able to call like Get-GitStatus to obtain the repository status.

Even calling Get-GitStatus -Force doesn't get the file status.

[rkeithhill]

What if we use the existing -Force parameter and have that override EnableFileStatus as well as EnablePromptStatus? Another option you could use for now is to not set EnableFileStatus to false and define your own prompt function in your profile. If you import posh-git after your prompt function def, posh-git will not override your prompt. Then Get-GitStatus will return the info you want and then you can display it however you want.

[elsassph]

If -Force would override EnableFileStatus that would be most suitable.

Currently the behaviour of Get-GitStatus basically depends on "user preferences", which means this function can't be safely used by utilities (or a script would have to temporarily change the prompt option).

[rkeithhill]

@elsassph Can you try the latest on master to see if it works as you expect it to now?

[elsassph]

@rkeithhill works great!

[rkeithhill]

Thanks for confirming!

[dahlbyk]

Finally putting together a release with this. From a documentation standpoint, I suppose we should change .INPUTS None to reflect the parameters? Or are those comments sufficient?

posh-git/src/GitUtils.ps1

Lines 188 to 219 in ade0c40

	<#
	.SYNOPSIS
	Gets a Git status object that is used by Write-GitStatus.
	.DESCRIPTION
	Gets a Git status object that is used by Write-GitStatus.
	The status object provides the information to be displayed in the various
	sections of the posh-git prompt.
	.EXAMPLE
	PS C:\> $s = Get-GitStatus; Write-GitStatus $s
	Gets a Git status object. Then passes the object to Write-GitStatus which
	writes out a posh-git prompt (or returns a string in ANSI mode) with the
	information contained in the status object.
	.INPUTS
	None
	.OUTPUTS
	System.Management.Automation.PSObject
	.LINK
	Write-GitStatus
	#>
	function Get-GitStatus {
	param(
	# The path of a directory within a Git repository that you want to get
	# the Git status.
	[Parameter(Position=0)]
	$GitDir = (Get-GitDirectory),
	# If specified, overrides $GitPromptSettings.EnableFileStatus and
	# $GitPromptSettings.EnablePromptStatus when they are set to $false.
	[Parameter()]
	[switch]
	$Force
	)

[rkeithhill]

.INPUTS is used to reflect pipeline input and since this method has no "pipeline bound" parameters, it doesn't handle pipeline input. So .INPUTS None is correct for this function.

[dahlbyk]

.INPUTS is used to reflect pipeline input and since this method has no "pipeline bound" parameters, it doesn't handle pipeline input. So .INPUTS None is correct for this function.

👍

https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7#parameter

You can also specify a parameter description by placing a comment in the function or script syntax immediately before the parameter variable name.

---

@elsassph is existing documentation sufficient?

[elsassph]

I appreciate that with the optional Force parameter this could justify changing the description of the method to be like

.SYNOPSIS
    Get the git status as a PS object

.DESCRIPTION
    The status object provides the information to be displayed in the various 
    sections of the posh-git prompt.
    This method respects `$EnableFileStatus` and will not provide detailed 
    file status unless the optional `Force` parameter is provided.