;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
|
||||
of balance - ie, the sum of posting amounts, both inflows and outflows -
|
||||
during the entire period of the journal. For real-world accounts, this
|
||||
should also match their end balance at the end of the journal period
|
||||
(more on this below).
|
||||
during the entire period of the journal. ("Simple" here means just one
|
||||
column of numbers, covering a single period. You can also have
|
||||
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
|
||||
by account name. For instance (using examples/sample.journal):
|
||||
@ -91,8 +94,8 @@ $ hledger -f examples/sample.journal bal
|
||||
--------------------
|
||||
0
|
||||
|
||||
Accounts with a zero balance (and no non-zero subaccounts, in tree mode
|
||||
- see below) are hidden by default. Use -E/--empty to show them
|
||||
Accounts with a zero balance (and no non-zero subaccounts, in tree
|
||||
mode - see below) are hidden by default. Use -E/--empty to show them
|
||||
(revealing assets:bank:checking here):
|
||||
|
||||
$ 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
|
||||
-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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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:
|
||||
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
|
||||
|
||||
It's important to be clear on the meaning of the numbers shown in
|
||||
@ -464,18 +386,26 @@ balances:
|
||||
|
||||
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] ...
|
||||
|
||||
The first two are the most important: calculation type selects the basic
|
||||
calculation to perform for each table cell, while 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. A valuation type can be added if you want to convert
|
||||
the basic report to value or cost.
|
||||
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
|
||||
|
||||
Calculation type:
|
||||
The basic calculation to perform for each table cell. It is one of:
|
||||
|
||||
- --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
|
||||
balance minus each amount's original cost)
|
||||
|
||||
Accumulation type:
|
||||
Accumulation type
|
||||
|
||||
Which postings should be included in each cell's calculation. It is one
|
||||
of:
|
||||
|
||||
@ -503,7 +434,8 @@ of:
|
||||
assets/liabilities/equity. (default for balancesheet,
|
||||
balancesheetequity, cashflow)
|
||||
|
||||
Valuation type:
|
||||
Valuation type
|
||||
|
||||
Which kind of valuation, valuation date(s) and optionally a target
|
||||
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.
|
||||
|
||||
Combining balance report types
|
||||
|
||||
Most combinations of these options should produce reasonable reports,
|
||||
but if you find any that seem wrong or misleading, let us know. The
|
||||
following restrictions are applied:
|
||||
@ -530,8 +464,8 @@ For reference, here is what the combinations of accumulation and
|
||||
valuation show:
|
||||
|
||||
------------------------------------------------------------------------------------------------
|
||||
Valuation: no valuation --value= then --value= end --value= YYYY-MM-DD /now
|
||||
>Accumulation: v
|
||||
Valuation:> no valuation --value= then --value= end --value= YYYY-MM-DD /now
|
||||
Accumulation:v
|
||||
------------------ ---------------- ----------------- --------------- --------------------------
|
||||
--change change in period sum of period-end DATE-value of change in
|
||||
posting-date value of change period
|
||||
@ -552,41 +486,6 @@ valuation show:
|
||||
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
|
||||
|
||||
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
|
||||
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
|
||||
can use --format FMT to customise the format and content of each line.
|
||||
Eg:
|
||||
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:
|
||||
|
||||
$ 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
|
||||
- --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 easily-consumed "tidy" form,
|
||||
with one row per data value (works only with CSV output)
|
||||
|
||||
The FMT format string (plus a newline) specifies the formatting applied
|
||||
to each account/balance pair. It may contain any suitable text, with
|
||||
data fields interpolated like so:
|
||||
These --layout modes are supported with some but not all of the output
|
||||
formats:
|
||||
|
||||
%[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,
|
||||
or if MIN is specified, MIN * depth spaces.
|
||||
- account - the account's name
|
||||
- total - the account's balance/posted total, right justified
|
||||
|| 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
|
||||
|
||||
Also, FMT can begin with an optional prefix to control how
|
||||
multi-commodity amounts are rendered:
|
||||
- Limited wide layout. A width limit reduces the width, but some
|
||||
commodities will be hidden:
|
||||
|
||||
- %_ - render on multiple lines, bottom-aligned (the default)
|
||||
- %^ - render on multiple lines, top-aligned
|
||||
- %, - render on one line, comma-separated
|
||||
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
|
||||
Balance changes in 2012-01-01..2014-12-31:
|
||||
|
||||
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.
|
||||
|| 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..
|
||||
|
||||
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
|
||||
- %-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
|
||||
$ 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
|
||||
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,
|
||||
inferring missing amounts where necessary, and possibly converting
|
||||
commodities using transaction prices or automatically-inferred
|
||||
transaction prices
|
||||
commodities using costs or automatically-inferred costs
|
||||
|
||||
- assertions - all balance assertions in the journal are passing.
|
||||
(This check can be disabled with -I/--ignore-assertions.)
|
||||
@ -47,7 +46,7 @@ check:
|
||||
- commodities - all commodity symbols used have been declared
|
||||
|
||||
- balancednoautoconversion - transactions are balanced, possibly using
|
||||
explicit transaction prices but not inferred ones
|
||||
explicit costs but not inferred ones
|
||||
|
||||
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
|
||||
balances (good for troubleshooting).
|
||||
|
||||
close and prices
|
||||
close and costs
|
||||
|
||||
Transaction prices are ignored (and discarded) by closing/opening
|
||||
transactions, by default. With --show-costs, they are preserved; there
|
||||
will be a separate equity posting for each cost in each commodity. This
|
||||
means balance -B reports will look the same after the transition. Note
|
||||
if you have many foreign currency or investment transactions, this will
|
||||
generate very large journal entries.
|
||||
Costs are ignored (and discarded) by closing/opening transactions, by
|
||||
default. With --show-costs, they are preserved; there will be a separate
|
||||
equity posting for each cost in each commodity. This means balance -B
|
||||
reports will look the same after the transition. Note if you have many
|
||||
foreign currency or investment transactions, this will generate very
|
||||
large journal entries.
|
||||
|
||||
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
|
||||
will work:
|
||||
|
||||
end date argument explanation
|
||||
------------------- ------------------------------------------------
|
||||
-e 2021-01-01 end dates are exclusive
|
||||
-e 2021 equivalent, per smart dates
|
||||
-p 2020 equivalent, the period's begin date is ignored
|
||||
date:2020 equivalent query
|
||||
-----------------------------------------------------------------------
|
||||
end date explanation
|
||||
argument
|
||||
--------------- -------------------------------------------------------
|
||||
-e 2021-01-01 end dates are exclusive
|
||||
|
||||
-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
|
||||
|
||||
|
||||
@ -16,17 +16,21 @@ You can add a query to select a subset of transactions.
|
||||
|
||||
Examples:
|
||||
|
||||
1/1 (123)
|
||||
(a) 1
|
||||
2022/1/1 (123) Supermarket
|
||||
Food $5.00
|
||||
Checking
|
||||
|
||||
1/1 ()
|
||||
(a) 1
|
||||
2022/1/2 (124) Post Office
|
||||
Postage $8.32
|
||||
Checking
|
||||
|
||||
1/1
|
||||
(a) 1
|
||||
2022/1/3 Supermarket
|
||||
Food $11.23
|
||||
Checking
|
||||
|
||||
1/1 (126)
|
||||
(a) 1
|
||||
2022/1/4 (126) Post Office
|
||||
Postage $3.21
|
||||
Checking
|
||||
|
||||
$ hledger codes
|
||||
123
|
||||
@ -37,5 +41,4 @@ $ hledger codes -E
|
||||
123
|
||||
124
|
||||
|
||||
|
||||
126
|
||||
|
||||
@ -1,9 +1,8 @@
|
||||
prices
|
||||
Print market price directives from the journal. With
|
||||
--infer-market-prices, generate additional market prices from
|
||||
transaction prices. With --infer-reverse-prices, also generate market
|
||||
prices by inverting transaction prices. Prices (and postings providing
|
||||
transaction prices) can be filtered by a query. Price amounts are
|
||||
--infer-market-prices, generate additional market prices from costs.
|
||||
With --infer-reverse-prices, also generate market prices by inverting
|
||||
known prices. Prices can be filtered by a query. Price amounts are
|
||||
displayed with their full precision.
|
||||
|
||||
_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
|
||||
preserved. For example, when an amount is omitted in the journal, it
|
||||
will not appear in the output. Similarly, when a transaction price is
|
||||
implied but not written, it will not appear in the output. You can use
|
||||
the -x/--explicit flag to make all amounts and transaction prices
|
||||
explicit, which can be useful for troubleshooting or for making your
|
||||
journal more readable and robust against data entry errors. -x is also
|
||||
implied by using any of -B,-V,-X,--value.
|
||||
will not appear in the output. Similarly, when a cost is implied but not
|
||||
written, it will not appear in the output. You can use the -x/--explicit
|
||||
flag to make all amounts and costs explicit, which can be useful for
|
||||
troubleshooting or for making your journal more readable and robust
|
||||
against data entry errors. -x is also implied by using any of
|
||||
-B,-V,-X,--value.
|
||||
|
||||
Note, -x/--explicit will cause postings with a multi-commodity amount
|
||||
(these can arise when a multi-commodity transaction has an implicit
|
||||
amount) to be split into multiple single-commodity postings, keeping the
|
||||
output parseable.
|
||||
|
||||
With -B/--cost, amounts with transaction prices are converted to cost
|
||||
using that price. This can be used for troubleshooting.
|
||||
With -B/--cost, amounts with costs are converted to cost using that
|
||||
price. This can be used for troubleshooting.
|
||||
|
||||
With -m DESC/--match=DESC, print does a fuzzy search for the one
|
||||
transaction whose description is most similar to DESC, also preferring
|
||||
|
||||
Loading…
Reference in New Issue
Block a user