;update CLI usage texts
This commit is contained in:
Simon Michael
parent
fce0a690dd
commit
5dc644d280
@ -3,40 +3,77 @@ Show accounts and their balances.
|
||||
|
||||
_FLAGS
|
||||
|
||||
The balance command is hledger's most versatile command. Note, despite
|
||||
the name, it is not always used for showing real-world account balances;
|
||||
the more accounting-aware balancesheet and incomestatement may be more
|
||||
convenient for that.
|
||||
balance is one of hledger's oldest and most versatile commands, for
|
||||
listing account balances, balance changes, values, value changes and
|
||||
more, during one time period or many. Generally it shows a table, with
|
||||
rows representing accounts, and columns representing periods.
|
||||
|
||||
By default, it displays all accounts, and each account's change in
|
||||
balance during the entire period of the journal. Balance changes are
|
||||
calculated by adding up the postings in each account. You can limit the
|
||||
postings matched, by a query, to see fewer accounts, changes over a
|
||||
different time period, changes from only cleared transactions, etc.
|
||||
Note there are some higher-level variants of the balance command with
|
||||
convenient defaults, which can be simpler to use: balancesheet,
|
||||
balancesheetequity, cashflow and incomestatement. When you need more
|
||||
control, then use balance.
|
||||
|
||||
If you include an account's complete history of postings in the report,
|
||||
the balance change is equivalent to the account's current ending
|
||||
balance. For a real-world account, typically you won't have all
|
||||
transactions in the journal; instead you'll have all transactions after
|
||||
a certain date, and an "opening balances" transaction setting the
|
||||
correct starting balance on that date. Then the balance command will
|
||||
show real-world account balances. In some cases the -H/--historical flag
|
||||
is used to ensure this (more below).
|
||||
balance features
|
||||
|
||||
This command also supports the output destination and output format
|
||||
options The output formats supported are (in most modes): txt, csv,
|
||||
html, and json.
|
||||
Here's a quick overview of the balance command's features, followed by
|
||||
more detailed descriptions and examples. Many of these work with the
|
||||
higher-level commands as well.
|
||||
|
||||
The balance command can produce several styles of report:
|
||||
balance can show..
|
||||
|
||||
Single-period flat balance report
|
||||
- accounts as a list (-l) or a tree (-t)
|
||||
- optionally depth-limited (-[1-9])
|
||||
- sorted by declaration order and name, or by amount
|
||||
|
||||
This is the default for hledger's balance command: a flat list of all
|
||||
(or with a query, matched) accounts, showing full account names.
|
||||
Accounts are sorted by declaration order if any, and then by account
|
||||
name. Accounts which have zero balance are not shown unless -E/--empty
|
||||
is used. The reported balances' total is shown as the last line, unless
|
||||
disabled by -N/--no-total.
|
||||
..and their..
|
||||
|
||||
- balance changes (the default)
|
||||
- or actual and planned balance changes (--budget)
|
||||
- or value of balance changes (-V)
|
||||
- or change of balance values (--valuechange)
|
||||
|
||||
..in..
|
||||
|
||||
- one time period (the whole journal period by default)
|
||||
- or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
|
||||
|
||||
..either..
|
||||
|
||||
- per period (the default)
|
||||
- or accumulated since report start date (--cumulative)
|
||||
- or accumulated since account creation (--historical/-H)
|
||||
|
||||
..possibly converted to..
|
||||
|
||||
- cost (--value=cost[,COMM]/--cost/-B)
|
||||
- or market value, as of transaction dates (--value=then[,COMM])
|
||||
- or at period ends (--value=end[,COMM])
|
||||
- or now (--value=now)
|
||||
- or at some other date (--value=YYYY-MM-DD)
|
||||
|
||||
..with..
|
||||
|
||||
- totals (-T), averages (-A), percentages (-%), inverted sign
|
||||
(--invert)
|
||||
- rows and columns swapped (--transpose)
|
||||
- another field used as account name (--pivot)
|
||||
- custom-formatted line items (single-period reports only) (--format)
|
||||
|
||||
This command supports the output destination and output format options,
|
||||
with output formats txt, csv, json, and (multi-period reports only:)
|
||||
html. In txt output in a colour-supporting terminal, negative amounts
|
||||
are shown in red.
|
||||
|
||||
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).
|
||||
|
||||
Accounts are sorted by declaration order if any, and then alphabetically
|
||||
by account name. For instance, using examples/sample.journal:
|
||||
|
||||
$ hledger bal
|
||||
$1 assets:bank:saving
|
||||
@ -49,11 +86,43 @@ $ hledger bal
|
||||
--------------------
|
||||
0
|
||||
|
||||
Single-period tree-mode balance report
|
||||
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):
|
||||
|
||||
With the -t/--tree flag, accounts are displayed hierarchically, showing
|
||||
subaccounts as short names indented below their parent. (This is the
|
||||
default style in Ledger and in older hledger versions.)
|
||||
$ hledger -f examples/sample.journal bal -E
|
||||
0 assets:bank:checking
|
||||
$1 assets:bank:saving
|
||||
$-2 assets:cash
|
||||
$1 expenses:food
|
||||
$1 expenses:supplies
|
||||
$-1 income:gifts
|
||||
$-1 income:salary
|
||||
$1 liabilities:debts
|
||||
--------------------
|
||||
0
|
||||
|
||||
The total of the amounts displayed is shown as the last line, unless
|
||||
-N/--no-total is used.
|
||||
|
||||
Filtered balance report
|
||||
|
||||
You can show fewer accounts, a different time period, totals from
|
||||
cleared transactions only, etc. by using query arguments or options to
|
||||
limit the postings being matched. Eg:
|
||||
|
||||
$ hledger bal --cleared assets date:200806
|
||||
$-2 assets:cash
|
||||
--------------------
|
||||
$-2
|
||||
|
||||
List or tree mode
|
||||
|
||||
By default, or with -l/--flat, accounts are shown as a flat list with
|
||||
their full names visible, as in the examples above.
|
||||
|
||||
With -t/--tree, the account hierarchy is shown, with subaccounts' "leaf"
|
||||
names indented below their parent:
|
||||
|
||||
$ hledger balance
|
||||
$-1 assets
|
||||
@ -69,37 +138,52 @@ $ hledger balance
|
||||
--------------------
|
||||
0
|
||||
|
||||
For more compact output, "boring" accounts containing a single
|
||||
interesting subaccount and no balance of their own (assets:bank and
|
||||
liabilities here) are elided into the following line, unless --no-elide
|
||||
is used. And accounts which have zero balance and no non-zero
|
||||
subaccounts are omitted, unless -E/--empty is used.
|
||||
Notes:
|
||||
|
||||
Account balances in tree mode are "inclusive" - they include the
|
||||
balances of any subaccounts. Eg, the assets $-1 balance here includes
|
||||
the $1 from assets:bank:saving and the $-2 from assets:cash. (And it
|
||||
would include balance posted to the assets account itself, if there was
|
||||
any). Note this causes some repetition, and the final total (0) is the
|
||||
sum of the top-level balances, not of all the balances shown.
|
||||
- "Boring" accounts are combined with their subaccount for more
|
||||
compact output, unless --no-elide is used. Boring accounts have no
|
||||
balance of their own and just one subaccount (eg assets:bank and
|
||||
liabilities above).
|
||||
|
||||
Each group of sibling accounts is sorted separately, by declaration
|
||||
order and then by account name.
|
||||
- All balances shown are "inclusive", ie including the balances from
|
||||
all subaccounts. Note this means some repetition in the output,
|
||||
which requires explanation when sharing reports with
|
||||
non-plaintextaccounting-users. A tree mode report's final total is
|
||||
the sum of the top-level balances shown, not of all the balances
|
||||
shown.
|
||||
|
||||
- Each group of sibling accounts (ie, under a common parent) is sorted
|
||||
separately.
|
||||
|
||||
Depth limiting
|
||||
|
||||
With a depth:N query, or --depth N option, or just -N, balance reports
|
||||
will show accounts only to the specified depth, hiding the deeper
|
||||
subaccounts. Account balances at the depth limit always include the
|
||||
balances from any hidden subaccounts (even in list mode). This can be
|
||||
useful for getting an overview. Eg, limiting to depth 1:
|
||||
|
||||
$ hledger balance -N -1
|
||||
$-1 assets
|
||||
$2 expenses
|
||||
$-2 income
|
||||
$1 liabilities
|
||||
|
||||
You can also hide top-level account name parts, using --drop N. This can
|
||||
be useful for hiding repetitive top-level account names:
|
||||
|
||||
$ hledger bal expenses --drop 1
|
||||
$1 food
|
||||
$1 supplies
|
||||
--------------------
|
||||
$2
|
||||
|
||||
Multi-period balance report
|
||||
|
||||
Multi-period balance reports are a very useful hledger feature,
|
||||
activated if you provide one of the reporting interval flags, such as
|
||||
-M/--monthly. They are similar to single-period balance reports, but
|
||||
they show the report as a table, with columns representing one or more
|
||||
successive time periods. This is the usually the preferred style of
|
||||
balance report in hledger (even for a single period).
|
||||
|
||||
Multi-period balance reports come in several types, showing different
|
||||
information:
|
||||
|
||||
1. A balance change report: by default, each column shows the sum of
|
||||
postings in that period, ie the account's change of balance in that
|
||||
period. This is useful eg for a monthly income statement:
|
||||
With a report interval (set by the -D/--daily, -W/--weekly,
|
||||
-M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), balance
|
||||
shows a tabular report, with columns representing successive time
|
||||
periods (and a title):
|
||||
|
||||
$ hledger balance --quarterly income expenses -E
|
||||
Balance changes in 2008:
|
||||
@ -113,225 +197,240 @@ Balance changes in 2008:
|
||||
-------------------++---------------------------------
|
||||
|| $-1 $1 0 0
|
||||
|
||||
2. A cumulative end balance report: with --cumulative, each column
|
||||
shows the end balance for that period, accumulating the changes
|
||||
across periods, starting from 0 at the report start date:
|
||||
Notes:
|
||||
|
||||
$ hledger balance --quarterly income expenses -E --cumulative
|
||||
Ending balances (cumulative) in 2008:
|
||||
- The report's start/end dates will be expanded, if necessary, to
|
||||
fully encompass the displayed subperiods (so that the first and last
|
||||
subperiods have the same duration as the others).
|
||||
- Leading and trailing periods (columns) containing all zeroes are not
|
||||
shown, unless -E/--empty is used.
|
||||
- Accounts (rows) containing all zeroes are not shown, unless
|
||||
-E/--empty is used.
|
||||
- Amounts with many commodities are shown in abbreviated form, unless
|
||||
--no-elide is used. (experimental)
|
||||
- Average and/or total columns can be added with the -A/--average and
|
||||
-T/--row-total flags.
|
||||
- The --transpose flag can be used to exchange rows and columns.
|
||||
- The --pivot FIELD option causes a different transaction field to be
|
||||
used as "account name". See PIVOTING.
|
||||
|
||||
|| 2008/03/31 2008/06/30 2008/09/30 2008/12/31
|
||||
===================++=================================================
|
||||
expenses:food || 0 $1 $1 $1
|
||||
expenses:supplies || 0 $1 $1 $1
|
||||
income:gifts || 0 $-1 $-1 $-1
|
||||
income:salary || $-1 $-1 $-1 $-1
|
||||
-------------------++-------------------------------------------------
|
||||
|| $-1 0 0 0
|
||||
Multi-period reports with many periods can be too wide for easy viewing
|
||||
in the terminal. Here are some ways to handle that:
|
||||
|
||||
3. A historical end balance report: with --historical/-H, each column
|
||||
shows the actual historical end balance for that period,
|
||||
accumulating the changes across periods, and including the balance
|
||||
from any postings before the report start date. This is useful eg
|
||||
for a multi-period balance sheet, and when you want to see balances
|
||||
only after a certain date:
|
||||
|
||||
$ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1
|
||||
Ending balances (historical) in 2008/04/01-2008/12/31:
|
||||
|
||||
|| 2008/06/30 2008/09/30 2008/12/31
|
||||
======================++=====================================
|
||||
assets:bank:checking || $1 $1 0
|
||||
assets:bank:saving || $1 $1 $1
|
||||
assets:cash || $-2 $-2 $-2
|
||||
liabilities:debts || 0 0 $1
|
||||
----------------------++-------------------------------------
|
||||
|| 0 0 0
|
||||
|
||||
Note that --cumulative or --historical/-H disable --row-total/-T, since
|
||||
summing end balances generally does not make sense.
|
||||
|
||||
With a reporting interval (like --quarterly above), the report start/end
|
||||
dates will be adjusted if necessary so that they encompass the displayed
|
||||
report periods. This is so that the first and last periods will be
|
||||
"full" and comparable to the others.
|
||||
|
||||
The -E/--empty flag does two things in multicolumn balance reports:
|
||||
first, the report will show all columns within the specified report
|
||||
period (without -E, leading and trailing columns with all zeroes are not
|
||||
shown). Second, all accounts which existed at the report start date will
|
||||
be considered, not just the ones with activity during the report period
|
||||
(use -E to include low-activity accounts which would otherwise would be
|
||||
omitted).
|
||||
|
||||
The -T/--row-total flag adds an additional column showing the total for
|
||||
each row.
|
||||
|
||||
The -A/--average flag adds a column showing the average value in each
|
||||
row.
|
||||
|
||||
Here's an example of all three:
|
||||
|
||||
$ hledger balance -Q income expenses --tree -ETA
|
||||
Balance changes in 2008:
|
||||
|
||||
|| 2008q1 2008q2 2008q3 2008q4 Total Average
|
||||
============++===================================================
|
||||
expenses || 0 $2 0 0 $2 $1
|
||||
food || 0 $1 0 0 $1 0
|
||||
supplies || 0 $1 0 0 $1 0
|
||||
income || $-1 $-1 0 0 $-2 $-1
|
||||
gifts || 0 $-1 0 0 $-1 0
|
||||
salary || $-1 0 0 0 $-1 0
|
||||
------------++---------------------------------------------------
|
||||
|| $-1 $1 0 0 0 0
|
||||
|
||||
(Average is rounded to the dollar here since all journal amounts are)
|
||||
|
||||
The --transpose flag can be used to exchange the rows and columns of a
|
||||
multicolumn report.
|
||||
|
||||
When showing multicommodity amounts, multicolumn balance reports will
|
||||
elide any amounts which have more than two commodities, since otherwise
|
||||
columns could get very wide. The --no-elide flag disables this. Hiding
|
||||
totals with the -N/--no-total flag can also help reduce the width of
|
||||
multicommodity reports.
|
||||
|
||||
When the report is still too wide, a good workaround is to pipe it into
|
||||
less -RS (-R for colour, -S to chop long lines). Eg:
|
||||
hledger bal -D --color=yes | less -RS.
|
||||
|
||||
Depth limiting
|
||||
|
||||
With a depth:N query, or --depth N option, or just -N, balance reports
|
||||
will show accounts only to the specified depth. This is very useful to
|
||||
hide low-level accounts and get an overview. Eg, limiting to depth 1
|
||||
shows the top-level accounts:
|
||||
|
||||
$ hledger balance -N -1
|
||||
$-1 assets
|
||||
$2 expenses
|
||||
$-2 income
|
||||
$1 liabilities
|
||||
|
||||
Accounts at the depth limit will include the balances of any hidden
|
||||
subaccounts (even in flat mode, which normally shows exclusive
|
||||
balances).
|
||||
|
||||
You can also drop account name components from the start of account
|
||||
names, using --drop N. This can be useful to hide unwanted top-level
|
||||
detail.
|
||||
|
||||
Colour support
|
||||
|
||||
In terminal output, when colour is enabled, the balance command shows
|
||||
negative amounts in red.
|
||||
- Hide the totals row with -N/--no-total
|
||||
- Convert to a single currency with -V
|
||||
- Maximize the terminal window
|
||||
- Reduce the terminal's font size
|
||||
- View with a pager like less, eg:
|
||||
hledger bal -D --color=yes | less -RS
|
||||
- Output as CSV and use a CSV viewer like visidata
|
||||
(hledger bal -D -O csv | vd -f csv), Emacs' csv-mode
|
||||
(M-x csv-mode, C-c C-a), or a spreadsheet
|
||||
(hledger bal -D -o a.csv && open a.csv)
|
||||
- Output as HTML and view with a browser:
|
||||
hledger bal -D -o a.html && open a.html
|
||||
|
||||
Sorting by amount
|
||||
|
||||
With -S/--sort-amount, accounts with the largest (most positive)
|
||||
balances are shown first. For example, hledger bal expenses -MAS shows
|
||||
your biggest averaged monthly expenses first.
|
||||
balances are shown first. Eg: hledger bal expenses -MAS shows your
|
||||
biggest averaged monthly expenses first.
|
||||
|
||||
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 sign-flipping reports like
|
||||
balancesheet or incomestatement, which also support -S. Eg:
|
||||
hledger is -MAS.
|
||||
to flip the signs. (Or, use one of the higher-level reports, which flip
|
||||
the sign automatically. Eg: hledger incomestatement -MAS).
|
||||
|
||||
Percentages
|
||||
|
||||
With -% or --percent, balance reports show each account's value
|
||||
expressed as a percentage of the column's total. This is useful to get
|
||||
an overview of the relative sizes of account balances. For example to
|
||||
obtain an overview of expenses:
|
||||
With -%/--percent, balance reports show each account's value expressed
|
||||
as a percentage of the (column) total:
|
||||
|
||||
$ hledger balance expenses -%
|
||||
100.0 % expenses
|
||||
50.0 % food
|
||||
50.0 % supplies
|
||||
--------------------
|
||||
100.0 %
|
||||
$ hledger bal expenses -Q -%
|
||||
Balance changes in 2008:
|
||||
|
||||
Note that --tree does not have an effect on -%. The percentages are
|
||||
always relative to the total sum of each column, they are never relative
|
||||
to the parent account.
|
||||
|| 2008Q1 2008Q2 2008Q3 2008Q4
|
||||
===================++=================================
|
||||
expenses:food || 0 50.0 % 0 0
|
||||
expenses:supplies || 0 50.0 % 0 0
|
||||
-------------------++---------------------------------
|
||||
|| 0 100.0 % 0 0
|
||||
|
||||
Since the percentages are relative to the columns sum, it is usually not
|
||||
useful to calculate percentages if the signs of the amounts are mixed.
|
||||
Although the results are technically correct, they are most likely
|
||||
useless. Especially in a balance report that sums up to zero (eg
|
||||
hledger balance -B) all percentage values will be zero.
|
||||
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:
|
||||
|
||||
This flag does not work if the report contains any mixed commodity
|
||||
accounts. If there are mixed commodity accounts in the report be sure to
|
||||
use -V or -B to coerce the report into using a single commodity.
|
||||
$ hledger bal -% amt:`>0`
|
||||
$ hledger bal -% amt:`<0`
|
||||
|
||||
Customising single-period balance reports
|
||||
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:
|
||||
|
||||
You can customise the layout of single-period balance reports with
|
||||
--format FMT, which sets the format of each line. Eg:
|
||||
$ hledger bal -% cur:\\$
|
||||
$ hledger bal -% cur:€
|
||||
|
||||
$ hledger 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
|
||||
Balance change, end balance
|
||||
|
||||
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:
|
||||
It's important to be clear on the meaning of the numbers shown in
|
||||
balance reports. Here is some terminology we use:
|
||||
|
||||
%[MIN][.MAX](FIELDNAME)
|
||||
A balance change is the net amount added to, or removed from, an account
|
||||
during some period.
|
||||
|
||||
- MIN pads with spaces to at least this width (optional)
|
||||
An end balance is the amount accumulated in an account as of some date
|
||||
(and some time, but hledger doesn't store that; assume end of day in
|
||||
your timezone). It is the sum of previous balance changes.
|
||||
|
||||
- MAX truncates at this width (optional)
|
||||
We call it a historical end balance if it includes all balance changes
|
||||
since the account was created. For a real world account, this means it
|
||||
will match the "historical record", eg the balances reported in your
|
||||
bank statements or bank web UI. (If they are correct!)
|
||||
|
||||
- FIELDNAME must be enclosed in parentheses, and can be one of:
|
||||
In general, balance changes are what you want to see when reviewing
|
||||
revenues and expenses, and historical end balances are what you want to
|
||||
see when reviewing or reconciling asset, liability and equity accounts.
|
||||
|
||||
- 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
|
||||
balance shows balance changes by default. To see accurate historical end
|
||||
balances:
|
||||
|
||||
Also, FMT can begin with an optional prefix to control how
|
||||
multi-commodity amounts are rendered:
|
||||
1. Initialise account starting balances with an "opening balances"
|
||||
transaction (a transfer from equity to the account), unless the
|
||||
journal covers the account's full lifetime.
|
||||
|
||||
- %_ - render on multiple lines, bottom-aligned (the default)
|
||||
- %^ - render on multiple lines, top-aligned
|
||||
- %, - render on one line, comma-separated
|
||||
2. Include all of of the account's prior postings in the report, by not
|
||||
specifying a report start date, or by using the -H/--historical
|
||||
flag. (-H causes report start date to be ignored when summing
|
||||
postings.)
|
||||
|
||||
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.
|
||||
Balance report types
|
||||
|
||||
Some example formats:
|
||||
For more flexible reporting, there are three important option groups:
|
||||
|
||||
- %(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 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.
|
||||
|
||||
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
|
||||
- --valuechange : show the change in period-end historical balance
|
||||
values
|
||||
|
||||
Accumulation type:
|
||||
Which postings should be included in 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)
|
||||
|
||||
- --cumulative : postings from report start to column end, eg to show
|
||||
changes accumulated since the report's start date. Rarely 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
|
||||
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:
|
||||
|
||||
- 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)
|
||||
- --value=now[,COMM] : show value at today's date
|
||||
- --value=YYYY-MM-DD[,COMM] : show value at another date
|
||||
|
||||
or one of their aliases: --cost/-B, --market/-V or --exchange/-X.
|
||||
|
||||
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:
|
||||
|
||||
- --valuechange implies --value=end
|
||||
- --valuechange makes --change the default when used with the
|
||||
balancesheet/balancesheetequity commands
|
||||
- --cumulative or --historical disables --row-total/-T
|
||||
|
||||
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
|
||||
------------------ ---------------- ----------------- --------------- --------------------------
|
||||
--change change in period sum of period-end DATE-value of change in
|
||||
posting-date value of change period
|
||||
market values in in period
|
||||
period
|
||||
|
||||
--cumulative change from sum of period-end DATE-value of change from
|
||||
report start to posting-date value of change report start to period end
|
||||
period end market values from report
|
||||
from report start start to period
|
||||
to period end end
|
||||
|
||||
--historical /-H change from sum of period-end DATE-value of change from
|
||||
journal start to posting-date value of change journal start to period
|
||||
period end market values from journal end
|
||||
(historical end from journal start to period
|
||||
balance) start to period 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
|
||||
|
||||
There is also a special balance report mode for showing budget
|
||||
performance. The --budget flag activates extra columns showing the
|
||||
budget goals for each account and period, if any. For this report,
|
||||
budget goals are defined by periodic transactions. This is very useful
|
||||
for comparing planned and actual income, expenses, time usage, etc.
|
||||
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.
|
||||
|
||||
For example, you can take average monthly expenses in the common expense
|
||||
categories to construct a minimal monthly budget:
|
||||
@ -387,11 +486,11 @@ This is different from a normal balance report in several ways:
|
||||
goal amounts are shown, and the actual/goal percentage. (Note:
|
||||
budget goals should be in the same commodity as the actual amount.)
|
||||
|
||||
- All parent accounts are always shown, even in flat mode. Eg assets,
|
||||
- All parent accounts are always shown, even in list mode. Eg assets,
|
||||
assets:bank, and expenses above.
|
||||
|
||||
- Amounts always include all subaccounts, budgeted or unbudgeted, even
|
||||
in flat mode.
|
||||
in list mode.
|
||||
|
||||
This means that the numbers displayed will not always add up! Eg above,
|
||||
the expenses actual amount includes the gifts and supplies transactions,
|
||||
@ -564,3 +663,62 @@ Budget performance in 2019/01:
|
||||
liabilities || $-283.00 [ 26% of $-1100.00]
|
||||
----------------------------------------++-------------------------------
|
||||
|| 0 [ 0]
|
||||
|
||||
Customising single-period balance reports
|
||||
|
||||
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 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 (plus a newline) 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
|
||||
|
||||
@ -11,9 +11,6 @@ the Asset or Cash or Liability type, or otherwise all accounts under a
|
||||
top-level asset or liability account (case insensitive, plurals
|
||||
allowed).
|
||||
|
||||
(This report is essentially similar to "hledger balance --historical
|
||||
assets liabilities", with liabilities sign-flipped.)
|
||||
|
||||
Example:
|
||||
|
||||
$ hledger balancesheet
|
||||
@ -35,13 +32,10 @@ Total:
|
||||
--------------------
|
||||
0
|
||||
|
||||
With a reporting interval, multiple columns will be shown, one for each
|
||||
report period. As with multicolumn balance reports, you can alter the
|
||||
report mode with --change/--cumulative/--historical. Normally
|
||||
balancesheet shows historical ending balances, which is what you need
|
||||
for a balance sheet; note this means it ignores report begin dates (and
|
||||
-T/--row-total, since summing end balances generally does not make
|
||||
sense). Instead of absolute values percentages can be displayed with -%.
|
||||
This command is a higher-level variant of the balance command, and
|
||||
supports many of that command's features, such as multi-period reports.
|
||||
It is similar to hledger balance -H assets liabilities, but with smarter
|
||||
account detection, and liabilities displayed with their sign flipped.
|
||||
|
||||
This command also supports the output destination and output format
|
||||
options The output formats supported are txt, csv, html, and
|
||||
|
||||
@ -10,9 +10,6 @@ declared with the Asset, Cash, Liability or Equity type, or otherwise
|
||||
all accounts under a top-level asset, liability or equity account (case
|
||||
insensitive, plurals allowed).
|
||||
|
||||
(This report is essentially similar to "hledger balance --historical
|
||||
assets liabilities equity", with liabilities and equity sign-flipped.)
|
||||
|
||||
Example:
|
||||
|
||||
$ hledger balancesheetequity
|
||||
@ -39,6 +36,12 @@ Total:
|
||||
--------------------
|
||||
0
|
||||
|
||||
This command is a higher-level variant of the balance command, and
|
||||
supports many of that command's features, such as multi-period reports.
|
||||
It is similar to hledger balance -H assets liabilities equity, but with
|
||||
smarter account detection, and liabilities/equity displayed with their
|
||||
sign flipped.
|
||||
|
||||
This command also supports the output destination and output format
|
||||
options The output formats supported are txt, csv, html, and
|
||||
(experimental) json.
|
||||
|
||||
@ -10,9 +10,6 @@ type, or otherwise all accounts under a top-level asset account (case
|
||||
insensitive, plural allowed) which do not have fixed, investment,
|
||||
receivable or A/R in their name.
|
||||
|
||||
(This report is essentially similar to "hledger balance --change assets
|
||||
not:fixed not:investment not:receivable".)
|
||||
|
||||
Example:
|
||||
|
||||
$ hledger cashflow
|
||||
@ -29,11 +26,11 @@ Total:
|
||||
--------------------
|
||||
$-1
|
||||
|
||||
With a reporting interval, multiple columns will be shown, one for each
|
||||
report period. Normally cashflow shows changes in assets per period,
|
||||
though as with multicolumn balance reports you can alter the report mode
|
||||
with --change/--cumulative/--historical. Instead of absolute values
|
||||
percentages can be displayed with -%.
|
||||
This command is a higher-level variant of the balance command, and
|
||||
supports many of that command's features, such as multi-period reports.
|
||||
It is similar to
|
||||
hledger balance assets not:fixed not:investment not:receivable, but with
|
||||
smarter account detection.
|
||||
|
||||
This command also supports the output destination and output format
|
||||
options The output formats supported are txt, csv, html, and
|
||||
|
||||
@ -48,13 +48,11 @@ These checks can be run only by giving their names as arguments to
|
||||
check. They are more specialised and not desirable for everyone,
|
||||
therefore optional:
|
||||
|
||||
- ordereddates - transactions are ordered by date (similar to the old
|
||||
check-dates command)
|
||||
- ordereddates - transactions are ordered by date in each file
|
||||
|
||||
- payees - all payees used by transactions have been declared
|
||||
|
||||
- uniqueleafnames - all account leaf names are unique (similar to the
|
||||
old check-dupes command).
|
||||
- uniqueleafnames - all account leaf names are unique
|
||||
|
||||
Custom checks
|
||||
|
||||
|
||||
@ -6,18 +6,68 @@ transactions as imported, without actually importing any.
|
||||
|
||||
_FLAGS
|
||||
|
||||
The input files are specified as arguments - no need to write -f before
|
||||
each one. So eg to add new transactions from all CSV files to the main
|
||||
journal, it's just: hledger import *.csv
|
||||
Unlike other hledger commands, with import the journal file is an output
|
||||
file, and will be modified, though only by appending (existing data will
|
||||
not be changed). The input files are specified as arguments, so to
|
||||
import one or more CSV files to your main journal, you will run
|
||||
hledger import bank.csv or perhaps hledger import *.csv.
|
||||
|
||||
New transactions are detected in the same way as print --new: by
|
||||
assuming transactions are always added to the input files in increasing
|
||||
date order, and by saving .latest.FILE state files.
|
||||
Note you can import from any file format, though CSV files are the most
|
||||
common import source, and these docs focus on that case.
|
||||
|
||||
The --dry-run output is in journal format, so you can filter it, eg to
|
||||
see only uncategorised transactions:
|
||||
Deduplication
|
||||
|
||||
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
|
||||
As a convenience import does deduplication while reading transactions.
|
||||
This does not mean "ignore transactions that look the same", but rather
|
||||
"ignore transactions that have been seen before". This is intended for
|
||||
when you are periodically importing foreign data which may contain
|
||||
already-imported transactions. So eg, if every day you download bank CSV
|
||||
files containing redundant data, you can safely run
|
||||
hledger import bank.csv and only new transactions will be imported.
|
||||
(import is idempotent.)
|
||||
|
||||
Since the items being read (CSV records, eg) often do not come with
|
||||
unique identifiers, hledger detects new transactions by date, assuming
|
||||
that:
|
||||
|
||||
1. new items always have the newest dates
|
||||
2. item dates do not change across reads
|
||||
3. and items with the same date remain in the same relative order
|
||||
across reads.
|
||||
|
||||
These are often true of CSV files representing transactions, or true
|
||||
enough so that it works pretty well in practice. 1 is important, but
|
||||
violations of 2 and 3 amongst the old transactions won't matter (and if
|
||||
you import often, the new transactions will be few, so less likely to be
|
||||
the ones affected).
|
||||
|
||||
hledger remembers the latest date processed in each input file by saving
|
||||
a hidden ".latest" state file in the same directory. Eg when reading
|
||||
finance/bank.csv, it will look for and update the
|
||||
finance/.latest.bank.csv state file. The format is simple: one or more
|
||||
lines containing the same ISO-format date (YYYY-MM-DD), meaning "I have
|
||||
processed transactions up to this date, and this many of them on that
|
||||
date." Normally you won't see or manipulate these state files yourself.
|
||||
But if needed, you can delete them to reset the state (making all
|
||||
transactions "new"), or you can construct them to "catch up" to a
|
||||
certain date.
|
||||
|
||||
Note deduplication (and updating of state files) can also be done by
|
||||
print --new, but this is less often used.
|
||||
|
||||
Import testing
|
||||
|
||||
With --dry-run, the transactions that will be imported are printed to
|
||||
the terminal, without updating your journal or state files. The output
|
||||
is valid journal format, like the print command, so you can re-parse it.
|
||||
Eg, to see any importable transactions which CSV rules have not
|
||||
categorised:
|
||||
|
||||
$ hledger import --dry bank.csv | hledger -f- -I print unknown
|
||||
|
||||
or (live updating):
|
||||
|
||||
$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'
|
||||
|
||||
Importing balance assignments
|
||||
|
||||
|
||||
@ -11,9 +11,6 @@ the Revenue or Expense type, or otherwise all accounts under a top-level
|
||||
revenue or income or expense account (case insensitive, plurals
|
||||
allowed).
|
||||
|
||||
(This report is essentially similar to "hledger balance --change
|
||||
revenues expenses", with revenues sign-flipped.)
|
||||
|
||||
Example:
|
||||
|
||||
$ hledger incomestatement
|
||||
@ -37,11 +34,11 @@ Total:
|
||||
--------------------
|
||||
0
|
||||
|
||||
With a reporting interval, multiple columns will be shown, one for each
|
||||
report period. Normally incomestatement shows revenues/expenses per
|
||||
period, though as with multicolumn balance reports you can alter the
|
||||
report mode with --change/--cumulative/--historical. Instead of absolute
|
||||
values percentages can be displayed with -%.
|
||||
This command is a higher-level variant of the balance command, and
|
||||
supports many of that command's features, such as multi-period reports.
|
||||
It is similar to hledger balance '(revenues|income)' expenses, but with
|
||||
smarter account detection, and revenues/income displayed with their sign
|
||||
flipped.
|
||||
|
||||
This command also supports the output destination and output format
|
||||
options The output formats supported are txt, csv, html, and
|
||||
|
||||
@ -79,20 +79,9 @@ transaction: the one one whose description is most similar to STR, and
|
||||
is most recent. STR should contain at least two characters. If there is
|
||||
no similar-enough match, no transaction will be shown.
|
||||
|
||||
With --new, for each FILE being read, hledger reads (and writes) a
|
||||
special state file (.latest.FILE in the same directory), containing the
|
||||
latest transaction date(s) that were seen last time FILE was read. When
|
||||
this file is found, only transactions with newer dates (and new
|
||||
transactions on the latest date) are printed. This is useful for
|
||||
ignoring already-seen entries in import data, such as downloaded CSV
|
||||
files. Eg:
|
||||
|
||||
$ hledger -f bank1.csv print --new
|
||||
(shows transactions added since last print --new on this file)
|
||||
|
||||
This assumes that transactions added to FILE always have same or
|
||||
increasing dates, and that transactions on the same day do not get
|
||||
reordered. See also the import command.
|
||||
With --new, hledger prints only transactions it has not seen on a
|
||||
previous run. This uses the same deduplication system as the import
|
||||
command. (See import's docs for details.)
|
||||
|
||||
This command also supports the output destination and output format
|
||||
options The output formats supported are txt, csv, and (experimental)
|
||||
|
||||
@ -4,24 +4,23 @@ your investments.
|
||||
|
||||
_FLAGS
|
||||
|
||||
This command assumes that you have account(s) that hold nothing but your
|
||||
investments and whenever you record current appraisal/valuation of these
|
||||
investments you offset unrealized profit and loss into account(s) that,
|
||||
again, hold nothing but unrealized profit and loss.
|
||||
|
||||
Any transactions affecting balance of investment account(s) and not
|
||||
originating from unrealized profit and loss account(s) are assumed to be
|
||||
your investments or withdrawals.
|
||||
|
||||
At a minimum, you need to supply a query (which could be just an account
|
||||
name) to select your investments with --inv, and another query to
|
||||
name) to select your investment(s) with --inv, and another query to
|
||||
identify your profit and loss transactions with --pnl.
|
||||
|
||||
If you do not record changes in the value of your investment manually,
|
||||
or do not require computation of time-weighted return (TWR), --pnl could
|
||||
be an empty query (--pnl "" or --pnl STR where STR does not match any of
|
||||
your accounts).
|
||||
|
||||
This command will compute and display the internalized rate of return
|
||||
(IRR) and time-weighted rate of return (TWR) for your investments for
|
||||
the time period requested. Both rates of return are annualized before
|
||||
display, regardless of the length of reporting interval.
|
||||
|
||||
Price directives will be taken into account if you supply appropriate
|
||||
--cost or --value flags (see VALUATION).
|
||||
|
||||
Note, in some cases this report can fail, for these reasons:
|
||||
|
||||
- Error (NotBracketed): No solution for Internal Rate of Return (IRR).
|
||||
@ -33,10 +32,61 @@ Note, in some cases this report can fail, for these reasons:
|
||||
|
||||
Examples:
|
||||
|
||||
- Using roi to report unrealised gains:
|
||||
- Using roi to compute total return of investment in stocks:
|
||||
https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger
|
||||
|
||||
More background:
|
||||
- Cookbook -> Return on Investment
|
||||
|
||||
Semantics of --inv and --pnl
|
||||
|
||||
Query supplied to --inv has to match all transactions that are related
|
||||
to your investment. Transactions not matching --inv will be ignored.
|
||||
|
||||
In these transactions, ROI will conside postings that match --inv to be
|
||||
"investment postings" and other postings (not matching --inv) will be
|
||||
sorted into two categories: "cash flow" and "profit and loss", as ROI
|
||||
needs to know which part of the investment value is your contributions
|
||||
and which is due to the return on investment.
|
||||
|
||||
- "Cash flow" is depositing or withdrawing money, buying or selling
|
||||
assets, or otherwise converting between your investment commodity
|
||||
and any other commodity. Example:
|
||||
|
||||
2019-01-01 Investing in Snake Oil
|
||||
assets:cash -$100
|
||||
investment:snake oil
|
||||
|
||||
2020-01-01 Selling my Snake Oil
|
||||
assets:cash $10
|
||||
investment:snake oil = 0
|
||||
|
||||
- "Profit and loss" is change in the value of your investment:
|
||||
|
||||
2019-06-01 Snake Oil falls in value
|
||||
investment:snake oil = $57
|
||||
equity:unrealized profit or loss
|
||||
|
||||
All non-investment postings are assumed to be "cash flow", unless they
|
||||
match --pnl query. Changes in value of your investment due to "profit
|
||||
and loss" postings will be considered as part of your investment return.
|
||||
|
||||
Example: if you use --inv snake --pnl equity:unrealized, then postings
|
||||
in the example below would be classifed as:
|
||||
|
||||
2019-01-01 Snake Oil #1
|
||||
assets:cash -$100 ; cash flow posting
|
||||
investment:snake oil ; investment posting
|
||||
|
||||
2019-03-01 Snake Oil #2
|
||||
equity:unrealized pnl -$100 ; profit and loss posting
|
||||
snake oil ; investment posting
|
||||
|
||||
2019-07-01 Snake Oil #3
|
||||
equity:unrealized pnl ; profit and loss posting
|
||||
cash -$100 ; cash flow posting
|
||||
snake oil $50 ; investment posting
|
||||
|
||||
IRR and TWR explained
|
||||
|
||||
"ROI" stands for "return on investment". Traditionally this was computed
|
||||
as a difference between current value of investment and its initial
|
||||
@ -55,34 +105,34 @@ smaller (in absolute numbers), and will be a smaller percentage of your
|
||||
initial investment, and if you are adding to your investment, you will
|
||||
receive bigger absolute gains (but probably at the same rate of return).
|
||||
IRR is a way to compute rate of return for each period between in-flow
|
||||
or out-flow of money, and then combine them in a way that gives you an
|
||||
annual rate of return that investment is expected to generate.
|
||||
or out-flow of money, and then combine them in a way that gives you a
|
||||
compound annual rate of return that investment is expected to generate.
|
||||
|
||||
As mentioned before, in-flows and out-flows would be any cash that you
|
||||
personally put in or withdraw, and for the "roi" command, these are
|
||||
transactions that involve account(s) matching --inv argument and NOT
|
||||
involve account(s) matching --pnl argument.
|
||||
personally put in or withdraw, and for the "roi" command, these are the
|
||||
postings that match the query in the--inv argument and NOT match the
|
||||
query in the--pnl argument.
|
||||
|
||||
Presumably, you will also record changes in the value of your
|
||||
investment, and balance them against "profit and loss" (or "unrealized
|
||||
gains") account. Note that in order for IRR to compute the precise
|
||||
effect of your in-flows and out-flows on the rate of return, you will
|
||||
need to record the value of your investement on or close to the days
|
||||
when in- or out-flows occur.
|
||||
|
||||
Implementation of IRR in hledger should match the XIRR formula in Excel.
|
||||
|
||||
Second way to compute rate of return that roi command implements is
|
||||
called "time-weighted rate of return" or "TWR". Like IRR, it will also
|
||||
break the history of your investment into periods between in-flows and
|
||||
out-flows to compute rate of return per each period and then a compound
|
||||
rate of return. However, internal workings of TWR are quite different.
|
||||
If you manually record changes in the value of your investment as
|
||||
transactions that balance them against "profit and loss" (or "unrealized
|
||||
gains") account or use price directives, then in order for IRR to
|
||||
compute the precise effect of your in-flows and out-flows on the rate of
|
||||
return, you will need to record the value of your investement on or
|
||||
close to the days when in- or out-flows occur.
|
||||
|
||||
In technical terms, IRR uses the same approach as computation of net
|
||||
present value, and tries to find a discount rate that makes net present
|
||||
value of all the cash flows of your investment to add up to zero. This
|
||||
could be hard to wrap your head around, especially if you haven't done
|
||||
discounted cash flow analysis before.
|
||||
discounted cash flow analysis before. Implementation of IRR in hledger
|
||||
should produce results that match the XIRR formula in Excel.
|
||||
|
||||
Second way to compute rate of return that roi command implements is
|
||||
called "time-weighted rate of return" or "TWR". Like IRR, it will also
|
||||
break the history of your investment into periods between in-flows,
|
||||
out-flows and value changes, to compute rate of return per each period
|
||||
and then a compound rate of return. However, internal workings of TWR
|
||||
are quite different.
|
||||
|
||||
TWR represents your investment as an imaginary "unit fund" where
|
||||
in-flows/ out-flows lead to buying or selling "units" of your investment
|
||||
@ -93,158 +143,3 @@ your investment.
|
||||
References: * Explanation of rate of return * Explanation of IRR *
|
||||
Explanation of TWR * Examples of computing IRR and TWR and discussion of
|
||||
the limitations of both metrics
|
||||
|
||||
More examples:
|
||||
|
||||
Lets say that we found an investment in Snake Oil that is proising to
|
||||
give us 10% annually:
|
||||
|
||||
2019-01-01 Investing in Snake Oil
|
||||
assets:cash -$100
|
||||
investment:snake oil
|
||||
|
||||
2019-12-24 Recording the growth of Snake Oil
|
||||
investment:snake oil = $110
|
||||
equity:unrealized gains
|
||||
|
||||
For now, basic computation of the rate of return, as well as IRR and
|
||||
TWR, gives us the expected 10%:
|
||||
|
||||
$ hledger roi -Y --inv investment --pnl "unrealized"
|
||||
+---++------------+------------++---------------+----------+-------------+-----++--------+--------+
|
||||
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||
+===++============+============++===============+==========+=============+=====++========+========+
|
||||
| 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 110 | 10 || 10.00% | 10.00% |
|
||||
+---++------------+------------++---------------+----------+-------------+-----++--------+--------+
|
||||
|
||||
However, lets say that shorty after investing in the Snake Oil we
|
||||
started to have second thoughs, so we prompty withdrew $90, leaving only
|
||||
$10 in. Before Christmas, though, we started to get the "fear of mission
|
||||
out", so we put the $90 back in. So for most of the year, our investment
|
||||
was just $10 dollars, and it gave us just $1 in growth:
|
||||
|
||||
2019-01-01 Investing in Snake Oil
|
||||
assets:cash -$100
|
||||
investment:snake oil
|
||||
|
||||
2019-01-02 Buyers remorse
|
||||
assets:cash $90
|
||||
investment:snake oil
|
||||
|
||||
2019-12-30 Fear of missing out
|
||||
assets:cash -$90
|
||||
investment:snake oil
|
||||
|
||||
2019-12-31 Recording the growth of Snake Oil
|
||||
investment:snake oil = $101
|
||||
equity:unrealized gains
|
||||
|
||||
Now IRR and TWR are drastically different:
|
||||
|
||||
$ hledger roi -Y --inv investment --pnl "unrealized"
|
||||
+---++------------+------------++---------------+----------+-------------+-----++-------+-------+
|
||||
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||
+===++============+============++===============+==========+=============+=====++=======+=======+
|
||||
| 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 101 | 1 || 9.32% | 1.00% |
|
||||
+---++------------+------------++---------------+----------+-------------+-----++-------+-------+
|
||||
|
||||
Here, IRR tells us that we made close to 10% on the $10 dollars that we
|
||||
had in the account most of the time. And TWR is ... just 1%? Why?
|
||||
|
||||
Based on the transactions in our journal, TWR "think" that we are buying
|
||||
back $90 worst of Snake Oil at the same price that it had at the
|
||||
beginning of they year, and then after that our $100 investment gets $1
|
||||
increase in value, or 1% of $100. Let's take a closer look at what is
|
||||
happening here by asking for quarterly reports instead of annual:
|
||||
|
||||
$ hledger roi -Q --inv investment --pnl "unrealized"
|
||||
+---++------------+------------++---------------+----------+-------------+-----++--------+-------+
|
||||
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||
+===++============+============++===============+==========+=============+=====++========+=======+
|
||||
| 1 || 2019-01-01 | 2019-03-31 || 0 | 10 | 10 | 0 || 0.00% | 0.00% |
|
||||
| 2 || 2019-04-01 | 2019-06-30 || 10 | 0 | 10 | 0 || 0.00% | 0.00% |
|
||||
| 3 || 2019-07-01 | 2019-09-30 || 10 | 0 | 10 | 0 || 0.00% | 0.00% |
|
||||
| 4 || 2019-10-01 | 2019-12-31 || 10 | 90 | 101 | 1 || 37.80% | 4.03% |
|
||||
+---++------------+------------++---------------+----------+-------------+-----++--------+-------+
|
||||
|
||||
Now both IRR and TWR are thrown off by the fact that all of the growth
|
||||
for our investment happens in Q4 2019. This happes because IRR
|
||||
computation is still yielding 9.32% and TWR is still 1%, but this time
|
||||
these are rates for three month period instead of twelve, so in order to
|
||||
get an annual rate they should be multiplied by four!
|
||||
|
||||
Let's try to keep a better record of how Snake Oil grew in value:
|
||||
|
||||
2019-01-01 Investing in Snake Oil
|
||||
assets:cash -$100
|
||||
investment:snake oil
|
||||
|
||||
2019-01-02 Buyers remorse
|
||||
assets:cash $90
|
||||
investment:snake oil
|
||||
|
||||
2019-02-28 Recording the growth of Snake Oil
|
||||
investment:snake oil
|
||||
equity:unrealized gains -$0.25
|
||||
|
||||
2019-06-30 Recording the growth of Snake Oil
|
||||
investment:snake oil
|
||||
equity:unrealized gains -$0.25
|
||||
|
||||
2019-09-30 Recording the growth of Snake Oil
|
||||
investment:snake oil
|
||||
equity:unrealized gains -$0.25
|
||||
|
||||
2019-12-30 Fear of missing out
|
||||
assets:cash -$90
|
||||
investment:snake oil
|
||||
|
||||
2019-12-31 Recording the growth of Snake Oil
|
||||
investment:snake oil
|
||||
equity:unrealized gains -$0.25
|
||||
|
||||
Would our quartery report look better now? Almost:
|
||||
|
||||
$ hledger roi -Q --inv investment --pnl "unrealized"
|
||||
+---++------------+------------++---------------+----------+-------------+------++--------+--------+
|
||||
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||
+===++============+============++===============+==========+=============+======++========+========+
|
||||
| 1 || 2019-01-01 | 2019-03-31 || 0 | 10 | 10.25 | 0.25 || 9.53% | 10.53% |
|
||||
| 2 || 2019-04-01 | 2019-06-30 || 10.25 | 0 | 10.50 | 0.25 || 10.15% | 10.15% |
|
||||
| 3 || 2019-07-01 | 2019-09-30 || 10.50 | 0 | 10.75 | 0.25 || 9.79% | 9.78% |
|
||||
| 4 || 2019-10-01 | 2019-12-31 || 10.75 | 90 | 101.00 | 0.25 || 8.05% | 1.00% |
|
||||
+---++------------+------------++---------------+----------+-------------+------++--------+--------+
|
||||
|
||||
Something is still wrong with TWR computation for Q4, and if you have
|
||||
been paying attention you know what it is already: big $90 buy-back is
|
||||
recorded prior to the only transaction that captures the change of value
|
||||
of Snake Oil that happened in this time period. Lets combine
|
||||
transactions from 30th and 31st of Dec into one:
|
||||
|
||||
2019-12-30 Fear of missing out and growth of Snake Oil
|
||||
assets:cash -$90
|
||||
investment:snake oil
|
||||
equity:unrealized gains -$0.25
|
||||
|
||||
Now growth of investment properly affects its price at the time of
|
||||
buy-back:
|
||||
|
||||
$ hledger roi -Q --inv investment --pnl "unrealized"
|
||||
+---++------------+------------++---------------+----------+-------------+------++--------+--------+
|
||||
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||
+===++============+============++===============+==========+=============+======++========+========+
|
||||
| 1 || 2019-01-01 | 2019-03-31 || 0 | 10 | 10.25 | 0.25 || 9.53% | 10.53% |
|
||||
| 2 || 2019-04-01 | 2019-06-30 || 10.25 | 0 | 10.50 | 0.25 || 10.15% | 10.15% |
|
||||
| 3 || 2019-07-01 | 2019-09-30 || 10.50 | 0 | 10.75 | 0.25 || 9.79% | 9.78% |
|
||||
| 4 || 2019-10-01 | 2019-12-31 || 10.75 | 90 | 101.00 | 0.25 || 8.05% | 9.57% |
|
||||
+---++------------+------------++---------------+----------+-------------+------++--------+--------+
|
||||
|
||||
And for annual report, TWR now reports the exact profitability of our
|
||||
investment:
|
||||
|
||||
$ hledger roi -Y --inv investment --pnl "unrealized"
|
||||
+---++------------+------------++---------------+----------+-------------+------++-------+--------+
|
||||
| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR |
|
||||
+===++============+============++===============+==========+=============+======++=======+========+
|
||||
| 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 101.00 | 1.00 || 9.32% | 10.00% |
|
||||
+---++------------+------------++---------------+----------+-------------+------++-------+--------+
|
||||
|
||||
Loading…
Reference in New Issue
Block a user