trace API

The trace API can be used to print debug messages to stderr or a file. Trace code is inactive unless explicitly enabled by setting GIT_TRACE* environment variables.

The trace implementation automatically adds timestamp file:line ... \n to all trace messages. E.g.:

23:59:59.123456 git.c:312               trace: built-in: git 'foo'
00:00:00.000001 builtin/foo.c:99        foo: some message

Data Structures

struct trace_key

Defines a trace key (or category). The default (for API functions that don’t take a key) is GIT_TRACE.

E.g. to define a trace key controlled by environment variable GIT_TRACE_FOO:

static struct trace_key trace_foo = TRACE_KEY_INIT(FOO);

static void trace_print_foo(const char *message)
{
        trace_printf_key(&trace_foo, "%s", message);
}

Note: don’t use const as the trace implementation stores internal state in the trace_key structure.

Functions

int trace_want(struct trace_key *key)

Checks whether the trace key is enabled. Used to prevent expensive string formatting before calling one of the printing APIs.

void trace_disable(struct trace_key *key)

Disables tracing for the specified key, even if the environment variable was set.

void trace_printf(const char *format, ...)

void trace_printf_key(struct trace_key *key, const char *format, ...)

Prints a formatted message, similar to printf.

void trace_argv_printf(const char **argv, const char *format, ...)`

Prints a formatted message, followed by a quoted list of arguments.

void trace_strbuf(struct trace_key *key, const struct strbuf *data)

Prints the strbuf, without additional formatting (i.e. doesn’t choke on % or even \0).

uint64_t getnanotime(void)

Returns nanoseconds since the epoch (01/01/1970), typically used for performance measurements.

Currently there are high precision timer implementations for Linux (using clock_gettime(CLOCK_MONOTONIC)) and Windows (QueryPerformanceCounter). Other platforms use gettimeofday as time source.

void trace_performance(uint64_t nanos, const char *format, ...)

void trace_performance_since(uint64_t start, const char *format, ...)

Prints the elapsed time (in nanoseconds), or elapsed time since start, followed by a formatted message. Enabled via environment variable GIT_TRACE_PERFORMANCE. Used for manual profiling, e.g.:

uint64_t start = getnanotime();
/* code section to measure */
trace_performance_since(start, "foobar");

uint64_t t = 0;
for (;;) {
        /* ignore */
        t -= getnanotime();
        /* code section to measure */
        t += getnanotime();
        /* ignore */
}
trace_performance(t, "frotz");

Bugs & Caveats

GIT_TRACE_* environment variables can be used to tell Git to show trace output to its standard error stream. Git can often spawn a pager internally to run its subcommand and send its standard output and standard error to it.

Because GIT_TRACE_PERFORMANCE trace is generated only at the very end of the program with atexit(), which happens after the pager exits, it would not work well if you send its log to the standard error output and let Git spawn the pager at the same time.

As a work around, you can for example use --no-pager, or set GIT_TRACE_PERFORMANCE to another file descriptor which is redirected to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its absolute path.

For example instead of the following command which by default may not print any performance information:

GIT_TRACE_PERFORMANCE=2 git log -1

you may want to use:

GIT_TRACE_PERFORMANCE=2 git --no-pager log -1

or:

GIT_TRACE_PERFORMANCE=3 3>&2 git log -1

or:

GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1