From d5ceb7bba3da124e87c258ef89e0e82554e0fd30 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 19 Nov 2025 22:25:25 -1000 Subject: [PATCH] ;doc: update command docs --- hledger/Hledger/Cli/Commands/Stats.txt | 30 ++++++++++++++++---------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Stats.txt b/hledger/Hledger/Cli/Commands/Stats.txt index a0873ebdd..2ecf43014 100644 --- a/hledger/Hledger/Cli/Commands/Stats.txt +++ b/hledger/Hledger/Cli/Commands/Stats.txt @@ -3,6 +3,7 @@ stats Show journal and performance statistics. Flags: + -1 show a single line of output -v --verbose show more detailed output -o --output-file=FILE write output to FILE. @@ -10,20 +11,24 @@ The stats command shows summary information for the whole journal, or a matched part of it. With a reporting interval, it shows a report for each report period. -The default output is fairly impersonal, though it reveals the main file -name. With -v/--verbose, more details are shown, like file paths, -included files, and commodity names. +It also shows some performance statistics: -It also shows some run time statistics: +- how long the program ran for +- the number of transactions processed per second +- the peak live memory in use by the program to do its work +- the peak allocated memory as seen by the program -- elapsed time -- throughput: the number of transactions processed per second -- live: the peak memory in use by the program to do its work -- alloc: the peak memory allocation from the OS as seen by GHC. - Measuring this externally, eg with GNU time, is more accurate; usually - that will be a larger number; sometimes (with swapping?) smaller. +By default, the output is reasonably discreet; it reveals the main file +name, your activity level, and the speed of your machine. -The stats command's run time is similar to that of a balance report. +With -v/--verbose, more details are shown: the full paths of all files, +and the names of the commodities you work with. + +With -1, only one line of output is shown, in a machine-friendly +tab-separated format: the program version, the main journal file name, +and the performance stats, + +The run time of stats is similar to that of a balance report. Example: @@ -41,5 +46,8 @@ Commodities : 26 Market prices : 1000 Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc +$ hledger stats -1 -f examples/10ktxns-1kaccts.journal +1.50.99-g0835a2485-20251119, mac-aarch64 10ktxns-1kaccts.journal 0.66 s elapsed 15244 txns/s 28 MB live 86 MB alloc + This command supports the -o/--output-file option (but not -O/--output-format).