From b418e686c9987fe1ad5862ad3664047c9df1f970 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 20 Jan 2024 16:36:52 -1000 Subject: [PATCH] ;examples:multi-year: edits --- examples/multi-year/README.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/examples/multi-year/README.md b/examples/multi-year/README.md index 4b0911c6a..8fdfe873b 100644 --- a/examples/multi-year/README.md +++ b/examples/multi-year/README.md @@ -1,5 +1,7 @@ +## Working with multiple year files + Here are some yearly journal files demonstrating issues and techniques -discussed in the [close docs](https://hledger.org/dev/hledger.html>). +discussed in the [close docs](https://hledger.org/dev/hledger.html). `2021.journal`, `2022.journal` and `2023.journal` each have only an opening balances transaction and some ordinary transactions. @@ -12,23 +14,24 @@ To solve this, whenever we transition to a new file we can - add a counterbalancing [closing transaction](https://hledger.org/hledger.html#close) using `close`. -Also (not necessary for basic personal accounting, but if we want to be fully correct), we should ensure all equity is accounted for: +Also (not necessary for basic personal accounting, but if we want to be fully correct), we can ensure all equity is accounted for: -- where we have used @/@@ notation to convert between commodities, add [equivalent equity postings](https://hledger.org/hledger.html#equity-conversion-postings) +- wherever we have used [@/@@ notation](https://hledger.org/hledger.html#costs) to convert between commodities, + add [equivalent equity postings](https://hledger.org/hledger.html#equity-conversion-postings) - and consolidate revenues and expenses into equity (AKA [retain earnings](https://hledger.org/hledger.html#close)). -Combining all of these in the right sequence is tricky, so here's an example of fully migrating to a new file at the end of 2021/start of 2022. +Combining these in the right sequence can be tricky, so here's an example of fully migrating to a new file at the end of 2021/start of 2022. `2021-closed.journal` and `2022-closed.journal` are the result of applying this procedure to the 2021 and 2022 journals. -(They are given a different name here for clarity; normally you probably wouldn't change the name.) +(They are named differently from the original journals for clarity here; normally you wouldn't change the name.) -First ensure all equity changes are recorded: +First, ensure all equity changes are recorded: ```cli $ hledger -f 2021.journal print --infer-equity > 2021-closed.journal # add explicit equity:conversion postings where needed $ hledger -f 2021-closed.journal close --retain -e 2022 >> 2021-closed.journal # retain earnings (transfer RX to E) ``` -Next migrate asset/liability balances from old file to new file. +Next, migrate asset/liability balances from old file to new file. (If you want to preserve equity balances too, add a [`type:ALE` argument](https://hledger.org/hledger.html#account-types).) Note how --open is done first and --close second; or you could --close first and `--open not:desc:closing` second: @@ -37,19 +40,18 @@ $ hledger -f 2021-closed.journal close --open -e 2022 >> 2022.journal $ hledger -f 2021-closed.journal close --close -e 2022 >> 2021-closed.journal # migrate balances (add closing txn to 2021.journal) ``` -Finally, add a tag like this (manually) to the closing and opening transactions to make them easier to exclude from reports: +Finally, add a tag like this (manually for now) to the closing and opening transactions to make them easier to exclude from reports: ```journal 2021-12-31 closing balances ; start:2022 -... ``` ```journal 2022-01-01 opening balances ; start:2022 -... ``` -Now we can confirm that the accounting equation was preserved in 2021 (Net: is 0). -We must exclude the closing balances transaction to see the end balances: +Now we can confirm that the accounting equation was preserved in 2021, +by checking that the grand total of Assets, Liabilities, and Equity is zero. +To see the end balances, we must exclude the closing balances transaction: ```cli $ hledger -f 2021-closed.journal bse not:tag:start=2022 @@ -80,7 +82,7 @@ Balance Sheet With Equity 2021-12-31 Net: || 0 ``` -We can check the accounting equation for 2022 too, after adding all equity changes: +We can check this for 2022 too, if we add any missing equity changes with --infer-equity and --retain (temporarily): ```cli $ (hledger -f 2022.journal print --infer-equity; hledger -f 2022.journal close --retain) | hledger -f- bse @@ -111,7 +113,7 @@ Balance Sheet With Equity 2024-01-19 Net: || 0 ``` -We can see correct balance sheets from any range of files if we exclude all opening/closing transactions except the first: +We can see correct balance sheets from any range of files, if we exclude all opening/closing transactions except the first: ```cli $ hledger bs -Y -f 2021-closed.journal -f 2022-closed.journal -f 2023.journal expr:'tag:start=2021 or not tag:start' @@ -122,7 +124,7 @@ $ hledger bs -Y -f 2022-closed.journal ex $ hledger bs -Y -f 2023.journal # unclosed file, no query needed ``` -And we can see correct income statements from any range of files if we exclude retain earnings transactions: +We can see correct income statements from any range of files, if we exclude retain earnings transactions: ```cli $ hledger is -Y -f 2021-closed.journal -f 2022-closed.journal -f 2023.journal not:desc:retain