From e25cd526b7f03da219511605b805078a74bd85f7 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 6 Mar 2025 16:05:55 -1000 Subject: [PATCH] ;doc: update embedded manuals --- hledger-lib/.date.m4 | 2 +- hledger-ui/.date.m4 | 2 +- hledger-ui/hledger-ui.1 | 5 +- hledger-ui/hledger-ui.info | 38 +- hledger-ui/hledger-ui.txt | 4 +- hledger-web/.date.m4 | 2 +- hledger-web/hledger-web.1 | 2 +- hledger-web/hledger-web.info | 22 +- hledger-web/hledger-web.txt | 2 +- hledger/.date.m4 | 2 +- hledger/hledger.1 | 514 +++++---- hledger/hledger.info | 1319 +++++++++++----------- hledger/hledger.txt | 2018 ++++++++++++++++++---------------- 13 files changed, 2075 insertions(+), 1857 deletions(-) diff --git a/hledger-lib/.date.m4 b/hledger-lib/.date.m4 index 466686f62..e5d9e9e97 100644 --- a/hledger-lib/.date.m4 +++ b/hledger-lib/.date.m4 @@ -1,2 +1,2 @@ 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 diff --git a/hledger-ui/.date.m4 b/hledger-ui/.date.m4 index 466686f62..e5d9e9e97 100644 --- a/hledger-ui/.date.m4 +++ b/hledger-ui/.date.m4 @@ -1,2 +1,2 @@ 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 diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 9ea6d72e7..61f19def3 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -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 on both machines should be roughly in agreement. .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 with \f[CR]\-f/\-\-file\f[R]. Default: \f[CR]$HOME/.hledger.journal\f[R]. diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index 80bc3df32..6c1447ecb 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -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 START-INFO-DIR-ENTRY @@ -514,9 +514,7 @@ File: hledger-ui.info, Node: ENVIRONMENT, Next: BUGS, Prev: WATCH MODE, Up: 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'.  @@ -543,22 +541,22 @@ above).  Tag Table: -Node: Top223 -Node: OPTIONS1874 -Node: MOUSE8548 -Node: KEYS8880 -Node: SCREENS13884 -Node: Menu screen14624 -Node: Cash accounts screen14940 -Node: Balance sheet accounts screen15301 -Node: Income statement accounts screen15637 -Node: All accounts screen16022 -Node: Register screen16385 -Node: Transaction screen18828 -Node: Error screen20403 -Node: WATCH MODE20769 -Node: ENVIRONMENT22345 -Node: BUGS22652 +Node: Top221 +Node: OPTIONS1872 +Node: MOUSE8546 +Node: KEYS8878 +Node: SCREENS13882 +Node: Menu screen14622 +Node: Cash accounts screen14938 +Node: Balance sheet accounts screen15299 +Node: Income statement accounts screen15635 +Node: All accounts screen16020 +Node: Register screen16383 +Node: Transaction screen18826 +Node: Error screen20401 +Node: WATCH MODE20767 +Node: ENVIRONMENT22343 +Node: BUGS22576  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index a99d94fbe..d2fdd3efa 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -412,8 +412,6 @@ WATCH MODE clocks on both machines should be roughly in agreement. ENVIRONMENT - COLUMNS The screen width to use. Default: the full terminal width. - LEDGER_FILE The main journal file to use when not specified with -f/--file. Default: $HOME/.hledger.journal. @@ -452,4 +450,4 @@ LICENSE SEE ALSO 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) diff --git a/hledger-web/.date.m4 b/hledger-web/.date.m4 index 466686f62..e5d9e9e97 100644 --- a/hledger-web/.date.m4 +++ b/hledger-web/.date.m4 @@ -1,2 +1,2 @@ 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 diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 175a44768..2a878805e 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -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" diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 717b8ad92..5dbfda9a0 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -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 START-INFO-DIR-ENTRY @@ -528,16 +528,16 @@ https://bugs.hledger.org), or on the hledger chat or mail list  Tag Table: -Node: Top225 -Node: OPTIONS2571 -Node: PERMISSIONS11260 -Node: EDITING UPLOADING DOWNLOADING12611 -Node: RELOADING13626 -Node: JSON API14193 -Node: DEBUG OUTPUT19842 -Node: Debug output19994 -Node: ENVIRONMENT20512 -Node: BUGS20748 +Node: Top223 +Node: OPTIONS2569 +Node: PERMISSIONS11258 +Node: EDITING UPLOADING DOWNLOADING12609 +Node: RELOADING13624 +Node: JSON API14191 +Node: DEBUG OUTPUT19840 +Node: Debug output19992 +Node: ENVIRONMENT20510 +Node: BUGS20746  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index c946186cb..03af8e300 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -480,4 +480,4 @@ LICENSE SEE ALSO 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) diff --git a/hledger/.date.m4 b/hledger/.date.m4 index 466686f62..e5d9e9e97 100644 --- a/hledger/.date.m4 +++ b/hledger/.date.m4 @@ -1,2 +1,2 @@ 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 diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 75d173707..68a9db5a6 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"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 LEDGER_FILE. .SS Text encoding -Data files containing non\-ascii characters must use UTF\-8 encoding. -An optional byte order mark (BOM) is allowed, at the beginning of the -file (only). +hledger input files containing non\-ascii characters must use UTF\-8 +encoding, with the exception of CSV (SSV, TSV..) +files, which can be read from other encodings (see \f[CR]encoding\f[R] +CSV rule). .PP -Also, your system should be configured with a locale that can decode -UTF\-8 text. -On some unix systems, you may need set the \f[CR]LANG\f[R] environment -variable, eg. +In UTF\-8 input files, an optional byte order mark (BOM) at the +beginning of the file is allowed. +.PP +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. .PP -On unix systems you can check a file\[aq]s encoding with the -\f[CR]file\f[R] command. -If you need to import from a UTF\-16\-encoded CSV file, say, you can -convert it to UTF\-8 with the \f[CR]iconv\f[R] command. +On some unix systems you can use the \f[CR]file\f[R] command to show a +file\[aq]s text encoding. +On mac, you\[aq]ll need the version from homebrew: +\f[CR]brew install file\-formula\f[R]. +.PP +hledger\[aq]s text output is always UTF\-8 encoded. .SS Data formats 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: @@ -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 \f[I]experimental\f[R]. .SS Shell completions -If you use the bash shell, you can optionally set up context\-sensitive -autocompletions when you press TAB in a hledger command line. -At a bash shell prompt, try pressing \f[CR]hledger\f[R] -(should list all hledger commands) or -\f[CR]hledger reg acct:\f[R] (should list your top\-level -account names). +If you use the bash or zsh shells, you can optionally set up +context\-sensitive autocompletion for hledger command lines. +Try pressing \f[CR]hledger\f[R] (should list all +hledger commands) or \f[CR]hledger reg acct:\f[R] (should list +your top\-level account names). If completions aren\[aq]t working, or for more details, see Install > Shell completions. .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. (This can be challenging on MS Windows.) .PP -Some reports (\f[CR]register\f[R], \f[CR]aregister\f[R]) will use the -width indicated by the \f[CR]COLUMNS\f[R] environment variable. -If your shell and terminal are working well, they will keep COLUMNS -updated as you resize the window. -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. +Some reports (\f[CR]register\f[R], \f[CR]aregister\f[R]) will normally +use the full window width. +If this isn\[aq]t working or you want to override it, you can use the +\f[CR]\-w\f[R]/\f[CR]\-\-width\f[R] option. .PP Balance reports (\f[CR]balance\f[R], \f[CR]balancesheet\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 In unix\-like environments, when displaying large output (in any output 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 to see more. 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 \-\-ignore\-case \-\-mouse \-\-no\-init \-\-quit\-at\-eof \-\-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 \f[CR]HLEDGER_LESS\f[R] variable, which will be used instead. .SS HTML output @@ -1336,7 +1341,7 @@ shown: $ hledger print \-c \[aq]$1.000,0\[aq] .EE .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. Its argument is as described in the commodity directive. .PP @@ -1366,10 +1371,6 @@ hledger bal \-\-debug=3 2>hledger.log .SH Environment These environment variables affect hledger: .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 specifies the \f[CR]less\f[R] options hledger should use. (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: .IP .EX -$ hledger accounts \-\-alias assets=bassetts type:a +$ hledger accounts \-\-types \-1 \-\-alias assets=bassetts .EE .SS \f[CR]commodity\f[R] directive The \f[CR]commodity\f[R] directive performs several functions: @@ -3151,7 +3152,7 @@ and precise. .SS Commodity directive syntax A commodity directive is normally the word \f[CR]commodity\f[R] followed 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: .IP .EX @@ -3880,14 +3881,15 @@ See also https://hledger.org/ledger.html for a detailed hledger/Ledger syntax comparison. .SS Other cost/lot notations 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 \f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R] .RS 2 .IP \[bu] 2 expresses a conversion rate, as in hledger .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 .IP \[bu] 2 \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 use it when inferring market prices\[dq]. .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 -\f[CR]{=FIXEDUNITCOST}\f[R] and \f[CR]{{=FIXEDTOTALCOST}}\f[R] (fixed -price) +\f[CR]{=UNITCOST}\f[R] and \f[CR]{{=TOTALCOST}}\f[R] (fixed price) .RS 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] .RE .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 \f[CR]\[at]\[at] TOTALCOST\f[R], also creates a lot .IP \[bu] 2 -when selling, combined with \f[CR]\[at] ...\f[R], specifies an -investment lot by its cost basis; does not check if that lot is present +when selling, combined with \f[CR]\[at] ...\f[R], selects an existing +lot by its cost basis. +Does not check if that lot is present. .RE .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 .IP \[bu] 2 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 .RE .PP -Currently, hledger accepts any or all of the above in any order after -the posting amount, but ignores them. +Currently, hledger +.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.) .PP -For Beancount users, the notation and behaviour is different: +\f[B]Beancount\f[R] has simpler notation and different behaviour: .IP \[bu] 2 \f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R] .RS 2 .IP \[bu] 2 expresses a cost without creating a lot, as in hledger .IP \[bu] 2 -when buying (augmenting) or selling (reducing) a lot, combined with -\f[CR]{...}\f[R]: documents the cost/selling price (not used for -transaction balancing) +when buying (acquiring) or selling (disposing of) a lot, and combined +with \f[CR]{...}\f[R]: is not used except to document the cost/selling +price .RE .IP \[bu] 2 \f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R] .RS 2 .IP \[bu] 2 -when buying (augmenting), expresses the cost for transaction balancing, -and also creates a lot with this cost basis attached +when buying, expresses the cost for transaction balancing, and also +creates a lot with this cost basis attached .IP \[bu] 2 -when selling (reducing), +when selling, .RS 2 .IP \[bu] 2 selects a lot by its cost basis @@ -3968,15 +3975,24 @@ unambiguously (depending on booking method configured) expresses the selling price for transaction balancing .RE .RE -.PP -Currently, hledger accepts the -\f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation but ignores it. .IP \[bu] 2 -variations: \f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R], -\f[CR]{\[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]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R], \f[CR]{\[dq]LABEL\[dq]}\f[R], +\f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R], +\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 -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 .SH CSV hledger can read CSV files (Character Separated Value \- usually comma, @@ -4046,6 +4062,11 @@ T}@T{ optionally declare which file to read data from 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] T}@T{ declare the field separator, instead of relying on file extension @@ -4152,6 +4173,26 @@ source Checking1*.csv .EE .PP 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] You can use the \f[CR]separator\f[R] rule to read other kinds of character\-separated data. @@ -4697,12 +4738,20 @@ When an if block has multiple matchers, each on its own line, .IP \[bu] 2 By default they are OR\[aq]d (any of them can match). .IP \[bu] 2 -Matcher lines beginning with \f[CR]&\f[R] (and optional space) are -AND\[aq]ed with the matcher above (all in the AND\[aq]ed group must -match). +Matcher lines beginning with \f[CR]&\f[R] (or \f[CR]&&\f[R], \f[I]since +1.42\f[R]) are AND\[aq]ed with the matcher above (all in the AND\[aq]ed +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 -\f[I](Since 1.41:)\f[R] You can use a negated \f[CR]!\f[R] matcher on a -\f[CR]&\f[R] line, meaning AND NOT. +You can also combine multiple matchers one the same line separated by +\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 \f[I]Added in 1.32\f[R] .PP @@ -4739,9 +4788,9 @@ like this: .EX if,HLEDGERFIELD1,HLEDGERFIELD2,... MATCHERA,VALUE1,VALUE2,... -MATCHERB,VALUE1,VALUE2,... -; Comment line that explains MATCHERC -MATCHERC,VALUE1,VALUE2,... +MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*) +; Comment line that explains MATCHERD +MATCHERD,VALUE1,VALUE2,... .EE .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). .PP 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 -line to the corresponding hledger fields; If multiple lines match, later -lines will override fields assigned by the earlier ones \- just like the -sequence of \f[CR]if\f[R] blocks would behave. +lines with matchers; whenever a line with matchers succeeds, assign all +of the values on that line to the corresponding hledger fields; If +multiple lines match, later lines will override fields assigned by the +earlier ones \- just like the sequence of \f[CR]if\f[R] blocks would +behave. .PP If table presented above is equivalent to this sequence of if blocks: .IP @@ -4774,13 +4824,13 @@ if MATCHERA HLEDGERFIELD2 VALUE2 ... -if MATCHERB +if MATCHERB && MATCHERC HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 ... -; Comment line which explains MATCHERC -if MATCHERC +; Comment line which explains MATCHERD +if MATCHERD HLEDGERFIELD1 VALUE1 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. (Except in hledger 1.22, #1625.) .SH Pivoting -Normally, hledger groups and sums amounts within each account. -The \f[CR]\-\-pivot FIELD\f[R] option substitutes some other transaction -field for account names, causing amounts to be grouped and summed by -that field\[aq]s value instead. -FIELD can be any of the transaction fields \f[CR]acct\f[R], -\f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R], \f[CR]payee\f[R], -\f[CR]note\f[R], 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 \f[CR]colon:separated:parts\f[R] will be displayed -hierarchically, like account names. -Multiple, colon\-delimited fields can be pivoted simultaneously, -generating a hierarchical account name. +Normally, hledger groups amounts and displays their totals by account +(name). +With \f[CR]\-\-pivot PIVOTEXPR\f[R], some other field\[aq]s (or multiple +fields\[aq]) value is used as a synthetic account name, causing +different grouping and display. +PIVOTEXPR can be +.IP \[bu] 2 +any of these standard transaction or posting fields (their value is +substituted): \f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R], +\f[CR]payee\f[R], \f[CR]note\f[R], \f[CR]acct\f[R], +\f[CR]comm\f[R]/\f[CR]cur\f[R], \f[CR]amt\f[R], \f[CR]cost\f[R] +.IP \[bu] 2 +or a tag name +.IP \[bu] 2 +or any combination of these, colon\-separated. .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 .EX 2016/02/16 Yearly Dues Payment @@ -6828,7 +6895,7 @@ $ hledger balance \-\-pivot member acct:. \-2 EUR .EE .PP -Hierarchical reports can be generated with multiple pivots: +Hierarchical reports can be generated with multiple pivot values: .IP .EX $ 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. In these transactions there is a conversion rate, also called the cost (when buying) or selling price (when selling). -In hledger docs we just say \[dq]cost\[dq], for convenience; feel free -to mentally translate to \[dq]conversion rate\[dq] or \[dq]selling -price\[dq] if helpful. +(In hledger docs we just say \[dq]cost\[dq] generically for +convenience.) +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 We\[aq]ll explore several ways of recording transactions involving costs. @@ -7463,14 +7531,16 @@ alias h=\[dq]hledger \-\-infer\-equity \-\-infer\-costs\[dq] and let us know what problems you find. .PP .SH Value reporting -Instead of reporting amounts in their original commodity, hledger can -convert them to cost/sale amount (using the conversion rate recorded in -the transaction), and/or to market value (using some market price on a -certain date). -This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option, -which will be described below. -We also provide the simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R] -options, and often one of these is all you need: +hledger can also show amounts \[dq]at market value\[dq], converted to +some other commodity using the market price or conversion rate on a +certain date. +.PP +This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option. +We also provide simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R] +aliases for this, which are often sufficient. +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 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 @@ -8360,6 +8430,8 @@ $ hledger demo # list available demos $ hledger demo 1 # play the first demo at default speed (2x) $ hledger demo install \-s4 # play the \[dq]install\[dq] demo at 4x speed .EE +.PP +This command is experimental: there aren\[aq]t many useful demos yet. .SH User interface commands .SS ui Runs hledger\-ui (if installed). @@ -9019,13 +9091,14 @@ Flags: \-\-round=TYPE how much rounding or padding should be done when displaying amounts ? none \- show original decimal digits, - as in journal + as in journal (default) soft \- just add or remove decimal zeros - to match precision (default) + to match precision hard \- round posting amounts to precision (can unbalance transactions) all \- also round cost amounts to precision (can unbalance transactions) + \-\-invert display all amounts with reversed sign \-\-new show only newer\-dated transactions added in each file since last run \-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 converted to cost. .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 on a previous run. This uses the same deduplication system as the \f[CR]import\f[R] @@ -9243,8 +9321,8 @@ Flags: postings before report start date) (default) \-\-invert display all amounts with reversed sign \-\-heading=YN show heading row above table: yes (default) or no - \-w \-\-width=N set output width (default: terminal width or - $COLUMNS). \-wN,M sets description width as well. + \-w \-\-width=N set output width (default: terminal width). \-wN,M + sets description width as well. \-\-align\-all guarantee alignment across all lines (slower) \-O \-\-output\-format=FMT select the output format. Supported formats: txt, html, csv, tsv, json. @@ -9364,8 +9442,8 @@ Flags: \-\-sort=FIELDS sort by: date, desc, account, amount, absamount, or a comma\-separated combination of these. For a descending sort, prefix with \-. (Default: date) - \-w \-\-width=N set output width (default: terminal width or - $COLUMNS). \-wN,M sets description width as well. + \-w \-\-width=N set output width (default: terminal width). \-wN,M + sets description width as well. \-\-align\-all guarantee alignment across all lines (slower) \-\-base\-url=URLPREFIX in html output, generate links to hledger\-web, 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 program exit code will be non\-zero. .SS Custom register output -register uses the full terminal width by default, except on windows. -You can override this by setting the \f[CR]COLUMNS\f[R] environment -variable (not a bash shell variable) or by using the -\f[CR]\-\-width\f[R]/\f[CR]\-w\f[R] option. +register normally uses the full terminal width (or 80 columns if it +can\[aq]t detect that). +You can override this with the \f[CR]\-\-width\f[R]/\f[CR]\-w\f[R] +option. .PP The description and account columns normally share the space equally (about half of (width \- 40) each). @@ -9524,10 +9602,7 @@ and some examples: .EX $ hledger reg # use terminal width (or 80 on windows) $ 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 $COLUMNS,40 # use terminal width, & description width 40 .EE .PP This command also supports the output destination and output format @@ -10003,10 +10078,10 @@ Flags: \-\-transpose switch rows and columns (use vertical time axis) \-\-layout=ARG how to lay out multi\-commodity amounts and the overall table: - \[aq]wide[,WIDTH]\[aq]: commodities on one line - \[aq]tall\[aq] : commodities on separate lines - \[aq]bare\[aq] : commodity symbols in one column - \[aq]tidy\[aq] : every attribute in its own column + \[aq]wide[,W]\[aq]: commodities on same line, up to W wide + \[aq]tall\[aq] : commodities on separate lines + \[aq]bare\[aq] : commodity symbols in a separate column + \[aq]tidy\[aq] : each data field in its own column \-\-base\-url=URLPREFIX in html output, generate links to hledger\-web, with this prefix. (Usually the base url shown by hledger\-web; can also be relative.) @@ -11354,26 +11429,24 @@ $ hledger activity \-\-quarterly .SS close (equity) .PP -\f[CR]close\f[R] generates several kinds of \[dq]closing\[dq] and/or -\[dq]opening\[dq] transactions, useful in certain situations, including -migrating balances to a new journal file, retaining earnings into -equity, consolidating balances, or viewing lots. +\f[CR]close\f[R] prints several kinds of \[dq]closing\[dq] and/or +\[dq]opening\[dq] transactions, useful in various situations: migrating +balances to a new journal file, retaining earnings into equity, +consolidating balances, viewing lot costs.. 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 -with how they look. +You can copy these into your journal file(s) when you are happy with how +they look. .IP .EX Flags: - \-\-migrate[=NEW] show closing and opening transactions, for Asset - and Liability accounts by default, tagged for easy - matching. The tag\[aq]s default value can be overridden - by providing NEW. - \-\-close[=NEW] (default) show a closing transaction - \-\-open[=NEW] show an opening transaction - \-\-assign[=NEW] show opening balance assignments - \-\-assert[=NEW] show closing balance assertions - \-\-retain[=NEW] show a retain earnings transaction, for Revenue - and Expense accounts by default + \-\-clopen[=TAGVAL] show closing and opening balances transactions, + for AL accounts by default + \-\-close[=TAGVAL] show just a closing balances transaction + \-\-open[=TAGVAL] show just an opening balances transaction + \-\-assert[=TAGVAL] show a balance assertions transaction + \-\-assign[=TAGVAL] show a balance assignments transaction + \-\-retain[=TAGVAL] show a retain earnings transaction, for RX + accounts by default \-x \-\-explicit show all amounts explicitly \-\-show\-costs show amounts with different costs separately \-\-interleaved show source and destination postings together @@ -11385,97 +11458,116 @@ Flags: \-\-round=TYPE how much rounding or padding should be done when displaying amounts ? none \- show original decimal digits, - as in journal + as in journal (default) soft \- just add or remove decimal zeros - to match precision (default) + to match precision hard \- round posting amounts to precision (can unbalance transactions) all \- also round cost amounts to precision (can unbalance transactions) .EE .PP -\f[CR]close\f[R] currently has six modes, selected by a single mode -flag: -.SS close \-\-migrate -This is the most common mode. -It prints a \[dq]closing balances\[dq] transaction that zeroes out all -asset and liability balances (by default), and an opposite \[dq]opening -balances\[dq] transaction that restores them again. -The balancing account will be \f[CR]equity:opening/closing balances\f[R] -(or another specified by \f[CR]\-\-close\-acct\f[R] or -\f[CR]\-\-open\-acct\f[R]). +\f[CR]close\f[R] has six modes, selected by choosing one of the mode +flags (\f[CR]\-\-close\f[R] is the default). +They all do much the same operation, but with different defaults, useful +in different situations. +.SS close \-\-clopen +This is useful if migrating balances to a new journal file at the start +of a new year. +It prints a \[dq]closing balances\[dq] transaction that zeroes out +account balances (Asset and Liability accounts, by default), and an +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 -This is useful when migrating balances to a new journal file at the -start of a new year. -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]. +and then move the opening transaction from the old file to the new file +(and probably also update your LEDGER_FILE environment variable). .PP -You can close a different set of accounts by providing a query. -Eg if you want to include equity, you can add -\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R] arguments. -(The balancing account is always excluded.) -Revenues and expenses usually are not migrated to a new file directly; -see \f[CR]\-\-retain\f[R] below. +Why might you do this ? +If your reports are fast, you may not need it. +But at some point you will probably want to partition your data by time, +for performance or data integrity or regulatory reasons. +A new file or set of files per year is common. +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 -The generated transactions will have a \f[CR]start:\f[R] tag, with its -value set to \f[CR]\-\-migrate\f[R]\[aq]s \f[CR]NEW\f[R] argument if -any, for easier matching or exclusion. -When \f[CR]NEW\f[R] is not specified, it will be inferred if possible by -incrementing a number (eg a year number) within the default -journal\[aq]s main file name. -The other modes behave similarly. +The balances will be transferred to and from +\f[CR]equity:opening/closing balances\f[R] by default. +You can override this by using \f[CR]\-\-close\-acct\f[R] and/or +\f[CR]\-\-open\-acct\f[R]. +.PP +You can select a different set of accounts to close/open by providing an +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 This prints just the closing balances transaction of -\f[CR]\-\-migrate\f[R]. -It is the default behaviour if you specify no mode flag. -Using the customisation options below, you can move balances from any -set of accounts to a different account. +\f[CR]\-\-clopen\f[R]. +It is the default if you don\[aq]t specify a mode. +.PP +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 This prints just the opening balances transaction of -\f[CR]\-\-migrate\f[R]. -It is similar to Ledger\[aq]s equity command. +\f[CR]\-\-clopen\f[R]. +(It is similar to Ledger\[aq]s equity command.) .SS close \-\-assert -This prints a \[dq]closing balances\[dq] transaction (with -\f[CR]balances:\f[R] tag), that just declares balance assertions for the -current balances without changing them. +This prints a transaction that asserts the account balances as they are +on the end date (and adds an \f[CR]assert:\f[R] tag). 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 -preceding closing balances transaction is not needed. +This prints a transaction that assigns the account balances as they are +on the end date (and adds an \[dq]assign:\[dq] tag). +Unlike balance assertions, assignments will post changes to balances as +needed to reach the specified amounts. .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. +This is another way to set starting balances when migrating to a new +file, and it will set them correctly even in the presence of earlier +files which do not have a closing balances transaction. +However, it can hide errors, and disturb the accounting equation, so +\f[CR]\-\-clopen\f[R] is usually recommended. .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]. +This is like \f[CR]\-\-close\f[R], but it closes Revenue and Expense +account balances by default. +They will be transferred to \f[CR]equity:retained earnings\f[R], or +another account specified with \f[CR]\-\-close\-acct\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.) +Revenues and expenses correspond to changes in equity. +They are categorised separately for reporting purposes, but +traditionally at the end of each accounting period, businesses +consolidate them into equity, This is called \[dq]retaining +earnings\[dq], or \[dq]closing the books\[dq]. .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. +In personal accounting, there\[aq]s not much reason to do this, and most +people don\[aq]t. +(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 In all modes, the following things can be overridden: .IP \[bu] 2 @@ -11577,7 +11669,7 @@ Close assets/liabilities on 2022\-12\-31 and re\-open them on 2023\-01\-01: .IP .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 opening transaction to the start of 2023.journal .EE @@ -11590,15 +11682,15 @@ $ hledger \-f 2022.journal bs not:desc:\[aq]closing balances\[aq] .EE .PP 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: .IP .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 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] -$ 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] +$ 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:clopen=2021 or not tag:clopen\[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:clopen=2021 or not tag:clopen\[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 .EE .SS More detailed close examples diff --git a/hledger/hledger.info b/hledger/hledger.info index 9dd7aac5e..32fc32b30 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1,4 +1,4 @@ -This is hledger.info, produced by makeinfo version 7.1.1 from stdin. +This is hledger.info, produced by makeinfo version 7.2 from stdin. INFO-DIR-SECTION User Applications START-INFO-DIR-ENTRY @@ -177,18 +177,23 @@ File: hledger.info, Node: Text encoding, Next: Data formats, Up: Input 2.1 Text encoding ================= -Data files containing non-ascii characters must use UTF-8 encoding. An -optional byte order mark (BOM) is allowed, at the beginning of the file -(only). +hledger input files containing non-ascii characters must use UTF-8 +encoding, with the exception of CSV (SSV, TSV..) files, which can be +read from other encodings (see 'encoding' CSV rule). - Also, your system should be configured with a locale that can decode -UTF-8 text. On some unix systems, you may need set the 'LANG' -environment variable, eg. You can read more about this in Unicode -characters, below. + In UTF-8 input files, an optional byte order mark (BOM) at the +beginning of the file is allowed. - On unix systems you can check a file's encoding with the 'file' -command. If you need to import from a UTF-16-encoded CSV file, say, you -can convert it to UTF-8 with the 'iconv' command. + Your system may need to be configured with a locale that understands +the input file's encoding. Eg on some unix systems, you may need set +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.  File: hledger.info, Node: Data formats, Next: Standard input, Prev: Text encoding, Up: Input @@ -908,12 +913,12 @@ File: hledger.info, Node: Shell completions, Prev: Config files, Up: Options 4.6 Shell completions ===================== -If you use the bash shell, you can optionally set up context-sensitive -autocompletions when you press TAB in a hledger command line. At a bash -shell prompt, try pressing 'hledger' (should list all -hledger commands) or 'hledger reg acct:' (should list your -top-level account names). If completions aren't working, or for more -details, see Install > Shell completions. +If you use the bash or zsh shells, you can optionally set up +context-sensitive autocompletion for hledger command lines. Try +pressing 'hledger' (should list all hledger commands) +or 'hledger reg acct:' (should list your top-level account +names). If completions aren't working, or for more details, see Install +> Shell completions.  File: hledger.info, Node: Output, Next: Environment, Prev: Options, Up: Top @@ -1006,12 +1011,9 @@ for viewing with a monospace font in a terminal. If your data contains unicode or wide characters, you'll need a terminal and font that render those correctly. (This can be challenging on MS Windows.) - Some reports ('register', 'aregister') will use the width indicated -by the 'COLUMNS' environment variable. If your shell and terminal are -working well, they will keep COLUMNS updated as you resize the window. -So register 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. + Some reports ('register', 'aregister') will normally use the full +window width. If this isn't working or you want to override it, you can +use the '-w'/'--width' option. Balance reports ('balance', 'balancesheet', 'incomestatement'...) use whatever width they need. Multi-period multi-currency reports can @@ -1064,10 +1066,13 @@ File: hledger.info, Node: Paging, Prev: Colour, Up: Text output In unix-like environments, when displaying large output (in any output format) in the terminal, hledger tries to use a pager when appropriate. -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' shows help, and 'q' quits. The home/end/page up/page down/cursor -keys, and mouse scrolling, may also work. +(You can disable this with the '--pager=no' option, perhaps in your +config file.) + + 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' shows help, and 'q' quits. The home/end/page up/page +down/cursor keys, and mouse scrolling, may also work. hledger will use the pager specified by the 'PAGER' environment variable, otherwise 'less' if available, otherwise 'more' if available. @@ -1084,9 +1089,8 @@ number of options to the 'LESS' variable to enable ANSI colour and a number of other conveniences. (At the time of writing: -chop-long-lines -hilite-unread -ignore-case -mouse -no-init -quit-at-eof -quit-if-one-screen -RAW-CONTROL-CHARS -shift=8 -squeeze-blank-lines --use-backslash -use-color ). If these don't work well, you can set your -preferred options in the 'HLEDGER_LESS' variable, which will be used -instead. +-use-backslash ). If these don't work well, you can set your preferred +options in the 'HLEDGER_LESS' variable, which will be used instead.  File: hledger.info, Node: HTML output, Next: CSV / TSV output, Prev: Text output, Up: Output format @@ -1303,7 +1307,7 @@ following will force dollar amounts to be displayed as shown: $ hledger print -c '$1.000,0' - 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. Its argument is as described in the commodity directive. @@ -1338,10 +1342,6 @@ File: hledger.info, Node: Environment, Next: PART 2 DATA FORMATS, Prev: Outpu 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' options hledger should use. (Otherwise, 'LESS' + custom options are used.) @@ -3076,7 +3076,7 @@ renaming it by an alias could prevent or alter that. matching accounts as you expect, try troubleshooting with the accounts command, eg something like: -$ hledger accounts --alias assets=bassetts type:a +$ hledger accounts --types -1 --alias assets=bassetts  File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal @@ -3128,7 +3128,7 @@ File: hledger.info, Node: Commodity directive syntax, Next: Commodity error ch A commodity directive is normally the word 'commodity' followed by a sample 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 1.000,00 EUR @@ -3951,32 +3951,30 @@ File: hledger.info, Node: Other cost/lot notations, Prev: Other Ledger directi 8.27.11 Other cost/lot notations -------------------------------- -A slight digression for Ledger and Beancount users. Ledger has a number -of cost/lot-related notations: +A slight digression for Ledger and Beancount users. + + *Ledger* has a number of cost/lot-related notations: * '@ UNITCOST' and '@@ TOTALCOST' * expresses a conversion rate, as in hledger - * when buying, also creates a lot than can be selected at + * when buying, also creates a lot that can be selected at selling time * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost) * like the above, but also means "this cost was exceptional, don't use it when inferring market prices". - Currently, hledger treats the above like '@' and '@@'; the -parentheses are ignored. - - * '{=FIXEDUNITCOST}' and '{{=FIXEDTOTALCOST}}' (fixed price) - * when buying, means "this cost is also the fixed price, don't + * '{=UNITCOST}' and '{{=TOTALCOST}}' (fixed price) + * when buying, means "this cost is also the fixed value, don't let it fluctuate in value reports" * '{UNITCOST}' and '{{TOTALCOST}}' (lot price) * can be used identically to '@ UNITCOST' and '@@ TOTALCOST', also creates a lot - * when selling, combined with '@ ...', specifies an investment - lot by its cost basis; does not check if that lot is present + * when selling, combined with '@ ...', selects an existing lot + by its cost basis. Does not check if that lot is present. - * and related: '[YYYY/MM/DD]' (lot date) + * '[YYYY/MM/DD]' (lot date) * when buying, attaches this acquisition date to the lot * when selling, selects a lot by its acquisition date @@ -3984,36 +3982,42 @@ parentheses are ignored. * when buying, attaches this note to the lot * when selling, selects a lot by its note - Currently, hledger accepts any or all of the above in any order after -the posting amount, but ignores them. (This can break transaction -balancing.) + Currently, hledger - For Beancount users, the notation and behaviour is different: + * accepts any or all of the above in any order after the posting + amount + * supports '@' and '@@' + * treats '(@)' and '(@@)' as synonyms for '@' and '@@' + * and ignores the rest. (This can break transaction balancing.) + + *Beancount* has simpler notation and different behaviour: * '@ UNITCOST' and '@@ TOTALCOST' * expresses a cost without creating a lot, as in hledger - * when buying (augmenting) or selling (reducing) a lot, combined - with '{...}': documents the cost/selling price (not used for - transaction balancing) + * when buying (acquiring) or selling (disposing of) a lot, and + combined with '{...}': is not used except to document the + cost/selling price * '{UNITCOST}' and '{{TOTALCOST}}' - * when buying (augmenting), expresses the cost for transaction - balancing, and also creates a lot with this cost basis - attached - * when selling (reducing), + * when buying, expresses the cost for transaction balancing, and + also creates a lot with this cost basis attached + * when selling, * selects a lot by its cost basis * raises an error if that lot is not present or can not be selected unambiguously (depending on booking method configured) * expresses the selling price for transaction balancing - Currently, hledger accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation -but ignores it. + * '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, "LABEL"}', + '{UNITCOST, YYYY-MM-DD, "LABEL"}' + * when selling, other combinations of date/cost/label, like the + above, are accepted for selecting the lot. - * variations: '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, - "LABEL"}', '{UNITCOST, YYYY-MM-DD, "LABEL"}' etc. + Currently, hledger - Currently, hledger rejects these. + * supports '@' and '@@' + * accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation, but ignores it + * and rejects the rest.  File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top @@ -4067,6 +4071,7 @@ https://github.com/simonmichael/hledger/tree/master/examples/csv. * CSV rules cheatsheet:: * source:: +* encoding:: * separator:: * skip:: * date-format:: @@ -4096,6 +4101,8 @@ The following kinds of rule can appear in the rules file, in any order. *'source'* optionally declare which file to read data from +*'encoding'* optionally declare which text encoding the + data has *'separator'* declare the field separator, instead of relying on file extension *'skip'* skip one or more header lines at start of file @@ -4126,7 +4133,7 @@ The following kinds of rule can appear in the rules file, in any order. evaluated.  -File: hledger.info, Node: source, Next: separator, Prev: CSV rules cheatsheet, Up: CSV +File: hledger.info, Node: source, Next: encoding, Prev: CSV rules cheatsheet, Up: CSV 9.2 'source' ============ @@ -4156,9 +4163,31 @@ source Checking1*.csv See also "Working with CSV > Reading files specified by rule".  -File: hledger.info, Node: separator, Next: skip, Prev: source, Up: CSV +File: hledger.info, Node: encoding, Next: separator, Prev: source, Up: CSV -9.3 'separator' +9.3 '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-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. + + +File: hledger.info, Node: separator, Next: skip, Prev: encoding, Up: CSV + +9.4 'separator' =============== You can use the 'separator' rule to read other kinds of @@ -4183,7 +4212,7 @@ inferred automatically, and you won't need this rule.  File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV -9.4 'skip' +9.5 'skip' ========== skip N @@ -4202,7 +4231,7 @@ required to be valid CSV.  File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV -9.5 'date-format' +9.6 'date-format' ================= date-format DATEFMT @@ -4231,7 +4260,7 @@ date-format %-m/%-d/%Y %l:%M %p some other junk  File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV -9.6 'timezone' +9.7 'timezone' ============== timezone TIMEZONE @@ -4260,7 +4289,7 @@ For others, use numeric format: +HHMM or -HHMM.  File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV -9.7 'newest-first' +9.8 'newest-first' ================== hledger tries to ensure that the generated transactions will be ordered @@ -4283,7 +4312,7 @@ newest-first  File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV -9.8 'intra-day-reversed' +9.9 'intra-day-reversed' ======================== If CSV records within a single day are ordered opposite to the overall @@ -4302,8 +4331,8 @@ intra-day-reversed  File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV -9.9 'decimal-mark' -================== +9.10 'decimal-mark' +=================== decimal-mark . @@ -4320,7 +4349,7 @@ misparsed numbers.  File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV -9.10 'fields' list +9.11 'fields' list ================== fields FIELDNAME1, FIELDNAME2, ... @@ -4365,7 +4394,7 @@ field (and generating a balance assertion).  File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV -9.11 Field assignment +9.12 Field assignment ===================== HLEDGERFIELD FIELDVALUE @@ -4399,7 +4428,7 @@ comment note: %somefield - %anotherfield, date: %1  File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV -9.12 Field names +9.13 Field names ================ Note the two kinds of field names mentioned here, and used only in @@ -4448,7 +4477,7 @@ happens when you assign values to them:  File: hledger.info, Node: date field, Next: date2 field, Up: Field names -9.12.1 date field +9.13.1 date field ----------------- Assigning to 'date' sets the transaction date. @@ -4456,7 +4485,7 @@ Assigning to 'date' sets the transaction date.  File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names -9.12.2 date2 field +9.13.2 date2 field ------------------ 'date2' sets the transaction's secondary date, if any. @@ -4464,7 +4493,7 @@ File: hledger.info, Node: date2 field, Next: status field, Prev: date field,  File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names -9.12.3 status field +9.13.3 status field ------------------- 'status' sets the transaction's status, if any. @@ -4472,7 +4501,7 @@ File: hledger.info, Node: status field, Next: code field, Prev: date2 field,  File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names -9.12.4 code field +9.13.4 code field ----------------- 'code' sets the transaction's code, if any. @@ -4480,7 +4509,7 @@ File: hledger.info, Node: code field, Next: description field, Prev: status f  File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names -9.12.5 description field +9.13.5 description field ------------------------ 'description' sets the transaction's description, if any. @@ -4488,7 +4517,7 @@ File: hledger.info, Node: description field, Next: comment field, Prev: code  File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names -9.12.6 comment field +9.13.6 comment field -------------------- 'comment' sets the transaction's comment, if any. @@ -4506,7 +4535,7 @@ or a year-less date, will be ignored.  File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names -9.12.7 account field +9.13.7 account field -------------------- Assigning to 'accountN', where N is 1 to 99, sets the account name of @@ -4524,7 +4553,7 @@ or "income:unknown").  File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names -9.12.8 amount field +9.13.8 amount field ------------------- There are several ways to set posting amounts from CSV, useful in @@ -4582,7 +4611,7 @@ different situations.  File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names -9.12.9 currency field +9.13.9 currency field --------------------- 'currency' sets a currency symbol, to be prepended to all postings' @@ -4595,7 +4624,7 @@ amount.  File: hledger.info, Node: balance field, Prev: currency field, Up: Field names -9.12.10 balance field +9.13.10 balance field --------------------- 'balanceN' sets a balance assertion amount (or if the posting amount is @@ -4613,7 +4642,7 @@ and currency.  File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV -9.13 'if' block +9.14 'if' block =============== Rules can be applied conditionally, depending on patterns in the CSV @@ -4668,7 +4697,7 @@ if ,,,,  File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV -9.14 Matchers +9.15 Matchers ============= There are two kinds of matcher: @@ -4720,22 +4749,26 @@ expressions" in the hledger manual  File: hledger.info, Node: Multiple matchers, Next: Match groups, Up: Matchers -9.14.1 Multiple matchers +9.15.1 Multiple matchers ------------------------ When an if block has multiple matchers, each on its own line, * By default they are OR'd (any of them can match). - * Matcher lines beginning with '&' (and optional space) are AND'ed + * Matcher lines beginning with '&' (or '&&', _since 1.42_) are AND'ed with the matcher above (all in the AND'ed group must match). + * Matcher lines beginning with '& !' (_since 1.41_, or '&& !', _since + 1.42_) are first negated and then AND'ed with the matcher above. - _(Since 1.41:)_ You can use a negated '!' matcher on a '&' line, -meaning AND NOT. + 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._  File: hledger.info, Node: Match groups, Prev: Multiple matchers, Up: Matchers -9.14.2 Match groups +9.15.2 Match groups ------------------- _Added in 1.32_ @@ -4763,7 +4796,7 @@ if %account1 liabilities:family:(expenses:.*)  File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV -9.15 'if' table +9.16 'if' table =============== "if tables" are an alternative to if blocks; they can express many @@ -4772,9 +4805,9 @@ this: if,HLEDGERFIELD1,HLEDGERFIELD2,... MATCHERA,VALUE1,VALUE2,... -MATCHERB,VALUE1,VALUE2,... -; Comment line that explains MATCHERC -MATCHERC,VALUE1,VALUE2,... +MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*) +; Comment line that explains MATCHERD +MATCHERD,VALUE1,VALUE2,... The first character after 'if' is taken to be this if table's field @@ -4790,10 +4823,10 @@ comment lines in the table body. The table must be terminated by an empty line (or end of file). 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 -line to the corresponding hledger fields; If multiple lines match, later -lines will override fields assigned by the earlier ones - just like the -sequence of 'if' blocks would behave. +lines with matchers; whenever a line with matchers succeeds, assign all +of the values on that line to the corresponding hledger fields; If +multiple lines match, later lines will override fields assigned by the +earlier ones - just like the sequence of 'if' blocks would behave. If table presented above is equivalent to this sequence of if blocks: @@ -4802,13 +4835,13 @@ if MATCHERA HLEDGERFIELD2 VALUE2 ... -if MATCHERB +if MATCHERB && MATCHERC HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 ... -; Comment line which explains MATCHERC -if MATCHERC +; Comment line which explains MATCHERD +if MATCHERD HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 ... @@ -4824,7 +4857,7 @@ atm transaction fee,expenses:business:banking,deductible? check it  File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV -9.16 'balance-type' +9.17 'balance-type' =================== Balance assertions generated by assigning to balanceN are of the simple @@ -4847,7 +4880,7 @@ balance-type ==*  File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV -9.17 'include' +9.18 'include' ============== include RULESFILE @@ -4870,7 +4903,7 @@ include categorisation.rules  File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV -9.18 Working with CSV +9.19 Working with CSV ===================== Some tips: @@ -4896,7 +4929,7 @@ Some tips:  File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV -9.18.1 Rapid feedback +9.19.1 Rapid feedback --------------------- It's a good idea to get rapid feedback while creating/troubleshooting @@ -4912,7 +4945,7 @@ output.  File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV -9.18.2 Valid CSV +9.19.2 Valid CSV ---------------- Note that hledger will only accept valid CSV conforming to RFC 4180, and @@ -4933,7 +4966,7 @@ permissive CSV parser like python's csv lib.  File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV -9.18.3 File Extension +9.19.3 File Extension --------------------- To help hledger choose the CSV file reader and show the right error @@ -4953,7 +4986,7 @@ rule if needed.  File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV -9.18.4 Reading CSV from standard input +9.19.4 Reading CSV from standard input -------------------------------------- You'll need the file format prefix when reading CSV from stdin also, @@ -4964,7 +4997,7 @@ $ cat foo.dat | hledger -f ssv:- print  File: hledger.info, Node: Reading multiple CSV files, Next: Reading files specified by rule, Prev: Reading CSV from standard input, Up: Working with CSV -9.18.5 Reading multiple CSV files +9.19.5 Reading multiple CSV files --------------------------------- If you use multiple '-f' options to read multiple CSV files at once, @@ -4975,7 +5008,7 @@ will be used for all the CSV files.  File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV -9.18.6 Reading files specified by rule +9.19.6 Reading files specified by rule -------------------------------------- Instead of specifying a CSV file in the command line, you can specify a @@ -5004,7 +5037,7 @@ most recent.  File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading files specified by rule, Up: Working with CSV -9.18.7 Valid transactions +9.19.7 Valid transactions ------------------------- After reading a CSV file, hledger post-processes and validates the @@ -5023,7 +5056,7 @@ $ hledger -f file.csv print | hledger -f- print  File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV -9.18.8 Deduplicating, importing +9.19.8 Deduplicating, importing ------------------------------- When you download a CSV file periodically, eg to get your latest bank @@ -5053,7 +5086,7 @@ CSV data. See:  File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV -9.18.9 Setting amounts +9.19.9 Setting amounts ---------------------- Continuing from amount field above, here are more tips for @@ -5120,7 +5153,7 @@ amount-setting:  File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV -9.18.10 Amount signs +9.19.10 Amount signs -------------------- There is some special handling making it easier to parse and to reverse @@ -5150,7 +5183,7 @@ its absolute value, ie discard its sign.  File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV -9.18.11 Setting currency/commodity +9.19.11 Setting currency/commodity ---------------------------------- If the currency/commodity symbol is included in the CSV's amount @@ -5198,7 +5231,7 @@ that would trigger the prepending effect, which we don't want here.  File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV -9.18.12 Amount decimal places +9.19.12 Amount decimal places ----------------------------- When you are reading CSV data, eg with a command like 'hledger -f @@ -5227,7 +5260,7 @@ want, add a 'commodity' directive to specify them.  File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV -9.18.13 Referencing other fields +9.19.13 Referencing other fields -------------------------------- In field assignments, you can interpolate only CSV fields, not hledger @@ -5264,7 +5297,7 @@ if something  File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV -9.18.14 How CSV rules are evaluated +9.19.14 How CSV rules are evaluated ----------------------------------- Here's how to think of CSV rules being evaluated (if you really need @@ -5305,7 +5338,7 @@ command the user specified.  File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV -9.18.15 Well factored rules +9.19.15 Well factored rules --------------------------- Some things than can help reduce duplication and complexity in rules @@ -5321,7 +5354,7 @@ files:  File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV -9.19 CSV rules examples +9.20 CSV rules examples ======================= * Menu: @@ -5334,7 +5367,7 @@ File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV  File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples -9.19.1 Bank of Ireland +9.20.1 Bank of Ireland ---------------------- Here's a CSV with two amount fields (Debit and Credit), and a balance @@ -5387,7 +5420,7 @@ imported into a journal file.  File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples -9.19.2 Coinbase +9.20.2 Coinbase --------------- A simple example with some CSV from Coinbase. The spot price is @@ -5414,7 +5447,7 @@ $ hledger print -f coinbase.csv  File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples -9.19.3 Amazon +9.20.3 Amazon ------------- Here we convert amazon.com order history, and use an if block to @@ -5472,7 +5505,7 @@ $ hledger -f amazon-orders.csv print  File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples -9.19.4 Paypal +9.20.4 Paypal ------------- Here's a real-world rules file for (customised) Paypal CSV, with some @@ -6681,18 +6714,30 @@ File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up 16 Pivoting *********** -Normally, hledger groups and sums amounts within each account. The -'--pivot FIELD' option substitutes some other transaction field for -account names, causing amounts to be grouped and summed by that field's -value instead. FIELD can be any of the transaction fields 'acct', -'status', '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. +Normally, hledger groups amounts and displays their totals by account +(name). With '--pivot PIVOTEXPR', some other field's (or multiple +fields') value is used as a synthetic account name, causing different +grouping and display. PIVOTEXPR can be - Some examples: + * any of these standard transaction or posting fields (their value is + substituted): 'status', 'code', 'desc', 'payee', 'note', 'acct', + 'comm'/'cur', 'amt', 'cost' + * or a tag name + * or any combination of these, colon-separated. + + Some special cases: + + * Colons appearing in PIVOTEXPR or in a pivoted tag value will + generate account hierarchy. + * When pivoting a posting has multiple values for a tag, the pivoted + value of that tag will be the first value. + * 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 assets:bank account 2 EUR @@ -6729,7 +6774,7 @@ $ hledger balance --pivot member acct:. -------------------- -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 -2 EUR Lifetime:John Doe @@ -7137,9 +7182,9 @@ File: hledger.info, Node: Cost reporting, Next: Value reporting, Prev: Amount In some transactions - for example a currency conversion, or a purchase or sale of stock - one commodity is exchanged for another. In these transactions there is a conversion rate, also called the cost (when -buying) or selling price (when selling). In hledger docs we just say -"cost", for convenience; feel free to mentally translate to "conversion -rate" or "selling price" if helpful. +buying) or selling price (when selling). (In hledger docs we just say +"cost" generically for convenience.) With the '-B/--cost' flag, hledger +can show amounts "at cost", converted to the cost's commodity. * Menu: @@ -7394,12 +7439,14 @@ File: hledger.info, Node: Value reporting, Next: PART 4 COMMANDS, Prev: Cost 22 Value reporting ****************** -Instead of reporting amounts in their original commodity, hledger can -convert them to cost/sale amount (using the conversion rate recorded in -the transaction), and/or to market value (using some market price on a -certain date). This is controlled by the '--value=TYPE[,COMMODITY]' -option, which will be described below. We also provide the simpler '-V' -and '-X COMMODITY' options, and often one of these is all you need: +hledger can also show amounts "at market value", converted to some other +commodity using the market price or conversion rate on a certain date. + + This is controlled by the '--value=TYPE[,COMMODITY]' option. We also +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. * Menu: @@ -8095,6 +8142,8 @@ $ hledger demo # list available demos $ hledger demo 1 # play the first demo at default speed (2x) $ hledger demo install -s4 # play the "install" demo at 4x speed + This command is experimental: there aren't many useful demos yet. +  File: hledger.info, Node: User interface commands, Next: Data entry commands, Prev: Help commands, Up: Top @@ -8816,13 +8865,14 @@ Flags: --round=TYPE how much rounding or padding should be done when displaying amounts ? none - show original decimal digits, - as in journal + as in journal (default) soft - just add or remove decimal zeros - to match precision (default) + to match precision hard - round posting amounts to precision (can unbalance transactions) all - also round cost amounts to precision (can unbalance transactions) + --invert display all amounts with reversed sign --new show only newer-dated transactions added in each file since last run -m --match=DESC fuzzy search for one recent transaction with @@ -8950,6 +9000,10 @@ File: hledger.info, Node: print other features, Next: print output format, Pr 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 run. This uses the same deduplication system as the 'import' command. (See import's docs for details.) @@ -9045,8 +9099,8 @@ Flags: postings before report start date) (default) --invert display all amounts with reversed sign --heading=YN show heading row above table: yes (default) or no - -w --width=N set output width (default: terminal width or - $COLUMNS). -wN,M sets description width as well. + -w --width=N set output width (default: terminal width). -wN,M + sets description width as well. --align-all guarantee alignment across all lines (slower) -O --output-format=FMT select the output format. Supported formats: txt, html, csv, tsv, json. @@ -9168,8 +9222,8 @@ Flags: --sort=FIELDS sort by: date, desc, account, amount, absamount, or a comma-separated combination of these. For a descending sort, prefix with -. (Default: date) - -w --width=N set output width (default: terminal width or - $COLUMNS). -wN,M sets description width as well. + -w --width=N set output width (default: terminal width). -wN,M + sets description width as well. --align-all guarantee alignment across all lines (slower) --base-url=URLPREFIX in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by @@ -9293,9 +9347,9 @@ File: hledger.info, Node: Custom register output, Up: register 28.3.1 Custom register output ----------------------------- -register uses the full terminal width by default, except on windows. -You can override this by setting the 'COLUMNS' environment variable (not -a bash shell variable) or by using the '--width'/'-w' option. +register normally uses the full terminal width (or 80 columns if it +can't detect that). You can override this with the '--width'/'-w' +option. The description and account columns normally share the space equally (about half of (width - 40) each). You can adjust this by adding a @@ -9310,10 +9364,7 @@ DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA $ hledger reg # use terminal width (or 80 on windows) $ 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 $COLUMNS,40 # use terminal width, & description width 40 This command also supports the output destination and output format options The output formats supported are 'txt', 'csv', 'tsv' (_Added in @@ -9793,10 +9844,10 @@ Flags: --transpose switch rows and columns (use vertical time axis) --layout=ARG how to lay out multi-commodity amounts and the overall table: - 'wide[,WIDTH]': commodities on one line - 'tall' : commodities on separate lines - 'bare' : commodity symbols in one column - 'tidy' : every attribute in its own column + 'wide[,W]': commodities on same line, up to W wide + 'tall' : commodities on separate lines + 'bare' : commodity symbols in a separate column + 'tidy' : each data field in its own column --base-url=URLPREFIX in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by hledger-web; can also be relative.) @@ -11095,24 +11146,22 @@ File: hledger.info, Node: close, Next: rewrite, Up: Data generation commands (equity) - 'close' generates several kinds of "closing" and/or "opening" -transactions, useful in certain situations, including migrating balances -to a new journal file, retaining earnings into equity, consolidating -balances, or viewing lots. Like 'print', it prints valid journal -entries. You can append or copy these to your journal file(s) when you -are happy with how they look. + 'close' prints several kinds of "closing" and/or "opening" +transactions, useful in various situations: migrating balances to a new +journal file, retaining earnings into equity, consolidating balances, +viewing lot costs.. Like 'print', it prints valid journal entries. You +can copy these into your journal file(s) when you are happy with how +they look. Flags: - --migrate[=NEW] show closing and opening transactions, for Asset - and Liability accounts by default, tagged for easy - matching. The tag's default value can be overridden - by providing NEW. - --close[=NEW] (default) show a closing transaction - --open[=NEW] show an opening transaction - --assign[=NEW] show opening balance assignments - --assert[=NEW] show closing balance assertions - --retain[=NEW] show a retain earnings transaction, for Revenue - and Expense accounts by default + --clopen[=TAGVAL] show closing and opening balances transactions, + for AL accounts by default + --close[=TAGVAL] show just a closing balances transaction + --open[=TAGVAL] show just an opening balances transaction + --assert[=TAGVAL] show a balance assertions transaction + --assign[=TAGVAL] show a balance assignments transaction + --retain[=TAGVAL] show a retain earnings transaction, for RX + accounts by default -x --explicit show all amounts explicitly --show-costs show amounts with different costs separately --interleaved show source and destination postings together @@ -11124,19 +11173,21 @@ Flags: --round=TYPE how much rounding or padding should be done when displaying amounts ? none - show original decimal digits, - as in journal + as in journal (default) soft - just add or remove decimal zeros - to match precision (default) + to match precision hard - round posting amounts to precision (can unbalance transactions) all - also round cost amounts to precision (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. * Menu: -* close --migrate:: +* close --clopen:: * close --close:: * close --open:: * close --assert:: @@ -11147,50 +11198,64 @@ Flags: * close examples::  -File: hledger.info, Node: close --migrate, Next: close --close, Up: close +File: hledger.info, Node: close --clopen, Next: close --close, Up: close -31.1.1 close -migrate ---------------------- +31.1.1 close -clopen +-------------------- -This is the most common mode. It prints a "closing balances" -transaction that zeroes out all asset and liability balances (by -default), and an opposite "opening balances" transaction that restores -them again. The balancing account will be 'equity:opening/closing -balances' (or another specified by '--close-acct' or '--open-acct'). +This is useful if migrating balances to a new journal file at the start +of a new year. It prints a "closing balances" transaction that zeroes +out account balances (Asset and Liability accounts, by default), and an +opposite "opening balances" transaction that restores them again. +Typically, you would run - This is useful when migrating balances to a new journal file at the -start of a new year. Essentially, you run 'hledger close ---migrate=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 -balances correct when you use both old and new files together, by -cancelling out the following opening transaction and preventing buildup -of duplicated opening balances. Think of the closing/opening pair as -"moving the balances into the next file". +hledger close --clopen -e NEWYEAR >> $LEDGER_FILE - You can close a different set of accounts by providing a query. Eg -if you want to include equity, you can add 'assets liabilities equity' -or 'type:ALE' arguments. (The balancing account is always excluded.) -Revenues and expenses usually are not migrated to a new file directly; -see '--retain' below. + and then move the opening transaction from the old file to the new +file (and probably also update your LEDGER_FILE environment variable). - The generated transactions will have a 'start:' tag, with its value -set to '--migrate''s 'NEW' argument if any, for easier matching or -exclusion. When 'NEW' is not specified, it will be inferred if possible -by incrementing a number (eg a year number) within the default journal's -main file name. The other modes behave similarly. + Why might you do this ? If your reports are fast, you may not need +it. But at some point you will probably want to partition your data by +time, for performance or data integrity or regulatory reasons. A new +file or set of files per year is common. Then, having each file/fileset +"bookended" 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. + + 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 +journal'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'.  -File: hledger.info, Node: close --close, Next: close --open, Prev: close --migrate, Up: close +File: hledger.info, Node: close --close, Next: close --open, Prev: close --clopen, Up: close 31.1.2 close -close ------------------- -This prints just the closing balances transaction of '--migrate'. It is -the default behaviour if you specify no mode flag. Using the -customisation options below, you can move balances from any set of -accounts to a different account. +This prints just the closing balances transaction of '--clopen'. It is +the default if you don't specify a mode. + + 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.)  File: hledger.info, Node: close --open, Next: close --assert, Prev: close --close, Up: close @@ -11198,8 +11263,8 @@ File: hledger.info, Node: close --open, Next: close --assert, Prev: close --c 31.1.3 close -open ------------------ -This prints just the opening balances transaction of '--migrate'. It is -similar to Ledger's equity command. +This prints just the opening balances transaction of '--clopen'. (It is +similar to Ledger's equity command.)  File: hledger.info, Node: close --assert, Next: close --assign, Prev: close --open, Up: close @@ -11207,10 +11272,9 @@ File: hledger.info, Node: close --assert, Next: close --assign, Prev: close - 31.1.4 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. +This prints a transaction that asserts the account balances as they are +on the end date (and adds an 'assert:' tag). It could be useful as +documention and to guard against changes.  File: hledger.info, Node: close --assign, Next: close --retain, Prev: close --assert, Up: close @@ -11218,16 +11282,16 @@ File: hledger.info, Node: close --assign, Next: close --retain, Prev: close - 31.1.5 close -assign -------------------- -This prints an "opening balances" transaction that restores the account -balances using balance assignments. Balance assignments work regardless -of any previous balance, so a preceding closing balances transaction is -not needed. +This prints a transaction that assigns the account balances as they are +on the end date (and adds an "assign:" tag). Unlike balance assertions, +assignments will post changes to balances as needed to reach the +specified amounts. - However, omitting the closing balances transaction would unbalance -equity. This is relatively harmless for personal reports, but it -disturbs the accounting equation, removing a source of error detection. -So '--migrate' is generally the best way to set to set balances in new -files, for now. + This is another way to set starting balances when migrating to a new +file, and it will set them correctly even in the presence of earlier +files which do not have a closing balances transaction. However, it can +hide errors, and disturb the accounting equation, so '--clopen' is +usually recommended.  File: hledger.info, Node: close --retain, Next: close customisation, Prev: close --assign, Up: close @@ -11235,19 +11299,19 @@ File: hledger.info, Node: close --retain, Next: close customisation, Prev: cl 31.1.6 close -retain -------------------- -This is like '--close' with different defaults: it prints a "retain -earnings" transaction (with 'retain:' tag), that transfers revenue and -expense balances to 'equity:retained earnings'. +This is like '--close', but it closes Revenue and Expense account +balances by default. They will be transferred to 'equity:retained +earnings', or another account specified with '--close-acct'. - This is a different kind of closing, called "retaining earnings" or -"closing the books"; it is traditionally performed by businesses at the -end of each accounting period, to consolidate revenues and expenses into -the main equity balance. ("Revenues" and "expenses" are actually equity -by another name, kept separate temporarily for reporting purposes.) + Revenues and expenses correspond to changes in equity. They are +categorised separately for reporting purposes, but traditionally at the +end of each accounting period, businesses consolidate them into equity, +This is called "retaining earnings", or "closing the books". - 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. + In personal accounting, there's not much reason to do this, and most +people don't. (One reason to do it is to help the 'balancesheetequity' +report show a zero total, demonstrating that the accounting equation +(A-L=E) is satisfied.)  File: hledger.info, Node: close customisation, Next: close and balance assertions, Prev: close --retain, Up: close @@ -11364,7 +11428,7 @@ File: hledger.info, Node: Migrate balances to a new file, Next: More detailed 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 opening transaction to the start of 2023.journal @@ -11374,15 +11438,15 @@ closing balances transaction: $ hledger -f 2022.journal bs not:desc:'closing balances' For more flexibility, it helps to tag closing and opening -transactions with eg 'start:NEWYEAR', then you can ensure correct +transactions with eg 'clopen:NEWYEAR', then you can ensure correct balances by excluding 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 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 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:clopen=2021 or not tag:clopen' +$ 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:clopen=2021 or not tag:clopen' +$ 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  @@ -12316,382 +12380,383 @@ See hledger and Ledger for full details.  Tag Table: -Node: Top210 -Node: PART 1 USER INTERFACE4365 -Node: Input4504 -Node: Text encoding5596 -Node: Data formats6276 -Node: Standard input8000 -Node: Multiple files8389 -Node: Strict mode9126 -Node: Commands9960 -Node: Add-on commands11146 -Node: Options12364 -Node: Special characters18938 -Node: Escaping shell special characters19888 -Node: Escaping on Windows21132 -Node: Escaping regular expression special characters21865 -Node: Escaping add-on arguments22852 -Node: Escaping in other situations23881 -Node: Using a wild card24840 -Node: Unicode characters25219 -Node: Regular expressions26883 -Node: hledger's regular expressions30142 -Node: Argument files31783 -Node: Config files32486 -Node: Shell completions35639 -Node: Output36164 -Node: Output destination36355 -Node: Output format36913 -Node: Text output38699 -Node: Box-drawing characters39896 -Node: Colour40396 -Node: Paging40982 -Node: HTML output42433 -Node: CSV / TSV output42887 -Node: FODS output43141 -Node: Beancount output43945 -Node: Beancount account names45400 -Node: Beancount commodity names45941 -Node: Beancount virtual postings46588 -Node: Beancount metadata46904 -Node: Beancount costs47684 -Node: Beancount operating currency48100 -Node: SQL output48550 -Node: JSON output49341 -Node: Commodity styles50158 -Node: Debug output51042 -Node: Environment51874 -Node: PART 2 DATA FORMATS52723 -Node: Journal52866 -Node: Journal cheatsheet55344 -Node: Comments61558 -Node: Transactions62502 -Node: Dates63639 -Node: Simple dates63791 -Node: Posting dates64407 -Node: Status65494 -Node: Code67260 -Node: Description67595 -Node: Payee and note68282 -Node: Transaction comments69373 -Node: Postings69889 -Node: Debits and credits71052 -Node: The two space delimiter71662 -Node: Account names72227 -Node: Amounts74031 -Node: Decimal marks75060 -Node: Digit group marks76164 -Node: Commodity76799 -Node: Costs77916 -Node: Balance assertions80168 -Node: Assertions and ordering81431 -Node: Assertions and multiple included files82159 -Node: Assertions and multiple -f files82919 -Node: Assertions and costs83561 -Node: Assertions and commodities84211 -Node: Assertions and subaccounts85870 -Node: Assertions and status86530 -Node: Assertions and virtual postings86950 -Node: Assertions and auto postings87315 -Node: Assertions and precision88190 -Node: Posting comments88641 -Node: Transaction balancing89181 -Node: Tags91183 -Node: Querying with tags92477 -Node: Displaying tags93276 -Node: When to use tags ?93672 -Node: Tag names94336 -Node: Special tags94889 -Node: Directives96454 -Node: Directives and multiple files97911 -Node: Directive effects98856 -Node: account directive102012 -Node: Account comments103462 -Node: Account error checking104121 -Node: Account display order105658 -Node: Account types106856 -Node: alias directive110630 -Node: Basic aliases111841 -Node: Regex aliases112716 -Node: Combining aliases113763 -Node: Aliases and multiple files115217 -Node: end aliases directive116000 -Node: Aliases can generate bad account names116368 -Node: Aliases and account types117201 -Node: commodity directive118089 -Node: Commodity directive syntax119676 -Node: Commodity error checking121312 -Node: decimal-mark directive121787 -Node: include directive122366 -Node: P directive123442 -Node: payee directive124476 -Node: tag directive125098 -Node: Periodic transactions125710 -Node: Periodic rule syntax127864 -Node: Periodic rules and relative dates128687 -Node: Two spaces between period expression and description!129464 -Node: Auto postings130425 -Node: Auto postings and multiple files133585 -Node: Auto postings and dates133990 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions134431 -Node: Auto posting tags135277 -Node: Auto postings on forecast transactions only136172 -Node: Other syntax136642 -Node: Balance assignments137414 -Node: Balance assignments and costs138942 -Node: Balance assignments and multiple files139364 -Node: Bracketed posting dates139787 -Node: D directive140485 -Node: apply account directive142258 -Node: Y directive143125 -Node: Secondary dates144113 -Node: Star comments145598 -Node: Valuation expressions146290 -Node: Virtual postings146589 -Node: Other Ledger directives148213 -Node: Other cost/lot notations148975 -Node: CSV151737 -Node: CSV rules cheatsheet153820 -Node: source155745 -Node: separator156746 -Node: skip157397 -Node: date-format158047 -Node: timezone158890 -Node: newest-first160016 -Node: intra-day-reversed160729 -Node: decimal-mark161329 -Node: fields list161807 -Node: Field assignment163615 -Node: Field names164834 -Node: date field166166 -Node: date2 field166330 -Node: status field166525 -Node: code field166715 -Node: description field166903 -Node: comment field167120 -Node: account field167677 -Node: amount field168395 -Node: currency field171234 -Node: balance field171642 -Node: if block172165 -Node: Matchers173692 -Node: Multiple matchers175682 -Node: Match groups176158 -Node: if table177051 -Node: balance-type179052 -Node: include179879 -Node: Working with CSV180448 -Node: Rapid feedback181000 -Node: Valid CSV181583 -Node: File Extension182459 -Node: Reading CSV from standard input183194 -Node: Reading multiple CSV files183580 -Node: Reading files specified by rule184056 -Node: Valid transactions185453 -Node: Deduplicating importing186278 -Node: Setting amounts187507 -Node: Amount signs190034 -Node: Setting currency/commodity191099 -Node: Amount decimal places192475 -Node: Referencing other fields193732 -Node: How CSV rules are evaluated194840 -Node: Well factored rules196508 -Node: CSV rules examples196998 -Node: Bank of Ireland197196 -Node: Coinbase198793 -Node: Amazon199976 -Node: Paypal201818 -Node: Timeclock209568 -Node: Timedot211837 -Node: Timedot examples215314 -Node: PART 3 REPORTING CONCEPTS217591 -Node: Time periods217755 -Node: Report start & end date218028 -Node: Smart dates219504 -Node: Report intervals221447 -Node: Date adjustments222021 -Node: Start date adjustment222241 -Node: End date adjustment223144 -Node: Period headings223889 -Node: Period expressions224822 -Node: Period expressions with a report interval226727 -Node: More complex report intervals227175 -Node: Multiple weekday intervals229291 -Node: Depth230302 -Node: Queries232137 -Node: Query types233835 -Node: acct query234252 -Node: amt query234563 -Node: code query235180 -Node: cur query235375 -Node: desc query235981 -Node: date query236164 -Node: date2 query236560 -Node: depth query236851 -Node: expr query237187 -Node: not query237568 -Node: note query237908 -Node: payee query238174 -Node: real query238455 -Node: status query238660 -Node: type query238900 -Node: tag query239433 -Node: Combining query terms240062 -Node: Queries and command options241802 -Node: Queries and account aliases242256 -Node: Queries and valuation242581 -Node: Pivoting242943 -Node: Generating data244834 -Node: Forecasting246634 -Node: --forecast247290 -Node: Inspecting forecast transactions248391 -Node: Forecast reports249724 -Node: Forecast tags250833 -Node: Forecast period in detail251453 -Node: Forecast troubleshooting252541 -Node: Budgeting253612 -Node: Amount formatting254172 -Node: Commodity display style254416 -Node: Rounding256257 -Node: Trailing decimal marks256862 -Node: Amount parseability257795 -Node: Cost reporting259376 -Node: Recording costs260179 -Node: Reporting at cost261906 -Node: Equity conversion postings262671 -Node: Inferring equity conversion postings265316 -Node: Combining costs and equity conversion postings266458 -Node: Requirements for detecting equity conversion postings267683 -Node: Infer cost and equity by default ?269205 -Node: Value reporting269642 -Node: -V Value270523 -Node: -X Value in specified commodity270850 -Node: Valuation date271200 -Node: Finding market price272160 -Node: --infer-market-prices market prices from transactions273540 -Node: Valuation commodity276584 -Node: --value Flexible valuation278017 -Node: Valuation examples279860 -Node: Interaction of valuation and queries281992 -Node: Effect of valuation on reports282709 -Node: PART 4 COMMANDS290607 -Node: Help commands292823 -Node: help292996 -Node: demo294701 -Node: User interface commands295848 -Node: ui296042 -Node: web296167 -Node: Data entry commands296295 -Node: add296493 -Node: import298948 -Node: Import preview299982 -Node: Overlap detection300930 -Node: First import303816 -Node: Importing balance assignments305011 -Node: Import and commodity styles306066 -Node: Import special cases306504 -Node: Basic report commands307839 -Node: accounts308140 -Node: codes311013 -Node: commodities312035 -Node: descriptions312279 -Node: files312746 -Node: notes313043 -Node: payees313555 -Node: prices314339 -Node: stats315231 -Node: tags316972 -Node: Standard report commands318279 -Node: print318584 -Node: print explicitness321258 -Node: print amount style322178 -Node: print parseability323416 -Node: print other features324335 -Node: print output format325033 -Node: aregister328318 -Node: aregister and posting dates332789 -Node: register333690 -Node: Custom register output340877 -Node: balancesheet342353 -Node: balancesheetequity347123 -Node: cashflow352263 -Node: incomestatement356825 -Node: Advanced report commands361423 -Node: balance361631 -Node: balance features366801 -Node: Simple balance report368877 -Node: Balance report line format370687 -Node: Filtered balance report373047 -Node: List or tree mode373566 -Node: Depth limiting375079 -Node: Dropping top-level accounts375846 -Node: Showing declared accounts376356 -Node: Sorting by amount377086 -Node: Percentages377923 -Node: Multi-period balance report378630 -Node: Balance change end balance381382 -Node: Balance report types383019 -Node: Calculation type383698 -Node: Accumulation type384402 -Node: Valuation type385503 -Node: Combining balance report types386692 -Node: Budget report388724 -Node: Using the budget report391029 -Node: Budget date surprises393305 -Node: Selecting budget goals394669 -Node: Budgeting vs forecasting395617 -Node: Balance report layout397294 -Node: Wide layout398499 -Node: Tall layout400904 -Node: Bare layout402210 -Node: Tidy layout404274 -Node: Balance report output405818 -Node: Some useful balance reports406633 -Node: roi407893 -Node: Spaces and special characters in --inv and --pnl410140 -Node: Semantics of --inv and --pnl410866 -Node: IRR and TWR explained412953 -Node: Chart commands416364 -Node: activity416545 -Node: Data generation commands417042 -Node: close417248 -Node: close --migrate419840 -Node: close --close421604 -Node: close --open421982 -Node: close --assert422231 -Node: close --assign422596 -Node: close --retain423268 -Node: close customisation424164 -Node: close and balance assertions425808 -Node: close examples427330 -Node: Retain earnings427567 -Node: Migrate balances to a new file428070 -Node: More detailed close examples429422 -Node: rewrite429644 -Node: Re-write rules in a file432216 -Node: Diff output format433526 -Node: rewrite vs print --auto434799 -Node: Maintenance commands435513 -Node: check435722 -Node: Basic checks436804 -Node: Strict checks437757 -Node: Other checks438632 -Node: Custom checks440487 -Node: diff440942 -Node: test442149 -Node: PART 5 COMMON TASKS443021 -Node: Getting help443254 -Node: Constructing command lines444163 -Node: Starting a journal file445001 -Node: Setting LEDGER_FILE446385 -Node: Setting opening balances447643 -Node: Recording transactions450965 -Node: Reconciling451690 -Node: Reporting454079 -Node: Migrating to a new file458193 -Node: BUGS458642 -Node: Troubleshooting459607 +Node: Top208 +Node: PART 1 USER INTERFACE4363 +Node: Input4502 +Node: Text encoding5594 +Node: Data formats6451 +Node: Standard input8175 +Node: Multiple files8564 +Node: Strict mode9301 +Node: Commands10135 +Node: Add-on commands11321 +Node: Options12539 +Node: Special characters19113 +Node: Escaping shell special characters20063 +Node: Escaping on Windows21307 +Node: Escaping regular expression special characters22040 +Node: Escaping add-on arguments23027 +Node: Escaping in other situations24056 +Node: Using a wild card25015 +Node: Unicode characters25394 +Node: Regular expressions27058 +Node: hledger's regular expressions30317 +Node: Argument files31958 +Node: Config files32661 +Node: Shell completions35814 +Node: Output36303 +Node: Output destination36494 +Node: Output format37052 +Node: Text output38838 +Node: Box-drawing characters39817 +Node: Colour40317 +Node: Paging40903 +Node: HTML output42429 +Node: CSV / TSV output42883 +Node: FODS output43137 +Node: Beancount output43941 +Node: Beancount account names45396 +Node: Beancount commodity names45937 +Node: Beancount virtual postings46584 +Node: Beancount metadata46900 +Node: Beancount costs47680 +Node: Beancount operating currency48096 +Node: SQL output48546 +Node: JSON output49337 +Node: Commodity styles50154 +Node: Debug output51041 +Node: Environment51873 +Node: PART 2 DATA FORMATS52530 +Node: Journal52673 +Node: Journal cheatsheet55151 +Node: Comments61365 +Node: Transactions62309 +Node: Dates63446 +Node: Simple dates63598 +Node: Posting dates64214 +Node: Status65301 +Node: Code67067 +Node: Description67402 +Node: Payee and note68089 +Node: Transaction comments69180 +Node: Postings69696 +Node: Debits and credits70859 +Node: The two space delimiter71469 +Node: Account names72034 +Node: Amounts73838 +Node: Decimal marks74867 +Node: Digit group marks75971 +Node: Commodity76606 +Node: Costs77723 +Node: Balance assertions79975 +Node: Assertions and ordering81238 +Node: Assertions and multiple included files81966 +Node: Assertions and multiple -f files82726 +Node: Assertions and costs83368 +Node: Assertions and commodities84018 +Node: Assertions and subaccounts85677 +Node: Assertions and status86337 +Node: Assertions and virtual postings86757 +Node: Assertions and auto postings87122 +Node: Assertions and precision87997 +Node: Posting comments88448 +Node: Transaction balancing88988 +Node: Tags90990 +Node: Querying with tags92284 +Node: Displaying tags93083 +Node: When to use tags ?93479 +Node: Tag names94143 +Node: Special tags94696 +Node: Directives96261 +Node: Directives and multiple files97718 +Node: Directive effects98663 +Node: account directive101819 +Node: Account comments103269 +Node: Account error checking103928 +Node: Account display order105465 +Node: Account types106663 +Node: alias directive110437 +Node: Basic aliases111648 +Node: Regex aliases112523 +Node: Combining aliases113570 +Node: Aliases and multiple files115024 +Node: end aliases directive115807 +Node: Aliases can generate bad account names116175 +Node: Aliases and account types117008 +Node: commodity directive117900 +Node: Commodity directive syntax119487 +Node: Commodity error checking121136 +Node: decimal-mark directive121611 +Node: include directive122190 +Node: P directive123266 +Node: payee directive124300 +Node: tag directive124922 +Node: Periodic transactions125534 +Node: Periodic rule syntax127688 +Node: Periodic rules and relative dates128511 +Node: Two spaces between period expression and description!129288 +Node: Auto postings130249 +Node: Auto postings and multiple files133409 +Node: Auto postings and dates133814 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions134255 +Node: Auto posting tags135101 +Node: Auto postings on forecast transactions only135996 +Node: Other syntax136466 +Node: Balance assignments137238 +Node: Balance assignments and costs138766 +Node: Balance assignments and multiple files139188 +Node: Bracketed posting dates139611 +Node: D directive140309 +Node: apply account directive142082 +Node: Y directive142949 +Node: Secondary dates143937 +Node: Star comments145422 +Node: Valuation expressions146114 +Node: Virtual postings146413 +Node: Other Ledger directives148037 +Node: Other cost/lot notations148799 +Node: CSV151640 +Node: CSV rules cheatsheet153736 +Node: source155763 +Node: encoding156763 +Node: separator157702 +Node: skip158355 +Node: date-format159005 +Node: timezone159848 +Node: newest-first160974 +Node: intra-day-reversed161687 +Node: decimal-mark162287 +Node: fields list162767 +Node: Field assignment164575 +Node: Field names165794 +Node: date field167126 +Node: date2 field167290 +Node: status field167485 +Node: code field167675 +Node: description field167863 +Node: comment field168080 +Node: account field168637 +Node: amount field169355 +Node: currency field172194 +Node: balance field172602 +Node: if block173125 +Node: Matchers174652 +Node: Multiple matchers176642 +Node: Match groups177450 +Node: if table178343 +Node: balance-type180406 +Node: include181233 +Node: Working with CSV181802 +Node: Rapid feedback182354 +Node: Valid CSV182937 +Node: File Extension183813 +Node: Reading CSV from standard input184548 +Node: Reading multiple CSV files184934 +Node: Reading files specified by rule185410 +Node: Valid transactions186807 +Node: Deduplicating importing187632 +Node: Setting amounts188861 +Node: Amount signs191388 +Node: Setting currency/commodity192453 +Node: Amount decimal places193829 +Node: Referencing other fields195086 +Node: How CSV rules are evaluated196194 +Node: Well factored rules197862 +Node: CSV rules examples198352 +Node: Bank of Ireland198550 +Node: Coinbase200147 +Node: Amazon201330 +Node: Paypal203172 +Node: Timeclock210922 +Node: Timedot213191 +Node: Timedot examples216668 +Node: PART 3 REPORTING CONCEPTS218945 +Node: Time periods219109 +Node: Report start & end date219382 +Node: Smart dates220858 +Node: Report intervals222801 +Node: Date adjustments223375 +Node: Start date adjustment223595 +Node: End date adjustment224498 +Node: Period headings225243 +Node: Period expressions226176 +Node: Period expressions with a report interval228081 +Node: More complex report intervals228529 +Node: Multiple weekday intervals230645 +Node: Depth231656 +Node: Queries233491 +Node: Query types235189 +Node: acct query235606 +Node: amt query235917 +Node: code query236534 +Node: cur query236729 +Node: desc query237335 +Node: date query237518 +Node: date2 query237914 +Node: depth query238205 +Node: expr query238541 +Node: not query238922 +Node: note query239262 +Node: payee query239528 +Node: real query239809 +Node: status query240014 +Node: type query240254 +Node: tag query240787 +Node: Combining query terms241416 +Node: Queries and command options243156 +Node: Queries and account aliases243610 +Node: Queries and valuation243935 +Node: Pivoting244297 +Node: Generating data246573 +Node: Forecasting248373 +Node: --forecast249029 +Node: Inspecting forecast transactions250130 +Node: Forecast reports251463 +Node: Forecast tags252572 +Node: Forecast period in detail253192 +Node: Forecast troubleshooting254280 +Node: Budgeting255351 +Node: Amount formatting255911 +Node: Commodity display style256155 +Node: Rounding257996 +Node: Trailing decimal marks258601 +Node: Amount parseability259534 +Node: Cost reporting261115 +Node: Recording costs261946 +Node: Reporting at cost263673 +Node: Equity conversion postings264438 +Node: Inferring equity conversion postings267083 +Node: Combining costs and equity conversion postings268225 +Node: Requirements for detecting equity conversion postings269450 +Node: Infer cost and equity by default ?270972 +Node: Value reporting271409 +Node: -V Value272345 +Node: -X Value in specified commodity272672 +Node: Valuation date273022 +Node: Finding market price273982 +Node: --infer-market-prices market prices from transactions275362 +Node: Valuation commodity278406 +Node: --value Flexible valuation279839 +Node: Valuation examples281682 +Node: Interaction of valuation and queries283814 +Node: Effect of valuation on reports284531 +Node: PART 4 COMMANDS292429 +Node: Help commands294645 +Node: help294818 +Node: demo296523 +Node: User interface commands297740 +Node: ui297934 +Node: web298059 +Node: Data entry commands298187 +Node: add298385 +Node: import300840 +Node: Import preview301874 +Node: Overlap detection302822 +Node: First import305708 +Node: Importing balance assignments306903 +Node: Import and commodity styles307958 +Node: Import special cases308396 +Node: Basic report commands309731 +Node: accounts310032 +Node: codes312905 +Node: commodities313927 +Node: descriptions314171 +Node: files314638 +Node: notes314935 +Node: payees315447 +Node: prices316231 +Node: stats317123 +Node: tags318864 +Node: Standard report commands320171 +Node: print320476 +Node: print explicitness323217 +Node: print amount style324137 +Node: print parseability325375 +Node: print other features326294 +Node: print output format327157 +Node: aregister330442 +Node: aregister and posting dates334901 +Node: register335802 +Node: Custom register output342977 +Node: balancesheet344162 +Node: balancesheetequity348932 +Node: cashflow354072 +Node: incomestatement358634 +Node: Advanced report commands363232 +Node: balance363440 +Node: balance features368616 +Node: Simple balance report370692 +Node: Balance report line format372502 +Node: Filtered balance report374862 +Node: List or tree mode375381 +Node: Depth limiting376894 +Node: Dropping top-level accounts377661 +Node: Showing declared accounts378171 +Node: Sorting by amount378901 +Node: Percentages379738 +Node: Multi-period balance report380445 +Node: Balance change end balance383197 +Node: Balance report types384834 +Node: Calculation type385513 +Node: Accumulation type386217 +Node: Valuation type387318 +Node: Combining balance report types388507 +Node: Budget report390539 +Node: Using the budget report392844 +Node: Budget date surprises395120 +Node: Selecting budget goals396484 +Node: Budgeting vs forecasting397432 +Node: Balance report layout399109 +Node: Wide layout400314 +Node: Tall layout402719 +Node: Bare layout404025 +Node: Tidy layout406089 +Node: Balance report output407633 +Node: Some useful balance reports408448 +Node: roi409708 +Node: Spaces and special characters in --inv and --pnl411955 +Node: Semantics of --inv and --pnl412681 +Node: IRR and TWR explained414768 +Node: Chart commands418179 +Node: activity418360 +Node: Data generation commands418857 +Node: close419063 +Node: close --clopen421626 +Node: close --close423800 +Node: close --open424324 +Node: close --assert424574 +Node: close --assign424901 +Node: close --retain425580 +Node: close customisation426437 +Node: close and balance assertions428081 +Node: close examples429603 +Node: Retain earnings429840 +Node: Migrate balances to a new file430343 +Node: More detailed close examples431705 +Node: rewrite431927 +Node: Re-write rules in a file434499 +Node: Diff output format435809 +Node: rewrite vs print --auto437082 +Node: Maintenance commands437796 +Node: check438005 +Node: Basic checks439087 +Node: Strict checks440040 +Node: Other checks440915 +Node: Custom checks442770 +Node: diff443225 +Node: test444432 +Node: PART 5 COMMON TASKS445304 +Node: Getting help445537 +Node: Constructing command lines446446 +Node: Starting a journal file447284 +Node: Setting LEDGER_FILE448668 +Node: Setting opening balances449926 +Node: Recording transactions453248 +Node: Reconciling453973 +Node: Reporting456362 +Node: Migrating to a new file460476 +Node: BUGS460925 +Node: Troubleshooting461890  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 1951e01e2..faf0599a2 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -101,49 +101,54 @@ Input Common tasks > Setting LEDGER_FILE. Text encoding - Data files containing non-ascii characters must use UTF-8 encoding. An - optional byte order mark (BOM) is allowed, at the beginning of the file - (only). + hledger input files containing non-ascii characters must use UTF-8 en- + coding, with the exception of CSV (SSV, TSV..) files, which can be + read from other encodings (see encoding CSV rule). - Also, your system should be configured with a locale that can decode - UTF-8 text. On some unix systems, you may need set the LANG environ- - ment variable, eg. You can read more about this in Unicode characters, - below. + In UTF-8 input files, an optional byte order mark (BOM) at the begin- + ning of the file is allowed. - On unix systems you can check a file's encoding with the file command. - If you need to import from a UTF-16-encoded CSV file, say, you can con- - vert it to UTF-8 with the iconv command. + Your system may need to be configured with a locale that understands + the input file's encoding. Eg on some unix systems, you may need set + 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 - 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 any of the supported file formats, which currently are: - Reader: Reads: Automatically used for + Reader: Reads: Automatically used for files with extensions: ----------------------------------------------------------------------------- - journal hledger journal files and some .journal .j .hledger + journal hledger journal files and some .journal .j .hledger Ledger journals, for transactions .ledger timeclock timeclock files, for precise time .timeclock logging timedot timedot files, for approximate .timedot time logging - csv Comma or other character sepa- .csv + csv Comma or other character sepa- .csv rated values, for data import ssv Semicolon separated values .ssv tsv Tab separated values .tsv - rules CSV/SSV/TSV/other separated val- .rules + rules CSV/SSV/TSV/other separated val- .rules ues, alternate way These formats are described in more detail below. - hledger detects the format automatically based on the file extensions - shown above. If it can't recognise the file extension, it assumes - journal format. So for non-journal files, it's important to use a + hledger detects the format automatically based on the file extensions + shown above. If it can't recognise the file extension, it assumes + journal format. So for non-journal files, it's important to use a recognised file extension, so as to either read successfully or to show relevant error messages. - You can also force a specific reader/format by prefixing the file path - with the format and a colon. Eg, to read a .dat file containing tab + You can also force a specific reader/format by prefixing the file path + with the format and a colon. Eg, to read a .dat file containing tab separated values: $ hledger -f tsv:/some/file.dat stats @@ -153,29 +158,29 @@ Input $ cat FILE | hledger -f- print - If reading non-journal data in this way, you'll need to write the for- + If reading non-journal data in this way, you'll need to write the for- mat as a prefix, like timeclock: here: $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:- Multiple files - You can specify multiple -f options, to read multiple files as one big + You can specify multiple -f options, to read multiple files as one big journal. When doing this, note that certain features (described below) will be affected: - o Balance assertions will not see the effect of transactions in previ- - ous files. (Usually this doesn't matter as each file will set the + o Balance assertions will not see the effect of transactions in previ- + ous files. (Usually this doesn't matter as each file will set the corresponding opening balances.) o Some directives will not affect previous or subsequent files. - If needed, you can work around these by using a single parent file + If needed, you can work around these by using a single parent file which includes the others, or concatenating the files into one, eg: cat a.journal b.journal | hledger -f- CMD. Strict mode hledger checks input files for valid data. By default, the most impor- - tant errors are detected, while still accepting easy journal files + tant errors are detected, while still accepting easy journal files without a lot of declarations: o Are the input files parseable, with valid syntax ? @@ -186,7 +191,7 @@ Input With the -s/--strict flag, additional checks are performed: - o Are all accounts posted to, declared with an account directive ? + o Are all accounts posted to, declared with an account directive ? (Account error checking) o Are all commodities declared with a commodity directive ? (Commodity @@ -194,57 +199,57 @@ Input o Are all commodity conversions declared explicitly ? - You can use the check command to run individual checks -- the ones + You can use the check command to run individual checks -- the ones listed above and some more. Commands - hledger provides various subcommands for getting things done. Most of - these commands do not change the journal file; they just read it and - output a report. A few commands assist with adding data and file man- + hledger provides various subcommands for getting things done. Most of + these commands do not change the journal file; they just read it and + output a report. A few commands assist with adding data and file man- agement. - To show a summary of commands, run hledger with no arguments. You can + To show a summary of commands, run hledger with no arguments. You can see the same commands summary at the start of PART 4: COMMANDS below. To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS], - o CMD is the full command name, or its standard abbreviation shown in + o CMD is the full command name, or its standard abbreviation shown in the commands list, or any unambiguous prefix of the name. - o CMDOPTS are command-specific options, if any. Command-specific op- + o CMDOPTS are command-specific options, if any. Command-specific op- tions must be written after the command name. Eg: hledger print -x. - o CMDARGS are additional arguments to the command, if any. Most - hledger commands accept arguments representing a query, to limit the + o CMDARGS are additional arguments to the command, if any. Most + hledger commands accept arguments representing a query, to limit the data in some way. Eg: hledger reg assets:checking. To list a command's options, arguments, and documentation in the termi- nal, run hledger CMD -h. Eg: hledger bal -h. Add-on commands - In addition to the built-in commands, you can install add-on commands: - programs or scripts named "hledger-SOMETHING", which will also appear - in hledger's commands list. If you used the hledger-install script, - you will have several add-ons installed already. Some more can be - found in hledger's bin/ directory, documented at + In addition to the built-in commands, you can install add-on commands: + programs or scripts named "hledger-SOMETHING", which will also appear + in hledger's commands list. If you used the hledger-install script, + you will have several add-ons installed already. Some more can be + found in hledger's bin/ directory, documented at https://hledger.org/scripts.html. More precisely, add-on commands are programs or scripts in your shell's PATH, whose name starts with "hledger-" and ends with no extension or a - recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", - ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix + recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", + ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix and mac) which has executable permission for the current user. You can run add-on commands using hledger, much like built-in commands: hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double - hyphen argument, required before add-on-specific options. Eg: hledger - ui -- --watch or hledger web -- --serve. If this causes difficulty, + hyphen argument, required before add-on-specific options. Eg: hledger + ui -- --watch or hledger web -- --serve. If this causes difficulty, you can always run the add-on directly, without using hledger: hledger-ui --watch or hledger-web --serve. Options - Run hledger -h to see general command line help. Options can be writ- - ten either before or after the command name. These options are spe- + Run hledger -h to see general command line help. Options can be writ- + ten either before or after the command name. These options are spe- cific to the hledger CLI: Flags: @@ -336,45 +341,45 @@ Options --pager=YN use a pager when needed ? y/yes (default) or n/no --color=YNA --colour use ANSI color ? y/yes, n/no, or auto (default) - Usually hledger accepts any unambiguous flag prefix, eg you can write + Usually hledger accepts any unambiguous flag prefix, eg you can write --tl instead of --tldr or --dry instead of --dry-run. - If the same option appears more than once in a command, usually the + If the same option appears more than once in a command, usually the last (right-most) wins. - With most commands, arguments are interpreted as a hledger query which - filter the data. Some queries can be expressed either with options or + With most commands, arguments are interpreted as a hledger query which + filter the data. Some queries can be expressed either with options or with arguments. Below are more tips for using the command line interface - feel free to skip these until you need them. Special characters - Here we touch on shell escaping/quoting rules, and give some examples. - This is a slightly complicated topic which you may not need at first, + Here we touch on shell escaping/quoting rules, and give some examples. + This is a slightly complicated topic which you may not need at first, but you should be aware of it, so you can return here when needed. If you are able to minimise the use of special characters in your data, - you won't need escaping as much, and your command lines will be sim- - pler. For example, avoiding spaces in account names, and using an - ISO-4217 currency code like USD instead of the $ currency symbol, can + you won't need escaping as much, and your command lines will be sim- + pler. For example, avoiding spaces in account names, and using an + ISO-4217 currency code like USD instead of the $ currency symbol, can be helpful. - But if you want to use spaced account names and $, go right ahead; es- + But if you want to use spaced account names and $, go right ahead; es- caping isn't a big deal. Escaping shell special characters - At the command line, characters which have special meaning for your + At the command line, characters which have special meaning for your shell must be "shell-escaped" (AKA "quoted") if you want hledger to see them. Often these include space, <, >, (, ), |, \, $ and/or %. - For example, to match an account name containing the phrase "credit + For example, to match an account name containing the phrase "credit card", don't write this: $ hledger register credit card - In that command, "credit" and "card" are treated as separate query ar- - guments (described below), so this would match accounts containing ei- + In that command, "credit" and "card" are treated as separate query ar- + guments (described below), so this would match accounts containing ei- ther word. Instead, enclose the phrase in double or single quotes: $ hledger register "credit card" @@ -384,10 +389,10 @@ Options $ hledger register credit\ card - Some shell characters still have a special meaning inside double + Some shell characters still have a special meaning inside double quotes, such as the dollar sign ($). Eg in "assets:$account", the bash - shell would replace $account with the value of a shell variable with - that name. When you don't want that, use single quotes, which escape + shell would replace $account with the value of a shell variable with + that name. When you don't want that, use single quotes, which escape more strongly: $ hledger balance 'assets:$account' @@ -396,21 +401,21 @@ Options If you are using hledger in a Powershell or Command window on Microsoft Windows, the escaping rules are different: - o In a Powershell window (powershell, blue background), you must use + o In a Powershell window (powershell, blue background), you must use double quotes or single quotes (not backslash). - o In a Command window (cmd, black background), you must use double + o In a Command window (cmd, black background), you must use double quotes (not single quotes or backslash). - The next two sections were written for Unix-like shells, so might need + The next two sections were written for Unix-like shells, so might need to be adapted if you're using cmd or powershell. (Edits welcome.) Escaping regular expression special characters - Many hledger arguments are regular expressions (described below), and - these too have characters which cause special effects. Some of those - characters are ., ^, $, [, ], (, ), |, and \. When you don't want - these to cause special effects, you can "regex-escape" them by writing - \ (a backslash) before them. But since backslash is also special to + Many hledger arguments are regular expressions (described below), and + these too have characters which cause special effects. Some of those + characters are ., ^, $, [, ], (, ), |, and \. When you don't want + these to cause special effects, you can "regex-escape" them by writing + \ (a backslash) before them. But since backslash is also special to the shell, you may need to also shell-escape the backslashes. Eg, in the bash shell, to match a literal $ sign, you could write: @@ -421,14 +426,14 @@ Options $ hledger balance 'cur:\$' - (The dollar sign is regex-escaped by the backslash preceding it. Then - that backslash is shell-escaped by another backslash, or by single + (The dollar sign is regex-escaped by the backslash preceding it. Then + that backslash is shell-escaped by another backslash, or by single quotes.) Escaping add-on arguments When you run an external add-on command with hledger (described below), - any options or arguments being passed through to the add-on executable - lose one level of shell-escaping, so you must add an extra level of + any options or arguments being passed through to the add-on executable + lose one level of shell-escaping, so you must add an extra level of shell-escaping to compensate. Eg, in the bash shell, to run the ui add-on and match a literal $ sign, @@ -448,7 +453,7 @@ Options o \\$ is regex-escaped, then shell-escaped - o \\\\$ is regex-escaped, then shell-escaped, then both slashes are + o \\\\$ is regex-escaped, then shell-escaped, then both slashes are shell-escaped once more for hledger argument pass-through. Or you can avoid such triple-escaping, by running the add-on executable @@ -457,8 +462,8 @@ Options $ hledger-ui cur:\\$ Escaping in other situations - hledger options and arguments are sometimes used in places other than - the command line, with different escaping rules. For example, back- + hledger options and arguments are sometimes used in places other than + the command line, with different escaping rules. For example, back- slash-quoting generally does not work there. Here are some more tips. In Windows cmd Use double quotes @@ -468,16 +473,16 @@ Options filter prompt In hledger-web's Use single or double quotes search form - In an argument Don't use spaces, don't shell-escape, do regex-es- + In an argument Don't use spaces, don't shell-escape, do regex-es- file cape when needed - In a config file Use single or double quotes, and enclose the whole + In a config file Use single or double quotes, and enclose the whole argument ("desc:a b" not desc:"a b") - In ghci (the Use double quotes, and enclose the whole argument + In ghci (the Use double quotes, and enclose the whole argument Haskell REPL) Using a wild card - When escaping a special character is too much hassle (or impossible), - you can often just write . (period) instead. In regular expressions, + When escaping a special character is too much hassle (or impossible), + you can often just write . (period) instead. In regular expressions, this means "accept any character here". Eg: $ hledger register credit.card @@ -485,8 +490,8 @@ Options Unicode characters hledger is expected to handle non-ascii characters correctly: - o they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web's search/add/edit + o they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web's search/add/edit forms, etc.) o they should be displayed correctly by all hledger tools, and @@ -494,40 +499,40 @@ Options This requires a well-configured environment. Here are some tips: - o A system locale must be configured, and it must be one that can de- - code the characters being used. In bash, you can set a locale like - this: export LANG=en_US.UTF-8. There are some more details in Trou- - bleshooting. This step is essential - without it, hledger will quit - on encountering a non-ascii character (as with all GHC-compiled pro- + o A system locale must be configured, and it must be one that can de- + code the characters being used. In bash, you can set a locale like + this: export LANG=en_US.UTF-8. There are some more details in Trou- + bleshooting. This step is essential - without it, hledger will quit + on encountering a non-ascii character (as with all GHC-compiled pro- grams). - o Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + o Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) must support unicode. On Windows, you may need to use Windows Termi- nal and/or enable UTF-8 support. o The terminal must be using a font which includes the required unicode glyphs. - o The terminal should be configured to display wide characters as dou- + o The terminal should be configured to display wide characters as dou- ble width (for report alignment). - o On Windows, for best results you should run hledger in the same kind - of environment in which it was built. Eg hledger built in the stan- - dard CMD.EXE environment (like the binaries on our download page) - might show display problems when run in a cygwin or msys terminal, + o On Windows, for best results you should run hledger in the same kind + of environment in which it was built. Eg hledger built in the stan- + dard CMD.EXE environment (like the binaries on our download page) + might show display problems when run in a cygwin or msys terminal, and vice versa. (See eg #961). Regular expressions - A regular expression (regexp) is a small piece of text where certain - characters (like ., ^, $, +, *, (), |, [], \) have special meanings, - forming a tiny language for matching text precisely - very useful in - hledger and elsewhere. To learn all about them, visit regular-expres- + A regular expression (regexp) is a small piece of text where certain + characters (like ., ^, $, +, *, (), |, [], \) have special meanings, + forming a tiny language for matching text precisely - very useful in + hledger and elsewhere. To learn all about them, visit regular-expres- sions.info. - hledger supports regexps whenever you are entering a pattern to match - something, eg in query arguments, account aliases, CSV if rules, + hledger supports regexps whenever you are entering a pattern to match + something, eg in query arguments, account aliases, CSV if rules, hledger-web's search form, hledger-ui's / search, etc. You may need to - wrap them in quotes, especially at the command line (see Special char- + wrap them in quotes, especially at the command line (see Special char- acters above). Here are some examples: Account name queries (quoted for command line use): @@ -583,59 +588,59 @@ Options & %date (29|30|31|01|02|03)$ hledger's regular expressions - hledger's regular expressions come from the regex-tdfa library. If - they're not doing what you expect, it's important to know exactly what + hledger's regular expressions come from the regex-tdfa library. If + they're not doing what you expect, it's important to know exactly what they support: 1. they are case insensitive - 2. they are infix matching (they do not need to match the entire thing + 2. they are infix matching (they do not need to match the entire thing being matched) 3. they are POSIX ERE (extended regular expressions) 4. they also support GNU word boundaries (\b, \B, \<, \>) - 5. backreferences are supported when doing text replacement in account - aliases or CSV rules, where backreferences can be used in the re- + 5. backreferences are supported when doing text replacement in account + aliases or CSV rules, where backreferences can be used in the re- placement string to reference capturing groups in the search regexp. Otherwise, if you write \1, it will match the digit 1. - 6. they do not support mode modifiers ((?s)), character classes (\w, + 6. they do not support mode modifiers ((?s)), character classes (\w, \d), or anything else not mentioned above. - 7. they may not (I'm guessing not) properly support right-to-left or + 7. they may not (I'm guessing not) properly support right-to-left or bidirectional text. Some things to note: - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required. - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts with the dollar sign in hledger-web, write cur:\$. - o On the command line, some metacharacters like $ have a special mean- + o On the command line, some metacharacters like $ have a special mean- ing to the shell and so must be escaped at least once more. See Spe- cial characters. Argument files You can save a set of command line options and arguments in a file, and - then reuse them by writing @FILENAME as a command line argument. Eg: + then reuse them by writing @FILENAME as a command line argument. Eg: hledger bal @foo.args. - An argument file's format is more restrictive than the command line. + An argument file's format is more restrictive than the command line. Each line should contain just one option or argument. Don't use spaces - except inside quotes; write = or nothing between a flag and its argu- - ment. If you use quotes, they must enclose the whole line. For the - special characters mentioned above, use one less level of quoting than + except inside quotes; write = or nothing between a flag and its argu- + ment. If you use quotes, they must enclose the whole line. For the + special characters mentioned above, use one less level of quoting than you would at the command line. Config files - With hledger 1.40+, you can save extra command line options and argu- - ments in a more featureful hledger config file. Here's a small exam- + With hledger 1.40+, you can save extra command line options and argu- + ments in a more featureful hledger config file. Here's a small exam- ple: # General options are listed first, and used with hledger commands that support them. @@ -645,45 +650,45 @@ Options [print] --explicit --show-costs - To use a config file, specify it with the --conf option. Its options - will be inserted near the start of your command line, so you can over- + To use a config file, specify it with the --conf option. Its options + will be inserted near the start of your command line, so you can over- ride them with command line options if needed. - Or, you can set up an automatic config file that is used whenever you - run hledger, by creating hledger.conf in the current directory or - above, or .hledger.conf in your home directory (~/.hledger.conf), or - hledger.conf in your XDG config directory (~/.con- + Or, you can set up an automatic config file that is used whenever you + run hledger, by creating hledger.conf in the current directory or + above, or .hledger.conf in your home directory (~/.hledger.conf), or + hledger.conf in your XDG config directory (~/.con- fig/hledger/hledger.conf). - Here is another example config you could start with: + Here is another example config you could start with: https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample - You can put not only options, but also arguments in a config file. If - the first word in a config file's top (general) section does not begin - with a dash (eg: print), it is treated as the command argument (over- + You can put not only options, but also arguments in a config file. If + the first word in a config file's top (general) section does not begin + with a dash (eg: print), it is treated as the command argument (over- riding any argument on the command line). - On unix machines, you can add a shebang line at the top of a config - file, set executable permission on the file, and use it like a script. + On unix machines, you can add a shebang line at the top of a config + file, set executable permission on the file, and use it like a script. Eg (the -S is needed on some operating systems): #!/usr/bin/env -S hledger --conf You can ignore config files by adding the -n/--no-conf flag to the com- mand line. This is useful when using hledger in scripts, or when trou- - bleshooting. When both --conf and --no-conf options are used, the + bleshooting. When both --conf and --no-conf options are used, the right-most wins. To inspect the processing of config files, use --debug or --debug=8. Warning! - There aren't many hledger features that need a warning, but this is + There aren't many hledger features that need a warning, but this is one! - Automatic config files, while convenient, also make hledger less pre- - dictable and dependable. It's easy to make a config file that changes - a report's behaviour, or breaks your hledger-using scripts/applica- + Automatic config files, while convenient, also make hledger less pre- + dictable and dependable. It's easy to make a config file that changes + a report's behaviour, or breaks your hledger-using scripts/applica- tions, in ways that will surprise you later. If you don't want this, @@ -693,33 +698,33 @@ Options 2. Also be alert to downloaded directories which may contain a hledger.conf file. - 3. Also if you are sharing scripts or examples or support, consider + 3. Also if you are sharing scripts or examples or support, consider that others may have a hledger.conf file. Conversely, once you decide to use this feature, try to remember: - 1. Whenever a hledger command does not work as expected, try it again + 1. Whenever a hledger command does not work as expected, try it again with -n (--no-conf) to see if a config file was to blame. - 2. Whenever you call hledger from a script, consider whether that call + 2. Whenever you call hledger from a script, consider whether that call should use -n or not. - 3. Be conservative about what you put in your config file; try to con- + 3. Be conservative about what you put in your config file; try to con- sider the effect on all your reports. - 4. To troubleshoot the effect of config files, run with --debug or + 4. To troubleshoot the effect of config files, run with --debug or --debug 8. The config file feature was added in hledger 1.40 and is considered ex- perimental. Shell completions - If you use the bash shell, you can optionally set up context-sensitive - autocompletions when you press TAB in a hledger command line. At a - bash shell prompt, try pressing hledger (should list - all hledger commands) or hledger reg acct: (should list your - top-level account names). If completions aren't working, or for more - details, see Install > Shell completions. + If you use the bash or zsh shells, you can optionally set up con- + text-sensitive autocompletion for hledger command lines. Try pressing + hledger (should list all hledger commands) or hledger + reg acct: (should list your top-level account names). If + completions aren't working, or for more details, see Install > Shell + completions. Output Output destination @@ -728,15 +733,15 @@ Output $ hledger print > foo.txt - Some commands (print, register, stats, the balance commands) also pro- - vide the -o/--output-file option, which does the same thing without + Some commands (print, register, stats, the balance commands) also pro- + vide the -o/--output-file option, which does the same thing without needing the shell. Eg: $ hledger print -o foo.txt $ hledger print -o - # write to stdout (the default) Output format - Some commands offer other kinds of output, not just text on the termi- + Some commands offer other kinds of output, not just text on the termi- nal. Here are those commands and the formats currently supported: command txt html csv/tsv fods beancount sql json @@ -750,14 +755,14 @@ Output print Y Y Y Y Y Y Y register Y Y Y Y Y - You can also see which output formats a command supports by running + You can also see which output formats a command supports by running hledger CMD -h and looking for the -O/--output-format=FMT option, You can select the output format by using that option: $ hledger print -O csv # print CSV to standard output - or by choosing a suitable filename extension with the -o/--out- + or by choosing a suitable filename extension with the -o/--out- put-file=FILE.FMT option: $ hledger balancesheet -o foo.csv # write CSV to foo.csv @@ -775,12 +780,9 @@ Output unicode or wide characters, you'll need a terminal and font that render those correctly. (This can be challenging on MS Windows.) - Some reports (register, aregister) will use the width indicated by the - COLUMNS environment variable. If your shell and terminal are working - well, they will keep COLUMNS updated as you resize the window. So reg- - 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. + Some reports (register, aregister) will normally use the full window + width. If this isn't working or you want to override it, you can use + the -w/--width option. Balance reports (balance, balancesheet, incomestatement...) use what- ever width they need. Multi-period multi-currency reports can often be @@ -810,29 +812,32 @@ Output Paging In unix-like environments, when displaying large output (in any output format) in the terminal, hledger tries to use a pager when appropriate. - 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 - shows help, and q quits. The home/end/page up/page down/cursor keys, + (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 + 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, and mouse scrolling, may also work. hledger will use the pager specified by the PAGER environment variable, - otherwise less if available, otherwise more if available. (With one - exception: hledger help -p TOPIC will always use less, so that it can + otherwise less if available, otherwise more if available. (With one + exception: hledger help -p TOPIC will always use less, so that it can scroll to the topic.) - The pager is expected to display hledger's ANSI colour and text - styling. If you see junk characters, you might need to configure your - pager to handle ANSI codes. Or you could disable colour as described + The pager is expected to display hledger's ANSI colour and text + styling. If you see junk characters, you might need to configure your + pager to handle ANSI codes. Or you could disable colour as described above. If you are using the less pager, hledger automatically appends a number - of options to the LESS variable to enable ANSI colour and a number of - other conveniences. (At the time of writing: --chop-long-lines - --hilite-unread --ignore-case --mouse --no-init --quit-at-eof - --quit-if-one-screen --RAW-CONTROL-CHARS --shift=8 - --squeeze-blank-lines --use-backslash --use-color ). If these don't - work well, you can set your preferred options in the HLEDGER_LESS vari- - able, which will be used instead. + of options to the LESS variable to enable ANSI colour and a number of + other conveniences. (At the time of writing: --chop-long-lines + --hilite-unread --ignore-case --mouse --no-init --quit-at-eof + --quit-if-one-screen --RAW-CONTROL-CHARS --shift=8 + --squeeze-blank-lines --use-backslash ). If these don't work well, you + can set your preferred options in the HLEDGER_LESS variable, which will + be used instead. HTML output 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' - This option can repeated to set the display style for multiple commodi- - ties/currencies. Its argument is as described in the commodity direc- - tive. + This option can be repeated to set the display style for multiple com- + modities/currencies. Its argument is as described in the commodity di- + rective. In some cases hledger will adjust number formatting to improve their parseability (such as adding trailing decimal marks when needed). @@ -1004,10 +1009,6 @@ Output Environment 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 options hledger should use. (Otherwise, LESS + custom options are used.) @@ -2386,7 +2387,7 @@ Journal accounts as you expect, try troubleshooting with the accounts command, eg something like: - $ hledger accounts --alias assets=bassetts type:a + $ hledger accounts --types -1 --alias assets=bassetts commodity directive The commodity directive performs several functions: @@ -2422,7 +2423,7 @@ Journal Commodity directive syntax A commodity directive is normally the word commodity followed by a sam- 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 1.000,00 EUR @@ -3071,27 +3072,25 @@ Journal syntax comparison. Other cost/lot notations - A slight digression for Ledger and Beancount users. Ledger has a num- - ber of cost/lot-related notations: + A slight digression for Ledger and Beancount users. + + Ledger has a number of cost/lot-related notations: o @ UNITCOST and @@ TOTALCOST 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 o (@) UNITCOST and (@@) TOTALCOST (virtual cost) - 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". - Currently, hledger treats the above like @ and @@; the parentheses are - ignored. + o {=UNITCOST} and {{=TOTALCOST}} (fixed price) - o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price) - - o when buying, means "this cost is also the fixed price, don't let it + o when buying, means "this cost is also the fixed value, don't let it fluctuate in value reports" o {UNITCOST} and {{TOTALCOST}} (lot price) @@ -3099,10 +3098,10 @@ Journal o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- ates a lot - o when selling, combined with @ ..., specifies an investment lot by - its cost basis; does not check if that lot is present + o when selling, combined with @ ..., selects an existing lot by its + 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 @@ -3114,26 +3113,32 @@ Journal o when selling, selects a lot by its note - Currently, hledger accepts any or all of the above in any order after - the posting amount, but ignores them. (This can break transaction bal- - ancing.) + Currently, hledger - 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 expresses a cost without creating a lot, as in hledger - o when buying (augmenting) or selling (reducing) a lot, combined with - {...}: documents the cost/selling price (not used for transaction - balancing) + o when buying (acquiring) or selling (disposing of) a lot, and com- + bined with {...}: is not used except to document the cost/selling + price o {UNITCOST} and {{TOTALCOST}} - o when buying (augmenting), expresses the cost for transaction bal- - ancing, and also creates a lot with this cost basis attached + o when buying, expresses the cost for transaction balancing, and also + creates a lot with this cost basis attached - o when selling (reducing), + o when selling, o selects a lot by its cost basis @@ -3142,38 +3147,44 @@ Journal o expresses the selling price for transaction balancing - Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but - ignores it. + o {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNITCOST, + YYYY-MM-DD, "LABEL"} - o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- - COST, YYYY-MM-DD, "LABEL"} etc. + o when selling, other combinations of date/cost/label, like the + 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 - hledger can read CSV files (Character Separated Value - usually comma, - semicolon, or tab) containing dated records, automatically converting + hledger can read CSV files (Character Separated Value - usually comma, + semicolon, or tab) containing dated records, automatically converting each record into a transaction. (To learn about writing CSV, see CSV output.) - For best error messages when reading CSV/TSV/SSV files, make sure they + For best error messages when reading CSV/TSV/SSV files, make sure they have a corresponding .csv, .tsv or .ssv file extension or use a hledger file prefix (see File Extension below). Each CSV file must be described by a corresponding rules file. - This contains rules describing the CSV data (header line, fields lay- - out, date format etc.), how to construct hledger transactions from it, - and how to categorise transactions based on description or other at- + This contains rules describing the CSV data (header line, fields lay- + out, date format etc.), how to construct hledger transactions from it, + and how to categorise transactions based on description or other at- tributes. - By default, hledger expects this rules file to be named like the CSV - file, with an extra .rules extension added, in the same directory. Eg - when asked to read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. + By default, hledger expects this rules file to be named like the CSV + file, with an extra .rules extension added, in the same directory. Eg + when asked to read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. You can specify a different rules file with the --rules option. - At minimum, the rules file must identify the date and amount fields, - and often it also specifies the date format and how many header lines + At minimum, the rules file must identify the date and amount fields, + and often it also specifies the date format and how many header lines there are. Here's a simple CSV file and a rules file for it: Date, Description, Id, Amount @@ -3190,15 +3201,17 @@ CSV income:unknown -10.23 There's an introductory Importing CSV data tutorial on hledger.org, and - more CSV rules examples below, and a larger collection at + more CSV rules examples below, and a larger collection at https://github.com/simonmichael/hledger/tree/master/examples/csv. CSV rules cheatsheet The following kinds of rule can appear in the rules file, in any order. (Blank lines and lines beginning with # or ; or * are ignored.) - source optionally declare which file to read data + source optionally declare which file to read data from + encoding optionally declare which text encoding the + data has separator declare the field separator, instead of rely- ing on file extension 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". + 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 You can use the separator rule to read other kinds of character-sepa- 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 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). - (Since 1.41:) You can use a negated ! matcher on a & line, meaning AND - NOT. + o Matcher lines beginning with & ! (since 1.41, or && !, since 1.42) + 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 Added in 1.32 @@ -3729,9 +3764,9 @@ CSV if,HLEDGERFIELD1,HLEDGERFIELD2,... MATCHERA,VALUE1,VALUE2,... - MATCHERB,VALUE1,VALUE2,... - ; Comment line that explains MATCHERC - MATCHERC,VALUE1,VALUE2,... + MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*) + ; Comment line that explains MATCHERD + MATCHERD,VALUE1,VALUE2,... The first character after if is taken to be this if table's field sepa- @@ -3747,10 +3782,10 @@ CSV of file). 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 - line to the corresponding hledger fields; If multiple lines match, - later lines will override fields assigned by the earlier ones - just - like the sequence of if blocks would behave. + lines with matchers; whenever a line with matchers succeeds, assign all + of the values on that line to the corresponding hledger fields; If mul- + tiple lines match, later lines will override fields assigned by the + earlier ones - just like the sequence of if blocks would behave. If table presented above is equivalent to this sequence of if blocks: @@ -3759,13 +3794,13 @@ CSV HLEDGERFIELD2 VALUE2 ... - if MATCHERB + if MATCHERB && MATCHERC HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 ... - ; Comment line which explains MATCHERC - if MATCHERC + ; Comment line which explains MATCHERD + if MATCHERD HLEDGERFIELD1 VALUE1 HLEDGERFIELD2 VALUE2 ... @@ -3780,10 +3815,10 @@ CSV balance-type Balance assertions generated by assigning to balanceN are of the simple - = type by default, which is a single-commodity, subaccount-excluding + = type by default, which is a single-commodity, subaccount-excluding assertion. You may find the subaccount-including variants more useful, - eg if you have created some virtual subaccounts of checking to help - with budgeting. You can select a different type of assertion with the + eg if you have created some virtual subaccounts of checking to help + with budgeting. You can select a different type of assertion with the balance-type rule: # balance assertions will consider all commodities and all subaccounts @@ -3799,9 +3834,9 @@ CSV include include RULESFILE - This includes the contents of another CSV rules file at this point. - RULESFILE is an absolute file path or a path relative to the current - file's directory. This can be useful for sharing common rules between + This includes the contents of another CSV rules file at this point. + RULESFILE is an absolute file path or a path relative to the current + file's directory. This can be useful for sharing common rules between several rules files, eg: # someaccount.csv.rules @@ -3818,42 +3853,42 @@ CSV Some tips: Rapid feedback - It's a good idea to get rapid feedback while creating/troubleshooting + It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from eradman.com/entrproject: $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - A desc: query (eg) is used to select just one, or a few, transactions - of interest. "bash -c" is used to run multiple commands, so we can - echo a separator each time the command re-runs, making it easier to + A desc: query (eg) is used to select just one, or a few, transactions + of interest. "bash -c" is used to run multiple commands, so we can + echo a separator each time the command re-runs, making it easier to read the output. Valid CSV - Note that hledger will only accept valid CSV conforming to RFC 4180, + Note that hledger will only accept valid CSV conforming to RFC 4180, and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab as separators). This means, eg: o Values may be enclosed in double quotes, or not. Enclosing in single quotes is not allowed. (Eg 'A','B' is rejected.) - o When values are enclosed in double quotes, spaces outside the quotes + o When values are enclosed in double quotes, spaces outside the quotes are not allowed. (Eg "A", "B" is rejected.) - o When values are not enclosed in quotes, they may not contain double + o When values are not enclosed in quotes, they may not contain double quotes. (Eg A"A, B is rejected.) - If your CSV/SSV/TSV is not valid in this sense, you'll need to trans- - form it before reading with hledger. Try using sed, or a more permis- + If your CSV/SSV/TSV is not valid in this sense, you'll need to trans- + form it before reading with hledger. Try using sed, or a more permis- sive CSV parser like python's csv lib. File Extension - To help hledger choose the CSV file reader and show the right error - messages (and choose the right field separator character by default), - it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv + To help hledger choose the CSV file reader and show the right error + messages (and choose the right field separator character by default), + it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv filename extension. (More about this at Data formats.) - When reading files with the "wrong" extension, you can ensure the CSV - reader (and the default field separator) by prefixing the file path + When reading files with the "wrong" extension, you can ensure the CSV + reader (and the default field separator) by prefixing the file path with csv:, ssv: or tsv:: Eg: $ hledger -f ssv:foo.dat print @@ -3862,29 +3897,29 @@ CSV if needed. Reading CSV from standard input - You'll need the file format prefix when reading CSV from stdin also, + You'll need the file format prefix when reading CSV from stdin also, since hledger assumes journal format by default. Eg: $ cat foo.dat | hledger -f ssv:- print Reading multiple CSV files - If you use multiple -f options to read multiple CSV files at once, - hledger will look for a correspondingly-named rules file for each CSV - file. But if you specify a rules file with --rules, that rules file + If you use multiple -f options to read multiple CSV files at once, + hledger will look for a correspondingly-named rules file for each CSV + file. But if you specify a rules file with --rules, that rules file will be used for all the CSV files. Reading files specified by rule Instead of specifying a CSV file in the command line, you can specify a - rules file, as in hledger -f foo.csv.rules CMD. By default this will - read data from foo.csv in the same directory, but you can add a source - rule to specify a different data file, perhaps located in your web + rules file, as in hledger -f foo.csv.rules CMD. By default this will + read data from foo.csv in the same directory, but you can add a source + rule to specify a different data file, perhaps located in your web browser's download directory. This feature was added in hledger 1.30, so you won't see it in most CSV - rules examples. But it helps remove some of the busywork of managing + rules examples. But it helps remove some of the busywork of managing CSV downloads. Most of your financial institutions's default CSV file- - names are different and can be recognised by a glob pattern. So you - can put a rule like source Checking1*.csv in foo-checking.csv.rules, + names are different and can be recognised by a glob pattern. So you + can put a rule like source Checking1*.csv in foo-checking.csv.rules, and then periodically follow a workflow like: 1. Download CSV from Foo's website, using your browser's defaults @@ -3892,45 +3927,45 @@ CSV 2. Run hledger import foo-checking.csv.rules to import any new transac- tions - After import, you can: discard the CSV, or leave it where it is for a - while, or move it into your archives, as you prefer. If you do noth- - ing, next time your browser will save something like Checking1-2.csv, - and hledger will use that because of the * wild card and because it is + After import, you can: discard the CSV, or leave it where it is for a + while, or move it into your archives, as you prefer. If you do noth- + ing, next time your browser will save something like Checking1-2.csv, + and hledger will use that because of the * wild card and because it is the most recent. Valid transactions After reading a CSV file, hledger post-processes and validates the gen- erated journal entries as it would for a journal file - balancing them, - applying balance assignments, and canonicalising amount styles. Any - errors at this stage will be reported in the usual way, displaying the + applying balance assignments, and canonicalising amount styles. Any + errors at this stage will be reported in the usual way, displaying the problem entry. There is one exception: balance assertions, if you have generated them, - will not be checked, since normally these will work only when the CSV - data is part of the main journal. If you do need to check balance as- + will not be checked, since normally these will work only when the CSV + data is part of the main journal. If you do need to check balance as- sertions generated from CSV right away, pipe into another hledger: $ hledger -f file.csv print | hledger -f- print Deduplicating, importing - When you download a CSV file periodically, eg to get your latest bank - transactions, the new file may overlap with the old one, containing + When you download a CSV file periodically, eg to get your latest bank + transactions, the new file may overlap with the old one, containing some of the same records. The import command will (a) detect the new transactions, and (b) append just those transactions to your main journal. It is idempotent, so you - don't have to remember how many times you ran it or with which version - of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This + don't have to remember how many times you ran it or with which version + of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This is the easiest way to import CSV data. Eg: # download the latest CSV files, then run this command. # Note, no -f flags needed here. $ hledger import *.csv [--dry] - This method works for most CSV files. (Where records have a stable + This method works for most CSV files. (Where records have a stable chronological order, and new records appear only at the new end.) - A number of other tools and workflows, hledger-specific and otherwise, + A number of other tools and workflows, hledger-specific and otherwise, exist for converting, deduplicating, classifying and managing CSV data. See: @@ -3939,16 +3974,16 @@ CSV o https://plaintextaccounting.org -> data import/conversion Setting amounts - Continuing from amount field above, here are more tips for amount-set- + Continuing from amount field above, here are more tips for amount-set- ting: 1. If the amount is in a single CSV field: a. If its sign indicates direction of flow: - Assign it to amountN, to set the Nth posting's amount. N is usu- + Assign it to amountN, to set the Nth posting's amount. N is usu- ally 1 or 2 but can go up to 99. b. If another field indicates direction of flow: - Use one or more conditional rules to set the appropriate amount + Use one or more conditional rules to set the appropriate amount sign. Eg: # assume a withdrawal unless Type contains "deposit": @@ -3956,15 +3991,15 @@ CSV if %Type deposit amount1 %Amount - 2. If the amount is in two CSV fields (such as Debit and Credit, or In + 2. If the amount is in two CSV fields (such as Debit and Credit, or In and Out): a. If both fields are unsigned: - Assign one field to amountN-in and the other to amountN-out. - hledger will automatically negate the "out" field, and will use + Assign one field to amountN-in and the other to amountN-out. + hledger will automatically negate the "out" field, and will use whichever field value is non-zero as posting N's amount. b. If either field is signed: - You will probably need to override hledger's sign for one or the + You will probably need to override hledger's sign for one or the other field, as in the following example: # Negate the -out value, but only if it is not empty: @@ -3972,12 +4007,12 @@ CSV if %amount1-out [1-9] amount1-out -%amount1-out - c. If both fields can contain a non-zero value (or both can be + c. If both fields can contain a non-zero value (or both can be empty): - The -in/-out rules normally choose the value which is - non-zero/non-empty. Some value pairs can be ambiguous, such as 1 + The -in/-out rules normally choose the value which is + non-zero/non-empty. Some value pairs can be ambiguous, such as 1 and none. For such cases, use conditional rules to help select the - amount. Eg, to handle the above you could select the value con- + amount. Eg, to handle the above you could select the value con- taining non-zero digits: fields date, description, in, out @@ -3990,8 +4025,8 @@ CSV Use the unnumbered amount (or amount-in and amount-out) syntax. 4. If the CSV has only balance amounts, not transaction amounts: - Assign to balanceN, to set a balance assignment on the Nth posting, - causing the posting's amount to be calculated automatically. balance + Assign to balanceN, to set a balance assignment on the Nth posting, + causing the posting's amount to be calculated automatically. balance with no number is equivalent to balance1. In this situation hledger is more likely to guess the wrong default account name, so you may need to set that explicitly. @@ -4007,20 +4042,20 @@ CSV o If an amount value is parenthesised: it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT - o If an amount value has two minus signs (or two sets of parentheses, + o If an amount value has two minus signs (or two sets of parentheses, or a minus sign and parentheses): they cancel out and will be removed: --AMT or -(AMT) becomes AMT - o If an amount value contains just a sign (or just a set of parenthe- + o If an amount value contains just a sign (or just a set of parenthe- ses): - that is removed, making it an empty value. "+" or "-" or "()" becomes + that is removed, making it an empty value. "+" or "-" or "()" becomes "". - It's not possible (without preprocessing the CSV) to set an amount to + It's not possible (without preprocessing the CSV) to set an amount to its absolute value, ie discard its sign. Setting currency/commodity - If the currency/commodity symbol is included in the CSV's amount + If the currency/commodity symbol is included in the CSV's amount field(s): 2023-01-01,foo,$123.00 @@ -4039,7 +4074,7 @@ CSV 2023-01-01,foo,USD,123.00 You can assign that to the currency pseudo-field, which has the special - effect of prepending itself to every amount in the transaction (on the + effect of prepending itself to every amount in the transaction (on the left, with no separating space): fields date,description,currency,amount @@ -4048,7 +4083,7 @@ CSV expenses:unknown USD123.00 income:unknown USD-123.00 - Or, you can use a field assignment to construct the amount yourself, + Or, you can use a field assignment to construct the amount yourself, with more control. Eg to put the symbol on the right, and separated by a space: @@ -4059,38 +4094,38 @@ CSV expenses:unknown 123.00 USD income:unknown -123.00 USD - Note we used a temporary field name (cur) that is not currency - that + Note we used a temporary field name (cur) that is not currency - that would trigger the prepending effect, which we don't want here. Amount decimal places - When you are reading CSV data, eg with a command like hledger -f - foo.csv print, hledger will infer each commodity's decimal precision - (and other commodity display styles) from the amounts - much as when + When you are reading CSV data, eg with a command like hledger -f + foo.csv print, hledger will infer each commodity's decimal precision + (and other commodity display styles) from the amounts - much as when reading a journal file without commodity directives (see the link). - Note, the commodity styles are not inferred from the numbers in the + Note, the commodity styles are not inferred from the numbers in the original CSV data; rather, they are inferred from the amounts generated by the CSV rules. When you are importing CSV data with the import command, eg hledger im- - port foo.csv, there's another step: import tries to make the new en- - tries conform to the journal's existing styles. So for each commodity + port foo.csv, there's another step: import tries to make the new en- + tries conform to the journal's existing styles. So for each commodity - let's say it's EUR - import will choose: 1. the style declared for EUR by a commodity directive in the journal 2. otherwise, the style inferred from EUR amounts in the journal - 3. otherwise, the style inferred from EUR amounts generated by the CSV + 3. otherwise, the style inferred from EUR amounts generated by the CSV rules. - TLDR: if import is not generating the precisions or styles you want, + TLDR: if import is not generating the precisions or styles you want, add a commodity directive to specify them. Referencing other fields - In field assignments, you can interpolate only CSV fields, not hledger - fields. In the example below, there's both a CSV field and a hledger - field named amount1, but %amount1 always means the CSV field, not the + In field assignments, you can interpolate only CSV fields, not hledger + fields. In the example below, there's both a CSV field and a hledger + field named amount1, but %amount1 always means the CSV field, not the hledger field: # Name the third CSV field "amount1" @@ -4102,7 +4137,7 @@ CSV # Set comment to the CSV amount1 (not the amount1 assigned above) comment %amount1 - Here, since there's no CSV amount1 field, %amount1 will produce a lit- + Here, since there's no CSV amount1 field, %amount1 will produce a lit- eral "amount1": fields date,description,csvamount @@ -4110,7 +4145,7 @@ CSV # Can't interpolate amount1 here comment %amount1 - When there are multiple field assignments to the same hledger field, + When there are multiple field assignments to the same hledger field, only the last one takes effect. Here, comment's value will be be B, or C if "something" is matched, but never A: @@ -4120,14 +4155,14 @@ CSV comment C How CSV rules are evaluated - Here's how to think of CSV rules being evaluated (if you really need + Here's how to think of CSV rules being evaluated (if you really need to). First, - o include - all includes are inlined, from top to bottom, depth first. - (At each include point the file is inlined and scanned for further + o include - all includes are inlined, from top to bottom, depth first. + (At each include point the file is inlined and scanned for further includes, recursively, before proceeding.) - Then "global" rules are evaluated, top to bottom. If a rule is re- + Then "global" rules are evaluated, top to bottom. If a rule is re- peated, the last one wins: o skip (at top level) @@ -4141,30 +4176,30 @@ CSV Then for each CSV record in turn: - o test all if blocks. If any of them contain a end rule, skip all re- - maining CSV records. Otherwise if any of them contain a skip rule, - skip that many CSV records. If there are multiple matched skip + o test all if blocks. If any of them contain a end rule, skip all re- + maining CSV records. Otherwise if any of them contain a skip rule, + skip that many CSV records. If there are multiple matched skip rules, the first one wins. - o collect all field assignments at top level and in matched if blocks. - When there are multiple assignments for a field, keep only the last + o collect all field assignments at top level and in matched if blocks. + When there are multiple assignments for a field, keep only the last one. - o compute a value for each hledger field - either the one that was as- + o compute a value for each hledger field - either the one that was as- signed to it (and interpolate the %CSVFIELD references), or a default o generate a hledger transaction (journal entry) from these values. - This is all part of the CSV reader, one of several readers hledger can - use to parse input files. When all files have been read successfully, - the transactions are passed as input to whichever hledger command the + This is all part of the CSV reader, one of several readers hledger can + use to parse input files. When all files have been read successfully, + the transactions are passed as input to whichever hledger command the user specified. Well factored rules - Some things than can help reduce duplication and complexity in rules + Some things than can help reduce duplication and complexity in rules files: - o Extracting common rules usable with multiple CSV files into a com- + o Extracting common rules usable with multiple CSV files into a com- mon.rules, and adding include common.rules to each CSV's rules file. o Splitting if blocks into smaller if blocks, extracting the frequently @@ -4172,8 +4207,8 @@ CSV CSV rules examples Bank of Ireland - Here's a CSV with two amount fields (Debit and Credit), and a balance - field, which we can use to add balance assertions, which is not neces- + Here's a CSV with two amount fields (Debit and Credit), and a balance + field, which we can use to add balance assertions, which is not neces- sary but provides extra error checking: Date,Details,Debit,Credit,Balance @@ -4215,13 +4250,13 @@ CSV assets:bank:boi:checking EUR-5.0 = EUR126.0 expenses:unknown EUR5.0 - The balance assertions don't raise an error above, because we're read- - ing directly from CSV, but they will be checked if these entries are + The balance assertions don't raise an error above, because we're read- + ing directly from CSV, but they will be checked if these entries are imported into a journal file. Coinbase - A simple example with some CSV from Coinbase. The spot price is - recorded using cost notation. The legacy amount field name conve- + A simple example with some CSV from Coinbase. The spot price is + recorded using cost notation. The legacy amount field name conve- niently sets amount 2 (posting 2's amount) to the total cost. # Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes @@ -4243,7 +4278,7 @@ CSV Amazon Here we convert amazon.com order history, and use an if block to gener- - ate a third posting if there's a fee. (In practice you'd probably get + ate a third posting if there's a fee. (In practice you'd probably get this data from your bank instead, but it's an example.) "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" @@ -4295,7 +4330,7 @@ CSV expenses:fees $1.00 Paypal - Here's a real-world rules file for (customised) Paypal CSV, with some + Here's a real-world rules file for (customised) Paypal CSV, with some Paypal-specific rules, and a second rules file included: "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" @@ -4446,12 +4481,12 @@ CSV Timeclock The time logging format of timeclock.el, as read by hledger. - hledger can read time logs in timeclock format. As with Ledger, these - are (a subset of) timeclock.el's format, containing clock-in and - clock-out entries as in the example below. The date is a simple date. - The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are op- - tional. The timezone, if present, must be four digits and is ignored - (currently the time is always interpreted as a local time). Lines be- + hledger can read time logs in timeclock format. As with Ledger, these + are (a subset of) timeclock.el's format, containing clock-in and + clock-out entries as in the example below. The date is a simple date. + The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are op- + tional. The timezone, if present, must be four digits and is ignored + (currently the time is always interpreted as a local time). Lines be- ginning with # or ; or *, and blank lines, are ignored. i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags: @@ -4459,9 +4494,9 @@ Timeclock i 2015/03/31 22:21:45 another:account o 2015/04/01 02:00:34 - hledger treats each clock-in/clock-out pair as a transaction posting - some number of hours to an account. Or if the session spans more than - one day, it is split into several transactions, one for each day. For + hledger treats each clock-in/clock-out pair as a transaction posting + some number of hours to an account. Or if the session spans more than + one day, it is split into several transactions, one for each day. For the above time log, hledger print generates these journal entries: $ hledger -f t.timeclock print @@ -4491,13 +4526,13 @@ Timeclock perhaps the extras in ledgerutils.el o or use the old ti and to scripts in the ledger 2.x repository. These - rely on a "timeclock" executable which I think is just the ledger 2 + rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. Timedot - timedot format is hledger's human-friendly time logging format. Com- - pared to timeclock format, it is more convenient for quick, approxi- - mate, and retroactive time logging, and more human-readable (you can + timedot format is hledger's human-friendly time logging format. Com- + pared to timeclock format, it is more convenient for quick, approxi- + mate, and retroactive time logging, and more human-readable (you can see at a glance where time was spent). A quick example: 2023-05-01 @@ -4516,59 +4551,59 @@ Timedot (per:admin:finance) 0 A timedot file contains a series of transactions (usually one per day). - Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be + Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be followed on the same line by a transaction description, and/or a trans- action comment following a semicolon. After the date line are zero or more time postings, consisting of: - o An account name - any hledger-style account name, optionally in- + o An account name - any hledger-style account name, optionally in- dented. - o Two or more spaces - required if there is an amount (as in journal + o Two or more spaces - required if there is an amount (as in journal format). o A timedot amount, which can be o empty (representing zero) - o a number, optionally followed by a unit s, m, h, d, w, mo, or y, - representing a precise number of seconds, minutes, hours, days + o a number, optionally followed by a unit s, m, h, d, w, mo, or y, + representing a precise number of seconds, minutes, hours, days weeks, months or years (hours is assumed by default), which will be - converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = + converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. - o one or more dots (period characters), each representing 0.25. - These are the dots in "timedot". Spaces are ignored and can be + o one or more dots (period characters), each representing 0.25. + These are the dots in "timedot". Spaces are ignored and can be used for grouping/alignment. - o Added in 1.32 one or more letters. These are like dots but they - also generate a tag t: (short for "type") with the letter as its - value, and a separate posting for each of the values. This pro- - vides a second dimension of categorisation, viewable in reports + o Added in 1.32 one or more letters. These are like dots but they + also generate a tag t: (short for "type") with the letter as its + value, and a separate posting for each of the values. This pro- + 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). - There is some flexibility to help with keeping time log data and notes + There is some flexibility to help with keeping time log data and notes in the same file: o Blank lines and lines beginning with # or ; are ignored. - o After the first date line, lines which do not contain a double space + o After the first date line, lines which do not contain a double space are parsed as postings with zero amount. (hledger's register reports will show these if you add -E). - o Before the first date line, lines beginning with * (eg org headings) - are ignored. And from the first date line onward, Emacs org mode + o Before the first date line, lines beginning with * (eg org headings) + are ignored. And from the first date line onward, Emacs org mode heading prefixes at the start of lines (one or more *'s followed by a - space) will be ignored. This means the time log can also be a org + space) will be ignored. This means the time log can also be a org outline. Timedot files don't support directives like journal files. So a common - pattern is to have a main journal file (eg time.journal) that contains - any needed directives, and then includes the timedot file (include + pattern is to have a main journal file (eg time.journal) that contains + any needed directives, and then includes the timedot file (include time.timedot). Timedot examples @@ -4676,21 +4711,21 @@ Timedot PART 3: REPORTING CONCEPTS Time periods Report start & end date - Most hledger reports will by default show the full time period repre- - sented by the journal. The report start date will be the earliest + Most hledger reports will by default show the full time period repre- + sented by the journal. The report start date will be the earliest transaction or posting date, and the report end date will be the latest transaction, posting, or market price date. Often you will want to see a shorter period, such as the current month. - You can specify a start and/or end date with the -b/--begin, -e/--end, - or -p/--period options, or a date: query argument, described below. + You can specify a start and/or end date with the -b/--begin, -e/--end, + or -p/--period options, or a date: query argument, described below. All of these accept the smart date syntax, also described below. End dates are exclusive; specify the day after the last day you want to see in the report. When dates are specified by multiple options, the last (right-most) op- - tion wins. And when date: queries and date options are combined, the + tion wins. And when date: queries and date options are combined, the report period will be their intersection. Examples: @@ -4718,17 +4753,17 @@ Time periods -b and -e) Smart dates - In hledger's user interfaces (though not in the journal file), you can - optionally use "smart date" syntax. Smart dates can be written with - english words, can be relative, and can have parts omitted. Missing - parts are inferred as 1, when needed. Smart dates can be interpreted + In hledger's user interfaces (though not in the journal file), you can + optionally use "smart date" syntax. Smart dates can be written with + english words, can be relative, and can have parts omitted. Missing + parts are inferred as 1, when needed. Smart dates can be interpreted as dates or periods depending on context. Examples: 2004-01-01, 2004/10/1, 2004.9.1, 20240504 : - Exact dates. The year must have at least four digits, the month must - be 1-12, the day must be 1-31, the separator can be - or / or . or + Exact dates. The year must have at least four digits, the month must + be 1-12, the day must be 1-31, the separator can be - or / or . or nothing. 2004-10 @@ -4761,7 +4796,7 @@ Time periods 201812 6 digit YYYYMM with valid year and month - Dates with no separators are allowed but might give surprising results + Dates with no separators are allowed but might give surprising results if mistyped: o 20181301 (YYYYMMDD with an invalid month) is parsed as an eight-digit @@ -4769,20 +4804,20 @@ Time periods o 20181232 (YYYYMMDD with an invalid day) gives a parse error - o 201801012 (a valid YYYYMMDD followed by additional digits) gives a + o 201801012 (a valid YYYYMMDD followed by additional digits) gives a parse error - The meaning of relative dates depends on today's date. If you need to - test or reproduce old reports, you can use the --today option to over- - ride that. (Except for periodic transaction rules, which are not af- + The meaning of relative dates depends on today's date. If you need to + test or reproduce old reports, you can use the --today option to over- + ride that. (Except for periodic transaction rules, which are not af- fected by --today.) Report intervals - A report interval can be specified so that reports like register, bal- + A report interval can be specified so that reports like register, bal- ance or activity become multi-period, showing each subperiod as a sepa- rate row or column. - The following standard intervals can be enabled with command-line + The following standard intervals can be enabled with command-line flags: o -D/--daily @@ -4795,7 +4830,7 @@ Time periods o -Y/--yearly - More complex intervals can be specified using -p/--period, described + More complex intervals can be specified using -p/--period, described below. Date adjustments @@ -4806,17 +4841,17 @@ Time periods For example, if the journal's first transaction is on january 10th, - o hledger register (no report interval) will start the report on janu- + o hledger register (no report interval) will start the report on janu- ary 10th. - o hledger register --monthly will start the report on the previous + o hledger register --monthly will start the report on the previous month boundary, january 1st. o hledger register --monthly --begin 1/5 will start the report on janu- ary 5th [1]. - Also if you are generating transactions or budget goals with periodic - transaction rules, their start date may be adjusted in a similar way + Also if you are generating transactions or budget goals with periodic + transaction rules, their start date may be adjusted in a similar way (in certain situations). End date adjustment @@ -4827,7 +4862,7 @@ Time periods o hledger register will end the report on february 20th. - o hledger register --monthly will end the report at the end of febru- + o hledger register --monthly will end the report at the end of febru- ary. o hledger register --monthly --end 2/14 also will end the report at the @@ -4839,40 +4874,40 @@ Time periods [1] Since hledger 1.29. Period headings - With non-standard subperiods, hledger will show "STARTDATE..ENDDATE" + With non-standard subperiods, hledger will show "STARTDATE..ENDDATE" headings. With standard subperiods (ie, starting on a natural interval - boundary), you'll see more compact headings, which are usually prefer- + boundary), you'll see more compact headings, which are usually prefer- able. (Though month names will be in english, currently.) - So if you are specifying a start date and you want compact headings: + So if you are specifying a start date and you want compact headings: choose a start of year for yearly reports, a start of quarter for quar- - terly reports, a start of month for monthly reports, etc. (Remember, - you can write eg -b 2024 or 1/1 as a shortcut for a start of year, or + terly reports, a start of month for monthly reports, etc. (Remember, + you can write eg -b 2024 or 1/1 as a shortcut for a start of year, or 2024-04 or 202404 or Apr for a start of month or quarter.) - For weekly reports, choose a date that's a Monday. (You can try dif- - ferent dates until you see the short headings, or write eg -b '3 weeks + For weekly reports, choose a date that's a Monday. (You can try dif- + ferent dates until you see the short headings, or write eg -b '3 weeks ago'.) Period expressions - The -p/--period option specifies a period expression, which is a com- + The -p/--period option specifies a period expression, which is a com- pact way of expressing a start date, end date, and/or report interval. - Here's a period expression with a start and end date (specifying the + Here's a period expression with a start and end date (specifying the first quarter of 2009): -p "from 2009/1/1 to 2009/4/1" - Several keywords like "from" and "to" are supported for readability; - these are optional. "to" can also be written as ".." or "-". The - spaces are also optional, as long as you don't run two dates together. + Several keywords like "from" and "to" are supported for readability; + these are optional. "to" can also be written as ".." or "-". The + spaces are also optional, as long as you don't run two dates together. So the following are equivalent to the above: -p "2009/1/1 2009/4/1" -p2009/1/1to2009/4/1 -p2009/1/1..2009/4/1 - Dates are smart dates, so if the current year is 2009, these are also + Dates are smart dates, so if the current year is 2009, these are also equivalent to the above: -p "1/1 4/1" @@ -4884,28 +4919,28 @@ Time periods -p "from 2009/1/1" everything after january 1, 2009 - -p "since 2009/1" the same, since is a syn- + -p "since 2009/1" the same, since is a syn- onym -p "from 2009" the same - -p "to 2009" everything before january + -p "to 2009" everything before january 1, 2009 You can also specify a period by writing a single partial or full date: -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of january 2009; equivalent to "2009/1/1 to + -p "2009/1" the month of january 2009; equivalent to "2009/1/1 to 2009/2/1" - -p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to + -p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to 2009/1/2" or by using the "Q" quarter-year syntax (case insensitive): - -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to + -p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to 2009/4/1" -p "q4" fourth quarter of the current year Period expressions with a report interval - A period expression can also begin with a report interval, separated + A period expression can also begin with a report interval, separated from the start/end dates (if any) by a space or the word in: -p "weekly from 2009/1/1 to 2009/4/1" @@ -4928,15 +4963,15 @@ Time periods Weekly on a custom day: - o every Nth day of week (th, nd, rd, or st are all accepted after the + o every Nth day of week (th, nd, rd, or st are all accepted after the number) - o every WEEKDAYNAME (full or three-letter english weekday name, case + o every WEEKDAYNAME (full or three-letter english weekday name, case insensitive) Monthly on a custom day: - o every Nth day [of month] (31st day will be adjusted to each month's + o every Nth day [of month] (31st day will be adjusted to each month's last day) o every Nth WEEKDAYNAME [of month] @@ -4945,7 +4980,7 @@ Time periods o every MM/DD [of year] (month number and day of month number) - o every MONTHNAME DDth [of year] (full or three-letter english month + o every MONTHNAME DDth [of year] (full or three-letter english month name, case insensitive, and day of month number) o every DDth MONTHNAME [of year] (equivalent to the above) @@ -4958,21 +4993,21 @@ Time periods 2009/03" -p "every 2nd day of week" periods will go from Tue to Tue -p "every Tue" same - -p "every 15th day" period boundaries will be on 15th of each + -p "every 15th day" period boundaries will be on 15th of each month - -p "every 2nd Monday" period boundaries will be on second Monday + -p "every 2nd Monday" period boundaries will be on second Monday of each month - -p "every 11/05" yearly periods with boundaries on 5th of + -p "every 11/05" yearly periods with boundaries on 5th of November -p "every 5th November" same -p "every Nov 5th" same - Show historical balances at end of the 15th day of each month (N is an + Show historical balances at end of the 15th day of each month (N is an end date, exclusive as always): $ hledger balance -H -p "every 16th day" - Group postings from the start of wednesday to end of the following + Group postings from the start of wednesday to end of the following tuesday (N is both (inclusive) start date and (exclusive) end date): $ hledger register checking -p "every 3rd day of week" @@ -4983,10 +5018,10 @@ Time periods o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week- day names, case insensitive) - Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and + Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and sat,sun. - This is mainly intended for use with --forecast, to generate periodic + This is mainly intended for use with --forecast, to generate periodic transactions on arbitrary days of the week. It may be less useful with -p, since it divides each week into subperiods of unequal length, which is unusual. (Related: #1632) @@ -4995,32 +5030,32 @@ Time periods -p "every dates will be Mon, Wed, Fri; periods will be mon,wed,fri" Mon-Tue, Wed-Thu, Fri-Sun - -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will + -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will be Mon, Tue, Wed, Thu, Fri-Sun -p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri day" Depth - With the --depth NUM option (short form: -NUM), reports will show ac- - counts only to the specified depth, hiding deeper subaccounts. Use - this when you want a summary with less detail. This flag has the same + With the --depth NUM option (short form: -NUM), reports will show ac- + counts only to the specified depth, hiding deeper subaccounts. Use + this when you want a summary with less detail. This flag has the same effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva- lent. - In place of a single number which limits the depth for all accounts, + In place of a single number which limits the depth for all accounts, you can also provide separate depth limits for different accounts using regular expressions (since 1.41). - For example, --depth assets=2 (or, equivalently: depth:assets=2) will - collapse accounts matching the regular expression assets to depth 2. + For example, --depth assets=2 (or, equivalently: depth:assets=2) will + collapse accounts matching the regular expression assets to depth 2. So assets:bank:savings would be collapsed to assets:bank, while liabil- - ities:bank:credit card would not be affected. This can be combined - with a flat depth to collapse other accounts not matching the regular - expression, so --depth assets=2 --depth 1 would collapse as- - sets:bank:savings to assets:bank and liabilities:bank:credit card to + ities:bank:credit card would not be affected. This can be combined + with a flat depth to collapse other accounts not matching the regular + expression, so --depth assets=2 --depth 1 would collapse as- + sets:bank:savings to assets:bank and liabilities:bank:credit card to liabilities. - You can supply multiple depth arguments and they will all be applied, + You can supply multiple depth arguments and they will all be applied, so --depth assets=2 --depth liabilities=3 --depth 1 would collapse: o accounts matching assets to depth 2, @@ -5029,31 +5064,31 @@ Depth o all other accounts to depth 1. - If an account is matched by more than one regular expression depth ar- - gument then the more specific one will used. For example, if --depth - assets=1 --depth assets:bank:savings=2 is provided, then as- - sets:bank:savings will be collapsed to depth 2 rather than depth 1. - This is because assets:bank:savings matches at level 3 in the account + If an account is matched by more than one regular expression depth ar- + gument then the more specific one will used. For example, if --depth + assets=1 --depth assets:bank:savings=2 is provided, then as- + sets:bank:savings will be collapsed to depth 2 rather than depth 1. + This is because assets:bank:savings matches at level 3 in the account name, while assets matches at level 1. The same would be true with the argument --depth assets=1 --depth savings=2. Queries One of hledger's strengths is being able to quickly report on a precise - subset of your data. Most hledger commands accept query arguments, to + subset of your data. Most hledger commands accept query arguments, to restrict their scope. Multiple query terms can be provided to build up a more complex query. - o By default, a query term is interpreted as a case-insensitive sub- + o By default, a query term is interpreted as a case-insensitive sub- string pattern for matching account names: car:fuel dining groceries - o Patterns containing spaces or other special characters must be en- + o Patterns containing spaces or other special characters must be en- closed in single or double quotes: 'personal care' - o These patterns are actually regular expressions, so you can add reg- - exp metacharacters for more precision (see "Regular expressions" + o These patterns are actually regular expressions, so you can add reg- + exp metacharacters for more precision (see "Regular expressions" above for details): '^expenses\b' @@ -5074,15 +5109,15 @@ Queries not:status:'*' not:desc:'opening|closing' not:cur:USD - o Terms with different types are AND-ed, terms with the same type are - OR-ed (mostly; see "Combining query terms" below). The following + o Terms with different types are AND-ed, terms with the same type are + OR-ed (mostly; see "Combining query terms" below). The following query: date:2022 desc:amazon desc:amzn is interpreted as: - date is in 2022 AND ( transaction description contains "amazon" OR + date is in 2022 AND ( transaction description contains "amazon" OR "amzn" ) Query types @@ -5090,19 +5125,19 @@ Queries acct: query acct:REGEX, or just REGEX - Match account names containing this case insensitive regular expres- + Match account names containing this case insensitive regular expres- sion. - This is the default query type, so we usually don't bother writing the + This is the default query type, so we usually don't bother writing the "acct:" prefix. amt: query amt:N, amt:'N', amt:'>=N' - Match postings with a single-commodity amount equal to, less than, or - greater than N. (Postings with multi-commodity amounts are not tested + Match postings with a single-commodity amount equal to, less than, or + greater than N. (Postings with multi-commodity amounts are not tested and will always match.) The comparison has two modes: if N is preceded - by a + or - sign (or is 0), the two signed numbers are compared. Oth- - erwise, the absolute magnitudes are compared, ignoring sign. amt: - needs quotes to hide the less than/greater than sign from the command + by a + or - sign (or is 0), the two signed numbers are compared. Oth- + erwise, the absolute magnitudes are compared, ignoring sign. amt: + needs quotes to hide the less than/greater than sign from the command line shell. code: query @@ -5113,10 +5148,10 @@ Queries cur:REGEX Match postings or transactions including any amounts whose cur- rency/commodity symbol is fully matched by REGEX. (Contrary to - hledger's usual infix matching. To do infix matching, write + hledger's usual infix matching. To do infix matching, write .*REGEX.*.) Note, to match special characters which are regex-signifi- - cant, you need to escape them with \. And for characters which are - significant to your shell you will usually need one more level of es- + cant, you need to escape them with \. And for characters which are + significant to your shell you will usually need one more level of es- caping. Eg to match the dollar sign: cur:\\$ or cur:'\$' desc: query @@ -5125,25 +5160,25 @@ Queries date: query date:PERIODEXPR - Match dates (or with the --date2 flag, secondary dates) within the + Match dates (or with the --date2 flag, secondary dates) within the specified period. PERIODEXPR is a period expression with no report in- terval. Examples: date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter. date2: query date2:PERIODEXPR - If you use secondary dates: this matches secondary dates within the + If you use secondary dates: this matches secondary dates within the specified period. It is not affected by the --date2 flag. depth: query depth:[REGEXP=]N - Match (or display, depending on command) accounts at or above this + Match (or display, depending on command) accounts at or above this depth, optionally only for accounts matching a provided regular expres- sion. See Depth for detailed rules. expr: query expr:'QUERYEXPR' - expr lets you write more complicated query expressions with AND, OR, + expr lets you write more complicated query expressions with AND, OR, NOT, and parentheses. Eg: expr:'date:lastmonth and not (food or rent)' The expression should be enclosed in quotes. See Combining query terms @@ -5153,7 +5188,7 @@ Queries not:QUERYTERM You can prepend not: to any other query term to negate the match. Eg: not:equity, not:desc:apple - (Also, a trick: not:not:... can sometimes solve query problems conve- + (Also, a trick: not:not:... can sometimes solve query problems conve- niently..) note: query @@ -5163,7 +5198,7 @@ Queries payee: query payee:REGEX - Match transaction payee/payer names (the part of the description left + Match transaction payee/payer names (the part of the description left of |, or the whole description if there's no |). real: query @@ -5176,18 +5211,18 @@ Queries type: query type:TYPECODES - Match by account type (see Declaring accounts > Account types). TYPE- - CODES is one or more of the single-letter account type codes ALERXCV, + Match by account type (see Declaring accounts > Account types). TYPE- + CODES is one or more of the single-letter account type codes ALERXCV, case insensitive. Note type:A and type:E will also match their respec- - tive subtypes C (Cash) and V (Conversion). Certain kinds of account - alias can disrupt account types, see Rewriting accounts > Aliases and + tive subtypes C (Cash) and V (Conversion). Certain kinds of account + alias can disrupt account types, see Rewriting accounts > Aliases and account types. tag: query tag:NAMEREGEX[=VALREGEX] Match by tag name, and optionally also by tag value. Note: - o Both regular expressions do infix matching. If you need a complete + o Both regular expressions do infix matching. If you need a complete match, use ^ and $. Eg: tag:'^fullname$', tag:'^fullname$=^fullvalue$ @@ -5201,7 +5236,7 @@ Queries o Transactions also acquire the tags of their postings. Combining query terms - When given multiple space-separated query terms, most commands select + When given multiple space-separated query terms, most commands select things which match: o any of the description terms AND @@ -5222,8 +5257,8 @@ Queries o match all the other terms. - We also support more complex boolean queries with the expr: prefix. - This allows one to combine query terms using and, or, not keywords + We also support more complex boolean queries with the expr: prefix. + This allows one to combine query terms using and, or, not keywords (case insensitive), and to group them by enclosing in parentheses. Some examples: @@ -5236,48 +5271,64 @@ Queries expr:"desc:cool and tag:A" (expr:"desc:cool tag:A" is equivalent) - o Match things which either do not reference the 'expenses:food' ac- + o Match things which either do not reference the 'expenses:food' ac- count, or do have the 'A' tag: expr:"not expenses:food or tag:A" - o Match things which either do not reference the 'expenses:food' ac- - count, or which reference the 'expenses:drink' account and also have + o Match things which either do not reference the 'expenses:food' ac- + count, or which reference the 'expenses:drink' account and also have the 'A' tag: expr:"expenses:food or (expenses:drink and tag:A)" - expr: has a restriction: date: queries may not be used inside or ex- + expr: has a restriction: date: queries may not be used inside or ex- pressions. That would allow disjoint report periods or disjoint result sets, with unclear semantics for our reports. Queries and command options - Some queries can also be expressed as command-line options: depth:2 is + Some queries can also be expressed as command-line options: depth:2 is equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When - you mix command options and query arguments, generally the resulting + you mix command options and query arguments, generally the resulting query is their intersection. Queries and account aliases - When account names are rewritten with --alias or alias, acct: will + When account names are rewritten with --alias or alias, acct: will match either the old or the new account name. Queries and valuation - When amounts are converted to other commodities in cost or value re- - ports, cur: and amt: match the old commodity symbol and the old amount + When amounts are converted to other commodities in cost or value re- + ports, cur: and amt: match the old commodity symbol and the old amount quantity, not the new ones. (Except in hledger 1.22, #1625.) Pivoting - Normally, hledger groups and sums amounts within each account. The - --pivot FIELD option substitutes some other transaction field for ac- - count names, causing amounts to be grouped and summed by that field's - value instead. FIELD can be any of the transaction fields acct, sta- - 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. + Normally, hledger groups amounts and displays their totals by account + (name). With --pivot PIVOTEXPR, some other field's (or multiple + fields') value is used as a synthetic account name, causing different + grouping and display. PIVOTEXPR can be - 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 assets:bank account 2 EUR @@ -5314,7 +5365,7 @@ Pivoting -------------------- -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 -2 EUR Lifetime:John Doe @@ -5664,15 +5715,15 @@ Cost reporting In some transactions - for example a currency conversion, or a purchase or sale of stock - one commodity is exchanged for another. In these transactions there is a conversion rate, also called the cost (when - buying) or selling price (when selling). In hledger docs we just say - "cost", for convenience; feel free to mentally translate to "conversion - rate" or "selling price" if helpful. + buying) or selling price (when selling). (In hledger docs we just say + "cost" generically for convenience.) With the -B/--cost flag, hledger + can show amounts "at cost", converted to the cost's commodity. Recording costs - We'll explore several ways of recording transactions involving costs. + We'll explore several ways of recording transactions involving costs. These are also summarised at hledger Cookbook > Cost notation. - Costs can be recorded explicitly in the journal, using the @ UNITCOST + Costs can be recorded explicitly in the journal, using the @ UNITCOST or @@ TOTALCOST notation described in Journal > Costs: Variant 1 @@ -5687,11 +5738,11 @@ Cost reporting assets:dollars $-135 assets:euros 100 @@ $135 ; $135 total cost - Typically, writing the unit cost (variant 1) is preferable; it can be + Typically, writing the unit cost (variant 1) is preferable; it can be more effort, requiring more attention to decimal digits; but it reveals the per-unit cost basis, and makes stock sales easier. - Costs can also be left implicit, and hledger will infer the cost that + Costs can also be left implicit, and hledger will infer the cost that is consistent with a balanced transaction: Variant 3 @@ -5700,49 +5751,49 @@ Cost reporting assets:dollars $-135 assets:euros 100 - Here, hledger will attach a @@ 100 cost to the first amount (you can - see it with hledger print -x). This form looks convenient, but there + Here, hledger will attach a @@ 100 cost to the first amount (you can + see it with hledger print -x). This form looks convenient, but there are downsides: - o It sacrifices some error checking. For example, if you accidentally + o It sacrifices some error checking. For example, if you accidentally wrote 10 instead of 100, hledger would not be able to detect the mis- take. - o It is sensitive to the order of postings - if they were reversed, a + o It is sensitive to the order of postings - if they were reversed, a different entry would be inferred and reports would be different. o The per-unit cost basis is not easy to read. - So generally this kind of entry is not recommended. You can make sure + So generally this kind of entry is not recommended. You can make sure you have none of these by using -s (strict mode), or by running hledger check balanced. Reporting at cost - Now when you add the -B/--cost flag to reports ("B" is from Ledger's - -B/--basis/--cost flag), any amounts which have been annotated with - costs will be converted to their cost's commodity (in the report out- + Now when you add the -B/--cost flag to reports ("B" is from Ledger's + -B/--basis/--cost flag), any amounts which have been annotated with + costs will be converted to their cost's commodity (in the report out- put). Ie they will be displayed "at cost" or "at sale price". Some things to note: - o Costs are attached to specific posting amounts in specific transac- - tions, and once recorded they do not change. This contrasts with + o Costs are attached to specific posting amounts in specific transac- + tions, and once recorded they do not change. This contrasts with market prices, which are ambient and fluctuating. - o Conversion to cost is performed before conversion to market value + o Conversion to cost is performed before conversion to market value (described below). Equity conversion postings - There is a problem with the entries above - they are not conventional - Double Entry Bookkeeping (DEB) notation, and because of the "magical" - transformation of one commodity into another, they cause an imbalance + There is a problem with the entries above - they are not conventional + Double Entry Bookkeeping (DEB) notation, and because of the "magical" + transformation of one commodity into another, they cause an imbalance in the Accounting Equation. This shows up as a non-zero grand total in balance reports like hledger bse. - For most hledger users, this doesn't matter in practice and can safely + For most hledger users, this doesn't matter in practice and can safely be ignored ! But if you'd like to learn more, keep reading. - Conventional DEB uses an extra pair of equity postings to balance the + Conventional DEB uses an extra pair of equity postings to balance the transaction. Of course you can do this in hledger as well: Variant 4 @@ -5753,10 +5804,10 @@ Cost reporting equity:conversion $135 equity:conversion -100 - Now the transaction is perfectly balanced according to standard DEB, + Now the transaction is perfectly balanced according to standard DEB, and hledger bse's total will not be disrupted. - And, hledger can still infer the cost for cost reporting, but it's not + And, hledger can still infer the cost for cost reporting, but it's not done by default - you must add the --infer-costs flag like so: $ hledger print --infer-costs @@ -5778,14 +5829,14 @@ Cost reporting o Instead of -B you must remember to type -B --infer-costs. - o --infer-costs works only where hledger can identify the two eq- - uity:conversion postings and match them up with the two non-equity - postings. So writing the journal entry in a particular format be- + o --infer-costs works only where hledger can identify the two eq- + uity:conversion postings and match them up with the two non-equity + postings. So writing the journal entry in a particular format be- comes more important. More on this below. Inferring equity conversion postings Can we go in the other direction ? Yes, if you have transactions writ- - ten with the @/@@ cost notation, hledger can infer the missing equity + ten with the @/@@ cost notation, hledger can infer the missing equity postings, if you add the --infer-equity flag. Eg: 2022-01-01 @@ -5799,18 +5850,18 @@ Cost reporting equity:conversion:$-: -100 equity:conversion:$-:$ $135.00 - The equity account names will be "equity:conversion:A-B:A" and "eq- - uity:conversion:A-B:B" where A is the alphabetically first commodity + The equity account names will be "equity:conversion:A-B:A" and "eq- + uity:conversion:A-B:B" where A is the alphabetically first commodity symbol. You can customise the "equity:conversion" part by declaring an account with the V/Conversion account type. - Note you will need to add account declarations for these to your jour- + Note you will need to add account declarations for these to your jour- nal, if you use check accounts or check --strict. Combining costs and equity conversion postings Finally, you can use both the @/@@ cost notation and equity postings at - the same time. This in theory gives the best of all worlds - preserv- - ing the accounting equation, revealing the per-unit cost basis, and + the same time. This in theory gives the best of all worlds - preserv- + ing the accounting equation, revealing the per-unit cost basis, and providing more flexibility in how you write the entry: Variant 5 @@ -5821,15 +5872,15 @@ Cost reporting equity:conversion -100 assets:euros 100 @ $1.35 - All the other variants above can (usually) be rewritten to this final + All the other variants above can (usually) be rewritten to this final form with: $ hledger print -x --infer-costs --infer-equity Downsides: - o The precise format of the journal entry becomes more important. If - hledger can't detect and match up the cost and equity postings, it + o The precise format of the journal entry becomes more important. If + hledger can't detect and match up the cost and equity postings, it will give a transaction balancing error. o The add command does not yet accept this kind of entry (#2056). @@ -5837,34 +5888,34 @@ Cost reporting o This is the most verbose form. Requirements for detecting equity conversion postings - --infer-costs has certain requirements (unlike --infer-equity, which + --infer-costs has certain requirements (unlike --infer-equity, which always works). It will infer costs only in transactions with: - o Two non-equity postings, in different commodities. Their order is + o Two non-equity postings, in different commodities. Their order is significant: the cost will be added to the first of them. - o Two postings to equity conversion accounts, next to one another, + o Two postings to equity conversion accounts, next to one another, which balance the two non-equity postings. This balancing is checked - to the same precision (number of decimal places) used in the conver- + to the same precision (number of decimal places) used in the conver- sion posting's amount. Equity conversion accounts are: o any accounts declared with account type V/Conversion, or their sub- accounts - o otherwise, accounts named equity:conversion, equity:trade, or eq- + o otherwise, accounts named equity:conversion, equity:trade, or eq- uity:trading, or their subaccounts. - And multiple such four-posting groups can coexist within a single - transaction. When --infer-costs fails, it does not infer a cost in - that transaction, and does not raise an error (ie, it infers costs + And multiple such four-posting groups can coexist within a single + transaction. When --infer-costs fails, it does not infer a cost in + that transaction, and does not raise an error (ie, it infers costs where it can). - Reading variant 5 journal entries, combining cost notation and equity - postings, has all the same requirements. When reading such an entry + Reading variant 5 journal entries, combining cost notation and equity + postings, has all the same requirements. When reading such an entry fails, hledger raises an "unbalanced transaction" error. Infer cost and equity by default ? - Should --infer-costs and --infer-equity be enabled by default ? Try + Should --infer-costs and --infer-equity be enabled by default ? Try using them always, eg with a shell alias: alias h="hledger --infer-equity --infer-costs" @@ -5872,101 +5923,104 @@ Cost reporting and let us know what problems you find. Value reporting - Instead of reporting amounts in their original commodity, hledger can - convert them to cost/sale amount (using the conversion rate recorded in - the transaction), and/or to market value (using some market price on a - certain date). This is controlled by the --value=TYPE[,COMMODITY] op- - tion, which will be described below. We also provide the simpler -V - and -X COMMODITY options, and often one of these is all you need: + hledger can also show amounts "at market value", converted to some + other commodity using the market price or conversion rate on a certain + date. + + This is controlled by the --value=TYPE[,COMMODITY] option. We also + 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 - The -V/--market flag converts amounts to market value in their default + The -V/--market flag converts amounts to market value in their default valuation commodity, using the market prices in effect on the valuation date(s), if any. More on these in a minute. -X: Value in specified commodity The -X/--exchange=COMM option is like -V, except you tell it which cur- - rency you want to convert to, and it tries to convert everything to + rency you want to convert to, and it tries to convert everything to that. Valuation date - Market prices can change from day to day. hledger will use the prices - on a particular valuation date (or on more than one date). By default + Market prices can change from day to day. hledger will use the prices + on a particular valuation date (or on more than one date). By default hledger uses "end" dates for valuation. More specifically: - o For single period reports (including normal print and register re- + o For single period reports (including normal print and register re- ports): o If an explicit report end date is specified, that is used - o Otherwise the latest transaction date or P directive date is used + o Otherwise the latest transaction date or P directive date is used (even if it's in the future) o For multiperiod reports, each period is valued on its last day. - This can be customised with the --value option described below, which + This can be customised with the --value option described below, which can select either "then", "end", "now", or "custom" dates. (Note, this has a bug in hledger-ui <=1.31: turning on valuation with the V key al- ways resets it to "end".) Finding market price - To convert a commodity A to its market value in another commodity B, - hledger looks for a suitable market price (exchange rate) as follows, + To convert a commodity A to its market value in another commodity B, + hledger looks for a suitable market price (exchange rate) as follows, in this order of preference: - 1. A declared market price or inferred market price: A's latest market + 1. A declared market price or inferred market price: A's latest market price in B on or before the valuation date as declared by a P direc- tive, or (with the --infer-market-prices flag) inferred from costs. 2. A reverse market price: the inverse of a declared or inferred market price from B to A. - 3. A forward chain of market prices: a synthetic price formed by com- + 3. A forward chain of market prices: a synthetic price formed by com- bining the shortest chain of "forward" (only 1 above) market prices, leading from A to B. - 4. Any chain of market prices: a chain of any market prices, including - both forward and reverse prices (1 and 2 above), leading from A to + 4. Any chain of market prices: a chain of any market prices, including + both forward and reverse prices (1 and 2 above), leading from A to B. - There is a limit to the length of these price chains; if hledger - reaches that length without finding a complete chain or exhausting all - possibilities, it will give up (with a "gave up" message visible in + There is a limit to the length of these price chains; if hledger + reaches that length without finding a complete chain or exhausting all + possibilities, it will give up (with a "gave up" message visible in --debug=2 output). That limit is currently 1000. - Amounts for which no suitable market price can be found, are not con- + Amounts for which no suitable market price can be found, are not con- verted. --infer-market-prices: market prices from transactions Normally, market value in hledger is fully controlled by, and requires, P directives in your journal. Since adding and updating those can be a - chore, and since transactions usually take place at close to market - value, why not use the recorded costs as additional market prices (as - Ledger does) ? Adding the --infer-market-prices flag to -V, -X or + chore, and since transactions usually take place at close to market + value, why not use the recorded costs as additional market prices (as + Ledger does) ? Adding the --infer-market-prices flag to -V, -X or --value enables this. - So for example, hledger bs -V --infer-market-prices will get market - prices both from P directives and from transactions. If both occur on + So for example, hledger bs -V --infer-market-prices will get market + prices both from P directives and from transactions. If both occur on the same day, the P directive takes precedence. There is a downside: value reports can sometimes be affected in confus- - ing/undesired ways by your journal entries. If this happens to you, - read all of this Value reporting section carefully, and try adding + ing/undesired ways by your journal entries. If this happens to you, + read all of this Value reporting section carefully, and try adding --debug or --debug=2 to troubleshoot. --infer-market-prices can infer market prices from: o multicommodity transactions with explicit prices (@/@@) - o multicommodity transactions with implicit prices (no @, two commodi- - ties, unbalanced). (With these, the order of postings matters. + o multicommodity transactions with implicit prices (no @, two commodi- + ties, unbalanced). (With these, the order of postings matters. hledger print -x can be useful for troubleshooting.) o multicommodity transactions with equity postings, if cost is inferred with --infer-costs. - There is a limitation (bug) currently: when a valuation commodity is - not specified, prices inferred with --infer-market-prices do not help + There is a limitation (bug) currently: when a valuation commodity is + not specified, prices inferred with --infer-market-prices do not help select a default valuation commodity, as P prices would. So conversion might not happen because no valuation commodity was detected (--debug=2 will show this). To be safe, specify the valuation commmodity, eg: @@ -5976,8 +6030,8 @@ Value reporting o --value=then,EUR --infer-market-prices, not --value=then --infer-mar- ket-prices - Signed costs and market prices can be confusing. For reference, here - is the current behaviour, since hledger 1.25. (If you think it should + Signed costs and market prices can be confusing. For reference, here + is the current behaviour, since hledger 1.25. (If you think it should work differently, see #1870.) 2022-01-01 Positive Unit prices @@ -6007,7 +6061,7 @@ Value reporting b B -1 @@ A -1 All of the transactions above are considered balanced (and on each day, - the two transactions are considered equivalent). Here are the market + the two transactions are considered equivalent). Here are the market prices inferred for B: $ hledger -f- --infer-market-prices prices @@ -6020,34 +6074,34 @@ Value reporting Valuation commodity When you specify a valuation commodity (-X COMM or --value TYPE,COMM): - hledger will convert all amounts to COMM, wherever it can find a suit- + hledger will convert all amounts to COMM, wherever it can find a suit- able market price (including by reversing or chaining prices). - When you leave the valuation commodity unspecified (-V or --value + When you leave the valuation commodity unspecified (-V or --value TYPE): - For each commodity A, hledger picks a default valuation commodity as + For each commodity A, hledger picks a default valuation commodity as follows, in this order of preference: 1. The price commodity from the latest P-declared market price for A on or before valuation date. 2. The price commodity from the latest P-declared market price for A on - any date. (Allows conversion to proceed when there are inferred + any date. (Allows conversion to proceed when there are inferred prices before the valuation date.) - 3. If there are no P directives at all (any commodity or date) and the - --infer-market-prices flag is used: the price commodity from the + 3. If there are no P directives at all (any commodity or date) and the + --infer-market-prices flag is used: the price commodity from the latest transaction-inferred price for A on or before valuation date. This means: - o If you have P directives, they determine which commodities -V will + o If you have P directives, they determine which commodities -V will convert, and to what. - o If you have no P directives, and use the --infer-market-prices flag, + o If you have no P directives, and use the --infer-market-prices flag, costs determine it. - Amounts for which no valuation commodity can be found are not con- + Amounts for which no valuation commodity can be found are not con- verted. --value: Flexible valuation @@ -6064,26 +6118,26 @@ Value reporting The TYPE part selects cost or value and valuation date: --value=then - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity, using market prices on each posting's date. --value=end - Convert amounts to their value in the default valuation commod- - ity, using market prices on the last day of the report period - (or if unspecified, the journal's end date); or in multiperiod + Convert amounts to their value in the default valuation commod- + ity, using market prices on the last day of the report period + (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in the default valuation commod- - ity using current market prices (as of when report is gener- + Convert amounts to their value in the default valuation commod- + ity using current market prices (as of when report is gener- ated). --value=YYYY-MM-DD - Convert amounts to their value in the default valuation commod- + Convert amounts to their value in the default valuation commod- ity using market prices on this date. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. hledger will do its best to convert amounts to this commodity, deducing market prices as described above. @@ -6111,13 +6165,13 @@ Value reporting $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V $103.00 assets:euros - Here are some examples showing the effect of --value, as seen with + Here are some examples showing the effect of --value, as seen with print: P 2000-01-01 A 1 B @@ -6155,7 +6209,7 @@ Value reporting 2000-02-01 (a) 2 B - With no report period specified, that shows the value as of the last + With no report period specified, that shows the value as of the last day of the journal (2000-03-01): $ hledger -f- print --value=end @@ -6193,7 +6247,7 @@ Value reporting (a) 1 B Interaction of valuation and queries - When matching postings based on queries in the presence of valuation, + When matching postings based on queries in the presence of valuation, the following happens: 1. The query is separated into two parts: @@ -6207,45 +6261,45 @@ Value reporting 3. Valuation is applied to the postings. - 4. The postings are matched to the other parts of the query based on + 4. The postings are matched to the other parts of the query based on post-valued amounts. Related: #1625 Effect of valuation on reports - Here is a reference for how valuation is supposed to affect each part - of hledger's reports. (It's wide, you may need to scroll sideways.) - It may be useful when troubleshooting. If you find problems, please - report them, ideally with a reproducible example. Related: #329, + Here is a reference for how valuation is supposed to affect each part + of hledger's reports. (It's wide, you may need to scroll sideways.) + It may be useful when troubleshooting. If you find problems, please + report them, ideally with a reproducible example. Related: #329, #1083. First, a quick glossary: cost calculated using price(s) recorded in the transaction(s). - value market value using available market price declarations, or the + value market value using available market price declarations, or the unchanged amount if no conversion rate can be found. report start - the first day of the report period specified with -b or -p or + the first day of the report period specified with -b or -p or date:, otherwise today. report or journal start - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, otherwise today. report end - the last day of the report period specified with -e or -p or + the last day of the report period specified with -e or -p or date:, otherwise today. report or journal end - the last day of the report period specified with -e or -p or - date:, otherwise the latest transaction date in the journal, + the last day of the report period specified with -e or -p or + date:, otherwise the latest transaction date in the journal, otherwise today. report interval - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperi- ods). @@ -6253,8 +6307,8 @@ Value reporting type --value=now -------------------------------------------------------------------------------------------- print - posting cost value at re- value at posting value at re- value at - amounts port end or date port or DATE/today + posting cost value at re- value at posting value at re- value at + amounts port end or date port or DATE/today today journal end balance unchanged unchanged unchanged unchanged unchanged asser- @@ -6270,7 +6324,7 @@ Value reporting (-H) with port or posting was made port or report journal journal interval start start - posting cost value at re- value at posting value at re- value at + posting cost value at re- value at posting value at re- value at amounts port or date port or DATE/today journal end journal end summary summarised value at pe- sum of postings value at pe- value at @@ -6286,8 +6340,8 @@ Value reporting balance (bs, bse, cf, is) - balance sums of value at re- value at posting value at re- value at - changes costs port end or date port or DATE/today of + balance sums of value at re- value at posting value at re- value at + changes costs port end or date port or DATE/today of today of journal end sums of post- sums of of sums of ings postings postings @@ -6295,7 +6349,7 @@ Value reporting amounts changes changes changes ances changes (--bud- get) - grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- + grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis- tal played val- played val- valued played val- played values ues ues ues @@ -6321,7 +6375,7 @@ Value reporting end bal- sums of same as sums of values of period end value at ances costs of --value=end postings from be- balances, DATE/today of (bal -H, postings fore period start valued at sums of post- - is --H, from before to period end at period ends ings + is --H, from before to period end at period ends ings bs, cf) report start respective post- to period ing dates end @@ -6330,10 +6384,10 @@ Value reporting (--bud- balances balances ances balances get) row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver- - tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- + tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis- averages played val- played val- played val- played values (-T, -A) ues ues ues - column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- + column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis- totals played val- played val- values played val- played values ues ues ues grand to- sum, average sum, average sum, average of sum, average sum, average @@ -6346,7 +6400,7 @@ Value reporting starting balance. PART 4: COMMANDS - Here are the standard commands, which you can list by running hledger. + Here are the standard commands, which you can list by running hledger. If you have installed more add-on commands, they also will be listed. Help commands @@ -6395,7 +6449,7 @@ PART 4: COMMANDS o aregister (areg) - show transactions in a particular account - o register (reg) - show postings in one or more accounts & running to- + o register (reg) - show postings in one or more accounts & running to- tal o balancesheet (bs) - show assets, liabilities and net worth @@ -6434,7 +6488,7 @@ PART 4: COMMANDS Help commands help - Show the hledger user manual with info, man, or a pager. With a (case + Show the hledger user manual with info, man, or a pager. With a (case insensitive) TOPIC argument, try to open it at that section heading. Flags: @@ -6443,23 +6497,23 @@ Help commands -p show the manual with $PAGER or less (less is always used if TOPIC is specified) - This command shows the hledger manual built in to your hledger exe- - cutable. It can be useful when offline, or when you prefer the termi- + This command shows the hledger manual built in to your hledger exe- + cutable. It can be useful when offline, or when you prefer the termi- nal to a web browser, or when the appropriate hledger manual or viewers are not installed properly on your system. - By default it chooses the best viewer found in $PATH, trying in this - order: info, man, $PAGER, less, more, stdout. (If a TOPIC is speci- - fied, $PAGER and more are not tried.) You can force the use of info, - man, or a pager with the -i, -m, or -p flags. If no viewer can be - found, or if running non-interactively, it just prints the manual to + By default it chooses the best viewer found in $PATH, trying in this + order: info, man, $PAGER, less, more, stdout. (If a TOPIC is speci- + fied, $PAGER and more are not tried.) You can force the use of info, + man, or a pager with the -i, -m, or -p flags. If no viewer can be + found, or if running non-interactively, it just prints the manual to stdout. - When using info, TOPIC can match either the full heading or a prefix. + When using info, TOPIC can match either the full heading or a prefix. If your info --version is < 6, you'll need to upgrade it, eg with 'brew install texinfo' on mac. - When using man or less, TOPIC must match the full heading. For a pre- + When using man or less, TOPIC must match the full heading. For a pre- fix match, you can write 'TOPIC.*'. Examples @@ -6476,19 +6530,19 @@ Help commands -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 is double, etc (default: 2)) - Run this command with no argument to list the demos. To play a demo, + Run this command with no argument to list the demos. To play a demo, write its number or a prefix or substring of its title. Tips: Make your terminal window large enough to see the demo clearly. - Use the -s/--speed SPEED option to set your preferred playback speed, + Use the -s/--speed SPEED option to set your preferred playback speed, eg -s4 to play at 4x original speed or -s.5 to play at half speed. The default speed is 2x. - Other asciinema options can be added following a double dash, eg -- + Other asciinema options can be added following a double dash, eg -- -i.1 to limit pauses or -- -h to list asciinema's other options. - During playback, several keys are available: SPACE to pause/unpause, . + During playback, several keys are available: SPACE to pause/unpause, . to step forward (while paused), CTRL-c quit. Examples: @@ -6497,6 +6551,8 @@ Help commands $ hledger demo 1 # play the first demo at default speed (2x) $ 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 ui Runs hledger-ui (if installed). @@ -6511,30 +6567,30 @@ Data entry commands Flags: --no-new-accounts don't allow creating new accounts - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- - actions, and appends them to the main journal file (which should be in - journal format). Existing transactions are not changed. This is one - of the few hledger commands that writes to the journal file (see also + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- + actions, and appends them to the main journal file (which should be in + journal format). Existing transactions are not changed. This is one + of the few hledger commands that writes to the journal file (see also import). To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar (by de- - scription) recent transaction (filtered by the query, if any) as a + o add tries to provide useful defaults, using the most similar (by de- + scription) recent transaction (filtered by the query, if any) as a template. o You can also set the initial defaults with command line arguments. o Readline-style edit keys can be used during data entry. - o The tab key will auto-complete whenever possible - accounts, pay- - ees/descriptions, dates (yesterday, today, tomorrow). If the input + o The tab key will auto-complete whenever possible - accounts, pay- + ees/descriptions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. o A parenthesised transaction code may be entered following a date. @@ -6543,15 +6599,15 @@ Data entry commands o If you make a mistake, enter < at any prompt to go one step backward. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Notes: o If you enter a number with no commodity symbol, and you have declared - a default commodity with a D directive, you might expect add to add - this symbol for you. It does not do this; we assume that if you are - using a D directive you prefer not to see the commodity symbol re- + a default commodity with a D directive, you might expect add to add + this symbol for you. It does not do this; we assume that if you are + using a D directive you prefer not to see the commodity symbol re- peated on amounts in the journal. Examples: @@ -6572,22 +6628,22 @@ Data entry commands There is a detailed tutorial at https://hledger.org/add.html. import - Import new transactions from one or more data files to the main jour- + Import new transactions from one or more data files to the main jour- nal. Flags: --catchup just mark all transactions as already imported --dry-run just show the transactions to be imported - This command detects new transactions in one or more data files speci- + This command detects new transactions in one or more data files speci- fied as arguments, and appends them to the main journal. - You can import from any input file format hledger supports, but + You can import from any input file format hledger supports, but CSV/SSV/TSV files, downloaded from financial institutions, are the most common import source. - The import destination is the default journal file, or another speci- - fied in the usual way with $LEDGER_FILE or -f/--file. It should be in + The import destination is the default journal file, or another speci- + fied in the usual way with $LEDGER_FILE or -f/--file. It should be in journal format. Examples: @@ -6597,44 +6653,44 @@ Data entry commands $ hledger import *.csv Import preview - It's useful to preview the import by running first with --dry-run, to + It's useful to preview the import by running first with --dry-run, to sanity check the range of dates being imported, and to check the effect of your conversion rules if converting from CSV. Eg: $ hledger import bank.csv --dry-run The dry run output is valid journal format, so hledger can re-parse it. - If the output is large, you could show just the uncategorised transac- + If the output is large, you could show just the uncategorised transac- tions like so: $ hledger import --dry-run bank.csv | hledger -f- -I print unknown - You could also run this repeatedly to see the effect of edits to your + You could also run this repeatedly to see the effect of edits to your conversion rules: $ watchexec -- 'hledger import --dry-run bank.csv | hledger -f- -I print unknown' - Once the conversion and dates look good enough to import to your jour- + Once the conversion and dates look good enough to import to your jour- nal, perhaps with some manual fixups to follow, you would do the actual import: $ hledger import bank.csv Overlap detection - Reading CSV files is built in to hledger, and not specific to import; - so you could also import by doing hledger -f bank.csv print + Reading CSV files is built in to hledger, and not specific to import; + so you could also import by doing hledger -f bank.csv print >>$LEDGER_FILE. - But import is easier and provides some advantages. The main one is - that it avoids re-importing transactions it has seen on previous runs. + But import is easier and provides some advantages. The main one is + that it avoids re-importing transactions it has seen on previous runs. This means you don't have to worry about overlapping data in successive - downloads of your bank CSV; just download and import as often as you + downloads of your bank CSV; just download and import as often as you like, and only the new transactions will be imported each time. - We don't call this "deduplication", as it's generally not possible to - reliably detect duplicates in bank CSV. Instead, import remembers the - latest date processed previously in each CSV file (saving it in a hid- - den file), and skips any records prior to that date. This works well + We don't call this "deduplication", as it's generally not possible to + reliably detect duplicates in bank CSV. Instead, import remembers the + latest date processed previously in each CSV file (saving it in a hid- + den file), and skips any records prior to that date. This works well for most real-world CSV, where: 1. the data file name is stable (does not change) across imports @@ -6645,115 +6701,115 @@ Data entry commands 4. the newest items have the newest dates - (Occasional violations of 2-4 are often harmless; you can reduce the + (Occasional violations of 2-4 are often harmless; you can reduce the chance of disruption by downloading and importing more often.) - Overlap detection is automatic, and shouldn't require much attention - from you, except perhaps at first import (see below). But here's how + Overlap detection is automatic, and shouldn't require much attention + from you, except perhaps at first import (see below). But here's how it works: o For each FILE being imported from: - 1. hledger reads a file named .latest.FILE file in the same direc- - tory, if any. This file contains the latest record date previ- - ously imported from FILE, in YYYY-MM-DD format. If multiple - records with that date were imported, the date is repeated on N + 1. hledger reads a file named .latest.FILE file in the same direc- + tory, if any. This file contains the latest record date previ- + ously imported from FILE, in YYYY-MM-DD format. If multiple + records with that date were imported, the date is repeated on N lines. - 2. hledger reads records from FILE. If a latest date was found in - step 1, any records before that date, and the first N records on + 2. hledger reads records from FILE. If a latest date was found in + step 1, any records before that date, and the first N records on that date, are skipped. - o After a successful import from all FILEs, without error and without + o After a successful import from all FILEs, without error and without --dry-run, hledger updates each FILE's .latest.FILE for next time. If this goes wrong, it's relatively easy to repair: - o You'll notice it before import when you preview with import + o You'll notice it before import when you preview with import --dry-run. - o Or after import when you try to reconcile your hledger account bal- + o Or after import when you try to reconcile your hledger account bal- ances with your bank. - o hledger print -f FILE.csv will show all recently downloaded transac- + o hledger print -f FILE.csv will show all recently downloaded transac- tions. Compare these with your journal. Copy/paste if needed. o Update your conversion rules and print again, if needed. - o You can manually update or remove the .latest file, or use import + o You can manually update or remove the .latest file, or use import --catchup FILE. - o Download and import more often, eg twice a week, at least while you - are learning. It's easier to review and troubleshoot when there are + o Download and import more often, eg twice a week, at least while you + are learning. It's easier to review and troubleshoot when there are fewer transactions. First import - The first time you import from a file, when no corresponding .latest + The first time you import from a file, when no corresponding .latest file has been created yet, all of the records will be imported. - But perhaps you have been entering the data manually, so you know that + But perhaps you have been entering the data manually, so you know that all of these transactions are already recorded in the journal. In this - case you can run hledger import --catchup once. This will create a - .latest file containing the latest CSV record date, so that none of + case you can run hledger import --catchup once. This will create a + .latest file containing the latest CSV record date, so that none of those records will be re-imported. - Or, if you know that some but not all of the transactions are in the - journal, you can create the .latest file yourself. Eg, let's say you - previously recorded foobank transactions up to 2024-10-31 in the jour- - nal. Then in the directory where you'll be saving foobank.csv, you + Or, if you know that some but not all of the transactions are in the + journal, you can create the .latest file yourself. Eg, let's say you + previously recorded foobank transactions up to 2024-10-31 in the jour- + nal. Then in the directory where you'll be saving foobank.csv, you would create a .latest.foobank.csv file containing 2024-10-31 - Or if you had three foobank transactions recorded with that date, you + Or if you had three foobank transactions recorded with that date, you would repeat the date that many times: 2024-10-31 2024-10-31 2024-10-31 - Then hledger import foobank.csv [--dry-run] will import only the newer + Then hledger import foobank.csv [--dry-run] will import only the newer records. Importing balance assignments - Journal entries added by import will have all posting amounts made ex- + Journal entries added by import will have all posting amounts made ex- plicit (like print -x). - This means that any balance assignments in the imported entries would - need to be evaluated. But this generally isn't possible, as the main + This means that any balance assignments in the imported entries would + need to be evaluated. But this generally isn't possible, as the main file's account balances are not visible during import. So try to avoid generating balance assignments with your CSV rules, or importing from a - journal that contains balance assignments. (Balance assignments are + journal that contains balance assignments. (Balance assignments are best avoided anyway.) - But if you must use them, eg because your CSV includes only balances: - you can import with print, which leaves implicit amounts implicit. + But if you must use them, eg because your CSV includes only balances: + you can import with print, which leaves implicit amounts implicit. (print can also do overlap detection like import, with the --new flag): $ hledger print --new -f bank.csv >> $LEDGER_FILE - (If you think import should preserve implicit balances, please test + (If you think import should preserve implicit balances, please test that and send a pull request.) Import and commodity styles - Amounts in entries added by import will be formatted according to the - journal's canonical commodity styles, as declared by commodity direc- + Amounts in entries added by import will be formatted according to the + journal's canonical commodity styles, as declared by commodity direc- tives or inferred from the journal's amounts. Related: CSV > Amount decimal places. Import special cases If you have a download whose file name varies, you could rename it to a - fixed name after each download. Or you could use a CSV source rule - with a suitable glob pattern, and import from the .rules file instead + fixed name after each download. Or you could use a CSV source rule + with a suitable glob pattern, and import from the .rules file instead of the data file. - Here's a situation where you would need to run import with care: say - you download bank.csv, but forget to import it or delete it. And next + Here's a situation where you would need to run import with care: say + you download bank.csv, but forget to import it or delete it. And next month you download it again. This time your web browser may save it as - bank (2).csv. So now each of these may have data not included in the + bank (2).csv. So now each of these may have data not included in the other. And a source rule with a glob pattern would match only the most - recent file. So in this case you should import from each one in turn, + recent file. So in this case you should import from each one in turn, in the correct order, taking care to use the same filename each time: $ hledger import bank.csv @@ -6761,13 +6817,13 @@ Data entry commands $ hledger import bank.csv Here are two kinds of "deduplication" which import does not handle (and - generally should not, since these can happen legitimately in financial + generally should not, since these can happen legitimately in financial data): - o Two or more of the new CSV records are identical, and generate iden- + o Two or more of the new CSV records are identical, and generate iden- tical new journal entries. - o A new CSV record generates a journal entry identical to one(s) al- + o A new CSV record generates a journal entry identical to one(s) al- ready in the journal. Basic report commands @@ -6789,38 +6845,38 @@ Basic report commands -t --tree show accounts as a tree --drop=N flat mode: omit N leading account name parts - This command lists account names. By default it shows all known ac- - counts, either used in transactions or declared with account direc- + This command lists account names. By default it shows all known ac- + counts, either used in transactions or declared with account direc- tives. With query arguments, only matched account names and account names ref- erenced by matched postings are shown. - Or it can show just the used accounts (--used/-u), the declared ac- - counts (--declared/-d), the accounts declared but not used (--unused), + Or it can show just the used accounts (--used/-u), the declared ac- + counts (--declared/-d), the accounts declared but not used (--unused), the accounts used but not declared (--undeclared), or the first account matched by an account name pattern, if any (--find). - It shows a flat list by default. With --tree, it uses indentation to - show the account hierarchy. In flat mode you can add --drop N to omit - the first few account name components. Account names can be + It shows a flat list by default. With --tree, it uses indentation to + show the account hierarchy. In flat mode you can add --drop N to omit + the first few account name components. Account names can be depth-clipped with depth:N or --depth N or -N. - With --types, it also shows each account's type, if it's known. (See + With --types, it also shows each account's type, if it's known. (See Declaring accounts > Account types.) - With --positions, it also shows the file and line number of each ac- - count's declaration, if any, and the account's overall declaration or- + With --positions, it also shows the file and line number of each ac- + count's declaration, if any, and the account's overall declaration or- der; these may be useful when troubleshooting account display order. - With --directives, it adds the account keyword, showing valid account + With --directives, it adds the account keyword, showing valid account directives which can be pasted into a journal file. This is useful to- - gether with --undeclared when updating your account declarations to + gether with --undeclared when updating your account declarations to satisfy hledger check accounts. - The --find flag can be used to look up a single account name, in the - same way that the aregister command does. It returns the alphanumeri- - cally-first matched account name, or if none can be found, it fails + The --find flag can be used to look up a single account name, in the + same way that the aregister command does. It returns the alphanumeri- + cally-first matched account name, or if none can be found, it fails with a non-zero exit code. Examples: @@ -6844,13 +6900,13 @@ Basic report commands Flags: no command-specific flags - This command prints the value of each transaction's code field, in the - order transactions were parsed. The transaction code is an optional - value written in parentheses between the date and description, often + This command prints the value of each transaction's code field, in the + order transactions were parsed. The transaction code is an optional + value written in parentheses between the date and description, often used to store a cheque number, order number or similar. Transactions aren't required to have a code, and missing or empty codes - will not be shown by default. With the -E/--empty flag, they will be + will not be shown by default. With the -E/--empty flag, they will be printed as blank lines. You can add a query to select a subset of transactions. @@ -6897,7 +6953,7 @@ Basic report commands no command-specific flags This command lists the unique descriptions that appear in transactions, - in alphabetic order. You can add a query to select a subset of trans- + in alphabetic order. You can add a query to select a subset of trans- actions. Example: @@ -6908,7 +6964,7 @@ Basic report commands Person A files - List all files included in the journal. With a REGEX argument, only + List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. Flags: @@ -6921,8 +6977,8 @@ Basic report commands no command-specific flags This command lists the unique notes that appear in transactions, in al- - phabetic order. You can add a query to select a subset of transac- - tions. The note is the part of the transaction description after a | + phabetic order. You can add a query to select a subset of transac- + tions. The note is the part of the transaction description after a | character (or if there is no |, the whole description). Example: @@ -6938,14 +6994,14 @@ Basic report commands --declared show payees declared with payee directives --used show payees referenced by transactions - This command lists unique payee/payer names which have been declared - with payee directives (--declared), used in transaction descriptions + This command lists unique payee/payer names which have been declared + with payee directives (--declared), used in transaction descriptions (--used), or both (the default). - The payee/payer is the part of the transaction description before a | + The payee/payer is the part of the transaction description before a | character (or if there is no |, the whole description). - You can add query arguments to select a subset of transactions. This + You can add query arguments to select a subset of transactions. This implies --used. Example: @@ -6956,8 +7012,8 @@ Basic report commands Person A prices - Print the market prices declared with P directives. With --infer-mar- - ket-prices, also show any additional prices inferred from costs. With + Print the market prices declared with P directives. With --infer-mar- + ket-prices, also show any additional prices inferred from costs. With --show-reverse, also show additional prices inferred by reversing known prices. @@ -6965,14 +7021,14 @@ Basic report commands --show-reverse also show the prices inferred by reversing known prices - Price amounts are always displayed with their full precision, except + Price amounts are always displayed with their full precision, except for reverse prices which are limited to 8 decimal digits. Prices can be filtered by a date:, cur: or amt: query. Generally if you run this command with --infer-market-prices --show-re- - verse, it will show the same prices used internally to calculate value - reports. But if in doubt, you can inspect those directly by running + verse, it will show the same prices used internally to calculate value + reports. But if in doubt, you can inspect those directly by running the value report with --debug=2. stats @@ -6983,10 +7039,10 @@ Basic report commands -o --output-file=FILE write output to FILE. The stats command shows summary information for the whole journal, or a - matched part of it. With a reporting interval, it shows a report for + matched part of it. With a reporting interval, it shows a report for each report period. - The default output is fairly impersonal, though it reveals the main + The default output is fairly impersonal, though it reveals the main file name. With -v/--verbose, more details are shown, like file paths, included files, and commodity names. @@ -6998,8 +7054,8 @@ Basic report commands o live: the peak memory in use by the program to do its work - o alloc: the peak memory allocation from the OS as seen by GHC. Mea- - suring this externally, eg with GNU time, is more accurate; usually + o alloc: the peak memory allocation from the OS as seen by GHC. Mea- + suring this externally, eg with GNU time, is more accurate; usually that will be a larger number; sometimes (with swapping?) smaller. The stats command's run time is similar to that of a balance report. @@ -7020,7 +7076,7 @@ Basic report commands Market prices : 1000 Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc - This command supports the -o/--output-file option (but not -O/--out- + This command supports the -o/--output-file option (but not -O/--out- put-format). tags @@ -7034,22 +7090,22 @@ Basic report commands This command lists the tag names used in the journal, whether on trans- actions, postings, or account declarations. - With a TAGREGEX argument, only tag names matching this regular expres- + With a TAGREGEX argument, only tag names matching this regular expres- sion (case insensitive, infix matched) are shown. - With QUERY arguments, only transactions and accounts matching this + With QUERY arguments, only transactions and accounts matching this query are considered. If the query involves transaction fields (date:, desc:, amt:, ...), the search is restricted to the matched transactions and their accounts. - With the --values flag, the tags' unique non-empty values are listed + With the --values flag, the tags' unique non-empty values are listed instead. With -E/--empty, blank/empty values are also shown. - With --parsed, tags or values are shown in the order they were parsed, - with duplicates included. (Except, tags from account declarations are + With --parsed, tags or values are shown in the order they were parsed, + with duplicates included. (Except, tags from account declarations are always shown first.) - Tip: remember, accounts also acquire tags from their parents, postings + Tip: remember, accounts also acquire tags from their parents, postings also acquire tags from their account and transaction, transactions also acquire tags from their postings. @@ -7064,13 +7120,14 @@ Standard report commands --round=TYPE how much rounding or padding should be done when displaying amounts ? none - show original decimal digits, - as in journal + as in journal (default) soft - just add or remove decimal zeros - to match precision (default) + to match precision hard - round posting amounts to precision (can unbalance transactions) all - also round cost amounts to precision (can unbalance transactions) + --invert display all amounts with reversed sign --new show only newer-dated transactions added in each file since last run -m --match=DESC fuzzy search for one recent transaction with @@ -7086,9 +7143,9 @@ Standard report commands The print command displays full journal entries (transactions) from the journal file, sorted by date (or with --date2, by secondary date). - Directives and inter-transaction comments are not shown, currently. + Directives and inter-transaction comments are not shown, currently. This means the print command is somewhat lossy, and if you are using it - to reformat/regenerate your journal you should take care to also copy + to reformat/regenerate your journal you should take care to also copy over the directives and inter-transaction comments. Eg: @@ -7108,55 +7165,55 @@ Standard report commands assets:cash $-2 print explicitness - Normally, whether posting amounts are implicit or explicit is pre- + Normally, whether posting amounts are implicit or explicit is pre- served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, if a conversion cost is implied + not appear in the output. Similarly, if a conversion cost is implied but not written, it will not appear in the output. - You can use the -x/--explicit flag to force explicit display of all - amounts and costs. This can be useful for troubleshooting or for mak- - ing your journal more readable and robust against data entry errors. + You can use the -x/--explicit flag to force explicit display of all + amounts and costs. This can be useful for troubleshooting or for mak- + ing your journal more readable and robust against data entry errors. -x is also implied by using any of -B,-V,-X,--value. - The -x/--explicit flag will cause any postings with a multi-commodity - amount (which can arise when a multi-commodity transaction has an im- - plicit amount) to be split into multiple single-commodity postings, + The -x/--explicit flag will cause any postings with a multi-commodity + amount (which can arise when a multi-commodity transaction has an im- + plicit amount) to be split into multiple single-commodity postings, keeping the output parseable. print amount style - Amounts are shown right-aligned within each transaction (but not - aligned across all transactions; you can do that with ledger-mode in + Amounts are shown right-aligned within each transaction (but not + aligned across all transactions; you can do that with ledger-mode in Emacs). - Amounts will be (mostly) normalised to their commodity display style: - their symbol placement, decimal mark, and digit group marks will be - made consistent. By default, decimal digits are shown as they are + Amounts will be (mostly) normalised to their commodity display style: + their symbol placement, decimal mark, and digit group marks will be + made consistent. By default, decimal digits are shown as they are written in the journal. - With the --round (Added in 1.32) option, print will try increasingly - hard to display decimal digits according to the commodity display + With the --round (Added in 1.32) option, print will try increasingly + hard to display decimal digits according to the commodity display styles: o --round=none show amounts with original precisions (default) o --round=soft add/remove decimal zeros in amounts (except costs) - o --round=hard round amounts (except costs), possibly hiding signifi- + o --round=hard round amounts (except costs), possibly hiding signifi- cant digits o --round=all round all amounts and costs - soft is good for non-lossy cleanup, formatting amounts more consis- + soft is good for non-lossy cleanup, formatting amounts more consis- tently where it's safe to do so. - hard and all can cause print to show invalid unbalanced journal en- - tries; they may be useful eg for stronger cleanup, with manual fixups + hard and all can cause print to show invalid unbalanced journal en- + tries; they may be useful eg for stronger cleanup, with manual fixups when needed. print parseability - print's output is usually a valid hledger journal, and you can process + print's output is usually a valid hledger journal, and you can process it again with a second hledger command. This can be useful for certain - kinds of search (though the same can be achieved with expr: queries + kinds of search (though the same can be achieved with expr: queries now): # Show running total of food expenses paid from cash. @@ -7165,7 +7222,7 @@ Standard report commands There are some situations where print's output can become unparseable: - o Value reporting affects posting amounts but not balance assertion or + o Value reporting affects posting amounts but not balance assertion or balance assignment amounts, potentially causing those to fail. o Auto postings can generate postings with too many missing amounts. @@ -7175,38 +7232,42 @@ Standard report commands print, other features 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 - 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.) With -m DESC/--match=DESC, print shows one recent transaction whose de- - scription is most similar to DESC. DESC should contain at least two - characters. If there is no similar-enough match, no transaction will + scription is most similar to DESC. DESC should contain at least two + characters. If there is no similar-enough match, no transaction will be shown and the program exit code will be non-zero. print output format This command also supports the output destination and output format op- - tions The output formats supported are txt, beancount (Added in 1.32), + tions The output formats supported are txt, beancount (Added in 1.32), 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: - o Transaction and postings with unmarked status are converted to + o Transaction and postings with unmarked status are converted to cleared (*) status. - o Transactions' payee and note are backslash-escaped and dou- + o Transactions' payee and note are backslash-escaped and dou- ble-quote-escaped and wrapped in double quotes. o Transaction tags are copied to Beancount #tag format. - o Commodity symbols are converted to upper case, and a small number of - currency symbols like $ are converted to the corresponding currency + o Commodity symbols are converted to upper case, and a small number of + currency symbols like $ are converted to the corresponding currency names. o Account name parts are capitalised and unsupported characters are re- placed with -. If an account name part does not begin with a letter, - or if the first part is not Assets, Liabilities, Equity, Income, or + or if the first part is not Assets, Liabilities, Equity, Income, or Expenses, an error is raised. (Use --alias options to bring your ac- counts into compliance.) @@ -7239,26 +7300,26 @@ Standard report commands "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) aregister (areg) - Show the transactions and running balances in one account, with each + Show the transactions and running balances in one account, with each transaction on one line. Flags: @@ -7271,8 +7332,8 @@ Standard report commands postings before report start date) (default) --invert display all amounts with reversed sign --heading=YN show heading row above table: yes (default) or no - -w --width=N set output width (default: terminal width or - $COLUMNS). -wN,M sets description width as well. + -w --width=N set output width (default: terminal width). -wN,M + sets description width as well. --align-all guarantee alignment across all lines (slower) -O --output-format=FMT select the output format. Supported formats: txt, html, csv, tsv, json. @@ -7280,64 +7341,64 @@ Standard report commands one of the above formats selects that format. aregister shows the overall transactions affecting a particular account - (and any subaccounts). Each report line represents one transaction in - this account. Transactions before the report start date are included - in the running balance (--historical mode is the default). You can + (and any subaccounts). Each report line represents one transaction in + this account. Transactions before the report start date are included + in the running balance (--historical mode is the default). You can suppress this behaviour using the --cumulative option. - This is a more "real world", bank-like view than the register command - (which shows individual postings, possibly from multiple accounts, not + This is a more "real world", bank-like view than the register command + (which shows individual postings, possibly from multiple accounts, not necessarily in historical mode). As a quick rule of thumb: - use areg- ister for reviewing and reconciling real-world asset/liability accounts - use register for reviewing detailed revenues/expenses. - aregister requires one argument: the account to report on. You can - write either the full account name, or a case-insensitive regular ex- + aregister requires one argument: the account to report on. You can + write either the full account name, or a case-insensitive regular ex- pression which will select the alphabetically first matched account. When there are multiple matches, the alphabetically-first choice can be - surprising; eg if you have assets:per:checking 1 and assets:biz:check- - ing 2 accounts, hledger areg checking would select assets:biz:checking - 2. It's just a convenience to save typing, so if in doubt, write the + surprising; eg if you have assets:per:checking 1 and assets:biz:check- + ing 2 accounts, hledger areg checking would select assets:biz:checking + 2. It's just a convenience to save typing, so if in doubt, write the full account name, or a distinctive substring that matches uniquely. - Transactions involving subaccounts of this account will also be shown. - aregister ignores depth limits, so its final total will always match a + Transactions involving subaccounts of this account will also be shown. + aregister ignores depth limits, so its final total will always match a balance report with similar arguments. - Any additional arguments form a query which will filter the transac- + Any additional arguments form a query which will filter the transac- tions shown. Note some queries will disturb the running balance, caus- ing it to be different from the account's real-world running balance. - An example: this shows the transactions and historical running balance + An example: this shows the transactions and historical running balance during july, in the first account whose name contains "checking": $ hledger areg checking date:jul Each aregister line item shows: - o the transaction's date (or the relevant posting's date if different, + o the transaction's date (or the relevant posting's date if different, see below) - o the names of all the other account(s) involved in this transaction + o the names of all the other account(s) involved in this transaction (probably abbreviated) o the total change to this account's balance from this transaction o the account's historical running balance after this transaction. - Transactions making a net change of zero are not shown by default; add + Transactions making a net change of zero are not shown by default; add the -E/--empty flag to show them. - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. - By default, aregister shows a heading above the data. However, when - reporting in a language different from English, it is easier to omit - this heading and prepend your own one. For this purpose, use the + By default, aregister shows a heading above the data. However, when + reporting in a language different from English, it is easier to omit + this heading and prepend your own one. For this purpose, use the --heading=no option. This command also supports the output destination and output format op- @@ -7345,13 +7406,13 @@ Standard report commands html, fods (Added in 1.41) and json. aregister and posting dates - aregister always shows one line (and date and amount) per transaction. - But sometimes transactions have postings with different dates. Also, - not all of a transaction's postings may be within the report period. + aregister always shows one line (and date and amount) per transaction. + But sometimes transactions have postings with different dates. Also, + not all of a transaction's postings may be within the report period. To resolve this, aregister shows the earliest of the transaction's date and posting dates that is in-period, and the sum of the in-period post- - ings. In other words it will show a combined line item with just the - earliest date, and the running balance will (temporarily, until the + ings. In other words it will show a combined line item with just the + earliest date, and the running balance will (temporarily, until the transaction's last posting) be inaccurate. Use register -H if you need to see the individual postings. @@ -7378,8 +7439,8 @@ Standard report commands --sort=FIELDS sort by: date, desc, account, amount, absamount, or a comma-separated combination of these. For a descending sort, prefix with -. (Default: date) - -w --width=N set output width (default: terminal width or - $COLUMNS). -wN,M sets description width as well. + -w --width=N set output width (default: terminal width). -wN,M + sets description width as well. --align-all guarantee alignment across all lines (slower) --base-url=URLPREFIX in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by @@ -7390,14 +7451,14 @@ Standard report commands one of the above formats selects that format. The register command displays matched postings, across all accounts, in - date order, with their running total or running historical balance. - (See also the aregister command, which shows matched transactions in a + date order, with their running total or running historical balance. + (See also the aregister command, which shows matched transactions in a specific account.) register normally shows line per posting, but note that multi-commodity amounts will occupy multiple lines (one line per commodity). - It is typically used with a query selecting a particular account, to + It is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -7408,14 +7469,14 @@ Standard report commands With --date2, it shows and sorts by secondary date instead. - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -7425,25 +7486,25 @@ Standard report commands The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one ac- + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- count and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account to- + bers. It's also useful to show postings on the checking account to- gether with the related account: - The --sort=FIELDS flag sorts by the fields given, which can be any of + The --sort=FIELDS flag sorts by the fields given, which can be any of account, amount, absamount, date, or desc/description, optionally sepa- - rated by commas. For example, --sort account,amount will group all + rated by commas. For example, --sort account,amount will group all transactions in each account, sorted by transaction amount. Each field - can be negated by a preceding -, so --sort -amount will show transac- + can be negated by a preceding -, so --sort -amount will show transac- tions ordered from smallest amount to largest amount. $ hledger register --related --invert assets:checking @@ -7455,7 +7516,7 @@ Standard report commands 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -7472,7 +7533,7 @@ Standard report commands 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth op- + Often, you'll want to see just one line per interval. The --depth op- tion helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h @@ -7480,20 +7541,19 @@ Standard report commands 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of in- - tervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of in- + tervals. This ensures that the first and last intervals are full length and comparable to the others in the report. - With -m DESC/--match=DESC, register does a fuzzy search for one recent + With -m DESC/--match=DESC, register does a fuzzy search for one recent posting whose description is most similar to DESC. DESC should contain at least two characters. If there is no similar-enough match, no post- ing will be shown and the program exit code will be non-zero. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not - a bash shell variable) or by using the --width/-w option. + register normally uses the full terminal width (or 80 columns if it + can't detect that). You can override this with the --width/-w option. The description and account columns normally share the space equally (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 -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 $COLUMNS,40 # use terminal width, & description width 40 This command also supports the output destination and output format op- 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) --layout=ARG how to lay out multi-commodity amounts and the overall table: - 'wide[,WIDTH]': commodities on one line - 'tall' : commodities on separate lines - 'bare' : commodity symbols in one column - 'tidy' : every attribute in its own column + 'wide[,W]': commodities on same line, up to W wide + 'tall' : commodities on separate lines + 'bare' : commodity symbols in a separate column + 'tidy' : each data field in its own column --base-url=URLPREFIX in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by hledger-web; can also be relative.) @@ -9066,24 +9123,21 @@ Data generation commands close (equity) - close generates several kinds of "closing" and/or "opening" transac- - tions, useful in certain situations, including migrating balances to a - new journal file, retaining earnings into equity, consolidating bal- - ances, or viewing lots. Like print, it prints valid journal entries. - You can append or copy these to your journal file(s) when you are happy - with how they look. + close prints several kinds of "closing" and/or "opening" transactions, + useful in various situations: migrating balances to a new journal file, + retaining earnings into equity, consolidating balances, viewing lot + costs.. Like print, it prints valid journal entries. You can copy + these into your journal file(s) when you are happy with how they look. Flags: - --migrate[=NEW] show closing and opening transactions, for Asset - and Liability accounts by default, tagged for easy - matching. The tag's default value can be overridden - by providing NEW. - --close[=NEW] (default) show a closing transaction - --open[=NEW] show an opening transaction - --assign[=NEW] show opening balance assignments - --assert[=NEW] show closing balance assertions - --retain[=NEW] show a retain earnings transaction, for Revenue - and Expense accounts by default + --clopen[=TAGVAL] show closing and opening balances transactions, + for AL accounts by default + --close[=TAGVAL] show just a closing balances transaction + --open[=TAGVAL] show just an opening balances transaction + --assert[=TAGVAL] show a balance assertions transaction + --assign[=TAGVAL] show a balance assignments transaction + --retain[=TAGVAL] show a retain earnings transaction, for RX + accounts by default -x --explicit show all amounts explicitly --show-costs show amounts with different costs separately --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 displaying amounts ? none - show original decimal digits, - as in journal + as in journal (default) soft - just add or remove decimal zeros - to match precision (default) + to match precision hard - round posting amounts to precision (can unbalance transactions) all - also round cost amounts to precision (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 - This is the most common mode. It prints a "closing balances" transac- - tion that zeroes out all asset and liability balances (by default), and - an opposite "opening balances" transaction that restores them again. - The balancing account will be equity:opening/closing balances (or an- - other specified by --close-acct or --open-acct). + close --clopen + This is useful if migrating balances to a new journal file at the start + of a new year. It prints a "closing balances" transaction that zeroes + out account balances (Asset and Liability accounts, by default), and an + opposite "opening balances" transaction that restores them again. Typ- + ically, you would run - This is useful when migrating balances to a new journal file at the - 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". + hledger close --clopen -e NEWYEAR >> $LEDGER_FILE - You can close a different set of accounts by providing a query. Eg if - you want to include equity, you can add assets liabilities equity or - 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. + and then move the opening transaction from the old file to the new file + (and probably also update your LEDGER_FILE environment variable). - The generated transactions will have a start: tag, with its value set - to --migrate's NEW argument if any, for easier matching or exclusion. - 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. + Why might you do this ? If your reports are fast, you may not need it. + But at some point you will probably want to partition your data by + time, for performance or data integrity or regulatory reasons. A new + file or set of files per year is common. Then, having each file/file- + 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 - This prints just the closing balances transaction of --migrate. It is - the default behaviour if you specify no mode flag. Using the customi- - sation options below, you can move balances from any set of accounts to - a different account. + This prints just the closing balances transaction of --clopen. It is + the default if you don't specify a mode. + + 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 - This prints just the opening balances transaction of --migrate. It is - similar to Ledger's equity command. + This prints just the opening balances transaction of --clopen. (It is + similar to Ledger's equity command.) 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. + This prints a transaction that asserts the account balances as they are + on the end date (and adds an assert: tag). It could be useful as docu- + mention 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. + This prints a transaction that assigns the account balances as they are + on the end date (and adds an "assign:" tag). Unlike balance asser- + tions, assignments will post changes to balances as needed to reach the + specified amounts. - 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. + This is another way to set starting balances when migrating to a new + file, and it will set them correctly even in the presence of earlier + files which do not have a closing balances transaction. However, it + can hide errors, and disturb the accounting equation, so --clopen is + usually recommended. 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 like --close, but it closes Revenue and Expense account bal- + ances by default. They will be transferred to equity:retained earn- + ings, or another account specified with --close-acct. - 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.) + Revenues and expenses correspond to changes in equity. They are cate- + gorised separately for reporting purposes, but traditionally at the end + of each accounting period, businesses consolidate them into equity, + This is called "retaining earnings", or "closing the books". - 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. + In personal accounting, there's not much reason to do this, and most + people don't. (One reason to do it is to help the balancesheetequity + report show a zero total, demonstrating that the accounting equation + (A-L=E) is satisfied.) close customisation In all modes, the following things can be overridden: @@ -9186,57 +9254,57 @@ Data generation commands o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT - o the transaction descriptions, with --close-desc=DESC and + o the transaction descriptions, with --close-desc=DESC and --open-desc=DESC o the transaction's tag value, with a --MODE=NEW option argument o the closing/opening dates, with -e OPENDATE - By default, the closing date is yesterday, or the journal's end date, - whichever is later; and the opening date is always one day after the - closing date. You can change these by specifying a report end date; + By default, the closing date is yesterday, or the journal's end date, + whichever is later; and the opening date is always one day after the + closing date. You can change these by specifying a report end date; 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- + 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 - destination postings next to each other (perhaps useful for trou- + With --interleaved, each individual transfer is shown with source and + destination postings next to each other (perhaps useful for trou- bleshooting). With --show-costs, balances' costs are also shown, with different costs - kept separate. This may generate very large journal entries, if you - have many currency conversions or investment transactions. close - --show-costs is currently the best way to view investment lots with - hledger. (To move or dispose of lots, see the more capable + kept separate. This may generate very large journal entries, if you + have many currency conversions or investment transactions. close + --show-costs is currently the best way to view investment lots with + hledger. (To move or dispose of lots, see the more capable hledger-move script.) close and balance assertions close adds balance assertions verifying that the accounts have been re- set to zero in a closing transaction or restored to their previous bal- - ances in an opening transaction. These provide useful error checking, + 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. - Single-commodity, subaccount-exclusive balance assertions (=) are gen- - erated by default. This can be changed with --assertion-type='==*' + Single-commodity, subaccount-exclusive balance assertions (=) are gen- + erated by default. This can be changed with --assertion-type='==*' (eg). - When running close you should probably avoid using -C, -R, status: - (filtering by status or realness) or --auto (generating postings), + When running close you should probably avoid using -C, -R, status: + (filtering by status or realness) or --auto (generating postings), since the generated balance assertions would then require these. - Transactions with multiple dates (eg posting dates) spanning the file + Transactions with multiple dates (eg posting dates) spanning the file boundary also can disrupt the balance assertions: 2023-12-30 a purchase made in december, cleared in january expenses:food 5 assets:bank:checking -5 ; date: 2023-01-02 - To solve this 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, splitting the multi-day transaction into two single-day transac- tions: @@ -9257,7 +9325,7 @@ Data generation commands $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - After this, to see 2022's revenues and expenses you must exclude the + After this, to see 2022's revenues and expenses you must exclude the retain earnings transaction: $ hledger -f 2022.journal is not:desc:'retain earnings' @@ -9265,24 +9333,24 @@ Data generation commands Migrate balances to a new file 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 opening transaction to the start of 2023.journal - After this, to see 2022's end-of-year balances you must exclude the + After this, to see 2022's end-of-year balances you must exclude the closing balances transaction: $ hledger -f 2022.journal bs not:desc:'closing balances' - For more flexibility, it helps to tag closing and opening transactions - with eg start:NEWYEAR, then you can ensure correct balances by exclud- + For more flexibility, it helps to tag closing and opening transactions + with eg clopen:NEWYEAR, then you can ensure correct balances by exclud- 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 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 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:clopen=2021 or not tag:clopen' + $ 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:clopen=2021 or not tag:clopen' + $ 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 More detailed close examples @@ -10079,4 +10147,4 @@ LICENSE SEE ALSO 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)