# 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.
```