Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Environment Variables

GIT_TRACE and friends

Reference for GIT_TRACE, GIT_TRACE_PACKET, GIT_TRACE_PERFORMANCE, GIT_TRACE_SETUP and GIT_TRACE2: see which commands Git runs, what it sends, and where time goes.

Git has a family of environment variables that make it narrate what it is doing. They write to standard error (or to a file you name) and never change the behavior of the command, so they are safe to switch on whenever something looks odd: an alias that does not expand as expected, a fetch that hangs, a git status that takes ten seconds.

Each variable covers one aspect. GIT_TRACE shows commands and aliases, GIT_TRACE_PACKET the pkt-line conversation with a remote, GIT_TRACE_PERFORMANCE timings, GIT_TRACE_SETUP how the repository was found, and GIT_TRACE2 the newer structured event stream.

Terminal
GIT_TRACE=1 git st
GIT_TRACE_PACKET=1 git ls-remote origin
GIT_TRACE_PERFORMANCE=1 git status

Try it

Bash Follow an alias and a command invocation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Watch the ref advertisement on the wire

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
GIT_TRACE=<1|2|path|0> git <command>
Variable What it shows
GIT_TRACE General messages: executable lookup, alias expansion, built-in versus external dispatch, child processes.
GIT_TRACE_PACKET Every pkt-line sent and received by fetch, push and ls-remote, including capabilities.
GIT_TRACE_PERFORMANCE Wall-clock time of internal phases such as reading the index, plus the total per command.
GIT_TRACE_SETUP How the repository, work tree and prefix were discovered (useful with GIT_DIR and GIT_CEILING_DIRECTORIES).
GIT_TRACE_CURL Full HTTP exchange including headers; add GIT_TRACE_CURL_NO_DATA=1 to hide payloads.
GIT_TRACE_PACK_ACCESS, GIT_TRACE_SHALLOW, GIT_TRACE_FSMONITOR Narrower traces for pack reads, shallow negotiation and the file-system monitor.
GIT_TRACE2, GIT_TRACE2_EVENT, GIT_TRACE2_PERF The Trace2 facility: normal, JSON event and per-thread performance formats.

Values: unset, empty, 0, false or no disable the trace. 1, 2, true write to standard error. A value from 3 to 9 is treated as an open file descriptor. An absolute path appends to that file. The GIT_TRACE2* variables additionally accept a directory (one file per process) and an af_unix: socket path for collectors.

Usage notes

  • Output is noisy and contains paths, repository URLs and, with GIT_TRACE_CURL, authorization headers. Redact tokens before pasting a trace into a bug report.
  • The timestamp column and source file:line prefix (10:42:07.123456 git.c:757) vary between runs and versions. Filter with grep or sed when you compare traces.
  • Aliases appear as two steps: Git first tries to run an external git-<name>, finds none, then logs the alias expansion. That is normal, not a failure.
  • Scripts and hooks inherit the variables, so a trace set for git push also records the hooks Git starts. Write to a file in that case, since a hook's stderr may be shown to the user.
  • GIT_TRACE_PERFORMANCE is the first stop for a slow git status: a long refresh index or untracked phase points at the file system, core.fsmonitor or core.untrackedCache.
  • GIT_TRACE_PACKET shows protocol v2 by default on modern Git (version 2, ls-refs, fetch). Set protocol.version=1 to compare.
  • Trace2 is meant for tooling; its normal format (GIT_TRACE2=1) is human-readable, and the JSON format suits telemetry. It also records the child process tree and config settings.