Scott
5c09b7c5a8
- adds GitRepoRegistration cmdlets - adds basic tests for GitRepoRegistration implementations - adds initial build project and scripts Refs: #5, #6
133 lines
No EOL
5.5 KiB
Markdown
133 lines
No EOL
5.5 KiB
Markdown
# Git Repo Registration
|
|
|
|
- all commands support `-debug`
|
|
- at its simplest level these commands allow you to register a git repo against a simple name, and provide the ability to quickly pushd to a location
|
|
|
|
Most `*-GitRepoRegistration` commands are expected to be run within a folder that is contained within a git repo. The only exceptions to this are any verbs that list information or change locations such as `Get-`, `Show-`, `Push-`, `Pop-`.
|
|
|
|
Any exceptions to behaviours are outlined within the relevant command section.
|
|
|
|
> ### Case-Sensitivity
|
|
> For all commands, the `Name` parameter is treated as _case-sensitive_, so multiple registrations can exist with the same name but different casing and point to different git repo locations or the same location - acting as an alias in a sense.
|
|
>
|
|
> While this isn't explicitly supported functionality, we don't do anything to prevent you having multiple registrations for the same git repo. Why should we after all? This set of commandlets are designed to make git repos more organised so how you use it is up to you.
|
|
|
|
## New-GitRepoRegistration
|
|
|
|
`New-GitRepoRegistration [-Name string]`
|
|
|
|
Creates a new registration for the current directory, optionally registering against the given name. If `-Name` is not given the folder for the root level of the git repo will be used.
|
|
|
|
Name registrations are _not_ case-sensitive, so registrations can be made using different cases for the same location, and multiple registrations can exist for the git repository.
|
|
|
|
If `New-GitRepoRegistration` is used in 2 repositories with the same name but different locations, the 2nd call will fail as a registration will already exist by name.
|
|
|
|
```pwsh
|
|
# Default registration without a name within a folder in a git repo
|
|
PS D:/Repos/Project-a> New-GitRepoRegistration -debug
|
|
DEBUG: Checking if current directory is a git repository...
|
|
DEBUG: ...location is a git repo!
|
|
DEBUG: No name given for registration, defaulting to git folder root.
|
|
DEBUG: Registered 'D:/Repos/Project-a' to name 'Project-a'
|
|
|
|
# Named registration
|
|
PS D:/Repos/Project-a> New-GitRepoRegistration "test repo" -debug
|
|
DEBUG: Checking if current directory is a git repository...
|
|
DEBUG: ...location is a git repo!
|
|
DEBUG: Registered 'D:/Repos/Project-a' to name 'test repo'
|
|
|
|
PS D:/Repos/Project-a> Get-GitRepoRegistration
|
|
|
|
Name Location CurrentBranch
|
|
---- -------- -------------
|
|
test-repo D:/Repos/Project-a main
|
|
Project-a D:/Repos/Project-a main
|
|
```
|
|
|
|
If the current directory is not in a git repo, a registration already exists by name or default folder, or if any other issue occurs such as git not being available an error will be thrown.
|
|
|
|
## Get-GitRepoRegistration
|
|
|
|
`Get-GitRepoRegistration`
|
|
|
|
Returns all currently registered git repositories, as well as their current branch.
|
|
|
|
```pwsh
|
|
PS D:/Repos/Project-a> Get-GitRepoRegistration
|
|
|
|
Name Location CurrentBranch
|
|
---- -------- -------------
|
|
test-repo D:/Repos/Project-a main
|
|
Project-a D:/Repos/Project-a main
|
|
```
|
|
|
|
The current branch is cached for 15 minutes for performance reasons so it may not be up to date if a git repo has recently had its branch changed.
|
|
|
|
## Show-GitRepoRegistration
|
|
|
|
`Show-GitRepoRegistration -Name string [-NoStack|-NoPushLocation]`
|
|
|
|
Changes your location to the location of the git repo registered by the given `-Name` and your original location will be preserved and can be returned to at any time via `Pop-Location`/`Popd`. By default, this command is identical to calling
|
|
`pushd [repository directory]`.
|
|
|
|
Using `-NoStack`/`-NoPushLocation` will not push your current location onto the stack, and will behave the same as `cd [repository directory]`/`Set-Location [repository directory]`.
|
|
|
|
```pwsh
|
|
PS C:/> Show-GitRepoRegistration Project-a
|
|
PS D:/Repos/Project-a> Get-Location -stack
|
|
|
|
Path
|
|
----
|
|
C:\
|
|
|
|
PS D:/Repos/Project-a> cd ./build
|
|
PS D:/Repos/Project-a/Build> Get-Location -stack
|
|
|
|
Path
|
|
----
|
|
C:\
|
|
|
|
PS D:/Repos/Project-a/Build> popd
|
|
PS C:/>
|
|
```
|
|
|
|
## Remove-GitRepoRegistration
|
|
|
|
`Remove-GitRepoRegistration [-Name string]`
|
|
|
|
Removes a repo registration by the given name, or if no name is specified, attempts to remove the git repo registered by resolving the git repo.
|
|
|
|
If `Name` is not provided then the command must be run in a location that is a git repo and the registration to remove will use the parent git repo folder name. If `Name` _is_ provided this command can be executed from any location.
|
|
|
|
```pwsh
|
|
# Default registration without a name within a folder in a git repo
|
|
PS D:/Repos/Project-a> New-GitRepoRegistration
|
|
|
|
# List registrations
|
|
PS D:/Repos/Project-a> Get-GitRepoRegistration
|
|
|
|
Name Location CurrentBranch
|
|
---- -------- -------------
|
|
Project-a D:/Repos/Project-a main
|
|
Test-Repo D:/Repos/Project-a main
|
|
|
|
# Remove a registration from within a git repo
|
|
PS D:/Repos/Project-a> Remove-GitRepoRegistration
|
|
# No output indicates successful removal
|
|
|
|
PS D:/Repos/Project-a> Get-GitRepoRegistration
|
|
|
|
Name Location CurrentBranch
|
|
---- -------- -------------
|
|
Test-Repo D:/Repos/Project-a main
|
|
|
|
# Duplicate calls error if there is no registration
|
|
PS D:/Repos/Project-a> Remove-GitRepoRegistration
|
|
Remove-GitRepoRegistration: No registration exists for 'Project-a'.
|
|
|
|
# Debug output via named argument
|
|
PS D:/Repos/Project-a> Remove-GitRepoRegistration -name Test-Repo -debug
|
|
DEBUG: Checking if current directory is a git repository...
|
|
DEBUG: ...location is a git repo!
|
|
DEBUG: Removed Test-Repo.
|
|
``` |