docs: write documentation for release 0.4.0 (#85)

docs/git/checkout.md

@@ -1,6 +1,5 @@
 ---
 icon: material/source-branch-sync
-status: new
 title: Checking out a branch
 description: Clone a repository by its provided URL into a newly created directory
 ---

docs/git/clone.md

@@ -1,6 +1,5 @@
 ---
 icon: material/sheep
-status: new
 title: Cloning a repository
 description: Clone a repository by its provided URL into a newly created directory
 ---
@@ -74,7 +73,7 @@ func main() {
 
 Printing the log results in:
 
-```text
+```{ .text .no-select .no-copy }
 feat: add options that can configure the size of the repository during a clone
 ```
 
@@ -114,7 +113,7 @@ func main() {
 
 Printing the output results in:
 
-```text
+```{ .text .no-select .no-copy }
 repository has no tags
 ```
 

docs/git/config.md

@@ -0,0 +1,126 @@
+---
+icon: material/keyboard-settings-outline
+status: new
+title: Managing your git config
+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
+
+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"}
+
+Providing a valid path to `Config` will retrieve all values associated with a setting in modification order.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "fmt"
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+    // setting user.name to purpleclay to cover up real identity
+
+    cfg, err := client.Config("user.name")
+    if err != nil {
+        log.Fatal("failed to retrieve config setting")
+    }
+
+    for _, v := range cfg {
+        fmt.Println(v)
+    }
+}
+```
+
+The values 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"}
+
+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.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "fmt"
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+    cfg, err := client.ConfigL("user.name", "user.email")
+    if err != nil {
+        log.Fatal("failed to retrieve config settings")
+    }
+
+    fmt.Println(cfg["user.name"][0])
+    fmt.Println(cfg["user.email"][0])
+}
+```
+
+The value for each config setting would be:
+
+```{ .text .no-select .no-copy }
+purpleclay
+**********************
+```
+
+## Update a local setting :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
+
+To update a local git setting, call `ConfigSet`` with a path and corresponding value.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+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")
+    }
+}
+```

docs/git/log.md

@@ -1,5 +1,6 @@
 ---
 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
 ---
@@ -174,6 +175,10 @@ d611a22c1a009bd74bc2c691b331b9df38828dae fix: typos in file content
 9b342465255d1a8ec4f5517eef6049e5bcc8fb45 feat: a brand new feature
 ```
 
+### Resolving explicit file paths :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
+
+Querying the log with explicit paths isn't supported and will return no history. Converting to a relative one can be achieved with the `ToRelativePath` helper, as it resolves paths against the root working directory of the current repository.
+
 ## Cherry-picking a section of the log
 
 Cherry-pick a section of the log by skipping and taking a set number of entries using the respective `WithSkip` and `WithTake` options. If combined, skipping has a higher order of precedence:

docs/git/push.md

@@ -1,6 +1,5 @@
 ---
 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
 ---

docs/git/tag.md

@@ -84,7 +84,7 @@ created tag 0.1.0
 associated commit message
 ```
 
-## Retrieving all tags :material-new-box:{.new-feature title="Feature added on the 23rd March of 2023"}
+## Retrieving all tags
 
 Calling `Tags` will retrieve all tags from the current repository in ascending lexicographic order:
 
@@ -115,14 +115,14 @@ func main() {
 
 The resulting output would be:
 
-```text
+```{ .text .no-select .no-copy }
 0.10.0
 0.11.0
 0.9.0
 0.9.1
 ```
 
-### Changing the sort order :material-new-box:{.new-feature title="Feature added on the 23rd March of 2023"}
+### Changing the sort order
 
 You can change the default sort order when retrieving tags by using the `WithSortBy` option. Various [sort keys](https://git-scm.com/docs/git-for-each-ref#_field_names) exist, each affecting the overall sort differently. If using multiple sort keys, the last one becomes the primary key. Prefix any key with a `-` for a descending sort. For convenience `gitz` provides constants for the most common sort keys:
 
@@ -159,14 +159,14 @@ func main() {
 
 The resulting output would now be:
 
-```text
+```{ .text .no-select .no-copy }
 0.11.0
 0.10.0
 0.9.1
 0.9.0
 ```
 
-### Filtering by pattern :material-new-box:{.new-feature title="Feature added on the 23rd March of 2023"}
+### Filtering by pattern
 
 Filter local tags using pattern-based git [shell globs](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm) with the `WithShellGlob` option. If using multiple patterns, a tag only needs to match one.
 
@@ -187,7 +187,7 @@ func main() {
 
     tags, err := client.Tags(git.WithShellGlob("*.*.*"))
     if err != nil {
-        log.Fatal("failed to delete tag)
+        log.Fatal("failed to retrieve local repository tags")
     }
 
     for _, tag := range tags {
@@ -198,12 +198,96 @@ func main() {
 
 The filtered output would be:
 
-```text
+```{ .text .no-select .no-copy }
 0.8.0
 0.9.0
 1.0.0
 ```
 
+### User-defined filters :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
+
+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.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "fmt"
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+var (
+    uiFilter = func(tag string) bool {
+        return strings.HasPrefix(tag, "ui/")
+    }
+
+    noVTagsFilter := func(tag string) bool {
+        return !strings.HasSuffix(tag, "v1")
+    }
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    // Repository contains tags ui/1.0.0, ui/v1, backend/1.0.0, backend/v1
+
+    tags, err := client.Tags(git.WithFilters(uiFilter, noVTagsFilter))
+    if err != nil {
+        log.Fatal("failed to retrieve local repository tags")
+    }
+
+    for _, tag := range tags {
+        fmt.Println(tag)
+    }
+}
+```
+
+The filtered output would be:
+
+```{ .text .no-select .no-copy }
+ui/0.1.0
+```
+
+### Limiting the number of tags :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
+
+Define the maximum number of returned tags through the `WithCount` option. Limiting is applied as a post-processing step after all other options.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "fmt"
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    // Repository contains tags 0.1.0, 0.2.0, 0.3.0, 0.4.0
+
+    tags, err := client.Tags(git.WithSortBy(git.VersionDesc),
+        git.WithCount(2))
+    if err != nil {
+        log.Fatal("failed to retrieve local repository tags")
+    }
+
+    for _, tag := range tags {
+        fmt.Println(tag)
+    }
+}
+```
+
+The limited output would be:
+
+```{ .text .no-select .no-copy }
+0.4.0
+0.3.0
+```
+
 ## Deleting a tag
 
 Call `DeleteTag` to delete a local tag and sync it with the remote:

docs/testing/git-test.md

@@ -1,5 +1,6 @@
 ---
 icon: material/test-tube
+status: new
 title: Testing your interactions with git
 description: A dedicated package for testing your interactions with git
 ---
@@ -74,6 +75,20 @@ ci: include github release workflow`
 }
 ```
 
+#### Multi-line commits :material-new-box:{.new-feature title="Feature added on the 31st March of 2023"}
+
+Import multi-line commits by prefixing each commit with a `>` token. The expected format is equivalent to the output from the git command:
+
+`git log --pretty='format:> %d %s%+b%-N'`
+
+```{ .text .no-select .no-copy }
+> (tag: 0.1.0, main, origin/main) feat: multi-line commits is supported
+> feat(deps): bump github.com/stretchr/testify from 1.8.1 to 1.8.2
+
+Signed-off-by: dependabot[bot] <[email protected]>
+Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
+```
+
 ### With a remote log
 
 Initialize the remote origin of a repository with a predefined log using the `WithRemoteLog` option. Ideal for simulating a delta between the current log and its remote counterpart.

mkdocs.yml

@@ -42,6 +42,7 @@ nav:
   - Getting Started:
       - Git Checks: git/checks.md
       - Git Clone: git/clone.md
+      - Git Config: git/config.md
       - Git Checkout: git/checkout.md
       - Git Pull: git/pull.md
       - Git Push: git/push.md