feat(git): fully managed Git backend selectable via GITVERSION_GIT_BACKEND

.github/workflows/_unit_tests.yml

@@ -16,14 +16,17 @@ permissions:
 
 jobs:
   unit_test:
-    name: ${{ matrix.os }} - net${{ matrix.dotnet_version }}
+    name: ${{ matrix.os }} - net${{ matrix.dotnet_version }} - ${{ matrix.git_backend }}
     permissions:
       id-token: write
     strategy:
       fail-fast: false
       matrix:
         os: [ windows-2025-vs2026, ubuntu-24.04, macos-26 ]
         dotnet_version: ${{ fromJson(inputs.dotnet_versions) }}
+        # Run the suite against both Git backends until libgit2 is removed,
+        # see https://github.com/GitTools/GitVersion/issues/5031
+        git_backend: [ libgit2, managed ]
 
     runs-on: ${{ matrix.os }}
     steps:
@@ -41,6 +44,8 @@ jobs:
 
       - name: '[Unit Test]'
         uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0
+        env:
+          GITVERSION_GIT_BACKEND: ${{ matrix.git_backend }}
         with:
           shell: pwsh
           timeout_minutes: 30
@@ -60,6 +65,7 @@ jobs:
         with:
           files: artifacts/test-results/**/results.xml
           report_type: 'test_results'
+          flags: ${{ matrix.git_backend }}
           use_oidc: true
 
       - name: Upload Coverage
@@ -68,4 +74,5 @@ jobs:
         with:
           directory: artifacts/test-results
           report_type: 'coverage'
+          flags: ${{ matrix.git_backend }}
           use_oidc: true

.github/workflows/ci.yml

@@ -18,6 +18,8 @@ on:
       - main
       - 'support/*'
       - 'next/*'
+      # gate managed-git phase PRs with the full test matrix pre-merge (#5031)
+      - 'feature/managed-git'
     paths:
       - '**'
       - '!docs/**'

BREAKING_CHANGES.md

@@ -16,6 +16,21 @@ GitVersion no longer ships native `osx-x64` artifacts. Apple Silicon (`osx-arm64
 
 `CommitsSinceVersionSource` is no longer emitted in JSON output, build-agent environment variables, generated version-information files, or the MSBuild `GetVersion` task. It can no longer be used in custom format strings. Use `VersionSourceDistance` instead; it has the same value.
 
+### Selectable Git backend (libgit2 vs. managed)
+
+GitVersion is migrating away from LibGit2Sharp and its native libgit2 binaries towards a managed implementation combined with the `git` CLI ([#5031](https://github.com/GitTools/GitVersion/issues/5031)). A single environment variable selects the backend:
+
+| 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 |
+
+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.
+
 ### 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.
 

build/parity-corpus.md

@@ -0,0 +1,51 @@
+# parity-corpus.ps1 — real-world corpus parity check
+
+Phase B validation tooling for the managed-git migration
+(see `docs/design/managed-git-migration.md`, §5 Phase B and §7 item 3).
+
+Runs the locally built `GitVersion.App` twice per repository/checkout shape —
+once with `GITVERSION_GIT_BACKEND=libgit2`, once with `=managed` — using
+`--output json --no-cache --no-fetch --no-normalize` (read-only, deterministic)
+and diffs the JSON version variables field by field.
+
+## Usage
+
+```bash
+# default corpus: GitVersion, GitReleaseManager, and this checkout itself
+pwsh ./build/parity-corpus.ps1
+
+# custom corpus / subset of variants / reuse binaries
+pwsh ./build/parity-corpus.ps1 -Repos /path/to/repo -Variants full,worktree -SkipBuild
+
+# keep clones in a persistent cache
+pwsh ./build/parity-corpus.ps1 -WorkDir ~/.cache/gitversion-parity
+```
+
+## Parameters
+
+| Parameter | Default | Meaning |
+|---|---|---|
+| `-Repos` | GitVersion, GitReleaseManager, local checkout | Git URLs or local paths |
+| `-WorkDir` | `$TMPDIR/gitversion-parity-corpus` | Clone cache; repeat runs reuse it |
+| `-Variants` | `full,shallow,worktree` | Checkout shapes to exercise |
+| `-Configuration` / `-Framework` | `Release` / `net10.0` | Which App build to run |
+| `-SkipBuild` | off | Reuse existing `GitVersion.App` binaries |
+
+## What it does per repository
+
+1. Full clone into the cache (skipped when already present).
+2. Derives a **shallow** clone (`git clone --depth 1 file://<full-clone>`, run with
+   `--allow-shallow`) and a **linked worktree** (`git worktree add --detach`) — the two
+   CI-style shapes called out in the migration design.
+3. Runs both backends per variant, normalizes/parses the JSON, and reports:
+   - `MATCH` — identical variables,
+   - `DIFF` — any field difference, or one backend failing while the other succeeds
+     (a parity failure; a readable per-field diff is printed),
+   - `ERROR` — variant setup failed or *both* backends refused the shape
+     (environment limitation, not counted as a parity failure).
+4. Prints a summary table with per-backend elapsed milliseconds (coarse perf signal).
+
+## Exit code
+
+The number of repo/variant combinations with result `DIFF`. `0` = full parity.
+Errors do not abort the run; remaining repos/variants are still checked.