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

imp:close: change the start: tag to clopen:, and change --assign's tag to assign:

Browse Source 
And some doc edits.
This commit is contained in:
Simon Michael 2025-01-09 14:59:13 -10:00
parent 88379684c0
commit 2588e31466
2 changed files with 27 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
hledger/Hledger/Cli/Commands/Close.hs
View File

@ -85,8 +85,9 @@ close CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do
tagval = fromMaybe "" $ maybestringopt modeflag rawopts where modeflag = lowercase $ show mode_ tagval = fromMaybe "" $ maybestringopt modeflag rawopts where modeflag = lowercase $ show mode_
comment = T.pack $ if comment = T.pack $ if
| mode_ == Assert -> "assert:" <> tagval | mode_ == Assert -> "assert:" <> tagval
| mode_ == Assign -> "assign:" <> tagval
| mode_ == Retain -> "retain:" <> tagval | mode_ == Retain -> "retain:" <> tagval
| otherwise -> "start:" <> if null tagval then inferredval else tagval | otherwise -> "clopen:" <> if null tagval then inferredval else tagval
where where
inferredval = newfilename inferredval = newfilename
where where

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

@ -44,7 +44,7 @@ Flags:
### close --migrate ### close --migrate
This is the most common mode. This is the most common mode.
It prints a "closing balances" transaction that zeroes out all asset and liability balances (by default), 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. 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` or `--open-acct`). The balancing account will be `equity:opening/closing balances` (or another specified by `--close-acct` or `--open-acct`).
@ -62,7 +62,7 @@ Eg if you want to include equity, you can add `assets liabilities equity` or [`t
(The balancing account is always excluded.) (The balancing account is always excluded.)
Revenues and expenses usually are not migrated to a new file directly; see `--retain` below. Revenues and expenses usually are not migrated to a new file directly; see `--retain` below.
The generated transactions will have a `start:` tag, with its value set to The generated transactions will have a `clopen:` tag, with its value set to
`--migrate`'s `NEW` argument if any, for easier matching or exclusion. `--migrate`'s `NEW` argument if any, for easier matching or exclusion.
When `NEW` is not specified, it will be inferred if possible by incrementing When `NEW` is not specified, it will be inferred if possible by incrementing
a number (eg a year number) within the default journal's main file name. a number (eg a year number) within the default journal's main file name.
@ -81,33 +81,32 @@ It is similar to [Ledger's equity command](https://ledger-cli.org/doc/ledger3.ht
### close --assert ### close --assert
This prints a "closing balances" transaction (with `balances:` tag), This prints a transaction that [asserts](#balance-assertions) the account balances as they are on the end date (and adds an `assert:` tag).
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. It could be useful as documention and to guard against changes.
### close --assign ### close --assign
This prints an "opening balances" transaction that This prints a transaction that [assigns](#balance-assignments) the account balances as they are on the end date (and adds an "assign:" tag).
restores the account balances using [balance assignments](#balance-assignments). Unlike balance assertions, assignments will post changes to balances as needed to reach the specified amounts.
Balance assignments work regardless of any previous balance, so a preceding closing balances transaction is not needed.
However, omitting the closing balances transaction would unbalance equity. This is another way to set starting balances when migrating to a new file,
This is relatively harmless for personal reports, but it disturbs the accounting equation, removing a source of error detection. and it will set them correctly even in the presence of earlier files which do not have a closing balances transaction.
So `--migrate` is generally the best way to set to set balances in new files, [for now](https://github.com/simonmichael/hledger/issues/2151). However, it can hide errors, and disturb the accounting equation,
so `--migrate` is usually recommended [for now](https://github.com/simonmichael/hledger/issues/2151).
### close --retain ### close --retain
This is like `--close` with different defaults: This is like `--close`, but with different defaults:
it prints a "retain earnings" transaction (with `retain:` tag), it prints a transaction that transfers Revenue and Expense balances to `equity:retained earnings` (and adds a `retain:` tag).
that transfers revenue and expense balances to `equity:retained earnings`.
This is a different kind of closing, called "retaining earnings" or "closing the books"; This is called "retaining earnings", or "closing the books".
it is traditionally performed by businesses at the end of each accounting period, Revenues and expenses are actually part of equity, kept separate temporarily for clarity;
to consolidate revenues and expenses into the main equity balance. once they have been seen and noted, at the end of each accounting period,
("Revenues" and "expenses" are actually equity by another name, kept separate temporarily for reporting purposes.) businesses normally consolidate them into equity,
In personal accounting you generally don't need to do this, In personal accounting, there's not much benefit from this, and most people don't do it.
unless you want the `balancesheetequity` report to show a zero total, demonstrating that the accounting equation (A-L=E) is satisfied. One reason to do it is to help the `balancesheetequity` report show a zero total,
demonstrating that the accounting equation (A-L=E) is satisfied.
### close customisation ### close customisation
@ -208,15 +207,15 @@ After this, to see 2022's end-of-year balances you must exclude the closing bala
$ hledger -f 2022.journal bs not:desc:'closing balances' $ hledger -f 2022.journal bs not:desc:'closing balances'
``` ```
For more flexibility, it helps to tag closing and opening transactions with eg `start:NEWYEAR`, For more flexibility, it helps to tag closing and opening transactions with eg `clopen:NEWYEAR`,
then you can ensure correct balances by excluding all opening/closing transactions except the first, like so: then you can ensure correct balances by excluding all opening/closing transactions except the first, like so:
```cli ```cli
$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start' $ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen'
$ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:start=2021 or not tag:start' $ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:clopen=2021 or not tag:clopen'
$ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:start=2022 or not tag:start' $ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:clopen=2022 or not tag:clopen'
$ hledger bs -Y -f 2021.j expr:'tag:start=2021 or not tag:start' $ hledger bs -Y -f 2021.j expr:'tag:clopen=2021 or not tag:clopen'
$ hledger bs -Y -f 2022.j expr:'tag:start=2022 or not tag:start' $ hledger bs -Y -f 2022.j expr:'tag:clopen=2022 or not tag:clopen'
$ hledger bs -Y -f 2023.j # unclosed file, no query needed $ hledger bs -Y -f 2023.j # unclosed file, no query needed
``` ```