thodg/libgit2/docs/error-handling.md

Download

Error reporting in libgit2

Error reporting is performed on an explicit git_error ** argument, which appears at the end of all API calls that can return an error. Yes, this does clutter the API.

When a function fails, an error is set on the error variable and returns one of the generic error codes.

int git_repository_open(git_repository **repository, const char *path, git_error **error)
{
    // perform some opening
    if (p_exists(path) < 0) {
        giterr_set(error, GITERR_REPOSITORY, "The path '%s' doesn't exist", path);
        return GIT_ENOTFOUND;
    }

    ...

    if (try_to_parse(path, error) < 0)
        return GIT_ERROR;

    ...
}

The simple error API

The new error code return values

We are doing this the POSIX way: one error code for each “expected failure”, and a generic error code for all the critical failures.

For instance: A reference lookup can have an expected failure (which is when the reference cannot be found), and a critical failure (which could be any of a long list of things that could go wrong, such as the refs packfile being corrupted, a loose ref being written with the wrong permissions, etc). We cannot have distinct error codes for every single error in the library, hence git_reference_lookup would return GIT_SUCCESS if the operation was successful, GIT_ENOTFOUND when the reference doesn’t exist, and GIT_ERROR when an error happens – the error is then detailed in the git_error parameter.

Please be smart when returning error codes. Functions have max two “expected errors”, and in most cases only one.

Writing error messages

Here are some guidelines when writing error messages:

General guidelines for error reporting


Source

Download