Skip to main content
Git provides a rich set of internal APIs for working with its core data structures and operations. This guide provides an overview of the major API categories.

​
Error Handling API

BUG

For failed internal assertions that should never happen (bugs in Git itself). Calls abort().
BUG("unexpected null pointer");

bug

Like BUG but prints message without calling abort() immediately. Collected bugs trigger BUG() at exit or when BUG_if_bug() is called.
bug("validation failed for option %d", i);
BUG_if_bug(); // abort if any bugs

die

For fatal application errors. Prints message and exits with status 128.
die("fatal: could not open '%s'", path);

usage

For command line usage errors. Exits with status 129.
usage("git command [options]");

error

For non-fatal library errors. Prints message and returns -1.
return error("invalid configuration");

warning

For situations users can work around. Returns -1 after reporting.
warning("file may be corrupted");

​
Customizable Error Handlers

You can override default error behavior: 
set_die_routine(my_custom_die_handler);
set_error_routine(my_custom_error_handler);

​
Caller-Handled Errors

Many functions take a struct strbuf *err parameter: 
struct strbuf err = STRBUF_INIT;

if (ref_transaction_commit(transaction, &err))
    die("%s", err.buf);

// Chain multiple calls
struct transaction *t = ref_transaction_begin(&err);
if (!t ||
    ref_transaction_update(t, "HEAD", ..., &err) ||
    ref_transaction_commit(t, &err))
    die("%s", err.buf);

​
Parse Options API

The parse-options API provides consistent command-line parsing.

​
Basic Usage

1

Include header

#include "parse-options.h"
2

Define usage string

static const char * const builtin_foo_usage[] = {
    "git foo [options] [<args>]",
    NULL
};
3

Define options array

static struct option builtin_foo_options[] = {
    OPT_BOOL('v', "verbose", &verbose, "be verbose"),
    OPT_STRING('o', "output", &output, "file", "output file"),
    OPT_END()
};
4

Parse in cmd_foo

int cmd_foo(int argc, const char **argv, const char *prefix) {
    argc = parse_options(argc, argv, prefix,
                       builtin_foo_options,
                       builtin_foo_usage, 0);
    // Use parsed options...
}

​
Common Option Macros

// Boolean options
OPT_BOOL('v', "verbose", &verbose, "be verbose")
OPT__VERBOSE(&verbose, "be verbose")
OPT__QUIET(&quiet, "be quiet")
OPT__FORCE(&force, "force operation")
OPT__DRY_RUN(&dry_run, "dry run")

// String options  
OPT_STRING('o', "output", &output, "file", "output file")
OPT_FILENAME('f', "file", &filename, "input file")

// Integer options
OPT_INTEGER('n', "number", &number, "number of items")
OPT_COUNTUP('v', "verbose", &verbose, "increase verbosity")

// Callbacks
OPT_CALLBACK('c', "config", &config, "key=value", "set config", config_callback)

// Subcommands
OPT_SUBCOMMAND("add", &cmd_fn, cmd_add)
OPT_SUBCOMMAND("remove", &cmd_fn, cmd_remove)

​
Parse Flags

// Keep the "--" separator
PARSE_OPT_KEEP_DASHDASH

// Stop at first non-option
PARSE_OPT_STOP_AT_NON_OPTION

// Keep argv[0] (program name)
PARSE_OPT_KEEP_ARGV0

// Don't handle -h/--help internally
PARSE_OPT_NO_INTERNAL_HELP

// Allow zero subcommands
PARSE_OPT_SUBCOMMAND_OPTIONAL

​
Trace2 API

Trace2 provides debugging, performance, and telemetry information.

​
Enabling Trace2

export GIT_TRACE2=~/log.normal
git status
Traditional printf-style format similar to GIT_TRACE.

​
Using Trace2 in Code

trace2_cmd_name("checkout");
trace2_cmd_mode("branch");
trace2_def_repo(the_repository);

​
Configuration Parameters

Log interesting config values: 
export GIT_TRACE2_CONFIG_PARAMS=color.ui,core.abbrev
git version

​
Common Data Structures

Git uses several fundamental data structures:
Efficient string building with automatic memory management.
struct strbuf buf = STRBUF_INIT;
strbuf_addstr(&buf, "Hello ");
strbuf_addstr(&buf, "World");
printf("%s\n", buf.buf);
strbuf_release(&buf);
Sorted or unsorted lists of strings.
struct string_list list = STRING_LIST_INIT_DUP;
string_list_append(&list, "item1");
string_list_append(&list, "item2");
string_list_clear(&list, 0);
Dynamic arrays of strings, commonly for argv-like uses.
struct strvec args = STRVEC_INIT;
strvec_push(&args, "git");
strvec_push(&args, "status");
strvec_clear(&args);
Generic hash map implementation.
struct hashmap map;
hashmap_init(&map, hash_fn, cmp_fn, 0);
// Add, lookup, iterate...
hashmap_clear(&map);

​
API Documentation Locations

Detailed API documentation is available in header files:
  • trace2.h - Trace2 public API
  • parse-options.h - Option parsing
  • strbuf.h - String buffers
  • merge-ll.h - Low-level merge
  • xdiff/xdiff.h - Diff engine
When documenting new APIs, use strbuf.h as a model for appropriate tone and level of detail.