Re: [PATCH 1/1] trace2: Add variable description to git.txt

["SZEDER Gábor" <szeder.dev@gmail.com>]

Thanks for the quick turnaround.


On Fri, May 10, 2019 at 12:44:26PM -0700, Derrick Stolee via GitGitGadget wrote:
> From: Derrick Stolee <dstolee@microsoft.com>
> 
> Documentation/technical/api-trace2.txt contains the full details
> of the trace2 API and the GIT_TR2* environment variables. However,
> most environment variables are included in Documentation/git.txt,
> including the GIT_TRACE* variables.
> 
> Add a brief description of the GIT_TR2* variables with links to
> the full technical details. The biggest difference from the
> original variables is that we can specify a Unix Domain Socket.
> Mention this difference, but leave the details to the technical
> documents.

I think that it would be better to spell out the details instead of
linking to the technical docs, because the link will only really work
if you view the docs in a browser and you have the full docs
available.  OTOH, in 'man git' there are no links to conveniently
click on, and the git packages from e.g. Ubuntu only include the man
pages, the technical docs and the docs in html format are in the
separate 'git-doc' package.


> Reported-by: Szeder Gábor <szeder.dev@gmail.com>
> Signed-off-by: Derrick Stolee <dstolee@microsoft.com>
> ---
>  Documentation/git.txt | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 00156d64aa..e802886999 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -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
> -- 
> gitgitgadget