;doc: update CLI usage texts
This commit is contained in:
Simon Michael
parent
2ba91b1195
commit
cf607adfcf
@ -73,9 +73,12 @@ Simple balance report
|
|||||||
|
|
||||||
With no arguments, balance shows a list of all accounts and their change
|
With no arguments, balance shows a list of all accounts and their change
|
||||||
of balance - ie, the sum of posting amounts, both inflows and outflows -
|
of balance - ie, the sum of posting amounts, both inflows and outflows -
|
||||||
during the entire period of the journal. For real-world accounts, this
|
during the entire period of the journal. ("Simple" here means just one
|
||||||
should also match their end balance at the end of the journal period
|
column of numbers, covering a single period. You can also have
|
||||||
(more on this below).
|
multi-period reports, described later.)
|
||||||
|
|
||||||
|
For real-world accounts, these numbers will normally be their end
|
||||||
|
balance at the end of the journal period; more on this below.
|
||||||
|
|
||||||
Accounts are sorted by declaration order if any, and then alphabetically
|
Accounts are sorted by declaration order if any, and then alphabetically
|
||||||
by account name. For instance (using examples/sample.journal):
|
by account name. For instance (using examples/sample.journal):
|
||||||
@ -91,8 +94,8 @@ $ hledger -f examples/sample.journal bal
|
|||||||
--------------------
|
--------------------
|
||||||
0
|
0
|
||||||
|
|
||||||
Accounts with a zero balance (and no non-zero subaccounts, in tree mode
|
Accounts with a zero balance (and no non-zero subaccounts, in tree
|
||||||
- see below) are hidden by default. Use -E/--empty to show them
|
mode - see below) are hidden by default. Use -E/--empty to show them
|
||||||
(revealing assets:bank:checking here):
|
(revealing assets:bank:checking here):
|
||||||
|
|
||||||
$ hledger -f examples/sample.journal bal -E
|
$ hledger -f examples/sample.journal bal -E
|
||||||
@ -110,6 +113,65 @@ $ hledger -f examples/sample.journal bal -E
|
|||||||
The total of the amounts displayed is shown as the last line, unless
|
The total of the amounts displayed is shown as the last line, unless
|
||||||
-N/--no-total is used.
|
-N/--no-total is used.
|
||||||
|
|
||||||
|
Balance report line format
|
||||||
|
|
||||||
|
For single-period balance reports displayed in the terminal (only), you
|
||||||
|
can use --format FMT to customise the format and content of each line.
|
||||||
|
Eg:
|
||||||
|
|
||||||
|
$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
|
||||||
|
assets $-1
|
||||||
|
bank:saving $1
|
||||||
|
cash $-2
|
||||||
|
expenses $2
|
||||||
|
food $1
|
||||||
|
supplies $1
|
||||||
|
income $-2
|
||||||
|
gifts $-1
|
||||||
|
salary $-1
|
||||||
|
liabilities:debts $1
|
||||||
|
---------------------------------
|
||||||
|
0
|
||||||
|
|
||||||
|
The FMT format string specifies the formatting applied to each
|
||||||
|
account/balance pair. It may contain any suitable text, with data fields
|
||||||
|
interpolated like so:
|
||||||
|
|
||||||
|
%[MIN][.MAX](FIELDNAME)
|
||||||
|
|
||||||
|
- MIN pads with spaces to at least this width (optional)
|
||||||
|
|
||||||
|
- MAX truncates at this width (optional)
|
||||||
|
|
||||||
|
- FIELDNAME must be enclosed in parentheses, and can be one of:
|
||||||
|
|
||||||
|
- depth_spacer - a number of spaces equal to the account's depth,
|
||||||
|
or if MIN is specified, MIN * depth spaces.
|
||||||
|
- account - the account's name
|
||||||
|
- total - the account's balance/posted total, right justified
|
||||||
|
|
||||||
|
Also, FMT can begin with an optional prefix to control how
|
||||||
|
multi-commodity amounts are rendered:
|
||||||
|
|
||||||
|
- %_ - render on multiple lines, bottom-aligned (the default)
|
||||||
|
- %^ - render on multiple lines, top-aligned
|
||||||
|
- %, - render on one line, comma-separated
|
||||||
|
|
||||||
|
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
|
||||||
|
effect, instead %(account) has indentation built in. Experimentation may
|
||||||
|
be needed to get pleasing results.
|
||||||
|
|
||||||
|
Some example formats:
|
||||||
|
|
||||||
|
- %(total) - the account's total
|
||||||
|
- %-20.20(account) - the account's name, left justified, padded to 20
|
||||||
|
characters and clipped at 20 characters
|
||||||
|
- %,%-50(account) %25(total) - account name padded to 50 characters,
|
||||||
|
total padded to 20 characters, with multiple commodities rendered on
|
||||||
|
one line
|
||||||
|
- %20(total) %2(depth_spacer)%-(account) - the default format for the
|
||||||
|
single-column balance report
|
||||||
|
|
||||||
Filtered balance report
|
Filtered balance report
|
||||||
|
|
||||||
You can show fewer accounts, a different time period, totals from
|
You can show fewer accounts, a different time period, totals from
|
||||||
@ -190,6 +252,53 @@ $ hledger -f examples/sample.journal bal expenses --drop 1
|
|||||||
--------------------
|
--------------------
|
||||||
$2
|
$2
|
||||||
|
|
||||||
|
Showing declared accounts
|
||||||
|
|
||||||
|
With --declared, accounts which have been declared with an account
|
||||||
|
directive will be included in the balance report, even if they have no
|
||||||
|
transactions. (Since they will have a zero balance, you will also need
|
||||||
|
-E/--empty to see them.)
|
||||||
|
|
||||||
|
More precisely, leaf declared accounts (with no subaccounts) will be
|
||||||
|
included, since those are usually the more useful in reports.
|
||||||
|
|
||||||
|
The idea of this is to be able to see a useful "complete" balance
|
||||||
|
report, even when you don't have transactions in all of your declared
|
||||||
|
accounts yet.
|
||||||
|
|
||||||
|
Sorting by amount
|
||||||
|
|
||||||
|
With -S/--sort-amount, accounts with the largest (most positive)
|
||||||
|
balances are shown first. Eg: hledger bal expenses -MAS shows your
|
||||||
|
biggest averaged monthly expenses first. When more than one commodity is
|
||||||
|
present, they will be sorted by the alphabetically earliest commodity
|
||||||
|
first, and then by subsequent commodities (if an amount is missing a
|
||||||
|
commodity, it is treated as 0).
|
||||||
|
|
||||||
|
Revenues and liability balances are typically negative, however, so -S
|
||||||
|
shows these in reverse order. To work around this, you can add --invert
|
||||||
|
to flip the signs. (Or, use one of the higher-level reports, which flip
|
||||||
|
the sign automatically. Eg: hledger incomestatement -MAS).
|
||||||
|
|
||||||
|
Percentages
|
||||||
|
|
||||||
|
With -%/--percent, balance reports show each account's value expressed
|
||||||
|
as a percentage of the (column) total.
|
||||||
|
|
||||||
|
Note it is not useful to calculate percentages if the amounts in a
|
||||||
|
column have mixed signs. In this case, make a separate report for each
|
||||||
|
sign, eg:
|
||||||
|
|
||||||
|
$ hledger bal -% amt:`>0`
|
||||||
|
$ hledger bal -% amt:`<0`
|
||||||
|
|
||||||
|
Similarly, if the amounts in a column have mixed commodities, convert
|
||||||
|
them to one commodity with -B, -V, -X or --value, or make a separate
|
||||||
|
report for each commodity:
|
||||||
|
|
||||||
|
$ hledger bal -% cur:\\$
|
||||||
|
$ hledger bal -% cur:€
|
||||||
|
|
||||||
Multi-period balance report
|
Multi-period balance report
|
||||||
|
|
||||||
With a report interval (set by the -D/--daily, -W/--weekly,
|
With a report interval (set by the -D/--daily, -W/--weekly,
|
||||||
@ -242,193 +351,6 @@ in the terminal. Here are some ways to handle that:
|
|||||||
- Output as HTML and view with a browser:
|
- Output as HTML and view with a browser:
|
||||||
hledger bal -D -o a.html && open a.html
|
hledger bal -D -o a.html && open a.html
|
||||||
|
|
||||||
Showing declared accounts
|
|
||||||
|
|
||||||
With --declared, accounts which have been declared with an account
|
|
||||||
directive will be included in the balance report, even if they have no
|
|
||||||
transactions. (Since they will have a zero balance, you will also need
|
|
||||||
-E/--empty to see them.)
|
|
||||||
|
|
||||||
More precisely, leaf declared accounts (with no subaccounts) will be
|
|
||||||
included, since those are usually the more useful in reports.
|
|
||||||
|
|
||||||
The idea of this is to be able to see a useful "complete" balance
|
|
||||||
report, even when you don't have transactions in all of your declared
|
|
||||||
accounts yet.
|
|
||||||
|
|
||||||
Data layout
|
|
||||||
|
|
||||||
The --layout option affects how multi-commodity amounts are displayed,
|
|
||||||
and some other things, influencing the overall layout of the report
|
|
||||||
data:
|
|
||||||
|
|
||||||
- --layout=wide[,WIDTH]: commodities are shown on a single line,
|
|
||||||
possibly elided to the specified 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=tidy: data is normalised to tidy form, with one row per
|
|
||||||
data value. We currently support this with CSV output only. In tidy
|
|
||||||
mode, totals and row averages are disabled (-N/--no-total is implied
|
|
||||||
and -T/--row-total and -A/--average will be ignored).
|
|
||||||
|
|
||||||
These --layout modes are supported with some but not all of the output
|
|
||||||
formats:
|
|
||||||
|
|
||||||
- txt csv html json sql
|
|
||||||
------ ----- ----- ------ ------ -----
|
|
||||||
wide Y Y Y
|
|
||||||
tall Y Y Y
|
|
||||||
bare Y Y Y
|
|
||||||
tidy Y
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
- Wide layout. With many commodities, reports can be very wide:
|
|
||||||
|
|
||||||
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
|
|
||||||
Balance changes in 2012-01-01..2014-12-31:
|
|
||||||
|
|
||||||
|| 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
|
|
||||||
|
|
||||||
- Limited wide layout. A width limit reduces the width, but some
|
|
||||||
commodities will be hidden:
|
|
||||||
|
|
||||||
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
|
|
||||||
Balance changes in 2012-01-01..2014-12-31:
|
|
||||||
|
|
||||||
|| 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..
|
|
||||||
|
|
||||||
- Tall layout. Each commodity gets a new line (may be different in
|
|
||||||
each column), and 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:
|
|
||||||
|
|
||||||
|| 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
|
|
||||||
|
|
||||||
- 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=bare
|
|
||||||
Balance changes in 2012-01-01..2014-12-31:
|
|
||||||
|
|
||||||
|| 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 also affects CSV output, which is useful for producing
|
|
||||||
data that is easier to consume, eg when making charts:
|
|
||||||
|
|
||||||
$ 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"
|
|
||||||
|
|
||||||
- Tidy layout produces normalised "tidy data", where every variable is
|
|
||||||
a column and each row represents a single data point (see
|
|
||||||
https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html).
|
|
||||||
This kind of data is the easiest to process with other software:
|
|
||||||
|
|
||||||
$ 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"
|
|
||||||
|
|
||||||
Sorting by amount
|
|
||||||
|
|
||||||
With -S/--sort-amount, accounts with the largest (most positive)
|
|
||||||
balances are shown first. Eg: hledger bal expenses -MAS shows your
|
|
||||||
biggest averaged monthly expenses first. When more than one commodity is
|
|
||||||
present, they will be sorted by the alphabetically earliest commodity
|
|
||||||
first, and then by subsequent commodities (if an amount is missing a
|
|
||||||
commodity, it is treated as 0).
|
|
||||||
|
|
||||||
Revenues and liability balances are typically negative, however, so -S
|
|
||||||
shows these in reverse order. To work around this, you can add --invert
|
|
||||||
to flip the signs. (Or, use one of the higher-level reports, which flip
|
|
||||||
the sign automatically. Eg: hledger incomestatement -MAS).
|
|
||||||
|
|
||||||
Percentages
|
|
||||||
|
|
||||||
With -%/--percent, balance reports show each account's value expressed
|
|
||||||
as a percentage of the (column) total:
|
|
||||||
|
|
||||||
$ hledger -f examples/sample.journal bal expenses -Q -%
|
|
||||||
Balance changes in 2008:
|
|
||||||
|
|
||||||
|| 2008Q1 2008Q2 2008Q3 2008Q4
|
|
||||||
===================++=================================
|
|
||||||
expenses:food || 0 50.0 % 0 0
|
|
||||||
expenses:supplies || 0 50.0 % 0 0
|
|
||||||
-------------------++---------------------------------
|
|
||||||
|| 0 100.0 % 0 0
|
|
||||||
|
|
||||||
Note it is not useful to calculate percentages if the amounts in a
|
|
||||||
column have mixed signs. In this case, make a separate report for each
|
|
||||||
sign, eg:
|
|
||||||
|
|
||||||
$ hledger bal -% amt:`>0`
|
|
||||||
$ hledger bal -% amt:`<0`
|
|
||||||
|
|
||||||
Similarly, if the amounts in a column have mixed commodities, convert
|
|
||||||
them to one commodity with -B, -V, -X or --value, or make a separate
|
|
||||||
report for each commodity:
|
|
||||||
|
|
||||||
$ hledger bal -% cur:\\$
|
|
||||||
$ hledger bal -% cur:€
|
|
||||||
|
|
||||||
Balance change, end balance
|
Balance change, end balance
|
||||||
|
|
||||||
It's important to be clear on the meaning of the numbers shown in
|
It's important to be clear on the meaning of the numbers shown in
|
||||||
@ -464,18 +386,26 @@ balances:
|
|||||||
|
|
||||||
Balance report types
|
Balance report types
|
||||||
|
|
||||||
For more flexible reporting, there are three important option groups:
|
The balance command is quite flexible; here is the full detail on how to
|
||||||
|
control what it reports. There are three important option groups:
|
||||||
|
|
||||||
hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...
|
hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...
|
||||||
|
|
||||||
The first two are the most important: calculation type selects the basic
|
The first two are the most important:
|
||||||
calculation to perform for each table cell, while accumulation type says
|
|
||||||
which postings should be included in each cell's calculation. Typically
|
- calculation type selects the basic calculation to perform for each
|
||||||
one or both of these are selected by default, so you don't need to write
|
table cell
|
||||||
them explicitly. A valuation type can be added if you want to convert
|
- accumulation type says which postings should be included in each
|
||||||
the basic report to value or cost.
|
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
|
||||||
|
|
||||||
Calculation type:
|
|
||||||
The basic calculation to perform for each table cell. It is one of:
|
The basic calculation to perform for each table cell. It is one of:
|
||||||
|
|
||||||
- --sum : sum the posting amounts (default)
|
- --sum : sum the posting amounts (default)
|
||||||
@ -486,7 +416,8 @@ The basic calculation to perform for each table cell. It is one of:
|
|||||||
- --gain : show the unrealised capital gain/loss, (the current valued
|
- --gain : show the unrealised capital gain/loss, (the current valued
|
||||||
balance minus each amount's original cost)
|
balance minus each amount's original cost)
|
||||||
|
|
||||||
Accumulation type:
|
Accumulation type
|
||||||
|
|
||||||
Which postings should be included in each cell's calculation. It is one
|
Which postings should be included in each cell's calculation. It is one
|
||||||
of:
|
of:
|
||||||
|
|
||||||
@ -503,7 +434,8 @@ of:
|
|||||||
assets/liabilities/equity. (default for balancesheet,
|
assets/liabilities/equity. (default for balancesheet,
|
||||||
balancesheetequity, cashflow)
|
balancesheetequity, cashflow)
|
||||||
|
|
||||||
Valuation type:
|
Valuation type
|
||||||
|
|
||||||
Which kind of valuation, valuation date(s) and optionally a target
|
Which kind of valuation, valuation date(s) and optionally a target
|
||||||
valuation commodity to use. It is one of:
|
valuation commodity to use. It is one of:
|
||||||
|
|
||||||
@ -517,6 +449,8 @@ valuation commodity to use. It is one of:
|
|||||||
|
|
||||||
or one of their aliases: --cost/-B, --market/-V or --exchange/-X.
|
or one of their aliases: --cost/-B, --market/-V or --exchange/-X.
|
||||||
|
|
||||||
|
Combining balance report types
|
||||||
|
|
||||||
Most combinations of these options should produce reasonable reports,
|
Most combinations of these options should produce reasonable reports,
|
||||||
but if you find any that seem wrong or misleading, let us know. The
|
but if you find any that seem wrong or misleading, let us know. The
|
||||||
following restrictions are applied:
|
following restrictions are applied:
|
||||||
@ -530,8 +464,8 @@ For reference, here is what the combinations of accumulation and
|
|||||||
valuation show:
|
valuation show:
|
||||||
|
|
||||||
------------------------------------------------------------------------------------------------
|
------------------------------------------------------------------------------------------------
|
||||||
Valuation: no valuation --value= then --value= end --value= YYYY-MM-DD /now
|
Valuation:> no valuation --value= then --value= end --value= YYYY-MM-DD /now
|
||||||
>Accumulation: v
|
Accumulation:v
|
||||||
------------------ ---------------- ----------------- --------------- --------------------------
|
------------------ ---------------- ----------------- --------------- --------------------------
|
||||||
--change change in period sum of period-end DATE-value of change in
|
--change change in period sum of period-end DATE-value of change in
|
||||||
posting-date value of change period
|
posting-date value of change period
|
||||||
@ -552,41 +486,6 @@ valuation show:
|
|||||||
end
|
end
|
||||||
------------------------------------------------------------------------------------------------
|
------------------------------------------------------------------------------------------------
|
||||||
|
|
||||||
Useful balance reports
|
|
||||||
|
|
||||||
Some frequently used balance options/reports are:
|
|
||||||
|
|
||||||
- bal -M revenues expenses
|
|
||||||
Show revenues/expenses in each month. Also available as the
|
|
||||||
incomestatement command.
|
|
||||||
|
|
||||||
- bal -M -H assets liabilities
|
|
||||||
Show historical asset/liability balances at each month end. Also
|
|
||||||
available as the balancesheet command.
|
|
||||||
|
|
||||||
- bal -M -H assets liabilities equity
|
|
||||||
Show historical asset/liability/equity balances at each month end.
|
|
||||||
Also available as the balancesheetequity command.
|
|
||||||
|
|
||||||
- bal -M assets not:receivable
|
|
||||||
Show changes to liquid assets in each month. Also available as the
|
|
||||||
cashflow command.
|
|
||||||
|
|
||||||
Also:
|
|
||||||
|
|
||||||
- bal -M expenses -2 -SA
|
|
||||||
Show monthly expenses summarised to depth 2 and sorted by average
|
|
||||||
amount.
|
|
||||||
|
|
||||||
- bal -M --budget expenses
|
|
||||||
Show monthly expenses and budget goals.
|
|
||||||
|
|
||||||
- bal -M --valuechange investments
|
|
||||||
Show monthly change in market value of investment assets.
|
|
||||||
|
|
||||||
- bal investments --valuechange -D date:lastweek amt:'>1000' -STA [--invert]
|
|
||||||
Show top gainers [or losers] last week
|
|
||||||
|
|
||||||
Budget report
|
Budget report
|
||||||
|
|
||||||
The --budget report type activates extra columns showing any budget
|
The --budget report type activates extra columns showing any budget
|
||||||
@ -848,61 +747,175 @@ regular expression or query). This means you can give your periodic
|
|||||||
rules descriptions (remember that two spaces are needed), and then
|
rules descriptions (remember that two spaces are needed), and then
|
||||||
select from multiple budgets defined in your journal.
|
select from multiple budgets defined in your journal.
|
||||||
|
|
||||||
Customising single-period balance reports
|
Data layout
|
||||||
|
|
||||||
For single-period balance reports displayed in the terminal (only), you
|
The --layout option affects how balance reports show commodity symbols
|
||||||
can use --format FMT to customise the format and content of each line.
|
and multi-commodity amounts, which can improve readability. It can also
|
||||||
Eg:
|
normalise the data for easy consumption by other programs. It has four
|
||||||
|
possible values:
|
||||||
|
|
||||||
$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
|
- --layout=wide[,WIDTH]: commodities are shown on a single line,
|
||||||
assets $-1
|
possibly elided to the specified width
|
||||||
bank:saving $1
|
- --layout=tall: each commodity is shown on a separate line
|
||||||
cash $-2
|
- --layout=bare: amounts are shown as bare numbers, with commodity
|
||||||
expenses $2
|
symbols in a separate column
|
||||||
food $1
|
- --layout=tidy: data is normalised to easily-consumed "tidy" form,
|
||||||
supplies $1
|
with one row per data value (works only with CSV output)
|
||||||
income $-2
|
|
||||||
gifts $-1
|
|
||||||
salary $-1
|
|
||||||
liabilities:debts $1
|
|
||||||
---------------------------------
|
|
||||||
0
|
|
||||||
|
|
||||||
The FMT format string (plus a newline) specifies the formatting applied
|
These --layout modes are supported with some but not all of the output
|
||||||
to each account/balance pair. It may contain any suitable text, with
|
formats:
|
||||||
data fields interpolated like so:
|
|
||||||
|
|
||||||
%[MIN][.MAX](FIELDNAME)
|
- txt csv html json sql
|
||||||
|
------ ----- ----- ------ ------ -----
|
||||||
|
wide Y Y Y
|
||||||
|
tall Y Y Y
|
||||||
|
bare Y Y Y
|
||||||
|
tidy Y
|
||||||
|
|
||||||
- MIN pads with spaces to at least this width (optional)
|
Examples:
|
||||||
|
|
||||||
- MAX truncates at this width (optional)
|
- Wide layout. With many commodities, reports can be very wide:
|
||||||
|
|
||||||
- FIELDNAME must be enclosed in parentheses, and can be one of:
|
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
|
||||||
|
Balance changes in 2012-01-01..2014-12-31:
|
||||||
|
|
||||||
- depth_spacer - a number of spaces equal to the account's depth,
|
|| 2012 2013 2014 Total
|
||||||
or if MIN is specified, MIN * depth spaces.
|
==================++====================================================================================================================================================================================================================
|
||||||
- account - the account's name
|
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
|
||||||
- total - the account's balance/posted total, right justified
|
------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
||||||
|
|| 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
|
||||||
|
|
||||||
Also, FMT can begin with an optional prefix to control how
|
- Limited wide layout. A width limit reduces the width, but some
|
||||||
multi-commodity amounts are rendered:
|
commodities will be hidden:
|
||||||
|
|
||||||
- %_ - render on multiple lines, bottom-aligned (the default)
|
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
|
||||||
- %^ - render on multiple lines, top-aligned
|
Balance changes in 2012-01-01..2014-12-31:
|
||||||
- %, - render on one line, comma-separated
|
|
||||||
|
|
||||||
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
|
|| 2012 2013 2014 Total
|
||||||
effect, instead %(account) has indentation built in. Experimentation may
|
==================++===========================================================================================================================
|
||||||
be needed to get pleasing results.
|
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..
|
||||||
|
|
||||||
Some example formats:
|
- Tall layout. Each commodity gets a new line (may be different in
|
||||||
|
each column), and account names are repeated:
|
||||||
|
|
||||||
- %(total) - the account's total
|
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall
|
||||||
- %-20.20(account) - the account's name, left justified, padded to 20
|
Balance changes in 2012-01-01..2014-12-31:
|
||||||
characters and clipped at 20 characters
|
|
||||||
- %,%-50(account) %25(total) - account name padded to 50 characters,
|
|| 2012 2013 2014 Total
|
||||||
total padded to 20 characters, with multiple commodities rendered on
|
==================++==================================================
|
||||||
one line
|
Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
|
||||||
- %20(total) %2(depth_spacer)%-(account) - the default format for the
|
Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
|
||||||
single-column balance report
|
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
|
||||||
|
|
||||||
|
- 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=bare
|
||||||
|
Balance changes in 2012-01-01..2014-12-31:
|
||||||
|
|
||||||
|
|| 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 also affects CSV output, which is useful for producing
|
||||||
|
data that is easier to consume, eg when making charts:
|
||||||
|
|
||||||
|
$ 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"
|
||||||
|
|
||||||
|
- 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:
|
||||||
|
|
||||||
|
$ 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"
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
- bal -M revenues expenses
|
||||||
|
Show revenues/expenses in each month. Also available as the
|
||||||
|
incomestatement command.
|
||||||
|
|
||||||
|
- bal -M -H assets liabilities
|
||||||
|
Show historical asset/liability balances at each month end. Also
|
||||||
|
available as the balancesheet command.
|
||||||
|
|
||||||
|
- bal -M -H assets liabilities equity
|
||||||
|
Show historical asset/liability/equity balances at each month end.
|
||||||
|
Also available as the balancesheetequity command.
|
||||||
|
|
||||||
|
- bal -M assets not:receivable
|
||||||
|
Show changes to liquid assets in each month. Also available as the
|
||||||
|
cashflow command.
|
||||||
|
|
||||||
|
Also:
|
||||||
|
|
||||||
|
- bal -M expenses -2 -SA
|
||||||
|
Show monthly expenses summarised to depth 2 and sorted by average
|
||||||
|
amount.
|
||||||
|
|
||||||
|
- bal -M --budget expenses
|
||||||
|
Show monthly expenses and budget goals.
|
||||||
|
|
||||||
|
- bal -M --valuechange investments
|
||||||
|
Show monthly change in market value of investment assets.
|
||||||
|
|
||||||
|
- bal investments --valuechange -D date:lastweek amt:'>1000' -STA [--invert]
|
||||||
|
Show top gainers [or losers] last week
|
||||||
|
|||||||
@ -30,8 +30,7 @@ commands, including check:
|
|||||||
|
|
||||||
- balancedwithautoconversion - all transactions are balanced,
|
- balancedwithautoconversion - all transactions are balanced,
|
||||||
inferring missing amounts where necessary, and possibly converting
|
inferring missing amounts where necessary, and possibly converting
|
||||||
commodities using transaction prices or automatically-inferred
|
commodities using costs or automatically-inferred costs
|
||||||
transaction prices
|
|
||||||
|
|
||||||
- assertions - all balance assertions in the journal are passing.
|
- assertions - all balance assertions in the journal are passing.
|
||||||
(This check can be disabled with -I/--ignore-assertions.)
|
(This check can be disabled with -I/--ignore-assertions.)
|
||||||
@ -47,7 +46,7 @@ check:
|
|||||||
- commodities - all commodity symbols used have been declared
|
- commodities - all commodity symbols used have been declared
|
||||||
|
|
||||||
- balancednoautoconversion - transactions are balanced, possibly using
|
- balancednoautoconversion - transactions are balanced, possibly using
|
||||||
explicit transaction prices but not inferred ones
|
explicit costs but not inferred ones
|
||||||
|
|
||||||
Other checks
|
Other checks
|
||||||
|
|
||||||
|
|||||||
@ -38,14 +38,14 @@ separate equity posting for each commodity (as in the print command).
|
|||||||
With --interleaved, each equity posting is shown next to the posting it
|
With --interleaved, each equity posting is shown next to the posting it
|
||||||
balances (good for troubleshooting).
|
balances (good for troubleshooting).
|
||||||
|
|
||||||
close and prices
|
close and costs
|
||||||
|
|
||||||
Transaction prices are ignored (and discarded) by closing/opening
|
Costs are ignored (and discarded) by closing/opening transactions, by
|
||||||
transactions, by default. With --show-costs, they are preserved; there
|
default. With --show-costs, they are preserved; there will be a separate
|
||||||
will be a separate equity posting for each cost in each commodity. This
|
equity posting for each cost in each commodity. This means balance -B
|
||||||
means balance -B reports will look the same after the transition. Note
|
reports will look the same after the transition. Note if you have many
|
||||||
if you have many foreign currency or investment transactions, this will
|
foreign currency or investment transactions, this will generate very
|
||||||
generate very large journal entries.
|
large journal entries.
|
||||||
|
|
||||||
close date
|
close date
|
||||||
|
|
||||||
@ -59,12 +59,18 @@ closing date. The opening date is always the following day. So to close
|
|||||||
on (end of) 2020-12-31 and open on (start of) 2021-01-01, any of these
|
on (end of) 2020-12-31 and open on (start of) 2021-01-01, any of these
|
||||||
will work:
|
will work:
|
||||||
|
|
||||||
end date argument explanation
|
-----------------------------------------------------------------------
|
||||||
------------------- ------------------------------------------------
|
end date explanation
|
||||||
-e 2021-01-01 end dates are exclusive
|
argument
|
||||||
-e 2021 equivalent, per smart dates
|
--------------- -------------------------------------------------------
|
||||||
-p 2020 equivalent, the period's begin date is ignored
|
-e 2021-01-01 end dates are exclusive
|
||||||
date:2020 equivalent query
|
|
||||||
|
-e 2021 equivalent, per smart dates
|
||||||
|
|
||||||
|
-p 2020 equivalent, the period's begin date is ignored
|
||||||
|
|
||||||
|
date:2020 equivalent query
|
||||||
|
-----------------------------------------------------------------------
|
||||||
|
|
||||||
Example: close asset/liability accounts for file transition
|
Example: close asset/liability accounts for file transition
|
||||||
|
|
||||||
|
|||||||
@ -16,17 +16,21 @@ You can add a query to select a subset of transactions.
|
|||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
|
|
||||||
1/1 (123)
|
2022/1/1 (123) Supermarket
|
||||||
(a) 1
|
Food $5.00
|
||||||
|
Checking
|
||||||
|
|
||||||
1/1 ()
|
2022/1/2 (124) Post Office
|
||||||
(a) 1
|
Postage $8.32
|
||||||
|
Checking
|
||||||
|
|
||||||
1/1
|
2022/1/3 Supermarket
|
||||||
(a) 1
|
Food $11.23
|
||||||
|
Checking
|
||||||
|
|
||||||
1/1 (126)
|
2022/1/4 (126) Post Office
|
||||||
(a) 1
|
Postage $3.21
|
||||||
|
Checking
|
||||||
|
|
||||||
$ hledger codes
|
$ hledger codes
|
||||||
123
|
123
|
||||||
@ -37,5 +41,4 @@ $ hledger codes -E
|
|||||||
123
|
123
|
||||||
124
|
124
|
||||||
|
|
||||||
|
|
||||||
126
|
126
|
||||||
|
|||||||
@ -1,9 +1,8 @@
|
|||||||
prices
|
prices
|
||||||
Print market price directives from the journal. With
|
Print market price directives from the journal. With
|
||||||
--infer-market-prices, generate additional market prices from
|
--infer-market-prices, generate additional market prices from costs.
|
||||||
transaction prices. With --infer-reverse-prices, also generate market
|
With --infer-reverse-prices, also generate market prices by inverting
|
||||||
prices by inverting transaction prices. Prices (and postings providing
|
known prices. Prices can be filtered by a query. Price amounts are
|
||||||
transaction prices) can be filtered by a query. Price amounts are
|
|
||||||
displayed with their full precision.
|
displayed with their full precision.
|
||||||
|
|
||||||
_FLAGS
|
_FLAGS
|
||||||
|
|||||||
@ -60,20 +60,20 @@ There are some situations where print's output can become unparseable:
|
|||||||
|
|
||||||
Normally, the journal entry's explicit or implicit amount style is
|
Normally, the journal entry's explicit or implicit amount style is
|
||||||
preserved. For example, when an amount is omitted in the journal, it
|
preserved. For example, when an amount is omitted in the journal, it
|
||||||
will not appear in the output. Similarly, when a transaction price is
|
will not appear in the output. Similarly, when a cost is implied but not
|
||||||
implied but not written, it will not appear in the output. You can use
|
written, it will not appear in the output. You can use the -x/--explicit
|
||||||
the -x/--explicit flag to make all amounts and transaction prices
|
flag to make all amounts and costs explicit, which can be useful for
|
||||||
explicit, which can be useful for troubleshooting or for making your
|
troubleshooting or for making your journal more readable and robust
|
||||||
journal more readable and robust against data entry errors. -x is also
|
against data entry errors. -x is also implied by using any of
|
||||||
implied by using any of -B,-V,-X,--value.
|
-B,-V,-X,--value.
|
||||||
|
|
||||||
Note, -x/--explicit will cause postings with a multi-commodity amount
|
Note, -x/--explicit will cause postings with a multi-commodity amount
|
||||||
(these can arise when a multi-commodity transaction has an implicit
|
(these can arise when a multi-commodity transaction has an implicit
|
||||||
amount) to be split into multiple single-commodity postings, keeping the
|
amount) to be split into multiple single-commodity postings, keeping the
|
||||||
output parseable.
|
output parseable.
|
||||||
|
|
||||||
With -B/--cost, amounts with transaction prices are converted to cost
|
With -B/--cost, amounts with costs are converted to cost using that
|
||||||
using that price. This can be used for troubleshooting.
|
price. This can be used for troubleshooting.
|
||||||
|
|
||||||
With -m DESC/--match=DESC, print does a fuzzy search for the one
|
With -m DESC/--match=DESC, print does a fuzzy search for the one
|
||||||
transaction whose description is most similar to DESC, also preferring
|
transaction whose description is most similar to DESC, also preferring
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user