13490 lines
460 KiB
Groff
13490 lines
460 KiB
Groff
.\"t
|
|
|
|
.TH "HLEDGER" "1" "November 2025" "hledger-1.50.99 " "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
hledger \- a robust, friendly plain text accounting app (command line
|
|
version).
|
|
.SH SYNOPSIS
|
|
\f[CR]hledger\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
or
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]hledger COMMAND [OPTS] [ARGS]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.SH DESCRIPTION
|
|
hledger is a robust, user\-friendly, cross\-platform set of programs for
|
|
tracking money, time, or any other commodity, using double\-entry
|
|
accounting and a simple, editable file format.
|
|
hledger is inspired by and largely compatible with ledger(1), and
|
|
largely interconvertible with beancount(1).
|
|
.PP
|
|
This manual is for hledger\[aq]s command line interface, version
|
|
1.50.99.
|
|
It also describes the common options, file formats and concepts used by
|
|
all hledger programs.
|
|
It might accidentally teach you some bookkeeping/accounting as well!
|
|
You don\[aq]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 open a built\-in copy, at a point of interest, by running
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\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).
|
|
Many reports are available, as subcommands.
|
|
hledger will also detect other \f[CR]hledger\-*\f[R] executables as
|
|
extra subcommands.
|
|
.PP
|
|
hledger usually reads from (and appends to) a journal file specified by
|
|
the \f[CR]LEDGER_FILE\f[R] environment variable (defaulting to
|
|
\f[CR]$HOME/.hledger.journal\f[R]); or you can specify files with
|
|
\f[CR]\-f\f[R] options.
|
|
It can also read timeclock files, timedot files, or any CSV/SSV/TSV file
|
|
with a date field.
|
|
.PP
|
|
Here is a small journal file describing one transaction:
|
|
.IP
|
|
.EX
|
|
2015\-10\-16 bought food
|
|
expenses:food $10
|
|
assets:cash
|
|
.EE
|
|
.PP
|
|
Transactions are dated movements of money (etc.)
|
|
between two or more \f[I]accounts\f[R]: bank accounts, your wallet,
|
|
revenue/expense categories, people, etc.
|
|
You can choose any account names you wish, using \f[CR]:\f[R] to
|
|
indicate subaccounts.
|
|
There must be at least two spaces between account name and amount.
|
|
Positive amounts are inflow to that account (\f[I]debit\f[R]), negatives
|
|
are outflow from it (\f[I]credit\f[R]).
|
|
(Some reports show revenue, liability and equity account balances as
|
|
negative numbers as a result; this is normal.)
|
|
.PP
|
|
hledger\[cq]s add command can help you add transactions, or you can
|
|
install other data entry UIs like hledger\-web or hledger\-iadd.
|
|
For more extensive/efficient changes, use a text editor: Emacs +
|
|
ledger\-mode, VIM + vim\-ledger, or VS Code + hledger\-vscode are some
|
|
good choices (see https://hledger.org/editors.html).
|
|
.PP
|
|
To get started, run \f[CR]hledger add\f[R] and follow the prompts, or
|
|
save some entries like the above in \f[CR]$HOME/.hledger.journal\f[R],
|
|
then try commands like:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-x
|
|
$ hledger aregister assets
|
|
$ hledger balance
|
|
$ hledger balancesheet
|
|
$ hledger incomestatement
|
|
.EE
|
|
.PP
|
|
Run \f[CR]hledger\f[R] to list the commands.
|
|
See also the \[dq]Starting a journal file\[dq] and \[dq]Setting opening
|
|
balances\[dq] sections in PART 5: COMMON TASKS.
|
|
.SH PART 1: USER INTERFACE
|
|
.SH Input
|
|
hledger reads one or more data files, each time you run it.
|
|
You can specify a file with \f[CR]\-f\f[R], like so
|
|
.IP
|
|
.EX
|
|
$ hledger \-f FILE [\-f FILE2 ...] print
|
|
.EE
|
|
.PP
|
|
Files are most often in hledger\[aq]s journal format, with the
|
|
\f[CR].journal\f[R] file extension (\f[CR].hledger\f[R] or \f[CR].j\f[R]
|
|
also work); these files describe transactions, like an accounting
|
|
general journal.
|
|
.PP
|
|
When no file is specified, hledger looks for \f[CR].hledger.journal\f[R]
|
|
in your home directory.
|
|
.PP
|
|
But most people prefer to keep financial files in a dedicated folder,
|
|
perhaps with version control.
|
|
Also, starting a new journal file each year is common (it\[aq]s not
|
|
required, but helps keep things fast and organised).
|
|
So we usually configure a different journal file, by setting the
|
|
\f[CR]LEDGER_FILE\f[R] environment variable, to something like
|
|
\f[CR]\[ti]/finance/2023.journal\f[R].
|
|
For more about how to do that on your system, see Common tasks > Setting
|
|
LEDGER_FILE.
|
|
.SS Text encoding
|
|
hledger expects non\-ascii input to be decodable with the system
|
|
locale\[aq]s text encoding.
|
|
(For CSV/SSV/TSV files, this can be overridden by the
|
|
\f[CR]encoding\f[R] CSV rule.)
|
|
.PP
|
|
So, trying to read non\-ascii files which have the wrong text encoding,
|
|
or when no system locale is configured, will fail.
|
|
To fix this, configure your system locale appropriately, and/or convert
|
|
the files to your system\[aq]s text encoding (using \f[CR]iconv\f[R] on
|
|
unix, or powershell or notepad on Windows).
|
|
See Install: Text encoding for more tips.
|
|
.PP
|
|
hledger\[aq]s output will use the system locale\[aq]s encoding.
|
|
.PP
|
|
hledger\[aq]s docs and example files mostly use UTF\-8 encoding.
|
|
.SS Data formats
|
|
Usually the data file is in hledger\[aq]s journal format, but it can be
|
|
in any of the supported file formats, which currently are:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(13.5n) lw(33.0n) lw(23.5n).
|
|
T{
|
|
Reader:
|
|
T}@T{
|
|
Reads:
|
|
T}@T{
|
|
Automatically used for files with extensions:
|
|
T}
|
|
_
|
|
T{
|
|
\f[CR]journal\f[R]
|
|
T}@T{
|
|
hledger journal files and some Ledger journals, for transactions
|
|
T}@T{
|
|
\f[CR].journal\f[R] \f[CR].j\f[R] \f[CR].hledger\f[R] \f[CR].ledger\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]timeclock\f[R]
|
|
T}@T{
|
|
timeclock files, for precise time logging
|
|
T}@T{
|
|
\f[CR].timeclock\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]timedot\f[R]
|
|
T}@T{
|
|
timedot files, for approximate time logging
|
|
T}@T{
|
|
\f[CR].timedot\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]csv\f[R]
|
|
T}@T{
|
|
Comma\- or other delimiter\-separated values, for data import
|
|
T}@T{
|
|
\f[CR].csv\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]ssv\f[R]
|
|
T}@T{
|
|
Semicolon separated values
|
|
T}@T{
|
|
\f[CR].ssv\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]tsv\f[R]
|
|
T}@T{
|
|
Tab separated values
|
|
T}@T{
|
|
\f[CR].tsv\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]rules\f[R]
|
|
T}@T{
|
|
CSV/SSV/TSV/other separated values, alternate way
|
|
T}@T{
|
|
\f[CR].rules\f[R]
|
|
T}
|
|
.TE
|
|
.PP
|
|
These formats are described in more detail below.
|
|
.PP
|
|
hledger detects the format automatically based on the file extensions
|
|
shown above.
|
|
If it can\[aq]t recognise the file extension, it assumes
|
|
\f[CR]journal\f[R] format.
|
|
So for non\-journal files, it\[aq]s important to use a recognised file
|
|
extension, so as to either read successfully or to show relevant error
|
|
messages.
|
|
.PP
|
|
You can also force a specific reader/format by prefixing the file path
|
|
with the format and a colon.
|
|
Eg, to read a .dat file containing tab separated values:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f tsv:/some/file.dat stats
|
|
.EE
|
|
.SS Standard input
|
|
The file name \f[CR]\-\f[R] means standard input:
|
|
.IP
|
|
.EX
|
|
$ cat FILE | hledger \-f\- print
|
|
.EE
|
|
.PP
|
|
If reading non\-journal data in this way, you\[aq]ll need to write the
|
|
format as a prefix, like \f[CR]timeclock:\f[R] here:
|
|
.IP
|
|
.EX
|
|
$ echo \[aq]i 2009/13/1 08:00:00\[aq] | hledger print \-f timeclock:\-
|
|
.EE
|
|
.SS Multiple files
|
|
You can specify multiple \f[CR]\-f\f[R] options, to read multiple files
|
|
as one big journal.
|
|
When doing this, note that certain features (described below) will be
|
|
affected:
|
|
.IP \[bu] 2
|
|
Balance assertions will not see the effect of transactions in previous
|
|
files.
|
|
(Usually this doesn\[aq]t matter as each file will set the corresponding
|
|
opening balances.)
|
|
.IP \[bu] 2
|
|
Some directives will not affect previous or subsequent files.
|
|
.PP
|
|
If needed, you can work around these by using a single parent file which
|
|
includes the others, or concatenating the files into one, eg:
|
|
\f[CR]cat a.journal b.journal | hledger \-f\- CMD\f[R].
|
|
.SS Strict mode
|
|
hledger checks input files for valid data.
|
|
By default, the most important errors are detected, while still
|
|
accepting easy journal files without a lot of declarations:
|
|
.IP \[bu] 2
|
|
Are the input files parseable, with valid syntax ?
|
|
.IP \[bu] 2
|
|
Are all transactions balanced ?
|
|
.IP \[bu] 2
|
|
Do all balance assertions pass ?
|
|
.PP
|
|
With the \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] flag, additional checks
|
|
are performed:
|
|
.IP \[bu] 2
|
|
Are all accounts posted to, declared with an \f[CR]account\f[R]
|
|
directive ?
|
|
(Account error checking)
|
|
.IP \[bu] 2
|
|
Are all commodities declared with a \f[CR]commodity\f[R] directive ?
|
|
(Commodity error checking)
|
|
.IP \[bu] 2
|
|
Are all commodity conversions declared explicitly ?
|
|
.PP
|
|
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.
|
|
Most of these commands do not change the journal file; they just read it
|
|
and output a report.
|
|
A few commands assist with adding data and file management.
|
|
Some often\-used commands are \f[CR]add\f[R], \f[CR]print\f[R],
|
|
\f[CR]register\f[R], \f[CR]balancesheet\f[R] and
|
|
\f[CR]incomestatement\f[R].
|
|
.PP
|
|
To show a summary of commands, run \f[CR]hledger\f[R] with no arguments.
|
|
You can see the same commands summary at the start of PART 4: COMMANDS
|
|
below.
|
|
.PP
|
|
To use a particular command, run
|
|
\f[CR]hledger CMD [CMDOPTS] [CMDARGS]\f[R],
|
|
.IP \[bu] 2
|
|
CMD is the full command name, or its standard abbreviation shown in the
|
|
commands list, or any unambiguous prefix of the name.
|
|
.IP \[bu] 2
|
|
CMDOPTS are command\-specific options, if any.
|
|
Command\-specific options must be written after the command name.
|
|
Eg: \f[CR]hledger print \-x\f[R].
|
|
.IP \[bu] 2
|
|
CMDARGS are additional arguments to the command, if any.
|
|
Most hledger commands accept arguments representing a query, to limit
|
|
the data in some way.
|
|
Eg: \f[CR]hledger reg assets:checking\f[R].
|
|
.PP
|
|
To list a command\[aq]s options, arguments, and documentation in the
|
|
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], 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
|
|
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 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.
|
|
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=[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.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
|
|
rules (\[dq]=\[dq]) to all transactions
|
|
\-\-forecast[=PERIOD] Generate extra transactions from periodic rules
|
|
(\[dq]\[ti]\[dq]), from after the latest ordinary transaction
|
|
until 6 months from now. Or, during the specified
|
|
PERIOD (the equals is required). Auto posting rules
|
|
will also be applied to these transactions. In
|
|
hledger\-ui, also make future\-dated transactions
|
|
visible at startup.
|
|
\-I \-\-ignore\-assertions don\[aq]t check balance assertions by default
|
|
\-\-txn\-balancing=... how to check that transactions are balanced:
|
|
\[aq]old\[aq]: use global display precision
|
|
\[aq]exact\[aq]: use transaction precision (default)
|
|
\-\-infer\-costs infer conversion equity postings from costs
|
|
\-\-infer\-equity infer costs from conversion equity postings
|
|
\-\-infer\-market\-prices infer market prices from costs
|
|
\-\-pivot=TAGNAME use a different field or tag as account names
|
|
\-s \-\-strict do extra error checks (and override \-I)
|
|
\-\-verbose\-tags add tags indicating generated/modified data
|
|
|
|
General output/reporting flags (supported by some commands):
|
|
\-b \-\-begin=DATE include postings/transactions on/after this date
|
|
\-e \-\-end=DATE include postings/transactions before this date
|
|
(with a report interval, will be adjusted to
|
|
following subperiod end)
|
|
\-D \-\-daily multiperiod report with 1 day interval
|
|
\-W \-\-weekly multiperiod report with 1 week interval
|
|
\-M \-\-monthly multiperiod report with 1 month interval
|
|
\-Q \-\-quarterly multiperiod report with 1 quarter interval
|
|
\-Y \-\-yearly multiperiod report with 1 year interval
|
|
\-p \-\-period=PERIODEXP set begin date, end date, and/or report interval,
|
|
with more flexibility
|
|
\-\-today=DATE override today\[aq]s date (affects relative dates)
|
|
\-\-date2 match/use secondary dates instead (deprecated)
|
|
\-U \-\-unmarked include only unmarked postings/transactions
|
|
\-P \-\-pending include only pending postings/transactions
|
|
\-C \-\-cleared include only cleared postings/transactions
|
|
(\-U/\-P/\-C can be combined)
|
|
\-R \-\-real include only non\-virtual postings
|
|
\-E \-\-empty Show zero items, which are normally hidden.
|
|
In hledger\-ui & hledger\-web, do the opposite.
|
|
\-\-depth=DEPTHEXP if a number (or \-NUM): show only top NUM levels
|
|
of accounts. If REGEXP=NUM, only apply limiting to
|
|
accounts matching the regular expression.
|
|
\-B \-\-cost show amounts converted to their cost/sale amount
|
|
\-V \-\-market Show amounts converted to their value at period
|
|
end(s) in their default valuation commodity.
|
|
Equivalent to \-\-value=end.
|
|
\-X \-\-exchange=COMM Show amounts converted to their value at period
|
|
end(s) in the specified commodity.
|
|
Equivalent to \-\-value=end,COMM.
|
|
\-\-value=WHEN[,COMM] show amounts converted to their value on the
|
|
specified date(s) in their default valuation
|
|
commodity or a specified commodity. WHEN can be:
|
|
\[aq]then\[aq]: value on transaction dates
|
|
\[aq]end\[aq]: value at period end(s)
|
|
\[aq]now\[aq]: value today
|
|
YYYY\-MM\-DD: value on given date
|
|
\-c \-\-commodity\-style=S Override a commodity\[aq]s display style.
|
|
Eg: \-c \[aq].\[aq] or \-c \[aq]1.000,00 EUR\[aq]
|
|
\-\-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.
|
|
|
|
General help flags:
|
|
\-h \-\-help show command line help
|
|
\-\-tldr show command examples with tldr
|
|
\-\-info show the manual with info
|
|
\-\-man show the manual with man
|
|
\-\-version show version information
|
|
\-\-debug=[1\-9] show this much debug output (default: 1)
|
|
\-\-pager=YN use a pager when needed ? y/yes (default) or n/no
|
|
\-\-color=YNA \-\-colour use ANSI color ? y/yes, n/no, or auto (default)
|
|
.EE
|
|
.PP
|
|
Usually hledger accepts any unambiguous flag prefix, eg you can write
|
|
\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
|
|
right\-most wins.
|
|
(When flags are mutually exclusive, they\[aq]ll usually have a group
|
|
prefix in \-\-help.)
|
|
.PP
|
|
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.
|
|
.PP
|
|
Below are more tips for using the command line interface \- feel free to
|
|
skip these until you need them.
|
|
.SS Special characters
|
|
In commands you type at the command line, certain characters have
|
|
special meaning and sometimes need to be \[dq]escaped\[dq] or
|
|
\[dq]quoted\[dq], by prefixing backslashes or enclosing in quotes.
|
|
.PP
|
|
If you are able to minimise the use of special characters in your data,
|
|
you won\[aq]t have to deal with this as much.
|
|
For example, you could use hyphen \f[CR]\-\f[R] or underscore
|
|
\f[CR]_\f[R] instead of spaces in account names, and you could use the
|
|
\f[CR]USD\f[R] currency code instead of the \f[CR]$\f[R] currency symbol
|
|
in amounts.
|
|
.PP
|
|
But if you prefer to use spaced account names and \f[CR]$\f[R], it\[aq]s
|
|
fine.
|
|
Just be aware of this topic so you can check this doc when needed.
|
|
(These examples are mostly tested on unix; some details might need to be
|
|
adapted if you\[aq]re on Windows.)
|
|
.SS Escaping shell special characters
|
|
These are some characters which may have special meaning to your shell
|
|
(the program which interprets command lines):
|
|
.IP \[bu] 2
|
|
SPACE, \f[CR]<\f[R], \f[CR]>\f[R], \f[CR](\f[R], \f[CR])\f[R],
|
|
\f[CR]|\f[R], \f[CR]\[rs]\f[R], \f[CR]%\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]$\f[R] if followed by a word character
|
|
.PP
|
|
So for example, to match an account name containing spaces, like
|
|
\[dq]credit card\[dq], don\[aq]t write:
|
|
.IP
|
|
.EX
|
|
$ hledger register credit card
|
|
.EE
|
|
.PP
|
|
Instead, enclose the name in single quotes:
|
|
.IP
|
|
.EX
|
|
$ hledger register \[aq]credit card\[aq]
|
|
.EE
|
|
.PP
|
|
On unix or in Windows powershell, if you use double quotes your shell
|
|
will silently treat \f[CR]$\f[R] as variable interpolation.
|
|
So you should probably avoid double quotes, unless you want that
|
|
behaviour, eg in a script:
|
|
.IP
|
|
.EX
|
|
$ hledger register \[dq]assets:$SOMEACCT\[dq]
|
|
.EE
|
|
.PP
|
|
But in an older Windows CMD.EXE window, you must use double quotes:
|
|
.IP
|
|
.EX
|
|
C:\[rs]Users\[rs]Me> hledger register \[dq]credit card\[dq]
|
|
.EE
|
|
.PP
|
|
On unix or in Windows powershell, as an alternative to quotes you can
|
|
write a backslash before each special character:
|
|
.IP
|
|
.EX
|
|
$ hledger register credit\[rs] card
|
|
.EE
|
|
.PP
|
|
Finally, since hledger\[aq]s query arguments are regular expressions
|
|
(described below), you could also fill that gap with \f[CR].\f[R] which
|
|
matches any character:
|
|
.IP
|
|
.EX
|
|
$ hledger register credit.card
|
|
.EE
|
|
.SS Escaping regular expression special characters
|
|
Some characters also have special meaning in regular expressions, which
|
|
hledger\[aq]s arguments often are.
|
|
Those include:
|
|
.IP \[bu] 2
|
|
\f[CR].\f[R], \f[CR]\[ha]\f[R], \f[CR]$\f[R], \f[CR][\f[R],
|
|
\f[CR]]\f[R], \f[CR](\f[R], \f[CR])\f[R], \f[CR]|\f[R], \f[CR]\[rs]\f[R]
|
|
.PP
|
|
To escape one of these, write \f[CR]\[rs]\f[R] before it.
|
|
But note this is in addition to the shell escaping above.
|
|
So for characters which are special to both shell and regular
|
|
expressions, like \f[CR]\[rs]\f[R] and \f[CR]$\f[R], you will sometimes
|
|
need two levels of escaping.
|
|
.PP
|
|
For example, a balance report that uses a \f[CR]cur:\f[R] query
|
|
restricting it to just the $ currency, should be written like this:
|
|
.IP
|
|
.EX
|
|
$ hledger balance cur:\[rs]\[rs]$
|
|
.EE
|
|
.PP
|
|
Explanation:
|
|
.IP "1." 3
|
|
Add a backslash \f[CR]\[rs]\f[R] before the dollar sign \f[CR]$\f[R] to
|
|
protect it from regular expressions (so it will be matched literally
|
|
with no special meaning).
|
|
.IP "2." 3
|
|
Add another backslash before that backslash, to protect it from the
|
|
shell (so the shell won\[aq]t consume it).
|
|
.IP "3." 3
|
|
\f[CR]$\f[R] doesn\[aq]t need to be protected from the shell in this
|
|
case, because it\[aq]s not followed by a word character; but it would be
|
|
harmless to do so.
|
|
.PP
|
|
But here\[aq]s another way to write that, which tends to be easier: add
|
|
backslashes to escape from regular expressions, then enclose with quotes
|
|
to escape from the shell:
|
|
.IP
|
|
.EX
|
|
$ hledger balance cur:\[aq]\[rs]$\[aq]
|
|
.EE
|
|
.SS Escaping in other situations
|
|
hledger options and arguments are sometimes used in places other than
|
|
the command line, where the escaping/quoting rules are different.
|
|
For example, backslash\-quoting may not be available.
|
|
Here\[aq]s a quick reference:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(17.5n) lw(52.5n).
|
|
T{
|
|
In unix shell
|
|
T}@T{
|
|
Use single quotes and/or backslash (or double quotes for variable
|
|
interpolation)
|
|
T}
|
|
T{
|
|
In Windows \f[CR]powershell\f[R]
|
|
T}@T{
|
|
Use single quotes (or double quotes for variable interpolation)
|
|
T}
|
|
T{
|
|
In Windows \f[CR]cmd\f[R]
|
|
T}@T{
|
|
Use double quotes
|
|
T}
|
|
T{
|
|
In hledger\-ui\[aq]s filter prompt
|
|
T}@T{
|
|
Use single or double quotes
|
|
T}
|
|
T{
|
|
In hledger\-web\[aq]s search form
|
|
T}@T{
|
|
Use single or double quotes
|
|
T}
|
|
T{
|
|
In an argument file
|
|
T}@T{
|
|
Don\[aq]t use spaces, don\[aq]t shell\-escape, do regex\-escape, write
|
|
one argument/option per line
|
|
T}
|
|
T{
|
|
In a config file
|
|
T}@T{
|
|
Use single or double quotes, and enclose the whole argument
|
|
(\f[CR]\[aq]desc:a b\[aq]\f[R] not \f[CR]desc:\[aq]a b\[aq]\f[R])
|
|
T}
|
|
T{
|
|
In \f[CR]ghci\f[R] (the Haskell REPL)
|
|
T}@T{
|
|
Use double quotes, and enclose the whole argument
|
|
T}
|
|
.TE
|
|
.SS Unicode characters
|
|
hledger is expected to handle non\-ascii characters correctly:
|
|
.IP \[bu] 2
|
|
they should be parsed correctly in input files and on the command line,
|
|
by all hledger tools (add, iadd, hledger\-web\[aq]s search/add/edit
|
|
forms, etc.)
|
|
.IP \[bu] 2
|
|
they should be displayed correctly by all hledger tools, and on\-screen
|
|
alignment should be preserved.
|
|
.PP
|
|
This requires a well\-configured environment.
|
|
Here are some tips:
|
|
.IP \[bu] 2
|
|
A system locale must be configured, which can decode the characters
|
|
being used.
|
|
This is essential \- see Text encoding and Install: Text encoding.
|
|
.IP \[bu] 2
|
|
Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
|
|
must support unicode.
|
|
On Windows, you may need to use Windows Terminal.
|
|
.IP \[bu] 2
|
|
The terminal must be using a font which includes the required unicode
|
|
glyphs.
|
|
.IP \[bu] 2
|
|
The terminal should be configured to display wide characters as double
|
|
width (for report alignment).
|
|
.IP \[bu] 2
|
|
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 standard 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).
|
|
.SS Regular expressions
|
|
A regular expression (regexp) is a small piece of text where certain
|
|
characters (like \f[CR].\f[R], \f[CR]\[ha]\f[R], \f[CR]$\f[R],
|
|
\f[CR]+\f[R], \f[CR]*\f[R], \f[CR]()\f[R], \f[CR]|\f[R], \f[CR][]\f[R],
|
|
\f[CR]\[rs]\f[R]) have special meanings, forming a tiny language for
|
|
matching text precisely \- very useful in hledger and elsewhere.
|
|
To learn all about them, visit regular\-expressions.info.
|
|
.PP
|
|
hledger supports regexps whenever you are entering a pattern to match
|
|
something, eg in query arguments, account aliases, CSV if rules,
|
|
hledger\-web\[aq]s search form, hledger\-ui\[aq]s \f[CR]/\f[R] search,
|
|
etc.
|
|
You may need to wrap them in quotes, especially at the command line (see
|
|
Special characters above).
|
|
Here are some examples:
|
|
.PP
|
|
Account name queries (quoted for command line use):
|
|
.IP
|
|
.EX
|
|
Regular expression: Matches:
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
bank assets:bank, assets:bank:savings, expenses:art:banksy, ...
|
|
:bank assets:bank:savings, expenses:art:banksy
|
|
:bank: assets:bank:savings
|
|
\[aq]\[ha]bank\[aq] none of those ( \[ha] matches beginning of text )
|
|
\[aq]bank$\[aq] assets:bank ( $ matches end of text )
|
|
\[aq]big \[rs]$ bank\[aq] big $ bank ( \[rs] disables following character\[aq]s special meaning )
|
|
\[aq]\[rs]bbank\[rs]b\[aq] assets:bank, assets:bank:savings ( \[rs]b matches word boundaries )
|
|
\[aq](sav|check)ing\[aq] saving or checking ( (|) matches either alternative )
|
|
\[aq]saving|checking\[aq] saving or checking ( outer parentheses are not needed )
|
|
\[aq]savings?\[aq] saving or savings ( ? matches 0 or 1 of the preceding thing )
|
|
\[aq]my +bank\[aq] my bank, my bank, ... ( + matches 1 or more of the preceding thing )
|
|
\[aq]my *bank\[aq] mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing )
|
|
\[aq]b.nk\[aq] bank, bonk, b nk, ... ( . matches any character )
|
|
.EE
|
|
.PP
|
|
Some other queries:
|
|
.IP
|
|
.EX
|
|
desc:\[aq]amazon|amzn|audible\[aq] Amazon transactions
|
|
cur:EUR amounts with commodity symbol containing EUR
|
|
cur:\[aq]\[rs]$\[aq] amounts with commodity symbol containing $
|
|
cur:\[aq]\[ha]\[rs]$$\[aq] only $ amounts, not eg AU$ or CA$
|
|
cur:....? amounts with 4\-or\-more\-character symbols
|
|
tag:.=202[1\-3] things with any tag whose value contains 2021, 2022 or 2023
|
|
.EE
|
|
.PP
|
|
Account name aliases: accept \f[CR].\f[R] instead of \f[CR]:\f[R] as
|
|
account separator:
|
|
.IP
|
|
.EX
|
|
alias /\[rs]./=: replaces all periods in account names with colons
|
|
.EE
|
|
.PP
|
|
Show multiple top\-level accounts combined as one:
|
|
.IP
|
|
.EX
|
|
\-\-alias=\[aq]/\[ha][\[ha]:]+/=combined\[aq] ( [\[ha]:] matches any character other than : )
|
|
.EE
|
|
.PP
|
|
Show accounts with the second\-level part removed:
|
|
.IP
|
|
.EX
|
|
\-\-alias \[aq]/\[ha]([\[ha]:]+):[\[ha]:]+/ = \[rs]1\[aq]
|
|
match a top\-level account and a second\-level account
|
|
and replace those with just the top\-level account
|
|
( \[rs]1 in the replacement text means \[dq]whatever was matched
|
|
by the first parenthesised part of the regexp\[dq]
|
|
.EE
|
|
.PP
|
|
CSV rules: match CSV records containing dining\-related MCC codes:
|
|
.IP
|
|
.EX
|
|
if \[rs]?MCC581[124]
|
|
.EE
|
|
.PP
|
|
Match CSV records with a specific amount around the end/start of month:
|
|
.IP
|
|
.EX
|
|
if %amount \[rs]b3\[rs].99
|
|
& %date (29|30|31|01|02|03)$
|
|
.EE
|
|
.SS hledger\[aq]s regular expressions
|
|
hledger\[aq]s regular expressions come from the regex\-tdfa library.
|
|
If they\[aq]re not doing what you expect, it\[aq]s important to know
|
|
exactly what they support:
|
|
.IP "1." 3
|
|
they are case insensitive
|
|
.IP "2." 3
|
|
they are infix matching (they do not need to match the entire thing
|
|
being matched)
|
|
.IP "3." 3
|
|
they are POSIX ERE (extended regular expressions)
|
|
.IP "4." 3
|
|
they also support GNU word boundaries (\f[CR]\[rs]b\f[R],
|
|
\f[CR]\[rs]B\f[R], \f[CR]\[rs]<\f[R], \f[CR]\[rs]>\f[R])
|
|
.IP "5." 3
|
|
backreferences are supported when doing text replacement in account
|
|
aliases or CSV rules, where backreferences can be used in the
|
|
replacement string to reference capturing groups in the search regexp.
|
|
Otherwise, if you write \f[CR]\[rs]1\f[R], it will match the digit
|
|
\f[CR]1\f[R].
|
|
.IP "6." 3
|
|
they do not support mode modifiers (\f[CR](?s)\f[R]), character classes
|
|
(\f[CR]\[rs]w\f[R], \f[CR]\[rs]d\f[R]), or anything else not mentioned
|
|
above.
|
|
.IP "7." 3
|
|
they may not (I\[aq]m guessing not) properly support right\-to\-left or
|
|
bidirectional text.
|
|
.PP
|
|
Some things to note:
|
|
.IP \[bu] 2
|
|
In the \f[CR]alias\f[R] directive and \f[CR]\-\-alias\f[R] option,
|
|
regular expressions must be enclosed in forward slashes
|
|
(\f[CR]/REGEX/\f[R]).
|
|
Elsewhere in hledger, these are not required.
|
|
.IP \[bu] 2
|
|
In queries, to match a regular expression metacharacter like
|
|
\f[CR]$\f[R] as a literal character, prepend a backslash.
|
|
Eg to search for amounts with the dollar sign in hledger\-web, write
|
|
\f[CR]cur:\[rs]$\f[R].
|
|
.IP \[bu] 2
|
|
On the command line, some metacharacters like \f[CR]$\f[R] have a
|
|
special meaning to the shell and so must be escaped at least once more.
|
|
See Special characters.
|
|
.SS Argument files
|
|
You can save a set of command line options and arguments in a file, and
|
|
then use them by writing \f[CR]\[at]FILE.args\f[R] as a hledger command
|
|
argument.
|
|
The \f[CR].args\f[R] file extension is conventional, but not required.
|
|
In an argument file,
|
|
.IP \[bu] 2
|
|
Each line can contain one argument, flag, or option.
|
|
.IP \[bu] 2
|
|
Blank lines or lines beginning with \f[CR]#\f[R] are ignored.
|
|
.IP \[bu] 2
|
|
An option\[aq]s flag and value should be joined by \f[CR]=\f[R].
|
|
.IP \[bu] 2
|
|
An option value or an argument may contain spaces.
|
|
Don\[aq]t use single or double quotes.
|
|
.IP \[bu] 2
|
|
And generally, use one less level of quoting/escaping than at the
|
|
command line.
|
|
Eg \f[CR]cur:\[rs]$\f[R], not \f[CR]cur:\[rs]\[rs]$\f[R] as on the
|
|
command line.
|
|
.PP
|
|
For example:
|
|
.IP
|
|
.EX
|
|
# cash.args
|
|
|
|
assets:cash
|
|
assets:charles schwab:sweep
|
|
cur:\[rs]$
|
|
\-c=$1.
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger bal \[at]cash.args
|
|
.EE
|
|
.SS Config files
|
|
With hledger 1.40+, you can save extra command line options and
|
|
arguments in a more featureful hledger config file.
|
|
Here\[aq]s a small example:
|
|
.IP
|
|
.EX
|
|
\f[I]# General options are listed first, and used with hledger commands that support them.\f[R]
|
|
\-\-pretty
|
|
|
|
\f[I]# Options following a \[ga][COMMAND]\[ga] heading are used with that hledger command only.\f[R]
|
|
\f[B][print]\f[R]
|
|
\-\-explicit \-\-infer\-costs
|
|
.EE
|
|
.PP
|
|
To use a config file, specify it with the \f[CR]\-\-conf\f[R] option.
|
|
Its options will be inserted near the start of your command line, so you
|
|
can override them with command line options if needed.
|
|
.PP
|
|
Or, you can set up an automatic config file that is used whenever you
|
|
run hledger, by creating \f[CR]hledger.conf\f[R] in the current
|
|
directory or above, or \f[CR].hledger.conf\f[R] in your home directory
|
|
(\f[CR]\[ti]/.hledger.conf\f[R]), or \f[CR]hledger.conf\f[R] in your XDG
|
|
config directory (\f[CR]\[ti]/.config/hledger/hledger.conf\f[R]).
|
|
.PP
|
|
Here is another example config you could start with:
|
|
https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
|
|
.PP
|
|
You can put not only options, but also arguments in a config file.
|
|
If the first word in a config file\[aq]s top (general) section does not
|
|
begin with a dash (eg: \f[CR]print\f[R]), it is treated as the command
|
|
argument (overriding any argument on the command line).
|
|
.PP
|
|
On unix machines, you can add a shebang line at the top of a config
|
|
file, set executable permission on the file, and use it like a script.
|
|
Eg (the \f[CR]\-S\f[R] is needed on some operating systems):
|
|
.IP
|
|
.EX
|
|
#!/usr/bin/env \-S hledger \-\-conf
|
|
.EE
|
|
.PP
|
|
You can ignore config files by adding the
|
|
\f[CR]\-n\f[R]/\f[CR]\-\-no\-conf\f[R] flag to the command line.
|
|
This is useful when using hledger in scripts, or when troubleshooting.
|
|
When both \f[CR]\-\-conf\f[R] and \f[CR]\-\-no\-conf\f[R] options are
|
|
used, the right\-most wins.
|
|
.PP
|
|
To inspect the processing of config files, use \f[CR]\-\-debug\f[R] or
|
|
\f[CR]\-\-debug=8\f[R].
|
|
Or, run the \f[CR]setup\f[R] command, which will display any active
|
|
config files.
|
|
(\f[CR]setup\f[R] is not affected by config files itself, unlike other
|
|
commands.)
|
|
.PP
|
|
\f[B]Warning!\f[R]
|
|
.PP
|
|
There aren\[aq]t many hledger features that need a warning, but this is
|
|
one!
|
|
.PP
|
|
Automatic config files, while convenient, also make hledger less
|
|
predictable and dependable.
|
|
It\[aq]s easy to make a config file that changes a report\[aq]s
|
|
behaviour, or breaks your hledger\-using scripts/applications, in ways
|
|
that will surprise you later.
|
|
.PP
|
|
If you don\[aq]t want this,
|
|
.IP "1." 3
|
|
Just don\[aq]t create a hledger.conf file on your machine.
|
|
.IP "2." 3
|
|
Also be alert to downloaded directories which may contain a hledger.conf
|
|
file.
|
|
.IP "3." 3
|
|
Also if you are sharing scripts or examples or support, consider that
|
|
others may have a hledger.conf file.
|
|
.PP
|
|
Conversely, once you decide to use this feature, try to remember:
|
|
.IP "1." 3
|
|
Whenever a hledger command does not work as expected, try it again with
|
|
\f[CR]\-n\f[R] (\f[CR]\-\-no\-conf\f[R]) to see if a config file was to
|
|
blame.
|
|
.IP "2." 3
|
|
Whenever you call hledger from a script, consider whether that call
|
|
should use \f[CR]\-n\f[R] or not.
|
|
.IP "3." 3
|
|
Be conservative about what you put in your config file; try to consider
|
|
the effect on all your reports.
|
|
.IP "4." 3
|
|
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.
|
|
.SS Shell completions
|
|
If you use the bash or zsh shells, you can optionally set up
|
|
context\-sensitive autocompletion for hledger command lines.
|
|
Try pressing \f[CR]hledger<SPACE><TAB><TAB>\f[R] (should list all
|
|
hledger commands) or \f[CR]hledger reg acct:<TAB><TAB>\f[R] (should list
|
|
your top\-level account names).
|
|
If completions aren\[aq]t working, or for more details, see Install >
|
|
Shell completions.
|
|
.SH Output
|
|
.SS Output destination
|
|
hledger commands send their output to the terminal by default.
|
|
You can of course redirect this, eg into a file, using standard shell
|
|
syntax:
|
|
.IP
|
|
.EX
|
|
$ hledger print > foo.txt
|
|
.EE
|
|
.PP
|
|
Some commands (print, register, stats, the balance commands) also
|
|
provide the \f[CR]\-o\f[R]/\f[CR]\-\-output\-file\f[R] option, which
|
|
does the same thing without needing the shell.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-o foo.txt
|
|
$ hledger print \-o \- # write to stdout (the default)
|
|
.EE
|
|
.SS Output format
|
|
Some commands offer other kinds of output, not just text on the
|
|
terminal.
|
|
Here are those commands and the formats currently supported:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(20.6n) lw(5.1n) lw(6.2n) lw(9.3n) lw(6.2n) lw(11.3n) lw(5.1n) lw(6.2n).
|
|
T{
|
|
command
|
|
T}@T{
|
|
txt
|
|
T}@T{
|
|
html
|
|
T}@T{
|
|
csv/tsv
|
|
T}@T{
|
|
fods
|
|
T}@T{
|
|
beancount
|
|
T}@T{
|
|
sql
|
|
T}@T{
|
|
json
|
|
T}
|
|
_
|
|
T{
|
|
aregister
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
balance
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
balancesheet
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
balancesheetequity
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
cashflow
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
incomestatement
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
print
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
register
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
Y
|
|
T}
|
|
.TE
|
|
.PP
|
|
You can also see which output formats a command supports by running
|
|
\f[CR]hledger CMD \-h\f[R] and looking for the
|
|
\f[CR]\-O\f[R]/\f[CR]\-\-output\-format=FMT\f[R] option,
|
|
.PP
|
|
You can select the output format by using that option:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-O csv # print CSV to standard output
|
|
.EE
|
|
.PP
|
|
or by choosing a suitable filename extension with the
|
|
\f[CR]\-o\f[R]/\f[CR]\-\-output\-file=FILE.FMT\f[R] option:
|
|
.IP
|
|
.EX
|
|
$ hledger balancesheet \-o foo.csv # write CSV to foo.csv
|
|
.EE
|
|
.PP
|
|
The \f[CR]\-O\f[R] option can be combined with \f[CR]\-o\f[R] to
|
|
override the file extension if needed:
|
|
.IP
|
|
.EX
|
|
$ hledger balancesheet \-o foo.txt \-O csv # write CSV to foo.txt
|
|
.EE
|
|
.PP
|
|
Here are some notes about the various output formats.
|
|
.SS Text output
|
|
This is the default: human readable, plain text report output, suitable
|
|
for viewing with a monospace font in a terminal.
|
|
If your data contains unicode or wide characters, you\[aq]ll need a
|
|
terminal and font that render those correctly.
|
|
(This can be challenging on MS Windows.)
|
|
.PP
|
|
Some reports (\f[CR]register\f[R], \f[CR]aregister\f[R]) will normally
|
|
use the full window width.
|
|
If this isn\[aq]t working or you want to override it, you can use the
|
|
\f[CR]\-w\f[R]/\f[CR]\-\-width\f[R] option.
|
|
.PP
|
|
Balance reports (\f[CR]balance\f[R], \f[CR]balancesheet\f[R],
|
|
\f[CR]incomestatement\f[R]...)
|
|
use whatever width they need.
|
|
Multi\-period multi\-currency reports can often be wider than the
|
|
window.
|
|
Besides using a pager, helpful techniques for this situation include
|
|
\f[CR]\-\-layout=bare\f[R], \f[CR]\-V\f[R], \f[CR]cur:\f[R],
|
|
\f[CR]\-\-transpose\f[R], \f[CR]\-\-tree\f[R], \f[CR]\-\-depth\f[R],
|
|
\f[CR]\-\-drop\f[R], switching to html output, etc.
|
|
.SS Box\-drawing characters
|
|
hledger draws simple table borders by default, to minimise the risk of
|
|
display problems caused by a terminal/font not supporting box\-drawing
|
|
characters.
|
|
.PP
|
|
But your terminal and font probably do support them, so we recommend
|
|
using the \f[CR]\-\-pretty\f[R] flag to show prettier tables in the
|
|
terminal.
|
|
This is a good flag to add to your hledger config file.
|
|
.SS Colour
|
|
hledger tries to automatically detect ANSI colour and text styling
|
|
support and use it when appropriate.
|
|
(Currently, it is used rather minimally: some reports show negative
|
|
numbers in red, and help output uses bold text for emphasis.)
|
|
.PP
|
|
You can override this by setting the \f[CR]NO_COLOR\f[R] environment
|
|
variable to disable it, or by using the \f[CR]\-\-color/\-\-colour\f[R]
|
|
option, perhaps in your config file, with a \f[CR]y\f[R]/\f[CR]yes\f[R]
|
|
or \f[CR]n\f[R]/\f[CR]no\f[R] value to force it on or off.
|
|
.SS Paging
|
|
In unix\-like environments, when displaying large output (in any output
|
|
format) in the terminal, hledger tries to use a pager when appropriate.
|
|
(You can disable this with the \f[CR]\-\-pager=no\f[R] option, perhaps
|
|
in your config file.)
|
|
.PP
|
|
The pager shows one page of text at a time, and lets you scroll around
|
|
to see more.
|
|
While it is active, usually \f[CR]SPACE\f[R] shows the next page,
|
|
\f[CR]h\f[R] shows help, and \f[CR]q\f[R] quits.
|
|
The home/end/page up/page down/cursor keys, and mouse scrolling, may
|
|
also work.
|
|
.PP
|
|
hledger will use the pager specified by the \f[CR]PAGER\f[R] environment
|
|
variable, otherwise \f[CR]less\f[R] if available, otherwise
|
|
\f[CR]more\f[R] if available.
|
|
(With one exception: \f[CR]hledger help \-p TOPIC\f[R] will always use
|
|
\f[CR]less\f[R], so that it can scroll to the topic.)
|
|
.PP
|
|
The pager is expected to display hledger\[aq]s ANSI colour and text
|
|
styling.
|
|
If you see junk characters, you might need to configure your pager to
|
|
handle ANSI codes.
|
|
Or you could disable colour as described above.
|
|
.PP
|
|
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 \-\-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
|
|
\f[CR]HLEDGER_LESS\f[R] variable, which will be used instead.
|
|
.SS HTML output
|
|
HTML output can be styled by an optional \f[CR]hledger.css\f[R] file in
|
|
the same directory.
|
|
.PP
|
|
HTML output will be a HTML fragment, not a complete HTML document.
|
|
Like other hledger output, for non\-ascii characters it will use the
|
|
system locale\[aq]s text encoding (see Text encoding).
|
|
.SS CSV / TSV output
|
|
In CSV or TSV output, digit group marks (such as thousands separators)
|
|
are disabled automatically.
|
|
.SS FODS output
|
|
FODS is the OpenDocument Spreadsheet format as plain XML, as accepted by
|
|
LibreOffice and OpenOffice.
|
|
If you use their spreadsheet applications, this is better than CSV
|
|
because it works across locales (decimal point vs.
|
|
decimal comma, character encoding stored in XML header, thus no problems
|
|
with umlauts), it supports fixed header rows and columns, cell types
|
|
(string vs.
|
|
number vs.
|
|
date), separation of number and currency (currency is displayed but the
|
|
cell type is still a number accessible for computation), styles (bold),
|
|
borders.
|
|
Btw.
|
|
you can still extract CSV from FODS/ODS using various utilities like
|
|
\f[CR]libreoffice \-\-headless\f[R] or ods2csv.
|
|
.SS Beancount output
|
|
This is Beancount\[aq]s journal format.
|
|
You can use this to export your hledger data to Beancount, eg to use the
|
|
Fava web app.
|
|
.PP
|
|
hledger will try to adjust your data to suit Beancount, automatically.
|
|
Be cautious and check the conversion until you are confident it is good.
|
|
If you plan to export to Beancount often, you may want to follow its
|
|
conventions, for a cleaner conversion:
|
|
.IP \[bu] 2
|
|
use Beancount\-friendly account names
|
|
.IP \[bu] 2
|
|
use currency codes instead of currency symbols
|
|
.IP \[bu] 2
|
|
use cost notation instead of equity conversion postings
|
|
.IP \[bu] 2
|
|
avoid virtual postings, balance assignments, and secondary dates.
|
|
.PP
|
|
There is one big adjustment you must handle yourself: for Beancount, the
|
|
top level account names must be \f[CR]Assets\f[R],
|
|
\f[CR]Liabilities\f[R], \f[CR]Equity\f[R], \f[CR]Income\f[R], and/or
|
|
\f[CR]Expenses\f[R].
|
|
You can use account aliases to rewrite your account names temporarily,
|
|
if needed, as in this hledger2beancount.conf config file.
|
|
.PP
|
|
2024\-12\-20: Some more things not yet handled for you:
|
|
.IP \[bu] 2
|
|
P directives are not converted automatically \- convert those yourself.
|
|
.IP \[bu] 2
|
|
Balance assignments are not converted (Beancount doesn\[aq]t support
|
|
them) \- replace those with explicit amounts.
|
|
.SS Beancount account names
|
|
Aside from the top\-level names, hledger will adjust your account names
|
|
to make valid Beancount account names, by capitalising each part,
|
|
replacing spaces with \f[CR]\-\f[R], replacing other unsupported
|
|
characters with \f[CR]C<HEXBYTES>\f[R], prepending \f[CR]A\f[R] to
|
|
account name parts which don\[aq]t begin with a letter or digit, and
|
|
appending \f[CR]:A\f[R] to account names which have only one part.
|
|
.SS Beancount commodity names
|
|
hledger will adjust your commodity names to make valid Beancount
|
|
commodity/currency names, which must be 2\-24 uppercase letters, digits,
|
|
or \f[CR]\[aq]\f[R], \f[CR].\f[R], \f[CR]_\f[R], \f[CR]\-\f[R],
|
|
beginning with a letter and ending with a letter or digit.
|
|
hledger will convert known currency symbols to ISO 4217 currency codes,
|
|
capitalise letters, replace spaces with \f[CR]\-\f[R], replace other
|
|
unsupported characters with \f[CR]C<HEXBYTES>\f[R], and prepend or
|
|
append \f[CR]C\f[R] if needed.
|
|
.SS Beancount virtual postings
|
|
Beancount doesn\[aq]t allow virtual postings; if you have any, they will
|
|
be omitted from beancount output.
|
|
.SS Beancount metadata
|
|
hledger tags will be converted to Beancount metadata (except for tags
|
|
whose name begins with \f[CR]_\f[R]).
|
|
Metadata names will be adjusted to be Beancount\-compatible: beginning
|
|
with a lowercase letter, at least two characters long, and with
|
|
unsupported characters encoded.
|
|
Metadata values will use Beancount\[aq]s string type.
|
|
.PP
|
|
In hledger, objects can have the same tag repeated with multiple values.
|
|
Eg an \f[CR]assets:cash\f[R] account might have both
|
|
\f[CR]type:Asset\f[R] and \f[CR]type:Cash\f[R] tags.
|
|
For Beancount these will be combined into one, with the values combined,
|
|
comma separated.
|
|
Eg: \f[CR]type: \[dq]Asset, Cash\[dq]\f[R].
|
|
.SS Beancount costs
|
|
Beancount doesn\[aq]t allow redundant costs and conversion postings as
|
|
hledger does.
|
|
If you have any of these, the conversion postings will be omitted.
|
|
Currently we support at most one cost + conversion postings group per
|
|
transaction.
|
|
.SS Beancount operating currency
|
|
Declaring an operating currency (or several) improves Beancount and Fava
|
|
reports.
|
|
Currently hledger will declare each currency used in cost amounts as an
|
|
operating currency.
|
|
If needed, replace these with your own declaration, like
|
|
.IP
|
|
.EX
|
|
option \[dq]operating_currency\[dq] \[dq]USD\[dq]
|
|
.EE
|
|
.SS SQL output
|
|
SQL output is expected to work at least with SQLite, MySQL and Postgres.
|
|
.PP
|
|
The SQL statements are expected to be executed in the empty database.
|
|
If you already have tables created via SQL output of hledger, you would
|
|
probably want to either clear data from these (via \f[CR]delete\f[R] or
|
|
\f[CR]truncate\f[R] SQL statements) or \f[CR]drop\f[R] the tables
|
|
completely before import; otherwise your postings would be duplicated.
|
|
.PP
|
|
For SQLite, it is more useful if you modify the generated \f[CR]id\f[R]
|
|
field to be a PRIMARY KEY.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-O sql | sed \[aq]s/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g\[aq] | ...
|
|
.EE
|
|
.PP
|
|
This is not yet much used; feedback is welcome.
|
|
.SS JSON output
|
|
Our JSON is rather large and verbose, since it is a faithful
|
|
representation of hledger\[aq]s internal data types.
|
|
To understand its structure, read the Haskell type definitions, which
|
|
are mostly in
|
|
https://github.com/simonmichael/hledger/blob/master/hledger\-lib/Hledger/Data/Types.hs.
|
|
hledger\-web\[aq]s OpenAPI specification may also be relevant.
|
|
.PP
|
|
hledger stores numbers with sometimes up to 255 significant digits.
|
|
This is too many digits for most JSON consumers, so in JSON output we
|
|
round numbers to at most 10 decimal places.
|
|
(We don\[aq]t limit the number of integer digits.)
|
|
If you find this causing problems, please let us know.
|
|
Related: #1195
|
|
.PP
|
|
This is not yet much used; feedback is welcome.
|
|
.SS Commodity styles
|
|
When displaying amounts, hledger infers a standard display style for
|
|
each commodity/currency, as described below in Commodity display style.
|
|
.PP
|
|
If needed, this can be overridden by a
|
|
\f[CR]\-c/\-\-commodity\-style\f[R] option (except for cost amounts and
|
|
amounts displayed by the \f[CR]print\f[R] command, which are always
|
|
displayed with all decimal digits).
|
|
For example, the following will force dollar amounts to be displayed as
|
|
shown:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-c \[aq]$1.000,0\[aq]
|
|
.EE
|
|
.PP
|
|
This option can be repeated to set the display style for multiple
|
|
commodities/currencies.
|
|
Its argument is as described in the commodity directive.
|
|
Note that omitting the commodity symbol will set the display style for
|
|
just the no\-symbol commodity, not all commodities.
|
|
.PP
|
|
In some cases hledger will adjust number formatting to improve their
|
|
parseability (such as adding trailing decimal marks when needed).
|
|
.SS Debug output
|
|
We intend hledger to be relatively easy to troubleshoot, introspect and
|
|
develop.
|
|
You can add \f[CR]\-\-debug[=N]\f[R] to any hledger command line to see
|
|
additional debug output.
|
|
N ranges from 1 (least output, the default) to 9 (maximum output).
|
|
Typically you would start with 1 and increase until you are seeing
|
|
enough.
|
|
Debug output goes to stderr, and is not affected by
|
|
\f[CR]\-o/\-\-output\-file\f[R] (unless you redirect stderr to stdout,
|
|
eg: \f[CR]2>&1\f[R]).
|
|
It will be interleaved with normal output, which can help reveal when
|
|
parts of the code are evaluated.
|
|
To capture debug output in a log file instead, you can usually redirect
|
|
stderr, eg:
|
|
.IP
|
|
.EX
|
|
hledger bal \-\-debug=3 2>hledger.log
|
|
.EE
|
|
.PP
|
|
(This option doesn\[aq]t work in a config file yet.)
|
|
.SH Environment
|
|
These environment variables affect hledger:
|
|
.PP
|
|
\f[B]HLEDGER_LESS\f[R] If \f[CR]less\f[R] is your pager, this variable
|
|
specifies the \f[CR]less\f[R] options hledger should use.
|
|
(Otherwise, \f[CR]LESS\f[R] + custom options are used.)
|
|
.PP
|
|
\f[B]LEDGER_FILE\f[R] The main journal file to use when not specified
|
|
with \f[CR]\-f/\-\-file\f[R].
|
|
Default: \f[CR]$HOME/.hledger.journal\f[R].
|
|
.PP
|
|
\f[B]NO_COLOR\f[R] If this environment variable exists (with any value,
|
|
including empty), hledger will not use ANSI color codes in terminal
|
|
output, unless overridden by an explicit \f[CR]\-\-color=y\f[R] or
|
|
\f[CR]\-\-colour=y\f[R] option.
|
|
.SH PART 2: DATA FORMATS
|
|
.SH Journal
|
|
hledger\[aq]s usual data source is a plain text file containing journal
|
|
entries in hledger \f[CR]journal\f[R] format.
|
|
If you\[aq]re looking for a quick reference, jump ahead to the journal
|
|
cheatsheet (or use the table of contents at
|
|
https://hledger.org/hledger.html).
|
|
.PP
|
|
This file represents an accounting General Journal.
|
|
The \f[CR].journal\f[R] file extension is most often used, though not
|
|
strictly required.
|
|
The journal file contains a number of transaction entries, each
|
|
describing a transfer of money (or any commodity) between two or more
|
|
named accounts, in a simple format readable by both hledger and humans.
|
|
.PP
|
|
hledger\[aq]s journal format is compatible with most of Ledger\[aq]s
|
|
journal format, but not all of it.
|
|
The differences and interoperation tips are described at hledger and
|
|
Ledger.
|
|
With some care, and by avoiding incompatible features, you can keep your
|
|
hledger journal readable by Ledger and vice versa.
|
|
This can useful eg for comparing the behaviour of one app against the
|
|
other.
|
|
.PP
|
|
You can use hledger without learning any more about this file; just use
|
|
the add or web or import commands to create and update it.
|
|
.PP
|
|
Many users, though, edit the journal file with a text editor, and track
|
|
changes with a version control system such as git.
|
|
Editor add\-ons such as ledger\-mode or hledger\-mode for Emacs,
|
|
vim\-ledger for Vim, and hledger\-vscode for Visual Studio Code, make
|
|
this easier, adding colour, formatting, tab completion, and useful
|
|
commands.
|
|
See Editors at hledger.org for the full list.
|
|
.PP
|
|
A hledger journal file can contain three kinds of thing: comment lines,
|
|
transactions, and/or directives (including periodic transaction rules
|
|
and auto posting rules).
|
|
Understanding the journal file format will also give you a good
|
|
understanding of hledger\[aq]s data model.
|
|
Here\[aq]s a quick cheatsheet/overview, followed by detailed
|
|
descriptions of each part.
|
|
.SS Journal cheatsheet
|
|
.IP
|
|
.EX
|
|
# Here is the main syntax of hledger\[aq]s journal format
|
|
# (omitting extra Ledger compatibility syntax).
|
|
|
|
###############################################################################
|
|
|
|
# 1. These are comment lines, for notes or temporarily disabling things.
|
|
; They begin with # or ;
|
|
|
|
comment
|
|
Or, lines can be enclosed within \[dq]comment\[dq] / \[dq]end comment\[dq].
|
|
This is a block of
|
|
commented lines.
|
|
end comment
|
|
|
|
# Some journal entries can have semicolon comments at end of line ; like this
|
|
# Some of them require 2 or more spaces before the semicolon.
|
|
|
|
###############################################################################
|
|
|
|
# 2. Directives customise processing or output in some way.
|
|
# You don\[aq]t need any directives to get started.
|
|
# But they can add more error checking, or change how things are displayed.
|
|
# They begin with a word, letter, or symbol.
|
|
# They are most often placed at the top, before transactions.
|
|
|
|
account assets ; Declare valid account names and display order.
|
|
account assets:savings ; A subaccount. This one represents a bank account.
|
|
account assets:checking ; Another. Note, 2+ spaces after the account name.
|
|
account assets:receivable ; Accounting type is inferred from english names,
|
|
account passifs ; or declared with a \[dq]type\[dq] tag, type:L
|
|
account expenses ; type:X
|
|
; A follow\-on comment line, indented.
|
|
account expenses:rent ; Expense and revenue categories are also accounts.
|
|
; Subaccounts inherit their parent\[aq]s type.
|
|
|
|
commodity $0.00 ; Declare valid commodities and their display styles.
|
|
commodity 1.000,00 EUR
|
|
|
|
decimal\-mark . ; The decimal mark used in this file (if ambiguous).
|
|
|
|
payee Whole Foods ; Declare a valid payee name.
|
|
|
|
tag trip ; Declare a valid tag name.
|
|
|
|
P 2024\-03\-01 AAPL $179 ; Declare a market price for AAPL in $ on this date.
|
|
|
|
include other.journal ; Include another journal file here.
|
|
|
|
# Declare a recurring \[dq]periodic transaction\[dq], for budget/forecast reports
|
|
\[ti] monthly set budget goals ; <\- Note, 2+ spaces before the description.
|
|
(expenses:rent) $1000
|
|
(expenses:food) $500
|
|
|
|
# Declare an auto posting rule, to modify existing transactions in reports
|
|
= revenues:consulting
|
|
liabilities:tax:2024:us *0.25 ; Add a tax liability & expense
|
|
expenses:tax:2024:us *\-0.25 ; for 25% of the revenue.
|
|
|
|
###############################################################################
|
|
|
|
# 3. Transactions are what it\[aq]s all about.
|
|
# They are dated events, usually movements of money between 2 or more accounts.
|
|
# They begin with a numeric date.
|
|
# Here is their basic shape:
|
|
#
|
|
# DATE DESCRIPTION ; The transaction\[aq]s date and optional description.
|
|
# ACCOUNT1 AMOUNT ; A posting of an amount to/from this account, indented.
|
|
# ACCOUNT2 AMOUNT ; A second posting, balancing the first.
|
|
# ... ; More if needed. Amounts must sum to zero.
|
|
# ; Note, 2+ spaces between account names and amounts.
|
|
|
|
2024\-01\-01 opening balances ; At the start, declare pre\-existing balances this way.
|
|
assets:savings $10000 ; Account names can be anything. lower case is easy to type.
|
|
assets:checking $1000 ; assets, liabilities, equity, revenues, expenses are common.
|
|
liabilities:credit card $\-500 ; liabilities, equity, revenues balances are usually negative.
|
|
equity:start ; One amount can be left blank. $\-10500 is inferred here.
|
|
; Some of these accounts we didn\[aq]t declare above,
|
|
; so \-s/\-\-strict would complain.
|
|
|
|
2024\-01\-03 ! (12345) pay rent
|
|
; Additional transaction comment lines, indented.
|
|
; There can be a ! or * after the date meaning \[dq]pending\[dq] or \[dq]cleared\[dq].
|
|
; There can be a parenthesised (code) after the date/status.
|
|
; Amounts\[aq] sign shows direction of flow.
|
|
assets:checking $\-500 ; Minus means removed from this account (credit).
|
|
expenses:rent $500 ; Plus means added to this account (debit).
|
|
|
|
; Keeping transactions in date order is optional (but helps error checking).
|
|
|
|
2024\-01\-02 Gringott\[aq]s Bank | withdrawal ; Description can be PAYEE | NOTE
|
|
assets:bank:gold \-10 gold
|
|
assets:pouch 10 gold
|
|
|
|
2024\-01\-02 shopping
|
|
expenses:clothing 1 gold
|
|
expenses:wands 5 gold
|
|
assets:pouch \-6 gold
|
|
|
|
2024\-01\-02 receive gift
|
|
revenues:gifts \-3 \[dq]Chocolate Frogs\[dq] ; Complex commodity symbols
|
|
assets:pouch 3 \[dq]Chocolate Frogs\[dq] ; must be in double quotes.
|
|
|
|
2024\-01\-15 buy some shares, in two lots ; Cost can be noted.
|
|
assets:investments:2024\-01\-15 2.0 AAAA \[at] $1.50 ; \[at] means per\-unit cost
|
|
assets:investments:2024\-01\-15\-02 3.0 AAAA \[at]\[at] $4 ; \[at]\[at] means total cost
|
|
; \[ha] Per\-lot subaccounts are sometimes useful.
|
|
assets:checking $\-7
|
|
|
|
2024\-01\-15 assert some account balances on this date
|
|
; Balances can be asserted in any transaction, with =, for extra error checking.
|
|
; Assertion txns like this one can be made with hledger close \-\-assert \-\-show\-costs
|
|
;
|
|
assets:savings $0 = $10000
|
|
assets:checking $0 = $493
|
|
assets:bank:gold 0 gold = \-10 gold
|
|
assets:pouch 0 gold = 4 gold
|
|
assets:pouch 0 \[dq]Chocolate Frogs\[dq] = 3 \[dq]Chocolate Frogs\[dq]
|
|
assets:investments:2024\-01\-15 0.0 AAAA = 2.0 AAAA \[at] $1.50
|
|
assets:investments:2024\-01\-15\-02 0.0 AAAA = 3.0 AAAA \[at]\[at] $4
|
|
liabilities:credit card $0 = $\-500
|
|
|
|
2024\-02\-01 note some event, or a transaction not yet fully entered, on this date
|
|
; Postings are not required.
|
|
|
|
# Consistent YYYY\-MM\-DD date format is recommended,
|
|
# but you can use . or / and omit leading zeros if you prefer.
|
|
2024.01.01
|
|
2024/1/1
|
|
.EE
|
|
.SS Comments
|
|
Lines in the journal will be ignored if they begin with a hash
|
|
(\f[CR]#\f[R]) or a semicolon (\f[CR];\f[R]).
|
|
(See also Other syntax.)
|
|
hledger will also ignore regions beginning with a \f[CR]comment\f[R]
|
|
line and ending with an \f[CR]end comment\f[R] line (or file end).
|
|
Here\[aq]s a suggestion for choosing between them:
|
|
.IP \[bu] 2
|
|
\f[CR]#\f[R] for top\-level notes
|
|
.IP \[bu] 2
|
|
\f[CR];\f[R] for commenting out things temporarily
|
|
.IP \[bu] 2
|
|
\f[CR]comment\f[R] for quickly commenting large regions (remember
|
|
it\[aq]s there, or you might get confused)
|
|
.PP
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
# a comment line
|
|
; another commentline
|
|
comment
|
|
A multi\-line comment block,
|
|
continuing until \[dq]end comment\[dq] directive
|
|
or the end of the current file.
|
|
end comment
|
|
.EE
|
|
.PP
|
|
Some hledger entries can have same\-line comments attached to them, from
|
|
; (semicolon) to end of line.
|
|
See Transaction comments, Posting comments, and Account comments below.
|
|
.SS Transactions
|
|
Transactions are the main unit of information in a journal file.
|
|
They represent events, typically a movement of some quantity of
|
|
commodities between two or more named accounts.
|
|
.PP
|
|
Each transaction is recorded as a journal entry, beginning with a simple
|
|
date in column 0.
|
|
This can be followed by any of the following optional fields, separated
|
|
by spaces:
|
|
.IP \[bu] 2
|
|
a status character (empty, \f[CR]!\f[R], or \f[CR]*\f[R])
|
|
.IP \[bu] 2
|
|
a code (any short number or text, enclosed in parentheses)
|
|
.IP \[bu] 2
|
|
a description (any remaining text until end of line or a semicolon)
|
|
.IP \[bu] 2
|
|
a comment (any remaining text following a semicolon until end of line,
|
|
and any following indented lines beginning with a semicolon)
|
|
.IP \[bu] 2
|
|
0 or more indented \f[I]posting\f[R] lines, describing what was
|
|
transferred and the accounts involved (indented comment lines are also
|
|
allowed, but not blank lines or non\-indented lines).
|
|
.PP
|
|
Here\[aq]s a simple journal file containing one transaction:
|
|
.IP
|
|
.EX
|
|
2008/01/01 income
|
|
assets:bank:checking $1
|
|
income:salary $\-1
|
|
.EE
|
|
.SS Dates
|
|
.SS Simple dates
|
|
Dates in the journal file use \f[I]simple dates\f[R] format:
|
|
\f[CR]YYYY\-MM\-DD\f[R] or \f[CR]YYYY/MM/DD\f[R] or
|
|
\f[CR]YYYY.MM.DD\f[R], with leading zeros optional.
|
|
The year may be omitted, in which case it will be inferred from the
|
|
context: the current transaction, the default year set with a
|
|
\f[CR]Y\f[R] directive, or the current date when the command is run.
|
|
Some examples: \f[CR]2010\-01\-31\f[R], \f[CR]2010/01/31\f[R],
|
|
\f[CR]2010.1.31\f[R], \f[CR]1/31\f[R].
|
|
.PP
|
|
(The UI also accepts simple dates, as well as the more flexible smart
|
|
dates documented in the hledger manual.)
|
|
.SS Posting dates
|
|
You can give individual postings a different date from their parent
|
|
transaction, by adding a posting comment containing a tag (see below)
|
|
like \f[CR]; date:DATE\f[R].
|
|
(There\[aq]s also a Ledger\-compatible syntax, \f[CR]; [DATE]\f[R],
|
|
which can be convenient.)
|
|
.PP
|
|
This is probably the best way to control posting dates precisely.
|
|
Eg in this example the expense should appear in May reports, and the
|
|
deduction from checking should be reported on 6/1 for easy bank
|
|
reconciliation:
|
|
.IP
|
|
.EX
|
|
2015/5/30
|
|
expenses:food $10 ; food purchased on saturday 5/30
|
|
assets:checking ; bank cleared it on monday, date:6/1
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f t.j register food
|
|
2015\-05\-30 expenses:food $10 $10
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f t.j register checking
|
|
2015\-06\-01 assets:checking $\-10 $\-10
|
|
.EE
|
|
.PP
|
|
DATE should be a simple date; if the year is not specified it will use
|
|
the year of the transaction\[aq]s date.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
The \f[CR]date:\f[R] tag must have a valid simple date value if it is
|
|
present, eg a \f[CR]date:\f[R] tag with no value is not allowed.
|
|
.SS Status
|
|
Transactions (or individual postings within a transaction) can have a
|
|
status mark, which is a single character before the transaction
|
|
description (or posting account name), separated from it by a space,
|
|
indicating one of three statuses:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
mark \
|
|
T}@T{
|
|
status
|
|
T}
|
|
_
|
|
T{
|
|
\
|
|
T}@T{
|
|
unmarked
|
|
T}
|
|
T{
|
|
\f[CR]!\f[R]
|
|
T}@T{
|
|
pending
|
|
T}
|
|
T{
|
|
\f[CR]*\f[R]
|
|
T}@T{
|
|
cleared
|
|
T}
|
|
.TE
|
|
.PP
|
|
When reporting, you can filter by status with the
|
|
\f[CR]\-U/\-\-unmarked\f[R], \f[CR]\-P/\-\-pending\f[R], and
|
|
\f[CR]\-C/\-\-cleared\f[R] flags (and you can combine these, eg
|
|
\f[CR]\-UP\f[R] to match all except cleared things).
|
|
Or you can use the \f[CR]status:\f[R], \f[CR]status:!\f[R], and
|
|
\f[CR]status:*\f[R] queries, or the U, P, C keys in hledger\-ui.
|
|
.PP
|
|
(Note: in Ledger the \[dq]unmarked\[dq] state is called
|
|
\[dq]uncleared\[dq]; in hledger we renamed it to \[dq]unmarked\[dq] for
|
|
semantic clarity.)
|
|
.PP
|
|
Status marks are optional, but can be helpful eg for reconciling with
|
|
real\-world accounts.
|
|
Some editor modes provide highlighting and shortcuts for working with
|
|
status.
|
|
Eg in Emacs ledger\-mode, you can toggle transaction status with C\-c
|
|
C\-e, or posting status with C\-c C\-c.
|
|
.PP
|
|
What \[dq]uncleared\[dq], \[dq]pending\[dq], and \[dq]cleared\[dq]
|
|
actually mean is up to you.
|
|
Here\[aq]s one suggestion:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(9.7n) lw(60.3n).
|
|
T{
|
|
status
|
|
T}@T{
|
|
meaning
|
|
T}
|
|
_
|
|
T{
|
|
uncleared
|
|
T}@T{
|
|
recorded but not yet reconciled; needs review
|
|
T}
|
|
T{
|
|
pending
|
|
T}@T{
|
|
tentatively reconciled (if needed, eg during a big reconciliation)
|
|
T}
|
|
T{
|
|
cleared
|
|
T}@T{
|
|
complete, reconciled as far as possible, and considered correct
|
|
T}
|
|
.TE
|
|
.PP
|
|
With this scheme, you would use \f[CR]\-PC\f[R] to see the current
|
|
balance at your bank, \f[CR]\-U\f[R] to see things which will probably
|
|
hit your bank soon (like uncashed checks), and no flags to see the most
|
|
up\-to\-date state of your finances.
|
|
.SS Code
|
|
After the status mark, but before the description, you can optionally
|
|
write a transaction \[dq]code\[dq], enclosed in parentheses.
|
|
This is a good place to record a check number, or some other important
|
|
transaction id or reference number.
|
|
.SS Description
|
|
After the date, status mark and/or code fields, the rest of the line (or
|
|
until a comment is begun with \f[CR];\f[R]) is the transaction\[aq]s
|
|
description.
|
|
Here you can describe the transaction (called the \[dq]narration\[dq] in
|
|
traditional bookkeeping), or you can record a payee/payer name, or you
|
|
can leave it empty.
|
|
.PP
|
|
Transaction descriptions show up in print output and in register
|
|
reports, and can be listed with the descriptions command.
|
|
.PP
|
|
You can query by description with \f[CR]desc:DESCREGEX\f[R], or pivot on
|
|
description with \f[CR]\-\-pivot desc\f[R].
|
|
.SS Payee and note
|
|
Sometimes people want a dedicated payee/payer field that can be queried
|
|
and checked more strictly.
|
|
If you want that, you can write a \f[CR]|\f[R] (pipe) character in the
|
|
description.
|
|
This divides it into a \[dq]payee\[dq] field on the left, and a
|
|
\[dq]note\[dq] field on the right.
|
|
(Either can be empty.)
|
|
.PP
|
|
You can query these with \f[CR]payee:PAYEEREGEX\f[R] and
|
|
\f[CR]note:NOTEREGEX\f[R], list their values with the payees and notes
|
|
commands, or pivot on \f[CR]payee\f[R] or \f[CR]note\f[R].
|
|
.PP
|
|
Note: in transactions with no \f[CR]|\f[R] character, description,
|
|
payee, and note all have the same value.
|
|
Once a \f[CR]|\f[R] is added, they become distinct.
|
|
(If you\[aq]d like to change this behaviour, please propose it on the
|
|
mail list.)
|
|
.PP
|
|
If you want more strict error checking, you can declare the valid payee
|
|
names with payee directives, and then enforce these with hledger check
|
|
payees.
|
|
(Note: because of the above, for this you\[aq]ll need to ensure every
|
|
transaction description contains a \f[CR]|\f[R] and therefore a
|
|
checkable payee name, even if it\[aq]s empty.)
|
|
.SS Transaction comments
|
|
Text following \f[CR];\f[R], after a transaction description, and/or on
|
|
indented lines immediately below it, form comments for that transaction.
|
|
They are reproduced by \f[CR]print\f[R] but otherwise ignored, except
|
|
they may contain tags, which are not ignored.
|
|
.IP
|
|
.EX
|
|
2012\-01\-01 something ; a transaction comment
|
|
; a second line of transaction comment
|
|
expenses 1
|
|
assets
|
|
.EE
|
|
.SS Postings
|
|
A posting is an addition of some amount to, or removal of some amount
|
|
from, an account.
|
|
Each posting line begins with at least one space or tab (2 or 4 spaces
|
|
is common), followed by:
|
|
.IP \[bu] 2
|
|
(optional) a status character (empty, \f[CR]!\f[R], or \f[CR]*\f[R]),
|
|
followed by a space
|
|
.IP \[bu] 2
|
|
(required) an account name (any text, optionally including single
|
|
spaces.
|
|
If anything follows the account name on the same line, the account name
|
|
must be ended by \f[B]two or more spaces\f[R].)
|
|
.IP \[bu] 2
|
|
(optional) an amount
|
|
.IP \[bu] 2
|
|
(optional) a same\-line posting comment, beginning with a semicolon
|
|
(\f[CR];\f[R]).
|
|
.PP
|
|
If the amount is positive, it is being added to the account; if
|
|
negative, it is being removed from the account.
|
|
.PP
|
|
The posting amounts in a transaction must sum up to zero, indicating
|
|
that the inflows and outflows are equal.
|
|
We call this a balanced transaction.
|
|
(You can read more about the details of transaction balancing below.)
|
|
.PP
|
|
If no amount is written, it will be calculated automatically from the
|
|
other postings in the transaction, so as to balance the transaction.
|
|
In other words, in any transaction you can leave one posting amountless
|
|
to save typing.
|
|
.SS Debits and credits
|
|
The traditional accounting concepts of debit and credit of course exist
|
|
in hledger, but we represent them with numeric sign.
|
|
Positive and negative posting amounts represent debits and credits
|
|
respectively.
|
|
.PP
|
|
You don\[aq]t need to remember that, but if you would like to \- eg for
|
|
helping newcomers or for talking with your accountant \- here\[aq]s a
|
|
handy mnemonic:
|
|
.PP
|
|
\f[I]\f[CI]debit / plus / left / short words\f[I]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[I]\f[CI]credit / minus / right / longer words\f[I]\f[R]
|
|
.SS Account names
|
|
Accounts are the main way of categorising things in hledger.
|
|
As in Double Entry Bookkeeping, they can represent real world accounts
|
|
(such as a bank account), or more abstract categories such as \[dq]money
|
|
spent on food\[dq] or \[dq]money borrowed from Frank\[dq].
|
|
.PP
|
|
Account names are flexible.
|
|
They may be capitalised or not; they may contain letters, numbers,
|
|
punctuation, symbols, or single spaces; they may be in any language.
|
|
.PP
|
|
Typically we use the five traditional accounting categories as the
|
|
starting point for account names.
|
|
In english they are:
|
|
.PP
|
|
\f[CR]assets\f[R], \f[CR]liabilities\f[R], \f[CR]equity\f[R],
|
|
\f[CR]revenues\f[R], \f[CR]expenses\f[R]
|
|
.PP
|
|
These will be discussed more in Account types below.
|
|
In hledger docs you may see them referred to as A, L, E, R, X for short.
|
|
.SS Two space delimiter
|
|
Note the \f[B]two or more spaces\f[R] delimiter that\[aq]s sometimes
|
|
required after account names.
|
|
\ hledger\[aq]s account names, inherited from Ledger, are very
|
|
permissive; they may contain pretty much any kind of text, including
|
|
single spaces and semicolons.
|
|
Because of this, they must be terminated by \f[B]two or more spaces\f[R]
|
|
if there is anything following them on the same line.
|
|
For example, if an amount, balance assignment, or same\-line comment
|
|
follows an account name, they must be preceded by two or more spaces,
|
|
else they would be considered part of the account name:
|
|
.IP
|
|
.EX
|
|
bad: assets:accounts receivable $10 ; <\- too close!
|
|
good: assets:accounts receivable $10
|
|
.EE
|
|
.IP
|
|
.EX
|
|
bad: assets:accounts receivable =$1000 ; <\- too close!
|
|
good: assets:accounts receivable =$1000
|
|
.EE
|
|
.IP
|
|
.EX
|
|
bad: assets:accounts receivable ; comment. <\- too close!
|
|
good: assets:accounts receivable ; comment
|
|
.EE
|
|
.PP
|
|
This two\-space delimiter appears in a few places in hledger, such as
|
|
after account names in postings or account directives; also after the
|
|
period expression in periodic transaction rules.
|
|
When you are starting out, expect it to catch you out at least once.
|
|
It\[aq]s annoying sometimes, but it lets us use expressive account names
|
|
while still keeping the syntax light.
|
|
.SS Account hierarchy
|
|
For more precise reporting, we usually divide accounts into more
|
|
detailed subaccounts, subsubaccounts, and so on, by writing a full colon
|
|
between account name parts.
|
|
For example, instead of writing \f[CR]assets\f[R] and
|
|
\f[CR]expenses\f[R], we might write \f[CR]assets:bank:checking\f[R] and
|
|
\f[CR]expenses:food\f[R].
|
|
From these names hledger will infer this hierarchy of five accounts:
|
|
.IP
|
|
.EX
|
|
assets
|
|
assets:bank
|
|
assets:bank:checking
|
|
expenses
|
|
expenses:food
|
|
.EE
|
|
.PP
|
|
Or as an outline:
|
|
.IP
|
|
.EX
|
|
assets
|
|
bank
|
|
checking
|
|
expenses
|
|
food
|
|
.EE
|
|
.PP
|
|
hledger reports can summarise the account tree to any depth, so you can
|
|
make your subcategories as detailed as you like.
|
|
But don\[aq]t go overboard, especially when getting started; simpler
|
|
categories can be less work.
|
|
.SS Other account name features
|
|
Enclosing the account name in parentheses or brackets, like
|
|
\f[CR](expenses:food)\f[R], enables a non\-standard bookkeeping feature:
|
|
virtual postings.
|
|
.PP
|
|
Account names can be rewritten and restructured, temporarily or
|
|
permanently, by account aliases.
|
|
.SS Amounts
|
|
After the account name, there is usually an amount.
|
|
(Remember: between account name and amount, there must be two or more
|
|
spaces.)
|
|
.PP
|
|
hledger\[aq]s amount format is flexible, supporting several
|
|
international formats.
|
|
Here are some examples.
|
|
Amounts have a number (the \[dq]quantity\[dq]):
|
|
.IP
|
|
.EX
|
|
1
|
|
.EE
|
|
.PP
|
|
\&..and usually a currency symbol or commodity name (more on this
|
|
below), to the left or right of the quantity, with or without a
|
|
separating space:
|
|
.IP
|
|
.EX
|
|
$1
|
|
4000 AAPL
|
|
3 \[dq]green apples\[dq]
|
|
.EE
|
|
.PP
|
|
Amounts can be preceded by a minus sign (or a plus sign, though plus is
|
|
the default), The sign can be written before or after a left\-side
|
|
commodity symbol:
|
|
.IP
|
|
.EX
|
|
\-$1
|
|
$\-1
|
|
.EE
|
|
.PP
|
|
One or more spaces between the sign and the number are acceptable when
|
|
parsing (but they won\[aq]t be displayed in output):
|
|
.IP
|
|
.EX
|
|
+ $1
|
|
$\- 1
|
|
.EE
|
|
.PP
|
|
Scientific E notation is allowed:
|
|
.IP
|
|
.EX
|
|
1E\-6
|
|
EUR 1E3
|
|
.EE
|
|
.PP
|
|
.SS Decimal marks
|
|
A \f[I]decimal mark\f[R] can be written as a period or a comma:
|
|
.IP
|
|
.EX
|
|
1.23
|
|
1,23
|
|
.EE
|
|
.PP
|
|
Both of these are common in international number formats, so hledger is
|
|
not biased towards one or the other.
|
|
Because hledger also supports digit group marks (eg thousands
|
|
separators), this means that a number like \f[CR]1,000\f[R] or
|
|
\f[CR]1.000\f[R] containing just one period or comma is ambiguous.
|
|
In such cases, hledger by default assumes it is a decimal mark, and will
|
|
parse both of those as 1.
|
|
.PP
|
|
To help hledger parse such ambiguous numbers more accurately, if you use
|
|
digit group marks, we recommend declaring the decimal mark explicitly.
|
|
The best way is to add a \f[CR]decimal\-mark\f[R] directive at the top
|
|
of each data file, like this:
|
|
.IP
|
|
.EX
|
|
decimal\-mark .
|
|
.EE
|
|
.PP
|
|
Or you can declare it per commodity with \f[CR]commodity\f[R]
|
|
directives, described below.
|
|
.PP
|
|
hledger also accepts numbers like \f[CR]10.\f[R] with no digits after
|
|
the decimal mark (and will sometimes display numbers that way to
|
|
disambiguate them \- see Trailing decimal marks).
|
|
.SS Digit group marks
|
|
In the integer part of the amount quantity (left of the decimal mark),
|
|
groups of digits can optionally be separated by a \f[I]digit group
|
|
mark\f[R] \- a comma or period (whichever is not used as decimal mark),
|
|
or a space (several Unicode space variants, like no\-break space, are
|
|
also accepted).
|
|
\ So these are all valid amounts in a journal file:
|
|
.IP
|
|
.EX
|
|
$1,000,000.00
|
|
EUR 2.000.000,00
|
|
INR 9,99,99,999.00
|
|
1 000 000.00 ; <\- ordinary space
|
|
1\ 000\ 000.00 ; <\- no\-break space
|
|
.EE
|
|
.SS Commodity
|
|
Amounts in hledger have both a \[dq]quantity\[dq], which is a signed
|
|
decimal number, and a \[dq]commodity\[dq], which is a currency symbol,
|
|
stock ticker, or any word or phrase describing something you are
|
|
tracking.
|
|
.PP
|
|
If the commodity name contains non\-letters (spaces, numbers, or
|
|
punctuation), you must always write it inside double quotes
|
|
(\f[CR]\[dq]green apples\[dq]\f[R], \f[CR]\[dq]ABC123\[dq]\f[R]).
|
|
.PP
|
|
If you write just a bare number, that too will have a commodity, with
|
|
name \f[CR]\[dq]\[dq]\f[R]; we call that the \[dq]no\-symbol
|
|
commodity\[dq].
|
|
.PP
|
|
Actually, hledger combines these single\-commodity amounts into more
|
|
powerful multi\-commodity amounts, which are what it works with most of
|
|
the time.
|
|
A multi\-commodity amount could be, eg:
|
|
\f[CR]1 USD, 2 EUR, 3.456 TSLA\f[R].
|
|
In practice, you will only see multi\-commodity amounts in hledger\[aq]s
|
|
output; you can\[aq]t write them directly in the journal file.
|
|
\
|
|
.PP
|
|
By default, the format of amounts in the journal influences how hledger
|
|
displays them in output.
|
|
This is explained in Commodity display style below.
|
|
.PP
|
|
.SS Costs
|
|
After a posting amount, you can note its cost (when buying) or selling
|
|
price (when selling) in another commodity, by writing either
|
|
\f[CR]\[at] UNITPRICE\f[R] or \f[CR]\[at]\[at] TOTALPRICE\f[R] after it.
|
|
This indicates a conversion transaction, where one commodity is
|
|
exchanged for another.
|
|
.PP
|
|
(You might also see this called \[dq]transaction price\[dq] in hledger
|
|
docs, discussions, or code; that term was directionally neutral and
|
|
reminded that it is a price specific to a transaction, but we now just
|
|
call it \[dq]cost\[dq], with the understanding that the transaction
|
|
could be a purchase or a sale.)
|
|
.PP
|
|
Costs are usually written explicitly with \f[CR]\[at]\f[R] or
|
|
\f[CR]\[at]\[at]\f[R], but can also be inferred automatically for simple
|
|
multi\-commodity transactions.
|
|
Note, if costs are inferred, the order of postings is significant; the
|
|
first posting will have a cost attached, in the commodity of the second.
|
|
.PP
|
|
As an example, here are several ways to record purchases of a foreign
|
|
currency in hledger, using the cost notation either explicitly or
|
|
implicitly:
|
|
.IP "1." 3
|
|
Write the price per unit, as \f[CR]\[at] UNITPRICE\f[R] after the
|
|
amount:
|
|
.RS 4
|
|
.IP
|
|
.EX
|
|
2009/1/1
|
|
assets:euros €100 \[at] $1.35 ; one hundred euros purchased at $1.35 each
|
|
assets:dollars ; balancing amount is \-$135.00
|
|
.EE
|
|
.RE
|
|
.IP "2." 3
|
|
Write the total price, as \f[CR]\[at]\[at] TOTALPRICE\f[R] after the
|
|
amount:
|
|
.RS 4
|
|
.IP
|
|
.EX
|
|
2009/1/1
|
|
assets:euros €100 \[at]\[at] $135 ; one hundred euros purchased at $135 for the lot
|
|
assets:dollars
|
|
.EE
|
|
.RE
|
|
.IP "3." 3
|
|
Specify amounts for all postings, using exactly two commodities, and let
|
|
hledger infer the price that balances the transaction.
|
|
Note the effect of posting order: the price is added to first posting,
|
|
making it \f[CR]€100 \[at]\[at] $135\f[R], as in example 2:
|
|
.RS 4
|
|
.IP
|
|
.EX
|
|
2009/1/1
|
|
assets:euros €100 ; one hundred euros purchased
|
|
assets:dollars $\-135 ; for $135
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Amounts can be converted to cost at report time using the
|
|
\f[CR]\-B/\-\-cost\f[R] flag; this is discussed more in the Cost
|
|
reporting section.
|
|
.PP
|
|
Note that the cost normally should be a positive amount, though it\[aq]s
|
|
not required to be.
|
|
This can be a little confusing, see discussion at
|
|
\-\-infer\-market\-prices: market prices from transactions.
|
|
.SS Balance assertions
|
|
hledger supports Ledger\-style balance assertions in journal files.
|
|
These look like, for example, \f[CR]= EXPECTEDBALANCE\f[R] following a
|
|
posting\[aq]s amount.
|
|
Eg here we assert the expected dollar balance in accounts a and b after
|
|
each posting:
|
|
.IP
|
|
.EX
|
|
2013/1/1
|
|
a $1 = $1
|
|
b = $\-1
|
|
|
|
2013/1/2
|
|
a $1 = $2
|
|
b $\-1 = $\-2
|
|
.EE
|
|
.PP
|
|
After reading a journal file, hledger will check all balance assertions
|
|
and report an error if any of them fail.
|
|
Balance assertions can protect you from, eg, inadvertently disrupting
|
|
reconciled balances while cleaning up old entries.
|
|
You can disable them temporarily with the
|
|
\f[CR]\-I/\-\-ignore\-assertions\f[R] flag, which can be useful for
|
|
troubleshooting or for reading Ledger files.
|
|
(Note: this flag currently does not disable balance assignments,
|
|
described below).
|
|
.SS Assertions and ordering
|
|
hledger calculates and checks an account\[aq]s balance assertions in
|
|
date order (and when there are multiple assertions on the same day, in
|
|
parse order).
|
|
Note this is different from Ledger, which checks assertions always in
|
|
parse order, ignoring dates.
|
|
.PP
|
|
This means in hledger you can freely reorder transactions, postings, or
|
|
files, and balance assertions will usually keep working.
|
|
The exception is when you reorder multiple postings on the same day, to
|
|
the same account, which have balance assertions; those will likely need
|
|
updating.
|
|
.SS Assertions and multiple files
|
|
If an account has transactions appearing in multiple files, balance
|
|
assertions can still work \- but \f[I]only if those files are part of a
|
|
hierarchy made by include directives\f[R].
|
|
.PP
|
|
If the same files are specified with two \f[CR]\-f\f[R] options on the
|
|
command line, the assertions in the second will not see the balances
|
|
from the first.
|
|
.PP
|
|
To work around this, arrange your files in a hierarchy with
|
|
\f[CR]include\f[R].
|
|
Or, you could concatenate the files temporarily, and process them like
|
|
one big file.
|
|
.PP
|
|
Why does it work this way ?
|
|
It might be related to hledger\[aq]s goal of stable predictable reports.
|
|
File hierarchy is considered \[dq]permanent\[dq], part of your data,
|
|
while the order of command line options/arguments is not.
|
|
We don\[aq]t want transient changes to be able to change the meaning of
|
|
the data.
|
|
Eg it would be frustrating if tomorrow all your balance assertions broke
|
|
because you wrote command line arguments in a different order.
|
|
(Discussion welcome.)
|
|
.SS Assertions and costs
|
|
Balance assertions ignore costs, and should normally be written without
|
|
one:
|
|
.IP
|
|
.EX
|
|
2019/1/1
|
|
(a) $1 \[at] €1 = $1
|
|
.EE
|
|
.PP
|
|
We do allow costs to be written in balance assertion amounts, however,
|
|
and print shows them, but they don\[aq]t affect whether the assertion
|
|
passes or fails.
|
|
This is for backward compatibility (hledger\[aq]s close command used to
|
|
generate balance assertions with costs), and because balance
|
|
\f[I]assignments\f[R] do use costs (see below).
|
|
.SS Assertions and commodities
|
|
The balance assertions described so far are \[dq]\f[B]single commodity
|
|
balance assertions\f[R]\[dq]: they assert and check the balance in one
|
|
commodity, ignoring any others that may be present.
|
|
This is how balance assertions work in Ledger also.
|
|
.PP
|
|
If an account contains multiple commodities, you can assert their
|
|
balances by writing multiple postings with balance assertions, one for
|
|
each commodity:
|
|
.IP
|
|
.EX
|
|
2013/1/1
|
|
usd $\-1
|
|
eur €\-1
|
|
both
|
|
|
|
2013/1/2
|
|
both 0 = $1
|
|
both 0 = €1
|
|
.EE
|
|
.PP
|
|
In hledger you can make a stronger \[dq]\f[B]sole commodity balance
|
|
assertion\f[R]\[dq] by writing two equals signs
|
|
(\f[CR]== EXPECTEDBALANCE\f[R]).
|
|
This also asserts that there are no other commodities in the account
|
|
besides the asserted one (or at least, that their current balance is
|
|
zero):
|
|
.IP
|
|
.EX
|
|
2013/1/1
|
|
usd $\-1 == $\-1 ; these sole commodity assertions succeed
|
|
eur €\-1 == €\-1
|
|
both ;== $1 ; this one would fail because \[aq]both\[aq] contains $ and €
|
|
.EE
|
|
.PP
|
|
It\[aq]s less easy to make a \[dq]\f[B]sole commodities balance
|
|
assertion\f[R]\[dq] (note the plural) \- ie, asserting that an account
|
|
contains two or more specified commodities and no others.
|
|
It can be done by
|
|
.IP "1." 3
|
|
isolating each commodity in a subaccount, and asserting those
|
|
.IP "2." 3
|
|
and also asserting there are no commodities in the parent account
|
|
itself:
|
|
.IP
|
|
.EX
|
|
2013/1/1
|
|
usd $\-1
|
|
eur €\-1
|
|
both 0 == 0 ; nothing up my sleeve
|
|
both:usd $1 == $1 ; a dollar here
|
|
both:eur €1 == €1 ; a euro there
|
|
.EE
|
|
.SS Assertions and subaccounts
|
|
All of the balance assertions above (both \f[CR]=\f[R] and
|
|
\f[CR]==\f[R]) are \[dq]\f[B]subaccount\-exclusive balance
|
|
assertions\f[R]\[dq]; they ignore any balances that exist in deeper
|
|
subaccounts.
|
|
.PP
|
|
In hledger you can make \[dq]\f[B]subaccount\-inclusive balance
|
|
assertions\f[R]\[dq] by adding a star after the equals (\f[CR]=*\f[R] or
|
|
\f[CR]==*\f[R]):
|
|
.IP
|
|
.EX
|
|
2019/1/1
|
|
equity:start
|
|
assets:checking $10
|
|
assets:savings $10
|
|
assets $0 ==* $20 ; assets + subaccounts contains $20 and nothing else
|
|
.EE
|
|
.SS Assertions and status
|
|
Balance assertions always consider postings of all statuses (unmarked,
|
|
pending, or cleared); they are not affected by the
|
|
\f[CR]\-U\f[R]/\f[CR]\-\-unmarked\f[R] /
|
|
\f[CR]\-P\f[R]/\f[CR]\-\-pending\f[R] /
|
|
\f[CR]\-C\f[R]/\f[CR]\-\-cleared\f[R] flags or the \f[CR]status:\f[R]
|
|
query.
|
|
.SS Assertions and virtual postings
|
|
Balance assertions always consider both real and virtual postings; they
|
|
are not affected by the \f[CR]\-\-real/\-R\f[R] flag or \f[CR]real:\f[R]
|
|
query.
|
|
.SS Assertions and auto postings
|
|
Balance assertions \f[I]are\f[R] affected by the \f[CR]\-\-auto\f[R]
|
|
flag, which generates auto postings, which can alter account balances.
|
|
Because auto postings are optional in hledger, accounts affected by them
|
|
effectively have two balances.
|
|
But balance assertions can only test one or the other of these.
|
|
So to avoid making fragile assertions, either:
|
|
.IP \[bu] 2
|
|
assert the balance calculated with \f[CR]\-\-auto\f[R], and always use
|
|
\f[CR]\-\-auto\f[R] with that file
|
|
.IP \[bu] 2
|
|
or assert the balance calculated without \f[CR]\-\-auto\f[R], and never
|
|
use \f[CR]\-\-auto\f[R] with that file
|
|
.IP \[bu] 2
|
|
or avoid balance assertions on accounts affected by auto postings (or
|
|
avoid auto postings entirely).
|
|
.SS Assertions and precision
|
|
Balance assertions compare the exactly calculated amounts, which are not
|
|
always what is shown by reports.
|
|
Eg a commodity directive may limit the display precision, but this will
|
|
not affect balance assertions.
|
|
Balance assertion failure messages show exact amounts.
|
|
.SS Assertions and hledger add
|
|
Balance assertions can be included in the amounts given in
|
|
\f[CR]add\f[R].
|
|
All types of assertions are supported, and assertions can be used as in
|
|
a normal journal file.
|
|
.PP
|
|
All transactions, not just those that have an explicit assertion, are
|
|
validated against the existing assertions in the journal.
|
|
This means it is possible for an added transaction to fail even if its
|
|
assertions are correct as of the transaction date.
|
|
.PP
|
|
If this assertion checking is not desired, then it can be disabled with
|
|
\f[CR]\-I\f[R].
|
|
.PP
|
|
However, balance assignments are currently not supported.
|
|
.SS Posting comments
|
|
Text following \f[CR];\f[R], at the end of a posting line, and/or on
|
|
indented lines immediately below it, form comments for that posting.
|
|
They are reproduced by \f[CR]print\f[R] but otherwise ignored, except
|
|
they may contain tags, which are not ignored.
|
|
.IP
|
|
.EX
|
|
2012\-01\-01
|
|
expenses 1 ; a comment for posting 1
|
|
assets
|
|
; a comment for posting 2
|
|
; a second comment line for posting 2
|
|
.EE
|
|
.SS Transaction balancing
|
|
How exactly does hledger decide when a transaction is balanced ?
|
|
Especially when it involves costs, which often are not exact, because of
|
|
repeating decimals, or imperfect data from financial institutions ?
|
|
In each commodity, hledger sums the transaction\[aq]s posting amounts,
|
|
after converting any with costs; then it checks if that sum is zero,
|
|
when rounded to a suitable number of decimal digits \- which we call the
|
|
\f[I]balancing precision\f[R].
|
|
.PP
|
|
Since version 1.50, hledger infers balancing precision in each
|
|
transaction from the amounts in that transaction\[aq]s journal entry
|
|
(like Ledger).
|
|
Ie, when checking the balance of commodity A, it uses the highest
|
|
decimal precision seen for A in the journal entry (excluding cost
|
|
amounts).
|
|
This makes transaction balancing robust; any imbalances must be visibly
|
|
accounted for in the journal entry, display precision can be freely
|
|
increased with \f[CR]\-c\f[R], and compatibility with Ledger and
|
|
Beancount journals is good.
|
|
.PP
|
|
Note that hledger versions before 1.50 worked differently: they allowed
|
|
display precision to override the balancing precision.
|
|
This masked small imbalances and caused fragility (see issue #2402).
|
|
As a result, some journal entries (or CSV rules) that worked with
|
|
hledger <1.50, are now rejected with an \[dq]unbalanced transaction\[dq]
|
|
error.
|
|
If you hit this problem, it\[aq]s easy to fix:
|
|
.IP \[bu] 2
|
|
You can restore the old behaviour, by adding
|
|
\f[CR]\-\-txn\-balancing=old\f[R] to the command or to your
|
|
\f[CR]\[ti]/.hledger.conf\f[R] file.
|
|
This lets you keep using old journals unchanged, though without the
|
|
above benefits.
|
|
.IP \[bu] 2
|
|
Or you can fix the problem entries (recommended).
|
|
There are three ways, use whichever seems best:
|
|
.RS 2
|
|
.IP "1." 3
|
|
make cost amounts more precise (add more/better decimal digits)
|
|
.IP "2." 3
|
|
or make non\-cost amounts less precise (remove unnecessary decimal
|
|
digits that are raising the precision)
|
|
.IP "3." 3
|
|
or add a posting to absorb the imbalance (eg
|
|
\[dq]expenses:rounding\[dq].
|
|
Remember that one posting may omit the amount; that\[aq]s convenient
|
|
here.)
|
|
.RE
|
|
.SS Tags
|
|
Tags are a way to add extra labels or data fields to transactions,
|
|
postings, or accounts, which you can match with a \f[CR]tag:\f[R] query
|
|
in reports.
|
|
(See queries below.)
|
|
.PP
|
|
Tags are a single word or hyphenated word, immediately followed by a
|
|
full colon, written within a comment.
|
|
(Yes, storing data in comments is slightly weird.)
|
|
Here\[aq]s a transaction with a tag:
|
|
.IP
|
|
.EX
|
|
2025\-01\-01 groceries ; some\-tag:
|
|
assets:checking
|
|
expenses:food $1
|
|
.EE
|
|
.PP
|
|
A tag can have a value, a single line of text written after the colon.
|
|
Tag values can\[aq]t contain newlines.:
|
|
.IP
|
|
.EX
|
|
2025\-01\-01 groceries ; tag1: this is tag1\[aq]s value
|
|
.EE
|
|
.PP
|
|
Multiple tags can be separated by comma.
|
|
Tag values can\[aq]t contain commas.:
|
|
.IP
|
|
.EX
|
|
2025\-01\-01 groceries ; tag1:value 1, tag2:value 2, comment text
|
|
.EE
|
|
.PP
|
|
A tag can have multiple values:
|
|
.IP
|
|
.EX
|
|
2025\-01\-01 groceries ; tag1:value 1, tag1:value 2
|
|
.EE
|
|
.PP
|
|
You can write each tag on its own line of you prefer (but they still
|
|
can\[aq]t contain commas):
|
|
.IP
|
|
.EX
|
|
2025\-01\-01 groceries
|
|
; tag1: value 1
|
|
; tag2: value 2
|
|
.EE
|
|
.PP
|
|
Tags can be attached to individual postings, rather than the overall
|
|
transaction:
|
|
.IP
|
|
.EX
|
|
2025\-01\-01 rent
|
|
assets:checking
|
|
expenses:rent $1000 ; postingtag:
|
|
.EE
|
|
.PP
|
|
Tags can be attached to accounts, in their account directive:
|
|
.IP
|
|
.EX
|
|
account assets:checking ; acct\-number: 123\-45\-6789
|
|
.EE
|
|
.SS Tag propagation
|
|
In addition to what they are attached to, tags also affect related data
|
|
in a few ways, allowing more powerful queries:
|
|
.IP "1." 3
|
|
Accounts \-> postings.
|
|
Postings inherit tags from their account.
|
|
.IP "2." 3
|
|
Transactions \-> postings.
|
|
Postings inherit tags from their transaction.
|
|
.IP "3." 3
|
|
Postings \-> transactions.
|
|
Transactions also acquire the tags of their postings.
|
|
\
|
|
.PP
|
|
So when you use a \f[CR]tag:\f[R] query to match whole transactions,
|
|
individual postings, or accounts, it\[aq]s good to understand how tags
|
|
behave.
|
|
Here\[aq]s an example showing all three kinds of propagation:
|
|
.IP
|
|
.EX
|
|
account assets:checking
|
|
account expenses:food ; atag:
|
|
|
|
2025\-01\-01 groceries ; ttag:
|
|
assets:checking ; p1tag:
|
|
expenses:food $1 ; p2tag:
|
|
.EE
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(13.3n) lw(13.8n) lw(43.0n).
|
|
T{
|
|
data part
|
|
T}@T{
|
|
has tags
|
|
T}@T{
|
|
explanation
|
|
T}
|
|
_
|
|
T{
|
|
assets:checking\ account
|
|
T}@T{
|
|
T}@T{
|
|
no tags attached
|
|
T}
|
|
T{
|
|
expenses:food account
|
|
T}@T{
|
|
atag
|
|
T}@T{
|
|
atag: in comment
|
|
T}
|
|
T{
|
|
assets:checking posting
|
|
T}@T{
|
|
p1tag, ttag
|
|
T}@T{
|
|
p1tag: in comment, ttag acquired from transaction
|
|
T}
|
|
T{
|
|
expenses:food posting
|
|
T}@T{
|
|
p2tag, atag, ttag
|
|
T}@T{
|
|
p2tag: in comment, atag from account, ttag from transaction
|
|
T}
|
|
T{
|
|
groceries transaction
|
|
T}@T{
|
|
ttag, p1tag, p2tag, atag
|
|
T}@T{
|
|
ttag: in comment, p1tag from first posting, p2tag and atag from second
|
|
posting
|
|
T}
|
|
.TE
|
|
.SS Displaying tags
|
|
You can use the \f[CR]tags\f[R] command to list tag names or values.
|
|
.PP
|
|
The \f[CR]print\f[R] command also shows tags.
|
|
.PP
|
|
You can use \-\-pivot to display tag values in other reports, in various
|
|
ways (eg appended to account names, like pseudo subaccounts).
|
|
.SS When to use tags ?
|
|
Tags provide more dimensions of categorisation, complementing accounts
|
|
and transaction descriptions.
|
|
When to use each of these is somewhat a matter of taste.
|
|
Accounts have the most built\-in support, and regex queries on
|
|
descriptions are also quite powerful.
|
|
So you may not need tags at all.
|
|
But if you want to track multiple cross\-cutting categories, they can be
|
|
a good fit.
|
|
For example, you could tag trip\-related transactions with
|
|
\f[CR]trip: YEAR:PLACE\f[R], without disturbing your usual account
|
|
categories.
|
|
.SS Tag names
|
|
What is allowed in a tag name ?
|
|
Most non\-whitespace characters.
|
|
Eg \f[CR]😀:\f[R] is a valid tag.
|
|
.PP
|
|
For extra error checking, you can declare valid tag names with the
|
|
\f[CR]tag\f[R] directive, and then enforce these with the
|
|
\f[CR]check\f[R] command.
|
|
But note that tags are detected quite loosely at present, sometimes
|
|
where you didn\[aq]t intend them.
|
|
Eg a comment like \f[CR]; see https://foo.com\f[R] adds a
|
|
\f[CR]https\f[R] tag.
|
|
.PP
|
|
There are several tag names which have special significance to hledger.
|
|
They are explained elsewhere, but here\[aq]s a quick reference:
|
|
.IP
|
|
.EX
|
|
type \-\- declares an account\[aq]s type
|
|
date \-\- overrides a posting\[aq]s date
|
|
date2 \-\- overrides a posting\[aq]s secondary date
|
|
assert \-\- appears on txns generated by close \-\-assert
|
|
retain \-\- appears on txns generated by close \-\-retain
|
|
start \-\- appears on txns generated by close \-\-migrate/\-\-close/\-\-open/\-\-assign
|
|
t \-\- appears on postings generated from timedot letters
|
|
|
|
generated\-transaction \-\- appears on txns generated by a periodic rule
|
|
modified\-transaction \-\- appears on txns which have had auto postings added
|
|
generated\-posting \-\- appears on generated postings
|
|
cost\-posting \-\- appears on postings which have (or could have) a cost,
|
|
and which have equivalent conversion postings in the transaction
|
|
conversion\-posting \-\- appears on postings which are to a V/Conversion account
|
|
and which have an equivalent cost posting in the transaction
|
|
.EE
|
|
.PP
|
|
The second group above (generated\-transaction, etc.)
|
|
are normally hidden, with a \f[CR]_\f[R] prefix added.
|
|
This means \f[CR]print\f[R] doesn\[aq]t show them by default; but you
|
|
can still use them in queries.
|
|
You can add the \f[CR]\-\-verbose\-tags\f[R] flag to make them visible,
|
|
which can be useful for troubleshooting.
|
|
.SS Directives
|
|
Besides transactions, there is something else you can put in a
|
|
\f[CR]journal\f[R] file: directives.
|
|
These are declarations, beginning with a keyword, that modify
|
|
hledger\[aq]s behaviour.
|
|
Some directives can have more specific subdirectives, indented below
|
|
them.
|
|
hledger\[aq]s directives are similar to Ledger\[aq]s in many cases, but
|
|
there are also many differences.
|
|
Directives are not required, but can be useful.
|
|
Here are the main directives:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(39.7n) lw(30.3n).
|
|
T{
|
|
purpose
|
|
T}@T{
|
|
directive
|
|
T}
|
|
_
|
|
T{
|
|
\f[B]READING DATA:\f[R]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
Rewrite account names
|
|
T}@T{
|
|
\f[CR]alias\f[R]
|
|
T}
|
|
T{
|
|
Comment out sections of the file
|
|
T}@T{
|
|
\f[CR]comment\f[R]
|
|
T}
|
|
T{
|
|
Declare file\[aq]s decimal mark, to help parse amounts accurately
|
|
T}@T{
|
|
\f[CR]decimal\-mark\f[R]
|
|
T}
|
|
T{
|
|
Include other data files
|
|
T}@T{
|
|
\f[CR]include\f[R]
|
|
T}
|
|
T{
|
|
\f[B]GENERATING DATA:\f[R]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
Generate recurring transactions or budget goals
|
|
T}@T{
|
|
\f[CR]\[ti]\f[R]
|
|
T}
|
|
T{
|
|
Generate extra postings on existing transactions
|
|
T}@T{
|
|
\f[CR]=\f[R]
|
|
T}
|
|
T{
|
|
\f[B]CHECKING FOR ERRORS:\f[R]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
Define valid entities to provide more error checking
|
|
T}@T{
|
|
\f[CR]account\f[R], \f[CR]commodity\f[R], \f[CR]payee\f[R],
|
|
\f[CR]tag\f[R]
|
|
T}
|
|
T{
|
|
\f[B]REPORTING:\f[R]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
Declare accounts\[aq] type and display order
|
|
T}@T{
|
|
\f[CR]account\f[R]
|
|
T}
|
|
T{
|
|
Declare commodity display styles
|
|
T}@T{
|
|
\f[CR]commodity\f[R]
|
|
T}
|
|
T{
|
|
Declare market prices
|
|
T}@T{
|
|
\f[CR]P\f[R]
|
|
T}
|
|
.TE
|
|
.SS Directives and multiple files
|
|
Directives vary in their scope, ie which journal entries and which input
|
|
files they affect.
|
|
Most often, a directive will affect the following entries and included
|
|
files if any, until the end of the current file \- and no further.
|
|
You might find this inconvenient!
|
|
For example, \f[CR]alias\f[R] directives do not affect parent or sibling
|
|
files.
|
|
But there are usually workarounds; for example, put \f[CR]alias\f[R]
|
|
directives in your top\-most file, before including other files.
|
|
.PP
|
|
The restriction, though it may be annoying at first, is in a good cause;
|
|
it allows reports to be stable and deterministic, independent of the
|
|
order of input.
|
|
Without it, reports could show different numbers depending on the order
|
|
of \-f options, or the positions of include directives in your files.
|
|
.SS Directive effects
|
|
Here are all hledger\[aq]s directives, with their effects and scope
|
|
summarised \- nine main directives, plus four others which we consider
|
|
non\-essential:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(3.5n) lw(64.1n) lw(2.4n).
|
|
T{
|
|
directive
|
|
T}@T{
|
|
what it does
|
|
T}@T{
|
|
ends at file end?
|
|
T}
|
|
_
|
|
T{
|
|
\f[B]\f[CB]account\f[B]\f[R]
|
|
T}@T{
|
|
Declares an account, for checking all entries in all files; and its
|
|
display order and type.
|
|
Subdirectives: any text, ignored.
|
|
T}@T{
|
|
N
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]alias\f[B]\f[R]
|
|
T}@T{
|
|
Rewrites account names, in following entries until end of current file
|
|
or \f[CR]end aliases\f[R].
|
|
Command line equivalent: \f[CR]\-\-alias\f[R]
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]comment\f[B]\f[R]
|
|
T}@T{
|
|
Ignores part of the journal file, until end of current file or
|
|
\f[CR]end comment\f[R].
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]commodity\f[B]\f[R]
|
|
T}@T{
|
|
Declares up to four things: 1.
|
|
a commodity symbol, for checking all amounts in all files 2.
|
|
the display style for all amounts of this commodity 3.
|
|
the decimal mark for parsing amounts of this commodity, in the rest of
|
|
this file and its children, if there is no \f[CR]decimal\-mark\f[R]
|
|
directive 4.
|
|
the precision to use for balanced\-transaction checking in this
|
|
commodity, in this file and its children.
|
|
\ Takes precedence over \f[CR]D\f[R].
|
|
Subdirectives: \f[CR]format\f[R] (ignored).
|
|
Command line equivalent: \f[CR]\-c/\-\-commodity\-style\f[R]
|
|
T}@T{
|
|
N,N,Y,Y
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]decimal\-mark\f[B]\f[R]
|
|
T}@T{
|
|
Declares the decimal mark, for parsing amounts of all commodities in
|
|
following entries until next \f[CR]decimal\-mark\f[R] or end of current
|
|
file.
|
|
Included files can override.
|
|
Takes precedence over \f[CR]commodity\f[R] and \f[CR]D\f[R].
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]include\f[B]\f[R]
|
|
T}@T{
|
|
Includes entries and directives from another file, as if they were
|
|
written inline.
|
|
Command line alternative: multiple \f[CR]\-f/\-\-file\f[R]
|
|
T}@T{
|
|
N
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]payee\f[B]\f[R]
|
|
T}@T{
|
|
Declares a payee name, for checking all entries in all files.
|
|
T}@T{
|
|
N
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]P\f[B]\f[R]
|
|
T}@T{
|
|
Declares the market price of a commodity on some date, for value
|
|
reports.
|
|
T}@T{
|
|
N
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]\[ti]\f[B]\f[R] (tilde)
|
|
T}@T{
|
|
Declares a periodic transaction rule that generates future transactions
|
|
with \f[CR]\-\-forecast\f[R] and budget goals with
|
|
\f[CR]balance \-\-budget\f[R].
|
|
T}@T{
|
|
N
|
|
T}
|
|
T{
|
|
Other syntax:
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]apply account\f[B]\f[R]
|
|
T}@T{
|
|
Prepends a common parent account to all account names, in following
|
|
entries until end of current file or \f[CR]end apply account\f[R].
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]D\f[B]\f[R]
|
|
T}@T{
|
|
Sets a default commodity to use for no\-symbol amounts;and, if there is
|
|
no \f[CR]commodity\f[R] directive for this commodity: its decimal mark,
|
|
balancing precision, and display style, as above.
|
|
T}@T{
|
|
Y,Y,N,N
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]Y\f[B]\f[R]
|
|
T}@T{
|
|
Sets a default year to use for any yearless dates, in following entries
|
|
until end of current file.
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]=\f[B]\f[R] (equals)
|
|
T}@T{
|
|
Declares an auto posting rule that generates extra postings on matched
|
|
transactions with \f[CR]\-\-auto\f[R], in current, parent, and child
|
|
files (but not sibling files, see #1212).
|
|
T}@T{
|
|
partly
|
|
T}
|
|
T{
|
|
\f[B]Other Ledger directives\f[R]
|
|
T}@T{
|
|
Other directives from Ledger\[aq]s file format are accepted but ignored.
|
|
T}@T{
|
|
T}
|
|
.TE
|
|
.SS \f[CR]account\f[R] directive
|
|
\f[CR]account\f[R] directives can be used to declare accounts (ie, the
|
|
places that amounts are transferred from and to).
|
|
Though not required, these declarations can provide several benefits:
|
|
.IP \[bu] 2
|
|
They can document your intended chart of accounts, providing a
|
|
reference.
|
|
.IP \[bu] 2
|
|
They can store additional account information as comments, or as tags
|
|
which can be used to filter or pivot reports.
|
|
.IP \[bu] 2
|
|
They can restrict which accounts may be posted to by transactions, eg in
|
|
strict mode, which helps prevent errors.
|
|
.IP \[bu] 2
|
|
They influence account display order in reports, allowing
|
|
non\-alphabetic sorting (eg Revenues to appear above Expenses).
|
|
.IP \[bu] 2
|
|
They can help hledger know your accounts\[aq] types (asset, liability,
|
|
equity, revenue, expense), enabling reports like balancesheet and
|
|
incomestatement.
|
|
.IP \[bu] 2
|
|
They help with account name completion (in hledger add, hledger\-web,
|
|
hledger\-iadd, ledger\-mode, etc.)
|
|
.PP
|
|
They are written as the word \f[CR]account\f[R] followed by a
|
|
hledger\-style account name.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
account assets:bank:checking
|
|
.EE
|
|
.PP
|
|
Ledger\-style indented subdirectives are also accepted, but ignored:
|
|
.IP
|
|
.EX
|
|
account assets:bank:checking
|
|
format subdirective ; currently ignored
|
|
.EE
|
|
.SS Account comments
|
|
Text following \f[B]two or more spaces\f[R] and \f[CR];\f[R] at the end
|
|
of an account directive line, and/or following \f[CR];\f[R] on indented
|
|
lines immediately below it, form comments for that account.
|
|
They are ignored except they may contain tags, which are not ignored.
|
|
.PP
|
|
The two\-space requirement for same\-line account comments is because
|
|
\f[CR];\f[R] is allowed in account names.
|
|
.IP
|
|
.EX
|
|
account assets:bank:checking ; same\-line comment, at least 2 spaces before the semicolon
|
|
; next\-line comment
|
|
; some tags \- type:A, acctnum:12345
|
|
.EE
|
|
.SS Account error checking
|
|
By default, accounts need not be declared; they come into existence when
|
|
a posting references them.
|
|
This is convenient, but it means hledger can\[aq]t warn you when you
|
|
mis\-spell an account name in the journal.
|
|
Usually you\[aq]ll find that error later, as an extra account in balance
|
|
reports, or an incorrect balance when reconciling.
|
|
.PP
|
|
In strict mode, enabled with the \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R]
|
|
flag, or when you run \f[CR]hledger check accounts\f[R], hledger will
|
|
report an error if any transaction uses an account name that has not
|
|
been declared by an account directive.
|
|
Some notes:
|
|
.IP \[bu] 2
|
|
The declaration is case\-sensitive; transactions must use the correct
|
|
account name capitalisation.
|
|
.IP \[bu] 2
|
|
The account directive\[aq]s scope is \[dq]whole file and below\[dq] (see
|
|
directives).
|
|
This means it affects all of the current file, and any files it
|
|
includes, but not parent or sibling files.
|
|
The position of account directives within the file does not matter,
|
|
though it\[aq]s usual to put them at the top.
|
|
.IP \[bu] 2
|
|
Accounts can only be declared in \f[CR]journal\f[R] files, but will
|
|
affect included files of all types.
|
|
.IP \[bu] 2
|
|
It\[aq]s currently not possible to declare \[dq]all possible
|
|
subaccounts\[dq] with a wildcard; every account posted to must be
|
|
declared.
|
|
.IP \[bu] 2
|
|
If you use the \-\-infer\-equity flag, you will also need declarations
|
|
for the account names it generates.
|
|
.SS Account display order
|
|
Account directives also cause hledger to display accounts in a
|
|
particular order, not just alphabetically.
|
|
Eg, here is a conventional ordering for the top\-level accounts:
|
|
.IP
|
|
.EX
|
|
account assets
|
|
account liabilities
|
|
account equity
|
|
account revenues
|
|
account expenses
|
|
.EE
|
|
.PP
|
|
Now hledger displays them in that order:
|
|
.IP
|
|
.EX
|
|
$ hledger accounts
|
|
assets
|
|
liabilities
|
|
equity
|
|
revenues
|
|
expenses
|
|
.EE
|
|
.PP
|
|
If there are undeclared accounts, those will be displayed last, in
|
|
alphabetical order.
|
|
.PP
|
|
Sorting is done within each group of sibling accounts, at each level of
|
|
the account tree.
|
|
Eg, a declaration like \f[CR]account parent:child\f[R] influences
|
|
\f[CR]child\f[R]\[aq]s position among its siblings.
|
|
.PP
|
|
Note, it does not affect \f[CR]parent\f[R]\[aq]s position; for that, you
|
|
need an \f[CR]account parent\f[R] declaration.
|
|
.PP
|
|
Sibling accounts are always displayed together; hledger won\[aq]t
|
|
display \f[CR]x:y\f[R] in between \f[CR]a:b\f[R] and \f[CR]a:c\f[R].
|
|
.PP
|
|
An account directive both declares an account as a valid posting target,
|
|
and declares its display order; you can\[aq]t easily do one without the
|
|
other.
|
|
.SS Account types
|
|
hledger knows that in accounting there are three main account types:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l l.
|
|
T{
|
|
\f[CR]Asset\f[R]
|
|
T}@T{
|
|
\f[CR]A\f[R]
|
|
T}@T{
|
|
things you own
|
|
T}
|
|
T{
|
|
\f[CR]Liability\f[R]
|
|
T}@T{
|
|
\f[CR]L\f[R]
|
|
T}@T{
|
|
things you owe
|
|
T}
|
|
T{
|
|
\f[CR]Equity\f[R]
|
|
T}@T{
|
|
\f[CR]E\f[R]
|
|
T}@T{
|
|
owner\[aq]s investment, balances the two above
|
|
T}
|
|
.TE
|
|
.PP
|
|
and two more representing changes in these:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l l.
|
|
T{
|
|
\f[CR]Revenue\f[R]
|
|
T}@T{
|
|
\f[CR]R\f[R]
|
|
T}@T{
|
|
inflows (also known as \f[CR]Income\f[R])
|
|
T}
|
|
T{
|
|
\f[CR]Expense\f[R]
|
|
T}@T{
|
|
\f[CR]X\f[R]
|
|
T}@T{
|
|
outflows
|
|
T}
|
|
.TE
|
|
.PP
|
|
hledger also uses a couple of subtypes:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l l.
|
|
T{
|
|
\f[CR]Cash\f[R]
|
|
T}@T{
|
|
\f[CR]C\f[R]
|
|
T}@T{
|
|
liquid assets
|
|
T}
|
|
T{
|
|
\f[CR]Conversion\f[R]
|
|
T}@T{
|
|
\f[CR]V\f[R]
|
|
T}@T{
|
|
commodity conversions equity
|
|
T}
|
|
.TE
|
|
.PP
|
|
As a convenience, hledger will detect these types automatically from
|
|
english account names.
|
|
But it\[aq]s better to declare them explicitly by adding a
|
|
\f[CR]type:\f[R] tag in the account directives.
|
|
The tag\[aq]s value can be any of the types or one\-letter abbreviations
|
|
above.
|
|
.PP
|
|
Here is a typical set of account type declarations.
|
|
Subaccounts will inherit their parent\[aq]s type, or can override it:
|
|
.IP
|
|
.EX
|
|
account assets ; type: A
|
|
account liabilities ; type: L
|
|
account equity ; type: E
|
|
account revenues ; type: R
|
|
account expenses ; type: X
|
|
|
|
account assets:bank ; type: C
|
|
account assets:cash ; type: C
|
|
|
|
account equity:conversion ; type: V
|
|
.EE
|
|
.PP
|
|
This enables the easy balancesheet, balancesheetequity, cashflow and
|
|
incomestatement reports, and querying by type:.
|
|
.PP
|
|
Tips:
|
|
.IP \[bu] 2
|
|
You can list accounts and their types, for troubleshooting:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
$ hledger accounts \-\-types [ACCTPAT] [type:TYPECODES] [\-DEPTH] [\-\-locations]
|
|
.EE
|
|
.RE
|
|
.IP \[bu] 2
|
|
It\[aq]s a good idea to declare at least one account for each account
|
|
type.
|
|
Having some types declared and some inferred can disrupt certain
|
|
reports.
|
|
.IP \[bu] 2
|
|
The rules for inferring types from account names are as follows (using
|
|
Regular expressions).
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
If they don\[aq]t work for you, just ignore them and declare your types
|
|
with \f[CR]type:\f[R] tags.
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
If account\[aq]s name contains this case insensitive regular expression | its type is
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\[ha]assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash
|
|
\[ha]assets?(:|$) | Asset
|
|
\[ha](debts?|liabilit(y|ies))(:|$) | Liability
|
|
\[ha]equity:(trad(e|ing)|conversion)s?(:|$) | Conversion
|
|
\[ha]equity(:|$) | Equity
|
|
\[ha](income|revenue)s?(:|$) | Revenue
|
|
\[ha]expenses?(:|$) | Expense
|
|
.EE
|
|
.RE
|
|
.IP \[bu] 2
|
|
As mentioned above, subaccounts will inherit a type from their parent
|
|
account.
|
|
To be precise, an account\[aq]s type is decided by the first of these
|
|
that exists:
|
|
.RS 2
|
|
.IP "1." 3
|
|
A \f[CR]type:\f[R] declaration for this account.
|
|
.IP "2." 3
|
|
A \f[CR]type:\f[R] declaration in the parent accounts above it,
|
|
preferring the nearest.
|
|
.IP "3." 3
|
|
An account type inferred from this account\[aq]s name.
|
|
.IP "4." 3
|
|
An account type inferred from a parent account\[aq]s name, preferring
|
|
the nearest parent.
|
|
.IP "5." 3
|
|
Otherwise, it will have no type.
|
|
.RE
|
|
.IP \[bu] 2
|
|
Account aliases can disrupt account types.
|
|
.SS \f[CR]alias\f[R] directive
|
|
You can define account alias rules which rewrite your account names, or
|
|
parts of them, before generating reports.
|
|
This can be useful for:
|
|
.IP \[bu] 2
|
|
expanding shorthand account names to their full form, allowing easier
|
|
data entry and a less verbose journal
|
|
.IP \[bu] 2
|
|
adapting old journals to your current chart of accounts
|
|
.IP \[bu] 2
|
|
experimenting with new account organisations, like a new hierarchy
|
|
.IP \[bu] 2
|
|
combining two accounts into one, eg to see their sum or difference on
|
|
one line
|
|
.IP \[bu] 2
|
|
customising reports
|
|
.PP
|
|
Account aliases also rewrite account names in account directives.
|
|
They do not affect account names being entered via hledger add or
|
|
hledger\-web.
|
|
.PP
|
|
Account aliases are very powerful.
|
|
They are generally easy to use correctly, but you can also generate
|
|
invalid account names with them; more on this below.
|
|
.PP
|
|
See also Rewrite account names.
|
|
.SS Basic aliases
|
|
To set an account alias, use the \f[CR]alias\f[R] directive in your
|
|
journal file.
|
|
This affects all subsequent journal entries in the current file or its
|
|
included files (but note: not sibling or parent files).
|
|
The spaces around the = are optional:
|
|
.IP
|
|
.EX
|
|
alias OLD = NEW
|
|
.EE
|
|
.PP
|
|
Or, you can use the \f[CR]\-\-alias \[aq]OLD=NEW\[aq]\f[R] option on the
|
|
command line.
|
|
This affects all entries.
|
|
It\[aq]s useful for trying out aliases interactively.
|
|
.PP
|
|
OLD and NEW are case sensitive full account names.
|
|
hledger will replace any occurrence of the old account name with the new
|
|
one.
|
|
Subaccounts are also affected.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
alias checking = assets:bank:wells fargo:checking
|
|
; rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq]
|
|
.EE
|
|
.SS Regex aliases
|
|
There is also a more powerful variant that uses a regular expression,
|
|
indicated by wrapping the pattern in forward slashes.
|
|
(This is the only place where hledger requires forward slashes around a
|
|
regular expression.)
|
|
.PP
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
alias /REGEX/ = REPLACEMENT
|
|
.EE
|
|
.PP
|
|
or:
|
|
.IP
|
|
.EX
|
|
$ hledger \-\-alias \[aq]/REGEX/=REPLACEMENT\[aq] ...
|
|
.EE
|
|
.PP
|
|
Any part of an account name matched by REGEX will be replaced by
|
|
REPLACEMENT.
|
|
REGEX is case\-insensitive as usual.
|
|
.PP
|
|
If you need to match a forward slash, escape it with a backslash, eg
|
|
\f[CR]/\[rs]/=:\f[R].
|
|
.PP
|
|
If REGEX contains parenthesised match groups, these can be referenced by
|
|
the usual backslash and number in REPLACEMENT:
|
|
.IP
|
|
.EX
|
|
alias /\[ha](.+):bank:([\[ha]:]+):(.*)/ = \[rs]1:\[rs]2 \[rs]3
|
|
; rewrites \[dq]assets:bank:wells fargo:checking\[dq] to \[dq]assets:wells fargo checking\[dq]
|
|
.EE
|
|
.PP
|
|
REPLACEMENT continues to the end of line (or on command line, to end of
|
|
option argument), so it can contain trailing whitespace.
|
|
.SS Combining aliases
|
|
You can define as many aliases as you like, using journal directives
|
|
and/or command line options.
|
|
.PP
|
|
Recursive aliases \- where an account name is rewritten by one alias,
|
|
then by another alias, and so on \- are allowed.
|
|
Each alias sees the effect of previously applied aliases.
|
|
.PP
|
|
In such cases it can be important to understand which aliases will be
|
|
applied and in which order.
|
|
For (each account name in) each journal entry, we apply:
|
|
.IP "1." 3
|
|
\f[CR]alias\f[R] directives preceding the journal entry, most recently
|
|
parsed first (ie, reading upward from the journal entry, bottom to top)
|
|
.IP "2." 3
|
|
\f[CR]\-\-alias\f[R] options, in the order they appeared on the command
|
|
line (left to right).
|
|
.PP
|
|
In other words, for (an account name in) a given journal entry:
|
|
.IP \[bu] 2
|
|
the nearest alias declaration before/above the entry is applied first
|
|
.IP \[bu] 2
|
|
the next alias before/above that will be be applied next, and so on
|
|
.IP \[bu] 2
|
|
aliases defined after/below the entry do not affect it.
|
|
.PP
|
|
This gives nearby aliases precedence over distant ones, and helps
|
|
provide semantic stability \- aliases will keep working the same way
|
|
independent of which files are being read and in which order.
|
|
.PP
|
|
In case of trouble, adding \f[CR]\-\-debug=6\f[R] to the command line
|
|
will show which aliases are being applied when.
|
|
.SS Aliases and multiple files
|
|
As explained at Directives and multiple files, \f[CR]alias\f[R]
|
|
directives do not affect parent or sibling files.
|
|
Eg in this command,
|
|
.IP
|
|
.EX
|
|
hledger \-f a.aliases \-f b.journal
|
|
.EE
|
|
.PP
|
|
account aliases defined in a.aliases will not affect b.journal.
|
|
Including the aliases doesn\[aq]t work either:
|
|
.IP
|
|
.EX
|
|
include a.aliases
|
|
|
|
2023\-01\-01 ; not affected by a.aliases
|
|
foo 1
|
|
bar
|
|
.EE
|
|
.PP
|
|
This means that account aliases should usually be declared at the start
|
|
of your top\-most file, like this:
|
|
.IP
|
|
.EX
|
|
alias foo=Foo
|
|
alias bar=Bar
|
|
|
|
2023\-01\-01 ; affected by aliases above
|
|
foo 1
|
|
bar
|
|
|
|
include c.journal ; also affected
|
|
.EE
|
|
.SS \f[CR]end aliases\f[R] directive
|
|
You can clear (forget) all currently defined aliases (seen in the
|
|
journal so far, or defined on the command line) with this directive:
|
|
.IP
|
|
.EX
|
|
end aliases
|
|
.EE
|
|
.SS Aliases can generate bad account names
|
|
Be aware that account aliases can produce malformed account names, which
|
|
could cause confusing reports or invalid \f[CR]print\f[R] output.
|
|
For example, you could erase all account names:
|
|
.IP
|
|
.EX
|
|
2021\-01\-01
|
|
a:aa 1
|
|
b
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger print \-\-alias \[aq]/.*/=\[aq]
|
|
2021\-01\-01
|
|
1
|
|
.EE
|
|
.PP
|
|
The above \f[CR]print\f[R] output is not a valid journal.
|
|
Or you could insert an illegal double space, causing \f[CR]print\f[R]
|
|
output that would give a different journal when reparsed:
|
|
.IP
|
|
.EX
|
|
2021\-01\-01
|
|
old 1
|
|
other
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger print \-\-alias old=\[dq]new USD\[dq] | hledger \-f\- print
|
|
2021\-01\-01
|
|
new USD 1
|
|
other
|
|
.EE
|
|
.SS Aliases and account types
|
|
If an account with a type declaration (see Declaring accounts > Account
|
|
types) is renamed by an alias, normally the account type remains in
|
|
effect.
|
|
.PP
|
|
However, renaming in a way that reshapes the account tree (eg renaming
|
|
parent accounts but not their children, or vice versa) could prevent
|
|
child accounts from inheriting the account type of their parents.
|
|
.PP
|
|
Secondly, if an account\[aq]s type is being inferred from its name,
|
|
renaming it by an alias could prevent or alter that.
|
|
.PP
|
|
If you are using account aliases and the \f[CR]type:\f[R] query is not
|
|
matching accounts as you expect, try troubleshooting with the accounts
|
|
command, eg something like:
|
|
.IP
|
|
.EX
|
|
$ hledger accounts \-\-types \-1 \-\-alias assets=bassetts
|
|
.EE
|
|
.SS \f[CR]commodity\f[R] directive
|
|
The \f[CR]commodity\f[R] directive performs several functions:
|
|
.IP "1." 3
|
|
It declares which commodity symbols may be used in the journal, enabling
|
|
useful error checking with strict mode or the check command.
|
|
See Commodity error checking below.
|
|
.IP "2." 3
|
|
It declares how all amounts in this commodity should be displayed, eg
|
|
how many decimals to show.
|
|
See Commodity display style above.
|
|
.IP "3." 3
|
|
(If no \f[CR]decimal\-mark\f[R] directive is in effect:) It sets the
|
|
decimal mark to expect (period or comma) when parsing amounts in this
|
|
commodity, in this file and files it includes, from the directive until
|
|
end of current file.
|
|
See Decimal marks above.
|
|
.IP "4." 3
|
|
It declares the precision with which this commodity\[aq]s amounts should
|
|
be compared when checking for balanced transactions, anywhere in this
|
|
file and files it includes, until end of current file.
|
|
.PP
|
|
Declaring commodities solves several common parsing/display problems, so
|
|
we recommend it.
|
|
.PP
|
|
Note that effects 3 and 4 above end at the end of the directive\[aq]s
|
|
file, and will not affect sibling or parent files.
|
|
So if you are relying on them (especially 4) and using multiple files,
|
|
placing your commodity directives in a top\-level parent file might be
|
|
important.
|
|
Or, keep your decimal marks unambiguous and your entries well balanced
|
|
and precise.
|
|
.PP
|
|
Omitting the commodity symbol will set the display style for just the
|
|
no\-symbol commodity, not all commodities.
|
|
.PP
|
|
Commodity styles can be overridden by the
|
|
\f[CR]\-c/\-\-commodity\-style\f[R] command line option.
|
|
.PP
|
|
(Related: #793)
|
|
.SS Commodity directive syntax
|
|
A commodity directive is normally the word \f[CR]commodity\f[R] followed
|
|
by a sample amount (and optionally a comment).
|
|
Only the amount\[aq]s symbol and the number\[aq]s format is significant.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
commodity $1000.00
|
|
commodity 1.000,00 EUR
|
|
commodity 1 000 000.0000 ; the no\-symbol commodity
|
|
.EE
|
|
.PP
|
|
Commodities do not have tags (tags in the comment will be ignored).
|
|
.PP
|
|
A commodity directive\[aq]s sample amount must always include a period
|
|
or comma decimal mark (this rule helps disambiguate decimal marks and
|
|
digit group marks).
|
|
If you don\[aq]t want to show any decimal digits, write the decimal mark
|
|
at the end:
|
|
.IP
|
|
.EX
|
|
commodity 1000. AAAA ; show AAAA with no decimals
|
|
.EE
|
|
.PP
|
|
Commodity symbols containing spaces, numbers, or punctuation must be
|
|
enclosed in double quotes, as usual:
|
|
.IP
|
|
.EX
|
|
commodity 1.0000 \[dq]AAAA 2023\[dq]
|
|
.EE
|
|
.PP
|
|
Commodity directives normally include a sample amount, but can declare
|
|
only a symbol (ie, just function 1 above):
|
|
.IP
|
|
.EX
|
|
commodity $
|
|
commodity INR
|
|
commodity \[dq]AAAA 2023\[dq]
|
|
commodity \[dq]\[dq] ; the no\-symbol commodity
|
|
.EE
|
|
.PP
|
|
Commodity directives may also be written with an indented
|
|
\f[CR]format\f[R] subdirective, as in Ledger.
|
|
The symbol is repeated and must be the same in both places.
|
|
Other subdirectives are currently ignored:
|
|
.IP
|
|
.EX
|
|
; display indian rupees with currency name on the left,
|
|
; thousands, lakhs and crores comma\-separated,
|
|
; period as decimal point, and two decimal places.
|
|
commodity INR
|
|
format INR 1,00,00,000.00
|
|
an unsupported subdirective ; ignored by hledger
|
|
.EE
|
|
.SS Commodity error checking
|
|
In strict mode (\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R]) (or when you run
|
|
\f[CR]hledger check commodities\f[R]), hledger will report an error if
|
|
an undeclared commodity symbol is used.
|
|
(With one exception: zero amounts are always allowed to have no
|
|
commodity symbol.)
|
|
It works like account error checking (described above).
|
|
.SS \f[CR]decimal\-mark\f[R] directive
|
|
You can use a \f[CR]decimal\-mark\f[R] directive \- usually one per
|
|
file, at the top of the file \- to declare which character represents a
|
|
decimal mark when parsing amounts in this file.
|
|
It can look like
|
|
.IP
|
|
.EX
|
|
decimal\-mark .
|
|
.EE
|
|
.PP
|
|
or
|
|
.IP
|
|
.EX
|
|
decimal\-mark ,
|
|
.EE
|
|
.PP
|
|
This prevents any ambiguity when parsing numbers in the file, so we
|
|
recommend it, especially if the file contains digit group marks (eg
|
|
thousands separators).
|
|
.SS \f[CR]include\f[R] directive
|
|
You can pull in the content of additional files by writing an include
|
|
directive, like this:
|
|
.IP
|
|
.EX
|
|
include SOMEFILE
|
|
.EE
|
|
.PP
|
|
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
|
|
Only journal files can include other files.
|
|
They can include journal, timeclock or timedot files, but not CSV files.
|
|
.PP
|
|
If the file path begins with a tilde, that means your home directory:
|
|
\f[CR]include \[ti]/main.journal\f[R].
|
|
.PP
|
|
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
|
|
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 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.
|
|
This allows value reports to convert amounts of one commodity to their
|
|
value in another, on or after that date.
|
|
These prices are often obtained from a stock exchange, cryptocurrency
|
|
exchange, the or foreign exchange market.
|
|
.PP
|
|
The format is:
|
|
.IP
|
|
.EX
|
|
P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT
|
|
.EE
|
|
.PP
|
|
DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity
|
|
being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity)
|
|
of commodity 2 that one unit of commodity 1 is worth on this date.
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
# one euro was worth $1.35 from 2009\-01\-01 onward:
|
|
P 2009\-01\-01 € $1.35
|
|
|
|
# and $1.40 from 2010\-01\-01 onward:
|
|
P 2010\-01\-01 € $1.40
|
|
.EE
|
|
.PP
|
|
The \f[CR]\-V\f[R], \f[CR]\-X\f[R] and \f[CR]\-\-value\f[R] flags use
|
|
these market prices to show amount values in another commodity.
|
|
See Value reporting.
|
|
.PP
|
|
.SS \f[CR]payee\f[R] directive
|
|
\f[CR]payee PAYEE NAME\f[R]
|
|
.PP
|
|
This directive can be used to declare a limited set of payees which may
|
|
appear in transaction descriptions.
|
|
The \[dq]payees\[dq] check will report an error if any transaction
|
|
refers to a payee that has not been declared.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
payee Whole Foods ; a comment
|
|
.EE
|
|
.PP
|
|
Payees do not have tags (tags in the comment will be ignored).
|
|
.PP
|
|
To declare the empty payee name, use \f[CR]\[dq]\[dq]\f[R].
|
|
.IP
|
|
.EX
|
|
payee \[dq]\[dq]
|
|
.EE
|
|
.PP
|
|
Ledger\-style indented subdirectives, if any, are currently ignored.
|
|
.SS \f[CR]tag\f[R] directive
|
|
\f[CR]tag TAGNAME\f[R]
|
|
.PP
|
|
This directive can be used to declare a limited set of tag names allowed
|
|
in tags.
|
|
TAGNAME should be a valid tag name (no spaces).
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
tag item\-id
|
|
.EE
|
|
.PP
|
|
Any indented subdirectives are currently ignored.
|
|
.PP
|
|
The \[dq]tags\[dq] check will report an error if any undeclared tag name
|
|
is used.
|
|
It is quite easy to accidentally create a tag through normal use of
|
|
colons in comments; if you want to prevent this, you can declare and
|
|
check your tags .
|
|
.SS Periodic transactions
|
|
The \f[CR]\[ti]\f[R] directive declares a \[dq]periodic rule\[dq] which
|
|
generates temporary extra transactions, usually recurring at some
|
|
interval, when hledger is run with the \f[CR]\-\-forecast\f[R] flag.
|
|
These \[dq]forecast transactions\[dq] are useful for forecasting future
|
|
activity.
|
|
They exist only for the duration of the report, and only when
|
|
\f[CR]\-\-forecast\f[R] is used; they are not saved in the journal file
|
|
by hledger.
|
|
.PP
|
|
Periodic rules also have a second use: with the \f[CR]\-\-budget\f[R]
|
|
flag they set budget goals for budgeting.
|
|
.PP
|
|
Periodic rules can be a little tricky, so before you use them, read this
|
|
whole section, or at least the following tips:
|
|
.IP "1." 3
|
|
Two spaces accidentally added or omitted will cause you trouble \- read
|
|
about this below.
|
|
.IP "2." 3
|
|
For troubleshooting, show the generated transactions with
|
|
\f[CR]hledger print \-\-forecast tag:generated\f[R] or
|
|
\f[CR]hledger register \-\-forecast tag:generated\f[R].
|
|
.IP "3." 3
|
|
Forecasted transactions will begin only after the last non\-forecasted
|
|
transaction\[aq]s date.
|
|
.IP "4." 3
|
|
Forecasted transactions will end 6 months from today, by default.
|
|
See below for the exact start/end rules.
|
|
.IP "5." 3
|
|
period expressions can be tricky.
|
|
Their documentation needs improvement, but is worth studying.
|
|
.IP "6." 3
|
|
Some period expressions with a repeating interval must begin on a
|
|
natural boundary of that interval.
|
|
Eg in \f[CR]weekly from DATE\f[R], DATE must be a monday.
|
|
\f[CR]\[ti] weekly from 2019/10/1\f[R] (a tuesday) will give an error.
|
|
.IP "7." 3
|
|
Other period expressions with an interval are automatically expanded to
|
|
cover a whole number of that interval.
|
|
(This is done to improve reports, but it also affects periodic
|
|
transactions.
|
|
Yes, it\[aq]s a bit inconsistent with the above.)
|
|
Eg: \f[CR]\[ti] every 10th day of month from 2023/01\f[R], which is
|
|
equivalent to \f[CR]\[ti] every 10th day of month from 2023/01/01\f[R],
|
|
will be adjusted to start on 2019/12/10.
|
|
.SS Periodic rule syntax
|
|
A periodic transaction rule looks like a normal journal entry, with the
|
|
date replaced by a tilde (\f[CR]\[ti]\f[R]) followed by a period
|
|
expression (mnemonic: \f[CR]\[ti]\f[R] looks like a recurring sine
|
|
wave.):
|
|
.IP
|
|
.EX
|
|
# every first of month
|
|
\[ti] monthly
|
|
expenses:rent $2000
|
|
assets:bank:checking
|
|
|
|
# every 15th of month in 2023\[aq]s first quarter:
|
|
\[ti] monthly from 2023\-04\-15 to 2023\-06\-16
|
|
expenses:utilities $400
|
|
assets:bank:checking
|
|
.EE
|
|
.PP
|
|
The period expression is the same syntax used for specifying
|
|
multi\-period reports, just interpreted differently; there, it specifies
|
|
report periods; here it specifies recurrence dates (the periods\[aq]
|
|
start dates).
|
|
.SS Periodic rules and relative dates
|
|
Partial or relative dates (like \f[CR]12/31\f[R], \f[CR]25\f[R],
|
|
\f[CR]tomorrow\f[R], \f[CR]last week\f[R], \f[CR]next quarter\f[R]) are
|
|
usually not recommended in periodic rules, since the results will change
|
|
as time passes.
|
|
If used, they will be interpreted relative to, in order of preference:
|
|
.IP "1." 3
|
|
the first day of the default year specified by a recent \f[CR]Y\f[R]
|
|
directive
|
|
.IP "2." 3
|
|
or the date specified with \f[CR]\-\-today\f[R]
|
|
.IP "3." 3
|
|
or the date on which you are running the report.
|
|
.PP
|
|
They will not be affected at all by report period or forecast period
|
|
dates.
|
|
.SS Two spaces between period expression and description!
|
|
If the period expression is followed by a transaction description, these
|
|
must be separated by \f[B]two or more spaces\f[R].
|
|
This helps hledger know where the period expression ends, so that
|
|
descriptions can not accidentally alter their meaning, as in this
|
|
example:
|
|
.IP
|
|
.EX
|
|
; 2 or more spaces needed here, so the period is not understood as \[dq]every 2 months in 2023\[dq]
|
|
; ||
|
|
; vv
|
|
\[ti] every 2 months in 2023, we will review
|
|
assets:bank:checking $1500
|
|
income:acme inc
|
|
.EE
|
|
.PP
|
|
So,
|
|
.IP \[bu] 2
|
|
Do write two spaces between your period expression and your transaction
|
|
description, if any.
|
|
.IP \[bu] 2
|
|
Don\[aq]t accidentally write two spaces in the middle of your period
|
|
expression.
|
|
.SS Auto postings
|
|
The \f[CR]=\f[R] directive declares an \[dq]auto posting rule\[dq],
|
|
which adds extra postings to existing transactions.
|
|
(Remember, postings are the account name & amount lines below a
|
|
transaction\[aq]s date & description.)
|
|
.PP
|
|
In the journal, an auto posting rule looks quite like a transaction, but
|
|
instead of date and description it has \f[CR]=\f[R] (mnemonic:
|
|
\[dq]match\[dq]) and a query, like this:
|
|
.IP
|
|
.EX
|
|
= QUERY
|
|
ACCOUNT AMOUNT
|
|
...
|
|
.EE
|
|
.PP
|
|
Queries are just like command line queries; an account name substring is
|
|
most common.
|
|
Query terms containing spaces should be enclosed in single or double
|
|
quotes.
|
|
.PP
|
|
Each \f[CR]=\f[R] rule works like this: when hledger is run with the
|
|
\f[CR]\-\-auto\f[R] flag, wherever the QUERY matches a posting in the
|
|
journal, the rule\[aq]s postings are added to that transaction,
|
|
immediately below the matched posting.
|
|
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
|
|
standard percentage.
|
|
AMOUNT can be:
|
|
.IP \[bu] 2
|
|
a number with no commodity symbol, like \f[CR]2\f[R].
|
|
The matched posting\[aq]s commodity symbol will be added to this.
|
|
.IP \[bu] 2
|
|
a normal amount with a commodity symbol, like \f[CR]$2\f[R].
|
|
This will be used as\-is.
|
|
.IP \[bu] 2
|
|
an asterisk followed by a number, like \f[CR]*2\f[R].
|
|
This will multiply the matched posting\[aq]s amount (and total price, if
|
|
any) by the number.
|
|
.IP \[bu] 2
|
|
an asterisk followed by an amount with commodity symbol, like
|
|
\f[CR]*$2\f[R].
|
|
This multiplies and also replaces the commodity symbol with this new
|
|
one.
|
|
.PP
|
|
Some examples:
|
|
.IP
|
|
.EX
|
|
; every time I buy food, schedule a dollar donation
|
|
= expenses:food
|
|
(liabilities:charity) $\-1
|
|
|
|
; when I buy a gift, also deduct that amount from a budget envelope subaccount
|
|
= expenses:gifts
|
|
assets:checking:gifts *\-1
|
|
assets:checking *1
|
|
|
|
2017/12/1
|
|
expenses:food $10
|
|
assets:checking
|
|
|
|
2017/12/14
|
|
expenses:gifts $20
|
|
assets:checking
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger print \-\-auto
|
|
2017\-12\-01
|
|
expenses:food $10
|
|
assets:checking
|
|
(liabilities:charity) $\-1
|
|
|
|
2017\-12\-14
|
|
expenses:gifts $20
|
|
assets:checking
|
|
assets:checking:gifts \-$20
|
|
assets:checking $20
|
|
.EE
|
|
.PP
|
|
Note that depending fully on generated data such as this has some
|
|
drawbacks \- it\[aq]s less portable, less future\-proof, less auditable
|
|
by others, and less robust (eg your balance assertions will depend on
|
|
whether you use or don\[aq]t use \f[CR]\-\-auto\f[R]).
|
|
An alternative is to use auto postings in \[dq]one time\[dq] fashion \-
|
|
use them to help build a complex journal entry, view it with
|
|
\f[CR]hledger print \-\-auto\f[R], and then copy that output into the
|
|
journal file to make it permanent.
|
|
.SS Auto postings and multiple files
|
|
An auto posting rule can affect any transaction in the current file, or
|
|
in any parent file or child file.
|
|
Note, currently it will not affect sibling files (when multiple
|
|
\f[CR]\-f\f[R]/\f[CR]\-\-file\f[R] are used \- see #1212).
|
|
.SS Auto postings and dates
|
|
A posting date (or secondary date) in the matched posting, or (taking
|
|
precedence) a posting date in the auto posting rule itself, will also be
|
|
used in the generated posting.
|
|
.SS Auto postings and transaction balancing / inferred amounts / balance assertions
|
|
Currently, auto postings are added:
|
|
.IP \[bu] 2
|
|
after missing amounts are inferred, and transactions are checked for
|
|
balancedness,
|
|
.IP \[bu] 2
|
|
but before balance assertions are checked.
|
|
.PP
|
|
Note this means that journal entries must be balanced both before and
|
|
after auto postings are added.
|
|
This changed in hledger 1.12+; see #893 for background.
|
|
.PP
|
|
This also means that you cannot have more than one auto\-posting with a
|
|
missing amount applied to a given transaction, as it will be unable to
|
|
infer amounts.
|
|
.SS Auto posting tags
|
|
Automated postings will have some extra tags:
|
|
.IP \[bu] 2
|
|
\f[CR]generated\-posting:= QUERY\f[R] \- shows this was generated by an
|
|
auto posting rule, and the query
|
|
.IP \[bu] 2
|
|
\f[CR]_generated\-posting:= QUERY\f[R] \- a hidden tag, which does not
|
|
appear in hledger\[aq]s output.
|
|
This can be used to match postings generated \[dq]just now\[dq], rather
|
|
than generated in the past and saved to the journal.
|
|
.PP
|
|
Also, any transaction that has been changed by auto posting rules will
|
|
have these tags added:
|
|
.IP \[bu] 2
|
|
\f[CR]modified:\f[R] \- this transaction was modified
|
|
.IP \[bu] 2
|
|
\f[CR]_modified:\f[R] \- a hidden tag not appearing in the comment; this
|
|
transaction was modified \[dq]just now\[dq].
|
|
.SS Auto postings on forecast transactions only
|
|
Tip: you can can make auto postings that will apply to forecast
|
|
transactions but not recorded transactions, by adding
|
|
\f[CR]tag:_generated\-transaction\f[R] to their QUERY.
|
|
This can be useful when generating new journal entries to be saved in
|
|
the journal.
|
|
.SS Other syntax
|
|
hledger journal format supports quite a few other features, mainly to
|
|
make interoperating with or converting from Ledger easier.
|
|
Note some of the features below are powerful and can be useful in
|
|
special cases, but in general, features in this section are considered
|
|
less important or even not recommended for most users.
|
|
Downsides are mentioned to help you decide if you want to use them.
|
|
.SS Balance assignments
|
|
Ledger\-style balance assignments are also supported.
|
|
These are like balance assertions, but with no posting amount on the
|
|
left side of the equals sign; instead it is calculated automatically so
|
|
as to satisfy the assertion.
|
|
This can be a convenience during data entry, eg when setting opening
|
|
balances:
|
|
.IP
|
|
.EX
|
|
; starting a new journal, set asset account balances
|
|
2016/1/1 opening balances
|
|
assets:checking = $409.32
|
|
assets:savings = $735.24
|
|
assets:cash = $42
|
|
equity:opening balances
|
|
.EE
|
|
.PP
|
|
or when adjusting a balance to reality:
|
|
.IP
|
|
.EX
|
|
; no cash left; update balance, record any untracked spending as a generic expense
|
|
2016/1/15
|
|
assets:cash = $0
|
|
expenses:misc
|
|
.EE
|
|
.PP
|
|
The calculated amount depends on the account\[aq]s balance in the
|
|
commodity at that point (which depends on the previously\-dated postings
|
|
of the commodity to that account since the last balance assertion or
|
|
assignment).
|
|
.PP
|
|
Downsides: using balance assignments makes your journal less explicit;
|
|
to know the exact amount posted, you have to run hledger or do the
|
|
calculations yourself, instead of just reading it.
|
|
Also balance assignments\[aq] forcing of balances can hide errors.
|
|
These things make your financial data less portable, less future\-proof,
|
|
and less trustworthy in an audit.
|
|
.SS Balance assignments and costs
|
|
A cost in a balance assignment will cause the calculated amount to have
|
|
that cost attached:
|
|
.IP
|
|
.EX
|
|
2019/1/1
|
|
(a) = $1 \[at] €2
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger print \-\-explicit
|
|
2019\-01\-01
|
|
(a) $1 \[at] €2 = $1 \[at] €2
|
|
.EE
|
|
.SS Balance assignments and multiple files
|
|
Balance assignments handle multiple files like balance assertions.
|
|
They see balance from other files previously included from the current
|
|
file, but not from previous sibling or parent files.
|
|
.SS Bracketed posting dates
|
|
For setting posting dates and secondary posting dates, Ledger\[aq]s
|
|
bracketed date syntax is also supported: \f[CR][DATE]\f[R],
|
|
\f[CR][DATE=DATE2]\f[R] or \f[CR][=DATE2]\f[R] in posting comments.
|
|
hledger will attempt to parse any square\-bracketed sequence of the
|
|
\f[CR]0123456789/\-.=\f[R] characters in this way.
|
|
With this syntax, DATE infers its year from the transaction and DATE2
|
|
infers its year from DATE.
|
|
.PP
|
|
Downsides: another syntax to learn, redundant with hledger\[aq]s
|
|
\f[CR]date:\f[R]/\f[CR]date2:\f[R] tags, and confusingly similar to
|
|
Ledger\[aq]s lot date syntax.
|
|
.SS \f[CR]D\f[R] directive
|
|
\f[CR]D AMOUNT\f[R]
|
|
.PP
|
|
This directive sets a default commodity, to be used for any subsequent
|
|
commodityless amounts (ie, plain numbers) seen while parsing the
|
|
journal.
|
|
This effect lasts until the next \f[CR]D\f[R] directive, or the end of
|
|
the current file.
|
|
.PP
|
|
For compatibility/historical reasons, \f[CR]D\f[R] also acts like a
|
|
\f[CR]commodity\f[R] directive (setting the commodity\[aq]s decimal mark
|
|
for parsing and display style for output).
|
|
So its argument is not just a commodity symbol, but a full amount
|
|
demonstrating the style.
|
|
The amount must include a decimal mark (either period or comma).
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
; commodity\-less amounts should be treated as dollars
|
|
; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
|
|
D $1,000.00
|
|
|
|
1/1
|
|
a 5 ; <\- commodity\-less amount, parsed as $5 and displayed as $5.00
|
|
b
|
|
.EE
|
|
.PP
|
|
Interactions with other directives:
|
|
.PP
|
|
For setting a commodity\[aq]s display style, a \f[CR]commodity\f[R]
|
|
directive has highest priority, then a \f[CR]D\f[R] directive.
|
|
.PP
|
|
For detecting a commodity\[aq]s decimal mark during parsing,
|
|
\f[CR]decimal\-mark\f[R] has highest priority, then
|
|
\f[CR]commodity\f[R], then \f[CR]D\f[R].
|
|
.PP
|
|
For checking commodity symbols with the check command, a
|
|
\f[CR]commodity\f[R] directive is required
|
|
(\f[CR]hledger check commodities\f[R] ignores \f[CR]D\f[R] directives).
|
|
.PP
|
|
Downsides: omitting commodity symbols makes your financial data less
|
|
explicit, less portable, and less trustworthy in an audit.
|
|
It is usually an unsustainable shortcut; sooner or later you will want
|
|
to track multiple commodities.
|
|
D is overloaded with functions redundant with \f[CR]commodity\f[R] and
|
|
\f[CR]decimal\-mark\f[R].
|
|
And it works differently from Ledger\[aq]s \f[CR]D\f[R].
|
|
.SS \f[CR]apply account\f[R] directive
|
|
This directive sets a default parent account, which will be prepended to
|
|
all accounts in following entries, until an \f[CR]end apply account\f[R]
|
|
directive or end of current file.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
apply account home
|
|
|
|
2010/1/1
|
|
food $10
|
|
cash
|
|
|
|
end apply account
|
|
.EE
|
|
.PP
|
|
is equivalent to:
|
|
.IP
|
|
.EX
|
|
2010/01/01
|
|
home:food $10
|
|
home:cash $\-10
|
|
.EE
|
|
.PP
|
|
\f[CR]account\f[R] directives are also affected, and so is any
|
|
\f[CR]include\f[R]d content.
|
|
.PP
|
|
Account names entered via hledger add or hledger\-web are not affected.
|
|
.PP
|
|
Account aliases, if any, are applied after the parent account is
|
|
prepended.
|
|
.PP
|
|
Downsides: this can make your financial data less explicit, less
|
|
portable, and less trustworthy in an audit.
|
|
.SS \f[CR]Y\f[R] directive
|
|
\f[CR]Y YEAR\f[R]
|
|
.PP
|
|
or (deprecated backward\-compatible forms):
|
|
.PP
|
|
\f[CR]year YEAR\f[R] \f[CR]apply year YEAR\f[R]
|
|
.PP
|
|
The space is optional.
|
|
This sets a default year to be used for subsequent dates which don\[aq]t
|
|
specify a year.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
Y2009 ; set default year to 2009
|
|
|
|
12/15 ; equivalent to 2009/12/15
|
|
expenses 1
|
|
assets
|
|
|
|
year 2010 ; change default year to 2010
|
|
|
|
2009/1/30 ; specifies the year, not affected
|
|
expenses 1
|
|
assets
|
|
|
|
1/31 ; equivalent to 2010/1/31
|
|
expenses 1
|
|
assets
|
|
.EE
|
|
.PP
|
|
Downsides: omitting the year (from primary transaction dates, at least)
|
|
makes your financial data less explicit, less portable, and less
|
|
trustworthy in an audit.
|
|
Such dates can get separated from their corresponding Y directive, eg
|
|
when evaluating a region of the journal in your editor.
|
|
A missing Y directive makes reports dependent on today\[aq]s date.
|
|
.SS Secondary dates
|
|
A secondary date is written after the primary date, following an equals
|
|
sign: \f[CR]DATE1=DATE2\f[R].
|
|
If the year is omitted, the primary date\[aq]s year is assumed.
|
|
When running reports, the primary (left side) date is used by default,
|
|
but with the \f[CR]\-\-date2\f[R] flag (\f[CR]\-\-aux\-date\f[R]
|
|
or\f[CR]\-\-effective\f[R] also work, for Ledger users), the secondary
|
|
(right side) date will be used instead.
|
|
.PP
|
|
The meaning of secondary dates is up to you.
|
|
Eg it could be \[dq]primary is the bank\[aq]s clearing date, secondary
|
|
is the date the transaction was initiated, if different\[dq].
|
|
.PP
|
|
In practice, this feature usually adds confusion:
|
|
.IP \[bu] 2
|
|
You have to remember the primary and secondary dates\[aq] meaning, and
|
|
follow that consistently.
|
|
.IP \[bu] 2
|
|
It splits your bookkeeping into two modes, and you have to remember
|
|
which mode is appropriate for a given report.
|
|
.IP \[bu] 2
|
|
Usually your balance assertions will work with only one of these modes.
|
|
.IP \[bu] 2
|
|
It makes your financial data more complicated, less portable, and less
|
|
clear in an audit.
|
|
.IP \[bu] 2
|
|
It interacts with every feature, creating an ongoing cost for
|
|
implementors.
|
|
.IP \[bu] 2
|
|
It distracts new users and supporters.
|
|
.IP \[bu] 2
|
|
Posting dates are simpler and work better.
|
|
.PP
|
|
So secondary dates are officially deprecated in hledger, remaining only
|
|
as a Ledger compatibility aid; we recommend using posting dates instead.
|
|
.SS Star comments
|
|
Lines beginning with \f[CR]*\f[R] (star/asterisk) are also comment
|
|
lines.
|
|
This feature allows Emacs users to insert org headings in their journal,
|
|
allowing them to fold/unfold/navigate it like an outline when viewed
|
|
with org mode.
|
|
.PP
|
|
Downsides: another, unconventional comment syntax to learn.
|
|
Decreases your journal\[aq]s portability.
|
|
And switching to Emacs org mode just for folding/unfolding meant losing
|
|
the benefits of ledger mode; nowadays you can add outshine mode to
|
|
ledger mode to get folding without losing ledger mode\[aq]s features.
|
|
.SS Valuation expressions
|
|
Ledger allows a valuation function or value to be written in double
|
|
parentheses after an amount.
|
|
hledger ignores these.
|
|
.SS Virtual postings
|
|
A posting with parentheses around the account name, like
|
|
\f[CR](some:account) 10\f[R], is called an \f[I]unbalanced virtual
|
|
posting\f[R].
|
|
These postings do not participate in transaction balancing.
|
|
(And if you write them without an amount, a zero amount is always
|
|
inferred.)
|
|
These can occasionally be convenient for special circumstances, but they
|
|
violate double entry bookkeeping and make your data less portable across
|
|
applications, so many people avoid using them at all.
|
|
.PP
|
|
A posting with brackets around the account name
|
|
(\f[CR][some:account]\f[R]) is called a \f[I]balanced virtual
|
|
posting\f[R].
|
|
The balanced virtual postings in a transaction must add up to zero, just
|
|
like ordinary postings, but separately from them.
|
|
These are not part of double entry bookkeeping either, but they are at
|
|
least balanced.
|
|
An example:
|
|
.IP
|
|
.EX
|
|
2022\-01\-01 buy food with cash, update budget envelope subaccounts, & something else
|
|
assets:cash $\-10 ; <\- these balance each other
|
|
expenses:food $7 ; <\-
|
|
expenses:food $3 ; <\-
|
|
[assets:checking:budget:food] $\-10 ; <\- and these balance each other
|
|
[assets:checking:available] $10 ; <\-
|
|
(something:else) $5 ; <\- this is not required to balance
|
|
.EE
|
|
.PP
|
|
Ordinary postings, whose account names are neither parenthesised nor
|
|
bracketed, are called \f[I]real postings\f[R].
|
|
You can exclude virtual postings from reports with the
|
|
\f[CR]\-R/\-\-real\f[R] flag or a \f[CR]real:1\f[R] query.
|
|
.SS Other Ledger directives
|
|
These other Ledger directives are currently accepted but ignored.
|
|
This allows hledger to read more Ledger files, but be aware that
|
|
hledger\[aq]s reports may differ from Ledger\[aq]s if you use these.
|
|
.IP
|
|
.EX
|
|
apply fixed COMM AMT
|
|
apply tag TAG
|
|
assert EXPR
|
|
bucket / A ACCT
|
|
capture ACCT REGEX
|
|
check EXPR
|
|
define VAR=EXPR
|
|
end apply fixed
|
|
end apply tag
|
|
end apply year
|
|
end tag
|
|
eval / expr EXPR
|
|
python
|
|
PYTHONCODE
|
|
tag NAME
|
|
value EXPR
|
|
\-\-command\-line\-flags
|
|
.EE
|
|
.PP
|
|
See also https://hledger.org/ledger.html for a detailed hledger/Ledger
|
|
syntax comparison.
|
|
.SS Other cost/lot notations
|
|
A slight digression for Ledger and Beancount users.
|
|
.PP
|
|
\f[B]Ledger\f[R] has a number of cost/lot\-related notations:
|
|
.IP \[bu] 2
|
|
\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R]
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
expresses a conversion rate, as in hledger
|
|
.IP \[bu] 2
|
|
when buying, also creates a lot that can be selected at selling time
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CR](\[at]) UNITCOST\f[R] and \f[CR](\[at]\[at]) TOTALCOST\f[R]
|
|
(virtual cost)
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
like the above, but also means \[dq]this cost was exceptional, don\[aq]t
|
|
use it when inferring market prices\[dq].
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CR]{=UNITCOST}\f[R] and \f[CR]{{=TOTALCOST}}\f[R] (fixed price)
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
when buying, means \[dq]this cost is also the fixed value, don\[aq]t let
|
|
it fluctuate in value reports\[dq]
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R] (lot price)
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
can be used identically to \f[CR]\[at] UNITCOST\f[R] and
|
|
\f[CR]\[at]\[at] TOTALCOST\f[R], also creates a lot
|
|
.IP \[bu] 2
|
|
when selling, combined with \f[CR]\[at] ...\f[R], selects an existing
|
|
lot by its cost basis.
|
|
Does not check if that lot is present.
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CR][YYYY/MM/DD]\f[R] (lot date)
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
when buying, attaches this acquisition date to the lot
|
|
.IP \[bu] 2
|
|
when selling, selects a lot by its acquisition date
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CR](SOME TEXT)\f[R] (lot note)
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
when buying, attaches this note to the lot
|
|
.IP \[bu] 2
|
|
when selling, selects a lot by its note
|
|
.RE
|
|
.PP
|
|
Currently, hledger
|
|
.IP \[bu] 2
|
|
accepts any or all of the above in any order after the posting amount
|
|
.IP \[bu] 2
|
|
supports \f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]
|
|
.IP \[bu] 2
|
|
treats \f[CR](\[at])\f[R] and \f[CR](\[at]\[at])\f[R] as synonyms for
|
|
\f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]
|
|
.IP \[bu] 2
|
|
and ignores the rest.
|
|
(This can break transaction balancing.)
|
|
.PP
|
|
\f[B]Beancount\f[R] has simpler notation and different behaviour:
|
|
.IP \[bu] 2
|
|
\f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R]
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
expresses a cost without creating a lot, as in hledger
|
|
.IP \[bu] 2
|
|
when buying (acquiring) or selling (disposing of) a lot, and combined
|
|
with \f[CR]{...}\f[R]: is not used except to document the cost/selling
|
|
price
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R]
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
when buying, expresses the cost for transaction balancing, and also
|
|
creates a lot with this cost basis attached
|
|
.IP \[bu] 2
|
|
when selling,
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
selects a lot by its cost basis
|
|
.IP \[bu] 2
|
|
raises an error if that lot is not present or can not be selected
|
|
unambiguously (depending on booking method configured)
|
|
.IP \[bu] 2
|
|
expresses the selling price for transaction balancing
|
|
.RE
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R], \f[CR]{\[dq]LABEL\[dq]}\f[R],
|
|
\f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R],
|
|
\f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R]
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
when selling, other combinations of date/cost/label, like the above, are
|
|
accepted for selecting the lot.
|
|
.RE
|
|
.PP
|
|
Currently, hledger
|
|
.IP \[bu] 2
|
|
supports \f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]
|
|
.IP \[bu] 2
|
|
accepts the \f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation, but
|
|
ignores it
|
|
.IP \[bu] 2
|
|
and rejects the rest.
|
|
.PP
|
|
.SH CSV
|
|
hledger can read transactions from CSV (comma\-separated values) files.
|
|
More precisely, it can read DSV (delimiter\-separated values), from a
|
|
file or standard input.
|
|
Comma\-separated, semicolon\-separated and tab\-separated are the most
|
|
common variants, and hledger will recognise these three automatically
|
|
based on a \f[CR].csv\f[R], \f[CR].ssv\f[R] or \f[CR].tsv\f[R] file name
|
|
extension or a \f[CR]csv:\f[R], \f[CR]ssv:\f[R] or \f[CR]tsv:\f[R] file
|
|
path prefix.
|
|
.PP
|
|
(To learn about producing CSV or TSV \f[I]output\f[R], see Output
|
|
format.)
|
|
.PP
|
|
Each CSV file must be described by a corresponding \f[I]rules file\f[R].
|
|
This contains rules describing the CSV data (header line, fields layout,
|
|
date format etc.), how to construct hledger transactions from it, and
|
|
how to categorise transactions based on description or other attributes.
|
|
.PP
|
|
By default, hledger expects this rules file to be named like the CSV
|
|
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\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
|
|
are.
|
|
Here\[aq]s a simple CSV file and a rules file for it:
|
|
.IP
|
|
.EX
|
|
Date, Description, Id, Amount
|
|
12/11/2019, Foo, 123, 10.23
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# basic.csv.rules
|
|
skip 1
|
|
fields date, description, , amount
|
|
date\-format %d/%m/%Y
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger print \-f basic.csv
|
|
2019\-11\-12 Foo
|
|
expenses:unknown 10.23
|
|
income:unknown \-10.23
|
|
.EE
|
|
.PP
|
|
There\[aq]s an introductory Tutorial: Import CSV data on hledger.org,
|
|
and more CSV rules examples below, and a larger collection at
|
|
https://github.com/simonmichael/hledger/tree/master/examples/csv.
|
|
.SS CSV rules cheatsheet
|
|
The following kinds of rule can appear in the rules file, in any order.
|
|
(Blank lines and lines beginning with \f[CR]#\f[R] or \f[CR];\f[R] or
|
|
\f[CR]*\f[R] are ignored.)
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(23.7n) lw(46.3n).
|
|
T{
|
|
\f[B]\f[CB]source\f[B]\f[R]
|
|
T}@T{
|
|
optionally declare which file to read data from
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]archive\f[B]\f[R]
|
|
T}@T{
|
|
optionally enable an archive of imported files
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]encoding\f[B]\f[R]
|
|
T}@T{
|
|
optionally declare which text encoding the data has
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]separator\f[B]\f[R]
|
|
T}@T{
|
|
declare the field separator, instead of relying on file extension
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]skip\f[B]\f[R]
|
|
T}@T{
|
|
skip one or more header lines at start of file
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]date\-format\f[B]\f[R]
|
|
T}@T{
|
|
declare how to parse CSV dates/date\-times
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]timezone\f[B]\f[R]
|
|
T}@T{
|
|
declare the time zone of ambiguous CSV date\-times
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]newest\-first\f[B]\f[R]
|
|
T}@T{
|
|
improve txn order when: there are multiple records, newest first, all
|
|
with the same date
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]intra\-day\-reversed\f[B]\f[R]
|
|
T}@T{
|
|
improve txn order when: same\-day txns are in opposite order to the
|
|
overall file
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]decimal\-mark\f[B]\f[R]
|
|
T}@T{
|
|
declare the decimal mark used in CSV amounts, when ambiguous
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]fields\f[B] list\f[R]
|
|
T}@T{
|
|
name CSV fields for easy reference, and optionally assign their values
|
|
to hledger fields
|
|
T}
|
|
T{
|
|
\f[B]Field assignment\f[R]
|
|
T}@T{
|
|
assign a CSV value or interpolated text value to a hledger field
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]if\f[B] block\f[R]
|
|
T}@T{
|
|
conditionally assign values to hledger fields, or \f[CR]skip\f[R] a
|
|
record or \f[CR]end\f[R] (skip rest of file)
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]if\f[B] table\f[R]
|
|
T}@T{
|
|
conditionally assign values to hledger fields, using compact syntax
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]balance\-type\f[B]\f[R]
|
|
T}@T{
|
|
select which type of balance assertions/assignments to generate
|
|
T}
|
|
T{
|
|
\f[B]\f[CB]include\f[B]\f[R]
|
|
T}@T{
|
|
inline another CSV rules file
|
|
T}
|
|
.TE
|
|
.PP
|
|
Working with CSV tips can be found below, including How CSV rules are
|
|
evaluated.
|
|
.SS \f[CR]source\f[R]
|
|
If you tell hledger to read a csv file with \f[CR]\-f foo.csv\f[R], it
|
|
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).
|
|
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.
|
|
.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 the \f[CR]\[ti]/Downloads\f[R] folder:
|
|
.IP
|
|
.EX
|
|
source Checking1.csv
|
|
.EE
|
|
.PP
|
|
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].
|
|
.SS Data cleaning / generating commands
|
|
After \f[CR]source\f[R]\[aq]s file pattern, you can write \f[CR]|\f[R]
|
|
(pipe) and a data cleaning command.
|
|
If hledger\[aq]s CSV rules aren\[aq]t enough, you can pre\-process the
|
|
downloaded data here with a shell command or script, to make it more
|
|
suitable for conversion.
|
|
The command will be executed by your default shell, in the directory of
|
|
the rules file, will receive the data file\[aq]s content as standard
|
|
input, and should output zero or more lines of
|
|
character\-separated\-values, suitable for conversion by the CSV rules.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
source ./paypal.json | paypalcsv
|
|
source data/simplefin.json | simplefincsv \- \[aq]chase.*card\[aq]
|
|
source OfxDownload*.csv | grep \-vE \[aq]\[ha](([\[ha],]*,){6}[\[ha],]*|)$\[aq] | sort \-t, \-n +2
|
|
source History_for_Account_Z20144832*.csv # | grep \-E \[aq]\[ha]([\[ha],]*,){12}[\[ha],]*$\[aq] | sed \-E \-e \[aq]s/\[ha] //\[aq] \-e \[aq]s/\[rs].([0\-9]),/.\[rs]10,/g\[aq] \-e \[aq]s/,([0\-9]+),/,\[rs]1.00,/g\[aq]
|
|
.EE
|
|
.PP
|
|
Or, after \f[CR]source\f[R] you can write \f[CR]|\f[R] and a data
|
|
generating command (with no file pattern before the \f[CR]|\f[R]).
|
|
This command receives no input, and should output zero or more lines of
|
|
character\-separated values, suitable for conversion by the CSV rules.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
source | paypaljson | paypalcsv
|
|
source | paypalcsv data/paypal.json
|
|
source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json \[aq]chase.*card\[aq]
|
|
source | simplefincsv data/simplefin.json \[aq]unify.*checking\[aq]
|
|
.EE
|
|
.PP
|
|
(\f[CR]paypal*\f[R] and \f[CR]simplefin*\f[R] scripts are in bin/)
|
|
.PP
|
|
Whenever hledger runs one of these commands, it will echo the command on
|
|
stderr.
|
|
If the command produces error output, but exits successfully, hledger
|
|
will show the error output as a warning.
|
|
If the command fails, hledger will fail and show the error output in the
|
|
error message.
|
|
.PP
|
|
\f[I]Added in 1.50; experimental.\f[R]
|
|
.SS \f[CR]archive\f[R]
|
|
With \f[CR]archive\f[R] added to a rules file, the \f[CR]import\f[R]
|
|
command will archive each successfully processed data file or data
|
|
command output in a nearby \f[CR]data/\f[R] directory.
|
|
The archive file name will be based on the rules file and the data
|
|
file\[aq]s modification date and extension (or for a data\-generating
|
|
command, the current date and the \[dq].csv\[dq] extension).
|
|
The original data file, if any, will be removed.
|
|
.PP
|
|
Also, in this mode \f[CR]import\f[R] will prefer the oldest file matched
|
|
by the \f[CR]source\f[R] rule\[aq]s glob pattern, not the newest.
|
|
(So if there are multiple downloads, they will be imported and archived
|
|
oldest first.)
|
|
.PP
|
|
Archiving is optional, but it can be useful for troubleshooting your CSV
|
|
rules, regenerating entries with improved rules, checking for variations
|
|
in your bank\[aq]s CSV, etc.
|
|
.PP
|
|
\f[I]Added in 1.50; experimental.\f[R]
|
|
.SS \f[CR]encoding\f[R]
|
|
.IP
|
|
.EX
|
|
encoding ENCODING
|
|
.EE
|
|
.PP
|
|
hledger normally expects non\-ascii text to be using the system
|
|
locale\[aq]s text encoding.
|
|
If you need to read CSV files which have some other encoding, you can do
|
|
it by adding \f[CR]encoding ENCODING\f[R] to your CSV rules.
|
|
Eg: \f[CR]encoding iso\-8859\-1\f[R].
|
|
.PP
|
|
The following encodings are supported:
|
|
.PP
|
|
\f[CR]ascii\f[R], \f[CR]utf\-8\f[R], \f[CR]utf\-16\f[R],
|
|
\f[CR]utf\-32\f[R], \f[CR]iso\-8859\-1\f[R], \f[CR]iso\-8859\-2\f[R],
|
|
\f[CR]iso\-8859\-3\f[R], \f[CR]iso\-8859\-4\f[R],
|
|
\f[CR]iso\-8859\-5\f[R], \f[CR]iso\-8859\-6\f[R],
|
|
\f[CR]iso\-8859\-7\f[R], \f[CR]iso\-8859\-8\f[R],
|
|
\f[CR]iso\-8859\-9\f[R], \f[CR]iso\-8859\-10\f[R],
|
|
\f[CR]iso\-8859\-11\f[R], \f[CR]iso\-8859\-13\f[R],
|
|
\f[CR]iso\-8859\-14\f[R], \f[CR]iso\-8859\-15\f[R],
|
|
\f[CR]iso\-8859\-16\f[R], \f[CR]cp1250\f[R], \f[CR]cp1251\f[R],
|
|
\f[CR]cp1252\f[R], \f[CR]cp1253\f[R], \f[CR]cp1254\f[R],
|
|
\f[CR]cp1255\f[R], \f[CR]cp1256\f[R], \f[CR]cp1257\f[R],
|
|
\f[CR]cp1258\f[R], \f[CR]koi8\-r\f[R], \f[CR]koi8\-u\f[R],
|
|
\f[CR]gb18030\f[R], \f[CR]macintosh\f[R], \f[CR]jis\-x\-0201\f[R],
|
|
\f[CR]jis\-x\-0208\f[R], \f[CR]iso\-2022\-jp\f[R],
|
|
\f[CR]shift\-jis\f[R], \f[CR]cp437\f[R], \f[CR]cp737\f[R],
|
|
\f[CR]cp775\f[R], \f[CR]cp850\f[R], \f[CR]cp852\f[R], \f[CR]cp855\f[R],
|
|
\f[CR]cp857\f[R], \f[CR]cp860\f[R], \f[CR]cp861\f[R], \f[CR]cp862\f[R],
|
|
\f[CR]cp863\f[R], \f[CR]cp864\f[R], \f[CR]cp865\f[R], \f[CR]cp866\f[R],
|
|
\f[CR]cp869\f[R], \f[CR]cp874\f[R], \f[CR]cp932\f[R].
|
|
.PP
|
|
\f[I]Added in 1.42.\f[R]
|
|
.SS \f[CR]separator\f[R]
|
|
You can use the \f[CR]separator\f[R] rule to read other kinds of
|
|
character\-separated data.
|
|
The argument is any single separator character, or the words
|
|
\f[CR]tab\f[R] or \f[CR]space\f[R] (case insensitive).
|
|
Eg, for comma\-separated values (CSV):
|
|
.IP
|
|
.EX
|
|
separator ,
|
|
.EE
|
|
.PP
|
|
or for semicolon\-separated values (SSV):
|
|
.IP
|
|
.EX
|
|
separator ;
|
|
.EE
|
|
.PP
|
|
or for tab\-separated values (TSV):
|
|
.IP
|
|
.EX
|
|
separator TAB
|
|
.EE
|
|
.PP
|
|
If the input file has a \f[CR].csv\f[R], \f[CR].ssv\f[R] or
|
|
\f[CR].tsv\f[R] file extension (or a \f[CR]csv:\f[R], \f[CR]ssv:\f[R],
|
|
\f[CR]tsv:\f[R] prefix), the appropriate separator will be inferred
|
|
automatically, and you won\[aq]t need this rule.
|
|
.SS \f[CR]skip\f[R]
|
|
.IP
|
|
.EX
|
|
skip N
|
|
.EE
|
|
.PP
|
|
The word \f[CR]skip\f[R] followed by a number (or no number, meaning 1)
|
|
tells hledger to ignore this many non\-empty lines at the start of the
|
|
input data.
|
|
You\[aq]ll need this whenever your CSV data contains header lines.
|
|
Note, empty and blank lines are skipped automatically, so you don\[aq]t
|
|
need to count those.
|
|
.PP
|
|
\f[CR]skip\f[R] has a second meaning: it can be used inside if blocks
|
|
(described below), to skip one or more records whenever the condition is
|
|
true.
|
|
Records skipped in this way are ignored, except they are still required
|
|
to be valid CSV.
|
|
.SS \f[CR]date\-format\f[R]
|
|
.IP
|
|
.EX
|
|
date\-format DATEFMT
|
|
.EE
|
|
.PP
|
|
This is a helper for the \f[CR]date\f[R] (and \f[CR]date2\f[R]) fields.
|
|
If your CSV dates are not formatted like \f[CR]YYYY\-MM\-DD\f[R],
|
|
\f[CR]YYYY/MM/DD\f[R] or \f[CR]YYYY.MM.DD\f[R], you\[aq]ll need to add a
|
|
date\-format rule describing them with a strptime\-style date parsing
|
|
pattern \- see
|
|
https://hackage.haskell.org/package/time/docs/Data\-Time\-Format.html#v:formatTime.
|
|
The pattern must parse the CSV date value completely.
|
|
Some examples:
|
|
.IP
|
|
.EX
|
|
# MM/DD/YY
|
|
date\-format %m/%d/%y
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# D/M/YYYY
|
|
# The \- makes leading zeros optional.
|
|
date\-format %\-d/%\-m/%Y
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# YYYY\-Mmm\-DD
|
|
date\-format %Y\-%h\-%d
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# M/D/YYYY HH:MM AM some other junk
|
|
# 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
|
|
timezone TIMEZONE
|
|
.EE
|
|
.PP
|
|
When CSV contains date\-times that are implicitly in some time zone
|
|
other than yours, but containing no explicit time zone information, you
|
|
can use this rule to declare the CSV\[aq]s native time zone, which helps
|
|
prevent off\-by\-one dates.
|
|
.PP
|
|
When the CSV date\-times do contain time zone information, you don\[aq]t
|
|
need this rule; instead, use \f[CR]%Z\f[R] in \f[CR]date\-format\f[R]
|
|
(or \f[CR]%z\f[R], \f[CR]%EZ\f[R], \f[CR]%Ez\f[R]; see the formatTime
|
|
link above).
|
|
.PP
|
|
In either of these cases, hledger will do a time\-zone\-aware
|
|
conversion, localising the CSV date\-times to your current system time
|
|
zone.
|
|
If you prefer to localise to some other time zone, eg for
|
|
reproducibility, you can (on unix at least) set the output timezone with
|
|
the TZ environment variable, eg:
|
|
.IP
|
|
.EX
|
|
$ TZ=\-1000 hledger print \-f foo.csv # or TZ=\-1000 hledger import foo.csv
|
|
.EE
|
|
.PP
|
|
\f[CR]timezone\f[R] currently does not understand timezone names, except
|
|
\[dq]UTC\[dq], \[dq]GMT\[dq], \[dq]EST\[dq], \[dq]EDT\[dq],
|
|
\[dq]CST\[dq], \[dq]CDT\[dq], \[dq]MST\[dq], \[dq]MDT\[dq],
|
|
\[dq]PST\[dq], or \[dq]PDT\[dq].
|
|
For others, use numeric format: +HHMM or \-HHMM.
|
|
.SS \f[CR]newest\-first\f[R]
|
|
hledger tries to ensure that the generated transactions will be ordered
|
|
chronologically, including same\-day transactions.
|
|
Usually it can auto\-detect how the CSV records are ordered.
|
|
But if it encounters CSV where all records are on the same date, it
|
|
assumes that the records are oldest first.
|
|
If in fact the CSV\[aq]s records are normally newest first, like:
|
|
.IP
|
|
.EX
|
|
2022\-10\-01, txn 3...
|
|
2022\-10\-01, txn 2...
|
|
2022\-10\-01, txn 1...
|
|
.EE
|
|
.PP
|
|
you can add the \f[CR]newest\-first\f[R] rule to help hledger generate
|
|
the transactions in correct order.
|
|
.IP
|
|
.EX
|
|
# same\-day CSV records are newest first
|
|
newest\-first
|
|
.EE
|
|
.SS \f[CR]intra\-day\-reversed\f[R]
|
|
If CSV records within a single day are ordered opposite to the overall
|
|
record order, you can add the \f[CR]intra\-day\-reversed\f[R] rule to
|
|
improve the order of journal entries.
|
|
Eg, here the overall record order is newest first, but same\-day records
|
|
are oldest first:
|
|
.IP
|
|
.EX
|
|
2022\-10\-02, txn 3...
|
|
2022\-10\-02, txn 4...
|
|
2022\-10\-01, txn 1...
|
|
2022\-10\-01, txn 2...
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# transactions within each day are reversed with respect to the overall date order
|
|
intra\-day\-reversed
|
|
.EE
|
|
.SS \f[CR]decimal\-mark\f[R]
|
|
.IP
|
|
.EX
|
|
decimal\-mark .
|
|
.EE
|
|
.PP
|
|
or:
|
|
.IP
|
|
.EX
|
|
decimal\-mark ,
|
|
.EE
|
|
.PP
|
|
hledger automatically accepts either period or comma as a decimal mark
|
|
when parsing numbers (cf Amounts).
|
|
However if any numbers in the CSV contain digit group marks, such as
|
|
thousand\-separating commas, you should declare the decimal mark
|
|
explicitly with this rule, to avoid misparsed numbers.
|
|
.SS \f[CR]fields\f[R] list
|
|
.IP
|
|
.EX
|
|
fields FIELDNAME1, FIELDNAME2, ...
|
|
.EE
|
|
.PP
|
|
A fields list (the word \f[CR]fields\f[R] followed by comma\-separated
|
|
field names) is optional, but convenient.
|
|
It does two things:
|
|
.IP "1." 3
|
|
It names the CSV field in each column.
|
|
This can be convenient if you are referencing them in other rules, so
|
|
you can say \f[CR]%SomeField\f[R] instead of remembering \f[CR]%13\f[R].
|
|
.IP "2." 3
|
|
Whenever you use one of the special hledger field names (described
|
|
below), it assigns the CSV value in this position to that hledger field.
|
|
This is the quickest way to populate hledger\[aq]s fields and build a
|
|
transaction.
|
|
.PP
|
|
Here\[aq]s an example that says \[dq]use the 1st, 2nd and 4th fields as
|
|
the transaction\[aq]s date, description and amount; name the last two
|
|
fields for later reference; and ignore the others\[dq]:
|
|
.IP
|
|
.EX
|
|
fields date, description, , amount, , , somefield, anotherfield
|
|
.EE
|
|
.PP
|
|
In a fields list, the separator is always comma; it is unrelated to the
|
|
CSV file\[aq]s separator.
|
|
Also:
|
|
.IP \[bu] 2
|
|
There must be least two items in the list (at least one comma).
|
|
.IP \[bu] 2
|
|
Field names may not contain spaces.
|
|
Spaces before/after field names are optional.
|
|
.IP \[bu] 2
|
|
Field names may contain \f[CR]_\f[R] (underscore) or \f[CR]\-\f[R]
|
|
(hyphen).
|
|
.IP \[bu] 2
|
|
Fields you don\[aq]t care about can be given a dummy name or an empty
|
|
name.
|
|
.PP
|
|
If the CSV contains column headings, it\[aq]s convenient to use these
|
|
for your field names, suitably modified (eg lower\-cased with spaces
|
|
replaced by underscores).
|
|
.PP
|
|
Sometimes you may want to alter a CSV field name to avoid assigning to a
|
|
hledger field with the same name.
|
|
Eg you could call the CSV\[aq]s \[dq]balance\[dq] field
|
|
\f[CR]balance_\f[R] to avoid directly setting hledger\[aq]s
|
|
\f[CR]balance\f[R] field (and generating a balance assertion).
|
|
.SS Field assignment
|
|
.IP
|
|
.EX
|
|
HLEDGERFIELD FIELDVALUE
|
|
.EE
|
|
.PP
|
|
Field assignments are the more flexible way to assign CSV values to
|
|
hledger fields.
|
|
They can be used instead of or in addition to a fields list (see above).
|
|
.PP
|
|
To assign a value to a hledger field, write the field name (any of the
|
|
standard hledger field/pseudo\-field names, defined below), a space,
|
|
followed by a text value on the same line.
|
|
This text value may interpolate CSV fields, referenced either by their
|
|
1\-based position in the CSV record (\f[CR]%N\f[R]) or by the name they
|
|
were given in the fields list (\f[CR]%CSVFIELD\f[R]), and regular
|
|
expression match groups (\f[CR]\[rs]N\f[R]).
|
|
.PP
|
|
Some examples:
|
|
.IP
|
|
.EX
|
|
# set the amount to the 4th CSV field, with \[dq] USD\[dq] appended
|
|
amount %4 USD
|
|
|
|
# combine three fields to make a comment, containing note: and date: tags
|
|
comment note: %somefield \- %anotherfield, date: %1
|
|
.EE
|
|
.PP
|
|
Tips:
|
|
.IP \[bu] 2
|
|
Interpolation strips outer whitespace (so a CSV value like
|
|
\f[CR]\[dq] 1 \[dq]\f[R] becomes \f[CR]1\f[R] when interpolated)
|
|
(#1051).
|
|
.IP \[bu] 2
|
|
Interpolations always refer to a CSV field \- you can\[aq]t interpolate
|
|
a hledger field.
|
|
(See Referencing other fields below).
|
|
.SS Field names
|
|
Note the two kinds of field names mentioned here, and used only in
|
|
hledger CSV rules files:
|
|
.IP "1." 3
|
|
\f[B]CSV field names\f[R] (\f[CR]CSVFIELD\f[R] in these docs): you can
|
|
optionally name the CSV columns for easy reference (since hledger
|
|
doesn\[aq]t yet automatically recognise column headings in a CSV file),
|
|
by writing arbitrary names in a \f[CR]fields\f[R] list, eg:
|
|
.RS 4
|
|
.IP
|
|
.EX
|
|
fields When, What, Some_Id, Net, Total, Foo, Bar
|
|
.EE
|
|
.RE
|
|
.IP "2." 3
|
|
Special \f[B]hledger field names\f[R] (\f[CR]HLEDGERFIELD\f[R] in these
|
|
docs): you must set at least some of these to generate the hledger
|
|
transaction from a CSV record, by writing them as the left hand side of
|
|
a field assignment, eg:
|
|
.RS 4
|
|
.IP
|
|
.EX
|
|
date %When
|
|
code %Some_Id
|
|
description %What
|
|
comment %Foo %Bar
|
|
amount1 $ %Total
|
|
.EE
|
|
.PP
|
|
or directly in a \f[CR]fields\f[R] list:
|
|
.IP
|
|
.EX
|
|
fields date, description, code, , amount1, Foo, Bar
|
|
currency $
|
|
comment %Foo %Bar
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Here are all the special hledger field names available, and what happens
|
|
when you assign values to them:
|
|
.SS date field
|
|
Assigning to \f[CR]date\f[R] sets the transaction date.
|
|
.SS date2 field
|
|
\f[CR]date2\f[R] sets the transaction\[aq]s secondary date, if any.
|
|
.SS status field
|
|
\f[CR]status\f[R] sets the transaction\[aq]s status, if any.
|
|
.SS code field
|
|
\f[CR]code\f[R] sets the transaction\[aq]s code, if any.
|
|
.SS description field
|
|
\f[CR]description\f[R] sets the transaction\[aq]s description, if any.
|
|
.SS comment field
|
|
\f[CR]comment\f[R] sets the transaction\[aq]s comment, if any.
|
|
.PP
|
|
\f[CR]commentN\f[R], where N is a number, sets the Nth posting\[aq]s
|
|
comment.
|
|
.PP
|
|
You can assign multi\-line comments by writing literal \f[CR]\[rs]n\f[R]
|
|
in the code.
|
|
A comment starting with \f[CR]\[rs]n\f[R] will begin on a new line.
|
|
.PP
|
|
Comments can contain tags, as usual.
|
|
.PP
|
|
Posting comments can also contain a posting date.
|
|
A secondary date, or a year\-less date, will be ignored.
|
|
.SS account field
|
|
Assigning to \f[CR]accountN\f[R], where N is 1 to 99, sets the account
|
|
name of the Nth posting, and causes that posting to be generated.
|
|
.PP
|
|
Most often there are two postings, so you\[aq]ll want to set
|
|
\f[CR]account1\f[R] and \f[CR]account2\f[R].
|
|
Typically \f[CR]account1\f[R] is associated with the CSV file, and is
|
|
set once with a top\-level assignment, while \f[CR]account2\f[R] is set
|
|
based on each transaction\[aq]s description, in conditional rules.
|
|
.PP
|
|
If a posting\[aq]s account name is left unset but its amount is set (see
|
|
below), a default account name will be chosen (like
|
|
\[dq]expenses:unknown\[dq] or \[dq]income:unknown\[dq]).
|
|
.SS amount field
|
|
There are several ways to set posting amounts from CSV, useful in
|
|
different situations.
|
|
.IP "1." 3
|
|
\f[B]\f[CB]amount\f[B]\f[R] is the oldest and simplest.
|
|
Assigning to this sets the amount of the first and second postings.
|
|
In the second posting, the amount will be negated; also, if it has a
|
|
cost attached, it will be converted to cost.
|
|
.IP "2." 3
|
|
\f[B]\f[CB]amount\-in\f[B]\f[R] and \f[B]\f[CB]amount\-out\f[B]\f[R]
|
|
work exactly like the above, but should be used when the CSV has two
|
|
amount fields (such as \[dq]Debit\[dq] and \[dq]Credit\[dq], or
|
|
\[dq]Inflow\[dq] and \[dq]Outflow\[dq]).
|
|
Whichever field has a non\-zero value will be used as the amount of the
|
|
first and second postings.
|
|
Here are some tips to avoid confusion:
|
|
.RS 4
|
|
.IP \[bu] 2
|
|
It\[aq]s not \[dq]amount\-in for posting 1 and amount\-out for posting
|
|
2\[dq], it is \[dq]extract a single amount from the amount\-in or
|
|
amount\-out field, and use that for posting 1 and (negated) for posting
|
|
2\[dq].
|
|
.IP \[bu] 2
|
|
Don\[aq]t use both \f[CR]amount\f[R] and
|
|
\f[CR]amount\-in\f[R]/\f[CR]amount\-out\f[R] in the same rules file;
|
|
choose based on whether the amount is in a single CSV field or spread
|
|
across two fields.
|
|
.IP \[bu] 2
|
|
In each record, at most one of the two CSV fields should contain a
|
|
non\-zero amount; the other field must contain a zero or nothing.
|
|
.IP \[bu] 2
|
|
hledger assumes both CSV fields contain unsigned numbers, and it
|
|
automatically negates the amount\-out values.
|
|
.IP \[bu] 2
|
|
If the data doesn\[aq]t fit these requirements, you\[aq]ll probably need
|
|
an if rule (see below).
|
|
.RE
|
|
.IP "3." 3
|
|
\f[B]\f[CB]amountN\f[B]\f[R] (where N is a number from 1 to 99) sets the
|
|
amount of only a single posting: the Nth posting in the transaction.
|
|
You\[aq]ll usually need at least two such assignments to make a balanced
|
|
transaction.
|
|
You can also generate more than two postings, to represent more complex
|
|
transactions.
|
|
The posting numbers don\[aq]t have to be consecutive; with if rules,
|
|
higher posting numbers can be useful to ensure a certain order of
|
|
postings.
|
|
.IP "4." 3
|
|
\f[B]\f[CB]amountN\-in\f[B]\f[R] and \f[B]\f[CB]amountN\-out\f[B]\f[R]
|
|
work exactly like the above, but should be used when the CSV has two
|
|
amount fields.
|
|
This is analogous to \f[CR]amount\-in\f[R] and \f[CR]amount\-out\f[R],
|
|
and those tips also apply here.
|
|
.IP "5." 3
|
|
Remember that a \f[CR]fields\f[R] list can also do assignments.
|
|
So in a fields list if you name a CSV field \[dq]amount\[dq], that
|
|
counts as assigning to \f[CR]amount\f[R].
|
|
(If you don\[aq]t want that, call it something else in the fields list,
|
|
like \[dq]amount_\[dq].)
|
|
.IP "6." 3
|
|
The above don\[aq]t handle every situation; if you need more
|
|
flexibility, use an \f[CR]if\f[R] rule to set amounts conditionally.
|
|
See \[dq]Working with CSV > Setting amounts\[dq] below for more on this
|
|
and on amount\-setting generally.
|
|
.SS currency field
|
|
\f[CR]currency\f[R] sets a currency symbol, to be prepended to all
|
|
postings\[aq] amounts.
|
|
You can use this if the CSV amounts do not have a currency symbol, eg if
|
|
it is in a separate column.
|
|
.PP
|
|
\f[CR]currencyN\f[R] prepends a currency symbol to just the Nth
|
|
posting\[aq]s amount.
|
|
.SS balance field
|
|
\f[CR]balanceN\f[R] sets a balance assertion amount (or if the posting
|
|
amount is left empty, a balance assignment) on posting N.
|
|
.PP
|
|
\f[CR]balance\f[R] is a compatibility spelling for hledger <1.17; it is
|
|
equivalent to \f[CR]balance1\f[R].
|
|
.PP
|
|
You can adjust the type of assertion/assignment with the
|
|
\f[CR]balance\-type\f[R] rule (see below).
|
|
.PP
|
|
See the Working with CSV tips below for more about setting amounts and
|
|
currency.
|
|
.SS \f[CR]if\f[R] block
|
|
Rules can be applied conditionally, depending on patterns in the CSV
|
|
data.
|
|
This allows flexibility; in particular, it is how you can categorise
|
|
transactions, selecting an appropriate account name based on their
|
|
description (for example).
|
|
There are two ways to write conditional rules: \[dq]if blocks\[dq],
|
|
described here, and \[dq]if tables\[dq], described below.
|
|
.PP
|
|
An if block is the word \f[CR]if\f[R] and one or more \[dq]matcher\[dq]
|
|
expressions (can be a word or phrase), one per line, starting either on
|
|
the same or next line; followed by one or more indented rules.
|
|
Eg,
|
|
.IP
|
|
.EX
|
|
if MATCHER
|
|
RULE
|
|
.EE
|
|
.PP
|
|
or
|
|
.IP
|
|
.EX
|
|
if
|
|
MATCHER
|
|
MATCHER
|
|
MATCHER
|
|
RULE
|
|
RULE
|
|
.EE
|
|
.PP
|
|
If any of the matchers succeeds, all of the indented rules will be
|
|
applied.
|
|
They are usually field assignments, but the following special rules may
|
|
also be used within an if block:
|
|
.IP \[bu] 2
|
|
\f[CR]skip\f[R] \- skips the matched CSV record (generating no
|
|
transaction from it)
|
|
.IP \[bu] 2
|
|
\f[CR]end\f[R] \- skips the rest of the current CSV file.
|
|
.PP
|
|
Some examples:
|
|
.IP
|
|
.EX
|
|
# if the record contains \[dq]groceries\[dq], set account2 to \[dq]expenses:groceries\[dq]
|
|
if groceries
|
|
account2 expenses:groceries
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# if the record contains any of these phrases, set account2 and a transaction comment as shown
|
|
if
|
|
monthly service fee
|
|
atm transaction fee
|
|
banking thru software
|
|
account2 expenses:business:banking
|
|
comment XXX deductible ? check it
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# if an empty record is seen (assuming five fields), ignore the rest of the CSV file
|
|
if ,,,,
|
|
end
|
|
.EE
|
|
.SS Matchers
|
|
There are two kinds of matcher:
|
|
.IP "1." 3
|
|
A whole record matcher is simplest: it is just a word, single\-line text
|
|
fragment, or other regular expression, which hledger will try to match
|
|
case\-insensitively anywhere within the CSV record.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Eg: \f[CR]whole foods\f[R].
|
|
.IP "2." 3
|
|
A field matcher has a percent\-prefixed CSV field number or name before
|
|
the pattern.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Eg: \f[CR]%3 whole foods\f[R] or \f[CR]%description whole foods\f[R].
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
hledger will try to match the pattern just within the named CSV field.
|
|
.PP
|
|
When using these, there\[aq]s two things to be aware of:
|
|
.IP "1." 3
|
|
Whole record matchers don\[aq]t see the exact original record; they see
|
|
a reconstruction of it, in which values are comma\-separated, and quotes
|
|
enclosing values and whitespace outside those quotes are removed.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Eg when reading an SSV record like:
|
|
\f[CR]2023\-01\-01 ; \[dq]Acme, Inc. \[dq] ; 1,000\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
the whole record matcher sees instead:
|
|
\f[CR]2023\-01\-01,Acme, Inc. ,1,000\f[R]
|
|
.IP "2." 3
|
|
Field matchers expect either a CSV field number, or a CSV field name
|
|
declared with \f[CR]fields\f[R].
|
|
(Don\[aq]t use a hledger field name here, unless it is also a CSV field
|
|
name.)
|
|
A non\-CSV field name will cause the matcher to match against
|
|
\f[CR]\[dq]\[dq]\f[R] (the empty string), and does not raise an error,
|
|
allowing easier reuse of common rules with different CSV files.
|
|
.PP
|
|
You can also prefix a matcher with \f[CR]!\f[R] (and optional space) to
|
|
negate it.
|
|
Eg \f[CR]! whole foods\f[R], \f[CR]! %3 whole foods\f[R],
|
|
\f[CR]!%description whole foods\f[R] will match if \[dq]whole foods\[dq]
|
|
is NOT present.
|
|
\f[I]Added in 1.32.\f[R]
|
|
.PP
|
|
The pattern is, as usual in hledger, a POSIX extended regular expression
|
|
that also supports GNU word boundaries (\f[CR]\[rs]b\f[R],
|
|
\f[CR]\[rs]B\f[R], \f[CR]\[rs]<\f[R], \f[CR]\[rs]>\f[R]) and nothing
|
|
else.
|
|
If you have trouble with it, see \[dq]Regular expressions\[dq] in the
|
|
hledger manual (https://hledger.org/hledger.html#regular\-expressions).
|
|
.SS Multiple matchers
|
|
When an if block has multiple matchers, each on its own line,
|
|
.IP \[bu] 2
|
|
By default they are OR\[aq]d (any of them can match).
|
|
.IP \[bu] 2
|
|
Matcher lines beginning with \f[CR]&\f[R] (or \f[CR]&&\f[R], \f[I]since
|
|
1.42\f[R]) are AND\[aq]ed with the matcher above (all in the AND\[aq]ed
|
|
group must match).
|
|
.IP \[bu] 2
|
|
Matcher lines beginning with \f[CR]& !\f[R] (\f[I]since 1.41\f[R], or
|
|
\f[CR]&& !\f[R], \f[I]since 1.42\f[R]) are first negated and then
|
|
AND\[aq]ed with the matcher above.
|
|
.PP
|
|
You can also combine multiple matchers one the same line separated by
|
|
\f[CR]&&\f[R] (AND) or \f[CR]&& !\f[R] (AND NOT).
|
|
Eg \f[CR]%description amazon && %date 2025\-01\-01\f[R] will match only
|
|
when the description field contains \[dq]amazon\[dq] and the date field
|
|
contains \[dq]2025\-01\-01\[dq].
|
|
\f[I]Added in 1.42.\f[R]
|
|
.SS Match groups
|
|
\f[I]Added in 1.32\f[R]
|
|
.PP
|
|
Matchers can define match groups: parenthesised portions of the regular
|
|
expression which are available for reference in field assignments.
|
|
Groups are enclosed in regular parentheses (\f[CR](\f[R] and
|
|
\f[CR])\f[R]) and can be nested.
|
|
Each group is available in field assignments using the token
|
|
\f[CR]\[rs]N\f[R], where N is an index into the match groups for this
|
|
conditional block (e.g.
|
|
\f[CR]\[rs]1\f[R], \f[CR]\[rs]2\f[R], etc.).
|
|
.PP
|
|
Example: Warp credit card payment postings to the beginning of the
|
|
billing period (Month start), to match how they are presented in
|
|
statements, using posting dates:
|
|
.IP
|
|
.EX
|
|
if %date (....\-..)\-..
|
|
comment2 date:\[rs]1\-01
|
|
.EE
|
|
.PP
|
|
Another example: Read the expense account from the CSV field, but throw
|
|
away a prefix:
|
|
.IP
|
|
.EX
|
|
if %account1 liabilities:family:(expenses:.*)
|
|
account1 \[rs]1
|
|
.EE
|
|
.SS \f[CR]if\f[R] table
|
|
\[dq]if tables\[dq] are an alternative to if blocks; they can express
|
|
many matchers and field assignments in a more compact tabular format,
|
|
like this:
|
|
.IP
|
|
.EX
|
|
if,HLEDGERFIELD1,HLEDGERFIELD2,...
|
|
MATCHERA,VALUE1,VALUE2,...
|
|
MATCHERB && MATCHERC,VALUE1,VALUE2,... (*since 1.42*)
|
|
; Comment line that explains MATCHERD
|
|
MATCHERD,VALUE1,VALUE2,...
|
|
<empty line>
|
|
.EE
|
|
.PP
|
|
The first character after \f[CR]if\f[R] is taken to be this if
|
|
table\[aq]s field separator.
|
|
It is unrelated to the separator used in the CSV file.
|
|
It should be a non\-alphanumeric character like \f[CR],\f[R] or
|
|
\f[CR]|\f[R] that does not appear anywhere else in the table (it should
|
|
not be used in field names or matchers or values, and it cannot be
|
|
escaped with a backslash).
|
|
.PP
|
|
Each line must contain the same number of separators; empty values are
|
|
allowed.
|
|
Whitespace can be used in the matcher lines for readability (but not in
|
|
the if line, currently).
|
|
You can use the comment lines in the table body.
|
|
The table must be terminated by an empty line (or end of file).
|
|
.PP
|
|
An if table like the above is interpreted as follows: try all of the
|
|
lines with matchers; whenever a line with matchers succeeds, assign all
|
|
of the values on that line to the corresponding hledger fields; If
|
|
multiple lines match, later lines will override fields assigned by the
|
|
earlier ones \- just like the sequence of \f[CR]if\f[R] blocks would
|
|
behave.
|
|
.PP
|
|
If table presented above is equivalent to this sequence of if blocks:
|
|
.IP
|
|
.EX
|
|
if MATCHERA
|
|
HLEDGERFIELD1 VALUE1
|
|
HLEDGERFIELD2 VALUE2
|
|
...
|
|
|
|
if MATCHERB && MATCHERC
|
|
HLEDGERFIELD1 VALUE1
|
|
HLEDGERFIELD2 VALUE2
|
|
...
|
|
|
|
; Comment line which explains MATCHERD
|
|
if MATCHERD
|
|
HLEDGERFIELD1 VALUE1
|
|
HLEDGERFIELD2 VALUE2
|
|
...
|
|
.EE
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
if,account2,comment
|
|
atm transaction fee,expenses:business:banking,deductible? check it
|
|
%description groceries,expenses:groceries,
|
|
;; Comment line that desribes why this particular date is special
|
|
2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call\-out
|
|
.EE
|
|
.SS \f[CR]balance\-type\f[R]
|
|
Balance assertions generated by assigning to balanceN are of the simple
|
|
\f[CR]=\f[R] type by default, which is a single\-commodity,
|
|
subaccount\-excluding assertion.
|
|
You may find the subaccount\-including variants more useful, eg if you
|
|
have created some virtual subaccounts of checking to help with
|
|
budgeting.
|
|
You can select a different type of assertion with the
|
|
\f[CR]balance\-type\f[R] rule:
|
|
.IP
|
|
.EX
|
|
# balance assertions will consider all commodities and all subaccounts
|
|
balance\-type ==*
|
|
.EE
|
|
.PP
|
|
Here are the balance assertion types for quick reference:
|
|
.IP
|
|
.EX
|
|
= single commodity, exclude subaccounts
|
|
=* single commodity, include subaccounts
|
|
== multi commodity, exclude subaccounts
|
|
==* multi commodity, include subaccounts
|
|
.EE
|
|
.SS \f[CR]include\f[R]
|
|
.IP
|
|
.EX
|
|
include RULESFILE
|
|
.EE
|
|
.PP
|
|
This includes the contents of another CSV rules file at this point.
|
|
\f[CR]RULESFILE\f[R] is an absolute file path or a path relative to the
|
|
current file\[aq]s directory.
|
|
This can be useful for sharing common rules between several rules files,
|
|
eg:
|
|
.IP
|
|
.EX
|
|
# someaccount.csv.rules
|
|
|
|
## someaccount\-specific rules
|
|
fields date,description,amount
|
|
account1 assets:someaccount
|
|
account2 expenses:misc
|
|
|
|
## common rules
|
|
include categorisation.rules
|
|
.EE
|
|
.SS Working with CSV
|
|
Some tips:
|
|
.SS Rapid feedback
|
|
It\[aq]s a good idea to get rapid feedback while
|
|
creating/troubleshooting CSV rules.
|
|
Here\[aq]s a good way, using entr from eradman.com/entrproject:
|
|
.IP
|
|
.EX
|
|
$ ls foo.csv* | entr bash \-c \[aq]echo \-\-\-\-; hledger \-f foo.csv print desc:SOMEDESC\[aq]
|
|
.EE
|
|
.PP
|
|
A desc: query (eg) is used to select just one, or a few, transactions of
|
|
interest.
|
|
\[dq]bash \-c\[dq] is used to run multiple commands, so we can echo a
|
|
separator each time the command re\-runs, making it easier to read the
|
|
output.
|
|
.SS Valid CSV
|
|
Note that hledger will only accept valid CSV conforming to RFC 4180, and
|
|
equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab
|
|
as separators).
|
|
This means, eg:
|
|
.IP \[bu] 2
|
|
Values may be enclosed in double quotes, or not.
|
|
Enclosing in single quotes is not allowed.
|
|
(Eg \f[CR]\[aq]A\[aq],\[aq]B\[aq]\f[R] is rejected.)
|
|
.IP \[bu] 2
|
|
When values are enclosed in double quotes, spaces outside the quotes are
|
|
not allowed.
|
|
(Eg \f[CR]\[dq]A\[dq], \[dq]B\[dq]\f[R] is rejected.)
|
|
.IP \[bu] 2
|
|
When values are not enclosed in quotes, they may not contain double
|
|
quotes.
|
|
(Eg \f[CR]A\[dq]A, B\f[R] is rejected.)
|
|
.PP
|
|
If your CSV/SSV/TSV is not valid in this sense, you\[aq]ll need to
|
|
transform it before reading with hledger.
|
|
Try using sed, or a more permissive CSV parser like python\[aq]s csv
|
|
lib.
|
|
.SS File Extension
|
|
To help hledger choose the CSV file reader and show the right error
|
|
messages (and choose the right field separator character by default),
|
|
it\[aq]s best if CSV/SSV/TSV files are named with a \f[CR].csv\f[R],
|
|
\f[CR].ssv\f[R] or \f[CR].tsv\f[R] filename extension.
|
|
(More about this at Data formats.)
|
|
.PP
|
|
When reading files with the \[dq]wrong\[dq] extension, you can ensure
|
|
the CSV reader (and the default field separator) by prefixing the file
|
|
path with \f[CR]csv:\f[R], \f[CR]ssv:\f[R] or \f[CR]tsv:\f[R]: Eg:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f ssv:foo.dat print
|
|
.EE
|
|
.PP
|
|
You can also override the default field separator with a separator rule
|
|
if needed.
|
|
.SS Reading CSV from standard input
|
|
You\[aq]ll need the file format prefix when reading CSV from stdin also,
|
|
since hledger assumes journal format by default.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
$ cat foo.dat | hledger \-f ssv:\- print
|
|
.EE
|
|
.SS Reading multiple CSV files
|
|
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 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].
|
|
By default this will read data from foo.csv in the same directory, but
|
|
you can add a source rule to specify a different data file, perhaps
|
|
located in your web browser\[aq]s download directory.
|
|
.PP
|
|
This feature was added in hledger 1.30, so you won\[aq]t see it in most
|
|
CSV rules examples.
|
|
But it helps remove some of the busywork of managing CSV downloads.
|
|
Most of your financial institutions\[aq]s default CSV filenames are
|
|
different and can be recognised by a glob pattern.
|
|
So you can put a rule like \f[CR]source Checking1*.csv\f[R] in
|
|
foo\-checking.csv.rules, and then periodically follow a workflow like:
|
|
.IP "1." 3
|
|
Download CSV from Foo\[aq]s website, using your browser\[aq]s defaults
|
|
.IP "2." 3
|
|
Run \f[CR]hledger import foo\-checking.csv.rules\f[R] to import any new
|
|
transactions
|
|
.PP
|
|
After import, you can: discard the CSV, or leave it where it is for a
|
|
while, or move it into your archives, as you prefer.
|
|
If you do nothing, next time your browser will save something like
|
|
Checking1\-2.csv, and hledger will use that because of the \f[CR]*\f[R]
|
|
wild card and because it is the most recent.
|
|
.SS Valid transactions
|
|
After reading a CSV file, hledger post\-processes and validates the
|
|
generated journal entries as it would for a journal file \- balancing
|
|
them, applying balance assignments, and canonicalising amount styles.
|
|
Any errors at this stage will be reported in the usual way, displaying
|
|
the problem entry.
|
|
.PP
|
|
There is one exception: balance assertions, if you have generated them,
|
|
will not be checked, since normally these will work only when the CSV
|
|
data is part of the main journal.
|
|
If you do need to check balance assertions generated from CSV right
|
|
away, pipe into another hledger:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f file.csv print | hledger \-f\- print
|
|
.EE
|
|
.SS Deduplicating, importing
|
|
When you download a CSV file periodically, eg to get your latest bank
|
|
transactions, the new file may overlap with the old one, containing some
|
|
of the same records.
|
|
.PP
|
|
The import command will (a) detect the new transactions, and (b) append
|
|
just those transactions to your main journal.
|
|
It is idempotent, so you don\[aq]t have to remember how many times you
|
|
ran it or with which version of the CSV.
|
|
(It keeps state in a hidden \f[CR].latest.FILE.csv\f[R] file.)
|
|
This is the easiest way to import CSV data.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
# download the latest CSV files, then run this command.
|
|
# Note, no \-f flags needed here.
|
|
$ hledger import *.csv [\-\-dry]
|
|
.EE
|
|
.PP
|
|
This method works for most CSV files.
|
|
(Where records have a stable chronological order, and new records appear
|
|
only at the new end.)
|
|
.PP
|
|
A number of other tools and workflows, hledger\-specific and otherwise,
|
|
exist for converting, deduplicating, classifying and managing CSV data.
|
|
See:
|
|
.IP \[bu] 2
|
|
https://hledger.org/cookbook.html#setups\-and\-workflows
|
|
.IP \[bu] 2
|
|
https://plaintextaccounting.org \-> data import/conversion
|
|
.SS Setting amounts
|
|
Continuing from amount field above, here are more tips for
|
|
amount\-setting:
|
|
.IP "1." 3
|
|
\f[B]If the amount is in a single CSV field:\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.RS 4
|
|
.IP "a." 3
|
|
\f[B]If its sign indicates direction of flow:\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Assign it to \f[CR]amountN\f[R], to set the Nth posting\[aq]s amount.
|
|
N is usually 1 or 2 but can go up to 99.
|
|
.IP "b." 3
|
|
\f[B]If another field indicates direction of flow:\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Use one or more conditional rules to set the appropriate amount sign.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
# assume a withdrawal unless Type contains \[dq]deposit\[dq]:
|
|
amount1 \-%Amount
|
|
if %Type deposit
|
|
amount1 %Amount
|
|
.EE
|
|
.RE
|
|
.IP "2." 3
|
|
\f[B]If the amount is in two CSV fields (such as Debit and Credit, or In
|
|
and Out):\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.RS 4
|
|
.IP "a." 3
|
|
\f[B]If both fields are unsigned:\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Assign one field to \f[CR]amountN\-in\f[R] and the other to
|
|
\f[CR]amountN\-out\f[R].
|
|
hledger will automatically negate the \[dq]out\[dq] field, and will use
|
|
whichever field value is non\-zero as posting N\[aq]s amount.
|
|
.IP "b." 3
|
|
\f[B]If either field is signed:\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
You will probably need to override hledger\[aq]s sign for one or the
|
|
other field, as in the following example:
|
|
.IP
|
|
.EX
|
|
# Negate the \-out value, but only if it is not empty:
|
|
fields date, description, amount1\-in, amount1\-out
|
|
if %amount1\-out [1\-9]
|
|
amount1\-out \-%amount1\-out
|
|
.EE
|
|
.IP "c." 3
|
|
\f[B]If both fields can contain a non\-zero value (or both can be
|
|
empty):\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
The \-in/\-out rules normally choose the value which is
|
|
non\-zero/non\-empty.
|
|
Some value pairs can be ambiguous, such as \f[CR]1\f[R] and
|
|
\f[CR]none\f[R].
|
|
For such cases, use conditional rules to help select the amount.
|
|
Eg, to handle the above you could select the value containing non\-zero
|
|
digits:
|
|
.IP
|
|
.EX
|
|
fields date, description, in, out
|
|
if %in [1\-9]
|
|
amount1 %in
|
|
if %out [1\-9]
|
|
amount1 %out
|
|
.EE
|
|
.RE
|
|
.IP "3." 3
|
|
\f[B]If you want posting 2\[aq]s amount converted to cost:\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Use the unnumbered \f[CR]amount\f[R] (or \f[CR]amount\-in\f[R] and
|
|
\f[CR]amount\-out\f[R]) syntax.
|
|
.IP "4." 3
|
|
\f[B]If the CSV has only balance amounts, not transaction amounts:\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Assign to \f[CR]balanceN\f[R], to set a balance assignment on the Nth
|
|
posting, causing the posting\[aq]s amount to be calculated
|
|
automatically.
|
|
\f[CR]balance\f[R] with no number is equivalent to \f[CR]balance1\f[R].
|
|
In this situation hledger is more likely to guess the wrong default
|
|
account name, so you may need to set that explicitly.
|
|
.SS Amount signs
|
|
There is some special handling making it easier to parse and to reverse
|
|
amount signs.
|
|
(This only works for whole amounts, not for cost amounts such as COST in
|
|
\f[CR]amount1 AMT \[at] COST\f[R]):
|
|
.IP \[bu] 2
|
|
\f[B]If an amount value begins with a plus sign:\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
that will be removed: \f[CR]+AMT\f[R] becomes \f[CR]AMT\f[R]
|
|
.IP \[bu] 2
|
|
\f[B]If an amount value is parenthesised:\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
it will be de\-parenthesised and sign\-flipped: \f[CR](AMT)\f[R] becomes
|
|
\f[CR]\-AMT\f[R]
|
|
.IP \[bu] 2
|
|
\f[B]If an amount value has two minus signs (or two sets of parentheses,
|
|
or a minus sign and parentheses):\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
they cancel out and will be removed: \f[CR]\-\-AMT\f[R] or
|
|
\f[CR]\-(AMT)\f[R] becomes \f[CR]AMT\f[R]
|
|
.IP \[bu] 2
|
|
\f[B]If an amount value contains just a sign (or just a set of
|
|
parentheses):\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
that is removed, making it an empty value.
|
|
\f[CR]\[dq]+\[dq]\f[R] or \f[CR]\[dq]\-\[dq]\f[R] or
|
|
\f[CR]\[dq]()\[dq]\f[R] becomes \f[CR]\[dq]\[dq]\f[R].
|
|
.PP
|
|
It\[aq]s not possible (without preprocessing the CSV) to set an amount
|
|
to its absolute value, ie discard its sign.
|
|
.SS Setting currency/commodity
|
|
If the currency/commodity symbol is included in the CSV\[aq]s amount
|
|
field(s):
|
|
.IP
|
|
.EX
|
|
2023\-01\-01,foo,$123.00
|
|
.EE
|
|
.PP
|
|
you don\[aq]t have to do anything special for the commodity symbol, it
|
|
will be assigned as part of the amount.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
fields date,description,amount
|
|
.EE
|
|
.IP
|
|
.EX
|
|
2023\-01\-01 foo
|
|
expenses:unknown $123.00
|
|
income:unknown $\-123.00
|
|
.EE
|
|
.PP
|
|
If the currency is provided as a separate CSV field:
|
|
.IP
|
|
.EX
|
|
2023\-01\-01,foo,USD,123.00
|
|
.EE
|
|
.PP
|
|
You can assign that to the \f[CR]currency\f[R] pseudo\-field, which has
|
|
the special effect of prepending itself to every amount in the
|
|
transaction (on the left, with no separating space):
|
|
.IP
|
|
.EX
|
|
fields date,description,currency,amount
|
|
.EE
|
|
.IP
|
|
.EX
|
|
2023\-01\-01 foo
|
|
expenses:unknown USD123.00
|
|
income:unknown USD\-123.00
|
|
.EE
|
|
.PP
|
|
Or, you can use a field assignment to construct the amount yourself,
|
|
with more control.
|
|
Eg to put the symbol on the right, and separated by a space:
|
|
.IP
|
|
.EX
|
|
fields date,description,cur,amt
|
|
amount %amt %cur
|
|
.EE
|
|
.IP
|
|
.EX
|
|
2023\-01\-01 foo
|
|
expenses:unknown 123.00 USD
|
|
income:unknown \-123.00 USD
|
|
.EE
|
|
.PP
|
|
Note we used a temporary field name (\f[CR]cur\f[R]) that is not
|
|
\f[CR]currency\f[R] \- that would trigger the prepending effect, which
|
|
we don\[aq]t want here.
|
|
.SS Amount decimal places
|
|
When you are reading CSV data, eg with a command like
|
|
\f[CR]hledger \-f foo.csv print\f[R], hledger will infer each
|
|
commodity\[aq]s decimal precision (and other commodity display styles)
|
|
from the amounts \- much as when reading a journal file without
|
|
\f[CR]commodity\f[R] directives (see the link).
|
|
.PP
|
|
Note, the commodity styles are not inferred from the numbers in the
|
|
original CSV data; rather, they are inferred from the amounts generated
|
|
by the CSV rules.
|
|
.PP
|
|
When you are importing CSV data with the \f[CR]import\f[R] command, eg
|
|
\f[CR]hledger import foo.csv\f[R], there\[aq]s another step:
|
|
\f[CR]import\f[R] tries to make the new entries conform to the
|
|
journal\[aq]s existing styles.
|
|
So for each commodity \- let\[aq]s say it\[aq]s EUR \- \f[CR]import\f[R]
|
|
will choose:
|
|
.IP "1." 3
|
|
the style declared for EUR by a \f[CR]commodity\f[R] directive in the
|
|
journal
|
|
.IP "2." 3
|
|
otherwise, the style inferred from EUR amounts in the journal
|
|
.IP "3." 3
|
|
otherwise, the style inferred from EUR amounts generated by the CSV
|
|
rules.
|
|
.PP
|
|
TLDR: if \f[CR]import\f[R] is not generating the precisions or styles
|
|
you want, add a \f[CR]commodity\f[R] directive to specify them.
|
|
.SS Referencing other fields
|
|
In field assignments, you can interpolate only CSV fields, not hledger
|
|
fields.
|
|
In the example below, there\[aq]s both a CSV field and a hledger field
|
|
named amount1, but %amount1 always means the CSV field, not the hledger
|
|
field:
|
|
.IP
|
|
.EX
|
|
# Name the third CSV field \[dq]amount1\[dq]
|
|
fields date,description,amount1
|
|
|
|
# Set hledger\[aq]s amount1 to the CSV amount1 field followed by USD
|
|
amount1 %amount1 USD
|
|
|
|
# Set comment to the CSV amount1 (not the amount1 assigned above)
|
|
comment %amount1
|
|
.EE
|
|
.PP
|
|
Here, since there\[aq]s no CSV amount1 field, %amount1 will produce a
|
|
literal \[dq]amount1\[dq]:
|
|
.IP
|
|
.EX
|
|
fields date,description,csvamount
|
|
amount1 %csvamount USD
|
|
# Can\[aq]t interpolate amount1 here
|
|
comment %amount1
|
|
.EE
|
|
.PP
|
|
When there are multiple field assignments to the same hledger field,
|
|
only the last one takes effect.
|
|
Here, comment\[aq]s value will be be B, or C if \[dq]something\[dq] is
|
|
matched, but never A:
|
|
.IP
|
|
.EX
|
|
comment A
|
|
comment B
|
|
if something
|
|
comment C
|
|
.EE
|
|
.SS How CSV rules are evaluated
|
|
Here\[aq]s how to think of CSV rules being evaluated.
|
|
If you get a confusing error while reading a CSV file, it may help to
|
|
try to understand which of these steps is failing:
|
|
.IP "1." 3
|
|
Any included rules files are inlined, from top to bottom, depth first
|
|
(scanning each included file for further includes, recursively, before
|
|
proceeding).
|
|
.IP "2." 3
|
|
Top level rules (\f[CR]date\-format\f[R], \f[CR]fields\f[R],
|
|
\f[CR]newest\-first\f[R], \f[CR]skip\f[R] etc) are read, top to bottom.
|
|
\[dq]Top level rules\[dq] means non\-conditional rules.
|
|
If a rule occurs more than once, the last one wins; except for
|
|
\f[CR]skip\f[R]/\f[CR]end\f[R] rules, where the first one wins.
|
|
.IP "3." 3
|
|
The CSV file is read as text.
|
|
Any non\-ascii characters will be decoded using the text encoding
|
|
specified by the \f[CR]encoding\f[R] rule, otherwise the system
|
|
locale\[aq]s text encoding.
|
|
.IP "4." 3
|
|
Any top\-level skip or end rule is applied.
|
|
\f[CR]skip [N]\f[R] immediately skips the current or next N CSV records;
|
|
\f[CR]end\f[R] immediately skips all remaining CSV records (not normally
|
|
used at top level).
|
|
.IP "5." 3
|
|
Now any remaining CSV records are processed.
|
|
For each CSV record, in file order:
|
|
.RS 4
|
|
.IP \[bu] 2
|
|
Is there a conditional skip/end rule that applies for this record ?
|
|
Search the \f[CR]if\f[R] blocks, from top to bottom, for a succeeding
|
|
one containing a \f[CR]skip\f[R] or \f[CR]end\f[R] rule.
|
|
If found, skip the specified number of CSV records, then continue at 5.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Otherwise...
|
|
.IP \[bu] 2
|
|
Do some basic validation on this CSV record (eg, check that it has at
|
|
least two fields).
|
|
.IP \[bu] 2
|
|
For each hledger field (\f[CR]date\f[R], \f[CR]description\f[R],
|
|
\f[CR]account1\f[R], etc.):
|
|
.RS 2
|
|
.IP "1." 3
|
|
Get the field\[aq]s assigned value, first searching top level
|
|
assignments, made directly or by the \f[CR]fields\f[R] rule, then
|
|
assignments made inside succeeding \f[CR]if\f[R] blocks.
|
|
If there are more than one, the last one wins.
|
|
.IP "2." 3
|
|
Compute the field\[aq]s actual value (as text), by interpolating any
|
|
%CSVFIELD references within the assigned value; or by choosing a default
|
|
value if there was no assignment.
|
|
.RE
|
|
.IP \[bu] 2
|
|
Generate a hledger transaction from the hledger field values, parsing
|
|
them if needed (eg from text to an amount).
|
|
.RE
|
|
.PP
|
|
This is all done by the CSV reader, one of several readers hledger can
|
|
use to read transactions from an input file.
|
|
When all input files have been read successfully, their transactions are
|
|
passed to whichever hledger command the user specified.
|
|
.SS Well factored rules
|
|
Some things than can help reduce duplication and complexity in rules
|
|
files:
|
|
.IP \[bu] 2
|
|
Extracting common rules usable with multiple CSV files into a
|
|
\f[CR]common.rules\f[R], and adding \f[CR]include common.rules\f[R] to
|
|
each CSV\[aq]s rules file.
|
|
.IP \[bu] 2
|
|
Splitting if blocks into smaller if blocks, extracting the frequently
|
|
used parts.
|
|
.SS CSV rules examples
|
|
.SS Bank of Ireland
|
|
Here\[aq]s a CSV with two amount fields (Debit and Credit), and a
|
|
balance field, which we can use to add balance assertions, which is not
|
|
necessary but provides extra error checking:
|
|
.IP
|
|
.EX
|
|
Date,Details,Debit,Credit,Balance
|
|
07/12/2012,LODGMENT 529898,,10.0,131.21
|
|
07/12/2012,PAYMENT,5,,126
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# bankofireland\-checking.csv.rules
|
|
|
|
# skip the header line
|
|
skip
|
|
|
|
# name the csv fields, and assign some of them as journal entry fields
|
|
fields date, description, amount\-out, amount\-in, balance
|
|
|
|
# We generate balance assertions by assigning to \[dq]balance\[dq]
|
|
# above, but you may sometimes need to remove these because:
|
|
#
|
|
# \- the CSV balance differs from the true balance,
|
|
# by up to 0.0000000000005 in my experience
|
|
#
|
|
# \- it is sometimes calculated based on non\-chronological ordering,
|
|
# eg when multiple transactions clear on the same day
|
|
|
|
# date is in UK/Ireland format
|
|
date\-format %d/%m/%Y
|
|
|
|
# set the currency
|
|
currency EUR
|
|
|
|
# set the base account for all txns
|
|
account1 assets:bank:boi:checking
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f bankofireland\-checking.csv print
|
|
2012\-12\-07 LODGMENT 529898
|
|
assets:bank:boi:checking EUR10.0 = EUR131.2
|
|
income:unknown EUR\-10.0
|
|
|
|
2012\-12\-07 PAYMENT
|
|
assets:bank:boi:checking EUR\-5.0 = EUR126.0
|
|
expenses:unknown EUR5.0
|
|
.EE
|
|
.PP
|
|
The balance assertions don\[aq]t raise an error above, because we\[aq]re
|
|
reading directly from CSV, but they will be checked if these entries are
|
|
imported into a journal file.
|
|
.SS Coinbase
|
|
A simple example with some CSV from Coinbase.
|
|
The spot price is recorded using cost notation.
|
|
The legacy \f[CR]amount\f[R] field name conveniently sets amount 2
|
|
(posting 2\[aq]s amount) to the total cost.
|
|
.IP
|
|
.EX
|
|
# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes
|
|
# 2021\-12\-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]Received 100.00 USDC from an external account\[dq]
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# coinbase.csv.rules
|
|
skip 1
|
|
fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes
|
|
date %Timestamp
|
|
date\-format %Y\-%m\-%dT%T%Z
|
|
description %Notes
|
|
account1 assets:coinbase:cc
|
|
amount %Quantity_Transacted %Asset \[at] %Spot_Price_at_Transaction %Spot_Price_Currency
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger print \-f coinbase.csv
|
|
2021\-12\-30 Received 100.00 USDC from an external account
|
|
assets:coinbase:cc 100 USDC \[at] 0.740000 GBP
|
|
income:unknown \-74.000000 GBP
|
|
.EE
|
|
.SS Amazon
|
|
Here we convert amazon.com order history, and use an if block to
|
|
generate a third posting if there\[aq]s a fee.
|
|
(In practice you\[aq]d probably get this data from your bank instead,
|
|
but it\[aq]s an example.)
|
|
.IP
|
|
.EX
|
|
\[dq]Date\[dq],\[dq]Type\[dq],\[dq]To/From\[dq],\[dq]Name\[dq],\[dq]Status\[dq],\[dq]Amount\[dq],\[dq]Fees\[dq],\[dq]Transaction ID\[dq]
|
|
\[dq]Jul 29, 2012\[dq],\[dq]Payment\[dq],\[dq]To\[dq],\[dq]Foo.\[dq],\[dq]Completed\[dq],\[dq]$20.00\[dq],\[dq]$0.00\[dq],\[dq]16000000000000DGLNJPI1P9B8DKPVHL\[dq]
|
|
\[dq]Jul 30, 2012\[dq],\[dq]Payment\[dq],\[dq]To\[dq],\[dq]Adapteva, Inc.\[dq],\[dq]Completed\[dq],\[dq]$25.00\[dq],\[dq]$1.00\[dq],\[dq]17LA58JSKRD4HDGLNJPI1P9B8DKPVHL\[dq]
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# amazon\-orders.csv.rules
|
|
|
|
# skip one header line
|
|
skip 1
|
|
|
|
# name the csv fields, and assign the transaction\[aq]s date, amount and code.
|
|
# Avoided the \[dq]status\[dq] and \[dq]amount\[dq] hledger field names to prevent confusion.
|
|
fields date, _, toorfrom, name, amzstatus, amzamount, fees, code
|
|
|
|
# how to parse the date
|
|
date\-format %b %\-d, %Y
|
|
|
|
# combine two fields to make the description
|
|
description %toorfrom %name
|
|
|
|
# save the status as a tag
|
|
comment status:%amzstatus
|
|
|
|
# set the base account for all transactions
|
|
account1 assets:amazon
|
|
# leave amount1 blank so it can balance the other(s).
|
|
# I\[aq]m assuming amzamount excludes the fees, don\[aq]t remember
|
|
|
|
# set a generic account2
|
|
account2 expenses:misc
|
|
amount2 %amzamount
|
|
# and maybe refine it further:
|
|
#include categorisation.rules
|
|
|
|
# add a third posting for fees, but only if they are non\-zero.
|
|
if %fees [1\-9]
|
|
account3 expenses:fees
|
|
amount3 %fees
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f amazon\-orders.csv print
|
|
2012\-07\-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed
|
|
assets:amazon
|
|
expenses:misc $20.00
|
|
|
|
2012\-07\-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed
|
|
assets:amazon
|
|
expenses:misc $25.00
|
|
expenses:fees $1.00
|
|
.EE
|
|
.SS Paypal
|
|
Here\[aq]s a real\-world rules file for (customised) Paypal CSV, with
|
|
some Paypal\-specific rules, and a second rules file included:
|
|
.IP
|
|
.EX
|
|
\[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Reference Txn ID\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Note\[dq]
|
|
\[dq]10/01/2019\[dq],\[dq]03:46:20\[dq],\[dq]PDT\[dq],\[dq]Calm Radio\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]\-6.99\[dq],\[dq]0.00\[dq],\[dq]\-6.99\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]memberships\[at]calmradio.com\[dq],\[dq]60P57143A8206782E\[dq],\[dq]MONTHLY \- $1 for the first 2 Months: Me \- Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month\[dq],\[dq]\[dq],\[dq]I\-R8YLY094FJYR\[dq],\[dq]\[dq],\[dq]\-6.99\[dq],\[dq]\[dq]
|
|
\[dq]10/01/2019\[dq],\[dq]03:46:20\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]6.99\[dq],\[dq]0.00\[dq],\[dq]6.99\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]0TU1544T080463733\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]60P57143A8206782E\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]
|
|
\[dq]10/01/2019\[dq],\[dq]08:57:01\[dq],\[dq]PDT\[dq],\[dq]Patreon\[dq],\[dq]PreApproved Payment Bill User Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]\-7.00\[dq],\[dq]0.00\[dq],\[dq]\-7.00\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]support\[at]patreon.com\[dq],\[dq]2722394R5F586712G\[dq],\[dq]Patreon* Membership\[dq],\[dq]\[dq],\[dq]B\-0PG93074E7M86381M\[dq],\[dq]\[dq],\[dq]\-7.00\[dq],\[dq]\[dq]
|
|
\[dq]10/01/2019\[dq],\[dq]08:57:01\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]7.00\[dq],\[dq]0.00\[dq],\[dq]7.00\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]71854087RG994194F\[dq],\[dq]Patreon* Membership\[dq],\[dq]\[dq],\[dq]2722394R5F586712G\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]
|
|
\[dq]10/19/2019\[dq],\[dq]03:02:12\[dq],\[dq]PDT\[dq],\[dq]Wikimedia Foundation, Inc.\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]\-2.00\[dq],\[dq]0.00\[dq],\[dq]\-2.00\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]tle\[at]wikimedia.org\[dq],\[dq]K9U43044RY432050M\[dq],\[dq]Monthly donation to the Wikimedia Foundation\[dq],\[dq]\[dq],\[dq]I\-R5C3YUS3285L\[dq],\[dq]\[dq],\[dq]\-2.00\[dq],\[dq]\[dq]
|
|
\[dq]10/19/2019\[dq],\[dq]03:02:12\[dq],\[dq]PDT\[dq],\[dq]\[dq],\[dq]Bank Deposit to PP Account \[dq],\[dq]Pending\[dq],\[dq]USD\[dq],\[dq]2.00\[dq],\[dq]0.00\[dq],\[dq]2.00\[dq],\[dq]\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]3XJ107139A851061F\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]K9U43044RY432050M\[dq],\[dq]\[dq],\[dq]0.00\[dq],\[dq]\[dq]
|
|
\[dq]10/22/2019\[dq],\[dq]05:07:06\[dq],\[dq]PDT\[dq],\[dq]Noble Benefactor\[dq],\[dq]Subscription Payment\[dq],\[dq]Completed\[dq],\[dq]USD\[dq],\[dq]10.00\[dq],\[dq]\-0.59\[dq],\[dq]9.41\[dq],\[dq]noble\[at]bene.fac.tor\[dq],\[dq]simon\[at]joyful.com\[dq],\[dq]6L8L1662YP1334033\[dq],\[dq]Joyful Systems\[dq],\[dq]\[dq],\[dq]I\-KC9VBGY2GWDB\[dq],\[dq]\[dq],\[dq]9.41\[dq],\[dq]\[dq]
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# paypal\-custom.csv.rules
|
|
|
|
# Tips:
|
|
# Export from Activity \-> Statements \-> Custom \-> Activity download
|
|
# Suggested transaction type: \[dq]Balance affecting\[dq]
|
|
# Paypal\[aq]s default fields in 2018 were:
|
|
# \[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Shipping Address\[dq],\[dq]Address Status\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Shipping and Handling Amount\[dq],\[dq]Insurance Amount\[dq],\[dq]Sales Tax\[dq],\[dq]Option 1 Name\[dq],\[dq]Option 1 Value\[dq],\[dq]Option 2 Name\[dq],\[dq]Option 2 Value\[dq],\[dq]Reference Txn ID\[dq],\[dq]Invoice Number\[dq],\[dq]Custom Number\[dq],\[dq]Quantity\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Address Line 1\[dq],\[dq]Address Line 2/District/Neighborhood\[dq],\[dq]Town/City\[dq],\[dq]State/Province/Region/County/Territory/Prefecture/Republic\[dq],\[dq]Zip/Postal Code\[dq],\[dq]Country\[dq],\[dq]Contact Phone Number\[dq],\[dq]Subject\[dq],\[dq]Note\[dq],\[dq]Country Code\[dq],\[dq]Balance Impact\[dq]
|
|
# This rules file assumes the following more detailed fields, configured in \[dq]Customize report fields\[dq]:
|
|
# \[dq]Date\[dq],\[dq]Time\[dq],\[dq]TimeZone\[dq],\[dq]Name\[dq],\[dq]Type\[dq],\[dq]Status\[dq],\[dq]Currency\[dq],\[dq]Gross\[dq],\[dq]Fee\[dq],\[dq]Net\[dq],\[dq]From Email Address\[dq],\[dq]To Email Address\[dq],\[dq]Transaction ID\[dq],\[dq]Item Title\[dq],\[dq]Item ID\[dq],\[dq]Reference Txn ID\[dq],\[dq]Receipt ID\[dq],\[dq]Balance\[dq],\[dq]Note\[dq]
|
|
|
|
fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note
|
|
|
|
skip 1
|
|
|
|
date\-format %\-m/%\-d/%Y
|
|
|
|
# ignore some paypal events
|
|
if
|
|
In Progress
|
|
Temporary Hold
|
|
Update to
|
|
skip
|
|
|
|
# add more fields to the description
|
|
description %description_ %itemtitle
|
|
|
|
# save some other fields as tags
|
|
comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
|
|
|
|
# convert to short currency symbols
|
|
if %currency USD
|
|
currency $
|
|
if %currency EUR
|
|
currency E
|
|
if %currency GBP
|
|
currency P
|
|
|
|
# generate postings
|
|
|
|
# the first posting will be the money leaving/entering my paypal account
|
|
# (negative means leaving my account, in all amount fields)
|
|
account1 assets:online:paypal
|
|
amount1 %netamount
|
|
|
|
# the second posting will be money sent to/received from other party
|
|
# (account2 is set below)
|
|
amount2 \-%grossamount
|
|
|
|
# if there\[aq]s a fee, add a third posting for the money taken by paypal.
|
|
if %feeamount [1\-9]
|
|
account3 expenses:banking:paypal
|
|
amount3 \-%feeamount
|
|
comment3 business:
|
|
|
|
# choose an account for the second posting
|
|
|
|
# override the default account names:
|
|
# if the amount is positive, it\[aq]s income (a debit)
|
|
if %grossamount \[ha][\[ha]\-]
|
|
account2 income:unknown
|
|
# if negative, it\[aq]s an expense (a credit)
|
|
if %grossamount \[ha]\-
|
|
account2 expenses:unknown
|
|
|
|
# apply common rules for setting account2 & other tweaks
|
|
include common.rules
|
|
|
|
# apply some overrides specific to this csv
|
|
|
|
# Transfers from/to bank. These are usually marked Pending,
|
|
# which can be disregarded in this case.
|
|
if
|
|
Bank Account
|
|
Bank Deposit to PP Account
|
|
description %type for %referencetxnid %itemtitle
|
|
account2 assets:bank:wf:pchecking
|
|
account1 assets:online:paypal
|
|
|
|
# Currency conversions
|
|
if Currency Conversion
|
|
account2 equity:currency conversion
|
|
.EE
|
|
.IP
|
|
.EX
|
|
# common.rules
|
|
|
|
if
|
|
darcs
|
|
noble benefactor
|
|
account2 revenues:foss donations:darcshub
|
|
comment2 business:
|
|
|
|
if
|
|
Calm Radio
|
|
account2 expenses:online:apps
|
|
|
|
if
|
|
electronic frontier foundation
|
|
Patreon
|
|
wikimedia
|
|
Advent of Code
|
|
account2 expenses:dues
|
|
|
|
if Google
|
|
account2 expenses:online:apps
|
|
description google | music
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f paypal\-custom.csv print
|
|
2019\-10\-01 (60P57143A8206782E) Calm Radio MONTHLY \- $1 for the first 2 Months: Me \- Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon\[at]joyful.com, toemail:memberships\[at]calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed
|
|
assets:online:paypal $\-6.99 = $\-6.99
|
|
expenses:online:apps $6.99
|
|
|
|
2019\-10\-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending
|
|
assets:online:paypal $6.99 = $0.00
|
|
assets:bank:wf:pchecking $\-6.99
|
|
|
|
2019\-10\-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon\[at]joyful.com, toemail:support\[at]patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed
|
|
assets:online:paypal $\-7.00 = $\-7.00
|
|
expenses:dues $7.00
|
|
|
|
2019\-10\-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending
|
|
assets:online:paypal $7.00 = $0.00
|
|
assets:bank:wf:pchecking $\-7.00
|
|
|
|
2019\-10\-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon\[at]joyful.com, toemail:tle\[at]wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed
|
|
assets:online:paypal $\-2.00 = $\-2.00
|
|
expenses:dues $2.00
|
|
expenses:banking:paypal ; business:
|
|
|
|
2019\-10\-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending
|
|
assets:online:paypal $2.00 = $0.00
|
|
assets:bank:wf:pchecking $\-2.00
|
|
|
|
2019\-10\-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble\[at]bene.fac.tor, toemail:simon\[at]joyful.com, time:05:07:06, type:Subscription Payment, status:Completed
|
|
assets:online:paypal $9.41 = $9.41
|
|
revenues:foss donations:darcshub $\-10.00 ; business:
|
|
expenses:banking:paypal $0.59 ; business:
|
|
.EE
|
|
.PP
|
|
.SH Timeclock
|
|
hledger can read time logs in the timeclock time logging format of
|
|
timeclock.el.
|
|
As with Ledger, hledger\[aq]s timeclock format is a subset/variant of
|
|
timeclock.el\[aq]s.
|
|
.PP
|
|
hledger\[aq]s timeclock format was updated in hledger 1.43 and 1.50.
|
|
If your old time logs are rejected, you should adapt them to modern
|
|
hledger; for now, you can restore the pre\-1.43 behaviour with the
|
|
\f[CR]\-\-old\-timeclock\f[R] flag.
|
|
.PP
|
|
Here the timeclock format in hledger 1.50+:
|
|
.IP
|
|
.EX
|
|
# Comment lines like these, and blank lines, are ignored:
|
|
# comment line
|
|
; comment line
|
|
* comment line
|
|
|
|
# Lines beginning with b, h, or capital O are also ignored, for compatibility:
|
|
b SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ TEXT]
|
|
h SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ TEXT]
|
|
O SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ TEXT]
|
|
|
|
# Lines beginning with i or o are are clock\-in / clock\-out entries:
|
|
i SIMPLEDATE HH:MM[:SS][+\-ZZZZ] ACCOUNT[ DESCRIPTION][;COMMENT]]
|
|
o SIMPLEDATE HH:MM[:SS][+\-ZZZZ][ ACCOUNT][;COMMENT]
|
|
.EE
|
|
.PP
|
|
The date is a hledger simple date (YYYY\-MM\-DD or similar).
|
|
The time parts must use two digits.
|
|
The seconds are optional.
|
|
A + or \- four\-digit time zone is accepted for compatibility, but
|
|
currently ignored; times are always interpreted as a local time.
|
|
.PP
|
|
In clock\-in entries (\f[CR]i\f[R]), the account name is required.
|
|
A transaction description, separated from the account name by 2+ spaces,
|
|
is optional.
|
|
A transaction comment, beginning with \f[CR];\f[R], is also optional.
|
|
(Indented following comment lines are also allowed, as in journal
|
|
format.)
|
|
.PP
|
|
In clock\-out entries (\f[CR]o\f[R]) have no description, but can have a
|
|
comment if you wish.
|
|
A clock\-in and clock\-out pair form a \[dq]transaction\[dq] posting
|
|
some number of hours to an account \- also known as a session.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
i 2015/03/30 09:00:00 session1
|
|
o 2015/03/30 10:00:00
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f a.timeclock print
|
|
2015\-03\-30 * 09:00\-10:00
|
|
(session1) 1.00h
|
|
.EE
|
|
.PP
|
|
Clock\-ins and clock\-outs are matched by their account/session name.
|
|
If a clock\-out does not specify a name, the most recent unclosed
|
|
clock\-in is closed.
|
|
You can have multiple sessions active simultaneously.
|
|
Entries are processed in the order they are parsed.
|
|
Sessions spanning more than one day are automatically split at day
|
|
boundaries.
|
|
.PP
|
|
Eg, the following time log:
|
|
.IP
|
|
.EX
|
|
i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags:
|
|
o 2015/03/30 09:20:00
|
|
i 2015/03/31 22:21:45 another:account
|
|
o 2015/04/01 02:00:34
|
|
i 2015/04/02 12:00:00 another:account ; this demonstrates multple sessions being clocked in
|
|
i 2015/04/02 13:00:00 some account
|
|
o 2015/04/02 14:00:00
|
|
o 2015/04/02 15:00:00 another:account
|
|
.EE
|
|
.PP
|
|
generates these transactions:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f t.timeclock print
|
|
2015\-03\-30 * optional description after 2 spaces ; optional comment, tags:
|
|
(some account) 0.33h
|
|
|
|
2015\-03\-31 * 22:21\-23:59
|
|
(another:account) 1.64h
|
|
|
|
2015\-04\-01 * 00:00\-02:00
|
|
(another:account) 2.01h
|
|
|
|
2015\-04\-02 * 12:00\-15:00 ; this demonstrates multiple sessions being clocked in
|
|
(another:account) 3.00h
|
|
|
|
2015\-04\-02 * 13:00\-14:00
|
|
(some account) 1.00h
|
|
.EE
|
|
.PP
|
|
Here is a sample.timeclock to download and some queries to try:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f sample.timeclock balance # current time balances
|
|
$ hledger \-f sample.timeclock register \-p 2009/3 # sessions in march 2009
|
|
$ hledger \-f sample.timeclock register \-p weekly \-\-depth 1 \-\-empty # time summary by week
|
|
.EE
|
|
.PP
|
|
To generate time logs, ie to clock in and clock out, you could:
|
|
.IP \[bu] 2
|
|
use these shell aliases at the command line:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
alias ti=\[aq]echo i \[ga]date \[dq]+%Y\-%m\-%d %H:%M:%S\[dq]\[ga] $* >>$TIMELOG\[aq]
|
|
alias to=\[aq]echo o \[ga]date \[dq]+%Y\-%m\-%d %H:%M:%S\[dq]\[ga] >>$TIMELOG\[aq]
|
|
.EE
|
|
.RE
|
|
.IP \[bu] 2
|
|
or Emacs\[aq]s built\-in timeclock.el, or the extended timeclock\-x.el,
|
|
and perhaps the extras in ledgerutils.el
|
|
.IP \[bu] 2
|
|
or use the old \f[CR]ti\f[R] and \f[CR]to\f[R] scripts in the ledger 2.x
|
|
repository.
|
|
These rely on a \[dq]timeclock\[dq] executable which I think is just the
|
|
ledger 2 executable renamed.
|
|
.PP
|
|
.SH Timedot
|
|
\f[CR]timedot\f[R] format is hledger\[aq]s human\-friendly time logging
|
|
format.
|
|
Compared to \f[CR]timeclock\f[R] format, it is more convenient for
|
|
quick, approximate, and retroactive time logging, and more
|
|
human\-readable (you can see at a glance where time was spent).
|
|
A quick example:
|
|
.IP
|
|
.EX
|
|
2023\-05\-01
|
|
hom:errands .... .... ; two hours; the space is ignored
|
|
fos:hledger:timedot .. ; half an hour
|
|
per:admin:finance ; no time spent yet
|
|
.EE
|
|
.PP
|
|
hledger reads this as a transaction on this day with three (unbalanced)
|
|
postings, where each dot represents \[dq]0.25\[dq].
|
|
No commodity symbol is assumed, but we typically interpret it as hours.
|
|
.IP
|
|
.EX
|
|
$ hledger \-f a.timedot print # .timedot file extension (or timedot: prefix) is required
|
|
2023\-05\-01 *
|
|
(hom:errands) 2.00 ; two hours
|
|
(fos:hledger:timedot) 0.50 ; half an hour
|
|
(per:admin:finance) 0
|
|
.EE
|
|
.PP
|
|
A timedot file contains a series of transactions (usually one per day).
|
|
Each begins with a \f[B]simple date\f[R] (Y\-M\-D, Y/M/D, or Y.M.D),
|
|
optionally be followed on the same line by a transaction description,
|
|
and/or a transaction comment following a semicolon.
|
|
.PP
|
|
After the date line are zero or more time postings, consisting of:
|
|
.IP \[bu] 2
|
|
\f[B]An account name\f[R] \- any hledger\-style account name, optionally
|
|
indented.
|
|
.IP \[bu] 2
|
|
\f[B]Two or more spaces\f[R] \- required if there is an amount (as in
|
|
journal format).
|
|
.IP \[bu] 2
|
|
\f[B]A timedot amount\f[R], which can be
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
empty (representing zero)
|
|
.IP \[bu] 2
|
|
a number, optionally followed by a unit \f[CR]s\f[R], \f[CR]m\f[R],
|
|
\f[CR]h\f[R], \f[CR]d\f[R], \f[CR]w\f[R], \f[CR]mo\f[R], or
|
|
\f[CR]y\f[R], representing a precise number of seconds, minutes, hours,
|
|
days weeks, months or years (hours is assumed by default), which will be
|
|
converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d = 1w,
|
|
30d = 1mo, 365d = 1y.
|
|
.IP \[bu] 2
|
|
one or more dots (period characters), each representing 0.25.
|
|
These are the dots in \[dq]timedot\[dq].
|
|
Spaces are ignored and can be used for grouping/alignment.
|
|
.IP \[bu] 2
|
|
\f[I]Added in 1.32\f[R] one or more letters.
|
|
These are like dots but they also generate a tag \f[CR]t:\f[R] (short
|
|
for \[dq]type\[dq]) with the letter as its value, and a separate posting
|
|
for each of the values.
|
|
This provides a second dimension of categorisation, viewable in reports
|
|
with \f[CR]\-\-pivot t\f[R].
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[B]An optional comment\f[R] following a semicolon (a hledger\-style
|
|
posting comment).
|
|
.PP
|
|
There is some flexibility to help with keeping time log data and notes
|
|
in the same file:
|
|
.IP \[bu] 2
|
|
Blank lines and lines beginning with \f[CR]#\f[R] or \f[CR];\f[R] are
|
|
ignored.
|
|
.IP \[bu] 2
|
|
After the first date line, lines which do not contain a double space are
|
|
parsed as postings with zero amount.
|
|
(hledger\[aq]s register reports will show these if you add \-E).
|
|
.IP \[bu] 2
|
|
Before the first date line, lines beginning with \f[CR]*\f[R] (eg org
|
|
headings) are ignored.
|
|
And from the first date line onward, Emacs org mode heading prefixes at
|
|
the start of lines (one or more \f[CR]*\f[R]\[aq]s followed by a space)
|
|
will be ignored.
|
|
This means the time log can also be a org outline.
|
|
.PP
|
|
Timedot files don\[aq]t support directives like journal files.
|
|
So a common pattern is to have a main journal file (eg
|
|
\f[CR]time.journal\f[R]) that contains any needed directives, and then
|
|
includes the timedot file (\f[CR]include time.timedot\f[R]).
|
|
.SS Timedot examples
|
|
Numbers:
|
|
.IP
|
|
.EX
|
|
2016/2/3
|
|
inc:client1 4
|
|
fos:hledger 3h
|
|
biz:research 60m
|
|
.EE
|
|
.PP
|
|
Dots:
|
|
.IP
|
|
.EX
|
|
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
|
|
2016/2/1
|
|
inc:client1 .... .... .... .... .... ....
|
|
fos:haskell .... ..
|
|
biz:research .
|
|
|
|
2016/2/2
|
|
inc:client1 .... ....
|
|
biz:research .
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f a.timedot print date:2016/2/2
|
|
2016\-02\-02 *
|
|
(inc:client1) 2.00
|
|
|
|
2016\-02\-02 *
|
|
(biz:research) 0.25
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f a.timedot bal \-\-daily \-\-tree
|
|
Balance changes in 2016\-02\-01\-2016\-02\-03:
|
|
|
|
|| 2016\-02\-01d 2016\-02\-02d 2016\-02\-03d
|
|
============++========================================
|
|
biz || 0.25 0.25 1.00
|
|
research || 0.25 0.25 1.00
|
|
fos || 1.50 0 3.00
|
|
haskell || 1.50 0 0
|
|
hledger || 0 0 3.00
|
|
inc || 6.00 2.00 4.00
|
|
client1 || 6.00 2.00 4.00
|
|
\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| 7.75 2.25 8.00
|
|
.EE
|
|
.PP
|
|
Letters:
|
|
.IP
|
|
.EX
|
|
# Activity types:
|
|
# c cleanup/catchup/repair
|
|
# e enhancement
|
|
# s support
|
|
# l learning/research
|
|
|
|
2023\-11\-01
|
|
work:adm ccecces
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f a.timedot print
|
|
2023\-11\-01
|
|
(work:adm) 1 ; t:c
|
|
(work:adm) 0.5 ; t:e
|
|
(work:adm) 0.25 ; t:s
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f a.timedot bal
|
|
1.75 work:adm
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
1.75
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f a.timedot bal \-\-pivot t
|
|
1.00 c
|
|
0.50 e
|
|
0.25 s
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
1.75
|
|
.EE
|
|
.PP
|
|
Org:
|
|
.IP
|
|
.EX
|
|
* 2023 Work Diary
|
|
** Q1
|
|
*** 2023\-02\-29
|
|
**** DONE
|
|
0700 yoga
|
|
**** UNPLANNED
|
|
**** BEGUN
|
|
hom:chores
|
|
cleaning ...
|
|
water plants
|
|
outdoor \- one full watering can
|
|
indoor \- light watering
|
|
**** TODO
|
|
adm:planning: trip
|
|
*** LATER
|
|
.EE
|
|
.PP
|
|
Using \f[CR].\f[R] as account name separator:
|
|
.IP
|
|
.EX
|
|
2016/2/4
|
|
fos.hledger.timedot 4h
|
|
fos.ledger ..
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger \-f a.timedot \-\-alias \[aq]/\[rs]./=:\[aq] bal \-t
|
|
4.50 fos
|
|
4.00 hledger:timedot
|
|
0.50 ledger
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
4.50
|
|
.EE
|
|
.SH PART 3: REPORTING CONCEPTS
|
|
.SH Time periods
|
|
.SS Report start & end date
|
|
Most hledger reports will by default show the full time period
|
|
represented by the journal.
|
|
The report start date will be the earliest transaction or posting date,
|
|
and the report end date will be the latest transaction, posting, or
|
|
market price date.
|
|
.PP
|
|
Often you will want to see a shorter period, such as the current month.
|
|
You can specify a start and/or end date with the
|
|
\f[CR]\-b/\-\-begin\f[R], \f[CR]\-e/\-\-end\f[R], or
|
|
\f[CR]\-p/\-\-period\f[R] options, or a \f[CR]date:\f[R] query argument,
|
|
described below.
|
|
All of these accept the smart date syntax, also described below.
|
|
.PP
|
|
End dates are exclusive; specify the day after the last day you want to
|
|
see in the report.
|
|
.PP
|
|
When dates are specified by multiple options, the last (right\-most)
|
|
option wins.
|
|
And when \f[CR]date:\f[R] queries and date options are combined, the
|
|
report period will be their intersection.
|
|
.PP
|
|
Examples:
|
|
.TP
|
|
\f[CR]\-b 2016/3/17\f[R]
|
|
beginning on St.
|
|
Patrick\[cq]s day 2016
|
|
.TP
|
|
\f[CR]\-e 12/1\f[R]
|
|
ending at the start of December 1st in the current year
|
|
.TP
|
|
\f[CR]\-p \[aq]this month\[aq]\f[R]
|
|
during the current month
|
|
.TP
|
|
\f[CR]\-p thismonth\f[R]
|
|
same as above, spaces are optional
|
|
.TP
|
|
\f[CR]\-b 2023\f[R]
|
|
beginning on the first day of 2023
|
|
.TP
|
|
\f[CR]date:2023..\f[R] or \f[CR]date:2023\-\f[R]
|
|
same as above
|
|
.PP
|
|
\f[CR]\-b 2024 \-e 2025 \-p \[aq]2000 to 2030\[aq] date:2020\-01 date:2020\f[R]
|
|
:
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
during January 2020 (the smallest common period, with the \-p overriding
|
|
\-b and \-e)
|
|
.SS Smart dates
|
|
In hledger\[aq]s user interfaces (though not in the journal file), you
|
|
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 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]2024Q1\f[R] :
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
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
|
|
\f[CR]10/1\f[R] or \f[CR]oct\f[R] or \f[CR]october\f[R]
|
|
October 1st in current year
|
|
.TP
|
|
\f[CR]21\f[R]
|
|
21st day in current month
|
|
.TP
|
|
\f[CR]yesterday, today, tomorrow\f[R]
|
|
\-1, 0, 1 days from today
|
|
.TP
|
|
\f[CR]last/this/next day/week/month/quarter/year\f[R]
|
|
\-1, 0, 1 periods from the current period
|
|
.TP
|
|
\f[CR]in n days/weeks/months/quarters/years\f[R]
|
|
n periods from the current period
|
|
.TP
|
|
\f[CR]n days/weeks/months/quarters/years ahead\f[R]
|
|
n periods from the current period
|
|
.TP
|
|
\f[CR]n days/weeks/months/quarters/years ago\f[R]
|
|
\-n periods from the current period
|
|
.TP
|
|
\f[CR]20181201\f[R]
|
|
8 digit YYYYMMDD with valid year month and day
|
|
.TP
|
|
\f[CR]201812\f[R]
|
|
6 digit YYYYMM with valid year and month
|
|
.PP
|
|
Dates with no separators are allowed but might give surprising results
|
|
if mistyped:
|
|
.IP \[bu] 2
|
|
\f[CR]20181301\f[R] (YYYYMMDD with an invalid month) is parsed as an
|
|
eight\-digit year
|
|
.IP \[bu] 2
|
|
\f[CR]20181232\f[R] (YYYYMMDD with an invalid day) gives a parse error
|
|
.IP \[bu] 2
|
|
\f[CR]201801012\f[R] (a valid YYYYMMDD followed by additional digits)
|
|
gives a parse error
|
|
.PP
|
|
The meaning of relative dates depends on today\[aq]s date.
|
|
If you need to test or reproduce old reports, you can use the
|
|
\f[CR]\-\-today\f[R] option to override that.
|
|
(Except for periodic transaction rules, which are not affected by
|
|
\f[CR]\-\-today\f[R].)
|
|
.SS Report intervals
|
|
A report interval can be specified so that reports like register,
|
|
balance or activity become multi\-period, showing each subperiod as a
|
|
separate row or column.
|
|
.PP
|
|
The following standard intervals can be enabled with command\-line
|
|
flags:
|
|
.IP \[bu] 2
|
|
\f[CR]\-D/\-\-daily\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]\-W/\-\-weekly\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]\-M/\-\-monthly\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]\-Q/\-\-quarterly\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]\-Y/\-\-yearly\f[R]
|
|
.PP
|
|
More complex intervals can be specified using \f[CR]\-p/\-\-period\f[R],
|
|
described below.
|
|
.SS Date adjustments
|
|
.SS Start date adjustment
|
|
If you let hledger infer a report\[aq]s start date, it will adjust the
|
|
date to the previous natural boundary of the report interval, for
|
|
convenient periodic reports.
|
|
(If you don\[aq]t want that, specify a start date.)
|
|
.PP
|
|
For example, if the journal\[aq]s first transaction is on january 10th,
|
|
.IP \[bu] 2
|
|
\f[CR]hledger register\f[R] (no report interval) will start the report
|
|
on january 10th.
|
|
.IP \[bu] 2
|
|
\f[CR]hledger register \-\-monthly\f[R] will start the report on the
|
|
previous month boundary, january 1st.
|
|
.IP \[bu] 2
|
|
\f[CR]hledger register \-\-monthly \-\-begin 1/5\f[R] will start the
|
|
report on january 5th [1].
|
|
.PP
|
|
Also if you are generating transactions or budget goals with periodic
|
|
transaction rules, their start date may be adjusted in a similar way (in
|
|
certain situations).
|
|
.SS End date adjustment
|
|
A report\[aq]s end date is always adjusted to include a whole number of
|
|
intervals, so that the last subperiod has the same length as the others.
|
|
.PP
|
|
For example, if the journal\[aq]s last transaction is on february 20th,
|
|
.IP \[bu] 2
|
|
\f[CR]hledger register\f[R] will end the report on february 20th.
|
|
.IP \[bu] 2
|
|
\f[CR]hledger register \-\-monthly\f[R] will end the report at the end
|
|
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 (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].
|
|
.PP
|
|
[1] Since hledger 1.29.
|
|
.SS Period headings
|
|
With non\-standard subperiods, hledger will show
|
|
\[dq]STARTDATE..ENDDATE\[dq] headings.
|
|
With standard subperiods (ie, starting on a natural interval boundary),
|
|
you\[aq]ll see more compact headings, which are usually preferable.
|
|
(Though month names will be in english, currently.)
|
|
.PP
|
|
So if you are specifying a start date and you want compact headings:
|
|
choose a start of year for yearly reports, a start of quarter for
|
|
quarterly reports, a start of month for monthly reports, etc.
|
|
(Remember, you can write eg \f[CR]\-b 2024\f[R] or \f[CR]1/1\f[R] as a
|
|
shortcut for a start of year, or \f[CR]2024\-04\f[R] or
|
|
\f[CR]202404\f[R] or \f[CR]Apr\f[R] for a start of month or quarter.)
|
|
.PP
|
|
For weekly reports, choose a date that\[aq]s a Monday.
|
|
(You can try different dates until you see the short headings, or write
|
|
eg \f[CR]\-b \[aq]3 weeks ago\[aq]\f[R].)
|
|
.SS Period expressions
|
|
The \f[CR]\-p/\-\-period\f[R] option specifies a period expression,
|
|
which is a compact way of expressing a start date, end date, and/or
|
|
report interval.
|
|
.PP
|
|
Here\[aq]s a period expression with a start and end date (specifying the
|
|
first quarter of 2009):
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[CR]\-p \[dq]from 2009/1/1 to 2009/4/1\[dq]\f[R]
|
|
T}
|
|
.TE
|
|
.PP
|
|
Several keywords like \[dq]from\[dq] and \[dq]to\[dq] are supported for
|
|
readability; these are optional.
|
|
\[dq]to\[dq] can also be written as \[dq]..\[dq] or \[dq]\-\[dq].
|
|
The spaces are also optional, as long as you don\[aq]t run two dates
|
|
together.
|
|
So the following are equivalent to the above:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[CR]\-p \[dq]2009/1/1 2009/4/1\[dq]\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]\-p2009/1/1to2009/4/1\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]\-p2009/1/1..2009/4/1\f[R]
|
|
T}
|
|
.TE
|
|
.PP
|
|
Dates are smart dates, so if the current year is 2009, these are also
|
|
equivalent to the above:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[CR]\-p \[dq]1/1 4/1\[dq]\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]jan\-apr\[dq]\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]this year to 4/1\[dq]\f[R]
|
|
T}
|
|
.TE
|
|
.PP
|
|
If you specify only one date, the missing start or end date will be the
|
|
earliest or latest transaction date in the journal:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
\f[CR]\-p \[dq]from 2009/1/1\[dq]\f[R]
|
|
T}@T{
|
|
everything after january 1, 2009
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]since 2009/1\[dq]\f[R]
|
|
T}@T{
|
|
the same, since is a synonym
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]from 2009\[dq]\f[R]
|
|
T}@T{
|
|
the same
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]to 2009\[dq]\f[R]
|
|
T}@T{
|
|
everything before january 1, 2009
|
|
T}
|
|
.TE
|
|
.PP
|
|
You can also specify a period by writing a single partial or full date:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(14.5n) lw(55.5n).
|
|
T{
|
|
\f[CR]\-p \[dq]2009\[dq]\f[R]
|
|
T}@T{
|
|
the year 2009; equivalent to \[lq]2009/1/1 to 2010/1/1\[rq]
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]2009/1\[dq]\f[R]
|
|
T}@T{
|
|
the month of january 2009; equivalent to \[lq]2009/1/1 to 2009/2/1\[rq]
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]2009/1/1\[dq]\f[R]
|
|
T}@T{
|
|
the first day of 2009; equivalent to \[lq]2009/1/1 to 2009/1/2\[rq]
|
|
T}
|
|
.TE
|
|
.PP
|
|
or by using the \[dq]Q\[dq] quarter\-year syntax (case insensitive):
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(15.3n) lw(54.7n).
|
|
T{
|
|
\f[CR]\-p \[dq]2009Q1\[dq]\f[R]
|
|
T}@T{
|
|
first quarter of 2009, equivalent to \[lq]2009/1/1 to 2009/4/1\[rq]
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]q4\[dq]\f[R]
|
|
T}@T{
|
|
fourth quarter of the current year
|
|
T}
|
|
.TE
|
|
.SS Period expressions with a report interval
|
|
A period expression can also begin with a report interval, separated
|
|
from the start/end dates (if any) by a space or the word \f[CR]in\f[R]:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l.
|
|
T{
|
|
\f[CR]\-p \[dq]weekly from 2009/1/1 to 2009/4/1\[dq]\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]monthly in 2008\[dq]\f[R]
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]quarterly\[dq]\f[R]
|
|
T}
|
|
.TE
|
|
.SS More complex report intervals
|
|
Some more complex intervals can be specified within period expressions,
|
|
such as:
|
|
.IP \[bu] 2
|
|
\f[CR]biweekly\f[R] (every two weeks)
|
|
.IP \[bu] 2
|
|
\f[CR]fortnightly\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]bimonthly\f[R] (every two months)
|
|
.IP \[bu] 2
|
|
\f[CR]every day|week|month|quarter|year\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]every N days|weeks|months|quarters|years\f[R]
|
|
.PP
|
|
Weekly on a custom day:
|
|
.IP \[bu] 2
|
|
\f[CR]every Nth day of week\f[R] (\f[CR]th\f[R], \f[CR]nd\f[R],
|
|
\f[CR]rd\f[R], or \f[CR]st\f[R] are all accepted after the number)
|
|
.IP \[bu] 2
|
|
\f[CR]every WEEKDAYNAME\f[R] (full or three\-letter english weekday
|
|
name, case insensitive)
|
|
.PP
|
|
Monthly on a custom day:
|
|
.IP \[bu] 2
|
|
\f[CR]every Nth day [of month]\f[R] (\f[CR]31st day\f[R] will be
|
|
adjusted to each month\[aq]s last day)
|
|
.IP \[bu] 2
|
|
\f[CR]every Nth WEEKDAYNAME [of month]\f[R]
|
|
.PP
|
|
Yearly on a custom month and day:
|
|
.IP \[bu] 2
|
|
\f[CR]every MM/DD [of year]\f[R] (month number and day of month number)
|
|
.IP \[bu] 2
|
|
\f[CR]every MONTHNAME DDth [of year]\f[R] (full or three\-letter english
|
|
month name, case insensitive, and day of month number)
|
|
.IP \[bu] 2
|
|
\f[CR]every DDth MONTHNAME [of year]\f[R] (equivalent to the above)
|
|
.PP
|
|
Examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(26.8n) lw(43.2n).
|
|
T{
|
|
\f[CR]\-p \[dq]bimonthly from 2008\[dq]\f[R]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every 2 weeks\[dq]\f[R]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every 5 months from 2009/03\[dq]\f[R]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every 2nd day of week\[dq]\f[R]
|
|
T}@T{
|
|
periods will go from Tue to Tue
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every Tue\[dq]\f[R]
|
|
T}@T{
|
|
same
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every 15th day\[dq]\f[R]
|
|
T}@T{
|
|
period boundaries will be on 15th of each month
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every 2nd Monday\[dq]\f[R]
|
|
T}@T{
|
|
period boundaries will be on second Monday of each month
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every 11/05\[dq]\f[R]
|
|
T}@T{
|
|
yearly periods with boundaries on 5th of November
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every 5th November\[dq]\f[R]
|
|
T}@T{
|
|
same
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every Nov 5th\[dq]\f[R]
|
|
T}@T{
|
|
same
|
|
T}
|
|
.TE
|
|
.PP
|
|
Show historical balances at end of the 15th day of each month (N is an
|
|
end date, exclusive as always):
|
|
.IP
|
|
.EX
|
|
$ hledger balance \-H \-p \[dq]every 16th day\[dq]
|
|
.EE
|
|
.PP
|
|
Group postings from the start of wednesday to end of the following
|
|
tuesday (N is both (inclusive) start date and (exclusive) end date):
|
|
.IP
|
|
.EX
|
|
$ hledger register checking \-p \[dq]every 3rd day of week\[dq]
|
|
.EE
|
|
.SS Multiple weekday intervals
|
|
This special form is also supported:
|
|
.IP \[bu] 2
|
|
\f[CR]every WEEKDAYNAME,WEEKDAYNAME,...\f[R] (full or three\-letter
|
|
english weekday names, case insensitive)
|
|
.PP
|
|
Also, \f[CR]weekday\f[R] and \f[CR]weekendday\f[R] are shorthand for
|
|
\f[CR]mon,tue,wed,thu,fri\f[R] and \f[CR]sat,sun\f[R].
|
|
.PP
|
|
This is mainly intended for use with \f[CR]\-\-forecast\f[R], to
|
|
generate periodic transactions on arbitrary days of the week.
|
|
It may be less useful with \f[CR]\-p\f[R], since it divides each week
|
|
into subperiods of unequal length, which is unusual.
|
|
(Related: #1632)
|
|
.PP
|
|
Examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(17.8n) lw(52.2n).
|
|
T{
|
|
\f[CR]\-p \[dq]every mon,wed,fri\[dq]\f[R]
|
|
T}@T{
|
|
dates will be Mon, Wed, Fri; periods will be Mon\-Tue, Wed\-Thu,
|
|
Fri\-Sun
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every weekday\[dq]\f[R]
|
|
T}@T{
|
|
dates will be Mon, Tue, Wed, Thu, Fri; periods will be Mon, Tue, Wed,
|
|
Thu, Fri\-Sun
|
|
T}
|
|
T{
|
|
\f[CR]\-p \[dq]every weekendday\[dq]\f[R]
|
|
T}@T{
|
|
dates will be Sat, Sun; periods will be Sat, Sun\-Fri
|
|
T}
|
|
.TE
|
|
.SH Depth
|
|
With the \f[CR]\-\-depth NUM\f[R] option (short form, usually preferred:
|
|
\f[CR]\-NUM\f[R]), reports will show accounts only to the specified
|
|
depth, hiding deeper subaccounts.
|
|
Use this when you want a summary with less detail.
|
|
This flag has the same effect as a \f[CR]depth:\f[R] query argument.
|
|
So all of these are equivalent: \f[CR]depth:2\f[R],
|
|
\f[CR]\-\-depth=2\f[R], \f[CR]\-2\f[R].
|
|
.PP
|
|
You can also provide custom depths for specific accounts, by providing a
|
|
\f[CR]REGEX=NUM\f[R] argument instead of just \f[CR]NUM\f[R] \f[I](since
|
|
1.41)\f[R].
|
|
For example, \f[CR]\-\-depth assets=2\f[R] (or
|
|
\f[CR]depth:assets=2\f[R]) will collapse accounts matching the regular
|
|
expression \[dq]assets\[dq] to depth 2.
|
|
So \f[CR]assets:bank:savings\f[R] would be collapsed to
|
|
\f[CR]assets:bank\f[R], but \f[CR]liabilities:bank:credit card\f[R]
|
|
would not be affected.
|
|
.PP
|
|
If REGEX contains spaces or other special characters, enclose it in
|
|
quotes in the usual way.
|
|
Eg: \f[CR]\-\-depth \[aq]credit card=2\[aq]\f[R]
|
|
.SS Combining depth options
|
|
If a command line contains multiple general depth options, the last one
|
|
wins.
|
|
(Useful for overriding a depth specified by scripts.)
|
|
.PP
|
|
Or a command may contain a combination of general and custom depth
|
|
options.
|
|
In this case, the most specifically (deepest) matching option wins.
|
|
Some examples:
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-depth assets=3 \-\-depth expenses=2 \-\-depth 1\f[R] would
|
|
collapse accounts containing \[dq]assets\[dq] to depth 3, accounts
|
|
containing \[dq]expenses\[dq] to depth 2, and all other accounts to
|
|
depth 1.
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R] would collapse
|
|
\f[CR]assets:bank:savings\f[R] to depth 2 (not depth 1; because
|
|
\[dq]savings\[dq] matches a deeper part of the account name than
|
|
\[dq]assets\[dq]).
|
|
.PP
|
|
Note currently, to override a custom depth option
|
|
\f[CR]\-\-depth REGEX=NUM\f[R] with a later option, the later option
|
|
must use the same REGEX.
|
|
.SH Queries
|
|
Many hledger commands accept query arguments, which restrict their scope
|
|
and let you report on a precise subset of your data.
|
|
Here\[aq]s a quick overview of hledger\[aq]s queries:
|
|
.IP \[bu] 2
|
|
By default, a query argument is treated as a case\-insensitive substring
|
|
pattern for matching account names.
|
|
Eg:
|
|
.RS 2
|
|
.PP
|
|
\f[CR]dining groceries\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]car:fuel\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.RE
|
|
.IP \[bu] 2
|
|
Patterns containing spaces or other special characters must be enclosed
|
|
in single or double quotes:
|
|
.RS 2
|
|
.PP
|
|
\f[CR]\[aq]personal care\[aq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.RE
|
|
.IP \[bu] 2
|
|
Patterns are actually regular expressions, so you can add regexp
|
|
metacharacters for more precision (or you may need to backslash\-escape
|
|
certain characters; see \[dq]Regular expressions\[dq] above):
|
|
.RS 2
|
|
.PP
|
|
\f[CR]\[aq]\[ha]expenses\[rs]b\[aq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]\[aq]food$\[aq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]\[aq]fuel|repair\[aq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]\[aq]accounts (payable|receivable)\[aq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.RE
|
|
.IP \[bu] 2
|
|
To match something other than the account name, you can add a query type
|
|
prefix, such as:
|
|
.RS 2
|
|
.PP
|
|
\f[CR]date:202312\-\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]status:\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]desc:amazon\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]cur:USD\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]cur:\[rs]\[rs]$\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]amt:\[aq]>0\[aq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]acct:groceries\f[R] (but \f[CR]acct:\f[R] is the default, so we
|
|
usually don\[aq]t bother writing it)
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.RE
|
|
.IP \[bu] 2
|
|
To negate a query, add a \f[CR]not:\f[R] prefix:
|
|
.RS 2
|
|
.PP
|
|
\f[CR]not:status:\[aq]*\[aq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]not:desc:\[aq]opening|closing\[aq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]not:cur:USD\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.RE
|
|
.IP \[bu] 2
|
|
Multiple query terms can be combined, as space\-separated queries Eg:
|
|
\f[CR]hledger print date:2022 desc:amazon desc:amzn\f[R] (show
|
|
transactions dated in 2022 whose description contains \[dq]amazon\[dq]
|
|
or \[dq]amzn\[dq]).
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.IP \[bu] 2
|
|
Or more flexibly as boolean queries.
|
|
Eg:
|
|
\f[CR]hledger print expr:\[aq]date:2022 and (desc:amazon or desc:amzn) and not date:202210\[aq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.PP
|
|
All hledger commands use the same query language, but different commands
|
|
may interpret the query in different ways.
|
|
We haven\[aq]t described the commands yet (that\[aq]s coming in PART 4:
|
|
COMMANDS below) but here\[aq]s the gist of it:
|
|
.IP \[bu] 2
|
|
Transaction\-oriented commands (\f[CR]print\f[R], \f[CR]aregister\f[R],
|
|
\f[CR]close\f[R], \f[CR]import\f[R], \f[CR]descriptions\f[R]..)
|
|
try to match transactions (including the transaction\[aq]s postings).
|
|
.IP \[bu] 2
|
|
Posting\-oriented commands (\f[CR]register\f[R], \f[CR]balance\f[R],
|
|
\f[CR]balancesheet\f[R], \f[CR]incomestatement\f[R],
|
|
\f[CR]accounts\f[R]..)
|
|
try to match postings.
|
|
Postings inherit their transaction\[aq]s attributes for querying
|
|
purposes, so transaction fields like date or description can still be
|
|
referenced in a posting query.
|
|
.IP \[bu] 2
|
|
A few commands match in more specific ways.
|
|
(Eg \f[CR]aregister\f[R], which has a special first argument.)
|
|
.SS Query types
|
|
Here are the query types available:
|
|
.SS acct: query
|
|
\f[B]\f[CB]acct:REGEX\f[B]\f[R], or just \f[B]\f[CB]REGEX\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match account names containing this case insensitive regular expression.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
This is the default query type, so we usually don\[aq]t bother writing
|
|
the \[dq]acct:\[dq] prefix.
|
|
.SS amt: query
|
|
\f[B]\f[CB]amt:N, amt:\[aq]<N\[aq], amt:\[aq]<=N\[aq], amt:\[aq]>N\[aq], amt:\[aq]>=N\[aq]\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match postings with a single\-commodity amount equal to, less than, or
|
|
greater than N. (Postings with multi\-commodity amounts are not tested
|
|
and will always match.)
|
|
\f[CR]amt:\f[R] needs quotes to hide the less than/greater than sign
|
|
from the command line shell.
|
|
.PP
|
|
The comparison has two modes: if N is preceded by a + or \- sign (or is
|
|
0), the two signed numbers are compared.
|
|
Otherwise, the absolute magnitudes are compared, ignoring sign.
|
|
.PP
|
|
Keep in mind that \f[CR]amt:\f[R] matches posting amounts, not account
|
|
balances.
|
|
.SS code: query
|
|
\f[B]\f[CB]code:REGEX\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match by transaction code (eg check number).
|
|
.SS cur: query
|
|
\f[B]\f[CB]cur:REGEX\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match postings or transactions including any amounts whose
|
|
currency/commodity symbol is fully matched by REGEX.
|
|
(Contrary to hledger\[aq]s usual infix matching.
|
|
To do infix matching, write \f[CR].*REGEX.*\f[R].)
|
|
Note, to match special characters which are regex\-significant, you need
|
|
to escape them with \f[CR]\[rs]\f[R].
|
|
And for characters which are significant to your shell you will usually
|
|
need one more level of escaping.
|
|
Eg to match the dollar sign: \f[CR]cur:\[rs]\[rs]$\f[R] or
|
|
\f[CR]cur:\[aq]\[rs]$\[aq]\f[R]
|
|
.SS desc: query
|
|
\f[B]\f[CB]desc:REGEX\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match transaction descriptions.
|
|
.SS date: query
|
|
\f[B]\f[CB]date:PERIODEXPR\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match dates (or with the \f[CR]\-\-date2\f[R] flag, secondary dates)
|
|
within the specified period.
|
|
PERIODEXPR is a period expression with no report interval.
|
|
Examples:
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]date:2016\f[R], \f[CR]date:thismonth\f[R],
|
|
\f[CR]date:2/1\-2/15\f[R], \f[CR]date:2021\-07\-27..nextquarter\f[R].
|
|
.SS date2: query
|
|
\f[B]\f[CB]date2:PERIODEXPR\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
If you use secondary dates: this matches secondary dates within the
|
|
specified period.
|
|
It is not affected by the \f[CR]\-\-date2\f[R] flag.
|
|
.SS depth: query
|
|
\f[B]\f[CB]depth:[REGEXP=]N\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match (or display, depending on command) accounts at or above this
|
|
depth, optionally only for accounts matching a provided regular
|
|
expression.
|
|
See Depth for detailed rules.
|
|
.SS note: query
|
|
\f[B]\f[CB]note:REGEX\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match transaction notes (the part of the description right of
|
|
\f[CR]|\f[R], or the whole description if there\[aq]s no \f[CR]|\f[R]).
|
|
.SS payee: query
|
|
\f[B]\f[CB]payee:REGEX\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match transaction payee/payer names (the part of the description left of
|
|
\f[CR]|\f[R], or the whole description if there\[aq]s no \f[CR]|\f[R]).
|
|
.SS real: query
|
|
\f[B]\f[CB]real:, real:0\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match real or virtual postings respectively.
|
|
.SS status: query
|
|
\f[B]\f[CB]status:, status:!, status:*\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match unmarked, pending, or cleared transactions respectively.
|
|
.SS type: query
|
|
\f[B]\f[CB]type:TYPECODES\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match by account type (see Declaring accounts > Account types).
|
|
\f[CR]TYPECODES\f[R] is one or more of the single\-letter account type
|
|
codes \f[CR]ALERXCV\f[R], case insensitive.
|
|
Note \f[CR]type:A\f[R] and \f[CR]type:E\f[R] will also match their
|
|
respective subtypes \f[CR]C\f[R] (Cash) and \f[CR]V\f[R] (Conversion).
|
|
Certain kinds of account alias can disrupt account types, see Rewriting
|
|
accounts > Aliases and account types.
|
|
.SS tag: query
|
|
\f[B]\f[CB]tag:NAMEREGEX[=VALREGEX]\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match by tag name, and optionally also by tag value.
|
|
Note:
|
|
.IP \[bu] 2
|
|
Both regular expressions do infix matching.
|
|
If you need a complete match, use \f[CR]\[ha]\f[R] and \f[CR]$\f[R].
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Eg: \f[CR]tag:\[aq]\[ha]fullname$\[aq]\f[R],
|
|
\f[CR]tag:\[aq]\[ha]fullname$=\[ha]fullvalue$\f[R]
|
|
.IP \[bu] 2
|
|
To match values, ignoring names, do \f[CR]tag:.=VALREGEX\f[R]
|
|
.IP \[bu] 2
|
|
Accounts also inherit the tags of their parent accounts.
|
|
.IP \[bu] 2
|
|
Postings also inherit the tags of their account and their transaction .
|
|
.IP \[bu] 2
|
|
Transactions also acquire the tags of their postings.
|
|
.SS Negative queries
|
|
.SS not: query
|
|
\f[B]\f[CB]not:QUERY\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
You can prepend \f[B]\f[CB]not:\f[B]\f[R] to a query to negate the
|
|
match.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Eg: \f[CR]not:equity\f[R], \f[CR]not:desc:apple\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
(Also, a trick: \f[CR]not:not:...\f[R] can sometimes solve query
|
|
problems conveniently.)
|
|
.SS Space\-separated queries
|
|
When given multiple space\-separated query terms, most commands select
|
|
things which match:
|
|
.IP \[bu] 2
|
|
any of the description terms AND
|
|
.IP \[bu] 2
|
|
any of the account terms AND
|
|
.IP \[bu] 2
|
|
any of the status terms AND
|
|
.IP \[bu] 2
|
|
all the other terms.
|
|
.PP
|
|
The print command is a little different, showing transactions which:
|
|
.IP \[bu] 2
|
|
match any of the description terms AND
|
|
.IP \[bu] 2
|
|
have any postings matching any of the positive account terms AND
|
|
.IP \[bu] 2
|
|
have no postings matching any of the negative account terms AND
|
|
.IP \[bu] 2
|
|
match all the other terms.
|
|
.SS Boolean queries
|
|
You can write more complicated \[dq]boolean\[dq] query expressions,
|
|
enclosed in quotes and prefixed with \f[CR]expr:\f[R].
|
|
These can combine subqueries with NOT, AND, OR operators (case
|
|
insensitive), and parentheses for grouping.
|
|
Eg, to show transactions involving both cash and expense accounts:
|
|
.IP
|
|
.EX
|
|
hledger print expr:\[aq]cash AND expenses\[aq]
|
|
.EE
|
|
.PP
|
|
The prefix and enclosing quotes are required, so don\[aq]t write
|
|
\f[CR]hledger print cash AND expenses\f[R].
|
|
That would be a space\-separated query showing transactions involving
|
|
accounts with any of \[dq]cash\[dq], \[dq]and\[dq], \[dq]expenses\[dq]
|
|
in their names.
|
|
.PP
|
|
You can write space\-separated queries \f[I]inside\f[R] a boolean query,
|
|
and they will combine as described above, but it might be confusing and
|
|
best avoided.
|
|
Eg these are equivalent, showing transactions involving cash or expenses
|
|
accounts:
|
|
.IP
|
|
.EX
|
|
hledger print expr:\[aq]cash expenses\[aq]
|
|
hledger print cash expenses
|
|
.EE
|
|
.PP
|
|
There is a restriction with \f[CR]date:\f[R] queries: they may not be
|
|
used inside OR expressions.
|
|
.PP
|
|
Actually, there are three types of boolean query: \f[CR]expr:\f[R] for
|
|
general use, and \f[CR]any:\f[R] and \f[CR]all:\f[R] variants which can
|
|
be useful with \f[CR]print\f[R].
|
|
.SS expr: query
|
|
\f[B]\f[CB]expr:\[aq]QUERYEXPR\[aq]\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
For example,
|
|
\f[CR]expr:\[aq]date:lastmonth AND NOT (food OR rent)\[aq]\f[R] means
|
|
\[dq]match things which are dated in the last month and do not have food
|
|
or rent in the account name\[dq].
|
|
.PP
|
|
When using \f[CR]expr:\f[R] with transaction\-oriented commands like
|
|
\f[CR]print\f[R], posting\-oriented query terms like \f[CR]acct:\f[R]
|
|
and \f[CR]amt:\f[R] are considered to match the transaction if they
|
|
match any of its postings.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
So, \f[CR]hledger print expr:\[aq]cash and amt:>0\[aq]\f[R] means
|
|
\[dq]show transactions with (at least one posting involving a cash
|
|
account) and (at least one posting with a positive amount)\[dq].
|
|
.SS any: query
|
|
\f[B]\f[CB]any:\[aq]QUERYEXPR\[aq]\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.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 a posting can
|
|
be matched by all of QUERYEXPR.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
So, \f[CR]hledger print any:\[aq]cash and amt:>0\[aq]\f[R] means
|
|
\[dq]show transactions where at least one posting posts a positive
|
|
amount to a cash account\[dq].
|
|
.SS all: query
|
|
\f[B]\f[CB]all:\[aq]QUERYEXPR\[aq]\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.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 (and there is at least one posting).
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
So, \f[CR]hledger print all:\[aq]cash and amt:0\[aq]\f[R] means
|
|
\[dq]show transactions where all postings involve a cash account and
|
|
have a zero amount\[dq].
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Or, \f[CR]hledger print all:\[aq]cash or checking\[aq]\f[R] means
|
|
\[dq]show transactions which touch only cash and/or checking
|
|
accounts\[dq].
|
|
.SS Queries and command options
|
|
Some queries can also be expressed as command\-line options:
|
|
\f[CR]depth:2\f[R] is equivalent to \f[CR]\-\-depth 2\f[R],
|
|
\f[CR]date:2023\f[R] is equivalent to \f[CR]\-p 2023\f[R], etc.
|
|
When you mix command options and query arguments, generally the
|
|
resulting query is their intersection.
|
|
.SS Queries and account aliases
|
|
When account names are rewritten with \f[CR]\-\-alias\f[R] or
|
|
\f[CR]alias\f[R], \f[CR]acct:\f[R] will match either the old or the new
|
|
account name.
|
|
.SS Queries and valuation
|
|
When amounts are converted to other commodities in cost or value
|
|
reports, \f[CR]cur:\f[R] and \f[CR]amt:\f[R] match the old commodity
|
|
symbol and the old amount quantity, not the new ones.
|
|
(Except in hledger 1.22, #1625.)
|
|
.SH Pivoting
|
|
Normally, hledger groups amounts and displays their totals by account
|
|
(name).
|
|
With \f[CR]\-\-pivot PIVOTEXPR\f[R], some other field\[aq]s (or multiple
|
|
fields\[aq]) value is used as a synthetic account name, causing
|
|
different grouping and display.
|
|
PIVOTEXPR can be
|
|
.IP \[bu] 2
|
|
any of these standard transaction or posting fields (their value is
|
|
substituted): \f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R],
|
|
\f[CR]payee\f[R], \f[CR]note\f[R], \f[CR]acct\f[R],
|
|
\f[CR]comm\f[R]/\f[CR]cur\f[R], \f[CR]amt\f[R], \f[CR]cost\f[R]
|
|
.IP \[bu] 2
|
|
or a tag name
|
|
.IP \[bu] 2
|
|
or any combination of these, colon\-separated.
|
|
.PP
|
|
Some special cases:
|
|
.IP \[bu] 2
|
|
Colons appearing in PIVOTEXPR or in a pivoted tag value will generate
|
|
account hierarchy.
|
|
.IP \[bu] 2
|
|
When pivoting a posting that has multiple values for a tag, the
|
|
tag\[aq]s first value will be used as the pivoted value.
|
|
.IP \[bu] 2
|
|
When a posting has multiple commodities, the pivoted value of
|
|
\[dq]comm\[dq]/\[dq]cur\[dq] will be \[dq]\[dq].
|
|
Also when an unrecognised tag name or field is provided, its pivoted
|
|
value will be \[dq]\[dq].
|
|
(If this causes confusing output, consider excluding those postings from
|
|
the report.)
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
2016/02/16 Yearly Dues Payment
|
|
assets:bank account 2 EUR
|
|
income:dues \-2 EUR ; member: John Doe, kind: Lifetime
|
|
.EE
|
|
.PP
|
|
Normal balance report showing account names:
|
|
.IP
|
|
.EX
|
|
$ hledger balance
|
|
2 EUR assets:bank account
|
|
\-2 EUR income:dues
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
0
|
|
.EE
|
|
.PP
|
|
Pivoted balance report, using member: tag values instead:
|
|
.IP
|
|
.EX
|
|
$ hledger balance \-\-pivot member
|
|
2 EUR
|
|
\-2 EUR John Doe
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
0
|
|
.EE
|
|
.PP
|
|
One way to show only amounts with a member: value (using a query):
|
|
.IP
|
|
.EX
|
|
$ hledger balance \-\-pivot member tag:member=.
|
|
\-2 EUR John Doe
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-2 EUR
|
|
.EE
|
|
.PP
|
|
Another way (the acct: query matches against the pivoted \[dq]account
|
|
name\[dq]):
|
|
.IP
|
|
.EX
|
|
$ hledger balance \-\-pivot member acct:.
|
|
\-2 EUR John Doe
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-2 EUR
|
|
.EE
|
|
.PP
|
|
Hierarchical reports can be generated with multiple pivot values:
|
|
.IP
|
|
.EX
|
|
$ hledger balance Income:Dues \-\-pivot kind:member
|
|
\-2 EUR Lifetime:John Doe
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-2 EUR
|
|
.EE
|
|
.SH Generating data
|
|
hledger can enrich the data provided to it, or generate new data, in a
|
|
number of ways.
|
|
Mostly, this is done only if you request it:
|
|
.IP \[bu] 2
|
|
Missing amounts or missing costs in transactions are inferred
|
|
automatically when possible.
|
|
.IP \[bu] 2
|
|
The \f[CR]\-\-infer\-equity\f[R] flag infers missing conversion equity
|
|
postings from \[at]/\[at]\[at] costs.
|
|
.IP \[bu] 2
|
|
The \f[CR]\-\-infer\-costs\f[R] flag infers missing costs from
|
|
conversion equity postings.
|
|
.IP \[bu] 2
|
|
The \f[CR]\-\-infer\-market\-prices\f[R] flag infers \f[CR]P\f[R] price
|
|
directives from costs.
|
|
.IP \[bu] 2
|
|
The \f[CR]\-\-auto\f[R] flag adds extra postings to transactions matched
|
|
by auto posting rules.
|
|
.IP \[bu] 2
|
|
The \f[CR]\-\-forecast\f[R] option generates transactions from periodic
|
|
transaction rules.
|
|
.IP \[bu] 2
|
|
The \f[CR]balance \-\-budget\f[R] report infers budget goals from
|
|
periodic transaction rules.
|
|
.IP \[bu] 2
|
|
Commands like \f[CR]close\f[R], \f[CR]rewrite\f[R], and
|
|
\f[CR]hledger\-interest\f[R] generate transactions or postings.
|
|
.IP \[bu] 2
|
|
CSV data is converted to transactions by applying CSV conversion rules..
|
|
etc.
|
|
.PP
|
|
Such generated data is temporary, existing only at report time.
|
|
You can convert it to permanent recorded data by, eg, capturing the
|
|
output of \f[CR]hledger print\f[R] and saving it in your journal file.
|
|
This can sometimes be useful as a data entry aid.
|
|
.PP
|
|
If you are curious what data is being generated and why, run
|
|
\f[CR]hledger print \-x \-\-verbose\-tags\f[R].
|
|
\f[CR]\-x/\-\-explicit\f[R] shows inferred amounts and
|
|
\f[CR]\-\-verbose\-tags\f[R] adds tags like
|
|
\f[CR]generated\-transaction\f[R] (from periodic rules) and
|
|
\f[CR]generated\-posting\f[R], \f[CR]modified\f[R] (from auto posting
|
|
rules).
|
|
Similar hidden tags (with an underscore prefix) are always present,
|
|
also, so you can always match such data with queries like
|
|
\f[CR]tag:generated\f[R] or \f[CR]tag:modified\f[R].
|
|
.SH Forecasting
|
|
Forecasting, or speculative future reporting, can be useful for
|
|
estimating future balances, or for exploring different future scenarios.
|
|
.PP
|
|
The simplest and most flexible way to do it with hledger is to manually
|
|
record a bunch of future\-dated transactions.
|
|
You could keep these in a separate \f[CR]future.journal\f[R] and include
|
|
that with \f[CR]\-f\f[R] only when you want to see them.
|
|
.SS \-\-forecast
|
|
There is another way: with the \f[CR]\-\-forecast\f[R] option, hledger
|
|
can generate temporary \[dq]forecast transactions\[dq] for reporting
|
|
purposes, according to periodic transaction rules defined in the
|
|
journal.
|
|
Each rule can generate multiple recurring transactions, so by changing
|
|
one rule you can change many forecasted transactions.
|
|
.PP
|
|
Forecast transactions usually start after ordinary transactions end.
|
|
By default, they begin after your latest\-dated ordinary transaction, or
|
|
today, whichever is later, and they end six months from today.
|
|
(The exact rules are a little more complicated, and are given below.)
|
|
.PP
|
|
This is the \[dq]forecast period\[dq], which need not be the same as the
|
|
report period.
|
|
You can override it \- eg to forecast farther into the future, or to
|
|
force forecast transactions to overlap your ordinary transactions \- by
|
|
giving the \-\-forecast option a period expression argument, like
|
|
\f[CR]\-\-forecast=..2099\f[R] or
|
|
\f[CR]\-\-forecast=2023\-02\-15..\f[R].
|
|
Note that the \f[CR]=\f[R] is required.
|
|
.SS Inspecting forecast transactions
|
|
\f[CR]print\f[R] is the best command for inspecting and troubleshooting
|
|
forecast transactions.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
\[ti] monthly from 2022\-12\-20 rent
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger print \-\-forecast \-\-today=2023/4/21
|
|
2023\-05\-20 rent
|
|
; generated\-transaction: \[ti] monthly from 2022\-12\-20
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
|
|
2023\-06\-20 rent
|
|
; generated\-transaction: \[ti] monthly from 2022\-12\-20
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
|
|
2023\-07\-20 rent
|
|
; generated\-transaction: \[ti] monthly from 2022\-12\-20
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
|
|
2023\-08\-20 rent
|
|
; generated\-transaction: \[ti] monthly from 2022\-12\-20
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
|
|
2023\-09\-20 rent
|
|
; generated\-transaction: \[ti] monthly from 2022\-12\-20
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
.EE
|
|
.PP
|
|
Here there are no ordinary transactions, so the forecasted transactions
|
|
begin on the first occurrence after today\[aq]s date.
|
|
(You won\[aq]t normally use \f[CR]\-\-today\f[R]; it\[aq]s just to make
|
|
these examples reproducible.)
|
|
.SS Forecast reports
|
|
Forecast transactions affect all reports, as you would expect.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
$ hledger areg rent \-\-forecast \-\-today=2023/4/21
|
|
Transactions in expenses:rent and subaccounts:
|
|
2023\-05\-20 rent as:ba:checking $1000 $1000
|
|
2023\-06\-20 rent as:ba:checking $1000 $2000
|
|
2023\-07\-20 rent as:ba:checking $1000 $3000
|
|
2023\-08\-20 rent as:ba:checking $1000 $4000
|
|
2023\-09\-20 rent as:ba:checking $1000 $5000
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger bal \-M expenses \-\-forecast \-\-today=2023/4/21
|
|
Balance changes in 2023\-05\-01..2023\-09\-30:
|
|
|
|
|| May Jun Jul Aug Sep
|
|
===============++===================================
|
|
expenses:rent || $1000 $1000 $1000 $1000 $1000
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $1000 $1000 $1000 $1000 $1000
|
|
.EE
|
|
.SS Forecast tags
|
|
Forecast transactions generated by \-\-forecast have a hidden tag,
|
|
\f[CR]_generated\-transaction\f[R].
|
|
So if you ever need to match forecast transactions, you could use
|
|
\f[CR]tag:_generated\-transaction\f[R] (or just
|
|
\f[CR]tag:generated\f[R]) in a query.
|
|
.PP
|
|
For troubleshooting, you can add the \f[CR]\-\-verbose\-tags\f[R] flag.
|
|
Then, visible \f[CR]generated\-transaction\f[R] tags will be added also,
|
|
so you can view them with the \f[CR]print\f[R] command.
|
|
Their value indicates which periodic rule was responsible.
|
|
.SS Forecast period, in detail
|
|
Forecast start/end dates are chosen so as to do something useful by
|
|
default in almost all situations, while also being flexible.
|
|
Here are (with luck) the exact rules, to help with troubleshooting:
|
|
.PP
|
|
The forecast period starts on:
|
|
.IP \[bu] 2
|
|
the later of
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
the start date in the periodic transaction rule
|
|
.IP \[bu] 2
|
|
the start date in \f[CR]\-\-forecast\f[R]\[aq]s argument
|
|
.RE
|
|
.IP \[bu] 2
|
|
otherwise (if those are not available): the later of
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
the report start date specified with
|
|
\f[CR]\-b\f[R]/\f[CR]\-p\f[R]/\f[CR]date:\f[R]
|
|
.IP \[bu] 2
|
|
the day after the latest ordinary transaction in the journal
|
|
.RE
|
|
.IP \[bu] 2
|
|
otherwise (if none of these are available): today.
|
|
.PP
|
|
The forecast period ends on:
|
|
.IP \[bu] 2
|
|
the earlier of
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
the end date in the periodic transaction rule
|
|
.IP \[bu] 2
|
|
the end date in \f[CR]\-\-forecast\f[R]\[aq]s argument
|
|
.RE
|
|
.IP \[bu] 2
|
|
otherwise: the report end date specified with
|
|
\f[CR]\-e\f[R]/\f[CR]\-p\f[R]/\f[CR]date:\f[R]
|
|
.IP \[bu] 2
|
|
otherwise: 180 days (\[ti]6 months) from today.
|
|
.SS Forecast troubleshooting
|
|
When \-\-forecast is not doing what you expect, one of these tips should
|
|
help:
|
|
.IP \[bu] 2
|
|
Remember to use the \f[CR]\-\-forecast\f[R] option.
|
|
.IP \[bu] 2
|
|
Remember to have at least one periodic transaction rule in your journal.
|
|
.IP \[bu] 2
|
|
Test with \f[CR]print \-\-forecast\f[R].
|
|
.IP \[bu] 2
|
|
Check for typos or too\-restrictive start/end dates in your periodic
|
|
transaction rule.
|
|
.IP \[bu] 2
|
|
Leave at least 2 spaces between the rule\[aq]s period expression and
|
|
description fields.
|
|
.IP \[bu] 2
|
|
Check for future\-dated ordinary transactions suppressing forecasted
|
|
transactions.
|
|
.IP \[bu] 2
|
|
Try setting explicit report start and/or end dates with \f[CR]\-b\f[R],
|
|
\f[CR]\-e\f[R], \f[CR]\-p\f[R] or \f[CR]date:\f[R]
|
|
.IP \[bu] 2
|
|
Try adding the \f[CR]\-E\f[R] flag to encourage display of empty
|
|
periods/zero transactions.
|
|
.IP \[bu] 2
|
|
Try setting explicit forecast start and/or end dates with
|
|
\f[CR]\-\-forecast=START..END\f[R]
|
|
.IP \[bu] 2
|
|
Consult Forecast period, in detail, above.
|
|
.IP \[bu] 2
|
|
Check inside the engine: add \f[CR]\-\-debug=2\f[R] (eg).
|
|
.SH Budgeting
|
|
With the balance command\[aq]s \f[CR]\-\-budget\f[R] report, each
|
|
periodic transaction rule generates recurring budget goals in specified
|
|
accounts, and goals and actual performance can be compared.
|
|
See the balance command\[aq]s doc below.
|
|
.PP
|
|
You can generate budget goals and forecast transactions at the same
|
|
time, from the same or different periodic transaction rules:
|
|
\f[CR]hledger bal \-M \-\-budget \-\-forecast ...\f[R]
|
|
.PP
|
|
See also: Budgeting and Forecasting.
|
|
.SH Amount formatting
|
|
.SS Commodity display style
|
|
For the amounts in each commodity, hledger chooses a consistent display
|
|
style (symbol placement, decimal mark and digit group marks, number of
|
|
decimal digits) to use in most reports.
|
|
This is inferred as follows:
|
|
.PP
|
|
First, if there\[aq]s a \f[CR]D\f[R] directive declaring a default
|
|
commodity, that commodity symbol and amount format is applied to all
|
|
no\-symbol amounts in the journal.
|
|
.PP
|
|
Then each commodity\[aq]s display style is determined from its
|
|
\f[CR]commodity\f[R] directive.
|
|
We recommend always declaring commodities with \f[CR]commodity\f[R]
|
|
directives, since they help ensure consistent display styles and
|
|
precisions, and bring other benefits such as error checking for
|
|
commodity symbols.
|
|
Here\[aq]s an example:
|
|
.IP
|
|
.EX
|
|
# Set display styles (and decimal marks, for parsing, if there is no decimal\-mark directive)
|
|
# for the $, EUR, INR and no\-symbol commodities:
|
|
commodity $1,000.00
|
|
commodity EUR 1.000,00
|
|
commodity INR 9,99,99,999.00
|
|
commodity 1 000 000.9455
|
|
.EE
|
|
.PP
|
|
But for convenience, if a \f[CR]commodity\f[R] directive is not present,
|
|
hledger infers a commodity\[aq]s display styles from its amounts as they
|
|
are written in the journal (excluding cost amounts and amounts in
|
|
periodic transaction rules or auto posting rules).
|
|
It uses
|
|
.IP \[bu] 2
|
|
the symbol placement and decimal mark of the first amount seen
|
|
.IP \[bu] 2
|
|
the digit group marks of the first amount with digit group marks
|
|
.IP \[bu] 2
|
|
and the maximum number of decimal digits seen across all amounts.
|
|
.PP
|
|
And as fallback if no applicable amounts are found, it would use a
|
|
default style, like \f[CR]$1000.00\f[R] (symbol on the left with no
|
|
space, period as decimal mark, and two decimal digits).
|
|
.PP
|
|
Finally, commodity styles can be overridden by the
|
|
\f[CR]\-c/\-\-commodity\-style\f[R] command line option.
|
|
.SS Rounding
|
|
Amounts are stored internally as decimal numbers with up to 255 decimal
|
|
places.
|
|
They are displayed with their original journal precisions by print and
|
|
print\-like reports, and rounded to their display precision (the number
|
|
of decimal digits specified by the commodity display style) by other
|
|
reports.
|
|
When rounding, hledger uses banker\[aq]s rounding (it rounds to the
|
|
nearest even digit).
|
|
So eg 0.5 displayed with zero decimal digits appears as \[dq]0\[dq].
|
|
.SS Trailing decimal marks
|
|
If you\[aq]re wondering why your \f[CR]print\f[R] report sometimes shows
|
|
trailing decimal marks, with no decimal digits; it does this when
|
|
showing amounts that have digit group marks but no decimal digits, to
|
|
disambiguate them and allow them to be re\-parsed reliably (see Decimal
|
|
marks).
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
commodity $1,000.00
|
|
|
|
2023\-01\-02
|
|
(a) $1000
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger print
|
|
2023\-01\-02
|
|
(a) $1,000.
|
|
.EE
|
|
.PP
|
|
If this is a problem (eg when exporting to Ledger), you can avoid it by
|
|
disabling digit group marks, eg with \-c/\-\-commodity (for each
|
|
affected commodity):
|
|
.IP
|
|
.EX
|
|
$ hledger print \-c \[aq]$1000.00\[aq]
|
|
2023\-01\-02
|
|
(a) $1000
|
|
.EE
|
|
.PP
|
|
or by forcing print to always show decimal digits, with \-\-round:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-c \[aq]$1,000.00\[aq] \-\-round=soft
|
|
2023\-01\-02
|
|
(a) $1,000.00
|
|
.EE
|
|
.SS Amount parseability
|
|
More generally, hledger output falls into three rough categories, which
|
|
format amounts a little bit differently to suit different consumers:
|
|
.PP
|
|
\f[B]1.
|
|
\[dq]hledger\-readable output\[dq] \- should be readable by hledger (and
|
|
by humans)\f[R]
|
|
.IP \[bu] 2
|
|
This is produced by reports that show full journal entries:
|
|
\f[CR]print\f[R], \f[CR]import\f[R], \f[CR]close\f[R],
|
|
\f[CR]rewrite\f[R] etc.
|
|
.IP \[bu] 2
|
|
It shows amounts with their original journal precisions, which may not
|
|
be consistent from one amount to the next.
|
|
.IP \[bu] 2
|
|
It adds a trailing decimal mark when needed to avoid showing ambiguous
|
|
amounts.
|
|
.IP \[bu] 2
|
|
It can be parsed reliably (by hledger and ledger2beancount at least, but
|
|
perhaps not by Ledger..)
|
|
.PP
|
|
\f[B]2.
|
|
\[dq]human\-readable output\[dq] \- usually for humans\f[R]
|
|
.IP \[bu] 2
|
|
This is produced by all other reports.
|
|
.IP \[bu] 2
|
|
It shows amounts with standard display precisions, which will be
|
|
consistent within each commodity.
|
|
.IP \[bu] 2
|
|
It shows ambiguous amounts unmodified.
|
|
.IP \[bu] 2
|
|
It can be parsed reliably in the context of a known report (when you
|
|
know decimals are consistently not being shown, you can assume a single
|
|
mark is a digit group mark).
|
|
.PP
|
|
\f[B]3.
|
|
\[dq]machine\-readable output\[dq] \- usually for other software\f[R]
|
|
.IP \[bu] 2
|
|
This is produced by all reports when an output format like
|
|
\f[CR]csv\f[R], \f[CR]tsv\f[R], \f[CR]json\f[R], or \f[CR]sql\f[R] is
|
|
selected.
|
|
.IP \[bu] 2
|
|
It shows amounts as 1 or 2 do, but without digit group marks.
|
|
.IP \[bu] 2
|
|
It can be parsed reliably (if needed, the decimal mark can be changed
|
|
with \-c/\-\-commodity\-style).
|
|
.SH Cost reporting
|
|
In some transactions \- for example a currency conversion, or a purchase
|
|
or sale of stock \- one commodity is exchanged for another.
|
|
In these transactions there is a conversion rate, also called the cost
|
|
(when buying) or selling price (when selling).
|
|
(In hledger docs we just say \[dq]cost\[dq] generically for
|
|
convenience.)
|
|
With the \f[CR]\-B/\-\-cost\f[R] flag, hledger can show amounts \[dq]at
|
|
cost\[dq], converted to the cost\[aq]s commodity.
|
|
.SS Recording costs
|
|
We\[aq]ll explore several ways of recording transactions involving
|
|
costs.
|
|
These are also summarised at hledger Cookbook > Cost notation.
|
|
.PP
|
|
Costs can be recorded explicitly in the journal, using the
|
|
\f[CR]\[at] UNITCOST\f[R] or \f[CR]\[at]\[at] TOTALCOST\f[R] notation
|
|
described in Journal > Costs:
|
|
.PP
|
|
\f[B]Variant 1\f[R]
|
|
.IP
|
|
.EX
|
|
2022\-01\-01
|
|
assets:dollars $\-135
|
|
assets:euros €100 \[at] $1.35 ; $1.35 per euro (unit cost)
|
|
.EE
|
|
.PP
|
|
\f[B]Variant 2\f[R]
|
|
.IP
|
|
.EX
|
|
2022\-01\-01
|
|
assets:dollars $\-135
|
|
assets:euros €100 \[at]\[at] $135 ; $135 total cost
|
|
.EE
|
|
.PP
|
|
Typically, writing the unit cost (variant 1) is preferable; it can be
|
|
more effort, requiring more attention to decimal digits; but it reveals
|
|
the per\-unit cost basis, and makes stock sales easier.
|
|
.PP
|
|
Costs can also be left implicit, and hledger will infer the cost that is
|
|
consistent with a balanced transaction:
|
|
.PP
|
|
\f[B]Variant 3\f[R]
|
|
.IP
|
|
.EX
|
|
2022\-01\-01
|
|
assets:dollars $\-135
|
|
assets:euros €100
|
|
.EE
|
|
.PP
|
|
Here, hledger will attach a \f[CR]\[at]\[at] €100\f[R] cost to the first
|
|
amount (you can see it with \f[CR]hledger print \-x\f[R]).
|
|
This form looks convenient, but there are downsides:
|
|
.IP \[bu] 2
|
|
It sacrifices some error checking.
|
|
For example, if you accidentally wrote €10 instead of €100, hledger
|
|
would not be able to detect the mistake.
|
|
.IP \[bu] 2
|
|
It is sensitive to the order of postings \- if they were reversed, a
|
|
different entry would be inferred and reports would be different.
|
|
.IP \[bu] 2
|
|
The per\-unit cost basis is not easy to read.
|
|
.PP
|
|
So generally this kind of entry is not recommended.
|
|
You can make sure you have none of these by using \f[CR]\-s\f[R] (strict
|
|
mode), or by running \f[CR]hledger check balanced\f[R].
|
|
.SS Reporting at cost
|
|
Now when you add the \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R] flag to reports
|
|
(\[dq]B\[dq] is from Ledger\[aq]s \-B/\-\-basis/\-\-cost flag), any
|
|
amounts which have been annotated with costs will be converted to their
|
|
cost\[aq]s commodity (in the report output).
|
|
Ie they will be displayed \[dq]at cost\[dq] or \[dq]at sale price\[dq].
|
|
.PP
|
|
Some things to note:
|
|
.IP \[bu] 2
|
|
Costs are attached to specific posting amounts in specific transactions,
|
|
and once recorded they do not change.
|
|
This contrasts with market prices, which are ambient and fluctuating.
|
|
.IP \[bu] 2
|
|
Conversion to cost is performed before conversion to market value
|
|
(described below).
|
|
.SS Equity conversion postings
|
|
There is a problem with the entries above \- they are not conventional
|
|
Double Entry Bookkeeping (DEB) notation, and because of the
|
|
\[dq]magical\[dq] transformation of one commodity into another, they
|
|
cause an imbalance in the Accounting Equation.
|
|
This shows up as a non\-zero grand total in balance reports like
|
|
\f[CR]hledger bse\f[R].
|
|
.PP
|
|
For most hledger users, this doesn\[aq]t matter in practice and can
|
|
safely be ignored !
|
|
But if you\[aq]d like to learn more, keep reading.
|
|
.PP
|
|
Conventional DEB uses an extra pair of equity postings to balance the
|
|
transaction.
|
|
Of course you can do this in hledger as well:
|
|
.PP
|
|
\f[B]Variant 4\f[R]
|
|
.IP
|
|
.EX
|
|
2022\-01\-01
|
|
assets:dollars $\-135
|
|
assets:euros €100
|
|
equity:conversion $135
|
|
equity:conversion €\-100
|
|
.EE
|
|
.PP
|
|
Now the transaction is perfectly balanced according to standard DEB, and
|
|
\f[CR]hledger bse\f[R]\[aq]s total will not be disrupted.
|
|
.PP
|
|
And, hledger can still infer the cost for cost reporting, but it\[aq]s
|
|
not done by default \- you must add the \f[CR]\-\-infer\-costs\f[R] flag
|
|
like so:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-\-infer\-costs
|
|
2022\-01\-01 one hundred euros purchased at $1.35 each
|
|
assets:dollars $\-135 \[at]\[at] €100
|
|
assets:euros €100
|
|
equity:conversion $135
|
|
equity:conversion €\-100
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger bal \-\-infer\-costs \-B
|
|
€\-100 assets:dollars
|
|
€100 assets:euros
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
0
|
|
.EE
|
|
.PP
|
|
Here are some downsides of this kind of entry:
|
|
.IP \[bu] 2
|
|
The per\-unit cost basis is not easy to read.
|
|
.IP \[bu] 2
|
|
Instead of \f[CR]\-B\f[R] you must remember to type
|
|
\f[CR]\-B \-\-infer\-costs\f[R].
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-infer\-costs\f[R] works only where hledger can identify the
|
|
two equity:conversion postings and match them up with the two
|
|
non\-equity postings.
|
|
So writing the journal entry in a particular format becomes more
|
|
important.
|
|
More on this below.
|
|
.SS Inferring equity conversion postings
|
|
Can we go in the other direction ?
|
|
Yes, if you have transactions written with the \[at]/\[at]\[at] cost
|
|
notation, hledger can infer the missing equity postings, if you add the
|
|
\f[CR]\-\-infer\-equity\f[R] flag.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
2022\-01\-01
|
|
assets:dollars \-$135
|
|
assets:euros €100 \[at] $1.35
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger print \-\-infer\-equity
|
|
2022\-01\-01
|
|
assets:dollars $\-135
|
|
assets:euros €100 \[at] $1.35
|
|
equity:conversion:$\-€:€ €\-100
|
|
equity:conversion:$\-€:$ $135.00
|
|
.EE
|
|
.PP
|
|
The equity account names will be \[dq]equity:conversion:A\-B:A\[dq] and
|
|
\[dq]equity:conversion:A\-B:B\[dq] where A is the alphabetically first
|
|
commodity symbol.
|
|
You can customise the \[dq]equity:conversion\[dq] part by declaring an
|
|
account with the \f[CR]V\f[R]/\f[CR]Conversion\f[R] account type.
|
|
.PP
|
|
Note you will need to add account declarations for these to your
|
|
journal, if you use \f[CR]check accounts\f[R] or
|
|
\f[CR]check \-\-strict\f[R].
|
|
.SS Combining costs and equity conversion postings
|
|
Finally, you can use both the \[at]/\[at]\[at] cost notation and equity
|
|
postings at the same time.
|
|
This in theory gives the best of all worlds \- preserving the accounting
|
|
equation, revealing the per\-unit cost basis, and providing more
|
|
flexibility in how you write the entry:
|
|
.PP
|
|
\f[B]Variant 5\f[R]
|
|
.IP
|
|
.EX
|
|
2022\-01\-01 one hundred euros purchased at $1.35 each
|
|
assets:dollars $\-135
|
|
equity:conversion $135
|
|
equity:conversion €\-100
|
|
assets:euros €100 \[at] $1.35
|
|
.EE
|
|
.PP
|
|
All the other variants above can (usually) be rewritten to this final
|
|
form with:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-x \-\-infer\-costs \-\-infer\-equity
|
|
.EE
|
|
.PP
|
|
Downsides:
|
|
.IP \[bu] 2
|
|
The precise format of the journal entry becomes more important.
|
|
If hledger can\[aq]t detect and match up the cost and equity postings,
|
|
it will give a transaction balancing error.
|
|
.IP \[bu] 2
|
|
The add command does not yet accept this kind of entry (#2056).
|
|
.IP \[bu] 2
|
|
This is the most verbose form.
|
|
.SS Requirements for detecting equity conversion postings
|
|
\f[CR]\-\-infer\-costs\f[R] has certain requirements (unlike
|
|
\f[CR]\-\-infer\-equity\f[R], which always works).
|
|
It will infer costs only in transactions with:
|
|
.IP \[bu] 2
|
|
Two non\-equity postings, in different commodities.
|
|
Their order is significant: the cost will be added to the first of them.
|
|
.IP \[bu] 2
|
|
Two postings to equity conversion accounts, next to one another, which
|
|
balance the two non\-equity postings.
|
|
This balancing is checked to the same precision (number of decimal
|
|
places) used in the conversion posting\[aq]s amount.
|
|
Equity conversion accounts are:
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
any accounts declared with account type
|
|
\f[CR]V\f[R]/\f[CR]Conversion\f[R], or their subaccounts
|
|
.IP \[bu] 2
|
|
otherwise, accounts named \f[CR]equity:conversion\f[R],
|
|
\f[CR]equity:trade\f[R], or \f[CR]equity:trading\f[R], or their
|
|
subaccounts.
|
|
.RE
|
|
.PP
|
|
And multiple such four\-posting groups can coexist within a single
|
|
transaction.
|
|
When \f[CR]\-\-infer\-costs\f[R] fails, it does not infer a cost in that
|
|
transaction, and does not raise an error (ie, it infers costs where it
|
|
can).
|
|
.PP
|
|
Reading variant 5 journal entries, combining cost notation and equity
|
|
postings, has all the same requirements.
|
|
When reading such an entry fails, hledger raises an \[dq]unbalanced
|
|
transaction\[dq] error.
|
|
.SS Infer cost and equity by default ?
|
|
Should \f[CR]\-\-infer\-costs\f[R] and \f[CR]\-\-infer\-equity\f[R] be
|
|
enabled by default ?
|
|
Try using them always, eg with a shell alias:
|
|
.IP
|
|
.EX
|
|
alias h=\[dq]hledger \-\-infer\-equity \-\-infer\-costs\[dq]
|
|
.EE
|
|
.PP
|
|
and let us know what problems you find.
|
|
.PP
|
|
.SH Value reporting
|
|
hledger can also show amounts \[dq]at market value\[dq], converted to
|
|
some other commodity using the market price or conversion rate on a
|
|
certain date.
|
|
.PP
|
|
This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option.
|
|
We also provide simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R]
|
|
aliases for this, which are often sufficient.
|
|
The market prices are declared with a special \f[CR]P\f[R] directive,
|
|
and/or they can be inferred from the costs recorded in transactions, by
|
|
using the \f[CR]\-\-infer\-market\-prices\f[R] flag.
|
|
.SS \-V: Value
|
|
The \f[CR]\-V/\-\-market\f[R] flag converts amounts to market value in
|
|
their default \f[I]valuation commodity\f[R], using the market prices in
|
|
effect on the \f[I]valuation date(s)\f[R], if any.
|
|
More on these in a minute.
|
|
.SS \-X: Value in specified commodity
|
|
The \f[CR]\-X/\-\-exchange=COMM\f[R] option is like \f[CR]\-V\f[R],
|
|
except you tell it which currency you want to convert to, and it tries
|
|
to convert everything to that.
|
|
.SS Valuation date
|
|
Market prices can change from day to day.
|
|
hledger will use the prices on a particular valuation date (or on more
|
|
than one date).
|
|
By default hledger uses \[dq]end\[dq] dates for valuation.
|
|
More specifically:
|
|
.IP \[bu] 2
|
|
For single period reports (including normal print and register reports):
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
If an explicit report end date is specified, that is used.
|
|
.IP \[bu] 2
|
|
Otherwise the latest transaction date or non\-future P directive date is
|
|
used.
|
|
.RE
|
|
.IP \[bu] 2
|
|
For multiperiod reports, each period is valued on its last day.
|
|
.PP
|
|
This can be customised with the \-\-value option described below, which
|
|
can select either \[dq]then\[dq], \[dq]end\[dq], \[dq]now\[dq], or
|
|
\[dq]custom\[dq] dates.
|
|
.SS Finding market price
|
|
To convert a commodity A to its market value in another commodity B,
|
|
hledger looks for a suitable market price (exchange rate) as follows, in
|
|
this order of preference:
|
|
.IP "1." 3
|
|
A \f[I]declared market price\f[R] or \f[I]inferred market price\f[R]:
|
|
A\[aq]s latest market price in B on or before the valuation date as
|
|
declared by a P directive, or (with the
|
|
\f[CR]\-\-infer\-market\-prices\f[R] flag) inferred from costs.
|
|
\
|
|
.IP "2." 3
|
|
A \f[I]reverse market price\f[R]: the inverse of a declared or inferred
|
|
market price from B to A.
|
|
.IP "3." 3
|
|
A \f[I]forward chain of market prices\f[R]: a synthetic price formed by
|
|
combining the shortest chain of \[dq]forward\[dq] (only 1 above) market
|
|
prices, leading from A to B.
|
|
.IP "4." 3
|
|
\f[I]Any chain of market prices\f[R]: a chain of any market prices,
|
|
including both forward and reverse prices (1 and 2 above), leading from
|
|
A to B.
|
|
.PP
|
|
There is a limit to the length of these price chains; if hledger reaches
|
|
that length without finding a complete chain or exhausting all
|
|
possibilities, it will give up (with a \[dq]gave up\[dq] message visible
|
|
in \f[CR]\-\-debug=2\f[R] output).
|
|
That limit is currently 1000.
|
|
.PP
|
|
Amounts for which no suitable market price can be found, are not
|
|
converted.
|
|
.SS \-\-infer\-market\-prices: market prices from transactions
|
|
Normally, market value in hledger is fully controlled by, and requires,
|
|
P directives in your journal.
|
|
Since adding and updating those can be a chore, and since transactions
|
|
usually take place at close to market value, why not use the recorded
|
|
costs as additional market prices (as Ledger does) ?
|
|
Adding the \f[CR]\-\-infer\-market\-prices\f[R] flag to \f[CR]\-V\f[R],
|
|
\f[CR]\-X\f[R] or \f[CR]\-\-value\f[R] enables this.
|
|
.PP
|
|
So for example, \f[CR]hledger bs \-V \-\-infer\-market\-prices\f[R] will
|
|
get market prices both from P directives and from transactions.
|
|
If both occur on the same day, the P directive takes precedence.
|
|
.PP
|
|
There is a downside: value reports can sometimes be affected in
|
|
confusing/undesired ways by your journal entries.
|
|
If this happens to you, read all of this Value reporting section
|
|
carefully, and try adding \f[CR]\-\-debug\f[R] or \f[CR]\-\-debug=2\f[R]
|
|
to troubleshoot.
|
|
.PP
|
|
\f[CR]\-\-infer\-market\-prices\f[R] can infer market prices from:
|
|
.IP \[bu] 2
|
|
multicommodity transactions with explicit prices
|
|
(\f[CR]\[at]\f[R]/\f[CR]\[at]\[at]\f[R])
|
|
.IP \[bu] 2
|
|
multicommodity transactions with implicit prices (no \f[CR]\[at]\f[R],
|
|
two commodities, unbalanced).
|
|
(With these, the order of postings matters.
|
|
\f[CR]hledger print \-x\f[R] can be useful for troubleshooting.)
|
|
.IP \[bu] 2
|
|
multicommodity transactions with equity postings, if cost is inferred
|
|
with \f[CR]\-\-infer\-costs\f[R].
|
|
.PP
|
|
There is a limitation (bug) currently: when a valuation commodity is not
|
|
specified, prices inferred with \f[CR]\-\-infer\-market\-prices\f[R] do
|
|
not help select a default valuation commodity, as \f[CR]P\f[R] prices
|
|
would.
|
|
So conversion might not happen because no valuation commodity was
|
|
detected (\f[CR]\-\-debug=2\f[R] will show this).
|
|
To be safe, specify the valuation commmodity, eg:
|
|
.IP \[bu] 2
|
|
\f[CR]\-X EUR \-\-infer\-market\-prices\f[R], not
|
|
\f[CR]\-V \-\-infer\-market\-prices\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-value=then,EUR \-\-infer\-market\-prices\f[R], not
|
|
\f[CR]\-\-value=then \-\-infer\-market\-prices\f[R]
|
|
.PP
|
|
Signed costs and market prices can be confusing.
|
|
For reference, here is the current behaviour, since hledger 1.25.
|
|
(If you think it should work differently, see #1870.)
|
|
.IP
|
|
.EX
|
|
2022\-01\-01 Positive Unit prices
|
|
a A 1
|
|
b B \-1 \[at] A 1
|
|
|
|
2022\-01\-01 Positive Total prices
|
|
a A 1
|
|
b B \-1 \[at]\[at] A 1
|
|
|
|
|
|
2022\-01\-02 Negative unit prices
|
|
a A 1
|
|
b B 1 \[at] A \-1
|
|
|
|
2022\-01\-02 Negative total prices
|
|
a A 1
|
|
b B 1 \[at]\[at] A \-1
|
|
|
|
|
|
2022\-01\-03 Double Negative unit prices
|
|
a A \-1
|
|
b B \-1 \[at] A \-1
|
|
|
|
2022\-01\-03 Double Negative total prices
|
|
a A \-1
|
|
b B \-1 \[at]\[at] A \-1
|
|
.EE
|
|
.PP
|
|
All of the transactions above are considered balanced (and on each day,
|
|
the two transactions are considered equivalent).
|
|
Here are the market prices inferred for B:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f\- \-\-infer\-market\-prices prices
|
|
P 2022\-01\-01 B A 1
|
|
P 2022\-01\-01 B A 1.0
|
|
P 2022\-01\-02 B A \-1
|
|
P 2022\-01\-02 B A \-1.0
|
|
P 2022\-01\-03 B A \-1
|
|
P 2022\-01\-03 B A \-1.0
|
|
.EE
|
|
.SS Valuation commodity
|
|
\f[B]When you specify a valuation commodity (\f[CB]\-X COMM\f[B] or
|
|
\f[CB]\-\-value TYPE,COMM\f[B]):\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
hledger will convert all amounts to COMM, wherever it can find a
|
|
suitable market price (including by reversing or chaining prices).
|
|
.PP
|
|
\f[B]When you leave the valuation commodity unspecified (\f[CB]\-V\f[B]
|
|
or \f[CB]\-\-value TYPE\f[B]):\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
For each commodity A, hledger picks a default valuation commodity as
|
|
follows, in this order of preference:
|
|
.IP "1." 3
|
|
The price commodity from the latest P\-declared market price for A on or
|
|
before valuation date.
|
|
.IP "2." 3
|
|
The price commodity from the latest P\-declared market price for A on
|
|
any date.
|
|
(Allows conversion to proceed when there are inferred prices before the
|
|
valuation date.)
|
|
.IP "3." 3
|
|
If there are no P directives at all (any commodity or date) and the
|
|
\f[CR]\-\-infer\-market\-prices\f[R] flag is used: the price commodity
|
|
from the latest transaction\-inferred price for A on or before valuation
|
|
date.
|
|
.PP
|
|
This means:
|
|
.IP \[bu] 2
|
|
If you have P directives, they determine which commodities
|
|
\f[CR]\-V\f[R] will convert, and to what.
|
|
.IP \[bu] 2
|
|
If you have no P directives, and use the
|
|
\f[CR]\-\-infer\-market\-prices\f[R] flag, costs determine it.
|
|
.PP
|
|
Amounts for which no valuation commodity can be found are not converted.
|
|
.SS \-\-value: Flexible valuation
|
|
\f[CR]\-V\f[R] and \f[CR]\-X\f[R] are special cases of the more general
|
|
\f[CR]\-\-value\f[R] option:
|
|
.IP
|
|
.EX
|
|
\-\-value=TYPE[,COMM] TYPE is then, end, now or YYYY\-MM\-DD.
|
|
COMM is an optional commodity symbol.
|
|
Shows amounts converted to:
|
|
\- default valuation commodity (or COMM) using market prices at posting dates
|
|
\- default valuation commodity (or COMM) using market prices at period end(s)
|
|
\- default valuation commodity (or COMM) using current market prices
|
|
\- default valuation commodity (or COMM) using market prices at some date
|
|
.EE
|
|
.PP
|
|
The TYPE part selects cost or value and valuation date:
|
|
.TP
|
|
\f[CR]\-\-value=then\f[R]
|
|
Convert amounts to their value in the default valuation commodity, using
|
|
market prices on each posting\[aq]s date.
|
|
.TP
|
|
\f[CR]\-\-value=end\f[R]
|
|
Convert amounts to their value in the default valuation commodity, using
|
|
market prices on the last day of the report period (or if unspecified,
|
|
the journal\[aq]s end date); or in multiperiod reports, market prices on
|
|
the last day of each subperiod.
|
|
.TP
|
|
\f[CR]\-\-value=now\f[R]
|
|
Convert amounts to their value in the default valuation commodity using
|
|
current market prices (as of when report is generated).
|
|
.TP
|
|
\f[CR]\-\-value=YYYY\-MM\-DD\f[R]
|
|
Convert amounts to their value in the default valuation commodity using
|
|
market prices on this date.
|
|
.PP
|
|
To select a different valuation commodity, add the optional
|
|
\f[CR],COMM\f[R] part: a comma, then the target commodity\[aq]s symbol.
|
|
Eg: \f[B]\f[CB]\-\-value=now,EUR\f[B]\f[R].
|
|
hledger will do its best to convert amounts to this commodity, deducing
|
|
market prices as described above.
|
|
.SS Valuation examples
|
|
Here are some quick examples of \f[CR]\-V\f[R]:
|
|
.IP
|
|
.EX
|
|
; one euro is worth this many dollars from nov 1
|
|
P 2016/11/01 € $1.10
|
|
|
|
; purchase some euros on nov 3
|
|
2016/11/3
|
|
assets:euros €100
|
|
assets:checking
|
|
|
|
; the euro is worth fewer dollars by dec 21
|
|
P 2016/12/21 € $1.03
|
|
.EE
|
|
.PP
|
|
How many euros do I have ?
|
|
.IP
|
|
.EX
|
|
$ hledger \-f t.j bal \-N euros
|
|
€100 assets:euros
|
|
.EE
|
|
.PP
|
|
What are they worth at end of nov 3 ?
|
|
.IP
|
|
.EX
|
|
$ hledger \-f t.j bal \-N euros \-V \-e 2016/11/4
|
|
$110.00 assets:euros
|
|
.EE
|
|
.PP
|
|
What are they worth after 2016/12/21 ?
|
|
(no report end date specified, defaults to today)
|
|
.IP
|
|
.EX
|
|
$ hledger \-f t.j bal \-N euros \-V
|
|
$103.00 assets:euros
|
|
.EE
|
|
.PP
|
|
Here are some examples showing the effect of \f[CR]\-\-value\f[R], as
|
|
seen with \f[CR]print\f[R]:
|
|
.IP
|
|
.EX
|
|
P 2000\-01\-01 A 1 B
|
|
P 2000\-02\-01 A 2 B
|
|
P 2000\-03\-01 A 3 B
|
|
P 2000\-04\-01 A 4 B
|
|
|
|
2000\-01\-01
|
|
(a) 1 A \[at] 5 B
|
|
|
|
2000\-02\-01
|
|
(a) 1 A \[at] 6 B
|
|
|
|
2000\-03\-01
|
|
(a) 1 A \[at] 7 B
|
|
.EE
|
|
.PP
|
|
Show the cost of each posting:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f\- print \-\-cost
|
|
2000\-01\-01
|
|
(a) 5 B
|
|
|
|
2000\-02\-01
|
|
(a) 6 B
|
|
|
|
2000\-03\-01
|
|
(a) 7 B
|
|
.EE
|
|
.PP
|
|
Show the value as of the last day of the report period (2000\-02\-29):
|
|
.IP
|
|
.EX
|
|
$ hledger \-f\- print \-\-value=end date:2000/01\-2000/03
|
|
2000\-01\-01
|
|
(a) 2 B
|
|
|
|
2000\-02\-01
|
|
(a) 2 B
|
|
.EE
|
|
.PP
|
|
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
|
|
2000\-01\-01
|
|
(a) 3 B
|
|
|
|
2000\-02\-01
|
|
(a) 3 B
|
|
|
|
2000\-03\-01
|
|
(a) 3 B
|
|
.EE
|
|
.PP
|
|
The value today is the same (the 2000\-04\-01 price is still in effect):
|
|
.IP
|
|
.EX
|
|
$ hledger \-f\- print \-\-value=now
|
|
2000\-01\-01
|
|
(a) 4 B
|
|
|
|
2000\-02\-01
|
|
(a) 4 B
|
|
|
|
2000\-03\-01
|
|
(a) 4 B
|
|
.EE
|
|
.PP
|
|
Show the value on 2000/01/15:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f\- print \-\-value=2000\-01\-15
|
|
2000\-01\-01
|
|
(a) 1 B
|
|
|
|
2000\-02\-01
|
|
(a) 1 B
|
|
|
|
2000\-03\-01
|
|
(a) 1 B
|
|
.EE
|
|
.SS Interaction of valuation and queries
|
|
When matching postings based on queries in the presence of valuation,
|
|
the following happens:
|
|
.IP "1." 3
|
|
The query is separated into two parts:
|
|
.RS 4
|
|
.IP "1." 3
|
|
the currency (\f[CR]cur:\f[R]) or amount (\f[CR]amt:\f[R]).
|
|
.IP "2." 3
|
|
all other parts.
|
|
.RE
|
|
.IP "2." 3
|
|
The postings are matched to the currency and amount queries based on
|
|
pre\-valued amounts.
|
|
.IP "3." 3
|
|
Valuation is applied to the postings.
|
|
.IP "4." 3
|
|
The postings are matched to the other parts of the query based on
|
|
post\-valued amounts.
|
|
.PP
|
|
Related: #1625
|
|
.SS Effect of valuation on reports
|
|
Here is a reference for how valuation is supposed to affect each part of
|
|
hledger\[aq]s reports.
|
|
It may be useful when troubleshooting.
|
|
If you find problems, please report them, ideally with a reproducible
|
|
example.
|
|
Related: #329, #1083.
|
|
.PP
|
|
First, a quick glossary:
|
|
.TP
|
|
\f[I]cost\f[R]
|
|
calculated using price(s) recorded in the transaction(s).
|
|
.TP
|
|
\f[I]value\f[R]
|
|
market value using available market price declarations, or the unchanged
|
|
amount if no conversion rate can be found.
|
|
.TP
|
|
\f[I]report start\f[R]
|
|
the first day of the report period specified with \-b or \-p or date:,
|
|
otherwise today.
|
|
.TP
|
|
\f[I]report or journal start\f[R]
|
|
the first day of the report period specified with \-b or \-p or date:,
|
|
otherwise the earliest transaction date in the journal, otherwise today.
|
|
.TP
|
|
\f[I]report end\f[R]
|
|
the last day of the report period specified with \-e or \-p or date:,
|
|
otherwise today.
|
|
.TP
|
|
\f[I]report or journal end\f[R]
|
|
the last day of the report period specified with \-e or \-p or date:,
|
|
otherwise the latest transaction date in the journal, otherwise today.
|
|
.TP
|
|
\f[I]report interval\f[R]
|
|
a flag (\-D/\-W/\-M/\-Q/\-Y) or period expression that activates the
|
|
report\[aq]s multi\-period mode (whether showing one or many
|
|
subperiods).
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(9.5n) lw(11.8n) lw(12.0n) lw(17.2n) lw(12.0n) lw(7.4n).
|
|
T{
|
|
Report type
|
|
T}@T{
|
|
\f[CR]\-B\f[R], \f[CR]\-\-cost\f[R]
|
|
T}@T{
|
|
\f[CR]\-V\f[R], \f[CR]\-X\f[R]
|
|
T}@T{
|
|
\f[CR]\-\-value=then\f[R]
|
|
T}@T{
|
|
\f[CR]\-\-value=end\f[R]
|
|
T}@T{
|
|
\f[CR]\-\-value=DATE\f[R], \f[CR]\-\-value=now\f[R]
|
|
T}
|
|
_
|
|
T{
|
|
\f[B]print\f[R]
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
posting amounts
|
|
T}@T{
|
|
cost
|
|
T}@T{
|
|
value at report end or today
|
|
T}@T{
|
|
value at posting date
|
|
T}@T{
|
|
value at report or journal end
|
|
T}@T{
|
|
value at DATE/today
|
|
T}
|
|
T{
|
|
balance assertions/assignments
|
|
T}@T{
|
|
unchanged
|
|
T}@T{
|
|
unchanged
|
|
T}@T{
|
|
unchanged
|
|
T}@T{
|
|
unchanged
|
|
T}@T{
|
|
unchanged
|
|
T}
|
|
T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[B]register\f[R]
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
starting balance (\-H)
|
|
T}@T{
|
|
cost
|
|
T}@T{
|
|
value at report or journal end
|
|
T}@T{
|
|
valued at day each historical posting was made
|
|
T}@T{
|
|
value at report or journal end
|
|
T}@T{
|
|
value at DATE/today
|
|
T}
|
|
T{
|
|
starting balance (\-H) with report interval
|
|
T}@T{
|
|
cost
|
|
T}@T{
|
|
value at day before report or journal start
|
|
T}@T{
|
|
valued at day each historical posting was made
|
|
T}@T{
|
|
value at day before report or journal start
|
|
T}@T{
|
|
value at DATE/today
|
|
T}
|
|
T{
|
|
posting amounts
|
|
T}@T{
|
|
cost
|
|
T}@T{
|
|
value at report or journal end
|
|
T}@T{
|
|
value at posting date
|
|
T}@T{
|
|
value at report or journal end
|
|
T}@T{
|
|
value at DATE/today
|
|
T}
|
|
T{
|
|
summary posting amounts with report interval
|
|
T}@T{
|
|
summarised cost
|
|
T}@T{
|
|
value at period ends
|
|
T}@T{
|
|
sum of postings in interval, valued at interval start
|
|
T}@T{
|
|
value at period ends
|
|
T}@T{
|
|
value at DATE/today
|
|
T}
|
|
T{
|
|
running total/average
|
|
T}@T{
|
|
sum/average of displayed values
|
|
T}@T{
|
|
sum/average of displayed values
|
|
T}@T{
|
|
sum/average of displayed values
|
|
T}@T{
|
|
sum/average of displayed values
|
|
T}@T{
|
|
sum/average of displayed values
|
|
T}
|
|
T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[B]balance (bs, bse, cf, is)\f[R]
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
balance changes
|
|
T}@T{
|
|
sums of costs
|
|
T}@T{
|
|
value at report end or today of sums of postings
|
|
T}@T{
|
|
value at posting date
|
|
T}@T{
|
|
value at report or journal end of sums of postings
|
|
T}@T{
|
|
value at DATE/today of sums of postings
|
|
T}
|
|
T{
|
|
budget amounts (\-\-budget)
|
|
T}@T{
|
|
like balance changes
|
|
T}@T{
|
|
like balance changes
|
|
T}@T{
|
|
like balance changes
|
|
T}@T{
|
|
like balances
|
|
T}@T{
|
|
like balance changes
|
|
T}
|
|
T{
|
|
grand total
|
|
T}@T{
|
|
sum of displayed values
|
|
T}@T{
|
|
sum of displayed values
|
|
T}@T{
|
|
sum of displayed valued
|
|
T}@T{
|
|
sum of displayed values
|
|
T}@T{
|
|
sum of displayed values
|
|
T}
|
|
T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[B]balance (bs, bse, cf, is) with report interval\f[R]
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
starting balances (\-H)
|
|
T}@T{
|
|
sums of costs of postings before report start
|
|
T}@T{
|
|
value at report start of sums of all postings before report start
|
|
T}@T{
|
|
sums of values of postings before report start at respective posting
|
|
dates
|
|
T}@T{
|
|
value at report start of sums of all postings before report start
|
|
T}@T{
|
|
sums of postings before report start
|
|
T}
|
|
T{
|
|
balance changes (bal, is, bs \-\-change, cf \-\-change)
|
|
T}@T{
|
|
sums of costs of postings in period
|
|
T}@T{
|
|
same as \-\-value=end
|
|
T}@T{
|
|
sums of values of postings in period at respective posting dates
|
|
T}@T{
|
|
balance change in each period, valued at period ends
|
|
T}@T{
|
|
value at DATE/today of sums of postings
|
|
T}
|
|
T{
|
|
end balances (bal \-H, is \-\-H, bs, cf)
|
|
T}@T{
|
|
sums of costs of postings from before report start to period end
|
|
T}@T{
|
|
same as \-\-value=end
|
|
T}@T{
|
|
sums of values of postings from before period start to period end at
|
|
respective posting dates
|
|
T}@T{
|
|
period end balances, valued at period ends
|
|
T}@T{
|
|
value at DATE/today of sums of postings
|
|
T}
|
|
T{
|
|
budget amounts (\-\-budget)
|
|
T}@T{
|
|
like balance changes/end balances
|
|
T}@T{
|
|
like balance changes/end balances
|
|
T}@T{
|
|
like balance changes/end balances
|
|
T}@T{
|
|
like balances
|
|
T}@T{
|
|
like balance changes/end balances
|
|
T}
|
|
T{
|
|
row totals, row averages (\-T, \-A)
|
|
T}@T{
|
|
sums, averages of displayed values
|
|
T}@T{
|
|
sums, averages of displayed values
|
|
T}@T{
|
|
sums, averages of displayed values
|
|
T}@T{
|
|
sums, averages of displayed values
|
|
T}@T{
|
|
sums, averages of displayed values
|
|
T}
|
|
T{
|
|
column totals
|
|
T}@T{
|
|
sums of displayed values
|
|
T}@T{
|
|
sums of displayed values
|
|
T}@T{
|
|
sums of displayed values
|
|
T}@T{
|
|
sums of displayed values
|
|
T}@T{
|
|
sums of displayed values
|
|
T}
|
|
T{
|
|
grand total, grand average
|
|
T}@T{
|
|
sum, average of column totals
|
|
T}@T{
|
|
sum, average of column totals
|
|
T}@T{
|
|
sum, average of column totals
|
|
T}@T{
|
|
sum, average of column totals
|
|
T}@T{
|
|
sum, average of column totals
|
|
T}
|
|
T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
.TE
|
|
.PP
|
|
\f[CR]\-\-cumulative\f[R] is omitted to save space, it works like
|
|
\f[CR]\-H\f[R] but with a zero starting balance.
|
|
.SH PART 4: COMMANDS
|
|
.PP
|
|
Here are hledger\[aq]s standard subcommands.
|
|
You can list these by running \f[CR]hledger\f[R].
|
|
If you have installed more add\-on commands, they also will be listed.
|
|
.PP
|
|
In the following command docs, each command\[aq]s specific options are
|
|
shown.
|
|
Most commands also support the general options described above, though
|
|
some of them might have no effect.
|
|
(Usually if there\[aq]s a sensible way for a general option to affect a
|
|
command, it will.)
|
|
You can list all of a command\[aq]s options by running
|
|
\f[CR]hledger CMD \-h\f[R].
|
|
.PP
|
|
\f[B]Help commands\f[R]
|
|
.IP \[bu] 2
|
|
commands \- show the hledger commands list (default)
|
|
.IP \[bu] 2
|
|
demo \- show small hledger demos in the terminal
|
|
.IP \[bu] 2
|
|
help \- show the hledger manual with info, man, or pager
|
|
.PP
|
|
\f[B]User interface commands\f[R]
|
|
.IP \[bu] 2
|
|
repl \- run commands from an interactive prompt
|
|
.IP \[bu] 2
|
|
run \- run commands from a script
|
|
.IP \[bu] 2
|
|
ui \- (if installed) run hledger\[aq]s terminal UI
|
|
.IP \[bu] 2
|
|
web \- (if installed) run hledger\[aq]s web UI
|
|
.PP
|
|
\f[B]Data entry commands\f[R]
|
|
.IP \[bu] 2
|
|
add \- add transactions using terminal prompts
|
|
.IP \[bu] 2
|
|
import \- add new transactions from other files, eg CSV files
|
|
.PP
|
|
\f[B]Basic report commands\f[R]
|
|
.IP \[bu] 2
|
|
accounts \- show account names
|
|
.IP \[bu] 2
|
|
codes \- show transaction codes
|
|
.IP \[bu] 2
|
|
commodities \- show commodity/currency symbols
|
|
.IP \[bu] 2
|
|
descriptions \- show transaction descriptions
|
|
.IP \[bu] 2
|
|
files \- show input file paths
|
|
.IP \[bu] 2
|
|
notes \- show note parts of transaction descriptions
|
|
.IP \[bu] 2
|
|
payees \- show payee parts of transaction descriptions
|
|
.IP \[bu] 2
|
|
prices \- show market prices
|
|
.IP \[bu] 2
|
|
stats \- show journal statistics
|
|
.IP \[bu] 2
|
|
tags \- show tag names
|
|
.PP
|
|
\f[B]Standard report commands\f[R]
|
|
.IP \[bu] 2
|
|
print \- show transactions or export journal data
|
|
.IP \[bu] 2
|
|
aregister (areg) \- show transactions in a particular account
|
|
.IP \[bu] 2
|
|
register (reg) \- show postings in one or more accounts & running total
|
|
.IP \[bu] 2
|
|
balancesheet (bs) \- show assets, liabilities and net worth
|
|
.IP \[bu] 2
|
|
balancesheetequity (bse) \- show assets, liabilities and equity
|
|
.IP \[bu] 2
|
|
cashflow (cf) \- show changes in liquid assets
|
|
.IP \[bu] 2
|
|
incomestatement (is) \- show revenues and expenses
|
|
.PP
|
|
\f[B]Advanced report commands\f[R]
|
|
.IP \[bu] 2
|
|
balance (bal) \- show balance changes, end balances, budgets, gains..
|
|
.IP \[bu] 2
|
|
roi \- show return on investments
|
|
.PP
|
|
\f[B]Chart commands\f[R]
|
|
.IP \[bu] 2
|
|
activity \- show bar charts of posting counts per period
|
|
.PP
|
|
\f[B]Data generation commands\f[R]
|
|
.IP \[bu] 2
|
|
close \- generate balance\-zeroing/restoring transactions
|
|
.IP \[bu] 2
|
|
rewrite \- generate auto postings, like print \-\-auto
|
|
.PP
|
|
\f[B]Maintenance commands\f[R]
|
|
.IP \[bu] 2
|
|
check \- check for various kinds of error in the data
|
|
.IP \[bu] 2
|
|
diff \- compare account transactions in two journal files
|
|
.IP \[bu] 2
|
|
setup \- check and show the status of the hledger installation
|
|
.IP \[bu] 2
|
|
test \- run self tests
|
|
.PP
|
|
Next, these commands are described in detail.
|
|
.SH Help commands
|
|
.SS commands
|
|
Show the hledger commands list.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-builtin show only builtin commands, not addons
|
|
.EE
|
|
.SS demo
|
|
Play demos of hledger usage in the terminal, if asciinema is installed.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-s \-\-speed=SPEED playback speed (1 is original speed, .5 is half, 2
|
|
is double, etc (default: 2))
|
|
.EE
|
|
.PP
|
|
Run this command with no argument to list the demos.
|
|
To play a demo, write its number or a prefix or substring of its title.
|
|
Tips:
|
|
.PP
|
|
Make your terminal window large enough to see the demo clearly.
|
|
.PP
|
|
Use the \-s/\-\-speed SPEED option to set your preferred playback speed,
|
|
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
|
|
During playback, several keys are available: SPACE to pause/unpause, .
|
|
to step forward (while paused), CTRL\-c quit.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
$ hledger demo # list available demos
|
|
$ hledger demo 1 # play the first demo at default speed (2x)
|
|
$ hledger demo install \-s4 # play the \[dq]install\[dq] demo at 4x speed
|
|
.EE
|
|
.PP
|
|
This command is experimental: there aren\[aq]t many useful demos yet.
|
|
.SS help
|
|
Show the hledger user manual with \f[CR]info\f[R], \f[CR]man\f[R], or a
|
|
pager.
|
|
With a (case insensitive) TOPIC argument, try to open it at that section
|
|
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)
|
|
.EE
|
|
.PP
|
|
This command shows the hledger manual built in to your hledger
|
|
executable.
|
|
It can be useful when offline, or when you prefer the terminal to a web
|
|
browser, or when the appropriate hledger manual or viewers are not
|
|
installed properly on your system.
|
|
.PP
|
|
By default it chooses the best viewer found in $PATH, trying in this
|
|
order: \f[CR]info\f[R], \f[CR]man\f[R], \f[CR]$PAGER\f[R],
|
|
\f[CR]less\f[R], \f[CR]more\f[R], stdout.
|
|
(If a TOPIC is specified, \f[CR]$PAGER\f[R] and \f[CR]more\f[R] are not
|
|
tried.)
|
|
You can force the use of info, man, or a pager with the \f[CR]\-i\f[R],
|
|
\f[CR]\-m\f[R], or \f[CR]\-p\f[R] flags.
|
|
If no viewer can be found, or if running non\-interactively, it just
|
|
prints the manual to stdout.
|
|
.PP
|
|
When using \f[CR]info\f[R], TOPIC can match either the full heading or a
|
|
prefix.
|
|
If your \f[CR]info \-\-version\f[R] is < 6, you\[aq]ll need to upgrade
|
|
it, eg with \[aq]\f[CR]brew install texinfo\f[R]\[aq] on mac.
|
|
.PP
|
|
When using \f[CR]man\f[R] or \f[CR]less\f[R], TOPIC must match the full
|
|
heading.
|
|
For a prefix match, you can write \[aq]\f[CR]TOPIC.*\f[R]\[aq].
|
|
.PP
|
|
Examples
|
|
.IP
|
|
.EX
|
|
$ hledger help \-h # show the help command\[aq]s usage
|
|
$ hledger help # show the manual with info, man or $PAGER
|
|
$ hledger help \[aq]time periods\[aq] # show the manual\[aq]s \[dq]Time periods\[dq] topic
|
|
$ hledger help \[aq]time periods\[aq] \-m # use man, even if info is installed
|
|
.EE
|
|
.SH User interface commands
|
|
.SS repl
|
|
Start an interactive prompt, where you can run any of hledger\[aq]s
|
|
commands.
|
|
Data files are parsed just once, so the commands run faster.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.PP
|
|
This command is experimental and could change in the future.
|
|
.PP
|
|
\f[CR]hledger repl\f[R] starts a read\-eval\-print loop (REPL) where you
|
|
can enter commands interactively.
|
|
As with the \f[CR]run\f[R] command, each input file (or each input
|
|
file/input options combination) is parsed just once, so commands will
|
|
run more quickly than if you ran them individually at the command line.
|
|
.PP
|
|
Also like \f[CR]run\f[R], the input file(s) specified for the
|
|
\f[CR]repl\f[R] command will be the default input for all interactive
|
|
commands.
|
|
You can override this temporarily by specifying an \f[CR]\-f\f[R] option
|
|
in particular commands.
|
|
But note that commands will not see any changes made to input files (eg
|
|
by \f[CR]add\f[R]) until you exit and restart the REPL.
|
|
.PP
|
|
The command syntax is the same as with \f[CR]run\f[R]:
|
|
.IP \[bu] 2
|
|
enter one hledger command at a time, without the usual
|
|
\f[CR]hledger\f[R] first word
|
|
.IP \[bu] 2
|
|
empty lines and comment text from \f[CR]#\f[R] to end of line are
|
|
ignored
|
|
.IP \[bu] 2
|
|
use single or double quotes to quote arguments when needed
|
|
.IP \[bu] 2
|
|
type \f[CR]exit\f[R] or \f[CR]quit\f[R] or control\-D to exit the REPL.
|
|
.PP
|
|
While it is running, the REPL remembers your command history, and you
|
|
can navigate in the usual ways:
|
|
.IP \[bu] 2
|
|
Keypad or Emacs navigation keys to edit the current command line
|
|
.IP \[bu] 2
|
|
UP/DOWN or control\-P/control\-N to step back/forward through history
|
|
.IP \[bu] 2
|
|
control\-R to search for a past command
|
|
.IP \[bu] 2
|
|
TAB to complete file paths.
|
|
.PP
|
|
Generally \f[CR]repl\f[R] command lines should feel much like the normal
|
|
hledger CLI, but you may find differences.
|
|
\f[CR]repl\f[R] is a little stricter; eg it requires full command names
|
|
or official abbreviations (as seen in the commands list).
|
|
.PP
|
|
The \f[CR]commands\f[R] and \f[CR]help\f[R] commands, and the command
|
|
help flags (\f[CR]CMD \-\-tldr\f[R], \f[CR]CMD \-h/\-\-help\f[R],
|
|
\f[CR]CMD \-\-info\f[R], \f[CR]CMD \-\-man\f[R]), can be useful.
|
|
.PP
|
|
You can type control\-C to cancel a long\-running command (but only
|
|
once; typing it a second time will exit the REPL).
|
|
.PP
|
|
And in most shells you can type control\-Z to temporarily exit to the
|
|
shell (and then \f[CR]fg\f[R] to return to the REPL).
|
|
.SS Examples
|
|
Start the REPL and enter some commands:
|
|
.IP
|
|
.EX
|
|
$ hledger repl
|
|
Enter hledger commands. To exit, enter \[aq]quit\[aq] or \[aq]exit\[aq], or send EOF.
|
|
% stats
|
|
Main file : .../2025.journal
|
|
\&...
|
|
% stats \-f 2024/2024.journal
|
|
Main file : .../2024.journal
|
|
\&...
|
|
% stats
|
|
Main file : .../2025.journal
|
|
\&...
|
|
.EE
|
|
.PP
|
|
or:
|
|
.IP
|
|
.EX
|
|
$ hledger repl \-f some.journal
|
|
Enter hledger commands. To exit, enter \[aq]quit\[aq] or \[aq]exit\[aq], or send EOF.
|
|
% bs
|
|
\&...
|
|
% print \-b \[aq]last week\[aq]
|
|
\&...
|
|
% bs \-f other.journal
|
|
\&...
|
|
.EE
|
|
.SS run
|
|
Run a sequence of hledger commands, provided as files or command line
|
|
arguments.
|
|
Data files are parsed just once, so the commands run faster.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.PP
|
|
This command is experimental and could change in the future.
|
|
.PP
|
|
You can use \f[CR]run\f[R] in three ways:
|
|
.IP \[bu] 2
|
|
\f[CR]hledger run \-\- CMD1 \-\- CMD2 \-\- CMD3\f[R] \- read commands
|
|
from the command line, separated by \f[CR]\-\-\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]hledger run SCRIPTFILE1 SCRIPTFILE2\f[R] \- read commands from one
|
|
or more files
|
|
.IP \[bu] 2
|
|
\f[CR]cat SCRIPTFILE1 | hledger run\f[R] \- read commands from standard
|
|
input.
|
|
.PP
|
|
\f[CR]run\f[R] first loads the input file(s) specified by
|
|
\f[CR]LEDGER_FILE\f[R] or by \f[CR]\-f\f[R] options, in the usual way.
|
|
Then it runs each command in turn, each using the same input data.
|
|
But if you want a particular command to use different input, you can
|
|
specify an \f[CR]\-f\f[R] option within that command.
|
|
This will override (not add to) the default input, just for that
|
|
command.
|
|
.PP
|
|
Each input file (more precisely, each combination of input file and
|
|
input options) is parsed only once.
|
|
This means that commands will not see any changes made to these files,
|
|
until the next run.
|
|
But the commands will run more quickly than if run individually
|
|
(typically about twice as fast).
|
|
.PP
|
|
Command scripts, whether in a file or written on the command line, have
|
|
a simple syntax:
|
|
.IP \[bu] 2
|
|
each line may contain a single hledger command and its arguments,
|
|
without the usual \f[CR]hledger\f[R] first word
|
|
.IP \[bu] 2
|
|
empty lines are ignored
|
|
.IP \[bu] 2
|
|
text from \f[CR]#\f[R] to end of line is a comment, and ignored
|
|
.IP \[bu] 2
|
|
you can use single or double quotes to quote arguments when needed, as
|
|
on the command line
|
|
.IP \[bu] 2
|
|
these extra commands are available: \f[CR]echo TEXT\f[R] prints some
|
|
text, and \f[CR]exit\f[R] or \f[CR]quit\f[R] ends the run.
|
|
.PP
|
|
On unix systems you can use \f[CR]#!/usr/bin/env hledger run\f[R] in the
|
|
first line of a command file to make it a runnable script.
|
|
If that gives an error, use \f[CR]#!/usr/bin/env \-S hledger run\f[R].
|
|
.PP
|
|
It\[aq]s ok to use the \f[CR]run\f[R] command recursively within a
|
|
command script.
|
|
.PP
|
|
You may find some differences in behaviour between \f[CR]run\f[R]
|
|
command lines and normal hledger command lines.
|
|
\f[CR]run\f[R] is a little stricter; eg it requires full command names
|
|
or official abbreviations (as seen in the commands list), and command
|
|
options must be written after the command name.
|
|
.SS Examples
|
|
Run commands from the command line:
|
|
.IP
|
|
.EX
|
|
hledger \-f some.journal run \-\- balance assets \-\-depth 2 \-\- balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose \-\- stats
|
|
.EE
|
|
.PP
|
|
This would load \f[CR]some.journal\f[R], run
|
|
\f[CR]balance assets \-\-depth 2\f[R] on it, then run
|
|
\f[CR]balance liabilities \-\-depth 3 \-\-transpose\f[R] on
|
|
\f[CR]/some/other.journal\f[R], and finally run \f[CR]stats\f[R] on
|
|
\f[CR]some.journal\f[R]
|
|
.PP
|
|
Run commands from standard input:
|
|
.IP
|
|
.EX
|
|
(echo \[dq]files\[dq]; echo \[dq]stats\[dq]) | hledger \-f some.journal run
|
|
.EE
|
|
.PP
|
|
Run commands as a script:
|
|
.IP
|
|
.EX
|
|
$ cat report
|
|
#!/usr/bin/env \-S hledger run \-f some.journal
|
|
|
|
echo \[dq]List of accounts in some.journal\[dq]
|
|
accounts
|
|
|
|
echo \[dq]Assets of some.journal\[dq]
|
|
balance assets \-\-depth 2
|
|
|
|
echo \[dq]Liabilities from /some/other.journal\[dq]
|
|
balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose
|
|
|
|
echo \[dq]Commands from another.script, applied to another.journal\[dq]
|
|
run \-f another.journal another.script
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ chmod +x report
|
|
$ ./report
|
|
List of accounts in some.journal
|
|
\&...
|
|
.EE
|
|
.SS ui
|
|
Runs hledger\-ui (if installed).
|
|
.SS web
|
|
Runs hledger\-web (if installed).
|
|
.SH Data entry commands
|
|
.SS add
|
|
Add new transactions to a journal file, with interactive prompting.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-no\-new\-accounts don\[aq]t allow creating new accounts
|
|
.EE
|
|
.PP
|
|
Many hledger users edit their journals directly with a text editor, or
|
|
generate them from CSV.
|
|
For more interactive data entry, there is the \f[CR]add\f[R] command,
|
|
which prompts interactively on the console for new transactions, and
|
|
appends them to the main journal file (which should be in journal
|
|
format).
|
|
Existing transactions are not changed.
|
|
This is one of the few hledger commands that writes to the journal file
|
|
(see also \f[CR]import\f[R]).
|
|
.PP
|
|
To use it, just run \f[CR]hledger add\f[R] and follow the prompts.
|
|
You can add as many transactions as you like; when you are finished,
|
|
enter \f[CR].\f[R] or press control\-d or control\-c to exit.
|
|
.PP
|
|
Features:
|
|
.IP \[bu] 2
|
|
add tries to provide useful defaults, using the most similar (by
|
|
description) recent transaction (filtered by the query, if any) as a
|
|
template.
|
|
.IP \[bu] 2
|
|
You can also set the initial defaults with command line arguments.
|
|
.IP \[bu] 2
|
|
Readline\-style edit keys can be used during data entry.
|
|
.IP \[bu] 2
|
|
The tab key will auto\-complete whenever possible \- accounts,
|
|
payees/descriptions, dates (\f[CR]yesterday\f[R], \f[CR]today\f[R],
|
|
\f[CR]tomorrow\f[R]).
|
|
If the input area is empty, it will insert the default value.
|
|
.IP \[bu] 2
|
|
A parenthesised transaction code may be entered following a date.
|
|
.IP \[bu] 2
|
|
Comments and tags may be entered following a description or amount.
|
|
.IP \[bu] 2
|
|
If you make a mistake, enter \f[CR]<\f[R] at any prompt to go one step
|
|
backward.
|
|
.IP \[bu] 2
|
|
Input prompts are displayed in a different colour when the terminal
|
|
supports it.
|
|
.PP
|
|
Notes:
|
|
.IP \[bu] 2
|
|
If you enter a number with no commodity symbol, and you have declared a
|
|
default commodity with a \f[CR]D\f[R] directive, you might expect
|
|
\f[CR]add\f[R] to add this symbol for you.
|
|
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
|
|
Record new transactions, saving to the default journal file:
|
|
.RS 2
|
|
.PP
|
|
\f[CR]hledger add\f[R]
|
|
.RE
|
|
.IP \[bu] 2
|
|
Add transactions to 2024.journal, but also load 2023.journal for
|
|
completions:
|
|
.RS 2
|
|
.PP
|
|
\f[CR]hledger add \-\-file 2024.journal \-\-file 2023.journal\f[R]
|
|
.RE
|
|
.IP \[bu] 2
|
|
Provide answers for the first four prompts:
|
|
.RS 2
|
|
.PP
|
|
\f[CR]hledger add today \[aq]best buy\[aq] expenses:supplies \[aq]$20\[aq]\f[R]
|
|
.RE
|
|
.PP
|
|
There is a detailed tutorial at https://hledger.org/add.html.
|
|
.SS add and balance assertions
|
|
Since hledger 1.43, whenever you enter a posting amount, \f[CR]add\f[R]
|
|
will re\-check all balance assertions in the journal, and if any of them
|
|
fail, it will report the problem and ask for the amount again.
|
|
.PP
|
|
You can also add a new balance assertion, following the amount as in
|
|
journal format.
|
|
.PP
|
|
The new transaction\[aq]s date, and the new posting\[aq]s posting date
|
|
if any (entered in a comment following the amount), will influence
|
|
assertion checking.
|
|
.PP
|
|
You can use \f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R] to disable
|
|
assertion checking temporarily.
|
|
.SS add and balance assignments
|
|
Balance assignments are not recalculated during a \f[CR]hledger add\f[R]
|
|
session.
|
|
When \f[CR]add\f[R] runs, it sees the journal with all balance
|
|
assignments already processed and converted to assertions.
|
|
So if you add a new posting which is dated earlier than a balance
|
|
assignment, it will break the assertion and be rejected.
|
|
You can make it work by using \f[CR]hledger add \-I\f[R].
|
|
.SS import
|
|
Import new transactions from one or more data files to the main journal.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-catchup just mark all transactions as already imported
|
|
\-\-dry\-run just show the transactions to be imported
|
|
.EE
|
|
.PP
|
|
This command detects new transactions in one or more data files
|
|
specified as arguments, and appends them to the main journal.
|
|
.PP
|
|
You can import from any input file format hledger supports, but
|
|
CSV/SSV/TSV files, downloaded from financial institutions, are the most
|
|
common import source.
|
|
.PP
|
|
The import destination is the default journal file, or another specified
|
|
in the usual way with \f[CR]$LEDGER_FILE\f[R] or
|
|
\f[CR]\-f/\-\-file\f[R].
|
|
It should be in journal format.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
$ hledger import bank1\-checking.csv bank1\-savings.csv
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger import *.csv
|
|
.EE
|
|
.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
|
|
from CSV.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
$ hledger import bank.csv \-\-dry\-run
|
|
.EE
|
|
.PP
|
|
The dry run output is valid journal format, so hledger can re\-parse it.
|
|
If the output is large, you could show just the uncategorised
|
|
transactions like so:
|
|
.IP
|
|
.EX
|
|
$ hledger import \-\-dry\-run bank.csv | hledger \-f\- \-I print unknown
|
|
.EE
|
|
.PP
|
|
You could also run this repeatedly to see the effect of edits to your
|
|
conversion rules:
|
|
.IP
|
|
.EX
|
|
$ 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
|
|
journal, perhaps with some manual fixups to follow, you would do the
|
|
actual import:
|
|
.IP
|
|
.EX
|
|
$ hledger import bank.csv
|
|
.EE
|
|
.SS Overlap detection
|
|
Reading CSV files is built in to hledger, and not specific to
|
|
\f[CR]import\f[R]; so you could also import by doing
|
|
\f[CR]hledger \-f bank.csv print >>$LEDGER_FILE\f[R].
|
|
.PP
|
|
But \f[CR]import\f[R] is easier and provides some advantages.
|
|
The main one is that it avoids re\-importing transactions it has seen on
|
|
previous runs.
|
|
This means you don\[aq]t have to worry about overlapping data in
|
|
successive downloads of your bank CSV; just download and
|
|
\f[CR]import\f[R] as often as you like, and only the new transactions
|
|
will be imported each time.
|
|
.PP
|
|
We don\[aq]t call this \[dq]deduplication\[dq], as it\[aq]s generally
|
|
not possible to reliably detect duplicates in bank CSV.
|
|
Instead, \f[CR]import\f[R] remembers the latest date processed
|
|
previously in each CSV file (saving it in a hidden file), and skips any
|
|
records prior to that date.
|
|
This works well for most real\-world CSV, where:
|
|
.IP "1." 3
|
|
the data file name is stable (does not change) across imports
|
|
.IP "2." 3
|
|
the item dates are stable across imports
|
|
.IP "3." 3
|
|
the order of same\-date items is stable across imports
|
|
.IP "4." 3
|
|
the newest items have the newest dates
|
|
.PP
|
|
(Occasional violations of 2\-4 are often harmless; you can reduce the
|
|
chance of disruption by downloading and importing more often.)
|
|
.PP
|
|
Overlap detection is automatic, and shouldn\[aq]t require much attention
|
|
from you, except perhaps at first import (see below).
|
|
But here\[aq]s how it works:
|
|
.IP \[bu] 2
|
|
For each \f[CR]FILE\f[R] being imported from:
|
|
.RS 2
|
|
.IP "1." 3
|
|
hledger reads a file named \f[CR].latest.FILE\f[R] file in the same
|
|
directory, if any.
|
|
This file contains the latest record date previously imported from FILE,
|
|
in YYYY\-MM\-DD format.
|
|
If multiple records with that date were imported, the date is repeated
|
|
on N lines.
|
|
.IP "2." 3
|
|
hledger reads records from FILE.
|
|
If a latest date was found in step 1, any records before that date, and
|
|
the first N records on that date, are skipped.
|
|
.RE
|
|
.IP \[bu] 2
|
|
After a successful import from all FILEs, without error and without
|
|
\f[CR]\-\-dry\-run\f[R], hledger updates each FILE\[aq]s
|
|
\f[CR].latest.FILE\f[R] for next time.
|
|
.PP
|
|
If this goes wrong, it\[aq]s relatively easy to repair:
|
|
.IP \[bu] 2
|
|
You\[aq]ll notice it before import when you preview with
|
|
\f[CR]import \-\-dry\-run\f[R].
|
|
.IP \[bu] 2
|
|
Or after import when you try to reconcile your hledger account balances
|
|
with your bank.
|
|
.IP \[bu] 2
|
|
\f[CR]hledger print \-f FILE.csv\f[R] will show all recently downloaded
|
|
transactions.
|
|
Compare these with your journal.
|
|
Copy/paste if needed.
|
|
.IP \[bu] 2
|
|
Update your conversion rules and print again, if needed.
|
|
.IP \[bu] 2
|
|
You can manually update or remove the .latest file, or use
|
|
\f[CR]import \-\-catchup FILE\f[R].
|
|
.IP \[bu] 2
|
|
Download and import more often, eg twice a week, at least while you are
|
|
learning.
|
|
It\[aq]s easier to review and troubleshoot when there are fewer
|
|
transactions.
|
|
.SS First import
|
|
The first time you import from a file, when no corresponding .latest
|
|
file has been created yet, all of the records will be imported.
|
|
.PP
|
|
But perhaps you have been entering the data manually, so you know that
|
|
all of these transactions are already recorded in the journal.
|
|
In this case you can run \f[CR]hledger import \-\-catchup\f[R] once.
|
|
This will create a .latest file containing the latest CSV record date,
|
|
so that none of those records will be re\-imported.
|
|
.PP
|
|
Or, if you know that some but not all of the transactions are in the
|
|
journal, you can create the .latest file yourself.
|
|
Eg, let\[aq]s say you previously recorded foobank transactions up to
|
|
2024\-10\-31 in the journal.
|
|
Then in the directory where you\[aq]ll be saving \f[CR]foobank.csv\f[R],
|
|
you would create a \f[CR].latest.foobank.csv\f[R] file containing
|
|
.IP
|
|
.EX
|
|
2024\-10\-31
|
|
.EE
|
|
.PP
|
|
Or if you had three foobank transactions recorded with that date, you
|
|
would repeat the date that many times:
|
|
.IP
|
|
.EX
|
|
2024\-10\-31
|
|
2024\-10\-31
|
|
2024\-10\-31
|
|
.EE
|
|
.PP
|
|
Then \f[CR]hledger import foobank.csv [\-\-dry\-run]\f[R] will import
|
|
only the newer records.
|
|
.SS Importing balance assignments
|
|
Journal entries added by import will have all posting amounts made
|
|
explicit (like \f[CR]print \-x\f[R]).
|
|
.PP
|
|
This means that any balance assignments in the imported entries would
|
|
need to be evaluated.
|
|
But this generally isn\[aq]t possible, as the main file\[aq]s account
|
|
balances are not visible during import.
|
|
So try to avoid generating balance assignments with your CSV rules, or
|
|
importing from a journal that contains balance assignments.
|
|
(Balance assignments are best avoided anyway.)
|
|
.PP
|
|
But if you must use them, eg because your CSV includes only balances:
|
|
you can import with \f[CR]print\f[R], which leaves implicit amounts
|
|
implicit.
|
|
(\f[CR]print\f[R] can also do overlap detection like import, with the
|
|
\f[CR]\-\-new\f[R] flag):
|
|
.IP
|
|
.EX
|
|
$ hledger print \-\-new \-f bank.csv >> $LEDGER_FILE
|
|
.EE
|
|
.PP
|
|
(If you think \f[CR]import\f[R] should preserve implicit balances,
|
|
please test that and send a pull request.)
|
|
.SS Import and commodity styles
|
|
Amounts in entries added by import will be formatted according to the
|
|
journal\[aq]s canonical commodity styles, as declared by
|
|
\f[CR]commodity\f[R] directives or inferred from the journal\[aq]s
|
|
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
|
|
.SS Deduplication
|
|
Here are two kinds of \[dq]deduplication\[dq] which \f[CR]import\f[R]
|
|
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.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-u \-\-used list accounts used
|
|
\-d \-\-declared list accounts declared
|
|
\-\-undeclared list accounts used but not declared
|
|
\-\-unused list accounts declared but not used
|
|
\-\-find list the first account matched by the first
|
|
argument (a case\-insensitive infix regexp)
|
|
\-\-directives show as account directives, for use in journals
|
|
\-\-locations also show where accounts were declared
|
|
\-\-types also show account types when known
|
|
\-l \-\-flat list/tree mode: show accounts as a flat list
|
|
(default)
|
|
\-t \-\-tree list/tree mode: show accounts as a tree
|
|
\-\-drop=N flat mode: omit N leading account name parts
|
|
.EE
|
|
.PP
|
|
This command lists account names \- all of them by default, or just the
|
|
ones which have been used in transactions (\f[CR]\-u/\-\-used\f[R]), or
|
|
declared with \f[CR]account\f[R] directives
|
|
(\f[CR]\-d/\-\-declared\f[R]), or used but not declared
|
|
(\f[CR]\-\-undeclared\f[R]), or declared but not used
|
|
(\f[CR]\-\-unused\f[R]), or just the first one matched by a pattern
|
|
(\f[CR]\-\-find\f[R], returning a non\-zero exit code if it fails).
|
|
.PP
|
|
You can add query arguments to select a subset of transactions or
|
|
accounts.
|
|
.PP
|
|
With \f[CR]\-\-directives\f[R], it shows valid account directives which
|
|
could be pasted into a journal file.
|
|
This is useful together with \f[CR]\-\-undeclared\f[R] when updating
|
|
your account declarations to satisfy \f[CR]hledger check accounts\f[R].
|
|
.PP
|
|
With \f[CR]\-\-locations\f[R], it also shows the file and line number of
|
|
each account\[aq]s declaration, if any, and the account\[aq]s overall
|
|
declaration order; these may be useful when troubleshooting account
|
|
display order.
|
|
.PP
|
|
With \f[CR]\-\-types\f[R], it also shows each account\[aq]s type, if
|
|
it\[aq]s known.
|
|
(See Declaring accounts > Account types.)
|
|
.PP
|
|
It shows a flat list by default.
|
|
With \f[CR]\-\-tree\f[R], it uses indentation to show the account
|
|
hierarchy.
|
|
In flat mode you can add \f[CR]\-\-drop N\f[R] to omit the first few
|
|
account name components.
|
|
Account names can be depth\-clipped with \f[CR]depth:N\f[R] or
|
|
\f[CR]\-\-depth N\f[R] or \f[CR]\-N\f[R].
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
$ hledger accounts
|
|
assets:bank:checking
|
|
assets:bank:saving
|
|
assets:cash
|
|
expenses:food
|
|
expenses:supplies
|
|
income:gifts
|
|
income:salary
|
|
liabilities:debts
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger accounts \-\-undeclared \-\-directives >> $LEDGER_FILE
|
|
$ hledger check accounts
|
|
.EE
|
|
.SS codes
|
|
List the codes seen in transactions, in the order parsed.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.PP
|
|
This command prints the value of each transaction\[aq]s code field, in
|
|
the order transactions were parsed.
|
|
The transaction code is an optional value written in parentheses between
|
|
the date and description, often used to store a cheque number, order
|
|
number or similar.
|
|
.PP
|
|
Transactions aren\[aq]t required to have a code, and missing or empty
|
|
codes will not be shown by default.
|
|
With the \f[CR]\-E\f[R]/\f[CR]\-\-empty\f[R] flag, they will be printed
|
|
as blank lines.
|
|
.PP
|
|
You can add a query to select a subset of transactions.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
2022/1/1 (123) Supermarket
|
|
Food $5.00
|
|
Checking
|
|
|
|
2022/1/2 (124) Post Office
|
|
Postage $8.32
|
|
Checking
|
|
|
|
2022/1/3 Supermarket
|
|
Food $11.23
|
|
Checking
|
|
|
|
2022/1/4 (126) Post Office
|
|
Postage $3.21
|
|
Checking
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger codes
|
|
123
|
|
124
|
|
126
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger codes \-E
|
|
123
|
|
124
|
|
|
|
126
|
|
.EE
|
|
.SS commodities
|
|
List the commodity symbols used or declared in the journal.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-used list commodities used
|
|
\-\-declared list commodities declared
|
|
\-\-undeclared list commodities used but not declared
|
|
\-\-unused list commodities declared but not used
|
|
\-\-find list the first commodity matched by the first
|
|
argument (a case\-insensitive infix regexp)
|
|
.EE
|
|
.PP
|
|
This command lists commodity symbols/names \- all of them by default, or
|
|
just the ones which have been used in transactions or \f[CR]P\f[R]
|
|
directives, or declared with \f[CR]commodity\f[R] directives, or used
|
|
but not declared, or declared but not used, or just the first one
|
|
matched by a pattern (with \f[CR]\-\-find\f[R], returning a non\-zero
|
|
exit code if it fails).
|
|
.PP
|
|
You can add \f[CR]cur:\f[R] query arguments to further limit the
|
|
commodities.
|
|
.SS descriptions
|
|
List the unique descriptions used in transactions.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.PP
|
|
This command lists the unique descriptions that appear in transactions,
|
|
in alphabetic order.
|
|
You can add a query to select a subset of transactions.
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
$ hledger descriptions
|
|
Store Name
|
|
Gas Station | Petrol
|
|
Person A
|
|
.EE
|
|
.SS files
|
|
List all files included in the journal.
|
|
With a REGEX argument, only file names matching the regular expression
|
|
(case sensitive) are shown.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.SS notes
|
|
List the unique notes that appear in transactions.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.PP
|
|
This command lists the unique notes that appear in transactions, in
|
|
alphabetic order.
|
|
You can add a query to select a subset of transactions.
|
|
The note is the part of the transaction description after a | character
|
|
(or if there is no |, the whole description).
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
$ hledger notes
|
|
Petrol
|
|
Snacks
|
|
.EE
|
|
.SS payees
|
|
List the payee/payer names used or declared in the journal.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-used list payees used
|
|
\-\-declared list payees declared
|
|
\-\-undeclared list payees used but not declared
|
|
\-\-unused list payees declared but not used
|
|
\-\-find list the first payee matched by the first
|
|
argument (a case\-insensitive infix regexp)
|
|
.EE
|
|
.PP
|
|
This command lists unique payee/payer names \- all of them by default,
|
|
or just the ones which have been used in transaction descriptions, or
|
|
declared with \f[CR]payee\f[R] directives, or used but not declared, or
|
|
declared but not used, or just the first one matched by a pattern (with
|
|
\f[CR]\-\-find\f[R], returning a non\-zero exit code if it fails).
|
|
.PP
|
|
The payee/payer name is the part of the transaction description before a
|
|
| character (or if there is no |, the whole description).
|
|
.PP
|
|
You can add query arguments to select a subset of transactions or
|
|
payees.
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
$ hledger payees
|
|
Store Name
|
|
Gas Station
|
|
Person A
|
|
.EE
|
|
.SS prices
|
|
Print the market prices declared with P directives.
|
|
With \-\-infer\-market\-prices, also show any additional prices inferred
|
|
from costs.
|
|
With \-\-show\-reverse, also show additional prices inferred by
|
|
reversing known prices.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-show\-reverse also show the prices inferred by reversing known
|
|
prices
|
|
.EE
|
|
.PP
|
|
Price amounts are always displayed with their full precision, except for
|
|
reverse prices which are limited to 8 decimal digits.
|
|
.PP
|
|
Prices can be filtered by a date:, cur: or amt: query.
|
|
.PP
|
|
Generally if you run this command with \-\-infer\-market\-prices
|
|
\-\-show\-reverse, it will show the same prices used internally to
|
|
calculate value reports.
|
|
But if in doubt, you can inspect those directly by running the value
|
|
report with \-\-debug=2.
|
|
.SS stats
|
|
Show journal and performance statistics.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-v \-\-verbose show more detailed output
|
|
\-o \-\-output\-file=FILE write output to FILE.
|
|
.EE
|
|
.PP
|
|
The stats command shows summary information for the whole journal, or a
|
|
matched part of it.
|
|
With a reporting interval, it shows a report for each report period.
|
|
.PP
|
|
The default output is fairly impersonal, though it reveals the main file
|
|
name.
|
|
With \f[CR]\-v/\-\-verbose\f[R], more details are shown, like file
|
|
paths, included files, and commodity names.
|
|
.PP
|
|
It also shows some run time statistics:
|
|
.IP \[bu] 2
|
|
elapsed time
|
|
.IP \[bu] 2
|
|
throughput: the number of transactions processed per second
|
|
.IP \[bu] 2
|
|
live: the peak memory in use by the program to do its work
|
|
.IP \[bu] 2
|
|
alloc: the peak memory allocation from the OS as seen by GHC.
|
|
Measuring this externally, eg with GNU time, is more accurate; usually
|
|
that will be a larger number; sometimes (with swapping?)
|
|
smaller.
|
|
.PP
|
|
The \f[CR]stats\f[R] command\[aq]s run time is similar to that of a
|
|
balance report.
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
$ hledger stats \-f examples/1ktxns\-1kaccts.journal
|
|
Main file : .../1ktxns\-1kaccts.journal
|
|
Included files : 0
|
|
Txns span : 2000\-01\-01 to 2002\-09\-27 (1000 days)
|
|
Last txn : 2002\-09\-26 (7827 days ago)
|
|
Txns : 1000 (1.0 per day)
|
|
Txns last 30 days : 0 (0.0 per day)
|
|
Txns last 7 days : 0 (0.0 per day)
|
|
Payees/descriptions : 1000
|
|
Accounts : 1000 (depth 10)
|
|
Commodities : 26
|
|
Market prices : 1000
|
|
Runtime stats : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc
|
|
.EE
|
|
.PP
|
|
This command supports the \-o/\-\-output\-file option (but not
|
|
\-O/\-\-output\-format).
|
|
.SS tags
|
|
List the tag names used or declared in the journal, or their values.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-used list tags used
|
|
\-\-declared list tags declared
|
|
\-\-undeclared list tags used but not declared
|
|
\-\-unused list tags declared but not used
|
|
\-\-find list the first tag whose name is matched by the
|
|
first argument (a case\-insensitive infix regexp)
|
|
\-\-values list tag values instead of tag names
|
|
\-\-parsed show them in the order they were parsed (mostly),
|
|
including duplicates
|
|
.EE
|
|
.PP
|
|
This command lists tag names \- all of them by default, or just the ones
|
|
which have been used on transactions/postings/accounts, or declared with
|
|
\f[CR]tag\f[R] directives, or used but not declared, or declared but not
|
|
used, or just the first one matched by a pattern (with
|
|
\f[CR]\-\-find\f[R], returning a non\-zero exit code if it fails).
|
|
.PP
|
|
Note this command\[aq]s non\-standard first argument: it is a
|
|
case\-insensitive infix regular expression for matching tag names, which
|
|
limits the tags shown.
|
|
Any additional arguments are standard query arguments, which limit the
|
|
transactions, postings, or accounts providing tags.
|
|
.PP
|
|
With \f[CR]\-\-values\f[R], the tags\[aq] unique non\-empty values are
|
|
listed instead.
|
|
.PP
|
|
With \f[CR]\-E\f[R]/\f[CR]\-\-empty\f[R], blank/empty values are also
|
|
shown.
|
|
.PP
|
|
With \f[CR]\-\-parsed\f[R], tags or values are shown in the order they
|
|
were parsed, with duplicates included.
|
|
(Except, tags from account declarations are always shown first.)
|
|
.PP
|
|
Remember that accounts also acquire tags from their parents; postings
|
|
also acquire tags from their account and transaction; and transactions
|
|
also acquire tags from their postings.
|
|
.SH Standard report commands
|
|
.SS print
|
|
Show full journal entries, representing transactions.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-x \-\-explicit show all amounts explicitly
|
|
\-\-invert display all amounts with reversed sign
|
|
\-\-locations add tags showing file paths and line numbers
|
|
\-m \-\-match=DESC fuzzy search for one recent transaction with
|
|
description closest to DESC
|
|
\-\-new show only newer\-dated transactions added in each
|
|
file since last run
|
|
\-\-round=TYPE how much rounding or padding should be done when
|
|
displaying amounts ?
|
|
none \- show original decimal digits,
|
|
as in journal (default)
|
|
soft \- just add or remove decimal zeros
|
|
to match precision
|
|
hard \- round posting amounts to precision
|
|
(can unbalance transactions)
|
|
all \- also round cost amounts to precision
|
|
(can unbalance transactions)
|
|
\-\-base\-url=URLPREFIX in html output, generate links to hledger\-web,
|
|
with this prefix. (Usually the base url shown by
|
|
hledger\-web; can also be relative.)
|
|
\-O \-\-output\-format=FMT select the output format. Supported formats:
|
|
txt, beancount, csv, tsv, html, fods, json, sql.
|
|
\-o \-\-output\-file=FILE write output to FILE. A file extension matching
|
|
one of the above formats selects that format.
|
|
.EE
|
|
.PP
|
|
The print command displays full journal entries (transactions) from the
|
|
journal file, sorted by date (or with \f[CR]\-\-date2\f[R], by secondary
|
|
date).
|
|
.PP
|
|
Directives and inter\-transaction comments are not shown, currently.
|
|
This means the print command is somewhat lossy, and if you are using it
|
|
to reformat/regenerate your journal you should take care to also copy
|
|
over the directives and inter\-transaction comments.
|
|
.PP
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-f examples/sample.journal date:200806
|
|
2008/06/01 gift
|
|
assets:bank:checking $1
|
|
income:gifts $\-1
|
|
|
|
2008/06/02 save
|
|
assets:bank:saving $1
|
|
assets:bank:checking $\-1
|
|
|
|
2008/06/03 * eat & shop
|
|
expenses:food $1
|
|
expenses:supplies $1
|
|
assets:cash $\-2
|
|
.EE
|
|
.SS print amount explicitness
|
|
Normally, whether posting amounts are implicit or explicit is preserved.
|
|
For example, when an amount is omitted in the journal, it will not
|
|
appear in the output.
|
|
Similarly, if a conversion cost is implied but not written, it will not
|
|
appear in the output.
|
|
.PP
|
|
You can use the \f[CR]\-x\f[R]/\f[CR]\-\-explicit\f[R] flag to force
|
|
explicit display of all amounts and costs.
|
|
This can be useful for troubleshooting or for making your journal more
|
|
readable and robust against data entry errors.
|
|
\f[CR]\-x\f[R] is also implied by using any of
|
|
\f[CR]\-B\f[R],\f[CR]\-V\f[R],\f[CR]\-X\f[R],\f[CR]\-\-value\f[R].
|
|
.PP
|
|
The \f[CR]\-x\f[R]/\f[CR]\-\-explicit\f[R] flag will cause any postings
|
|
with a multi\-commodity amount (which can arise when a multi\-commodity
|
|
transaction has an implicit amount) to be split into multiple
|
|
single\-commodity postings, keeping the output parseable.
|
|
.SS print alignment
|
|
Amounts are shown right\-aligned within each transaction (but not
|
|
aligned across all transactions; you can achieve that with ledger\-mode
|
|
in Emacs).
|
|
.SS print amount style
|
|
Amounts will be displayed mostly in their commodity\[aq]s display style,
|
|
with standardised symbol placement, decimal mark, and digit group marks.
|
|
This does not apply to their decimal digits; \f[CR]print\f[R] normally
|
|
shows the same decimal digits that are recorded in each journal entry.
|
|
.PP
|
|
You can override the decimal precisions with \f[CR]print\f[R]\[aq]s
|
|
special \f[CR]\-\-round\f[R] option (\f[I]since 1.32\f[R]).
|
|
\f[CR]\-\-round\f[R] tries to show amounts with their commodities\[aq]
|
|
standard decimal precisions, increasingly strongly:
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-round=none\f[R] show amounts with original precisions
|
|
(default)
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-round=soft\f[R] add/remove decimal zeros in amounts (except
|
|
costs)
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-round=hard\f[R] round amounts (except costs), possibly hiding
|
|
significant digits
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-round=all\f[R] round all amounts and costs
|
|
.PP
|
|
\f[CR]soft\f[R] is good for non\-lossy cleanup, displaying more
|
|
consistent decimals where possible, without making entries unbalanced.
|
|
.PP
|
|
\f[CR]hard\f[R] or \f[CR]all\f[R] can be good for stronger cleanup, when
|
|
decimal rounding is wanted.
|
|
Note rounding can produce unbalanced journal entries, perhaps requiring
|
|
manual fixup.
|
|
.SS print parseability
|
|
Normally, print\[aq]s output is a valid hledger journal, which you can
|
|
\[dq]pipe\[dq] to a second hledger command for further processing.
|
|
This is sometimes convenient for achieving certain kinds of query
|
|
(though less needed now that queries have become more powerful):
|
|
.IP
|
|
.EX
|
|
# Show running total of food expenses paid from cash.
|
|
# \-f\- reads from stdin. \-I/\-\-ignore\-assertions is sometimes needed.
|
|
$ hledger print assets:cash | hledger \-f\- \-I reg expenses:food
|
|
.EE
|
|
.PP
|
|
But here are some things which can cause print\[aq]s output to become
|
|
unparseable:
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-round\f[R] (see above) can disrupt transaction balancing.
|
|
.IP \[bu] 2
|
|
Account aliases or pivoting can disrupt account names, balance
|
|
assertions, or balance assignments.
|
|
.IP \[bu] 2
|
|
Value reporting also can disrupt balance assertions or balance
|
|
assignments.
|
|
.IP \[bu] 2
|
|
Auto postings can generate too many amountless postings.
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-infer\-costs or \-\-infer\-equity\f[R] can generate
|
|
too\-complex redundant costs.
|
|
.SS print, other features
|
|
With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown
|
|
converted to cost.
|
|
.PP
|
|
With \f[CR]\-\-invert\f[R], posting amounts are shown with their sign
|
|
flipped.
|
|
It could be useful if you have accidentally recorded some transactions
|
|
with the wrong signs.
|
|
.PP
|
|
With \f[CR]\-\-new\f[R], print shows only transactions it has not seen
|
|
on a previous run.
|
|
This uses the same deduplication system as the \f[CR]import\f[R]
|
|
command.
|
|
(See import\[aq]s docs for details.)
|
|
.PP
|
|
With \f[CR]\-m DESC\f[R]/\f[CR]\-\-match=DESC\f[R], print shows one
|
|
recent transaction whose description is most similar to DESC.
|
|
DESC should contain at least two characters.
|
|
If there is no similar\-enough match, no transaction will be shown and
|
|
the program exit code will be non\-zero.
|
|
.PP
|
|
With \f[CR]\-\-locations\f[R], print adds the source file and line
|
|
number to every transaction, as a tag.
|
|
.SS print output format
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are \f[CR]txt\f[R],
|
|
\f[CR]beancount\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]csv\f[R],
|
|
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]json\f[R] and
|
|
\f[CR]sql\f[R].
|
|
.PP
|
|
The \f[CR]beancount\f[R] format tries to produce Beancount\-compatible
|
|
output, as follows:
|
|
.IP \[bu] 2
|
|
Transaction and postings with unmarked status are converted to cleared
|
|
(\f[CR]*\f[R]) status.
|
|
.IP \[bu] 2
|
|
Transactions\[aq] payee and note are backslash\-escaped and
|
|
double\-quote\-escaped and wrapped in double quotes.
|
|
.IP \[bu] 2
|
|
Transaction tags are copied to Beancount #tag format.
|
|
.IP \[bu] 2
|
|
Commodity symbols are converted to upper case, and a small number of
|
|
currency symbols like \f[CR]$\f[R] are converted to the corresponding
|
|
currency names.
|
|
.IP \[bu] 2
|
|
Account name parts are capitalised and unsupported characters are
|
|
replaced with \f[CR]\-\f[R].
|
|
If an account name part does not begin with a letter, or if the first
|
|
part is not Assets, Liabilities, Equity, Income, or Expenses, an error
|
|
is raised.
|
|
(Use \f[CR]\-\-alias\f[R] options to bring your accounts into
|
|
compliance.)
|
|
.IP \[bu] 2
|
|
An \f[CR]open\f[R] directive is generated for each account used, on the
|
|
earliest transaction date.
|
|
.PP
|
|
Some limitations:
|
|
.IP \[bu] 2
|
|
Balance assertions are removed.
|
|
.IP \[bu] 2
|
|
Balance assignments become missing amounts.
|
|
.IP \[bu] 2
|
|
Virtual and balanced virtual postings become regular postings.
|
|
.IP \[bu] 2
|
|
Directives are not converted.
|
|
.PP
|
|
Here\[aq]s an example of print\[aq]s CSV output:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-Ocsv
|
|
\[dq]txnidx\[dq],\[dq]date\[dq],\[dq]date2\[dq],\[dq]status\[dq],\[dq]code\[dq],\[dq]description\[dq],\[dq]comment\[dq],\[dq]account\[dq],\[dq]amount\[dq],\[dq]commodity\[dq],\[dq]credit\[dq],\[dq]debit\[dq],\[dq]posting\-status\[dq],\[dq]posting\-comment\[dq]
|
|
\[dq]1\[dq],\[dq]2008/01/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]income\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
\[dq]1\[dq],\[dq]2008/01/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]income\[dq],\[dq]\[dq],\[dq]income:salary\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
\[dq]2\[dq],\[dq]2008/06/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]gift\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
\[dq]2\[dq],\[dq]2008/06/01\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]gift\[dq],\[dq]\[dq],\[dq]income:gifts\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
\[dq]3\[dq],\[dq]2008/06/02\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]save\[dq],\[dq]\[dq],\[dq]assets:bank:saving\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
\[dq]3\[dq],\[dq]2008/06/02\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]save\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]expenses:food\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]expenses:supplies\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
\[dq]4\[dq],\[dq]2008/06/03\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]eat & shop\[dq],\[dq]\[dq],\[dq]assets:cash\[dq],\[dq]\-2\[dq],\[dq]$\[dq],\[dq]2\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
\[dq]5\[dq],\[dq]2008/12/31\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]pay off\[dq],\[dq]\[dq],\[dq]liabilities:debts\[dq],\[dq]1\[dq],\[dq]$\[dq],\[dq]\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
\[dq]5\[dq],\[dq]2008/12/31\[dq],\[dq]\[dq],\[dq]*\[dq],\[dq]\[dq],\[dq]pay off\[dq],\[dq]\[dq],\[dq]assets:bank:checking\[dq],\[dq]\-1\[dq],\[dq]$\[dq],\[dq]1\[dq],\[dq]\[dq],\[dq]\[dq],\[dq]\[dq]
|
|
.EE
|
|
.IP \[bu] 2
|
|
There is one CSV record per posting, with the parent transaction\[aq]s
|
|
fields repeated.
|
|
.IP \[bu] 2
|
|
The \[dq]txnidx\[dq] (transaction index) field shows which postings
|
|
belong to the same transaction.
|
|
(This number might change if transactions are reordered within the file,
|
|
files are parsed/included in a different order, etc.)
|
|
.IP \[bu] 2
|
|
The amount is separated into \[dq]commodity\[dq] (the symbol) and
|
|
\[dq]amount\[dq] (numeric quantity) fields.
|
|
.IP \[bu] 2
|
|
The numeric amount is repeated in either the \[dq]credit\[dq] or
|
|
\[dq]debit\[dq] column, for convenience.
|
|
(Those names are not accurate in the accounting sense; it just puts
|
|
negative amounts under credit and zero or greater amounts under debit.)
|
|
.SS aregister
|
|
(areg)
|
|
.PP
|
|
Show the transactions and running balances in one account, with each
|
|
transaction on one line.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-txn\-dates filter strictly by transaction date, not posting
|
|
date. Warning: this can show a wrong running
|
|
balance.
|
|
\-\-no\-elide don\[aq]t show only 2 commodities per amount
|
|
\-\-cumulative accumulation mode: show running total from report
|
|
start date
|
|
\-H \-\-historical accumulation mode: show historical running
|
|
total/balance (includes postings before report
|
|
start date) (default)
|
|
\-\-invert display all amounts with reversed sign
|
|
\-\-heading=YN show heading row above table: yes (default) or no
|
|
\-w \-\-width=N set output width (default: terminal width). \-wN,M
|
|
sets description width as well.
|
|
\-\-align\-all guarantee alignment across all lines (slower)
|
|
\-O \-\-output\-format=FMT select the output format. Supported formats:
|
|
txt, html, csv, tsv, json.
|
|
\-o \-\-output\-file=FILE write output to FILE. A file extension matching
|
|
one of the above formats selects that format.
|
|
.EE
|
|
.PP
|
|
\f[CR]aregister\f[R] shows the overall transactions affecting a
|
|
particular account (and any subaccounts).
|
|
Each report line represents one transaction in this account.
|
|
Transactions before the report start date are included in the running
|
|
balance (\f[CR]\-\-historical\f[R] mode is the default).
|
|
You can suppress this behaviour using the \f[CR]\-\-cumulative\f[R]
|
|
option.
|
|
.PP
|
|
This is a more \[dq]real world\[dq], bank\-like view than the
|
|
\f[CR]register\f[R] command (which shows individual postings, possibly
|
|
from multiple accounts, not necessarily in historical mode).
|
|
As a quick rule of thumb: \- use \f[CR]aregister\f[R] for reviewing and
|
|
reconciling real\-world asset/liability accounts \- use
|
|
\f[CR]register\f[R] for reviewing detailed revenues/expenses.
|
|
.PP
|
|
Note this command\[aq]s non\-standard, and required, first argument; it
|
|
specifies the account whose register will be shown.
|
|
You can write the account\[aq]s name, or (to save typing) a
|
|
case\-insensitive infix regular expression matching the name, which
|
|
selects the alphabetically first matched account.
|
|
(For example, if you have \f[CR]assets:personal checking\f[R] and
|
|
\f[CR]assets:business checking\f[R], \f[CR]hledger areg checking\f[R]
|
|
would select \f[CR]assets:business checking\f[R].)
|
|
.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 historical balance report with similar arguments.
|
|
.PP
|
|
Any additional arguments are standard query arguments, which will limit
|
|
the transactions shown.
|
|
Note some queries will disturb the running balance, causing it to be
|
|
different from the account\[aq]s real\-world running balance.
|
|
.PP
|
|
An example: this shows the transactions and historical running balance
|
|
during july, in the first account whose name contains
|
|
\[dq]checking\[dq]:
|
|
.IP
|
|
.EX
|
|
$ hledger areg checking date:jul
|
|
.EE
|
|
.PP
|
|
Each \f[CR]aregister\f[R] line item shows:
|
|
.IP \[bu] 2
|
|
the transaction\[aq]s date (or the relevant posting\[aq]s date if
|
|
different, see below)
|
|
.IP \[bu] 2
|
|
the names of all the other account(s) involved in this transaction
|
|
(probably abbreviated)
|
|
.IP \[bu] 2
|
|
the total change to this account\[aq]s balance from this transaction
|
|
.IP \[bu] 2
|
|
the account\[aq]s historical running balance after this transaction.
|
|
.PP
|
|
Transactions making a net change of zero are not shown by default; add
|
|
the \f[CR]\-E/\-\-empty\f[R] flag to show them.
|
|
.PP
|
|
For performance reasons, column widths are chosen based on the first
|
|
1000 lines; this means unusually wide values in later lines can cause
|
|
visual discontinuities as column widths are adjusted.
|
|
If you want to ensure perfect alignment, at the cost of more time and
|
|
memory, use the \f[CR]\-\-align\-all\f[R] flag.
|
|
.PP
|
|
By default, \f[CR]aregister\f[R] shows a heading above the data.
|
|
However, when reporting in a language different from English, it is
|
|
easier to omit this heading and prepend your own one.
|
|
For this purpose, use the \f[CR]\-\-heading=no\f[R] option.
|
|
.PP
|
|
This command also supports the output destination and output format
|
|
options.
|
|
The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
|
|
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R],
|
|
\f[CR]fods\f[R] (\f[I]Added in 1.41\f[R]) and \f[CR]json\f[R].
|
|
.SS aregister and posting dates
|
|
aregister always shows one line (and date and amount) per transaction.
|
|
But sometimes transactions have postings with different dates.
|
|
Also, not all of a transaction\[aq]s postings may be within the report
|
|
period.
|
|
To resolve this, aregister shows the earliest of the transaction\[aq]s
|
|
date and posting dates that is in\-period, and the sum of the in\-period
|
|
postings.
|
|
In other words it will show a combined line item with just the earliest
|
|
date, and the running balance will (temporarily, until the
|
|
transaction\[aq]s last posting) be inaccurate.
|
|
Use \f[CR]register \-H\f[R] if you need to see the individual postings.
|
|
.PP
|
|
There is also a \f[CR]\-\-txn\-dates\f[R] flag, which filters strictly
|
|
by transaction date, ignoring posting dates.
|
|
This too can cause an inaccurate running balance.
|
|
.SS register
|
|
(reg)
|
|
.PP
|
|
Show postings and their running total.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-cumulative accumulation mode: show running total from report
|
|
start date (default)
|
|
\-H \-\-historical accumulation mode: show historical running
|
|
total/balance (includes postings before report
|
|
start date)
|
|
\-A \-\-average show running average of posting amounts instead
|
|
of total (implies \-\-empty)
|
|
\-m \-\-match=DESC fuzzy search for one recent posting with
|
|
description closest to DESC
|
|
\-r \-\-related show postings\[aq] siblings instead
|
|
\-\-invert display all amounts with reversed sign
|
|
\-\-sort=FIELDS sort by: date, desc, account, amount, absamount,
|
|
or a comma\-separated combination of these. For a
|
|
descending sort, prefix with \-. (Default: date)
|
|
\-w \-\-width=N set output width (default: terminal width). \-wN,M
|
|
sets description width as well.
|
|
\-\-align\-all guarantee alignment across all lines (slower)
|
|
\-\-base\-url=URLPREFIX in html output, generate links to hledger\-web,
|
|
with this prefix. (Usually the base url shown by
|
|
hledger\-web; can also be relative.)
|
|
\-O \-\-output\-format=FMT select the output format. Supported formats:
|
|
txt, csv, tsv, html, fods, json.
|
|
\-o \-\-output\-file=FILE write output to FILE. A file extension matching
|
|
one of the above formats selects that format.
|
|
.EE
|
|
.PP
|
|
The register command displays matched postings, across all accounts, in
|
|
date order, with their running total or running historical balance.
|
|
(See also the \f[CR]aregister\f[R] command, which shows matched
|
|
transactions in a specific account.)
|
|
.PP
|
|
register normally shows line per posting, but note that multi\-commodity
|
|
amounts will occupy multiple lines (one line per commodity).
|
|
.PP
|
|
It is typically used with a query selecting a particular account, to see
|
|
that account\[aq]s activity:
|
|
.IP
|
|
.EX
|
|
$ hledger register checking
|
|
2008/01/01 income assets:bank:checking $1 $1
|
|
2008/06/01 gift assets:bank:checking $1 $2
|
|
2008/06/02 save assets:bank:checking $\-1 $1
|
|
2008/12/31 pay off assets:bank:checking $\-1 0
|
|
.EE
|
|
.PP
|
|
With \f[CR]\-\-date2\f[R], it shows and sorts by secondary date instead.
|
|
.PP
|
|
For performance reasons, column widths are chosen based on the first
|
|
1000 lines; this means unusually wide values in later lines can cause
|
|
visual discontinuities as column widths are adjusted.
|
|
If you want to ensure perfect alignment, at the cost of more time and
|
|
memory, use the \f[CR]\-\-align\-all\f[R] flag.
|
|
.PP
|
|
The \f[CR]\-\-historical\f[R]/\f[CR]\-H\f[R] flag adds the balance from
|
|
any undisplayed prior postings to the running total.
|
|
This is useful when you want to see only recent activity, with a
|
|
historically accurate running balance:
|
|
.IP
|
|
.EX
|
|
$ hledger register checking \-b 2008/6 \-\-historical
|
|
2008/06/01 gift assets:bank:checking $1 $2
|
|
2008/06/02 save assets:bank:checking $\-1 $1
|
|
2008/12/31 pay off assets:bank:checking $\-1 0
|
|
.EE
|
|
.PP
|
|
The \f[CR]\-\-depth\f[R] option limits the amount of sub\-account detail
|
|
displayed.
|
|
.PP
|
|
The \f[CR]\-\-average\f[R]/\f[CR]\-A\f[R] flag shows the running average
|
|
posting amount instead of the running total (so, the final number
|
|
displayed is the average for the whole report period).
|
|
This flag implies \f[CR]\-\-empty\f[R] (see below).
|
|
It is affected by \f[CR]\-\-historical\f[R].
|
|
It works best when showing just one account and one commodity.
|
|
.PP
|
|
The \f[CR]\-\-related\f[R]/\f[CR]\-r\f[R] flag shows the \f[I]other\f[R]
|
|
postings in the transactions of the postings which would normally be
|
|
shown.
|
|
.PP
|
|
The \f[CR]\-\-invert\f[R] flag negates all amounts.
|
|
For example, it can be used on an income account where amounts are
|
|
normally displayed as negative numbers.
|
|
It\[aq]s also useful to show postings on the checking account together
|
|
with the related account:
|
|
.PP
|
|
The \f[CR]\-\-sort=FIELDS\f[R] flag sorts by the fields given, which can
|
|
be any of \f[CR]account\f[R], \f[CR]amount\f[R], \f[CR]absamount\f[R],
|
|
\f[CR]date\f[R], or \f[CR]desc\f[R]/\f[CR]description\f[R], optionally
|
|
separated by commas.
|
|
For example, \f[CR]\-\-sort account,amount\f[R] will group all
|
|
transactions in each account, sorted by transaction amount.
|
|
Each field can be negated by a preceding \f[CR]\-\f[R], so
|
|
\f[CR]\-\-sort \-amount\f[R] will show transactions ordered from
|
|
smallest amount to largest amount.
|
|
.IP
|
|
.EX
|
|
$ hledger register \-\-related \-\-invert assets:checking
|
|
.EE
|
|
.PP
|
|
With a reporting interval, register shows summary postings, one per
|
|
interval, aggregating the postings to each account:
|
|
.IP
|
|
.EX
|
|
$ hledger register \-\-monthly income
|
|
2008/01 income:salary $\-1 $\-1
|
|
2008/06 income:gifts $\-1 $\-2
|
|
.EE
|
|
.PP
|
|
Periods with no activity, and summary postings with a zero amount, are
|
|
not shown by default; use the \f[CR]\-\-empty\f[R]/\f[CR]\-E\f[R] flag
|
|
to see them:
|
|
.IP
|
|
.EX
|
|
$ hledger register \-\-monthly income \-E
|
|
2008/01 income:salary $\-1 $\-1
|
|
2008/02 0 $\-1
|
|
2008/03 0 $\-1
|
|
2008/04 0 $\-1
|
|
2008/05 0 $\-1
|
|
2008/06 income:gifts $\-1 $\-2
|
|
2008/07 0 $\-2
|
|
2008/08 0 $\-2
|
|
2008/09 0 $\-2
|
|
2008/10 0 $\-2
|
|
2008/11 0 $\-2
|
|
2008/12 0 $\-2
|
|
.EE
|
|
.PP
|
|
Often, you\[aq]ll want to see just one line per interval.
|
|
The \f[CR]\-\-depth\f[R] option helps with this, causing subaccounts to
|
|
be aggregated:
|
|
.IP
|
|
.EX
|
|
$ hledger register \-\-monthly assets \-\-depth 1
|
|
2008/01 assets $1 $1
|
|
2008/06 assets $\-1 0
|
|
2008/12 assets $\-1 $\-1
|
|
.EE
|
|
.PP
|
|
Note when using report intervals, if you specify start/end dates these
|
|
will be adjusted outward if necessary to contain a whole number of
|
|
intervals.
|
|
This ensures that the first and last intervals are full length and
|
|
comparable to the others in the report.
|
|
.PP
|
|
With \f[CR]\-m DESC\f[R]/\f[CR]\-\-match=DESC\f[R], register does a
|
|
fuzzy search for one recent posting whose description is most similar to
|
|
DESC.
|
|
DESC should contain at least two characters.
|
|
If there is no similar\-enough match, no posting will be shown and the
|
|
program exit code will be non\-zero.
|
|
.SS Custom register output
|
|
register normally uses the full terminal width (or 80 columns if it
|
|
can\[aq]t detect that).
|
|
You can override this with the \f[CR]\-\-width\f[R]/\f[CR]\-w\f[R]
|
|
option.
|
|
.PP
|
|
The description and account columns normally share the space equally
|
|
(about half of (width \- 40) each).
|
|
You can adjust this by adding a description width as part of
|
|
\-\-width\[aq]s argument, comma\-separated: \f[CR]\-\-width W,D\f[R] .
|
|
Here\[aq]s a diagram (won\[aq]t display correctly in \-\-help):
|
|
.IP
|
|
.EX
|
|
<\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- width (W) \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->
|
|
date (10) description (D) account (W\-41\-D) amount (12) balance (12)
|
|
DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
|
|
.EE
|
|
.PP
|
|
and some examples:
|
|
.IP
|
|
.EX
|
|
$ hledger reg # use terminal width (or 80 on windows)
|
|
$ hledger reg \-w 100 # use width 100
|
|
$ hledger reg \-w 100,40 # set overall width 100, description width 40
|
|
.EE
|
|
.PP
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
|
|
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), and \f[CR]json\f[R].
|
|
.SS balancesheet
|
|
(bs)
|
|
.PP
|
|
Show the end balances in asset and liability accounts.
|
|
Amounts are shown with normal positive sign, as in conventional
|
|
financial statements.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-sum calculation mode: show sum of posting amounts
|
|
(default)
|
|
\-\-valuechange calculation mode: show total change of value of
|
|
period\-end historical balances (caused by deposits,
|
|
withdrawals, market price fluctuations)
|
|
\-\-gain calculation mode: show unrealised capital
|
|
gain/loss (historical balance value minus cost
|
|
basis)
|
|
\-\-count calculation mode: show the count of postings
|
|
\-\-change accumulation mode: accumulate amounts from column
|
|
start to column end (in multicolumn reports)
|
|
\-\-cumulative accumulation mode: accumulate amounts from report
|
|
start (specified by e.g. \-b/\-\-begin) to column end
|
|
\-H \-\-historical accumulation mode: accumulate amounts from
|
|
journal start to column end (includes postings
|
|
before report start date) (default)
|
|
\-l \-\-flat list/tree mode: show accounts as a flat list
|
|
(default). Amounts exclude subaccount amounts,
|
|
except where the account is depth\-clipped.
|
|
\-t \-\-tree list/tree mode: show accounts as a tree. Amounts
|
|
include subaccount amounts.
|
|
\-\-drop=N in list mode, omit N leading account name parts
|
|
\-\-declared include non\-parent declared accounts (best used
|
|
with \-E)
|
|
\-A \-\-average show a row average column (in multicolumn
|
|
reports)
|
|
\-T \-\-row\-total show a row total column (in multicolumn reports)
|
|
\-\-summary\-only display only row summaries (e.g. row total,
|
|
average) (in multicolumn reports)
|
|
\-N \-\-no\-total omit the final total row
|
|
\-\-no\-elide in tree mode, don\[aq]t squash boring parent accounts
|
|
\-\-format=FORMATSTR use this custom line format (in simple reports)
|
|
\-S \-\-sort\-amount sort by amount instead of account code/name
|
|
\-% \-\-percent express values in percentage of each column\[aq]s
|
|
total
|
|
\-\-layout=ARG how to show multi\-commodity amounts:
|
|
\[aq]wide[,WIDTH]\[aq]: all commodities on one line
|
|
\[aq]tall\[aq] : each commodity on a new line
|
|
\[aq]bare\[aq] : bare numbers, symbols in a column
|
|
\-\-base\-url=URLPREFIX in html output, generate hyperlinks to
|
|
hledger\-web, with this prefix. (Usually the base
|
|
url shown by hledger\-web; can also be relative.)
|
|
\-O \-\-output\-format=FMT select the output format. Supported formats:
|
|
txt, html, csv, tsv, json.
|
|
\-o \-\-output\-file=FILE write output to FILE. A file extension matching
|
|
one of the above formats selects that format.
|
|
.EE
|
|
.PP
|
|
This command displays a balance sheet, showing historical ending
|
|
balances of asset and liability accounts.
|
|
(To see equity as well, use the balancesheetequity command.)
|
|
.PP
|
|
Accounts declared with the \f[CR]Asset\f[R], \f[CR]Cash\f[R] or
|
|
\f[CR]Liability\f[R] type are shown (see account types).
|
|
Or if no such accounts are declared, it shows top\-level accounts named
|
|
\f[CR]asset\f[R] or \f[CR]liability\f[R] (case insensitive, plurals
|
|
allowed) and their subaccounts.
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
$ hledger balancesheet
|
|
Balance Sheet 2008\-12\-31
|
|
|
|
|| 2008\-12\-31
|
|
====================++============
|
|
Assets ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
assets:bank:saving || $1
|
|
assets:cash || $\-2
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $\-1
|
|
====================++============
|
|
Liabilities ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
liabilities:debts || $\-1
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $\-1
|
|
====================++============
|
|
Net: || 0
|
|
.EE
|
|
.PP
|
|
This command is a higher\-level variant of the \f[CR]balance\f[R]
|
|
command, and supports many of that command\[aq]s features, such as
|
|
multi\-period reports.
|
|
It is similar to \f[CR]hledger balance \-H assets liabilities\f[R], but
|
|
with smarter account detection, and liabilities displayed with their
|
|
sign flipped.
|
|
.PP
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
|
|
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
|
|
\f[CR]json\f[R].
|
|
.SS balancesheetequity
|
|
(bse)
|
|
.PP
|
|
This command displays a balance sheet, showing historical ending
|
|
balances of asset, liability and equity accounts.
|
|
Amounts are shown with normal positive sign, as in conventional
|
|
financial statements.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-sum calculation mode: show sum of posting amounts
|
|
(default)
|
|
\-\-valuechange calculation mode: show total change of value of
|
|
period\-end historical balances (caused by deposits,
|
|
withdrawals, market price fluctuations)
|
|
\-\-gain calculation mode: show unrealised capital
|
|
gain/loss (historical balance value minus cost
|
|
basis)
|
|
\-\-count calculation mode: show the count of postings
|
|
\-\-change accumulation mode: accumulate amounts from column
|
|
start to column end (in multicolumn reports)
|
|
\-\-cumulative accumulation mode: accumulate amounts from report
|
|
start (specified by e.g. \-b/\-\-begin) to column end
|
|
\-H \-\-historical accumulation mode: accumulate amounts from
|
|
journal start to column end (includes postings
|
|
before report start date) (default)
|
|
\-l \-\-flat list/tree mode: show accounts as a flat list
|
|
(default). Amounts exclude subaccount amounts,
|
|
except where the account is depth\-clipped.
|
|
\-t \-\-tree list/tree mode: show accounts as a tree. Amounts
|
|
include subaccount amounts.
|
|
\-\-drop=N in list mode, omit N leading account name parts
|
|
\-\-declared include non\-parent declared accounts (best used
|
|
with \-E)
|
|
\-A \-\-average show a row average column (in multicolumn
|
|
reports)
|
|
\-T \-\-row\-total show a row total column (in multicolumn reports)
|
|
\-\-summary\-only display only row summaries (e.g. row total,
|
|
average) (in multicolumn reports)
|
|
\-N \-\-no\-total omit the final total row
|
|
\-\-no\-elide in tree mode, don\[aq]t squash boring parent accounts
|
|
\-\-format=FORMATSTR use this custom line format (in simple reports)
|
|
\-S \-\-sort\-amount sort by amount instead of account code/name
|
|
\-% \-\-percent express values in percentage of each column\[aq]s
|
|
total
|
|
\-\-layout=ARG how to show multi\-commodity amounts:
|
|
\[aq]wide[,WIDTH]\[aq]: all commodities on one line
|
|
\[aq]tall\[aq] : each commodity on a new line
|
|
\[aq]bare\[aq] : bare numbers, symbols in a column
|
|
\-\-base\-url=URLPREFIX in html output, generate hyperlinks to
|
|
hledger\-web, with this prefix. (Usually the base
|
|
url shown by hledger\-web; can also be relative.)
|
|
\-O \-\-output\-format=FMT select the output format. Supported formats:
|
|
txt, html, csv, tsv, json.
|
|
\-o \-\-output\-file=FILE write output to FILE. A file extension matching
|
|
one of the above formats selects that format.
|
|
.EE
|
|
.PP
|
|
This report shows accounts declared with the \f[CR]Asset\f[R],
|
|
\f[CR]Cash\f[R], \f[CR]Liability\f[R] or \f[CR]Equity\f[R] type (see
|
|
account types).
|
|
Or if no such accounts are declared, it shows top\-level accounts named
|
|
\f[CR]asset\f[R], \f[CR]liability\f[R] or \f[CR]equity\f[R] (case
|
|
insensitive, plurals allowed) and their subaccounts.
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
$ hledger balancesheetequity
|
|
Balance Sheet With Equity 2008\-12\-31
|
|
|
|
|| 2008\-12\-31
|
|
====================++============
|
|
Assets ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
assets:bank:saving || $1
|
|
assets:cash || $\-2
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $\-1
|
|
====================++============
|
|
Liabilities ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
liabilities:debts || $\-1
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $\-1
|
|
====================++============
|
|
Equity ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| 0
|
|
====================++============
|
|
Net: || 0
|
|
.EE
|
|
.PP
|
|
This command is a higher\-level variant of the \f[CR]balance\f[R]
|
|
command, and supports many of that command\[aq]s features, such as
|
|
multi\-period reports.
|
|
It is similar to
|
|
\f[CR]hledger balance \-H assets liabilities equity\f[R], but with
|
|
smarter account detection, and liabilities/equity displayed with their
|
|
sign flipped.
|
|
.PP
|
|
This report is the easiest way to see if the accounting equation (A+L+E
|
|
= 0) is satisfied (after you have done a \f[CR]close \-\-retain\f[R] to
|
|
merge revenues and expenses with equity, and perhaps added
|
|
\f[CR]\-\-infer\-equity\f[R] to balance your commodity conversions).
|
|
.PP
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
|
|
\f[CR]tsv\f[R], \f[CR]html\f[R], and \f[CR]json\f[R].
|
|
.SS cashflow
|
|
(cf)
|
|
.PP
|
|
This command displays a (simple) cashflow statement, showing the inflows
|
|
and outflows affecting \[dq]cash\[dq] (ie, liquid, easily convertible)
|
|
assets.
|
|
Amounts are shown with normal positive sign, as in conventional
|
|
financial statements.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-sum calculation mode: show sum of posting amounts
|
|
(default)
|
|
\-\-valuechange calculation mode: show total change of value of
|
|
period\-end historical balances (caused by deposits,
|
|
withdrawals, market price fluctuations)
|
|
\-\-gain calculation mode: show unrealised capital
|
|
gain/loss (historical balance value minus cost
|
|
basis)
|
|
\-\-count calculation mode: show the count of postings
|
|
\-\-change accumulation mode: accumulate amounts from column
|
|
start to column end (in multicolumn reports)
|
|
(default)
|
|
\-\-cumulative accumulation mode: accumulate amounts from report
|
|
start (specified by e.g. \-b/\-\-begin) to column end
|
|
\-H \-\-historical accumulation mode: accumulate amounts from
|
|
journal start to column end (includes postings
|
|
before report start date)
|
|
\-l \-\-flat list/tree mode: show accounts as a flat list
|
|
(default). Amounts exclude subaccount amounts,
|
|
except where the account is depth\-clipped.
|
|
\-t \-\-tree list/tree mode: show accounts as a tree. Amounts
|
|
include subaccount amounts.
|
|
\-\-drop=N in list mode, omit N leading account name parts
|
|
\-\-declared include non\-parent declared accounts (best used
|
|
with \-E)
|
|
\-A \-\-average show a row average column (in multicolumn
|
|
reports)
|
|
\-T \-\-row\-total show a row total column (in multicolumn reports)
|
|
\-\-summary\-only display only row summaries (e.g. row total,
|
|
average) (in multicolumn reports)
|
|
\-N \-\-no\-total omit the final total row
|
|
\-\-no\-elide in tree mode, don\[aq]t squash boring parent accounts
|
|
\-\-format=FORMATSTR use this custom line format (in simple reports)
|
|
\-S \-\-sort\-amount sort by amount instead of account code/name
|
|
\-% \-\-percent express values in percentage of each column\[aq]s
|
|
total
|
|
\-\-layout=ARG how to show multi\-commodity amounts:
|
|
\[aq]wide[,WIDTH]\[aq]: all commodities on one line
|
|
\[aq]tall\[aq] : each commodity on a new line
|
|
\[aq]bare\[aq] : bare numbers, symbols in a column
|
|
\-\-base\-url=URLPREFIX in html output, generate hyperlinks to
|
|
hledger\-web, with this prefix. (Usually the base
|
|
url shown by hledger\-web; can also be relative.)
|
|
\-O \-\-output\-format=FMT select the output format. Supported formats:
|
|
txt, html, csv, tsv, json.
|
|
\-o \-\-output\-file=FILE write output to FILE. A file extension matching
|
|
one of the above formats selects that format.
|
|
.EE
|
|
.PP
|
|
This report shows accounts declared with the \f[CR]Cash\f[R] type (see
|
|
account types).
|
|
Or if no such accounts are declared, it shows accounts
|
|
.IP \[bu] 2
|
|
under a top\-level account named \f[CR]asset\f[R] (case insensitive,
|
|
plural allowed)
|
|
.IP \[bu] 2
|
|
whose name contains some variation of \f[CR]cash\f[R], \f[CR]bank\f[R],
|
|
\f[CR]checking\f[R] or \f[CR]saving\f[R].
|
|
.PP
|
|
More precisely: all accounts matching this case insensitive regular
|
|
expression:
|
|
.PP
|
|
\f[CR]\[ha]assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)\f[R]
|
|
.PP
|
|
and their subaccounts.
|
|
.PP
|
|
An example cashflow report:
|
|
.IP
|
|
.EX
|
|
$ hledger cashflow
|
|
Cashflow Statement 2008
|
|
|
|
|| 2008
|
|
====================++======
|
|
Cash flows ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
|
|
assets:bank:saving || $1
|
|
assets:cash || $\-2
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
|
|
|| $\-1
|
|
.EE
|
|
.PP
|
|
This command is a higher\-level variant of the \f[CR]balance\f[R]
|
|
command, and supports many of that command\[aq]s features, such as
|
|
multi\-period reports.
|
|
It is similar to
|
|
\f[CR]hledger balance assets not:fixed not:investment not:receivable\f[R],
|
|
but with smarter account detection.
|
|
.PP
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
|
|
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
|
|
\f[CR]json\f[R].
|
|
.SS incomestatement
|
|
(is)
|
|
.PP
|
|
Show revenue inflows and expense outflows during the report period.
|
|
Amounts are shown with normal positive sign, as in conventional
|
|
financial statements.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-sum calculation mode: show sum of posting amounts
|
|
(default)
|
|
\-\-valuechange calculation mode: show total change of value of
|
|
period\-end historical balances (caused by deposits,
|
|
withdrawals, market price fluctuations)
|
|
\-\-gain calculation mode: show unrealised capital
|
|
gain/loss (historical balance value minus cost
|
|
basis)
|
|
\-\-count calculation mode: show the count of postings
|
|
\-\-change accumulation mode: accumulate amounts from column
|
|
start to column end (in multicolumn reports)
|
|
(default)
|
|
\-\-cumulative accumulation mode: accumulate amounts from report
|
|
start (specified by e.g. \-b/\-\-begin) to column end
|
|
\-H \-\-historical accumulation mode: accumulate amounts from
|
|
journal start to column end (includes postings
|
|
before report start date)
|
|
\-l \-\-flat list/tree mode: show accounts as a flat list
|
|
(default). Amounts exclude subaccount amounts,
|
|
except where the account is depth\-clipped.
|
|
\-t \-\-tree list/tree mode: show accounts as a tree. Amounts
|
|
include subaccount amounts.
|
|
\-\-drop=N in list mode, omit N leading account name parts
|
|
\-\-declared include non\-parent declared accounts (best used
|
|
with \-E)
|
|
\-A \-\-average show a row average column (in multicolumn
|
|
reports)
|
|
\-T \-\-row\-total show a row total column (in multicolumn reports)
|
|
\-\-summary\-only display only row summaries (e.g. row total,
|
|
average) (in multicolumn reports)
|
|
\-N \-\-no\-total omit the final total row
|
|
\-\-no\-elide in tree mode, don\[aq]t squash boring parent accounts
|
|
\-\-format=FORMATSTR use this custom line format (in simple reports)
|
|
\-S \-\-sort\-amount sort by amount instead of account code/name
|
|
\-% \-\-percent express values in percentage of each column\[aq]s
|
|
total
|
|
\-\-layout=ARG how to show multi\-commodity amounts:
|
|
\[aq]wide[,WIDTH]\[aq]: all commodities on one line
|
|
\[aq]tall\[aq] : each commodity on a new line
|
|
\[aq]bare\[aq] : bare numbers, symbols in a column
|
|
\-\-base\-url=URLPREFIX in html output, generate hyperlinks to
|
|
hledger\-web, with this prefix. (Usually the base
|
|
url shown by hledger\-web; can also be relative.)
|
|
\-O \-\-output\-format=FMT select the output format. Supported formats:
|
|
txt, html, csv, tsv, json.
|
|
\-o \-\-output\-file=FILE write output to FILE. A file extension matching
|
|
one of the above formats selects that format.
|
|
.EE
|
|
.PP
|
|
This command displays an income statement, showing revenues and expenses
|
|
during one or more periods.
|
|
.PP
|
|
It shows accounts declared with the \f[CR]Revenue\f[R] or
|
|
\f[CR]Expense\f[R] type (see account types).
|
|
Or if no such accounts are declared, it shows top\-level accounts named
|
|
\f[CR]revenue\f[R] or \f[CR]income\f[R] or \f[CR]expense\f[R] (case
|
|
insensitive, plurals allowed) and their subaccounts.
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
$ hledger incomestatement
|
|
Income Statement 2008
|
|
|
|
|| 2008
|
|
===================++======
|
|
Revenues ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
|
|
income:gifts || $1
|
|
income:salary || $1
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
|
|
|| $2
|
|
===================++======
|
|
Expenses ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
|
|
expenses:food || $1
|
|
expenses:supplies || $1
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-
|
|
|| $2
|
|
===================++======
|
|
Net: || 0
|
|
.EE
|
|
.PP
|
|
This command is a higher\-level variant of the \f[CR]balance\f[R]
|
|
command, and supports many of that command\[aq]s features, such as
|
|
multi\-period reports.
|
|
It is similar to
|
|
\f[CR]hledger balance \[aq](revenues|income)\[aq] expenses\f[R], but
|
|
with smarter account detection, and revenues/income displayed with their
|
|
sign flipped.
|
|
.PP
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are \f[CR]txt\f[R], \f[CR]csv\f[R],
|
|
\f[CR]tsv\f[R] (\f[I]Added in 1.32\f[R]), \f[CR]html\f[R], and
|
|
\f[CR]json\f[R].
|
|
.SH Advanced report commands
|
|
.SS balance
|
|
(bal)
|
|
.PP
|
|
A flexible, general purpose \[dq]summing\[dq] report that shows accounts
|
|
with some kind of numeric data.
|
|
This can be balance changes per period, end balances, budget
|
|
performance, unrealised capital gains, etc.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-sum calculation mode: show sum of posting amounts
|
|
(default)
|
|
\-\-valuechange calculation mode: show total change of value of
|
|
period\-end historical balances (caused by deposits,
|
|
withdrawals, market price fluctuations)
|
|
\-\-gain calculation mode: show unrealised capital
|
|
gain/loss (historical balance value minus cost
|
|
basis)
|
|
\-\-budget[=DESCPAT] calculation mode: show sum of posting amounts
|
|
together with budget goals defined by periodic
|
|
transactions. With a DESCPAT argument (must be
|
|
separated by = not space),
|
|
use only periodic transactions with matching
|
|
description
|
|
(case insensitive substring match).
|
|
\-\-count calculation mode: show the count of postings
|
|
\-\-change accumulation mode: accumulate amounts from column
|
|
start to column end (in multicolumn reports,
|
|
default)
|
|
\-\-cumulative accumulation mode: accumulate amounts from report
|
|
start (specified by e.g. \-b/\-\-begin) to column end
|
|
\-H \-\-historical accumulation mode: accumulate amounts from
|
|
journal start to column end (includes postings
|
|
before report start date)
|
|
\-l \-\-flat list/tree mode: show accounts as a flat list
|
|
(default). Amounts exclude subaccount amounts,
|
|
except where the account is depth\-clipped.
|
|
\-t \-\-tree list/tree mode: show accounts as a tree. Amounts
|
|
include subaccount amounts.
|
|
\-\-drop=N in list mode, omit N leading account name parts
|
|
\-\-declared include non\-parent declared accounts (best used
|
|
with \-E)
|
|
\-A \-\-average show a row average column (in multicolumn
|
|
reports)
|
|
\-T \-\-row\-total show a row total column (in multicolumn reports)
|
|
\-\-summary\-only display only row summaries (e.g. row total,
|
|
average) (in multicolumn reports)
|
|
\-N \-\-no\-total omit the final total row
|
|
\-\-no\-elide in tree mode, don\[aq]t squash boring parent accounts
|
|
\-\-format=FORMATSTR use this custom line format (in simple reports)
|
|
\-S \-\-sort\-amount sort by amount instead of account code/name (in
|
|
flat mode). With multiple columns, sorts by the row
|
|
total, or by row average if that is displayed.
|
|
\-% \-\-percent express values in percentage of each column\[aq]s
|
|
total
|
|
\-r \-\-related show the other accounts transacted with, instead
|
|
\-\-invert display all amounts with reversed sign
|
|
\-\-transpose switch rows and columns (use vertical time axis)
|
|
\-\-layout=ARG how to lay out multi\-commodity amounts and the
|
|
overall table:
|
|
\[aq]wide[,W]\[aq]: commodities on same line, up to W wide
|
|
\[aq]tall\[aq] : commodities on separate lines
|
|
\[aq]bare\[aq] : commodity symbols in a separate column
|
|
\[aq]tidy\[aq] : each data field in its own column
|
|
\-\-base\-url=URLPREFIX in html output, generate links to hledger\-web,
|
|
with this prefix. (Usually the base url shown by
|
|
hledger\-web; can also be relative.)
|
|
\-O \-\-output\-format=FMT select the output format. Supported formats:
|
|
txt, html, csv, tsv, json, fods.
|
|
\-o \-\-output\-file=FILE write output to FILE. A file extension matching
|
|
one of the above formats selects that format.
|
|
.EE
|
|
.PP
|
|
\f[CR]balance\f[R] is one of hledger\[aq]s oldest and most versatile
|
|
commands, for listing account balances, balance changes, values, value
|
|
changes and more, during one time period or many.
|
|
Generally it shows a table, with rows representing accounts, and columns
|
|
representing periods.
|
|
.PP
|
|
Note there are some variants of the \f[CR]balance\f[R] command with
|
|
convenient defaults, which are simpler to use: \f[CR]balancesheet\f[R],
|
|
\f[CR]balancesheetequity\f[R], \f[CR]cashflow\f[R] and
|
|
\f[CR]incomestatement\f[R].
|
|
When you need more control, then use \f[CR]balance\f[R].
|
|
.SS balance features
|
|
Here\[aq]s a quick overview of the \f[CR]balance\f[R] command\[aq]s
|
|
features, followed by more detailed descriptions and examples.
|
|
Many of these work with the other balance\-like commands as well
|
|
(\f[CR]bs\f[R], \f[CR]cf\f[R], \f[CR]is\f[R]..).
|
|
.PP
|
|
\f[CR]balance\f[R] can show..
|
|
.IP \[bu] 2
|
|
accounts as a list (\f[CR]\-l\f[R]) or a tree (\f[CR]\-t\f[R])
|
|
.IP \[bu] 2
|
|
optionally depth\-limited (\f[CR]\-[1\-9]\f[R])
|
|
.IP \[bu] 2
|
|
sorted by declaration order and name, or by amount
|
|
.PP
|
|
\&..and their..
|
|
.IP \[bu] 2
|
|
balance changes (the default)
|
|
.IP \[bu] 2
|
|
or actual and planned balance changes (\f[CR]\-\-budget\f[R])
|
|
.IP \[bu] 2
|
|
or value of balance changes (\f[CR]\-V\f[R])
|
|
.IP \[bu] 2
|
|
or change of balance values (\f[CR]\-\-valuechange\f[R])
|
|
.IP \[bu] 2
|
|
or unrealised capital gain/loss (\f[CR]\-\-gain\f[R])
|
|
.IP \[bu] 2
|
|
or balance changes from sibling postings
|
|
(\f[CR]\-\-related\f[R]/\f[CR]\-r\f[R])
|
|
.IP \[bu] 2
|
|
or postings count (\f[CR]\-\-count\f[R])
|
|
.PP
|
|
\&..in..
|
|
.IP \[bu] 2
|
|
one time period (the whole journal period by default)
|
|
.IP \[bu] 2
|
|
or multiple periods (\f[CR]\-D\f[R], \f[CR]\-W\f[R], \f[CR]\-M\f[R],
|
|
\f[CR]\-Q\f[R], \f[CR]\-Y\f[R], \f[CR]\-p INTERVAL\f[R])
|
|
.PP
|
|
\&..either..
|
|
.IP \[bu] 2
|
|
per period (the default)
|
|
.IP \[bu] 2
|
|
or accumulated since report start date (\f[CR]\-\-cumulative\f[R])
|
|
.IP \[bu] 2
|
|
or accumulated since account creation (\f[CR]\-\-historical/\-H\f[R])
|
|
.PP
|
|
\&..possibly converted to..
|
|
.IP \[bu] 2
|
|
cost
|
|
(\f[CR]\-\-value=cost[,COMM]\f[R]/\f[CR]\-\-cost\f[R]/\f[CR]\-B\f[R])
|
|
.IP \[bu] 2
|
|
or market value, as of transaction dates
|
|
(\f[CR]\-\-value=then[,COMM]\f[R])
|
|
.IP \[bu] 2
|
|
or at period ends (\f[CR]\-\-value=end[,COMM]\f[R])
|
|
.IP \[bu] 2
|
|
or now (\f[CR]\-\-value=now\f[R])
|
|
.IP \[bu] 2
|
|
or at some other date (\f[CR]\-\-value=YYYY\-MM\-DD\f[R])
|
|
.PP
|
|
\&..with..
|
|
.IP \[bu] 2
|
|
totals (\f[CR]\-T\f[R]), averages (\f[CR]\-A\f[R]), percentages
|
|
(\f[CR]\-%\f[R]), inverted sign (\f[CR]\-\-invert\f[R])
|
|
.IP \[bu] 2
|
|
rows and columns swapped (\f[CR]\-\-transpose\f[R])
|
|
.IP \[bu] 2
|
|
another field used as account name (\f[CR]\-\-pivot\f[R])
|
|
.IP \[bu] 2
|
|
custom\-formatted line items (single\-period reports only)
|
|
(\f[CR]\-\-format\f[R])
|
|
.IP \[bu] 2
|
|
commodities displayed on the same line or multiple lines
|
|
(\f[CR]\-\-layout\f[R])
|
|
.PP
|
|
This command supports the output destination and output format options,
|
|
with output formats \f[CR]txt\f[R], \f[CR]csv\f[R], \f[CR]tsv\f[R]
|
|
(\f[I]Added in 1.32\f[R]), \f[CR]json\f[R], and (multi\-period reports
|
|
only:) \f[CR]html\f[R], \f[CR]fods\f[R] (\f[I]Added in 1.40\f[R]).
|
|
In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative
|
|
amounts are shown in red.
|
|
.SS Simple balance report
|
|
With no arguments, \f[CR]balance\f[R] shows a list of all accounts and
|
|
their change of balance \- ie, the sum of posting amounts, both inflows
|
|
and outflows \- during the entire period of the journal.
|
|
(\[dq]Simple\[dq] here means just one column of numbers, covering a
|
|
single period.
|
|
You can also have multi\-period reports, described later.)
|
|
.PP
|
|
For real\-world accounts, these numbers will normally be their end
|
|
balance at the end of the journal period; more on this below.
|
|
.PP
|
|
Accounts are sorted by declaration order if any, and then alphabetically
|
|
by account name.
|
|
For instance (using examples/sample.journal):
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/sample.journal bal
|
|
$1 assets:bank:saving
|
|
$\-2 assets:cash
|
|
$1 expenses:food
|
|
$1 expenses:supplies
|
|
$\-1 income:gifts
|
|
$\-1 income:salary
|
|
$1 liabilities:debts
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
0
|
|
.EE
|
|
.PP
|
|
Accounts with a zero balance (and no non\-zero subaccounts, in tree mode
|
|
\- see below) are hidden by default.
|
|
Use \f[CR]\-E/\-\-empty\f[R] to show them (revealing
|
|
\f[CR]assets:bank:checking\f[R] here):
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/sample.journal bal \-E
|
|
0 assets:bank:checking
|
|
$1 assets:bank:saving
|
|
$\-2 assets:cash
|
|
$1 expenses:food
|
|
$1 expenses:supplies
|
|
$\-1 income:gifts
|
|
$\-1 income:salary
|
|
$1 liabilities:debts
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
0
|
|
.EE
|
|
.PP
|
|
The total of the amounts displayed is shown as the last line, unless
|
|
\f[CR]\-N\f[R]/\f[CR]\-\-no\-total\f[R] is used.
|
|
.SS Balance report line format
|
|
For single\-period balance reports displayed in the terminal (only), you
|
|
can use \f[CR]\-\-format FMT\f[R] to customise the format and content of
|
|
each line.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/sample.journal balance \-\-format \[dq]%20(account) %12(total)\[dq]
|
|
assets $\-1
|
|
bank:saving $1
|
|
cash $\-2
|
|
expenses $2
|
|
food $1
|
|
supplies $1
|
|
income $\-2
|
|
gifts $\-1
|
|
salary $\-1
|
|
liabilities:debts $1
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
0
|
|
.EE
|
|
.PP
|
|
The FMT format string specifies the formatting applied to each
|
|
account/balance pair.
|
|
It may contain any suitable text, with data fields interpolated like so:
|
|
.PP
|
|
\f[CR]%[MIN][.MAX](FIELDNAME)\f[R]
|
|
.IP \[bu] 2
|
|
MIN pads with spaces to at least this width (optional)
|
|
.IP \[bu] 2
|
|
MAX truncates at this width (optional)
|
|
.IP \[bu] 2
|
|
FIELDNAME must be enclosed in parentheses, and can be one of:
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
\f[CR]depth_spacer\f[R] \- a number of spaces equal to the account\[aq]s
|
|
depth, or if MIN is specified, MIN * depth spaces.
|
|
.IP \[bu] 2
|
|
\f[CR]account\f[R] \- the account\[aq]s name
|
|
.IP \[bu] 2
|
|
\f[CR]total\f[R] \- the account\[aq]s balance/posted total, right
|
|
justified
|
|
.RE
|
|
.PP
|
|
Also, FMT can begin with an optional prefix to control how
|
|
multi\-commodity amounts are rendered:
|
|
.IP \[bu] 2
|
|
\f[CR]%_\f[R] \- render on multiple lines, bottom\-aligned (the default)
|
|
.IP \[bu] 2
|
|
\f[CR]%\[ha]\f[R] \- render on multiple lines, top\-aligned
|
|
.IP \[bu] 2
|
|
\f[CR]%,\f[R] \- render on one line, comma\-separated
|
|
.PP
|
|
There are some quirks.
|
|
Eg in one\-line mode, \f[CR]%(depth_spacer)\f[R] has no effect, instead
|
|
\f[CR]%(account)\f[R] has indentation built in.
|
|
\ Experimentation may be needed to get pleasing results.
|
|
.PP
|
|
Some example formats:
|
|
.IP \[bu] 2
|
|
\f[CR]%(total)\f[R] \- the account\[aq]s total
|
|
.IP \[bu] 2
|
|
\f[CR]%\-20.20(account)\f[R] \- the account\[aq]s name, left justified,
|
|
padded to 20 characters and clipped at 20 characters
|
|
.IP \[bu] 2
|
|
\f[CR]%,%\-50(account) %25(total)\f[R] \- account name padded to 50
|
|
characters, total padded to 20 characters, with multiple commodities
|
|
rendered on one line
|
|
.IP \[bu] 2
|
|
\f[CR]%20(total) %2(depth_spacer)%\-(account)\f[R] \- the default
|
|
format for the single\-column balance report
|
|
.SS Filtered balance report
|
|
You can show fewer accounts, a different time period, totals from
|
|
cleared transactions only, etc.
|
|
by using query arguments or options to limit the postings being matched.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/sample.journal bal \-\-cleared assets date:200806
|
|
$\-2 assets:cash
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$\-2
|
|
.EE
|
|
.SS List or tree mode
|
|
By default, or with \f[CR]\-l/\-\-flat\f[R], accounts are shown as a
|
|
flat list with their full names visible, as in the examples above.
|
|
.PP
|
|
With \f[CR]\-t/\-\-tree\f[R], the account hierarchy is shown, with
|
|
subaccounts\[aq] \[dq]leaf\[dq] names indented below their parent:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/sample.journal balance
|
|
$\-1 assets
|
|
$1 bank:saving
|
|
$\-2 cash
|
|
$2 expenses
|
|
$1 food
|
|
$1 supplies
|
|
$\-2 income
|
|
$\-1 gifts
|
|
$\-1 salary
|
|
$1 liabilities:debts
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
0
|
|
.EE
|
|
.PP
|
|
Notes:
|
|
.IP \[bu] 2
|
|
\[dq]Boring\[dq] accounts are combined with their subaccount for more
|
|
compact output, unless \f[CR]\-\-no\-elide\f[R] is used.
|
|
Boring accounts have no balance of their own and just one subaccount (eg
|
|
\f[CR]assets:bank\f[R] and \f[CR]liabilities\f[R] above).
|
|
.IP \[bu] 2
|
|
All balances shown are \[dq]inclusive\[dq], ie including the balances
|
|
from all subaccounts.
|
|
Note this means some repetition in the output, which requires
|
|
explanation when sharing reports with non\-plaintextaccounting\-users.
|
|
A tree mode report\[aq]s final total is the sum of the top\-level
|
|
balances shown, not of all the balances shown.
|
|
.IP \[bu] 2
|
|
Each group of sibling accounts (ie, under a common parent) is sorted
|
|
separately.
|
|
.SS Depth limiting
|
|
With a \f[CR]depth:NUM\f[R] query, or \f[CR]\-\-depth NUM\f[R] option,
|
|
or just \f[CR]\-NUM\f[R] (eg: \f[CR]\-3\f[R]) balance reports will show
|
|
accounts only to the specified depth, hiding the deeper subaccounts.
|
|
This can be useful for getting an overview without too much detail.
|
|
.PP
|
|
Account balances at the depth limit always include the balances from any
|
|
deeper subaccounts (even in list mode).
|
|
Eg, limiting to depth 1:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/sample.journal balance \-1
|
|
$\-1 assets
|
|
$2 expenses
|
|
$\-2 income
|
|
$1 liabilities
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
0
|
|
.EE
|
|
.SS Dropping top\-level accounts
|
|
You can also hide one or more top\-level account name parts, using
|
|
\f[CR]\-\-drop NUM\f[R].
|
|
This can be useful for hiding repetitive top\-level account names:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/sample.journal bal expenses \-\-drop 1
|
|
$1 food
|
|
$1 supplies
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$2
|
|
.EE
|
|
.PP
|
|
.SS Showing declared accounts
|
|
With \f[CR]\-\-declared\f[R], accounts which have been declared with an
|
|
account directive will be included in the balance report, even if they
|
|
have no transactions.
|
|
(Since they will have a zero balance, you will also need
|
|
\f[CR]\-E/\-\-empty\f[R] to see them.)
|
|
.PP
|
|
More precisely, \f[I]leaf\f[R] declared accounts (with no subaccounts)
|
|
will be included, since those are usually the more useful in reports.
|
|
.PP
|
|
The idea of this is to be able to see a useful \[dq]complete\[dq]
|
|
balance report, even when you don\[aq]t have transactions in all of your
|
|
declared accounts yet.
|
|
.SS Sorting by amount
|
|
With \f[CR]\-S/\-\-sort\-amount\f[R], accounts with the largest (most
|
|
positive) balances are shown first.
|
|
Eg: \f[CR]hledger bal expenses \-MAS\f[R] shows your biggest averaged
|
|
monthly expenses first.
|
|
When more than one commodity is present, they will be sorted by the
|
|
alphabetically earliest commodity first, and then by subsequent
|
|
commodities (if an amount is missing a commodity, it is treated as 0).
|
|
.PP
|
|
Revenues and liability balances are typically negative, however, so
|
|
\f[CR]\-S\f[R] shows these in reverse order.
|
|
To work around this, you can add \f[CR]\-\-invert\f[R] to flip the
|
|
signs.
|
|
Or you could use one of the higher\-level balance reports
|
|
(\f[CR]bs\f[R], \f[CR]is\f[R]..), which flip the sign automatically (eg:
|
|
\f[CR]hledger is \-MAS\f[R]).
|
|
.PP
|
|
.SS Percentages
|
|
With \f[CR]\-%/\-\-percent\f[R], balance reports show each account\[aq]s
|
|
value expressed as a percentage of the (column) total.
|
|
.PP
|
|
Note it is not useful to calculate percentages if the amounts in a
|
|
column have mixed signs.
|
|
In this case, make a separate report for each sign, eg:
|
|
.IP
|
|
.EX
|
|
$ hledger bal \-% amt:\[ga]>0\[ga]
|
|
$ hledger bal \-% amt:\[ga]<0\[ga]
|
|
.EE
|
|
.PP
|
|
Similarly, if the amounts in a column have mixed commodities, convert
|
|
them to one commodity with \f[CR]\-B\f[R], \f[CR]\-V\f[R],
|
|
\f[CR]\-X\f[R] or \f[CR]\-\-value\f[R], or make a separate report for
|
|
each commodity:
|
|
.IP
|
|
.EX
|
|
$ hledger bal \-% cur:\[rs]\[rs]$
|
|
$ hledger bal \-% cur:€
|
|
.EE
|
|
.SS Multi\-period balance report
|
|
With a report interval (set by the \f[CR]\-D/\-\-daily\f[R],
|
|
\f[CR]\-W/\-\-weekly\f[R], \f[CR]\-M/\-\-monthly\f[R],
|
|
\f[CR]\-Q/\-\-quarterly\f[R], \f[CR]\-Y/\-\-yearly\f[R], or
|
|
\f[CR]\-p/\-\-period\f[R] flag), \f[CR]balance\f[R] shows a tabular
|
|
report, with columns representing successive time periods (and a title):
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/sample.journal bal \-\-quarterly income expenses \-E
|
|
Balance changes in 2008:
|
|
|
|
|| 2008q1 2008q2 2008q3 2008q4
|
|
===================++=================================
|
|
expenses:food || 0 $1 0 0
|
|
expenses:supplies || 0 $1 0 0
|
|
income:gifts || 0 $\-1 0 0
|
|
income:salary || $\-1 0 0 0
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $\-1 $1 0 0
|
|
.EE
|
|
.PP
|
|
Notes:
|
|
.IP \[bu] 2
|
|
The report\[aq]s start/end dates will be expanded, if necessary, to
|
|
fully encompass the displayed subperiods (so that the first and last
|
|
subperiods have the same duration as the others).
|
|
.IP \[bu] 2
|
|
Leading and trailing periods (columns) containing all zeroes are not
|
|
shown, unless \f[CR]\-E/\-\-empty\f[R] is used.
|
|
.IP \[bu] 2
|
|
Accounts (rows) containing all zeroes are not shown, unless
|
|
\f[CR]\-E/\-\-empty\f[R] is used.
|
|
.IP \[bu] 2
|
|
Amounts with many commodities are shown in abbreviated form, unless
|
|
\f[CR]\-\-no\-elide\f[R] is used.
|
|
.IP \[bu] 2
|
|
Average and/or total columns can be added with the
|
|
\f[CR]\-A/\-\-average\f[R] and \f[CR]\-T/\-\-row\-total\f[R] flags.
|
|
.IP \[bu] 2
|
|
The \f[CR]\-\-transpose\f[R] flag can be used to exchange rows and
|
|
columns.
|
|
.IP \[bu] 2
|
|
The \f[CR]\-\-pivot FIELD\f[R] option causes a different transaction
|
|
field to be used as \[dq]account name\[dq].
|
|
See PIVOTING.
|
|
.IP \[bu] 2
|
|
The \f[CR]\-\-summary\-only\f[R] flag (\f[CR]\-\-summary\f[R] also
|
|
works) hides all but the Total and Average columns (those should be
|
|
enabled with \f[CR]\-\-row\-total\f[R] and \f[CR]\-A/\-\-average\f[R]).
|
|
.PP
|
|
Multi\-period reports with many periods can be too wide for easy viewing
|
|
in the terminal.
|
|
Here are some ways to handle that:
|
|
.IP \[bu] 2
|
|
Hide the totals row with \f[CR]\-N/\-\-no\-total\f[R]
|
|
.IP \[bu] 2
|
|
Filter to a single currency with \f[CR]cur:\f[R]
|
|
.IP \[bu] 2
|
|
Convert to a single currency with
|
|
\f[CR]\-V [\-\-infer\-market\-price]\f[R]
|
|
.IP \[bu] 2
|
|
Use a more compact layout like \f[CR]\-\-layout=bare\f[R]
|
|
.IP \[bu] 2
|
|
Maximize the terminal window
|
|
.IP \[bu] 2
|
|
Reduce the terminal\[aq]s font size
|
|
.IP \[bu] 2
|
|
View with a pager like less, eg:
|
|
\f[CR]hledger bal \-D \-\-color=yes | less \-RS\f[R]
|
|
.IP \[bu] 2
|
|
Output as CSV and use a CSV viewer like visidata
|
|
(\f[CR]hledger bal \-D \-O csv | vd \-f csv\f[R]), Emacs\[aq] csv\-mode
|
|
(\f[CR]M\-x csv\-mode, C\-c C\-a\f[R]), or a spreadsheet
|
|
(\f[CR]hledger bal \-D \-o a.csv && open a.csv\f[R])
|
|
.IP \[bu] 2
|
|
Output as HTML and view with a browser:
|
|
\f[CR]hledger bal \-D \-o a.html && open a.html\f[R]
|
|
.SS Balance change, end balance
|
|
It\[aq]s important to be clear on the meaning of the numbers shown in
|
|
balance reports.
|
|
Here is some terminology we use:
|
|
.PP
|
|
A \f[B]\f[BI]balance change\f[B]\f[R] is the net amount added to, or
|
|
removed from, an account during some period.
|
|
.PP
|
|
An \f[B]\f[BI]end balance\f[B]\f[R] is the amount accumulated in an
|
|
account as of some date (and some time, but hledger doesn\[aq]t store
|
|
that; assume end of day in your timezone).
|
|
It is the sum of previous balance changes.
|
|
.PP
|
|
We call it a \f[B]\f[BI]historical end balance\f[B]\f[R] if it includes
|
|
all balance changes since the account was created.
|
|
For a real world account, this means it will match the \[dq]historical
|
|
record\[dq], eg the balances reported in your bank statements or bank
|
|
web UI.
|
|
(If they are correct!)
|
|
.PP
|
|
In general, balance changes are what you want to see when reviewing
|
|
revenues and expenses, and historical end balances are what you want to
|
|
see when reviewing or reconciling asset, liability and equity accounts.
|
|
.PP
|
|
\f[CR]balance\f[R] shows balance changes by default.
|
|
To see accurate historical end balances:
|
|
.IP "1." 3
|
|
Initialise account starting balances with an \[dq]opening balances\[dq]
|
|
transaction (a transfer from equity to the account), unless the journal
|
|
covers the account\[aq]s full lifetime.
|
|
.IP "2." 3
|
|
Include all of of the account\[aq]s prior postings in the report, by not
|
|
specifying a report start date, or by using the
|
|
\f[CR]\-H/\-\-historical\f[R] flag.
|
|
(\f[CR]\-H\f[R] causes report start date to be ignored when summing
|
|
postings.)
|
|
.SS Balance report modes
|
|
The balance command is quite flexible; here is the full detail on how to
|
|
control what it reports.
|
|
If the following seems complicated, don\[aq]t worry \- this is for
|
|
advanced reporting, and it does take time and experimentation to get
|
|
familiar with all the report modes.
|
|
.PP
|
|
There are three important option groups:
|
|
.PP
|
|
\f[CR]hledger balance [CALCULATIONMODE] [ACCUMULATIONMODE] [VALUATIONMODE] ...\f[R]
|
|
.SS Calculation mode
|
|
The basic calculation to perform for each table cell.
|
|
It is one of:
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-sum\f[R] : sum the posting amounts (\f[B]default\f[R])
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-budget\f[R] : sum the amounts, but also show the budget goal
|
|
amount (for each account/period)
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-valuechange\f[R] : show the change in period\-end historical
|
|
balance values (caused by deposits, withdrawals, and/or market price
|
|
fluctuations)
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-gain\f[R] : show the unrealised capital gain/loss, (the
|
|
current valued balance minus each amount\[aq]s original cost)
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-count\f[R] : show the count of postings
|
|
.SS Accumulation mode
|
|
How amounts should accumulate across a report\[aq]s subperiods/columns.
|
|
Another way to say it: which time period\[aq]s postings should
|
|
contribute to each cell\[aq]s calculation.
|
|
It is one of:
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-change\f[R] : calculate with postings from column start to
|
|
column end, ie \[dq]just this column\[dq].
|
|
Typically used to see revenues/expenses.
|
|
(\f[B]default for balance, cashflow, incomestatement\f[R])
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-cumulative\f[R] : calculate with postings from report start to
|
|
column end, ie \[dq]previous columns plus this column\[dq].
|
|
Typically used to show changes accumulated since the report\[aq]s start
|
|
date.
|
|
Not often used.
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-historical/\-H\f[R] : calculate with postings from journal
|
|
start to column end, ie \[dq]all postings from before report start date
|
|
until this column\[aq]s end\[dq].
|
|
Typically used to see historical end balances of
|
|
assets/liabilities/equity.
|
|
(\f[B]default for balancesheet, balancesheetequity\f[R])
|
|
.SS Valuation mode
|
|
Which kind of value or cost conversion should be applied, if any, before
|
|
displaying the report.
|
|
See Cost reporting and Value reporting for more about conversions.
|
|
.PP
|
|
A valuation (or cost) mode can be selected with the \-\-value option:
|
|
.IP \[bu] 2
|
|
no conversion : don\[aq]t convert to cost or value (\f[B]default\f[R])
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-value=cost[,COMM]\f[R] : convert amounts to cost (then
|
|
optionally to some other commodity)
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-value=then[,COMM]\f[R] : convert amounts to market value on
|
|
transaction dates
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-value=end[,COMM]\f[R] : convert amounts to market value on
|
|
period end date(s)
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
(\f[B]default with \f[CB]\-\-valuechange\f[B], \f[CB]\-\-gain\f[B]\f[R])
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-value=now[,COMM]\f[R] : convert amounts to market value on
|
|
today\[aq]s date
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-value=YYYY\-MM\-DD[,COMM]\f[R] : convert amounts to market
|
|
value on another date
|
|
.PP
|
|
or with the legacy \-B/\-V/\-X options, which are equivalent and easier
|
|
to type:
|
|
.IP \[bu] 2
|
|
\f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R] : like \-\-value=cost
|
|
.IP \[bu] 2
|
|
\f[CR]\-V\f[R]/\f[CR]\-\-market\f[R] : like \-\-value=end
|
|
.IP \[bu] 2
|
|
\f[CR]\-X COMM\f[R]/\f[CR]\-\-exchange COMM\f[R] : like
|
|
\-\-value=end,COMM
|
|
.PP
|
|
Note that \-\-value can also convert to cost, as a convenience; but
|
|
actually \-\-cost and \-\-value are independent options, and could be
|
|
used together.
|
|
.SS Combining balance report modes
|
|
Most combinations of these modes should produce reasonable reports, but
|
|
if you find any that seem wrong or misleading, let us know.
|
|
The following restrictions are applied:
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-valuechange\f[R] implies \f[CR]\-\-value=end\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-valuechange\f[R] makes \f[CR]\-\-change\f[R] the default when
|
|
used with the \f[CR]balancesheet\f[R]/\f[CR]balancesheetequity\f[R]
|
|
commands
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-cumulative\f[R] or \f[CR]\-\-historical\f[R] disables
|
|
\f[CR]\-\-row\-total/\-T\f[R]
|
|
.PP
|
|
For reference, here is what the combinations of accumulation and
|
|
valuation show:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(7.9n) lw(16.4n) lw(16.9n) lw(15.1n) lw(13.7n).
|
|
T{
|
|
Valuation:> Accumulation:v
|
|
T}@T{
|
|
no valuation
|
|
T}@T{
|
|
\f[CR]\-\-value= then\f[R]
|
|
T}@T{
|
|
\f[CR]\-\-value= end\f[R]
|
|
T}@T{
|
|
\f[CR]\-\-value= YYYY\-MM\-DD /now\f[R]
|
|
T}
|
|
_
|
|
T{
|
|
\f[CR]\-\-change\f[R]
|
|
T}@T{
|
|
change in period
|
|
T}@T{
|
|
sum of posting\-date market values in period
|
|
T}@T{
|
|
period\-end value of change in period
|
|
T}@T{
|
|
DATE\-value of change in period
|
|
T}
|
|
T{
|
|
\f[CR]\-\-cumulative\f[R]
|
|
T}@T{
|
|
change from report start to period end
|
|
T}@T{
|
|
sum of posting\-date market values from report start to period end
|
|
T}@T{
|
|
period\-end value of change from report start to period end
|
|
T}@T{
|
|
DATE\-value of change from report start to period end
|
|
T}
|
|
T{
|
|
\f[CR]\-\-historical /\-H\f[R]
|
|
T}@T{
|
|
change from journal start to period end (historical end balance)
|
|
T}@T{
|
|
sum of posting\-date market values from journal start to period end
|
|
T}@T{
|
|
period\-end value of change from journal start to period end
|
|
T}@T{
|
|
DATE\-value of change from journal start to period end
|
|
T}
|
|
.TE
|
|
.SS Budget report
|
|
The \f[CR]\-\-budget\f[R] report is like a regular balance report, but
|
|
with two main differences:
|
|
.IP \[bu] 2
|
|
Budget goals and performance percentages are also shown, in brackets
|
|
.IP \[bu] 2
|
|
Accounts which don\[aq]t have budget goals are hidden by default.
|
|
.PP
|
|
This is useful for comparing planned and actual income, expenses, time
|
|
usage, etc.
|
|
.PP
|
|
Periodic transaction rules are used to define budget goals.
|
|
For example, here\[aq]s a periodic rule defining monthly goals for bus
|
|
travel and food expenses:
|
|
.IP
|
|
.EX
|
|
;; Budget
|
|
\[ti] monthly
|
|
(expenses:bus) $30
|
|
(expenses:food) $400
|
|
.EE
|
|
.PP
|
|
After recording some actual expenses,
|
|
.IP
|
|
.EX
|
|
;; Two months worth of expenses
|
|
2017\-11\-01
|
|
income $\-1950
|
|
expenses:bus $35
|
|
expenses:food:groceries $310
|
|
expenses:food:dining $42
|
|
expenses:movies $38
|
|
assets:bank:checking
|
|
|
|
2017\-12\-01
|
|
income $\-2100
|
|
expenses:bus $53
|
|
expenses:food:groceries $380
|
|
expenses:food:dining $32
|
|
expenses:gifts $100
|
|
assets:bank:checking
|
|
.EE
|
|
.PP
|
|
we can see a budget report like this:
|
|
.IP
|
|
.EX
|
|
$ hledger bal \-M \-\-budget
|
|
Budget performance in 2017\-11\-01..2017\-12\-31:
|
|
|
|
|| Nov Dec
|
|
===============++============================================
|
|
<unbudgeted> || $\-425 $\-565
|
|
expenses || $425 [ 99% of $430] $565 [131% of $430]
|
|
expenses:bus || $35 [117% of $30] $53 [177% of $30]
|
|
expenses:food || $352 [ 88% of $400] $412 [103% of $400]
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| 0 [ 0% of $430] 0 [ 0% of $430]
|
|
.EE
|
|
.PP
|
|
This is \[dq]goal\-based budgeting\[dq]; you define goals for accounts
|
|
and periods, often recurring, and hledger shows performance relative to
|
|
the goals.
|
|
This contrasts with \[dq]envelope budgeting\[dq], which is more detailed
|
|
and strict \- useful when cash is tight, but also quite a bit more work.
|
|
https://plaintextaccounting.org/Budgeting has more on this topic.
|
|
.SS Using the budget report
|
|
Historically this report has been confusing and fragile.
|
|
hledger\[aq]s version should be relatively robust and intuitive, but you
|
|
may still find surprises.
|
|
Here are more notes to help with learning and troubleshooting.
|
|
.IP \[bu] 2
|
|
In the above example, \f[CR]expenses:bus\f[R] and
|
|
\f[CR]expenses:food\f[R] are shown because they have budget goals during
|
|
the report period.
|
|
.IP \[bu] 2
|
|
Their parent \f[CR]expenses\f[R] is also shown, with budget goals
|
|
aggregated from the children.
|
|
.IP \[bu] 2
|
|
The subaccounts \f[CR]expenses:food:groceries\f[R] and
|
|
\f[CR]expenses:food:dining\f[R] are not shown since they have no budget
|
|
goal of their own, but they contribute to \f[CR]expenses:food\f[R]\[aq]s
|
|
actual amount.
|
|
.IP \[bu] 2
|
|
Unbudgeted accounts \f[CR]expenses:movies\f[R] and
|
|
\f[CR]expenses:gifts\f[R] are also not shown, but they contribute to
|
|
\f[CR]expenses\f[R]\[aq]s actual amount.
|
|
.IP \[bu] 2
|
|
The other unbudgeted accounts \f[CR]income\f[R] and
|
|
\f[CR]assets:bank:checking\f[R] are grouped as \f[CR]<unbudgeted>\f[R].
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-depth\f[R] or \f[CR]depth:\f[R] can be used to limit report
|
|
depth in the usual way (but will not reveal unbudgeted subaccounts).
|
|
.IP \[bu] 2
|
|
Amounts are always inclusive of subaccounts (even in
|
|
\f[CR]\-l/\-\-list\f[R] mode).
|
|
.IP \[bu] 2
|
|
Numbers displayed in a \-\-budget report will not always agree with the
|
|
totals, because of hidden unbudgeted accounts; this is normal.
|
|
\f[CR]\-E/\-\-empty\f[R] can be used to reveal the hidden accounts.
|
|
.IP \[bu] 2
|
|
In the periodic rules used for setting budget goals, unbalanced postings
|
|
are convenient.
|
|
.IP \[bu] 2
|
|
You can filter budget reports with the usual queries, eg to focus on
|
|
particular accounts.
|
|
It\[aq]s common to restrict them to just expenses.
|
|
(The \f[CR]<unbudgeted>\f[R] account is occasionally hard to exclude;
|
|
this is because of date surprises, discussed below.)
|
|
.IP \[bu] 2
|
|
When you have multiple currencies, you may want to convert them to one
|
|
(\f[CR]\-X COMM \-\-infer\-market\-prices\f[R]) and/or show just one at
|
|
a time (\f[CR]cur:COMM\f[R]).
|
|
If you do need to show multiple currencies at once,
|
|
\f[CR]\-\-layout bare\f[R] can be helpful.
|
|
.IP \[bu] 2
|
|
You can \[dq]roll over\[dq] amounts (actual and budgeted) to the next
|
|
period with \f[CR]\-\-cumulative\f[R].
|
|
.PP
|
|
See also: https://hledger.org/budgeting.html.
|
|
.SS Budget date surprises
|
|
With small data, or when starting out, some of the generated budget goal
|
|
transaction dates might fall outside the report periods.
|
|
Eg with the following journal and report, the first period appears to
|
|
have no \f[CR]expenses:food\f[R] budget.
|
|
(Also the \f[CR]<unbudgeted>\f[R] account should be excluded by the
|
|
\f[CR]expenses\f[R] query, but isn\[aq]t.):
|
|
.IP
|
|
.EX
|
|
\[ti] monthly in 2020
|
|
(expenses:food) $500
|
|
|
|
2020\-01\-15
|
|
expenses:food $400
|
|
assets:checking
|
|
.EE
|
|
.IP
|
|
.EX
|
|
$ hledger bal \-\-budget expenses
|
|
Budget performance in 2020\-01\-15:
|
|
|
|
|| 2020\-01\-15
|
|
===============++====================
|
|
<unbudgeted> || $400
|
|
expenses:food || 0 [ 0% of $500]
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $400 [80% of $500]
|
|
.EE
|
|
.PP
|
|
In this case, the budget goal transactions are generated on first days
|
|
of of month (this can be seen with
|
|
\f[CR]hledger print \-\-forecast tag:generated expenses\f[R]).
|
|
Whereas the report period defaults to just the 15th day of january (this
|
|
can be seen from the report table\[aq]s column headings).
|
|
.PP
|
|
To fix this kind of thing, be more explicit about the report period
|
|
(and/or the periodic rules\[aq] dates).
|
|
In this case, adding \f[CR]\-b 2020\f[R] does the trick.
|
|
.SS Selecting budget goals
|
|
By default, the budget report uses all available periodic transaction
|
|
rules to generate goals.
|
|
This includes rules with a different report interval from your report.
|
|
Eg if you have daily, weekly and monthly periodic rules, all of these
|
|
will contribute to the goals in a monthly budget report.
|
|
.PP
|
|
You can select a subset of periodic rules by providing an argument to
|
|
the \f[CR]\-\-budget\f[R] flag.
|
|
\f[CR]\-\-budget=DESCPAT\f[R] will match all periodic rules whose
|
|
description contains DESCPAT, a case\-insensitive substring (not a
|
|
regular expression or query).
|
|
This means you can give your periodic rules descriptions (remember that
|
|
two spaces are needed between period expression and description), and
|
|
then select from multiple budgets defined in your journal.
|
|
.SS Budgeting vs forecasting
|
|
\f[CR]\-\-forecast\f[R] and \f[CR]\-\-budget\f[R] both use the periodic
|
|
transaction rules in the journal to generate temporary transactions for
|
|
reporting purposes.
|
|
However they are separate features \- though you can use both at the
|
|
same time if you want.
|
|
Here are some differences between them:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(38.2n) lw(31.8n).
|
|
T{
|
|
\-\-forecast
|
|
T}@T{
|
|
\-\-budget
|
|
T}
|
|
_
|
|
T{
|
|
is a general option; it enables forecasting with all reports
|
|
T}@T{
|
|
is a balance command option; it selects the balance report\[aq]s budget
|
|
mode
|
|
T}
|
|
T{
|
|
generates visible transactions which appear in reports
|
|
T}@T{
|
|
generates invisible transactions which produce goal amounts
|
|
T}
|
|
T{
|
|
generates forecast transactions from after the last regular transaction,
|
|
to the end of the report period; or with an argument
|
|
\f[CR]\-\-forecast=PERIODEXPR\f[R] generates them throughout the
|
|
specified period, both optionally restricted by periods specified in the
|
|
periodic transaction rules
|
|
T}@T{
|
|
generates budget goal transactions throughout the report period,
|
|
optionally restricted by periods specified in the periodic transaction
|
|
rules
|
|
T}
|
|
T{
|
|
uses all periodic rules
|
|
T}@T{
|
|
uses all periodic rules; or with an argument
|
|
\f[CR]\-\-budget=DESCPAT\f[R] uses just the rules matched by DESCPAT
|
|
T}
|
|
.TE
|
|
.SS Balance report layout
|
|
The \f[CR]\-\-layout\f[R] option affects how \f[CR]balance\f[R] and the
|
|
other balance\-like commands show multi\-commodity amounts and commodity
|
|
symbols.
|
|
It can improve readability, for humans and/or machines (other software).
|
|
It has four possible values:
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-layout=wide[,WIDTH]\f[R]: commodities are shown on a single
|
|
line, optionally elided to WIDTH
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-layout=tall\f[R]: each commodity is shown on a separate line
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-layout=bare\f[R]: commodity symbols are in their own column,
|
|
amounts are bare numbers
|
|
.IP \[bu] 2
|
|
\f[CR]\-\-layout=tidy\f[R]: data is normalised to easily\-consumed
|
|
\[dq]tidy\[dq] form, with one row per data value.
|
|
(This one is currently supported only by the \f[CR]balance\f[R]
|
|
command.)
|
|
.PP
|
|
Here are the \f[CR]\-\-layout\f[R] modes supported by each output format
|
|
Only CSV output supports all of them:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l l l l l.
|
|
T{
|
|
\-
|
|
T}@T{
|
|
txt
|
|
T}@T{
|
|
csv
|
|
T}@T{
|
|
html
|
|
T}@T{
|
|
json
|
|
T}@T{
|
|
sql
|
|
T}
|
|
_
|
|
T{
|
|
wide
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
tall
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
bare
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
T{
|
|
tidy
|
|
T}@T{
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
T}@T{
|
|
T}
|
|
.TE
|
|
.PP
|
|
Examples:
|
|
.SS Wide layout
|
|
With many commodities, reports can be very wide:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=wide
|
|
Balance changes in 2012\-01\-01..2014\-12\-31:
|
|
|
|
|| 2012 2013 2014 Total
|
|
==================++====================================================================================================================================================================================================================
|
|
Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, \-98.12 USD, 10.00 VEA, 18.00 VHT \-11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, \-98.12 USD, 10.00 VEA, 18.00 VHT \-11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
|
|
.EE
|
|
.PP
|
|
A width limit reduces the width, but some commodities will be hidden:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=wide,32
|
|
Balance changes in 2012\-01\-01..2014\-12\-31:
|
|
|
|
|| 2012 2013 2014 Total
|
|
==================++===========================================================================================================================
|
|
Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. \-11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. \-11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more..
|
|
.EE
|
|
.SS Tall layout
|
|
Each commodity gets a new line (may be different in each column), and
|
|
account names are repeated:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=tall
|
|
Balance changes in 2012\-01\-01..2014\-12\-31:
|
|
|
|
|| 2012 2013 2014 Total
|
|
==================++==================================================
|
|
Assets:US:ETrade || 10.00 ITOT 70.00 GLD \-11.00 ITOT 70.00 GLD
|
|
Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
|
|
Assets:US:ETrade || 12.00 VEA \-98.12 USD 14.00 VEA 5120.50 USD
|
|
Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
|
|
Assets:US:ETrade || 18.00 VHT 294.00 VHT
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| 10.00 ITOT 70.00 GLD \-11.00 ITOT 70.00 GLD
|
|
|| 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
|
|
|| 12.00 VEA \-98.12 USD 14.00 VEA 5120.50 USD
|
|
|| 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
|
|
|| 18.00 VHT 294.00 VHT
|
|
.EE
|
|
.SS Bare layout
|
|
Commodity symbols are kept in one column, each commodity has its own
|
|
row, amounts are bare numbers, account names are repeated:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-T \-Y \-\-layout=bare
|
|
Balance changes in 2012\-01\-01..2014\-12\-31:
|
|
|
|
|| Commodity 2012 2013 2014 Total
|
|
==================++=============================================
|
|
Assets:US:ETrade || GLD 0 70.00 0 70.00
|
|
Assets:US:ETrade || ITOT 10.00 18.00 \-11.00 17.00
|
|
Assets:US:ETrade || USD 337.18 \-98.12 4881.44 5120.50
|
|
Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00
|
|
Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| GLD 0 70.00 0 70.00
|
|
|| ITOT 10.00 18.00 \-11.00 17.00
|
|
|| USD 337.18 \-98.12 4881.44 5120.50
|
|
|| VEA 12.00 10.00 14.00 36.00
|
|
|| VHT 106.00 18.00 170.00 294.00
|
|
.EE
|
|
.PP
|
|
Bare layout also affects CSV output, which is useful for producing data
|
|
that is easier to consume, eg for making charts:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-O csv \-\-layout=bare
|
|
\[dq]account\[dq],\[dq]commodity\[dq],\[dq]balance\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]ITOT\[dq],\[dq]17.00\[dq]
|
|
\[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]
|
|
.EE
|
|
.PP
|
|
Bare layout will sometimes display an extra row for the no\-symbol
|
|
commodity, because of zero amounts (hledger treats zeroes as
|
|
commodity\-less, usually).
|
|
This can break \f[CR]hledger\-bar\f[R] confusingly (workaround: add a
|
|
\f[CR]cur:\f[R] query to exclude the no\-symbol row).
|
|
.SS Tidy layout
|
|
This produces normalised \[dq]tidy data\[dq] (see
|
|
https://cran.r\-project.org/web/packages/tidyr/vignettes/tidy\-data.html)
|
|
where every variable has its own column and each row represents a single
|
|
data point.
|
|
This is the easiest kind of data for other software to consume:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f examples/bcexample.hledger bal assets:us:etrade \-3 \-Y \-O csv \-\-layout=tidy
|
|
\[dq]account\[dq],\[dq]period\[dq],\[dq]start_date\[dq],\[dq]end_date\[dq],\[dq]commodity\[dq],\[dq]value\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]GLD\[dq],\[dq]0\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]ITOT\[dq],\[dq]10.00\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]USD\[dq],\[dq]337.18\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]VEA\[dq],\[dq]12.00\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2012\[dq],\[dq]2012\-01\-01\[dq],\[dq]2012\-12\-31\[dq],\[dq]VHT\[dq],\[dq]106.00\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]GLD\[dq],\[dq]70.00\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]ITOT\[dq],\[dq]18.00\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]USD\[dq],\[dq]\-98.12\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]VEA\[dq],\[dq]10.00\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2013\[dq],\[dq]2013\-01\-01\[dq],\[dq]2013\-12\-31\[dq],\[dq]VHT\[dq],\[dq]18.00\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]GLD\[dq],\[dq]0\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]ITOT\[dq],\[dq]\-11.00\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]USD\[dq],\[dq]4881.44\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]VEA\[dq],\[dq]14.00\[dq]
|
|
\[dq]Assets:US:ETrade\[dq],\[dq]2014\[dq],\[dq]2014\-01\-01\[dq],\[dq]2014\-12\-31\[dq],\[dq]VHT\[dq],\[dq]170.00\[dq]
|
|
.EE
|
|
.SS Balance report output
|
|
As noted in Output format, if you choose HTML output (by using
|
|
\f[CR]\-O html\f[R] or \f[CR]\-o somefile.html\f[R]), you can create a
|
|
\f[CR]hledger.css\f[R] file in the same directory to customise the
|
|
report\[aq]s appearance.
|
|
.PP
|
|
The HTML and FODS output formats can generate hyperlinks to a
|
|
\f[CR]hledger\-web\f[R] register view for each account and period.
|
|
E.g.
|
|
if your \f[CR]hledger\-web\f[R] server is reachable at
|
|
\f[CR]http://localhost:5000\f[R] then you might run the
|
|
\f[CR]balance\f[R] command with the extra option
|
|
\f[CR]\-\-base\-url=http://localhost:5000\f[R].
|
|
You can also produce relative links, like
|
|
\f[CR]\-\-base\-url=\[dq]some/path\[dq]\f[R] or
|
|
\f[CR]\-\-base\-url=\[dq]\[dq]\f[R].)
|
|
.SS Some useful balance reports
|
|
Some frequently used \f[CR]balance\f[R] options/reports are:
|
|
.IP \[bu] 2
|
|
\f[CR]bal \-M revenues expenses\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Show revenues/expenses in each month.
|
|
Also available as the \f[CR]incomestatement\f[R] command.
|
|
.IP \[bu] 2
|
|
\f[CR]bal \-M \-H assets liabilities\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Show historical asset/liability balances at each month end.
|
|
Also available as the \f[CR]balancesheet\f[R] command.
|
|
.IP \[bu] 2
|
|
\f[CR]bal \-M \-H assets liabilities equity\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Show historical asset/liability/equity balances at each month end.
|
|
Also available as the \f[CR]balancesheetequity\f[R] command.
|
|
.IP \[bu] 2
|
|
\f[CR]bal \-M assets not:receivable\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Show changes to liquid assets in each month.
|
|
Also available as the \f[CR]cashflow\f[R] command.
|
|
.PP
|
|
Also:
|
|
.IP \[bu] 2
|
|
\f[CR]bal \-M expenses \-2 \-SA\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Show monthly expenses summarised to depth 2 and sorted by average
|
|
amount.
|
|
.IP \[bu] 2
|
|
\f[CR]bal \-M \-\-budget expenses\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Show monthly expenses and budget goals.
|
|
.IP \[bu] 2
|
|
\f[CR]bal \-M \-\-valuechange investments\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Show monthly change in market value of investment assets.
|
|
.IP \[bu] 2
|
|
\f[CR]bal investments \-\-valuechange \-D date:lastweek amt:\[aq]>1000\[aq] \-STA [\-\-invert]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Show top gainers [or losers] last week
|
|
.SS roi
|
|
Shows the time\-weighted (TWR) and money\-weighted (IRR) rate of return
|
|
on your investments.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-cashflow show all amounts that were used to compute
|
|
returns
|
|
\-\-investment=QUERY query to select your investment transactions
|
|
\-\-profit\-loss=QUERY \-\-pnl query to select profit\-and\-loss or
|
|
appreciation/valuation transactions
|
|
.EE
|
|
.PP
|
|
At a minimum, you need to supply a query (which could be just an account
|
|
name) to select your investment(s) with \f[CR]\-\-inv\f[R], and another
|
|
query to identify your profit and loss transactions with
|
|
\f[CR]\-\-pnl\f[R].
|
|
.PP
|
|
If you do not record changes in the value of your investment manually,
|
|
or do not require computation of time\-weighted return (TWR),
|
|
\f[CR]\-\-pnl\f[R] could be an empty query
|
|
(\f[CR]\-\-pnl \[dq]\[dq]\f[R] or \f[CR]\-\-pnl STR\f[R] where
|
|
\f[CR]STR\f[R] does not match any of your accounts).
|
|
.PP
|
|
This command will compute and display the internalized rate of return
|
|
(IRR, also known as money\-weighted rate of return) and time\-weighted
|
|
rate of return (TWR) for your investments for the time period requested.
|
|
IRR is always annualized due to the way it is computed, but TWR is
|
|
reported both as a rate over the chosen reporting period and as an
|
|
annual rate.
|
|
.PP
|
|
Price directives will be taken into account if you supply appropriate
|
|
\f[CR]\-\-cost\f[R] or \f[CR]\-\-value\f[R] flags (see VALUATION).
|
|
.PP
|
|
Note, in some cases this report can fail, for these reasons:
|
|
.IP \[bu] 2
|
|
Error (NotBracketed): No solution for Internal Rate of Return (IRR).
|
|
Possible causes: IRR is huge (>1000000%), balance of investment becomes
|
|
negative at some point in time.
|
|
.IP \[bu] 2
|
|
Error (SearchFailed): Failed to find solution for Internal Rate of
|
|
Return (IRR).
|
|
Either search does not converge to a solution, or converges too slowly.
|
|
.PP
|
|
Examples:
|
|
.IP \[bu] 2
|
|
Using roi to compute total return of investment in stocks:
|
|
https://github.com/simonmichael/hledger/blob/master/examples/investing/roi\-unrealised.ledger
|
|
.IP \[bu] 2
|
|
Cookbook > Return on Investment: https://hledger.org/roi.html
|
|
.SS Spaces and special characters in \f[CR]\-\-inv\f[R] and \f[CR]\-\-pnl\f[R]
|
|
Note that \f[CR]\-\-inv\f[R] and \f[CR]\-\-pnl\f[R]\[aq]s argument is a
|
|
query, and queries could have several space\-separated terms (see
|
|
QUERIES).
|
|
.PP
|
|
To indicate that all search terms form single command\-line argument,
|
|
you will need to put them in quotes (see Special characters):
|
|
.IP
|
|
.EX
|
|
$ hledger roi \-\-inv \[aq]term1 term2 term3 ...\[aq]
|
|
.EE
|
|
.PP
|
|
If any query terms contain spaces themselves, you will need an extra
|
|
level of nested quoting, eg:
|
|
.IP
|
|
.EX
|
|
$ hledger roi \-\-inv=\[dq]\[aq]Assets:Test 1\[aq]\[dq] \-\-pnl=\[dq]\[aq]Equity:Unrealized Profit and Loss\[aq]\[dq]
|
|
.EE
|
|
.SS Semantics of \f[CR]\-\-inv\f[R] and \f[CR]\-\-pnl\f[R]
|
|
Query supplied to \f[CR]\-\-inv\f[R] has to match all transactions that
|
|
are related to your investment.
|
|
Transactions not matching \f[CR]\-\-inv\f[R] will be ignored.
|
|
.PP
|
|
In these transactions, ROI will conside postings that match
|
|
\f[CR]\-\-inv\f[R] to be \[dq]investment postings\[dq] and other
|
|
postings (not matching \f[CR]\-\-inv\f[R]) will be sorted into two
|
|
categories: \[dq]cash flow\[dq] and \[dq]profit and loss\[dq], as ROI
|
|
needs to know which part of the investment value is your contributions
|
|
and which is due to the return on investment.
|
|
.IP \[bu] 2
|
|
\[dq]Cash flow\[dq] is depositing or withdrawing money, buying or
|
|
selling assets, or otherwise converting between your investment
|
|
commodity and any other commodity.
|
|
Example:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
2019\-01\-01 Investing in Snake Oil
|
|
assets:cash \-$100
|
|
investment:snake oil
|
|
|
|
2020\-01\-01 Selling my Snake Oil
|
|
assets:cash $10
|
|
investment:snake oil = 0
|
|
.EE
|
|
.RE
|
|
.IP \[bu] 2
|
|
\[dq]Profit and loss\[dq] is change in the value of your investment:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
2019\-06\-01 Snake Oil falls in value
|
|
investment:snake oil = $57
|
|
equity:unrealized profit or loss
|
|
.EE
|
|
.RE
|
|
.PP
|
|
All non\-investment postings are assumed to be \[dq]cash flow\[dq],
|
|
unless they match \f[CR]\-\-pnl\f[R] query.
|
|
Changes in value of your investment due to \[dq]profit and loss\[dq]
|
|
postings will be considered as part of your investment return.
|
|
.PP
|
|
Example: if you use \f[CR]\-\-inv snake \-\-pnl equity:unrealized\f[R],
|
|
then postings in the example below would be classifed as:
|
|
.IP
|
|
.EX
|
|
2019\-01\-01 Snake Oil #1
|
|
assets:cash \-$100 ; cash flow posting
|
|
investment:snake oil ; investment posting
|
|
|
|
2019\-03\-01 Snake Oil #2
|
|
equity:unrealized pnl \-$100 ; profit and loss posting
|
|
snake oil ; investment posting
|
|
|
|
2019\-07\-01 Snake Oil #3
|
|
equity:unrealized pnl ; profit and loss posting
|
|
cash \-$100 ; cash flow posting
|
|
snake oil $50 ; investment posting
|
|
.EE
|
|
.SS IRR and TWR explained
|
|
\[dq]ROI\[dq] stands for \[dq]return on investment\[dq].
|
|
Traditionally this was computed as a difference between current value of
|
|
investment and its initial value, expressed in percentage of the initial
|
|
value.
|
|
.PP
|
|
However, this approach is only practical in simple cases, where
|
|
investments receives no in\-flows or out\-flows of money, and where rate
|
|
of growth is fixed over time.
|
|
For more complex scenarios you need different ways to compute rate of
|
|
return, and this command implements two of them: IRR and TWR.
|
|
.PP
|
|
Internal rate of return, or \[dq]IRR\[dq] (also called
|
|
\[dq]money\-weighted rate of return\[dq]) takes into account effects of
|
|
in\-flows and out\-flows, and the time between them.
|
|
Investment at a particular fixed interest rate is going to give you more
|
|
interest than the same amount invested at the same interest rate, but
|
|
made later in time.
|
|
If you are withdrawing from your investment, your future gains would be
|
|
smaller (in absolute numbers), and will be a smaller percentage of your
|
|
initial investment, so your IRR will be smaller.
|
|
And if you are adding to your investment, you will receive bigger
|
|
absolute gains, which will be a bigger percentage of your initial
|
|
investment, so your IRR will be larger.
|
|
.PP
|
|
As mentioned before, in\-flows and out\-flows would be any cash that you
|
|
personally put in or withdraw, and for the \[dq]roi\[dq] command, these
|
|
are the postings that match the query in the\f[CR]\-\-inv\f[R] argument
|
|
and NOT match the query in the\f[CR]\-\-pnl\f[R] argument.
|
|
.PP
|
|
If you manually record changes in the value of your investment as
|
|
transactions that balance them against \[dq]profit and loss\[dq] (or
|
|
\[dq]unrealized gains\[dq]) account or use price directives, then in
|
|
order for IRR to compute the precise effect of your in\-flows and
|
|
out\-flows on the rate of return, you will need to record the value of
|
|
your investement on or close to the days when in\- or out\-flows occur.
|
|
.PP
|
|
In technical terms, IRR uses the same approach as computation of net
|
|
present value, and tries to find a discount rate that makes net present
|
|
value of all the cash flows of your investment to add up to zero.
|
|
This could be hard to wrap your head around, especially if you
|
|
haven\[aq]t done discounted cash flow analysis before.
|
|
Implementation of IRR in hledger should produce results that match the
|
|
\f[CR]=XIRR\f[R] formula in Excel.
|
|
.PP
|
|
Second way to compute rate of return that \f[CR]roi\f[R] command
|
|
implements is called \[dq]time\-weighted rate of return\[dq] or
|
|
\[dq]TWR\[dq].
|
|
Like IRR, it will account for the effect of your in\-flows and
|
|
out\-flows, but unlike IRR it will try to compute the true rate of
|
|
return of the underlying asset, compensating for the effect that
|
|
deposits and withdrawas have on the apparent rate of growth of your
|
|
investment.
|
|
.PP
|
|
TWR represents your investment as an imaginary \[dq]unit fund\[dq] where
|
|
in\-flows/ out\-flows lead to buying or selling \[dq]units\[dq] of your
|
|
investment and changes in its value change the value of \[dq]investment
|
|
unit\[dq].
|
|
Change in \[dq]unit price\[dq] over the reporting period gives you rate
|
|
of return of your investment, and make TWR less sensitive than IRR to
|
|
the effects of cash in\-flows and out\-flows.
|
|
.PP
|
|
References:
|
|
.IP \[bu] 2
|
|
Explanation of rate of return
|
|
.IP \[bu] 2
|
|
Explanation of IRR
|
|
.IP \[bu] 2
|
|
Explanation of TWR
|
|
.IP \[bu] 2
|
|
IRR vs TWR
|
|
.IP \[bu] 2
|
|
Examples of computing IRR and TWR and discussion of the limitations of
|
|
both metrics
|
|
.SH Chart commands
|
|
.SS activity
|
|
Show an ascii barchart of posting counts per interval.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.PP
|
|
The activity command displays an ascii histogram showing transaction
|
|
counts by day, week, month or other reporting interval (by day is the
|
|
default).
|
|
With query arguments, it counts only matched transactions.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
$ hledger activity \-\-quarterly
|
|
2008\-01\-01 **
|
|
2008\-04\-01 *******
|
|
2008\-07\-01
|
|
2008\-10\-01 **
|
|
.EE
|
|
.SH Data generation commands
|
|
.SS close
|
|
(equity)
|
|
.PP
|
|
\f[CR]close\f[R] prints several kinds of \[dq]closing\[dq] and/or
|
|
\[dq]opening\[dq] transactions, useful in various situations: migrating
|
|
balances to a new journal file, retaining earnings into equity,
|
|
consolidating balances, viewing lot costs..
|
|
Like \f[CR]print\f[R], it prints valid journal entries.
|
|
You can copy these into your journal file(s) when you are happy with how
|
|
they look.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-clopen[=TAGVAL] show closing and opening balances transactions,
|
|
for AL accounts by default
|
|
\-\-close[=TAGVAL] show just a closing balances transaction
|
|
\-\-open[=TAGVAL] show just an opening balances transaction
|
|
\-\-assert[=TAGVAL] show a balance assertions transaction
|
|
\-\-assign[=TAGVAL] show a balance assignments transaction
|
|
\-\-retain[=TAGVAL] show a retain earnings transaction, for RX
|
|
accounts by default
|
|
\-x \-\-explicit show all amounts explicitly
|
|
\-\-show\-costs show amounts with different costs separately
|
|
\-\-interleaved show source and destination postings together
|
|
\-\-assertion\-type=TYPE =, ==, =* or ==*
|
|
\-\-close\-desc=DESC set closing transaction\[aq]s description
|
|
\-\-close\-acct=ACCT set closing transaction\[aq]s destination account
|
|
\-\-open\-desc=DESC set opening transaction\[aq]s description
|
|
\-\-open\-acct=ACCT set opening transaction\[aq]s source account
|
|
\-\-round=TYPE how much rounding or padding should be done when
|
|
displaying amounts ?
|
|
none \- show original decimal digits,
|
|
as in journal (default)
|
|
soft \- just add or remove decimal zeros
|
|
to match precision
|
|
hard \- round posting amounts to precision
|
|
(can unbalance transactions)
|
|
all \- also round cost amounts to precision
|
|
(can unbalance transactions)
|
|
.EE
|
|
.PP
|
|
\f[CR]close\f[R] has six modes, selected by choosing one of the mode
|
|
flags: \f[CR]\-\-clopen\f[R], \f[CR]\-\-close\f[R] (default),
|
|
\f[CR]\-\-open\f[R], \f[CR]\-\-assert\f[R], \f[CR]\-\-assign\f[R], or
|
|
\f[CR]\-\-retain\f[R].
|
|
They are all doing the same kind of operation, but with different
|
|
defaults for different situations.
|
|
.PP
|
|
The journal entries generated by \f[CR]close\f[R] will have a
|
|
\f[CR]clopen:\f[R] tag, which is helpful when you want to exclude them
|
|
from reports.
|
|
If the main journal file name contains a number, the tag\[aq]s value
|
|
will be that base file name with the number incremented.
|
|
Eg if the journal file is 2025.journal, the tag will be
|
|
\f[CR]clopen:2026\f[R].
|
|
Or you can set the tag value by providing an argument to the mode flag.
|
|
Eg \f[CR]\-\-close=foo\f[R] or \f[CR]\-\-clopen=2025\-main\f[R].
|
|
.SS close \-\-clopen
|
|
This is useful if migrating balances to a new journal file at the start
|
|
of a new year.
|
|
It prints a \[dq]closing balances\[dq] transaction that zeroes out
|
|
account balances (Asset and Liability accounts, by default), and an
|
|
opposite \[dq]opening balances\[dq] transaction that restores them
|
|
again.
|
|
Typically, you would run
|
|
.IP
|
|
.EX
|
|
hledger close \-\-clopen \-e NEWYEAR >> $LEDGER_FILE
|
|
.EE
|
|
.PP
|
|
and then move the opening transaction from the old file to the new file
|
|
(and probably also update your LEDGER_FILE environment variable).
|
|
.PP
|
|
Why might you do this ?
|
|
If your reports are fast, you may not need it.
|
|
But at some point you will probably want to partition your data by time,
|
|
for performance or data integrity or regulatory reasons.
|
|
A new file or set of files per year is common.
|
|
Then, having each file/fileset \[dq]bookended\[dq] with opening and
|
|
closing balance transactions will allow you to freely pick and choose
|
|
which files to read \- just the current year, any past year, any
|
|
sequence of years, or all of them \- while showing correct account
|
|
balances in each case.
|
|
The earliest opening balances transaction sets correct starting
|
|
balances, and any later closing/opening pairs will harmlessly cancel
|
|
each other out.
|
|
.PP
|
|
The balances will be transferred to and from
|
|
\f[CR]equity:opening/closing balances\f[R] by default.
|
|
You can override this by using \f[CR]\-\-close\-acct\f[R] and/or
|
|
\f[CR]\-\-open\-acct\f[R].
|
|
.PP
|
|
You can select a different set of accounts to close/open by providing an
|
|
account query.
|
|
Eg to add Equity accounts, provide arguments like
|
|
\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R].
|
|
When migrating to a new file, you\[aq]ll usually want to bring along the
|
|
AL or ALE accounts, but not the RX accounts (Revenue, Expense).
|
|
.PP
|
|
Assertions will be added indicating and checking the new balances of the
|
|
closed/opened accounts.
|
|
.SS close \-\-close
|
|
This prints just the closing balances transaction of
|
|
\f[CR]\-\-clopen\f[R].
|
|
It is the default if you don\[aq]t specify a mode.
|
|
.PP
|
|
More customisation options are described below.
|
|
Among other things, you can use \f[CR]close \-\-close\f[R] to generate a
|
|
transaction moving the balances from any set of accounts, to a different
|
|
account.
|
|
(If you need to move just a portion of the balance, see hledger\-move.)
|
|
.SS close \-\-open
|
|
This prints just the opening balances transaction of
|
|
\f[CR]\-\-clopen\f[R].
|
|
(It is similar to Ledger\[aq]s equity command.)
|
|
.SS close \-\-assert
|
|
This prints a transaction that asserts the account balances as they are
|
|
on the end date (and adds an \f[CR]assert:\f[R] tag).
|
|
It could be useful as documention and to guard against changes.
|
|
.SS close \-\-assign
|
|
This prints a transaction that assigns the account balances as they are
|
|
on the end date (and adds an \[dq]assign:\[dq] tag).
|
|
Unlike balance assertions, assignments will post changes to balances as
|
|
needed to reach the specified amounts.
|
|
.PP
|
|
This is another way to set starting balances when migrating to a new
|
|
file, and it will set them correctly even in the presence of earlier
|
|
files which do not have a closing balances transaction.
|
|
However, it can hide errors, and disturb the accounting equation, so
|
|
\f[CR]\-\-clopen\f[R] is usually recommended.
|
|
.SS close \-\-retain
|
|
This is like \f[CR]\-\-close\f[R], but it closes Revenue and Expense
|
|
account balances by default.
|
|
They will be transferred to \f[CR]equity:retained earnings\f[R], or
|
|
another account specified with \f[CR]\-\-close\-acct\f[R].
|
|
.PP
|
|
Revenues and expenses correspond to changes in equity.
|
|
They are categorised separately for reporting purposes, but
|
|
traditionally at the end of each accounting period, businesses
|
|
consolidate them into equity, This is called \[dq]retaining
|
|
earnings\[dq], or \[dq]closing the books\[dq].
|
|
.PP
|
|
In personal accounting, there\[aq]s not much reason to do this, and most
|
|
people don\[aq]t.
|
|
(One reason to do it is to help the \f[CR]balancesheetequity\f[R] report
|
|
show a zero total, demonstrating that the accounting equation (A\-L=E)
|
|
is satisfied.)
|
|
.SS close customisation
|
|
In all modes, the following things can be overridden:
|
|
.IP \[bu] 2
|
|
the accounts to be closed/opened, with account query arguments
|
|
.IP \[bu] 2
|
|
the closing/opening dates, with \f[CR]\-e OPENDATE\f[R]
|
|
.IP \[bu] 2
|
|
the balancing account, with \f[CR]\-\-close\-acct=ACCT\f[R] and/or
|
|
\f[CR]\-\-open\-acct=ACCT\f[R]
|
|
.IP \[bu] 2
|
|
the transaction descriptions, with \f[CR]\-\-close\-desc=DESC\f[R] and
|
|
\f[CR]\-\-open\-desc=DESC\f[R]
|
|
.IP \[bu] 2
|
|
the transactions\[aq] \f[CR]clopen\f[R] tag value, with a
|
|
\f[CR]TAGVAL\f[R] argument for the mode flag (see above).
|
|
.PP
|
|
By default, the closing date is yesterday, or the journal\[aq]s end
|
|
date, whichever is later; and the opening date is always one day after
|
|
the closing date.
|
|
You can change these by specifying a report end date; the closing date
|
|
will be the last day of the report period.
|
|
Eg \f[CR]\-e 2024\f[R] means \[dq]close on 2023\-12\-31, open on
|
|
2024\-01\-01\[dq].
|
|
.PP
|
|
With \f[CR]\-\-x/\-\-explicit\f[R], the balancing amount will be shown
|
|
explicitly, and if it involves multiple commodities, a separate posting
|
|
will be generated for each of them (similar to \f[CR]print \-x\f[R]).
|
|
.PP
|
|
With \f[CR]\-\-interleaved\f[R], each individual transfer is shown with
|
|
source and destination postings next to each other (perhaps useful for
|
|
troubleshooting).
|
|
.PP
|
|
With \f[CR]\-\-show\-costs\f[R], balances\[aq] costs are also shown,
|
|
with different costs kept separate.
|
|
This may generate very large journal entries, if you have many currency
|
|
conversions or investment transactions.
|
|
\f[CR]close \-\-show\-costs\f[R] is currently the best way to view
|
|
investment lots with hledger.
|
|
(To move or dispose of lots, see the more capable
|
|
\f[CR]hledger\-move\f[R] script.)
|
|
.SS close and balance assertions
|
|
\f[CR]close\f[R] adds balance assertions verifying that the accounts
|
|
have been reset to zero in a closing transaction or restored to their
|
|
previous balances in an opening transaction.
|
|
These provide useful error checking, but you can ignore them temporarily
|
|
with \f[CR]\-I\f[R], or remove them if you prefer.
|
|
.PP
|
|
Single\-commodity, subaccount\-exclusive balance assertions
|
|
(\f[CR]=\f[R]) are generated by default.
|
|
This can be changed with \f[CR]\-\-assertion\-type=\[aq]==*\[aq]\f[R]
|
|
(eg).
|
|
.PP
|
|
When running \f[CR]close\f[R] you should probably avoid using
|
|
\f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R] (filtering by status
|
|
or realness) or \f[CR]\-\-auto\f[R] (generating postings), since the
|
|
generated balance assertions would then require these.
|
|
.PP
|
|
Transactions with multiple dates (eg posting dates) spanning the file
|
|
boundary also can disrupt the balance assertions:
|
|
.IP
|
|
.EX
|
|
2023\-12\-30 a purchase made in december, cleared in january
|
|
expenses:food 5
|
|
assets:bank:checking \-5 ; date: 2023\-01\-02
|
|
.EE
|
|
.PP
|
|
To solve this you can transfer the money to and from a temporary
|
|
account, splitting the multi\-day transaction into two single\-day
|
|
transactions:
|
|
.IP
|
|
.EX
|
|
; in 2022.journal:
|
|
2022\-12\-30 a purchase made in december, cleared in january
|
|
expenses:food 5
|
|
equity:pending \-5
|
|
|
|
; in 2023.journal:
|
|
2023\-01\-02 last year\[aq]s transaction cleared
|
|
equity:pending 5 = 0
|
|
assets:bank:checking \-5
|
|
.EE
|
|
.SS close examples
|
|
.SS Retain earnings
|
|
Record 2022\[aq]s revenues/expenses as retained earnings on
|
|
2022\-12\-31, appending the generated transaction to the journal:
|
|
.IP
|
|
.EX
|
|
$ hledger close \-\-retain \-f 2022.journal \-p 2022 >> 2022.journal
|
|
.EE
|
|
.PP
|
|
After this, to see 2022\[aq]s revenues and expenses you must exclude the
|
|
retain earnings transaction:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f 2022.journal is not:desc:\[aq]retain earnings\[aq]
|
|
.EE
|
|
.SS Migrate balances to a new file
|
|
Close assets/liabilities on 2022\-12\-31 and re\-open them on
|
|
2023\-01\-01:
|
|
.IP
|
|
.EX
|
|
$ hledger close \-\-clopen \-f 2022.journal \-p 2022
|
|
# copy/paste the closing transaction to the end of 2022.journal
|
|
# copy/paste the opening transaction to the start of 2023.journal
|
|
.EE
|
|
.PP
|
|
After this, to see 2022\[aq]s end\-of\-year balances you must exclude
|
|
the closing balances transaction:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f 2022.journal bs not:desc:\[aq]closing balances\[aq]
|
|
.EE
|
|
.PP
|
|
For more flexibility, it helps to tag closing and opening transactions
|
|
with eg \f[CR]clopen:NEWYEAR\f[R], then you can ensure correct balances
|
|
by excluding all opening/closing transactions except the first, like so:
|
|
.IP
|
|
.EX
|
|
$ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]
|
|
$ hledger bs \-Y \-f 2021.j \-f 2022.j expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]
|
|
$ hledger bs \-Y \-f 2022.j \-f 2023.j expr:\[aq]tag:clopen=2022 or not tag:clopen\[aq]
|
|
$ hledger bs \-Y \-f 2021.j expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]
|
|
$ hledger bs \-Y \-f 2022.j expr:\[aq]tag:clopen=2022 or not tag:clopen\[aq]
|
|
$ hledger bs \-Y \-f 2023.j # unclosed file, no query needed
|
|
.EE
|
|
.SS More detailed close examples
|
|
See examples/multi\-year.
|
|
.SS rewrite
|
|
Print all transactions, rewriting the postings of matched transactions.
|
|
For now the only rewrite available is adding new postings, like print
|
|
\-\-auto.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
\-\-add\-posting=\[aq]ACCT AMTEXPR\[aq] add a posting to ACCT, which may be
|
|
parenthesised. AMTEXPR is either a literal
|
|
amount, or *N which means the transaction\[aq]s
|
|
first matched amount multiplied by N (a
|
|
decimal number). Two spaces separate ACCT
|
|
and AMTEXPR.
|
|
\-\-diff generate diff suitable as an input for
|
|
patch tool
|
|
.EE
|
|
.PP
|
|
This is a start at a generic rewriter of transaction entries.
|
|
It reads the default journal and prints the transactions, like print,
|
|
but adds one or more specified postings to any transactions matching
|
|
QUERY.
|
|
The posting amounts can be fixed, or a multiplier of the existing
|
|
transaction\[aq]s first posting amount.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
$ hledger\-rewrite.hs \[ha]income \-\-add\-posting \[aq](liabilities:tax) *.33 ; income tax\[aq] \-\-add\-posting \[aq](reserve:gifts) $100\[aq]
|
|
$ hledger\-rewrite.hs expenses:gifts \-\-add\-posting \[aq](reserve:gifts) *\-1\[dq]\[aq]
|
|
$ hledger\-rewrite.hs \-f rewrites.hledger
|
|
.EE
|
|
.PP
|
|
rewrites.hledger may consist of entries like:
|
|
.IP
|
|
.EX
|
|
= \[ha]income amt:<0 date:2017
|
|
(liabilities:tax) *0.33 ; tax on income
|
|
(reserve:grocery) *0.25 ; reserve 25% for grocery
|
|
(reserve:) *0.25 ; reserve 25% for grocery
|
|
.EE
|
|
.PP
|
|
Note the single quotes to protect the dollar sign from bash, and the two
|
|
spaces between account and amount.
|
|
.PP
|
|
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]
|
|
.EE
|
|
.PP
|
|
Argument for \f[CR]\-\-add\-posting\f[R] option is a usual posting of
|
|
transaction with an exception for amount specification.
|
|
More precisely, you can use \f[CR]\[aq]*\[aq]\f[R] (star symbol) before
|
|
the amount to indicate that that this is a factor for an amount of
|
|
original matched posting.
|
|
If the amount includes a commodity name, the new posting amount will be
|
|
in the new commodity; otherwise, it will be in the matched posting
|
|
amount\[aq]s commodity.
|
|
.SS Re\-write rules in a file
|
|
During the run this tool will execute so called \[dq]Automated
|
|
Transactions\[dq] found in any journal it process.
|
|
I.e instead of specifying this operations in command line you can put
|
|
them in a journal file.
|
|
.IP
|
|
.EX
|
|
$ rewrite\-rules.journal
|
|
.EE
|
|
.PP
|
|
Make contents look like this:
|
|
.IP
|
|
.EX
|
|
= \[ha]income
|
|
(liabilities:tax) *.33
|
|
|
|
= expenses:gifts
|
|
budget:gifts *\-1
|
|
assets:budget *1
|
|
.EE
|
|
.PP
|
|
Note that \f[CR]\[aq]=\[aq]\f[R] (equality symbol) that is used instead
|
|
of date in transactions you usually write.
|
|
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
|
|
.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]
|
|
\-\-add\-posting \[aq]assets:budget *1\[aq] \[rs]
|
|
> rewritten\-tidy\-output.journal
|
|
.EE
|
|
.PP
|
|
It is important to understand that relative order of such entries in
|
|
journal is important.
|
|
You can re\-use result of previously added postings.
|
|
.SS Diff output format
|
|
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]
|
|
.EE
|
|
.PP
|
|
Output might look like:
|
|
.IP
|
|
.EX
|
|
\-\-\- /tmp/examples/sample.journal
|
|
+++ /tmp/examples/sample.journal
|
|
\[at]\[at] \-18,3 +18,4 \[at]\[at]
|
|
2008/01/01 income
|
|
\- assets:bank:checking $1
|
|
+ assets:bank:checking $1
|
|
income:salary
|
|
+ (liabilities:tax) 0
|
|
\[at]\[at] \-22,3 +23,4 \[at]\[at]
|
|
2008/06/01 gift
|
|
\- assets:bank:checking $1
|
|
+ assets:bank:checking $1
|
|
income:gifts
|
|
+ (liabilities:tax) 0
|
|
.EE
|
|
.PP
|
|
If you\[aq]ll pass this through \f[CR]patch\f[R] tool you\[aq]ll get
|
|
transactions containing the posting that matches your query be updated.
|
|
Note that multiple files might be update according to list of input
|
|
files specified via \f[CR]\-\-file\f[R] options and \f[CR]include\f[R]
|
|
directives inside of these files.
|
|
.PP
|
|
Be careful.
|
|
Whole transaction being re\-formatted in a style of output from
|
|
\f[CR]hledger print\f[R].
|
|
.PP
|
|
See also:
|
|
.PP
|
|
https://github.com/simonmichael/hledger/issues/99
|
|
.SS rewrite vs. print \-\-auto
|
|
This command predates print \-\-auto, and currently does much the same
|
|
thing, but with these differences:
|
|
.IP \[bu] 2
|
|
with multiple files, rewrite lets rules in any file affect all other
|
|
files.
|
|
print \-\-auto uses standard directive scoping; rules affect only child
|
|
files.
|
|
.IP \[bu] 2
|
|
rewrite\[aq]s query limits which transactions can be rewritten; all are
|
|
printed.
|
|
print \-\-auto\[aq]s query limits which transactions are printed.
|
|
.IP \[bu] 2
|
|
rewrite applies rules specified on command line or in the journal.
|
|
print \-\-auto applies rules specified in the journal.
|
|
.SH Maintenance commands
|
|
.SS check
|
|
Check for various kinds of errors in your data.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.PP
|
|
hledger provides a number of built\-in correctness checks to help
|
|
validate your data and prevent errors.
|
|
Some are run automatically, some when you enable \f[CR]\-\-strict\f[R]
|
|
mode; or you can run any of them on demand by providing them as
|
|
arguments to the \f[CR]check\f[R] command.
|
|
\f[CR]check\f[R] produces no output and a zero exit code if all is well.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
hledger check # run basic checks
|
|
hledger check \-s # run basic and strict checks
|
|
hledger check ordereddates payees # run basic checks and two others
|
|
.EE
|
|
.PP
|
|
If you are an Emacs user, you can also configure flycheck\-hledger to
|
|
run these checks, providing instant feedback as you edit the journal.
|
|
.PP
|
|
Here are the checks currently available.
|
|
Generally, they are performed in the order they are shown here (and only
|
|
the first failure is reported).
|
|
.SS Basic checks
|
|
These important checks are performed by default, by almost all hledger
|
|
commands:
|
|
.IP \[bu] 2
|
|
\f[B]parseable\f[R] \- data files are in a supported format, with no
|
|
syntax errors and no invalid include directives.
|
|
This ensures that all files exist and are readable.
|
|
.IP \[bu] 2
|
|
\f[B]autobalanced\f[R] \- all transactions are balanced, after
|
|
automatically inferring missing amounts and conversion rates and then
|
|
converting amounts to cost.
|
|
This ensures that each transaction\[aq]s entry is well formed.
|
|
.IP \[bu] 2
|
|
\f[B]assertions\f[R] \- all balance assertions in the journal are
|
|
passing.
|
|
Balance assertions are a strong defense against errors; they help catch
|
|
many problems.
|
|
If this check gets in your way, you can disable it with
|
|
\f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R].
|
|
Or you can add that to your config file to disable it by default (and
|
|
then use \f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] or
|
|
\f[CR]hledger check assertions\f[R] to enable it).
|
|
.SS Strict checks
|
|
These additional checks are performed by all commands when the
|
|
\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] flag is used (strict mode).
|
|
They provide extra error\-catching power to keep your data clean and
|
|
correct.
|
|
Strict mode also always enables the \f[CR]assertions\f[R] check.
|
|
.IP \[bu] 2
|
|
\f[B]balanced\f[R] \- like \f[CR]autobalanced\f[R], but all conversions
|
|
between commodities must use explicit cost notation or equity postings.
|
|
This prevents wrong conversions caused by typos.
|
|
.IP \[bu] 2
|
|
\f[B]commodities\f[R] \- all commodity symbols used must be declared.
|
|
This guards against mistyping or omitting commodity symbols.
|
|
.IP \[bu] 2
|
|
\f[B]accounts\f[R] \- all account names used must be declared.
|
|
This prevents the use of mis\-spelled or outdated account names.
|
|
.SS Other checks
|
|
These are not wanted by everyone, but can be run using the
|
|
\f[CR]check\f[R] command:
|
|
.IP \[bu] 2
|
|
\f[B]tags\f[R] \- all tags used must be declared.
|
|
This prevents mis\-spelled tag names.
|
|
Note hledger fairly often finds unintended tags in comments.
|
|
.IP \[bu] 2
|
|
\f[B]payees\f[R] \- all payees used in transactions must be declared.
|
|
This will force you to declare any new payee name before using it.
|
|
Most people will probably find this a bit too strict.
|
|
.IP \[bu] 2
|
|
\f[B]ordereddates\f[R] \- within each file, transactions must be ordered
|
|
by date.
|
|
This is a simple and effective error catcher.
|
|
It\[aq]s not included in strict mode, but you can add it by running
|
|
\f[CR]hledger check \-s ordereddates\f[R].
|
|
If enabled, this check is performed before balance assertions.
|
|
.IP \[bu] 2
|
|
\f[B]recentassertions\f[R] \- all accounts with balance assertions must
|
|
have one that\[aq]s within the 7 days before their latest posting.
|
|
This will encourage adding balance assertions for your active
|
|
asset/liability accounts, which in turn should encourage you to
|
|
reconcile regularly with those real world balances \- another strong
|
|
defense against errors.
|
|
\f[CR]hledger close \-\-assert\f[R] can help generate assertion entries.
|
|
Over time the older assertions become somewhat redundant, and you can
|
|
remove them if you like (they don\[aq]t affect performance much, but
|
|
they add some noise to the journal).
|
|
.IP \[bu] 2
|
|
\f[B]uniqueleafnames\f[R] \- no two accounts may have the same last
|
|
account name part (eg the \f[CR]checking\f[R] in
|
|
\f[CR]assets:bank:checking\f[R]).
|
|
This ensures each account can be matched by a unique short name, easier
|
|
to remember and to type.
|
|
.SS Custom checks
|
|
You can build your own custom checks with add\-on command scripts.
|
|
See also Cookbook > Scripting.
|
|
Here are some examples from hledger/bin/:
|
|
.IP \[bu] 2
|
|
\f[B]hledger\-check\-tagfiles\f[R] \- all tag values containing / (a
|
|
forward slash) exist as file paths
|
|
.IP \[bu] 2
|
|
\f[B]hledger\-check\-fancyassertions\f[R] \- more complex balance
|
|
assertions are passing
|
|
.SS diff
|
|
Compares a particular account\[aq]s transactions in two input files.
|
|
It shows any transactions to this account which are in one file but not
|
|
in the other.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.PP
|
|
More precisely: for each posting affecting this account in either file,
|
|
this command looks for a corresponding posting in the other file which
|
|
posts the same amount to the same account (ignoring date, description,
|
|
etc).
|
|
.PP
|
|
Since it compares postings, not transactions, this also works when
|
|
multiple bank transactions have been combined into a single journal
|
|
entry.
|
|
.PP
|
|
This command is useful eg if you have downloaded an account\[aq]s
|
|
transactions from your bank (eg as CSV data): when hledger and your bank
|
|
disagree about the account balance, you can compare the bank data with
|
|
your journal to find out the cause.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
$ hledger diff \-f $LEDGER_FILE \-f bank.csv assets:bank:giro
|
|
These transactions are in the first file only:
|
|
|
|
2014/01/01 Opening Balances
|
|
assets:bank:giro EUR ...
|
|
...
|
|
equity:opening balances EUR \-...
|
|
|
|
These transactions are in the second file only:
|
|
.EE
|
|
.SS setup
|
|
Check the status of the hledger installation.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.PP
|
|
\f[CR]setup\f[R] tests your hledger installation and prints a list of
|
|
results, sometimes with helpful hints.
|
|
This is a good first command to run after installing hledger.
|
|
Also after upgrading, or when something\[aq]s not working, or just when
|
|
you want a reminder of where things are.
|
|
.PP
|
|
It makes one network request to detect the latest hledger release
|
|
version.
|
|
It\[aq]s ok if this fails or times out.
|
|
It will use ANSI color by default, unless disabled by NO_COLOR or
|
|
\-\-color=n.
|
|
It does not use a pager or a config file.
|
|
.PP
|
|
It expects that the hledger version you are running is installed in your
|
|
PATH.
|
|
If not, it will stop until you have done that (to keep things simple).
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
$ hledger setup
|
|
Checking your hledger setup..
|
|
Legend: good, neutral, unknown, warning
|
|
|
|
hledger
|
|
* is a released version ? no hledger 1.42.99\-gbca4b39c5\-20250425, mac\-aarch64
|
|
* is up to date ? yes 1.42.99 installed, latest is 1.42.1
|
|
* is a native binary for this machine ? yes aarch64
|
|
* is installed in PATH ? yes /Users/simon/.local/bin/hledger
|
|
* has a system text encoding configured ? yes UTF\-8, data files should use this encoding
|
|
* has a user config file ? (optional) no
|
|
* current directory has a local config ? yes /Users/simon/src/hledger/hledger.conf
|
|
* the config file is readable ? yes /Users/simon/src/hledger/hledger.conf
|
|
|
|
terminal
|
|
* the NO_COLOR variable is defined ? no
|
|
* \-\-color is configured by config file ? no
|
|
* hledger will use color by default ? yes
|
|
* the PAGER variable is defined ? yes less
|
|
* \-\-pager is configured by config file ? no
|
|
* hledger will use a pager when needed ? yes /opt/homebrew/bin/less
|
|
* the LESS variable is defined ? yes
|
|
* the HLEDGER_LESS variable is defined ? no
|
|
* adjusting LESS variable for color etc. ? yes
|
|
* \-\-pretty is enabled by config file ? no tables will use ASCII characters
|
|
* bash shell completions are installed ? ?
|
|
* zsh shell completions are installed ? ?
|
|
|
|
journal
|
|
* the LEDGER_FILE variable is defined ? yes /Users/simon/finance/2025/2025.journal
|
|
* a default journal file is readable ? yes /Users/simon/finance/2025/2025.journal
|
|
* it includes additional files ? yes 15
|
|
* all commodities are declared ? yes 10
|
|
* all accounts are declared ? yes 160
|
|
* all accounts have types ? no 14 untyped
|
|
* accounts of each type were detected ? yes ALERXCV
|
|
* commodities/accounts are checked ? no use \-s to check commodities/accounts
|
|
* balance assertions are checked ? yes use \-I to ignore assertions
|
|
.EE
|
|
.SS test
|
|
Run built\-in unit tests.
|
|
.IP
|
|
.EX
|
|
Flags:
|
|
no command\-specific flags
|
|
.EE
|
|
.PP
|
|
This command runs the unit tests built in to hledger and hledger\-lib,
|
|
printing the results on stdout.
|
|
If any test fails, the exit code will be non\-zero.
|
|
.PP
|
|
This is mainly used by hledger developers, but you can also use it to
|
|
sanity\-check the installed hledger executable on your platform.
|
|
All tests are expected to pass \- if you ever see a failure, please
|
|
report as a bug!
|
|
.PP
|
|
Any arguments before a \f[CR]\-\-\f[R] argument will be passed to the
|
|
\f[CR]tasty\f[R] test runner as test\-selecting \-p patterns, and any
|
|
arguments after \f[CR]\-\-\f[R] will be passed to tasty unchanged.
|
|
.PP
|
|
Examples:
|
|
.IP
|
|
.EX
|
|
$ hledger test # run all unit tests
|
|
$ hledger test balance # run tests with \[dq]balance\[dq] in their name
|
|
$ hledger test \-\- \-h # show tasty\[aq]s options
|
|
.EE
|
|
.PP
|
|
.SH PART 5: COMMON TASKS
|
|
Here are some quick examples of how to do some basic tasks with hledger.
|
|
.SS Getting help
|
|
Here\[aq]s how to list commands and view options and command docs:
|
|
.IP
|
|
.EX
|
|
$ hledger # show available commands
|
|
$ hledger \-\-help # show common options
|
|
$ hledger CMD \-\-help # show CMD\[aq]s options, common options and CMD\[aq]s documentation
|
|
.EE
|
|
.PP
|
|
You can also view your hledger version\[aq]s manual in several formats
|
|
by using the help command.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
$ hledger help # show the hledger manual with info, man or $PAGER (best available)
|
|
$ hledger help journal # show the journal topic in the hledger manual
|
|
$ hledger help \-\-help # find out more about the help command
|
|
.EE
|
|
.PP
|
|
To view manuals and introductory docs on the web, visit
|
|
https://hledger.org.
|
|
Chat and mail list support and discussion archives can be found at
|
|
https://hledger.org/support.
|
|
.SS Constructing command lines
|
|
hledger has a flexible command line interface.
|
|
We strive to keep it simple and ergonomic, but if you run into one of
|
|
the sharp edges described in OPTIONS, here are some tips that might
|
|
help:
|
|
.IP \[bu] 2
|
|
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
|
|
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] arguments in single quotes
|
|
.IP \[bu] 2
|
|
if needed, also add a backslash to hide regular expression
|
|
metacharacters from the shell
|
|
.IP \[bu] 2
|
|
to see how a misbehaving command line is being parsed, add
|
|
\f[CR]\-\-debug=2\f[R].
|
|
.SS Starting a journal file
|
|
hledger looks for your accounting data in a journal file,
|
|
\f[CR]$HOME/.hledger.journal\f[R] by default:
|
|
.IP
|
|
.EX
|
|
$ hledger stats
|
|
The hledger journal file \[dq]/Users/simon/.hledger.journal\[dq] was not found.
|
|
Please create it first, eg with \[dq]hledger add\[dq] or a text editor.
|
|
Or, specify an existing journal file with \-f or LEDGER_FILE.
|
|
.EE
|
|
.PP
|
|
You can override this by setting the \f[CR]LEDGER_FILE\f[R] environment
|
|
variable (see below).
|
|
It\[aq]s a good practice to keep this important file under version
|
|
control, and to start a new file each year.
|
|
So you could do something like this:
|
|
.IP
|
|
.EX
|
|
$ mkdir \[ti]/finance
|
|
$ cd \[ti]/finance
|
|
$ git init
|
|
Initialized empty Git repository in /Users/simon/finance/.git/
|
|
$ touch 2023.journal
|
|
$ echo \[dq]export LEDGER_FILE=$HOME/finance/2023.journal\[dq] >> \[ti]/.profile
|
|
$ source \[ti]/.profile
|
|
$ hledger stats
|
|
Main file : /Users/simon/finance/2023.journal
|
|
Included files :
|
|
Transactions span : to (0 days)
|
|
Last transaction : none
|
|
Transactions : 0 (0.0 per day)
|
|
Transactions last 30 days: 0 (0.0 per day)
|
|
Transactions last 7 days : 0 (0.0 per day)
|
|
Payees/descriptions : 0
|
|
Accounts : 0 (depth 0)
|
|
Commodities : 0 ()
|
|
Market prices : 0 ()
|
|
.EE
|
|
.SS Setting LEDGER_FILE
|
|
.SS Set LEDGER_FILE on unix
|
|
It depends on your shell, but running these commands in the terminal
|
|
will work for many people; adapt if needed:
|
|
.IP
|
|
.EX
|
|
$ echo \[aq]export LEDGER_FILE=\[ti]/finance/my.journal\[aq] >> \[ti]/.profile
|
|
$ source \[ti]/.profile
|
|
.EE
|
|
.PP
|
|
When correctly configured:
|
|
.IP \[bu] 2
|
|
\f[CR]env | grep LEDGER_FILE\f[R] will show your new setting
|
|
.IP \[bu] 2
|
|
and so should \f[CR]hledger setup\f[R] and (once the file exists)
|
|
\f[CR]hledger files\f[R].
|
|
.SS Set LEDGER_FILE on mac
|
|
In a terminal window, follow the unix procedure above.
|
|
.PP
|
|
Also, this optional step may be helpful for GUI applications:
|
|
.IP "1." 3
|
|
Add an entry to \f[CR]\[ti]/.MacOSX/environment.plist\f[R] like
|
|
.RS 4
|
|
.IP
|
|
.EX
|
|
{
|
|
\[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/my.journal\[dq]
|
|
}
|
|
.EE
|
|
.RE
|
|
.IP "2." 3
|
|
Run \f[CR]killall Dock\f[R] in a terminal window (or restart the
|
|
machine), to complete the change.
|
|
.PP
|
|
When correctly configured for GUI applications:
|
|
.IP \[bu] 2
|
|
apps started from the dock or a spotlight search, such as a GUI Emacs,
|
|
will be aware of the new LEDGER_FILE setting.
|
|
.SS Set LEDGER_FILE on Windows
|
|
Using the gui is easiest:
|
|
.IP "1." 3
|
|
In task bar, search for \f[CR]environment variables\f[R], and choose
|
|
\[dq]Edit environment variables for your account\[dq].
|
|
.IP "2." 3
|
|
Create or change a \f[CR]LEDGER_FILE\f[R] setting in the User variables
|
|
pane.
|
|
A typical value would be
|
|
\f[CR]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]my.journal\f[R].
|
|
.IP "3." 3
|
|
Click OK to complete the change.
|
|
.IP "4." 3
|
|
And open a new powershell window.
|
|
(Existing windows won\[aq]t see the change.)
|
|
.PP
|
|
Or at the command line, you can do it this way:
|
|
.IP "1." 3
|
|
In a powershell window, run
|
|
\f[CR][Environment]::SetEnvironmentVariable(\[dq]LEDGER_FILE\[dq], \[dq]C:\[rs]User\[rs]USERNAME\[rs]finance\[rs]my.journal\[dq], [System.EnvironmentVariableTarget]::User)\f[R]
|
|
.IP "2." 3
|
|
And open a new powershell window.
|
|
(Existing windows won\[aq]t see the change.)
|
|
.PP
|
|
Warning, doing this from the Windows command line can be tricky; other
|
|
methods you may find online:
|
|
.IP \[bu] 2
|
|
may not affect the current window
|
|
.IP \[bu] 2
|
|
may not be persistent
|
|
.IP \[bu] 2
|
|
may not work unless you are an administrator
|
|
.IP \[bu] 2
|
|
may limit values to 1024 characters
|
|
.IP \[bu] 2
|
|
may break dynamic references to other variables
|
|
.IP \[bu] 2
|
|
may require a new\-enough version of powershell
|
|
.IP \[bu] 2
|
|
or may be intended for the older command window.
|
|
.IP \[bu] 2
|
|
If you still have trouble, see eg Setting Windows PowerShell environment
|
|
variables or Adding path permanently to windows using powershell
|
|
doesn\[aq]t appear to work.
|
|
.PP
|
|
When correctly configured:
|
|
.IP \[bu] 2
|
|
in a new powershell window, \f[CR]$env:LEDGER_FILE\f[R] will show your
|
|
new setting
|
|
.IP \[bu] 2
|
|
and so should \f[CR]hledger setup\f[R] and (once the file exists)
|
|
\f[CR]hledger files\f[R].
|
|
.SS Setting opening balances
|
|
Pick a starting date for which you can look up the balances of some
|
|
real\-world assets (bank accounts, wallet..)
|
|
and liabilities (credit cards..).
|
|
.PP
|
|
To avoid a lot of data entry, you may want to start with just one or two
|
|
accounts, like your checking account or cash wallet; and pick a recent
|
|
starting date, like today or the start of the week.
|
|
You can always come back later and add more accounts and older
|
|
transactions, eg going back to january 1st.
|
|
.PP
|
|
Add an opening balances transaction to the journal, declaring the
|
|
balances on this date.
|
|
Here are two ways to do it:
|
|
.IP \[bu] 2
|
|
The first way: open the journal in any text editor and save an entry
|
|
like this:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
2023\-01\-01 * opening balances
|
|
assets:bank:checking $1000 = $1000
|
|
assets:bank:savings $2000 = $2000
|
|
assets:cash $100 = $100
|
|
liabilities:creditcard $\-50 = $\-50
|
|
equity:opening/closing balances
|
|
.EE
|
|
.PP
|
|
These are start\-of\-day balances, ie whatever was in the account at the
|
|
end of the previous day.
|
|
.PP
|
|
The * after the date is an optional status flag.
|
|
Here it means \[dq]cleared & confirmed\[dq].
|
|
.PP
|
|
The currency symbols are optional, but usually a good idea as you\[aq]ll
|
|
be dealing with multiple currencies sooner or later.
|
|
.PP
|
|
The = amounts are optional balance assertions, providing extra error
|
|
checking.
|
|
.RE
|
|
.IP \[bu] 2
|
|
The second way: run \f[CR]hledger add\f[R] and follow the prompts to
|
|
record a similar transaction:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
$ hledger add
|
|
Adding transactions to journal file /Users/simon/finance/2023.journal
|
|
Any command line arguments will be used as defaults.
|
|
Use tab key to complete, readline keys to edit, enter to accept defaults.
|
|
An optional (CODE) may follow transaction dates.
|
|
An optional ; COMMENT may follow descriptions or amounts.
|
|
If you make a mistake, enter < at any prompt to go one step backward.
|
|
To end a transaction, enter . when prompted.
|
|
To quit, enter . at a date prompt or press control\-d or control\-c.
|
|
Date [2023\-02\-07]: 2023\-01\-01
|
|
Description: * opening balances
|
|
Account 1: assets:bank:checking
|
|
Amount 1: $1000
|
|
Account 2: assets:bank:savings
|
|
Amount 2 [$\-1000]: $2000
|
|
Account 3: assets:cash
|
|
Amount 3 [$\-3000]: $100
|
|
Account 4: liabilities:creditcard
|
|
Amount 4 [$\-3100]: $\-50
|
|
Account 5: equity:opening/closing balances
|
|
Amount 5 [$\-3050]:
|
|
Account 6 (or . or enter to finish this transaction): .
|
|
2023\-01\-01 * opening balances
|
|
assets:bank:checking $1000
|
|
assets:bank:savings $2000
|
|
assets:cash $100
|
|
liabilities:creditcard $\-50
|
|
equity:opening/closing balances $\-3050
|
|
|
|
Save this transaction to the journal ? [y]:
|
|
Saved.
|
|
Starting the next transaction (. or ctrl\-D/ctrl\-C to quit)
|
|
Date [2023\-01\-01]: .
|
|
.EE
|
|
.RE
|
|
.PP
|
|
If you\[aq]re using version control, this could be a good time to commit
|
|
the journal.
|
|
Eg:
|
|
.IP
|
|
.EX
|
|
$ git commit \-m \[aq]initial balances\[aq] 2023.journal
|
|
.EE
|
|
.SS Recording transactions
|
|
As you spend or receive money, you can record these transactions using
|
|
one of the methods above (text editor, hledger add) or by using the
|
|
hledger\-iadd or hledger\-web add\-ons, or by using the import command
|
|
to convert CSV data downloaded from your bank.
|
|
.PP
|
|
Here are some simple transactions, see the hledger_journal(5) manual and
|
|
hledger.org for more ideas:
|
|
.IP
|
|
.EX
|
|
2023/1/10 * gift received
|
|
assets:cash $20
|
|
income:gifts
|
|
|
|
2023.1.12 * farmers market
|
|
expenses:food $13
|
|
assets:cash
|
|
|
|
2023\-01\-15 paycheck
|
|
income:salary
|
|
assets:bank:checking $1000
|
|
.EE
|
|
.SS Reconciling
|
|
Periodically you should reconcile \- compare your hledger\-reported
|
|
balances against external sources of truth, like bank statements or your
|
|
bank\[aq]s website \- to be sure that your ledger accurately represents
|
|
the real\-world balances (and, that the real\-world institutions have
|
|
not made a mistake!).
|
|
This gets easy and fast with (1) practice and (2) frequency.
|
|
If you do it daily, it can take 2\-10 minutes.
|
|
If you let it pile up, expect it to take longer as you hunt down errors
|
|
and discrepancies.
|
|
.PP
|
|
A typical workflow:
|
|
.IP "1." 3
|
|
Reconcile cash.
|
|
Count what\[aq]s in your wallet.
|
|
Compare with what hledger reports (\f[CR]hledger bal cash\f[R]).
|
|
If they are different, try to remember the missing transaction, or look
|
|
for the error in the already\-recorded transactions.
|
|
A register report can be helpful (\f[CR]hledger reg cash\f[R]).
|
|
If you can\[aq]t find the error, add an adjustment transaction.
|
|
Eg if you have $105 after the above, and can\[aq]t explain the missing
|
|
$2, it could be:
|
|
.RS 4
|
|
.IP
|
|
.EX
|
|
2023\-01\-16 * adjust cash
|
|
assets:cash $\-2 = $105
|
|
expenses:misc
|
|
.EE
|
|
.RE
|
|
.IP "2." 3
|
|
Reconcile checking.
|
|
Log in to your bank\[aq]s website.
|
|
Compare today\[aq]s (cleared) balance with hledger\[aq]s cleared balance
|
|
(\f[CR]hledger bal checking \-C\f[R]).
|
|
If they are different, track down the error or record the missing
|
|
transaction(s) or add an adjustment transaction, similar to the above.
|
|
Unlike the cash case, you can usually compare the transaction history
|
|
and running balance from your bank with the one reported by
|
|
\f[CR]hledger reg checking \-C\f[R].
|
|
This will be easier if you generally record transaction dates quite
|
|
similar to your bank\[aq]s clearing dates.
|
|
.IP "3." 3
|
|
Repeat for other asset/liability accounts.
|
|
.PP
|
|
Tip: instead of the register command, use hledger\-ui to see a
|
|
live\-updating register while you edit the journal:
|
|
\f[CR]hledger\-ui \-\-watch \-\-register checking \-C\f[R]
|
|
.PP
|
|
After reconciling, it could be a good time to mark the reconciled
|
|
transactions\[aq] status as \[dq]cleared and confirmed\[dq], if you want
|
|
to track that, by adding the \f[CR]*\f[R] marker.
|
|
Eg in the paycheck transaction above, insert \f[CR]*\f[R] between
|
|
\f[CR]2023\-01\-15\f[R] and \f[CR]paycheck\f[R]
|
|
.PP
|
|
If you\[aq]re using version control, this can be another good time to
|
|
commit:
|
|
.IP
|
|
.EX
|
|
$ git commit \-m \[aq]txns\[aq] 2023.journal
|
|
.EE
|
|
.SS Reporting
|
|
Here are some basic reports.
|
|
.PP
|
|
Show all transactions:
|
|
.IP
|
|
.EX
|
|
$ hledger print
|
|
2023\-01\-01 * opening balances
|
|
assets:bank:checking $1000
|
|
assets:bank:savings $2000
|
|
assets:cash $100
|
|
liabilities:creditcard $\-50
|
|
equity:opening/closing balances $\-3050
|
|
|
|
2023\-01\-10 * gift received
|
|
assets:cash $20
|
|
income:gifts
|
|
|
|
2023\-01\-12 * farmers market
|
|
expenses:food $13
|
|
assets:cash
|
|
|
|
2023\-01\-15 * paycheck
|
|
income:salary
|
|
assets:bank:checking $1000
|
|
|
|
2023\-01\-16 * adjust cash
|
|
assets:cash $\-2 = $105
|
|
expenses:misc
|
|
.EE
|
|
.PP
|
|
Show account names, and their hierarchy:
|
|
.IP
|
|
.EX
|
|
$ hledger accounts \-\-tree
|
|
assets
|
|
bank
|
|
checking
|
|
savings
|
|
cash
|
|
equity
|
|
opening/closing balances
|
|
expenses
|
|
food
|
|
misc
|
|
income
|
|
gifts
|
|
salary
|
|
liabilities
|
|
creditcard
|
|
.EE
|
|
.PP
|
|
Show all account totals:
|
|
.IP
|
|
.EX
|
|
$ hledger balance
|
|
$4105 assets
|
|
$4000 bank
|
|
$2000 checking
|
|
$2000 savings
|
|
$105 cash
|
|
$\-3050 equity:opening/closing balances
|
|
$15 expenses
|
|
$13 food
|
|
$2 misc
|
|
$\-1020 income
|
|
$\-20 gifts
|
|
$\-1000 salary
|
|
$\-50 liabilities:creditcard
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
0
|
|
.EE
|
|
.PP
|
|
Show only asset and liability balances, as a flat list, limited to depth
|
|
2:
|
|
.IP
|
|
.EX
|
|
$ hledger bal assets liabilities \-2
|
|
$4000 assets:bank
|
|
$105 assets:cash
|
|
$\-50 liabilities:creditcard
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$4055
|
|
.EE
|
|
.PP
|
|
Show the same thing without negative numbers, formatted as a simple
|
|
balance sheet:
|
|
.IP
|
|
.EX
|
|
$ hledger bs \-2
|
|
Balance Sheet 2023\-01\-16
|
|
|
|
|| 2023\-01\-16
|
|
========================++============
|
|
Assets ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
assets:bank || $4000
|
|
assets:cash || $105
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $4105
|
|
========================++============
|
|
Liabilities ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
liabilities:creditcard || $50
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $50
|
|
========================++============
|
|
Net: || $4055
|
|
.EE
|
|
.PP
|
|
The final total is your \[dq]net worth\[dq] on the end date.
|
|
(Or use \f[CR]bse\f[R] for a full balance sheet with equity.)
|
|
.PP
|
|
Show income and expense totals, formatted as an income statement:
|
|
.IP
|
|
.EX
|
|
hledger is
|
|
Income Statement 2023\-01\-01\-2023\-01\-16
|
|
|
|
|| 2023\-01\-01\-2023\-01\-16
|
|
===============++=======================
|
|
Revenues ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
income:gifts || $20
|
|
income:salary || $1000
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $1020
|
|
===============++=======================
|
|
Expenses ||
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
expenses:food || $13
|
|
expenses:misc || $2
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
|| $15
|
|
===============++=======================
|
|
Net: || $1005
|
|
.EE
|
|
.PP
|
|
The final total is your net income during this period.
|
|
.PP
|
|
Show transactions affecting your wallet, with running total:
|
|
.IP
|
|
.EX
|
|
$ hledger register cash
|
|
2023\-01\-01 opening balances assets:cash $100 $100
|
|
2023\-01\-10 gift received assets:cash $20 $120
|
|
2023\-01\-12 farmers market assets:cash $\-13 $107
|
|
2023\-01\-16 adjust cash assets:cash $\-2 $105
|
|
.EE
|
|
.PP
|
|
Show weekly posting counts as a bar chart:
|
|
.IP
|
|
.EX
|
|
$ hledger activity \-W
|
|
2019\-12\-30 *****
|
|
2023\-01\-06 ****
|
|
2023\-01\-13 ****
|
|
.EE
|
|
.SS Migrating to a new file
|
|
At the end of the year, you may want to continue your journal in a new
|
|
file, so that old transactions don\[aq]t slow down or clutter your
|
|
reports, and to help ensure the integrity of your accounting history.
|
|
See the close command.
|
|
.PP
|
|
If using version control, don\[aq]t forget to \f[CR]git add\f[R] the new
|
|
file.
|
|
.SH BUGS
|
|
We welcome bug reports in the hledger issue tracker
|
|
(https://bugs.hledger.org), or on the hledger chat or mail list
|
|
(https://hledger.org/support).
|
|
.PP
|
|
Some known issues and limitations:
|
|
.PP
|
|
hledger uses the system\[aq]s text encoding when reading non\-ascii
|
|
text.
|
|
If no system encoding is configured, or if the data\[aq]s encoding is
|
|
different, hledger will give an error.
|
|
(See Text encoding, Troubleshooting.)
|
|
.PP
|
|
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, may not be fully supported.
|
|
(For best results, try a powershell window.)
|
|
.PP
|
|
When processing large data files, hledger uses more memory than Ledger.
|
|
.SS Troubleshooting
|
|
Here are some common issues you might encounter when you run hledger,
|
|
and how to resolve them (and remember also you can usually get quick
|
|
Support):
|
|
.PP
|
|
\f[B]PATH issues: I get an error like \[dq]No command \[aq]hledger\[aq]
|
|
found\[dq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Depending how you installed hledger, the executables may not be in your
|
|
shell\[aq]s PATH.
|
|
Eg on unix systems, stack installs hledger in
|
|
\f[CR]\[ti]/.local/bin\f[R] and cabal installs it in
|
|
\f[CR]\[ti]/.cabal/bin\f[R].
|
|
You may need to add one of these directories to your shell\[aq]s PATH,
|
|
and/or open a new terminal window.
|
|
.PP
|
|
\f[B]LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not
|
|
using it\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
.IP \[bu] 2
|
|
\f[CR]LEDGER_FILE\f[R] should be a real environment variable, not just a
|
|
shell variable.
|
|
Eg on unix, the command \f[CR]env | grep LEDGER_FILE\f[R] should show
|
|
it.
|
|
You may need to use \f[CR]export\f[R] (see
|
|
https://stackoverflow.com/a/7411509).
|
|
On Windows, \f[CR]$env:LEDGER_FILE\f[R] should show it.
|
|
.IP \[bu] 2
|
|
You may need to force your shell to see the new configuration.
|
|
A simple way is to close your terminal window and open a new one.
|
|
.PP
|
|
\f[B]Text decoding issues: I get errors like \[dq]Illegal byte
|
|
sequence\[dq] or \[dq]Invalid or incomplete multibyte or wide
|
|
character\[dq] or \[dq]commitAndReleaseBuffer: invalid argument (invalid
|
|
character)\[dq]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
hledger usually needs its input to be decodable with the system
|
|
locale\[aq]s text encoding.
|
|
See Text encoding and Install: Text encoding.
|
|
.PP
|
|
\f[B]COMPATIBILITY ISSUES: hledger gives an error with my Ledger
|
|
file\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Not all of Ledger\[aq]s journal file syntax or feature set is supported.
|
|
See hledger and Ledger for full details.
|
|
|
|
|
|
.SH AUTHORS
|
|
Simon Michael <simon@joyful.com> and contributors.
|
|
.br
|
|
See http://hledger.org/CREDITS.html
|
|
|
|
.SH COPYRIGHT
|
|
Copyright 2007-2023 Simon Michael and contributors.
|
|
|
|
.SH LICENSE
|
|
Released under GNU GPL v3 or later.
|
|
|
|
.SH SEE ALSO
|
|
hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1)
|