diff --git a/bin/hledger-budget.hs b/bin/hledger-budget.hs index 82ec4ba19..cbef88269 100755 --- a/bin/hledger-budget.hs +++ b/bin/hledger-budget.hs @@ -5,6 +5,17 @@ --package text -} {-# LANGUAGE OverloadedStrings #-} +{- + +hledger-budget REPORT-COMMAND [--no-offset] [--no-buckets] [OPTIONS...] + +Perform some subset of reports available in core hledger but process automated +and periodic transactions. Also simplify tree of accounts to ease view of +"budget buckets". + +This addon tries to simulate behavior of "ledger --budget". + +-} import Control.Arrow (first) import Data.Maybe import Data.List diff --git a/hledger/doc/commands.m4.md b/hledger/doc/commands.m4.md index c6881f71b..2143207bb 100644 --- a/hledger/doc/commands.m4.md +++ b/hledger/doc/commands.m4.md @@ -1014,6 +1014,133 @@ update according to list of input files specified via `--file` options and Be careful. Whole transaction being re-formatted in a style of output from `hledger print`. +## budget +This tool helps to get reports useful for planning and tracking the budget. + +For people familiar with [`ledger` +budgeting](http://www.ledger-cli.org/3.0/doc/ledger3.html#Budgeting) may +consider this tool as an alias to `ledger --budget`. + +With this tool you may either use so called periodic transactions that being +issued with each new period or use a family of approaches with automated +transactions. You may want to look at [budgeting section of +plaintextaccounting](http://plaintextaccounting.org/#budgeting). + +Periodic transaction that being interpreted by this tool may look like: + +```ledger +~ monthly from 2017/3 + income:salary $-4,000.00 + expenses:taxes $1,000 + expenses:housing:rent $1,200 + expenses:grocery $400 + expenses:leisure $200 + expenses:health $200 + expenses $100 + assets:savings +``` + +Header of such entries starts with `'~'` (tilde symbol) following by an +interval with an effect period when transactions should be injected. + +Effect of declaring such periodic transaction is: + +- Transactions will be injected at the beginning of each period. I.e. for + monthly it will always refer to 1st day of month. +- Injected transaction will have inverted amounts to offset existing associated + expenses. I.e. for this example negative balance indicates how much you have + within your budget and positive amounts indicates how far you off from your + budget. +- Set of accounts across of all periodic transactions will form kinda buckets + where rest of the accounts will be sorted into. Each account not mentioned in + any of periodic transaction will be dropped without changing of balance for + parent account. I.e. for this example postings for `expenses:leisure:movie` + will contribute to the balance of `expenses:leisure` only in reports. + +Note that beside a periodic transaction all automated transactions will be +handled in a similar way how they are handled in `rewrite` command. + +### Bucketing +It is very common to have more expense accounts than budget +"envelopes"/"buckets". For this reason all periodic transactions are treated as +a source of information about your budget "buckets". + +I.e. example from previous section will build a sub-tree of accounts that look like + +``` +assets:savings +expenses + taxes + housing:rent + grocery + leisure + health +income:salary +``` + +All accounts used in your transactions journal files will be classified +according to that tree to contribute to an appropriate bucket of budget. + +Everything else will be collected under virtual account `` to give +you an idea of what parts of your accounts tree is not budgeted. For example +`liabilities` will contributed to that entry. + +### Reports +You can use `budget` command to produce next reports: + +- `balance` - the most important one to track how you follow your budget. If + you use month-based budgeting you may want to use `--monthly` and + `--row-total` option to see how you are doing through the months. You also + may find it useful to add `--tree` option to see aggregated totals per + intermediate node of accounts tree. +- `register` - might be useful if you want to see long history (ex. `--weekly`) + that is too wide to fit into your terminal. +- `print` - this is mostly to check what actually happens. But you may use it + if you prefer to generate budget transactions and store it in a separate + journal for some less popular budgeting scheme. + +### Extra options for reports +You may tweak behavior of this command with additional options `--no-offset` and `--no-bucketing`. + +- Don't use these options if your budgeting schema includes both periodic + transactions, and "bucketing". Unless you want to figure out how your + budgeting might look like. You may find helpful values of average column from + report + +```shell +$ hledger budget -- bal --period 'monthly to last month' --no-offset --average +``` + +- Use `--no-offset` and `--no-bucketing` if your schema fully relies on + automated transactions and hand-crafted budgeting transactions. In this mode + only automated transactions will be processed. I.e. when you journal looks + something like + +```ledger += ^expenses:food + budget:gifts *-1 + assets:budget *1 + +2017/1/1 Budget for Jan + assets:bank $-1000 + budget:gifts $200 + budget:misc +``` + +- Use `--no-bucketing` only if you want to produce a valid journal. For example + when you want to pass it as an input for other `hledger` command. Most people + will find this useless. + +### Recommendations +- Automated transaction should follow same rules that usual transactions follow + (i.e. keep balance for real and balanced virtual postings). +- Don't change the balance of real asset and liability accounts for which you + usually put assertions. Keep in mind that `hledger` do not apply modification + transactions. +- In periodic transactions to offset your budget use either top-level account + like `Assets` or introduce a "virtual" one like `Assets:Bank:Budget` that + will be a child to the one you want to offset. + ## ui Curses-style interface, see [hledger-ui](hledger-ui.html).