Errors topic

Errors

GitException represents engine failures and domain refusals and implements Exception. It carries a message, a nullable cause and a diagnostic. Catch a subclass to handle one refusal, or GitException for the common engine error hierarchy.

Argument and value validation can throw standard Dart errors and exceptions, including ArgumentError, RangeError and FormatException. Underlying process and file-system errors can also propagate without being wrapped in GitException. An operation's dartdoc describes its validation rules.

Named refusals

Each facade operation documents the exceptions it raises for the refusals a caller can treat. Other command failures use GitException, with no further promise about its concrete type. Portable code catches the named domain exceptions first and GitException last within that hierarchy; this does not catch validation errors or unwrapped platform failures.

A refusal decided before git runs is still typed. A reference name that cannot be a reference, a remote location in an unsupported form and a creation target that already holds files are refused this way; no command failed, so they carry no cause. A conflicted merge or a refused patch application is a result, not an exception.

try {
  await repo.branches.delete('topic');
} on GitRefNotFoundException {
  // the branch is already gone
} on GitException catch (error) {
  print(error.diagnostic);
}

Portability of refusals

Domain refusals are portable. A timeout (GitTimeoutException) and an engine older than the minimum (GitVersionException) are refusals every backend can report, whether or not it runs a git command. An operation the package implements but the backend cannot run raises GitFeatureUnavailableException. A backend that cannot be used on the host raises GitEngineUnavailableException; code portable between backends catches that supertype rather than a backend-specific subtype.

Domain exceptions derive from GitException through backend-independent types. They carry the underlying failure in cause when one exists, and leave it null on a backend that runs no command underneath. The process engine raises GitExecutableNotFoundException when it cannot find its executable; that subtype keeps the raw platform error in spawnError and leaves cause null. A repository of the wrong kind raises a GitRepositoryKindException subtype.

URL masking

Command failure messages and refused remote locations mask the userinfo of each scheme-based URL they name: https://user:token@host/repo reads as https://***@host/repo. diagnostic applies this masking throughout its cause chain. The scp-like user@host:path spelling has no scheme and is left as written.

A refused remote location keeps its original spelling on GitUnsupportedUrlException.url, which may contain secrets. Its message and diagnostic mask URL userinfo, but do not redact other kinds of secrets.

diagnostic

diagnostic is the complete technical text of a failure. It starts with message and, when there is a cause, appends that failure's own text after a blank line, stopping after sixteen failures in the chain. A command failure appends the command, its working directory, its exit code and its full output; a timeout cause appends the command and the output captured before the process was stopped.

URL userinfo masking is not general secret redaction. Query parameters, command arguments and process output can still contain tokens, headers or other sensitive data. Apply any additional redaction needed before logging or writing diagnostics to a file.

The format and language are not promised. Command output is not truncated by the diagnostic formatter; a logger applies its own size limit. Code must never read diagnostics to decide a behaviour: catch the exception type instead.

Exceptions / Errors

GitAuthenticationException Errors
The remote refused the offered credentials or demanded credentials that the environment did not provide.
GitBranchNotMergedException Errors
A branch was deleted without force although it is not fully merged.
GitEngineUnavailableException Errors
A git backend cannot be used on this host.
GitException Errors
Base class of the git engine's domain refusals and command failures.
GitExecutableNotFoundException Errors
The git executable could not be started because it was not found.
GitFeatureUnavailableException Errors
An operation the package implements but the backend cannot run.
GitInvalidObjectException Errors
The content handed to GitObjectWriter.writeObject was refused.
GitInvalidRefNameException Errors
A reference name an operation refuses before any git command runs.
GitLocalChangesOverwrittenException Errors
A checkout or a merge was refused because it would overwrite the local state of the work tree.
GitMergeNotFastForwardException Errors
A merge in fast-forward-only mode was refused because no fast-forward is possible from the current HEAD to the requested revision: the histories have diverged, the revision is behind the head, or they share no ancestor.
GitNoMergeInProgressException Errors
An in-progress merge was aborted although none is in progress.
GitNotABareRepositoryException Errors
A repository was opened as a bare repository but has a work tree.
GitNotARepositoryException Errors
The working directory is not inside a git repository.
GitNotAWorkingRepositoryException Errors
A repository was opened as a working repository but is bare.
GitNoUpstreamException Errors
A pull had no branch to integrate.
GitOccupiedDirectoryException Errors
A creation call refused the directory it was given because the directory already holds files.
GitOutputLimitException Errors
A git command produced more standard output than it was allowed.
GitPushRejectedException Errors
A push was refused by the remote.
GitRefExistsException Errors
A branch or a tag could not be created because its name is already taken.
GitRefMismatchException Errors
A ref update was rejected because the ref held a value other than the one the caller expected.
GitRefNotFoundException Errors
A branch or a tag an operation names does not exist.
GitRemoteRefNotFoundException Errors
A fetch or push named a ref the remote does not have.
GitRemoteRepositoryNotFoundException Errors
No repository exists at the remote location.
GitRemoteUnreachableException Errors
The remote host could not be reached.
GitRepositoryKindException Errors
Base class of the failures raised when a repository is not of the kind an opening call requires.
GitTimeoutException Errors
A git operation did not finish within the delay it was given.
GitUnknownRevisionException Errors
A revision an operation requires resolves to nothing.
GitUnknownServedRepositoryException Errors
A served repository identifier no backend resolution knows.
GitUnrelatedHistoriesException Errors
A merge was refused because the two histories share no common ancestor.
GitUnsupportedUrlException Errors
A remote location the client refuses before git runs at all.
GitVersionException Errors
The engine is older than the version required by the caller.