- GitVersion is a tool that generates a Semantic
- Version number based on your Git history. The version number generated
- from GitVersion can then be used for various different purposes, such as:
-
-
-
-
Stamping a version number on artifacts (packages) produced during build.
-
Exposing the version number to the build server to version the build itself.
-
- Patching AssemblyInfo.cs (and similar) files with the
- version number during the build, so the version number is embedded
- within the compiled binaries themselves.
-
These pages describe v7 development. Check your installed version with dotnet-gitversion --version and consult the v6 to v7 migration guide before applying examples to an older installation.
diff --git a/docs/input/docs/learn/branching-strategies/contribute-examples.md b/docs/input/docs/learn/branching-strategies/contribute-examples.md
index c3ba7b504a..44dbe8e32f 100644
--- a/docs/input/docs/learn/branching-strategies/contribute-examples.md
+++ b/docs/input/docs/learn/branching-strategies/contribute-examples.md
@@ -1,4 +1,5 @@
---
+ShowInSidebar: false
Order: 70
Title: Contribute Examples
Description: Contribute examples of how GitVersion works for your branching strategy
diff --git a/docs/input/docs/learn/branching-strategies/index.cshtml b/docs/input/docs/learn/branching-strategies/index.cshtml
index ededfb925e..f93b02d025 100644
--- a/docs/input/docs/learn/branching-strategies/index.cshtml
+++ b/docs/input/docs/learn/branching-strategies/index.cshtml
@@ -1,6 +1,6 @@
---
Order: 4000
-Title: Branching Strategies
+Title: Workflow examples
Description: Information about the different branching strategies supported by GitVersion
RedirectFrom:
- docs/git-branching-strategies/overview
@@ -8,6 +8,8 @@ RedirectFrom:
- docs/examples
---
+
Start by choosing a workflow. The examples below illustrate GitFlow and GitHubFlow histories; read each example with its configuration. For experimental trunk-based defaults, see TrunkBased/preview1.
+
@@ -26,8 +28,8 @@ b5d142 -> 2.0.0+0 (2.0.0 branch was merged, so main is now at 2.0.0)
This is just a small sample of the way GitVersion works. The idea is you
- just plug it in and you will get sensible version numbers by default. We
- support the following branch types out of the box:
+ inspect the configuration alongside its resulting versions. Depending on the
+ selected workflow, configured branch types can include:
diff --git a/docs/input/docs/learn/faq.md b/docs/input/docs/learn/faq.md
index 4f972dad4a..bad383e454 100644
--- a/docs/input/docs/learn/faq.md
+++ b/docs/input/docs/learn/faq.md
@@ -1,81 +1,77 @@
---
Order: 50
-Title: FAQ
+Title: Troubleshooting
RedirectFrom: docs/faq
---
+Start by recording the installed GitVersion version, the commit SHA, the effective configuration, and the output you expected. Compare the same commit and configuration locally and in CI.
## Why is my version not incrementing?
-GitVersion calculates the semantic version, this will only change once per
-_release_. Read more about [version increments][increments].
+A new CI run is not necessarily a new version. Check the [deployment mode](/docs/reference/modes), branch increment settings, applicable tags, and [commit-message increments](/docs/reference/version-increments).
-## I'm using Octopus deploy
+Use `dotnet-gitversion --show-config` to inspect the effective configuration. Changing the output format will not change the underlying version calculation.
-Because Octopus deploy cannot have the same version of a package to a NuGet
-feed. There is no magic solution to this, but you can read more about your
-options at [octopus deploy][octopus].
+## Local and CI versions differ
-## How can GitVersion run for a shallow clone or checkout on server working directories
+Check whether both environments have the same commit, branch context, configuration file, tags, and history. A shallow checkout or missing remote branch can affect the available version sources.
-GitVersion needs a proper git repository to run, some build servers do not do a
-proper clone which can cause issues. GitVersion has a feature called [dynamic
-repositories][dynamic-repos] which solves this by cloning the repository and
-working against that clone instead of the working directory.
+Follow the [CI checkout guide](/docs/reference/build-servers), then the page for your provider.
-## I don't understand what SemVer is all about
+
-Not a problem, we have a quick [introduction to SemVer][semver-intro] which can
-be a good primer to read before reading [SemVer.org][semver].
+## Shallow clone or missing history
-## I can't use the build number for NuGet
+Use a full checkout with the required tags and branches. For an existing shallow clone, fetch the missing history before running GitVersion. See [repository requirements](/docs/reference/requirements).
-If you have used NuGet you would notice the versions above are not compatible
-with NuGet. GitVersion solves this by providing [variables][variables].
+The `--allow-shallow` argument permits running on a shallow clone; it does not restore missing history or guarantee that the result matches a full clone.
-What you have seen above is the `SemVer` variable. You can use the
-`NuGetVersion` variable to have the version formatted in a NuGet compatible way.
+If no suitable local checkout is available, consider [dynamic repositories](/docs/learn/dynamic-repositories).
-So `1.0.1-rc.1+5` would become `1.0.1-rc0001`, this takes into account
-characters which are not allowed and NuGets crap sorting.
+## Branch detection and detached HEAD
-:::{.alert .alert-info}
-**Note**
+Ensure that the provider supplies the intended branch or tag and that the corresponding references are available. Review [repository setup](/docs/learn/git-setup) and provider-specific [CI guidance](/docs/reference/build-servers).
-The `NuGetVersion` variable is floating, so when NuGet 3.0 comes out
-with proper SemVer support GitVersion will switch this variable to a proper
-SemVer.
-:::
+## Configuration is not being used
-If you want to fix the version, use `NuGetVersionV2` which will stay the same
-after NuGet 3.0 comes out
+Check that the configuration file is checked out. Recognized names include `GitVersion.yml`, `GitVersion.yaml`, `.GitVersion.yml`, and `.GitVersion.yaml`.
-## Merged branch names as version source
+Select it explicitly and inspect the result:
+
+```shell
+dotnet-gitversion --config GitVersion.yml --show-config
+```
+
+See [Configure GitVersion](/docs/usage/configure).
+
+
-When GitVersion considers previous commits to calculate a version number, it's
-important that the metadata to be considered is _stable_. Since branches are
-usually deleted after they are merged, the name of a branch can't be considered
-as a stable version source. _Branch names are not stable_, they are ephemeral.
+## Package or assembly version is unsuitable
+
+Choose a variable supported by the consumer. Start with `SemVer` for the semantic version and the assembly-specific variables for .NET assemblies. Consult the [variable reference](/docs/reference/variables) and [custom formatting](/docs/reference/custom-formatting).
+
+Old examples mentioning `NuGetVersion` or `NuGetVersionV2` do not describe the current output-variable set.
+
+## Merged branch names as version source
-The only place a branch name can be considered for version calculation is for
-the branch itself. This is typically used for `release/*` branches, which
-usually have a version number in their name. For the release branch
-`release/1.2.3`, the verison number `1.2.3` will be used to calculate the final
-version number _for the release branch_.
+A deleted branch name is not durable history. Version tags and merge messages can retain information that a deleted branch reference cannot. See [calculation strategies](/docs/reference/version-sources) and the [workflow examples](/docs/learn/branching-strategies).
-However, when the `release/1.2.3` branch is merged into `main`, the fact that
-the merged commits came from a branch named `release/1.2.3` vanishes with the
-branch which will be deleted. The name of the merged release branch can
-therefore not be considered for version calculation in the target branch of the
-merge.
+## Collect diagnostic information
-[dynamic-repos]: /docs/learn/dynamic-repositories
+```shell
+dotnet-gitversion --show-config
+dotnet-gitversion --verbosity Diagnostic --log-file gitversion.log
+```
-[increments]: /docs/reference/version-increments
+To bypass cached calculation during an investigation, use `--no-cache`. Review logs and configuration for credentials and private repository details before sharing them in an issue.
-[octopus]: /docs/reference/build-servers/octopus-deploy
+For additional graph diagnostics, `--diagnose` requires `--log-file` and Git installed. See [CLI arguments](/docs/usage/cli/arguments).
-[semver-intro]: /docs/learn/intro-to-semver
+
+
-[semver]: https://semver.org
+## More help
-[variables]: /docs/reference/variables
+- [Upgrade scripts from v6 to v7](/docs/migration/v6-to-v7).
+- [Introduction to semantic versioning](/docs/learn/intro-to-semver).
+- [Version packages for Octopus Deploy](/docs/reference/build-servers/octopus-deploy).
+- [Ask a question](https://github.com/GitTools/GitVersion/discussions).
diff --git a/docs/input/docs/learn/git-setup.md b/docs/input/docs/learn/git-setup.md
index 1d8d08d67f..348cd8b26e 100644
--- a/docs/input/docs/learn/git-setup.md
+++ b/docs/input/docs/learn/git-setup.md
@@ -1,17 +1,24 @@
---
Order: 20
-Title: Git Setup
+Title: Repository setup
RedirectFrom: docs/reference/git-setup
---
+GitVersion needs the commit history and references used by your configuration. Remote names alone do not determine the version.
+
+## History and references
+
+Start with an unshallow checkout and fetch the tags and branches required by your workflow. Ensure that the configuration file is present. Follow [repository requirements](/docs/reference/requirements) and the guide for your [CI provider](/docs/reference/build-servers).
+
+## Branch context
+
+Build servers sometimes check out a commit in detached HEAD state. Use the provider's supported branch detection and checkout configuration rather than assuming a local branch name is available. See [environment variables](/docs/reference/environment-variables).
## Remotes
### upstream
-`upstream` should point at the main repository. Your workflow should be to
-fetch/pull from upstream. Update your local branches, then start working on a
-newly created feature branch
+A fork-based contributor workflow often calls the original project's remote `upstream`. This is a naming convention for contributors, not a universal GitVersion requirement.
### origin
-`origin` should point to your _fork_.
+A checkout normally has a remote called `origin`. It may refer to the main repository or a fork. Fetch the references that your versioning configuration needs; do not rename remotes simply to follow a contributor example.
diff --git a/docs/input/docs/learn/how-it-works.md b/docs/input/docs/learn/how-it-works.md
index a0c3ab5b4c..de4aa80d50 100644
--- a/docs/input/docs/learn/how-it-works.md
+++ b/docs/input/docs/learn/how-it-works.md
@@ -1,74 +1,42 @@
---
Order: 10
-Title: How it works
+Title: How versions are calculated
RedirectFrom: docs/more-info/how-it-works
---
+GitVersion combines repository history with effective configuration to calculate a version for the current commit. It then exposes that result as [version variables](/docs/reference/variables).
-GitVersion v3 works very differently to v2. Version 2 had knowledge of both
-GitFlow and GitHubFlow hard coded into it, with each branch having its own
-class which calculated the version for that branch type.
-
-v3 is driven by [configuration](/docs/reference/configuration), meaning most of the
-behaviors in GitVersion can be tweaked to work the way you want. This also makes
-it _much_ more predictable and easier to diagnose when odd things are happening.
-
-## Architecture
-
-GitVersion has three distinct steps for calculating versions in v3.
-
-1. If the current commit is tagged, the tag is used and build metadata
- (excluding commit count) is added. The other two steps will not execute.
-2. A set of strategies are evaluated to decide on the base version and some
- metadata about that version. See [Version Strategies](#version-strategies)
-3. The highest base version is selected, using that base version as the new
- version is calculated.
-
-Visually it looks something like this:
-
-
-^"../../../diagrams/version-calculation.mmd"
-
-
-[View diagram source](https://github.com/GitTools/GitVersion/blob/main/docs/diagrams/version-calculation.mmd)
-
-**\*** Some strategies allow the version to be incremented, others don't. More
-info below.
-**+** This version is out of context with the rest of the example. It is here
-simply to show what happens if the check is true.
-
-### Version Strategies
-
-Currently we have the following strategies:
-
-* `Fallback` - Always returns 0.0.0 and will be used for
- calculating the next version which is dependent on the increment strategy of
- the effected branch (e.g. on main the next version is 0.0.1 or on develop it is 0.1.0).
- The fallback strategy only applies if no other selected strategy returns a base version.
-* `ConfiguredNextVersion` - Returns the version from the GitVersion.yaml file
-* `MergeMessage` - Finds version numbers from merge messages
- (e.g., `Merge 'release/3.0.0' into 'main'` will return `3.0.0`)
-* `TaggedCommit` - Extracts version information from all tags on the branch which are valid,
- and not newer than the current commit.
-* `TrackReleaseBranches` - Considers the base version extracted from release branches when
- calculating the next version for branches configured with `track-release-branches: true`
- (part of default configuration for `develop` branch in `GitFlow` workflow)
-* `VersionInBranchName` - Extracts version information from the
- branch name (e.g., `release/3.0.0` will find `3.0.0`)
-* `Mainline` - Increments the version on every commit for branches configured with `is-main-branch: true`
-
-Each strategy needs to return an instance of `BaseVersion` which has the
-following properties:
-
-* `Source` - Description of the source (e.g., `Merge message 'Merge 'release/3.0.0' into 'main'`)
-* `ShouldIncrement` - Some strategies should have the version incremented,
- others do not (e.g., `ConfiguredNextVersion` returns false,
- `TaggedCommit` returns true)
-* `SemanticVersion` - SemVer of the base version strategy
-* `BaseVersionSource` - SHA hash of the source. Commits will be counted from
- this hash. Can be null (e.g., `ConfiguredNextVersion` returns
- null).
-* `BranchNameOverride` - When `useBranchName` or `{BranchName}` is used in the
- tag configuration, this allows the branch name to be changed by a base version.
- `VersionInBranchName` uses this to strip out anything before the
- first `-` or `/.` so `foo` ends up being evaluated as `foo`. If in doubt, just
- use null.
+
+
+## 1. Resolve the context and configuration
+
+GitVersion determines the current commit and branch and resolves configuration defaults and overrides. The effective branch configuration supplies matching rules, increment behavior, labels, and deployment mode.
+
+Missing tags, branches, or history can change the information available to the calculation. Start with the [repository requirements](/docs/reference/requirements).
+
+
+
+## 2. Consider tags and version strategies
+
+A suitable version tag on the current commit can determine the result when the effective configuration prevents incrementing an already-tagged commit. This is conditional: a tagged commit does not unconditionally bypass all other calculation.
+
+Otherwise, enabled [version strategies](/docs/reference/version-sources) examine sources such as tags, merge messages, release branches, and configured versions. Candidates carry information about the base version and its source in history.
+
+Fallback is considered after other strategies and is skipped when another strategy has returned a base version. It is not an unconditional fixed final version of 0.1.0.
+
+## 3. Apply increments and deployment behavior
+
+GitVersion compares candidate next versions, resolves the version source, and applies effective branch and [deployment-mode](/docs/reference/modes) rules. Branch settings, commit messages, tags, and merge history can all affect the result.
+
+Read [version increments](/docs/reference/version-increments) for increment controls, and [workflows, modes, and strategies](/docs/learn/workflows-modes-strategies) for their different responsibilities.
+
+## 4. Produce version variables
+
+The result is expanded into semantic versions, assembly versions, branch and commit information, and other variables. Formatting settings control additional representations such as assembly and informational versions.
+
+Choose [JSON, a single variable, a file, or build-server output](/docs/usage/cli/output) according to how your build consumes the result.
+
+## Follow an example
+
+The [GitHubFlow examples](/docs/learn/branching-strategies/githubflow/examples) and [GitFlow examples](/docs/learn/branching-strategies/gitflow/examples) show concrete histories and their expected versions. Always read an example together with its configuration.
+
+If your output is unexpected, follow [Troubleshooting](/docs/learn/faq) before changing version settings.
diff --git a/docs/input/docs/learn/index.cshtml b/docs/input/docs/learn/index.cshtml
index 1df455dbbd..53ed97742d 100644
--- a/docs/input/docs/learn/index.cshtml
+++ b/docs/input/docs/learn/index.cshtml
@@ -1,9 +1,15 @@
---
-Title: Learn
-Description: More in depth information about GitVersion
-Order: 2000
+Title: Concepts
+Description: Understand how GitVersion turns Git history into version numbers.
+Order: 30
RedirectFrom: docs/more-info
---
-
Once you understand the basics of GitVersion, there are a number of lower level functions and configurations that you might want to make. These are detailed in the following sections.
-
-@Html.Partial("_ChildPages")
+
Read these topics in order for an introduction to version calculation. To run the tool first, follow Getting started.
diff --git a/docs/input/docs/learn/workflows-modes-strategies.md b/docs/input/docs/learn/workflows-modes-strategies.md
new file mode 100644
index 0000000000..dcbcb56daf
--- /dev/null
+++ b/docs/input/docs/learn/workflows-modes-strategies.md
@@ -0,0 +1,29 @@
+---
+Title: Workflows, modes, and strategies
+Order: 15
+---
+GitVersion has three separate configuration choices. They work together, but they are not interchangeable.
+
+| Choice | Question it answers | Examples |
+| --- | --- | --- |
+| Workflow | Which configuration defaults should I start with? | `GitHubFlow/v1`, `GitFlow/v1`, `TrunkBased/preview1` (experimental). |
+| Deployment mode | How should versions behave between releases? | `ManualDeployment`, `ContinuousDelivery`, `ContinuousDeployment`. |
+| Calculation strategies | Which sources and algorithms should determine the version? | `TaggedCommit`, `MergeMessage`, `Mainline`. |
+
+## Workflows provide defaults
+
+A workflow loads a built-in configuration. Your configuration can override it. [Choose a workflow](/docs/usage/choose-workflow) and inspect the result with `dotnet-gitversion --show-config`.
+
+## Deployment modes shape the result
+
+The effective branch configuration determines the deployment mode. Compare the [deployment modes](/docs/reference/modes) and their examples before selecting one. The same commit count does not imply the same pre-release version under every mode.
+
+## Strategies examine history
+
+Strategies find candidate versions or calculate increments from history. They are configured with `strategies`. Mainline belongs to this set; it is not a workflow name or an additional deployment mode.
+
+See the [strategy reference](/docs/reference/version-sources) for each strategy's role, then read [how calculation works](/docs/learn/how-it-works).
+
+## Keep output separate
+
+After calculation, GitVersion exposes [variables](/docs/reference/variables). CLI output options choose how to consume them; assembly and custom formatting settings produce additional version representations. Changing the output destination does not select a new workflow.
diff --git a/docs/input/docs/migration/index.cshtml b/docs/input/docs/migration/index.cshtml
index 29caab1ada..9452eb1179 100644
--- a/docs/input/docs/migration/index.cshtml
+++ b/docs/input/docs/migration/index.cshtml
@@ -1,8 +1,10 @@
---
-Title: Migration
-Description: Technical reference documentation.
-Order: 100
+Title: Upgrading
+Description: Upgrade GitVersion and update scripts, configuration, and output consumers.
+Order: 60
---
-
@Html.Raw(Model.String(DocsKeys.Description))
-
-@Html.Partial("_ChildPages")
+
Match the documentation to the version you use. These pages describe v7 development; they do not imply that every documented change is available in the latest published package.
+
Check your installation with dotnet-gitversion --version. Pin the package or tool manifest version used by your team and CI.
+
From v6 to v7
+
Read the migration guide for renamed variables, command-line arguments, runtime requirements, artifacts, Git backends, and compatibility switches.
+
Before upgrading a pipeline, compare its calculated version and consumed variables on representative tagged, feature, and release commits.
diff --git a/docs/input/docs/reference/build-servers/index.cshtml b/docs/input/docs/reference/build-servers/index.cshtml
index dec0653f25..425ee06fd1 100644
--- a/docs/input/docs/reference/build-servers/index.cshtml
+++ b/docs/input/docs/reference/build-servers/index.cshtml
@@ -1,6 +1,7 @@
---
+Title: CI integrations
Order: 3000
-Description: Details on GitVersion's Build Server support
+Description: Prepare a checkout and use GitVersion in your build pipeline.
RedirectFrom:
- docs/build-server-support
- docs/build-server-support/build-server
@@ -8,60 +9,18 @@ RedirectFrom:
- docs/build-server-support/build-server-support
- docs/build-server-support/index.html
---
-
-
- Depending on the Build Server being used, i.e. TeamCity, Jenkins, etc,
- GitVersion might need to extra repository information in order to work
- correctly. GitVersion has knowledge of most of the main CI Providers, and when
- instructed to do so, will fetch the necessary information in order to
- correctly assert the semantic version number.
-
-
-
- In addition, most build servers allow the setting of the build number within
- the system, GitVersion knows how to do this automatically. GitVersion has
- support for quite a few build servers out of the box. Currently we support:
-
-
+
Calculate a version for the intended commit, then pass its values to packaging and deployment steps.
+
Prepare the checkout
+
Check out the commit you intend to version.
Fetch the tags and branch history required by your workflow. Start with an unshallow checkout; for GitHub Actions, set fetch-depth: 0.
Include your configuration file.
Follow the provider guide for branch detection, pull requests, and variable scope.
- When the gitVersion executable is run with the
- --output buildserver flag instead of outputting JSON, it will
- export its version variables to the
- current build server as build-server native variables. For instance if you
- are running in TeamCity after you run
- gitversion --output buildserver you will have the
- %system.GitVersion.SemVer% variable available for you to use
- in the rest of the build configuration.
-
-
+
Run dotnet-gitversion --output buildserver to use a supported provider's native variable and build-number mechanisms. Dedicated GitTools integrations can perform these steps for you. Check the provider guide for exact variable names and how to pass them to later jobs.
MSBuild Properties
-
-
- When running in MSBuild either from the
- MSBuild Task or by using
- /proj myproject.sln parameter, GitVersion will make its
- version variables available as
- MSBuild properties in the format $(GitVersion_SemVer).
-
-
+
The MSBuild task exposes properties such as $(GitVersion_SemVer). See that guide for assembly and package integration.
Environment Variables
-
-
- When executed within one of the supported build servers mentioned above,
- GitVersion will also expose the version
- variables as environment variables, in the format
- GitVersion_SemVer (and in some circumstances, as
- GitVersion.SemVer).
-
-
+
Provider integrations commonly expose values such as GitVersion_SemVer. Export mechanisms and scope differ between providers. For portable scripts, use JSON or dotenv output and explicitly pass the resulting file to downstream jobs.
Normalization
-
-
- The standard gitversion executable normalize the branches if
- there is a build server detected. This behavior can be disabled with the
- /nonormalize option.
-
+
GitVersion can normalize repository references when a build server is detected. The --no-normalize option disables that step; it does not supply missing references. Follow provider-specific checkout guidance before changing this behavior.
diff --git a/docs/input/docs/reference/configuration-topics/branches.md b/docs/input/docs/reference/configuration-topics/branches.md
new file mode 100644
index 0000000000..4d99470b40
--- /dev/null
+++ b/docs/input/docs/reference/configuration-topics/branches.md
@@ -0,0 +1,29 @@
+---
+Title: Branch configuration
+Description: Matching, inheritance, and merge behavior.
+---
+Branch settings apply through the effective configuration. A label changes the calculated semantic version. Use [workflow examples](/docs/learn/branching-strategies) to understand the effect of changes.
+
+| Setting | Detailed reference |
+| --- | --- |
+| `branches` | [branches](/docs/reference/configuration#branches) |
+| `regex` | [regex](/docs/reference/configuration#regex) |
+| `source-branches` | [source-branches](/docs/reference/configuration#source-branches) |
+| `is-source-branch-for` | [is-source-branch-for](/docs/reference/configuration#is-source-branch-for) |
+| `increment` | [increment](/docs/reference/configuration#increment) |
+| `label` | [label](/docs/reference/configuration#label) |
+| `label-number-pattern` | [label-number-pattern](/docs/reference/configuration#label-number-pattern) |
+| `mode` | [mode](/docs/reference/configuration#mode) |
+| `is-main-branch` | [is-main-branch](/docs/reference/configuration#is-main-branch) |
+| `is-release-branch` | [is-release-branch](/docs/reference/configuration#is-release-branch) |
+| `prevent-increment-of-merged-branch` | [prevent-increment-of-merged-branch](/docs/reference/configuration#prevent-increment-of-merged-branch) |
+| `prevent-increment-when-branch-merged` | [prevent-increment-when-branch-merged](/docs/reference/configuration#prevent-increment-when-branch-merged) |
+| `prevent-increment-when-current-commit-tagged` | [prevent-increment-when-current-commit-tagged](/docs/reference/configuration#prevent-increment-when-current-commit-tagged) |
+| `track-merge-message` | [track-merge-message](/docs/reference/configuration#track-merge-message) |
+| `track-merge-target` | [track-merge-target](/docs/reference/configuration#track-merge-target) |
+| `tracks-release-branches` | [tracks-release-branches](/docs/reference/configuration#tracks-release-branches) |
+
+Defaults can depend on the selected workflow and branch. The linked reference supplies accepted values, scope, and examples. Inspect the effective result with `dotnet-gitversion --show-config`.
+
+[All settings](/docs/reference/configuration-topics#alphabetical-settings-index) · [Complete configuration reference](/docs/reference/configuration)
+
diff --git a/docs/input/docs/reference/configuration-topics/calculation.md b/docs/input/docs/reference/configuration-topics/calculation.md
new file mode 100644
index 0000000000..9dd3aa7baa
--- /dev/null
+++ b/docs/input/docs/reference/configuration-topics/calculation.md
@@ -0,0 +1,26 @@
+---
+Title: Version calculation
+Description: Sources, increments, and history filters.
+---
+These settings affect which version is selected and how it is incremented. Review them with the [calculation overview](/docs/learn/how-it-works).
+
+| Setting | Detailed reference |
+| --- | --- |
+| `strategies` | [strategies](/docs/reference/configuration#strategies) |
+| `next-version` | [next-version](/docs/reference/configuration#next-version) |
+| `tag-prefix` | [tag-prefix](/docs/reference/configuration#tag-prefix) |
+| `version-in-branch-pattern` | [version-in-branch-pattern](/docs/reference/configuration#version-in-branch-pattern) |
+| `semantic-version-format` | [semantic-version-format](/docs/reference/configuration#semantic-version-format) |
+| `commit-message-incrementing` | [commit-message-incrementing](/docs/reference/configuration#commit-message-incrementing) |
+| `major-version-bump-message` | [major-version-bump-message](/docs/reference/configuration#major-version-bump-message) |
+| `minor-version-bump-message` | [minor-version-bump-message](/docs/reference/configuration#minor-version-bump-message) |
+| `patch-version-bump-message` | [patch-version-bump-message](/docs/reference/configuration#patch-version-bump-message) |
+| `no-bump-message` | [no-bump-message](/docs/reference/configuration#no-bump-message) |
+| `version-bump-reset-message` | [version-bump-reset-message](/docs/reference/configuration#version-bump-reset-message) |
+| `merge-message-formats` | [merge-message-formats](/docs/reference/configuration#merge-message-formats) |
+| `ignore` | [ignore](/docs/reference/configuration#ignore) |
+
+Defaults can depend on the selected workflow and branch. The linked reference supplies accepted values, scope, and examples. Inspect the effective result with `dotnet-gitversion --show-config`.
+
+[All settings](/docs/reference/configuration-topics#alphabetical-settings-index) · [Complete configuration reference](/docs/reference/configuration)
+
diff --git a/docs/input/docs/reference/configuration-topics/index.md b/docs/input/docs/reference/configuration-topics/index.md
new file mode 100644
index 0000000000..40299ac0ea
--- /dev/null
+++ b/docs/input/docs/reference/configuration-topics/index.md
@@ -0,0 +1,58 @@
+---
+Title: Configuration by topic
+Order: 1
+---
+Start with [Configure GitVersion](/docs/usage/configure) for file names, discovery, and inspecting the effective configuration.
+
+## Choose a topic
+
+- [Workflow defaults](/docs/reference/configuration#global-configuration): GitFlow/v1, GitHubFlow/v1, and experimental TrunkBased/preview1.
+- [Version calculation](/docs/reference/configuration-topics/calculation): sources, increments, and history filters.
+- [Branch configuration](/docs/reference/configuration-topics/branches): matching, inheritance, and merge behavior.
+- [Output and formatting](/docs/reference/configuration-topics/output): assembly versions, custom formats, and build numbers.
+
+The [complete configuration reference](/docs/reference/configuration) remains the authoritative settings catalog. Its existing URLs and anchors are preserved.
+
+## Alphabetical settings index
+
+- [`assembly-file-versioning-format`](/docs/reference/configuration#assembly-file-versioning-format)
+- [`assembly-file-versioning-scheme`](/docs/reference/configuration#assembly-file-versioning-scheme)
+- [`assembly-informational-format`](/docs/reference/configuration#assembly-informational-format)
+- [`assembly-versioning-format`](/docs/reference/configuration#assembly-versioning-format)
+- [`assembly-versioning-scheme`](/docs/reference/configuration#assembly-versioning-scheme)
+- [`branches`](/docs/reference/configuration#branches)
+- [`commit-date-format`](/docs/reference/configuration#commit-date-format)
+- [`commit-message-incrementing`](/docs/reference/configuration#commit-message-incrementing)
+- [`custom-version-format`](/docs/reference/configuration#custom-version-format)
+- [`ignore`](/docs/reference/configuration#ignore)
+- [`increment`](/docs/reference/configuration#increment)
+- [`is-main-branch`](/docs/reference/configuration#is-main-branch)
+- [`is-release-branch`](/docs/reference/configuration#is-release-branch)
+- [`is-source-branch-for`](/docs/reference/configuration#is-source-branch-for)
+- [`label`](/docs/reference/configuration#label)
+- [`label-number-pattern`](/docs/reference/configuration#label-number-pattern)
+- [`major-version-bump-message`](/docs/reference/configuration#major-version-bump-message)
+- [`merge-message-formats`](/docs/reference/configuration#merge-message-formats)
+- [`minor-version-bump-message`](/docs/reference/configuration#minor-version-bump-message)
+- [`mode`](/docs/reference/configuration#mode)
+- [`next-version`](/docs/reference/configuration#next-version)
+- [`no-bump-message`](/docs/reference/configuration#no-bump-message)
+- [`patch-version-bump-message`](/docs/reference/configuration#patch-version-bump-message)
+- [`pre-release-weight`](/docs/reference/configuration#pre-release-weight)
+- [`prevent-increment-of-merged-branch`](/docs/reference/configuration#prevent-increment-of-merged-branch)
+- [`prevent-increment-when-branch-merged`](/docs/reference/configuration#prevent-increment-when-branch-merged)
+- [`prevent-increment-when-current-commit-tagged`](/docs/reference/configuration#prevent-increment-when-current-commit-tagged)
+- [`regex`](/docs/reference/configuration#regex)
+- [`semantic-version-format`](/docs/reference/configuration#semantic-version-format)
+- [`source-branches`](/docs/reference/configuration#source-branches)
+- [`strategies`](/docs/reference/configuration#strategies)
+- [`tag-pre-release-weight`](/docs/reference/configuration#tag-pre-release-weight)
+- [`tag-prefix`](/docs/reference/configuration#tag-prefix)
+- [`track-merge-message`](/docs/reference/configuration#track-merge-message)
+- [`track-merge-target`](/docs/reference/configuration#track-merge-target)
+- [`tracks-release-branches`](/docs/reference/configuration#tracks-release-branches)
+- [`update-build-number`](/docs/reference/configuration#update-build-number)
+- [`version-bump-reset-message`](/docs/reference/configuration#version-bump-reset-message)
+- [`version-in-branch-pattern`](/docs/reference/configuration#version-in-branch-pattern)
+- [`workflow`](/docs/reference/configuration#workflow)
+
diff --git a/docs/input/docs/reference/configuration-topics/output.md b/docs/input/docs/reference/configuration-topics/output.md
new file mode 100644
index 0000000000..a6846ca129
--- /dev/null
+++ b/docs/input/docs/reference/configuration-topics/output.md
@@ -0,0 +1,23 @@
+---
+Title: Output and formatting
+Description: Assembly versions, custom formats, and build numbers.
+---
+These settings control additional representations of the calculated version or its integration into builds. Choose an [output variable](/docs/reference/variables) before defining a custom format.
+
+| Setting | Detailed reference |
+| --- | --- |
+| `assembly-versioning-format` | [assembly-versioning-format](/docs/reference/configuration#assembly-versioning-format) |
+| `assembly-versioning-scheme` | [assembly-versioning-scheme](/docs/reference/configuration#assembly-versioning-scheme) |
+| `assembly-file-versioning-format` | [assembly-file-versioning-format](/docs/reference/configuration#assembly-file-versioning-format) |
+| `assembly-file-versioning-scheme` | [assembly-file-versioning-scheme](/docs/reference/configuration#assembly-file-versioning-scheme) |
+| `assembly-informational-format` | [assembly-informational-format](/docs/reference/configuration#assembly-informational-format) |
+| `custom-version-format` | [custom-version-format](/docs/reference/configuration#custom-version-format) |
+| `commit-date-format` | [commit-date-format](/docs/reference/configuration#commit-date-format) |
+| `pre-release-weight` | [pre-release-weight](/docs/reference/configuration#pre-release-weight) |
+| `tag-pre-release-weight` | [tag-pre-release-weight](/docs/reference/configuration#tag-pre-release-weight) |
+| `update-build-number` | [update-build-number](/docs/reference/configuration#update-build-number) |
+
+Defaults can depend on the selected workflow and branch. The linked reference supplies accepted values, scope, and examples. Inspect the effective result with `dotnet-gitversion --show-config`.
+
+[All settings](/docs/reference/configuration-topics#alphabetical-settings-index) · [Complete configuration reference](/docs/reference/configuration)
+
diff --git a/docs/input/docs/reference/configuration.md b/docs/input/docs/reference/configuration.md
index bdfe0bfe68..8f42ffd06a 100644
--- a/docs/input/docs/reference/configuration.md
+++ b/docs/input/docs/reference/configuration.md
@@ -5,18 +5,13 @@ Description: Details about how GitVersion can be configured to suit your needs
RedirectFrom: docs/configuration
---
-GitVersion, starting from version 3.0, is mainly powered by configuration and no
-longer has branching strategies hard-coded.
+This is the complete settings reference, including built-in workflow defaults.
+For a shorter starting point, use [configuration by topic](/docs/reference/configuration-topics)
+or follow [Configure GitVersion](/docs/usage/configure).
-:::{.alert .alert-info}
-**Note**
-
-GitVersion ships with internal default configuration which works with
-GitHubFlow and GitFlow, probably with others too.
-:::
-
-The `develop` branch is set to `ContinuousDeployment` mode by default as we have
-found that is generally what is needed when using GitFlow.
+Defaults depend on the selected workflow and effective branch configuration.
+Use the configuration output below to inspect them rather than assuming that
+every workflow uses the same deployment mode.
To see the effective configuration (defaults and overrides), you can run
`gitversion --show-config`.
@@ -107,7 +102,7 @@ The following supported workflow configurations are available in GitVersion and
* GitFlow (GitFlow/v1)
* GitHubFlow (GitHubFlow/v1)
-* TrunkBased (TrunkBased/preview1)
+* TrunkBased (TrunkBased/preview1, experimental preview)
Example of using a `GitHubFlow` workflow with a different `tag-prefix`:
diff --git a/docs/input/docs/reference/environment-variables.md b/docs/input/docs/reference/environment-variables.md
new file mode 100644
index 0000000000..660f15c403
--- /dev/null
+++ b/docs/input/docs/reference/environment-variables.md
@@ -0,0 +1,19 @@
+---
+Title: Environment variables
+Order: 60
+---
+Distinguish variables **read by GitVersion** from version variables **exported to your build**.
+
+## Repository and execution inputs
+
+`Git_Branch` can identify the branch or tag when the build context is ambiguous. Provider-specific detection is described in the [CI guides](/docs/reference/build-servers). Ensure the selected reference and its history are available in the checkout.
+
+The [v6 to v7 migration guide](/docs/migration/v6-to-v7#environment-variables) documents Git backend selection and temporary compatibility controls, including `GITVERSION_USE_V6_ARGUMENT_PARSER`. Compatibility switches are migration aids, not recommended defaults for a new setup.
+
+## Output variables
+
+With a supported build-server integration, version variables are made available using the provider's mechanisms. A common environment-variable spelling is `GitVersion_SemVer`. Use the exact naming and job/step scope described for your provider.
+
+A child process cannot generally set environment variables in its parent shell. For shell scripts, use [JSON or dotenv output](/docs/usage/cli/output) and explicitly pass the result to later commands.
+
+For .NET builds, see the [MSBuild integration](/docs/usage/msbuild). For every available value and its meaning, see [version variables](/docs/reference/variables).
diff --git a/docs/input/docs/reference/index.cshtml b/docs/input/docs/reference/index.cshtml
index aad784ebf1..b73fc0a875 100644
--- a/docs/input/docs/reference/index.cshtml
+++ b/docs/input/docs/reference/index.cshtml
@@ -1,8 +1,16 @@
---
Title: Reference
-Description: Technical reference documentation.
-Order: 100
+Description: Look up exact settings, arguments, and output formats.
+Order: 40
---
-
@Html.Raw(Model.String(DocsKeys.Description))
-
-@Html.Partial("_ChildPages")
+
Use the reference for exact names and behavior. For a complete task, start with the guides.
diff --git a/docs/input/docs/reference/mdsource/configuration.source.md b/docs/input/docs/reference/mdsource/configuration.source.md
index ed5eed1ec7..6617a04fec 100644
--- a/docs/input/docs/reference/mdsource/configuration.source.md
+++ b/docs/input/docs/reference/mdsource/configuration.source.md
@@ -5,18 +5,13 @@ Description: Details about how GitVersion can be configured to suit your needs
RedirectFrom: docs/configuration
---
-GitVersion, starting from version 3.0, is mainly powered by configuration and no
-longer has branching strategies hard-coded.
+This is the complete settings reference, including built-in workflow defaults.
+For a shorter starting point, use [configuration by topic](/docs/reference/configuration-topics)
+or follow [Configure GitVersion](/docs/usage/configure).
-:::{.alert .alert-info}
-**Note**
-
-GitVersion ships with internal default configuration which works with
-GitHubFlow and GitFlow, probably with others too.
-:::
-
-The `develop` branch is set to `ContinuousDeployment` mode by default as we have
-found that is generally what is needed when using GitFlow.
+Defaults depend on the selected workflow and effective branch configuration.
+Use the configuration output below to inspect them rather than assuming that
+every workflow uses the same deployment mode.
To see the effective configuration (defaults and overrides), you can run
`gitversion --show-config`.
@@ -107,7 +102,7 @@ The following supported workflow configurations are available in GitVersion and
* GitFlow (GitFlow/v1)
* GitHubFlow (GitHubFlow/v1)
-* TrunkBased (TrunkBased/preview1)
+* TrunkBased (TrunkBased/preview1, experimental preview)
Example of using a `GitHubFlow` workflow with a different `tag-prefix`:
diff --git a/docs/input/docs/reference/modes/index.cshtml b/docs/input/docs/reference/modes/index.cshtml
index a0a8e8bb49..186d41e8fa 100644
--- a/docs/input/docs/reference/modes/index.cshtml
+++ b/docs/input/docs/reference/modes/index.cshtml
@@ -1,13 +1,16 @@
---
Order: 50
-Title: Versioning Modes
-Description: The different modes of versioning GitVersion supports
+Title: Deployment modes
+Description: Compare version behavior between releases.
RedirectFrom: docs/reference/versioning-modes/versioning-mode
---
-
-
- GitVersion supports a few different versioning modes. They are described
- in detail on the pages enumerated below.
-
-
-@Html.Partial("_ChildPages")
+
The effective branch configuration selects a deployment mode. This is separate from your workflow preset and calculation strategies.
+
+
Mode
Effect after version selection
Read more
+
+
ManualDeployment
Keeps the calculated pre-release version and adds build metadata; intermediate commits can share a semantic version.
A mode does not publish a package or deploy your application. Your pipeline performs those actions.
+
See workflows, modes, and strategies for how these choices fit together, and inspect your effective configuration with dotnet-gitversion --show-config.
diff --git a/docs/input/docs/reference/requirements.md b/docs/input/docs/reference/requirements.md
index 68acfb00d5..e589b406db 100644
--- a/docs/input/docs/reference/requirements.md
+++ b/docs/input/docs/reference/requirements.md
@@ -16,7 +16,8 @@ build server, needs to adhere to the below requirements.
The repository should be an [unshallow][git-unshallow] clone. This means
that the `fetch-depth` in GitHub Actions should set to `0`, unless
-the `allowshallow` flag is used.
+the `--allow-shallow` flag is used. That flag does not restore missing history
+or guarantee that the result matches a full clone.
Check with your [build server][build-servers] to see how it can be configured
appropriately.
diff --git a/docs/input/docs/reference/variables.md b/docs/input/docs/reference/variables.md
index e467d1b3a3..910c640a99 100644
--- a/docs/input/docs/reference/variables.md
+++ b/docs/input/docs/reference/variables.md
@@ -7,7 +7,8 @@ RedirectFrom: docs/more-info/variables
Version variables are quite useful if you need different formats of the version
number. Running the `gitversion` executable in your repository will show you
-what is available. For the `release/3.0.0` branch of GitVersion it shows:
+what is available. The following is illustrative output; your values depend on
+the repository history and effective configuration:
```json
{
diff --git a/docs/input/docs/reference/version-sources.md b/docs/input/docs/reference/version-sources.md
index dcdae9f82d..8dbee4e684 100644
--- a/docs/input/docs/reference/version-sources.md
+++ b/docs/input/docs/reference/version-sources.md
@@ -1,68 +1,59 @@
---
Order: 50
-Title: Version Sources
-Description: Details on how GitVersion finds a source for its generated version number
+Title: Calculation strategies
+Description: Sources and algorithms used to determine a version.
RedirectFrom: docs/more-info/version-sources
---
+Strategies are selected with the [`strategies` configuration setting](/docs/reference/configuration#strategies). They work with branch configuration and deployment modes; they do not independently define the final version.
-GitVersion has a two step process for calculating the version number. First it
-calculates the base version, which is then used to calculate what the next
-version should be.
+| Strategy | Role |
+| --- | --- |
+| `ConfiguredNextVersion` | Uses `next-version` as a candidate. |
+| `TaggedCommit` | Finds applicable semantic versions in tags. |
+| `MergeMessage` | Extracts version information from matching merge messages. |
+| `VersionInBranchName` | Extracts a version from a matching branch name. |
+| `TrackReleaseBranches` | Considers release-branch history according to effective branch configuration. |
+| `Mainline` | Calculates increments while walking history using mainline rules. |
+| `Fallback` | Supplies a starting candidate when no other selected strategy provides one; its increment is determined from configuration. |
-The logic of GitVersion is something like this:
+
-* Is the current commit tagged
- * Yes: Use the tag as the version
- * No: continue
-* Calculate the base version (highest version from all the sources)
-* Increment version if needed based on branch config
-* Calculate the build metadata (everything after the +) and append to the
- calculated version
+## Selection and increments
-## Version Sources
+The order of entries in `strategies` is not a priority list. GitVersion evaluates candidates and selects a next version with a corresponding version source. Fallback is deferred until other strategies have been considered.
-### Tag name
+Do not interpret a source as “always increments” or “never increments” without the relevant branch configuration. Tagged commits, merge handling, increment inheritance, and deployment mode affect the outcome.
-Returns the version numbers extracted from the current branch's tags.
+For the sequence of operations, see [how versions are calculated](/docs/learn/how-it-works).
-Will increment: true
+## Existing source topics
-### Version in branch name
+The following anchors are retained for older links.
-Returns the version number from the branch's name.
+### Tag name
-Will increment: false
+See `TaggedCommit` above and [tag-prefix](/docs/reference/configuration#tag-prefix).
-### Merge message
+### Version in branch name
-Returns the version number of any branch (with a version number in its name)
-merged into the current branch.
+See `VersionInBranchName` and [version-in-branch-pattern](/docs/reference/configuration#version-in-branch-pattern).
-Will increment: depends on the value of `prevent-increment-of-merged-branch-version`
+### Merge message
-### GitVersion.yml
+See `MergeMessage` and [merge-message-formats](/docs/reference/configuration#merge-message-formats).
-Returns the value of the `next-version` property in the config file.
+### GitVersion.yml
-Will increment: false
+See `ConfiguredNextVersion` and [next-version](/docs/reference/configuration#next-version).
### Develop branch
-For the develop branch, i.e. marked with `is-develop: true`
-
-* Returns the version number extracted from any child release-branches, i.e.
- those marked with `is-release-branch: true`
-* Returns the version number of any tags on the main branch
-
-Will increment: true
+See `TrackReleaseBranches` and the [GitFlow configuration](/docs/reference/configuration#global-configuration).
### Fallback
-Returns the version number `0.1.0`.
-
-Will increment: false
+Fallback determines an increment using the effective configuration. Do not rely on a fixed final version independent of branch settings.
-### Others?
+
-Want more ways to increment the version? Open an issue with your idea and submit
-a pull request!
+For configuration combinations, see [workflow examples](/docs/learn/branching-strategies). To propose additional strategy behavior, start a [discussion](https://github.com/GitTools/GitVersion/discussions).
diff --git a/docs/input/docs/usage/choose-workflow.md b/docs/input/docs/usage/choose-workflow.md
new file mode 100644
index 0000000000..5ad6b3a27a
--- /dev/null
+++ b/docs/input/docs/usage/choose-workflow.md
@@ -0,0 +1,34 @@
+---
+Title: Choose a workflow
+Order: 1
+---
+Choose defaults that match how you merge and release. A workflow is a configuration preset, not an instruction to change your branching process.
+
+| Workflow | Starting point | Configuration value |
+| --- | --- | --- |
+| GitHub Flow | A main branch with short-lived branches merged through pull requests. | `GitHubFlow/v1` |
+| Git Flow | Development and release branches with distinct release stages. | `GitFlow/v1` |
+| Trunk-based (preview) | Evaluate the experimental trunk-based configuration against your own histories. | `TrunkBased/preview1` |
+
+For example, create `GitVersion.yml` at the repository root:
+
+```yaml
+workflow: GitHubFlow/v1
+```
+
+Inspect the resolved settings with `dotnet-gitversion --show-config`. Compare the results on representative feature, tagged, and release commits before adopting changes.
+
+The preview workflow is experimental. Do not assume it has the same compatibility guarantees as the versioned GitFlow and GitHubFlow presets.
+
+## Understand the choices
+
+A workflow supplies defaults. A [deployment mode](/docs/reference/modes) controls version behavior between releases. A [calculation strategy](/docs/reference/version-sources) helps determine the version from history. **Mainline is a calculation strategy**, not a fourth deployment mode.
+
+Read [workflows, modes, and strategies](/docs/learn/workflows-modes-strategies) before combining custom settings.
+
+## Worked examples and defaults
+
+- [GitHub Flow](/docs/learn/branching-strategies/githubflow) and [examples](/docs/learn/branching-strategies/githubflow/examples).
+- [Git Flow](/docs/learn/branching-strategies/gitflow) and [examples](/docs/learn/branching-strategies/gitflow/examples).
+- [Built-in configurations](/docs/reference/configuration#global-configuration).
+- [Create and inspect configuration](/docs/usage/configure).
diff --git a/docs/input/docs/usage/ci.md b/docs/input/docs/usage/ci.md
index 6affabd81b..4bfd9459f7 100644
--- a/docs/input/docs/usage/ci.md
+++ b/docs/input/docs/usage/ci.md
@@ -1,38 +1,14 @@
---
Order: 5
Title: Continuous Integration
-Description: |
- GitVersion can be used in a Continuous Server pipeline to generate a
- version number that both labels the build itself and makes the different
- version variables available to the rest of the build pipeline.
+Description: Set up GitVersion in a build pipeline.
CardIcon: repeat.svg
---
+The [CI integration guide](/docs/reference/build-servers) is the starting point for checkout requirements, provider setup, and passing versions between build steps.
-GitVersion can be used in a Continuous Server pipeline to generate a version
-number that both labels the build itself and makes the different version
-variables available to the rest of the build pipeline. Choose between the
-supported continuous integration servers below.
+- [GitHub Actions](/docs/reference/build-servers/github-actions).
+- [Azure DevOps](/docs/reference/build-servers/azure-devops).
+- [GitLab CI](/docs/reference/build-servers/gitlab).
+- [All supported integrations](/docs/reference/build-servers).
-## GitHub Actions
-
-GitVersion's GitTools Actions allows for simple integration into a GitHub
-Actions build pipeline.
-
-[GitTools Actions][gittools-actions]{.btn .btn-primary}
-
-## Azure DevOps
-
-GitVersion's GitTools Azure DevOps Task allows for simple integration of
-GitVersion into an Azure DevOps build pipeline.
-
-[GitTools Task][gittools-task]{.btn .btn-primary}
-
-## GitLab CI Pipelines
-
-The GitLab CI example [gitlab-sample][] implements GitVersion support at the pipeline level by using a single job that runs the GitVersion container and passes the version number downstream into both _pipeline_ and _job_ level variables. It is also implemented as a reusable CI/CD Extension that can be included in many different projects.
-
-[gittools-actions]: https://github.com/marketplace/actions/gittools
-
-[gittools-task]: https://marketplace.visualstudio.com/items?itemName=gittools.gittools
-
-[gitlab-sample]: https://gitlab.com/guided-explorations/devops-patterns/utterly-automated-versioning/
+For local scripting and output formats, see [Use version output](/docs/usage/cli/output).
diff --git a/docs/input/docs/usage/cli/output.md b/docs/input/docs/usage/cli/output.md
index c20eecb21b..279ce5af36 100644
--- a/docs/input/docs/usage/cli/output.md
+++ b/docs/input/docs/usage/cli/output.md
@@ -1,37 +1,43 @@
---
Order: 30
-Title: Output
-Description: Details about the output types supported by the GitVersion CLI
+Title: Use version output
+Description: Read version variables in scripts and pass them to builds.
---
+By default GitVersion writes a JSON object containing its [version variables](/docs/reference/variables).
-By default GitVersion returns a json object to stdout containing all the
-[variables](/docs/reference/variables) which GitVersion generates. This works
-great if you want to get your build scripts to parse the json object then use
-the variables, but there is a simpler way.
-
-`GitVersion.exe --output buildserver` will change the mode of GitVersion to write
-out the variables to whatever build server it is running in. You can then use
-those variables in your build scripts or run different tools to create versioned
-NuGet packages or whatever you would like to do. See [build
-servers](/docs/reference/build-servers) for more information about this.
-
-You can even store the [variables](/docs/reference/variables) in a Dotenv file
-and load it to have the variables available in your environment.
-For that you have to run `GitVersion.exe --output dotenv` and store the output
-into e.g. a `gitversion.env` file. These files can also be passed around in CI environments
-like [GitHub](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#passing-values-between-steps-and-jobs-in-a-workflow)
-or [GitLab](https://docs.gitlab.com/ee/ci/variables/#pass-an-environment-variable-to-another-job).
-Below are some examples of using the Dotenv format in the Unix command line:
-```bash
-# Output version variables in Dotenv format
-gitversion --output dotenv
-
-# Show only a subset of the version variables in Dotenv format
-gitversion --output dotenv | grep -i "prerelease"
-
-# Show only a subset of the version variables that match the regex in Dotenv format
-gitversion --output dotenv | grep -iE "major|sha=|_prerelease"
-
-# Write version variables in Dotenv format into a file
-gitversion --output dotenv > gitversion.env
+## JSON and a single variable
+
+```shell
+dotnet-gitversion
+dotnet-gitversion --show-variable SemVer
+```
+
+Use `SemVer` when you need the semantic version, or select another variable for the target consuming it. See [formatting syntax](/docs/reference/custom-formatting) for custom formats.
+
+## Write a JSON file
+
+```shell
+dotnet-gitversion --output file --output-file gitversion.json
+```
+
+Pass this file to later steps or jobs using your CI provider's artifact mechanism.
+
+## Build-server output
+
+```shell
+dotnet-gitversion --output buildserver
+```
+
+On a supported build server, this uses the provider's variable and build-number mechanisms. Follow the [CI integration guide](/docs/reference/build-servers) for exact names and job/step scope.
+
+## Dotenv output
+
+```shell
+dotnet-gitversion --output dotenv > gitversion.env
```
+
+Load the file using your runner's or application's dotenv support. Writing a file does not automatically export variables into the invoking shell or later jobs.
+
+## .NET assemblies
+
+Use the [MSBuild task](/docs/usage/msbuild) or [assembly patching](/docs/usage/cli/assembly-patch) to put version values into build artifacts. Select the assembly variables or formatting rules appropriate for those artifacts.
diff --git a/docs/input/docs/usage/configure.md b/docs/input/docs/usage/configure.md
new file mode 100644
index 0000000000..868b11cd73
--- /dev/null
+++ b/docs/input/docs/usage/configure.md
@@ -0,0 +1,41 @@
+---
+Title: Configure GitVersion
+Order: 2
+---
+Start with a workflow and override only the settings your repository needs.
+
+## Create a configuration file
+
+Put `GitVersion.yml` at the repository root. GitVersion also recognizes `GitVersion.yaml`, `.GitVersion.yml`, and `.GitVersion.yaml`.
+
+```yaml
+workflow: GitHubFlow/v1
+tag-prefix: '[vV]?'
+```
+
+This selects the GitHubFlow defaults and permits a leading v or V in version tags. For a different starting point, [choose a workflow](/docs/usage/choose-workflow).
+
+## Inspect the effective configuration
+
+```shell
+dotnet-gitversion --show-config
+```
+
+The output includes defaults and your overrides. If you work in a subdirectory or maintain multiple configuration files, select the intended file explicitly:
+
+```shell
+dotnet-gitversion --config GitVersion.yml --show-config
+dotnet-gitversion --config GitVersion.yml --show-variable SemVer
+```
+
+Check that the file is included in your CI checkout. See [configuration troubleshooting](/docs/learn/faq#configuration-is-not-being-used).
+
+## Change one responsibility at a time
+
+- **Calculation:** tags, version sources, increments, and ignored history.
+- **Branches:** matching rules, inheritance, deployment mode, and pre-release labels.
+- **Output:** assembly versions, custom formatting, and CI build-number updates.
+
+Labels affect the calculated semantic version; they are not only a display preference.
+
+Use [configuration by topic](/docs/reference/configuration-topics) to find the relevant settings. Before adopting a change, compare the effective configuration and output on histories that represent your release process.
diff --git a/docs/input/docs/usage/index.cshtml b/docs/input/docs/usage/index.cshtml
index 60336a77e3..dfec1d7754 100644
--- a/docs/input/docs/usage/index.cshtml
+++ b/docs/input/docs/usage/index.cshtml
@@ -1,14 +1,15 @@
---
-Title: Usage
-Description: |
- There are four different ways to consume GitVersion itself. You can find
- each of these options below.
-Order: 1
+Title: Guides
+Description: Practical guides for configuring GitVersion and using it in your builds.
+Order: 20
RedirectFrom:
- docs/usage/gem
- docs/usage/usage
---
-
-
@Html.Raw(Model.String(DocsKeys.Description))
-
-@Html.Partial("_ChildPages")
+
Start with your first version, then choose the task you want to complete.
- GitVersion is built for many different use-cases and workflows, so whether you use
- Mainline,
- Git Flow or
- GitHub Flow,
- GitVersion has you covered.
-
+# Print a single version variable
+dotnet-gitversion @(new Version(Context.String("DocsEdition")).Major >= 7 ? "--show-variable" : "/showvariable") SemVer
+ Command-line options →
+
+
-
+
-
-
-
-
Configurable
-
- Gitversion is highly configurable
- and can be made to support your specific versioning scheme, almost
- regardless of what it may be.
-
+
+
How It Works
+
+
Version Calculation Example
GitVersion reads your tags, branches, and commits to calculate a semantic version for the current commit.
Your history is the starting point
Tags establish released versions.
Branches provide context for your workflow.
Configuration controls increments and pre-release labels.
This example is illustrative. Your output depends on your repository history and configuration.
- Expose version variables in different formats to the tools you use. Use GitVersion locally or in a
- build pipeline with
- TeamCity,
- AppVeyor,
- Jenkins or any of the other supported
- build servers.
-
