CodeLogic.GitHelper 4.9.98

This package has a SemVer 2.0.0 package version: 4.9.98+32aff20.

dotnet add package CodeLogic.GitHelper --version 4.9.98

NuGet\Install-Package CodeLogic.GitHelper -Version 4.9.98

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.9.98" />

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

<PackageVersion Include="CodeLogic.GitHelper" Version="4.9.98" />
                    

                            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.9.98

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

#r "nuget: CodeLogic.GitHelper, 4.9.98"

#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.9.98

#: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.9.98
                    

                            Install as a Cake Addin

#tool nuget:?package=CodeLogic.GitHelper&version=4.9.98
                    

                            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.

Changing config while running

With CodeLogic 4.9+, config.githelper.json applies live when changed through Libraries.UpdateConfigAsync, Libraries.ReloadConfigAsync, or the config file watcher. Only the repositories that changed are touched:

Changed or removed repository: dropped from the cache. Its old GitRepository is disposed once the git operation running on it finishes, and the next GetRepositoryAsync opens it with the new settings. Call GetRepositoryAsync again rather than keeping an old instance.
Added repository: available at once.
Untouched repositories: keep their open instances.
Library-wide settings (cache, timeouts, concurrency) apply at once. A changed baseDirectory re-resolves every relative localPath.
Added or changed repositories with autoFetch are fetched in the background.
Repositories added with RegisterRepository are kept across changes and never written to the file.
enabled can be switched either way.

Documentation

Full guide: CL.GitHelper documentation

Requirements

CodeLogic 4.9+ · .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.9.0 && < 5.0.0)
- LibGit2Sharp (>= 0.32.0)

NuGet packages (1)

Showing the top 1 NuGet packages that depend on CodeLogic.GitHelper:

Package	Downloads
CodeLogic.WebLogic Web application toolkit for CodeLogic 4 — routing, templates, forms, an ordered security pipeline, auth flows and realtime. No third-party dependencies beyond CodeLogic.*.	0

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
4.9.98	33	10/25/2026
4.8.93	54	9/23/2026
4.8.87	88	9/13/2026
4.8.86	56	9/13/2026
4.8.85	53	9/12/2026
4.6.72	225	6/20/2026
4.6.69-preview	56	6/20/2026
4.5.2	134	5/24/2026
4.5.2-preview.68	80	6/20/2026
4.5.1	182	5/24/2026
4.5.1-preview.56	121	5/24/2026
4.4.2-preview.53	83	5/24/2026
4.4.1	122	5/24/2026
4.0.5	122	5/15/2026
4.0.4	125	5/9/2026
4.0.3	131	5/9/2026
4.0.1	411	4/26/2026
3.3.1	651	4/18/2026
3.3.0	134	4/18/2026
3.2.11	137	4/18/2026

# CL.GitHelper — Changelog

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

## 2026-10-24

### Added

- **Live config changes** (requires CodeLogic 4.9+). `GitHelperLibrary` implements `IConfigReloadable`:
a change to `config.githelper.json` made through `Libraries.UpdateConfigAsync`,
`Libraries.ReloadConfigAsync` or the config file watcher is applied without a restart, touching only
the repositories that changed. Changed or removed repositories are evicted from the cache and their
old `GitRepository` is disposed once its running git operation finishes; untouched repositories keep
their instances; library-wide settings and `baseDirectory` apply at once; added or changed
repositories with `autoFetch` are fetched in the background. `Enabled` can be switched either way.
The `RequiresRestart` hints on `id`, `repositoryUrl`, `localPath` and `baseDirectory` were removed.

### Changed

- `GitManager` keeps its own copy of the configuration. Repositories added with `RegisterRepository`
no longer appear in `Configuration.Get<GitHelperConfig>()` (and so can no longer be written to
`config.githelper.json` by a later save); they are kept across config changes.

## 2026-09-12

### Changed

- Unified the version line with the CodeLogic framework on **4.8.x**. Every official
library and the framework now share one `major.minor`, so a given `4.8.<patch>`
means the same generation across all packages.
- `version.txt` moved from `4.6` to `4.8`. The patch component remains the CI run
number, composed at pack time; `AssemblyVersion` stays pinned at `Major.Minor.0.0`
(now `4.8.0.0`) so every patch in the line loads interchangeably.

## 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/zyntal-com/CodeLogic.Libs/commits/main/CL.GitHelper).