Soenneker.Git.Util 11.0.3901

Soenneker.Git.Util

Asynchronous Git operations backed by bundled Windows and Linux Git distributions, with repository discovery and optional bounded parallel execution across multiple repositories.

Install

dotnet add package Soenneker.Git.Util

Configure and register

using Soenneker.Git.Util.Registrars;
using Microsoft.Extensions.DependencyInjection;

services.AddGitUtilAsSingleton();

Scoped registration is available through AddGitUtilAsScoped().

The utility reads its default credentials and branch once when it is constructed:

{
  "Git": {
    "Token": "<GitHub token>",
    "Name": "Commit author",
    "Email": "author@example.com",
    "DefaultBranch": "main",
    "Log": false
  }
}

Token, Name, and Email are required configuration values. A token supplied to an individual method overrides the configured token. Authentication is non-interactive and is applied to GitHub HTTPS requests without putting the token in the remote URL or command log.

Common operations

IGitUtil git = serviceProvider.GetRequiredService<IGitUtil>();

string checkout = await git.CloneToTempDirectory(
    "https://github.com/example/project.git",
    cancellationToken: cancellationToken);

await git.Fetch(checkout, cancellationToken: cancellationToken);

if (await git.HasWorkingTreeChanges(checkout, cancellationToken))
{
    await git.Commit(checkout, "Update generated files", cancellationToken: cancellationToken);
    await git.Push(checkout, token, cancellationToken);
}

CloneToTempDirectory returns a shallow clone and transfers ownership of that temporary directory to the caller.

Repository discovery and batches

IReadOnlyList<string> dirty =
    await git.GetAllDirtyRepositories(@"C:\git", cancellationToken);

await git.FetchAllGitRepositories(
    @"C:\git",
    parallel: true,
    cancellationToken: cancellationToken);

Discovery accepts either a repository root or a directory containing repositories. Batch operations are sequential by default. With parallel: true, concurrency is bounded to at most eight repositories and the processor count.

API at a glance

Synchronization and recovery safety

SwitchToRemoteBranch fetches origin, then checks out the configured branch only when the working tree is clean and local HEAD is an ancestor of the remote branch. It refuses uncommitted changes, unpushed commits, and divergent history instead of resetting or cleaning them.

GarbageCollectOrReclone is intended for repository recovery. If garbage collection fails, it clones a replacement beside the repository first, swaps it into place only after cloning succeeds, and restores the original directory if the swap fails. A successful replacement intentionally discards local-only repository state, so use this method only when recloning from origin is acceptable.

Practical notes

• Cancellation stops process execution and pending batch work; it cannot undo a Git operation that already completed.
• DeleteMultiPackIndex, repack, garbage collection, commits, pushes, and recovery methods mutate repositories. Use the inspection methods first when caller-owned work may be present.