docs: write documentation for release 0.2.0 (#45)

.github/workflows/docs.yml

@@ -53,10 +53,10 @@ jobs:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GH_GHCR }}
 
-      - run: docker pull ghcr.io/purpleclay/mkdocs-material-insiders
+      - run: docker pull ghcr.io/purpleclay/mkdocs-material-insiders:9.0.13-insiders-4.32.0
 
       - name: Build
-        run: docker run --rm -i -v ${PWD}:/docs ghcr.io/purpleclay/mkdocs-material-insiders build
+        run: docker run --rm -i -v ${PWD}:/docs ghcr.io/purpleclay/mkdocs-material-insiders:9.0.13-insiders-4.32.0 build
 
       - name: HTML Test
         uses: wjdp/htmltest-action@master
@@ -84,4 +84,4 @@ jobs:
 
       - name: Deploy documentation
         if: ${{ startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch') }}
-        run: docker run --rm -i -v ${PWD}:/docs ghcr.io/purpleclay/mkdocs-material-insiders gh-deploy --force
+        run: docker run --rm -i -v ${PWD}:/docs ghcr.io/purpleclay/mkdocs-material-insiders:9.0.13-insiders-4.32.0 gh-deploy --force

docs/git/checks.md

@@ -24,7 +24,7 @@ func main() {
 }
 ```
 
-## Checking the Integrity of a Repository
+## Checking the integrity of a Repository :material-new-box:{.new-feature title="Feature added on the 10th March 2023"}
 
 Check the integrity of a repository by running a series of tests and capturing the results for inspection.
 

docs/git/clone.md

@@ -0,0 +1,27 @@
+---
+icon: material/sheep
+status: new
+---
+
+# Cloning a Repository
+
+[:simple-git:{ .git-icon } Git Documentation](https://git-scm.com/docs/git-clone)
+
+Clone a repository by its provided URL into a newly created directory and check out an initial branch forked from the cloned repository’s default branch.
+
+## Clone everything :material-new-box:{.new-feature title="Feature added on the 10th March 2023"}
+
+Calling `Clone` will result in a repository containing all remote-tracking branches, tags, and a complete history.
+
+```{ .go .select linenums="1" }
+package main
+
+func main() {
+    client, _ := git.NewClient()
+
+    _, err := client.Clone("https://github.com/purpleclay/gitz")
+    if err != nil {
+        log.Fatal("failed to clone repository")
+    }
+}
+```

docs/git/log.md

@@ -1,5 +1,6 @@
 ---
 icon: material/list-box-outline
+status: new
 ---
 
 # Inspecting the Commit Log of a Repository
@@ -66,7 +67,7 @@ Printing the `Commits` property should now be an empty slice:
 
 ## View the log from a point in time
 
-The `WithRef` option provides a starting point other than HEAD (_most recent commit_) when retrieving the log history. A reference can be a `Commit Hash`, `Branch Name`, or `Tag`. Output from this option will be a shorter, fine-tuned log.
+When retrieving the log history, the `WithRef` option provides a starting point other than HEAD (_most recent commit_). A reference can be a `Commit Hash`, `Branch Name`, or `Tag`. Output from this option will be a shorter, fine-tuned log.
 
 ```{ .go .select linenums="1" }
 package main
@@ -136,3 +137,76 @@ Printing the `Raw` output from this command:
 d611a22c1a009bd74bc2c691b331b9df38828dae fix: typos in file content
 9b342465255d1a8ec4f5517eef6049e5bcc8fb45 feat: a brand new feature
 ```
+
+## Cherry-picking a section of the log :material-new-box:{.new-feature title="Feature added on the 10th March 2023"}
+
+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:
+
+```{ .go .select linenums="1" }
+package main
+
+func main() {
+    client, _ := git.NewClient()
+
+    // assuming the repository has the current history:
+    //  ~ docs: document fix
+    //  ~ fix: filtering on unsupported prefixes
+    //  ~ docs: create docs using material mkdocs
+    //  ~ feat: add new support for filtering based on prefixes
+    //  ~ initialized the repository
+
+    log, err := client.Log(git.WithSkip(1), git.WithTake(2))
+    if err != nil {
+        log.Fatal("failed to retrieve log using custom paths")
+    }
+
+    fmt.Println(log.Raw)
+}
+```
+
+Printing the `Raw` output from this command:
+
+```text
+9967e3c6196422a6a97afa4b6fca9f609bb5490b fix: filtering on unsupported prefixes
+1b1f4a725cfe44d5c9bd992be59f1130ed9d9911 docs: create docs using material mkdocs
+```
+
+## Filtering the log with pattern matching :material-new-box:{.new-feature title="Feature added on the 10th March 2023"}
+
+Filter the commit log to only contain entries that match any set of patterns (_regular expressions_) using the `WithGrep` option:
+
+```{ .go .select linenums="1" }
+package main
+
+func main() {
+    client, _ := git.NewClient()
+
+    // assuming the repository has the current history:
+    //  ~ fix: forgot to trim whitespace from patterns
+    //  ~ docs: document pattern matching option
+    //  ~ feat: filter log with pattern matching
+    //  ~ initialized the repository
+
+    log, err := client.Log(git.WithGrep("^docs", "matching$"))
+    if err != nil {
+        log.Fatal("failed to retrieve log with pattern matching")
+    }
+
+    fmt.Println(log.Raw)
+}
+```
+
+Printing the `Raw` output from this command, with matches highlighted for reference only:
+
+```text
+2d68a506fe7d5148db0a10ea143752991a65c26d {==docs==}: document pattern matching option
+5bfd532328ed2e9ea6d3062eb3a331f42468a7e3 feat: filter log with pattern {==matching==}
+```
+
+### Filter entries that do not match
+
+Combining the `WithInvertGrep` and `WithGrep` options will inverse pattern matching and filter on log entries that do not contain any of the provided patterns.
+
+### Filter entries that match all patterns
+
+Pattern matching uses `or` semantics by default, matching on log entries that satisfy any of the defined patterns. You can change this behavior to match against all patterns using `and` semantics with the `WithMatchAll` option.

docs/git/stage.md

@@ -1,5 +1,6 @@
 ---
 icon: material/archive-lock-open-outline
+status: new
 ---
 
 # Staging changes within a Repository
@@ -8,9 +9,39 @@ icon: material/archive-lock-open-outline
 
 Stage changes to a particular file or folder within the current repository for inclusion within the next commit. Staging is a prerequisite to committing and pushing changes back to the repository remote.
 
-## Staging a File or Folder
+## Staging all changes :material-new-box:{.new-feature title="Feature added on the 10th March 2023"}
 
-Calling `Stage` with a relative path to an individual file or folder will stage any changes:
+By default, all files (`tracked` and `untracked`) within the current repository are staged automatically unless explicitly ignored through a `.gitignore` file:
+
+```{ .go .select linenums="1" }
+package main
+
+func main() {
+    client, _ := git.NewClient()
+
+    // create multiple files within the following hierarchy:
+    //  > a.txt
+    //  > b.txt
+
+    _, err := client.Stage()
+    if err != nil {
+        log.Fatal("failed to stage all files")
+    }
+}
+```
+
+And to verify the staged changes:
+
+```sh
+$ git status --porcelain
+
+A  a.txt
+A  b.txt
+```
+
+## Staging a file or folder
+
+Cherry-picking the staging of files and folders is accomplished using the `WithPathSpecs` option:
 
 ```{ .go .select linenums="1" }
 package main
@@ -24,29 +55,19 @@ func main() {
     //    > a.txt
     //    > b.txt
 
-    _, err := client.Stage("root.txt")
-    if err != nil {
-        log.Fatal("failed to stage file root.txt")
-    }
-
-    _, err := client.Stage("folder/")
+    _, err := client.Stage(git.WithPathSpecs("root.txt", "folder/a.txt"))
     if err != nil {
-        log.Fatal("failed to stage all changes within directory folder/")
+        log.Fatal("failed to stage files")
     }
 }
 ```
 
 And to verify the staged changes:
 
 ```sh
-$ git status
-
-On branch main
-Your branch is up to date with 'origin/main'.
+$ git status --porcelain
 
-Changes to be committed:
-  (use "git restore --staged <file>..." to unstage)
-    new file:   folder/a.txt
-    new file:   folder/b.txt
-    new file:   root.txt
+A  folder/a.txt
+?? folder/b.txt
+A  root.txt
 ```

docs/stylesheets/extra.css

@@ -20,4 +20,19 @@
 
 .md-typeset a:hover>span * {
     filter: brightness(85%);
+}
+
+@keyframes new-feature {
+    0%, 100% {
+        transform: scale(1) rotate(0deg);
+    }
+
+    50% {
+        transform: scale(1.15) rotate(10deg);
+    }
+}
+
+.new-feature {
+    color: #006C39;
+    animation: new-feature 2000ms infinite;
 }

docs/testing/git-test.md

@@ -1,5 +1,6 @@
 ---
 icon: material/test-tube
+status: new
 ---
 
 # Testing your Interactions with Git
@@ -121,11 +122,36 @@ func TestGreatFeature(t *testing.T) {
 }
 ```
 
+### With clone depth :material-new-box:{.new-feature title="Feature added on the 10th March 2023"}
+
+Shallow clone a repository by truncating its history to a set depth.
+
+```{ .go .select linenums="1" }
+func TestGreatFeature(t *testing.T) {
+    log := `(tag: 0.1.0) feat: this is a brand new feature
+docs: write amazing material mkdocs documentation
+ci: include github release workflow`
+    gittest.InitRepository(t,
+        gittest.WithLog(log), gittest.WithCloneDepth(1))
+
+    // test logic and assertions to follow ...
+}
+```
+
+Querying the repository log:
+
+```text
+$ git log --pretty=oneline --no-decorate --no-color
+
+e03726d3c24bbbab106bd1ac6231c030e1296eb9 feat: this is a brand new feature
+```
+
 ### Option initialization order
 
 You can use any combination of options during repository initialization, but a strict order is applied.
 
 1. `WithLog`: log history imported, both local and remote are in sync.
+1. `WithCloneDepth`: shallow clone at the required depth.
 1. `WithRemoteLog`: remote log history imported, creating a delta between local and remote.
 1. `WithLocalCommits`: local commits created and not pushed back to remote.
 1. `WithFiles` and `WithStagedFiles`: files generated and staged if needed.

log.go

@@ -115,8 +115,8 @@ func WithRawOnly() LogOption {
 // WithSkip skips any number of most recent commits from within the log
 // history. A positive number (greater than zero) is expected. Skipping
 // more commits than exists, will result in no history being retrieved.
-// Skipping zero commits, will retrieve the entire log. The option can
-// has a higher order of precedence than [git.WithTake]
+// Skipping zero commits, will retrieve the entire log. This option has
+// a higher order of precedence than [git.WithTake]
 func WithSkip(n int) LogOption {
 	return func(opts *logOptions) {
 		opts.SkipCount = n

mkdocs.yml

@@ -27,6 +27,7 @@ theme:
     - search.highlight
     - search.share
     - search.suggest
+    - toc.follow
   icon:
     repo: fontawesome/brands/github
   font:
@@ -40,6 +41,7 @@ nav:
   - Home: index.md
   - Getting Started:
       - Git Checks: git/checks.md
+      - Git Clone: git/clone.md
       - Git Pull: git/pull.md
       - Git Push: git/push.md
       - Git Stage: git/stage.md
@@ -71,7 +73,7 @@ extra:
       link: https://pkg.go.dev/github.com/purpleclay/gitz
       name: Gitz GoDocs
   status:
-    new: New Feature
+    new: New Features Added
     deprecated: No Longer Supported
 
 plugins:
@@ -85,12 +87,18 @@ plugins:
       minify_html: true
   - search
   - social
+  - typeset
 
 markdown_extensions:
+  - abbr
   - admonition
   - attr_list
   - def_list
   - footnotes
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic
   - pymdownx.details
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
@@ -100,10 +108,12 @@ markdown_extensions:
       line_spans: __span
       pygments_lang_class: true
   - pymdownx.inlinehilite
+  - pymdownx.mark
   - pymdownx.snippets
   - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true
+  - pymdownx.tilde
   - md_in_html
   - meta
   - toc: