The Trace2 facility

Trace2 (introduced in Git 2.22) is the structured tracing facility built into Git. It emits region begin/end events, child process tracking, and timing information in a stable schema, suitable for both human inspection and automated analysis.

Three flavors

• GIT_TRACE2: human-readable text.
• GIT_TRACE2_PERF: text with timing columns.
• GIT_TRACE2_EVENT: JSON, one event per line.

GIT_TRACE2=1 git status
GIT_TRACE2_PERF=/tmp/perf.log git fetch
GIT_TRACE2_EVENT=/tmp/event.jsonl git log --oneline | head

Set the variable to 1, 2, or true for stderr; an absolute path writes to a file; a directory accumulates one file per invocation.

Persistent config

[trace2]
perfTarget = ~/git-trace/
eventTarget = ~/git-trace/
eventNesting = 4
maxFiles = 200

Auto-deleted after maxFiles rotations.

Reading the perf format

Each line shows depth-indented region timing:

14:23:01.000 |  d0 | main         |  start  |  ... | git status
14:23:01.012 |  d0 | main         | region_enter |  | label:read_directory
14:23:01.220 |  d0 | main         | region_leave |  | label:read_directory
14:23:01.230 |  d0 | main         | exit         |  | code:0
14:23:01.230 |  d0 | main         | atexit       |  | code:0

Look for the longest region_enter/leave spans — those are the bottlenecks.

JSON analysis

jq -c 'select(.event=="region_leave") | {label, t_rel}' /tmp/event.jsonl
jq -s 'group_by(.label) | map({label:.[0].label, total:(map(.t_rel) | add)})' /tmp/event.jsonl

What to measure

• git status on a fresh checkout vs after enabling fsmonitor.
• git log -- path with and without changed-path Bloom filters.
• git fetch before and after MIDX and reachability bitmaps.
• git gc with geometric vs full repack.

Common mistakes

Only collecting one sample — caches and warm filesystem dramatically affect numbers. Run cold and warm. Forgetting to restart the fsmonitor daemon after changing config; it keeps a stale view. Comparing across Git versions without holding the repo state constant.

External tooling

Tools like git-trace2-tools on GitHub turn JSON streams into flame graphs. Microsoft's git-fast-stats aggregates across many runs.

Related

See "Why Git performance matters at scale" for the high-level map.