simonmichael/hledger
1
1
Fork 0
mirror of https://github.com/simonmichael/hledger.git synced 2024-10-06 10:57:30 +03:00
Code Issues Projects Releases Wiki Activity

doc: update manuals

Browse Source
This commit is contained in:
Simon Michael 2024-06-25 08:54:18 +01:00
parent d9f314dfa3
commit 5f285a56ab
9 changed files with 1042 additions and 914 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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

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

@ -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

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

@ -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.

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

@ -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

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

@ -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

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

@ -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-

109
hledger/hledger.1
View File

@ -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

1469
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

212
hledger/hledger.txt
View File

@ -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-