From 5f285a56aba33bef28e0a02df131613b05be8319 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Tue, 25 Jun 2024 08:54:18 +0100 Subject: [PATCH] doc: update manuals --- hledger-ui/hledger-ui.1 | 13 +- hledger-ui/hledger-ui.info | 69 +- hledger-ui/hledger-ui.txt | 13 +- hledger-web/hledger-web.1 | 13 +- hledger-web/hledger-web.info | 45 +- hledger-web/hledger-web.txt | 13 +- hledger/hledger.1 | 109 ++- hledger/hledger.info | 1469 ++++++++++++++++++---------------- hledger/hledger.txt | 212 +++-- 9 files changed, 1042 insertions(+), 914 deletions(-) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 7eeb19b1b..a918bd5bc 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -70,12 +70,13 @@ and also supports many of hledger\[aq]s general options: .IP .EX General input/data transformation flags: - \-f \-\-file=FILE Read data from FILE, or from stdin if \-. Can be - specified more than once. If not specified, reads - from $LEDGER_FILE or $HOME/.hledger.journal. - \-\-rules\-file=RULEFILE Use conversion rules from this file for + \-f \-\-file=[FMT:]FILE Read data from FILE, or from stdin if FILE is \-, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + \-\-rules=RULESFILE Use rules defined in this rules file for converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.rules for each such FILE. + specified, uses FILE.csv.rules for each FILE.csv. \-\-alias=A=B|/RGX/=RPL transform account names from A to B, or by replacing regular expression matches \-\-auto generate extra postings by applying auto posting @@ -138,7 +139,6 @@ General output/reporting flags (supported by some commands): \-\-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. - \-\-debug=[1\-9] show this level of debug output (default: 1) General help flags: \-h \-\-help show command line help @@ -146,6 +146,7 @@ General help flags: \-\-info show the manual with info \-\-man show the manual with man \-\-version show version information + \-\-debug=[1\-9] show this level of debug output (default: 1) .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 43e4ef0ee..79a173c30 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -81,12 +81,13 @@ Flags: and also supports many of hledger's general options: General input/data transformation flags: - -f --file=FILE Read data from FILE, or from stdin if -. Can be - specified more than once. If not specified, reads - from $LEDGER_FILE or $HOME/.hledger.journal. - --rules-file=RULEFILE Use conversion rules from this file for + -f --file=[FMT:]FILE Read data from FILE, or from stdin if FILE is -, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + --rules=RULESFILE Use rules defined in this rules file for converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.rules for each such FILE. + specified, uses FILE.csv.rules for each FILE.csv. --alias=A=B|/RGX/=RPL transform account names from A to B, or by replacing regular expression matches --auto generate extra postings by applying auto posting @@ -149,7 +150,6 @@ General output/reporting flags (supported by some commands): --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. - --debug=[1-9] show this level of debug output (default: 1) General help flags: -h --help show command line help @@ -157,6 +157,7 @@ General help flags: --info show the manual with info --man show the manual with man --version show version information + --debug=[1-9] show this level of debug output (default: 1) With hledger-ui, the '--debug' option sends debug output to a 'hledger-ui.log' file in the current directory. @@ -532,34 +533,34 @@ Tag Table: Node: Top221 Node: OPTIONS1872 Ref: #options1970 -Node: MOUSE8150 -Ref: #mouse8245 -Node: KEYS8482 -Ref: #keys8575 -Node: SCREENS13230 -Ref: #screens13334 -Node: Menu screen13970 -Ref: #menu-screen14091 -Node: Cash accounts screen14286 -Ref: #cash-accounts-screen14463 -Node: Balance sheet accounts screen14647 -Ref: #balance-sheet-accounts-screen14863 -Node: Income statement accounts screen14983 -Ref: #income-statement-accounts-screen15204 -Node: All accounts screen15368 -Ref: #all-accounts-screen15549 -Node: Register screen15731 -Ref: #register-screen15890 -Node: Transaction screen18174 -Ref: #transaction-screen18332 -Node: Error screen19749 -Ref: #error-screen19871 -Node: WATCH MODE20115 -Ref: #watch-mode20232 -Node: ENVIRONMENT21691 -Ref: #environment21807 -Node: BUGS21998 -Ref: #bugs22081 +Node: MOUSE8240 +Ref: #mouse8335 +Node: KEYS8572 +Ref: #keys8665 +Node: SCREENS13320 +Ref: #screens13424 +Node: Menu screen14060 +Ref: #menu-screen14181 +Node: Cash accounts screen14376 +Ref: #cash-accounts-screen14553 +Node: Balance sheet accounts screen14737 +Ref: #balance-sheet-accounts-screen14953 +Node: Income statement accounts screen15073 +Ref: #income-statement-accounts-screen15294 +Node: All accounts screen15458 +Ref: #all-accounts-screen15639 +Node: Register screen15821 +Ref: #register-screen15980 +Node: Transaction screen18264 +Ref: #transaction-screen18422 +Node: Error screen19839 +Ref: #error-screen19961 +Node: WATCH MODE20205 +Ref: #watch-mode20322 +Node: ENVIRONMENT21781 +Ref: #environment21897 +Node: BUGS22088 +Ref: #bugs22171  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index e00bd1916..525b633c6 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -59,12 +59,13 @@ OPTIONS and also supports many of hledger's general options: General input/data transformation flags: - -f --file=FILE Read data from FILE, or from stdin if -. Can be - specified more than once. If not specified, reads - from $LEDGER_FILE or $HOME/.hledger.journal. - --rules-file=RULEFILE Use conversion rules from this file for + -f --file=[FMT:]FILE Read data from FILE, or from stdin if FILE is -, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + --rules=RULESFILE Use rules defined in this rules file for converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.rules for each such FILE. + specified, uses FILE.csv.rules for each FILE.csv. --alias=A=B|/RGX/=RPL transform account names from A to B, or by replacing regular expression matches --auto generate extra postings by applying auto posting @@ -127,7 +128,6 @@ OPTIONS --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. - --debug=[1-9] show this level of debug output (default: 1) General help flags: -h --help show command line help @@ -135,6 +135,7 @@ OPTIONS --info show the manual with info --man show the manual with man --version show version information + --debug=[1-9] show this level of debug output (default: 1) 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 18c66c0f9..e597fd9a3 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -121,12 +121,13 @@ hledger\-web also supports many of hledger\[aq]s general options: .IP .EX General input/data transformation flags: - \-f \-\-file=FILE Read data from FILE, or from stdin if \-. Can be - specified more than once. If not specified, reads - from $LEDGER_FILE or $HOME/.hledger.journal. - \-\-rules\-file=RULEFILE Use conversion rules from this file for + \-f \-\-file=[FMT:]FILE Read data from FILE, or from stdin if FILE is \-, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + \-\-rules=RULESFILE Use rules defined in this rules file for converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.rules for each such FILE. + specified, uses FILE.csv.rules for each FILE.csv. \-\-alias=A=B|/RGX/=RPL transform account names from A to B, or by replacing regular expression matches \-\-auto generate extra postings by applying auto posting @@ -189,7 +190,6 @@ General output/reporting flags (supported by some commands): \-\-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. - \-\-debug=[1\-9] show this level of debug output (default: 1) General help flags: \-h \-\-help show command line help @@ -197,6 +197,7 @@ General help flags: \-\-info show the manual with info \-\-man show the manual with man \-\-version show version information + \-\-debug=[1\-9] show this level of debug output (default: 1) .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 964795fc9..c91ecdfd3 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -126,12 +126,13 @@ but not route parsing. hledger-web also supports many of hledger's general options: General input/data transformation flags: - -f --file=FILE Read data from FILE, or from stdin if -. Can be - specified more than once. If not specified, reads - from $LEDGER_FILE or $HOME/.hledger.journal. - --rules-file=RULEFILE Use conversion rules from this file for + -f --file=[FMT:]FILE Read data from FILE, or from stdin if FILE is -, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + --rules=RULESFILE Use rules defined in this rules file for converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.rules for each such FILE. + specified, uses FILE.csv.rules for each FILE.csv. --alias=A=B|/RGX/=RPL transform account names from A to B, or by replacing regular expression matches --auto generate extra postings by applying auto posting @@ -194,7 +195,6 @@ General output/reporting flags (supported by some commands): --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. - --debug=[1-9] show this level of debug output (default: 1) General help flags: -h --help show command line help @@ -202,6 +202,7 @@ General help flags: --info show the manual with info --man show the manual with man --version show version information + --debug=[1-9] show this level of debug output (default: 1) hledger-web shows accounts with zero balances by default (like 'hledger-ui', and unlike 'hledger'). Using the '-E/--empty' flag will @@ -524,22 +525,22 @@ Tag Table: Node: Top223 Node: OPTIONS2569 Ref: #options2674 -Node: PERMISSIONS10862 -Ref: #permissions11001 -Node: EDITING UPLOADING DOWNLOADING12213 -Ref: #editing-uploading-downloading12394 -Node: RELOADING13228 -Ref: #reloading13362 -Node: JSON API13795 -Ref: #json-api13910 -Node: DEBUG OUTPUT19444 -Ref: #debug-output19569 -Node: Debug output19596 -Ref: #debug-output-119697 -Node: ENVIRONMENT20114 -Ref: #environment20233 -Node: BUGS20350 -Ref: #bugs20434 +Node: PERMISSIONS10952 +Ref: #permissions11091 +Node: EDITING UPLOADING DOWNLOADING12303 +Ref: #editing-uploading-downloading12484 +Node: RELOADING13318 +Ref: #reloading13452 +Node: JSON API13885 +Ref: #json-api14000 +Node: DEBUG OUTPUT19534 +Ref: #debug-output19659 +Node: Debug output19686 +Ref: #debug-output-119787 +Node: ENVIRONMENT20204 +Ref: #environment20323 +Node: BUGS20440 +Ref: #bugs20524  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index ad726f484..5dcc30901 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -103,12 +103,13 @@ OPTIONS hledger-web also supports many of hledger's general options: General input/data transformation flags: - -f --file=FILE Read data from FILE, or from stdin if -. Can be - specified more than once. If not specified, reads - from $LEDGER_FILE or $HOME/.hledger.journal. - --rules-file=RULEFILE Use conversion rules from this file for + -f --file=[FMT:]FILE Read data from FILE, or from stdin if FILE is -, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + --rules=RULESFILE Use rules defined in this rules file for converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.rules for each such FILE. + specified, uses FILE.csv.rules for each FILE.csv. --alias=A=B|/RGX/=RPL transform account names from A to B, or by replacing regular expression matches --auto generate extra postings by applying auto posting @@ -171,7 +172,6 @@ OPTIONS --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. - --debug=[1-9] show this level of debug output (default: 1) General help flags: -h --help show command line help @@ -179,6 +179,7 @@ OPTIONS --info show the manual with info --man show the manual with man --version show version information + --debug=[1-9] show this level of debug output (default: 1) 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 a5ad40c6c..b0ee117ee 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -43,13 +43,15 @@ should answer it. It is detailed, so do skip ahead or skim when needed. You can read it on hledger.org, or as an info manual or man page on your system. -You can also get it from hledger itself with +You can also open a built\-in copy, at a point of interest, by running .PD 0 .P .PD -\f[CR]hledger \-\-man\f[R], \f[CR]hledger \-\-info\f[R] or +\f[CR]hledger \-\-man [CMD]\f[R], \f[CR]hledger \-\-info [CMD]\f[R] or \f[CR]hledger help [TOPIC]\f[R]. .PP +(And for shorter help, try \f[CR]hledger \-\-tldr [CMD]\f[R].) +.PP The main function of the hledger CLI is to read plain text files describing financial transactions, crunch the numbers, and print a useful report on the terminal (or save it as HTML, CSV, JSON or SQL). @@ -338,17 +340,28 @@ without using \f[CR]hledger\f[R]: \f[CR]hledger\-ui \-\-watch\f[R] or \f[CR]hledger\-web \-\-serve\f[R]. .SH Options Run \f[CR]hledger \-h\f[R] to see general command line help. -The following general options are common to most hledger commands. -General options can be written either before or after the command name. +Options can be written either before or after the command name. +These options are specific to the \f[CR]hledger\f[R] CLI: +.IP +.EX +Flags: + \-\-conf=CONFFILE Use extra options defined in this config file. If + not specified, searches upward and in XDG config + dir for hledger.conf (or .hledger.conf in $HOME). + \-n \-\-no\-conf ignore any config file +.EE +.PP +And the following general options are common to most hledger commands: .IP .EX General input/data transformation flags: - \-f \-\-file=FILE Read data from FILE, or from stdin if \-. Can be - specified more than once. If not specified, reads - from $LEDGER_FILE or $HOME/.hledger.journal. - \-\-rules\-file=RULEFILE Use conversion rules from this file for + \-f \-\-file=[FMT:]FILE Read data from FILE, or from stdin if FILE is \-, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + \-\-rules=RULESFILE Use rules defined in this rules file for converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.rules for each such FILE. + specified, uses FILE.csv.rules for each FILE.csv. \-\-alias=A=B|/RGX/=RPL transform account names from A to B, or by replacing regular expression matches \-\-auto generate extra postings by applying auto posting @@ -411,7 +424,6 @@ General output/reporting flags (supported by some commands): \-\-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. - \-\-debug=[1\-9] show this level of debug output (default: 1) General help flags: \-h \-\-help show command line help @@ -419,6 +431,7 @@ General help flags: \-\-info show the manual with info \-\-man show the manual with man \-\-version show version information + \-\-debug=[1\-9] show this level of debug output (default: 1) .EE .PP Usually hledger accepts any unambiguous flag prefix, eg you can write @@ -709,12 +722,40 @@ then reuse them by writing \f[CR]\[at]FILENAME\f[R] as a command line argument. Eg: \f[CR]hledger bal \[at]foo.args\f[R]. .PP -Inside the argument file, each line should contain just one option or +(Inside the argument file, each line should contain just one option or argument. -Don\[aq]t use spaces except inside quotes (or you\[aq]ll see a confusing -error); write \f[CR]=\f[R] (or nothing) between a flag and its argument. +Don\[aq]t use spaces except inside quotes; write \f[CR]=\f[R] or nothing +between a flag and its argument. For the special characters mentioned above, use one less level of -quoting than you would at the command prompt. +quoting than you would at the command prompt.) +.PP +Argument files are now superseded by.. +.SS Config files +hledger looks for a \f[CR]hledger.conf\f[R] file (or +\f[CR].hledger.conf\f[R] in your home directory) in the current +directory, then parent directories, then your XDG config directory +(\f[CR]\[ti]/.config/hledger/\f[R]). +Any command line options (or arguments) in this file will be added to +your \f[CR]hledger\f[R] commands, near the start of the command line (so +you can override them when needed). +.PP +Or you can specify a config file with the \f[CR]\-\-conf\f[R] option. +Or you can add a \f[CR]hledger \-\-conf\f[R] shebang line to a config +file and make it executable. +.PP +A hledger config file contains command line options, to be used with all +commands that support them, and optionally command\-specific options in +named sections. +hledger.conf.sample is a sample demonstrating the syntax; you can +install it as \f[CR]./hledger.conf\f[R] or +\f[CR]$HOME/.hledger.conf\f[R] and customise it. +.PP +You can disable config files entirely by running with the +\f[CR]\-n/\-\-no\-conf\f[R] flag. +This will ensure hledger runs with standard defaults, useful when +troubleshooting or when sharing examples with others. +.PP +\f[I](Added in 1.40; experimental)\f[R] .SH Output .SS Output destination hledger commands send their output to the terminal by default. @@ -968,14 +1009,12 @@ colour will not be used; otherwise, colour will be used if the output (terminal or file) supports it. .SS Box\-drawing -In terminal output, you can enable unicode box\-drawing characters to -render prettier tables: -.IP \[bu] 2 -if the \f[CR]\-\-pretty\f[R] option is given a value of \f[CR]yes\f[R] -or \f[CR]always\f[R] (or \f[CR]no\f[R] or \f[CR]never\f[R]), unicode -characters will (or will not) be used; -.IP \[bu] 2 -otherwise, unicode characters will not be used. +In terminal (text) output, to minimise the risk of display problems, +table borders are drawn using only ascii characters by default. +.PP +To see tables with prettier unicode box\-drawing characters, add the +\f[CR]\-\-pretty\f[R] flag. +This will also show outer borders and inter\-column borders. .SS Paging When showing long output in the terminal, hledger will try to use the pager specified by the \f[CR]PAGER\f[R] environment variable, or @@ -3659,8 +3698,8 @@ file, with an extra \f[CR].rules\f[R] extension added, in the same directory. Eg when asked to read \f[CR]foo/FILE.csv\f[R], hledger looks for \f[CR]foo/FILE.csv.rules\f[R]. -You can specify a different rules file with the -\f[CR]\-\-rules\-file\f[R] option. +You can specify a different rules file with the \f[CR]\-\-rules\f[R] +option. .PP At minimum, the rules file must identify the date and amount fields, and often it also specifies the date format and how many header lines there @@ -4548,8 +4587,8 @@ $ cat foo.dat | hledger \-f ssv:\- print If you use multiple \f[CR]\-f\f[R] options to read multiple CSV files at once, hledger will look for a correspondingly\-named rules file for each CSV file. -But if you use the \f[CR]\-\-rules\-file\f[R] option, that rules file -will be used for all the CSV files. +But if you specify a rules file with \f[CR]\-\-rules\f[R], that rules +file will be used for all the CSV files. .SS Reading files specified by rule Instead of specifying a CSV file in the command line, you can specify a rules file, as in \f[CR]hledger \-f foo.csv.rules CMD\f[R]. @@ -7811,10 +7850,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 @@ -10410,11 +10449,11 @@ $ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-O csv \-\-la \[dq]Assets:US:ETrade\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq] \[dq]Assets:US:ETrade\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq] \[dq]Assets:US:ETrade\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq] -\[dq]total\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq] -\[dq]total\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq] -\[dq]total\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq] -\[dq]total\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq] -\[dq]total\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq] +\[dq]Total:\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq] +\[dq]Total:\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq] +\[dq]Total:\[dq],\[dq]USD\[dq],\[dq]5120.50\[dq] +\[dq]Total:\[dq],\[dq]VEA\[dq],\[dq]36.00\[dq] +\[dq]Total:\[dq],\[dq]VHT\[dq],\[dq]294.00\[dq] .EE .PP Bare layout will sometimes display an extra row for the no\-symbol diff --git a/hledger/hledger.info b/hledger/hledger.info index 5798c0a3d..8d66b130c 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -33,9 +33,11 @@ bookkeeping/accounting as well! You don't need to know everything in here to use hledger productively, but when you have a question about functionality, this doc should answer it. It is detailed, so do skip ahead or skim when needed. You can read it on hledger.org, or as an -info manual or man page on your system. You can also get it from -hledger itself with -'hledger --man', 'hledger --info' or 'hledger help [TOPIC]'. +info manual or man page on your system. You can also open a built-in +copy, at a point of interest, by running +'hledger --man [CMD]', 'hledger --info [CMD]' or 'hledger help [TOPIC]'. + + (And for shorter help, try 'hledger --tldr [CMD]'.) The main function of the hledger CLI is to read plain text files describing financial transactions, crunch the numbers, and print a @@ -355,17 +357,27 @@ File: hledger.info, Node: Options, Next: Output, Prev: Commands, Up: Top 4 Options ********* -Run 'hledger -h' to see general command line help. The following -general options are common to most hledger commands. General options -can be written either before or after the command name. +Run 'hledger -h' to see general command line help. Options can be +written either before or after the command name. These options are +specific to the 'hledger' CLI: + +Flags: + --conf=CONFFILE Use extra options defined in this config file. If + not specified, searches upward and in XDG config + dir for hledger.conf (or .hledger.conf in $HOME). + -n --no-conf ignore any config file + + And the following general options are common to most hledger +commands: General input/data transformation flags: - -f --file=FILE Read data from FILE, or from stdin if -. Can be - specified more than once. If not specified, reads - from $LEDGER_FILE or $HOME/.hledger.journal. - --rules-file=RULEFILE Use conversion rules from this file for + -f --file=[FMT:]FILE Read data from FILE, or from stdin if FILE is -, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + --rules=RULESFILE Use rules defined in this rules file for converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.rules for each such FILE. + specified, uses FILE.csv.rules for each FILE.csv. --alias=A=B|/RGX/=RPL transform account names from A to B, or by replacing regular expression matches --auto generate extra postings by applying auto posting @@ -428,7 +440,6 @@ General output/reporting flags (supported by some commands): --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. - --debug=[1-9] show this level of debug output (default: 1) General help flags: -h --help show command line help @@ -436,6 +447,7 @@ General help flags: --info show the manual with info --man show the manual with man --version show version information + --debug=[1-9] show this level of debug output (default: 1) Usually hledger accepts any unambiguous flag prefix, eg you can write '--tl' instead of '--tldr' or '--dry' instead of '--dry-run'. @@ -456,6 +468,7 @@ to skip these until you need them. * Unicode characters:: * Regular expressions:: * Argument files:: +* Config files::  File: hledger.info, Node: Special characters, Next: Unicode characters, Up: Options @@ -709,7 +722,7 @@ they support: See Special characters.  -File: hledger.info, Node: Argument files, Prev: Regular expressions, Up: Options +File: hledger.info, Node: Argument files, Next: Config files, Prev: Regular expressions, Up: Options 4.4 Argument files ================== @@ -718,11 +731,43 @@ You can save a set of command line options and arguments in a file, and then reuse them by writing '@FILENAME' as a command line argument. Eg: 'hledger bal @foo.args'. - Inside the argument file, each line should contain just one option or -argument. Don't use spaces except inside quotes (or you'll see a -confusing error); write '=' (or nothing) between a flag and its -argument. For the special characters mentioned above, use one less -level of quoting than you would at the command prompt. + (Inside the argument file, each line should contain just one option +or argument. Don't use spaces except inside quotes; write '=' or +nothing between a flag and its argument. For the special characters +mentioned above, use one less level of quoting than you would at the +command prompt.) + + Argument files are now superseded by.. + + +File: hledger.info, Node: Config files, Prev: Argument files, Up: Options + +4.5 Config files +================ + +hledger looks for a 'hledger.conf' file (or '.hledger.conf' in your home +directory) in the current directory, then parent directories, then your +XDG config directory ('~/.config/hledger/'). Any command line options +(or arguments) in this file will be added to your 'hledger' commands, +near the start of the command line (so you can override them when +needed). + + Or you can specify a config file with the '--conf' option. Or you +can add a 'hledger --conf' shebang line to a config file and make it +executable. + + A hledger config file contains command line options, to be used with +all commands that support them, and optionally command-specific options +in named sections. hledger.conf.sample is a sample demonstrating the +syntax; you can install it as './hledger.conf' or '$HOME/.hledger.conf' +and customise it. + + You can disable config files entirely by running with the +'-n/--no-conf' flag. This will ensure hledger runs with standard +defaults, useful when troubleshooting or when sharing examples with +others. + + _(Added in 1.40; experimental)_  File: hledger.info, Node: Output, Next: Environment, Prev: Options, Up: Top @@ -914,12 +959,12 @@ File: hledger.info, Node: Box-drawing, Next: Paging, Prev: Colour, Up: Outpu 5.5 Box-drawing =============== -In terminal output, you can enable unicode box-drawing characters to -render prettier tables: +In terminal (text) output, to minimise the risk of display problems, +table borders are drawn using only ascii characters by default. - * if the '--pretty' option is given a value of 'yes' or 'always' (or - 'no' or 'never'), unicode characters will (or will not) be used; - * otherwise, unicode characters will not be used. + To see tables with prettier unicode box-drawing characters, add the +'--pretty' flag. This will also show outer borders and inter-column +borders.  File: hledger.info, Node: Paging, Next: Debug output, Prev: Box-drawing, Up: Output @@ -3649,7 +3694,7 @@ how to categorise transactions based on description or other attributes. file, with an extra '.rules' extension added, in the same directory. Eg when asked to read 'foo/FILE.csv', hledger looks for 'foo/FILE.csv.rules'. You can specify a different rules file with the -'--rules-file' option. +'--rules' option. At minimum, the rules file must identify the date and amount fields, and often it also specifies the date format and how many header lines @@ -4574,8 +4619,8 @@ File: hledger.info, Node: Reading multiple CSV files, Next: Reading files spec If you use multiple '-f' options to read multiple CSV files at once, hledger will look for a correspondingly-named rules file for each CSV -file. But if you use the '--rules-file' option, that rules file will be -used for all the CSV files. +file. But if you specify a rules file with '--rules', that rules file +will be used for all the CSV files.  File: hledger.info, Node: Reading files specified by rule, Next: Valid transactions, Prev: Reading multiple CSV files, Up: Working with CSV @@ -7422,10 +7467,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 @@ -10024,11 +10069,11 @@ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout= "Assets:US:ETrade","USD","5120.50" "Assets:US:ETrade","VEA","36.00" "Assets:US:ETrade","VHT","294.00" -"total","GLD","70.00" -"total","ITOT","17.00" -"total","USD","5120.50" -"total","VEA","36.00" -"total","VHT","294.00" +"Total:","GLD","70.00" +"Total:","ITOT","17.00" +"Total:","USD","5120.50" +"Total:","VEA","36.00" +"Total:","VHT","294.00" Bare layout will sometimes display an extra row for the no-symbol commodity, because of zero amounts (hledger treats zeroes as @@ -11574,682 +11619,684 @@ See hledger and Ledger for full details.  Tag Table: Node: Top208 -Node: PART 1 USER INTERFACE4270 -Ref: #part-1-user-interface4409 -Node: Input4409 -Ref: #input4519 -Node: Text encoding5486 -Ref: #text-encoding5600 -Node: Data formats6166 -Ref: #data-formats6301 -Node: Standard input7890 -Ref: #standard-input8030 -Node: Multiple files8279 -Ref: #multiple-files8418 -Node: Strict mode9016 -Ref: #strict-mode9126 -Node: Commands9850 -Ref: #commands9952 -Node: Add-on commands11019 -Ref: #add-on-commands11121 -Node: Options12237 -Ref: #options12338 -Node: Special characters18188 -Ref: #special-characters18325 -Node: Single escaping shell metacharacters18488 -Ref: #single-escaping-shell-metacharacters18729 -Node: Double escaping regular expression metacharacters19332 -Ref: #double-escaping-regular-expression-metacharacters19643 -Node: Triple escaping for add-on commands20169 -Ref: #triple-escaping-for-add-on-commands20429 -Node: Less escaping21073 -Ref: #less-escaping21227 -Node: Unicode characters21551 -Ref: #unicode-characters21716 -Node: Regular expressions23215 -Ref: #regular-expressions23378 -Node: hledger's regular expressions26474 -Ref: #hledgers-regular-expressions26633 -Node: Argument files28019 -Ref: #argument-files28145 -Node: Output28642 -Ref: #output28744 -Node: Output destination28871 -Ref: #output-destination29002 -Node: Output format29427 -Ref: #output-format29573 -Node: CSV output31170 -Ref: #csv-output31286 -Node: HTML output31389 -Ref: #html-output31527 -Node: JSON output31621 -Ref: #json-output31759 -Node: SQL output32744 -Ref: #sql-output32860 -Node: Commodity styles33595 -Ref: #commodity-styles33735 -Node: Colour34473 -Ref: #colour34591 -Node: Box-drawing34995 -Ref: #box-drawing35113 -Node: Paging35403 -Ref: #paging35517 -Node: Debug output36470 -Ref: #debug-output36576 -Node: Environment37239 -Ref: #environment37363 -Node: PART 2 DATA FORMATS37930 -Ref: #part-2-data-formats38073 -Node: Journal38073 -Ref: #journal38182 -Node: Journal cheatsheet40550 -Ref: #journal-cheatsheet40677 -Node: Comments46764 -Ref: #comments46892 -Node: Transactions47708 -Ref: #transactions47831 -Node: Dates48845 -Ref: #dates48952 -Node: Simple dates48997 -Ref: #simple-dates49113 -Node: Posting dates49613 -Ref: #posting-dates49731 -Node: Status50700 -Ref: #status50801 -Node: Code52466 -Ref: #code52569 -Node: Description52801 -Ref: #description52932 -Node: Payee and note53488 -Ref: #payee-and-note53594 -Node: Transaction comments54579 -Ref: #transaction-comments54732 -Node: Postings55095 -Ref: #postings55226 -Node: Debits and credits56258 -Ref: #debits-and-credits56405 -Node: The two space delimiter56868 -Ref: #the-two-space-delimiter57025 -Node: Account names57433 -Ref: #account-names57563 -Node: Amounts59237 -Ref: #amounts59365 -Node: Decimal marks60266 -Ref: #decimal-marks60393 -Node: Digit group marks61370 -Ref: #digit-group-marks61523 -Node: Commodity62005 -Ref: #commodity62134 -Node: Costs63122 -Ref: #costs63217 -Node: Balance assertions65374 -Ref: #balance-assertions65527 -Node: Assertions and ordering66611 -Ref: #assertions-and-ordering66800 -Node: Assertions and multiple included files67339 -Ref: #assertions-and-multiple-included-files67599 -Node: Assertions and multiple -f files68099 -Ref: #assertions-and-multiple--f-files68344 -Node: Assertions and costs68741 -Ref: #assertions-and-costs68950 -Node: Assertions and commodities69391 -Ref: #assertions-and-commodities69606 -Node: Assertions and subaccounts71050 -Ref: #assertions-and-subaccounts71276 -Node: Assertions and virtual postings71720 -Ref: #assertions-and-virtual-postings71958 -Node: Assertions and auto postings72090 -Ref: #assertions-and-auto-postings72320 -Node: Assertions and precision72965 -Ref: #assertions-and-precision73147 -Node: Posting comments73414 -Ref: #posting-comments73577 -Node: Transaction balancing73954 -Ref: #transaction-balancing74113 -Node: Tags75956 -Ref: #tags76075 -Node: Tag names77418 -Ref: #tag-names77525 -Node: Special tags77913 -Ref: #special-tags78045 -Node: Tag values79558 -Ref: #tag-values79668 -Node: Directives80540 -Ref: #directives80667 -Node: Directives and multiple files81997 -Ref: #directives-and-multiple-files82175 -Node: Directive effects82942 -Ref: #directive-effects83096 -Node: account directive86098 -Ref: #account-directive86254 -Node: Account comments87548 -Ref: #account-comments87699 -Node: Account error checking88207 -Ref: #account-error-checking88400 -Node: Account display order89589 -Ref: #account-display-order89777 -Node: Account types90787 -Ref: #account-types90928 -Node: alias directive94561 -Ref: #alias-directive94722 -Node: Basic aliases95772 -Ref: #basic-aliases95903 -Node: Regex aliases96647 -Ref: #regex-aliases96804 -Node: Combining aliases97694 -Ref: #combining-aliases97872 -Node: Aliases and multiple files99148 -Ref: #aliases-and-multiple-files99352 -Node: end aliases directive99931 -Ref: #end-aliases-directive100150 -Node: Aliases can generate bad account names100299 -Ref: #aliases-can-generate-bad-account-names100547 -Node: Aliases and account types101132 -Ref: #aliases-and-account-types101324 -Node: commodity directive102020 -Ref: #commodity-directive102194 -Node: Commodity directive syntax103607 -Ref: #commodity-directive-syntax103792 -Node: Commodity error checking105243 -Ref: #commodity-error-checking105424 -Node: decimal-mark directive105718 -Ref: #decimal-mark-directive105900 -Node: include directive106297 -Ref: #include-directive106461 -Node: P directive107373 -Ref: #p-directive107518 -Node: payee directive108407 -Ref: #payee-directive108556 -Node: tag directive109029 -Ref: #tag-directive109184 -Node: Periodic transactions109641 -Ref: #periodic-transactions109806 -Node: Periodic rule syntax111795 -Ref: #periodic-rule-syntax111973 -Node: Periodic rules and relative dates112618 -Ref: #periodic-rules-and-relative-dates112884 -Node: Two spaces between period expression and description!113395 -Ref: #two-spaces-between-period-expression-and-description113672 -Node: Auto postings114356 -Ref: #auto-postings114504 -Node: Auto postings and multiple files117334 -Ref: #auto-postings-and-multiple-files117498 -Node: Auto postings and dates117899 -Ref: #auto-postings-and-dates118147 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions118322 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions118678 -Node: Auto posting tags119181 -Ref: #auto-posting-tags119463 -Node: Auto postings on forecast transactions only120099 -Ref: #auto-postings-on-forecast-transactions-only120345 -Node: Other syntax120592 -Ref: #other-syntax120708 -Node: Balance assignments121364 -Ref: #balance-assignments121520 -Node: Balance assignments and costs122892 -Ref: #balance-assignments-and-costs123104 -Node: Balance assignments and multiple files123314 -Ref: #balance-assignments-and-multiple-files123544 -Node: Bracketed posting dates123737 -Ref: #bracketed-posting-dates123921 -Node: D directive124435 -Ref: #d-directive124603 -Node: apply account directive126208 -Ref: #apply-account-directive126388 -Node: Y directive127075 -Ref: #y-directive127235 -Node: Secondary dates128063 -Ref: #secondary-dates128217 -Node: Star comments129548 -Ref: #star-comments129708 -Node: Valuation expressions130240 -Ref: #valuation-expressions130417 -Node: Virtual postings130539 -Ref: #virtual-postings130716 -Node: Other Ledger directives132163 -Ref: #other-ledger-directives132359 -Node: Other cost/lot notations132925 -Ref: #other-costlot-notations133098 -Node: CSV135687 -Ref: #csv135778 -Node: CSV rules cheatsheet137775 -Ref: #csv-rules-cheatsheet137902 -Node: source139700 -Ref: #source139821 -Node: separator140701 -Ref: #separator140812 -Node: skip141352 -Ref: #skip141458 -Node: date-format142002 -Ref: #date-format142121 -Node: timezone142845 -Ref: #timezone142966 -Node: newest-first143971 -Ref: #newest-first144107 -Node: intra-day-reversed144684 -Ref: #intra-day-reversed144836 -Node: decimal-mark145284 -Ref: #decimal-mark145423 -Node: fields list145762 -Ref: #fields-list145899 -Node: Field assignment147570 -Ref: #field-assignment147712 -Node: Field names148789 -Ref: #field-names148918 -Node: date field150121 -Ref: #date-field150237 -Node: date2 field150285 -Ref: #date2-field150424 -Node: status field150480 -Ref: #status-field150621 -Node: code field150670 -Ref: #code-field150813 -Node: description field150858 -Ref: #description-field151016 -Node: comment field151075 -Ref: #comment-field151228 -Node: account field151521 -Ref: #account-field151669 -Node: amount field152239 -Ref: #amount-field152386 -Node: currency field155078 -Ref: #currency-field155229 -Node: balance field155486 -Ref: #balance-field155616 -Node: if block156009 -Ref: #if-block156128 -Node: Matchers157536 -Ref: #matchers157648 -Node: What matchers match158445 -Ref: #what-matchers-match158592 -Node: Combining matchers159032 -Ref: #combining-matchers159198 -Node: Match groups159735 -Ref: #match-groups159861 -Node: if table160629 -Ref: #if-table160749 -Node: balance-type162630 -Ref: #balance-type162757 -Node: include163457 -Ref: #include163582 -Node: Working with CSV164026 -Ref: #working-with-csv164171 -Node: Rapid feedback164578 -Ref: #rapid-feedback164709 -Node: Valid CSV165161 -Ref: #valid-csv165305 -Node: File Extension166037 -Ref: #file-extension166208 -Node: Reading CSV from standard input166772 -Ref: #reading-csv-from-standard-input166994 -Node: Reading multiple CSV files167158 -Ref: #reading-multiple-csv-files167387 -Node: Reading files specified by rule167628 -Ref: #reading-files-specified-by-rule167854 -Node: Valid transactions169025 -Ref: #valid-transactions169222 -Node: Deduplicating importing169850 -Ref: #deduplicating-importing170043 -Node: Setting amounts171079 -Ref: #setting-amounts171248 -Node: Amount signs173606 -Ref: #amount-signs173774 -Node: Setting currency/commodity174671 -Ref: #setting-currencycommodity174873 -Node: Amount decimal places176047 -Ref: #amount-decimal-places176251 -Node: Referencing other fields177304 -Ref: #referencing-other-fields177515 -Node: How CSV rules are evaluated178412 -Ref: #how-csv-rules-are-evaluated178627 -Node: Well factored rules180080 -Ref: #well-factored-rules180246 -Node: CSV rules examples180570 -Ref: #csv-rules-examples180703 -Node: Bank of Ireland180768 -Ref: #bank-of-ireland180903 -Node: Coinbase182365 -Ref: #coinbase182501 -Node: Amazon183548 -Ref: #amazon183671 -Node: Paypal185390 -Ref: #paypal185496 -Node: Timeclock193140 -Ref: #timeclock193245 -Node: Timedot195421 -Ref: #timedot195544 -Node: Timedot examples198665 -Ref: #timedot-examples198771 -Node: PART 3 REPORTING CONCEPTS200942 -Ref: #part-3-reporting-concepts201106 -Node: Time periods201106 -Ref: #time-periods201240 -Node: Report start & end date201358 -Ref: #report-start-end-date201510 -Node: Smart dates202834 -Ref: #smart-dates202987 -Node: Report intervals204777 -Ref: #report-intervals204932 -Node: Date adjustment205350 -Ref: #date-adjustment205510 -Node: Period expressions206361 -Ref: #period-expressions206502 -Node: Period expressions with a report interval208266 -Ref: #period-expressions-with-a-report-interval208500 -Node: More complex report intervals208714 -Ref: #more-complex-report-intervals208959 -Node: Multiple weekday intervals210820 -Ref: #multiple-weekday-intervals211009 -Node: Depth211831 -Ref: #depth211933 -Node: Queries212229 -Ref: #queries212331 -Node: Query types213927 -Ref: #query-types214048 -Node: Combining query terms217282 -Ref: #combining-query-terms217459 -Node: Queries and command options219022 -Ref: #queries-and-command-options219227 -Node: Queries and account aliases219476 -Ref: #queries-and-account-aliases219681 -Node: Queries and valuation219801 -Ref: #queries-and-valuation219958 -Node: Pivoting220163 -Ref: #pivoting220277 -Node: Generating data222054 -Ref: #generating-data222186 -Node: Forecasting223854 -Ref: #forecasting223979 -Node: --forecast224510 -Ref: #forecast224641 -Node: Inspecting forecast transactions225611 -Ref: #inspecting-forecast-transactions225813 -Node: Forecast reports226943 -Ref: #forecast-reports227116 -Node: Forecast tags228052 -Ref: #forecast-tags228212 -Node: Forecast period in detail228672 -Ref: #forecast-period-in-detail228866 -Node: Forecast troubleshooting229760 -Ref: #forecast-troubleshooting229928 -Node: Budgeting230831 -Ref: #budgeting230954 -Node: Amount formatting231391 -Ref: #amount-formatting231533 -Node: Commodity display style231635 -Ref: #commodity-display-style231789 -Node: Rounding233476 -Ref: #rounding233631 -Node: Trailing decimal marks234081 -Ref: #trailing-decimal-marks234260 -Node: Amount parseability235014 -Ref: #amount-parseability235170 -Node: Cost reporting236595 -Ref: #cost-reporting236737 -Node: Recording costs237398 -Ref: #recording-costs237534 -Node: Reporting at cost239125 -Ref: #reporting-at-cost239300 -Node: Equity conversion postings239890 -Ref: #equity-conversion-postings240104 -Node: Inferring equity conversion postings242535 -Ref: #inferring-equity-conversion-postings242798 -Node: Combining costs and equity conversion postings243550 -Ref: #combining-costs-and-equity-conversion-postings243860 -Node: Requirements for detecting equity conversion postings244775 -Ref: #requirements-for-detecting-equity-conversion-postings245097 -Node: Infer cost and equity by default ?246297 -Ref: #infer-cost-and-equity-by-default246526 -Node: Value reporting246734 -Ref: #value-reporting246876 -Node: -V Value247615 -Ref: #v-value247747 -Node: -X Value in specified commodity247942 -Ref: #x-value-in-specified-commodity248143 -Node: Valuation date248292 -Ref: #valuation-date248469 -Node: Finding market price249252 -Ref: #finding-market-price249463 -Node: --infer-market-prices market prices from transactions250632 -Ref: #infer-market-prices-market-prices-from-transactions250914 -Node: Valuation commodity253676 -Ref: #valuation-commodity253896 -Node: --value Flexible valuation255109 -Ref: #value-flexible-valuation255308 -Node: Valuation examples256952 -Ref: #valuation-examples257152 -Node: Interaction of valuation and queries259084 -Ref: #interaction-of-valuation-and-queries259324 -Node: Effect of valuation on reports259801 -Ref: #effect-of-valuation-on-reports260004 -Node: PART 4 COMMANDS267699 -Ref: #part-4-commands267842 -Node: Help commands269915 -Ref: #help-commands270060 -Node: help270088 -Ref: #help270177 -Node: demo271749 -Ref: #demo271838 -Node: User interface commands272882 -Ref: #user-interface-commands273051 -Node: ui273076 -Ref: #ui273168 -Node: web273201 -Ref: #web273295 -Node: Data entry commands273329 -Ref: #data-entry-commands273498 -Node: add273527 -Ref: #add273621 -Node: import276082 -Ref: #import276182 -Node: Date skipping277343 -Ref: #date-skipping277466 -Node: Import testing280244 -Ref: #import-testing280407 -Node: Importing balance assignments281250 -Ref: #importing-balance-assignments281457 -Node: Import and commodity styles282106 -Ref: #import-and-commodity-styles282286 -Node: Basic report commands282515 -Ref: #basic-report-commands282689 -Node: accounts282816 -Ref: #accounts282926 -Node: codes285689 -Ref: #codes285813 -Node: commodities286711 -Ref: #commodities286851 -Node: descriptions286955 -Ref: #descriptions287097 -Node: files287422 -Ref: #files287544 -Node: notes287719 -Ref: #notes287835 -Node: payees288231 -Ref: #payees288350 -Node: prices289015 -Ref: #prices289134 -Node: stats289907 -Ref: #stats290022 -Node: tags291648 -Ref: #tags-1291748 -Node: Standard report commands292955 -Ref: #standard-report-commands293140 -Node: print293260 -Ref: #print293368 -Node: print explicitness295706 -Ref: #print-explicitness295847 -Node: print amount style296626 -Ref: #print-amount-style296794 -Node: print parseability297864 -Ref: #print-parseability298034 -Node: print other features298783 -Ref: #print-other-features298960 -Node: print output format299481 -Ref: #print-output-format299627 -Node: aregister302766 -Ref: #aregister302899 -Node: aregister and posting dates306546 -Ref: #aregister-and-posting-dates306691 -Node: register307447 -Ref: #register307585 -Node: Custom register output313750 -Ref: #custom-register-output313879 -Node: balancesheet315226 -Ref: #balancesheet315381 -Node: balancesheetequity319862 -Ref: #balancesheetequity320029 -Node: cashflow324868 -Ref: #cashflow325018 -Node: incomestatement329296 -Ref: #incomestatement329433 -Node: Advanced report commands333760 -Ref: #advanced-report-commands333938 -Node: balance333968 -Ref: #balance334076 -Node: balance features338851 -Ref: #balance-features338991 -Node: Simple balance report340901 -Ref: #simple-balance-report341086 -Node: Balance report line format342711 -Ref: #balance-report-line-format342913 -Node: Filtered balance report345071 -Ref: #filtered-balance-report345263 -Node: List or tree mode345590 -Ref: #list-or-tree-mode345758 -Node: Depth limiting347103 -Ref: #depth-limiting347269 -Node: Dropping top-level accounts347870 -Ref: #dropping-top-level-accounts348070 -Node: Showing declared accounts348380 -Ref: #showing-declared-accounts348579 -Node: Sorting by amount349110 -Ref: #sorting-by-amount349277 -Node: Percentages349947 -Ref: #percentages350106 -Node: Multi-period balance report350654 -Ref: #multi-period-balance-report350854 -Node: Balance change end balance353406 -Ref: #balance-change-end-balance353615 -Node: Balance report types355043 -Ref: #balance-report-types355224 -Node: Calculation type355722 -Ref: #calculation-type355877 -Node: Accumulation type356426 -Ref: #accumulation-type356606 -Node: Valuation type357527 -Ref: #valuation-type357715 -Node: Combining balance report types358716 -Ref: #combining-balance-report-types358910 -Node: Budget report360748 -Ref: #budget-report360910 -Node: Using the budget report363053 -Ref: #using-the-budget-report363226 -Node: Budget date surprises365329 -Ref: #budget-date-surprises365529 -Node: Selecting budget goals366693 -Ref: #selecting-budget-goals366896 -Node: Budgeting vs forecasting367641 -Ref: #budgeting-vs-forecasting367818 -Node: Balance report layout369318 -Ref: #balance-report-layout369503 -Node: Wide layout370456 -Ref: #wide-layout370591 -Node: Tall layout372861 -Ref: #tall-layout373016 -Node: Bare layout374167 -Ref: #bare-layout374322 -Node: Tidy layout376226 -Ref: #tidy-layout376361 -Node: Some useful balance reports377770 -Ref: #some-useful-balance-reports377945 -Node: roi379030 -Ref: #roi379130 -Node: Spaces and special characters in --inv and --pnl381277 -Ref: #spaces-and-special-characters-in---inv-and---pnl381515 -Node: Semantics of --inv and --pnl382003 -Ref: #semantics-of---inv-and---pnl382240 -Node: IRR and TWR explained384090 -Ref: #irr-and-twr-explained384248 -Node: Chart commands387501 -Ref: #chart-commands387659 -Node: activity387682 -Ref: #activity387771 -Node: Data generation commands388179 -Ref: #data-generation-commands388353 -Node: close388385 -Ref: #close388491 -Node: close --migrate390977 -Ref: #close---migrate391102 -Node: close --close392741 -Ref: #close---close392883 -Node: close --open393119 -Ref: #close---open393258 -Node: close --assert393368 -Ref: #close---assert393512 -Node: close --assign393733 -Ref: #close---assign393879 -Node: close --retain394405 -Ref: #close---retain394556 -Node: close customisation395301 -Ref: #close-customisation395478 -Node: close and balance assertions396945 -Ref: #close-and-balance-assertions397140 -Node: close examples398467 -Ref: #close-examples398606 -Node: Retain earnings398704 -Ref: #retain-earnings398861 -Node: Migrate balances to a new file399207 -Ref: #migrate-balances-to-a-new-file399431 -Node: More detailed close examples400559 -Ref: #more-detailed-close-examples400755 -Node: rewrite400781 -Ref: #rewrite400891 -Node: Re-write rules in a file403353 -Ref: #re-write-rules-in-a-file403514 -Node: Diff output format404663 -Ref: #diff-output-format404844 -Node: rewrite vs print --auto405936 -Ref: #rewrite-vs.-print---auto406094 -Node: Maintenance commands406650 -Ref: #maintenance-commands406821 -Node: check406859 -Ref: #check406958 -Node: Basic checks407941 -Ref: #basic-checks408059 -Node: Strict checks408894 -Ref: #strict-checks409035 -Node: Other checks409769 -Ref: #other-checks409909 -Node: Custom checks411624 -Ref: #custom-checks411744 -Node: diff412079 -Ref: #diff412189 -Node: test413286 -Ref: #test413382 -Node: PART 5 COMMON TASKS414158 -Ref: #part-5-common-tasks414317 -Node: Getting help414391 -Ref: #getting-help414540 -Node: Constructing command lines415300 -Ref: #constructing-command-lines415481 -Node: Starting a journal file416138 -Ref: #starting-a-journal-file416320 -Node: Setting LEDGER_FILE417522 -Ref: #setting-ledger_file417694 -Node: Setting opening balances418651 -Ref: #setting-opening-balances418832 -Node: Recording transactions421973 -Ref: #recording-transactions422142 -Node: Reconciling422698 -Ref: #reconciling422830 -Node: Reporting425087 -Ref: #reporting425216 -Node: Migrating to a new file429201 -Ref: #migrating-to-a-new-file429351 -Node: BUGS429650 -Ref: #bugs429744 -Node: Troubleshooting430623 -Ref: #troubleshooting430723 +Node: PART 1 USER INTERFACE4363 +Ref: #part-1-user-interface4502 +Node: Input4502 +Ref: #input4612 +Node: Text encoding5579 +Ref: #text-encoding5693 +Node: Data formats6259 +Ref: #data-formats6394 +Node: Standard input7983 +Ref: #standard-input8123 +Node: Multiple files8372 +Ref: #multiple-files8511 +Node: Strict mode9109 +Ref: #strict-mode9219 +Node: Commands9943 +Ref: #commands10045 +Node: Add-on commands11112 +Ref: #add-on-commands11214 +Node: Options12330 +Ref: #options12431 +Node: Special characters18729 +Ref: #special-characters18866 +Node: Single escaping shell metacharacters19029 +Ref: #single-escaping-shell-metacharacters19270 +Node: Double escaping regular expression metacharacters19873 +Ref: #double-escaping-regular-expression-metacharacters20184 +Node: Triple escaping for add-on commands20710 +Ref: #triple-escaping-for-add-on-commands20970 +Node: Less escaping21614 +Ref: #less-escaping21768 +Node: Unicode characters22092 +Ref: #unicode-characters22257 +Node: Regular expressions23756 +Ref: #regular-expressions23919 +Node: hledger's regular expressions27015 +Ref: #hledgers-regular-expressions27174 +Node: Argument files28560 +Ref: #argument-files28707 +Node: Config files29213 +Ref: #config-files29328 +Node: Output30387 +Ref: #output30489 +Node: Output destination30616 +Ref: #output-destination30747 +Node: Output format31172 +Ref: #output-format31318 +Node: CSV output32915 +Ref: #csv-output33031 +Node: HTML output33134 +Ref: #html-output33272 +Node: JSON output33366 +Ref: #json-output33504 +Node: SQL output34489 +Ref: #sql-output34605 +Node: Commodity styles35340 +Ref: #commodity-styles35480 +Node: Colour36218 +Ref: #colour36336 +Node: Box-drawing36740 +Ref: #box-drawing36858 +Node: Paging37142 +Ref: #paging37256 +Node: Debug output38209 +Ref: #debug-output38315 +Node: Environment38978 +Ref: #environment39102 +Node: PART 2 DATA FORMATS39669 +Ref: #part-2-data-formats39812 +Node: Journal39812 +Ref: #journal39921 +Node: Journal cheatsheet42289 +Ref: #journal-cheatsheet42416 +Node: Comments48503 +Ref: #comments48631 +Node: Transactions49447 +Ref: #transactions49570 +Node: Dates50584 +Ref: #dates50691 +Node: Simple dates50736 +Ref: #simple-dates50852 +Node: Posting dates51352 +Ref: #posting-dates51470 +Node: Status52439 +Ref: #status52540 +Node: Code54205 +Ref: #code54308 +Node: Description54540 +Ref: #description54671 +Node: Payee and note55227 +Ref: #payee-and-note55333 +Node: Transaction comments56318 +Ref: #transaction-comments56471 +Node: Postings56834 +Ref: #postings56965 +Node: Debits and credits57997 +Ref: #debits-and-credits58144 +Node: The two space delimiter58607 +Ref: #the-two-space-delimiter58764 +Node: Account names59172 +Ref: #account-names59302 +Node: Amounts60976 +Ref: #amounts61104 +Node: Decimal marks62005 +Ref: #decimal-marks62132 +Node: Digit group marks63109 +Ref: #digit-group-marks63262 +Node: Commodity63744 +Ref: #commodity63873 +Node: Costs64861 +Ref: #costs64956 +Node: Balance assertions67113 +Ref: #balance-assertions67266 +Node: Assertions and ordering68350 +Ref: #assertions-and-ordering68539 +Node: Assertions and multiple included files69078 +Ref: #assertions-and-multiple-included-files69338 +Node: Assertions and multiple -f files69838 +Ref: #assertions-and-multiple--f-files70083 +Node: Assertions and costs70480 +Ref: #assertions-and-costs70689 +Node: Assertions and commodities71130 +Ref: #assertions-and-commodities71345 +Node: Assertions and subaccounts72789 +Ref: #assertions-and-subaccounts73015 +Node: Assertions and virtual postings73459 +Ref: #assertions-and-virtual-postings73697 +Node: Assertions and auto postings73829 +Ref: #assertions-and-auto-postings74059 +Node: Assertions and precision74704 +Ref: #assertions-and-precision74886 +Node: Posting comments75153 +Ref: #posting-comments75316 +Node: Transaction balancing75693 +Ref: #transaction-balancing75852 +Node: Tags77695 +Ref: #tags77814 +Node: Tag names79157 +Ref: #tag-names79264 +Node: Special tags79652 +Ref: #special-tags79784 +Node: Tag values81297 +Ref: #tag-values81407 +Node: Directives82279 +Ref: #directives82406 +Node: Directives and multiple files83736 +Ref: #directives-and-multiple-files83914 +Node: Directive effects84681 +Ref: #directive-effects84835 +Node: account directive87837 +Ref: #account-directive87993 +Node: Account comments89287 +Ref: #account-comments89438 +Node: Account error checking89946 +Ref: #account-error-checking90139 +Node: Account display order91328 +Ref: #account-display-order91516 +Node: Account types92526 +Ref: #account-types92667 +Node: alias directive96300 +Ref: #alias-directive96461 +Node: Basic aliases97511 +Ref: #basic-aliases97642 +Node: Regex aliases98386 +Ref: #regex-aliases98543 +Node: Combining aliases99433 +Ref: #combining-aliases99611 +Node: Aliases and multiple files100887 +Ref: #aliases-and-multiple-files101091 +Node: end aliases directive101670 +Ref: #end-aliases-directive101889 +Node: Aliases can generate bad account names102038 +Ref: #aliases-can-generate-bad-account-names102286 +Node: Aliases and account types102871 +Ref: #aliases-and-account-types103063 +Node: commodity directive103759 +Ref: #commodity-directive103933 +Node: Commodity directive syntax105346 +Ref: #commodity-directive-syntax105531 +Node: Commodity error checking106982 +Ref: #commodity-error-checking107163 +Node: decimal-mark directive107457 +Ref: #decimal-mark-directive107639 +Node: include directive108036 +Ref: #include-directive108200 +Node: P directive109112 +Ref: #p-directive109257 +Node: payee directive110146 +Ref: #payee-directive110295 +Node: tag directive110768 +Ref: #tag-directive110923 +Node: Periodic transactions111380 +Ref: #periodic-transactions111545 +Node: Periodic rule syntax113534 +Ref: #periodic-rule-syntax113712 +Node: Periodic rules and relative dates114357 +Ref: #periodic-rules-and-relative-dates114623 +Node: Two spaces between period expression and description!115134 +Ref: #two-spaces-between-period-expression-and-description115411 +Node: Auto postings116095 +Ref: #auto-postings116243 +Node: Auto postings and multiple files119073 +Ref: #auto-postings-and-multiple-files119237 +Node: Auto postings and dates119638 +Ref: #auto-postings-and-dates119886 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions120061 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions120417 +Node: Auto posting tags120920 +Ref: #auto-posting-tags121202 +Node: Auto postings on forecast transactions only121838 +Ref: #auto-postings-on-forecast-transactions-only122084 +Node: Other syntax122331 +Ref: #other-syntax122447 +Node: Balance assignments123103 +Ref: #balance-assignments123259 +Node: Balance assignments and costs124631 +Ref: #balance-assignments-and-costs124843 +Node: Balance assignments and multiple files125053 +Ref: #balance-assignments-and-multiple-files125283 +Node: Bracketed posting dates125476 +Ref: #bracketed-posting-dates125660 +Node: D directive126174 +Ref: #d-directive126342 +Node: apply account directive127947 +Ref: #apply-account-directive128127 +Node: Y directive128814 +Ref: #y-directive128974 +Node: Secondary dates129802 +Ref: #secondary-dates129956 +Node: Star comments131287 +Ref: #star-comments131447 +Node: Valuation expressions131979 +Ref: #valuation-expressions132156 +Node: Virtual postings132278 +Ref: #virtual-postings132455 +Node: Other Ledger directives133902 +Ref: #other-ledger-directives134098 +Node: Other cost/lot notations134664 +Ref: #other-costlot-notations134837 +Node: CSV137426 +Ref: #csv137517 +Node: CSV rules cheatsheet139509 +Ref: #csv-rules-cheatsheet139636 +Node: source141434 +Ref: #source141555 +Node: separator142435 +Ref: #separator142546 +Node: skip143086 +Ref: #skip143192 +Node: date-format143736 +Ref: #date-format143855 +Node: timezone144579 +Ref: #timezone144700 +Node: newest-first145705 +Ref: #newest-first145841 +Node: intra-day-reversed146418 +Ref: #intra-day-reversed146570 +Node: decimal-mark147018 +Ref: #decimal-mark147157 +Node: fields list147496 +Ref: #fields-list147633 +Node: Field assignment149304 +Ref: #field-assignment149446 +Node: Field names150523 +Ref: #field-names150652 +Node: date field151855 +Ref: #date-field151971 +Node: date2 field152019 +Ref: #date2-field152158 +Node: status field152214 +Ref: #status-field152355 +Node: code field152404 +Ref: #code-field152547 +Node: description field152592 +Ref: #description-field152750 +Node: comment field152809 +Ref: #comment-field152962 +Node: account field153255 +Ref: #account-field153403 +Node: amount field153973 +Ref: #amount-field154120 +Node: currency field156812 +Ref: #currency-field156963 +Node: balance field157220 +Ref: #balance-field157350 +Node: if block157743 +Ref: #if-block157862 +Node: Matchers159270 +Ref: #matchers159382 +Node: What matchers match160179 +Ref: #what-matchers-match160326 +Node: Combining matchers160766 +Ref: #combining-matchers160932 +Node: Match groups161469 +Ref: #match-groups161595 +Node: if table162363 +Ref: #if-table162483 +Node: balance-type164364 +Ref: #balance-type164491 +Node: include165191 +Ref: #include165316 +Node: Working with CSV165760 +Ref: #working-with-csv165905 +Node: Rapid feedback166312 +Ref: #rapid-feedback166443 +Node: Valid CSV166895 +Ref: #valid-csv167039 +Node: File Extension167771 +Ref: #file-extension167942 +Node: Reading CSV from standard input168506 +Ref: #reading-csv-from-standard-input168728 +Node: Reading multiple CSV files168892 +Ref: #reading-multiple-csv-files169121 +Node: Reading files specified by rule169368 +Ref: #reading-files-specified-by-rule169594 +Node: Valid transactions170765 +Ref: #valid-transactions170962 +Node: Deduplicating importing171590 +Ref: #deduplicating-importing171783 +Node: Setting amounts172819 +Ref: #setting-amounts172988 +Node: Amount signs175346 +Ref: #amount-signs175514 +Node: Setting currency/commodity176411 +Ref: #setting-currencycommodity176613 +Node: Amount decimal places177787 +Ref: #amount-decimal-places177991 +Node: Referencing other fields179044 +Ref: #referencing-other-fields179255 +Node: How CSV rules are evaluated180152 +Ref: #how-csv-rules-are-evaluated180367 +Node: Well factored rules181820 +Ref: #well-factored-rules181986 +Node: CSV rules examples182310 +Ref: #csv-rules-examples182443 +Node: Bank of Ireland182508 +Ref: #bank-of-ireland182643 +Node: Coinbase184105 +Ref: #coinbase184241 +Node: Amazon185288 +Ref: #amazon185411 +Node: Paypal187130 +Ref: #paypal187236 +Node: Timeclock194880 +Ref: #timeclock194985 +Node: Timedot197161 +Ref: #timedot197284 +Node: Timedot examples200405 +Ref: #timedot-examples200511 +Node: PART 3 REPORTING CONCEPTS202682 +Ref: #part-3-reporting-concepts202846 +Node: Time periods202846 +Ref: #time-periods202980 +Node: Report start & end date203098 +Ref: #report-start-end-date203250 +Node: Smart dates204574 +Ref: #smart-dates204727 +Node: Report intervals206517 +Ref: #report-intervals206672 +Node: Date adjustment207090 +Ref: #date-adjustment207250 +Node: Period expressions208101 +Ref: #period-expressions208242 +Node: Period expressions with a report interval210006 +Ref: #period-expressions-with-a-report-interval210240 +Node: More complex report intervals210454 +Ref: #more-complex-report-intervals210699 +Node: Multiple weekday intervals212560 +Ref: #multiple-weekday-intervals212749 +Node: Depth213571 +Ref: #depth213673 +Node: Queries213969 +Ref: #queries214071 +Node: Query types215667 +Ref: #query-types215788 +Node: Combining query terms219022 +Ref: #combining-query-terms219199 +Node: Queries and command options220762 +Ref: #queries-and-command-options220967 +Node: Queries and account aliases221216 +Ref: #queries-and-account-aliases221421 +Node: Queries and valuation221541 +Ref: #queries-and-valuation221698 +Node: Pivoting221903 +Ref: #pivoting222017 +Node: Generating data223794 +Ref: #generating-data223926 +Node: Forecasting225594 +Ref: #forecasting225719 +Node: --forecast226250 +Ref: #forecast226381 +Node: Inspecting forecast transactions227351 +Ref: #inspecting-forecast-transactions227553 +Node: Forecast reports228683 +Ref: #forecast-reports228856 +Node: Forecast tags229792 +Ref: #forecast-tags229952 +Node: Forecast period in detail230412 +Ref: #forecast-period-in-detail230606 +Node: Forecast troubleshooting231500 +Ref: #forecast-troubleshooting231668 +Node: Budgeting232571 +Ref: #budgeting232694 +Node: Amount formatting233131 +Ref: #amount-formatting233273 +Node: Commodity display style233375 +Ref: #commodity-display-style233529 +Node: Rounding235216 +Ref: #rounding235371 +Node: Trailing decimal marks235821 +Ref: #trailing-decimal-marks236000 +Node: Amount parseability236754 +Ref: #amount-parseability236910 +Node: Cost reporting238335 +Ref: #cost-reporting238477 +Node: Recording costs239138 +Ref: #recording-costs239274 +Node: Reporting at cost240865 +Ref: #reporting-at-cost241040 +Node: Equity conversion postings241630 +Ref: #equity-conversion-postings241844 +Node: Inferring equity conversion postings244275 +Ref: #inferring-equity-conversion-postings244538 +Node: Combining costs and equity conversion postings245290 +Ref: #combining-costs-and-equity-conversion-postings245600 +Node: Requirements for detecting equity conversion postings246515 +Ref: #requirements-for-detecting-equity-conversion-postings246837 +Node: Infer cost and equity by default ?248037 +Ref: #infer-cost-and-equity-by-default248266 +Node: Value reporting248474 +Ref: #value-reporting248616 +Node: -V Value249355 +Ref: #v-value249487 +Node: -X Value in specified commodity249682 +Ref: #x-value-in-specified-commodity249883 +Node: Valuation date250032 +Ref: #valuation-date250209 +Node: Finding market price250992 +Ref: #finding-market-price251203 +Node: --infer-market-prices market prices from transactions252372 +Ref: #infer-market-prices-market-prices-from-transactions252654 +Node: Valuation commodity255416 +Ref: #valuation-commodity255636 +Node: --value Flexible valuation256849 +Ref: #value-flexible-valuation257048 +Node: Valuation examples258692 +Ref: #valuation-examples258892 +Node: Interaction of valuation and queries260824 +Ref: #interaction-of-valuation-and-queries261064 +Node: Effect of valuation on reports261541 +Ref: #effect-of-valuation-on-reports261744 +Node: PART 4 COMMANDS269439 +Ref: #part-4-commands269582 +Node: Help commands271655 +Ref: #help-commands271800 +Node: help271828 +Ref: #help271917 +Node: demo273505 +Ref: #demo273594 +Node: User interface commands274638 +Ref: #user-interface-commands274807 +Node: ui274832 +Ref: #ui274924 +Node: web274957 +Ref: #web275051 +Node: Data entry commands275085 +Ref: #data-entry-commands275254 +Node: add275283 +Ref: #add275377 +Node: import277838 +Ref: #import277938 +Node: Date skipping279099 +Ref: #date-skipping279222 +Node: Import testing282000 +Ref: #import-testing282163 +Node: Importing balance assignments283006 +Ref: #importing-balance-assignments283213 +Node: Import and commodity styles283862 +Ref: #import-and-commodity-styles284042 +Node: Basic report commands284271 +Ref: #basic-report-commands284445 +Node: accounts284572 +Ref: #accounts284682 +Node: codes287445 +Ref: #codes287569 +Node: commodities288467 +Ref: #commodities288607 +Node: descriptions288711 +Ref: #descriptions288853 +Node: files289178 +Ref: #files289300 +Node: notes289475 +Ref: #notes289591 +Node: payees289987 +Ref: #payees290106 +Node: prices290771 +Ref: #prices290890 +Node: stats291663 +Ref: #stats291778 +Node: tags293404 +Ref: #tags-1293504 +Node: Standard report commands294711 +Ref: #standard-report-commands294896 +Node: print295016 +Ref: #print295124 +Node: print explicitness297462 +Ref: #print-explicitness297603 +Node: print amount style298382 +Ref: #print-amount-style298550 +Node: print parseability299620 +Ref: #print-parseability299790 +Node: print other features300539 +Ref: #print-other-features300716 +Node: print output format301237 +Ref: #print-output-format301383 +Node: aregister304522 +Ref: #aregister304655 +Node: aregister and posting dates308302 +Ref: #aregister-and-posting-dates308447 +Node: register309203 +Ref: #register309341 +Node: Custom register output315506 +Ref: #custom-register-output315635 +Node: balancesheet316982 +Ref: #balancesheet317137 +Node: balancesheetequity321618 +Ref: #balancesheetequity321785 +Node: cashflow326624 +Ref: #cashflow326774 +Node: incomestatement331052 +Ref: #incomestatement331189 +Node: Advanced report commands335516 +Ref: #advanced-report-commands335694 +Node: balance335724 +Ref: #balance335832 +Node: balance features340607 +Ref: #balance-features340747 +Node: Simple balance report342657 +Ref: #simple-balance-report342842 +Node: Balance report line format344467 +Ref: #balance-report-line-format344669 +Node: Filtered balance report346827 +Ref: #filtered-balance-report347019 +Node: List or tree mode347346 +Ref: #list-or-tree-mode347514 +Node: Depth limiting348859 +Ref: #depth-limiting349025 +Node: Dropping top-level accounts349626 +Ref: #dropping-top-level-accounts349826 +Node: Showing declared accounts350136 +Ref: #showing-declared-accounts350335 +Node: Sorting by amount350866 +Ref: #sorting-by-amount351033 +Node: Percentages351703 +Ref: #percentages351862 +Node: Multi-period balance report352410 +Ref: #multi-period-balance-report352610 +Node: Balance change end balance355162 +Ref: #balance-change-end-balance355371 +Node: Balance report types356799 +Ref: #balance-report-types356980 +Node: Calculation type357478 +Ref: #calculation-type357633 +Node: Accumulation type358182 +Ref: #accumulation-type358362 +Node: Valuation type359283 +Ref: #valuation-type359471 +Node: Combining balance report types360472 +Ref: #combining-balance-report-types360666 +Node: Budget report362504 +Ref: #budget-report362666 +Node: Using the budget report364809 +Ref: #using-the-budget-report364982 +Node: Budget date surprises367085 +Ref: #budget-date-surprises367285 +Node: Selecting budget goals368449 +Ref: #selecting-budget-goals368652 +Node: Budgeting vs forecasting369397 +Ref: #budgeting-vs-forecasting369574 +Node: Balance report layout371074 +Ref: #balance-report-layout371259 +Node: Wide layout372212 +Ref: #wide-layout372347 +Node: Tall layout374617 +Ref: #tall-layout374772 +Node: Bare layout375923 +Ref: #bare-layout376078 +Node: Tidy layout377987 +Ref: #tidy-layout378122 +Node: Some useful balance reports379531 +Ref: #some-useful-balance-reports379706 +Node: roi380791 +Ref: #roi380891 +Node: Spaces and special characters in --inv and --pnl383038 +Ref: #spaces-and-special-characters-in---inv-and---pnl383276 +Node: Semantics of --inv and --pnl383764 +Ref: #semantics-of---inv-and---pnl384001 +Node: IRR and TWR explained385851 +Ref: #irr-and-twr-explained386009 +Node: Chart commands389262 +Ref: #chart-commands389420 +Node: activity389443 +Ref: #activity389532 +Node: Data generation commands389940 +Ref: #data-generation-commands390114 +Node: close390146 +Ref: #close390252 +Node: close --migrate392738 +Ref: #close---migrate392863 +Node: close --close394502 +Ref: #close---close394644 +Node: close --open394880 +Ref: #close---open395019 +Node: close --assert395129 +Ref: #close---assert395273 +Node: close --assign395494 +Ref: #close---assign395640 +Node: close --retain396166 +Ref: #close---retain396317 +Node: close customisation397062 +Ref: #close-customisation397239 +Node: close and balance assertions398706 +Ref: #close-and-balance-assertions398901 +Node: close examples400228 +Ref: #close-examples400367 +Node: Retain earnings400465 +Ref: #retain-earnings400622 +Node: Migrate balances to a new file400968 +Ref: #migrate-balances-to-a-new-file401192 +Node: More detailed close examples402320 +Ref: #more-detailed-close-examples402516 +Node: rewrite402542 +Ref: #rewrite402652 +Node: Re-write rules in a file405114 +Ref: #re-write-rules-in-a-file405275 +Node: Diff output format406424 +Ref: #diff-output-format406605 +Node: rewrite vs print --auto407697 +Ref: #rewrite-vs.-print---auto407855 +Node: Maintenance commands408411 +Ref: #maintenance-commands408582 +Node: check408620 +Ref: #check408719 +Node: Basic checks409702 +Ref: #basic-checks409820 +Node: Strict checks410655 +Ref: #strict-checks410796 +Node: Other checks411530 +Ref: #other-checks411670 +Node: Custom checks413385 +Ref: #custom-checks413505 +Node: diff413840 +Ref: #diff413950 +Node: test415047 +Ref: #test415143 +Node: PART 5 COMMON TASKS415919 +Ref: #part-5-common-tasks416078 +Node: Getting help416152 +Ref: #getting-help416301 +Node: Constructing command lines417061 +Ref: #constructing-command-lines417242 +Node: Starting a journal file417899 +Ref: #starting-a-journal-file418081 +Node: Setting LEDGER_FILE419283 +Ref: #setting-ledger_file419455 +Node: Setting opening balances420412 +Ref: #setting-opening-balances420593 +Node: Recording transactions423734 +Ref: #recording-transactions423903 +Node: Reconciling424459 +Ref: #reconciling424591 +Node: Reporting426848 +Ref: #reporting426977 +Node: Migrating to a new file430962 +Ref: #migrating-to-a-new-file431112 +Node: BUGS431411 +Ref: #bugs431505 +Node: Troubleshooting432384 +Ref: #troubleshooting432484  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index e89c98fb7..7cd2ccfac 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -26,9 +26,11 @@ DESCRIPTION use hledger productively, but when you have a question about function- ality, this doc should answer it. It is detailed, so do skip ahead or skim when needed. You can read it on hledger.org, or as an info manual - or man page on your system. You can also get it from hledger itself - with - hledger --man, hledger --info or hledger help [TOPIC]. + or man page on your system. You can also open a built-in copy, at a + point of interest, by running + hledger --man [CMD], hledger --info [CMD] or hledger help [TOPIC]. + + (And for shorter help, try hledger --tldr [CMD].) The main function of the hledger CLI is to read plain text files de- scribing financial transactions, crunch the numbers, and print a useful @@ -241,17 +243,26 @@ Commands hledger-ui --watch or hledger-web --serve. Options - Run hledger -h to see general command line help. The following general - options are common to most hledger commands. General options can be - written either before or after the command name. + Run hledger -h to see general command line help. Options can be writ- + ten either before or after the command name. These options are spe- + cific to the hledger CLI: + + Flags: + --conf=CONFFILE Use extra options defined in this config file. If + not specified, searches upward and in XDG config + dir for hledger.conf (or .hledger.conf in $HOME). + -n --no-conf ignore any config file + + And the following general options are common to most hledger commands: General input/data transformation flags: - -f --file=FILE Read data from FILE, or from stdin if -. Can be - specified more than once. If not specified, reads - from $LEDGER_FILE or $HOME/.hledger.journal. - --rules-file=RULEFILE Use conversion rules from this file for + -f --file=[FMT:]FILE Read data from FILE, or from stdin if FILE is -, + inferring format from extension or a FMT: prefix. + Can be specified more than once. If not specified, + reads from $LEDGER_FILE or $HOME/.hledger.journal. + --rules=RULESFILE Use rules defined in this rules file for converting subsequent CSV/SSV/TSV files. If not - specified, uses FILE.rules for each such FILE. + specified, uses FILE.csv.rules for each FILE.csv. --alias=A=B|/RGX/=RPL transform account names from A to B, or by replacing regular expression matches --auto generate extra postings by applying auto posting @@ -314,7 +325,6 @@ Options --pretty[=YN] Use box-drawing characters in text output? Can be 'y'/'yes' or 'n'/'no'. If YN is specified, the equals is required. - --debug=[1-9] show this level of debug output (default: 1) General help flags: -h --help show command line help @@ -322,15 +332,16 @@ Options --info show the manual with info --man show the manual with man --version show version information + --debug=[1-9] show this level of debug output (default: 1) - Usually hledger accepts any unambiguous flag prefix, eg you can write + Usually hledger accepts any unambiguous flag prefix, eg you can write --tl instead of --tldr or --dry instead of --dry-run. - If the same option appears more than once in a command, usually the + If the same option appears more than once in a command, usually the last (right-most) wins. - With most commands, arguments are interpreted as a hledger query which - filter the data. Some queries can be expressed either with options or + With most commands, arguments are interpreted as a hledger query which + filter the data. Some queries can be expressed either with options or with arguments. Below are more tips for using the command line interface - feel free to @@ -338,10 +349,10 @@ Options Special characters Single escaping (shell metacharacters) - In shell command lines, characters significant to your shell - such as - spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want - hledger to see them. This is done by enclosing them in single or dou- - ble quotes, or by writing a backslash before them. Eg to match an ac- + In shell command lines, characters significant to your shell - such as + spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want + hledger to see them. This is done by enclosing them in single or dou- + ble quotes, or by writing a backslash before them. Eg to match an ac- count name containing a space: $ hledger register 'credit card' @@ -350,17 +361,17 @@ Options $ hledger register credit\ card - Windows users should keep in mind that cmd treats single quote as a - regular character, so you should be using double quotes exclusively. + Windows users should keep in mind that cmd treats single quote as a + regular character, so you should be using double quotes exclusively. PowerShell treats both single and double quotes as quotes. Double escaping (regular expression metacharacters) - Characters significant in regular expressions (described below) - such - as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if - you don't want them to be interpreted by hledger's regular expression - engine. This is done by writing backslashes before them, but since - backslash is typically also a shell metacharacter, both shell-escaping - and regex-escaping will be needed. Eg to match a literal $ sign while + Characters significant in regular expressions (described below) - such + as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if + you don't want them to be interpreted by hledger's regular expression + engine. This is done by writing backslashes before them, but since + backslash is typically also a shell metacharacter, both shell-escaping + and regex-escaping will be needed. Eg to match a literal $ sign while using the bash shell: $ hledger balance cur:'\$' @@ -370,10 +381,10 @@ Options $ hledger balance cur:\\$ Triple escaping (for add-on commands) - When you use hledger to run an external add-on command (described be- + When you use hledger to run an external add-on command (described be- low), one level of shell-escaping is lost from any options or arguments - intended for by the add-on command, so those need an extra level of - shell-escaping. Eg to match a literal $ sign while using the bash + intended for by the add-on command, so those need an extra level of + shell-escaping. Eg to match a literal $ sign while using the bash shell and running an add-on command (ui): $ hledger ui cur:'\\$' @@ -389,14 +400,14 @@ Options double-escaped: \\$ triple-escaped: \\\\$ - Or, you can avoid the extra escaping by running the add-on executable + Or, you can avoid the extra escaping by running the add-on executable directly: $ hledger-ui cur:\\$ Less escaping Options and arguments are sometimes used in places other than the shell - command line, where shell-escaping is not needed, so there you should + command line, where shell-escaping is not needed, so there you should use one less level of escaping. Those places include: o an @argumentfile @@ -410,8 +421,8 @@ Options Unicode characters hledger is expected to handle non-ascii characters correctly: - o they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web's search/add/edit + o they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web's search/add/edit forms, etc.) o they should be displayed correctly by all hledger tools, and @@ -419,40 +430,40 @@ Options This requires a well-configured environment. Here are some tips: - o A system locale must be configured, and it must be one that can de- - code the characters being used. In bash, you can set a locale like - this: export LANG=en_US.UTF-8. There are some more details in Trou- - bleshooting. This step is essential - without it, hledger will quit - on encountering a non-ascii character (as with all GHC-compiled pro- + o A system locale must be configured, and it must be one that can de- + code the characters being used. In bash, you can set a locale like + this: export LANG=en_US.UTF-8. There are some more details in Trou- + bleshooting. This step is essential - without it, hledger will quit + on encountering a non-ascii character (as with all GHC-compiled pro- grams). - o Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + o Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) must support unicode. On Windows, you may need to use Windows Termi- nal and/or enable UTF-8 support. o The terminal must be using a font which includes the required unicode glyphs. - o The terminal should be configured to display wide characters as dou- + o The terminal should be configured to display wide characters as dou- ble width (for report alignment). - o On Windows, for best results you should run hledger in the same kind - of environment in which it was built. Eg hledger built in the stan- - dard CMD.EXE environment (like the binaries on our download page) - might show display problems when run in a cygwin or msys terminal, + o On Windows, for best results you should run hledger in the same kind + of environment in which it was built. Eg hledger built in the stan- + dard CMD.EXE environment (like the binaries on our download page) + might show display problems when run in a cygwin or msys terminal, and vice versa. (See eg #961). Regular expressions - A regular expression (regexp) is a small piece of text where certain - characters (like ., ^, $, +, *, (), |, [], \) have special meanings, - forming a tiny language for matching text precisely - very useful in - hledger and elsewhere. To learn all about them, visit regular-expres- + A regular expression (regexp) is a small piece of text where certain + characters (like ., ^, $, +, *, (), |, [], \) have special meanings, + forming a tiny language for matching text precisely - very useful in + hledger and elsewhere. To learn all about them, visit regular-expres- sions.info. - hledger supports regexps whenever you are entering a pattern to match - something, eg in query arguments, account aliases, CSV if rules, + hledger supports regexps whenever you are entering a pattern to match + something, eg in query arguments, account aliases, CSV if rules, hledger-web's search form, hledger-ui's / search, etc. You may need to - wrap them in quotes, especially at the command line (see Special char- + wrap them in quotes, especially at the command line (see Special char- acters above). Here are some examples: Account name queries (quoted for command line use): @@ -508,51 +519,77 @@ Options & %date (29|30|31|01|02|03)$ hledger's regular expressions - hledger's regular expressions come from the regex-tdfa library. If - they're not doing what you expect, it's important to know exactly what + hledger's regular expressions come from the regex-tdfa library. If + they're not doing what you expect, it's important to know exactly what they support: 1. they are case insensitive - 2. they are infix matching (they do not need to match the entire thing + 2. they are infix matching (they do not need to match the entire thing being matched) 3. they are POSIX ERE (extended regular expressions) 4. they also support GNU word boundaries (\b, \B, \<, \>) - 5. backreferences are supported when doing text replacement in account - aliases or CSV rules, where backreferences can be used in the re- + 5. backreferences are supported when doing text replacement in account + aliases or CSV rules, where backreferences can be used in the re- placement string to reference capturing groups in the search regexp. Otherwise, if you write \1, it will match the digit 1. - 6. they do not support mode modifiers ((?s)), character classes (\w, + 6. they do not support mode modifiers ((?s)), character classes (\w, \d), or anything else not mentioned above. Some things to note: - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required. - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts with the dollar sign in hledger-web, write cur:\$. - o On the command line, some metacharacters like $ have a special mean- + o On the command line, some metacharacters like $ have a special mean- ing to the shell and so must be escaped at least once more. See Spe- cial characters. Argument files You can save a set of command line options and arguments in a file, and - then reuse them by writing @FILENAME as a command line argument. Eg: + then reuse them by writing @FILENAME as a command line argument. Eg: hledger bal @foo.args. - Inside the argument file, each line should contain just one option or - argument. Don't use spaces except inside quotes (or you'll see a con- - fusing error); write = (or nothing) between a flag and its argument. - For the special characters mentioned above, use one less level of quot- - ing than you would at the command prompt. + (Inside the argument file, each line should contain just one option or + argument. Don't use spaces except inside quotes; write = or nothing + between a flag and its argument. For the special characters mentioned + above, use one less level of quoting than you would at the command + prompt.) + + Argument files are now superseded by.. + + Config files + hledger looks for a hledger.conf file (or .hledger.conf in your home + directory) in the current directory, then parent directories, then your + XDG config directory (~/.config/hledger/). Any command line options + (or arguments) in this file will be added to your hledger commands, + near the start of the command line (so you can override them when + needed). + + Or you can specify a config file with the --conf option. Or you can + add a hledger --conf shebang line to a config file and make it exe- + cutable. + + A hledger config file contains command line options, to be used with + all commands that support them, and optionally command-specific options + in named sections. hledger.conf.sample is a sample demonstrating the + syntax; you can install it as ./hledger.conf or $HOME/.hledger.conf and + customise it. + + You can disable config files entirely by running with the -n/--no-conf + flag. This will ensure hledger runs with standard defaults, useful + when troubleshooting or when sharing examples with others. + + (Added in 1.40; experimental) Output Output destination @@ -681,13 +718,12 @@ Output ports it. Box-drawing - In terminal output, you can enable unicode box-drawing characters to - render prettier tables: + In terminal (text) output, to minimise the risk of display problems, + table borders are drawn using only ascii characters by default. - o if the --pretty option is given a value of yes or always (or no or - never), unicode characters will (or will not) be used; - - o otherwise, unicode characters will not be used. + To see tables with prettier unicode box-drawing characters, add the + --pretty flag. This will also show outer borders and inter-column bor- + ders. Paging When showing long output in the terminal, hledger will try to use the @@ -2879,7 +2915,7 @@ CSV By default, hledger expects this rules file to be named like the CSV file, with an extra .rules extension added, in the same directory. Eg when asked to read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. - You can specify a different rules file with the --rules-file option. + You can specify a different rules file with the --rules option. At minimum, the rules file must identify the date and amount fields, and often it also specifies the date format and how many header lines @@ -3573,8 +3609,8 @@ CSV Reading multiple CSV files If you use multiple -f options to read multiple CSV files at once, hledger will look for a correspondingly-named rules file for each CSV - file. But if you use the --rules-file option, that rules file will be - used for all the CSV files. + file. But if you specify a rules file with --rules, that rules file + will be used for all the CSV files. Reading files specified by rule Instead of specifying a CSV file in the command line, you can specify a @@ -6039,10 +6075,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- @@ -8279,11 +8315,11 @@ Advanced report commands "Assets:US:ETrade","USD","5120.50" "Assets:US:ETrade","VEA","36.00" "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" + "Total:","GLD","70.00" + "Total:","ITOT","17.00" + "Total:","USD","5120.50" + "Total:","VEA","36.00" + "Total:","VHT","294.00" Bare layout will sometimes display an extra row for the no-symbol com- modity, because of zero amounts (hledger treats zeroes as commod-