From 65a00c80b397d626ad215a46b5b9f0cd7940b7c1 Mon Sep 17 00:00:00 2001
From: Fabian Boehm <FHomborg@gmail.com>
Date: Thu, 1 Dec 2022 17:56:57 +0100
Subject: [PATCH] docs: Explain what `time`s output means

---
 doc_src/cmds/time.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/doc_src/cmds/time.rst b/doc_src/cmds/time.rst
index 064f642fc..63e5225c4 100644
--- a/doc_src/cmds/time.rst
+++ b/doc_src/cmds/time.rst
@@ -25,6 +25,31 @@ For checking timing after a command has completed, check :ref:`$CMD_DURATION <va
 
 Your system most likely also has a ``time`` command. To use that use something like ``command time``, as in ``command time sleep 10``. Because it's not inside fish, it won't have access to fish functions and won't be able to time blocks and such.
 
+How to interpret the output
+---------------------------
+
+Time outputs a few different values. Let's look at an example::
+
+  > time string repeat -n 10000000 y\n | command grep y >/dev/null
+  ________________________________________________________
+  Executed in  805.98 millis    fish           external
+     usr time  798.88 millis  763.88 millis   34.99 millis
+     sys time  141.22 millis   40.20 millis  101.02 millis
+
+The time after "Executed in" is what is known as the "wall-clock time". It is simply a measure of how long it took from the start of the command until it finished. Typically it is reasonably close to :envvar:`CMD_DURATION`, except for a slight skew because the two are taken at slightly different times.
+
+The other times are all measures of CPU time. That means they measure how long the CPU was used in this part, and they count multiple cores separately. So a program with four threads using all CPU for a second will have a time of 4 seconds.
+
+The "usr" time is how much CPU time was spent inside the program itself, the "sys" time is how long was spent in the kernel on behalf of that program.
+
+The "fish" time is how much CPU was spent in fish, the "external" time how much was spent in external commands.
+
+So in this example, since ``string`` is a builtin, everything that ``string repeat`` did is accounted to fish. Any time it spends doing syscalls like ``write()`` is accounted for in the fish/sys time.
+
+And ``grep`` here is explicitly invoked as an external command, so its times will be counted in the "external" column.
+
+Note that, as in this example, the CPU times can add up to more than the execution time. This is because things can be done in parallel - ``grep`` can match while ``string repeat`` writes.
+
 Example
 -------