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

;doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2024-01-26 22:49:07 -10:00
parent 015943b93d
commit 32ef1e3dd9
9 changed files with 2598 additions and 2423 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
hledger-ui/hledger-ui.1
View File

@ -113,9 +113,6 @@ Field separator to expect when reading CSV (default: \[aq],\[aq])
\f[CR]\-\-alias=OLD=NEW\f[R] \f[CR]\-\-alias=OLD=NEW\f[R]
rename accounts named OLD to NEW rename accounts named OLD to NEW
.TP .TP
\f[CR]\-\-anon\f[R]
anonymize accounts and payees
.TP
\f[CR]\-\-pivot FIELDNAME\f[R] \f[CR]\-\-pivot FIELDNAME\f[R]
use some other field or tag for the account name use some other field or tag for the account name
.TP .TP

71
hledger-ui/hledger-ui.info
View File

@ -148,9 +148,6 @@ File: hledger-ui.info, Node: General input options, Next: General reporting op
'--alias=OLD=NEW' '--alias=OLD=NEW'
rename accounts named OLD to NEW rename accounts named OLD to NEW
'--anon'
anonymize accounts and payees
'--pivot FIELDNAME' '--pivot FIELDNAME'
use some other field or tag for the account name use some other field or tag for the account name
@ -680,40 +677,40 @@ Node: General help options2951
Ref: #general-help-options3100 Ref: #general-help-options3100
Node: General input options3382 Node: General input options3382
Ref: #general-input-options3567 Ref: #general-input-options3567
Node: General reporting options4269 Node: General reporting options4224
Ref: #general-reporting-options4433 Ref: #general-reporting-options4388
Node: MOUSE7823 Node: MOUSE7778
Ref: #mouse7918 Ref: #mouse7873
Node: KEYS8155 Node: KEYS8110
Ref: #keys8248 Ref: #keys8203
Node: SCREENS12903 Node: SCREENS12858
Ref: #screens13001 Ref: #screens12956
Node: Menu13581 Node: Menu13536
Ref: #menu13674 Ref: #menu13629
Node: Cash accounts13869 Node: Cash accounts13824
Ref: #cash-accounts14011 Ref: #cash-accounts13966
Node: Balance sheet accounts14195 Node: Balance sheet accounts14150
Ref: #balance-sheet-accounts14376 Ref: #balance-sheet-accounts14331
Node: Income statement accounts14496 Node: Income statement accounts14451
Ref: #income-statement-accounts14682 Ref: #income-statement-accounts14637
Node: All accounts14846 Node: All accounts14801
Ref: #all-accounts14992 Ref: #all-accounts14947
Node: Register15174 Node: Register15129
Ref: #register15298 Ref: #register15253
Node: Transaction17582 Node: Transaction17537
Ref: #transaction17705 Ref: #transaction17660
Node: Error19122 Node: Error19077
Ref: #error19216 Ref: #error19171
Node: TIPS19460 Node: TIPS19415
Ref: #tips19559 Ref: #tips19514
Node: Watch mode19601 Node: Watch mode19556
Ref: #watch-mode19708 Ref: #watch-mode19663
Node: Debug output21167 Node: Debug output21122
Ref: #debug-output21278 Ref: #debug-output21233
Node: ENVIRONMENT21490 Node: ENVIRONMENT21445
Ref: #environment21600 Ref: #environment21555
Node: BUGS21791 Node: BUGS21746
Ref: #bugs21874 Ref: #bugs21829
 
End Tag Table End Tag Table

2
hledger-ui/hledger-ui.txt
View File

@ -102,8 +102,6 @@ OPTIONS
--alias=OLD=NEW --alias=OLD=NEW
rename accounts named OLD to NEW rename accounts named OLD to NEW
--anon anonymize accounts and payees
--pivot FIELDNAME --pivot FIELDNAME
use some other field or tag for the account name use some other field or tag for the account name

3
hledger-web/hledger-web.1
View File

@ -160,9 +160,6 @@ Field separator to expect when reading CSV (default: \[aq],\[aq])
\f[CR]\-\-alias=OLD=NEW\f[R] \f[CR]\-\-alias=OLD=NEW\f[R]
rename accounts named OLD to NEW rename accounts named OLD to NEW
.TP .TP
\f[CR]\-\-anon\f[R]
anonymize accounts and payees
.TP
\f[CR]\-\-pivot FIELDNAME\f[R] \f[CR]\-\-pivot FIELDNAME\f[R]
use some other field or tag for the account name use some other field or tag for the account name
.TP .TP

39
hledger-web/hledger-web.info
View File

@ -189,9 +189,6 @@ File: hledger-web.info, Node: General input options, Next: General reporting o
'--alias=OLD=NEW' '--alias=OLD=NEW'
rename accounts named OLD to NEW rename accounts named OLD to NEW
'--anon'
anonymize accounts and payees
'--pivot FIELDNAME' '--pivot FIELDNAME'
use some other field or tag for the account name use some other field or tag for the account name
@ -638,24 +635,24 @@ Node: General help options5257
Ref: #general-help-options5407 Ref: #general-help-options5407
Node: General input options5689 Node: General input options5689
Ref: #general-input-options5875 Ref: #general-input-options5875
Node: General reporting options6577 Node: General reporting options6532
Ref: #general-reporting-options6742 Ref: #general-reporting-options6697
Node: PERMISSIONS10132 Node: PERMISSIONS10087
Ref: #permissions10271 Ref: #permissions10226
Node: EDITING UPLOADING DOWNLOADING11483 Node: EDITING UPLOADING DOWNLOADING11438
Ref: #editing-uploading-downloading11664 Ref: #editing-uploading-downloading11619
Node: RELOADING12498 Node: RELOADING12453
Ref: #reloading12632 Ref: #reloading12587
Node: JSON API13065 Node: JSON API13020
Ref: #json-api13180 Ref: #json-api13135
Node: DEBUG OUTPUT18668 Node: DEBUG OUTPUT18623
Ref: #debug-output18793 Ref: #debug-output18748
Node: Debug output18820 Node: Debug output18775
Ref: #debug-output-118921 Ref: #debug-output-118876
Node: ENVIRONMENT19338 Node: ENVIRONMENT19293
Ref: #environment19457 Ref: #environment19412
Node: BUGS19574 Node: BUGS19529
Ref: #bugs19658 Ref: #bugs19613
 
End Tag Table End Tag Table

2
hledger-web/hledger-web.txt
View File

@ -142,8 +142,6 @@ OPTIONS
--alias=OLD=NEW --alias=OLD=NEW
rename accounts named OLD to NEW rename accounts named OLD to NEW
--anon anonymize accounts and payees
--pivot FIELDNAME --pivot FIELDNAME
use some other field or tag for the account name use some other field or tag for the account name

437
hledger/hledger.1
View File

@ -343,9 +343,6 @@ Field separator to expect when reading CSV (default: \[aq],\[aq])
\f[CR]\-\-alias=OLD=NEW\f[R] \f[CR]\-\-alias=OLD=NEW\f[R]
rename accounts named OLD to NEW rename accounts named OLD to NEW
.TP .TP
\f[CR]\-\-anon\f[R]
anonymize accounts and payees
.TP
\f[CR]\-\-pivot FIELDNAME\f[R] \f[CR]\-\-pivot FIELDNAME\f[R]
use some other field or tag for the account name use some other field or tag for the account name
.TP .TP
@ -992,6 +989,11 @@ $ hledger print \-c \[aq]$1.000,0\[aq]
This option can repeated to set the display style for multiple This option can repeated to set the display style for multiple
commodities/currencies. commodities/currencies.
Its argument is as described in the commodity directive. Its argument is as described in the commodity directive.
.PP
hledger will occasionally make some additional adjustments to number
formatting, eg adding a trailing decimal mark to disambiguate numbers
with digit group marks; for details, see Amount formatting,
parseability.
.SS Colour .SS Colour
In terminal output, some commands can produce colour when the terminal In terminal output, some commands can produce colour when the terminal
supports it: supports it:
@ -1667,6 +1669,11 @@ reports.
When rounding, hledger uses banker\[aq]s rounding (it rounds to the When rounding, hledger uses banker\[aq]s rounding (it rounds to the
nearest even digit). nearest even digit).
So eg 0.5 displayed with zero decimal digits appears as \[dq]0\[dq]. So eg 0.5 displayed with zero decimal digits appears as \[dq]0\[dq].
.SS Number format
hledger will occasionally make some additional adjustments to number
formatting, eg adding a trailing decimal mark to disambiguate numbers
with digit group marks; for details, see Amount formatting,
parseability.
.PP .PP
.SS Costs .SS Costs
After a posting amount, you can note its cost (when buying) or selling After a posting amount, you can note its cost (when buying) or selling
@ -2018,8 +2025,11 @@ by a full colon, in a transaction or posting or account directive\[aq]s
comment. comment.
(This is an exception to the usual rule that things in comments are (This is an exception to the usual rule that things in comments are
ignored.) ignored.)
Eg, here four different tags are recorded: one on the checking account, You can write multiple tags separated by comma, and/or you can add more
two on the transaction, and one on the expenses posting: comment lines and write more tags there.
.PP
Here five different tags are recorded: one on the checking account, two
on the transaction, and two on the expenses posting:
.IP .IP
.EX .EX
account assets:checking ; accounttag: account assets:checking ; accounttag:
@ -2027,18 +2037,58 @@ account assets:checking ; accounttag:
2017/1/16 bought groceries ; transactiontag\-1: 2017/1/16 bought groceries ; transactiontag\-1:
; transactiontag\-2: ; transactiontag\-2:
assets:checking $\-1 assets:checking $\-1
expenses:food $1 ; postingtag: expenses:food $1 ; postingtag:, another\-posting\-tag:
.EE .EE
.PP .PP
Postings also inherit tags from their transaction and their account.
And transactions also acquire tags from their postings (and
postings\[aq] accounts).
So in the example above, the expenses posting effectively has all four
tags (by inheriting from account and transaction), and the transaction
also has all four tags (by acquiring from the expenses posting).
.PP
You can list tag names with \f[CR]hledger tags [NAMEREGEX]\f[R], or You can list tag names with \f[CR]hledger tags [NAMEREGEX]\f[R], or
match by tag name with a \f[CR]tag:NAMEREGEX\f[R] query. match by tag name with a \f[CR]tag:NAMEREGEX\f[R] query.
.SS Tag inheritance
Postings also inherit tags from their transaction and their account.
And transactions also acquire tags from their postings (and
postings\[aq] accounts).
So in the example above, the expenses posting effectively has all five
tags (by inheriting from the account and transaction), and the
transaction also has all five tags (by acquiring from the expenses
posting).
.SS Tag names
Tag names are currently not very clearly specified; any sequence of
non\-whitespace characters followed by a colon may work.
.PP
The following tag names are generated by hledger or have special
significance to hledger, so you may want to avoid using them yourself:
.IP \[bu] 2
\f[CR]balances\f[R] \-\- a balance assertions transaction generated by
close
.IP \[bu] 2
\f[CR]retain\f[R] \-\- a retain earnings transaction generated by close
.IP \[bu] 2
\f[CR]start\f[R] \-\- a opening balances, closing balances or balance
assignment transaction generated by close
.IP \[bu] 2
\f[CR]generated\-transaction\f[R] \-\- a transaction generated by
\-\-forecast
.IP \[bu] 2
\f[CR]generated\-posting\f[R] \-\- a posting generated by \-\-auto
.IP \[bu] 2
\f[CR]modified\f[R] \-\- a transaction which has had postings added by
\-\-auto
.IP \[bu] 2
\f[CR]type\f[R] \-\- declares an account\[aq]s type in an account
declaration
.IP \[bu] 2
\f[CR]t\f[R] \-\- stores the (user defined, single letter) type of a 15m
unit of time parsed from timedot format
.PP
Some additional tag names with an underscore prefix are used internally
and not displayed in reports (but can be matched by queries):
.IP \[bu] 2
\f[CR]_generated\-transaction\f[R]
.IP \[bu] 2
\f[CR]_generated\-posting\f[R]
.IP \[bu] 2
\f[CR]_modified\f[R]
.IP \[bu] 2
\f[CR]_conversion\-matched\f[R]
.SS Tag values .SS Tag values
Tags can have a value, which is any text after the colon up until a Tags can have a value, which is any text after the colon up until a
comma or end of line (with surrounding whitespace removed). comma or end of line (with surrounding whitespace removed).
@ -4206,12 +4256,14 @@ By default they are OR\[aq]d (any one of them can match)
When a matcher is preceded by ampersand (\f[CR]&\f[R]) it will be When a matcher is preceded by ampersand (\f[CR]&\f[R]) it will be
AND\[aq]ed with the previous matcher (both of them must match) AND\[aq]ed with the previous matcher (both of them must match)
.IP \[bu] 2 .IP \[bu] 2
When a matcher is preceded by an exclamation mark (\f[CR]!\f[R]), the \f[I]Added in 1.32\f[R] When a matcher is preceded by an exclamation
matcher is negated (it may not match). mark (\f[CR]!\f[R]), the matcher is negated (it may not match).
.PP .PP
Currently there is a limitation: you can\[aq]t use both \f[CR]&\f[R] and Currently there is a limitation: you can\[aq]t use both \f[CR]&\f[R] and
\f[CR]!\f[R] on the same line (you can\[aq]t AND a negated matcher). \f[CR]!\f[R] on the same line (you can\[aq]t AND a negated matcher).
.SS Match groups .SS Match groups
\f[I]Added in 1.32\f[R]
.PP
Matchers can define match groups: parenthesised portions of the regular Matchers can define match groups: parenthesised portions of the regular
expression which are available for reference in field assignments. expression which are available for reference in field assignments.
Groups are enclosed in regular parentheses (\f[CR](\f[R] and Groups are enclosed in regular parentheses (\f[CR](\f[R] and
@ -5195,7 +5247,7 @@ one or more dots (period characters), each representing 0.25.
These are the dots in \[dq]timedot\[dq]. These are the dots in \[dq]timedot\[dq].
Spaces are ignored and can be used for grouping/alignment. Spaces are ignored and can be used for grouping/alignment.
.IP \[bu] 2 .IP \[bu] 2
one or more letters. \f[I]Added in 1.32\f[R] one or more letters.
These are like dots but they also generate a tag \f[CR]t:\f[R] (short These are like dots but they also generate a tag \f[CR]t:\f[R] (short
for \[dq]type\[dq]) with the letter as its value, and a separate posting for \[dq]type\[dq]) with the letter as its value, and a separate posting
for each of the values. for each of the values.
@ -7876,7 +7928,7 @@ memory, use the \f[CR]\-\-align\-all\f[R] flag.
This command also supports the output destination and output format This command also supports the output destination and output format
options. options.
The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R], The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
\f[CR]tsv\f[R], and \f[CR]json\f[R]. \f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].
.SS aregister and posting dates .SS aregister and posting dates
aregister always shows one line (and date and amount) per transaction. aregister always shows one line (and date and amount) per transaction.
But sometimes transactions have postings with different dates. But sometimes transactions have postings with different dates.
@ -7981,8 +8033,9 @@ commodities displayed on the same line or multiple lines
(\f[CR]\-\-layout\f[R]) (\f[CR]\-\-layout\f[R])
.PP .PP
This command supports the output destination and output format options, This command supports the output destination and output format options,
with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R], with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R]
\f[CR]json\f[R], and (multi\-period reports only:) \f[CR]html\f[R]. (\f[I]Added in 1.32\f[R]), \f[CR]json\f[R], and (multi\-period reports
only:) \f[CR]html\f[R].
In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative
amounts are shown in red. amounts are shown in red.
.PP .PP
@ -9041,7 +9094,8 @@ sign flipped.
.PP .PP
This command also supports the output destination and output format This command also supports the output destination and output format
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R], options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R]. \f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
\f[CR]json\f[R].
.SS balancesheetequity .SS balancesheetequity
(bse) (bse)
.PP .PP
@ -9149,7 +9203,8 @@ but with smarter account detection.
.PP .PP
This command also supports the output destination and output format This command also supports the output destination and output format
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R], options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R]. \f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
\f[CR]json\f[R].
.SS check .SS check
Check for various kinds of errors in your data. Check for various kinds of errors in your data.
.PP .PP
@ -9245,133 +9300,150 @@ against the real\-world balance.)
.SS close .SS close
(equity) (equity)
.PP .PP
A transaction\-generating command which generates several kinds of \f[CR]close\f[R] generates several kinds of \[dq]closing\[dq] and/or
\[dq]closing\[dq] and/or \[dq]opening\[dq] transactions useful in \[dq]opening\[dq] transactions, useful in certain situations, including
certain situations. migrating balances to a new journal file, retaining earnings into
It prints one or two transactions to stdout, but does not write them to equity, consolidating balances, or viewing lots.
the journal file; you can append or copy them there when you are happy Like \f[CR]print\f[R], it prints valid journal entries.
with the output. You can append or copy these to your journal file(s) when you are happy
with how they look.
.PP .PP
This command is most often used when migrating balances to a new journal \f[CR]close\f[R] currently has six modes, selected by a single mode
file, at the start of a new financial year. flag:
It can also be used to \[dq]retain earnings\[dq] (transfer revenues and .SS close \-\-migrate
expenses to equity), or as a sort of generic mover of balances from any This is the most common mode.
group of accounts to some other account. It prints a \[dq]closing balances\[dq] transaction that zeroes out all
So it currently has six modes, selected by a mode flag. asset and liability balances (by default), and an opposite \[dq]opening
Use only one of these flags at a time: balances\[dq] transaction that restores them again.
.IP "1." 3 The balancing account will be \f[CR]equity:opening/closing balances\f[R]
With \f[CR]\-\-close\f[R] (or no mode flag) it prints a \[dq]closing (or another specified by \f[CR]\-\-close\-acct\f[R] or
balances\[dq] transaction that zeroes out all the asset, liability, and \f[CR]\-\-open\-acct\f[R]).
equity account balances, by default (this requires inferred or declared .PP
account types). This is useful when migrating balances to a new journal file at the
Or, it will zero out the accounts matched by any ACCTQUERY arguments you start of a new year.
provide. Essentially, you run
All of the balances are transferred to a special \[dq]opening/closing \f[CR]hledger close \-\-migrate=NEWYEAR \-e NEWYEAR\f[R] and then copy
balances\[dq] equity account. the closing transaction to the end of the old file and the opening
.IP "2." 3 transaction to the start of the new file.
With \f[CR]\-\-open\f[R], it prints an opposite \[dq]opening The opening transaction sets correct starting balances in the new file
balances\[dq] transaction that restores the same account balances, when it is used alone, and the closing transaction keeps balances
starting from zero. correct when you use both old and new files together, by cancelling out
This mode is similar to Ledger\[aq]s equity command. the following opening transaction and preventing buildup of duplicated
.IP "3." 3 opening balances.
With \f[CR]\-\-migrate\f[R], it prints both the closing and opening Think of the closing/opening pair as \[dq]moving the balances into the
transactions above. next file\[dq].
This is a common way to migrate balances to a new file at year end; run .PP
\f[CR]hledger close \-\-migrate \-e NEWYEAR\f[R] (\-e influences the You can close a different set of accounts by providing a query.
transaction date) and add the closing transaction at the end of the old Eg if you want to include equity, you can add
file, and the opening transaction at the start of the new file. \f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R] arguments.
Doing this means you can include past year files in your reports at any (The balancing account is always excluded.)
time without disturbing asset/liability/equity balances, because the Revenues and expenses usually are not migrated to a new file directly;
closing balances transaction cancels out the following opening balances see \f[CR]\-\-retain\f[R] below.
transaction. .PP
You will sometimes need to exclude these transactions from reports, eg The generated transactions will have a \f[CR]start:\f[R] tag, with its
to see an end of year balance sheet; a \f[CR]not:opening/closing\f[R] value set to \f[CR]\-\-migrate\f[R]\[aq]s \f[CR]NEW\f[R] argument if
query argument should do. any, for easier matching or exclusion.
You should probably also use this query when \f[CR]close\f[R]\-ing, to When \f[CR]NEW\f[R] is not specified, it will be inferred if possible by
exclude the \[dq]opening/closing balances\[dq] account which might incrementing a number (eg a year number) within the default
otherwise cause problems. journal\[aq]s main file name.
Or you can just migrate assets and liabilities: The other modes behave similarly.
\f[CR]hledger close type:AL\f[R]. .SS close \-\-close
Most people don\[aq]t need to migrate equity. This prints just the closing balances transaction of
And revenues and expenses usually should not be migrated. \f[CR]\-\-migrate\f[R].
.IP "4." 3 It is the default behaviour if you specify no mode flag.
With \f[CR]\-\-assert\f[R] it prints a \[dq]closing balances\[dq] Using the customisation options below, you can move balances from any
transaction that just asserts the current balances, without changing set of accounts to a different account.
them. .SS close \-\-open
This can be useful as documention and to guard against errors and This prints just the opening balances transaction of
changes. \f[CR]\-\-migrate\f[R].
.IP "5." 3 It is similar to Ledger\[aq]s equity command.
With \f[CR]\-\-assign\f[R] it prints an \[dq]opening balances\[dq] .SS close \-\-assert
transaction that restores the account balances using balance This prints a \[dq]closing balances\[dq] transaction (with
assignments. \f[CR]balances:\f[R] tag), that just declares balance assertions for the
current balances without changing them.
It could be useful as documention and to guard against changes.
.SS close \-\-assign
This prints an \[dq]opening balances\[dq] transaction that restores the
account balances using balance assignments.
Balance assignments work regardless of any previous balance, so a Balance assignments work regardless of any previous balance, so a
preceding closing balances transaction is not needed. preceding closing balances transaction is not needed.
This is an alternative to \f[CR]\-\-close\f[R] and \f[CR]\-\-open\f[R]:
at year end, \f[CR]hledger close \-\-assert \-e NEWYEAR\f[R] in the old
file (optional, but useful for error checking), and
\f[CR]hledger close \-\-assign \-e NEWYEAR\f[R] in the new file.
This might be more convenient, eg if you are often doing cleanups or
fixes which would break closing/opening transactions.
.IP "6." 3
With \f[CR]\-\-retain\f[R], it prints a \[dq]retain earnings\[dq]
transaction that transfers revenue and expense balances to
\f[CR]equity:retained earnings\f[R].
This is a traditional end\-of\-period bookkeeping operation also called
\[dq]closing the books\[dq]; 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.
.PP .PP
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 \f[CR]\-\-migrate\f[R] is generally the best way to set to set
balances in new files, for now.
.SS close \-\-retain
This is like \f[CR]\-\-close\f[R] with different defaults: it prints a
\[dq]retain earnings\[dq] transaction (with \f[CR]retain:\f[R] tag),
that transfers revenue and expense balances to
\f[CR]equity:retained earnings\f[R].
.PP
This is a different kind of closing, called \[dq]retaining earnings\[dq]
or \[dq]closing the books\[dq]; it is traditionally performed by
businesses at the end of each accounting period, to consolidate revenues
and expenses into the main equity balance.
(\[dq]Revenues\[dq] and \[dq]expenses\[dq] are actually equity by
another name, kept separate temporarily for reporting purposes.)
.PP
In personal accounting you generally don\[aq]t need to do this, unless
you want the \f[CR]balancesheetequity\f[R] report to show a zero total,
demonstrating that the accounting equation (A\-L=E) is satisfied.
.SS close customisation
In all modes, the following things can be overridden: In all modes, the following things can be overridden:
.IP \[bu] 2 .IP \[bu] 2
the transaction descriptions can be changed with the accounts to be closed/opened, with account query arguments
\f[CR]\-\-close\-desc=DESC\f[R] and \f[CR]\-\-open\-desc=DESC\f[R]
.IP \[bu] 2 .IP \[bu] 2
the account to transfer to and from can be changed with the balancing account, with \f[CR]\-\-close\-acct=ACCT\f[R] and/or
\f[CR]\-\-close\-acct=ACCT\f[R] and \f[CR]\-\-open\-acct=ACCT\f[R] \f[CR]\-\-open\-acct=ACCT\f[R]
.IP \[bu] 2 .IP \[bu] 2
the accounts to be closed/opened can be changed with the transaction descriptions, with \f[CR]\-\-close\-desc=DESC\f[R] and
\f[CR]ACCTQUERY\f[R] (account query arguments). \f[CR]\-\-open\-desc=DESC\f[R]
.IP \[bu] 2 .IP \[bu] 2
the closing/opening dates can be changed with \f[CR]\-e DATE\f[R] (a the transaction\[aq]s tag value, with a \f[CR]\-\-MODE=NEW\f[R] option
report end date) argument
.IP \[bu] 2
the closing/opening dates, with \f[CR]\-e OPENDATE\f[R]
.PP .PP
By default just one destination/source posting will be used, with its By default, the closing date is yesterday, or the journal\[aq]s end
amount left implicit. date, whichever is later; and the opening date is always one day after
With \f[CR]\-\-x/\-\-explicit\f[R], the amount will be shown explicitly, the closing date.
and if it involves multiple commodities, a separate posting will be You can change these by specifying a report end date; the closing date
generated for each of them (similar to \f[CR]print \-x\f[R]). will be the last day of the report period.
Eg \f[CR]\-e 2024\f[R] means \[dq]close on 2023\-12\-31, open on
2024\-01\-01\[dq].
.PP .PP
With \f[CR]\-\-show\-costs\f[R], any amount costs are shown, with With \f[CR]\-\-x/\-\-explicit\f[R], the balancing amount will be shown
separate postings for each cost. explicitly, and if it involves multiple commodities, a separate posting
This is currently the best way to view investment lots. will be generated for each of them (similar to \f[CR]print \-x\f[R]).
If you have many currency conversion or investment transactions, it can
generate very large journal entries.
.PP .PP
With \f[CR]\-\-interleaved\f[R], each individual transfer is shown with With \f[CR]\-\-interleaved\f[R], each individual transfer is shown with
source and destination postings next to each other. source and destination postings next to each other (perhaps useful for
This could be useful for troubleshooting. troubleshooting).
.PP .PP
The default closing date is yesterday, or the journal\[aq]s end date, With \f[CR]\-\-show\-costs\f[R], balances\[aq] costs are also shown,
whichever is later. with different costs kept separate.
You can change this by specifying a report end date with \f[CR]\-e\f[R]. This may generate very large journal entries, if you have many currency
The last day of the report period will be the closing date, eg conversions or investment transactions.
\f[CR]\-e 2024\f[R] means \[dq]close on 2023\-12\-31\[dq]. \f[CR]close \-\-show\-costs\f[R] is currently the best way to view
The opening date is always the day after the closing date. investment lots with hledger.
(To move or dispose of lots, see the more capable
\f[CR]hledger\-move\f[R] script.)
.SS close and balance assertions .SS close and balance assertions
Balance assertions will be generated, verifying that the accounts have \f[CR]close\f[R] adds balance assertions verifying that the accounts
been reset to zero (and then restored to their previous balances, if have been reset to zero in a closing transaction or restored to their
there is an opening transaction). previous balances in an opening transaction.
.PP
These provide useful error checking, but you can ignore them temporarily These provide useful error checking, but you can ignore them temporarily
with \f[CR]\-I\f[R], or remove them if you prefer. with \f[CR]\-I\f[R], or remove them if you prefer.
.PP .PP
You probably should avoid filtering transactions by status or realness When running \f[CR]close\f[R] you should probably avoid using
(\f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R]), or generating \f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R] (filtering by status
postings (\f[CR]\-\-auto\f[R]), with this command, since the balance or realness) or \f[CR]\-\-auto\f[R] (generating postings), since the
assertions would depend on these. generated balance assertions would then require these.
.PP .PP
Note custom posting dates spanning the file boundary will disrupt the Transactions with multiple dates (eg posting dates) spanning the file
balance assertions: boundary also can disrupt the balance assertions:
.IP .IP
.EX .EX
2023\-12\-30 a purchase made in december, cleared in january 2023\-12\-30 a purchase made in december, cleared in january
@ -9379,9 +9451,9 @@ balance assertions:
assets:bank:checking \-5 ; date: 2023\-01\-02 assets:bank:checking \-5 ; date: 2023\-01\-02
.EE .EE
.PP .PP
To solve that you can transfer the money to and from a temporary To solve this you can transfer the money to and from a temporary
account, in effect splitting the multi\-day transaction into two account, splitting the multi\-day transaction into two single\-day
single\-day transactions: transactions:
.IP .IP
.EX .EX
; in 2022.journal: ; in 2022.journal:
@ -9394,7 +9466,8 @@ single\-day transactions:
equity:pending 5 = 0 equity:pending 5 = 0
assets:bank:checking \-5 assets:bank:checking \-5
.EE .EE
.SS Example: retain earnings .SS close examples
.SS Retain earnings
Record 2022\[aq]s revenues/expenses as retained earnings on Record 2022\[aq]s revenues/expenses as retained earnings on
2022\-12\-31, appending the generated transaction to the journal: 2022\-12\-31, appending the generated transaction to the journal:
.IP .IP
@ -9402,15 +9475,14 @@ Record 2022\[aq]s revenues/expenses as retained earnings on
$ hledger close \-\-retain \-f 2022.journal \-p 2022 >> 2022.journal $ hledger close \-\-retain \-f 2022.journal \-p 2022 >> 2022.journal
.EE .EE
.PP .PP
Note 2022\[aq]s income statement will now show only zeroes, because After this, to see 2022\[aq]s revenues and expenses you must exclude the
revenues and expenses have been moved entirely to equity. retain earnings transaction:
To see them again, you could exclude the retain transaction:
.IP .IP
.EX .EX
$ hledger \-f 2022.journal is not:desc:\[aq]retain earnings\[aq] $ hledger \-f 2022.journal is not:desc:\[aq]retain earnings\[aq]
.EE .EE
.SS Example: migrate balances to a new file .SS Migrate balances to a new file
Close assets/liabilities/equity on 2022\-12\-31 and re\-open them on Close assets/liabilities on 2022\-12\-31 and re\-open them on
2023\-01\-01: 2023\-01\-01:
.IP .IP
.EX .EX
@ -9419,74 +9491,27 @@ $ hledger close \-\-migrate \-f 2022.journal \-p 2022
# copy/paste the opening transaction to the start of 2023.journal # copy/paste the opening transaction to the start of 2023.journal
.EE .EE
.PP .PP
Now 2022\[aq]s balance sheet will show only zeroes, indicating a After this, to see 2022\[aq]s end\-of\-year balances you must exclude
balanced accounting equation. the closing balances transaction:
(Unless you are using \[at]/\[at]\[at] notation \- in that case, try
adding \-\-infer\-equity.)
To see the end\-of\-year balances again, you could exclude the closing
transaction:
.IP .IP
.EX .EX
$ hledger \-f 2022.journal bs not:desc:\[aq]closing balances\[aq] $ hledger \-f 2022.journal bs not:desc:\[aq]closing balances\[aq]
.EE .EE
.SS 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
\f[CR]print\f[R] and \f[CR]register\f[R].
You can exclude them as shown above, but \f[CR]not:desc:...\f[R] 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:
.PP .PP
Add \f[CR]clopen:\f[R] tags to all opening/closing balances transactions For more flexibility, it helps to tag closing and opening transactions
except the first, like this: with eg \f[CR]start:NEWYEAR\f[R], then you can ensure correct balances
by excluding all opening/closing transactions except the first, like so:
.IP .IP
.EX .EX
; 2021.journal $ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2021 or not tag:start\[aq]
2021\-06\-01 first opening balances $ hledger bs \-Y \-f 2021.j \-f 2022.j expr:\[aq]tag:start=2021 or not tag:start\[aq]
\&... $ hledger bs \-Y \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2022 or not tag:start\[aq]
2021\-12\-31 closing balances ; clopen:2022 $ hledger bs \-Y \-f 2021.j expr:\[aq]tag:start=2021 or not tag:start\[aq]
\&... $ hledger bs \-Y \-f 2022.j expr:\[aq]tag:start=2022 or not tag:start\[aq]
.EE $ hledger bs \-Y \-f 2023.j # unclosed file, no query needed
.IP
.EX
; 2022.journal
2022\-01\-01 opening balances ; clopen:2022
\&...
2022\-12\-31 closing balances ; clopen:2023
\&...
.EE
.IP
.EX
; 2023.journal
2023\-01\-01 opening balances ; clopen:2023
\&...
.EE
.PP
Now, assuming a combined journal like:
.IP
.EX
; all.journal
include 2021.journal
include 2022.journal
include 2023.journal
.EE
.PP
The \f[CR]clopen:\f[R] tag can exclude all but the first opening
transaction.
To show a clean multi\-year checking register:
.IP
.EX
$ hledger \-f all.journal areg checking not:tag:clopen
.EE
.PP
And the year values allow more precision.
To show 2022\[aq]s year\-end balance sheet:
.IP
.EX
$ hledger \-f all.journal bs \-e2023 not:tag:clopen=2023
.EE .EE
.SS More detailed close examples
See examples/multi\-year.
.SS codes .SS codes
List the codes seen in transactions, in the order parsed. List the codes seen in transactions, in the order parsed.
.PP .PP
@ -9816,7 +9841,8 @@ sign flipped.
.PP .PP
This command also supports the output destination and output format This command also supports the output destination and output format
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R], options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R]. \f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
\f[CR]json\f[R].
.SS notes .SS notes
List the unique notes that appear in transactions. List the unique notes that appear in transactions.
.PP .PP
@ -9928,9 +9954,9 @@ their symbol placement, decimal mark, and digit group marks will be made
consistent. consistent.
By default, decimal digits are shown as they are written in the journal. By default, decimal digits are shown as they are written in the journal.
.PP .PP
With the \f[CR]\-\-round\f[R] option, \f[CR]print\f[R] will try With the \f[CR]\-\-round\f[R] (\f[I]Added in 1.32\f[R]) option,
increasingly hard to display decimal digits according to the commodity \f[CR]print\f[R] will try increasingly hard to display decimal digits
display styles: according to the commodity display styles:
.IP \[bu] 2 .IP \[bu] 2
\f[CR]\-\-round=none\f[R] show amounts with original precisions \f[CR]\-\-round=none\f[R] show amounts with original precisions
(default) (default)
@ -9988,8 +10014,9 @@ the program exit code will be non\-zero.
.SS print output format .SS print output format
This command also supports the output destination and output format This command also supports the output destination and output format
options The output formats supported are \f[CR]txt\f[R], options The output formats supported are \f[CR]txt\f[R],
\f[CR]beancount\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R], \f[CR]json\f[R] \f[CR]beancount\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]csv\f[R],
and \f[CR]sql\f[R]. \f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]json\f[R] and
\f[CR]sql\f[R].
.PP .PP
The \f[CR]beancount\f[R] format tries to produce Beancount\-compatible The \f[CR]beancount\f[R] format tries to produce Beancount\-compatible
output, as follows: output, as follows:
@ -10211,7 +10238,7 @@ $ hledger reg \-w $COLUMNS,40 # use terminal width, & description width 40
.PP .PP
This command also supports the output destination and output format This command also supports the output destination and output format
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R], options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
\f[CR]tsv\f[R], and \f[CR]json\f[R]. \f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].
.SS rewrite .SS rewrite
Print all transactions, rewriting the postings of matched transactions. Print all transactions, rewriting the postings of matched transactions.
For now the only rewrite available is adding new postings, like print For now the only rewrite available is adding new postings, like print

1815
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

393
hledger/hledger.txt
View File

@ -251,8 +251,6 @@ Options
--alias=OLD=NEW --alias=OLD=NEW
rename accounts named OLD to NEW rename accounts named OLD to NEW
--anon anonymize accounts and payees
--pivot FIELDNAME --pivot FIELDNAME
use some other field or tag for the account name use some other field or tag for the account name
@ -713,6 +711,11 @@ Output
ties/currencies. Its argument is as described in the commodity direc- ties/currencies. Its argument is as described in the commodity direc-
tive. tive.
hledger will occasionally make some additional adjustments to number
formatting, eg adding a trailing decimal mark to disambiguate numbers
with digit group marks; for details, see Amount formatting, parseabil-
ity.
Colour Colour
In terminal output, some commands can produce colour when the terminal In terminal output, some commands can produce colour when the terminal
supports it: supports it:
@ -1284,6 +1287,12 @@ Journal
rounds to the nearest even digit). So eg 0.5 displayed with zero deci- rounds to the nearest even digit). So eg 0.5 displayed with zero deci-
mal digits appears as "0". mal digits appears as "0".
Number format
hledger will occasionally make some additional adjustments to number
formatting, eg adding a trailing decimal mark to disambiguate numbers
with digit group marks; for details, see Amount formatting, parseabil-
ity.
Costs Costs
After a posting amount, you can note its cost (when buying) or selling After a posting amount, you can note its cost (when buying) or selling
price (when selling) in another commodity, by writing either @ UNIT- price (when selling) in another commodity, by writing either @ UNIT-
@ -1581,27 +1590,66 @@ Journal
They are written as a word (optionally hyphenated) immediately followed They are written as a word (optionally hyphenated) immediately followed
by a full colon, in a transaction or posting or account directive's by a full colon, in a transaction or posting or account directive's
comment. (This is an exception to the usual rule that things in com- comment. (This is an exception to the usual rule that things in com-
ments are ignored.) Eg, here four different tags are recorded: one on ments are ignored.) You can write multiple tags separated by comma,
the checking account, two on the transaction, and one on the expenses and/or you can add more comment lines and write more tags there.
posting:
Here five different tags are recorded: one on the checking account, two
on the transaction, and two on the expenses posting:
account assets:checking ; accounttag: account assets:checking ; accounttag:
2017/1/16 bought groceries ; transactiontag-1: 2017/1/16 bought groceries ; transactiontag-1:
; transactiontag-2: ; transactiontag-2:
assets:checking $-1 assets:checking $-1
expenses:food $1 ; postingtag: expenses:food $1 ; postingtag:, another-posting-tag:
Postings also inherit tags from their transaction and their account.
And transactions also acquire tags from their postings (and postings'
accounts). So in the example above, the expenses posting effectively
has all four tags (by inheriting from account and transaction), and the
transaction also has all four tags (by acquiring from the expenses
posting).
You can list tag names with hledger tags [NAMEREGEX], or match by tag You can list tag names with hledger tags [NAMEREGEX], or match by tag
name with a tag:NAMEREGEX query. name with a tag:NAMEREGEX query.
Tag inheritance
Postings also inherit tags from their transaction and their account.
And transactions also acquire tags from their postings (and postings'
accounts). So in the example above, the expenses posting effectively
has all five tags (by inheriting from the account and transaction), and
the transaction also has all five tags (by acquiring from the expenses
posting).
Tag names
Tag names are currently not very clearly specified; any sequence of
non-whitespace characters followed by a colon may work.
The following tag names are generated by hledger or have special sig-
nificance to hledger, so you may want to avoid using them yourself:
o balances -- a balance assertions transaction generated by close
o retain -- a retain earnings transaction generated by close
o start -- a opening balances, closing balances or balance assignment
transaction generated by close
o generated-transaction -- a transaction generated by --forecast
o generated-posting -- a posting generated by --auto
o modified -- a transaction which has had postings added by --auto
o type -- declares an account's type in an account declaration
o t -- stores the (user defined, single letter) type of a 15m unit of
time parsed from timedot format
Some additional tag names with an underscore prefix are used internally
and not displayed in reports (but can be matched by queries):
o _generated-transaction
o _generated-posting
o _modified
o _conversion-matched
Tag values Tag values
Tags can have a value, which is any text after the colon up until a Tags can have a value, which is any text after the colon up until a
comma or end of line (with surrounding whitespace removed). Note this comma or end of line (with surrounding whitespace removed). Note this
@ -3303,13 +3351,15 @@ CSV
o When a matcher is preceded by ampersand (&) it will be AND'ed with o When a matcher is preceded by ampersand (&) it will be AND'ed with
the previous matcher (both of them must match) the previous matcher (both of them must match)
o When a matcher is preceded by an exclamation mark (!), the matcher is o Added in 1.32 When a matcher is preceded by an exclamation mark (!),
negated (it may not match). the matcher is negated (it may not match).
Currently there is a limitation: you can't use both & and ! on the same Currently there is a limitation: you can't use both & and ! on the same
line (you can't AND a negated matcher). line (you can't AND a negated matcher).
Match groups Match groups
Added in 1.32
Matchers can define match groups: parenthesised portions of the regular Matchers can define match groups: parenthesised portions of the regular
expression which are available for reference in field assignments. expression which are available for reference in field assignments.
Groups are enclosed in regular parentheses (( and )) and can be nested. Groups are enclosed in regular parentheses (( and )) and can be nested.
@ -4125,10 +4175,11 @@ Timedot
These are the dots in "timedot". Spaces are ignored and can be These are the dots in "timedot". Spaces are ignored and can be
used for grouping/alignment. used for grouping/alignment.
o one or more letters. These are like dots but they also generate a o Added in 1.32 one or more letters. These are like dots but they
tag t: (short for "type") with the letter as its value, and a sepa- also generate a tag t: (short for "type") with the letter as its
rate posting for each of the values. This provides a second dimen- value, and a separate posting for each of the values. This pro-
sion of categorisation, viewable in reports with --pivot t. vides a second dimension of categorisation, viewable in reports
with --pivot t.
o An optional comment following a semicolon (a hledger-style posting o An optional comment following a semicolon (a hledger-style posting
comment). comment).
@ -6044,7 +6095,8 @@ PART 4: COMMANDS
--align-all flag. --align-all flag.
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions. The output formats supported are txt, csv, tsv, and json. tions. The output formats supported are txt, csv, tsv (Added in 1.32),
and json.
aregister and posting dates aregister and posting dates
aregister always shows one line (and date and amount) per transaction. aregister always shows one line (and date and amount) per transaction.
@ -6143,9 +6195,9 @@ PART 4: COMMANDS
o commodities displayed on the same line or multiple lines (--layout) o commodities displayed on the same line or multiple lines (--layout)
This command supports the output destination and output format options, This command supports the output destination and output format options,
with output formats txt, csv, tsv, json, and (multi-period reports with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe-
only:) html. In txt output in a colour-supporting terminal, negative riod reports only:) html. In txt output in a colour-supporting termi-
amounts are shown in red. nal, negative amounts are shown in red.
The --related/-r flag shows the balance of the other postings in the The --related/-r flag shows the balance of the other postings in the
transactions of the postings which would normally be shown. transactions of the postings which would normally be shown.
@ -6986,7 +7038,8 @@ PART 4: COMMANDS
flipped. flipped.
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, tsv, html, and json. tions The output formats supported are txt, csv, tsv (Added in 1.32),
html, and json.
balancesheetequity balancesheetequity
(bse) (bse)
@ -7080,7 +7133,8 @@ PART 4: COMMANDS
not:receivable, but with smarter account detection. not:receivable, but with smarter account detection.
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, tsv, html, and json. tions The output formats supported are txt, csv, tsv (Added in 1.32),
html, and json.
check check
Check for various kinds of errors in your data. Check for various kinds of errors in your data.
@ -7172,124 +7226,145 @@ PART 4: COMMANDS
close close
(equity) (equity)
A transaction-generating command which generates several kinds of close generates several kinds of "closing" and/or "opening" transac-
"closing" and/or "opening" transactions useful in certain situations. tions, useful in certain situations, including migrating balances to a
It prints one or two transactions to stdout, but does not write them to new journal file, retaining earnings into equity, consolidating bal-
the journal file; you can append or copy them there when you are happy ances, or viewing lots. Like print, it prints valid journal entries.
with the output. You can append or copy these to your journal file(s) when you are happy
with how they look.
This command is most often used when migrating balances to a new jour- close currently has six modes, selected by a single mode flag:
nal 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" trans- close --migrate
action that zeroes out all the asset, liability, and equity account This is the most common mode. It prints a "closing balances" transac-
balances, by default (this requires inferred or declared account tion that zeroes out all asset and liability balances (by default), and
types). Or, it will zero out the accounts matched by any ACCTQUERY an opposite "opening balances" transaction that restores them again.
arguments you provide. All of the balances are transferred to a The balancing account will be equity:opening/closing balances (or an-
special "opening/closing balances" equity account. other specified by --close-acct or --open-acct).
2. With --open, it prints an opposite "opening balances" transaction This is useful when migrating balances to a new journal file at the
that restores the same account balances, starting from zero. This start of a new year. Essentially, you run hledger close --mi-
mode is similar to Ledger's equity command. grate=NEWYEAR -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 bal-
ances correct when you use both old and new files together, by can-
celling 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".
3. With --migrate, it prints both the closing and opening transactions You can close a different set of accounts by providing a query. Eg if
above. This is a common way to migrate balances to a new file at you want to include equity, you can add assets liabilities equity or
year end; run hledger close --migrate -e NEWYEAR (-e influences the type:ALE arguments. (The balancing account is always excluded.) Rev-
transaction date) and add the closing transaction at the end of the enues and expenses usually are not migrated to a new file directly; see
old file, and the opening transaction at the start of the new file. --retain below.
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. Or you can
just migrate assets and liabilities: hledger close type:AL. Most
people don't need to migrate equity. And revenues and expenses usu-
ally should not be migrated.
4. With --assert it prints a "closing balances" transaction that just The generated transactions will have a start: tag, with its value set
asserts the current balances, without changing them. This can be to --migrate's NEW argument if any, for easier matching or exclusion.
useful as documention and to guard against errors and changes. When NEW is not specified, it will be inferred if possible by incre-
menting a number (eg a year number) within the default journal's main
file name. The other modes behave similarly.
5. With --assign it prints an "opening balances" transaction that re- close --close
stores the account balances using balance assignments. Balance as- This prints just the closing balances transaction of --migrate. It is
signments work regardless of any previous balance, so a preceding the default behaviour if you specify no mode flag. Using the customi-
closing balances transaction is not needed. This is an alternative sation options below, you can move balances from any set of accounts to
to --close and --open: at year end, hledger close --assert -e a different account.
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 trans- close --open
fers revenue and expense balances to equity:retained earnings. This This prints just the opening balances transaction of --migrate. It is
is a traditional end-of-period bookkeeping operation also called similar to Ledger's equity command.
"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.
close --assert
This prints a "closing balances" transaction (with balances: tag), that
just declares 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 work regard-
less of any previous balance, so a preceding closing balances transac-
tion is not needed.
However, omitting the closing balances transaction would unbalance eq-
uity. This is relatively harmless for personal reports, but it dis-
turbs 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.
close --retain
This is like --close with different defaults: it prints a "retain earn-
ings" transaction (with retain: tag), that transfers revenue and ex-
pense 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 pur-
poses.)
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: In all modes, the following things can be overridden:
o the transaction descriptions can be changed with --close-desc=DESC o the accounts to be closed/opened, with account query arguments
and --open-desc=DESC
o the account to transfer to and from can be changed with o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
--close-acct=ACCT and --open-acct=ACCT
o the accounts to be closed/opened can be changed with ACCTQUERY (ac- o the transaction descriptions, with --close-desc=DESC and
count query arguments). --open-desc=DESC
o the closing/opening dates can be changed with -e DATE (a report end o the transaction's tag value, with a --MODE=NEW option argument
date)
By default just one destination/source posting will be used, with its o the closing/opening dates, with -e OPENDATE
amount left implicit. With --x/--explicit, the 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 By default, the closing date is yesterday, or the journal's end date,
for each cost. This is currently the best way to view investment lots. whichever is later; and the opening date is always one day after the
If you have many currency conversion or investment transactions, it can closing date. You can change these by specifying a report end date;
generate very large journal entries. 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".
With --x/--explicit, the balancing amount will be shown explicitly, and
if it involves multiple commodities, a separate posting will be gener-
ated for each of them (similar to print -x).
With --interleaved, each individual transfer is shown with source and With --interleaved, each individual transfer is shown with source and
destination postings next to each other. This could be useful for destination postings next to each other (perhaps useful for trou-
troubleshooting. bleshooting).
The default closing date is yesterday, or the journal's end date, With --show-costs, balances' costs are also shown, with different costs
whichever is later. You can change this by specifying a report end kept separate. This may generate very large journal entries, if you
date with -e. The last day of the report period will be the closing have many currency conversions or investment transactions. close
date, eg -e 2024 means "close on 2023-12-31". The opening date is al- --show-costs is currently the best way to view investment lots with
ways the day after the closing date. hledger. (To move or dispose of lots, see the more capable
hledger-move script.)
close and balance assertions close and balance assertions
Balance assertions will be generated, verifying that the accounts have close adds balance assertions verifying that the accounts have been re-
been reset to zero (and then restored to their previous balances, if set to zero in a closing transaction or restored to their previous bal-
there is an opening transaction). ances in an opening transaction. These provide useful error checking,
but you can ignore them temporarily with -I, or remove them if you pre-
fer.
These provide useful error checking, but you can ignore them temporar- When running close you should probably avoid using -C, -R, status:
ily with -I, or remove them if you prefer. (filtering by status or realness) or --auto (generating postings),
since the generated balance assertions would then require these.
You probably should avoid filtering transactions by status or realness Transactions with multiple dates (eg posting dates) spanning the file
(-C, -R, status:), or generating postings (--auto), with this command, boundary also can disrupt the balance assertions:
since the balance assertions would depend on these.
Note custom posting dates spanning the file boundary will disrupt the
balance assertions:
2023-12-30 a purchase made in december, cleared in january 2023-12-30 a purchase made in december, cleared in january
expenses:food 5 expenses:food 5
assets:bank:checking -5 ; date: 2023-01-02 assets:bank:checking -5 ; date: 2023-01-02
To solve that you can transfer the money to and from a temporary ac- To solve this you can transfer the money to and from a temporary ac-
count, in effect splitting the multi-day transaction into two sin- count, splitting the multi-day transaction into two single-day transac-
gle-day transactions: tions:
; in 2022.journal: ; in 2022.journal:
2022-12-30 a purchase made in december, cleared in january 2022-12-30 a purchase made in december, cleared in january
@ -7301,76 +7376,43 @@ PART 4: COMMANDS
equity:pending 5 = 0 equity:pending 5 = 0
assets:bank:checking -5 assets:bank:checking -5
Example: retain earnings close examples
Retain earnings
Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap- Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap-
pending the generated transaction to the journal: pending the generated transaction to the journal:
$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
Note 2022's income statement will now show only zeroes, because rev- After this, to see 2022's revenues and expenses you must exclude the
enues and expenses have been moved entirely to equity. To see them retain earnings transaction:
again, you could exclude the retain transaction:
$ hledger -f 2022.journal is not:desc:'retain earnings' $ 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 Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:
2023-01-01:
$ hledger close --migrate -f 2022.journal -p 2022 $ hledger close --migrate -f 2022.journal -p 2022
# copy/paste the closing transaction to the end of 2022.journal # copy/paste the closing transaction to the end of 2022.journal
# copy/paste the opening transaction to the start of 2023.journal # copy/paste the opening transaction to the start of 2023.journal
Now 2022's balance sheet will show only zeroes, indicating a balanced After this, to see 2022's end-of-year balances you must exclude the
accounting equation. (Unless you are using @/@@ notation - in that closing balances transaction:
case, try adding --infer-equity.) To see the end-of-year balances
again, you could exclude the closing transaction:
$ hledger -f 2022.journal bs not:desc:'closing balances' $ hledger -f 2022.journal bs not:desc:'closing balances'
Example: excluding closing/opening transactions For more flexibility, it helps to tag closing and opening transactions
When combining many files for multi-year reports, the closing/opening with eg start:NEWYEAR, then you can ensure correct balances by exclud-
transactions cause some noise in transaction-oriented reports like ing all opening/closing transactions except the first, like so:
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 transac-
tion, which could be awkward. Here is one alternative, using tags:
Add clopen: tags to all opening/closing balances transactions except $ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start'
the first, like this: $ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:start=2021 or not tag:start'
$ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:start=2022 or not tag:start'
$ hledger bs -Y -f 2021.j expr:'tag:start=2021 or not tag:start'
$ hledger bs -Y -f 2022.j expr:'tag:start=2022 or not tag:start'
$ hledger bs -Y -f 2023.j # unclosed file, no query needed
; 2021.journal More detailed close examples
2021-06-01 first opening balances See examples/multi-year.
...
2021-12-31 closing balances ; clopen:2022
...
; 2022.journal
2022-01-01 opening balances ; clopen:2022
...
2022-12-31 closing balances ; clopen:2023
...
; 2023.journal
2023-01-01 opening balances ; clopen:2023
...
Now, assuming a combined journal like:
; all.journal
include 2021.journal
include 2022.journal
include 2023.journal
The clopen: tag can exclude all but the first opening transaction. To
show a clean multi-year checking register:
$ hledger -f all.journal areg checking not:tag:clopen
And the year values allow more precision. To show 2022's year-end bal-
ance sheet:
$ hledger -f all.journal bs -e2023 not:tag:clopen=2023
codes codes
List the codes seen in transactions, in the order parsed. List the codes seen in transactions, in the order parsed.
@ -7662,7 +7704,8 @@ PART 4: COMMANDS
sign flipped. sign flipped.
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, tsv, html, and json. tions The output formats supported are txt, csv, tsv (Added in 1.32),
html, and json.
notes notes
List the unique notes that appear in transactions. List the unique notes that appear in transactions.
@ -7767,8 +7810,9 @@ PART 4: COMMANDS
made consistent. By default, decimal digits are shown as they are made consistent. By default, decimal digits are shown as they are
written in the journal. written in the journal.
With the --round option, print will try increasingly hard to display With the --round (Added in 1.32) option, print will try increasingly
decimal digits according to the commodity display styles: hard to display decimal digits according to the commodity display
styles:
o --round=none show amounts with original precisions (default) o --round=none show amounts with original precisions (default)
@ -7819,8 +7863,8 @@ PART 4: COMMANDS
print output format print output format
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, beancount, csv, tsv, json tions The output formats supported are txt, beancount (Added in 1.32),
and sql. csv, tsv (Added in 1.32), json and sql.
The beancount format tries to produce Beancount-compatible output, as The beancount format tries to produce Beancount-compatible output, as
follows: follows:
@ -8011,7 +8055,8 @@ PART 4: COMMANDS
$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
This command also supports the output destination and output format op- This command also supports the output destination and output format op-
tions The output formats supported are txt, csv, tsv, and json. tions The output formats supported are txt, csv, tsv (Added in 1.32),
and json.
rewrite rewrite
Print all transactions, rewriting the postings of matched transactions. Print all transactions, rewriting the postings of matched transactions.