CodeLogic.GitHelper 4.6.69-preview

This is a prerelease version of CodeLogic.GitHelper.

This package has a SemVer 2.0.0 package version: 4.6.69-preview+38521e3.

There is a newer version of this package available.
See the version list below for details.

dotnet add package CodeLogic.GitHelper --version 4.6.69-preview

NuGet\Install-Package CodeLogic.GitHelper -Version 4.6.69-preview

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="CodeLogic.GitHelper" Version="4.6.69-preview" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="CodeLogic.GitHelper" Version="4.6.69-preview" />
                    

                            Directory.Packages.props

<PackageReference Include="CodeLogic.GitHelper" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add CodeLogic.GitHelper --version 4.6.69-preview

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: CodeLogic.GitHelper, 4.6.69-preview"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package CodeLogic.GitHelper@4.6.69-preview

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=CodeLogic.GitHelper&version=4.6.69-preview&prerelease
                    

                            Install as a Cake Addin

#tool nuget:?package=CodeLogic.GitHelper&version=4.6.69-preview&prerelease
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

CodeLogic.GitHelper

Programmatic Git repository management for CodeLogic 4 — clone, fetch, pull, push, commit, branch, and reset, all from configured repositories.

A thin, async wrapper over LibGit2Sharp that manages a pool of named repositories. Every operation returns a GitResult<T> instead of throwing, carries rich GitDiagnostics (timing and transfer counters), and the standout EnsureUpToDateAsync gives you one idempotent call that clones a repository if it's missing or hard-resets it to the remote tip if it already exists.

Install

dotnet add package CodeLogic.GitHelper

Quick start

using CL.GitHelper;

await Libraries.LoadAsync<GitHelperLibrary>();   // register before ConfigureAsync()
await CodeLogic.ConfigureAsync();
await CodeLogic.StartAsync();

var git  = Libraries.Get<GitHelperLibrary>();
var repo = await git.GetRepositoryAsync("Default");

// One idempotent call: clones if missing, else fetches + hard-resets to the remote tip.
GitResult<RepositoryInfo> sync = await repo.EnsureUpToDateAsync();
if (sync.IsSuccess)
    Console.WriteLine($"On {sync.Value!.CurrentBranch} @ {sync.Value.HeadCommitSha[..7]}");
else
    Console.WriteLine($"Sync failed: {sync.ErrorMessage}");

Features

Idempotent sync — EnsureUpToDateAsync clones-or-updates in a single call; the easiest way to keep a working copy at the remote tip.
Full remote workflow — CloneAsync, FetchAsync, PullAsync, PushAsync, each with an options model and CancellationToken.
Commit & status — stage and commit with author metadata (CommitAsync), and inspect the working tree (GetStatusAsync).
Branches — list local/remote branches and check them out (ListBranchesAsync, CheckoutBranchAsync).
Reset & history — ResetHardAsync and GetCommitLogAsync.
Batch operations — FetchAllAsync and GetAllStatusAsync run across every configured repository with bounded concurrency.
Repository caching — configurable in-memory pool with automatic eviction.
No exceptions — every operation returns a GitResult<T> with IsSuccess, Value, ErrorMessage, Exception, and Diagnostics.

Configuration

Auto-generated on first run as config.githelper.json:

{
  "Enabled": true,
  "BaseDirectory": "",
  "DefaultTimeoutSeconds": 300,
  "MaxConcurrentOperations": 3,
  "EnableRepositoryCaching": true,
  "CacheTimeoutMinutes": 30,
  "Repositories": [
    {
      "Id": "Default",
      "Name": "My Repository",
      "RepositoryUrl": "https://github.com/username/repository.git",
      "LocalPath": "my-repo",
      "DefaultBranch": "main",
      "Username": null,
      "Password": null,
      "AutoFetch": false,
      "AutoFetchIntervalMinutes": 0,
      "TimeoutSeconds": 300
    }
  ]
}

Setting	Default	Description
`Enabled`	`true`	Master switch; when `false` the library is inactive and health reports disabled.
`BaseDirectory`	`""`	Root for relative `LocalPath` values; empty means the library data directory.
`DefaultTimeoutSeconds`	`300`	Default per-operation timeout (1–3600).
`MaxConcurrentOperations`	`3`	Concurrency cap for batch operations (1–20).
`EnableRepositoryCaching`	`true`	Keep opened repositories in an in-memory pool.
`CacheTimeoutMinutes`	`30`	Idle eviction window (0–1440; `0` = never expire).
`Repositories`	one entry	Per-repository definitions (URL, local path, branch, credentials).

Each repository entry: Id, Name, RepositoryUrl (required), LocalPath (required; absolute or relative to BaseDirectory), DefaultBranch, Username, Password (PAT), AutoFetch, AutoFetchIntervalMinutes, TimeoutSeconds. Authentication is HTTPS only — see the full guide for details. SSH key fields exist in config but are not currently wired.

Documentation

Full guide: CL.GitHelper documentation

Requirements

CodeLogic 4 · .NET 10
LibGit2Sharp 0.30.x

License

MIT — see LICENSE.

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- CodeLogic (>= 4.0.0 && < 5.0.0)
- LibGit2Sharp (>= 0.30.0)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
4.6.72	179	6/20/2026
4.6.69-preview	32	6/20/2026
4.5.2	104	5/24/2026
4.5.2-preview.68	55	6/20/2026
4.5.1	158	5/24/2026
4.5.1-preview.56	96	5/24/2026
4.4.2-preview.53	62	5/24/2026
4.4.1	104	5/24/2026
4.0.5	104	5/15/2026
4.0.4	105	5/9/2026
4.0.3	112	5/9/2026
4.0.1	398	4/26/2026
3.3.1	614	4/18/2026
3.3.0	115	4/18/2026
3.2.11	126	4/18/2026
3.2.10	107	4/18/2026
3.2.9	112	4/18/2026
3.2.8	103	4/18/2026
3.2.7	104	4/18/2026
3.2.6	110	4/18/2026

# CL.GitHelper — Changelog

All notable changes to **CodeLogic.GitHelper** are documented here. Versions follow
[Semantic Versioning](https://semver.org/).

## 2026-06-20

### Fixed

- SSH is not supported by the bundled LibGit2Sharp transport; configuring an SSH
key now logs a clear warning and cloning an SSH URL (`git@…` / `ssh://…`)
fails fast with an explanatory message instead of silently doing nothing.
- `EnsureUpToDateAsync` now refuses to hard-reset (and discard) a dirty working
tree unless called with `discardLocalChanges: true`, preventing accidental
data loss.
- The repository cache now expires entries by idle time rather than absolute
age, so a repository in active use is no longer disposed out from under a
caller; batch concurrency is clamped to at least 1; `CommitOptions` gained a
`CancellationToken`.

### Documentation

- Full house-style rewrite of the README and the `docs/libs/githelper.md` deep guide.
- Documented the repository workflow around `GetRepositoryAsync` and highlighted
`EnsureUpToDateAsync` as the idempotent clone-or-update easy path.
- Documented the per-operation options models (`GitCloneOptions`, `GitFetchOptions`,
`GitPullOptions`, `GitPushOptions`, `GitCommitOptions`) and the `MergeStrategy` enum.
- Documented the `GitResult<T>` / `GitDiagnostics` contract and the result-bearing models
(`RepositoryInfo`, `CommitInfo`, `BranchInfo`, `RepositoryStatus`, `FileStatusEntry`).
- Documented manager batch operations (`FetchAllAsync`, `GetAllStatusAsync`), runtime
registration, repository caching (`CacheStats` / `CacheEntryStats`), and the health check.
- Clarified authentication: HTTPS only, PAT-only auth sends `x-access-token`, and the SSH
key fields are present in config but not currently wired.

## [4.5.2] — 2026-06-20

### Documentation

- Documented the full `GitRepository` workflow in the README: `CloneAsync`,
`FetchAsync`, `PullAsync`, `PushAsync`, `ListBranchesAsync`, `CheckoutBranchAsync`,
`CommitAsync` (with `FilesToStage`), and `GetCommitLogAsync`.
- Documented the `ResetHardAsync` and `EnsureUpToDateAsync` sync helpers with examples.
- Documented the `GitResult<T>` return contract (`IsSuccess` / `Value` / `ErrorMessage`
/ `Diagnostics`).
- Documented `GitManager` access via `GetManager()`, including `ExecuteOnAllAsync`,
`HealthCheckAsync`, runtime `RegisterRepository` / `UnregisterRepositoryAsync`, and
cache control (`GetCacheStats`, `ClearCacheAsync`).
- Clarified authentication: PAT-only auth sends `x-access-token`, and the SSH key
configuration fields are reserved but not currently wired (use HTTPS URLs).

## [4.5.0] — 2026-05-24

### Changed

- **Unified versioning.** All CodeLogic.Libs now share a single version line
controlled by `version.txt` in the repo root. This is a version alignment
release — no functional changes to this library.
## [4.0.4] — 2026-04-16

### Changed

- README + manifest refresh for the v4 baseline. No functional changes vs 4.0.3.
- `LibraryManifest.Version` now reads from assembly metadata.

## [4.0.3] — 2026-04-15

### Added

- Wired credentials through to `Clone` / `Fetch` / `Pull` and added
`ResetHard` + `EnsureUpToDate` helpers.

## [4.0.2] — 2026-04-09

### Changed

- Annotated GitHelper configuration with `[ConfigField]` for the admin UI surface.
- Aligned with the v4 baseline across all libraries.

## [4.0.0] — 2026-04-09

Major rewrite. Republished as v4.0.0 to reset the version line under the
unified v4 baseline. Thin libgit2sharp wrapper for programmatic clone /
pull / fetch / reset.

### Notes

- Earlier history is retained in the
[git log](https://github.com/Media2A/CodeLogic.Libs/commits/main/CL.GitHelper).