Debian Codegraph @

Hledger/Cli/Commands/Close.txt

raw
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.