docs: include 0.7.0 features and fixes in documentation (#131)

docs/git/checks.md

@@ -1,6 +1,5 @@
 ---
 icon: material/clipboard-check-outline
-status: new
 title: Git checks and how to use them
 description: A series of inbuilt check for inspecting the environment and current repository
 ---
@@ -33,7 +32,7 @@ func main() {
 }
 ```
 
-## Checking the integrity of a Repository :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+## Checking the integrity of a Repository
 
 Check the integrity of a repository by running a series of tests and capturing the results for inspection.
 

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
 ---
@@ -166,6 +165,6 @@ func main() {
 }
 ```
 
-## Providing git config at execution :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+## Providing git config at execution
 
 You can provide git config through the `WithCloneConfig` option to only take effect during the execution of a `Clone`, removing the need to change config permanently.

docs/git/commit.md

@@ -1,6 +1,5 @@
 ---
 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
 ---
@@ -142,6 +141,6 @@ func main() {
 }
 ```
 
-## Providing git config at execution :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+## Providing git config at execution
 
 You can provide git config through the `WithCommitConfig` option to only take effect during the execution of a `Commit`, removing the need to change config permanently.

docs/git/fetch.md

@@ -0,0 +1,169 @@
+---
+icon: material/clipboard-arrow-left-outline
+status: new
+title: Fetching the latest changes from a remote
+description: Fetch all changes from a remote without integrating them into the current working directory
+---
+
+# Fetching the latest changes from a remote
+
+[:simple-git:{ .git-icon } Git Documentation](https://git-scm.com/docs/git-fetch)
+
+Fetch all remote changes from a remote repository without integrating (merging) them into the current repository (working directory). Ensures the existing repository only tracks the latest remote changes.
+
+## Fetch all changes
+
+Calling `Fetch` without any options will attempt to retrieve and track all the latest changes from the default remote.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    _, err := client.Fetch()
+    if err != nil {
+        log.Fatal("failed to fetch all changes from the remote")
+    }
+}
+```
+
+## Fetch from all remotes
+
+To fetch the latest changes from all tracked remotes, use the `WithAll` option.
+
+## Fetch and follow tags
+
+Retrieve all of the latest tags and track them locally with the `WithTags` option.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "fmt"
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    // Existing locally tracked tags: 0.1.0
+    // Additional tags that exist at the remote: 0.2.0, 0.3.0
+
+    _, err := client.Fetch(git.WithTags())
+    if err != nil {
+        log.Fatal("failed to fetch all changes from the remote")
+    }
+
+    tags, err := client.Tags()
+    if err != nil {
+        log.Fatal("failed to retrieve local repository tags")
+    }
+
+    for _, tag := range tags {
+        fmt.Println(tag)
+    }
+}
+```
+
+```{ .text .no-select .no-copy }
+0.1.0
+0.2.0
+0.3.0
+```
+
+## Fetch but do not follow tags
+
+The `WithIgnoreTags` option turns off local tracking of tags retrieved from the remote.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "fmt"
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    // Existing locally tracked tags: 0.1.0
+    // Additional tags that exist at the remote: 0.2.0, 0.3.0
+
+    _, err := client.Fetch(git.WithIgnoreTags())
+    if err != nil {
+        log.Fatal("failed to fetch all changes from the remote")
+    }
+
+    tags, err := client.Tags()
+    if err != nil {
+        log.Fatal("failed to retrieve local repository tags")
+    }
+
+    for _, tag := range tags {
+        fmt.Println(tag)
+    }
+}
+```
+
+```{ .text .no-select .no-copy }
+0.1.0
+```
+
+## Limit fetching of commit history
+
+Limit the number of commits fetched from the tip of each remote branch history, using the `WithDepthTo` option. This can be used to deepen or shorten the existing history of a shallow cloned repository.
+
+```{ .go .select linenums="1" }
+package main
+
+import (
+    "fmt"
+    "log"
+
+    git "github.com/purpleclay/gitz"
+)
+
+func main() {
+    client, _ := git.NewClient()
+
+    _, err := client.Fetch(git.WithDepthTo(2))
+    if err != nil {
+        log.Fatal("failed to fetch all changes from the remote")
+    }
+
+    repoLog, err := client.Log()
+    if err != nil {
+        log.Fatal("failed to retrieve repository log")
+    }
+
+    for _, commit := range repoLog.Commits {
+        fmt.Println(commit.Message)
+    }
+}
+```
+
+Printing the log results in:
+
+```{ .text .no-select .no-copy }
+feat: add initial support for git fetch
+feat: extend pull options to control how change sets are retrieved
+```
+
+## Force fetching into an existing local branch
+
+Fetching may be refused if updating a locally tracked branch through the `WithFetchRefSpecs` option. Use the `WithForce` option to turn off this check.
+
+## Providing git config at execution
+
+You can provide git config through the `WithFetchConfig` option to only take effect during the execution of a `Fetch`, removing the need to change config permanently.

docs/git/pull.md

@@ -2,7 +2,7 @@
 icon: material/arrow-left-bold-box-outline
 status: new
 title: Pulling the latest changes from a remote
-description: Pull all changes from a remote into the current working directory
+description: Pull all changes from a remote and integrate them into the current working directory
 ---
 
 # Pulling the latest changes from a remote
@@ -58,6 +58,12 @@ Fast-forward
  create mode 100644 folder/c.txt
 ```
 
-## Providing git config at execution :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+## Configuring fetch behavior :material-new-box:{.new-feature title="Feature added on the 21st of August 2023"}
+
+When pulling changes from a remote repository, a fetch happens before merging any changes. Configuring the behavior of this fetch is possible using the supported `WithFetch...` [options](./fetch.md).
+
+For example, you can limit the fetched commit history with the `WithFetchDepthTo` option.
+
+## Providing git config at execution
 
 You can provide git config through the `WithPullConfig` option to only take effect during the execution of a `Pull`, removing the need to change config permanently.

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
 ---
@@ -142,7 +141,7 @@ func main() {
 }
 ```
 
-## Deleting references from the remote :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+## Deleting references from the remote
 
 Delete any number of references from the remote by using the `WithDeleteRefSpecs` option.
 
@@ -167,6 +166,6 @@ func main() {
 }
 ```
 
-## Providing git config at execution :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+## Providing git config at execution
 
 You can provide git config through the `WithPushConfig` option to only take effect during the execution of a `Push`, removing the need to change config permanently.

docs/git/show.md

@@ -1,6 +1,5 @@
 ---
 icon: material/text-search
-status: new
 title: Inspect an object within a repository
 description: Retrieve details about a specific object from within a repository
 ---

docs/git/status.md

@@ -1,6 +1,5 @@
 ---
 icon: material/format-list-checkbox
-status: new
 title: Inspecting the status of a repository
 description: Check the status of the current repository and identify if any changes exist
 ---
@@ -11,7 +10,7 @@ description: Check the status of the current repository and identify if any chan
 
 Identify if any differences exist between the git staging area (_known as the index_) and the latest commit.
 
-## Porcelain status :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+## Porcelain status
 
 To retrieve a parseable list of changes within a repository, call `PorcelainStatus`. Changes are listed using the porcelain V1 format, consisting of a two-character indicator followed by a path to the identified change.
 
@@ -61,7 +60,7 @@ A two-character indicator, `' A'`, denotes the status of a file. It should be re
 '?' Untracked
 ```
 
-## Check if a repository is clean :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+## Check if a repository is clean
 
 Calling `Clean` will return `true` if a repository has no outstanding changes.
 

docs/git/tag.md

@@ -84,6 +84,10 @@ created tag 0.1.0
 associated commit message
 ```
 
+### Creating a local tag :material-new-box:{.new-feature title="Feature added on the 21st of August 2023"}
+
+Use the `WithLocalOnly` option to prevent a tag from being pushed back to the remote.
+
 ## Retrieving all tags
 
 Calling `Tags` will retrieve all tags from the current repository in ascending lexicographic order:
@@ -315,11 +319,11 @@ 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
 
-### Only delete local reference :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+### Only delete local reference
 
 To prevent a deletion from being pushed back to the remote, use the `WithLocalDelete` option.
 
-## Deleting multiple tags :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+## Deleting multiple tags
 
 Call `DeleteTags` if you need to delete a batch of tags and sync it with the remote. Use the `WithLocalDelete` option to prevent any deletion from being pushed back to the remote.
 
@@ -396,6 +400,6 @@ func main() {
 }
 ```
 
-## Providing git config at execution :material-new-box:{.new-feature title="Feature added on the 26th of July 2023"}
+## Providing git config at execution
 
 You can provide git config through the `WithTagConfig` option to only take effect during the execution of a `Tag`, removing the need to change config permanently.

docs/testing/git-test.md

@@ -2,6 +2,7 @@
 icon: material/test-tube
 title: Testing your interactions with git
 description: A dedicated package for testing your interactions with git
+status: new
 ---
 
 # Testing your interactions with git
@@ -164,6 +165,53 @@ func TestInitRepositoryWithStagedFiles(t *testing.T) {
 }
 ```
 
+### With committed files :material-new-box:{.new-feature title="Feature added on the 21st of August 2023"}
+
+Create a set of files that will be committed to the repository using the `WithCommittedFiles` option. A single commit of `include test files` will be created.
+
+```{ .go .select linenums="1" }
+package git_test
+
+import (
+    "testing"
+
+    "github.com/purpleclay/gitz/gittest"
+    "github.com/stretchr/testify/assert"
+)
+
+func TestInitRepositoryWithCommittedFiles(t *testing.T) {
+    gittest.InitRepository(t,
+       gittest.WithCommittedFiles("a.txt", "dir/b.txt"))
+
+    status := gittest.PorcelainStatus(t)
+    assert.Empty(t, status)
+}
+```
+
+### With file content :material-new-box:{.new-feature title="Feature added on the 21st of August 2023"}
+
+Allows files created with the `WithFiles`, `WithStagedFiles` or `WithCommittedFiles` options to be overwritten with user-defined content. Key value pairs must be provided to the `WithFileContent` option when overriding existing files.
+
+```{ .go .select linenums="1" }
+package git_test
+
+import (
+    "testing"
+
+    "github.com/purpleclay/gitz/gittest"
+    "github.com/stretchr/testify/assert"
+)
+
+func TestInitRepositoryWithFileContent(t *testing.T) {
+    gittest.InitRepository(t,
+		gittest.WithCommittedFiles("a.txt", "dir/b.txt"),
+		gittest.WithFileContent("a.txt", "hello", "dir/b.txt", "world!"))
+
+	assert.Equal(t, "hello", gittest.Blob(t, "a.txt"))
+	assert.Equal(t, "world!", gittest.Blob(t, "dir/b.txt"))
+}
+```
+
 ### With local commits
 
 Generate a set of local empty commits, ready to be pushed back to the remote, with the `WithLocalCommits` option. Generated Commits will be in chronological order.
@@ -235,4 +283,5 @@ You can use any combination of options during repository initialization, but a s
 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.
+1. `WithFiles`, `WithCommittedFiles` and `WithStagedFiles`: files generated and either committed or staged if needed.
+1. `WithFileContent`: Overwrites existing files with user-defined content.