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

From: SZEDER Gábor <szeder.dev@gmail.com>
Date: May 10, 2019, 21:15 UTC
Message-ID: <20190510211502.GS14763@szeder.dev>
In-Reply-To: <768bdf1c210fd34776f667b080a23eb6f9e17125.1557517464.git.gitgitgadget@gmail.com>

Thanks for the quick turnaround.

On Fri, May 10, 2019 at 12:44:26PM -0700, Derrick Stolee via GitGitGadget wrote:

Show 12 quoted lines

> 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.

Show 40 quoted lines

> 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