docs: explain v7 defaults and staged compatibility removal

Author: arturcic

BREAKING_CHANGES.md

@@ -35,14 +35,14 @@ GitVersion is migrating away from LibGit2Sharp and its native libgit2 binaries t
 
 | Release | Default backend | Switch |
 | ------- | --------------- | ------ |
-| v7.0    | `libgit2`       | `GITVERSION_GIT_BACKEND=managed` to opt in to the new backend |
-| v7.1    | `managed`       | `GITVERSION_GIT_BACKEND=libgit2` to fall back |
-| later   | `managed`       | libgit2 backend removed |
+| v7.0    | `managed`       | `GITVERSION_GIT_BACKEND=libgit2` is a temporary fallback |
+| v7.1    | `managed`       | libgit2 is removed; `libgit2` reports an actionable error, explicit `managed` remains accepted |
+| v8      | `managed`       | the selector is removed |
 
 Behavioral notes when using the `managed` backend:
 
 * Mutating and network operations (repository normalization on CI build agents, dynamic repositories via `--url`, checkout, fetch) are performed by invoking the `git` executable, which must be available on the `PATH`. Plain version calculation on an already-prepared checkout does not require it.
-* v7.0 behavior is unchanged unless you opt in. Please test the `managed` backend and report issues — the libgit2 backend will be removed once the new backend has proven itself over several releases.
+* The default changes to `managed` in v7.0. LibGit2Sharp/native binaries remain available through the explicit fallback until their scheduled v7.1 removal.
 
 ### Invalid label formatting is not ignored
 Previously bad label formatting config would be silently accepted. For example `{Branhc}` (when BranchName is misspelled) or even `{BranchName` (missing a closing brace). This is not ignored now and exceptions will be thrown if formatting problems exist in the label config. This brings it into line with how assembly string formatting is treated.
@@ -53,7 +53,13 @@ The command-line interface has been migrated from Windows-style (`/switch` and s
 
 **Old-style arguments are no longer accepted by default.** Update any scripts, CI pipelines, or tooling accordingly.
 
-As a temporary migration aid, set the environment variable `GITVERSION_USE_V6_ARGUMENT_PARSER=true` to restore the legacy `/switch` and `-switch` argument handling. This escape hatch will be removed in a future release.
+As a temporary v7.0 migration aid, set `GITVERSION_ARGUMENT_PARSER_VERSION=v6` to restore legacy `/switch` and `-switch` handling. The default is `v7`. Unset `GITVERSION_USE_V6_ARGUMENT_PARSER`: any presence of that retired variable, including `false`, now fails with replacement guidance. The legacy parser is scheduled for removal in v7.1; the selector remains until v8.
+
+The parser, configuration and Git backend selectors are independent. They trim
+values, ignore case, treat blanks as unset and reject unknown values with the
+accepted values. Effective selections are logged at information level; console
+logs use stderr for machine-readable output, while build-server logs keep their
+existing channel.
 
 ### Configuration structure and migration
 
@@ -75,6 +81,10 @@ writes YAML to stdout by default, supports `--config`, `--output`,
 `--in-place`, and `--force`, and warns that comments cannot be preserved when
 replacing a file.
 
+Flat v6 runtime support is scheduled for removal in v7.1. Explicit `v7` remains
+accepted throughout v7.x, and the configuration selector is removed in v8.
+`gitversion config migrate` remains available after runtime removal.
+
 #### Full argument mapping
 
 | Old argument                  | New argument                     | Short alias                    | Env var alternative          |

docs/design/managed-git-migration.md

@@ -200,7 +200,7 @@ Build `GitVersion.Git.Managed` bottom-up with per-layer unit tests against git-C
 (loose/packed/mixed objects, packed-refs, worktrees, shallow, multi-pack-index, index v4).
 The final B step takes the `GitVersion.Core` reference, lands the direct `IGitRepository`/
 `IMutatingGitRepository` implementations, absorbs `GitVersion.Git.CommandLine` (see §4), and wires
-backend selection via `GITVERSION_GIT_BACKEND=managed|libgit2` (default `libgit2`). Validation:
+backend selection via `GITVERSION_GIT_BACKEND=managed|libgit2` (initially `libgit2`, changed to `managed` for v7.0 under #5135). Validation:
 - **CI matrix**: full integration suites (`GitVersion.Core.Tests`, `GitVersion.App.Tests`) run on both backends,
   three OSes — the suites assert exact SemVer strings over complex histories and are the strongest parity oracle
 - **DualBackendParityTests**: open the same fixture with both backends; deep-equality on ref enumeration,
@@ -209,25 +209,33 @@ backend selection via `GITVERSION_GIT_BACKEND=managed|libgit2` (default `libgit2
 - **Real-world corpus script**: `gitversion /nocache /output json` diffed across backends on this repo,
   GitReleaseManager, dotnet/runtime, a shallow CI-style clone, and a worktree checkout
 
-### Phase C — default flip in v7.1 · ~1 week + multi-release soak
-**v7.0 ships with default `libgit2`** (managed opt-in); **v7.1 flips the default to `managed`** with
-`GITVERSION_GIT_BACKEND=libgit2` as the fallback while users validate the new backend. The dual-backend
-CI matrix stays green throughout the window.
+### Phase C — managed default in v7.0
+**v7.0 ships with default `managed`** under #5135, with
+`GITVERSION_GIT_BACKEND=libgit2` as the temporary fallback. The independent
+parser/configuration selectors default to `v7`. All selectors trim values,
+ignore case, treat blanks as unset and reject unknown values. Effective
+selections are logged without mixing logs into machine-readable stdout.
+The dual-backend CI matrix stays green throughout the v7.0 window.
 
 ### Phase D — fixture migration (parallel with B) · ~2–3 weeks
 `GitVersion.Testing` moves to pure git-CLI writes via the existing `ExecuteGitCmd` pattern:
 deterministic `GIT_AUTHOR_*`/`GIT_COMMITTER_*` env (several tests advance commit time explicitly),
 `git commit --allow-empty`, `-c commit.gpgsign=false -c gc.auto=0`. Migrate the six direct-usage test files.
 If suite time regresses from process spawns, batch history creation with `git fast-import`.
 
-### Phase E — remove LibGit2Sharp · ~1–2 weeks
+### Phase E — remove LibGit2Sharp in v7.1 (#5040)
 Delete `src/GitVersion.LibGit2Sharp` and `new-cli/GitVersion.Core.Libgit2Sharp`; drop the package from
 `Directory.Packages.props`; re-point new-cli source-linking at `GitVersion.Git.Managed`
 (read-only subset). Add a packaging assertion test: **zero `runtimes/**/native/*` entries** in the
 `GitVersion.MsBuild` and `GitVersion.Tool` nupkgs. Document the new runtime requirement: `git` on PATH is needed
 **only** for dynamic-repo/CI-normalization scenarios — pure version calculation on a prepared checkout needs no
 git binary at all (a strict improvement for MSBuild-task users).
 
+Parser and flat configuration runtime removal in v7.1 is tracked separately
+by #5188. Keep `gitversion config migrate` and actionable retired selector
+value diagnostics throughout v7.x. #5136 removes all three selectors in v8;
+explicit `v7` and `managed` remain accepted until then.
+
 ### Phase F (optional) — performance accelerators · ~2–3 weeks
 Commit-graph reader (generation numbers for topo sort and merge-base), benchmark-driven pack cache tuning.
 

docs/input/docs/migration/v6-to-v7.md

@@ -51,7 +51,7 @@ GitVersion now uses POSIX-style command-line arguments powered by System.Command
 :::{.alert .alert-warning}
 **Breaking change:** Legacy Windows-style (`/switch`) and legacy single-dash long-form (`-switch`) arguments are no longer accepted by default.
 
-As a temporary migration aid, set `GITVERSION_USE_V6_ARGUMENT_PARSER=true` to restore legacy argument handling. This compatibility mode is temporary and will be removed in a future release.
+As a temporary v7.0 migration aid, set `GITVERSION_ARGUMENT_PARSER_VERSION=v6` to restore legacy argument handling. The legacy parser is removed in v7.1. Unset the retired `GITVERSION_USE_V6_ARGUMENT_PARSER` variable: its presence is an error, even when set to `false`; it is not an alias for the new selector.
 :::
 
 ### What you need to change
@@ -149,14 +149,14 @@ migrate` to retain schema validation.
 
 ## Git backend
 
-GitVersion v7 introduces a fully managed Git backend as an alternative to the native LibGit2Sharp (libgit2) implementation. The backend is selected with the `GITVERSION_GIT_BACKEND` environment variable. When the variable is not set (or empty), the release's default backend is used — you never need to set it. Setting it to any value other than `libgit2` or `managed` (case-insensitive) is an error: GitVersion fails fast instead of silently running the default backend with a typo unnoticed.
+GitVersion v7.0 uses the managed Git backend by default. The `GITVERSION_GIT_BACKEND` environment variable accepts `managed` or the temporary `libgit2` fallback.
 
 :::{.alert .alert-info}
-In v7.0 the `libgit2` backend remains the **default** — behaviour is unchanged unless you opt in. Set `GITVERSION_GIT_BACKEND=managed` to try the managed backend and help validate it. In v7.1 the default flips to `managed`, with `GITVERSION_GIT_BACKEND=libgit2` available as a fallback. Both backends ship side by side for several releases before libgit2 is removed.
+In v7.0, use `GITVERSION_GIT_BACKEND=libgit2` only if you need the temporary native backend fallback. LibGit2Sharp and its native binaries are scheduled for removal in v7.1. Explicit `managed` remains accepted throughout v7.x; the selector is removed in v8.
 :::
 
-- `libgit2` — the native, libgit2-based backend (default in v7.0).
-- `managed` — a managed implementation for all read/history operations, combined with the `git` command-line executable for network and write operations (clone, fetch, checkout, and CI repository normalization).
+- `libgit2` — the temporary native backend fallback in v7.0.
+- `managed` — the v7.0 default: a managed implementation for all read/history operations, combined with the `git` command-line executable for network and write operations (clone, fetch, checkout, and CI repository normalization).
 
 :::{.alert .alert-warning}
 When using the `managed` backend, the `git` executable must be available on the `PATH` **only** for the network/normalization scenarios above (dynamic repositories, build-agent normalization). Plain version calculation on an already-prepared checkout does not require `git` on the `PATH`.
@@ -169,7 +169,26 @@ The environment variables relevant to migrating from v6 to v7:
 | Variable                            | Purpose                                                                                                             |
 | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
 | `GITVERSION_CONFIGURATION_VERSION`   | Selects the configuration layout: `v7` (default) or temporary flat `v6` fallback.                                   |
-| `GITVERSION_GIT_BACKEND`             | Selects the Git backend: `libgit2` (default in v7.0) or `managed`. See [Git backend](#git-backend).                 |
-| `GITVERSION_USE_V6_ARGUMENT_PARSER` | Set to `true` to temporarily restore the legacy v6 (`/switch`) argument parser. Removed in a future release.        |
+| `GITVERSION_GIT_BACKEND`             | Selects the Git backend: `managed` (default) or temporary `libgit2` fallback. See [Git backend](#git-backend). |
+| `GITVERSION_ARGUMENT_PARSER_VERSION` | Selects the argument parser: `v7` (default, POSIX syntax) or temporary `v6` fallback (`/switch` and `-switch`). |
 | `GITVERSION_REMOTE_USERNAME`        | Alternative to `--username` for dynamic-repository credentials.                                                     |
 | `GITVERSION_REMOTE_PASSWORD`        | Alternative to `--password` for dynamic-repository credentials.                                                     |
+
+The three selectors are independent: selecting the v6 parser does not select
+flat configuration or libgit2. Values are trimmed and case-insensitive;
+unset, empty, and whitespace-only values use the defaults. Unknown values
+fail before execution and list the accepted values. Replace
+`GITVERSION_USE_V6_ARGUMENT_PARSER=true` with
+`GITVERSION_ARGUMENT_PARSER_VERSION=v6` and unset the old variable.
+
+Effective selections are logged at information level. Use `--log-file <path>`
+to capture them or `--log-file console` to see them on stderr with
+machine-readable output. Build-server console logging retains its normal
+output channel. For migration, place logging options before the command:
+`gitversion --log-file console config migrate --config GitVersion.yml`.
+
+In v7.1, legacy parser and flat configuration runtime support are scheduled
+for removal alongside libgit2. Retired `v6`/`libgit2` selections will report
+actionable errors; explicit `v7`/`managed` selections remain accepted during
+v7.x. All three selectors are removed in v8. `gitversion config migrate`
+remains available to convert flat files after runtime support is removed.

docs/input/docs/reference/environment-variables.md

@@ -8,7 +8,7 @@ Distinguish variables **read by GitVersion** from version variables **exported t
 
 `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.
+The [v6 to v7 migration guide](/docs/migration/v6-to-v7#environment-variables) documents the independent selectors `GITVERSION_ARGUMENT_PARSER_VERSION`, `GITVERSION_CONFIGURATION_VERSION`, and `GITVERSION_GIT_BACKEND`. Their v7.0 defaults are `v7`, `v7`, and `managed`; temporary fallbacks are `v6`, `v6`, and `libgit2`. Values are trimmed and case-insensitive; blank values use the defaults and unknown values fail with accepted-value guidance. The retired `GITVERSION_USE_V6_ARGUMENT_PARSER` variable must be unset. Legacy implementations are removed in v7.1 and selectors in v8.
 
 ## Output variables
 

docs/input/docs/usage/cli/arguments.md

@@ -8,7 +8,10 @@ Description: The supported arguments of the GitVersion Command Line Interface
 **Note:** GitVersion uses POSIX-style `--long-name` arguments from version 7 and up. Long-form
 arguments are recommended for readability in scripts and documentation. Short aliases
 (e.g. `-l`, `-o`, `-b`) are also supported. The legacy `/switch` and `-switch`
-syntax is still available when `GITVERSION_USE_V6_ARGUMENT_PARSER=true` is set.
+syntax is available during v7.0 when `GITVERSION_ARGUMENT_PARSER_VERSION=v6` is set.
+The default is `v7`. Unset the retired `GITVERSION_USE_V6_ARGUMENT_PARSER`
+variable; it now produces a replacement diagnostic. The legacy parser is
+removed in v7.1 and the selector in v8.
 
 See [Migration v6 to v7](/docs/migration/v6-to-v7) for upgrade guidance and the full argument mapping.
 :::
@@ -122,7 +125,8 @@ writes YAML to stdout unless `--output` or `--in-place` is selected. `--output`
 will not replace an existing file without `--force`; it cannot be combined with
 `--in-place`. Replacing a file warns that comments are not preserved. The
 command does not require a Git repository and is unavailable when
-`GITVERSION_USE_V6_ARGUMENT_PARSER=true` selects the legacy parser.
+`GITVERSION_ARGUMENT_PARSER_VERSION=v6` selects the legacy parser. Migration
+remains available after v6 runtime support is removed in v7.1.
 
 ## Override config