;doc: update CLI usage texts
This commit is contained in:
Simon Michael
parent
a7bb6dc5b5
commit
dbb1441402
@ -24,8 +24,8 @@ Features:
|
||||
- You can also set the initial defaults with command line arguments.
|
||||
- Readline-style edit keys can be used during data entry.
|
||||
- The tab key will auto-complete whenever possible - accounts,
|
||||
descriptions, dates (yesterday, today, tomorrow). If the input area
|
||||
is empty, it will insert the default value.
|
||||
payees/descriptions, dates (yesterday, today, tomorrow). If the
|
||||
input area is empty, it will insert the default value.
|
||||
- If the journal defines a default commodity, it will be added to any
|
||||
bare numbers entered.
|
||||
- A parenthesised transaction code may be entered following a date.
|
||||
|
||||
@ -387,29 +387,21 @@ balances:
|
||||
Balance report types
|
||||
|
||||
The balance command is quite flexible; here is the full detail on how to
|
||||
control what it reports. There are three important option groups:
|
||||
control what it reports. If the following seems complicated, don't
|
||||
worry - this is for advanced reporting, and it does typically take some
|
||||
time and experimentation to get clear on all these report modes.
|
||||
|
||||
There are three important option groups:
|
||||
|
||||
hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...
|
||||
|
||||
The first two are the most important:
|
||||
|
||||
- calculation type selects the basic calculation to perform for each
|
||||
table cell
|
||||
- accumulation type says which postings should be included in each
|
||||
cell's calculation
|
||||
|
||||
Typically one or both of these are selected by default, so you don't
|
||||
need to write them explicitly. Then
|
||||
|
||||
- a valuation type can be added if you want to convert the basic
|
||||
report to value or cost
|
||||
|
||||
Calculation type
|
||||
|
||||
The basic calculation to perform for each table cell. It is one of:
|
||||
|
||||
- --sum : sum the posting amounts (default)
|
||||
- --budget : like --sum but also show a goal amount
|
||||
- --budget : sum the amounts, but also show the budget goal amount
|
||||
(for each account/period)
|
||||
- --valuechange : show the change in period-end historical balance
|
||||
values (caused by deposits, withdrawals, and/or market price
|
||||
fluctuations)
|
||||
@ -418,36 +410,49 @@ The basic calculation to perform for each table cell. It is one of:
|
||||
|
||||
Accumulation type
|
||||
|
||||
Which postings should be included in each cell's calculation. It is one
|
||||
of:
|
||||
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:
|
||||
|
||||
- --change : postings from column start to column end, ie within the
|
||||
cell's period. Typically used to see revenues/expenses. (default for
|
||||
balance, incomestatement)
|
||||
- --change : calculate with postings from column start to column end,
|
||||
ie "just this column". Typically used to see revenues/expenses.
|
||||
(default for balance, incomestatement)
|
||||
|
||||
- --cumulative : postings from report start to column end, eg to show
|
||||
changes accumulated since the report's start date. Rarely used.
|
||||
- --cumulative : calculate with postings from report start to column
|
||||
end, ie "previous columns plus this column". Typically used to show
|
||||
changes accumulated since the report's start date. Not often used.
|
||||
|
||||
- --historical/-H : postings from journal start to column end, ie all
|
||||
postings from account creation to the end of the cell's period.
|
||||
Typically used to see historical end balances of
|
||||
- --historical/-H : calculate with postings from journal start to
|
||||
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)
|
||||
|
||||
Valuation type
|
||||
|
||||
Which kind of valuation, valuation date(s) and optionally a target
|
||||
valuation commodity to use. It is one of:
|
||||
Which kind of value or cost conversion should be applied, if any, before
|
||||
displaying the report. It is one of:
|
||||
|
||||
- no valuation, show amounts in their original commodities (default)
|
||||
- --value=cost[,COMM] : no valuation, show amounts converted to cost
|
||||
- --value=then[,COMM] : show value at transaction dates
|
||||
- --value=end[,COMM] : show value at period end date(s) (default with
|
||||
--valuechange, --gain)
|
||||
- --value=now[,COMM] : show value at today's date
|
||||
- --value=YYYY-MM-DD[,COMM] : show value at another date
|
||||
- no valuation type : don't convert to cost or value (default)
|
||||
- --value=cost[,COMM] : convert amounts to cost (then optionally to
|
||||
some other commodity)
|
||||
- --value=then[,COMM] : convert amounts to market value on transaction
|
||||
dates
|
||||
- --value=end[,COMM] : convert amounts to market value on period end
|
||||
date(s)
|
||||
(default with --valuechange, --gain)
|
||||
- --value=now[,COMM] : convert amounts to market value on today's date
|
||||
- --value=YYYY-MM-DD[,COMM] : convert amounts to market value on
|
||||
another date
|
||||
|
||||
or one of their aliases: --cost/-B, --market/-V or --exchange/-X.
|
||||
or one of the equivalent simpler flags:
|
||||
|
||||
- -B/--cost : like --value=cost (though, note --cost and --value are
|
||||
independent options which can both be used at once)
|
||||
- -V/--market : like --value=end
|
||||
- -X COMM/--exchange COMM : like --value=end,COMM
|
||||
|
||||
See Cost reporting and Valuation for more about these.
|
||||
|
||||
Combining balance report types
|
||||
|
||||
@ -490,8 +495,8 @@ Budget report
|
||||
|
||||
The --budget report type activates extra columns showing any budget
|
||||
goals for each account and period. The budget goals are defined by
|
||||
periodic transactions. This is very useful for comparing planned and
|
||||
actual income, expenses, time usage, etc.
|
||||
periodic transactions. This is useful for comparing planned and actual
|
||||
income, expenses, time usage, etc.
|
||||
|
||||
For example, you can take average monthly expenses in the common expense
|
||||
categories to construct a minimal monthly budget:
|
||||
@ -749,21 +754,21 @@ select from multiple budgets defined in your journal.
|
||||
|
||||
Data layout
|
||||
|
||||
The --layout option affects how balance reports show commodity symbols
|
||||
and multi-commodity amounts, which can improve readability. It can also
|
||||
normalise the data for easy consumption by other programs. It has four
|
||||
possible values:
|
||||
The --layout option affects how balance reports show multi-commodity
|
||||
amounts and commodity symbols, which can improve readability. It can
|
||||
also normalise the data for easy consumption by other programs. It has
|
||||
four possible values:
|
||||
|
||||
- --layout=wide[,WIDTH]: commodities are shown on a single line,
|
||||
possibly elided to the specified width
|
||||
optionally elided to WIDTH
|
||||
- --layout=tall: each commodity is shown on a separate line
|
||||
- --layout=bare: amounts are shown as bare numbers, with commodity
|
||||
symbols in a separate column
|
||||
- --layout=bare: commodity symbols are in their own column, amounts
|
||||
are bare numbers
|
||||
- --layout=tidy: data is normalised to easily-consumed "tidy" form,
|
||||
with one row per data value (works only with CSV output)
|
||||
with one row per data value
|
||||
|
||||
These --layout modes are supported with some but not all of the output
|
||||
formats:
|
||||
Here are the --layout modes supported by each output format; note only
|
||||
CSV output supports all of them:
|
||||
|
||||
- txt csv html json sql
|
||||
------ ----- ----- ------ ------ -----
|
||||
@ -838,7 +843,7 @@ Examples:
|
||||
|| VHT 106.00 18.00 170.00 294.00
|
||||
|
||||
- Bare layout also affects CSV output, which is useful for producing
|
||||
data that is easier to consume, eg when making charts:
|
||||
data that is easier to consume, eg for making charts:
|
||||
|
||||
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
|
||||
"account","commodity","balance"
|
||||
@ -856,10 +861,8 @@ Examples:
|
||||
- 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 kind of output is the easiest to process with other software.
|
||||
Here's how it looks:
|
||||
for more. This is the easiest kind of data for other software to
|
||||
consume. Here's how it looks:
|
||||
|
||||
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
|
||||
"account","period","start_date","end_date","commodity","value"
|
||||
@ -879,12 +882,6 @@ Examples:
|
||||
"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"
|
||||
|
||||
Currently tidy layout is supported only with CSV output.
|
||||
|
||||
In tidy mode, row totals, row averages and column totals are not
|
||||
shown (-T/--row-total and -A/--average flags are disabled and
|
||||
-N/--no-total is enabled).
|
||||
|
||||
Useful balance reports
|
||||
|
||||
Some frequently used balance options/reports are:
|
||||
|
||||
@ -32,5 +32,5 @@ Market prices : 1000 (A)
|
||||
Run time : 0.12 s
|
||||
Throughput : 8342 txns/s
|
||||
|
||||
This command also supports output destination and output format
|
||||
selection.
|
||||
This command supports the -o/--output-file option (but not
|
||||
-O/--output-format selection).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user