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

;examples:multi-year: expand, show equity & accounting equation [#2151]

Browse Source
This commit is contained in:
Simon Michael 2024-01-20 14:25:18 -10:00
parent e61c9bad10
commit 4ccb5ad9f6
7 changed files with 200 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
examples/multi-year/2021-closed.journal Normal file
View File

@ -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

8
examples/multi-year/2021.journal
View File

@ -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

26
examples/multi-year/2022-closed.journal Normal file
View File

@ -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

8
examples/multi-year/2022.journal
View File

@ -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

6
examples/multi-year/2023.journal
View File

@ -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

139
examples/multi-year/README.md
View File

@ -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
```

14
examples/multi-year/reports
View File

@ -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