@matheusbsbs / matheus-bagliano / commits / 4e0d3aa18a

trace2: document the supported values of GIT_TRACE2* env variables

The descriptions of the GIT_TRACE2* environment variables link to the technical docs for further details on the supported values. However, a link like this only really works if the docs are viewed in a browser and the full documentation is available. OTOH, in 'man git' there are no links to conveniently click on, and distro-shipped git packages tend to include only the man pages, while the technical docs and the docs in html format are in a separate 'git-doc' package. So let's describe the supported values to make the manpage more self-contained, but still keep the references to the technical docs because the details of the SID, and the JSON and perf output formats are definitely beyond the scope of 'man git'. Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

SZEDER Gábor committed May 19, 2019 at 16:43 UTC 4e0d3aa18a60db8bf3448d4fceeed9c8ac8cc597

1 file changed +35 -8

Documentation/git.txt

+35 -8

@@ -665,21 +665,48 @@ of clones and fetches.

665 Output from `GIT_TRACE2` is a simple text-based format for human

666 readability.

667 +

668 -The `GIT_TRACE2` variables can take many values. Any value available to

669 -the `GIT_TRACE` variables is also available to `GIT_TRACE2`. The `GIT_TRACE2`

670 -variables can also specify a Unix Domain Socket. See

671 -link:technical/api-trace2.html[Trace2 documentation] for full details.

668 +If this variable is set to "1", "2" or "true" (comparison

669 +is case insensitive), trace messages will be printed to

670 +stderr.

671 ++

672 +If the variable is set to an integer value greater than 2

673 +and lower than 10 (strictly) then Git will interpret this

674 +value as an open file descriptor and will try to write the

675 +trace messages into this file descriptor.

676 ++

677 +Alternatively, if the variable is set to an absolute path

678 +(starting with a '/' character), Git will interpret this

679 +as a file path and will try to append the trace messages

680 +to it. If the path already exists and is a directory, the

681 +trace messages will be written to files (one per process)

682 +in that directory, named according to the last component

683 +of the SID and an optional counter (to avoid filename

684 +collisions).

685 ++

686 +In addition, if the variable is set to

687 +`af_unix:[<socket_type>:]<absolute-pathname>`, Git will try

688 +to open the path as a Unix Domain Socket. The socket type

689 +can be either `stream` or `dgram`.

690 ++

691 +Unsetting the variable, or setting it to empty, "0" or

692 +"false" (case insensitive) disables trace messages.

693 ++

694 +See link:technical/api-trace2.html[Trace2 documentation]

695 +for full details.

696 +

697

698 `GIT_TRACE2_EVENT`::

699 This setting writes a JSON-based format that is suited for machine

675 - interpretation. See link:technical/api-trace2.html[Trace2 documentation]

676 - for full details.

700 + interpretation.

701 + See `GIT_TRACE2` for available trace output options and

702 + link:technical/api-trace2.html[Trace2 documentation] for full details.

703

704 `GIT_TRACE2_PERF`::

705 In addition to the text-based messages available in `GIT_TRACE2`, this

706 setting writes a column-based format for understanding nesting

681 - regions. See link:technical/api-trace2.html[Trace2 documentation]

682 - for full details.

707 + regions.

708 + See `GIT_TRACE2` for available trace output options and

709 + link:technical/api-trace2.html[Trace2 documentation] for full details.

710

711 `GIT_REDACT_COOKIES`::

712 This can be set to a comma-separated list of strings. When a curl trace