[PATCH v2] Documentation: talk about pager in api-trace.txt

[PATCH v2] Documentation: talk about pager in api-trace.txt

[Christian Couder]

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 Documentation/technical/api-trace.txt | 44 +++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/Documentation/technical/api-trace.txt b/Documentation/technical/api-trace.txt
index 097a651..0e1af02 100644
--- a/Documentation/technical/api-trace.txt
+++ b/Documentation/technical/api-trace.txt
@@ -95,3 +95,47 @@ for (;;) {
 }
 trace_performance(t, "frotz");
 ------------
+
+Bugs & Caveats
+--------------
+
+GIT_TRACE_* environment variables can be used to tell Git to show
+trace output to its standard error stream. Git can often spawn a pager
+internally to run its subcommand and send its standard output and
+standard error to it.
+
+Because GIT_TRACE_PERFORMANCE trace is generated only at the very end
+of the program with atexit(), which happens after the pager exits, it
+would not work well if you send its log to the standard error output
+and let Git spawn the pager at the same time.
+
+As a work around, you can for example use '--no-pager', or set
+GIT_TRACE_PERFORMANCE to another file descriptor which is redirected
+to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its
+absolute path.
+
+For example instead of the following command which by default may not
+print any performance information:
+
+------------
+GIT_TRACE_PERFORMANCE=2 git log -1
+------------
+
+you may want to use:
+
+------------
+GIT_TRACE_PERFORMANCE=2 git --no-pager log -1
+------------
+
+or:
+
+------------
+GIT_TRACE_PERFORMANCE=3 3>&2 git log -1
+------------
+
+or:
+
+------------
+GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1
+------------
+
-- 
2.8.0.rc0.1.gd285ab0

Re: [PATCH v2] Documentation: talk about pager in api-trace.txt

[Junio C Hamano]

Christian Couder <christian.couder@gmail.com> writes:

> Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
> ---
>  Documentation/technical/api-trace.txt | 44 +++++++++++++++++++++++++++++++++++
>  1 file changed, 44 insertions(+)

I think this is fine. I'm not sure how many people would look at the
technical/api documentation in such a case, but I don't think it hurts
to document this stuff.

Having re-read this, I have a feeling that this is purely "Caveats",
not "Bugs & Caveats", though.

Will queue, but this will not be so urgent for 2.8.

> diff --git a/Documentation/technical/api-trace.txt b/Documentation/technical/api-trace.txt
> index 097a651..0e1af02 100644
> --- a/Documentation/technical/api-trace.txt
> +++ b/Documentation/technical/api-trace.txt
> @@ -95,3 +95,47 @@ for (;;) {
>  }
>  trace_performance(t, "frotz");
>  ------------
> +
> +Bugs & Caveats
> +--------------
> +
> +GIT_TRACE_* environment variables can be used to tell Git to show
> +trace output to its standard error stream. Git can often spawn a pager
> +internally to run its subcommand and send its standard output and
> +standard error to it.
> +
> +Because GIT_TRACE_PERFORMANCE trace is generated only at the very end
> +of the program with atexit(), which happens after the pager exits, it
> +would not work well if you send its log to the standard error output
> +and let Git spawn the pager at the same time.
> +
> +As a work around, you can for example use '--no-pager', or set
> +GIT_TRACE_PERFORMANCE to another file descriptor which is redirected
> +to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its
> +absolute path.
> +
> +For example instead of the following command which by default may not
> +print any performance information:
> +
> +------------
> +GIT_TRACE_PERFORMANCE=2 git log -1
> +------------
> +
> +you may want to use:
> +
> +------------
> +GIT_TRACE_PERFORMANCE=2 git --no-pager log -1
> +------------
> +
> +or:
> +
> +------------
> +GIT_TRACE_PERFORMANCE=3 3>&2 git log -1
> +------------
> +
> +or:
> +
> +------------
> +GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1
> +------------
> +