Public API

All public library types live in CODE.Git.Client. The source XML comments are the member-level reference.

Client operations

GitClient(Uri repositoryUrl, IGitCredentials? credentials = null, HttpClient? httpClient = null, GitClientOptions? options = null) validates the URL/options and creates the acquisition pipeline. Dispose the client after awaiting all operations. Caller-injected HTTP clients remain caller-owned.

Member	Contract
`GetFileTreeAsync(CancellationToken = default)`	Returns a complete metadata tree pinned to HEAD, without blob contents; needs shallow and filter support for nonempty repositories
`CloneAsync(IFileHandler, GitFileTree? = null, Func<GitFile, bool>? = null, CancellationToken = default)`	Acquires a snapshot and delivers selected regular/executable files sequentially; returns accounting on success
`Dispose()`	Releases owned transport resources; must not run concurrently with an operation

A null predicate selects every regular/executable file and uses the full acquisition path. A nonnull predicate selects before blob fetch. Passing file => true still uses selective fetching, so it has different server capability requirements from omitting the predicate. A supplied tree is checked against its commit; it must describe the whole snapshot.

Snapshot models

Type	Members and meaning
`GitEntry`	Base class with required `Name` and slash-separated repository-relative `Path`
`GitDirectory`	`Children` are defensively copied and sorted by name using ordinal comparison; root name/path are empty
`GitFile`	Required SHA-1 `ObjectId`, `Mode`, and nullable `Size`; listing has unknown size, callbacks have actual size
`GitFileMode`	`Regular`, `Executable`, `Symlink`, `Gitlink`
`GitFileTree`	Required canonical `RepositoryUrl`, `CommitId`, `Root`; optional `ReferenceName`; `EnumerateFiles()` traverses depth first in deterministic ordinal order

Empty/unborn repositories use an empty commit ID and root. Detached HEAD has a null reference name. Enumeration includes symlink/gitlink entries, even though their content cannot be delivered. Repository identity normalizes trailing slashes but preserves significant path casing and .git spelling.

File delivery

IFileHandler.HandleFileAsync(GitFile, Stream, CancellationToken = default) receives one stream at a time. Read it or deliberately discard it before returning; do not retain it or start background work that outlives the callback. The library closes it immediately afterward. Handler side effects are never retried.

CustomFileHandler adapts a Func<GitFile, Stream, CancellationToken, Task> into this interface. It validates basic path shape and regular/executable mode before invoking the delegate. Applications writing their own filesystem destinations remain responsible for complete path safety.

DiskFileHandler(string rootFolder) creates the destination and writes each file using a sibling temporary file followed by replacement. It validates paths, case collisions, reserved names, and symlink/reparse-point ancestors. Existing destination files can be replaced; unrelated files are not removed. Executable mode is retained as metadata but Unix permissions are not applied. Use a trusted destination exclusively owned by your process. File-level replacement does not make the snapshot transactional.

Results

GitCloneResult describes successful completion. CommitId identifies the pinned snapshot; SelectedFiles counts selected regular/executable files, including skipped LFS pointers; ProcessedFiles counts completed callbacks. TransferredBytes includes HTTP response framing, rather than only file contents.

Warnings records content explicitly skipped under SkipUnsupportedEntries. Failures is empty for library-produced successful results: failed operations throw. IsComplete requires no warnings/failures and equal selected/processed counts. A filtered result can be complete for its selection without containing every repository file.

Errors and cancellation

Exception	Typical cause
`ArgumentException` / `ArgumentOutOfRangeException`	Invalid URL/options or supplied tree that does not match its repository/commit
`ObjectDisposedException`	Operation invoked on a disposed client
`HttpRequestException`	Network failure, HTTP access error, rejected destination, or redirect
`GitUnsupportedOperationException`	Missing protocol capability, refused selective fetch, unsupported object format or snapshot content
`InvalidDataException` / `EndOfStreamException`	Invalid/truncated framing, packs or trees, or exceeded acquisition budgets
`IOException`	Disk failure or handler failure; wrapped callback errors name the path and preserve the inner exception
`OperationCanceledException`	Caller cancellation or cancellation caused by request timeout

Failures can occur after earlier files were delivered. Treat output as partial until a successful result has been checked. Request timeout covers response consumption; a transport timeout is not a whole-operation deadline. Pass a cancellation token to bound the complete operation. Await async APIs; do not require special debugger configuration or block UI threads with .Result/.Wait().

See Authentication for credential types and Security and limits for all GitClientOptions defaults.