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

[Christian Couder <christian.couder@gmail.com>]

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

diff --git a/Documentation/technical/api-trace.txt b/Documentation/technical/api-trace.txt
index 097a651..a10b3a9 100644
--- a/Documentation/technical/api-trace.txt
+++ b/Documentation/technical/api-trace.txt
@@ -95,3 +95,46 @@ for (;;) {
 }
 trace_performance(t, "frotz");
 ------------
+
+Bugs & Caveats
+--------------
+
+Some git commands, like `git log`, are run by default using a
+pager. In this case, stdout and stderr are redirected to the pager and
+are closed when the pager exits.
+
+If a GIT_TRACE* environment variable has been set to "1" or "2" to
+print traces on stderr, no trace output will be printed after the
+pager has exited.
+
+This can be annoying, because GIT_TRACE_PERFORMANCE by default prints
+the performance stats for the whole command at atexit() time which
+happens after the pager has exited.
+
+So the following command will print no performance stat:
+
+------------
+GIT_TRACE_PERFORMANCE=2 git log -1
+------------
+
+To overcome this problem, you can use one of the following
+work-arounds:
+
+  - redirect to another file descriptor which is redirected to stderr,
+    like this:
+
+------------
+GIT_TRACE_PERFORMANCE=3 3>&2 git log -1
+------------
+
+  - redirect to a file specified by its absolute path, like this:
+
+------------
+GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1
+------------
+
+  - use "--no-pager", like this:
+
+------------
+GIT_TRACE_PERFORMANCE=2 git --no-pager log -1
+------------
-- 
2.7.1.289.gf4cc727