slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: update command help

Browse Source
This commit is contained in:
Simon Michael 2023-12-15 13:59:12 -10:00
parent ac50d8c5a6
commit fccaf0d35a
1 changed files with 124 additions and 243 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

367
hledger/Hledger/Cli/Commands/Balance.txt
View File

@ -498,137 +498,121 @@ valuation show:
Budget report Budget report
The --budget report type activates extra columns showing any budget The --budget report type is like a regular balance report, but with two
goals for each account and period. The budget goals are defined by main differences:
periodic transactions. This is useful for comparing planned and actual
income, expenses, time usage, etc.
For example, you can take average monthly expenses in the common expense - Budget goals and performance percentages are also shown, in brackets
categories to construct a minimal monthly budget: - Accounts which don't have budget goals are hidden by default.
This is useful for comparing planned and actual income, expenses, time
usage, etc.
Periodic transaction rules are used to define budget goals. For example,
here's a periodic rule defining monthly goals for bus travel and food
expenses:
;; Budget ;; Budget
~ monthly ~ monthly
income $2000 (expenses:bus) $30
expenses:food $400 (expenses:food) $400
expenses:bus $50
expenses:movies $30 After recording some actual expenses,
assets:bank:checking
;; Two months worth of expenses ;; Two months worth of expenses
2017-11-01 2017-11-01
income $1950 income $-1950
expenses:food $396 expenses:bus $35
expenses:bus $49 expenses:food:groceries $310
expenses:movies $30 expenses:food:dining $42
expenses:supplies $20 expenses:movies $38
assets:bank:checking assets:bank:checking
2017-12-01 2017-12-01
income $2100 income $-2100
expenses:food $412 expenses:bus $53
expenses:bus $53 expenses:food:groceries $380
expenses:gifts $100 expenses:food:dining $32
expenses:gifts $100
assets:bank:checking assets:bank:checking
You can now see a monthly budget report: we can see a budget report like this:
$ hledger balance -M --budget $ hledger bal -M --budget
Budget performance in 2017/11/01-2017/12/31: Budget performance in 2017-11-01..2017-12-31:
|| Nov Dec || Nov Dec
======================++==================================================== ===============++============================================
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] <unbudgeted> || $-425 $-565
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] expenses || $425 [ 99% of $430] $565 [131% of $430]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] expenses:bus || $35 [117% of $30] $53 [177% of $30]
expenses || $495 [ 103% of $480] $565 [ 118% of $480] expenses:food || $352 [ 88% of $400] $412 [103% of $400]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] ---------------++--------------------------------------------
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] || 0 [ 0% of $430] 0 [ 0% of $430]
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
This is different from a normal balance report in several ways. This is "goal-based budgeting"; you define goals for accounts and
Currently: periods, often recurring, and hledger shows performance relative to the
goals. This contrasts with "envelope budgeting", which is more detailed
and strict - useful when cash is tight, but also quite a bit more work.
https://plaintextaccounting.org/Budgeting has more on this topic.
- Accounts with budget goals during the report period, and their Using the budget report
parents, are shown.
- Their subaccounts are not shown (regardless of the depth setting).
- Accounts without budget goals, if any, are aggregated and shown as
"<unbudgeted>".
- Amounts are always inclusive (subaccount-including), even in list
mode.
- After each actual amount, the corresponding goal amount and
percentage of goal reached are also shown, in square brackets.
This means that the numbers displayed will not always add up! Eg above, Historically this report has been confusing and fragile. hledger's
the expenses actual amount includes the gifts and supplies transactions, version should be relatively robust and intuitive, but you may still
but the expenses:gifts and expenses:supplies accounts are not shown, as find surprises. Here are more notes to help with learning and
they have no budget amounts declared. troubleshooting.
This can be confusing. When you need to make things clearer, use the - In the above example, expenses:bus and expenses:food are shown
-E/--empty flag, which will reveal all accounts including unbudgeted because they have budget goals during the report period.
ones, giving the full picture. Eg:
$ hledger balance -M --budget --empty - Their parent expenses is also shown, with budget goals aggregated
Budget performance in 2017/11/01-2017/12/31: from the children.
|| Nov Dec - The subaccounts expenses:food:groceries and expenses:food:dining are
======================++==================================================== not shown since they have no budget goal of their own, but they
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] contribute to expenses:food's actual amount.
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
expenses:gifts || 0 $100
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
expenses:supplies || $20 0
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
You can roll over unspent budgets to next period with --cumulative: - Unbudgeted accounts expenses:movies and expenses:gifts are also not
shown, but they contribute to expenses's actual amount.
$ hledger balance -M --budget --cumulative - The other unbudgeted accounts income and assets:bank:checking are
Budget performance in 2017/11/01-2017/12/31: grouped as <unbudgeted>.
|| Nov Dec - --depth or depth: can be used to limit report depth in the usual way
======================++==================================================== (but will not reveal unbudgeted subaccounts).
assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
----------------------++----------------------------------------------------
|| 0 [ 0] 0 [ 0]
It's common to limit budgets/budget reports to just expenses - Amounts are always inclusive of subaccounts (even in -l/--list
mode).
hledger bal -M --budget expenses - 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.
or just revenues and expenses (eg, using account types): - In the periodic rules used for setting budget goals, unbalanced
postings are convenient.
hledger bal -M --budget type:rx - 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.)
It's also common to limit or convert them to a single currency (cur:COMM - When you have multiple currencies, you may want to convert them to
or -X COMM [--infer-market-prices]). If showing multiple currencies, one (-X COMM --infer-market-prices) and/or show just one at a time
--layout bare or --layout tall can help. (cur:COMM). If you do need to show multiple currencies at once,
--layout bare can be helpful.
For more examples and notes, see Budgeting. - You can "roll over" amounts (actual and budgeted) to the next period
with --cumulative.
Budget report start date See also: https://hledger.org/budgeting.html.
This might be a bug, but for now: when making budget reports, it's a Budget date surprises
good idea to explicitly set the report's start date to the first day of
a reporting period, because a periodic rule like ~ monthly generates its With small data, or when starting out, some of the generated budget goal
transactions on the 1st of each month, and if your journal has no transaction dates might fall outside the report periods. Eg with the
regular transactions on the 1st, the default report start date could following journal and report, the first period appears to have no
exclude that budget goal, which can be a little surprising. Eg here the expenses:food budget. (Also the <unbudgeted> account should be excluded
default report period is just the day of 2020-01-15: by the expenses query, but isn't.):
~ monthly in 2020 ~ monthly in 2020
(expenses:food) $500 (expenses:food) $500
@ -637,123 +621,28 @@ default report period is just the day of 2020-01-15:
expenses:food $400 expenses:food $400
assets:checking assets:checking
$ hledger bal expenses --budget $ hledger bal --budget expenses
Budget performance in 2020-01-15: Budget performance in 2020-01-15:
|| 2020-01-15 || 2020-01-15
==============++============ ===============++====================
<unbudgeted> || $400 <unbudgeted> || $400
--------------++------------ expenses:food || 0 [ 0% of $500]
|| $400 ---------------++--------------------
|| $400 [80% of $500]
To avoid this, specify the budget report's period, or at least the start In this case, the budget goal transactions are generated on first days
date, with -b/-e/-p/date:, to ensure it includes the budget goal of of month (this can be seen with
transactions (periodic transactions) that you want. Eg, adding hledger print --forecast tag:generated expenses). Whereas the report
-b 2020/1/1 to the above: period defaults to just the 15th day of january (this can be seen from
the report table's column headings).
$ hledger bal expenses --budget -b 2020/1/1 To fix this kind of thing, be more explicit about the report period
Budget performance in 2020-01-01..2020-01-15: (and/or the periodic rules' dates). In this case, adding -b 2020 does
the trick.
|| 2020-01-01..2020-01-15
===============++========================
expenses:food || $400 [80% of $500]
---------------++------------------------
|| $400 [80% of $500]
Budgets and subaccounts
You can add budgets to any account in your account hierarchy. If you
have budgets on both parent account and some of its children, then
budget(s) of the child account(s) would be added to the budget of their
parent, much like account balances behave.
In the most simple case this means that once you add a budget to any
account, all its parents would have budget as well.
To illustrate this, consider the following budget:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
With this, monthly budget for electronics is defined to be $100 and
budget for personal expenses is an additional $1000, which implicitly
means that budget for both expenses:personal and expenses is $1100.
Transactions in expenses:personal:electronics will be counted both
towards its $100 budget and $1100 of expenses:personal , and
transactions in any other subaccount of expenses:personal would be
counted towards only towards the budget of expenses:personal.
For example, let's consider these transactions:
~ monthly from 2019/01
expenses:personal $1,000.00
expenses:personal:electronics $100.00
liabilities
2019/01/01 Google home hub
expenses:personal:electronics $90.00
liabilities $-90.00
2019/01/02 Phone screen protector
expenses:personal:electronics:upgrades $10.00
liabilities
2019/01/02 Weekly train ticket
expenses:personal:train tickets $153.00
liabilities
2019/01/03 Flowers
expenses:personal $30.00
liabilities
As you can see, we have transactions in
expenses:personal:electronics:upgrades and
expenses:personal:train tickets, and since both of these accounts are
without explicitly defined budget, these transactions would be counted
towards budgets of expenses:personal:electronics and expenses:personal
accordingly:
$ hledger balance --budget -M
Budget performance in 2019/01:
|| Jan
===============================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
liabilities || $-283.00 [ 26% of $-1100.00]
-------------------------------++-------------------------------
|| 0 [ 0]
And with --empty, we can get a better picture of budget allocation and
consumption:
$ hledger balance --budget -M --empty
Budget performance in 2019/01:
|| Jan
========================================++===============================
expenses || $283.00 [ 26% of $1100.00]
expenses:personal || $283.00 [ 26% of $1100.00]
expenses:personal:electronics || $100.00 [ 100% of $100.00]
expenses:personal:electronics:upgrades || $10.00
expenses:personal:train tickets || $153.00
liabilities || $-283.00 [ 26% of $-1100.00]
----------------------------------------++-------------------------------
|| 0 [ 0]
Selecting budget goals Selecting budget goals
The budget report evaluates periodic transaction rules to generate
special "goal transactions", which generate the goal amounts for each
account in each report subperiod. When troubleshooting, you can use
print --forecast to show these as forecasted transactions:
$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
By default, the budget report uses all available periodic transaction By default, the budget report uses all available periodic transaction
rules to generate goals. This includes rules with a different report rules to generate goals. This includes rules with a different report
interval from your report. Eg if you have daily, weekly and monthly interval from your report. Eg if you have daily, weekly and monthly
@ -764,49 +653,41 @@ You can select a subset of periodic rules by providing an argument to
the --budget flag. --budget=DESCPAT will match all periodic rules whose the --budget flag. --budget=DESCPAT will match all periodic rules whose
description contains DESCPAT, a case-insensitive substring (not a description contains DESCPAT, a case-insensitive substring (not a
regular expression or query). This means you can give your periodic regular expression or query). This means you can give your periodic
rules descriptions (remember that two spaces are needed), and then rules descriptions (remember that two spaces are needed between period
select from multiple budgets defined in your journal. expression and description), and then select from multiple budgets
defined in your journal.
Budget vs forecast Budgeting vs forecasting
hledger --forecast ... and hledger balance --budget ... are separate --budget and --forecast both use the periodic transaction rules in the
features, though both of them use the periodic transaction rules defined journal to generate temporary transactions for reporting purposes.
in the journal, and both of them generate temporary transactions for However they are separate features - though you can use both at the same
reporting purposes ("forecast transactions" and "budget goal time if you want. Here are some differences between them:
transactions", respectively). You can use both features at the same time
if you want. Here are some differences between them, as of hledger 1.29:
CLI: 1. --budget is a command-specific option; it selects the budget report.
- --forecast is a general hledger option, usable with any command --forecast is a general option; forecasting works with all reports.
- --budget is a balance command option, usable only with that command.
Visibility of generated transactions: 2. --budget uses all periodic rules; --budget=DESCPAT uses just the
rules matched by DESCPAT.
- forecast transactions are visible in any report, like ordinary --forecast uses all periodic rules.
transactions
- budget goal transactions are invisible except for the goal amounts
they produce in --budget reports.
Periodic transaction rules: 3. --budget's budget goal transactions are invisible, except that they
produce goal amounts.
- --forecast uses all available periodic transaction rules --forecast's forecast transactions are visible, and appear in
- --budget uses all periodic rules (--budget) or a selected subset reports.
(--budget=DESCPAT)
Period of generated transactions: 4. --budget generates budget goal transactions throughout the report
period, optionally restricted by periods specified in the periodic
transaction rules.
- --forecast generates forecast transactions --forecast generates forecast transactions from after the last
- from after the last regular transaction to the end of the report regular transaction, to the end of the report period; while
period (--forecast) --forecast=PERIODEXPR generates them throughout the specified
- or, during a specified period (--forecast=PERIODEXPR) period; both optionally restricted by periods specified in the
- possibly further restricted by a period specified in the periodic transaction rules.
periodic transaction rule
- and always restricted within the bounds of the report period
- --budget generates budget goal transactions
- throughout the report period
- possibly restricted by a period specified in the periodic
transaction rule.
Balance report layout Balance report layout