From 4ccb5ad9f631eebe20ee6c8e39ae1d36e39eba43 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 20 Jan 2024 14:25:18 -1000 Subject: [PATCH] ;examples:multi-year: expand, show equity & accounting equation [#2151] --- examples/multi-year/2021-closed.journal | 26 +++++ examples/multi-year/2021.journal | 8 +- examples/multi-year/2022-closed.journal | 26 +++++ examples/multi-year/2022.journal | 8 +- examples/multi-year/2023.journal | 6 +- examples/multi-year/README.md | 139 +++++++++++++++++++++++- examples/multi-year/reports | 14 --- 7 files changed, 200 insertions(+), 27 deletions(-) create mode 100644 examples/multi-year/2021-closed.journal create mode 100644 examples/multi-year/2022-closed.journal delete mode 100755 examples/multi-year/reports diff --git a/examples/multi-year/2021-closed.journal b/examples/multi-year/2021-closed.journal new file mode 100644 index 000000000..ff0a6fc91 --- /dev/null +++ b/examples/multi-year/2021-closed.journal @@ -0,0 +1,26 @@ +; 2021-closed.journal + +2021-06-01 opening balances ; start:2021 + assets 20 = 20 + equity:opening/closing balances + +2021-07-01 income + income + assets 1 + +2021-08-01 currency conversion + income -1 A + equity:conversion:A-B:A 1 A + equity:conversion:A-B:B -1 B + expenses 1 B + +2021-12-31 retain earnings + expenses -1 B = 0 B + income 1 = 0 + income 1 A = 0 A + equity:retained earnings + +2021-12-31 closing balances ; start:2022 + assets -21 = 0 + equity:opening/closing balances + diff --git a/examples/multi-year/2021.journal b/examples/multi-year/2021.journal index 64e5940c5..cb7597dde 100644 --- a/examples/multi-year/2021.journal +++ b/examples/multi-year/2021.journal @@ -2,13 +2,13 @@ 2021-06-01 opening balances ; start:2021 assets 20 = 20 - equity:start + equity:opening/closing balances 2021-07-01 income income assets 1 -2021-12-31 closing balances ; start:2022 - assets -21 = 0 - equity:start +2021-08-01 currency conversion + income -1 A + expenses 1 B diff --git a/examples/multi-year/2022-closed.journal b/examples/multi-year/2022-closed.journal new file mode 100644 index 000000000..bbdd0ec52 --- /dev/null +++ b/examples/multi-year/2022-closed.journal @@ -0,0 +1,26 @@ +; 2022-closed.journal + +2022-01-01 opening balances ; start:2022 + assets 21 = 21 + equity:opening/closing balances + +2022-07-01 income + income + assets 1 + +2022-08-01 currency conversion + income -1 A + equity:conversion:A-B:A 1 A + equity:conversion:A-B:B -1 B + expenses 1 B + +2022-12-31 retain earnings + expenses -1 B = 0 B + income 1 = 0 + income 1 A = 0 A + equity:retained earnings + +2022-12-31 closing balances ; start:2023 + assets -22 = 0 + equity:opening/closing balances + diff --git a/examples/multi-year/2022.journal b/examples/multi-year/2022.journal index 6b0c467ee..266531ea0 100644 --- a/examples/multi-year/2022.journal +++ b/examples/multi-year/2022.journal @@ -2,13 +2,13 @@ 2022-01-01 opening balances ; start:2022 assets 21 = 21 - equity:start + equity:opening/closing balances 2022-07-01 income income assets 1 -2022-12-31 closing balances ; start:2023 - assets -22 = 0 - equity:start +2022-08-01 currency conversion + income -1 A + expenses 1 B diff --git a/examples/multi-year/2023.journal b/examples/multi-year/2023.journal index 37c2520ac..15665596b 100644 --- a/examples/multi-year/2023.journal +++ b/examples/multi-year/2023.journal @@ -2,9 +2,13 @@ 2023-01-01 opening balances ; start:2023 assets 22 = 22 - equity:start + equity:opening/closing balances 2023-07-01 income income assets 1 +2023-08-01 currency conversion + income -1 A + expenses 1 B + diff --git a/examples/multi-year/README.md b/examples/multi-year/README.md index 49f46a2cc..4b0911c6a 100644 --- a/examples/multi-year/README.md +++ b/examples/multi-year/README.md @@ -1,4 +1,135 @@ -Multiple yearly journal files, demonstrating the tags and commands -suggested in the [close command's doc](https://hledger.org/dev/hledger.html#example-exclude-openingclosing-transactions>) -for flexible multi-year reporting. -See `reports`. +Here are some yearly journal files demonstrating issues and techniques +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. +These are what you'd get if you started a new file each year +using hledger's `close --open` command or Ledger's `equity` command. +These files show correct balances when used individually, but they can't be combined for a multi-year report; +their opening transactions are redundant and will produce nonsense balances. + +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: + +- where we have used @/@@ notation 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. +`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.) + +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. +(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: + +```cli +$ hledger -f 2021-closed.journal close --open -e 2022 >> 2022.journal # migrate balances (add opening txn to 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: + +```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: + +```cli +$ hledger -f 2021-closed.journal bse not:tag:start=2022 +Balance Sheet With Equity 2021-12-31 + + || 2021-12-31 +=================================++============== + Assets || +---------------------------------++-------------- + assets || 21 +---------------------------------++-------------- + || 21 +=================================++============== + Liabilities || +---------------------------------++-------------- +---------------------------------++-------------- + || +=================================++============== + Equity || +---------------------------------++-------------- + equity:conversion:A-B:A || -1 A + equity:conversion:A-B:B || 1 B + equity:opening/closing balances || 20 + equity:retained earnings || 1, 1 A, -1 B +---------------------------------++-------------- + || 21 +=================================++============== + Net: || 0 +``` + +We can check the accounting equation for 2022 too, after adding all equity changes: + +```cli +$ (hledger -f 2022.journal print --infer-equity; hledger -f 2022.journal close --retain) | hledger -f- bse +Balance Sheet With Equity 2024-01-19 + + || 2024-01-19 +==========================++============== + Assets || +--------------------------++-------------- + assets || 22 +--------------------------++-------------- + || 22 +==========================++============== + Liabilities || +--------------------------++-------------- +--------------------------++-------------- + || +==========================++============== + Equity || +--------------------------++-------------- + equity:conversion:A-B:A || -1 A + equity:conversion:A-B:B || 1 B + equity:retained earnings || 1, 1 A, -1 B + equity:start || 21 +--------------------------++-------------- + || 22 +==========================++============== + Net: || 0 +``` + +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' +$ hledger bs -Y -f 2021-closed.journal -f 2022-closed.journal expr:'tag:start=2021 or not tag:start' +$ hledger bs -Y -f 2022-closed.journal -f 2023.journal expr:'tag:start=2022 or not tag:start' +$ hledger bs -Y -f 2021-closed.journal expr:'tag:start=2021 or not tag:start' +$ hledger bs -Y -f 2022-closed.journal expr:'tag:start=2022 or not tag:start' +$ 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: + +```cli +$ hledger is -Y -f 2021-closed.journal -f 2022-closed.journal -f 2023.journal not:desc:retain +$ hledger is -Y -f 2021-closed.journal -f 2022-closed.journal not:desc:retain +$ hledger is -Y -f 2022-closed.journal -f 2023.journal not:desc:retain +$ hledger is -Y -f 2021-closed.journal not:desc:retain +$ hledger is -Y -f 2022-closed.journal not:desc:retain +$ hledger is -Y -f 2023.journal # unclosed file, no query needed +``` + diff --git a/examples/multi-year/reports b/examples/multi-year/reports deleted file mode 100755 index ee090de5c..000000000 --- a/examples/multi-year/reports +++ /dev/null @@ -1,14 +0,0 @@ -#!/usr/bin/env sh - -# Suppressing redundant starting/ending balances transactions as suggested in -# https://hledger.org/dev/hledger.html#example-exclude-openingclosing-transactions . -# All of these will show the year-end balances correctly. -# In each case, we exclude all transactions tagged with start: except the earliest. - -hledger bs -Y -f 2021.journal -f 2022.journal -f 2023.journal expr:'tag:start=2021 or not tag:start' -hledger bs -Y -f 2021.journal -f 2022.journal expr:'tag:start=2021 or not tag:start' -hledger bs -Y -f 2022.journal -f 2023.journal expr:'tag:start=2022 or not tag:start' -hledger bs -Y -f 2021.journal expr:'tag:start=2021 or not tag:start' -hledger bs -Y -f 2022.journal expr:'tag:start=2022 or not tag:start' -hledger bs -Y -f 2023.journal # unclosed file, no query needed -