Skip to content

Commit

Permalink
;doc:close: rewrite again; and give a better excluding technique [sim…
Browse files Browse the repository at this point in the history 
…onmichael#2151]
  • Loading branch information
@simonmichael @adept
simonmichael authored and adept committed Mar 8, 2024
1 parent 795aaac commit b41aa27
Showing 1 changed file with 110 additions and 106 deletions.
216 changes: 110 additions & 106 deletions hledger/Hledger/Cli/Commands/Close.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,90 +2,104 @@

(equity)

A transaction-generating command which generates several kinds of "closing"
and/or "opening" transactions useful in certain situations.
It prints one or two transactions to stdout, but does not write them to the journal file;
you can append or copy them there when you are happy with the output.
`close` generates several kinds of "closing" and/or "opening" transactions, useful in certain situations, including
migrating balances to a new journal file, retaining earnings into equity, consolidating balances, or viewing lots.
Like `print`, it prints valid journal entries.
You can append or copy these to your journal file(s) when you are happy with how they look.

_FLAGS

<!-- related: -->

This command is most often used when migrating balances to a new journal file, at the start of a new financial year.
It can also be used to "retain earnings" (transfer revenues and expenses to equity),
or as a sort of generic mover of balances from any group of accounts to some other account.
So it currently has six modes, selected by a mode flag. Use only one of these flags at a time:

1. With `--close` (or no mode flag) it prints a "closing balances" transaction
that zeroes out all the asset and liability account balances, by default
(this requires [account types](hledger.md#account-types) to be detected or declared.).
All of the balances are transferred to a special "opening/closing balances" equity account.
Or, if it will zero out the accounts matched by query arguments you provide.
Eg you could include assets, liabilities, and equity with `hledger close type:ALE`.
The "opening/closing balances" equity account is always excluded.

2. With `--open`, it prints an opposite "opening balances" transaction that
restores the same account balances, starting from zero.
<!-- This mode is similar to [Ledger's equity command](https://ledger-cli.org/doc/ledger3.html#The-equity-command). -->

3. With `--migrate`, it prints both the closing and opening transactions above.
This is a common way to migrate balances to a new file at year end;
run `hledger close --migrate -e NEWYEAR` (-e influences the transaction date)
and add the closing transaction at the end of the old file,
and the opening transaction at the start of the new file.
Doing this means you can include past year files in your reports at any time
without disturbing asset/liability/equity balances,
because the closing balances transaction cancels out the following opening balances transaction.
You will sometimes need to exclude these transactions from reports, eg to see an end of year balance sheet;
a `not:opening/closing` query argument should do.
You should probably also use this query when `close`-ing, to exclude the "opening/closing balances" account
which might otherwise [cause problems](https://www.reddit.com/r/plaintextaccounting/comments/18zxlbn/hledger_year_closing/).
Or you can just migrate assets and liabilities: `hledger close type:AL`.
Most people don't need to migrate equity.
And revenues and expenses usually should not be migrated.

4. With `--assert` it prints a "closing balances" transaction that
just asserts the current balances, without changing them.
This can be useful as documention and to guard against errors and changes.

5. With `--assign` it prints an "opening balances" transaction that
`close` currently has six modes, selected by a single mode flag:

### `close --migrate`

This is the most common mode.
It prints a "closing balances" transaction that zeroes out all asset and liability balances (by default),
and an opposite "opening balances" transaction that restores them again.
The balancing account will be `equity:opening/closing balances` (or another specified by `--close-acct` and/or `--open-acct`).

This is useful when migrating balances to a new journal file at the start of a new year.
Essentially, you run `hledger close --migrate -e NEWYEAR`
and then copy the closing transaction to the end of the old file
and the opening transaction to the start of the new file.
The opening transaction sets correct starting balances in the new file when it is used alone,
and the closing transaction keeps balances correct when you use both old and new files together,
by cancelling out the following opening transaction and preventing buildup of duplicated opening balances.
Think of the closing/opening pair as "moving the balances into the next file".

You can close a different set of accounts by providing a query.
Most people don't need to migrate equity (?)
but you can include it by adding a `type:ALE` argument (except `equity:opening/closing balances`, which is always excluded).
Revenues and expenses usually are not migrated to a new file directly; see `--retain` below.

### `close --close`

This prints just the closing balances transaction of `--migrate`.
It is the default behaviour if you specify no mode flag.
Using the customisation options below, you can move balances from any set of accounts to a different account.

### `close --open`

This prints just the opening balances transaction of `--migrate`.
It is similar to [Ledger's equity command](https://ledger-cli.org/doc/ledger3.html#The-equity-command).

### `close --assert`

This prints a "closing balances" transaction that just declares [balance assertions](#balance-assertions)
for the current balances without changing them.
It could be useful as documention and to guard against changes.

### `close --assign`

This prints an "opening balances" transaction that
restores the account balances using [balance assignments](#balance-assignments).
Balance assignments work regardless of any previous balance, so a preceding closing balances transaction is not needed.
This is an alternative to `--close` and `--open`: at year end,
`hledger close --assert -e NEWYEAR` in the old file (optional, but useful for error checking),
and `hledger close --assign -e NEWYEAR` in the new file.
This might be more convenient, eg if you are often doing cleanups or fixes which would break closing/opening transactions.

6. With `--retain`, it prints a "retain earnings" transaction that transfers
revenue and expense balances to `equity:retained earnings`.
This is a traditional end-of-period bookkeeping operation also called "closing the books";
in personal accounting you probably will not need this but it could be useful
if you want to see the accounting equation (A=L+E) balanced.
However, omitting the closing balances transaction would unbalance equity.
This is relatively harmless for personal reports, but it disturbs the accounting equation, removing a source of error detection.
So `--migrate` is generally the best way to set to set balances in new files, [for now](https://github.com/simonmichael/hledger/issues/2151).

### `close --retain`

This is like `--close` with different defaults:
it prints a "retain earnings" transaction that transfers revenue and expense balances to `equity:retained earnings`.

This is a different kind of closing, called "retaining earnings" or "closing the books";
it is traditionally performed by businesses at the end of each accounting period,
to consolidate revenues and expenses into the main equity balance.
("Revenues" and "expenses" are actually equity by another name, kept separate temporarily for reporting purposes.)

In personal accounting you generally don't need to do this,
unless you want the `balancesheetequity` report to show a zero total, demonstrating that the accounting equation (A-L=E) is satisfied.

### `close` customisation

In all modes, the following things can be overridden:

- the transaction descriptions can be changed with `--close-desc=DESC` and `--open-desc=DESC`
- the account to transfer to and from can be changed with `--close-acct=ACCT` and `--open-acct=ACCT`
- the accounts to be closed/opened can be changed with `ACCTQUERY` (account query arguments).
- the closing/opening dates can be changed with `-e DATE` (a report end date)
- the accounts to be closed/opened, with account query arguments
- the balancing account, with `--close-acct=ACCT` and/or `--open-acct=ACCT`
- the transaction descriptions, with `--close-desc=DESC` and `--open-desc=DESC`
- the closing/opening dates, with `-e OPENDATE`

By default, the closing date is yesterday, or the journal's end date, whichever is later;
and the opening date is always one day after the closing date.
You can change these by specifying a [report end date](#report-start--end-date);
the closing date will be the last day of the report period.
Eg `-e 2024` means "close on 2023-12-31, open on 2024-01-01".

By default just one destination/source posting will be used, with its amount left implicit.
With `--x/--explicit`, the amount will be shown explicitly,
With `--x/--explicit`, the balancing amount will be shown explicitly,
and if it involves multiple commodities, a separate posting will be generated for each of them
(similar to `print -x`).

With `--show-costs`, any amount costs are shown, with separate postings for each cost.
This is currently the best way to view investment lots.
If you have many currency conversion or investment transactions, it can generate very large journal entries.
With `--interleaved`, each individual transfer is shown with source and destination postings next to each other
(perhaps useful for troubleshooting).

With `--interleaved`, each individual transfer is shown with source
and destination postings next to each other.
This could be useful for troubleshooting.

The default closing date is yesterday, or the journal's end date, whichever is later.
You can change this by specifying a [report end date](#report-start--end-date) with `-e`.
The last day of the report period will be the closing date, eg `-e 2024` means "close on 2023-12-31".
The opening date is always the day after the closing date.
With `--show-costs`, balances' costs are also shown, with different costs kept separate.
This may generate very large journal entries, if you have many currency conversions or investment transactions.
`close --show-costs` is currently the best way to view investment lots with hledger.
(To move or dispose of lots, see the more capable [`hledger-move`](scripts.md#hledger-move) script.)

### close and balance assertions

Expand Down Expand Up @@ -122,7 +136,9 @@ in effect splitting the multi-day transaction into two single-day transactions:
assets:bank:checking -5
```

### Example: retain earnings
### close examples

#### Retain earnings

<!-- XXX update -->

Expand All @@ -133,16 +149,16 @@ appending the generated transaction to the journal:
$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
```

Note 2022's income statement will now show only zeroes,
2022's income statement will now show only zeroes,
because revenues and expenses have been moved entirely to equity.
To see them again, you could exclude the retain transaction:
To see their end balances, you could exclude the retain transaction:
```cli
$ hledger -f 2022.journal is not:desc:'retain earnings'
```

### Example: migrate balances to a new file
#### Migrate balances to a new file

Close assets/liabilities/equity on 2022-12-31 and re-open them on 2023-01-01:
Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:

```cli
$ hledger close --migrate -f 2022.journal -p 2022
Expand All @@ -159,63 +175,51 @@ $ hledger close --open -f 2022.journal -p 2022 >> 2022.journal
```
-->

Now 2022's balance sheet will show only zeroes, indicating a balanced accounting equation.
2022's balance sheet will now show only zeroes, indicating a balanced accounting equation.
([Unless](/investments.html#a-more-correct-entry) you are using @/@@ notation - in that case, try adding --infer-equity.)
To see the end-of-year balances again, you could exclude the closing transaction:
(Do we need to close equity also ? retest)
To see the end-of-year balances, you could exclude the closing transaction:
```cli
$ hledger -f 2022.journal bs not:desc:'closing balances'
```

### Example: excluding closing/opening transactions

When combining many files for multi-year reports,
the closing/opening transactions cause some noise in transaction-oriented reports like `print` and `register`.
You can exclude them as shown above, but `not:desc:...` is not ideal
as it depends on consistent descriptions; also you will want to avoid excluding
the very first opening transaction, which could be awkward.
Here is one alternative, using tags:
#### Exclude opening/closing transactions

Add `clopen:` tags to all opening/closing balances transactions except the first,
like this:
When combining files for multi-year reports, for some reports (eg a yearly balance sheet)
you may need to suppress all opening/closing transactions except the first.
This is a bit awkward if you also want to be able to choose any range of year files,
but here is a way, using tags:

```journal
; 2021.journal
2021-06-01 first opening balances
2021-06-01 opening balances ; start:2021
...
2021-12-31 closing balances ; clopen:2022
2021-12-31 closing balances ; start:2022
...
```

```journal
; 2022.journal
2022-01-01 opening balances ; clopen:2022
2022-01-01 opening balances ; start:2022
...
2022-12-31 closing balances ; clopen:2023
2022-12-31 closing balances ; start:2023
...
```

```journal
; 2023.journal
2023-01-01 opening balances ; clopen:2023
2023-01-01 opening balances ; start:2023
...
```

Now, assuming a combined journal like:

```journal
; all.journal
include 2021.journal
include 2022.journal
include 2023.journal
```
All of these will show the year-end balances correctly:

The `clopen:` tag can exclude all but the first opening transaction.
To show a clean multi-year checking register:
```cli
$ hledger -f all.journal areg checking not:tag:clopen
$ 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
```

And the year values allow more precision.
To show 2022's year-end balance sheet:
```cli
$ hledger -f all.journal bs -e2023 not:tag:clopen=2023
```

0 comments on commit b41aa27

Please sign in to comment.