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

imp: close: doc: rewrite manual (#1604)

Browse Source
This commit is contained in:
Simon Michael 2021-07-11 13:41:04 -10:00
parent 0a66068ad1
commit daa95aeb7b
1 changed files with 169 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

238
hledger/Hledger/Cli/Commands/Close.md
View File

@ -1,104 +1,204 @@
close, equity\ close, equity\
Prints a "closing balances" transaction and an "opening balances" transaction Prints a sample "closing" transaction bringing specified account balances to zero,
that bring account balances to and from zero, respectively. and an inverse "opening" transaction restoring the same account balances.
These can be added to your journal file(s), eg to bring
asset/liability balances forward into a new journal file, or to If like most people you split your journal files by time, eg by year:
close out revenues/expenses to retained earnings at the end of a period. at the end of the year you can use this command to "close out" your
asset and liability (and perhaps equity) balances in the old file, and reinitialise them in the new file.
This helps ensure that report balances remain correct whether you are including old files or not.
(Because all closing/opening transactions except the very first will cancel out - see example below.)
Some people also use this command to close out revenue and expense balances at the end of an accounting period.
This properly records the period's profit/loss as "retained earnings" (part of equity),
and allows the accounting equation (A-L=E) to balance,
which you could then check by the [bse](#balancesheetequity) report's zero total.
_FLAGS _FLAGS
You can print just one of these transactions by using the `--close` or `--open` flag. You can print just the closing transaction by using the `--close` flag,
You can customise their descriptions with the `--close-desc` and `--open-desc` options. or just the opening transaction with the `--open` flag.
One amountless posting to "equity:opening/closing balances" is added Their descriptions are `closing balances` and `opening balances` by default;
to balance the transactions, by default. you can customise these with the `--close-desc` and `--open-desc` options.
You can customise this account name with `--close-acct` and `--open-acct`;
if you specify only one of these, it will be used for both.
With `--x/--explicit`, the equity posting's amount will be shown. Just one balancing equity posting is used by default, with the amount left implicit.
And if it involves multiple commodities, a posting for each commodity The default account name is `equity:opening/closing balances`.
will be shown, as with the print command. You can customise the account name(s) with `--close-acct` and `--open-acct`.
(If you specify only one of these, it will be used for both.)
With `--interleaved`, the equity postings are shown next to the With `--x/--explicit`, the equity posting's amount will be shown explicitly,
postings they balance, which makes troubleshooting easier. and if it involves multiple commodities, there will be a separate equity posting for each commodity
(as in the print command).
By default, transaction prices in the journal are ignored when With `--interleaved`, each equity posting is shown next to the posting it balances
generating the closing/opening transactions. (good for troubleshooting).
With `--show-costs`, this cost information is preserved
(`balance -B` reports will be unchanged after the transition).
Separate postings are generated for each cost in each commodity.
Note this can generate very large journal entries, if you have many
foreign currency or investment transactions.
### close usage ### close and prices
If you split your journal files by time (eg yearly), you will Transaction prices are ignored (and discarded) by closing/opening transactions, by default.
typically run this command at the end of the year, and save the With `--show-costs`, they are preserved;
closing transaction as last entry of the old file, and the opening there will be a separate equity posting for each cost in each commodity.
transaction as the first entry of the new file. This means `balance -B` reports will look the same after the transition.
This makes the files self contained, so that correct balances are Note if you have many foreign currency or investment transactions,
reported no matter which of them are loaded. Ie, if you load just one this will generate very large journal entries.
file, the balances are initialised correctly; or if you load several
files, the redundant closing/opening transactions cancel each other
out. (They will show up in print or register reports; you can exclude
them with a query like `not:desc:'(opening|closing) balances'`.)
If you're running a business, you might also use this command to ### close date
"close the books" at the end of an accounting period, transferring
income statement account balances to retained earnings. (You may want
to change the equity account name to something like
"equity:retained earnings".)
By default, the closing transaction is dated yesterday, the balances The default closing date is yesterday, or the journal's end date, whichever is later.
are calculated as of end of yesterday, and the opening transaction is dated today.
To close on some other date, use: `hledger close -e OPENINGDATE`.
Eg, to close/open on the 2018/2019 boundary, use `-e 2019`.
You can also use -p or `date:PERIOD` (any starting date is ignored).
Both transactions will include balance assertions for the Unless you are running `close` on exactly the first day of the new period,
closed/reopened accounts. You probably shouldn't use status or you'll want to override the closing date.
realness filters (like -C or -R or `status:`) with this command, or This is done by specifying a [report period](#report-start--end-date),
the generated balance assertions will depend on these flags. where "last day of the report period" will be the closing date.
Likewise, if you run this command with --auto, the balance assertions The opening date is always the following day.
will probably always require --auto. So to close on 2020-12-31 and open on 2021-01-01, any of these work
Examples: - `-p 2020`
- `date:2020`
- `-e 2021-01-01` (remember `-e` specifies an exclusive end date)
- `-e 2021`
Carrying asset/liability balances into a new file for 2019: ### Example: close asset/liability accounts for file transition
Carrying asset/liability balances from 2020.journal into a new file for 2021:
```shell ```shell
$ hledger close -f 2018.journal -e 2019 assets liabilities --open $ hledger close -f 2020.journal -p 2020 assets liabilities
# (copy/paste the output to the start of your 2019 journal file) # copy/paste the closing transaction to the end of 2020.journal
$ hledger close -f 2018.journal -e 2019 assets liabilities --close # copy/paste the opening transaction to the start of 2021.journal
# (copy/paste the output to the end of your 2018 journal file)
``` ```
Now: Or:
```shell ```shell
$ hledger bs -f 2019.journal # one file - balances are correct $ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction
$ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct $ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction
$ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn
``` ```
Transactions spanning the closing date can complicate matters, breaking balance assertions: Now,
```shell
$ hledger bs -f 2021.journal # just new file - balances correct
$ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct
$ hledger bs -f 2020.journal # just old files - balances are zero ?
# (exclude final closing txn, see below)
```
### Hiding opening/closing transactions
Although the closing/opening transactions cancel out, they will be visible in reports like `print` and `register`,
creating some visual clutter. You can exclude them all with a query, like:
```shell
$ hledger print not:desc:'opening|closing' # less typing
$ hledger print not:'equity:opening/closing balances' # more precise
```
But when reporting on multiple files, this can get a bit tricky;
you may need to keep the earliest opening balances, for a historical register report;
or you may need to suppress a closing transaction, to see year-end balances.
If you find yourself needing more precise [queries](#queries), here's one solution:
add more easily-matched tags to opening/closing transactions, like this:
```journal ```journal
2018/12/30 a purchase made in 2018, clearing the following year ; 2019.journal
2019-01-01 opening balances ; earliest opening txn, no tag here
...
2019-12-31 closing balances ; close:2019
...
```
```journal
; 2020.journal
2020-01-01 opening balances ; open:2020
...
2020-12-31 closing balances ; close:2020
...
```
```journal
; 2021.journal
2021-01-01 opening balances ; open:2021
...
```
Now with
```journal
; all.journal
include 2019.journal
include 2020.journal
include 2021.journal
```
you could do eg:
```shell
$ hledger -f all.journal reg -H checking not:tag:'open|close'
# all years checking register, hiding non-essential opening/closing txns
$ hledger -f all.journal bs -p 2020 not:tag:close=2020
# 2020 year end balances, suppressing 2020 closing txn
$ hledger -f 2020.journal bs not:tag:close
# 2020 year end balances, easier case
```
### close and balance assertions
The closing and opening transactions will include balance assertions,
verifying that the accounts have first been reset to zero and then restored to their previous balance.
These provide valuable error checking, alerting you when things get out of line,
but you can ignore them temporarily with `-I` or just remove them if you prefer.
You probably shouldn't use status or realness filters (like -C or -R or `status:`) with `close`,
or the generated balance assertions will depend on these flags.
Likewise, if you run this command with `--auto`, the balance assertions would probably always require `--auto`.
Multi-day transactions (where some postings have a different date) break the balance assertions,
because the money is temporarily "invisible" while in transit:
```journal
2020/12/30 a purchase made in december, cleared in the next year
expenses:food 5 expenses:food 5
assets:bank:checking -5 ; [2019/1/2] assets:bank:checking -5 ; date: 2021/1/2
``` ```
Here's one way to resolve that: To fix the assertions, you can add a temporary account to track such in-transit money
(splitting the multi-day transaction into two single-day transactions):
```journal ```journal
; in 2018.journal: ; in 2020.journal:
2018/12/30 a purchase made in 2018, clearing the following year 2020/12/30 a purchase made in december, cleared in the next year
expenses:food 5 expenses:food 5
liabilities:pending liabilities:pending
; in 2019.journal: ; in 2021.journal:
2019/1/2 clearance of last year's pending transactions 2021/1/2 clearance of last year's pending transactions
liabilities:pending 5 = 0 liabilities:pending 5 = 0
assets:checking assets:bank:checking
```
### Example: close revenue/expense accounts to retained earnings
Here, the opening transaction is supressed with `--close`, as it's probably not needed.
Also you'll want to use a different equity account name:
```shell
$ hledger close -f 2021.journal -p 2021Q1 --close --close-acct='equity:retained earnings' revenues expenses >> 2021.journal
# close 2021 first quarter revenues/expenses
```
Or, operating on the default journal:
```shell
$ hledger close -p Q1 --close --close-acct='equity:retained earnings' revenues expenses >> $LEDGER_FILE
# close current year's first quarter revenues/expenses
```
Now, eg:
```shell
$ hledger bse -p Q1
# Q1 full balance sheet, total should be zero
$ hledger is -p Q1 not:'retained earnings'
# Q1 income statement, must suppress the closing txn
``` ```