ktsu.GitIntegration 2.4.0

ktsu.GitIntegration

A .NET library that wraps the git binary behind a fluent, strongly-typed interface, and unifies access to hosted Git providers behind a single abstraction.

Introduction

ktsu.GitIntegration is a two-layer library. The local layer wraps the git executable found on PATH behind a fluent, strongly-typed interface: open or discover a repository, then build and run both read-only commands (status, log, diff, branches, remotes, rev-parse) and mutating commands (init, clone, add, commit, branch creation and deletion, checkout, remote management, and remote sync via fetch, pull, and push) without shelling out or hand-parsing porcelain output yourself. The hosting layer — the original half of this library — unifies access to hosted Git providers behind a GitProvider abstraction, with a GitHubProvider implementation built on Octokit.

Every value that would otherwise be a bare string — a branch name, a commit SHA, a remote name, an author email — is instead a validated semantic type built on ktsu.Semantics, so a GitBranchName can no longer be accidentally passed where a GitCommitSha is expected.

Azure DevOps hosting support is planned but not yet implemented. The two Azure DevOps client packages were deliberately left out of this release because they pull in System.Data.SqlClient, which carries a known high-severity advisory, as a direct dependency of the published package.

Features

• Local Git Client: IGitClient/GitClient finds and opens repositories — GetVersionAsync, IsRepositoryAsync, OpenAsync, DiscoverAsync — and creates new ones — Init(...), Clone(...) — by delegating every invocation to ktsu.RunCommand.
• Fluent Verb Builders: GitRepository exposes one builder per read-only verb — Status(), Log(), Diff(), Branches(), Remotes(), RevParse(...) — and one per mutating verb — Add(), Commit(...), CreateBranch(...), DeleteBranch(...), Checkout(...), AddRemote(...), RemoveRemote(...), SetRemoteUrl(...), Fetch(), Pull(), Push() — each configurable via chained method calls and run with ExecuteAsync or the non-throwing TryExecuteAsync.
• Remote Sync: Fetch() downloads objects and refs without touching the working tree, Pull() fetches and integrates into the current branch, and Push() sends local commits — fetch and push report a machine-readable, per-reference account of what happened via GitFetchResult/GitPushResult, and a rejected push is the one place in this library where ExecuteAsync and TryExecuteAsync diverge in more than exception-versus-result.
• Strongly-Typed Results: GitStatus, GitCommit, GitBranch, GitRemote, GitDiffEntry, GitVersion, GitInitResult, GitCompleted, GitFetchResult, GitPushResult, and GitRefUpdate records replace ad-hoc porcelain parsing with typed models — GitCompleted is the shared result for mutating verbs whose only outcome is success.
• Reproducible Failures: every command is scoped with git -C <path> instead of a process working directory, so a failing invocation's exact argument vector can be read off a GitCommandException and rerun verbatim.
• Locale-Safe Parsing: every invocation runs with GIT_TERMINAL_PROMPT=0 (no hanging credential prompts) and LC_ALL=C (English, machine-stable output), which is what makes the output parsers safe to write against fixed English text.
• Dependency Injection: AddGitIntegration() registers the client, process runner, and options as singletons in one call.
• Hosting Provider Abstraction: GitProvider defines a common contract for enumerating and refreshing remote repositories; GitHubProvider implements it on top of Octokit.
• Credential Resolution: hosting providers integrate with ktsu.CredentialCache, so credentials come from the host's native keyring rather than configuration files.
• Semantic Git Types: 13 validated wrapper types for every identifier Git tooling passes around, so mismatched arguments fail at compile time rather than at runtime.

Installation

Package Manager Console

Install-Package ktsu.GitIntegration

.NET CLI

dotnet add package ktsu.GitIntegration

Package Reference

<PackageReference Include="ktsu.GitIntegration" Version="x.y.z" />

Usage Examples

Basic Example

Register the library with dependency injection, then resolve IGitClient:

using ktsu.GitIntegration;
using Microsoft.Extensions.DependencyInjection;

ServiceCollection services = new();
services.AddGitIntegration();

using ServiceProvider provider = services.BuildServiceProvider();
IGitClient client = provider.GetRequiredService<IGitClient>();

Discovering a Repository and Reading Its Status

using ktsu.GitIntegration;
using ktsu.Semantics.Paths;
using ktsu.Semantics.Strings;

AbsoluteDirectoryPath here = Environment.CurrentDirectory.As<AbsoluteDirectoryPath>();
GitRepository? repository = await client.DiscoverAsync(here);

if (repository is not null)
{
    GitStatus status = await repository.Status().ExecuteAsync();

    Console.WriteLine(status.IsClean
        ? "Working tree is clean."
        : $"{status.Entries.Count} changed path(s) on {status.Branch?.WeakString}.");
}

Listing Commits and Diffs

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

IReadOnlyList<GitCommit> commits = await repository.Log()
    .Take(10)
    .FirstParentOnly()
    .ExecuteAsync();

foreach (GitCommit commit in commits)
{
    Console.WriteLine($"{commit.Sha.WeakString[..7]} {commit.Subject}");
}

IReadOnlyList<GitDiffEntry> changes = await repository.Diff()
    .Staged()
    .DetectRenames()
    .ExecuteAsync();

Initializing or Cloning a Repository

Init probes the target path before running git init, so GitInitResult.AlreadyExisted can tell a caller whether a repository was already there — git init is idempotent and silently ignores --initial-branch when re-initialising, so a caller that asked for a particular initial branch and got AlreadyExisted == true did not get the branch it asked for:

using ktsu.GitIntegration;
using ktsu.Semantics.Paths;
using ktsu.Semantics.Strings;

AbsoluteDirectoryPath target = Environment.CurrentDirectory.As<AbsoluteDirectoryPath>();

GitInitResult init = await client.Init(target)
    .WithInitialBranch("main".As<GitBranchName>())
    .ExecuteAsync();

GitRepository repository = init.Repository;

Clone builds git clone. Its destination pre-check is advisory only — git enforces the same rule itself, so the check exists solely to fail a doomed clone before it pays its network cost, and it is deliberately racy:

using ktsu.GitIntegration;
using ktsu.Semantics.Paths;
using ktsu.Semantics.Strings;

GitRepositoryRemotePath source = "https://github.com/ktsu-dev/GitIntegration.git".As<GitRepositoryRemotePath>();
AbsoluteDirectoryPath destination = Environment.CurrentDirectory.As<AbsoluteDirectoryPath>();

GitRepository cloned = await client.Clone(source, destination)
    .WithDepth(1)
    .ReportingProgress(new Progress<string>(line => Console.WriteLine(line)))
    .ExecuteAsync();

Staging and Committing Changes

Commit runs git twice: git commit itself, then git log -1 with this library's pinned format, because commit's own output is a human summary carrying only an abbreviated object id, with no machine-readable alternative:

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

await repository.Add().All().ExecuteAsync();

GitCommit commit = await repository.Commit("Add feature X".As<GitCommitMessage>())
    .WithBody("Longer explanation of the change.")
    .WithAuthor("Ada Lovelace".As<GitAuthorName>(), "ada@example.com".As<GitAuthorEmail>())
    .ExecuteAsync();

Console.WriteLine(commit.Sha.WeakString);

Committing with nothing staged throws GitNothingToCommitException, a GitCommandException specialization, rather than the generic base type — the one commit failure that is an ordinary program state rather than a fault:

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

try
{
    await repository.Commit("Nothing changed".As<GitCommitMessage>()).ExecuteAsync();
}
catch (GitNothingToCommitException)
{
    Console.WriteLine("Nothing was staged; skipping this commit.");
}

Creating Branches and Switching

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

await repository.CreateBranch("feature/new-thing".As<GitBranchName>())
    .StartingAt("main".As<GitRefName>())
    .ExecuteAsync();

await repository.Checkout("feature/new-thing".As<GitRefName>()).ExecuteAsync();

// Later, once the branch is no longer needed:
await repository.DeleteBranch("feature/new-thing".As<GitBranchName>())
    .Force()
    .ExecuteAsync();

Managing Remotes

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

GitRepositoryRemotePath url = "https://github.com/example/repo.git".As<GitRepositoryRemotePath>();

await repository.AddRemote("upstream".As<GitRemoteName>(), url)
    .WithFetch()
    .ExecuteAsync();

await repository.SetRemoteUrl("upstream".As<GitRemoteName>(), url)
    .ForPushOnly()
    .ExecuteAsync();

await repository.RemoveRemote("upstream".As<GitRemoteName>()).ExecuteAsync();

Fetching

fetch --porcelain is only available from git 2.41 onward, so Fetch() probes the installed git's version first. Below that threshold the fetch still runs and still succeeds, but GitFetchResult.DetailAvailable is false and Updates is empty — check DetailAvailable before trusting an empty Updates as "nothing changed":

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

GitFetchResult fetched = await repository.Fetch()
    .FromRemote("origin".As<GitRemoteName>())
    .Prune()
    .WithTags()
    .ExecuteAsync();

if (fetched.DetailAvailable)
{
    Console.WriteLine(fetched.IsUpToDate
        ? "Already up to date."
        : $"{fetched.Updates.Count} reference(s) updated.");
}
else
{
    Console.WriteLine("Fetch completed, but this git is older than 2.41 so no per-reference detail is available.");
}

Pulling

Pull() returns GitCompleted rather than a parsed result, because everything git pull prints is human prose with no porcelain form. Use Status() and Log() afterwards to learn what changed. A merge conflict is the one outcome with its own exception, GitPullConflictException, because it leaves the repository mid-merge:

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

try
{
    await repository.Pull()
        .FromRemote("origin".As<GitRemoteName>())
        .WithBranch("main".As<GitBranchName>())
        .FastForwardOnly()
        .ExecuteAsync();
}
catch (GitPullConflictException)
{
    GitStatus status = await repository.Status().ExecuteAsync();
    IEnumerable<GitStatusEntry> unmerged = status.Entries.Where(e => e.IndexState == GitFileState.Unmerged);

    Console.WriteLine($"Pull left {unmerged.Count()} unmerged path(s); resolve them and commit.");
}

FastForwardOnly() and Rebase() are mutually exclusive — combining them throws InvalidOperationException when the argument vector is built, since they mean opposite things about history.

Pushing — Why ExecuteAsync and TryExecuteAsync Disagree

push is the one verb in this library where the two entry points mean genuinely different things, not just exception-versus-result. A rejected push exits non-zero from git and prints a complete porcelain record of every reference — git got far enough to talk about them and refused some. A caller who does not know this will get it wrong by assuming TryExecuteAsync returning Success means the push landed:

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

// ExecuteAsync stays strict: a rejection throws, and the exception carries the full parsed result.
try
{
    GitPushResult pushed = await repository.Push()
        .ToRemote("origin".As<GitRemoteName>())
        .WithBranch("main".As<GitBranchName>())
        .SettingUpstream()
        .ExecuteAsync();
}
catch (GitPushRejectedException ex)
{
    // ex.Result is the same GitPushResult a successful push would have returned.
    foreach (GitRefUpdate update in ex.Result!.Updates.Where(u => u.IsRejected))
    {
        Console.WriteLine($"{update.Reference.WeakString}: {update.Summary}");
    }
}

TryExecuteAsync does not throw for a rejection — git ran and reported exactly what happened, so that report comes back as a successful GitResult. Always check HasRejections, not just Success:

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

GitResult<GitPushResult> result = await repository.Push()
    .ToRemote("origin".As<GitRemoteName>())
    .WithBranch("main".As<GitBranchName>())
    .TryExecuteAsync();

if (result.Success && result.Value!.HasRejections)
{
    // This is still result.Success == true: TryExecuteAsync only fails when git never reached
    // the remote at all. A rejection is reported as data, not as GitResult failure.
    Console.WriteLine("Push ran but at least one reference was rejected — check result.Value.Updates.");
}

ForceWithLease() wins over Force() when both are set, being the safer of the two — it refuses if the remote moved since it was last fetched.

Resolving a Revision Without Throwing

TryExecuteAsync reports a non-zero exit as a result instead of an exception — useful when "no such revision" is an expected outcome rather than a failure:

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

GitResult<GitCommitSha> result = await repository
    .RevParse("maybe-missing-branch".As<GitRefName>())
    .TryExecuteAsync();

if (result.Success)
{
    Console.WriteLine(result.Value!.WeakString);
}
else
{
    Console.WriteLine($"git exited {result.Error!.ExitCode}: {result.Error.StandardError}");
}

Reproducing a Failing Command

ExecuteAsync throws GitCommandException on a non-zero exit, carrying the exact argument vector git was invoked with:

try
{
    await repository.RevParse("no-such-ref".As<GitRefName>()).ExecuteAsync();
}
catch (GitCommandException ex)
{
    // ex.Arguments already begins with "-C <path>", so this can be pasted straight after `git`
    // on a command line to reproduce the failure exactly.
    Console.WriteLine("git " + string.Join(' ', ex.Arguments));
}

Working with a Hosting Provider

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

GitProvider provider = new GitHubProvider
{
    Owner = "ktsu-dev".As<GitProviderOwner>(),
};

// Pulls credentials from the credential cache, then authenticates the client.
provider.RefreshRemoteRepositories();

Working with Semantic Types

using ktsu.GitIntegration;
using ktsu.Semantics.Strings;

GitBranchName branch = "main".As<GitBranchName>();
GitRemoteName remote = "origin".As<GitRemoteName>();
GitCommitSha sha = "9fceb02d0ae598e95dc970b74767f19372d61af8".As<GitCommitSha>();

// These are distinct types — passing a GitBranchName where a GitCommitSha
// is expected is a compile error, not a runtime surprise.

Advanced Usage

Argument Vectors Are Inspectable Before They Run

Every builder's BuildArguments() is a pure computation with no I/O, so the exact command can be asserted or logged before it executes:

IReadOnlyList<string> arguments = repository.Status().BuildArguments();
// ["-C", "<path>", "--no-pager", "-c", "core.quotepath=false", "-c", "color.ui=false",
//  "status", "--porcelain=v2", "--branch", "-z"]

Metadata-Only Repositories

A GitRepository produced by a hosting provider (rather than IGitClient.OpenAsync or DiscoverAsync) carries hosting metadata but no ProcessRunner. Calling any verb on it throws InvalidOperationException immediately, rather than failing later inside git:

GitRepository metadataOnly = new() { LocalPath = somePath, Name = "GitIntegration".As<GitRepositoryName>() };

// Throws InvalidOperationException — obtain a runnable repository from IGitClient first.
_ = metadataOnly.Status();

API Reference

IGitClient / GitClient

The entry point to the local layer: finds and opens repositories, and reports on the git binary.

Methods

GitRepository

Carries LocalPath plus optional hosting metadata, and exposes one builder factory per verb.

Properties

Methods

IGitCommandBuilder<TResult>

The shared contract every verb builder implements. A builder is single-use and not thread-safe.

Methods

Verb Builders

Result and Execution Models

Exceptions

Result Models

GitProvider

Abstract base class describing a hosted Git provider.

Properties

Methods

GitHubProvider

GitProvider implementation backed by Octokit. Authenticates the underlying GitHubClient from a CredentialWithUsernamePassword resolved via TryGetCredential.

ServiceCollectionExtensions

Semantic Types

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License. See the LICENSE.md file for details.