| 1 |
close |
| 2 |
|
| 3 |
(equity) |
| 4 |
|
| 5 |
close prints several kinds of "closing" and/or "opening" transactions, |
| 6 |
useful in various situations: migrating balances to a new journal file, |
| 7 |
retaining earnings into equity, consolidating balances, viewing lot |
| 8 |
costs.. Like print, it prints valid journal entries. You can copy these |
| 9 |
into your journal file(s) when you are happy with how they look. |
| 10 |
|
| 11 |
Flags: |
| 12 |
--clopen[=TAGVAL] show closing and opening balances transactions, |
| 13 |
for AL accounts by default |
| 14 |
--close[=TAGVAL] show just a closing balances transaction |
| 15 |
--open[=TAGVAL] show just an opening balances transaction |
| 16 |
--assert[=TAGVAL] show a balance assertions transaction |
| 17 |
--assign[=TAGVAL] show a balance assignments transaction |
| 18 |
--retain[=TAGVAL] show a retain earnings transaction, for RX |
| 19 |
accounts by default |
| 20 |
-x --explicit show all amounts explicitly |
| 21 |
--show-costs show amounts with different costs separately |
| 22 |
--interleaved show source and destination postings together |
| 23 |
--assertion-type=TYPE =, ==, =* or ==* |
| 24 |
--close-desc=DESC set closing transaction's description |
| 25 |
--close-acct=ACCT set closing transaction's destination account |
| 26 |
--open-desc=DESC set opening transaction's description |
| 27 |
--open-acct=ACCT set opening transaction's source account |
| 28 |
--round=TYPE how much rounding or padding should be done when |
| 29 |
displaying amounts ? |
| 30 |
none - show original decimal digits, |
| 31 |
as in journal (default) |
| 32 |
soft - just add or remove decimal zeros |
| 33 |
to match precision |
| 34 |
hard - round posting amounts to precision |
| 35 |
(can unbalance transactions) |
| 36 |
all - also round cost amounts to precision |
| 37 |
(can unbalance transactions) |
| 38 |
|
| 39 |
close has six modes, selected by choosing one of the mode flags: |
| 40 |
--clopen, --close (default), --open, --assert, --assign, or --retain. |
| 41 |
They are all doing the same kind of operation, but with different |
| 42 |
defaults for different situations. |
| 43 |
|
| 44 |
The journal entries generated by close will have a clopen: tag, which is |
| 45 |
helpful when you want to exclude them from reports. If the main journal |
| 46 |
file name contains a number, the tag's value will be that base file name |
| 47 |
with the number incremented. Eg if the journal file is 2025.journal, the |
| 48 |
tag will be clopen:2026. Or you can set the tag value by providing an |
| 49 |
argument to the mode flag. Eg --close=foo or --clopen=2025-main. |
| 50 |
|
| 51 |
close --clopen |
| 52 |
|
| 53 |
This is useful if migrating balances to a new journal file at the start |
| 54 |
of a new year. It prints a "closing balances" transaction that zeroes |
| 55 |
out account balances (Asset and Liability accounts, by default), and an |
| 56 |
opposite "opening balances" transaction that restores them again. |
| 57 |
Typically, you would run |
| 58 |
|
| 59 |
hledger close --clopen -e NEWYEAR >> $LEDGER_FILE |
| 60 |
|
| 61 |
and then move the opening transaction from the old file to the new file |
| 62 |
(and probably also update your LEDGER_FILE environment variable). |
| 63 |
|
| 64 |
Why might you do this ? If your reports are fast, you may not need it. |
| 65 |
But at some point you will probably want to partition your data by time, |
| 66 |
for performance or data integrity or regulatory reasons. A new file or |
| 67 |
set of files per year is common. Then, having each file/fileset |
| 68 |
"bookended" with opening and closing balance transactions will allow you |
| 69 |
to freely pick and choose which files to read - just the current year, |
| 70 |
any past year, any sequence of years, or all of them - while showing |
| 71 |
correct account balances in each case. The earliest opening balances |
| 72 |
transaction sets correct starting balances, and any later |
| 73 |
closing/opening pairs will harmlessly cancel each other out. |
| 74 |
|
| 75 |
The balances will be transferred to and from |
| 76 |
equity:opening/closing balances by default. You can override this by |
| 77 |
using --close-acct and/or --open-acct. |
| 78 |
|
| 79 |
You can select a different set of accounts to close/open by providing an |
| 80 |
account query. Eg to add Equity accounts, provide arguments like |
| 81 |
assets liabilities equity or type:ALE. When migrating to a new file, |
| 82 |
you'll usually want to bring along the AL or ALE accounts, but not the |
| 83 |
RX accounts (Revenue, Expense). |
| 84 |
|
| 85 |
Assertions will be added indicating and checking the new balances of the |
| 86 |
closed/opened accounts. |
| 87 |
|
| 88 |
close --close |
| 89 |
|
| 90 |
This prints just the closing balances transaction of --clopen. It is the |
| 91 |
default if you don't specify a mode. |
| 92 |
|
| 93 |
More customisation options are described below. Among other things, you |
| 94 |
can use close --close to generate a transaction moving the balances from |
| 95 |
any set of accounts, to a different account. (If you need to move just a |
| 96 |
portion of the balance, see hledger-move.) |
| 97 |
|
| 98 |
close --open |
| 99 |
|
| 100 |
This prints just the opening balances transaction of --clopen. (It is |
| 101 |
similar to Ledger's equity command.) |
| 102 |
|
| 103 |
close --assert |
| 104 |
|
| 105 |
This prints a transaction that asserts the account balances as they are |
| 106 |
on the end date (and adds an assert: tag). It could be useful as |
| 107 |
documention and to guard against changes. |
| 108 |
|
| 109 |
close --assign |
| 110 |
|
| 111 |
This prints a transaction that assigns the account balances as they are |
| 112 |
on the end date (and adds an "assign:" tag). Unlike balance assertions, |
| 113 |
assignments will post changes to balances as needed to reach the |
| 114 |
specified amounts. |
| 115 |
|
| 116 |
This is another way to set starting balances when migrating to a new |
| 117 |
file, and it will set them correctly even in the presence of earlier |
| 118 |
files which do not have a closing balances transaction. However, it can |
| 119 |
hide errors, and disturb the accounting equation, so --clopen is usually |
| 120 |
recommended. |
| 121 |
|
| 122 |
close --retain |
| 123 |
|
| 124 |
This is like --close, but it closes Revenue and Expense account balances |
| 125 |
by default. They will be transferred to equity:retained earnings, or |
| 126 |
another account specified with --close-acct. |
| 127 |
|
| 128 |
Revenues and expenses correspond to changes in equity. They are |
| 129 |
categorised separately for reporting purposes, but traditionally at the |
| 130 |
end of each accounting period, businesses consolidate them into equity, |
| 131 |
This is called "retaining earnings", or "closing the books". |
| 132 |
|
| 133 |
In personal accounting, there's not much reason to do this, and most |
| 134 |
people don't. (One reason to do it is to help the balancesheetequity |
| 135 |
report show a zero total, demonstrating that the accounting equation |
| 136 |
(A-L=E) is satisfied.) |
| 137 |
|
| 138 |
close customisation |
| 139 |
|
| 140 |
In all modes, the following things can be overridden: |
| 141 |
|
| 142 |
- the accounts to be closed/opened, with account query arguments |
| 143 |
- the closing/opening dates, with -e OPENDATE |
| 144 |
- the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT |
| 145 |
- the transaction descriptions, with --close-desc=DESC and |
| 146 |
--open-desc=DESC |
| 147 |
- the transactions' clopen tag value, with a TAGVAL argument for the |
| 148 |
mode flag (see above). |
| 149 |
|
| 150 |
By default, the closing date is yesterday, or the journal's end date, |
| 151 |
whichever is later; and the opening date is always one day after the |
| 152 |
closing date. You can change these by specifying a report end date; the |
| 153 |
closing date will be the last day of the report period. Eg -e 2024 means |
| 154 |
"close on 2023-12-31, open on 2024-01-01". |
| 155 |
|
| 156 |
With --x/--explicit, the balancing amount will be shown explicitly, and |
| 157 |
if it involves multiple commodities, a separate posting will be |
| 158 |
generated for each of them (similar to print -x). |
| 159 |
|
| 160 |
With --interleaved, each individual transfer is shown with source and |
| 161 |
destination postings next to each other (perhaps useful for |
| 162 |
troubleshooting). |
| 163 |
|
| 164 |
With --show-costs, balances' costs are also shown, with different costs |
| 165 |
kept separate. This may generate very large journal entries, if you have |
| 166 |
many currency conversions or investment transactions. close --show-costs |
| 167 |
is currently the best way to view investment lots with hledger. (To move |
| 168 |
or dispose of lots, see the more capable hledger-move script.) |
| 169 |
|
| 170 |
close and balance assertions |
| 171 |
|
| 172 |
close adds balance assertions verifying that the accounts have been |
| 173 |
reset to zero in a closing transaction or restored to their previous |
| 174 |
balances in an opening transaction. These provide useful error checking, |
| 175 |
but you can ignore them temporarily with -I, or remove them if you |
| 176 |
prefer. |
| 177 |
|
| 178 |
Single-commodity, subaccount-exclusive balance assertions (=) are |
| 179 |
generated by default. This can be changed with --assertion-type='==*' |
| 180 |
(eg). |
| 181 |
|
| 182 |
When running close you should probably avoid using -C, -R, status: |
| 183 |
(filtering by status or realness) or --auto (generating postings), since |
| 184 |
the generated balance assertions would then require these. |
| 185 |
|
| 186 |
Transactions with multiple dates (eg posting dates) spanning the file |
| 187 |
boundary also can disrupt the balance assertions: |
| 188 |
|
| 189 |
2023-12-30 a purchase made in december, cleared in january |
| 190 |
expenses:food 5 |
| 191 |
assets:bank:checking -5 ; date: 2023-01-02 |
| 192 |
|
| 193 |
To solve this you can transfer the money to and from a temporary |
| 194 |
account, splitting the multi-day transaction into two single-day |
| 195 |
transactions: |
| 196 |
|
| 197 |
; in 2022.journal: |
| 198 |
2022-12-30 a purchase made in december, cleared in january |
| 199 |
expenses:food 5 |
| 200 |
equity:pending -5 |
| 201 |
|
| 202 |
; in 2023.journal: |
| 203 |
2023-01-02 last year's transaction cleared |
| 204 |
equity:pending 5 = 0 |
| 205 |
assets:bank:checking -5 |
| 206 |
|
| 207 |
close examples |
| 208 |
|
| 209 |
Retain earnings |
| 210 |
|
| 211 |
Record 2022's revenues/expenses as retained earnings on 2022-12-31, |
| 212 |
appending the generated transaction to the journal: |
| 213 |
|
| 214 |
$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal |
| 215 |
|
| 216 |
After this, to see 2022's revenues and expenses you must exclude the |
| 217 |
retain earnings transaction: |
| 218 |
|
| 219 |
$ hledger -f 2022.journal is not:desc:'retain earnings' |
| 220 |
|
| 221 |
Migrate balances to a new file |
| 222 |
|
| 223 |
Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01: |
| 224 |
|
| 225 |
$ hledger close --clopen -f 2022.journal -p 2022 |
| 226 |
# copy/paste the closing transaction to the end of 2022.journal |
| 227 |
# copy/paste the opening transaction to the start of 2023.journal |
| 228 |
|
| 229 |
After this, to see 2022's end-of-year balances you must exclude the |
| 230 |
closing balances transaction: |
| 231 |
|
| 232 |
$ hledger -f 2022.journal bs not:desc:'closing balances' |
| 233 |
|
| 234 |
For more flexibility, it helps to tag closing and opening transactions |
| 235 |
with eg clopen:NEWYEAR, then you can ensure correct balances by |
| 236 |
excluding all opening/closing transactions except the first, like so: |
| 237 |
|
| 238 |
$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen' |
| 239 |
$ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:clopen=2021 or not tag:clopen' |
| 240 |
$ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:clopen=2022 or not tag:clopen' |
| 241 |
$ hledger bs -Y -f 2021.j expr:'tag:clopen=2021 or not tag:clopen' |
| 242 |
$ hledger bs -Y -f 2022.j expr:'tag:clopen=2022 or not tag:clopen' |
| 243 |
$ hledger bs -Y -f 2023.j # unclosed file, no query needed |
| 244 |
|
| 245 |
More detailed close examples |
| 246 |
|
| 247 |
See examples/multi-year. |