diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/config/trace2.txt | 18 | ||||
| -rw-r--r-- | Documentation/git.txt | 53 | ||||
| -rw-r--r-- | Documentation/technical/api-trace2.txt | 46 |
3 files changed, 72 insertions, 45 deletions
diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt index a5f409c1c1..2edbfb02fe 100644 --- a/Documentation/config/trace2.txt +++ b/Documentation/config/trace2.txt @@ -4,17 +4,17 @@ command line arguments are not respected. trace2.normalTarget:: This variable controls the normal target destination. - It may be overridden by the `GIT_TR2` environment variable. + It may be overridden by the `GIT_TRACE2` environment variable. The following table shows possible values. trace2.perfTarget:: This variable controls the performance target destination. - It may be overridden by the `GIT_TR2_PERF` environment variable. + It may be overridden by the `GIT_TRACE2_PERF` environment variable. The following table shows possible values. trace2.eventTarget:: This variable controls the event target destination. - It may be overridden by the `GIT_TR2_EVENT` environment variable. + It may be overridden by the `GIT_TRACE2_EVENT` environment variable. The following table shows possible values. + include::../trace2-target-values.txt[] @@ -22,22 +22,22 @@ include::../trace2-target-values.txt[] trace2.normalBrief:: Boolean. When true `time`, `filename`, and `line` fields are omitted from normal output. May be overridden by the - `GIT_TR2_BRIEF` environment variable. Defaults to false. + `GIT_TRACE2_BRIEF` environment variable. Defaults to false. trace2.perfBrief:: Boolean. When true `time`, `filename`, and `line` fields are omitted from PERF output. May be overridden by the - `GIT_TR2_PERF_BRIEF` environment variable. Defaults to false. + `GIT_TRACE2_PERF_BRIEF` environment variable. Defaults to false. trace2.eventBrief:: Boolean. When true `time`, `filename`, and `line` fields are omitted from event output. May be overridden by the - `GIT_TR2_EVENT_BRIEF` environment variable. Defaults to false. + `GIT_TRACE2_EVENT_BRIEF` environment variable. Defaults to false. trace2.eventNesting:: Integer. Specifies desired depth of nested regions in the event output. Regions deeper than this value will be - omitted. May be overridden by the `GIT_TR2_EVENT_NESTING` + omitted. May be overridden by the `GIT_TRACE2_EVENT_NESTING` environment variable. Defaults to 2. trace2.configParams:: @@ -45,7 +45,7 @@ trace2.configParams:: settings that should be recorded in the trace2 output. For example, `core.*,remote.*.url` would cause the trace2 output to contain events listing each configured remote. - May be overridden by the `GIT_TR2_CONFIG_PARAMS` environment + May be overridden by the `GIT_TRACE2_CONFIG_PARAMS` environment variable. Unset by default. trace2.destinationDebug:: @@ -53,4 +53,4 @@ trace2.destinationDebug:: trace target destination cannot be opened for writing. By default, these errors are suppressed and tracing is silently disabled. May be overridden by the - `GIT_TR2_DST_DEBUG` environment variable. + `GIT_TRACE2_DST_DEBUG` environment variable. diff --git a/Documentation/git.txt b/Documentation/git.txt index 72adfcc5e2..6ddc1e2ca6 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -660,26 +660,53 @@ of clones and fetches. When a curl trace is enabled (see `GIT_TRACE_CURL` above), do not dump data (that is, only dump info lines and headers). -`GIT_TR2`:: +`GIT_TRACE2`:: Enables more detailed trace messages from the "trace2" library. - Output from `GIT_TR2` is a simple text-based format for human + Output from `GIT_TRACE2` is a simple text-based format for human readability. + -The `GIT_TR2` variables can take many values. Any value available to -the `GIT_TRACE` variables is also available to `GIT_TR2`. The `GIT_TR2` -variables can also specify a Unix Domain Socket. See -link:technical/api-trace2.html[Trace2 documentation] for full details. +If this variable is set to "1", "2" or "true" (comparison +is case insensitive), trace messages will be printed to +stderr. ++ +If the variable is set to an integer value greater than 2 +and lower than 10 (strictly) then Git will interpret this +value as an open file descriptor and will try to write the +trace messages into this file descriptor. ++ +Alternatively, if the variable is set to an absolute path +(starting with a '/' character), Git will interpret this +as a file path and will try to append the trace messages +to it. If the path already exists and is a directory, the +trace messages will be written to files (one per process) +in that directory, named according to the last component +of the SID and an optional counter (to avoid filename +collisions). ++ +In addition, if the variable is set to +`af_unix:[<socket_type>:]<absolute-pathname>`, Git will try +to open the path as a Unix Domain Socket. The socket type +can be either `stream` or `dgram`. ++ +Unsetting the variable, or setting it to empty, "0" or +"false" (case insensitive) disables trace messages. ++ +See link:technical/api-trace2.html[Trace2 documentation] +for full details. + -`GIT_TR2_EVENT`:: +`GIT_TRACE2_EVENT`:: This setting writes a JSON-based format that is suited for machine - interpretation. See link:technical/api-trace2.html[Trace2 documentation] - for full details. + interpretation. + See `GIT_TRACE2` for available trace output options and + link:technical/api-trace2.html[Trace2 documentation] for full details. -`GIT_TR2_PERF`:: - In addition to the text-based messages available in `GIT_TR2`, this +`GIT_TRACE2_PERF`:: + In addition to the text-based messages available in `GIT_TRACE2`, this setting writes a column-based format for understanding nesting - regions. See link:technical/api-trace2.html[Trace2 documentation] - for full details. + regions. + See `GIT_TRACE2` for available trace output options and + link:technical/api-trace2.html[Trace2 documentation] for full details. `GIT_REDACT_COOKIES`:: This can be set to a comma-separated list of strings. When a curl trace diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 9e585b8e79..23c3cc7a37 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -23,7 +23,7 @@ formats in the future. This might be used to define a binary format, for example. Trace2 is controlled using `trace2.*` config values in the system and -global config files and `GIT_TR2*` environment variables. Trace2 does +global config files and `GIT_TRACE2*` environment variables. Trace2 does not read from repo local or worktree config files or respect `-c` command line config settings. @@ -42,7 +42,7 @@ config setting. For example ------------ -$ export GIT_TR2=~/log.normal +$ export GIT_TRACE2=~/log.normal $ git version git version 2.20.1.155.g426c96fcdb ------------ @@ -71,13 +71,13 @@ $ cat ~/log.normal The performance format target (PERF) is a column-based format to replace GIT_TRACE_PERFORMANCE and is suitable for development and testing, possibly to complement tools like gprof. This format is -enabled with the `GIT_TR2_PERF` environment variable or the +enabled with the `GIT_TRACE2_PERF` environment variable or the `trace2.perfTarget` system or global config setting. For example ------------ -$ export GIT_TR2_PERF=~/log.perf +$ export GIT_TRACE2_PERF=~/log.perf $ git version git version 2.20.1.155.g426c96fcdb ------------ @@ -104,14 +104,14 @@ $ cat ~/log.perf === The Event Format Target The event format target is a JSON-based format of event data suitable -for telemetry analysis. This format is enabled with the `GIT_TR2_EVENT` +for telemetry analysis. This format is enabled with the `GIT_TRACE2_EVENT` environment variable or the `trace2.eventTarget` system or global config setting. For example ------------ -$ export GIT_TR2_EVENT=~/log.event +$ export GIT_TRACE2_EVENT=~/log.event $ git version git version 2.20.1.155.g426c96fcdb ------------ @@ -273,7 +273,7 @@ significantly affects program performance or behavior, such as Emits a "def_param" messages for "important" configuration settings. + -The environment variable `GIT_TR2_CONFIG_PARAMS` or the `trace2.configParams` +The environment variable `GIT_TRACE2_CONFIG_PARAMS` or the `trace2.configParams` config value can be set to a list of patterns of important configuration settings, for example: `core.*,remote.*.url`. This function will iterate over all config @@ -465,7 +465,7 @@ Events are written as lines of the form: Note that this may contain embedded LF or CRLF characters that are not escaped, so the event may spill across multiple lines. -If `GIT_TR2_BRIEF` or `trace2.normalBrief` is true, the `time`, `filename`, +If `GIT_TRACE2_BRIEF` or `trace2.normalBrief` is true, the `time`, `filename`, and `line` fields are omitted. This target is intended to be more of a summary (like GIT_TRACE) and @@ -533,7 +533,7 @@ This field is in anticipation of in-proc submodules in the future. 15:33:33.532712 wt-status.c:2331 | d0 | main | region_leave | r1 | 0.127568 | 0.001504 | status | label:print ------------ -If `GIT_TR2_PERF_BRIEF` or `trace2.perfBrief` is true, the `time`, `file`, +If `GIT_TRACE2_PERF_BRIEF` or `trace2.perfBrief` is true, the `time`, `file`, and `line` fields are omitted. ------------ @@ -598,7 +598,7 @@ The following key/value pairs are common to all events: `"repo":<repo-id>`:: when present, is the integer repo-id as described previously. -If `GIT_TR2_EVENT_BRIEF` or `trace2.eventBrief` is true, the `file` +If `GIT_TRACE2_EVENT_BRIEF` or `trace2.eventBrief` is true, the `file` and `line` fields are omitted from all events and the `time` field is only present on the "start" and "atexit" events. @@ -911,7 +911,7 @@ visited. The `category` field may be used in a future enhancement to do category-based filtering. + -`GIT_TR2_EVENT_NESTING` or `trace2.eventNesting` can be used to +`GIT_TRACE2_EVENT_NESTING` or `trace2.eventNesting` can be used to filter deeply nested regions and data events. It defaults to "2". `"region_leave"`:: @@ -1039,8 +1039,8 @@ rev-list, and gc. This example also shows that fetch took 5.199 seconds and of that 4.932 was in ssh. + ---------------- -$ export GIT_TR2_BRIEF=1 -$ export GIT_TR2=~/log.normal +$ export GIT_TRACE2_BRIEF=1 +$ export GIT_TRACE2=~/log.normal $ git fetch origin ... ---------------- @@ -1075,8 +1075,8 @@ its name as "gc", it also reports the hierarchy as "fetch/gc". indented for clarity.) + ---------------- -$ export GIT_TR2_BRIEF=1 -$ export GIT_TR2=~/log.normal +$ export GIT_TRACE2_BRIEF=1 +$ export GIT_TRACE2=~/log.normal $ git fetch origin ... ---------------- @@ -1134,8 +1134,8 @@ In this example, scanning for untracked files ran from +0.012568 to +0.027149 (since the process started) and took 0.014581 seconds. + ---------------- -$ export GIT_TR2_PERF_BRIEF=1 -$ export GIT_TR2_PERF=~/log.perf +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf $ git status ... @@ -1180,8 +1180,8 @@ static enum path_treatment read_directory_recursive(struct dir_struct *dir, We can further investigate the time spent scanning for untracked files. + ---------------- -$ export GIT_TR2_PERF_BRIEF=1 -$ export GIT_TR2_PERF=~/log.perf +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf $ git status ... $ cat ~/log.perf @@ -1236,8 +1236,8 @@ int read_index_from(struct index_state *istate, const char *path, This example shows that the index contained 3552 entries. + ---------------- -$ export GIT_TR2_PERF_BRIEF=1 -$ export GIT_TR2_PERF=~/log.perf +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf $ git status ... $ cat ~/log.perf @@ -1310,8 +1310,8 @@ Data events are tagged with the active thread name. They are used to report the per-thread parameters. + ---------------- -$ export GIT_TR2_PERF_BRIEF=1 -$ export GIT_TR2_PERF=~/log.perf +$ export GIT_TRACE2_PERF_BRIEF=1 +$ export GIT_TRACE2_PERF=~/log.perf $ git status ... $ cat ~/log.perf |