git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: "SZEDER Gábor" <szeder.dev@gmail.com>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Derrick Stolee" <dstolee@microsoft.com>,
	git@jeffhostetler.com, git@vger.kernel.org,
	"SZEDER Gábor" <szeder.dev@gmail.com>
Subject: [PATCH 2/2] trace2: document the supported values of GIT_TRACE2* env variables
Date: Sun, 19 May 2019 16:43:09 +0200	[thread overview]
Message-ID: <20190519144309.9597-2-szeder.dev@gmail.com> (raw)
In-Reply-To: <20190519144309.9597-1-szeder.dev@gmail.com>

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>
---
 Documentation/git.txt | 43 +++++++++++++++++++++++++++++++++++--------
 1 file changed, 35 insertions(+), 8 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index fcf81e3acf..6ddc1e2ca6 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -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
-- 
2.22.0.rc1.424.g15834b9bb1


  reply	other threads:[~2019-05-19 17:32 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-05-10 19:44 [PATCH 0/1] trace2: Add variable description to git.txt Derrick Stolee via GitGitGadget
2019-05-10 19:44 ` [PATCH 1/1] " Derrick Stolee via GitGitGadget
2019-05-10 21:15   ` SZEDER Gábor
2019-05-19 14:43     ` [PATCH 1/2] trace2: rename environment variables to GIT_TRACE2* SZEDER Gábor
2019-05-19 14:43       ` SZEDER Gábor [this message]
2019-05-28 16:25       ` Junio C Hamano
2019-05-28 16:46         ` Derrick Stolee
2019-05-29 19:52           ` Jeff Hostetler
2019-05-28 23:02       ` Ævar Arnfjörð Bjarmason
2019-05-29 19:58         ` Jeff Hostetler
2019-05-29 21:45           ` Junio C Hamano
2019-06-12 14:29       ` [PATCH] Revert "test-lib: whitelist GIT_TR2_* in the environment" Ævar Arnfjörð Bjarmason
2019-06-12 17:49         ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190519144309.9597-2-szeder.dev@gmail.com \
    --to=szeder.dev@gmail.com \
    --cc=dstolee@microsoft.com \
    --cc=git@jeffhostetler.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).