From 95ef5fad9a2c9a2c1381ad2db2a945219ac029da Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 20 Oct 2024 09:26:32 -1000 Subject: [PATCH] ;doc: update manuals --- hledger-ui/hledger-ui.1 | 4 +- hledger-ui/hledger-ui.info | 32 +- hledger-ui/hledger-ui.txt | 4 +- hledger-web/hledger-web.1 | 4 +- hledger-web/hledger-web.info | 20 +- hledger-web/hledger-web.txt | 4 +- hledger/hledger.1 | 125 ++--- hledger/hledger.info | 866 ++++++++++++++++++----------------- hledger/hledger.txt | 631 ++++++++++++------------- 9 files changed, 862 insertions(+), 828 deletions(-) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 7d735e38e..073bd23ea 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -134,8 +134,6 @@ General output/reporting flags (supported by some commands): YYYY\-MM\-DD: value on given date \-c \-\-commodity\-style=S Override a commodity\[aq]s display style. Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq] - \-\-color=YN \-\-colour Use ANSI color codes in text output? Can be - \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq]. \-\-pretty[=YN] Use box\-drawing characters in text output? Can be \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq]. If YN is specified, the equals is required. @@ -147,6 +145,8 @@ General help flags: \-\-man show the manual with man \-\-version show version information \-\-debug=[1\-9] show this much debug output (default: 1) + \-\-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) .EE .PP With hledger\-ui, the \f[CR]\-\-debug\f[R] option sends debug output to diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index 53965f1ee..d391fafe9 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -145,8 +145,6 @@ General output/reporting flags (supported by some commands): YYYY-MM-DD: value on given date -c --commodity-style=S Override a commodity's display style. Eg: -c '.' or -c '1.000,00 EUR' - --color=YN --colour Use ANSI color codes in text output? Can be - 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -158,6 +156,8 @@ General help flags: --man show the manual with man --version show version information --debug=[1-9] show this much debug output (default: 1) + --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) With hledger-ui, the '--debug' option sends debug output to a 'hledger-ui.log' file in the current directory. @@ -540,20 +540,20 @@ above). Tag Table: Node: Top223 Node: OPTIONS1874 -Node: MOUSE8391 -Node: KEYS8723 -Node: SCREENS13551 -Node: Menu screen14291 -Node: Cash accounts screen14607 -Node: Balance sheet accounts screen14968 -Node: Income statement accounts screen15304 -Node: All accounts screen15689 -Node: Register screen16052 -Node: Transaction screen18495 -Node: Error screen20070 -Node: WATCH MODE20436 -Node: ENVIRONMENT22012 -Node: BUGS22319 +Node: MOUSE8397 +Node: KEYS8729 +Node: SCREENS13557 +Node: Menu screen14297 +Node: Cash accounts screen14613 +Node: Balance sheet accounts screen14974 +Node: Income statement accounts screen15310 +Node: All accounts screen15695 +Node: Register screen16058 +Node: Transaction screen18501 +Node: Error screen20076 +Node: WATCH MODE20442 +Node: ENVIRONMENT22018 +Node: BUGS22325  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 92291353a..14a926035 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -123,8 +123,6 @@ OPTIONS YYYY-MM-DD: value on given date -c --commodity-style=S Override a commodity's display style. Eg: -c '.' or -c '1.000,00 EUR' - --color=YN --colour Use ANSI color codes in text output? Can be - 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -136,6 +134,8 @@ OPTIONS --man show the manual with man --version show version information --debug=[1-9] show this much debug output (default: 1) + --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) With hledger-ui, the --debug option sends debug output to a hledger-ui.log file in the current directory. diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 0c1c14e63..e95416894 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -185,8 +185,6 @@ General output/reporting flags (supported by some commands): YYYY\-MM\-DD: value on given date \-c \-\-commodity\-style=S Override a commodity\[aq]s display style. Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq] - \-\-color=YN \-\-colour Use ANSI color codes in text output? Can be - \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq]. \-\-pretty[=YN] Use box\-drawing characters in text output? Can be \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq]. If YN is specified, the equals is required. @@ -198,6 +196,8 @@ General help flags: \-\-man show the manual with man \-\-version show version information \-\-debug=[1\-9] show this much debug output (default: 1) + \-\-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) .EE .PP hledger\-web shows accounts with zero balances by default (like diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index a7d1baa1c..13751e9f9 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -190,8 +190,6 @@ General output/reporting flags (supported by some commands): YYYY-MM-DD: value on given date -c --commodity-style=S Override a commodity's display style. Eg: -c '.' or -c '1.000,00 EUR' - --color=YN --colour Use ANSI color codes in text output? Can be - 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -203,6 +201,8 @@ General help flags: --man show the manual with man --version show version information --debug=[1-9] show this much debug output (default: 1) + --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) hledger-web shows accounts with zero balances by default (like 'hledger-ui', and unlike 'hledger'). Using the '-E/--empty' flag will @@ -528,14 +528,14 @@ http://bugs.hledger.org), or on the #hledger chat or hledger mail list Tag Table: Node: Top225 Node: OPTIONS2571 -Node: PERMISSIONS11103 -Node: EDITING UPLOADING DOWNLOADING12454 -Node: RELOADING13469 -Node: JSON API14036 -Node: DEBUG OUTPUT19685 -Node: Debug output19837 -Node: ENVIRONMENT20355 -Node: BUGS20591 +Node: PERMISSIONS11109 +Node: EDITING UPLOADING DOWNLOADING12460 +Node: RELOADING13475 +Node: JSON API14042 +Node: DEBUG OUTPUT19691 +Node: Debug output19843 +Node: ENVIRONMENT20361 +Node: BUGS20597  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 549e0cfbb..876e13531 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -167,8 +167,6 @@ OPTIONS YYYY-MM-DD: value on given date -c --commodity-style=S Override a commodity's display style. Eg: -c '.' or -c '1.000,00 EUR' - --color=YN --colour Use ANSI color codes in text output? Can be - 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -180,6 +178,8 @@ OPTIONS --man show the manual with man --version show version information --debug=[1-9] show this much debug output (default: 1) + --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) hledger-web shows accounts with zero balances by default (like hledger-ui, and unlike hledger). Using the -E/--empty flag will re- diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 78b0e15d9..8c9c777d7 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -420,8 +420,6 @@ General output/reporting flags (supported by some commands): YYYY\-MM\-DD: value on given date \-c \-\-commodity\-style=S Override a commodity\[aq]s display style. Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq] - \-\-color=YN \-\-colour Use ANSI color codes in text output? Can be - \[aq]y\[aq]/\[aq]yes\[aq]/\[aq]always\[aq], \[aq]n\[aq]/\[aq]no\[aq]/\[aq]never\[aq] or \[aq]auto\[aq]. \-\-pretty[=YN] Use box\-drawing characters in text output? Can be \[aq]y\[aq]/\[aq]yes\[aq] or \[aq]n\[aq]/\[aq]no\[aq]. If YN is specified, the equals is required. @@ -433,6 +431,8 @@ General help flags: \-\-man show the manual with man \-\-version show version information \-\-debug=[1\-9] show this much debug output (default: 1) + \-\-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) .EE .PP Usually hledger accepts any unambiguous flag prefix, eg you can write @@ -961,6 +961,7 @@ Y T}@T{ Y T}@T{ +Y T}@T{ T}@T{ T}@T{ @@ -1098,28 +1099,6 @@ override the file extension if needed: .EX $ hledger balancesheet \-o foo.txt \-O csv # write CSV to foo.txt .EE -.SS Paging -On unix\-like systems, when displaying large output in the terminal, -hledger tries to use a pager when appropriate: the one specified by the -\f[CR]PAGER\f[R] environment variable, otherwise \f[CR]less\f[R] if -available, otherwise \f[CR]more\f[R] if available. -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, -\f[CR]q\f[R] quits, and \f[CR]?\f[R] shows more features. -.PP -The pager is expected to display ANSI color and text styling if -possible. -hledger adds \f[CR]R\f[R] to the \f[CR]LESS\f[R] and \f[CR]MORE\f[R] -environment variables to enable this in \f[CR]less\f[R] (and in its -\f[CR]more\f[R] compatibility mode). -If you use a different pager, you might need to configure it similarly, -to avoid seeing junk on screen. -Or you can set the \f[CR]NO_COLOR\f[R] environment variable described -below. -.PP -You can prevent the use of a pager by providing the -\f[CR]\-\-no\-pager\f[R] flag at the command line, or in a config file. .PP Here are some notes about the various output formats. .SS Text output @@ -1146,29 +1125,52 @@ Besides using a pager, helpful techniques for this situation include \f[CR]\-\-layout=bare\f[R], \f[CR]\-V\f[R], \f[CR]cur:\f[R], \f[CR]\-\-transpose\f[R], \f[CR]\-\-tree\f[R], \f[CR]\-\-depth\f[R], \f[CR]\-\-drop\f[R], switching to html output, etc. +.SS Box\-drawing characters +hledger draws simple table borders by default, to minimise the risk of +display problems caused by a terminal/font not supporting box\-drawing +characters. .PP -(Help output uses a pager automatically when appropriate, but regular -reports do not, currently.) -.SS Colour -hledger tries to detect ANSI color and text styling support and use it -when appropriate, though currently rather minimally: some reports show -negative numbers in red, and help output uses bold text for emphasis. -.PP -You can override this in the usual ways. -If the \f[CR]NO_COLOR\f[R] environment variable is set, colour will be -disabled by default. -Or you can use the \f[CR]\-\-color/\-\-colour\f[R] option with a -\f[CR]y\f[R]/\f[CR]yes\f[R] value, or \f[CR]n\f[R]/\f[CR]no\f[R], to -force colour on or off. -(This option doesn\[aq]t work in a config file yet.) -.SS Box\-drawing -By default, hledger draws table borders using ascii characters, to -minimise the chance of display problems. -.PP -If your terminal and font support box\-drawing characters (they probably -do), you will probably want to use the \f[CR]\-\-pretty\f[R] flag to -show prettier tables. +But your terminal and font probably do support them, so we recommend +using the \f[CR]\-\-pretty\f[R] flag to show prettier tables in the +terminal. This is a good flag to add to your hledger config file. +.SS Colour +hledger tries to automatically detect ANSI colour and text styling +support and use it when appropriate. +(Currently, it is used rather minimally: some reports show negative +numbers in red, and help output uses bold text for emphasis.) +.PP +You can override this by setting the \f[CR]NO_COLOR\f[R] environment +variable to disable it, or by using the \f[CR]\-\-color/\-\-colour\f[R] +option, perhaps in your config file, with a \f[CR]y\f[R]/\f[CR]yes\f[R] +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 the +terminal, hledger tries to use a pager when appropriate. +(Actually it does this for any output format displayed in the terminal, +not just text.) +You can prevent this with the \f[CR]\-\-pager=no\f[R] option, perhaps in +your config file. +.PP +It will use the pager specified by the \f[CR]PAGER\f[R] environment +variable, otherwise \f[CR]less\f[R] if available, otherwise +\f[CR]more\f[R] if available. +.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, +\f[CR]q\f[R] quits, and \f[CR]?\f[R] shows more features. +(And in \f[CR]less\f[R], \f[CR]G\f[R] jumps to the end, which is useful +when you are viewing register output.) +.PP +The pager is expected to display hledger\[aq]s ANSI colour and text +styling. +hledger adds \f[CR]R\f[R] to the \f[CR]LESS\f[R] and \f[CR]MORE\f[R] +environment variables to enable this for \f[CR]less\f[R] and its +\f[CR]more\f[R] compatibility mode. +If you use a different pager, you might need to configure it similarly, +to avoid seeing junk on screen. +(Or you can disable colour, as described above.) .SS HTML output HTML output can be styled by an optional \f[CR]hledger.css\f[R] file in the same directory. @@ -2352,18 +2354,29 @@ Tags hledger adds to indicate generated data: generated\-transaction \-\- appears on generated periodic txns (with \-\-verbose\-tags) generated\-posting \-\- appears on generated auto postings (with \-\-verbose\-tags) modified \-\- appears on txns which have had auto postings added (with \-\-verbose\-tags) - -Not displayed, but queryable: +.EE +.PP +These similar tags are also provided; they are not displayed, but can be +relied on for querying: +.IP +.EX _generated\-transaction \-\- exists on generated periodic txns (always) _generated\-posting \-\- exists on generated auto postings (always) _modified \-\- exists on txns which have had auto postings added (always) .EE .PP -Other tags hledger uses internally: +The following non\-displayed tags are used internally by hledger, (1) to +ignore redundant costs when balancing transactions, (2) when using +\-\-infer\-costs, and (3) when using \-\-infer\-equity. +Essentially they mark postings with costs which have corresponding +equity conversion postings, and vice\-versa. +They are queryable, but you should not rely on them for your reports: .IP .EX - _cost\-matched \-\- marks postings with a cost which have been matched with a nearby pair of equity conversion postings - _conversion\-matched \-\- marks equity conversion postings which have been matched with a nearby posting with a cost + _conversion\-matched \-\- marks \[dq]matched conversion postings\[dq], which are to a V/Conversion account + and have a nearby equivalent costful or potentially costful posting + _cost\-matched \-\- marks \[dq]matched cost postings\[dq], which have or could have a cost + that\[aq]s equivalent to nearby conversion postings .EE .SS Tag values Tags can have a value, which is any text after the colon up until a @@ -8181,10 +8194,10 @@ heading. .IP .EX Flags: - \-i show the manual with info - \-m show the manual with man - \-p show the manual with $PAGER or less - (less is always used if TOPIC is specified) + \-i show the manual with info + \-m show the manual with man + \-p show the manual with $PAGER or less + (less is always used if TOPIC is specified) .EE .PP This command shows the hledger manual built in to your hledger @@ -8225,8 +8238,8 @@ Play demos of hledger usage in the terminal, if asciinema is installed. .IP .EX Flags: - \-s \-\-speed=SPEED playback speed (1 is original speed, .5 is half, 2 - is double, etc (default: 2)) + \-s \-\-speed=SPEED playback speed (1 is original speed, .5 is half, 2 + is double, etc (default: 2)) .EE .PP Run this command with no argument to list the demos. diff --git a/hledger/hledger.info b/hledger/hledger.info index 54f1378f0..7b808a977 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -436,8 +436,6 @@ General output/reporting flags (supported by some commands): YYYY-MM-DD: value on given date -c --commodity-style=S Override a commodity's display style. Eg: -c '.' or -c '1.000,00 EUR' - --color=YN --colour Use ANSI color codes in text output? Can be - 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -449,6 +447,8 @@ General help flags: --man show the manual with man --version show version information --debug=[1-9] show this much debug output (default: 1) + --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 '--tl' instead of '--tldr' or '--dry' instead of '--dry-run'. @@ -921,7 +921,6 @@ File: hledger.info, Node: Output, Next: Environment, Prev: Options, Up: Top * Output destination:: * Output format:: -* Paging:: * Commodity styles:: * Debug output:: @@ -944,7 +943,7 @@ $ hledger print -o foo.txt $ hledger print -o - # write to stdout (the default)  -File: hledger.info, Node: Output format, Next: Paging, Prev: Output destination, Up: Output +File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output 5.2 Output format ================= @@ -954,7 +953,7 @@ terminal. Here are those commands and the formats currently supported: command txt html csv/tsv fods beancount sql json ------------------------------------------------------------------------------ -aregister Y Y Y Y +aregister Y Y Y Y Y balance Y Y Y Y Y balancesheet Y Y Y Y Y balancesheetequity Y Y Y Y Y @@ -980,29 +979,6 @@ extension if needed: $ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt - -File: hledger.info, Node: Paging, Next: Commodity styles, Prev: Output format, Up: Output - -5.3 Paging -========== - -On unix-like systems, when displaying large output in the terminal, -hledger tries to use a pager when appropriate: the one specified by the -'PAGER' environment variable, otherwise 'less' if available, otherwise -'more' if available. 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, 'q' quits, and '?' shows more features. - - The pager is expected to display ANSI color and text styling if -possible. hledger adds 'R' to the 'LESS' and 'MORE' environment -variables to enable this in 'less' (and in its 'more' compatibility -mode). If you use a different pager, you might need to configure it -similarly, to avoid seeing junk on screen. Or you can set the -'NO_COLOR' environment variable described below. - - You can prevent the use of a pager by providing the '--no-pager' flag -at the command line, or in a config file. - Here are some notes about the various output formats. * Menu: @@ -1016,9 +992,9 @@ at the command line, or in a config file. * JSON output::  -File: hledger.info, Node: Text output, Next: HTML output, Up: Paging +File: hledger.info, Node: Text output, Next: HTML output, Up: Output format -5.3.1 Text output +5.2.1 Text output ----------------- This is the default: human readable, plain text report output, suitable @@ -1040,48 +1016,73 @@ techniques for this situation include '--layout=bare', '-V', 'cur:', '--transpose', '--tree', '--depth', '--drop', switching to html output, etc. - (Help output uses a pager automatically when appropriate, but regular -reports do not, currently.) - * Menu: +* Box-drawing characters:: * Colour:: -* Box-drawing:: +* Paging::  -File: hledger.info, Node: Colour, Next: Box-drawing, Up: Text output +File: hledger.info, Node: Box-drawing characters, Next: Colour, Up: Text output -5.3.1.1 Colour +5.2.1.1 Box-drawing characters +.............................. + +hledger draws simple table borders by default, to minimise the risk of +display problems caused by a terminal/font not supporting box-drawing +characters. + + But your terminal and font probably do support them, so we recommend +using the '--pretty' flag to show prettier tables in the terminal. This +is a good flag to add to your hledger config file. + + +File: hledger.info, Node: Colour, Next: Paging, Prev: Box-drawing characters, Up: Text output + +5.2.1.2 Colour .............. -hledger tries to detect ANSI color and text styling support and use it -when appropriate, though currently rather minimally: some reports show -negative numbers in red, and help output uses bold text for emphasis. +hledger tries to automatically detect ANSI colour and text styling +support and use it when appropriate. (Currently, it is used rather +minimally: some reports show negative numbers in red, and help output +uses bold text for emphasis.) - You can override this in the usual ways. If the 'NO_COLOR' -environment variable is set, colour will be disabled by default. Or you -can use the '--color/--colour' option with a 'y'/'yes' value, or -'n'/'no', to force colour on or off. (This option doesn't work in a -config file yet.) + You can override this by setting the 'NO_COLOR' environment variable +to disable it, or by using the '--color/--colour' option, perhaps in +your config file, with a 'y'/'yes' or 'n'/'no' value to force it on or +off.  -File: hledger.info, Node: Box-drawing, Prev: Colour, Up: Text output +File: hledger.info, Node: Paging, Prev: Colour, Up: Text output -5.3.1.2 Box-drawing -................... +5.2.1.3 Paging +.............. -By default, hledger draws table borders using ascii characters, to -minimise the chance of display problems. - - If your terminal and font support box-drawing characters (they -probably do), you will probably want to use the '--pretty' flag to show -prettier tables. This is a good flag to add to your hledger config +In unix-like environments, when displaying large output in the terminal, +hledger tries to use a pager when appropriate. (Actually it does this +for any output format displayed in the terminal, not just text.) You +can prevent this with the '--pager=no' option, perhaps in your config file. - -File: hledger.info, Node: HTML output, Next: CSV / TSV output, Prev: Text output, Up: Paging + It will use the pager specified by the 'PAGER' environment variable, +otherwise 'less' if available, otherwise 'more' if available. -5.3.2 HTML output + 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, 'q' quits, and '?' shows more features. (And in 'less', 'G' jumps +to the end, which is useful when you are viewing register output.) + + The pager is expected to display hledger's ANSI colour and text +styling. hledger adds 'R' to the 'LESS' and 'MORE' environment +variables to enable this for 'less' and its 'more' compatibility mode. +If you use a different pager, you might need to configure it similarly, +to avoid seeing junk on screen. (Or you can disable colour, as +described above.) + + +File: hledger.info, Node: HTML output, Next: CSV / TSV output, Prev: Text output, Up: Output format + +5.2.2 HTML output ----------------- HTML output can be styled by an optional 'hledger.css' file in the same @@ -1093,18 +1094,18 @@ in Safari, see View -> Text Encoding and Settings -> Advanced -> Default Encoding.  -File: hledger.info, Node: CSV / TSV output, Next: FODS output, Prev: HTML output, Up: Paging +File: hledger.info, Node: CSV / TSV output, Next: FODS output, Prev: HTML output, Up: Output format -5.3.3 CSV / TSV output +5.2.3 CSV / TSV output ---------------------- In CSV or TSV output, digit group marks (such as thousands separators) are disabled automatically.  -File: hledger.info, Node: FODS output, Next: Beancount output, Prev: CSV / TSV output, Up: Paging +File: hledger.info, Node: FODS output, Next: Beancount output, Prev: CSV / TSV output, Up: Output format -5.3.4 FODS output +5.2.4 FODS output ----------------- FODS is the OpenDocument Spreadsheet format as plain XML, as accepted by @@ -1119,9 +1120,9 @@ CSV from FODS/ODS using various utilities like 'libreoffice --headless' or ods2csv.  -File: hledger.info, Node: Beancount output, Next: SQL output, Prev: FODS output, Up: Paging +File: hledger.info, Node: Beancount output, Next: SQL output, Prev: FODS output, Up: Output format -5.3.5 Beancount output +5.2.5 Beancount output ---------------------- This is Beancount's journal format. You can use this to export your @@ -1146,7 +1147,7 @@ Beancount" https://hledger.org/beancount.html).  File: hledger.info, Node: Beancount account names, Next: Beancount commodity names, Up: Beancount output -5.3.5.1 Beancount account names +5.2.5.1 Beancount account names ............................... hledger will try adjust your account names, if needed, to Beancount @@ -1166,7 +1167,7 @@ config file. (An example: hledger2beancount.conf)  File: hledger.info, Node: Beancount commodity names, Next: Beancount virtual postings, Prev: Beancount account names, Up: Beancount output -5.3.5.2 Beancount commodity names +5.2.5.2 Beancount commodity names ................................. hledger will adjust your commodity names, if needed, to Beancount @@ -1182,7 +1183,7 @@ name.)  File: hledger.info, Node: Beancount virtual postings, Next: Beancount costs, Prev: Beancount commodity names, Up: Beancount output -5.3.5.3 Beancount virtual postings +5.2.5.3 Beancount virtual postings .................................. Beancount doesn't allow unbalanced/virtual postings, so you will need to @@ -1193,7 +1194,7 @@ postings, you'll have to do something more.)  File: hledger.info, Node: Beancount costs, Next: Beancount operating currency, Prev: Beancount virtual postings, Up: Beancount output -5.3.5.4 Beancount costs +5.2.5.4 Beancount costs ....................... Beancount doesn't allow redundant cost notation as hledger does. If you @@ -1203,7 +1204,7 @@ the equity postings.  File: hledger.info, Node: Beancount operating currency, Prev: Beancount costs, Up: Beancount output -5.3.5.5 Beancount operating currency +5.2.5.5 Beancount operating currency .................................... Declaring an operating currency improves Beancount and Fava reports. @@ -1213,9 +1214,9 @@ journal: option "operating_currency" "USD"  -File: hledger.info, Node: SQL output, Next: JSON output, Prev: Beancount output, Up: Paging +File: hledger.info, Node: SQL output, Next: JSON output, Prev: Beancount output, Up: Output format -5.3.6 SQL output +5.2.6 SQL output ---------------- SQL output is expected to work at least with SQLite, MySQL and Postgres. @@ -1234,9 +1235,9 @@ $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT N This is not yet much used; feedback is welcome.  -File: hledger.info, Node: JSON output, Prev: SQL output, Up: Paging +File: hledger.info, Node: JSON output, Prev: SQL output, Up: Output format -5.3.7 JSON output +5.2.7 JSON output ----------------- Our JSON is rather large and verbose, since it is a faithful @@ -1254,9 +1255,9 @@ know. Related: #1195 This is not yet much used; feedback is welcome.  -File: hledger.info, Node: Commodity styles, Next: Debug output, Prev: Paging, Up: Output +File: hledger.info, Node: Commodity styles, Next: Debug output, Prev: Output format, Up: Output -5.4 Commodity styles +5.3 Commodity styles ==================== When displaying amounts, hledger infers a standard display style for @@ -1279,7 +1280,7 @@ parseability (such as adding trailing decimal marks when needed).  File: hledger.info, Node: Debug output, Prev: Commodity styles, Up: Output -5.5 Debug output +5.4 Debug output ================ We intend hledger to be relatively easy to troubleshoot, introspect and @@ -2415,15 +2416,24 @@ elsewhere, but here is a quick list for reference: generated-posting -- appears on generated auto postings (with --verbose-tags) modified -- appears on txns which have had auto postings added (with --verbose-tags) -Not displayed, but queryable: + These similar tags are also provided; they are not displayed, but can +be relied on for querying: + _generated-transaction -- exists on generated periodic txns (always) _generated-posting -- exists on generated auto postings (always) _modified -- exists on txns which have had auto postings added (always) - Other tags hledger uses internally: + The following non-displayed tags are used internally by hledger, (1) +to ignore redundant costs when balancing transactions, (2) when using +-infer-costs, and (3) when using -infer-equity. Essentially they mark +postings with costs which have corresponding equity conversion postings, +and vice-versa. They are queryable, but you should not rely on them for +your reports: - _cost-matched -- marks postings with a cost which have been matched with a nearby pair of equity conversion postings - _conversion-matched -- marks equity conversion postings which have been matched with a nearby posting with a cost + _conversion-matched -- marks "matched conversion postings", which are to a V/Conversion account + and have a nearby equivalent costful or potentially costful posting + _cost-matched -- marks "matched cost postings", which have or could have a cost + that's equivalent to nearby conversion postings  File: hledger.info, Node: Tag values, Prev: Special tags, Up: Tags @@ -7823,10 +7833,10 @@ Show the hledger user manual with 'info', 'man', or a pager. With a heading. Flags: - -i show the manual with info - -m show the manual with man - -p show the manual with $PAGER or less - (less is always used if TOPIC is specified) + -i show the manual with info + -m show the manual with man + -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 executable. It can be useful when offline, or when you prefer the @@ -7863,8 +7873,8 @@ File: hledger.info, Node: demo, Prev: help, Up: Help commands Play demos of hledger usage in the terminal, if asciinema is installed. Flags: - -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 - is double, etc (default: 2)) + -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, write its number or a prefix or substring of its title. Tips: @@ -12044,350 +12054,350 @@ Node: Strict mode9126 Node: Commands9960 Node: Add-on commands11146 Node: Options12364 -Node: Special characters18781 -Node: Escaping shell special characters19731 -Node: Escaping on Windows20975 -Node: Escaping regular expression special characters21708 -Node: Escaping add-on arguments22695 -Node: Escaping in other situations23724 -Node: Using a wild card24683 -Node: Unicode characters25062 -Node: Regular expressions26726 -Node: hledger's regular expressions29985 -Node: Argument files31530 -Node: Config files32233 -Node: Shell completions35386 -Node: Output35911 -Node: Output destination36113 -Node: Output format36671 -Node: Paging38258 -Node: Text output39481 -Node: Colour40751 -Node: Box-drawing41359 -Node: HTML output41797 -Node: CSV / TSV output42244 -Node: FODS output42491 -Node: Beancount output43288 -Node: Beancount account names44199 -Node: Beancount commodity names45174 -Node: Beancount virtual postings45950 -Node: Beancount costs46421 -Node: Beancount operating currency46779 -Node: SQL output47143 -Node: JSON output47927 -Node: Commodity styles48737 -Node: Debug output49614 -Node: Environment50446 -Node: PART 2 DATA FORMATS51140 -Node: Journal51283 -Node: Journal cheatsheet53761 -Node: Comments59975 -Node: Transactions60919 -Node: Dates62056 -Node: Simple dates62208 -Node: Posting dates62824 -Node: Status63911 -Node: Code65677 -Node: Description66012 -Node: Payee and note66699 -Node: Transaction comments67790 -Node: Postings68306 -Node: Debits and credits69469 -Node: The two space delimiter70079 -Node: Account names70644 -Node: Amounts72448 -Node: Decimal marks73477 -Node: Digit group marks74581 -Node: Commodity75216 -Node: Costs76333 -Node: Balance assertions78585 -Node: Assertions and ordering79822 -Node: Assertions and multiple included files80550 -Node: Assertions and multiple -f files81310 -Node: Assertions and costs81952 -Node: Assertions and commodities82602 -Node: Assertions and subaccounts84261 -Node: Assertions and virtual postings84931 -Node: Assertions and auto postings85301 -Node: Assertions and precision86176 -Node: Posting comments86625 -Node: Transaction balancing87165 -Node: Tags89167 -Node: Tag names90629 -Node: Special tags91124 -Node: Tag values92916 -Node: Directives93898 -Node: Directives and multiple files95355 -Node: Directive effects96300 -Node: account directive99456 -Node: Account comments100906 -Node: Account error checking101565 -Node: Account display order103102 -Node: Account types104300 -Node: alias directive108074 -Node: Basic aliases109285 -Node: Regex aliases110160 -Node: Combining aliases111207 -Node: Aliases and multiple files112661 -Node: end aliases directive113444 -Node: Aliases can generate bad account names113812 -Node: Aliases and account types114645 -Node: commodity directive115533 -Node: Commodity directive syntax117120 -Node: Commodity error checking118756 -Node: decimal-mark directive119231 -Node: include directive119810 -Node: P directive120886 -Node: payee directive121920 -Node: tag directive122542 -Node: Periodic transactions123154 -Node: Periodic rule syntax125308 -Node: Periodic rules and relative dates126131 -Node: Two spaces between period expression and description!126908 -Node: Auto postings127869 -Node: Auto postings and multiple files131029 -Node: Auto postings and dates131434 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions131875 -Node: Auto posting tags132721 -Node: Auto postings on forecast transactions only133616 -Node: Other syntax134086 -Node: Balance assignments134858 -Node: Balance assignments and costs136386 -Node: Balance assignments and multiple files136808 -Node: Bracketed posting dates137231 -Node: D directive137929 -Node: apply account directive139702 -Node: Y directive140569 -Node: Secondary dates141557 -Node: Star comments143042 -Node: Valuation expressions143734 -Node: Virtual postings144033 -Node: Other Ledger directives145657 -Node: Other cost/lot notations146419 -Node: CSV149181 -Node: CSV rules cheatsheet151264 -Node: source153189 -Node: separator154190 -Node: skip154841 -Node: date-format155491 -Node: timezone156334 -Node: newest-first157460 -Node: intra-day-reversed158173 -Node: decimal-mark158773 -Node: fields list159251 -Node: Field assignment161059 -Node: Field names162278 -Node: date field163610 -Node: date2 field163774 -Node: status field163969 -Node: code field164159 -Node: description field164347 -Node: comment field164564 -Node: account field165121 -Node: amount field165839 -Node: currency field168678 -Node: balance field169086 -Node: if block169609 -Node: Matchers171136 -Node: What matchers match172045 -Node: Combining matchers172632 -Node: Match groups173335 -Node: if table174229 -Node: balance-type176230 -Node: include177057 -Node: Working with CSV177626 -Node: Rapid feedback178178 -Node: Valid CSV178761 -Node: File Extension179637 -Node: Reading CSV from standard input180372 -Node: Reading multiple CSV files180758 -Node: Reading files specified by rule181234 -Node: Valid transactions182631 -Node: Deduplicating importing183456 -Node: Setting amounts184685 -Node: Amount signs187212 -Node: Setting currency/commodity188277 -Node: Amount decimal places189653 -Node: Referencing other fields190910 -Node: How CSV rules are evaluated192018 -Node: Well factored rules193686 -Node: CSV rules examples194176 -Node: Bank of Ireland194374 -Node: Coinbase195971 -Node: Amazon197154 -Node: Paypal198996 -Node: Timeclock206746 -Node: Timedot209015 -Node: Timedot examples212492 -Node: PART 3 REPORTING CONCEPTS214769 -Node: Time periods214933 -Node: Report start & end date215206 -Node: Smart dates216682 -Node: Report intervals218625 -Node: Date adjustments219199 -Node: Start date adjustment219419 -Node: End date adjustment220322 -Node: Period headings221067 -Node: Period expressions222000 -Node: Period expressions with a report interval223905 -Node: More complex report intervals224353 -Node: Multiple weekday intervals226469 -Node: Depth227480 -Node: Queries227878 -Node: Query types229576 -Node: Combining query terms232931 -Node: Queries and command options234671 -Node: Queries and account aliases235125 -Node: Queries and valuation235450 -Node: Pivoting235812 -Node: Generating data237703 -Node: Forecasting239503 -Node: --forecast240159 -Node: Inspecting forecast transactions241260 -Node: Forecast reports242593 -Node: Forecast tags243702 -Node: Forecast period in detail244322 -Node: Forecast troubleshooting245410 -Node: Budgeting246481 -Node: Amount formatting247041 -Node: Commodity display style247285 -Node: Rounding249126 -Node: Trailing decimal marks249731 -Node: Amount parseability250664 -Node: Cost reporting252245 -Node: Recording costs253048 -Node: Reporting at cost254775 -Node: Equity conversion postings255540 -Node: Inferring equity conversion postings258185 -Node: Combining costs and equity conversion postings259327 -Node: Requirements for detecting equity conversion postings260552 -Node: Infer cost and equity by default ?262074 -Node: Value reporting262511 -Node: -V Value263392 -Node: -X Value in specified commodity263719 -Node: Valuation date264069 -Node: Finding market price265029 -Node: --infer-market-prices market prices from transactions266409 -Node: Valuation commodity269453 -Node: --value Flexible valuation270886 -Node: Valuation examples272729 -Node: Interaction of valuation and queries274861 -Node: Effect of valuation on reports275578 -Node: PART 4 COMMANDS283476 -Node: Help commands285692 -Node: help285865 -Node: demo287566 -Node: User interface commands288711 -Node: ui288905 -Node: web289030 -Node: Data entry commands289158 -Node: add289356 -Node: import291811 -Node: Date skipping293072 -Node: Import testing295973 -Node: Importing balance assignments296979 -Node: Import and commodity styles297835 -Node: Basic report commands298244 -Node: accounts298545 -Node: codes301418 -Node: commodities302440 -Node: descriptions302684 -Node: files303151 -Node: notes303448 -Node: payees303960 -Node: prices304744 -Node: stats305636 -Node: tags307377 -Node: Standard report commands308684 -Node: print308989 -Node: print explicitness311663 -Node: print amount style312583 -Node: print parseability313821 -Node: print other features314740 -Node: print output format315438 -Node: aregister318723 -Node: aregister and posting dates322503 -Node: register323404 -Node: Custom register output330591 -Node: balancesheet332067 -Node: balancesheetequity336979 -Node: cashflow342261 -Node: incomestatement346965 -Node: Advanced report commands351705 -Node: balance351913 -Node: balance features357083 -Node: Simple balance report359159 -Node: Balance report line format360969 -Node: Filtered balance report363329 -Node: List or tree mode363848 -Node: Depth limiting365361 -Node: Dropping top-level accounts366128 -Node: Showing declared accounts366638 -Node: Sorting by amount367368 -Node: Percentages368205 -Node: Multi-period balance report368912 -Node: Balance change end balance371664 -Node: Balance report types373301 -Node: Calculation type373980 -Node: Accumulation type374684 -Node: Valuation type375785 -Node: Combining balance report types376974 -Node: Budget report379006 -Node: Using the budget report381311 -Node: Budget date surprises383587 -Node: Selecting budget goals384951 -Node: Budgeting vs forecasting385899 -Node: Balance report layout387576 -Node: Wide layout388781 -Node: Tall layout391186 -Node: Bare layout392492 -Node: Tidy layout394556 -Node: Balance report output396100 -Node: Some useful balance reports397086 -Node: roi398346 -Node: Spaces and special characters in --inv and --pnl400593 -Node: Semantics of --inv and --pnl401319 -Node: IRR and TWR explained403406 -Node: Chart commands406817 -Node: activity406998 -Node: Data generation commands407495 -Node: close407701 -Node: close --migrate410293 -Node: close --close412057 -Node: close --open412435 -Node: close --assert412684 -Node: close --assign413049 -Node: close --retain413721 -Node: close customisation414617 -Node: close and balance assertions416261 -Node: close examples417783 -Node: Retain earnings418020 -Node: Migrate balances to a new file418523 -Node: More detailed close examples419875 -Node: rewrite420097 -Node: Re-write rules in a file422669 -Node: Diff output format423979 -Node: rewrite vs print --auto425252 -Node: Maintenance commands425966 -Node: check426175 -Node: Basic checks427257 -Node: Strict checks428210 -Node: Other checks429085 -Node: Custom checks430940 -Node: diff431395 -Node: test432602 -Node: PART 5 COMMON TASKS433474 -Node: Getting help433707 -Node: Constructing command lines434616 -Node: Starting a journal file435454 -Node: Setting LEDGER_FILE436838 -Node: Setting opening balances437967 -Node: Recording transactions441289 -Node: Reconciling442014 -Node: Reporting444403 -Node: Migrating to a new file448517 -Node: BUGS448966 -Node: Troubleshooting449939 +Node: Special characters18787 +Node: Escaping shell special characters19737 +Node: Escaping on Windows20981 +Node: Escaping regular expression special characters21714 +Node: Escaping add-on arguments22701 +Node: Escaping in other situations23730 +Node: Using a wild card24689 +Node: Unicode characters25068 +Node: Regular expressions26732 +Node: hledger's regular expressions29991 +Node: Argument files31536 +Node: Config files32239 +Node: Shell completions35392 +Node: Output35917 +Node: Output destination36108 +Node: Output format36666 +Node: Text output38452 +Node: Box-drawing characters39649 +Node: Colour40149 +Node: Paging40735 +Node: HTML output41899 +Node: CSV / TSV output42353 +Node: FODS output42607 +Node: Beancount output43411 +Node: Beancount account names44329 +Node: Beancount commodity names45304 +Node: Beancount virtual postings46080 +Node: Beancount costs46551 +Node: Beancount operating currency46909 +Node: SQL output47273 +Node: JSON output48064 +Node: Commodity styles48881 +Node: Debug output49765 +Node: Environment50597 +Node: PART 2 DATA FORMATS51291 +Node: Journal51434 +Node: Journal cheatsheet53912 +Node: Comments60126 +Node: Transactions61070 +Node: Dates62207 +Node: Simple dates62359 +Node: Posting dates62975 +Node: Status64062 +Node: Code65828 +Node: Description66163 +Node: Payee and note66850 +Node: Transaction comments67941 +Node: Postings68457 +Node: Debits and credits69620 +Node: The two space delimiter70230 +Node: Account names70795 +Node: Amounts72599 +Node: Decimal marks73628 +Node: Digit group marks74732 +Node: Commodity75367 +Node: Costs76484 +Node: Balance assertions78736 +Node: Assertions and ordering79973 +Node: Assertions and multiple included files80701 +Node: Assertions and multiple -f files81461 +Node: Assertions and costs82103 +Node: Assertions and commodities82753 +Node: Assertions and subaccounts84412 +Node: Assertions and virtual postings85082 +Node: Assertions and auto postings85452 +Node: Assertions and precision86327 +Node: Posting comments86776 +Node: Transaction balancing87316 +Node: Tags89318 +Node: Tag names90780 +Node: Special tags91275 +Node: Tag values93587 +Node: Directives94569 +Node: Directives and multiple files96026 +Node: Directive effects96971 +Node: account directive100127 +Node: Account comments101577 +Node: Account error checking102236 +Node: Account display order103773 +Node: Account types104971 +Node: alias directive108745 +Node: Basic aliases109956 +Node: Regex aliases110831 +Node: Combining aliases111878 +Node: Aliases and multiple files113332 +Node: end aliases directive114115 +Node: Aliases can generate bad account names114483 +Node: Aliases and account types115316 +Node: commodity directive116204 +Node: Commodity directive syntax117791 +Node: Commodity error checking119427 +Node: decimal-mark directive119902 +Node: include directive120481 +Node: P directive121557 +Node: payee directive122591 +Node: tag directive123213 +Node: Periodic transactions123825 +Node: Periodic rule syntax125979 +Node: Periodic rules and relative dates126802 +Node: Two spaces between period expression and description!127579 +Node: Auto postings128540 +Node: Auto postings and multiple files131700 +Node: Auto postings and dates132105 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions132546 +Node: Auto posting tags133392 +Node: Auto postings on forecast transactions only134287 +Node: Other syntax134757 +Node: Balance assignments135529 +Node: Balance assignments and costs137057 +Node: Balance assignments and multiple files137479 +Node: Bracketed posting dates137902 +Node: D directive138600 +Node: apply account directive140373 +Node: Y directive141240 +Node: Secondary dates142228 +Node: Star comments143713 +Node: Valuation expressions144405 +Node: Virtual postings144704 +Node: Other Ledger directives146328 +Node: Other cost/lot notations147090 +Node: CSV149852 +Node: CSV rules cheatsheet151935 +Node: source153860 +Node: separator154861 +Node: skip155512 +Node: date-format156162 +Node: timezone157005 +Node: newest-first158131 +Node: intra-day-reversed158844 +Node: decimal-mark159444 +Node: fields list159922 +Node: Field assignment161730 +Node: Field names162949 +Node: date field164281 +Node: date2 field164445 +Node: status field164640 +Node: code field164830 +Node: description field165018 +Node: comment field165235 +Node: account field165792 +Node: amount field166510 +Node: currency field169349 +Node: balance field169757 +Node: if block170280 +Node: Matchers171807 +Node: What matchers match172716 +Node: Combining matchers173303 +Node: Match groups174006 +Node: if table174900 +Node: balance-type176901 +Node: include177728 +Node: Working with CSV178297 +Node: Rapid feedback178849 +Node: Valid CSV179432 +Node: File Extension180308 +Node: Reading CSV from standard input181043 +Node: Reading multiple CSV files181429 +Node: Reading files specified by rule181905 +Node: Valid transactions183302 +Node: Deduplicating importing184127 +Node: Setting amounts185356 +Node: Amount signs187883 +Node: Setting currency/commodity188948 +Node: Amount decimal places190324 +Node: Referencing other fields191581 +Node: How CSV rules are evaluated192689 +Node: Well factored rules194357 +Node: CSV rules examples194847 +Node: Bank of Ireland195045 +Node: Coinbase196642 +Node: Amazon197825 +Node: Paypal199667 +Node: Timeclock207417 +Node: Timedot209686 +Node: Timedot examples213163 +Node: PART 3 REPORTING CONCEPTS215440 +Node: Time periods215604 +Node: Report start & end date215877 +Node: Smart dates217353 +Node: Report intervals219296 +Node: Date adjustments219870 +Node: Start date adjustment220090 +Node: End date adjustment220993 +Node: Period headings221738 +Node: Period expressions222671 +Node: Period expressions with a report interval224576 +Node: More complex report intervals225024 +Node: Multiple weekday intervals227140 +Node: Depth228151 +Node: Queries228549 +Node: Query types230247 +Node: Combining query terms233602 +Node: Queries and command options235342 +Node: Queries and account aliases235796 +Node: Queries and valuation236121 +Node: Pivoting236483 +Node: Generating data238374 +Node: Forecasting240174 +Node: --forecast240830 +Node: Inspecting forecast transactions241931 +Node: Forecast reports243264 +Node: Forecast tags244373 +Node: Forecast period in detail244993 +Node: Forecast troubleshooting246081 +Node: Budgeting247152 +Node: Amount formatting247712 +Node: Commodity display style247956 +Node: Rounding249797 +Node: Trailing decimal marks250402 +Node: Amount parseability251335 +Node: Cost reporting252916 +Node: Recording costs253719 +Node: Reporting at cost255446 +Node: Equity conversion postings256211 +Node: Inferring equity conversion postings258856 +Node: Combining costs and equity conversion postings259998 +Node: Requirements for detecting equity conversion postings261223 +Node: Infer cost and equity by default ?262745 +Node: Value reporting263182 +Node: -V Value264063 +Node: -X Value in specified commodity264390 +Node: Valuation date264740 +Node: Finding market price265700 +Node: --infer-market-prices market prices from transactions267080 +Node: Valuation commodity270124 +Node: --value Flexible valuation271557 +Node: Valuation examples273400 +Node: Interaction of valuation and queries275532 +Node: Effect of valuation on reports276249 +Node: PART 4 COMMANDS284147 +Node: Help commands286363 +Node: help286536 +Node: demo288241 +Node: User interface commands289388 +Node: ui289582 +Node: web289707 +Node: Data entry commands289835 +Node: add290033 +Node: import292488 +Node: Date skipping293749 +Node: Import testing296650 +Node: Importing balance assignments297656 +Node: Import and commodity styles298512 +Node: Basic report commands298921 +Node: accounts299222 +Node: codes302095 +Node: commodities303117 +Node: descriptions303361 +Node: files303828 +Node: notes304125 +Node: payees304637 +Node: prices305421 +Node: stats306313 +Node: tags308054 +Node: Standard report commands309361 +Node: print309666 +Node: print explicitness312340 +Node: print amount style313260 +Node: print parseability314498 +Node: print other features315417 +Node: print output format316115 +Node: aregister319400 +Node: aregister and posting dates323180 +Node: register324081 +Node: Custom register output331268 +Node: balancesheet332744 +Node: balancesheetequity337656 +Node: cashflow342938 +Node: incomestatement347642 +Node: Advanced report commands352382 +Node: balance352590 +Node: balance features357760 +Node: Simple balance report359836 +Node: Balance report line format361646 +Node: Filtered balance report364006 +Node: List or tree mode364525 +Node: Depth limiting366038 +Node: Dropping top-level accounts366805 +Node: Showing declared accounts367315 +Node: Sorting by amount368045 +Node: Percentages368882 +Node: Multi-period balance report369589 +Node: Balance change end balance372341 +Node: Balance report types373978 +Node: Calculation type374657 +Node: Accumulation type375361 +Node: Valuation type376462 +Node: Combining balance report types377651 +Node: Budget report379683 +Node: Using the budget report381988 +Node: Budget date surprises384264 +Node: Selecting budget goals385628 +Node: Budgeting vs forecasting386576 +Node: Balance report layout388253 +Node: Wide layout389458 +Node: Tall layout391863 +Node: Bare layout393169 +Node: Tidy layout395233 +Node: Balance report output396777 +Node: Some useful balance reports397763 +Node: roi399023 +Node: Spaces and special characters in --inv and --pnl401270 +Node: Semantics of --inv and --pnl401996 +Node: IRR and TWR explained404083 +Node: Chart commands407494 +Node: activity407675 +Node: Data generation commands408172 +Node: close408378 +Node: close --migrate410970 +Node: close --close412734 +Node: close --open413112 +Node: close --assert413361 +Node: close --assign413726 +Node: close --retain414398 +Node: close customisation415294 +Node: close and balance assertions416938 +Node: close examples418460 +Node: Retain earnings418697 +Node: Migrate balances to a new file419200 +Node: More detailed close examples420552 +Node: rewrite420774 +Node: Re-write rules in a file423346 +Node: Diff output format424656 +Node: rewrite vs print --auto425929 +Node: Maintenance commands426643 +Node: check426852 +Node: Basic checks427934 +Node: Strict checks428887 +Node: Other checks429762 +Node: Custom checks431617 +Node: diff432072 +Node: test433279 +Node: PART 5 COMMON TASKS434151 +Node: Getting help434384 +Node: Constructing command lines435293 +Node: Starting a journal file436131 +Node: Setting LEDGER_FILE437515 +Node: Setting opening balances438644 +Node: Recording transactions441966 +Node: Reconciling442691 +Node: Reporting445080 +Node: Migrating to a new file449194 +Node: BUGS449643 +Node: Troubleshooting450616  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index c0953bfdf..0a01159fb 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -320,8 +320,6 @@ Options YYYY-MM-DD: value on given date -c --commodity-style=S Override a commodity's display style. Eg: -c '.' or -c '1.000,00 EUR' - --color=YN --colour Use ANSI color codes in text output? Can be - 'y'/'yes'/'always', 'n'/'no'/'never' or 'auto'. --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. @@ -333,6 +331,8 @@ Options --man show the manual with man --version show version information --debug=[1-9] show this much debug output (default: 1) + --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 --tl instead of --tldr or --dry instead of --dry-run. @@ -736,7 +736,7 @@ Output command txt html csv/tsv fods beancount sql json -------------------------------------------------------------------------------------------- - aregister Y Y Y Y + aregister Y Y Y Y Y balance Y Y Y Y Y balancesheet Y Y Y Y Y balancesheetequity Y Y Y Y Y @@ -762,24 +762,6 @@ Output $ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt - Paging - On unix-like systems, when displaying large output in the terminal, - hledger tries to use a pager when appropriate: the one specified by the - PAGER environment variable, otherwise less if available, otherwise more - if available. 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, q quits, and ? shows more features. - - The pager is expected to display ANSI color and text styling if possi- - ble. hledger adds R to the LESS and MORE environment variables to en- - able this in less (and in its more compatibility mode). If you use a - different pager, you might need to configure it similarly, to avoid - seeing junk on screen. Or you can set the NO_COLOR environment vari- - able described below. - - You can prevent the use of a pager by providing the --no-pager flag at - the command line, or in a config file. - Here are some notes about the various output formats. Text output @@ -788,132 +770,152 @@ 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 + 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 + working or you want to override it, you can manually set COLUMNS, or use the -w/--width option. - Balance reports (balance, balancesheet, incomestatement...) use what- + Balance reports (balance, balancesheet, incomestatement...) use what- ever width they need. Multi-period multi-currency reports can often be - wider than the window. Besides using a pager, helpful techniques for - this situation include --layout=bare, -V, cur:, --transpose, --tree, + wider than the window. Besides using a pager, helpful techniques for + this situation include --layout=bare, -V, cur:, --transpose, --tree, --depth, --drop, switching to html output, etc. - (Help output uses a pager automatically when appropriate, but regular - reports do not, currently.) + Box-drawing characters + hledger draws simple table borders by default, to minimise the risk of + display problems caused by a terminal/font not supporting box-drawing + characters. + + But your terminal and font probably do support them, so we recommend + using the --pretty flag to show prettier tables in the terminal. This + is a good flag to add to your hledger config file. Colour - hledger tries to detect ANSI color and text styling support and use it - when appropriate, though currently rather minimally: some reports show - negative numbers in red, and help output uses bold text for emphasis. + hledger tries to automatically detect ANSI colour and text styling sup- + port and use it when appropriate. (Currently, it is used rather mini- + mally: some reports show negative numbers in red, and help output uses + bold text for emphasis.) - You can override this in the usual ways. If the NO_COLOR environment - variable is set, colour will be disabled by default. Or you can use - the --color/--colour option with a y/yes value, or n/no, to force - colour on or off. (This option doesn't work in a config file yet.) + You can override this by setting the NO_COLOR environment variable to + disable it, or by using the --color/--colour option, perhaps in your + config file, with a y/yes or n/no value to force it on or off. - Box-drawing - By default, hledger draws table borders using ascii characters, to min- - imise the chance of display problems. + Paging + In unix-like environments, when displaying large output in the termi- + nal, hledger tries to use a pager when appropriate. (Actually it does + this for any output format displayed in the terminal, not just text.) + You can prevent this with the --pager=no option, perhaps in your config + file. - If your terminal and font support box-drawing characters (they probably - do), you will probably want to use the --pretty flag to show prettier - tables. This is a good flag to add to your hledger config file. + It will use the pager specified by the PAGER environment variable, oth- + erwise less if available, otherwise more if available. + + 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, q + quits, and ? shows more features. (And in less, G jumps to the end, + which is useful when you are viewing register output.) + + The pager is expected to display hledger's ANSI colour and text + styling. hledger adds R to the LESS and MORE environment variables to + enable this for less and its more compatibility mode. If you use a + different pager, you might need to configure it similarly, to avoid + seeing junk on screen. (Or you can disable colour, as described + above.) HTML output - HTML output can be styled by an optional hledger.css file in the same + HTML output can be styled by an optional hledger.css file in the same directory. HTML output will be UTF-8 encoded. If your web browser is showing junk - characters, you may need to change its text encoding to UTF-8. Eg in - Safari, see View -> Text Encoding and Settings -> Advanced -> Default + characters, you may need to change its text encoding to UTF-8. Eg in + Safari, see View -> Text Encoding and Settings -> Advanced -> Default Encoding. CSV / TSV output - In CSV or TSV output, digit group marks (such as thousands separators) + In CSV or TSV output, digit group marks (such as thousands separators) are disabled automatically. FODS output - FODS is the OpenDocument Spreadsheet format as plain XML, as accepted - by LibreOffice and OpenOffice. If you use their spreadsheet applica- + FODS is the OpenDocument Spreadsheet format as plain XML, as accepted + by LibreOffice and OpenOffice. If you use their spreadsheet applica- tions, this is better than CSV because it works across locales (decimal point vs. decimal comma, character encoding stored in XML header, thus - no problems with umlauts), it supports fixed header rows and columns, - cell types (string vs. number vs. date), separation of number and + no problems with umlauts), it supports fixed header rows and columns, + cell types (string vs. number vs. date), separation of number and currency (currency is displayed but the cell type is still a number ac- cessible for computation), styles (bold), borders. Btw. you can still - extract CSV from FODS/ODS using various utilities like libreoffice + extract CSV from FODS/ODS using various utilities like libreoffice --headless or ods2csv. Beancount output - This is Beancount's journal format. You can use this to export your - hledger data to Beancount, perhaps to query it with Beancount Query - Language or with the Fava web app. hledger will try to adjust your - data to suit Beancount. If you plan to export often, you may want to - follow Beancount's conventions in your hledger data, to ease conver- - sion. Eg use Beancount-friendly account names, currency codes instead - of currency symbols, and avoid virtual postings, redundant cost nota- + This is Beancount's journal format. You can use this to export your + hledger data to Beancount, perhaps to query it with Beancount Query + Language or with the Fava web app. hledger will try to adjust your + data to suit Beancount. If you plan to export often, you may want to + follow Beancount's conventions in your hledger data, to ease conver- + sion. Eg use Beancount-friendly account names, currency codes instead + of currency symbols, and avoid virtual postings, redundant cost nota- tion, etc. - Here are more details, included here for now (see also "hledger and + Here are more details, included here for now (see also "hledger and Beancount" https://hledger.org/beancount.html). Beancount account names hledger will try adjust your account names, if needed, to Beancount ac- - count names, by capitalising, replacing unsupported characters with -, - and prepending B to parts which don't begin with a letter or digit. - (It's possible for this to convert distinct hledger account names to + count names, by capitalising, replacing unsupported characters with -, + and prepending B to parts which don't begin with a letter or digit. + (It's possible for this to convert distinct hledger account names to the same beancount name. Eg, hledger's automatic equity conversion ac- counts can have currency symbols in their name, so equity:conversion:$- becomes equity:conversion:B---.) - In addition, you must ensure that the top level account names are As- - sets, Liabilities, Equity, Income, and Expenses, which Beancount re- - quires. If yours are named differently, you can use account aliases, - usually in the form of --alias options, possibly stored in a config + In addition, you must ensure that the top level account names are As- + sets, Liabilities, Equity, Income, and Expenses, which Beancount re- + quires. If yours are named differently, you can use account aliases, + usually in the form of --alias options, possibly stored in a config file. (An example: hledger2beancount.conf) Beancount commodity names - hledger will adjust your commodity names, if needed, to Beancount com- + hledger will adjust your commodity names, if needed, to Beancount com- modity/currency names, which must be 2-24 uppercase letters, digits, or - ', ., _, -, beginning with a letter and ending with a letter or digit. + ', ., _, -, beginning with a letter and ending with a letter or digit. hledger will convert known currency symbols to ISO 4217 currency codes. - Otherwise, it will capitalise letters, replace unsupported characters - with a dash (-), and prepend/append a "B" when needed. (It's possible + Otherwise, it will capitalise letters, replace unsupported characters + with a dash (-), and prepend/append a "B" when needed. (It's possible for this to generate unreadable commodity names, or to convert distinct hledger commodity names to the same beancount name.) Beancount virtual postings - Beancount doesn't allow unbalanced/virtual postings, so you will need - to comment those, or use --real to exclude transactions that use them. - (If you have transactions which are a mixture of balanced and unbal- + Beancount doesn't allow unbalanced/virtual postings, so you will need + to comment those, or use --real to exclude transactions that use them. + (If you have transactions which are a mixture of balanced and unbal- anced postings, you'll have to do something more.) Beancount costs - Beancount doesn't allow redundant cost notation as hledger does. If - you have entries like this, you will need to comment out either the + Beancount doesn't allow redundant cost notation as hledger does. If + you have entries like this, you will need to comment out either the costs or the equity postings. Beancount operating currency - Declaring an operating currency improves Beancount and Fava reports. - You can do this manually by adding a line like this to the beancount + Declaring an operating currency improves Beancount and Fava reports. + You can do this manually by adding a line like this to the beancount journal: option "operating_currency" "USD" SQL output - SQL output is expected to work at least with SQLite, MySQL and Post- + SQL output is expected to work at least with SQLite, MySQL and Post- gres. - The SQL statements are expected to be executed in the empty database. + The SQL statements are expected to be executed in the empty database. If you already have tables created via SQL output of hledger, you would - probably want to either clear data from these (via delete or truncate - SQL statements) or drop the tables completely before import; otherwise + probably want to either clear data from these (via delete or truncate + SQL statements) or drop the tables completely before import; otherwise your postings would be duplicated. - For SQLite, it is more useful if you modify the generated id field to + For SQLite, it is more useful if you modify the generated id field to be a PRIMARY KEY. Eg: $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ... @@ -921,48 +923,48 @@ Output This is not yet much used; feedback is welcome. JSON output - Our JSON is rather large and verbose, since it is a faithful represen- - tation of hledger's internal data types. To understand its structure, - read the Haskell type definitions, which are mostly in + Our JSON is rather large and verbose, since it is a faithful represen- + tation of hledger's internal data types. To understand its structure, + read the Haskell type definitions, which are mostly in https://github.com/simonmichael/hledger/blob/mas- - ter/hledger-lib/Hledger/Data/Types.hs. hledger-web's OpenAPI specifi- + ter/hledger-lib/Hledger/Data/Types.hs. hledger-web's OpenAPI specifi- cation may also be relevant. - hledger stores numbers with sometimes up to 255 significant digits. - This is too many digits for most JSON consumers, so in JSON output we + hledger stores numbers with sometimes up to 255 significant digits. + This is too many digits for most JSON consumers, so in JSON output we round numbers to at most 10 decimal places. (We don't limit the number - of integer digits.) If you find this causing problems, please let us + of integer digits.) If you find this causing problems, please let us know. Related: #1195 This is not yet much used; feedback is welcome. Commodity styles - When displaying amounts, hledger infers a standard display style for + When displaying amounts, hledger infers a standard display style for each commodity/currency, as described below in Commodity display style. If needed, this can be overridden by a -c/--commodity-style option (ex- cept for cost amounts and amounts displayed by the print command, which - are always displayed with all decimal digits). For example, the fol- + are always displayed with all decimal digits). For example, the fol- lowing 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 commodi- - ties/currencies. Its argument is as described in the commodity direc- + ties/currencies. Its argument is as described in the commodity direc- tive. - In some cases hledger will adjust number formatting to improve their + In some cases hledger will adjust number formatting to improve their parseability (such as adding trailing decimal marks when needed). Debug output We intend hledger to be relatively easy to troubleshoot, introspect and - develop. You can add --debug[=N] to any hledger command line to see - additional debug output. N ranges from 1 (least output, the default) - to 9 (maximum output). Typically you would start with 1 and increase - until you are seeing enough. Debug output goes to stderr, and is not + develop. You can add --debug[=N] to any hledger command line to see + additional debug output. N ranges from 1 (least output, the default) + to 9 (maximum output). Typically you would start with 1 and increase + until you are seeing enough. Debug output goes to stderr, and is not affected by -o/--output-file (unless you redirect stderr to stdout, eg: - 2>&1). It will be interleaved with normal output, which can help re- - veal when parts of the code are evaluated. To capture debug output in + 2>&1). It will be interleaved with normal output, which can help re- + veal when parts of the code are evaluated. To capture debug output in a log file instead, you can usually redirect stderr, eg: hledger bal --debug=3 2>hledger.log @@ -972,35 +974,35 @@ 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 + 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. - 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. NO_COLOR If this environment variable exists (with any value, including - empty), hledger will not use ANSI color codes in terminal output, un- + empty), hledger will not use ANSI color codes in terminal output, un- less overridden by an explicit --color=y or --colour=y option. PART 2: DATA FORMATS Journal hledger's usual data source is a plain text file containing journal en- - tries in hledger journal format. If you're looking for a quick refer- - ence, jump ahead to the journal cheatsheet (or use the table of con- + tries in hledger journal format. If you're looking for a quick refer- + ence, jump ahead to the journal cheatsheet (or use the table of con- tents at https://hledger.org/hledger.html). - This file represents an accounting General Journal. The .journal file - extension is most often used, though not strictly required. The jour- - nal file contains a number of transaction entries, each describing a - transfer of money (or any commodity) between two or more named ac- + This file represents an accounting General Journal. The .journal file + extension is most often used, though not strictly required. The jour- + nal file contains a number of transaction entries, each describing a + transfer of money (or any commodity) between two or more named ac- counts, in a simple format readable by both hledger and humans. - hledger's journal format is compatible with most of Ledger's journal + hledger's journal format is compatible with most of Ledger's journal format, but not all of it. The differences and interoperation tips are - described at hledger and Ledger. With some care, and by avoiding in- - compatible features, you can keep your hledger journal readable by - Ledger and vice versa. This can useful eg for comparing the behaviour + described at hledger and Ledger. With some care, and by avoiding in- + compatible features, you can keep your hledger journal readable by + Ledger and vice versa. This can useful eg for comparing the behaviour of one app against the other. You can use hledger without learning any more about this file; just use @@ -1008,16 +1010,16 @@ Journal Many users, though, edit the journal file with a text editor, and track changes with a version control system such as git. Editor add-ons such - as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and + as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and hledger-vscode for Visual Studio Code, make this easier, adding colour, formatting, tab completion, and useful commands. See Editor configura- tion at hledger.org for the full list. A hledger journal file can contain three kinds of thing: comment lines, - transactions, and/or directives (including periodic transaction rules - and auto posting rules). Understanding the journal file format will - also give you a good understanding of hledger's data model. Here's a - quick cheatsheet/overview, followed by detailed descriptions of each + transactions, and/or directives (including periodic transaction rules + and auto posting rules). Understanding the journal file format will + also give you a good understanding of hledger's data model. Here's a + quick cheatsheet/overview, followed by detailed descriptions of each part. Journal cheatsheet @@ -1151,7 +1153,7 @@ Journal Comments Lines in the journal will be ignored if they begin with a hash (#) or a - semicolon (;). (See also Other syntax.) hledger will also ignore re- + semicolon (;). (See also Other syntax.) hledger will also ignore re- gions beginning with a comment line and ending with an end comment line (or file end). Here's a suggestion for choosing between them: @@ -1173,15 +1175,15 @@ Journal end comment Some hledger entries can have same-line comments attached to them, from - ; (semicolon) to end of line. See Transaction comments, Posting com- + ; (semicolon) to end of line. See Transaction comments, Posting com- ments, and Account comments below. Transactions - Transactions are the main unit of information in a journal file. They - represent events, typically a movement of some quantity of commodities + Transactions are the main unit of information in a journal file. They + represent events, typically a movement of some quantity of commodities between two or more named accounts. - Each transaction is recorded as a journal entry, beginning with a sim- + Each transaction is recorded as a journal entry, beginning with a sim- ple date in column 0. This can be followed by any of the following op- tional fields, separated by spaces: @@ -1191,11 +1193,11 @@ Journal o a description (any remaining text until end of line or a semicolon) - o a comment (any remaining text following a semicolon until end of + o a comment (any remaining text following a semicolon until end of line, and any following indented lines beginning with a semicolon) o 0 or more indented posting lines, describing what was transferred and - the accounts involved (indented comment lines are also allowed, but + the accounts involved (indented comment lines are also allowed, but not blank lines or non-indented lines). Here's a simple journal file containing one transaction: @@ -1206,22 +1208,22 @@ Journal Dates Simple dates - Dates in the journal file use simple dates format: YYYY-MM-DD or + Dates in the journal file use simple dates format: YYYY-MM-DD or YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be - omitted, in which case it will be inferred from the context: the cur- - rent transaction, the default year set with a Y directive, or the cur- + omitted, in which case it will be inferred from the context: the cur- + rent transaction, the default year set with a Y directive, or the cur- rent date when the command is run. Some examples: 2010-01-31, 2010/01/31, 2010.1.31, 1/31. - (The UI also accepts simple dates, as well as the more flexible smart + (The UI also accepts simple dates, as well as the more flexible smart dates documented in the hledger manual.) Posting dates - You can give individual postings a different date from their parent - transaction, by adding a posting comment containing a tag (see below) + You can give individual postings a different date from their parent + transaction, by adding a posting comment containing a tag (see below) like date:DATE. This is probably the best way to control posting dates - precisely. Eg in this example the expense should appear in May re- - ports, and the deduction from checking should be reported on 6/1 for + precisely. Eg in this example the expense should appear in May re- + ports, and the deduction from checking should be reported on 6/1 for easy bank reconciliation: 2015/5/30 @@ -1234,15 +1236,15 @@ Journal $ hledger -f t.j register checking 2015-06-01 assets:checking $-10 $-10 - DATE should be a simple date; if the year is not specified it will use + DATE should be a simple date; if the year is not specified it will use the year of the transaction's date. - The date: tag must have a valid simple date value if it is present, eg + The date: tag must have a valid simple date value if it is present, eg a date: tag with no value is not allowed. Status - Transactions (or individual postings within a transaction) can have a - status mark, which is a single character before the transaction de- - scription (or posting account name), separated from it by a space, in- + Transactions (or individual postings within a transaction) can have a + status mark, which is a single character before the transaction de- + scription (or posting account name), separated from it by a space, in- dicating one of three statuses: mark status @@ -1251,20 +1253,20 @@ Journal ! pending * cleared - When reporting, you can filter by status with the -U/--unmarked, + When reporting, you can filter by status with the -U/--unmarked, -P/--pending, and -C/--cleared flags (and you can combine these, eg -UP - to match all except cleared things). Or you can use the status:, sta- + to match all except cleared things). Or you can use the status:, sta- tus:!, and status:* queries, or the U, P, C keys in hledger-ui. (Note: in Ledger the "unmarked" state is called "uncleared"; in hledger we renamed it to "unmarked" for semantic clarity.) - Status marks are optional, but can be helpful eg for reconciling with + Status marks are optional, but can be helpful eg for reconciling with real-world accounts. Some editor modes provide highlighting and short- - cuts for working with status. Eg in Emacs ledger-mode, you can toggle + cuts for working with status. Eg in Emacs ledger-mode, you can toggle transaction status with C-c C-e, or posting status with C-c C-c. - What "uncleared", "pending", and "cleared" actually mean is up to you. + What "uncleared", "pending", and "cleared" actually mean is up to you. Here's one suggestion: status meaning @@ -1275,55 +1277,55 @@ Journal cleared complete, reconciled as far as possible, and considered cor- rect - With this scheme, you would use -PC to see the current balance at your + With this scheme, you would use -PC to see the current balance at your bank, -U to see things which will probably hit your bank soon (like un- - cashed checks), and no flags to see the most up-to-date state of your + cashed checks), and no flags to see the most up-to-date state of your finances. Code - After the status mark, but before the description, you can optionally - write a transaction "code", enclosed in parentheses. This is a good - place to record a check number, or some other important transaction id + After the status mark, but before the description, you can optionally + write a transaction "code", enclosed in parentheses. This is a good + place to record a check number, or some other important transaction id or reference number. Description - After the date, status mark and/or code fields, the rest of the line - (or until a comment is begun with ;) is the transaction's description. + After the date, status mark and/or code fields, the rest of the line + (or until a comment is begun with ;) is the transaction's description. Here you can describe the transaction (called the "narration" in tradi- - tional bookkeeping), or you can record a payee/payer name, or you can + tional bookkeeping), or you can record a payee/payer name, or you can leave it empty. - Transaction descriptions show up in print output and in register re- + Transaction descriptions show up in print output and in register re- ports, and can be listed with the descriptions command. - You can query by description with desc:DESCREGEX, or pivot on descrip- + You can query by description with desc:DESCREGEX, or pivot on descrip- tion with --pivot desc. Payee and note Sometimes people want a dedicated payee/payer field that can be queried - and checked more strictly. If you want that, you can write a | (pipe) - character in the description. This divides it into a "payee" field on + and checked more strictly. If you want that, you can write a | (pipe) + character in the description. This divides it into a "payee" field on the left, and a "note" field on the right. (Either can be empty.) - You can query these with payee:PAYEEREGEX and note:NOTEREGEX, list - their values with the payees and notes commands, or pivot on payee or + You can query these with payee:PAYEEREGEX and note:NOTEREGEX, list + their values with the payees and notes commands, or pivot on payee or note. Note: in transactions with no | character, description, payee, and note all have the same value. Once a | is added, they become distinct. (If - you'd like to change this behaviour, please propose it on the mail + you'd like to change this behaviour, please propose it on the mail list.) If you want more strict error checking, you can declare the valid payee - names with payee directives, and then enforce these with hledger check - payees. (Note: because of the above, for this you'll need to ensure - every transaction description contains a | and therefore a checkable + names with payee directives, and then enforce these with hledger check + payees. (Note: because of the above, for this you'll need to ensure + every transaction description contains a | and therefore a checkable payee name, even if it's empty.) Transaction comments - Text following ;, after a transaction description, and/or on indented - lines immediately below it, form comments for that transaction. They - are reproduced by print but otherwise ignored, except they may contain + Text following ;, after a transaction description, and/or on indented + lines immediately below it, form comments for that transaction. They + are reproduced by print but otherwise ignored, except they may contain tags, which are not ignored. 2012-01-01 something ; a transaction comment @@ -1332,63 +1334,63 @@ Journal assets Postings - A posting is an addition of some amount to, or removal of some amount - from, an account. Each posting line begins with at least one space or + A posting is an addition of some amount to, or removal of some amount + from, an account. Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by: o (optional) a status character (empty, !, or *), followed by a space - o (required) an account name (any text, optionally containing single + o (required) an account name (any text, optionally containing single spaces, until end of line or a double space) o (optional) two or more spaces (or tabs) followed by an amount. - If the amount is positive, it is being added to the account; if nega- + If the amount is positive, it is being added to the account; if nega- tive, it is being removed from the account. - The posting amounts in a transaction must sum up to zero, indicating - that the inflows and outflows are equal. We call this a balanced + The posting amounts in a transaction must sum up to zero, indicating + that the inflows and outflows are equal. We call this a balanced transaction. (You can read more about the nitty-gritty details of "sum up to zero" in Transaction balancing below.) - As a convenience, you can optionally leave one amount blank; hledger + As a convenience, you can optionally leave one amount blank; hledger will infer what it should be so as to balance the transaction. Debits and credits The traditional accounting concepts of debit and credit of course exist - in hledger, but we represent them with numeric sign, as described - above. Positive and negative posting amounts represent debits and + in hledger, but we represent them with numeric sign, as described + above. Positive and negative posting amounts represent debits and credits respectively. - You don't need to remember that, but if you would like to - eg for - helping newcomers or for talking with your accountant - here's a handy + You don't need to remember that, but if you would like to - eg for + helping newcomers or for talking with your accountant - here's a handy mnemonic: debit / plus / left / short words credit / minus / right / longer words The two space delimiter - Be sure to notice the unusual separator between the account name and + Be sure to notice the unusual separator between the account name and the following amount. Because hledger allows account names with spaces - in them, you must separate the account name and amount (if any) by two - or more spaces (or tabs). It's easy to forget at first. If you ever - see the amount being treated as part of the account name, you'll know + in them, you must separate the account name and amount (if any) by two + or more spaces (or tabs). It's easy to forget at first. If you ever + see the amount being treated as part of the account name, you'll know you probably need to add another space between them. Account names - Accounts are the main way of categorising things in hledger. As in - Double Entry Bookkeeping, they can represent real world accounts (such + Accounts are the main way of categorising things in hledger. As in + Double Entry Bookkeeping, they can represent real world accounts (such as a bank account), or more abstract categories such as "money borrowed from Frank" or "money spent on electricity". - You can use any account names you like, but we usually start with the + You can use any account names you like, but we usually start with the traditional accounting categories, which in english are assets, liabil- ities, equity, revenues, expenses. (You might see these referred to as A, L, E, R, X for short.) - For more precise reporting, we usually divide the top level accounts + For more precise reporting, we usually divide the top level accounts into more detailed subaccounts, by writing a full colon between account - name parts. For example, from the account names assets:bank:checking + name parts. For example, from the account names assets:bank:checking and expenses:food, hledger will infer this hierarchy of five accounts: assets @@ -1406,33 +1408,33 @@ Journal food hledger reports can summarise the account tree to any depth, so you can - go as deep as you like with subcategories, but keeping your account + go as deep as you like with subcategories, but keeping your account names relatively simple may be best when starting out. Account names may be capitalised or not; they may contain letters, num- - bers, symbols, or single spaces. Note, when an account name and an - amount are written on the same line, they must be separated by two or + bers, symbols, or single spaces. Note, when an account name and an + amount are written on the same line, they must be separated by two or more spaces (or tabs). - Parentheses or brackets enclosing the full account name indicate vir- - tual postings, described below. Parentheses or brackets internal to + Parentheses or brackets enclosing the full account name indicate vir- + tual postings, described below. Parentheses or brackets internal to the account name have no special meaning. - Account names can be altered temporarily or permanently by account + Account names can be altered temporarily or permanently by account aliases. Amounts After the account name, there is usually an amount. (Remember: between account name and amount, there must be two or more spaces.) - hledger's amount format is flexible, supporting several international - formats. Here are some examples. Amounts have a number (the "quan- + hledger's amount format is flexible, supporting several international + formats. Here are some examples. Amounts have a number (the "quan- tity"): 1 ..and usually a currency symbol or commodity name (more on this below), - to the left or right of the quantity, with or without a separating + to the left or right of the quantity, with or without a separating space: $1 @@ -1440,13 +1442,13 @@ Journal 3 "green apples" Amounts can be preceded by a minus sign (or a plus sign, though plus is - the default), The sign can be written before or after a left-side com- + the default), The sign can be written before or after a left-side com- modity symbol: -$1 $-1 - One or more spaces between the sign and the number are acceptable when + One or more spaces between the sign and the number are acceptable when parsing (but they won't be displayed in output): + $1 @@ -1464,31 +1466,31 @@ Journal 1,23 Both of these are common in international number formats, so hledger is - not biased towards one or the other. Because hledger also supports - digit group marks (eg thousands separators), this means that a number - like 1,000 or 1.000 containing just one period or comma is ambiguous. - In such cases, hledger by default assumes it is a decimal mark, and + not biased towards one or the other. Because hledger also supports + digit group marks (eg thousands separators), this means that a number + like 1,000 or 1.000 containing just one period or comma is ambiguous. + In such cases, hledger by default assumes it is a decimal mark, and will parse both of those as 1. - To help hledger parse such ambiguous numbers more accurately, if you - use digit group marks, we recommend declaring the decimal mark explic- - itly. The best way is to add a decimal-mark directive at the top of + To help hledger parse such ambiguous numbers more accurately, if you + use digit group marks, we recommend declaring the decimal mark explic- + itly. The best way is to add a decimal-mark directive at the top of each data file, like this: decimal-mark . - Or you can declare it per commodity with commodity directives, de- + Or you can declare it per commodity with commodity directives, de- scribed below. - hledger also accepts numbers like 10. with no digits after the decimal - mark (and will sometimes display numbers that way to disambiguate them + hledger also accepts numbers like 10. with no digits after the decimal + mark (and will sometimes display numbers that way to disambiguate them - see Trailing decimal marks). Digit group marks - In the integer part of the amount quantity (left of the decimal mark), - groups of digits can optionally be separated by a digit group mark - a - comma or period (whichever is not used as decimal mark), or a space - (several Unicode space variants, like no-break space, are also ac- + In the integer part of the amount quantity (left of the decimal mark), + groups of digits can optionally be separated by a digit group mark - a + comma or period (whichever is not used as decimal mark), or a space + (several Unicode space variants, like no-break space, are also ac- cepted). So these are all valid amounts in a journal file: $1,000,000.00 @@ -1498,46 +1500,46 @@ Journal 1 000 000.00 ; <- no-break space Commodity - Amounts in hledger have both a "quantity", which is a signed decimal + Amounts in hledger have both a "quantity", which is a signed decimal number, and a "commodity", which is a currency symbol, stock ticker, or any word or phrase describing something you are tracking. If the commodity name contains non-letters (spaces, numbers, or punctu- - ation), you must always write it inside double quotes ("green apples", + ation), you must always write it inside double quotes ("green apples", "ABC123"). - If you write just a bare number, that too will have a commodity, with + If you write just a bare number, that too will have a commodity, with name ""; we call that the "no-symbol commodity". - Actually, hledger combines these single-commodity amounts into more - powerful multi-commodity amounts, which are what it works with most of - the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 - TSLA. In practice, you will only see multi-commodity amounts in + Actually, hledger combines these single-commodity amounts into more + powerful multi-commodity amounts, which are what it works with most of + the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 + TSLA. In practice, you will only see multi-commodity amounts in hledger's output; you can't write them directly in the journal file. By default, the format of amounts in the journal influences how hledger - displays them in output. This is explained in Commodity display style + displays them in output. This is explained in Commodity display style below. Costs - After a posting amount, you can note its cost (when buying) or selling - price (when selling) in another commodity, by writing either @ UNIT- - PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- + After a posting amount, you can note its cost (when buying) or selling + price (when selling) in another commodity, by writing either @ UNIT- + PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- tion, where one commodity is exchanged for another. - (You might also see this called "transaction price" in hledger docs, - discussions, or code; that term was directionally neutral and reminded - that it is a price specific to a transaction, but we now just call it + (You might also see this called "transaction price" in hledger docs, + discussions, or code; that term was directionally neutral and reminded + that it is a price specific to a transaction, but we now just call it "cost", with the understanding that the transaction could be a purchase or a sale.) - Costs are usually written explicitly with @ or @@, but can also be in- + Costs are usually written explicitly with @ or @@, but can also be in- ferred automatically for simple multi-commodity transactions. Note, if - costs are inferred, the order of postings is significant; the first + costs are inferred, the order of postings is significant; the first posting will have a cost attached, in the commodity of the second. - As an example, here are several ways to record purchases of a foreign - currency in hledger, using the cost notation either explicitly or im- + As an example, here are several ways to record purchases of a foreign + currency in hledger, using the cost notation either explicitly or im- plicitly: 1. Write the price per unit, as @ UNITPRICE after the amount: @@ -1561,17 +1563,17 @@ Journal assets:euros 100 ; one hundred euros purchased assets:dollars $-135 ; for $135 - Amounts can be converted to cost at report time using the -B/--cost + Amounts can be converted to cost at report time using the -B/--cost flag; this is discussed more in the Cost reporting section. - Note that the cost normally should be a positive amount, though it's - not required to be. This can be a little confusing, see discussion at + Note that the cost normally should be a positive amount, though it's + not required to be. This can be a little confusing, see discussion at --infer-market-prices: market prices from transactions. Balance assertions - hledger supports Ledger-style balance assertions in journal files. - These look like, for example, = EXPECTEDBALANCE following a posting's - amount. Eg here we assert the expected dollar balance in accounts a + hledger supports Ledger-style balance assertions in journal files. + These look like, for example, = EXPECTEDBALANCE following a posting's + amount. Eg here we assert the expected dollar balance in accounts a and b after each posting: 2013/1/1 @@ -1583,42 +1585,42 @@ Journal b $-1 = $-2 After reading a journal file, hledger will check all balance assertions - and report an error if any of them fail. Balance assertions can pro- - tect you from, eg, inadvertently disrupting reconciled balances while - cleaning up old entries. You can disable them temporarily with the + and report an error if any of them fail. Balance assertions can pro- + tect you from, eg, inadvertently disrupting reconciled balances while + cleaning up old entries. You can disable them temporarily with the -I/--ignore-assertions flag, which can be useful for troubleshooting or - for reading Ledger files. (Note: this flag currently does not disable + for reading Ledger files. (Note: this flag currently does not disable balance assignments, described below). Assertions and ordering - hledger calculates and checks an account's balance assertions in date + hledger calculates and checks an account's balance assertions in date order (and when there are multiple assertions on the same day, in parse - order). Note this is different from Ledger, which checks assertions + order). Note this is different from Ledger, which checks assertions always in parse order, ignoring dates. This means in hledger you can freely reorder transactions, postings, or files, and balance assertions will usually keep working. The exception - is when you reorder multiple postings on the same day, to the same ac- + is when you reorder multiple postings on the same day, to the same ac- count, which have balance assertions; those will likely need updating. Assertions and multiple included files - Multiple files included with the include directive are processed as if - concatenated into one file, preserving their order and the posting or- - der within each file. It means that balance assertions in later files + Multiple files included with the include directive are processed as if + concatenated into one file, preserving their order and the posting or- + der within each file. It means that balance assertions in later files will see balance from earlier files. - And if you have multiple postings to an account on the same day, split - across multiple files, and you want to assert the account's balance on + And if you have multiple postings to an account on the same day, split + across multiple files, and you want to assert the account's balance on that day, you'll need to put the assertion in the right file - the last one in the sequence, probably. Assertions and multiple -f files - Unlike include, when multiple files are specified on the command line - with multiple -f/--file options, balance assertions will not see bal- + Unlike include, when multiple files are specified on the command line + with multiple -f/--file options, balance assertions will not see bal- ance from earlier files. This can be useful when you do not want prob- lems in earlier files to disrupt valid assertions in later files. - If you do want assertions to see balance from earlier files, use in- + If you do want assertions to see balance from earlier files, use in- clude, or concatenate the files temporarily. Assertions and costs @@ -1628,20 +1630,20 @@ Journal 2019/1/1 (a) $1 @ 1 = $1 - We do allow costs to be written in balance assertion amounts, however, - and print shows them, but they don't affect whether the assertion - passes or fails. This is for backward compatibility (hledger's close - command used to generate balance assertions with costs), and because + We do allow costs to be written in balance assertion amounts, however, + and print shows them, but they don't affect whether the assertion + passes or fails. This is for backward compatibility (hledger's close + command used to generate balance assertions with costs), and because balance assignments do use costs (see below). Assertions and commodities - The balance assertions described so far are "single commodity balance + The balance assertions described so far are "single commodity balance assertions": they assert and check the balance in one commodity, ignor- - ing any others that may be present. This is how balance assertions + ing any others that may be present. This is how balance assertions work in Ledger also. - If an account contains multiple commodities, you can assert their bal- - ances by writing multiple postings with balance assertions, one for + If an account contains multiple commodities, you can assert their bal- + ances by writing multiple postings with balance assertions, one for each commodity: 2013/1/1 @@ -1653,8 +1655,8 @@ Journal both 0 = $1 both 0 = 1 - In hledger you can make a stronger "sole commodity balance assertion" - by writing two equals signs (== EXPECTEDBALANCE). This also asserts + In hledger you can make a stronger "sole commodity balance assertion" + by writing two equals signs (== EXPECTEDBALANCE). This also asserts that there are no other commodities in the account besides the asserted one (or at least, that their current balance is zero): @@ -1664,12 +1666,12 @@ Journal both ;== $1 ; this one would fail because 'both' contains $ and It's less easy to make a "sole commodities balance assertion" (note the - plural) - ie, asserting that an account contains two or more specified + plural) - ie, asserting that an account contains two or more specified commodities and no others. It can be done by 1. isolating each commodity in a subaccount, and asserting those - 2. and also asserting there are no commodities in the parent account + 2. and also asserting there are no commodities in the parent account itself: 2013/1/1 @@ -1681,10 +1683,10 @@ Journal Assertions and subaccounts All of the balance assertions above (both = and ==) are "subaccount-ex- - clusive balance assertions"; they ignore any balances that exist in + clusive balance assertions"; they ignore any balances that exist in deeper subaccounts. - In hledger you can make "subaccount-inclusive balance assertions" by + In hledger you can make "subaccount-inclusive balance assertions" by adding a star after the equals (=* or ==*): 2019/1/1 @@ -1698,10 +1700,10 @@ Journal are not affected by the --real/-R flag or real: query. Assertions and auto postings - Balance assertions are affected by the --auto flag, which generates + Balance assertions are affected by the --auto flag, which generates auto postings, which can alter account balances. Because auto postings are optional in hledger, accounts affected by them effectively have two - balances. But balance assertions can only test one or the other of + balances. But balance assertions can only test one or the other of these. So to avoid making fragile assertions, either: o assert the balance calculated with --auto, and always use --auto with @@ -1714,15 +1716,15 @@ Journal avoid auto postings entirely). Assertions and precision - Balance assertions compare the exactly calculated amounts, which are - not always what is shown by reports. Eg a commodity directive may - limit the display precision, but this will not affect balance asser- + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- tions. Balance assertion failure messages show exact amounts. Posting comments - Text following ;, at the end of a posting line, and/or on indented - lines immediately below it, form comments for that posting. They are - reproduced by print but otherwise ignored, except they may contain + Text following ;, at the end of a posting line, and/or on indented + lines immediately below it, form comments for that posting. They are + reproduced by print but otherwise ignored, except they may contain tags, which are not ignored. 2012-01-01 @@ -1732,55 +1734,55 @@ Journal ; a second comment line for posting 2 Transaction balancing - How exactly does hledger decide when a transaction is balanced ? The + How exactly does hledger decide when a transaction is balanced ? The general goal is that if you look at the journal entry and calculate the amounts' sum perfectly with pencil and paper, hledger should agree with you. - Real world transactions, especially for investments or cryptocurren- - cies, often involve imprecise costs, complex decimals, and/or infi- - nitely-recurring decimals, which are difficult or inconvenient to han- + Real world transactions, especially for investments or cryptocurren- + cies, often involve imprecise costs, complex decimals, and/or infi- + nitely-recurring decimals, which are difficult or inconvenient to han- dle on a computer. So to be a practical accounting system, hledger al- - lows some imprecision when checking transaction balancedness. The + lows some imprecision when checking transaction balancedness. The question is, how much imprecision should be allowed ? - hledger currently decides it based on the commodity display styles: if + hledger currently decides it based on the commodity display styles: if the postings' sum would appear to be zero when displayed with the stan- dard display precisions, the transaction is considered balanced. Or equivalently: if the journal entry is displayed with amounts rounded - to the standard display precisions (with hledger print --round=hard), - and a human with pencil and paper would agree that those displayed + to the standard display precisions (with hledger print --round=hard), + and a human with pencil and paper would agree that those displayed amounts add up to zero, the transaction is considered balanced. - This has some advantages: it is fairly intuitive, general not - hard-coded, yet configurable when needed. On the downside it means - that transaction balancedness is related to commodity display preci- - sions, so eg when using -c/--commodity-style to display things with - more than usual precision, you might need to fix some of your journal + This has some advantages: it is fairly intuitive, general not + hard-coded, yet configurable when needed. On the downside it means + that transaction balancedness is related to commodity display preci- + sions, so eg when using -c/--commodity-style to display things with + more than usual precision, you might need to fix some of your journal entries (ie, add decimal digits to make them balance more precisely). Other PTA tools (Ledger, Beancount..) have their own ways of doing it. Possible improvements are discussed at #1964. - Note: if you have multiple journal files, and are relying on commodity - directives to make imprecise journal entries balance, the directives' + Note: if you have multiple journal files, and are relying on commodity + directives to make imprecise journal entries balance, the directives' placement might be important - see commodity directive. Tags - Tags are a way to add extra labels or data fields to transactions, + Tags are a way to add extra labels or data fields to transactions, postings, or accounts, which you can then search or pivot on. - A tag is a word, optionally hyphenated, immediately followed by a full + A tag is a word, optionally hyphenated, immediately followed by a full colon, in the comment of a transaction, a posting, or an account direc- - tive. Eg: 2024-01-01 a transaction ; foo: Note this is an exception + tive. Eg: 2024-01-01 a transaction ; foo: Note this is an exception to the usual rule that things in comments are ignored. - You can write multiple tags on one line, separated by comma. Or you - can write each tag on its own comment line (no comma needed in this + You can write multiple tags on one line, separated by comma. Or you + can write each tag on its own comment line (no comma needed in this case). - For example, here are five different tags: one on the assets:checking + For example, here are five different tags: one on the assets:checking account, two on the transaction, and two on the expenses:food posting: account assets:checking ; accounttag: @@ -1790,15 +1792,15 @@ Journal assets:checking $-1 expenses:food $1 ; postingtag:, another-posting-tag: - Postings also inherit tags from their transaction and their account. - And transactions also acquire tags from their postings (and postings' - accounts). So in the example above, the expenses posting effectively + Postings also inherit tags from their transaction and their account. + And transactions also acquire tags from their postings (and postings' + accounts). So in the example above, the expenses posting effectively has all five tags (by inheriting from the account and transaction), and - the transaction also has all five tags (by acquiring from the expenses + the transaction also has all five tags (by acquiring from the expenses posting). Tag names - Most non-whitespace characters are allowed in tag names. Eg : is a + Most non-whitespace characters are allowed in tag names. Eg : is a valid tag. You can list the tag names used in your journal with the tags command: @@ -1807,13 +1809,13 @@ Journal In commands which use a query, you can match by tag name. Eg: hledger print tag:NAMEREGEX - You can declare valid tag names with the tag directive and then check + You can declare valid tag names with the tag directive and then check them with the check command. Special tags - Some tag names have special significance to hledger. There's not much - harm in using them yourself, but some could produce an error message, - particularly the date: and type: tags. They are explained elsewhere, + Some tag names have special significance to hledger. There's not much + harm in using them yourself, but some could produce an error message, + particularly the date: and type: tags. They are explained elsewhere, but here is a quick list for reference: Tags you can set to influence hledger's behaviour: @@ -1832,15 +1834,24 @@ Journal generated-posting -- appears on generated auto postings (with --verbose-tags) modified -- appears on txns which have had auto postings added (with --verbose-tags) - Not displayed, but queryable: + These similar tags are also provided; they are not displayed, but can + be relied on for querying: + _generated-transaction -- exists on generated periodic txns (always) _generated-posting -- exists on generated auto postings (always) _modified -- exists on txns which have had auto postings added (always) - Other tags hledger uses internally: + The following non-displayed tags are used internally by hledger, (1) to + ignore redundant costs when balancing transactions, (2) when using + --infer-costs, and (3) when using --infer-equity. Essentially they + mark postings with costs which have corresponding equity conversion + postings, and vice-versa. They are queryable, but you should not rely + on them for your reports: - _cost-matched -- marks postings with a cost which have been matched with a nearby pair of equity conversion postings - _conversion-matched -- marks equity conversion postings which have been matched with a nearby posting with a cost + _conversion-matched -- marks "matched conversion postings", which are to a V/Conversion account + and have a nearby equivalent costful or potentially costful posting + _cost-matched -- marks "matched cost postings", which have or could have a cost + that's equivalent to nearby conversion postings Tag values Tags can have a value, which is any text after the colon up until a @@ -6338,10 +6349,10 @@ Help commands insensitive) TOPIC argument, try to open it at that section heading. Flags: - -i show the manual with info - -m show the manual with man - -p show the manual with $PAGER or less - (less is always used if TOPIC is specified) + -i show the manual with info + -m show the manual with man + -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- @@ -6373,8 +6384,8 @@ Help commands Play demos of hledger usage in the terminal, if asciinema is installed. Flags: - -s --speed=SPEED playback speed (1 is original speed, .5 is half, 2 - is double, etc (default: 2)) + -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, write its number or a prefix or substring of its title. Tips: