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

;doc:journal: periodic txns, auto postings: edits

Browse Source
This commit is contained in:
Simon Michael 2023-12-27 08:41:55 -10:00
parent 1ac5237d54
commit bcf7ad9bf2
1 changed files with 20 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
hledger/hledger.m4.md
View File

@ -2291,12 +2291,14 @@ if you want to prevent this, you can declare and check your tags .
## Periodic transactions ## Periodic transactions
The `~` directive declares recurring transactions. The `~` directive declares a "periodic rule" which generates temporary extra transactions, usually recurring at some interval,
Such directives allow hledger to generate temporary future transactions (visible in reports, not in the journal file) when hledger is run with the `--forecast` flag.
to help with [forecasting](#forecasting) or [budgeting](#budgeting). These "forecast transactions" are useful for [forecasting](#forecasting) future activity.
They exist only for the duration of the report, and only when `--forecast` is used; they are not saved in the journal file by hledger.
Periodic transactions can be a little tricky, so before you use them, Periodic rules also have a second use: with the `--budget` flag they set budget goals for [budgeting](#budgeting).
read this whole section, or at least these tips:
Periodic rules can be a little tricky, so before you use them, read this whole section, or at least the following tips:
1. Two spaces accidentally added or omitted will cause you trouble - read about this below. 1. Two spaces accidentally added or omitted will cause you trouble - read about this below.
2. For troubleshooting, show the generated transactions with `hledger print --forecast tag:generated` or `hledger register --forecast tag:generated`. 2. For troubleshooting, show the generated transactions with `hledger print --forecast tag:generated` or `hledger register --forecast tag:generated`.
@ -2369,29 +2371,32 @@ So,
## Auto postings ## Auto postings
The `=` directive declares a rule for generating temporary extra postings on transactions. The `=` directive declares an "auto posting rule" which generates temporary extra postings on existing transactions,
When the `--auto` flag is used, wherever the `=` rule matches an existing posting, when hledger is run with the `--auto` flag.
it will generate a new companion posting (or several) below it. (Remember, [postings](#postings) are the account name & amount lines.)
Optionally the generated posting amount(s) can depend on the matched posting's amount. The rule contains a [query](#queries) and one or more posting templates.
This can be useful for generating tax postings with a standard percentage, for example. Wherever the query matches an existing posting, the new posting(s) will be generated and added below that one.
Optionally the generated amount(s) can depend on the matched posting's amount.
Note these generated postings exist only for the duration of the report, and only when hledger is run with the `--auto` flag. These auto postings can be useful for, eg, adding tax postings with a standard percentage.
They affect the report calculations and output but they are not saved in the journal file by hledger. They exist only for the duration of the report, and only when `--auto` is used; they are not saved in the journal file by hledger.
Also note that depending fully on this kind of generated data has some drawbacks - Note that depending fully on generated data such as this has some drawbacks -
it's less portable, less future-proof, less auditable by others, and less robust it's less portable, less future-proof, less auditable by others, and less robust
(since other features like balance assertions will depend on whether you use or don't use `--auto`). (eg your balance assertions will depend on whether you use or don't use `--auto`).
An alternative is to use auto postings in "one time" fashion - An alternative is to use auto postings in "one time" fashion -
use them to help build a complex journal entry, view it with `hledger print --auto`, use them to help build a complex journal entry, view it with `hledger print --auto`,
and then copy that output into the journal file to make it permanent. and then copy that output into the journal file to make it permanent.
An auto posting rule looks a bit like a transaction: Here's the journal file syntax. An auto posting rule looks a bit like a transaction:
```journal ```journal
= QUERY = QUERY
ACCOUNT AMOUNT ACCOUNT AMOUNT
... ...
ACCOUNT [AMOUNT] ACCOUNT [AMOUNT]
``` ```
except the first line is an equals sign (mnemonic: `=` suggests matching), except the first line is an equals sign (mnemonic: `=` suggests matching),
followed by a [query](#queries) (which matches existing postings), followed by a [query](#queries) (which matches existing postings),
and each "posting" line describes a posting to be generated, and each "posting" line describes a posting to be generated,