;doc: update command help

This commit is contained in:
Simon Michael 2024-03-01 09:13:00 -10:00
parent 7db8e01200
commit afd009db9e
3 changed files with 167 additions and 149 deletions

View File

@ -35,6 +35,7 @@ balance can show..
- or value of balance changes (-V)
- or change of balance values (--valuechange)
- or unrealised capital gain/loss (--gain)
- or balance changes from sibling postings (--related/-r)
- or postings count (--count)
..in..
@ -70,9 +71,6 @@ with output formats txt, csv, tsv (Added in 1.32), json, and
(multi-period reports only:) html. In txt output in a colour-supporting
terminal, negative amounts are shown in red.
The --related/-r flag shows the balance of the other postings in the
transactions of the postings which would normally be shown.
Simple balance report
With no arguments, balance shows a list of all accounts and their change
@ -343,7 +341,9 @@ Multi-period reports with many periods can be too wide for easy viewing
in the terminal. Here are some ways to handle that:
- Hide the totals row with -N/--no-total
- Convert to a single currency with -V
- Filter to a single currency with cur:
- Convert to a single currency with -V [--infer-market-price]
- Use a more compact layout like --layout=bare
- Maximize the terminal window
- Reduce the terminal's font size
- View with a pager like less, eg:
@ -415,13 +415,13 @@ The basic calculation to perform for each table cell. It is one of:
Accumulation type
How amounts should accumulate across report periods. Another way to say
it: which time period's postings should contribute to each cell's
calculation. It is one of:
How amounts should accumulate across a report's subperiods/columns.
Another way to say it: which time period's postings should contribute to
each cell's calculation. It is one of:
- --change : calculate with postings from column start to column end,
ie "just this column". Typically used to see revenues/expenses.
(default for balance, incomestatement)
(default for balance, cashflow, incomestatement)
- --cumulative : calculate with postings from report start to column
end, ie "previous columns plus this column". Typically used to show
@ -431,7 +431,7 @@ calculation. It is one of:
column end, ie "all postings from before report start date until
this column's end". Typically used to see historical end balances of
assets/liabilities/equity. (default for balancesheet,
balancesheetequity, cashflow)
balancesheetequity)
Valuation type
@ -659,35 +659,35 @@ defined in your journal.
Budgeting vs forecasting
--budget and --forecast both use the periodic transaction rules in the
--forecast and --budget both use the periodic transaction rules in the
journal to generate temporary transactions for reporting purposes.
However they are separate features - though you can use both at the same
time if you want. Here are some differences between them:
1. --budget is a command-specific option; it selects the budget report.
-----------------------------------------------------------------------
--forecast --budget
-------------------------------------- --------------------------------
is a general option; it enables is a balance command option; it
forecasting with all reports selects the balance report's
budget mode
--forecast is a general option; forecasting works with all reports.
generates visible transactions which generates invisible transactions
appear in reports which produce goal amounts
2. --budget uses all periodic rules; --budget=DESCPAT uses just the
rules matched by DESCPAT.
generates forecast transactions from generates budget goal
after the last regular transaction, to transactions throughout the
the end of the report period; or with report period, optionally
an argument --forecast=PERIODEXPR restricted by periods specified
generates them throughout the in the periodic transaction
specified period, both optionally rules
restricted by periods specified in the
periodic transaction rules
--forecast uses all periodic rules.
3. --budget's budget goal transactions are invisible, except that they
produce goal amounts.
--forecast's forecast transactions are visible, and appear in
reports.
4. --budget generates budget goal transactions throughout the report
period, optionally restricted by periods specified in the periodic
transaction rules.
--forecast generates forecast transactions from after the last
regular transaction, to the end of the report period; while
--forecast=PERIODEXPR generates them throughout the specified
period; both optionally restricted by periods specified in the
periodic transaction rules.
uses all periodic rules uses all periodic rules; or with
an argument --budget=DESCPAT
uses just the rules matched by
DESCPAT
-----------------------------------------------------------------------
Balance report layout
@ -704,8 +704,8 @@ four possible values:
- --layout=tidy: data is normalised to easily-consumed "tidy" form,
with one row per data value
Here are the --layout modes supported by each output format; note only
CSV output supports all of them:
Here are the --layout modes supported by each output format Only CSV
output supports all of them:
- txt csv html json sql
------ ----- ----- ------ ------ -----
@ -716,115 +716,122 @@ CSV output supports all of them:
Examples:
- Wide layout. With many commodities, reports can be very wide:
Wide layout
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
Balance changes in 2012-01-01..2014-12-31:
With many commodities, reports can be very wide:
|| 2012 2013 2014 Total
==================++====================================================================================================================================================================================================================
Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|| 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
Balance changes in 2012-01-01..2014-12-31:
- Limited wide layout. A width limit reduces the width, but some
commodities will be hidden:
|| 2012 2013 2014 Total
==================++====================================================================================================================================================================================================================
Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|| 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
Balance changes in 2012-01-01..2014-12-31:
A width limit reduces the width, but some commodities will be hidden:
|| 2012 2013 2014 Total
==================++===========================================================================================================================
Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
------------------++---------------------------------------------------------------------------------------------------------------------------
|| 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
Balance changes in 2012-01-01..2014-12-31:
- Tall layout. Each commodity gets a new line (may be different in
each column), and account names are repeated:
|| 2012 2013 2014 Total
==================++===========================================================================================================================
Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
------------------++---------------------------------------------------------------------------------------------------------------------------
|| 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall
Balance changes in 2012-01-01..2014-12-31:
Tall layout
|| 2012 2013 2014 Total
==================++==================================================
Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD
Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
Assets:US:ETrade || 18.00 VHT 294.00 VHT
------------------++--------------------------------------------------
|| 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
|| 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
|| 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD
|| 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
|| 18.00 VHT 294.00 VHT
Each commodity gets a new line (may be different in each column), and
account names are repeated:
- Bare layout. Commodity symbols are kept in one column, each
commodity gets its own report row, account names are repeated:
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall
Balance changes in 2012-01-01..2014-12-31:
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare
Balance changes in 2012-01-01..2014-12-31:
|| 2012 2013 2014 Total
==================++==================================================
Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD
Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
Assets:US:ETrade || 18.00 VHT 294.00 VHT
------------------++--------------------------------------------------
|| 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
|| 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
|| 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD
|| 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
|| 18.00 VHT 294.00 VHT
|| Commodity 2012 2013 2014 Total
==================++=============================================
Assets:US:ETrade || GLD 0 70.00 0 70.00
Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00
Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50
Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00
Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00
------------------++---------------------------------------------
|| GLD 0 70.00 0 70.00
|| ITOT 10.00 18.00 -11.00 17.00
|| USD 337.18 -98.12 4881.44 5120.50
|| VEA 12.00 10.00 14.00 36.00
|| VHT 106.00 18.00 170.00 294.00
Bare layout
- Bare layout also affects CSV output, which is useful for producing
data that is easier to consume, eg for making charts:
Commodity symbols are kept in one column, each commodity has its own
row, amounts are bare numbers, account names are repeated:
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
"account","commodity","balance"
"Assets:US:ETrade","GLD","70.00"
"Assets:US:ETrade","ITOT","17.00"
"Assets:US:ETrade","USD","5120.50"
"Assets:US:ETrade","VEA","36.00"
"Assets:US:ETrade","VHT","294.00"
"total","GLD","70.00"
"total","ITOT","17.00"
"total","USD","5120.50"
"total","VEA","36.00"
"total","VHT","294.00"
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare
Balance changes in 2012-01-01..2014-12-31:
- Note: bare layout will sometimes display an extra row for the
no-symbol commodity, because of zero amounts (hledger treats zeroes
as commodity-less, usually). This can break hledger-bar confusingly
(workaround: add a cur: query to exclude the no-symbol row).
|| Commodity 2012 2013 2014 Total
==================++=============================================
Assets:US:ETrade || GLD 0 70.00 0 70.00
Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00
Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50
Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00
Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00
------------------++---------------------------------------------
|| GLD 0 70.00 0 70.00
|| ITOT 10.00 18.00 -11.00 17.00
|| USD 337.18 -98.12 4881.44 5120.50
|| VEA 12.00 10.00 14.00 36.00
|| VHT 106.00 18.00 170.00 294.00
- Tidy layout produces normalised "tidy data", where every variable
has its own column and each row represents a single data point. See
https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html
for more. This is the easiest kind of data for other software to
consume. Here's how it looks:
Bare layout also affects CSV output, which is useful for producing data
that is easier to consume, eg for making charts:
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
"account","period","start_date","end_date","commodity","value"
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
"account","commodity","balance"
"Assets:US:ETrade","GLD","70.00"
"Assets:US:ETrade","ITOT","17.00"
"Assets:US:ETrade","USD","5120.50"
"Assets:US:ETrade","VEA","36.00"
"Assets:US:ETrade","VHT","294.00"
"total","GLD","70.00"
"total","ITOT","17.00"
"total","USD","5120.50"
"total","VEA","36.00"
"total","VHT","294.00"
Useful balance reports
Bare layout will sometimes display an extra row for the no-symbol
commodity, because of zero amounts (hledger treats zeroes as
commodity-less, usually). This can break hledger-bar confusingly
(workaround: add a cur: query to exclude the no-symbol row).
Tidy layout
This produces normalised "tidy data" (see
https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html)
where every variable has its own column and each row represents a single
data point. This is the easiest kind of data for other software to
consume:
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
"account","period","start_date","end_date","commodity","value"
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
Some useful balance reports
Some frequently used balance options/reports are:

View File

@ -132,6 +132,10 @@ balances in an opening transaction. These provide useful error checking,
but you can ignore them temporarily with -I, or remove them if you
prefer.
Single-commodity, subaccount-exclusive balance assertions (=) are
generated by default. This can be changed with --assertion-type='==*'
(eg).
When running close you should probably avoid using -C, -R, status:
(filtering by status or realness) or --auto (generating postings), since
the generated balance assertions would then require these.

View File

@ -4,34 +4,41 @@ Show journal and performance statistics.
_FLAGS
The stats command displays summary information for the whole journal, or
a matched part of it. With a reporting interval, it shows a report for
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.
At the end, it shows (in the terminal) the overall run time and number
of transactions processed per second. Note these are approximate and
will vary based on machine, current load, data size, hledger version,
haskell lib versions, GHC version.. but they may be of interest. The
stats command's run time is similar to that of a single-column balance
report.
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 run time statistics:
- 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.
The stats command's run time is similar to that of a balance report.
Example:
$ hledger stats -f examples/1000x1000x10.journal
Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal
Included files :
Transactions span : 2000-01-01 to 2002-09-27 (1000 days)
Last transaction : 2002-09-26 (6995 days ago)
Transactions : 1000 (1.0 per day)
Transactions last 30 days: 0 (0.0 per day)
Transactions last 7 days : 0 (0.0 per day)
Payees/descriptions : 1000
Accounts : 1000 (depth 10)
Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)
Market prices : 1000 (A)
Run time : 0.12 s
Throughput : 8342 txns/s
$ hledger stats -f examples/1ktxns-1kaccts.journal
Main file : .../1ktxns-1kaccts.journal
Included files : 0
Txns span : 2000-01-01 to 2002-09-27 (1000 days)
Last txn : 2002-09-26 (7827 days ago)
Txns : 1000 (1.0 per day)
Txns last 30 days : 0 (0.0 per day)
Txns last 7 days : 0 (0.0 per day)
Payees/descriptions : 1000
Accounts : 1000 (depth 10)
Commodities : 26
Market prices : 1000
Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc
This command supports the -o/--output-file option (but not
-O/--output-format selection).
-O/--output-format).