docs: add a section to the documentation about setting options (#204)

purpleclay · Dec 28, 2024 · fdc8205 · fdc8205
1 parent 192b1e7
commit fdc8205
Show file tree

Hide file tree

Showing 13 changed files with 55 additions and 14 deletions.
diff --git a/docs/git-repair.md b/docs/git-repair.md
@@ -1,7 +1,6 @@
 ---
 icon: material/tools
 description: Repair a git repository ready for versioning
-status: new
 ---
 
 # Repair a repository ready for versioning

diff --git a/docs/install/binary.md b/docs/install/binary.md
@@ -2,7 +2,6 @@
 icon: material/package-variant-closed
 social:
   cards: false
-status: new
 ---
 
 # Installing the Binary

diff --git a/docs/options.md b/docs/options.md
@@ -0,0 +1,35 @@
+---
+icon: material/cog-outline
+social:
+  cards: false
+status: new
+---
+
+# Different ways of customizing NSV
+
+`nsv` is designed to be config-free and requires minimal to no runtime options to release your software. If you need to set config, you have one of <u>three ways</u>, ordered from highest to lowest precedence.
+
+## CLI flags
+
+A CLI flag is the most explicit way to set an option and will always override the other two methods.
+
+```{ .sh .no-select }
+nsv next --format "{{.SemVer}}" --fix-shallow
+```
+
+## Environment variables
+
+Environment variables provide great flexibility and support dynamic setting of options, for example, within a CI pipeline.
+
+```{ .sh .no-select }
+NSV_FORMAT="{{.SemVer}}" NSV_FIX_SHALLOW="true" nsv next
+```
+
+## DotEnv file
+
+A `.env` file located in the root of a project is automatically loaded at runtime and injected into the `nsv` context.
+
+```{ .sh .no-select }
+NSV_FORMAT="{{.SemVer}}"
+NSV_FIX_SHALLOW="true"
+```
diff --git a/docs/patch-files.md b/docs/patch-files.md
@@ -1,7 +1,6 @@
 ---
 icon: material/file-edit-outline
 description: Automatically patch files in your repository with the next semantic version
-status: new
 ---
 
 # Patch files with the next semantic version

diff --git a/docs/reference/cli/nsv-next.md b/docs/reference/cli/nsv-next.md
@@ -19,6 +19,7 @@ Environment Variables:
 | NO_COLOR           | switch to using an ASCII color profile within the      |
 |                    | terminal                                               |
 | NO_LOG             | disable all log output                                 |
+| NSV_FIX_SHALLOW    | fix a shallow clone of a repository if detected        |
 | NSV_FORMAT         | provide a go template for changing the default version |
 |                    | format                                                 |
 | NSV_MAJOR_PREFIXES | a comma separated list of conventional commit prefixes |
@@ -43,6 +44,7 @@ nsv next [<path>...] [flags]
 ## Flags
 
 ```{ .text .no-select .no-copy }
+    --fix-shallow              fix a shallow clone of a repository if detected
 -f, --format string            provide a go template for changing the default
                                version format
 -h, --help                     help for next

diff --git a/docs/reference/cli/nsv-patch.md b/docs/reference/cli/nsv-patch.md
@@ -2,7 +2,6 @@
 icon: material/console
 social:
   cards: false
-status: new
 ---
 
 # nsv patch
@@ -24,6 +23,7 @@ Environment Variables:
 |                    | supports go text templates. The default is: "chore:    |
 |                    | patched files for release {{.Tag}}"                    |
 | NSV_DRY_RUN        | no changes will be made to the repository              |
+| NSV_FIX_SHALLOW    | fix a shallow clone of a repository if detected        |
 | NSV_FORMAT         | provide a go template for changing the default version |
 |                    | format                                                 |
 | NSV_HOOK           | a user-defined hook that will be executed before any   |
@@ -67,6 +67,7 @@ nsv patch [<path>...] [flags]
                                supports go text templates (default "chore:
                                patched files for release {{.Tag}}")
     --dry-run                  no changes will be made to the repository
+    --fix-shallow              fix a shallow clone of a repository if detected
 -f, --format string            provide a go template for changing the default
                                version format
 -h, --help                     help for tag

diff --git a/docs/reference/cli/nsv-tag.md b/docs/reference/cli/nsv-tag.md
@@ -24,6 +24,7 @@ Environment Variables:
 |                    | patched files for release {{.Tag}}                     |
 |                    | {{.SkipPipelineTag}}"                                  |
 | NSV_DRY_RUN        | no changes will be made to the repository              |
+| NSV_FIX_SHALLOW    | fix a shallow clone of a repository if detected        |
 | NSV_FORMAT         | provide a go template for changing the default version |
 |                    | format                                                 |
 | NSV_HOOK           | a user-defined hook that will be executed before the   |
@@ -69,6 +70,7 @@ nsv tag [<path>...] [flags]
                                supports go text templates (default "chore:
                                tagged release {{.Tag}} {{.SkipPipelineTag}}")
     --dry-run                  no changes will be made to the repository
+    --fix-shallow              fix a shallow clone of a repository if detected
 -f, --format string            provide a go template for changing the default
                                version format
 -h, --help                     help for tag

diff --git a/docs/reference/cli/nsv.md b/docs/reference/cli/nsv.md
@@ -45,7 +45,6 @@ nsv [command]
 completion  Generate the autocompletion script for the specified shell
 help        Help about any command
 next        Generate the next semantic version
-playground  A playground for discovering go template support
 tag         Tag the repository with the next semantic version
 version     Print build time version information
 ```

diff --git a/docs/reference/env-vars.md b/docs/reference/env-vars.md
@@ -1,12 +1,12 @@
 ---
 icon: material/earth
-title: Dynamic Configuration
-description: Customize behavior with environment variables
+social:
+  cards: false
 ---
 
-# Dynamic Configuration with Environment Variables
+# Available Environment Variables
 
-If you need to customize the behavior of `nsv` you can use the supported environment variables. Environment variables provide a dynamic approach to configuration perfect for integrating `nsv` into your CI workflow.
+If you need to customize the behavior of `nsv` you can use the supported environment variables. Environment variables are perfect for running `nsv` within your CI workflow.
 
 ## Global Variables
 
@@ -15,18 +15,24 @@ If you need to customize the behavior of `nsv` you can use the supported environ
 | `LOG_LEVEL`          | the level of logging when printing to stderr <br/>(`debug`, `info`, `warn`, `error`, `fatal`)                 |
 | `NO_COLOR`           | switch to using an ASCII color profile within the terminal                                                    |
 | `NO_LOG`             | disable all log output                                                                                        |
+| `NSV_FIX_SHALLOW`    | fix a shallow clone of a repository if detected                                                               |
 | `NSV_FORMAT`         | set a go template for formatting the provided tag                                                             |
 | `NSV_MAJOR_PREFIXES` | a comma separated list of conventional commit prefixes for triggering <br/>a major semantic version increment |
 | `NSV_MINOR_PREFIXES` | a comma separated list of conventional commit prefixes for triggering <br/>a minor semantic version increment |
 | `NSV_PATCH_PREFIXES` | a comma separated list of conventional commit prefixes for triggering <br/>a patch semantic version increment |
 | `NSV_PRETTY`         | pretty-print the output of the next semantic version in a given format                                        |
 | `NSV_SHOW`           | show how the next semantic version was generated                                                              |
 
-## Tag Variables
+## Tag and Patch Variables
 
 | Variable Name        | Description                                                                                                                                           |
 | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `NSV_COMMIT_MESSAGE` | a custom message when committing file changes, supports go text templates.<br />The default is: `chore: tagged release {{.Tag}} {{.SkipPipelineTag}}` |
 | `NSV_DRY_RUN`        | no changes will be made to the repository                                                                                                             |
 | `NSV_HOOK`           | a user-defined hook that will be executed before the repository is tagged<br />with the next semantic version                                         |
-| `NSV_TAG_MESSAGE`    | a custom message for the annotated tag, supports go text templates.<br />The default is: `chore: tagged release <version>`                            |
+
+## Tag Variables
+
+| Variable Name        | Description                                                                                                                                           |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NSV_TAG_MESSAGE`    | a custom message for the annotated tag, supports go text templates. The default <br/>is: `chore: tagged release {{.Tag}}`                             |
diff --git a/docs/running/dagger.md b/docs/running/dagger.md
@@ -2,7 +2,6 @@
 icon: material/sword
 social:
   cards: false
-status: new
 ---
 
 # Running with Dagger

diff --git a/docs/running/nix.md b/docs/running/nix.md
@@ -2,7 +2,6 @@
 icon: material/nix
 social:
   cards: false
-status: new
 ---
 
 # Running with Nix

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -53,6 +53,7 @@ nav:
       - Pretty Print: pretty.md
       - Git Signing: git-signing.md
       - Git Repair: git-repair.md
+      - Setting Options: options.md
       - Installation:
           - Binary: install/binary.md
           - From Source: install/source.md

diff --git a/taskfile.yaml b/taskfile.yaml
@@ -74,6 +74,6 @@ tasks:
   docs:
     desc: Builds and hosts the MkDocs documentation
     vars:
-      MKDOCS_MATERIAL_VERSION: '{{default "9.5.26-insiders-4.53.11" .MKDOCS_MATERIAL_VERSION}}'
+      MKDOCS_MATERIAL_VERSION: '{{default "9.5.49-insiders-4.53.14-patched" .MKDOCS_MATERIAL_VERSION}}'
     cmds:
       - docker run --rm -it -p 8000:8000 -v $PWD:/docs ghcr.io/purpleclay/mkdocs-material-insiders:{{.MKDOCS_MATERIAL_VERSION}}