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

;doc: update embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2025-03-06 16:05:55 -10:00
parent 0cd86d959e
commit e25cd526b7
13 changed files with 2075 additions and 1857 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
hledger-lib/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{December 2024}})m4_dnl m4_define({{_monthyear_}}, {{March 2025}})m4_dnl

2
hledger-ui/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{December 2024}})m4_dnl m4_define({{_monthyear_}}, {{March 2025}})m4_dnl

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

@ -1,5 +1,5 @@
.TH "HLEDGER\-UI" "1" "December 2024" "hledger-ui-1.41.99 " "hledger User Manuals" .TH "HLEDGER\-UI" "1" "March 2025" "hledger-ui-1.41.99 " "hledger User Manuals"
@ -458,9 +458,6 @@ know.)
If you are viewing files mounted from another machine, the system clocks If you are viewing files mounted from another machine, the system clocks
on both machines should be roughly in agreement. on both machines should be roughly in agreement.
.SH ENVIRONMENT .SH ENVIRONMENT
\f[B]COLUMNS\f[R] The screen width to use.
Default: the full terminal width.
.PP
\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified \f[B]LEDGER_FILE\f[R] The main journal file to use when not specified
with \f[CR]\-f/\-\-file\f[R]. with \f[CR]\-f/\-\-file\f[R].
Default: \f[CR]$HOME/.hledger.journal\f[R]. Default: \f[CR]$HOME/.hledger.journal\f[R].

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

@ -1,4 +1,4 @@
This is hledger-ui.info, produced by makeinfo version 7.1.1 from stdin. This is hledger-ui.info, produced by makeinfo version 7.2 from stdin.
INFO-DIR-SECTION User Applications INFO-DIR-SECTION User Applications
START-INFO-DIR-ENTRY START-INFO-DIR-ENTRY
@ -514,9 +514,7 @@ File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: WATCH MODE, Up:
6 ENVIRONMENT 6 ENVIRONMENT
************* *************
*COLUMNS* The screen width to use. Default: the full terminal width. *LEDGER_FILE* The main journal file to use when not specified with
*LEDGER_FILE* The main journal file to use when not specified with
'-f/--file'. Default: '$HOME/.hledger.journal'. '-f/--file'. Default: '$HOME/.hledger.journal'.
 
@ -543,22 +541,22 @@ above).
 
Tag Table: Tag Table:
Node: Top223 Node: Top221
Node: OPTIONS1874 Node: OPTIONS1872
Node: MOUSE8548 Node: MOUSE8546
Node: KEYS8880 Node: KEYS8878
Node: SCREENS13884 Node: SCREENS13882
Node: Menu screen14624 Node: Menu screen14622
Node: Cash accounts screen14940 Node: Cash accounts screen14938
Node: Balance sheet accounts screen15301 Node: Balance sheet accounts screen15299
Node: Income statement accounts screen15637 Node: Income statement accounts screen15635
Node: All accounts screen16022 Node: All accounts screen16020
Node: Register screen16385 Node: Register screen16383
Node: Transaction screen18828 Node: Transaction screen18826
Node: Error screen20403 Node: Error screen20401
Node: WATCH MODE20769 Node: WATCH MODE20767
Node: ENVIRONMENT22345 Node: ENVIRONMENT22343
Node: BUGS22652 Node: BUGS22576
 
End Tag Table End Tag Table

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

@ -412,8 +412,6 @@ WATCH MODE
clocks on both machines should be roughly in agreement. clocks on both machines should be roughly in agreement.
ENVIRONMENT ENVIRONMENT
COLUMNS The screen width to use. Default: the full terminal width.
LEDGER_FILE The main journal file to use when not specified with LEDGER_FILE The main journal file to use when not specified with
-f/--file. Default: $HOME/.hledger.journal. -f/--file. Default: $HOME/.hledger.journal.
@ -452,4 +450,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-ui-1.41.99 December 2024 HLEDGER-UI(1) hledger-ui-1.41.99 March 2025 HLEDGER-UI(1)

2
hledger-web/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{December 2024}})m4_dnl m4_define({{_monthyear_}}, {{March 2025}})m4_dnl

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

@ -1,5 +1,5 @@
.TH "HLEDGER\-WEB" "1" "December 2024" "hledger-web-1.41.99 " "hledger User Manuals" .TH "HLEDGER\-WEB" "1" "March 2025" "hledger-web-1.41.99 " "hledger User Manuals"

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

@ -1,4 +1,4 @@
This is hledger-web.info, produced by makeinfo version 7.1.1 from stdin. This is hledger-web.info, produced by makeinfo version 7.2 from stdin.
INFO-DIR-SECTION User Applications INFO-DIR-SECTION User Applications
START-INFO-DIR-ENTRY START-INFO-DIR-ENTRY
@ -528,16 +528,16 @@ https://bugs.hledger.org), or on the hledger chat or mail list
 
Tag Table: Tag Table:
Node: Top225 Node: Top223
Node: OPTIONS2571 Node: OPTIONS2569
Node: PERMISSIONS11260 Node: PERMISSIONS11258
Node: EDITING UPLOADING DOWNLOADING12611 Node: EDITING UPLOADING DOWNLOADING12609
Node: RELOADING13626 Node: RELOADING13624
Node: JSON API14193 Node: JSON API14191
Node: DEBUG OUTPUT19842 Node: DEBUG OUTPUT19840
Node: Debug output19994 Node: Debug output19992
Node: ENVIRONMENT20512 Node: ENVIRONMENT20510
Node: BUGS20748 Node: BUGS20746
 
End Tag Table End Tag Table

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

@ -480,4 +480,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-web-1.41.99 December 2024 HLEDGER-WEB(1) hledger-web-1.41.99 March 2025 HLEDGER-WEB(1)

2
hledger/.date.m4
View File

@ -1,2 +1,2 @@
m4_dnl Date to show in man pages. Updated by "Shake manuals" m4_dnl Date to show in man pages. Updated by "Shake manuals"
m4_define({{_monthyear_}}, {{December 2024}})m4_dnl m4_define({{_monthyear_}}, {{March 2025}})m4_dnl

512
hledger/hledger.1
View File

@ -1,6 +1,6 @@
.\"t .\"t
.TH "HLEDGER" "1" "December 2024" "hledger-1.41.99 " "hledger User Manuals" .TH "HLEDGER" "1" "March 2025" "hledger-1.41.99 " "hledger User Manuals"
@ -133,20 +133,26 @@ So we usually configure a different journal file, by setting the
For more about how to do that on your system, see Common tasks > Setting For more about how to do that on your system, see Common tasks > Setting
LEDGER_FILE. LEDGER_FILE.
.SS Text encoding .SS Text encoding
Data files containing non\-ascii characters must use UTF\-8 encoding. hledger input files containing non\-ascii characters must use UTF\-8
An optional byte order mark (BOM) is allowed, at the beginning of the encoding, with the exception of CSV (SSV, TSV..)
file (only). files, which can be read from other encodings (see \f[CR]encoding\f[R]
CSV rule).
.PP .PP
Also, your system should be configured with a locale that can decode In UTF\-8 input files, an optional byte order mark (BOM) at the
UTF\-8 text. beginning of the file is allowed.
On some unix systems, you may need set the \f[CR]LANG\f[R] environment .PP
variable, eg. Your system may need to be configured with a locale that understands the
input file\[aq]s encoding.
Eg on some unix systems, you may need set the \f[CR]LANG\f[R]
environment variable.
You can read more about this in Unicode characters, below. You can read more about this in Unicode characters, below.
.PP .PP
On unix systems you can check a file\[aq]s encoding with the On some unix systems you can use the \f[CR]file\f[R] command to show a
\f[CR]file\f[R] command. file\[aq]s text encoding.
If you need to import from a UTF\-16\-encoded CSV file, say, you can On mac, you\[aq]ll need the version from homebrew:
convert it to UTF\-8 with the \f[CR]iconv\f[R] command. \f[CR]brew install file\-formula\f[R].
.PP
hledger\[aq]s text output is always UTF\-8 encoded.
.SS Data formats .SS Data formats
Usually the data file is in hledger\[aq]s journal format, but it can be Usually the data file is in hledger\[aq]s journal format, but it can be
in any of the supported file formats, which currently are: in any of the supported file formats, which currently are:
@ -904,12 +910,11 @@ To troubleshoot the effect of config files, run with
The config file feature was added in hledger 1.40 and is considered The config file feature was added in hledger 1.40 and is considered
\f[I]experimental\f[R]. \f[I]experimental\f[R].
.SS Shell completions .SS Shell completions
If you use the bash shell, you can optionally set up context\-sensitive If you use the bash or zsh shells, you can optionally set up
autocompletions when you press TAB in a hledger command line. context\-sensitive autocompletion for hledger command lines.
At a bash shell prompt, try pressing \f[CR]hledger<SPACE><TAB><TAB>\f[R] Try pressing \f[CR]hledger<SPACE><TAB><TAB>\f[R] (should list all
(should list all hledger commands) or hledger commands) or \f[CR]hledger reg acct:<TAB><TAB>\f[R] (should list
\f[CR]hledger reg acct:<TAB><TAB>\f[R] (should list your top\-level your top\-level account names).
account names).
If completions aren\[aq]t working, or for more details, see Install > If completions aren\[aq]t working, or for more details, see Install >
Shell completions. Shell completions.
.SH Output .SH Output
@ -1113,13 +1118,10 @@ If your data contains unicode or wide characters, you\[aq]ll need a
terminal and font that render those correctly. terminal and font that render those correctly.
(This can be challenging on MS Windows.) (This can be challenging on MS Windows.)
.PP .PP
Some reports (\f[CR]register\f[R], \f[CR]aregister\f[R]) will use the Some reports (\f[CR]register\f[R], \f[CR]aregister\f[R]) will normally
width indicated by the \f[CR]COLUMNS\f[R] environment variable. use the full window width.
If your shell and terminal are working well, they will keep COLUMNS If this isn\[aq]t working or you want to override it, you can use the
updated as you resize the window. \f[CR]\-w\f[R]/\f[CR]\-\-width\f[R] option.
So register reports normally will use the full window width.
When this isn\[aq]t working or you want to override it, you can manually
set COLUMNS, or use the \f[CR]\-w\f[R]/\f[CR]\-\-width\f[R] option.
.PP .PP
Balance reports (\f[CR]balance\f[R], \f[CR]balancesheet\f[R], Balance reports (\f[CR]balance\f[R], \f[CR]balancesheet\f[R],
\f[CR]incomestatement\f[R]...) \f[CR]incomestatement\f[R]...)
@ -1152,6 +1154,9 @@ or \f[CR]n\f[R]/\f[CR]no\f[R] value to force it on or off.
.SS Paging .SS Paging
In unix\-like environments, when displaying large output (in any output In unix\-like environments, when displaying large output (in any output
format) in the terminal, hledger tries to use a pager when appropriate. format) in the terminal, hledger tries to use a pager when appropriate.
(You can disable this with the \f[CR]\-\-pager=no\f[R] option, perhaps
in your config file.)
.PP
The pager shows one page of text at a time, and lets you scroll around The pager shows one page of text at a time, and lets you scroll around
to see more. to see more.
While it is active, usually \f[CR]SPACE\f[R] shows the next page, While it is active, usually \f[CR]SPACE\f[R] shows the next page,
@ -1177,7 +1182,7 @@ ANSI colour and a number of other conveniences.
(At the time of writing: \-\-chop\-long\-lines \-\-hilite\-unread (At the time of writing: \-\-chop\-long\-lines \-\-hilite\-unread
\-\-ignore\-case \-\-mouse \-\-no\-init \-\-quit\-at\-eof \-\-ignore\-case \-\-mouse \-\-no\-init \-\-quit\-at\-eof
\-\-quit\-if\-one\-screen \-\-RAW\-CONTROL\-CHARS \-\-shift=8 \-\-quit\-if\-one\-screen \-\-RAW\-CONTROL\-CHARS \-\-shift=8
\-\-squeeze\-blank\-lines \-\-use\-backslash \-\-use\-color ). \-\-squeeze\-blank\-lines \-\-use\-backslash ).
If these don\[aq]t work well, you can set your preferred options in the If these don\[aq]t work well, you can set your preferred options in the
\f[CR]HLEDGER_LESS\f[R] variable, which will be used instead. \f[CR]HLEDGER_LESS\f[R] variable, which will be used instead.
.SS HTML output .SS HTML output
@ -1336,7 +1341,7 @@ shown:
$ hledger print \-c \[aq]$1.000,0\[aq] $ hledger print \-c \[aq]$1.000,0\[aq]
.EE .EE
.PP .PP
This option can repeated to set the display style for multiple This option can be 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 .PP
@ -1366,10 +1371,6 @@ hledger bal \-\-debug=3 2>hledger.log
.SH Environment .SH Environment
These environment variables affect hledger: These environment variables affect hledger:
.PP .PP
\f[B]COLUMNS\f[R] This is normally set by your terminal; some hledger
commands (\f[CR]register\f[R]) will format their output to this width.
If not set, they will try to use the available terminal width.
.PP
\f[B]HLEDGER_LESS\f[R] If \f[CR]less\f[R] is your pager, this variable \f[B]HLEDGER_LESS\f[R] If \f[CR]less\f[R] is your pager, this variable
specifies the \f[CR]less\f[R] options hledger should use. specifies the \f[CR]less\f[R] options hledger should use.
(Otherwise, \f[CR]LESS\f[R] + custom options are used.) (Otherwise, \f[CR]LESS\f[R] + custom options are used.)
@ -3113,7 +3114,7 @@ matching accounts as you expect, try troubleshooting with the accounts
command, eg something like: command, eg something like:
.IP .IP
.EX .EX
$ hledger accounts \-\-alias assets=bassetts type:a $ hledger accounts \-\-types \-1 \-\-alias assets=bassetts
.EE .EE
.SS \f[CR]commodity\f[R] directive .SS \f[CR]commodity\f[R] directive
The \f[CR]commodity\f[R] directive performs several functions: The \f[CR]commodity\f[R] directive performs several functions:
@ -3151,7 +3152,7 @@ and precise.
.SS Commodity directive syntax .SS Commodity directive syntax
A commodity directive is normally the word \f[CR]commodity\f[R] followed A commodity directive is normally the word \f[CR]commodity\f[R] followed
by a sample amount (and optionally a comment). by a sample amount (and optionally a comment).
Only the amount\[aq]s symbol and format is significant. Only the amount\[aq]s symbol and the number\[aq]s format is significant.
Eg: Eg:
.IP .IP
.EX .EX
@ -3880,14 +3881,15 @@ See also https://hledger.org/ledger.html for a detailed hledger/Ledger
syntax comparison. syntax comparison.
.SS Other cost/lot notations .SS Other cost/lot notations
A slight digression for Ledger and Beancount users. A slight digression for Ledger and Beancount users.
Ledger has a number of cost/lot\-related notations: .PP
\f[B]Ledger\f[R] has a number of cost/lot\-related notations:
.IP \[bu] 2 .IP \[bu] 2
\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R] \f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R]
.RS 2 .RS 2
.IP \[bu] 2 .IP \[bu] 2
expresses a conversion rate, as in hledger expresses a conversion rate, as in hledger
.IP \[bu] 2 .IP \[bu] 2
when buying, also creates a lot than can be selected at selling time when buying, also creates a lot that can be selected at selling time
.RE .RE
.IP \[bu] 2 .IP \[bu] 2
\f[CR](\[at]) UNITCOST\f[R] and \f[CR](\[at]\[at]) TOTALCOST\f[R] \f[CR](\[at]) UNITCOST\f[R] and \f[CR](\[at]\[at]) TOTALCOST\f[R]
@ -3897,15 +3899,11 @@ when buying, also creates a lot than can be selected at selling time
like the above, but also means \[dq]this cost was exceptional, don\[aq]t like the above, but also means \[dq]this cost was exceptional, don\[aq]t
use it when inferring market prices\[dq]. use it when inferring market prices\[dq].
.RE .RE
.PP
Currently, hledger treats the above like \f[CR]\[at]\f[R] and
\f[CR]\[at]\[at]\f[R]; the parentheses are ignored.
.IP \[bu] 2 .IP \[bu] 2
\f[CR]{=FIXEDUNITCOST}\f[R] and \f[CR]{{=FIXEDTOTALCOST}}\f[R] (fixed \f[CR]{=UNITCOST}\f[R] and \f[CR]{{=TOTALCOST}}\f[R] (fixed price)
price)
.RS 2 .RS 2
.IP \[bu] 2 .IP \[bu] 2
when buying, means \[dq]this cost is also the fixed price, don\[aq]t let when buying, means \[dq]this cost is also the fixed value, don\[aq]t let
it fluctuate in value reports\[dq] it fluctuate in value reports\[dq]
.RE .RE
.IP \[bu] 2 .IP \[bu] 2
@ -3915,11 +3913,12 @@ it fluctuate in value reports\[dq]
can be used identically to \f[CR]\[at] UNITCOST\f[R] and can be used identically to \f[CR]\[at] UNITCOST\f[R] and
\f[CR]\[at]\[at] TOTALCOST\f[R], also creates a lot \f[CR]\[at]\[at] TOTALCOST\f[R], also creates a lot
.IP \[bu] 2 .IP \[bu] 2
when selling, combined with \f[CR]\[at] ...\f[R], specifies an when selling, combined with \f[CR]\[at] ...\f[R], selects an existing
investment lot by its cost basis; does not check if that lot is present lot by its cost basis.
Does not check if that lot is present.
.RE .RE
.IP \[bu] 2 .IP \[bu] 2
and related: \f[CR][YYYY/MM/DD]\f[R] (lot date) \f[CR][YYYY/MM/DD]\f[R] (lot date)
.RS 2 .RS 2
.IP \[bu] 2 .IP \[bu] 2
when buying, attaches this acquisition date to the lot when buying, attaches this acquisition date to the lot
@ -3935,29 +3934,37 @@ when buying, attaches this note to the lot
when selling, selects a lot by its note when selling, selects a lot by its note
.RE .RE
.PP .PP
Currently, hledger accepts any or all of the above in any order after Currently, hledger
the posting amount, but ignores them. .IP \[bu] 2
accepts any or all of the above in any order after the posting amount
.IP \[bu] 2
supports \f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]
.IP \[bu] 2
treats \f[CR](\[at])\f[R] and \f[CR](\[at]\[at])\f[R] as synonyms for
\f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]
.IP \[bu] 2
and ignores the rest.
(This can break transaction balancing.) (This can break transaction balancing.)
.PP .PP
For Beancount users, the notation and behaviour is different: \f[B]Beancount\f[R] has simpler notation and different behaviour:
.IP \[bu] 2 .IP \[bu] 2
\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R] \f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R]
.RS 2 .RS 2
.IP \[bu] 2 .IP \[bu] 2
expresses a cost without creating a lot, as in hledger expresses a cost without creating a lot, as in hledger
.IP \[bu] 2 .IP \[bu] 2
when buying (augmenting) or selling (reducing) a lot, combined with when buying (acquiring) or selling (disposing of) a lot, and combined
\f[CR]{...}\f[R]: documents the cost/selling price (not used for with \f[CR]{...}\f[R]: is not used except to document the cost/selling
transaction balancing) price
.RE .RE
.IP \[bu] 2 .IP \[bu] 2
\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R] \f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R]
.RS 2 .RS 2
.IP \[bu] 2 .IP \[bu] 2
when buying (augmenting), expresses the cost for transaction balancing, when buying, expresses the cost for transaction balancing, and also
and also creates a lot with this cost basis attached creates a lot with this cost basis attached
.IP \[bu] 2 .IP \[bu] 2
when selling (reducing), when selling,
.RS 2 .RS 2
.IP \[bu] 2 .IP \[bu] 2
selects a lot by its cost basis selects a lot by its cost basis
@ -3968,15 +3975,24 @@ unambiguously (depending on booking method configured)
expresses the selling price for transaction balancing expresses the selling price for transaction balancing
.RE .RE
.RE .RE
.PP
Currently, hledger accepts the
\f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation but ignores it.
.IP \[bu] 2 .IP \[bu] 2
variations: \f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R], \f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R], \f[CR]{\[dq]LABEL\[dq]}\f[R],
\f[CR]{\[dq]LABEL\[dq]}\f[R], \f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R], \f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R],
\f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R] etc. \f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R]
.RS 2
.IP \[bu] 2
when selling, other combinations of date/cost/label, like the above, are
accepted for selecting the lot.
.RE
.PP .PP
Currently, hledger rejects these. Currently, hledger
.IP \[bu] 2
supports \f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]
.IP \[bu] 2
accepts the \f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation, but
ignores it
.IP \[bu] 2
and rejects the rest.
.PP .PP
.SH CSV .SH CSV
hledger can read CSV files (Character Separated Value \- usually comma, hledger can read CSV files (Character Separated Value \- usually comma,
@ -4046,6 +4062,11 @@ T}@T{
optionally declare which file to read data from optionally declare which file to read data from
T} T}
T{ T{
\f[B]\f[CB]encoding\f[B]\f[R]
T}@T{
optionally declare which text encoding the data has
T}
T{
\f[B]\f[CB]separator\f[B]\f[R] \f[B]\f[CB]separator\f[B]\f[R]
T}@T{ T}@T{
declare the field separator, instead of relying on file extension declare the field separator, instead of relying on file extension
@ -4152,6 +4173,26 @@ source Checking1*.csv
.EE .EE
.PP .PP
See also \[dq]Working with CSV > Reading files specified by rule\[dq]. See also \[dq]Working with CSV > Reading files specified by rule\[dq].
.SS \f[CR]encoding\f[R]
.IP
.EX
encoding ENCODING
.EE
.PP
hledger normally expects non\-ascii text to be UTF8\-encoded.
If you need to read CSV files which have some other encoding, you can do
it by adding \f[CR]encoding ENCODING\f[R] to your CSV rules.
Eg: \f[CR]encoding ISO88591\f[R].
.PP
The following encodings are supported (these names are
case\-insensitive, and can be written with inner spaces or hyphens if
you prefer): ASCII, UTF8, UTF16, UTF32, ISO88591, ISO88592, ISO88593,
ISO88594, ISO88595, ISO88596, ISO88597, ISO88598, ISO88599, ISO885910,
ISO885911, ISO885913, ISO885914, ISO885915, ISO885916, CP1250, CP1251,
CP1252, CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, KOI8R, KOI8U,
GB18030, MacOSRoman, JISX0201, JISX0208, ISO2022JP, ShiftJIS, CP437,
CP737, CP775, CP850, CP852, CP855, CP857, CP860, CP861, CP862, CP863,
CP864, CP865, CP866, CP869, CP874, CP932.
.SS \f[CR]separator\f[R] .SS \f[CR]separator\f[R]
You can use the \f[CR]separator\f[R] rule to read other kinds of You can use the \f[CR]separator\f[R] rule to read other kinds of
character\-separated data. character\-separated data.
@ -4697,12 +4738,20 @@ When an if block has multiple matchers, each on its own line,
.IP \[bu] 2 .IP \[bu] 2
By default they are OR\[aq]d (any of them can match). By default they are OR\[aq]d (any of them can match).
.IP \[bu] 2 .IP \[bu] 2
Matcher lines beginning with \f[CR]&\f[R] (and optional space) are Matcher lines beginning with \f[CR]&\f[R] (or \f[CR]&&\f[R], \f[I]since
AND\[aq]ed with the matcher above (all in the AND\[aq]ed group must 1.42\f[R]) are AND\[aq]ed with the matcher above (all in the AND\[aq]ed
match). group must match).
.IP \[bu] 2
Matcher lines beginning with \f[CR]& !\f[R] (\f[I]since 1.41\f[R], or
\f[CR]&& !\f[R], \f[I]since 1.42\f[R]) are first negated and then
AND\[aq]ed with the matcher above.
.PP .PP
\f[I](Since 1.41:)\f[R] You can use a negated \f[CR]!\f[R] matcher on a You can also combine multiple matchers one the same line separated by
\f[CR]&\f[R] line, meaning AND NOT. \f[CR]&&\f[R] (AND) or \f[CR]&& !\f[R] (AND NOT).
Eg \f[CR]%description amazon && %date 2025\-01\-01\f[R] will match only
when the description field contains \[dq]amazon\[dq] and the date field
contains \[dq]2025\-01\-01\[dq].
\f[I]Added in 1.42.\f[R]
.SS Match groups .SS Match groups
\f[I]Added in 1.32\f[R] \f[I]Added in 1.32\f[R]
.PP .PP
@ -4739,9 +4788,9 @@ like this:
.EX .EX
if,HLEDGERFIELD1,HLEDGERFIELD2,... if,HLEDGERFIELD1,HLEDGERFIELD2,...
MATCHERA,VALUE1,VALUE2,... MATCHERA,VALUE1,VALUE2,...
MATCHERB,VALUE1,VALUE2,... MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*)
; Comment line that explains MATCHERC ; Comment line that explains MATCHERD
MATCHERC,VALUE1,VALUE2,... MATCHERD,VALUE1,VALUE2,...
<empty line> <empty line>
.EE .EE
.PP .PP
@ -4761,10 +4810,11 @@ You can use the comment lines in the table body.
The table must be terminated by an empty line (or end of file). The table must be terminated by an empty line (or end of file).
.PP .PP
An if table like the above is interpreted as follows: try all of the An if table like the above is interpreted as follows: try all of the
matchers; whenever a matcher succeeds, assign all of the values on that lines with matchers; whenever a line with matchers succeeds, assign all
line to the corresponding hledger fields; If multiple lines match, later of the values on that line to the corresponding hledger fields; If
lines will override fields assigned by the earlier ones \- just like the multiple lines match, later lines will override fields assigned by the
sequence of \f[CR]if\f[R] blocks would behave. earlier ones \- just like the sequence of \f[CR]if\f[R] blocks would
behave.
.PP .PP
If table presented above is equivalent to this sequence of if blocks: If table presented above is equivalent to this sequence of if blocks:
.IP .IP
@ -4774,13 +4824,13 @@ if MATCHERA
HLEDGERFIELD2 VALUE2 HLEDGERFIELD2 VALUE2
... ...
if MATCHERB if MATCHERB && MATCHERC
HLEDGERFIELD1 VALUE1 HLEDGERFIELD1 VALUE1
HLEDGERFIELD2 VALUE2 HLEDGERFIELD2 VALUE2
... ...
; Comment line which explains MATCHERC ; Comment line which explains MATCHERD
if MATCHERC if MATCHERD
HLEDGERFIELD1 VALUE1 HLEDGERFIELD1 VALUE1
HLEDGERFIELD2 VALUE2 HLEDGERFIELD2 VALUE2
... ...
@ -6767,21 +6817,38 @@ reports, \f[CR]cur:\f[R] and \f[CR]amt:\f[R] match the old commodity
symbol and the old amount quantity, not the new ones. symbol and the old amount quantity, not the new ones.
(Except in hledger 1.22, #1625.) (Except in hledger 1.22, #1625.)
.SH Pivoting .SH Pivoting
Normally, hledger groups and sums amounts within each account. Normally, hledger groups amounts and displays their totals by account
The \f[CR]\-\-pivot FIELD\f[R] option substitutes some other transaction (name).
field for account names, causing amounts to be grouped and summed by With \f[CR]\-\-pivot PIVOTEXPR\f[R], some other field\[aq]s (or multiple
that field\[aq]s value instead. fields\[aq]) value is used as a synthetic account name, causing
FIELD can be any of the transaction fields \f[CR]acct\f[R], different grouping and display.
\f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R], \f[CR]payee\f[R], PIVOTEXPR can be
\f[CR]note\f[R], or a tag name. .IP \[bu] 2
When pivoting on a tag and a posting has multiple values of that tag, any of these standard transaction or posting fields (their value is
only the first value is displayed. substituted): \f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R],
Values containing \f[CR]colon:separated:parts\f[R] will be displayed \f[CR]payee\f[R], \f[CR]note\f[R], \f[CR]acct\f[R],
hierarchically, like account names. \f[CR]comm\f[R]/\f[CR]cur\f[R], \f[CR]amt\f[R], \f[CR]cost\f[R]
Multiple, colon\-delimited fields can be pivoted simultaneously, .IP \[bu] 2
generating a hierarchical account name. or a tag name
.IP \[bu] 2
or any combination of these, colon\-separated.
.PP .PP
Some examples: Some special cases:
.IP \[bu] 2
Colons appearing in PIVOTEXPR or in a pivoted tag value will generate
account hierarchy.
.IP \[bu] 2
When pivoting a posting has multiple values for a tag, the pivoted value
of that tag will be the first value.
.IP \[bu] 2
When a posting has multiple commodities, the pivoted value of
\[dq]comm\[dq]/\[dq]cur\[dq] will be \[dq]\[dq].
Also when an unrecognised tag name or field is provided, its pivoted
value will be \[dq]\[dq].
(If this causes confusing output, consider excluding those postings from
the report.)
.PP
Examples:
.IP .IP
.EX .EX
2016/02/16 Yearly Dues Payment 2016/02/16 Yearly Dues Payment
@ -6828,7 +6895,7 @@ $ hledger balance \-\-pivot member acct:.
\-2 EUR \-2 EUR
.EE .EE
.PP .PP
Hierarchical reports can be generated with multiple pivots: Hierarchical reports can be generated with multiple pivot values:
.IP .IP
.EX .EX
$ hledger balance Income:Dues \-\-pivot kind:member $ hledger balance Income:Dues \-\-pivot kind:member
@ -7217,9 +7284,10 @@ In some transactions \- for example a currency conversion, or a purchase
or sale of stock \- one commodity is exchanged for another. or sale of stock \- one commodity is exchanged for another.
In these transactions there is a conversion rate, also called the cost In these transactions there is a conversion rate, also called the cost
(when buying) or selling price (when selling). (when buying) or selling price (when selling).
In hledger docs we just say \[dq]cost\[dq], for convenience; feel free (In hledger docs we just say \[dq]cost\[dq] generically for
to mentally translate to \[dq]conversion rate\[dq] or \[dq]selling convenience.)
price\[dq] if helpful. With the \f[CR]\-B/\-\-cost\f[R] flag, hledger can show amounts \[dq]at
cost\[dq], converted to the cost\[aq]s commodity.
.SS Recording costs .SS Recording costs
We\[aq]ll explore several ways of recording transactions involving We\[aq]ll explore several ways of recording transactions involving
costs. costs.
@ -7463,14 +7531,16 @@ alias h=\[dq]hledger \-\-infer\-equity \-\-infer\-costs\[dq]
and let us know what problems you find. and let us know what problems you find.
.PP .PP
.SH Value reporting .SH Value reporting
Instead of reporting amounts in their original commodity, hledger can hledger can also show amounts \[dq]at market value\[dq], converted to
convert them to cost/sale amount (using the conversion rate recorded in some other commodity using the market price or conversion rate on a
the transaction), and/or to market value (using some market price on a certain date.
certain date). .PP
This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option, This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option.
which will be described below. We also provide simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R]
We also provide the simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R] aliases for this, which are often sufficient.
options, and often one of these is all you need: The market prices are declared with a special \f[CR]P\f[R] directive,
and/or they can be inferred from the costs recorded in transactions, by
using the \f[CR]\-\-infer\-market\-prices\f[R] flag.
.SS \-V: Value .SS \-V: Value
The \f[CR]\-V/\-\-market\f[R] flag converts amounts to market value in The \f[CR]\-V/\-\-market\f[R] flag converts amounts to market value in
their default \f[I]valuation commodity\f[R], using the market prices in their default \f[I]valuation commodity\f[R], using the market prices in
@ -8360,6 +8430,8 @@ $ hledger demo # list available demos
$ hledger demo 1 # play the first demo at default speed (2x) $ hledger demo 1 # play the first demo at default speed (2x)
$ hledger demo install \-s4 # play the \[dq]install\[dq] demo at 4x speed $ hledger demo install \-s4 # play the \[dq]install\[dq] demo at 4x speed
.EE .EE
.PP
This command is experimental: there aren\[aq]t many useful demos yet.
.SH User interface commands .SH User interface commands
.SS ui .SS ui
Runs hledger\-ui (if installed). Runs hledger\-ui (if installed).
@ -9019,13 +9091,14 @@ Flags:
\-\-round=TYPE how much rounding or padding should be done when \-\-round=TYPE how much rounding or padding should be done when
displaying amounts ? displaying amounts ?
none \- show original decimal digits, none \- show original decimal digits,
as in journal as in journal (default)
soft \- just add or remove decimal zeros soft \- just add or remove decimal zeros
to match precision (default) to match precision
hard \- round posting amounts to precision hard \- round posting amounts to precision
(can unbalance transactions) (can unbalance transactions)
all \- also round cost amounts to precision all \- also round cost amounts to precision
(can unbalance transactions) (can unbalance transactions)
\-\-invert display all amounts with reversed sign
\-\-new show only newer\-dated transactions added in each \-\-new show only newer\-dated transactions added in each
file since last run file since last run
\-m \-\-match=DESC fuzzy search for one recent transaction with \-m \-\-match=DESC fuzzy search for one recent transaction with
@ -9139,6 +9212,11 @@ Account aliases can generate bad account names.
With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown
converted to cost. converted to cost.
.PP .PP
With \f[CR]\-\-invert\f[R], posting amounts are shown with their sign
flipped.
It could be useful if you have accidentally recorded some transactions
with the wrong signs.
.PP
With \f[CR]\-\-new\f[R], print shows only transactions it has not seen With \f[CR]\-\-new\f[R], print shows only transactions it has not seen
on a previous run. on a previous run.
This uses the same deduplication system as the \f[CR]import\f[R] This uses the same deduplication system as the \f[CR]import\f[R]
@ -9243,8 +9321,8 @@ Flags:
postings before report start date) (default) postings before report start date) (default)
\-\-invert display all amounts with reversed sign \-\-invert display all amounts with reversed sign
\-\-heading=YN show heading row above table: yes (default) or no \-\-heading=YN show heading row above table: yes (default) or no
\-w \-\-width=N set output width (default: terminal width or \-w \-\-width=N set output width (default: terminal width). \-wN,M
$COLUMNS). \-wN,M sets description width as well. sets description width as well.
\-\-align\-all guarantee alignment across all lines (slower) \-\-align\-all guarantee alignment across all lines (slower)
\-O \-\-output\-format=FMT select the output format. Supported formats: \-O \-\-output\-format=FMT select the output format. Supported formats:
txt, html, csv, tsv, json. txt, html, csv, tsv, json.
@ -9364,8 +9442,8 @@ Flags:
\-\-sort=FIELDS sort by: date, desc, account, amount, absamount, \-\-sort=FIELDS sort by: date, desc, account, amount, absamount,
or a comma\-separated combination of these. For a or a comma\-separated combination of these. For a
descending sort, prefix with \-. (Default: date) descending sort, prefix with \-. (Default: date)
\-w \-\-width=N set output width (default: terminal width or \-w \-\-width=N set output width (default: terminal width). \-wN,M
$COLUMNS). \-wN,M sets description width as well. sets description width as well.
\-\-align\-all guarantee alignment across all lines (slower) \-\-align\-all guarantee alignment across all lines (slower)
\-\-base\-url=URLPREFIX in html output, generate links to hledger\-web, \-\-base\-url=URLPREFIX in html output, generate links to hledger\-web,
with this prefix. (Usually the base url shown by with this prefix. (Usually the base url shown by
@ -9502,10 +9580,10 @@ DESC should contain at least two characters.
If there is no similar\-enough match, no posting will be shown and the If there is no similar\-enough match, no posting will be shown and the
program exit code will be non\-zero. program exit code will be non\-zero.
.SS Custom register output .SS Custom register output
register uses the full terminal width by default, except on windows. register normally uses the full terminal width (or 80 columns if it
You can override this by setting the \f[CR]COLUMNS\f[R] environment can\[aq]t detect that).
variable (not a bash shell variable) or by using the You can override this with the \f[CR]\-\-width\f[R]/\f[CR]\-w\f[R]
\f[CR]\-\-width\f[R]/\f[CR]\-w\f[R] option. option.
.PP .PP
The description and account columns normally share the space equally The description and account columns normally share the space equally
(about half of (width \- 40) each). (about half of (width \- 40) each).
@ -9524,10 +9602,7 @@ and some examples:
.EX .EX
$ hledger reg # use terminal width (or 80 on windows) $ hledger reg # use terminal width (or 80 on windows)
$ hledger reg \-w 100 # use width 100 $ hledger reg \-w 100 # use width 100
$ COLUMNS=100 hledger reg # set with one\-time environment variable
$ export COLUMNS=100; hledger reg # set till session end (or window resize)
$ hledger reg \-w 100,40 # set overall width 100, description width 40 $ hledger reg \-w 100,40 # set overall width 100, description width 40
$ hledger reg \-w $COLUMNS,40 # use terminal width, & description width 40
.EE .EE
.PP .PP
This command also supports the output destination and output format This command also supports the output destination and output format
@ -10003,10 +10078,10 @@ Flags:
\-\-transpose switch rows and columns (use vertical time axis) \-\-transpose switch rows and columns (use vertical time axis)
\-\-layout=ARG how to lay out multi\-commodity amounts and the \-\-layout=ARG how to lay out multi\-commodity amounts and the
overall table: overall table:
\[aq]wide[,WIDTH]\[aq]: commodities on one line \[aq]wide[,W]\[aq]: commodities on same line, up to W wide
\[aq]tall\[aq] : commodities on separate lines \[aq]tall\[aq] : commodities on separate lines
\[aq]bare\[aq] : commodity symbols in one column \[aq]bare\[aq] : commodity symbols in a separate column
\[aq]tidy\[aq] : every attribute in its own column \[aq]tidy\[aq] : each data field in its own column
\-\-base\-url=URLPREFIX in html output, generate links to hledger\-web, \-\-base\-url=URLPREFIX in html output, generate links to hledger\-web,
with this prefix. (Usually the base url shown by with this prefix. (Usually the base url shown by
hledger\-web; can also be relative.) hledger\-web; can also be relative.)
@ -11354,26 +11429,24 @@ $ hledger activity \-\-quarterly
.SS close .SS close
(equity) (equity)
.PP .PP
\f[CR]close\f[R] generates several kinds of \[dq]closing\[dq] and/or \f[CR]close\f[R] prints several kinds of \[dq]closing\[dq] and/or
\[dq]opening\[dq] transactions, useful in certain situations, including \[dq]opening\[dq] transactions, useful in various situations: migrating
migrating balances to a new journal file, retaining earnings into balances to a new journal file, retaining earnings into equity,
equity, consolidating balances, or viewing lots. consolidating balances, viewing lot costs..
Like \f[CR]print\f[R], it prints valid journal entries. Like \f[CR]print\f[R], it prints valid journal entries.
You can append or copy these to your journal file(s) when you are happy You can copy these into your journal file(s) when you are happy with how
with how they look. they look.
.IP .IP
.EX .EX
Flags: Flags:
\-\-migrate[=NEW] show closing and opening transactions, for Asset \-\-clopen[=TAGVAL] show closing and opening balances transactions,
and Liability accounts by default, tagged for easy for AL accounts by default
matching. The tag\[aq]s default value can be overridden \-\-close[=TAGVAL] show just a closing balances transaction
by providing NEW. \-\-open[=TAGVAL] show just an opening balances transaction
\-\-close[=NEW] (default) show a closing transaction \-\-assert[=TAGVAL] show a balance assertions transaction
\-\-open[=NEW] show an opening transaction \-\-assign[=TAGVAL] show a balance assignments transaction
\-\-assign[=NEW] show opening balance assignments \-\-retain[=TAGVAL] show a retain earnings transaction, for RX
\-\-assert[=NEW] show closing balance assertions accounts by default
\-\-retain[=NEW] show a retain earnings transaction, for Revenue
and Expense accounts by default
\-x \-\-explicit show all amounts explicitly \-x \-\-explicit show all amounts explicitly
\-\-show\-costs show amounts with different costs separately \-\-show\-costs show amounts with different costs separately
\-\-interleaved show source and destination postings together \-\-interleaved show source and destination postings together
@ -11385,97 +11458,116 @@ Flags:
\-\-round=TYPE how much rounding or padding should be done when \-\-round=TYPE how much rounding or padding should be done when
displaying amounts ? displaying amounts ?
none \- show original decimal digits, none \- show original decimal digits,
as in journal as in journal (default)
soft \- just add or remove decimal zeros soft \- just add or remove decimal zeros
to match precision (default) to match precision
hard \- round posting amounts to precision hard \- round posting amounts to precision
(can unbalance transactions) (can unbalance transactions)
all \- also round cost amounts to precision all \- also round cost amounts to precision
(can unbalance transactions) (can unbalance transactions)
.EE .EE
.PP .PP
\f[CR]close\f[R] currently has six modes, selected by a single mode \f[CR]close\f[R] has six modes, selected by choosing one of the mode
flag: flags (\f[CR]\-\-close\f[R] is the default).
.SS close \-\-migrate They all do much the same operation, but with different defaults, useful
This is the most common mode. in different situations.
It prints a \[dq]closing balances\[dq] transaction that zeroes out all .SS close \-\-clopen
asset and liability balances (by default), and an opposite \[dq]opening This is useful if migrating balances to a new journal file at the start
balances\[dq] transaction that restores them again. of a new year.
The balancing account will be \f[CR]equity:opening/closing balances\f[R] It prints a \[dq]closing balances\[dq] transaction that zeroes out
(or another specified by \f[CR]\-\-close\-acct\f[R] or account balances (Asset and Liability accounts, by default), and an
\f[CR]\-\-open\-acct\f[R]). opposite \[dq]opening balances\[dq] transaction that restores them
again.
Typically, you would run
.IP
.EX
hledger close \-\-clopen \-e NEWYEAR >> $LEDGER_FILE
.EE
.PP .PP
This is useful when migrating balances to a new journal file at the and then move the opening transaction from the old file to the new file
start of a new year. (and probably also update your LEDGER_FILE environment variable).
Essentially, you run
\f[CR]hledger close \-\-migrate=NEWYEAR \-e NEWYEAR\f[R] 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 \[dq]moving the balances into the
next file\[dq].
.PP .PP
You can close a different set of accounts by providing a query. Why might you do this ?
Eg if you want to include equity, you can add If your reports are fast, you may not need it.
\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R] arguments. But at some point you will probably want to partition your data by time,
(The balancing account is always excluded.) for performance or data integrity or regulatory reasons.
Revenues and expenses usually are not migrated to a new file directly; A new file or set of files per year is common.
see \f[CR]\-\-retain\f[R] below. Then, having each file/fileset \[dq]bookended\[dq] with opening and
closing balance transactions will allow you to freely pick and choose
which files to read \- just the current year, any past year, any
sequence of years, or all of them \- while showing correct account
balances in each case.
The earliest opening balances transaction sets correct starting
balances, and any later closing/opening pairs will harmlessly cancel
each other out.
.PP .PP
The generated transactions will have a \f[CR]start:\f[R] tag, with its The balances will be transferred to and from
value set to \f[CR]\-\-migrate\f[R]\[aq]s \f[CR]NEW\f[R] argument if \f[CR]equity:opening/closing balances\f[R] by default.
any, for easier matching or exclusion. You can override this by using \f[CR]\-\-close\-acct\f[R] and/or
When \f[CR]NEW\f[R] is not specified, it will be inferred if possible by \f[CR]\-\-open\-acct\f[R].
incrementing a number (eg a year number) within the default .PP
journal\[aq]s main file name. You can select a different set of accounts to close/open by providing an
The other modes behave similarly. account query.
Eg to add Equity accounts, provide arguments like
\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R].
When migrating to a new file, you\[aq]ll usually want to bring along the
AL or ALE accounts, but not the RX accounts (Revenue, Expense).
.PP
Assertions will be added indicating and checking the new balances of the
closed/opened accounts.
.PP
The generated transactions will have a \f[CR]clopen:\f[R] tag.
If the main journal\[aq]s base file name contains a number (eg a year
number), the tag\[aq]s value will be that base file name with the number
incremented.
Or you can choose the tag value yourself, by using
\f[CR]\-\-clopen=TAGVAL\f[R].
.SS close \-\-close .SS close \-\-close
This prints just the closing balances transaction of This prints just the closing balances transaction of
\f[CR]\-\-migrate\f[R]. \f[CR]\-\-clopen\f[R].
It is the default behaviour if you specify no mode flag. It is the default if you don\[aq]t specify a mode.
Using the customisation options below, you can move balances from any .PP
set of accounts to a different account. More customisation options are described below.
Among other things, you can use \f[CR]close \-\-close\f[R] to generate a
transaction moving the balances from any set of accounts, to a different
account.
(If you need to move just a portion of the balance, see hledger\-move.)
.SS close \-\-open .SS close \-\-open
This prints just the opening balances transaction of This prints just the opening balances transaction of
\f[CR]\-\-migrate\f[R]. \f[CR]\-\-clopen\f[R].
It is similar to Ledger\[aq]s equity command. (It is similar to Ledger\[aq]s equity command.)
.SS close \-\-assert .SS close \-\-assert
This prints a \[dq]closing balances\[dq] transaction (with This prints a transaction that asserts the account balances as they are
\f[CR]balances:\f[R] tag), that just declares balance assertions for the on the end date (and adds an \f[CR]assert:\f[R] tag).
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.
.SS close \-\-assign .SS close \-\-assign
This prints an \[dq]opening balances\[dq] transaction that restores the This prints a transaction that assigns the account balances as they are
account balances using balance assignments. on the end date (and adds an \[dq]assign:\[dq] tag).
Balance assignments work regardless of any previous balance, so a Unlike balance assertions, assignments will post changes to balances as
preceding closing balances transaction is not needed. needed to reach the specified amounts.
.PP .PP
However, omitting the closing balances transaction would unbalance This is another way to set starting balances when migrating to a new
equity. file, and it will set them correctly even in the presence of earlier
This is relatively harmless for personal reports, but it disturbs the files which do not have a closing balances transaction.
accounting equation, removing a source of error detection. However, it can hide errors, and disturb the accounting equation, so
So \f[CR]\-\-migrate\f[R] is generally the best way to set to set \f[CR]\-\-clopen\f[R] is usually recommended.
balances in new files, for now.
.SS close \-\-retain .SS close \-\-retain
This is like \f[CR]\-\-close\f[R] with different defaults: it prints a This is like \f[CR]\-\-close\f[R], but it closes Revenue and Expense
\[dq]retain earnings\[dq] transaction (with \f[CR]retain:\f[R] tag), account balances by default.
that transfers revenue and expense balances to They will be transferred to \f[CR]equity:retained earnings\f[R], or
\f[CR]equity:retained earnings\f[R]. another account specified with \f[CR]\-\-close\-acct\f[R].
.PP .PP
This is a different kind of closing, called \[dq]retaining earnings\[dq] Revenues and expenses correspond to changes in equity.
or \[dq]closing the books\[dq]; it is traditionally performed by They are categorised separately for reporting purposes, but
businesses at the end of each accounting period, to consolidate revenues traditionally at the end of each accounting period, businesses
and expenses into the main equity balance. consolidate them into equity, This is called \[dq]retaining
(\[dq]Revenues\[dq] and \[dq]expenses\[dq] are actually equity by earnings\[dq], or \[dq]closing the books\[dq].
another name, kept separate temporarily for reporting purposes.)
.PP .PP
In personal accounting you generally don\[aq]t need to do this, unless In personal accounting, there\[aq]s not much reason to do this, and most
you want the \f[CR]balancesheetequity\f[R] report to show a zero total, people don\[aq]t.
demonstrating that the accounting equation (A\-L=E) is satisfied. (One reason to do it is to help the \f[CR]balancesheetequity\f[R] report
show a zero total, demonstrating that the accounting equation (A\-L=E)
is satisfied.)
.SS close customisation .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
@ -11577,7 +11669,7 @@ Close assets/liabilities on 2022\-12\-31 and re\-open them on
2023\-01\-01: 2023\-01\-01:
.IP .IP
.EX .EX
$ hledger close \-\-migrate \-f 2022.journal \-p 2022 $ hledger close \-\-clopen \-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
.EE .EE
@ -11590,15 +11682,15 @@ $ hledger \-f 2022.journal bs not:desc:\[aq]closing balances\[aq]
.EE .EE
.PP .PP
For more flexibility, it helps to tag closing and opening transactions For more flexibility, it helps to tag closing and opening transactions
with eg \f[CR]start:NEWYEAR\f[R], then you can ensure correct balances with eg \f[CR]clopen:NEWYEAR\f[R], then you can ensure correct balances
by excluding all opening/closing transactions except the first, like so: by excluding all opening/closing transactions except the first, like so:
.IP .IP
.EX .EX
$ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2021 or not tag:start\[aq] $ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]
$ hledger bs \-Y \-f 2021.j \-f 2022.j expr:\[aq]tag:start=2021 or not tag:start\[aq] $ hledger bs \-Y \-f 2021.j \-f 2022.j expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]
$ hledger bs \-Y \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2022 or not tag:start\[aq] $ hledger bs \-Y \-f 2022.j \-f 2023.j expr:\[aq]tag:clopen=2022 or not tag:clopen\[aq]
$ hledger bs \-Y \-f 2021.j expr:\[aq]tag:start=2021 or not tag:start\[aq] $ hledger bs \-Y \-f 2021.j expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]
$ hledger bs \-Y \-f 2022.j expr:\[aq]tag:start=2022 or not tag:start\[aq] $ hledger bs \-Y \-f 2022.j expr:\[aq]tag:clopen=2022 or not tag:clopen\[aq]
$ hledger bs \-Y \-f 2023.j # unclosed file, no query needed $ hledger bs \-Y \-f 2023.j # unclosed file, no query needed
.EE .EE
.SS More detailed close examples .SS More detailed close examples

1317
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

452
hledger/hledger.txt
View File

@ -101,18 +101,23 @@ Input
Common tasks > Setting LEDGER_FILE. Common tasks > Setting LEDGER_FILE.
Text encoding Text encoding
Data files containing non-ascii characters must use UTF-8 encoding. An hledger input files containing non-ascii characters must use UTF-8 en-
optional byte order mark (BOM) is allowed, at the beginning of the file coding, with the exception of CSV (SSV, TSV..) files, which can be
(only). read from other encodings (see encoding CSV rule).
Also, your system should be configured with a locale that can decode In UTF-8 input files, an optional byte order mark (BOM) at the begin-
UTF-8 text. On some unix systems, you may need set the LANG environ- ning of the file is allowed.
ment variable, eg. You can read more about this in Unicode characters,
below.
On unix systems you can check a file's encoding with the file command. Your system may need to be configured with a locale that understands
If you need to import from a UTF-16-encoded CSV file, say, you can con- the input file's encoding. Eg on some unix systems, you may need set
vert it to UTF-8 with the iconv command. the LANG environment variable. You can read more about this in Unicode
characters, below.
On some unix systems you can use the file command to show a file's text
encoding. On mac, you'll need the version from homebrew: brew install
file-formula.
hledger's text output is always UTF-8 encoded.
Data formats Data formats
Usually the data file is in hledger's journal format, but it can be in Usually the data file is in hledger's journal format, but it can be in
@ -714,12 +719,12 @@ Options
perimental. perimental.
Shell completions Shell completions
If you use the bash shell, you can optionally set up context-sensitive If you use the bash or zsh shells, you can optionally set up con-
autocompletions when you press TAB in a hledger command line. At a text-sensitive autocompletion for hledger command lines. Try pressing
bash shell prompt, try pressing hledger<SPACE><TAB><TAB> (should list hledger<SPACE><TAB><TAB> (should list all hledger commands) or hledger
all hledger commands) or hledger reg acct:<TAB><TAB> (should list your reg acct:<TAB><TAB> (should list your top-level account names). If
top-level account names). If completions aren't working, or for more completions aren't working, or for more details, see Install > Shell
details, see Install > Shell completions. completions.
Output Output
Output destination Output destination
@ -775,12 +780,9 @@ Output
unicode or wide characters, you'll need a terminal and font that render unicode or wide characters, you'll need a terminal and font that render
those correctly. (This can be challenging on MS Windows.) those correctly. (This can be challenging on MS Windows.)
Some reports (register, aregister) will use the width indicated by the Some reports (register, aregister) will normally use the full window
COLUMNS environment variable. If your shell and terminal are working width. If this isn't working or you want to override it, you can use
well, they will keep COLUMNS updated as you resize the window. So reg- the -w/--width option.
ister reports normally will use the full window width. When this isn't
working or you want to override it, you can manually set COLUMNS, or
use the -w/--width option.
Balance reports (balance, balancesheet, incomestatement...) use what- Balance reports (balance, balancesheet, incomestatement...) use what-
ever width they need. Multi-period multi-currency reports can often be ever width they need. Multi-period multi-currency reports can often be
@ -810,6 +812,9 @@ Output
Paging Paging
In unix-like environments, when displaying large output (in any output In unix-like environments, when displaying large output (in any output
format) in the terminal, hledger tries to use a pager when appropriate. format) in the terminal, hledger tries to use a pager when appropriate.
(You can disable this with the --pager=no option, perhaps in your con-
fig file.)
The pager shows one page of text at a time, and lets you scroll around The pager shows one page of text at a time, and lets you scroll around
to see more. While it is active, usually SPACE shows the next page, h to see more. While it is active, usually SPACE shows the next page, h
shows help, and q quits. The home/end/page up/page down/cursor keys, shows help, and q quits. The home/end/page up/page down/cursor keys,
@ -830,9 +835,9 @@ Output
other conveniences. (At the time of writing: --chop-long-lines other conveniences. (At the time of writing: --chop-long-lines
--hilite-unread --ignore-case --mouse --no-init --quit-at-eof --hilite-unread --ignore-case --mouse --no-init --quit-at-eof
--quit-if-one-screen --RAW-CONTROL-CHARS --shift=8 --quit-if-one-screen --RAW-CONTROL-CHARS --shift=8
--squeeze-blank-lines --use-backslash --use-color ). If these don't --squeeze-blank-lines --use-backslash ). If these don't work well, you
work well, you can set your preferred options in the HLEDGER_LESS vari- can set your preferred options in the HLEDGER_LESS variable, which will
able, which will be used instead. be used instead.
HTML output HTML output
HTML output can be styled by an optional hledger.css file in the same HTML output can be styled by an optional hledger.css file in the same
@ -979,9 +984,9 @@ Output
$ hledger print -c '$1.000,0' $ hledger print -c '$1.000,0'
This option can repeated to set the display style for multiple commodi- This option can be repeated to set the display style for multiple com-
ties/currencies. Its argument is as described in the commodity direc- modities/currencies. Its argument is as described in the commodity di-
tive. rective.
In some cases hledger will adjust number formatting to improve their In some cases hledger will adjust number formatting to improve their
parseability (such as adding trailing decimal marks when needed). parseability (such as adding trailing decimal marks when needed).
@ -1004,10 +1009,6 @@ Output
Environment Environment
These environment variables affect hledger: These environment variables affect hledger:
COLUMNS This is normally set by your terminal; some hledger commands
(register) will format their output to this width. If not set, they
will try to use the available terminal width.
HLEDGER_LESS If less is your pager, this variable specifies the less HLEDGER_LESS If less is your pager, this variable specifies the less
options hledger should use. (Otherwise, LESS + custom options are options hledger should use. (Otherwise, LESS + custom options are
used.) used.)
@ -2386,7 +2387,7 @@ Journal
accounts as you expect, try troubleshooting with the accounts command, accounts as you expect, try troubleshooting with the accounts command,
eg something like: eg something like:
$ hledger accounts --alias assets=bassetts type:a $ hledger accounts --types -1 --alias assets=bassetts
commodity directive commodity directive
The commodity directive performs several functions: The commodity directive performs several functions:
@ -2422,7 +2423,7 @@ Journal
Commodity directive syntax Commodity directive syntax
A commodity directive is normally the word commodity followed by a sam- A commodity directive is normally the word commodity followed by a sam-
ple amount (and optionally a comment). Only the amount's symbol and ple amount (and optionally a comment). Only the amount's symbol and
format is significant. Eg: the number's format is significant. Eg:
commodity $1000.00 commodity $1000.00
commodity 1.000,00 EUR commodity 1.000,00 EUR
@ -3071,14 +3072,15 @@ Journal
syntax comparison. syntax comparison.
Other cost/lot notations Other cost/lot notations
A slight digression for Ledger and Beancount users. Ledger has a num- A slight digression for Ledger and Beancount users.
ber of cost/lot-related notations:
Ledger has a number of cost/lot-related notations:
o @ UNITCOST and @@ TOTALCOST o @ UNITCOST and @@ TOTALCOST
o expresses a conversion rate, as in hledger o expresses a conversion rate, as in hledger
o when buying, also creates a lot than can be selected at selling o when buying, also creates a lot that can be selected at selling
time time
o (@) UNITCOST and (@@) TOTALCOST (virtual cost) o (@) UNITCOST and (@@) TOTALCOST (virtual cost)
@ -3086,12 +3088,9 @@ Journal
o like the above, but also means "this cost was exceptional, don't o like the above, but also means "this cost was exceptional, don't
use it when inferring market prices". use it when inferring market prices".
Currently, hledger treats the above like @ and @@; the parentheses are o {=UNITCOST} and {{=TOTALCOST}} (fixed price)
ignored.
o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price) o when buying, means "this cost is also the fixed value, don't let it
o when buying, means "this cost is also the fixed price, don't let it
fluctuate in value reports" fluctuate in value reports"
o {UNITCOST} and {{TOTALCOST}} (lot price) o {UNITCOST} and {{TOTALCOST}} (lot price)
@ -3099,10 +3098,10 @@ Journal
o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre-
ates a lot ates a lot
o when selling, combined with @ ..., specifies an investment lot by o when selling, combined with @ ..., selects an existing lot by its
its cost basis; does not check if that lot is present cost basis. Does not check if that lot is present.
o and related: [YYYY/MM/DD] (lot date) o [YYYY/MM/DD] (lot date)
o when buying, attaches this acquisition date to the lot o when buying, attaches this acquisition date to the lot
@ -3114,26 +3113,32 @@ Journal
o when selling, selects a lot by its note o when selling, selects a lot by its note
Currently, hledger accepts any or all of the above in any order after Currently, hledger
the posting amount, but ignores them. (This can break transaction bal-
ancing.)
For Beancount users, the notation and behaviour is different: o accepts any or all of the above in any order after the posting amount
o supports @ and @@
o treats (@) and (@@) as synonyms for @ and @@
o and ignores the rest. (This can break transaction balancing.)
Beancount has simpler notation and different behaviour:
o @ UNITCOST and @@ TOTALCOST o @ UNITCOST and @@ TOTALCOST
o expresses a cost without creating a lot, as in hledger o expresses a cost without creating a lot, as in hledger
o when buying (augmenting) or selling (reducing) a lot, combined with o when buying (acquiring) or selling (disposing of) a lot, and com-
{...}: documents the cost/selling price (not used for transaction bined with {...}: is not used except to document the cost/selling
balancing) price
o {UNITCOST} and {{TOTALCOST}} o {UNITCOST} and {{TOTALCOST}}
o when buying (augmenting), expresses the cost for transaction bal- o when buying, expresses the cost for transaction balancing, and also
ancing, and also creates a lot with this cost basis attached creates a lot with this cost basis attached
o when selling (reducing), o when selling,
o selects a lot by its cost basis o selects a lot by its cost basis
@ -3142,13 +3147,19 @@ Journal
o expresses the selling price for transaction balancing o expresses the selling price for transaction balancing
Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but o {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNITCOST,
ignores it. YYYY-MM-DD, "LABEL"}
o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- o when selling, other combinations of date/cost/label, like the
COST, YYYY-MM-DD, "LABEL"} etc. above, are accepted for selecting the lot.
Currently, hledger rejects these. Currently, hledger
o supports @ and @@
o accepts the {UNITCOST}/{{TOTALCOST}} notation, but ignores it
o and rejects the rest.
CSV CSV
hledger can read CSV files (Character Separated Value - usually comma, hledger can read CSV files (Character Separated Value - usually comma,
@ -3199,6 +3210,8 @@ CSV
source optionally declare which file to read data source optionally declare which file to read data
from from
encoding optionally declare which text encoding the
data has
separator declare the field separator, instead of rely- separator declare the field separator, instead of rely-
ing on file extension ing on file extension
skip skip one or more header lines at start of file skip skip one or more header lines at start of file
@ -3251,6 +3264,23 @@ CSV
See also "Working with CSV > Reading files specified by rule". See also "Working with CSV > Reading files specified by rule".
encoding
encoding ENCODING
hledger normally expects non-ascii text to be UTF8-encoded. If you
need to read CSV files which have some other encoding, you can do it by
adding encoding ENCODING to your CSV rules. Eg: encoding ISO88591.
The following encodings are supported (these names are case-insensi-
tive, and can be written with inner spaces or hyphens if you prefer):
ASCII, UTF8, UTF16, UTF32, ISO88591, ISO88592, ISO88593, ISO88594,
ISO88595, ISO88596, ISO88597, ISO88598, ISO88599, ISO885910, ISO885911,
ISO885913, ISO885914, ISO885915, ISO885916, CP1250, CP1251, CP1252,
CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, KOI8R, KOI8U, GB18030,
MacOSRoman, JISX0201, JISX0208, ISO2022JP, ShiftJIS, CP437, CP737,
CP775, CP850, CP852, CP855, CP857, CP860, CP861, CP862, CP863, CP864,
CP865, CP866, CP869, CP874, CP932.
separator separator
You can use the separator rule to read other kinds of character-sepa- You can use the separator rule to read other kinds of character-sepa-
rated data. The argument is any single separator character, or the rated data. The argument is any single separator character, or the
@ -3693,11 +3723,16 @@ CSV
o By default they are OR'd (any of them can match). o By default they are OR'd (any of them can match).
o Matcher lines beginning with & (and optional space) are AND'ed with o Matcher lines beginning with & (or &&, since 1.42) are AND'ed with
the matcher above (all in the AND'ed group must match). the matcher above (all in the AND'ed group must match).
(Since 1.41:) You can use a negated ! matcher on a & line, meaning AND o Matcher lines beginning with & ! (since 1.41, or && !, since 1.42)
NOT. are first negated and then AND'ed with the matcher above.
You can also combine multiple matchers one the same line separated by
&& (AND) or && ! (AND NOT). Eg %description amazon && %date 2025-01-01
will match only when the description field contains "amazon" and the
date field contains "2025-01-01". Added in 1.42.
Match groups Match groups
Added in 1.32 Added in 1.32
@ -3729,9 +3764,9 @@ CSV
if,HLEDGERFIELD1,HLEDGERFIELD2,... if,HLEDGERFIELD1,HLEDGERFIELD2,...
MATCHERA,VALUE1,VALUE2,... MATCHERA,VALUE1,VALUE2,...
MATCHERB,VALUE1,VALUE2,... MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*)
; Comment line that explains MATCHERC ; Comment line that explains MATCHERD
MATCHERC,VALUE1,VALUE2,... MATCHERD,VALUE1,VALUE2,...
<empty line> <empty line>
The first character after if is taken to be this if table's field sepa- The first character after if is taken to be this if table's field sepa-
@ -3747,10 +3782,10 @@ CSV
of file). of file).
An if table like the above is interpreted as follows: try all of the An if table like the above is interpreted as follows: try all of the
matchers; whenever a matcher succeeds, assign all of the values on that lines with matchers; whenever a line with matchers succeeds, assign all
line to the corresponding hledger fields; If multiple lines match, of the values on that line to the corresponding hledger fields; If mul-
later lines will override fields assigned by the earlier ones - just tiple lines match, later lines will override fields assigned by the
like the sequence of if blocks would behave. earlier ones - just like the sequence of if blocks would behave.
If table presented above is equivalent to this sequence of if blocks: If table presented above is equivalent to this sequence of if blocks:
@ -3759,13 +3794,13 @@ CSV
HLEDGERFIELD2 VALUE2 HLEDGERFIELD2 VALUE2
... ...
if MATCHERB if MATCHERB && MATCHERC
HLEDGERFIELD1 VALUE1 HLEDGERFIELD1 VALUE1
HLEDGERFIELD2 VALUE2 HLEDGERFIELD2 VALUE2
... ...
; Comment line which explains MATCHERC ; Comment line which explains MATCHERD
if MATCHERC if MATCHERD
HLEDGERFIELD1 VALUE1 HLEDGERFIELD1 VALUE1
HLEDGERFIELD2 VALUE2 HLEDGERFIELD2 VALUE2
... ...
@ -5267,17 +5302,33 @@ Queries
quantity, not the new ones. (Except in hledger 1.22, #1625.) quantity, not the new ones. (Except in hledger 1.22, #1625.)
Pivoting Pivoting
Normally, hledger groups and sums amounts within each account. The Normally, hledger groups amounts and displays their totals by account
--pivot FIELD option substitutes some other transaction field for ac- (name). With --pivot PIVOTEXPR, some other field's (or multiple
count names, causing amounts to be grouped and summed by that field's fields') value is used as a synthetic account name, causing different
value instead. FIELD can be any of the transaction fields acct, sta- grouping and display. PIVOTEXPR can be
tus, code, desc, payee, note, or a tag name. When pivoting on a tag
and a posting has multiple values of that tag, only the first value is
displayed. Values containing colon:separated:parts will be displayed
hierarchically, like account names. Multiple, colon-delimited fields
can be pivoted simultaneously, generating a hierarchical account name.
Some examples: o any of these standard transaction or posting fields (their value is
substituted): status, code, desc, payee, note, acct, comm/cur, amt,
cost
o or a tag name
o or any combination of these, colon-separated.
Some special cases:
o Colons appearing in PIVOTEXPR or in a pivoted tag value will generate
account hierarchy.
o When pivoting a posting has multiple values for a tag, the pivoted
value of that tag will be the first value.
o When a posting has multiple commodities, the pivoted value of
"comm"/"cur" will be "". Also when an unrecognised tag name or field
is provided, its pivoted value will be "". (If this causes confusing
output, consider excluding those postings from the report.)
Examples:
2016/02/16 Yearly Dues Payment 2016/02/16 Yearly Dues Payment
assets:bank account 2 EUR assets:bank account 2 EUR
@ -5314,7 +5365,7 @@ Pivoting
-------------------- --------------------
-2 EUR -2 EUR
Hierarchical reports can be generated with multiple pivots: Hierarchical reports can be generated with multiple pivot values:
$ hledger balance Income:Dues --pivot kind:member $ hledger balance Income:Dues --pivot kind:member
-2 EUR Lifetime:John Doe -2 EUR Lifetime:John Doe
@ -5664,9 +5715,9 @@ Cost reporting
In some transactions - for example a currency conversion, or a purchase In some transactions - for example a currency conversion, or a purchase
or sale of stock - one commodity is exchanged for another. In these or sale of stock - one commodity is exchanged for another. In these
transactions there is a conversion rate, also called the cost (when transactions there is a conversion rate, also called the cost (when
buying) or selling price (when selling). In hledger docs we just say buying) or selling price (when selling). (In hledger docs we just say
"cost", for convenience; feel free to mentally translate to "conversion "cost" generically for convenience.) With the -B/--cost flag, hledger
rate" or "selling price" if helpful. can show amounts "at cost", converted to the cost's commodity.
Recording costs Recording costs
We'll explore several ways of recording transactions involving costs. We'll explore several ways of recording transactions involving costs.
@ -5872,12 +5923,15 @@ Cost reporting
and let us know what problems you find. and let us know what problems you find.
Value reporting Value reporting
Instead of reporting amounts in their original commodity, hledger can hledger can also show amounts "at market value", converted to some
convert them to cost/sale amount (using the conversion rate recorded in other commodity using the market price or conversion rate on a certain
the transaction), and/or to market value (using some market price on a date.
certain date). This is controlled by the --value=TYPE[,COMMODITY] op-
tion, which will be described below. We also provide the simpler -V This is controlled by the --value=TYPE[,COMMODITY] option. We also
and -X COMMODITY options, and often one of these is all you need: provide simpler -V and -X COMMODITY aliases for this, which are often
sufficient. The market prices are declared with a special P directive,
and/or they can be inferred from the costs recorded in transactions, by
using the --infer-market-prices flag.
-V: Value -V: Value
The -V/--market flag converts amounts to market value in their default The -V/--market flag converts amounts to market value in their default
@ -6497,6 +6551,8 @@ Help commands
$ hledger demo 1 # play the first demo at default speed (2x) $ hledger demo 1 # play the first demo at default speed (2x)
$ hledger demo install -s4 # play the "install" demo at 4x speed $ hledger demo install -s4 # play the "install" demo at 4x speed
This command is experimental: there aren't many useful demos yet.
User interface commands User interface commands
ui ui
Runs hledger-ui (if installed). Runs hledger-ui (if installed).
@ -7064,13 +7120,14 @@ Standard report commands
--round=TYPE how much rounding or padding should be done when --round=TYPE how much rounding or padding should be done when
displaying amounts ? displaying amounts ?
none - show original decimal digits, none - show original decimal digits,
as in journal as in journal (default)
soft - just add or remove decimal zeros soft - just add or remove decimal zeros
to match precision (default) to match precision
hard - round posting amounts to precision hard - round posting amounts to precision
(can unbalance transactions) (can unbalance transactions)
all - also round cost amounts to precision all - also round cost amounts to precision
(can unbalance transactions) (can unbalance transactions)
--invert display all amounts with reversed sign
--new show only newer-dated transactions added in each --new show only newer-dated transactions added in each
file since last run file since last run
-m --match=DESC fuzzy search for one recent transaction with -m --match=DESC fuzzy search for one recent transaction with
@ -7175,6 +7232,10 @@ Standard report commands
print, other features print, other features
With -B/--cost, amounts with costs are shown converted to cost. With -B/--cost, amounts with costs are shown converted to cost.
With --invert, posting amounts are shown with their sign flipped. It
could be useful if you have accidentally recorded some transactions
with the wrong signs.
With --new, print shows only transactions it has not seen on a previous With --new, print shows only transactions it has not seen on a previous
run. This uses the same deduplication system as the import command. run. This uses the same deduplication system as the import command.
(See import's docs for details.) (See import's docs for details.)
@ -7271,8 +7332,8 @@ Standard report commands
postings before report start date) (default) postings before report start date) (default)
--invert display all amounts with reversed sign --invert display all amounts with reversed sign
--heading=YN show heading row above table: yes (default) or no --heading=YN show heading row above table: yes (default) or no
-w --width=N set output width (default: terminal width or -w --width=N set output width (default: terminal width). -wN,M
$COLUMNS). -wN,M sets description width as well. sets description width as well.
--align-all guarantee alignment across all lines (slower) --align-all guarantee alignment across all lines (slower)
-O --output-format=FMT select the output format. Supported formats: -O --output-format=FMT select the output format. Supported formats:
txt, html, csv, tsv, json. txt, html, csv, tsv, json.
@ -7378,8 +7439,8 @@ Standard report commands
--sort=FIELDS sort by: date, desc, account, amount, absamount, --sort=FIELDS sort by: date, desc, account, amount, absamount,
or a comma-separated combination of these. For a or a comma-separated combination of these. For a
descending sort, prefix with -. (Default: date) descending sort, prefix with -. (Default: date)
-w --width=N set output width (default: terminal width or -w --width=N set output width (default: terminal width). -wN,M
$COLUMNS). -wN,M sets description width as well. sets description width as well.
--align-all guarantee alignment across all lines (slower) --align-all guarantee alignment across all lines (slower)
--base-url=URLPREFIX in html output, generate links to hledger-web, --base-url=URLPREFIX in html output, generate links to hledger-web,
with this prefix. (Usually the base url shown by with this prefix. (Usually the base url shown by
@ -7491,9 +7552,8 @@ Standard report commands
ing will be shown and the program exit code will be non-zero. ing will be shown and the program exit code will be non-zero.
Custom register output Custom register output
register uses the full terminal width by default, except on windows. register normally uses the full terminal width (or 80 columns if it
You can override this by setting the COLUMNS environment variable (not can't detect that). You can override this with the --width/-w option.
a bash shell variable) or by using the --width/-w option.
The description and account columns normally share the space equally The description and account columns normally share the space equally
(about half of (width - 40) each). You can adjust this by adding a de- (about half of (width - 40) each). You can adjust this by adding a de-
@ -7508,10 +7568,7 @@ Standard report commands
$ hledger reg # use terminal width (or 80 on windows) $ hledger reg # use terminal width (or 80 on windows)
$ hledger reg -w 100 # use width 100 $ hledger reg -w 100 # use width 100
$ COLUMNS=100 hledger reg # set with one-time environment variable
$ export COLUMNS=100; hledger reg # set till session end (or window resize)
$ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w 100,40 # set overall width 100, 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 (Added in 1.32), tions The output formats supported are txt, csv, tsv (Added in 1.32),
@ -7954,10 +8011,10 @@ Advanced report commands
--transpose switch rows and columns (use vertical time axis) --transpose switch rows and columns (use vertical time axis)
--layout=ARG how to lay out multi-commodity amounts and the --layout=ARG how to lay out multi-commodity amounts and the
overall table: overall table:
'wide[,WIDTH]': commodities on one line 'wide[,W]': commodities on same line, up to W wide
'tall' : commodities on separate lines 'tall' : commodities on separate lines
'bare' : commodity symbols in one column 'bare' : commodity symbols in a separate column
'tidy' : every attribute in its own column 'tidy' : each data field in its own column
--base-url=URLPREFIX in html output, generate links to hledger-web, --base-url=URLPREFIX in html output, generate links to hledger-web,
with this prefix. (Usually the base url shown by with this prefix. (Usually the base url shown by
hledger-web; can also be relative.) hledger-web; can also be relative.)
@ -9066,24 +9123,21 @@ Data generation commands
close close
(equity) (equity)
close generates several kinds of "closing" and/or "opening" transac- close prints several kinds of "closing" and/or "opening" transactions,
tions, useful in certain situations, including migrating balances to a useful in various situations: migrating balances to a new journal file,
new journal file, retaining earnings into equity, consolidating bal- retaining earnings into equity, consolidating balances, viewing lot
ances, or viewing lots. Like print, it prints valid journal entries. costs.. Like print, it prints valid journal entries. You can copy
You can append or copy these to your journal file(s) when you are happy these into your journal file(s) when you are happy with how they look.
with how they look.
Flags: Flags:
--migrate[=NEW] show closing and opening transactions, for Asset --clopen[=TAGVAL] show closing and opening balances transactions,
and Liability accounts by default, tagged for easy for AL accounts by default
matching. The tag's default value can be overridden --close[=TAGVAL] show just a closing balances transaction
by providing NEW. --open[=TAGVAL] show just an opening balances transaction
--close[=NEW] (default) show a closing transaction --assert[=TAGVAL] show a balance assertions transaction
--open[=NEW] show an opening transaction --assign[=TAGVAL] show a balance assignments transaction
--assign[=NEW] show opening balance assignments --retain[=TAGVAL] show a retain earnings transaction, for RX
--assert[=NEW] show closing balance assertions accounts by default
--retain[=NEW] show a retain earnings transaction, for Revenue
and Expense accounts by default
-x --explicit show all amounts explicitly -x --explicit show all amounts explicitly
--show-costs show amounts with different costs separately --show-costs show amounts with different costs separately
--interleaved show source and destination postings together --interleaved show source and destination postings together
@ -9095,89 +9149,103 @@ Data generation commands
--round=TYPE how much rounding or padding should be done when --round=TYPE how much rounding or padding should be done when
displaying amounts ? displaying amounts ?
none - show original decimal digits, none - show original decimal digits,
as in journal as in journal (default)
soft - just add or remove decimal zeros soft - just add or remove decimal zeros
to match precision (default) to match precision
hard - round posting amounts to precision hard - round posting amounts to precision
(can unbalance transactions) (can unbalance transactions)
all - also round cost amounts to precision all - also round cost amounts to precision
(can unbalance transactions) (can unbalance transactions)
close currently has six modes, selected by a single mode flag: close has six modes, selected by choosing one of the mode flags
(--close is the default). They all do much the same operation, but
with different defaults, useful in different situations.
close --migrate close --clopen
This is the most common mode. It prints a "closing balances" transac- This is useful if migrating balances to a new journal file at the start
tion that zeroes out all asset and liability balances (by default), and of a new year. It prints a "closing balances" transaction that zeroes
an opposite "opening balances" transaction that restores them again. out account balances (Asset and Liability accounts, by default), and an
The balancing account will be equity:opening/closing balances (or an- opposite "opening balances" transaction that restores them again. Typ-
other specified by --close-acct or --open-acct). ically, you would run
This is useful when migrating balances to a new journal file at the hledger close --clopen -e NEWYEAR >> $LEDGER_FILE
start of a new year. Essentially, you run hledger close --mi-
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".
You can close a different set of accounts by providing a query. Eg if and then move the opening transaction from the old file to the new file
you want to include equity, you can add assets liabilities equity or (and probably also update your LEDGER_FILE environment variable).
type:ALE arguments. (The balancing account is always excluded.) Rev-
enues 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 Why might you do this ? If your reports are fast, you may not need it.
to --migrate's NEW argument if any, for easier matching or exclusion. But at some point you will probably want to partition your data by
When NEW is not specified, it will be inferred if possible by incre- time, for performance or data integrity or regulatory reasons. A new
menting a number (eg a year number) within the default journal's main file or set of files per year is common. Then, having each file/file-
file name. The other modes behave similarly. set "bookended" with opening and closing balance transactions will al-
low you to freely pick and choose which files to read - just the cur-
rent year, any past year, any sequence of years, or all of them - while
showing correct account balances in each case. The earliest opening
balances transaction sets correct starting balances, and any later
closing/opening pairs will harmlessly cancel each other out.
The balances will be transferred to and from equity:opening/closing
balances by default. You can override this by using --close-acct
and/or --open-acct.
You can select a different set of accounts to close/open by providing
an account query. Eg to add Equity accounts, provide arguments like
assets liabilities equity or type:ALE. When migrating to a new file,
you'll usually want to bring along the AL or ALE accounts, but not the
RX accounts (Revenue, Expense).
Assertions will be added indicating and checking the new balances of
the closed/opened accounts.
The generated transactions will have a clopen: tag. If the main jour-
nal's base file name contains a number (eg a year number), the tag's
value will be that base file name with the number incremented. Or you
can choose the tag value yourself, by using --clopen=TAGVAL.
close --close close --close
This prints just the closing balances transaction of --migrate. It is This prints just the closing balances transaction of --clopen. It is
the default behaviour if you specify no mode flag. Using the customi- the default if you don't specify a mode.
sation options below, you can move balances from any set of accounts to
a different account. More customisation options are described below. Among other things,
you can use close --close to generate a transaction moving the balances
from any set of accounts, to a different account. (If you need to move
just a portion of the balance, see hledger-move.)
close --open close --open
This prints just the opening balances transaction of --migrate. It is This prints just the opening balances transaction of --clopen. (It is
similar to Ledger's equity command. similar to Ledger's equity command.)
close --assert close --assert
This prints a "closing balances" transaction (with balances: tag), that This prints a transaction that asserts the account balances as they are
just declares balance assertions for the current balances without on the end date (and adds an assert: tag). It could be useful as docu-
changing them. It could be useful as documention and to guard against mention and to guard against changes.
changes.
close --assign close --assign
This prints an "opening balances" transaction that restores the account This prints a transaction that assigns the account balances as they are
balances using balance assignments. Balance assignments work regard- on the end date (and adds an "assign:" tag). Unlike balance asser-
less of any previous balance, so a preceding closing balances transac- tions, assignments will post changes to balances as needed to reach the
tion is not needed. specified amounts.
However, omitting the closing balances transaction would unbalance eq- This is another way to set starting balances when migrating to a new
uity. This is relatively harmless for personal reports, but it dis- file, and it will set them correctly even in the presence of earlier
turbs the accounting equation, removing a source of error detection. files which do not have a closing balances transaction. However, it
So --migrate is generally the best way to set to set balances in new can hide errors, and disturb the accounting equation, so --clopen is
files, for now. usually recommended.
close --retain close --retain
This is like --close with different defaults: it prints a "retain earn- This is like --close, but it closes Revenue and Expense account bal-
ings" transaction (with retain: tag), that transfers revenue and ex- ances by default. They will be transferred to equity:retained earn-
pense balances to equity:retained earnings. ings, or another account specified with --close-acct.
This is a different kind of closing, called "retaining earnings" or Revenues and expenses correspond to changes in equity. They are cate-
"closing the books"; it is traditionally performed by businesses at the gorised separately for reporting purposes, but traditionally at the end
end of each accounting period, to consolidate revenues and expenses of each accounting period, businesses consolidate them into equity,
into the main equity balance. ("Revenues" and "expenses" are actually This is called "retaining earnings", or "closing the books".
equity by another name, kept separate temporarily for reporting pur-
poses.)
In personal accounting you generally don't need to do this, unless you In personal accounting, there's not much reason to do this, and most
want the balancesheetequity report to show a zero total, demonstrating people don't. (One reason to do it is to help the balancesheetequity
that the accounting equation (A-L=E) is satisfied. report show a zero total, demonstrating that the accounting equation
(A-L=E) is satisfied.)
close customisation close customisation
In all modes, the following things can be overridden: In all modes, the following things can be overridden:
@ -9265,7 +9333,7 @@ Data generation commands
Migrate balances to a new file Migrate balances to a new file
Close assets/liabilities 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:
$ hledger close --migrate -f 2022.journal -p 2022 $ hledger close --clopen -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
@ -9275,14 +9343,14 @@ Data generation commands
$ 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 For more flexibility, it helps to tag closing and opening transactions
with eg start:NEWYEAR, then you can ensure correct balances by exclud- with eg clopen:NEWYEAR, then you can ensure correct balances by exclud-
ing all opening/closing transactions except the first, like so: ing all opening/closing transactions except the first, like so:
$ 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
More detailed close examples More detailed close examples
@ -10079,4 +10147,4 @@ LICENSE
SEE ALSO SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), ledger(1) hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
hledger-1.41.99 December 2024 HLEDGER(1) hledger-1.41.99 March 2025 HLEDGER(1)