;doc: update command docs
This commit is contained in:
Simon Michael
parent
2899b46c59
commit
8498894a96
@ -19,42 +19,41 @@ control-d or control-c to exit.
|
||||
|
||||
Features:
|
||||
|
||||
- add tries to provide useful defaults, using the most similar (by
|
||||
description) recent transaction (filtered by the query, if any) as a
|
||||
template.
|
||||
- You can also set the initial defaults with command line arguments.
|
||||
- Readline-style edit keys can be used during data entry.
|
||||
- The tab key will auto-complete whenever possible - accounts,
|
||||
payees/descriptions, dates (yesterday, today, tomorrow). If the
|
||||
input area is empty, it will insert the default value.
|
||||
- A parenthesised transaction code may be entered following a date.
|
||||
- Comments and tags may be entered following a description or amount.
|
||||
- If you make a mistake, enter < at any prompt to go one step
|
||||
backward.
|
||||
- Input prompts are displayed in a different colour when the terminal
|
||||
supports it.
|
||||
- add tries to provide useful defaults, using the most similar (by
|
||||
description) recent transaction (filtered by the query, if any) as a
|
||||
template.
|
||||
- You can also set the initial defaults with command line arguments.
|
||||
- Readline-style edit keys can be used during data entry.
|
||||
- The tab key will auto-complete whenever possible - accounts,
|
||||
payees/descriptions, dates (yesterday, today, tomorrow). If the input
|
||||
area is empty, it will insert the default value.
|
||||
- A parenthesised transaction code may be entered following a date.
|
||||
- Comments and tags may be entered following a description or amount.
|
||||
- If you make a mistake, enter < at any prompt to go one step backward.
|
||||
- Input prompts are displayed in a different colour when the terminal
|
||||
supports it.
|
||||
|
||||
Notes:
|
||||
|
||||
- If you enter a number with no commodity symbol, and you have
|
||||
declared a default commodity with a D directive, you might expect
|
||||
add to add this symbol for you. It does not do this; we assume that
|
||||
if you are using a D directive you prefer not to see the commodity
|
||||
symbol repeated on amounts in the journal.
|
||||
- If you enter a number with no commodity symbol, and you have declared
|
||||
a default commodity with a D directive, you might expect add to add
|
||||
this symbol for you. It does not do this; we assume that if you are
|
||||
using a D directive you prefer not to see the commodity symbol
|
||||
repeated on amounts in the journal.
|
||||
|
||||
Examples:
|
||||
|
||||
- Record new transactions, saving to the default journal file:
|
||||
- Record new transactions, saving to the default journal file:
|
||||
|
||||
hledger add
|
||||
hledger add
|
||||
|
||||
- Add transactions to 2024.journal, but also load 2023.journal for
|
||||
completions:
|
||||
- Add transactions to 2024.journal, but also load 2023.journal for
|
||||
completions:
|
||||
|
||||
hledger add --file 2024.journal --file 2023.journal
|
||||
hledger add --file 2024.journal --file 2023.journal
|
||||
|
||||
- Provide answers for the first four prompts:
|
||||
- Provide answers for the first four prompts:
|
||||
|
||||
hledger add today 'best buy' expenses:supplies '$20'
|
||||
hledger add today 'best buy' expenses:supplies '$20'
|
||||
|
||||
There is a detailed tutorial at https://hledger.org/add.html.
|
||||
|
||||
@ -63,12 +63,12 @@ $ hledger areg checking date:jul
|
||||
|
||||
Each aregister line item shows:
|
||||
|
||||
- the transaction's date (or the relevant posting's date if different,
|
||||
see below)
|
||||
- the names of all the other account(s) involved in this transaction
|
||||
(probably abbreviated)
|
||||
- the total change to this account's balance from this transaction
|
||||
- the account's historical running balance after this transaction.
|
||||
- the transaction's date (or the relevant posting's date if different,
|
||||
see below)
|
||||
- the names of all the other account(s) involved in this transaction
|
||||
(probably abbreviated)
|
||||
- the total change to this account's balance from this transaction
|
||||
- the account's historical running balance after this transaction.
|
||||
|
||||
Transactions making a net change of zero are not shown by default; add
|
||||
the -E/--empty flag to show them.
|
||||
|
||||
@ -74,60 +74,59 @@ 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.
|
||||
|
||||
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.
|
||||
Note there are some variants of the balance command with convenient
|
||||
defaults, which are simpler to use: balancesheet, balancesheetequity,
|
||||
cashflow and incomestatement. When you need more control, then use
|
||||
balance.
|
||||
|
||||
balance features
|
||||
|
||||
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.
|
||||
other balance-like commands as well (bs, cf, is..).
|
||||
|
||||
balance can show..
|
||||
|
||||
- accounts as a list (-l) or a tree (-t)
|
||||
- optionally depth-limited (-[1-9])
|
||||
- sorted by declaration order and name, or by amount
|
||||
- accounts as a list (-l) or a tree (-t)
|
||||
- optionally depth-limited (-[1-9])
|
||||
- sorted by declaration order and name, or by amount
|
||||
|
||||
..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)
|
||||
- or unrealised capital gain/loss (--gain)
|
||||
- or balance changes from sibling postings (--related/-r)
|
||||
- or postings count (--count)
|
||||
- balance changes (the default)
|
||||
- or actual and planned balance changes (--budget)
|
||||
- or value of balance changes (-V)
|
||||
- or change of balance values (--valuechange)
|
||||
- or unrealised capital gain/loss (--gain)
|
||||
- or balance changes from sibling postings (--related/-r)
|
||||
- or postings count (--count)
|
||||
|
||||
..in..
|
||||
|
||||
- one time period (the whole journal period by default)
|
||||
- or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
|
||||
- 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)
|
||||
- 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)
|
||||
- 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)
|
||||
- commodities displayed on the same line or multiple lines (--layout)
|
||||
- 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)
|
||||
- commodities displayed on the same line or multiple lines (--layout)
|
||||
|
||||
This command supports the output destination and output format options,
|
||||
with output formats txt, csv, tsv (Added in 1.32), json, and
|
||||
@ -204,23 +203,23 @@ interpolated like so:
|
||||
|
||||
%[MIN][.MAX](FIELDNAME)
|
||||
|
||||
- MIN pads with spaces to at least this width (optional)
|
||||
- MIN pads with spaces to at least this width (optional)
|
||||
|
||||
- MAX truncates at this width (optional)
|
||||
- MAX truncates at this width (optional)
|
||||
|
||||
- FIELDNAME must be enclosed in parentheses, and can be one of:
|
||||
- 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
|
||||
- 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
|
||||
- %_ - 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
|
||||
@ -228,14 +227,14 @@ 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
|
||||
- %(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
|
||||
|
||||
@ -272,20 +271,19 @@ $ hledger -f examples/sample.journal balance
|
||||
|
||||
Notes:
|
||||
|
||||
- "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).
|
||||
- "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).
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
- Each group of sibling accounts (ie, under a common parent) is sorted
|
||||
separately.
|
||||
|
||||
Depth limiting
|
||||
|
||||
@ -342,8 +340,9 @@ 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).
|
||||
to flip the signs. Or you could use one of the higher-level balance
|
||||
reports (bs, is..), which flip the sign automatically (eg:
|
||||
hledger is -MAS).
|
||||
|
||||
Percentages
|
||||
|
||||
@ -385,41 +384,40 @@ Balance changes in 2008:
|
||||
|
||||
Notes:
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
- The --summary-only flag (--summary also works) hides all but the
|
||||
Total and Average columns (those should be enabled with --row-total
|
||||
and -A/--average).
|
||||
- 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.
|
||||
- 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.
|
||||
- The --summary-only flag (--summary also works) hides all but the Total
|
||||
and Average columns (those should be enabled with --row-total and
|
||||
-A/--average).
|
||||
|
||||
Multi-period reports with many periods can be too wide for easy viewing
|
||||
in the terminal. Here are some ways to handle that:
|
||||
|
||||
- Hide the totals row with -N/--no-total
|
||||
- Filter to a single currency with cur:
|
||||
- Convert to a single currency with -V [--infer-market-price]
|
||||
- Use a more compact layout like --layout=bare
|
||||
- Maximize the terminal window
|
||||
- Reduce the terminal's font size
|
||||
- View with a pager like less, eg:
|
||||
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
|
||||
- Hide the totals row with -N/--no-total
|
||||
- Filter to a single currency with cur:
|
||||
- Convert to a single currency with -V [--infer-market-price]
|
||||
- Use a more compact layout like --layout=bare
|
||||
- Maximize the terminal window
|
||||
- Reduce the terminal's font size
|
||||
- View with a pager like less, eg: 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
|
||||
|
||||
Balance change, end balance
|
||||
|
||||
@ -454,7 +452,7 @@ balances:
|
||||
flag. (-H causes report start date to be ignored when summing
|
||||
postings.)
|
||||
|
||||
Balance report types
|
||||
Balance report modes
|
||||
|
||||
The balance command is quite flexible; here is the full detail on how to
|
||||
control what it reports. If the following seems complicated, don't
|
||||
@ -463,78 +461,83 @@ experimentation to get familiar with all the report modes.
|
||||
|
||||
There are three important option groups:
|
||||
|
||||
hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...
|
||||
hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] ...
|
||||
|
||||
Calculation type
|
||||
Calculation mode
|
||||
|
||||
The basic calculation to perform for each table cell. It is one of:
|
||||
|
||||
- --sum : sum the posting amounts (default)
|
||||
- --budget : sum the amounts, but also show the budget goal amount
|
||||
(for each account/period)
|
||||
- --valuechange : show the change in period-end historical balance
|
||||
values (caused by deposits, withdrawals, and/or market price
|
||||
fluctuations)
|
||||
- --gain : show the unrealised capital gain/loss, (the current valued
|
||||
balance minus each amount's original cost)
|
||||
- --count : show the count of postings
|
||||
- --sum : sum the posting amounts (default)
|
||||
- --budget : sum the amounts, but also show the budget goal amount (for
|
||||
each account/period)
|
||||
- --valuechange : show the change in period-end historical balance
|
||||
values (caused by deposits, withdrawals, and/or market price
|
||||
fluctuations)
|
||||
- --gain : show the unrealised capital gain/loss, (the current valued
|
||||
balance minus each amount's original cost)
|
||||
- --count : show the count of postings
|
||||
|
||||
Accumulation type
|
||||
Accumulation mode
|
||||
|
||||
How amounts should accumulate across a report's subperiods/columns.
|
||||
Another way to say it: which time period's postings should contribute to
|
||||
each cell's calculation. It is one of:
|
||||
|
||||
- --change : calculate with postings from column start to column end,
|
||||
ie "just this column". Typically used to see revenues/expenses.
|
||||
(default for balance, cashflow, incomestatement)
|
||||
- --change : calculate with postings from column start to column end, ie
|
||||
"just this column". Typically used to see revenues/expenses. (default
|
||||
for balance, cashflow, incomestatement)
|
||||
|
||||
- --cumulative : calculate with postings from report start to column
|
||||
end, ie "previous columns plus this column". Typically used to show
|
||||
changes accumulated since the report's start date. Not often used.
|
||||
- --cumulative : calculate with postings from report start to column
|
||||
end, ie "previous columns plus this column". Typically used to show
|
||||
changes accumulated since the report's start date. Not often used.
|
||||
|
||||
- --historical/-H : calculate with postings from journal start to
|
||||
column end, ie "all postings from before report start date until
|
||||
this column's end". Typically used to see historical end balances of
|
||||
assets/liabilities/equity. (default for balancesheet,
|
||||
balancesheetequity)
|
||||
- --historical/-H : calculate with postings from journal start to column
|
||||
end, ie "all postings from before report start date until this
|
||||
column's end". Typically used to see historical end balances of
|
||||
assets/liabilities/equity. (default for balancesheet,
|
||||
balancesheetequity)
|
||||
|
||||
Valuation type
|
||||
Valuation mode
|
||||
|
||||
Which kind of value or cost conversion should be applied, if any, before
|
||||
displaying the report. It is one of:
|
||||
displaying the report. See Cost reporting and Value reporting for more
|
||||
about conversions.
|
||||
|
||||
- no valuation type : don't convert to cost or value (default)
|
||||
- --value=cost[,COMM] : convert amounts to cost (then optionally to
|
||||
some other commodity)
|
||||
- --value=then[,COMM] : convert amounts to market value on transaction
|
||||
dates
|
||||
- --value=end[,COMM] : convert amounts to market value on period end
|
||||
date(s)
|
||||
(default with --valuechange, --gain)
|
||||
- --value=now[,COMM] : convert amounts to market value on today's date
|
||||
- --value=YYYY-MM-DD[,COMM] : convert amounts to market value on
|
||||
another date
|
||||
A valuation (or cost) mode can be selected with the --value option:
|
||||
|
||||
or one of the equivalent simpler flags:
|
||||
- no conversion : don't convert to cost or value (default)
|
||||
- --value=cost[,COMM] : convert amounts to cost (then optionally to some
|
||||
other commodity)
|
||||
- --value=then[,COMM] : convert amounts to market value on transaction
|
||||
dates
|
||||
- --value=end[,COMM] : convert amounts to market value on period end
|
||||
date(s)
|
||||
(default with --valuechange, --gain)
|
||||
- --value=now[,COMM] : convert amounts to market value on today's date
|
||||
- --value=YYYY-MM-DD[,COMM] : convert amounts to market value on another
|
||||
date
|
||||
|
||||
- -B/--cost : like --value=cost (though, note --cost and --value are
|
||||
independent options which can both be used at once)
|
||||
- -V/--market : like --value=end
|
||||
- -X COMM/--exchange COMM : like --value=end,COMM
|
||||
or with the legacy -B/-V/-X options, which are equivalent and easier to
|
||||
type:
|
||||
|
||||
See Cost reporting and Value reporting for more about these.
|
||||
- -B/--cost : like --value=cost
|
||||
- -V/--market : like --value=end
|
||||
- -X COMM/--exchange COMM : like --value=end,COMM
|
||||
|
||||
Combining balance report types
|
||||
Note that --value can also convert to cost, as a convenience; but
|
||||
actually --cost and --value are independent options, and could be used
|
||||
together.
|
||||
|
||||
Most combinations of these options should produce reasonable reports,
|
||||
but if you find any that seem wrong or misleading, let us know. The
|
||||
Combining balance report modes
|
||||
|
||||
Most combinations of these modes 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
|
||||
- --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:
|
||||
@ -564,11 +567,11 @@ valuation show:
|
||||
|
||||
Budget report
|
||||
|
||||
The --budget report type is like a regular balance report, but with two
|
||||
main differences:
|
||||
The --budget report is like a regular balance report, but with two main
|
||||
differences:
|
||||
|
||||
- Budget goals and performance percentages are also shown, in brackets
|
||||
- Accounts which don't have budget goals are hidden by default.
|
||||
- Budget goals and performance percentages are also shown, in brackets
|
||||
- Accounts which don't have budget goals are hidden by default.
|
||||
|
||||
This is useful for comparing planned and actual income, expenses, time
|
||||
usage, etc.
|
||||
@ -628,47 +631,46 @@ version should be relatively robust and intuitive, but you may still
|
||||
find surprises. Here are more notes to help with learning and
|
||||
troubleshooting.
|
||||
|
||||
- In the above example, expenses:bus and expenses:food are shown
|
||||
because they have budget goals during the report period.
|
||||
- In the above example, expenses:bus and expenses:food are shown because
|
||||
they have budget goals during the report period.
|
||||
|
||||
- Their parent expenses is also shown, with budget goals aggregated
|
||||
from the children.
|
||||
- Their parent expenses is also shown, with budget goals aggregated from
|
||||
the children.
|
||||
|
||||
- The subaccounts expenses:food:groceries and expenses:food:dining are
|
||||
not shown since they have no budget goal of their own, but they
|
||||
contribute to expenses:food's actual amount.
|
||||
- The subaccounts expenses:food:groceries and expenses:food:dining are
|
||||
not shown since they have no budget goal of their own, but they
|
||||
contribute to expenses:food's actual amount.
|
||||
|
||||
- Unbudgeted accounts expenses:movies and expenses:gifts are also not
|
||||
shown, but they contribute to expenses's actual amount.
|
||||
- Unbudgeted accounts expenses:movies and expenses:gifts are also not
|
||||
shown, but they contribute to expenses's actual amount.
|
||||
|
||||
- The other unbudgeted accounts income and assets:bank:checking are
|
||||
grouped as <unbudgeted>.
|
||||
- The other unbudgeted accounts income and assets:bank:checking are
|
||||
grouped as <unbudgeted>.
|
||||
|
||||
- --depth or depth: can be used to limit report depth in the usual way
|
||||
(but will not reveal unbudgeted subaccounts).
|
||||
- --depth or depth: can be used to limit report depth in the usual way
|
||||
(but will not reveal unbudgeted subaccounts).
|
||||
|
||||
- Amounts are always inclusive of subaccounts (even in -l/--list
|
||||
mode).
|
||||
- Amounts are always inclusive of subaccounts (even in -l/--list mode).
|
||||
|
||||
- Numbers displayed in a --budget report will not always agree with
|
||||
the totals, because of hidden unbudgeted accounts; this is normal.
|
||||
-E/--empty can be used to reveal the hidden accounts.
|
||||
- Numbers displayed in a --budget report will not always agree with the
|
||||
totals, because of hidden unbudgeted accounts; this is normal.
|
||||
-E/--empty can be used to reveal the hidden accounts.
|
||||
|
||||
- In the periodic rules used for setting budget goals, unbalanced
|
||||
postings are convenient.
|
||||
- In the periodic rules used for setting budget goals, unbalanced
|
||||
postings are convenient.
|
||||
|
||||
- You can filter budget reports with the usual queries, eg to focus on
|
||||
particular accounts. It's common to restrict them to just expenses.
|
||||
(The <unbudgeted> account is occasionally hard to exclude; this is
|
||||
because of date surprises, discussed below.)
|
||||
- You can filter budget reports with the usual queries, eg to focus on
|
||||
particular accounts. It's common to restrict them to just expenses.
|
||||
(The <unbudgeted> account is occasionally hard to exclude; this is
|
||||
because of date surprises, discussed below.)
|
||||
|
||||
- When you have multiple currencies, you may want to convert them to
|
||||
one (-X COMM --infer-market-prices) and/or show just one at a time
|
||||
(cur:COMM). If you do need to show multiple currencies at once,
|
||||
--layout bare can be helpful.
|
||||
- When you have multiple currencies, you may want to convert them to one
|
||||
(-X COMM --infer-market-prices) and/or show just one at a time
|
||||
(cur:COMM). If you do need to show multiple currencies at once,
|
||||
--layout bare can be helpful.
|
||||
|
||||
- You can "roll over" amounts (actual and budgeted) to the next period
|
||||
with --cumulative.
|
||||
- You can "roll over" amounts (actual and budgeted) to the next period
|
||||
with --cumulative.
|
||||
|
||||
See also: https://hledger.org/budgeting.html.
|
||||
|
||||
@ -762,14 +764,14 @@ commands show multi-commodity amounts and commodity symbols. It can
|
||||
improve readability, for humans and/or machines (other software). It has
|
||||
four possible values:
|
||||
|
||||
- --layout=wide[,WIDTH]: commodities are shown on a single line,
|
||||
optionally elided to WIDTH
|
||||
- --layout=tall: each commodity is shown on a separate line
|
||||
- --layout=bare: commodity symbols are in their own column, amounts
|
||||
are bare numbers
|
||||
- --layout=tidy: data is normalised to easily-consumed "tidy" form,
|
||||
with one row per data value. (This one is currently supported only
|
||||
by the balance command.)
|
||||
- --layout=wide[,WIDTH]: commodities are shown on a single line,
|
||||
optionally elided to WIDTH
|
||||
- --layout=tall: each commodity is shown on a separate line
|
||||
- --layout=bare: commodity symbols are in their own column, amounts are
|
||||
bare numbers
|
||||
- --layout=tidy: data is normalised to easily-consumed "tidy" form, with
|
||||
one row per data value. (This one is currently supported only by the
|
||||
balance command.)
|
||||
|
||||
Here are the --layout modes supported by each output format Only CSV
|
||||
output supports all of them:
|
||||
@ -901,9 +903,8 @@ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layo
|
||||
Balance report output
|
||||
|
||||
As noted in Output format, if you choose HTML output (by using -O html
|
||||
or -o somefile.html), it will use the UTF-8 text encoding, And you can
|
||||
create a hledger.css file in the same directory to customise the
|
||||
report's appearance.
|
||||
or -o somefile.html), you can create a hledger.css file in the same
|
||||
directory to customise the report's appearance.
|
||||
|
||||
The HTML and FODS output formats can generate hyperlinks to a
|
||||
hledger-web register view for each account and period. E.g. if your
|
||||
@ -916,33 +917,33 @@ Some 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 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
|
||||
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 -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.
|
||||
- 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 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 --budget expenses
|
||||
Show monthly expenses and budget goals.
|
||||
|
||||
- bal -M --valuechange investments
|
||||
Show monthly change in market value of investment assets.
|
||||
- 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
|
||||
- bal investments --valuechange -D date:lastweek amt:'>1000' -STA [--invert]
|
||||
Show top gainers [or losers] last week
|
||||
|
||||
@ -59,10 +59,9 @@ Flags:
|
||||
This report shows accounts declared with the Cash type (see account
|
||||
types). Or if no such accounts are declared, it shows accounts
|
||||
|
||||
- under a top-level account named asset (case insensitive, plural
|
||||
allowed)
|
||||
- whose name contains some variation of cash, bank, checking or
|
||||
saving.
|
||||
- under a top-level account named asset (case insensitive, plural
|
||||
allowed)
|
||||
- whose name contains some variation of cash, bank, checking or saving.
|
||||
|
||||
More precisely: all accounts matching this case insensitive regular
|
||||
expression:
|
||||
|
||||
@ -27,80 +27,80 @@ Basic checks
|
||||
These important checks are performed by default, by almost all hledger
|
||||
commands:
|
||||
|
||||
- parseable - data files are in a supported format, with no syntax
|
||||
errors and no invalid include directives. This ensures that all
|
||||
files exist and are readable.
|
||||
- parseable - data files are in a supported format, with no syntax
|
||||
errors and no invalid include directives. This ensures that all files
|
||||
exist and are readable.
|
||||
|
||||
- autobalanced - all transactions are balanced, after inferring
|
||||
missing amounts and conversion costs where possible, and then
|
||||
converting to cost. This ensures that each individual transaction is
|
||||
well formed.
|
||||
- autobalanced - all transactions are balanced, after automatically
|
||||
inferring missing amounts and conversion rates and then converting
|
||||
amounts to cost. This ensures that each transaction's entry is well
|
||||
formed.
|
||||
|
||||
- assertions - all balance assertions in the journal are passing.
|
||||
Balance assertions are like canaries in your journal, they catch
|
||||
many problems. They can get in the way sometimes; you can disable
|
||||
them temporarily with -I/--ignore-assertions (unless overridden with
|
||||
-s/--strict or hledger check assertions).
|
||||
- assertions - all balance assertions in the journal are passing.
|
||||
Balance assertions are a strong defense against errors; they help
|
||||
catch many problems. If this check gets in your way, you can disable
|
||||
it with -I/--ignore-assertions. Or you can add that to your config
|
||||
file to disable it by default (and then use -s/--strict or
|
||||
hledger check assertions to enable it).
|
||||
|
||||
Strict checks
|
||||
|
||||
These additional checks are performed by any command when the
|
||||
-s/--strict flag is used (strict mode). Strict mode always enables the
|
||||
balance assertions check, also. These provide extra error-catching power
|
||||
when you are serious about keeping your data clean and free of typos:
|
||||
These additional checks are performed by all commands when the
|
||||
-s/--strict flag is used (strict mode). They provide extra
|
||||
error-catching power to keep your data clean and correct. Strict mode
|
||||
also always enables the assertions check.
|
||||
|
||||
- balanced - like autobalanced, but in conversion transactions, costs
|
||||
must be written explicitly. This ensures some redundancy in the
|
||||
entry, which helps prevent typos.
|
||||
- balanced - like autobalanced, but all conversions between commodities
|
||||
must use explicit cost notation or equity postings. This prevents
|
||||
wrong conversions caused by typos.
|
||||
|
||||
- commodities - all commodity symbols used must be declared. This
|
||||
guards against mistyping or omitting commodity symbols.
|
||||
- commodities - all commodity symbols used must be declared. This guards
|
||||
against mistyping or omitting commodity symbols. Declaring commodities
|
||||
also sets their precision for display and transaction balancing.
|
||||
|
||||
- accounts - all account names used must be declared. This prevents
|
||||
the use of mis-spelled or outdated account names.
|
||||
- accounts - all account names used must be declared. This prevents the
|
||||
use of mis-spelled or outdated account names.
|
||||
|
||||
Other checks
|
||||
|
||||
These other checks are not wanted by everyone, but can be run using the
|
||||
check command:
|
||||
These are not wanted by everyone, but can be run using the check
|
||||
command:
|
||||
|
||||
- ordereddates - within each file, transactions are ordered by date.
|
||||
This is a simple and effective error catcher, and you should use it.
|
||||
Alas! not everyone wants it. If you do, use
|
||||
hledger check -s ordereddates. When enabled, this check is performed
|
||||
early, before balance assertions (because copy-pasted dates are
|
||||
often the root cause of balance assertion failures).
|
||||
- tags - all tags used must be declared. This prevents mis-spelled tag
|
||||
names. Note hledger fairly often finds unintended tags in comments.
|
||||
|
||||
- payees - all payees used by transactions must be declared. This will
|
||||
force you to always use known/declared payee names. For most people
|
||||
this is a bit too restrictive.
|
||||
- payees - all payees used in transactions must be declared. This will
|
||||
force you to declare any new payee name before using it. Most people
|
||||
will probably find this a bit too strict.
|
||||
|
||||
- tags - all tags used by transactions must be declared. This prevents
|
||||
mistyped tag names.
|
||||
- ordereddates - within each file, transactions must be ordered by date.
|
||||
This is a simple and effective error catcher. It's not included in
|
||||
strict mode, but you can add it by running
|
||||
hledger check -s ordereddates. If enabled, this check is performed
|
||||
before balance assertions.
|
||||
|
||||
- recentassertions - all accounts with balance assertions must have a
|
||||
balance assertion within the last 7 days before their latest
|
||||
posting. This encourages you to add balance assertions fairly
|
||||
regularly for your active asset/liability accounts, which in turn
|
||||
should encourage you to check and reconcile with their real world
|
||||
balances fairly regularly. close --assert can be helpful. (The older
|
||||
balance assertions become redundant; you can remove them
|
||||
periodically, or leave them in place, perhaps commented, as
|
||||
documentation.)
|
||||
- recentassertions - all accounts with balance assertions must have one
|
||||
that's within the 7 days before their latest posting. This will
|
||||
encourage adding balance assertions for your active asset/liability
|
||||
accounts, which in turn should encourage you to reconcile regularly
|
||||
with those real world balances - another strong defense against
|
||||
errors. hledger close --assert can help generate assertion entries.
|
||||
Over time the older assertions become somewhat redundant, and you can
|
||||
remove them if you like (they don't affect performance much, but they
|
||||
add some noise to the journal).
|
||||
|
||||
- uniqueleafnames - no two accounts may have the same leaf name. The
|
||||
leaf name is the last colon-separated part of an account name, eg
|
||||
checking in assets:bank:checking. This encourages you to keep those
|
||||
unique, effectively giving each account a short name which is easier
|
||||
to remember and to type in reporting commands.
|
||||
- uniqueleafnames - no two accounts may have the same last account name
|
||||
part (eg the checking in assets:bank:checking). This ensures each
|
||||
account can be matched by a unique short name, easier to remember and
|
||||
to type.
|
||||
|
||||
Custom checks
|
||||
|
||||
You can build your own custom checks with add-on command scripts. See
|
||||
also Cookbook > Scripting. Here are some examples from hledger/bin/:
|
||||
|
||||
- hledger-check-tagfiles - all tag values containing / (a forward
|
||||
slash) exist as file paths
|
||||
- hledger-check-tagfiles - all tag values containing / (a forward slash)
|
||||
exist as file paths
|
||||
|
||||
- hledger-check-fancyassertions - more complex balance assertions are
|
||||
passing
|
||||
- hledger-check-fancyassertions - more complex balance assertions are
|
||||
passing
|
||||
|
||||
@ -136,13 +136,12 @@ close customisation
|
||||
|
||||
In all modes, the following things can be overridden:
|
||||
|
||||
- the accounts to be closed/opened, with account query arguments
|
||||
- the balancing account, with --close-acct=ACCT and/or
|
||||
--open-acct=ACCT
|
||||
- the transaction descriptions, with --close-desc=DESC and
|
||||
--open-desc=DESC
|
||||
- the transaction's tag value, with a --MODE=NEW option argument
|
||||
- the closing/opening dates, with -e OPENDATE
|
||||
- the accounts to be closed/opened, with account query arguments
|
||||
- the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
|
||||
- the transaction descriptions, with --close-desc=DESC and
|
||||
--open-desc=DESC
|
||||
- the transaction's tag value, with a --MODE=NEW option argument
|
||||
- the closing/opening dates, with -e OPENDATE
|
||||
|
||||
By default, the closing date is yesterday, or the journal's end date,
|
||||
whichever is later; and the opening date is always one day after the
|
||||
|
||||
@ -77,35 +77,34 @@ Overlap detection is automatic, and shouldn't require much attention
|
||||
from you, except perhaps at first import (see below). But here's how it
|
||||
works:
|
||||
|
||||
- For each FILE being imported from:
|
||||
- For each FILE being imported from:
|
||||
|
||||
1. hledger reads a file named .latest.FILE file in the same
|
||||
directory, if any. This file contains the latest record date
|
||||
previously imported from FILE, in YYYY-MM-DD format. If multiple
|
||||
records with that date were imported, the date is repeated on N
|
||||
lines.
|
||||
1. hledger reads a file named .latest.FILE file in the same
|
||||
directory, if any. This file contains the latest record date
|
||||
previously imported from FILE, in YYYY-MM-DD format. If multiple
|
||||
records with that date were imported, the date is repeated on N
|
||||
lines.
|
||||
|
||||
2. hledger reads records from FILE. If a latest date was found in
|
||||
step 1, any records before that date, and the first N records on
|
||||
that date, are skipped.
|
||||
2. hledger reads records from FILE. If a latest date was found in
|
||||
step 1, any records before that date, and the first N records on
|
||||
that date, are skipped.
|
||||
|
||||
- After a successful import from all FILEs, without error and without
|
||||
--dry-run, hledger updates each FILE's .latest.FILE for next time.
|
||||
- After a successful import from all FILEs, without error and without
|
||||
--dry-run, hledger updates each FILE's .latest.FILE for next time.
|
||||
|
||||
If this goes wrong, it's relatively easy to repair:
|
||||
|
||||
- You'll notice it before import when you preview with
|
||||
import --dry-run.
|
||||
- Or after import when you try to reconcile your hledger account
|
||||
balances with your bank.
|
||||
- hledger print -f FILE.csv will show all recently downloaded
|
||||
transactions. Compare these with your journal. Copy/paste if needed.
|
||||
- Update your conversion rules and print again, if needed.
|
||||
- You can manually update or remove the .latest file, or use
|
||||
import --catchup FILE.
|
||||
- Download and import more often, eg twice a week, at least while you
|
||||
are learning. It's easier to review and troubleshoot when there are
|
||||
fewer transactions.
|
||||
- You'll notice it before import when you preview with import --dry-run.
|
||||
- Or after import when you try to reconcile your hledger account
|
||||
balances with your bank.
|
||||
- hledger print -f FILE.csv will show all recently downloaded
|
||||
transactions. Compare these with your journal. Copy/paste if needed.
|
||||
- Update your conversion rules and print again, if needed.
|
||||
- You can manually update or remove the .latest file, or use
|
||||
import --catchup FILE.
|
||||
- Download and import more often, eg twice a week, at least while you
|
||||
are learning. It's easier to review and troubleshoot when there are
|
||||
fewer transactions.
|
||||
|
||||
First import
|
||||
|
||||
@ -188,7 +187,7 @@ Here are two kinds of "deduplication" which import does not handle (and
|
||||
generally should not, since these can happen legitimately in financial
|
||||
data):
|
||||
|
||||
- Two or more of the new CSV records are identical, and generate
|
||||
identical new journal entries.
|
||||
- A new CSV record generates a journal entry identical to one(s)
|
||||
already in the journal.
|
||||
- Two or more of the new CSV records are identical, and generate
|
||||
identical new journal entries.
|
||||
- A new CSV record generates a journal entry identical to one(s) already
|
||||
in the journal.
|
||||
|
||||
@ -25,11 +25,11 @@ Flags:
|
||||
--base-url=URLPREFIX in html output, generate links to hledger-web,
|
||||
with this prefix. (Usually the base url shown by
|
||||
hledger-web; can also be relative.)
|
||||
--location add file/line number tags to print output
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, beancount, csv, tsv, html, fods, json, sql.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
one of the above formats selects that format.
|
||||
--location add file/line number tags to print output.
|
||||
```
|
||||
|
||||
The print command displays full journal entries (transactions)
|
||||
|
||||
@ -24,6 +24,7 @@ Flags:
|
||||
--base-url=URLPREFIX in html output, generate links to hledger-web,
|
||||
with this prefix. (Usually the base url shown by
|
||||
hledger-web; can also be relative.)
|
||||
--location add file/line number tags to print output
|
||||
-O --output-format=FMT select the output format. Supported formats:
|
||||
txt, beancount, csv, tsv, html, fods, json, sql.
|
||||
-o --output-file=FILE write output to FILE. A file extension matching
|
||||
@ -84,11 +85,11 @@ With the --round (Added in 1.32) option, print will try increasingly
|
||||
hard to display decimal digits according to the commodity display
|
||||
styles:
|
||||
|
||||
- --round=none show amounts with original precisions (default)
|
||||
- --round=soft add/remove decimal zeros in amounts (except costs)
|
||||
- --round=hard round amounts (except costs), possibly hiding
|
||||
significant digits
|
||||
- --round=all round all amounts and costs
|
||||
- --round=none show amounts with original precisions (default)
|
||||
- --round=soft add/remove decimal zeros in amounts (except costs)
|
||||
- --round=hard round amounts (except costs), possibly hiding significant
|
||||
digits
|
||||
- --round=all round all amounts and costs
|
||||
|
||||
soft is good for non-lossy cleanup, formatting amounts more consistently
|
||||
where it's safe to do so.
|
||||
@ -110,10 +111,10 @@ $ hledger print assets:cash | hledger -f- -I reg expenses:food
|
||||
|
||||
There are some situations where print's output can become unparseable:
|
||||
|
||||
- Value reporting affects posting amounts but not balance assertion or
|
||||
balance assignment amounts, potentially causing those to fail.
|
||||
- Auto postings can generate postings with too many missing amounts.
|
||||
- Account aliases can generate bad account names.
|
||||
- Value reporting affects posting amounts but not balance assertion or
|
||||
balance assignment amounts, potentially causing those to fail.
|
||||
- Auto postings can generate postings with too many missing amounts.
|
||||
- Account aliases can generate bad account names.
|
||||
|
||||
print, other features
|
||||
|
||||
@ -132,6 +133,9 @@ description is most similar to DESC. DESC should contain at least two
|
||||
characters. If there is no similar-enough match, no transaction will be
|
||||
shown and the program exit code will be non-zero.
|
||||
|
||||
With --location, print adds the source file and line number to every
|
||||
transaction, as a tag.
|
||||
|
||||
print output format
|
||||
|
||||
This command also supports the output destination and output format
|
||||
@ -141,28 +145,28 @@ csv, tsv (Added in 1.32), json and sql.
|
||||
The beancount format tries to produce Beancount-compatible output, as
|
||||
follows:
|
||||
|
||||
- Transaction and postings with unmarked status are converted to
|
||||
cleared (*) status.
|
||||
- Transactions' payee and note are backslash-escaped and
|
||||
double-quote-escaped and wrapped in double quotes.
|
||||
- Transaction tags are copied to Beancount #tag format.
|
||||
- Commodity symbols are converted to upper case, and a small number of
|
||||
currency symbols like $ are converted to the corresponding currency
|
||||
names.
|
||||
- Account name parts are capitalised and unsupported characters are
|
||||
replaced with -. If an account name part does not begin with a
|
||||
letter, or if the first part is not Assets, Liabilities, Equity,
|
||||
Income, or Expenses, an error is raised. (Use --alias options to
|
||||
bring your accounts into compliance.)
|
||||
- An open directive is generated for each account used, on the
|
||||
earliest transaction date.
|
||||
- Transaction and postings with unmarked status are converted to cleared
|
||||
(*) status.
|
||||
- Transactions' payee and note are backslash-escaped and
|
||||
double-quote-escaped and wrapped in double quotes.
|
||||
- Transaction tags are copied to Beancount #tag format.
|
||||
- Commodity symbols are converted to upper case, and a small number of
|
||||
currency symbols like $ are converted to the corresponding currency
|
||||
names.
|
||||
- Account name parts are capitalised and unsupported characters are
|
||||
replaced with -. If an account name part does not begin with a letter,
|
||||
or if the first part is not Assets, Liabilities, Equity, Income, or
|
||||
Expenses, an error is raised. (Use --alias options to bring your
|
||||
accounts into compliance.)
|
||||
- An open directive is generated for each account used, on the earliest
|
||||
transaction date.
|
||||
|
||||
Some limitations:
|
||||
|
||||
- Balance assertions are removed.
|
||||
- Balance assignments become missing amounts.
|
||||
- Virtual and balanced virtual postings become regular postings.
|
||||
- Directives are not converted.
|
||||
- Balance assertions are removed.
|
||||
- Balance assignments become missing amounts.
|
||||
- Virtual and balanced virtual postings become regular postings.
|
||||
- Directives are not converted.
|
||||
|
||||
Here's an example of print's CSV output:
|
||||
|
||||
@ -180,15 +184,15 @@ $ hledger print -Ocsv
|
||||
"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
|
||||
"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
|
||||
|
||||
- There is one CSV record per posting, with the parent transaction's
|
||||
fields repeated.
|
||||
- The "txnidx" (transaction index) field shows which postings belong
|
||||
to the same transaction. (This number might change if transactions
|
||||
are reordered within the file, files are parsed/included in a
|
||||
different order, etc.)
|
||||
- The amount is separated into "commodity" (the symbol) and "amount"
|
||||
(numeric quantity) fields.
|
||||
- The numeric amount is repeated in either the "credit" or "debit"
|
||||
column, for convenience. (Those names are not accurate in the
|
||||
accounting sense; it just puts negative amounts under credit and
|
||||
zero or greater amounts under debit.)
|
||||
- There is one CSV record per posting, with the parent transaction's
|
||||
fields repeated.
|
||||
- The "txnidx" (transaction index) field shows which postings belong to
|
||||
the same transaction. (This number might change if transactions are
|
||||
reordered within the file, files are parsed/included in a different
|
||||
order, etc.)
|
||||
- The amount is separated into "commodity" (the symbol) and "amount"
|
||||
(numeric quantity) fields.
|
||||
- The numeric amount is repeated in either the "credit" or "debit"
|
||||
column, for convenience. (Those names are not accurate in the
|
||||
accounting sense; it just puts negative amounts under credit and zero
|
||||
or greater amounts under debit.)
|
||||
|
||||
@ -22,19 +22,19 @@ until you exit and restart the REPL.
|
||||
|
||||
The command syntax is the same as with run:
|
||||
|
||||
- enter one hledger command at a time, without the usual hledger first
|
||||
word
|
||||
- empty lines and comment text from # to end of line are ignored
|
||||
- use single or double quotes to quote arguments when needed
|
||||
- type exit or quit or control-D to exit the REPL.
|
||||
- enter one hledger command at a time, without the usual hledger first
|
||||
word
|
||||
- empty lines and comment text from # to end of line are ignored
|
||||
- use single or double quotes to quote arguments when needed
|
||||
- type exit or quit or control-D to exit the REPL.
|
||||
|
||||
While it is running, the REPL remembers your command history, and you
|
||||
can navigate in the usual ways:
|
||||
|
||||
- Keypad or Emacs navigation keys to edit the current command line
|
||||
- UP/DOWN or control-P/control-N to step back/forward through history
|
||||
- control-R to search for a past command
|
||||
- TAB to complete file paths.
|
||||
- Keypad or Emacs navigation keys to edit the current command line
|
||||
- UP/DOWN or control-P/control-N to step back/forward through history
|
||||
- control-R to search for a past command
|
||||
- TAB to complete file paths.
|
||||
|
||||
Generally repl command lines should feel much like the normal hledger
|
||||
CLI, but you may find differences. repl is a little stricter; eg it
|
||||
|
||||
@ -126,12 +126,12 @@ rewrite vs. print --auto
|
||||
This command predates print --auto, and currently does much the same
|
||||
thing, but with these differences:
|
||||
|
||||
- with multiple files, rewrite lets rules in any file affect all other
|
||||
files. print --auto uses standard directive scoping; rules affect
|
||||
only child files.
|
||||
- with multiple files, rewrite lets rules in any file affect all other
|
||||
files. print --auto uses standard directive scoping; rules affect only
|
||||
child files.
|
||||
|
||||
- rewrite's query limits which transactions can be rewritten; all are
|
||||
printed. print --auto's query limits which transactions are printed.
|
||||
- rewrite's query limits which transactions can be rewritten; all are
|
||||
printed. print --auto's query limits which transactions are printed.
|
||||
|
||||
- rewrite applies rules specified on command line or in the journal.
|
||||
print --auto applies rules specified in the journal.
|
||||
- rewrite applies rules specified on command line or in the journal.
|
||||
print --auto applies rules specified in the journal.
|
||||
|
||||
@ -31,19 +31,19 @@ Price directives will be taken into account if you supply appropriate
|
||||
|
||||
Note, in some cases this report can fail, for these reasons:
|
||||
|
||||
- Error (NotBracketed): No solution for Internal Rate of Return (IRR).
|
||||
Possible causes: IRR is huge (>1000000%), balance of investment
|
||||
becomes negative at some point in time.
|
||||
- Error (SearchFailed): Failed to find solution for Internal Rate of
|
||||
Return (IRR). Either search does not converge to a solution, or
|
||||
converges too slowly.
|
||||
- Error (NotBracketed): No solution for Internal Rate of Return (IRR).
|
||||
Possible causes: IRR is huge (>1000000%), balance of investment
|
||||
becomes negative at some point in time.
|
||||
- Error (SearchFailed): Failed to find solution for Internal Rate of
|
||||
Return (IRR). Either search does not converge to a solution, or
|
||||
converges too slowly.
|
||||
|
||||
Examples:
|
||||
|
||||
- Using roi to compute total return of investment in stocks:
|
||||
https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger
|
||||
- Using roi to compute total return of investment in stocks:
|
||||
https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger
|
||||
|
||||
- Cookbook > Return on Investment: https://hledger.org/roi.html
|
||||
- Cookbook > Return on Investment: https://hledger.org/roi.html
|
||||
|
||||
Spaces and special characters in --inv and --pnl
|
||||
|
||||
@ -71,23 +71,23 @@ 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:
|
||||
- "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
|
||||
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
|
||||
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:
|
||||
- "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
|
||||
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
|
||||
@ -167,9 +167,9 @@ cash in-flows and out-flows.
|
||||
|
||||
References:
|
||||
|
||||
- Explanation of rate of return
|
||||
- Explanation of IRR
|
||||
- Explanation of TWR
|
||||
- IRR vs TWR
|
||||
- Examples of computing IRR and TWR and discussion of the limitations
|
||||
of both metrics
|
||||
- Explanation of rate of return
|
||||
- Explanation of IRR
|
||||
- Explanation of TWR
|
||||
- IRR vs TWR
|
||||
- Examples of computing IRR and TWR and discussion of the limitations of
|
||||
both metrics
|
||||
|
||||
@ -10,11 +10,11 @@ This command is experimental and could change in the future.
|
||||
|
||||
You can use run in three ways:
|
||||
|
||||
- hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command
|
||||
line, separated by --
|
||||
- hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more
|
||||
files
|
||||
- cat SCRIPTFILE1 | hledger run - read commands from standard input.
|
||||
- hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command
|
||||
line, separated by --
|
||||
- hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more
|
||||
files
|
||||
- cat SCRIPTFILE1 | hledger run - read commands from standard input.
|
||||
|
||||
run first loads the input file(s) specified by LEDGER_FILE or by -f
|
||||
options, in the usual way. Then it runs each command in turn, each using
|
||||
@ -31,14 +31,14 @@ twice as fast).
|
||||
Command scripts, whether in a file or written on the command line, have
|
||||
a simple syntax:
|
||||
|
||||
- each line may contain a single hledger command and its arguments,
|
||||
without the usual hledger first word
|
||||
- empty lines are ignored
|
||||
- text from # to end of line is a comment, and ignored
|
||||
- you can use single or double quotes to quote arguments when needed,
|
||||
as on the command line
|
||||
- these extra commands are available: echo TEXT prints some text, and
|
||||
exit or quit ends the run.
|
||||
- each line may contain a single hledger command and its arguments,
|
||||
without the usual hledger first word
|
||||
- empty lines are ignored
|
||||
- text from # to end of line is a comment, and ignored
|
||||
- you can use single or double quotes to quote arguments when needed, as
|
||||
on the command line
|
||||
- these extra commands are available: echo TEXT prints some text, and
|
||||
exit or quit ends the run.
|
||||
|
||||
On unix systems you can use #!/usr/bin/env hledger run in the first line
|
||||
of a command file to make it a runnable script. If that gives an error,
|
||||
|
||||
@ -1,6 +1,61 @@
|
||||
setup
|
||||
|
||||
Check and help set up various installation things.
|
||||
Check the status of the hledger installation.
|
||||
|
||||
Flags:
|
||||
no command-specific flags
|
||||
|
||||
setup tests your hledger installation and prints a list of results,
|
||||
sometimes with helpful hints. This is a good first command to run after
|
||||
installing hledger. Also after upgrading, or when something's not
|
||||
working, or just when you want a reminder of where things are.
|
||||
|
||||
It makes one network request to detect the latest hledger release
|
||||
version. It's ok if this fails or times out. It will use ANSI color by
|
||||
default, unless disabled by NO_COLOR or --color=n. It does not use a
|
||||
pager or a config file.
|
||||
|
||||
It expects that the hledger version you are running is installed in your
|
||||
PATH. If not, it will stop until you have done that (to keep things
|
||||
simple).
|
||||
|
||||
Example:
|
||||
|
||||
$ hledger setup
|
||||
Checking your hledger setup..
|
||||
Legend: good, neutral, unknown, warning
|
||||
|
||||
hledger
|
||||
* is a released version ? no hledger 1.42.99-gbca4b39c5-20250425, mac-aarch64
|
||||
* is up to date ? yes 1.42.99 installed, latest is 1.42.1
|
||||
* is a native binary for this machine ? yes aarch64
|
||||
* is installed in PATH ? yes /Users/simon/.local/bin/hledger
|
||||
* has a system text encoding configured ? yes UTF-8, data files should use this encoding
|
||||
* has a user config file ? (optional) no
|
||||
* current directory has a local config ? yes /Users/simon/src/hledger/hledger.conf
|
||||
* the config file is readable ? yes /Users/simon/src/hledger/hledger.conf
|
||||
|
||||
terminal
|
||||
* the NO_COLOR variable is defined ? no
|
||||
* --color is configured by config file ? no
|
||||
* hledger will use color by default ? yes
|
||||
* the PAGER variable is defined ? yes less
|
||||
* --pager is configured by config file ? no
|
||||
* hledger will use a pager when needed ? yes /opt/homebrew/bin/less
|
||||
* the LESS variable is defined ? yes
|
||||
* the HLEDGER_LESS variable is defined ? no
|
||||
* adjusting LESS variable for color etc. ? yes
|
||||
* --pretty is enabled by config file ? no tables will use ASCII characters
|
||||
* bash shell completions are installed ? ?
|
||||
* zsh shell completions are installed ? ?
|
||||
|
||||
journal
|
||||
* the LEDGER_FILE variable is defined ? yes /Users/simon/finance/2025/2025.journal
|
||||
* a default journal file is readable ? yes /Users/simon/finance/2025/2025.journal
|
||||
* it includes additional files ? yes 15
|
||||
* all commodities are declared ? yes 10
|
||||
* all accounts are declared ? yes 160
|
||||
* all accounts have types ? no 14 untyped
|
||||
* accounts of each type were detected ? yes ALERXCV
|
||||
* commodities/accounts are checked ? no use -s to check commodities/accounts
|
||||
* balance assertions are checked ? yes use -I to ignore assertions
|
||||
|
||||
@ -16,13 +16,12 @@ included files, and commodity names.
|
||||
|
||||
It also shows some run time statistics:
|
||||
|
||||
- elapsed time
|
||||
- throughput: the number of transactions processed per second
|
||||
- live: the peak memory in use by the program to do its work
|
||||
- alloc: the peak memory allocation from the OS as seen by GHC.
|
||||
Measuring this externally, eg with GNU time, is more accurate;
|
||||
usually that will be a larger number; sometimes (with swapping?)
|
||||
smaller.
|
||||
- elapsed time
|
||||
- throughput: the number of transactions processed per second
|
||||
- live: the peak memory in use by the program to do its work
|
||||
- alloc: the peak memory allocation from the OS as seen by GHC.
|
||||
Measuring this externally, eg with GNU time, is more accurate; usually
|
||||
that will be a larger number; sometimes (with swapping?) smaller.
|
||||
|
||||
The stats command's run time is similar to that of a balance report.
|
||||
|
||||
|
||||
@ -14,11 +14,12 @@ sanity-check the installed hledger executable on your platform. All
|
||||
tests are expected to pass - if you ever see a failure, please report as
|
||||
a bug!
|
||||
|
||||
This command also accepts tasty test runner options, written after a --
|
||||
(double hyphen). Eg to run only the tests in Hledger.Data.Amount, with
|
||||
ANSI colour codes disabled:
|
||||
Any arguments before a -- argument will be passed to the tasty test
|
||||
runner as test-selecting -p patterns, and any arguments after -- will be
|
||||
passed to tasty unchanged.
|
||||
|
||||
$ hledger test -- -pData.Amount --color=never
|
||||
Examples:
|
||||
|
||||
For help on these, see https://github.com/feuerbach/tasty#options
|
||||
(-- --help currently doesn't show them).
|
||||
$ hledger test # run all unit tests
|
||||
$ hledger test balance # run tests with "balance" in their name
|
||||
$ hledger test -- -h # show tasty's options
|
||||
|
||||
Loading…
Reference in New Issue
Block a user