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

;doc: update embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2025-08-24 09:01:04 +01:00
parent 4c1c44ce36
commit 4f4426dc24
9 changed files with 1545 additions and 1266 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -15,7 +15,7 @@ or
.PD 0
.P
.PD
\f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R]
\f[CR]hledger ui [OPTS] [QUERYARGS]\f[R]
.SH DESCRIPTION
This manual is for hledger\[aq]s terminal interface, version 1.43.99.
See also the hledger manual for common concepts and file formats.

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

@ -16,7 +16,7 @@ plain text accounting app.
'hledger-ui [OPTS] [QUERYARGS]'
or
'hledger ui -- [OPTS] [QUERYARGS]'
'hledger ui [OPTS] [QUERYARGS]'
This manual is for hledger's terminal interface, version 1.43.99.
See also the hledger manual for common concepts and file formats.
@ -565,22 +565,22 @@ with the UI unresponsive.

Tag Table:
Node: Top221
Node: OPTIONS1872
Node: MOUSE8758
Node: KEYS9090
Node: SCREENS14094
Node: Menu screen14834
Node: Cash accounts screen15150
Node: Balance sheet accounts screen15511
Node: Income statement accounts screen15847
Node: All accounts screen16232
Node: Register screen16595
Node: Transaction screen19038
Node: Error screen20613
Node: WATCH MODE20979
Node: --watch problems21877
Node: ENVIRONMENT23230
Node: BUGS23463
Node: OPTIONS1869
Node: MOUSE8755
Node: KEYS9087
Node: SCREENS14091
Node: Menu screen14831
Node: Cash accounts screen15147
Node: Balance sheet accounts screen15508
Node: Income statement accounts screen15844
Node: All accounts screen16229
Node: Register screen16592
Node: Transaction screen19035
Node: Error screen20610
Node: WATCH MODE20976
Node: --watch problems21874
Node: ENVIRONMENT23227
Node: BUGS23460

End Tag Table

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

@ -8,7 +8,7 @@ NAME
SYNOPSIS
hledger-ui [OPTS] [QUERYARGS]
or
hledger ui -- [OPTS] [QUERYARGS]
hledger ui [OPTS] [QUERYARGS]
DESCRIPTION
This manual is for hledger's terminal interface, version 1.43.99. See

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

@ -15,7 +15,7 @@ or
.PD 0
.P
.PD
\f[CR]hledger web \-\- [OPTS] [QUERY]\f[R]
\f[CR]hledger web [OPTS] [QUERY]\f[R]
.SH DESCRIPTION
This manual is for hledger\[aq]s web interface, version 1.43.99.
See also the hledger manual for common concepts and file formats.
@ -84,7 +84,7 @@ Flags:
\-\-base\-url=BASEURL set the base url (default: http://IPADDR:PORT)
\-\-test run hledger\-web\[aq]s tests and exit. hspec test
runner args may follow a \-\-, eg: hledger\-web \-\-test
\-\- \-\-help
\-\-help
.EE
.PP
By default hledger\-web listens only on IP address \f[CR]127.0.0.1\f[R],

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

@ -16,7 +16,7 @@ plain text accounting app.
'hledger-web [OPTS] [QUERY]'
or
'hledger web -- [OPTS] [QUERY]'
'hledger web [OPTS] [QUERY]'
This manual is for hledger's web interface, version 1.43.99. See
also the hledger manual for common concepts and file formats.
@ -96,7 +96,7 @@ Flags:
--base-url=BASEURL set the base url (default: http://IPADDR:PORT)
--test run hledger-web's tests and exit. hspec test
runner args may follow a --, eg: hledger-web --test
-- --help
--help
By default hledger-web listens only on IP address '127.0.0.1', which
be accessed only from the local machine.
@ -528,15 +528,15 @@ We welcome bug reports in the hledger issue tracker

Tag Table:
Node: Top223
Node: OPTIONS2581
Node: PERMISSIONS11482
Node: EDITING UPLOADING DOWNLOADING12632
Node: RELOADING13647
Node: JSON API14214
Node: DEBUG OUTPUT19863
Node: Debug output20015
Node: ENVIRONMENT20533
Node: BUGS20769
Node: OPTIONS2578
Node: PERMISSIONS11476
Node: EDITING UPLOADING DOWNLOADING12626
Node: RELOADING13641
Node: JSON API14208
Node: DEBUG OUTPUT19857
Node: Debug output20009
Node: ENVIRONMENT20527
Node: BUGS20763

End Tag Table

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

@ -8,7 +8,7 @@ NAME
SYNOPSIS
hledger-web [OPTS] [QUERY]
or
hledger web -- [OPTS] [QUERY]
hledger web [OPTS] [QUERY]
DESCRIPTION
This manual is for hledger's web interface, version 1.43.99. See also
@ -73,7 +73,7 @@ OPTIONS
--base-url=BASEURL set the base url (default: http://IPADDR:PORT)
--test run hledger-web's tests and exit. hspec test
runner args may follow a --, eg: hledger-web --test
-- --help
--help
By default hledger-web listens only on IP address 127.0.0.1, which be
accessed only from the local machine.

313
hledger/hledger.1
View File

@ -20,11 +20,6 @@ or
.PD 0
.P
.PD
or
.PD 0
.P
.PD
\f[CR]hledger ADDONCMD [OPTS] \-\- [ADDONOPTS] [ADDONARGS]\f[R]
.SH DESCRIPTION
hledger is a robust, user\-friendly, cross\-platform set of programs for
tracking money, time, or any other commodity, using double\-entry
@ -283,7 +278,7 @@ Are all commodities declared with a \f[CR]commodity\f[R] directive ?
.IP \[bu] 2
Are all commodity conversions declared explicitly ?
.PP
You can use the check command to run individual checks \-\- the ones
You can use the check command to run individual checks \- the ones
listed above and some more.
.SH Commands
hledger provides various subcommands for getting things done.
@ -318,31 +313,27 @@ terminal, run \f[CR]hledger CMD \-h\f[R].
Eg: \f[CR]hledger bal \-h\f[R].
.SS Add\-on commands
In addition to the built\-in commands, you can install \f[I]add\-on
commands\f[R]: programs or scripts named \[dq]hledger\-SOMETHING\[dq],
which will also appear in hledger\[aq]s commands list.
If you used the hledger\-install script, you will have several add\-ons
installed already.
Some more can be found in hledger\[aq]s bin/ directory, documented at
commands\f[R], which will also appear in hledger\[aq]s commands list.
Some of these can be installed as separate packages; others can be found
in hledger\[aq]s bin/ directory, documented at
https://hledger.org/scripts.html.
.PP
More precisely, add\-on commands are programs or scripts in your
shell\[aq]s PATH, whose name starts with \[dq]hledger\-\[dq] and ends
with no extension or a recognised extension (\[dq].bat\[dq],
\[dq].com\[dq], \[dq].exe\[dq], \[dq].hs\[dq], \[dq].js\[dq],
\[dq].lhs\[dq], \[dq].lua\[dq], \[dq].php\[dq], \[dq].pl\[dq],
\[dq].py\[dq], \[dq].rb\[dq], \[dq].rkt\[dq], or \[dq].sh\[dq]), and (on
unix and mac) which has executable permission for the current user.
Add\-on commands are programs or scripts in your shell\[aq]s PATH, whose
name starts with \[dq]hledger\-\[dq] and ends with no extension or a
recognised extension (\[dq].bat\[dq], \[dq].com\[dq], \[dq].exe\[dq],
\[dq].hs\[dq], \[dq].js\[dq], \[dq].lhs\[dq], \[dq].lua\[dq],
\[dq].php\[dq], \[dq].pl\[dq], \[dq].py\[dq], \[dq].rb\[dq],
\[dq].rkt\[dq], or \[dq].sh\[dq]), and (on unix and mac) which has
executable permission for the current user.
.PP
You can run add\-on commands using hledger, much like built\-in
commands:
\f[CR]hledger ADDONCMD [\-\- ADDONCMDOPTS] [ADDONCMDARGS]\f[R].
But note the double hyphen argument, required before add\-on\-specific
options.
Eg: \f[CR]hledger ui \-\- \-\-watch\f[R] or
\f[CR]hledger web \-\- \-\-serve\f[R].
If this causes difficulty, you can always run the add\-on directly,
without using \f[CR]hledger\f[R]: \f[CR]hledger\-ui \-\-watch\f[R] or
\f[CR]hledger\-web \-\-serve\f[R].
You can run add\-on commands directly: \f[CR]hledger\-ui \-\-watch\f[R].
.PP
Or you can run them with hledger, like built\-in commands:
\f[CR]hledger ui \-\-watch\f[R].
In this case hledger\[aq]s config file will be used, so you can set
custom options for the addon there.
(Before hledger 1.50, an \f[CR]\-\-\f[R] argument was needed before
addon options, but not any more.)
.SH Options
Run \f[CR]hledger \-h\f[R] to see general command line help.
Options can be written either before or after the command name.
@ -448,6 +439,11 @@ Usually hledger accepts any unambiguous flag prefix, eg you can write
\f[CR]\-\-tl\f[R] instead of \f[CR]\-\-tldr\f[R] or \f[CR]\-\-dry\f[R]
instead of \f[CR]\-\-dry\-run\f[R].
.PP
You can combine short flags which don\[aq]t take arguments, eg you can
write \f[CR]\-MAST\f[R] instead of \f[CR]\-M \-A \-S \-T\f[R].
Flags requiring an argument can\[aq]t be combined in this way
(\f[CR]\-If FILE\f[R] won\[aq]t work).
.PP
If the same option appears more than once in a command line, usually the
last (right\-most) wins.
Similarly, if mutually exclusive flags are used together, the
@ -911,8 +907,7 @@ the effect on all your reports.
To troubleshoot the effect of config files, run with
\f[CR]\-\-debug\f[R] or \f[CR]\-\-debug 8\f[R].
.PP
The config file feature was added in hledger 1.40 and is considered
\f[I]experimental\f[R].
The config file feature was added in hledger 1.40.
.SS Shell completions
If you use the bash or zsh shells, you can optionally set up
context\-sensitive autocompletion for hledger command lines.
@ -1184,7 +1179,7 @@ If you are using the \f[CR]less\f[R] pager, hledger automatically
appends a number of options to the \f[CR]LESS\f[R] variable to enable
ANSI colour and a number of other conveniences.
(At the time of writing: \-\-chop\-long\-lines \-\-hilite\-unread
\-\-ignore\-case \-\-mouse \-\-no\-init \-\-quit\-at\-eof
\-\-ignore\-case \-\-no\-init \-\-quit\-at\-eof
\-\-quit\-if\-one\-screen \-\-RAW\-CONTROL\-CHARS \-\-shift=8
\-\-squeeze\-blank\-lines \-\-use\-backslash ).
If these don\[aq]t work well, you can set your preferred options in the
@ -3312,29 +3307,57 @@ You can pull in the content of additional files by writing an include
directive, like this:
.IP
.EX
include FILEPATH
include SOMEFILE
.EE
.PP
Only journal files can include, and only journal, timeclock or timedot
files can be included (not CSV files, currently).
This has the same effect as if SOMEFILE\[aq]s content was inlined at
this point.
(With any include directives in SOMEFILE processed similarly,
recursively.)
.PP
If the file path does not begin with a slash, it is relative to the
current file\[aq]s folder.
Only journal files can include other files.
They can include journal, timeclock or timedot files, but not CSV files.
.PP
A tilde means home directory, eg: \f[CR]include \[ti]/main.journal\f[R].
If the file path begins with a tilde, that means your home directory:
\f[CR]include \[ti]/main.journal\f[R].
.PP
The path may contain glob patterns to match multiple files, eg:
\f[CR]include *.journal\f[R].
If it begins with a slash, it is an absolute path:
\f[CR]include /home/user/main.journal\f[R].
Otherwise it is relative to the including file\[aq]s folder:
\f[CR]include ../finances/main.journal\f[R].
.PP
There is limited support for recursive wildcards: \f[CR]**/\f[R] (the
slash is required) matches 0 or more subdirectories.
It\[aq]s not super convenient since you have to avoid include cycles and
including directories, but this can be done, eg:
\f[CR]include */**/*.journal\f[R].
Also, the path may have a file type prefix to force a specific file
format, overriding the file extension(s) (as described in Data formats):
\f[CR]include timedot:notes/2023.md\f[R].
.PP
The path may also be prefixed to force a specific file format,
overriding the file extension (as described in Data formats):
\f[CR]include timedot:\[ti]/notes/2023*.md\f[R].
The path may contain glob patterns to match multiple files.
hledger\[aq]s globs are similar to zsh\[aq]s: \f[CR]?\f[R] to match any
character; \f[CR][a\-z]\f[R] to match any character in a range;
\f[CR]*\f[R] to match zero or more characters that aren\[aq]t a path
separator (like \f[CR]/\f[R]); \f[CR]**\f[R] to match zero or more
subdirectories and/or zero or more characters at the start of a file
name; etc.
Also, hledger\[aq]s globs always exclude the including file itself.
So, you can do
.IP \[bu] 2
\f[CR]include *.journal\f[R] to include all other journal files in the
current directory (excluding dot files)
.IP \[bu] 2
\f[CR]include **.journal\f[R] to include all other journal files in this
directory and below (excluding dot directories/files)
.IP \[bu] 2
\f[CR]include timelogs/2???.timedot\f[R] to include all timedot files
named like a year number.
.PP
There is a limitation: hledger\[aq]s globs always exclude paths
involving dot files or dot directories.
This is a workaround for unavoidable dot directory traversal; you can
disable it and revert to older behaviour with the
\f[CR]\-\-old\-glob\f[R] flag, for now.
.PP
If you are using many, or deeply nested, include files, and have an
error that\[aq]s hard to pinpoint: a good troubleshooting command is
\f[CR]hledger files \-\-debug=6\f[R] (or 7).
.SS \f[CR]P\f[R] directive
The \f[CR]P\f[R] directive declares a market price, which is a
conversion rate between two commodities on a certain date.
@ -3542,6 +3565,9 @@ Note these generated postings are temporary, existing only for the
duration of the report, and only when \f[CR]\-\-auto\f[R] is used; they
are not saved in the journal file by hledger.
.PP
The postings can contain the special string \f[CR]%account\f[R] which
will be expanded to the account name of the matched account.
.PP
Generated postings\[aq] amounts can depend on the matched posting\[aq]s
amount.
So auto postings can be useful for, eg, adding tax postings with a
@ -4222,34 +4248,68 @@ will look for rules in \f[CR]foo.csv.rules\f[R].
Or, you can tell it to read the rules file, with
\f[CR]\-f foo.csv.rules\f[R], and it will look for data in
\f[CR]foo.csv\f[R] (since 1.30).
.PP
These are mostly equivalent, but the second method provides some extra
features.
For one, the data file can be missing, without causing an error; it is
just considered empty.
And, you can specify a different data file by adding a \[dq]source\[dq]
rule:
.PP
For more flexibility, add a \f[CR]source\f[R] rule, which lets you
specify a different data file:
.IP
.EX
source ./Checking1.csv
.EE
.PP
If the file does not exist, it is just considered empty, without raising
an error.
.PP
If you specify just a file name with no path, hledger will look for it
in your system\[aq]s downloads directory (\f[CR]\[ti]/Downloads\f[R],
currently):
in the \f[CR]\[ti]/Downloads\f[R] folder:
.IP
.EX
source Checking1.csv
.EE
.PP
And if you specify a glob pattern, hledger will read the most recent of
the matched files (useful with repeated downloads):
You can use a glob pattern, to avoid specifying the file name exactly:
.IP
.EX
source Checking1*.csv
.EE
.PP
This has another benefit: if the pattern matches multiple files, hledger
will read the newest (most recently modified) one.
This avoids problems if you have downloaded a file multiple times
without cleaning up.
.PP
All this enables a convenient workflow where can you just download CSV
files, then run \f[CR]hledger import rules/*\f[R].
.PP
See also \[dq]Working with CSV > Reading files specified by rule\[dq].
.PP
The \f[CR]archive\f[R] rule adds a few more features to
\f[CR]source\f[R]; see below.
.SS \f[CR]archive\f[R]
Adding the \f[CR]archive\f[R] rule to your rules file affects importing
or reading files specified by \f[CR]source\f[R]:
.IP \[bu] 2
After successfully importing, \f[CR]import\f[R] will move the data file
to an archive directory (\f[CR]data/\f[R] next to the rules file,
auto\-created), renamed to
\f[CR]RULESFILEBASENAME.DATAFILEMODDATE.DATAFILEEXT\f[R].
Archiving data files is optional, but it can be useful for
troubleshooting, detecting variations in your banks\[aq] CSV data,
regenerating entries with improved rules, etc.
.IP \[bu] 2
\f[CR]import\f[R] will pick the oldest of \f[CR]source\f[R] glob
matches, rather than the newest.
So if you have multiple versions of a download, repeated imports will
process them in chronological order.
.IP \[bu] 2
For commands other than \f[CR]import\f[R], when the \f[CR]source\f[R]
path or glob pattern matches no files, hledger will try to read the
latest archived data file instead.
This is convenient for working with the downloaded data again, even
after it has been imported.
.SS \f[CR]encoding\f[R]
.IP
.EX
@ -4366,6 +4426,9 @@ date\-format %Y\-%h\-%d
# Note the time and junk must be fully parsed, though only the date is used.
date\-format %\-m/%\-d/%Y %l:%M %p some other junk
.EE
.PP
Note currently there is no locale awareness for things like
\f[CR]%b\f[R], and setting LC_TIME won\[aq]t help.
.SS \f[CR]timezone\f[R]
.IP
.EX
@ -6110,12 +6173,13 @@ can optionally use \[dq]smart date\[dq] syntax.
Smart dates can be written with english words, can be relative, and can
have parts omitted.
Missing parts are inferred as 1, when needed.
Smart dates can be interpreted as dates or periods depending on context.
Smart dates can be interpreted as dates or periods depending on the
context.
.PP
Examples:
.PP
\f[CR]2004\-01\-01\f[R], \f[CR]2004/10/1\f[R], \f[CR]2004.9.1\f[R],
\f[CR]20240504\f[R] :
\f[CR]20240504\f[R], \f[CR]2024Q1\f[R] :
.PD 0
.P
.PD
@ -6123,10 +6187,17 @@ Exact dates.
The year must have at least four digits, the month must be 1\-12, the
day must be 1\-31, the separator can be \f[CR]\-\f[R] or \f[CR]/\f[R] or
\f[CR].\f[R] or nothing.
The q can be upper or lower case and the quarter number must be 1\-4.
.TP
\f[CR]2004\-10\f[R]
start of month
.TP
\f[CR]2004q3\f[R]
start of third quarter of 2004
.TP
\f[CR]q3\f[R]
start of third quarter of current year
.TP
\f[CR]2004\f[R]
start of year
.TP
@ -6226,7 +6297,7 @@ For example, if the journal\[aq]s last transaction is on february 20th,
of february.
.IP \[bu] 2
\f[CR]hledger register \-\-monthly \-\-end 2/14\f[R] also will end the
report at the end of february.
report at the end of february (overriding the requested end date).
.IP \[bu] 2
\f[CR]hledger register \-\-monthly \-\-begin 1/5 \-\-end 2/14\f[R] will
end the report on march 4th [1].
@ -6565,7 +6636,7 @@ accounts matching \f[CR]liabilities\f[R] to depth 3,
all other accounts to depth 1.
.PP
If an account is matched by more than one regular expression depth
argument then the more specific one will used.
argument then the more specific one will be used.
For example, if
\f[CR]\-\-depth assets=1 \-\-depth assets:bank:savings=2\f[R] is
provided, then \f[CR]assets:bank:savings\f[R] will be collapsed to depth
@ -6975,7 +7046,7 @@ amount to a cash account\[dq].
.PD
Like \f[CR]expr:\f[R], but when used with transaction\-oriented commands
like \f[CR]print\f[R], it matches the transaction only if all postings
are matched by all of QUERYEXPR.
are matched by all of QUERYEXPR (and there is at least one posting).
.PD 0
.P
.PD
@ -8041,8 +8112,8 @@ $ hledger \-f\- print \-\-value=end date:2000/01\-2000/03
(a) 2 B
.EE
.PP
With no report period specified, that shows the value as of the last day
of the journal (2000\-03\-01):
With no report period specified, the latest transaction date or price
date is used as valuation date (2000\-04\-01):
.IP
.EX
$ hledger \-f\- print \-\-value=end
@ -8056,8 +8127,7 @@ $ hledger \-f\- print \-\-value=end
(a) 3 B
.EE
.PP
Show the current value (the 2000\-04\-01 price is still in effect
today):
The value today is the same (the 2000\-04\-01 price is still in effect):
.IP
.EX
$ hledger \-f\- print \-\-value=now
@ -8580,10 +8650,6 @@ eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to
play at half speed.
The default speed is 2x.
.PP
Other asciinema options can be added following a double dash, eg
\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list
asciinema\[aq]s other options.
.PP
During playback, several keys are available: SPACE to pause/unpause, .
to step forward (while paused), CTRL\-c quit.
.PP
@ -8852,7 +8918,7 @@ Runs hledger\-ui (if installed).
Runs hledger\-web (if installed).
.SH Data entry commands
.SS add
Record new transactions with interactive prompting in the console.
Add new transactions to a journal file, with interactive prompting.
.IP
.EX
Flags:
@ -8906,6 +8972,9 @@ default commodity with a \f[CR]D\f[R] directive, you might expect
It does not do this; we assume that if you are using a \f[CR]D\f[R]
directive you prefer not to see the commodity symbol repeated on amounts
in the journal.
.IP \[bu] 2
\f[CR]add\f[R] creates entries in journal format; it won\[aq]t work with
timeclock or timedot files.
.PP
Examples:
.IP \[bu] 2
@ -8981,7 +9050,7 @@ $ hledger import bank1\-checking.csv bank1\-savings.csv
.EX
$ hledger import *.csv
.EE
.SS Import preview
.SS Import dry run
It\[aq]s useful to preview the import by running first with
\f[CR]\-\-dry\-run\f[R], to sanity check the range of dates being
imported, and to check the effect of your conversion rules if converting
@ -9004,7 +9073,7 @@ You could also run this repeatedly to see the effect of edits to your
conversion rules:
.IP
.EX
$ watchexec \-\- \[aq]hledger import \-\-dry\-run bank.csv | hledger \-f\- \-I print unknown\[aq]
$ watchexec \-\- \[dq]hledger import \-\-dry\-run bank.csv | hledger \-f\- \-I print unknown\[dq]
.EE
.PP
Once the conversion and dates look good enough to import to your
@ -9153,38 +9222,58 @@ journal\[aq]s canonical commodity styles, as declared by
amounts.
.PP
Related: CSV > Amount decimal places.
.SS Import archiving
When importing from a CSV rules file
(\f[CR]hledger import bank.rules\f[R]), you can use the archive rule to
enable automatic archiving of the data file.
After a successful import, the data file (specified by
\f[CR]source\f[R]) will be moved to an archive folder (\f[CR]data/\f[R],
next to the rules file, auto\-created), and renamed similar to the rules
file, with a date.
This can be useful for troubleshooting, detecting variations in your
banks\[aq] CSV data, regenerating entries with improved rules, etc.
.PP
The \f[CR]archive\f[R] rule also causes \f[CR]import\f[R] to handle
\f[CR]source\f[R] glob patterns differently: when there are multiple
matched files, it will pick the oldest, not the newest.
.SS Import special cases
If you have a download whose file name varies, you could rename it to a
fixed name after each download.
Or you could use a CSV \f[CR]source\f[R] rule with a suitable glob
pattern, and import from the .rules file instead of the data file.
.PP
Here\[aq]s a situation where you would need to run \f[CR]import\f[R]
with care: say you download \f[CR]bank.csv\f[R], but forget to import it
or delete it.
And next month you download it again.
This time your web browser may save it as \f[CR]bank (2).csv\f[R].
So now each of these may have data not included in the other.
And a \f[CR]source\f[R] rule with a glob pattern would match only the
most recent file.
So in this case you should import from each one in turn, in the correct
order, taking care to use the same filename each time:
.IP
.EX
$ hledger import bank.csv
$ mv \[aq]bank (2).csv\[aq] bank.csv
$ hledger import bank.csv
.EE
.PP
.SS Deduplication
Here are two kinds of \[dq]deduplication\[dq] which \f[CR]import\f[R]
does not handle (and generally should not, since these can happen
legitimately in financial data):
does not handle (and should not, because these can happen legitimately
in financial data):
.IP \[bu] 2
Two or more of the new CSV records are identical, and generate identical
new journal entries.
.IP \[bu] 2
A new CSV record generates a journal entry identical to one(s) already
in the journal.
.SS Varying file name
If you have a download whose file name varies, you could rename it to a
fixed name after each download.
Or you could use a CSV \f[CR]source\f[R] rule with a suitable glob
pattern, and import from the .rules file.
.SS Multiple versions
Say you download \f[CR]bank.csv\f[R], import it, but forget to delete it
from your downloads folder.
The next time you download it, your web browser will save it as (eg)
\f[CR]bank (2).csv\f[R].
The source rule\[aq]s glob patterns are for just this situation: instead
of specifying \f[CR]source bank.csv\f[R], specify
\f[CR]source bank*.csv\f[R].
Then \f[CR]hledger \-f bank.rules CMD\f[R] or
\f[CR]hledger import bank.rules\f[R] will automatically pick the newest
matched file (\f[CR]bank (2).csv\f[R]).
.PP
Alternately, what if you download, but forget to import or delete, then
download again ?
Now each of \f[CR]bank.csv\f[R] and \f[CR]bank (2).csv\f[R] might
contain data that\[aq]s not in the other, and not in your journal.
In this case, it\[aq]s best to import each of them in turn, oldest first
(otherwise, overlap detection could cause new records to be skipped).
Enabling import archiving ensures this.
Then \f[CR]hledger import bank.rules; hledger import bank.rules\f[R]
will import and archive first \f[CR]bank.csv\f[R], then
\f[CR]bank (2).csv\f[R].
.SH Basic report commands
.SS accounts
List the account names used or declared in the journal.
@ -9813,7 +9902,7 @@ full account name, or a distinctive substring that matches uniquely.
.PP
Transactions involving subaccounts of this account will also be shown.
\f[CR]aregister\f[R] ignores depth limits, so its final total will
always match a balance report with similar arguments.
always match a historical balance report with similar arguments.
.PP
Any additional arguments form a query which will filter the transactions
shown.
@ -12212,10 +12301,10 @@ spaces between account and amount.
More:
.IP
.EX
$ hledger rewrite \-\- [QUERY] \-\-add\-posting \[dq]ACCT AMTEXPR\[dq] ...
$ hledger rewrite \-\- \[ha]income \-\-add\-posting \[aq](liabilities:tax) *.33\[aq]
$ hledger rewrite \-\- expenses:gifts \-\-add\-posting \[aq](budget:gifts) *\-1\[dq]\[aq]
$ hledger rewrite \-\- \[ha]income \-\-add\-posting \[aq](budget:foreign currency) *0.25 JPY; diversify\[aq]
$ hledger rewrite [QUERY] \-\-add\-posting \[dq]ACCT AMTEXPR\[dq] ...
$ hledger rewrite \[ha]income \-\-add\-posting \[aq](liabilities:tax) *.33\[aq]
$ hledger rewrite expenses:gifts \-\-add\-posting \[aq](budget:gifts) *\-1\[dq]\[aq]
$ hledger rewrite \[ha]income \-\-add\-posting \[aq](budget:foreign currency) *0.25 JPY; diversify\[aq]
.EE
.PP
Argument for \f[CR]\-\-add\-posting\f[R] option is a usual posting of
@ -12253,14 +12342,14 @@ It indicates the query by which you want to match the posting to add new
ones.
.IP
.EX
$ hledger rewrite \-\- \-f input.journal \-f rewrite\-rules.journal > rewritten\-tidy\-output.journal
$ hledger rewrite \-f input.journal \-f rewrite\-rules.journal > rewritten\-tidy\-output.journal
.EE
.PP
This is something similar to the commands pipeline:
.IP
.EX
$ hledger rewrite \-\- \-f input.journal \[aq]\[ha]income\[aq] \-\-add\-posting \[aq](liabilities:tax) *.33\[aq] \[rs]
| hledger rewrite \-\- \-f \- expenses:gifts \-\-add\-posting \[aq]budget:gifts *\-1\[aq] \[rs]
$ hledger rewrite \-f input.journal \[aq]\[ha]income\[aq] \-\-add\-posting \[aq](liabilities:tax) *.33\[aq] \[rs]
| hledger rewrite \-f \- expenses:gifts \-\-add\-posting \[aq]budget:gifts *\-1\[aq] \[rs]
\-\-add\-posting \[aq]assets:budget *1\[aq] \[rs]
> rewritten\-tidy\-output.journal
.EE
@ -12273,7 +12362,7 @@ To use this tool for batch modification of your journal files you may
find useful output in form of unified diff.
.IP
.EX
$ hledger rewrite \-\- \-\-diff \-f examples/sample.journal \[aq]\[ha]income\[aq] \-\-add\-posting \[aq](liabilities:tax) *.33\[aq]
$ hledger rewrite \-\-diff \-f examples/sample.journal \[aq]\[ha]income\[aq] \-\-add\-posting \[aq](liabilities:tax) *.33\[aq]
.EE
.PP
Output might look like:
@ -12604,10 +12693,10 @@ help:
command\-specific options must go after the command (it\[aq]s fine to
put common options there too: \f[CR]hledger CMD OPTS ARGS\f[R])
.IP \[bu] 2
running add\-on executables directly simplifies command line parsing
(\f[CR]hledger\-ui OPTS ARGS\f[R])
you can run addon commands via hledger (\f[CR]hledger ui [ARGS]\f[R]) or
directly (\f[CR]hledger\-ui [ARGS]\f[R])
.IP \[bu] 2
enclose \[dq]problematic\[dq] args in single quotes
enclose \[dq]problematic\[dq] arguments in single quotes
.IP \[bu] 2
if needed, also add a backslash to hide regular expression
metacharacters from the shell
@ -13038,19 +13127,13 @@ We welcome bug reports in the hledger issue tracker
.PP
Some known issues and limitations:
.PP
The need to precede add\-on command options with \f[CR]\-\-\f[R] when
invoked from hledger is awkward.
(See Command options, Constructing command lines.)
.PP
A system locale with a suitable text encoding must be configured to work
with non\-ascii data.
(See Text encoding, Troubleshooting.)
.PP
On Microsoft Windows, depending whether you are running in a CMD window
or a Cygwin/MSYS/Mintty window and how you installed hledger, non\-ascii
characters and colours may not be supported, and the tab key may not be
supported by \f[CR]hledger add\f[R].
(Running in a WSL window should resolve these.)
On Microsoft Windows, depending what kind of terminal window you use,
non\-ascii characters, ANSI text formatting, and/or the add
command\[aq]s TAB key for completion, may not be supported.
.PP
When processing large data files, hledger uses more memory than Ledger.
.SS Troubleshooting

1221
hledger/hledger.info
View File

File diff suppressed because it is too large Load Diff

283
hledger/hledger.txt
View File

@ -9,9 +9,6 @@ SYNOPSIS
hledger
or
hledger COMMAND [OPTS] [ARGS]
or
hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]
DESCRIPTION
hledger is a robust, user-friendly, cross-platform set of programs for
tracking money, time, or any other commodity, using double-entry ac-
@ -195,7 +192,7 @@ Input
o Are all commodity conversions declared explicitly ?
You can use the check command to run individual checks -- the ones
You can use the check command to run individual checks - the ones
listed above and some more.
Commands
@ -224,25 +221,23 @@ Commands
nal, run hledger CMD -h. Eg: hledger bal -h.
Add-on commands
In addition to the built-in commands, you can install add-on commands:
programs or scripts named "hledger-SOMETHING", which will also appear
in hledger's commands list. If you used the hledger-install script,
you will have several add-ons installed already. Some more can be
found in hledger's bin/ directory, documented at
https://hledger.org/scripts.html.
In addition to the built-in commands, you can install add-on commands,
which will also appear in hledger's commands list. Some of these can
be installed as separate packages; others can be found in hledger's
bin/ directory, documented at https://hledger.org/scripts.html.
More precisely, add-on commands are programs or scripts in your shell's
PATH, whose name starts with "hledger-" and ends with no extension or a
recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs",
".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix
and mac) which has executable permission for the current user.
Add-on commands are programs or scripts in your shell's PATH, whose
name starts with "hledger-" and ends with no extension or a recognised
extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs", ".lua",
".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix and mac)
which has executable permission for the current user.
You can run add-on commands using hledger, much like built-in commands:
hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double
hyphen argument, required before add-on-specific options. Eg: hledger
ui -- --watch or hledger web -- --serve. If this causes difficulty,
you can always run the add-on directly, without using hledger:
hledger-ui --watch or hledger-web --serve.
You can run add-on commands directly: hledger-ui --watch.
Or you can run them with hledger, like built-in commands: hledger ui
--watch. In this case hledger's config file will be used, so you can
set custom options for the addon there. (Before hledger 1.50, an --
argument was needed before addon options, but not any more.)
Options
Run hledger -h to see general command line help. Options can be writ-
@ -344,6 +339,10 @@ Options
Usually hledger accepts any unambiguous flag prefix, eg you can write
--tl instead of --tldr or --dry instead of --dry-run.
You can combine short flags which don't take arguments, eg you can
write -MAST instead of -M -A -S -T. Flags requiring an argument can't
be combined in this way (-If FILE won't work).
If the same option appears more than once in a command line, usually
the last (right-most) wins. Similarly, if mutually exclusive flags are
used together, the right-most wins. (When flags are mutually exclu-
@ -716,8 +715,7 @@ Options
4. To troubleshoot the effect of config files, run with --debug or
--debug 8.
The config file feature was added in hledger 1.40 and is considered ex-
perimental.
The config file feature was added in hledger 1.40.
Shell completions
If you use the bash or zsh shells, you can optionally set up con-
@ -834,7 +832,7 @@ Output
If you are using the less pager, hledger automatically appends a number
of options to the LESS variable to enable ANSI colour and a number of
other conveniences. (At the time of writing: --chop-long-lines
--hilite-unread --ignore-case --mouse --no-init --quit-at-eof
--hilite-unread --ignore-case --no-init --quit-at-eof
--quit-if-one-screen --RAW-CONTROL-CHARS --shift=8
--squeeze-blank-lines --use-backslash ). If these don't work well, you
can set your preferred options in the HLEDGER_LESS variable, which will
@ -2508,27 +2506,51 @@ Journal
You can pull in the content of additional files by writing an include
directive, like this:
include FILEPATH
include SOMEFILE
Only journal files can include, and only journal, timeclock or timedot
files can be included (not CSV files, currently).
This has the same effect as if SOMEFILE's content was inlined at this
point. (With any include directives in SOMEFILE processed similarly,
recursively.)
If the file path does not begin with a slash, it is relative to the
current file's folder.
Only journal files can include other files. They can include journal,
timeclock or timedot files, but not CSV files.
A tilde means home directory, eg: include ~/main.journal.
If the file path begins with a tilde, that means your home directory:
include ~/main.journal.
The path may contain glob patterns to match multiple files, eg: include
*.journal.
If it begins with a slash, it is an absolute path: include
/home/user/main.journal. Otherwise it is relative to the including
file's folder: include ../finances/main.journal.
There is limited support for recursive wildcards: **/ (the slash is re-
quired) matches 0 or more subdirectories. It's not super convenient
since you have to avoid include cycles and including directories, but
this can be done, eg: include */**/*.journal.
Also, the path may have a file type prefix to force a specific file
format, overriding the file extension(s) (as described in Data for-
mats): include timedot:notes/2023.md.
The path may also be prefixed to force a specific file format, overrid-
ing the file extension (as described in Data formats): include time-
dot:~/notes/2023*.md.
The path may contain glob patterns to match multiple files. hledger's
globs are similar to zsh's: ? to match any character; [a-z] to match
any character in a range; * to match zero or more characters that
aren't a path separator (like /); ** to match zero or more subdirecto-
ries and/or zero or more characters at the start of a file name; etc.
Also, hledger's globs always exclude the including file itself. So,
you can do
o include *.journal to include all other journal files in the current
directory (excluding dot files)
o include **.journal to include all other journal files in this direc-
tory and below (excluding dot directories/files)
o include timelogs/2???.timedot to include all timedot files named like
a year number.
There is a limitation: hledger's globs always exclude paths involving
dot files or dot directories. This is a workaround for unavoidable dot
directory traversal; you can disable it and revert to older behaviour
with the --old-glob flag, for now.
If you are using many, or deeply nested, include files, and have an er-
ror that's hard to pinpoint: a good troubleshooting command is hledger
files --debug=6 (or 7).
P directive
The P directive declares a market price, which is a conversion rate be-
@ -2709,6 +2731,9 @@ Journal
the duration of the report, and only when --auto is used; they are not
saved in the journal file by hledger.
The postings can contain the special string %account which will be ex-
panded to the account name of the matched account.
Generated postings' amounts can depend on the matched posting's amount.
So auto postings can be useful for, eg, adding tax postings with a
standard percentage. AMOUNT can be:
@ -3262,27 +3287,59 @@ CSV
If you tell hledger to read a csv file with -f foo.csv, it will look
for rules in foo.csv.rules. Or, you can tell it to read the rules
file, with -f foo.csv.rules, and it will look for data in foo.csv
(since 1.30).
(since 1.30). These are mostly equivalent, but the second method pro-
vides some extra features. For one, the data file can be missing,
without causing an error; it is just considered empty.
These are mostly equivalent, but the second method provides some extra
features. For one, the data file can be missing, without causing an
error; it is just considered empty. And, you can specify a different
data file by adding a "source" rule:
For more flexibility, add a source rule, which lets you specify a dif-
ferent data file:
source ./Checking1.csv
If the file does not exist, it is just considered empty, without rais-
ing an error.
If you specify just a file name with no path, hledger will look for it
in your system's downloads directory (~/Downloads, currently):
in the ~/Downloads folder:
source Checking1.csv
And if you specify a glob pattern, hledger will read the most recent of
the matched files (useful with repeated downloads):
You can use a glob pattern, to avoid specifying the file name exactly:
source Checking1*.csv
This has another benefit: if the pattern matches multiple files,
hledger will read the newest (most recently modified) one. This avoids
problems if you have downloaded a file multiple times without cleaning
up.
All this enables a convenient workflow where can you just download CSV
files, then run hledger import rules/*.
See also "Working with CSV > Reading files specified by rule".
The archive rule adds a few more features to source; see below.
archive
Adding the archive rule to your rules file affects importing or reading
files specified by source:
o After successfully importing, import will move the data file to an
archive directory (data/ next to the rules file, auto-created), re-
named to RULESFILEBASENAME.DATAFILEMODDATE.DATAFILEEXT. Archiving
data files is optional, but it can be useful for troubleshooting, de-
tecting variations in your banks' CSV data, regenerating entries with
improved rules, etc.
o import will pick the oldest of source glob matches, rather than the
newest. So if you have multiple versions of a download, repeated im-
ports will process them in chronological order.
o For commands other than import, when the source path or glob pattern
matches no files, hledger will try to read the latest archived data
file instead. This is convenient for working with the downloaded
data again, even after it has been imported.
encoding
encoding ENCODING
@ -3362,6 +3419,9 @@ CSV
# Note the time and junk must be fully parsed, though only the date is used.
date-format %-m/%-d/%Y %l:%M %p some other junk
Note currently there is no locale awareness for things like %b, and
setting LC_TIME won't help.
timezone
timezone TIMEZONE
@ -4805,18 +4865,23 @@ Time periods
optionally use "smart date" syntax. Smart dates can be written with
english words, can be relative, and can have parts omitted. Missing
parts are inferred as 1, when needed. Smart dates can be interpreted
as dates or periods depending on context.
as dates or periods depending on the context.
Examples:
2004-01-01, 2004/10/1, 2004.9.1, 20240504 :
2004-01-01, 2004/10/1, 2004.9.1, 20240504, 2024Q1 :
Exact dates. The year must have at least four digits, the month must
be 1-12, the day must be 1-31, the separator can be - or / or . or
nothing.
nothing. The q can be upper or lower case and the quarter number must
be 1-4.
2004-10
start of month
2004q3 start of third quarter of 2004
q3 start of third quarter of current year
2004 start of year
10/1 or oct or october
@ -4914,7 +4979,7 @@ Time periods
ary.
o hledger register --monthly --end 2/14 also will end the report at the
end of february.
end of february (overriding the requested end date).
o hledger register --monthly --begin 1/5 --end 2/14 will end the report
on march 4th [1].
@ -5113,8 +5178,8 @@ Depth
o all other accounts to depth 1.
If an account is matched by more than one regular expression depth ar-
gument then the more specific one will used. For example, if --depth
assets=1 --depth assets:bank:savings=2 is provided, then as-
gument then the more specific one will be used. For example, if
--depth assets=1 --depth assets:bank:savings=2 is provided, then as-
sets:bank:savings will be collapsed to depth 2 rather than depth 1.
This is because assets:bank:savings matches at level 3 in the account
name, while assets matches at level 1. The same would be true with the
@ -5365,7 +5430,7 @@ Queries
all:'QUERYEXPR'
Like expr:, but when used with transaction-oriented commands like
print, it matches the transaction only if all postings are matched by
all of QUERYEXPR.
all of QUERYEXPR (and there is at least one posting).
So, hledger print all:'cash and amt:0' means "show transactions where
all postings involve a cash account and have a zero amount".
Or, hledger print all:'cash or checking' means "show transactions which
@ -6294,8 +6359,8 @@ Value reporting
2000-02-01
(a) 2 B
With no report period specified, that shows the value as of the last
day of the journal (2000-03-01):
With no report period specified, the latest transaction date or price
date is used as valuation date (2000-04-01):
$ hledger -f- print --value=end
2000-01-01
@ -6307,7 +6372,7 @@ Value reporting
2000-03-01
(a) 3 B
Show the current value (the 2000-04-01 price is still in effect today):
The value today is the same (the 2000-04-01 price is still in effect):
$ hledger -f- print --value=now
2000-01-01
@ -6609,9 +6674,6 @@ Help commands
eg -s4 to play at 4x original speed or -s.5 to play at half speed. The
default speed is 2x.
Other asciinema options can be added following a double dash, eg --
-i.1 to limit pauses or -- -h to list asciinema's other options.
During playback, several keys are available: SPACE to pause/unpause, .
to step forward (while paused), CTRL-c quit.
@ -6846,7 +6908,7 @@ User interface commands
Data entry commands
add
Record new transactions with interactive prompting in the console.
Add new transactions to a journal file, with interactive prompting.
Flags:
--no-new-accounts don't allow creating new accounts
@ -6894,6 +6956,9 @@ Data entry commands
using a D directive you prefer not to see the commodity symbol re-
peated on amounts in the journal.
o add creates entries in journal format; it won't work with timeclock
or timedot files.
Examples:
o Record new transactions, saving to the default journal file:
@ -6958,7 +7023,7 @@ Data entry commands
$ hledger import *.csv
Import preview
Import dry run
It's useful to preview the import by running first with --dry-run, to
sanity check the range of dates being imported, and to check the effect
of your conversion rules if converting from CSV. Eg:
@ -6974,7 +7039,7 @@ Data entry commands
You could also run this repeatedly to see the effect of edits to your
conversion rules:
$ watchexec -- 'hledger import --dry-run bank.csv | hledger -f- -I print unknown'
$ watchexec -- "hledger import --dry-run bank.csv | hledger -f- -I print unknown"
Once the conversion and dates look good enough to import to your jour-
nal, perhaps with some manual fixups to follow, you would do the actual
@ -7104,27 +7169,23 @@ Data entry commands
Related: CSV > Amount decimal places.
Import archiving
When importing from a CSV rules file (hledger import bank.rules), you
can use the archive rule to enable automatic archiving of the data
file. After a successful import, the data file (specified by source)
will be moved to an archive folder (data/, next to the rules file,
auto-created), and renamed similar to the rules file, with a date.
This can be useful for troubleshooting, detecting variations in your
banks' CSV data, regenerating entries with improved rules, etc.
The archive rule also causes import to handle source glob patterns dif-
ferently: when there are multiple matched files, it will pick the old-
est, not the newest.
Import special cases
If you have a download whose file name varies, you could rename it to a
fixed name after each download. Or you could use a CSV source rule
with a suitable glob pattern, and import from the .rules file instead
of the data file.
Here's a situation where you would need to run import with care: say
you download bank.csv, but forget to import it or delete it. And next
month you download it again. This time your web browser may save it as
bank (2).csv. So now each of these may have data not included in the
other. And a source rule with a glob pattern would match only the most
recent file. So in this case you should import from each one in turn,
in the correct order, taking care to use the same filename each time:
$ hledger import bank.csv
$ mv 'bank (2).csv' bank.csv
$ hledger import bank.csv
Deduplication
Here are two kinds of "deduplication" which import does not handle (and
generally should not, since these can happen legitimately in financial
data):
should not, because these can happen legitimately in financial data):
o Two or more of the new CSV records are identical, and generate iden-
tical new journal entries.
@ -7132,6 +7193,29 @@ Data entry commands
o A new CSV record generates a journal entry identical to one(s) al-
ready in the journal.
Varying file name
If you have a download whose file name varies, you could rename it to a
fixed name after each download. Or you could use a CSV source rule
with a suitable glob pattern, and import from the .rules file.
Multiple versions
Say you download bank.csv, import it, but forget to delete it from your
downloads folder. The next time you download it, your web browser will
save it as (eg) bank (2).csv. The source rule's glob patterns are for
just this situation: instead of specifying source bank.csv, specify
source bank*.csv. Then hledger -f bank.rules CMD or hledger import
bank.rules will automatically pick the newest matched file (bank
(2).csv).
Alternately, what if you download, but forget to import or delete, then
download again ? Now each of bank.csv and bank (2).csv might contain
data that's not in the other, and not in your journal. In this case,
it's best to import each of them in turn, oldest first (otherwise,
overlap detection could cause new records to be skipped). Enabling im-
port archiving ensures this. Then hledger import bank.rules; hledger
import bank.rules will import and archive first bank.csv, then bank
(2).csv.
Basic report commands
accounts
List the account names used or declared in the journal.
@ -7690,7 +7774,7 @@ Standard report commands
Transactions involving subaccounts of this account will also be shown.
aregister ignores depth limits, so its final total will always match a
balance report with similar arguments.
historical balance report with similar arguments.
Any additional arguments form a query which will filter the transac-
tions shown. Note some queries will disturb the running balance, caus-
@ -9738,10 +9822,10 @@ Data generation commands
More:
$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'
$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
$ hledger rewrite [QUERY] --add-posting "ACCT AMTEXPR" ...
$ hledger rewrite ^income --add-posting '(liabilities:tax) *.33'
$ hledger rewrite expenses:gifts --add-posting '(budget:gifts) *-1"'
$ hledger rewrite ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
Argument for --add-posting option is a usual posting of transaction
with an exception for amount specification. More precisely, you can
@ -9771,12 +9855,12 @@ Data generation commands
actions you usually write. It indicates the query by which you want to
match the posting to add new ones.
$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
$ hledger rewrite -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
This is something similar to the commands pipeline:
$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \
| hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \
$ hledger rewrite -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \
| hledger rewrite -f - expenses:gifts --add-posting 'budget:gifts *-1' \
--add-posting 'assets:budget *1' \
> rewritten-tidy-output.journal
@ -9788,7 +9872,7 @@ Data generation commands
To use this tool for batch modification of your journal files you may
find useful output in form of unified diff.
$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
$ hledger rewrite --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
Output might look like:
@ -10086,10 +10170,10 @@ Constructing command lines
o command-specific options must go after the command (it's fine to put
common options there too: hledger CMD OPTS ARGS)
o running add-on executables directly simplifies command line parsing
(hledger-ui OPTS ARGS)
o you can run addon commands via hledger (hledger ui [ARGS]) or di-
rectly (hledger-ui [ARGS])
o enclose "problematic" args in single quotes
o enclose "problematic" arguments in single quotes
o if needed, also add a backslash to hide regular expression metachar-
acters from the shell
@ -10471,17 +10555,12 @@ BUGS
Some known issues and limitations:
The need to precede add-on command options with -- when invoked from
hledger is awkward. (See Command options, Constructing command lines.)
A system locale with a suitable text encoding must be configured to
work with non-ascii data. (See Text encoding, Troubleshooting.)
On Microsoft Windows, depending whether you are running in a CMD window
or a Cygwin/MSYS/Mintty window and how you installed hledger, non-ascii
characters and colours may not be supported, and the tab key may not be
supported by hledger add. (Running in a WSL window should resolve
these.)
On Microsoft Windows, depending what kind of terminal window you use,
non-ascii characters, ANSI text formatting, and/or the add command's
TAB key for completion, may not be supported.
When processing large data files, hledger uses more memory than Ledger.