Documentation: talk about pager in api-trace.txt
Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Christian Couder committed
Mar 7, 2016 at 11:38 UTC
3bd1b51d3a3884df186beddaf3a101a5e624f07a
1 file changed
+43
Documentation/technical/api-trace.txt
+43
@@ -95,3 +95,46 @@ for (;;) {
95
}
96
trace_performance(t, "frotz");
97
------------
98
+
99
+Bugs & Caveats
100
+--------------
101
+
102
+GIT_TRACE_* environment variables can be used to tell Git to show
103
+trace output to its standard error stream. Git can often spawn a pager
104
+internally to run its subcommand and send its standard output and
105
+standard error to it.
106
+
107
+Because GIT_TRACE_PERFORMANCE trace is generated only at the very end
108
+of the program with atexit(), which happens after the pager exits, it
109
+would not work well if you send its log to the standard error output
110
+and let Git spawn the pager at the same time.
111
+
112
+As a work around, you can for example use '--no-pager', or set
113
+GIT_TRACE_PERFORMANCE to another file descriptor which is redirected
114
+to stderr, or set GIT_TRACE_PERFORMANCE to a file specified by its
115
+absolute path.
116
+
117
+For example instead of the following command which by default may not
118
+print any performance information:
119
+
120
+------------
121
+GIT_TRACE_PERFORMANCE=2 git log -1
122
+------------
123
+
124
+you may want to use:
125
+
126
+------------
127
+GIT_TRACE_PERFORMANCE=2 git --no-pager log -1
128
+------------
129
+
130
+or:
131
+
132
+------------
133
+GIT_TRACE_PERFORMANCE=3 3>&2 git log -1
134
+------------
135
+
136
+or:
137
+
138
+------------
139
+GIT_TRACE_PERFORMANCE=/path/to/log/file git log -1
140
+------------