docs: write documentation for release 0.5.0 (#95)

docs/git/commit.md

@@ -1,5 +1,6 @@
 ---
 icon: material/archive-lock-outline
+status: new
 title: Committing changes to a repository
 description: Create a commit within the current repository and describe those changes with a given log message
 ---
@@ -46,3 +47,97 @@ Date:   Mon Feb 20 20:43:49 2023 +0000
 
     feat: a brand new feature
 ```
+
+## Allowing an empty commit :material-new-box:{.new-feature title="Feature added on the 16th of May 2023"}
+
+You can create empty commits without staging any files using the `WithAllowEmpty` option.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+    client.Commit("no files are staged here", git.WithAllowEmpty())
+}
+```
+
+## Signing a commit using GPG :material-new-box:{.new-feature title="Feature added on the 16th of May 2023"}
+
+Any commit to a repository can be GPG signed by an author to prove its authenticity through GPG verification. By setting the `commit.gpgSign` and `user.signingKey` git config options, GPG signing, can become an automatic process. `gitz` provides options to control this process and manually overwrite existing settings per commit.
+
+### Sign an individual commit
+
+If the `commit.gpgSign` git config setting is not enabled; you can selectively GPG sign a commit using the `WithGpgSign` option.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    _, err := client.Commit("no files are staged here",
+        git.WithAllowEmpty(),
+        git.WithGpgSign())
+    if err != nil {
+        log.Fatal("failed to gpg sign commit with user.signingKey")
+    }
+}
+```
+
+### Select a GPG signing key
+
+If multiple GPG keys exist, you can cherry-pick a key during a commit using the `WithGpgSigningKey` option, overriding the `user.signingKey` git config setting, if set.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    _, err := client.Commit("no files are staged here",
+        git.WithAllowEmpty(),
+        git.WithGpgSigningKey("E5389A1079D5A52F"))
+    if err != nil {
+        log.Fatal("failed to gpg sign commit with provided public key")
+    }
+}
+```
+
+### Prevent a commit from being signed
+
+You can disable the GPG signing of a commit by using the `WithNoGpgSign` option, overriding the `commit.gpgSign` git config setting, if set.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+    client.Commit("prevent commit from being signed",
+        git.WithAllowEmpty(),
+        git.WithNoGpgSign())
+}
+```

docs/git/config.md

@@ -7,13 +7,13 @@ description: Get and set your local git repository config
 
 # Managing your git config
 
-[:simple-git:{ .git-icon } Git Documentation](https://git-scm.com/docs/git-config) | :material-beaker-outline: Experimental
+[:simple-git:{ .git-icon } Git Documentation](https://git-scm.com/docs/git-config)
 
 Manage settings within your local git config, changing the behavior of the git client.
 
-## Retrieve a local setting :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
+## Retrieve all settings :material-new-box:{.new-feature title="Feature added on the 16th of May 2023"}
 
-Providing a valid path to `Config` will retrieve all values associated with a setting in modification order.
+Retrieve all git config for the current repository using `Config`.
 
 ```{ .go .select linenums="1" }
 package main
@@ -27,29 +27,25 @@ import (
 
 func main() {
     client, _ := git.NewClient()
-    // setting user.name to purpleclay to cover up real identity
 
-    cfg, err := client.Config("user.name")
+    cfg, err := client.Config()
     if err != nil {
-        log.Fatal("failed to retrieve config setting")
+        log.Fatal("failed to retrieve config for current repository")
     }
 
-    for _, v := range cfg {
-        fmt.Println(v)
-    }
+    fmt.Println(cfg["user.name"])
 }
 ```
 
-The values for the config setting would be:
+The value for the config setting would be:
 
 ```{ .text .no-select .no-copy }
 purpleclay
-****
 ```
 
-## Retrieve a batch of local settings :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
+## Retrieve a batch of settings :material-new-box:{.new-feature title="Feature added on the 16th of May 2023"}
 
-For convenience, multiple local settings can be retrieved in a batch using `ConfigL`. A partial batch is not supported and will fail if any setting does not exist.
+A batch of settings can be retrieved using `ConfigL` (_local_), `ConfigS` (_system_), or `ConfigG` (_global_). A partial retrieval is not supported and will fail if any are missing. All values for a setting are retrieved and ordered by the latest.
 
 ```{ .go .select linenums="1" }
 package main
@@ -65,7 +61,7 @@ func main() {
     client, _ := git.NewClient()
     cfg, err := client.ConfigL("user.name", "user.email")
     if err != nil {
-        log.Fatal("failed to retrieve config settings")
+        log.Fatal("failed to retrieve local config settings")
     }
 
     fmt.Println(cfg["user.name"][0])
@@ -80,9 +76,9 @@ purpleclay
 **********************
 ```
 
-## Update a local setting :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
+## Update a batch of settings :material-new-box:{.new-feature title="Feature added on the 16th of May 2023"}
 
-To update a local git setting, call `ConfigSet`` with a path and corresponding value.
+You can update multiple settings in a batch using `ConfigSetL` (_local_), `ConfigSetS` (_system_), or `ConfigSetG` (_global_). Pre-validation of config paths improves the chance of a successful update, but a partial batch may occur upon failure.
 
 ```{ .go .select linenums="1" }
 package main
@@ -95,32 +91,11 @@ import (
 
 func main() {
     client, _ := git.NewClient()
-    err := client.ConfigSet("custom.setting", "value")
-    if err != nil {
-        log.Fatal("failed to set config setting")
-    }
-}
-```
-
-## Updating a batch of local settings :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
-
-Multiple local settings can be updated in a batch using `ConfigSetL`. Pre-validation of config paths improves the chance of a successful update, but a partial batch may occur upon failure.
-
-```{ .go .select linenums="1" }
-package main
 
-import (
-    "log"
-
-    git "github.com/purpleclay/gitz"
-)
-
-func main() {
-    client, _ := git.NewClient()
     err := client.ConfigSetL("custom.setting1", "value",
         "custom.setting2", "value")
     if err != nil {
-        log.Fatal("failed to set config setting")
+        log.Fatal("failed to set local config settings")
     }
 }
 ```

docs/git/log.md

@@ -1,6 +1,5 @@
 ---
 icon: material/list-box-outline
-status: new
 title: Inspecting the commit log of a repository
 description: Retrieve the commit log of a repository in an easy-to-parse format
 ---

docs/git/push.md

@@ -1,5 +1,6 @@
 ---
 icon: material/arrow-right-bold-box-outline
+status: new
 title: Pushing the latest changes back to a remote
 description: Push all local repository changes back to the remote
 ---
@@ -35,7 +36,7 @@ func main() {
 }
 ```
 
-## Pushing all local branches :material-new-box:{.new-feature title="Feature added on the 23rd March of 2023"}
+## Pushing all local branches
 
 To push changes spread across multiple branches back to the remote in a single atomic operation, use the `WillAllBranches` option:
 
@@ -66,7 +67,7 @@ func main() {
 }
 ```
 
-## Pushing all local tags :material-new-box:{.new-feature title="Feature added on the 23rd March of 2023"}
+## Pushing all local tags
 
 All locally created tags can also be pushed back to the remote in a single atomic operation using the `WithAllTags` option:
 
@@ -91,7 +92,7 @@ func main() {
 }
 ```
 
-## Cherry-pick what is pushed to the remote :material-new-box:{.new-feature title="Feature added on the 23rd March of 2023"}
+## Cherry-pick what is pushed to the remote
 
 The `WithRefSpecs` option provides greater freedom to cherry-pick locally created references (_branches and tags_) and push them back to the remote. A reference can be as simple as a name or as explicit as providing a source (_local_) to destination (_remote_) mapping. Please read the official git specification on how to construct [refspecs](https://git-scm.com/docs/git-push#Documentation/git-push.txt-ltrefspecgt82308203).
 
@@ -116,7 +117,7 @@ func main() {
 }
 ```
 
-## Push a single branch or tag :material-new-box:{.new-feature title="Feature added on the 23rd March of 2023"}
+## Push a single branch or tag
 
 `PushRef` can be called to cherry-pick and push a single reference (_branch or tag_) back to the remote:
 
@@ -140,3 +141,28 @@ func main() {
     }
 }
 ```
+
+## Push options :material-new-box:{.new-feature title="Feature added on the 16th of May 2023"}
+
+Support the transmission of arbitrary strings to the remote server using the `WithPushOptions` option.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    // all changes have been staged and committed locally
+
+    _, err := client.Push(git.WithPushOptions("ci.skip=true"))
+    if err != nil {
+        log.Fatal("failed to push committed changes to the remote")
+    }
+}
+```

docs/git/tag.md

@@ -204,7 +204,7 @@ The filtered output would be:
 1.0.0
 ```
 
-### User-defined filters :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
+### User-defined filters
 
 Extend filtering by applying user-defined filters to the list of retrieved tags with the `WithFilters` option. Execution of filters is in the order defined.
 
@@ -250,7 +250,7 @@ The filtered output would be:
 ui/0.1.0
 ```
 
-### Limiting the number of tags :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
+### Limiting the number of tags
 
 Define the maximum number of returned tags through the `WithCount` option. Limiting is applied as a post-processing step after all other options.
 
@@ -314,3 +314,76 @@ func main() {
 ```
 
 [^1]: Gitz defers the validation of a tag name to the git client. Any error is captured and returned back to the caller
+
+## Signing a tag using GPG :material-new-box:{.new-feature title="Feature added on the 16th of May 2023"}
+
+Any tag against a repository can be GPG signed by the tagger to prove its authenticity through GPG verification. By setting the `tag.gpgSign` and `user.signingKey` git config options, GPG signing, can become an automatic process. `gitz` provides options to control this process and manually overwrite existing settings per tag.
+
+### Annotating the signed tag
+
+A signed tag must have an annotation. `gitz` defaults this to `created tag <ref>`, but you can change this with the `WithAnnotation` option.
+
+### Sign an individual tag
+
+If the `tag.gpgSign` git config setting is not enabled, you can selectively GPG sign a tag using the `WithSigned` option.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    _, err := client.Tag("0.1.0", git.WithSigned())
+    if err != nil {
+        log.Fatal("failed to gpg sign tag with user.signingKey")
+    }
+}
+```
+
+### Select a GPG signing key
+
+If multiple GPG keys exist, you can cherry-pick a key when tagging using the `WithSigningKey` option, overriding the `user.signingKey` git config setting, if set.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    _, err := client.Tag("0.1.0", git.WithSigningKey("E5389A1079D5A52F"))
+    if err != nil {
+        log.Fatal("failed to gpg sign tag with provided public key")
+    }
+}
+```
+
+### Prevent a tag from being signed
+
+You can disable the GPG signing of a tag by using the `WithSkipSigning` option, overriding the `tag.gpgSign` git config setting if set.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+    client.Tag("0.1.0", git.WithSkipSigning())
+}
+```