trace2: Add variable description to git.txt

index 00156d64aa..e802886999 100644
@@ -661,6 +661,27 @@ 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`::
+	Enables more detailed trace messages from the "trace2" library.
+	Output from `GIT_TR2` 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.
+
+`GIT_TR2_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.
+
+`GIT_TR2_PERF`::
+	In addition to the text-based messages available in `GIT_TR2`, this
+	setting writes a column-based format for understanding nesting
+	regions. See 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
 	is enabled (see `GIT_TRACE_CURL` above), whenever a "Cookies:" header

index a5f409c1c1..2edbfb02fe 100644
@@ -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.

index 72adfcc5e2..fcf81e3acf 100644
@@ -660,23 +660,23 @@ 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`
+The `GIT_TRACE2` variables can take many values. Any value available to
+the `GIT_TRACE` variables is also available to `GIT_TRACE2`. The `GIT_TRACE2`
 variables can also specify a Unix Domain Socket. 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.
 
-`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.

147 lines not on this page · raw message

index 1f462204ea..77a224aafb 100755
@@ -93,7 +93,7 @@ test_expect_success 'No extra GIT_* on alias scripts' '
 		sed -n \
 			-e "/^GIT_PREFIX=/d" \
 			-e "/^GIT_TEXTDOMAINDIR=/d" \
-			-e "/^GIT_TR2_PARENT/d" \
+			-e "/^GIT_TRACE2_PARENT/d" \
 			-e "/^GIT_/s/=.*//p" |
 		sort
 	EOF

index 71194a3623..ce7574edb1 100755
@@ -4,9 +4,9 @@ test_description='test trace2 facility (normal target)'
 . ./test-lib.sh
 
 # Turn off any inherited trace2 settings for this test.
-sane_unset GIT_TR2 GIT_TR2_PERF GIT_TR2_EVENT
-sane_unset GIT_TR2_BRIEF
-sane_unset GIT_TR2_CONFIG_PARAMS
+sane_unset GIT_TRACE2 GIT_TRACE2_PERF GIT_TRACE2_EVENT
+sane_unset GIT_TRACE2_BRIEF
+sane_unset GIT_TRACE2_CONFIG_PARAMS
 
 # Add t/helper directory to PATH so that we can use a relative
 # path to run nested instances of test-tool.exe (see 004child).

@@ -27,12 +27,12 @@ V=$(git version | sed -e 's/^git version //') && export V
 # to whatever filtering that target decides to do).
 # This script tests the normal target in isolation.
 #
-# Defer setting GIT_TR2 until the actual command line we want to test
+# Defer setting GIT_TRACE2 until the actual command line we want to test
 # because hidden git and test-tool commands run by the test harness
 # can contaminate our output.
 
 # Enable "brief" feature which turns off "<clock> <file>:<line> " prefix.
-GIT_TR2_BRIEF=1 && export GIT_TR2_BRIEF
+GIT_TRACE2_BRIEF=1 && export GIT_TRACE2_BRIEF
 
 # Basic tests of the trace2 normal stream.  Since this stream is used
 # primarily with printf-style debugging/tracing, we do limited testing

@@ -54,7 +54,7 @@ GIT_TR2_BRIEF=1 && export GIT_TR2_BRIEF
 
 test_expect_success 'normal stream, return code 0' '
 	test_when_finished "rm trace.normal actual expect" &&
-	GIT_TR2="$(pwd)/trace.normal" test-tool trace2 001return 0 &&
+	GIT_TRACE2="$(pwd)/trace.normal" test-tool trace2 001return 0 &&
 	perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <trace.normal >actual &&
 	cat >expect <<-EOF &&
 		version $V

@@ -68,7 +68,7 @@ test_expect_success 'normal stream, return code 0' '
 
 test_expect_success 'normal stream, return code 1' '
 	test_when_finished "rm trace.normal actual expect" &&
-	test_must_fail env GIT_TR2="$(pwd)/trace.normal" test-tool trace2 001return 1 &&
+	test_must_fail env GIT_TRACE2="$(pwd)/trace.normal" test-tool trace2 001return 1 &&
 	perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <trace.normal >actual &&
 	cat >expect <<-EOF &&
 		version $V

@@ -83,7 +83,7 @@ test_expect_success 'normal stream, return code 1' '
 test_expect_success 'automatic filename' '
 	test_when_finished "rm -r traces actual expect" &&
 	mkdir traces &&
-	GIT_TR2="$(pwd)/traces" test-tool trace2 001return 0 &&
+	GIT_TRACE2="$(pwd)/traces" test-tool trace2 001return 0 &&
 	perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <"$(ls traces/*)" >actual &&
 	cat >expect <<-EOF &&
 		version $V

@@ -101,7 +101,7 @@ test_expect_success 'automatic filename' '
 
 test_expect_success 'normal stream, exit code 0' '
 	test_when_finished "rm trace.normal actual expect" &&
-	GIT_TR2="$(pwd)/trace.normal" test-tool trace2 002exit 0 &&
+	GIT_TRACE2="$(pwd)/trace.normal" test-tool trace2 002exit 0 &&
 	perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <trace.normal >actual &&
 	cat >expect <<-EOF &&
 		version $V

@@ -115,7 +115,7 @@ test_expect_success 'normal stream, exit code 0' '
 
 test_expect_success 'normal stream, exit code 1' '
 	test_when_finished "rm trace.normal actual expect" &&
-	test_must_fail env GIT_TR2="$(pwd)/trace.normal" test-tool trace2 002exit 1 &&
+	test_must_fail env GIT_TRACE2="$(pwd)/trace.normal" test-tool trace2 002exit 1 &&
 	perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <trace.normal >actual &&
 	cat >expect <<-EOF &&
 		version $V

@@ -133,7 +133,7 @@ test_expect_success 'normal stream, exit code 1' '
 
 test_expect_success 'normal stream, error event' '
 	test_when_finished "rm trace.normal actual expect" &&
-	GIT_TR2="$(pwd)/trace.normal" test-tool trace2 003error "hello world" "this is a test" &&
+	GIT_TRACE2="$(pwd)/trace.normal" test-tool trace2 003error "hello world" "this is a test" &&
 	perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <trace.normal >actual &&
 	cat >expect <<-EOF &&
 		version $V

@@ -147,7 +147,7 @@ test_expect_success 'normal stream, error event' '
 	test_cmp expect actual
 '
 
-sane_unset GIT_TR2_BRIEF
+sane_unset GIT_TRACE2_BRIEF
 
 # Now test without environment variables and get all Trace2 settings
 # from the global config.

index b501e867af..2c3ad6e8c1 100755
@@ -4,9 +4,9 @@ test_description='test trace2 facility (perf target)'
 . ./test-lib.sh
 
 # Turn off any inherited trace2 settings for this test.
-sane_unset GIT_TR2 GIT_TR2_PERF GIT_TR2_EVENT
-sane_unset GIT_TR2_PERF_BRIEF
-sane_unset GIT_TR2_CONFIG_PARAMS
+sane_unset GIT_TRACE2 GIT_TRACE2_PERF GIT_TRACE2_EVENT
+sane_unset GIT_TRACE2_PERF_BRIEF
+sane_unset GIT_TRACE2_CONFIG_PARAMS
 
 # Add t/helper directory to PATH so that we can use a relative
 # path to run nested instances of test-tool.exe (see 004child).

@@ -27,13 +27,13 @@ V=$(git version | sed -e 's/^git version //') && export V
 # to whatever filtering that target decides to do).
 # Test each target independently.
 #
-# Defer setting GIT_TR2_PERF until the actual command we want to
+# Defer setting GIT_TRACE2_PERF until the actual command we want to
 # test because hidden git and test-tool commands in the test
 # harness can contaminate our output.
 
 # Enable "brief" feature which turns off the prefix:
 #     "<clock> <file>:<line> | <nr_parents> | "
-GIT_TR2_PERF_BRIEF=1 && export GIT_TR2_PERF_BRIEF
+GIT_TRACE2_PERF_BRIEF=1 && export GIT_TRACE2_PERF_BRIEF
 
 # Repeat some of the t0210 tests using the perf target stream instead of
 # the normal stream.

@@ -46,7 +46,7 @@ GIT_TR2_PERF_BRIEF=1 && export GIT_TR2_PERF_BRIEF
 
 test_expect_success 'perf stream, return code 0' '
 	test_when_finished "rm trace.perf actual expect" &&
-	GIT_TR2_PERF="$(pwd)/trace.perf" test-tool trace2 001return 0 &&
+	GIT_TRACE2_PERF="$(pwd)/trace.perf" test-tool trace2 001return 0 &&
 	perl "$TEST_DIRECTORY/t0211/scrub_perf.perl" <trace.perf >actual &&
 	cat >expect <<-EOF &&
 		d0|main|version|||||$V

@@ -60,7 +60,7 @@ test_expect_success 'perf stream, return code 0' '
 
 test_expect_success 'perf stream, return code 1' '
 	test_when_finished "rm trace.perf actual expect" &&
-	test_must_fail env GIT_TR2_PERF="$(pwd)/trace.perf" test-tool trace2 001return 1 &&
+	test_must_fail env GIT_TRACE2_PERF="$(pwd)/trace.perf" test-tool trace2 001return 1 &&
 	perl "$TEST_DIRECTORY/t0211/scrub_perf.perl" <trace.perf >actual &&
 	cat >expect <<-EOF &&
 		d0|main|version|||||$V

@@ -78,7 +78,7 @@ test_expect_success 'perf stream, return code 1' '
 
 test_expect_success 'perf stream, error event' '
 	test_when_finished "rm trace.perf actual expect" &&
-	GIT_TR2_PERF="$(pwd)/trace.perf" test-tool trace2 003error "hello world" "this is a test" &&
+	GIT_TRACE2_PERF="$(pwd)/trace.perf" test-tool trace2 003error "hello world" "this is a test" &&
 	perl "$TEST_DIRECTORY/t0211/scrub_perf.perl" <trace.perf >actual &&
 	cat >expect <<-EOF &&
 		d0|main|version|||||$V

@@ -124,7 +124,7 @@ test_expect_success 'perf stream, error event' '
 
 test_expect_success 'perf stream, child processes' '
 	test_when_finished "rm trace.perf actual expect" &&
-	GIT_TR2_PERF="$(pwd)/trace.perf" test-tool trace2 004child test-tool trace2 004child test-tool trace2 001return 0 &&
+	GIT_TRACE2_PERF="$(pwd)/trace.perf" test-tool trace2 004child test-tool trace2 004child test-tool trace2 001return 0 &&
 	perl "$TEST_DIRECTORY/t0211/scrub_perf.perl" <trace.perf >actual &&
 	cat >expect <<-EOF &&
 		d0|main|version|||||$V

@@ -150,7 +150,7 @@ test_expect_success 'perf stream, child processes' '
 	test_cmp expect actual
 '
 
-sane_unset GIT_TR2_PERF_BRIEF
+sane_unset GIT_TRACE2_PERF_BRIEF
 
 # Now test without environment variables and get all Trace2 settings
 # from the global config.

index 59adae8123..ff5b9cc729 100755
@@ -4,9 +4,9 @@ test_description='test trace2 facility'
 . ./test-lib.sh
 
 # Turn off any inherited trace2 settings for this test.
-sane_unset GIT_TR2 GIT_TR2_PERF GIT_TR2_EVENT
-sane_unset GIT_TR2_BARE
-sane_unset GIT_TR2_CONFIG_PARAMS
+sane_unset GIT_TRACE2 GIT_TRACE2_PERF GIT_TRACE2_EVENT
+sane_unset GIT_TRACE2_BARE
+sane_unset GIT_TRACE2_CONFIG_PARAMS
 
 perl -MJSON::PP -e 0 >/dev/null 2>&1 && test_set_prereq JSON_PP
 

@@ -29,7 +29,7 @@ V=$(git version | sed -e 's/^git version //') && export V
 # to whatever filtering that target decides to do).
 # Test each target independently.
 #
-# Defer setting GIT_TR2_PERF until the actual command we want to
+# Defer setting GIT_TRACE2_PERF until the actual command we want to
 # test because hidden git and test-tool commands in the test
 # harness can contaminate our output.
 

@@ -42,7 +42,7 @@ V=$(git version | sed -e 's/^git version //') && export V
 
 test_expect_success JSON_PP 'event stream, error event' '
 	test_when_finished "rm trace.event actual expect" &&
-	GIT_TR2_EVENT="$(pwd)/trace.event" test-tool trace2 003error "hello world" "this is a test" &&
+	GIT_TRACE2_EVENT="$(pwd)/trace.event" test-tool trace2 003error "hello world" "this is a test" &&
 	perl "$TEST_DIRECTORY/t0212/parse_events.perl" <trace.event >actual &&
 	sed -e "s/^|//" >expect <<-EOF &&
 	|VAR1 = {

@@ -79,7 +79,7 @@ test_expect_success JSON_PP 'event stream, error event' '
 
 test_expect_success JSON_PP 'event stream, return code 0' '
 	test_when_finished "rm trace.event actual expect" &&
-	GIT_TR2_EVENT="$(pwd)/trace.event" test-tool trace2 004child test-tool trace2 004child test-tool trace2 001return 0 &&
+	GIT_TRACE2_EVENT="$(pwd)/trace.event" test-tool trace2 004child test-tool trace2 004child test-tool trace2 001return 0 &&
 	perl "$TEST_DIRECTORY/t0212/parse_events.perl" <trace.event >actual &&
 	sed -e "s/^|//" >expect <<-EOF &&
 	|VAR1 = {

@@ -168,7 +168,7 @@ test_expect_success JSON_PP 'event stream, list config' '
 	test_when_finished "rm trace.event actual expect" &&
 	git config --local t0212.abc 1 &&
 	git config --local t0212.def "hello world" &&
-	GIT_TR2_EVENT="$(pwd)/trace.event" GIT_TR2_CONFIG_PARAMS="t0212.*" test-tool trace2 001return 0 &&
+	GIT_TRACE2_EVENT="$(pwd)/trace.event" GIT_TRACE2_CONFIG_PARAMS="t0212.*" test-tool trace2 001return 0 &&
 	perl "$TEST_DIRECTORY/t0212/parse_events.perl" <trace.event >actual &&
 	sed -e "s/^|//" >expect <<-EOF &&
 	|VAR1 = {

@@ -201,7 +201,7 @@ test_expect_success JSON_PP 'event stream, list config' '
 
 test_expect_success JSON_PP 'basic trace2_data' '
 	test_when_finished "rm trace.event actual expect" &&
-	GIT_TR2_EVENT="$(pwd)/trace.event" test-tool trace2 006data test_category k1 v1 test_category k2 v2 &&
+	GIT_TRACE2_EVENT="$(pwd)/trace.event" test-tool trace2 006data test_category k1 v1 test_category k2 v2 &&
 	perl "$TEST_DIRECTORY/t0212/parse_events.perl" <trace.event >actual &&
 	sed -e "s/^|//" >expect <<-EOF &&
 	|VAR1 = {

index a2776ba216..6584bb5634 100644
@@ -26,7 +26,7 @@
 
 # The version of the trace2 event target format that we understand.
 # This is reported in the 'version' event in the 'evt' field.
-# It comes from the GIT_TR2_EVENT_VERSION macro in trace2/tr2_tgt_event.c
+# It comes from the GIT_TRACE2_EVENT_VERSION macro in trace2/tr2_tgt_event.c
 my $evt_version = '1';
 
 my $show_children = 1;

index fcf81e3acf..6ddc1e2ca6 100644
@@ -665,21 +665,48 @@ of clones and fetches.
 	Output from `GIT_TRACE2` is a simple text-based format for human
 	readability.
 +
-The `GIT_TRACE2` variables can take many values. Any value available to
-the `GIT_TRACE` variables is also available to `GIT_TRACE2`. The `GIT_TRACE2`
-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_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_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

index 599fd70e14..57f7c30377 100644
@@ -386,7 +386,6 @@ unset VISUAL EMAIL LANGUAGE COLUMNS $("$PERL_PATH" -e '
 	my @env = keys %ENV;
 	my $ok = join("|", qw(
 		TRACE
-		TR2_
 		DEBUG
 		TEST
 		.*_TEST