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

[arturcic]

Follow-up to #5075 (closed).

Implements the managed Git backend for the v7.0 dual-backend window (#5031, design: docs/design/managed-git-migration.md): a vendored, fully managed reader for all read/history operations paired with the git CLI for mutations and network, selectable at runtime alongside the existing libgit2 backend.

What's in the branch

Layered bottom-up, one commit per layer, each with its tests:

• Object database — hash-agnostic GitObjectId, zlib/random-access streams, pack + idx v2 readers with delta application, bounded pack memory cache, multi-pack-index, loose objects, SHA-256 detection with a clear failure message (NOTICE attribution for code ported from Nerdbank.GitVersioning ManagedGit, MIT).
• Parsers — commit (signatures, encoding with Latin-1 fallback), tree (streaming reads), annotated tags.
• Refs & repository layout — loose/packed refs (peeled, symrefs, .lock skipping), walk-up discovery with .git-file indirection, worktrees/commondir, shallow detection, config parsing, reftable rejection.
• Revision walker — libgit2-parity time/topo ordering with exact tie-break mechanics, mark-uninteresting limiting, paint-down-to-common merge-base, .git/shallow boundaries grafted parentless.
• Diff & status — changed-paths tree diff in raw byte order, index v2–v4 reader, gitignore matching, working-tree status matching the libgit2 adapter's uncommitted-changes expression.
• CLI mutator — plumbing-only parsing, ArgumentList invocation (LC_ALL=C, no terminal prompts), per-invocation auth headers, stderr classification mapped to the existing exceptions (Polly LockedFileException retry preserved).
• Adapters & selection — Managed* implementations of the Core git abstractions over an immutable session snapshot (invalidated after mutations); GITVERSION_GIT_BACKEND=libgit2|managed resolved once in GitBackendSelector (unset ⇒ libgit2 in v7.0; unknown values fail fast); the resolved backend is logged at startup.

Behavior

• v7.0 default is unchanged (libgit2) — the managed backend is opt-in for validation; v7.1 flips the default per the release plan.
• With managed, git on PATH is required only for normalization/dynamic-repo scenarios; plain version calculation on a prepared checkout needs no git binary.

Validation

• CI unit-test matrix runs every leg against both backends (git_backend dimension) on three OSes — the full integration suites assert exact SemVer strings over complex histories.
• DualBackendParityTests: deep-equality on ref enumeration, order-sensitive walks, merge-base over commit pairs (criss-cross, equal timestamps), DiffPaths, UncommittedChangesCount.
• build/parity-corpus.ps1 diffs gitversion /nocache /output json across backends on real-world repositories.

🤖 Generated with Claude Code

[arturcic]

@asbjornu @HHobeck hey guys would you mind to review this PR and actually give it a try? I really need your feedback, which I can address before we merge it for v7

[Copilot]

Pull request overview

Adds a new fully managed Git backend (read/history in-process; mutations/network via git CLI) to the legacy src/ GitVersion stack, selectable at runtime via GITVERSION_GIT_BACKEND (defaulting to libgit2 for v7.0), and wires CI/documentation to support dual-backend parity validation.

Changes:

• Introduces GitVersion.Git.Managed (managed ODB/pack/idx/midx, refs/repo layout, revwalk, tree diff, index/status, git-CLI mutator, Core adapter implementations) plus a dedicated test project.
• Adds backend selection (GitBackendSelector) and integrates backend choice into CLI/module composition roots and logging.
• Updates CI pipelines/docs/release notes to run/test both backends and document the new environment switch.

Reviewed changes

Copilot reviewed 117 out of 117 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/GitVersion.slnx	Adds managed backend and its tests to the legacy solution.
src/GitVersion.MsBuild.Tests/GitVersion.MsBuild.Tests.csproj	References managed backend from MSBuild tests.
src/GitVersion.Git.Managed/StreamExtensions.cs	Adds stream helpers used by pack/object parsing.
src/GitVersion.Git.Managed/SafeFileHandleExtensions.cs	Adds random-access read helper for pack/idx reads.
src/GitVersion.Git.Managed/Refs/GitReference.cs	Defines internal reference model used by ref store/adapter.
src/GitVersion.Git.Managed/RandomAccessStream.cs	Provides per-reader positioning over shared file handles.
src/GitVersion.Git.Managed/PublicAPI.Unshipped.txt	Declares new public surface for the managed module.
src/GitVersion.Git.Managed/PublicAPI.Shipped.txt	Initializes shipped API baseline for the new project.
src/GitVersion.Git.Managed/NOTICE.md	Adds third-party attribution for ported components.
src/GitVersion.Git.Managed/History/GitRevisionWalkOptions.cs	Defines walk options for managed revwalk.
src/GitVersion.Git.Managed/History/GitRevisionSortStrategies.cs	Adds managed sort-strategy flags for revwalk parity.
src/GitVersion.Git.Managed/GitZLibStream.cs	Implements zlib-wrapped deflate reader for git object data.
src/GitVersion.Git.Managed/GitVersionManagedGitModule.cs	Registers managed backend services into DI.
src/GitVersion.Git.Managed/GitVersion.Git.Managed.csproj	Adds the managed backend project and internals visibility.
src/GitVersion.Git.Managed/GitTreeStreamingReader.cs	Fast tree scanning for node lookup without full parsing.
src/GitVersion.Git.Managed/GitTreeReader.cs	Parses git tree objects into GitTree/GitTreeEntry.
src/GitVersion.Git.Managed/GitTree.cs	Adds managed tree model used by diff/status code.
src/GitVersion.Git.Managed/GitTextDecoder.cs	Implements git-like UTF-8/Latin-1 fallback decoding.
src/GitVersion.Git.Managed/GitTagReader.cs	Parses annotated tag objects.
src/GitVersion.Git.Managed/GitTag.cs	Adds annotated tag model.
src/GitVersion.Git.Managed/GitSignature.cs	Parses and represents author/committer/tagger signatures.
src/GitVersion.Git.Managed/GitPackReader.cs	Reads pack entries, including delta application.
src/GitVersion.Git.Managed/GitPackObjectType.cs	Defines pack object type enum.
src/GitVersion.Git.Managed/GitPackMemoryCacheViewStream.cs	Adds view streams over cached pack objects.
src/GitVersion.Git.Managed/GitPackMemoryCacheStream.cs	Adds decompressed-object caching stream to enable random reads.
src/GitVersion.Git.Managed/GitPackMemoryCache.cs	Adds bounded LRU cache for pack objects.
src/GitVersion.Git.Managed/GitPackIndexReader.cs	Reads .idx v2 to map object IDs to pack offsets.
src/GitVersion.Git.Managed/GitPackDeltafiedStream.cs	Implements delta instruction application stream (naming flagged).
src/GitVersion.Git.Managed/GitPackCache.cs	Defines cache abstraction for pack-object caching.
src/GitVersion.Git.Managed/GitPack.cs	Wraps pack+idx access and integrates caching.
src/GitVersion.Git.Managed/GitObjectTypes.cs	Centralizes canonical object type strings.
src/GitVersion.Git.Managed/GitObjectStream.cs	Reads loose objects (type/size header + zlib content).
src/GitVersion.Git.Managed/GitObjectStoreException.cs	Defines managed object-store exception type.
src/GitVersion.Git.Managed/GitCommitReader.cs	Parses commit objects while deferring expensive decoding.
src/GitVersion.Git.Managed/GitCommit.cs	Adds commit model with lazy-decoded fields.
src/GitVersion.Git.Managed/FileHelpers.cs	Adds file open helper with IO-failure handling.
src/GitVersion.Git.Managed/Diff/GitTreeDiff.cs	Implements tree-vs-tree diff producing libgit2-parity path lists.
src/GitVersion.Git.Managed/DeltaStreamReader.cs	Reads pack delta instructions.
src/GitVersion.Git.Managed/DeltaInstruction.cs	Defines delta instruction representation.
src/GitVersion.Git.Managed/CommandLine/PullRequestBranchOperations.cs	Adds PR-ref normalization logic for CLI mutator path.
src/GitVersion.Git.Managed/CommandLine/GitRemoteReference.cs	Adds remote ref record for ls-remote-style output.
src/GitVersion.Git.Managed/CommandLine/GitCliExecutor.cs	Implements safe git CLI invocation with env scrubbing/redaction.
src/GitVersion.Git.Managed/Adapter/RepositoryPathResolution.cs	Adds path-resolution utilities for managed repo info.
src/GitVersion.Git.Managed/Adapter/ManagedTagCollection.cs	Exposes tags via Core abstractions.
src/GitVersion.Git.Managed/Adapter/ManagedTag.cs	Implements ITag over managed refs/object store.
src/GitVersion.Git.Managed/Adapter/ManagedRemoteCollection.cs	Exposes remotes via Core abstractions (with CLI-backed mutations).
src/GitVersion.Git.Managed/Adapter/ManagedRemote.cs	Implements IRemote and refspec exposure for managed backend.
src/GitVersion.Git.Managed/Adapter/ManagedRefSpecCollection.cs	Wraps refspec enumeration.
src/GitVersion.Git.Managed/Adapter/ManagedRefSpec.cs	Parses refspecs in a libgit2-compatible way.
src/GitVersion.Git.Managed/Adapter/ManagedReferenceCollection.cs	Exposes references via Core abstractions, incl. glob enumeration.
src/GitVersion.Git.Managed/Adapter/ManagedReference.cs	Implements IReference over managed reference model.
src/GitVersion.Git.Managed/Adapter/ManagedObjectId.cs	Implements Core IObjectId over hash-agnostic IDs.
src/GitVersion.Git.Managed/Adapter/ManagedGitRepositoryInfo.cs	Implements IGitRepositoryInfo for managed discovery/dynamic repos.
src/GitVersion.Git.Managed/Adapter/ManagedGitRepository.mutating.cs	Implements CLI-backed mutating repository operations.
src/GitVersion.Git.Managed/Adapter/ManagedGitRepository.cs	Implements managed IGitRepository with session invalidation model.
src/GitVersion.Git.Managed/Adapter/ManagedCommitCollection.cs	Implements commit enumeration and filtering with managed revwalk.
src/GitVersion.Git.Managed/Adapter/ManagedCommit.cs	Implements ICommit with managed diff-paths integration.
src/GitVersion.Git.Managed/Adapter/ManagedBranchCollection.cs	Exposes branches via Core abstractions.
src/GitVersion.Git.Managed/Adapter/ManagedBranch.cs	Implements IBranch over managed references.
src/GitVersion.Git.Managed/Adapter/DynamicRepositoryPath.cs	Computes/chooses dynamic clone paths for remote URL scenarios.
src/GitVersion.Git.Managed.Tests/TreeTests.cs	Adds managed ODB tree parsing/streaming reader tests.
src/GitVersion.Git.Managed.Tests/TempDirectory.cs	Adds temp directory helper for managed backend tests.
src/GitVersion.Git.Managed.Tests/TagTests.cs	Adds annotated tag parsing tests (loose/packed/nested).
src/GitVersion.Git.Managed.Tests/PullRequestBranchOperationsTests.cs	Adds tests for PR-ref normalization candidate selection.
src/GitVersion.Git.Managed.Tests/PackedObjectTests.cs	Adds tests for pack reading and deep delta chains.
src/GitVersion.Git.Managed.Tests/MultiPackIndexTests.cs	Adds tests for multi-pack-index reading and lookups.
src/GitVersion.Git.Managed.Tests/GitVersion.Git.Managed.Tests.csproj	Adds the managed-backend test project definition.
src/GitVersion.Git.Managed.Tests/GitTreeDiffTests.cs	Adds libgit2 parity tests for tree diff path listing.
src/GitVersion.Git.Managed.Tests/GitTestRepository.cs	Adds deterministic git-CLI-backed repo fixture for managed tests.
src/GitVersion.Git.Managed.Tests/GitRepositoryLayoutTests.cs	Adds discovery/worktree/shallow/bare/reftable/sha256 tests.
src/GitVersion.Git.Managed.Tests/GitObjectIdTests.cs	Adds tests for hash-agnostic object ID parsing/equality.
src/GitVersion.Git.Managed.Tests/GitIndexTests.cs	Adds tests for index v2–v4 parsing and parity with git ls-files.
src/GitVersion.Git.Managed.Tests/GitConfigurationFileTests.cs	Adds tests for config parsing/escaping behavior.
src/GitVersion.Git.Managed.Tests/DeltaStreamReaderTests.cs	Adds unit tests for delta instruction decoding.
src/GitVersion.Git.Managed.Tests/AssemblyParallelizable.cs	Enables fixture-level test parallelization for managed tests.
src/GitVersion.Core/GitVersion.Core.csproj	Adds internals visibility for managed backend and its tests.
src/GitVersion.Core/Git/GitBackend.cs	Introduces backend enum + environment-based selector.
src/GitVersion.Core.Tests/Helpers/GitVersionCoreTestModule.cs	Selects managed vs libgit2 module in Core test composition.
src/GitVersion.Core.Tests/GitVersion.Core.Tests.csproj	References managed backend from Core tests.
src/GitVersion.Core.Tests/Core/GitCliMutatorTests.cs	Adds tests for CLI mutator behavior and error classification.
src/GitVersion.Core.Tests/Core/GitBackendSelectorTests.cs	Adds tests for env-var backend resolution and fail-fast behavior.
src/GitVersion.App/GitVersionExecutor.cs	Logs selected backend at startup.
src/GitVersion.App/GitVersion.App.csproj	References managed backend from legacy CLI project.
src/GitVersion.App/CliHost.cs	Selects backend module at runtime via GitBackendSelector.
src/.run/cli (version).run.xml	Adds IDE run config for version command.
src/.run/cli (managed).run.xml	Adds IDE run config for managed backend execution.
src/.run/cli (libgit2sharp).run.xml	Adds IDE run config for libgit2 backend execution.
new-cli/GitVersion.Common/GitVersion.Common.csproj	Adds Microsoft.Extensions.Logging using for source-linked files.
docs/input/docs/migration/v6-to-v7.md	Documents backend selection and v7.0/v7.1 default behavior.
build/parity-corpus.md	Documents parity corpus tool for real-world backend diffing.
build/common/Utilities/DockerContextExtensions.cs	Forwards backend env var into docker runs.
BREAKING_CHANGES.md	Documents selectable backend and managed backend behavioral notes.
.github/workflows/ci.yml	Ensures CI runs for the managed-git feature branch.
.github/workflows/_unit_tests.yml	Adds git_backend matrix dimension and forwards env var/flags.
.github/workflows/_docker.yml	Runs docker tests per backend and forwards backend selection.
.github/workflows/_artifacts_windows.yml	Runs artifacts tests sequentially for both backends (Windows).
.github/workflows/_artifacts_linux.yml	Runs artifacts tests for both backends and forwards env var.
.github/actions/docker-test/action.yml	Adds git_backend input and forwards env var into docker tests.

[Copilot]

Pull request overview

Copilot reviewed 118 out of 118 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

src/GitVersion.Git.Managed/Adapter/DynamicRepositoryPath.cs:33

• targetUrl.Split(...)[^1].Replace(".git", string.Empty) removes every occurrence of ".git" (not just a trailing suffix) and also mishandles URLs ending with a slash. This can generate incorrect dynamic-repo directory names (and collisions) for some URLs.
  src/GitVersion.Git.Managed/CommandLine/GitCliExecutor.cs:31
• The git CLI output/error streams are decoded using the process default encoding. Git may emit UTF-8 (e.g., non-ASCII ref names/paths in stderr), which will be garbled on Windows unless the encodings are explicitly set when redirecting output.

[Copilot]

Pull request overview

Copilot reviewed 118 out of 118 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/GitVersion.Git.Managed/CommandLine/GitCliExecutor.cs:97

• BeginOutputReadLine/BeginErrorReadLine uses async event handlers; a single WaitForExit() does not guarantee those handlers have fully drained stdout/stderr. This can truncate output and lead to incorrect error classification/logging. Add a second WaitForExit() (or switch to ReadToEndAsync) to ensure all output is captured before constructing GitCliResult.
  src/GitVersion.Git.Managed/RandomAccessStream.cs:77
• RandomAccessStream advertises CanSeek=true, but Seek throws for SeekOrigin.End. Some consumers of Stream legitimately use SeekOrigin.End (e.g., to seek relative to the end of a known-length file), so this can cause unexpected runtime failures. Support SeekOrigin.End by translating it to length + offset.
  docs/input/docs/migration/v6-to-v7.md:125
• Spelling inconsistency: the docs use American English elsewhere (e.g., “Behavioral notes” in BREAKING_CHANGES.md). Consider changing “behaviour” to “behavior” for consistency.

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.

[Copilot]

Pull request overview

Copilot reviewed 118 out of 118 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/GitVersion.Git.Managed/Adapter/ManagedRemote.cs:21

• The typed Select(IRefSpec (spec) => ...) syntax is invalid C# and will not compile, which breaks construction of the refspec list.
  src/GitVersion.Git.Managed/CommandLine/GitCliExecutor.cs:97
• After switching to ManualResetEvent signaling in the output handlers, the executor also needs to wait for both streams to complete after WaitForExit() to ensure all captured output has been appended before constructing GitCliResult.
  src/GitVersion.Git.Managed/CommandLine/GitCliExecutor.cs:82
• BeginOutputReadLine/BeginErrorReadLine with DataReceived handlers needs an explicit wait for the end-of-stream signal (where e.Data == null). As written, WaitForExit() can return before the last async output callbacks are processed, leading to truncated stdout/stderr capture and potentially misclassified errors.

This issue also appears on line 94 of the same file.

[Copilot]

Pull request overview

Copilot reviewed 118 out of 118 changed files in this pull request and generated 4 comments.

Suppressed comments (2)

.github/workflows/_artifacts_linux.yml:80

• background: true is not a valid GitHub Actions step key and will make the workflow invalid. Remove it; the step will run sequentially like the rest.

      - name: '[Test Artifacts] (managed)'
        background: true
        uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0
        env:

.github/workflows/_docker.yml:74

• background: true is not a valid GitHub Actions step key and will make the workflow fail to parse. Remove it; steps already run sequentially.

      - name: Docker Test (managed)
        if: success() && inputs.publish_images == false
        background: true
        uses: ./.github/actions/docker-test

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.5% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Pull request overview

Copilot reviewed 118 out of 118 changed files in this pull request and generated no new comments.

Suppressed comments (7)

.github/workflows/_docker.yml:64

• background is not a valid GitHub Actions step key, so this workflow will fail YAML validation and never run the docker tests. If you want concurrent runs, use a matrix (e.g., git_backend: [libgit2, managed]) or separate jobs; otherwise run the steps sequentially.

      - name: Docker Test (libgit2)
        if: success() && inputs.publish_images == false
        background: true
        uses: ./.github/actions/docker-test

.github/workflows/_docker.yml:74

• background is not a valid GitHub Actions step key, so this workflow will fail YAML validation. Run this step sequentially (remove background) or switch to a matrix strategy for backend parallelism.

      - name: Docker Test (managed)
        if: success() && inputs.publish_images == false
        background: true
        uses: ./.github/actions/docker-test

.github/workflows/_docker.yml:83

• wait-all is not a valid GitHub Actions step key and there is no built-in mechanism to wait for “background” steps. This step should be removed; if you switch to a matrix or separate jobs, GitHub Actions will handle synchronization automatically.

      - name: Wait for docker backend tests
        wait-all:

.github/workflows/_artifacts_linux.yml:64

• background is not a valid GitHub Actions step key, so this workflow will fail validation. If you need both backends, run these steps sequentially or convert this to a matrix/job fan-out.

      - name: '[Test Artifacts] (libgit2)'
        background: true
        uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0
        env:

.github/workflows/_artifacts_linux.yml:80

• background is not a valid GitHub Actions step key, so this workflow will fail validation. Remove it (sequential execution) or switch to a matrix/job fan-out for parallel backend runs.

      - name: '[Test Artifacts] (managed)'
        background: true
        uses: nick-fields/retry@ad984534de44a9489a53aefd81eb77f87c70dc60 # v4.0.0
        env:

.github/workflows/_artifacts_linux.yml:95

• wait-all is not a valid GitHub Actions step key; this will fail workflow validation. Remove this step. If you need synchronization, use separate jobs (which naturally join) or a matrix strategy.

      - name: Wait for artifact backend tests
        wait-all:

src/GitVersion.Git.Managed/CommandLine/GitCliExecutor.cs:31

• git output decoding can vary by OS/default code page (notably on Windows). Since later code will parse stdout/stderr, set explicit encodings to keep behavior deterministic and avoid corrupting non-ASCII refs/paths in output.

[mergify]

Thank you @arturcic for your contribution!