11213 lines
365 KiB
Groff
11213 lines
365 KiB
Groff
.\"t
|
|
|
|
.TH "HLEDGER" "1" "January 2024" "hledger-1.32.99 " "hledger User Manuals"
|
|
|
|
|
|
|
|
.SH NAME
|
|
hledger \- robust, friendly plain text accounting (CLI version)
|
|
.SH SYNOPSIS
|
|
\f[CR]hledger\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]hledger COMMAND [OPTS] [ARGS]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]hledger ADDONCMD \-\- [OPTS] [ARGS]\f[R]
|
|
.SH DESCRIPTION
|
|
hledger is a robust, user\-friendly, cross\-platform set of programs for
|
|
tracking money, time, or any other commodity, using double\-entry
|
|
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.32.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 get it from hledger itself with
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]hledger \-\-man\f[R], \f[CR]hledger \-\-info\f[R] or
|
|
\f[CR]hledger help [TOPIC]\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:
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]hledger print \-x\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]hledger aregister assets\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]hledger balance\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]hledger balancesheet\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]hledger incomestatement\f[R].
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
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 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 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(12.3n) lw(30.0n) lw(27.7n).
|
|
T{
|
|
Reader:
|
|
T}@T{
|
|
Reads:
|
|
T}@T{
|
|
Used for file 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{
|
|
CSV/SSV/TSV/character\-separated values, for data import
|
|
T}@T{
|
|
\f[CR].csv\f[R] \f[CR].ssv\f[R] \f[CR].tsv\f[R] \f[CR].csv.rules\f[R]
|
|
\f[CR].ssv.rules\f[R] \f[CR].tsv.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 as csv format:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f csv:/some/csv\-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 add a file
|
|
format prefix, like:
|
|
.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.
|
|
.PP
|
|
To show the commands list, run \f[CR]hledger\f[R] with no arguments.
|
|
The commands are described in detail in 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]: programs or scripts named \[dq]hledger\-SOMETHING\[dq],
|
|
which will also appear in hledger\[aq]s commands list.
|
|
If you used the hledger\-install script, you will have several add\-ons
|
|
installed already.
|
|
Some more can be found in hledger\[aq]s bin/ directory, documented at
|
|
https://hledger.org/scripts.html.
|
|
.PP
|
|
More precisely, add\-on commands are programs or scripts in your
|
|
shell\[aq]s PATH, whose name starts with \[dq]hledger\-\[dq] and ends
|
|
with no extension or a recognised extension (\[dq].bat\[dq],
|
|
\[dq].com\[dq], \[dq].exe\[dq], \[dq].hs\[dq], \[dq].js\[dq],
|
|
\[dq].lhs\[dq], \[dq].lua\[dq], \[dq].php\[dq], \[dq].pl\[dq],
|
|
\[dq].py\[dq], \[dq].rb\[dq], \[dq].rkt\[dq], or \[dq].sh\[dq]), and (on
|
|
unix and mac) which has executable permission for the current user.
|
|
.PP
|
|
You can run add\-on commands using hledger, much like built\-in
|
|
commands:
|
|
\f[CR]hledger ADDONCMD [\-\- ADDONCMDOPTS] [ADDONCMDARGS]\f[R].
|
|
But note the double hyphen argument, required before add\-on\-specific
|
|
options.
|
|
Eg: \f[CR]hledger ui \-\- \-\-watch\f[R] or
|
|
\f[CR]hledger web \-\- \-\-serve\f[R].
|
|
If this causes difficulty, you can always run the add\-on directly,
|
|
without using \f[CR]hledger\f[R]: \f[CR]hledger\-ui \-\-watch\f[R] or
|
|
\f[CR]hledger\-web \-\-serve\f[R].
|
|
.SH Options
|
|
Run \f[CR]hledger \-h\f[R] to see general command line help, and general
|
|
options which are common to most hledger commands.
|
|
These options can be written anywhere on the command line.
|
|
They can be grouped into help, input, and reporting options:
|
|
.SS General help options
|
|
.TP
|
|
\f[CR]\-h \-\-help\f[R]
|
|
show general or COMMAND help
|
|
.TP
|
|
\f[CR]\-\-man\f[R]
|
|
show general or COMMAND user manual with man
|
|
.TP
|
|
\f[CR]\-\-info\f[R]
|
|
show general or COMMAND user manual with info
|
|
.TP
|
|
\f[CR]\-\-version\f[R]
|
|
show general or ADDONCMD version
|
|
.TP
|
|
\f[CR]\-\-debug[=N]\f[R]
|
|
show debug output (levels 1\-9, default: 1)
|
|
.SS General input options
|
|
.TP
|
|
\f[CR]\-f FILE \-\-file=FILE\f[R]
|
|
use a different input file.
|
|
For stdin, use \- (default: \f[CR]$LEDGER_FILE\f[R] or
|
|
\f[CR]$HOME/.hledger.journal\f[R])
|
|
.TP
|
|
\f[CR]\-\-rules\-file=RULESFILE\f[R]
|
|
Conversion rules file to use when reading CSV (default: FILE.rules)
|
|
.TP
|
|
\f[CR]\-\-separator=CHAR\f[R]
|
|
Field separator to expect when reading CSV (default: \[aq],\[aq])
|
|
.TP
|
|
\f[CR]\-\-alias=OLD=NEW\f[R]
|
|
rename accounts named OLD to NEW
|
|
.TP
|
|
\f[CR]\-\-anon\f[R]
|
|
anonymize accounts and payees
|
|
.TP
|
|
\f[CR]\-\-pivot FIELDNAME\f[R]
|
|
use some other field or tag for the account name
|
|
.TP
|
|
\f[CR]\-I \-\-ignore\-assertions\f[R]
|
|
disable balance assertion checks (note: does not disable balance
|
|
assignments)
|
|
.TP
|
|
\f[CR]\-s \-\-strict\f[R]
|
|
do extra error checking (check that all posted accounts are declared)
|
|
.SS General reporting options
|
|
.TP
|
|
\f[CR]\-b \-\-begin=DATE\f[R]
|
|
include postings/txns on or after this date (will be adjusted to
|
|
preceding subperiod start when using a report interval)
|
|
.TP
|
|
\f[CR]\-e \-\-end=DATE\f[R]
|
|
include postings/txns before this date (will be adjusted to following
|
|
subperiod end when using a report interval)
|
|
.TP
|
|
\f[CR]\-D \-\-daily\f[R]
|
|
multiperiod/multicolumn report by day
|
|
.TP
|
|
\f[CR]\-W \-\-weekly\f[R]
|
|
multiperiod/multicolumn report by week
|
|
.TP
|
|
\f[CR]\-M \-\-monthly\f[R]
|
|
multiperiod/multicolumn report by month
|
|
.TP
|
|
\f[CR]\-Q \-\-quarterly\f[R]
|
|
multiperiod/multicolumn report by quarter
|
|
.TP
|
|
\f[CR]\-Y \-\-yearly\f[R]
|
|
multiperiod/multicolumn report by year
|
|
.TP
|
|
\f[CR]\-p \-\-period=PERIODEXP\f[R]
|
|
set start date, end date, and/or reporting interval all at once using
|
|
period expressions syntax
|
|
.TP
|
|
\f[CR]\-\-date2\f[R]
|
|
match the secondary date instead (see command help for other effects)
|
|
.TP
|
|
\f[CR]\-\-today=DATE\f[R]
|
|
override today\[aq]s date (affects relative smart dates, for
|
|
tests/examples)
|
|
.TP
|
|
\f[CR]\-U \-\-unmarked\f[R]
|
|
include only unmarked postings/txns (can combine with \-P or \-C)
|
|
.TP
|
|
\f[CR]\-P \-\-pending\f[R]
|
|
include only pending postings/txns
|
|
.TP
|
|
\f[CR]\-C \-\-cleared\f[R]
|
|
include only cleared postings/txns
|
|
.TP
|
|
\f[CR]\-R \-\-real\f[R]
|
|
include only non\-virtual postings
|
|
.TP
|
|
\f[CR]\-NUM \-\-depth=NUM\f[R]
|
|
hide/aggregate accounts or postings more than NUM levels deep
|
|
.TP
|
|
\f[CR]\-E \-\-empty\f[R]
|
|
show items with zero amount, normally hidden (and vice\-versa in
|
|
hledger\-ui/hledger\-web)
|
|
.TP
|
|
\f[CR]\-B \-\-cost\f[R]
|
|
convert amounts to their cost/selling amount at transaction time
|
|
.TP
|
|
\f[CR]\-V \-\-market\f[R]
|
|
convert amounts to their market value in default valuation commodities
|
|
.TP
|
|
\f[CR]\-X \-\-exchange=COMM\f[R]
|
|
convert amounts to their market value in commodity COMM
|
|
.TP
|
|
\f[CR]\-\-value\f[R]
|
|
convert amounts to cost or market value, more flexibly than \-B/\-V/\-X
|
|
.TP
|
|
\f[CR]\-\-infer\-equity\f[R]
|
|
infer conversion equity postings from costs
|
|
.TP
|
|
\f[CR]\-\-infer\-costs\f[R]
|
|
infer costs from conversion equity postings
|
|
.TP
|
|
\f[CR]\-\-infer\-market\-prices\f[R]
|
|
use costs as additional market prices, as if they were P directives
|
|
.TP
|
|
\f[CR]\-\-forecast\f[R]
|
|
generate transactions from periodic rules,
|
|
between the latest recorded txn and 6 months from today,
|
|
or during the specified PERIOD (= is required).
|
|
Auto posting rules will be applied to these transactions as well.
|
|
Also, in hledger\-ui make future\-dated transactions visible.
|
|
.TP
|
|
\f[CR]\-\-auto\f[R]
|
|
generate extra postings by applying auto posting rules to all txns (not
|
|
just forecast txns)
|
|
.TP
|
|
\f[CR]\-\-verbose\-tags\f[R]
|
|
add visible tags indicating transactions or postings which have been
|
|
generated/modified
|
|
.TP
|
|
\f[CR]\-\-commodity\-style\f[R]
|
|
Override the commodity style in the output for the specified commodity.
|
|
For example \[aq]EUR1.000,00\[aq].
|
|
.TP
|
|
\f[CR]\-\-color=WHEN (or \-\-colour=WHEN)\f[R]
|
|
Should color\-supporting commands use ANSI color codes in text output.
|
|
\[aq]auto\[aq] (default): whenever stdout seems to be a
|
|
color\-supporting terminal.
|
|
\[aq]always\[aq] or \[aq]yes\[aq]: always, useful eg when piping output
|
|
into \[aq]less \-R\[aq].
|
|
\[aq]never\[aq] or \[aq]no\[aq]: never.
|
|
A NO_COLOR environment variable overrides this.
|
|
.TP
|
|
\f[CR]\-\-pretty[=WHEN]\f[R]
|
|
Show prettier output, e.g.
|
|
using unicode box\-drawing characters.
|
|
Accepts \[aq]yes\[aq] (the default) or \[aq]no\[aq] (\[aq]y\[aq],
|
|
\[aq]n\[aq], \[aq]always\[aq], \[aq]never\[aq] also work).
|
|
If you provide an argument you must use \[aq]=\[aq], e.g.
|
|
\[aq]\-\-pretty=yes\[aq].
|
|
.PP
|
|
When a reporting option appears more than once in the command line, the
|
|
last one takes precedence.
|
|
.PP
|
|
Some reporting options can also be written as query arguments.
|
|
.SH Command line tips
|
|
Here are some details useful to know about for hledger command lines
|
|
(and elsewhere).
|
|
Feel free to skip this section until you need it.
|
|
.SS Option repetition
|
|
If options are repeated in a command line, hledger will generally use
|
|
the last (right\-most) occurence.
|
|
.SS Special characters
|
|
.SS Single escaping (shell metacharacters)
|
|
In shell command lines, characters significant to your shell \- such as
|
|
spaces, \f[CR]<\f[R], \f[CR]>\f[R], \f[CR](\f[R], \f[CR])\f[R],
|
|
\f[CR]|\f[R], \f[CR]$\f[R] and \f[CR]\[rs]\f[R] \- should be
|
|
\[dq]shell\-escaped\[dq] if you want hledger to see them.
|
|
This is done by enclosing them in single or double quotes, or by writing
|
|
a backslash before them.
|
|
Eg to match an account name containing a space:
|
|
.IP
|
|
.EX
|
|
$ hledger register \[aq]credit card\[aq]
|
|
.EE
|
|
.PP
|
|
or:
|
|
.IP
|
|
.EX
|
|
$ hledger register credit\[rs] card
|
|
.EE
|
|
.PP
|
|
Windows users should keep in mind that \f[CR]cmd\f[R] treats single
|
|
quote as a regular character, so you should be using double quotes
|
|
exclusively.
|
|
PowerShell treats both single and double quotes as quotes.
|
|
.SS Double escaping (regular expression metacharacters)
|
|
Characters significant in regular expressions (described below) \- such
|
|
as \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], and
|
|
\f[CR]\[rs]\f[R] \- may need to be \[dq]regex\-escaped\[dq] if you
|
|
don\[aq]t want them to be interpreted by hledger\[aq]s regular
|
|
expression engine.
|
|
This is done by writing backslashes before them, but since backslash is
|
|
typically also a shell metacharacter, both shell\-escaping and
|
|
regex\-escaping will be needed.
|
|
Eg to match a literal \f[CR]$\f[R] sign while using the bash shell:
|
|
.IP
|
|
.EX
|
|
$ hledger balance cur:\[aq]\[rs]$\[aq]
|
|
.EE
|
|
.PP
|
|
or:
|
|
.IP
|
|
.EX
|
|
$ hledger balance cur:\[rs]\[rs]$
|
|
.EE
|
|
.SS Triple escaping (for add\-on commands)
|
|
When you use hledger to run an external add\-on command (described
|
|
below), one level of shell\-escaping is lost from any options or
|
|
arguments intended for by the add\-on command, so those need an extra
|
|
level of shell\-escaping.
|
|
Eg to match a literal \f[CR]$\f[R] sign while using the bash shell and
|
|
running an add\-on command (\f[CR]ui\f[R]):
|
|
.IP
|
|
.EX
|
|
$ hledger ui cur:\[aq]\[rs]\[rs]$\[aq]
|
|
.EE
|
|
.PP
|
|
or:
|
|
.IP
|
|
.EX
|
|
$ hledger ui cur:\[rs]\[rs]\[rs]\[rs]$
|
|
.EE
|
|
.PP
|
|
If you wondered why \f[I]four\f[R] backslashes, perhaps this helps:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
l l.
|
|
T{
|
|
unescaped:
|
|
T}@T{
|
|
\f[CR]$\f[R]
|
|
T}
|
|
T{
|
|
escaped:
|
|
T}@T{
|
|
\f[CR]\[rs]$\f[R]
|
|
T}
|
|
T{
|
|
double\-escaped:
|
|
T}@T{
|
|
\f[CR]\[rs]\[rs]$\f[R]
|
|
T}
|
|
T{
|
|
triple\-escaped:
|
|
T}@T{
|
|
\f[CR]\[rs]\[rs]\[rs]\[rs]$\f[R]
|
|
T}
|
|
.TE
|
|
.PP
|
|
Or, you can avoid the extra escaping by running the add\-on executable
|
|
directly:
|
|
.IP
|
|
.EX
|
|
$ hledger\-ui cur:\[rs]\[rs]$
|
|
.EE
|
|
.SS Less escaping
|
|
Options and arguments are sometimes used in places other than the shell
|
|
command line, where shell\-escaping is not needed, so there you should
|
|
use one less level of escaping.
|
|
Those places include:
|
|
.IP \[bu] 2
|
|
an \[at]argumentfile
|
|
.IP \[bu] 2
|
|
hledger\-ui\[aq]s filter field
|
|
.IP \[bu] 2
|
|
hledger\-web\[aq]s search form
|
|
.IP \[bu] 2
|
|
GHCI\[aq]s prompt (used by developers).
|
|
.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, and it must be one that can decode
|
|
the characters being used.
|
|
In bash, you can set a locale like this:
|
|
\f[CR]export LANG=en_US.UTF\-8\f[R].
|
|
There are some more details in Troubleshooting.
|
|
This step is essential \- without it, hledger will quit on encountering
|
|
a non\-ascii character (as with all GHC\-compiled programs).
|
|
.IP \[bu] 2
|
|
your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
|
|
must support unicode
|
|
.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.
|
|
.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 reuse them by writing \f[CR]\[at]FILENAME\f[R] as a command line
|
|
argument.
|
|
Eg: \f[CR]hledger bal \[at]foo.args\f[R].
|
|
.PP
|
|
Inside the argument file, each line should contain just one option or
|
|
argument.
|
|
Don\[aq]t use spaces except inside quotes (or you\[aq]ll see a confusing
|
|
error); write \f[CR]=\f[R] (or nothing) between a flag and its argument.
|
|
For the special characters mentioned above, use one less level of
|
|
quoting than you would at the command prompt.
|
|
.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/\-\-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(16.1n) lw(14.5n) lw(14.5n) lw(16.1n) lw(4.8n) lw(4.0n).
|
|
T{
|
|
\-
|
|
T}@T{
|
|
txt
|
|
T}@T{
|
|
csv/tsv
|
|
T}@T{
|
|
html
|
|
T}@T{
|
|
json
|
|
T}@T{
|
|
sql
|
|
T}
|
|
_
|
|
T{
|
|
aregister
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}
|
|
T{
|
|
balance
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y \f[I]1,2\f[R]
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}
|
|
T{
|
|
balancesheet
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}
|
|
T{
|
|
balancesheetequity
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}
|
|
T{
|
|
cashflow
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}
|
|
T{
|
|
incomestatement
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y \f[I]1\f[R]
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}
|
|
T{
|
|
print
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}
|
|
T{
|
|
register
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}@T{
|
|
Y
|
|
T}@T{
|
|
T}
|
|
.TE
|
|
.IP \[bu] 2
|
|
\f[I]1 Also affected by the balance commands\[aq] \f[CI]\-\-layout\f[I]
|
|
option.\f[R]
|
|
.IP \[bu] 2
|
|
\f[I]2 \f[CI]balance\f[I] does not support html output without a report
|
|
interval or with \f[CI]\-\-budget\f[I].\f[R]
|
|
.PP
|
|
The output format is selected by the
|
|
\f[CR]\-O/\-\-output\-format=FMT\f[R] option:
|
|
.IP
|
|
.EX
|
|
$ hledger print \-O csv # print CSV on stdout
|
|
.EE
|
|
.PP
|
|
or by the filename extension of an output file specified with the
|
|
\f[CR]\-o/\-\-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
|
|
Some notes about the various output formats:
|
|
.SS CSV output
|
|
.IP \[bu] 2
|
|
In CSV output, digit group marks (such as thousands separators) are
|
|
disabled automatically.
|
|
.SS HTML output
|
|
.IP \[bu] 2
|
|
HTML output can be styled by an optional \f[CR]hledger.css\f[R] file in
|
|
the same directory.
|
|
.SS JSON output
|
|
.IP \[bu] 2
|
|
This is not yet much used; real\-world feedback is welcome.
|
|
.IP \[bu] 2
|
|
Our JSON is rather large and verbose, since it is a faithful
|
|
representation of hledger\[aq]s internal data types.
|
|
To understand the JSON, read the Haskell type definitions, which are
|
|
mostly in
|
|
https://github.com/simonmichael/hledger/blob/master/hledger\-lib/Hledger/Data/Types.hs.
|
|
.IP \[bu] 2
|
|
hledger represents quantities as Decimal values storing up to 255
|
|
significant digits, eg for repeating decimals.
|
|
Such numbers can arise in practice (from automatically\-calculated
|
|
transaction prices), and would break most JSON consumers.
|
|
So in JSON, we show quantities as simple Numbers with at most 10 decimal
|
|
places.
|
|
We don\[aq]t limit the number of integer digits, but that part is under
|
|
your control.
|
|
We hope this approach will not cause problems in practice; if you find
|
|
otherwise, please let us know.
|
|
(Cf #1195)
|
|
.SS SQL output
|
|
.IP \[bu] 2
|
|
This is not yet much used; real\-world feedback is welcome.
|
|
.IP \[bu] 2
|
|
SQL output is expected to work at least with SQLite, MySQL and Postgres.
|
|
.IP \[bu] 2
|
|
For SQLite, it will be more useful if you modify the generated
|
|
\f[CR]id\f[R] field to be a PRIMARY KEY.
|
|
Eg:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
$ hledger print \-O sql | sed \[aq]s/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g\[aq] | ...
|
|
.EE
|
|
.RE
|
|
.IP \[bu] 2
|
|
SQL output is structured with the expectations that statements will be
|
|
executed in the empty database.
|
|
If you already have tables created via SQL output of hledger, you would
|
|
probably want to either clear tables of existing data (via
|
|
\f[CR]delete\f[R] or \f[CR]truncate\f[R] SQL statements) or drop tables
|
|
completely as otherwise your postings will be duped.
|
|
.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 repeated to set the display style for multiple
|
|
commodities/currencies.
|
|
Its argument is as described in the commodity directive.
|
|
.SS Colour
|
|
In terminal output, some commands can produce colour when the terminal
|
|
supports it:
|
|
.IP \[bu] 2
|
|
if the \f[CR]\-\-color/\-\-colour\f[R] option is given a value of
|
|
\f[CR]yes\f[R] or \f[CR]always\f[R] (or \f[CR]no\f[R] or
|
|
\f[CR]never\f[R]), colour will (or will not) be used;
|
|
.IP \[bu] 2
|
|
otherwise, if the \f[CR]NO_COLOR\f[R] environment variable is set,
|
|
colour will not be used;
|
|
.IP \[bu] 2
|
|
otherwise, colour will be used if the output (terminal or file) supports
|
|
it.
|
|
.SS Box\-drawing
|
|
In terminal output, you can enable unicode box\-drawing characters to
|
|
render prettier tables:
|
|
.IP \[bu] 2
|
|
if the \f[CR]\-\-pretty\f[R] option is given a value of \f[CR]yes\f[R]
|
|
or \f[CR]always\f[R] (or \f[CR]no\f[R] or \f[CR]never\f[R]), unicode
|
|
characters will (or will not) be used;
|
|
.IP \[bu] 2
|
|
otherwise, unicode characters will not be used.
|
|
.SS Paging
|
|
When showing long output in the terminal, hledger will try to use the
|
|
pager specified by the \f[CR]PAGER\f[R] environment variable, or
|
|
\f[CR]less\f[R], or \f[CR]more\f[R].
|
|
(A pager is a helper program that shows one page at a time rather than
|
|
scrolling everything off screen).
|
|
Currently it does this only for help output, not for reports;
|
|
specifically,
|
|
.IP \[bu] 2
|
|
when listing commands, with \f[CR]hledger\f[R]
|
|
.IP \[bu] 2
|
|
when showing help with \f[CR]hledger [CMD] \-\-help\f[R],
|
|
.IP \[bu] 2
|
|
when viewing manuals with \f[CR]hledger help\f[R] or
|
|
\f[CR]hledger \-\-man\f[R].
|
|
.PP
|
|
Note the pager is expected to handle ANSI codes, which hledger uses eg
|
|
for bold emphasis.
|
|
For the common pager \f[CR]less\f[R] (and its \f[CR]more\f[R]
|
|
compatibility mode), we add \f[CR]R\f[R] to the \f[CR]LESS\f[R] and
|
|
\f[CR]MORE\f[R] environment variables to make this work.
|
|
If you use a different pager, you might need to configure it similarly,
|
|
to avoid seeing junk on screen (let us know).
|
|
Otherwise, you can set the \f[CR]NO_COLOR\f[R] environment variable to 1
|
|
to disable all ANSI output (see Colour).
|
|
.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
|
|
.SH Environment
|
|
These environment variables affect hledger:
|
|
.PP
|
|
\f[B]COLUMNS\f[R] This is normally set by your terminal; some hledger
|
|
commands (\f[CR]register\f[R]) will format their output to this width.
|
|
If not set, they will try to use the available terminal width.
|
|
.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 is set (with any value),
|
|
hledger will not use ANSI color codes in terminal output, unless
|
|
overridden by an explicit \f[CR]\-\-color/\-\-colour\f[R] option.
|
|
.SH PART 2: DATA FORMATS
|
|
.SH Journal
|
|
hledger\[aq]s default file format, representing a General Journal.
|
|
Here\[aq]s a cheatsheet/mini\-tutorial, or you can skip ahead to About
|
|
journal format.
|
|
.SS Journal cheatsheet
|
|
.IP
|
|
.EX
|
|
# Here is the main syntax of hledger\[aq]s journal format
|
|
# (omitting extra Ledger compatibility syntax).
|
|
# hledger journals contain comments, directives, and transactions, in any order:
|
|
|
|
###############################################################################
|
|
# 1. Comment lines are for notes or temporarily disabling things.
|
|
# They begin with #, ;, or a line containing the word \[dq]comment\[dq].
|
|
|
|
# hash comment line
|
|
; semicolon comment line
|
|
comment
|
|
These lines
|
|
are commented.
|
|
end comment
|
|
|
|
# Some but not all hledger entries can have same\-line comments attached to them,
|
|
# from ; (semicolon) to end of line.
|
|
|
|
###############################################################################
|
|
# 2. Directives modify parsing or reports in some way.
|
|
# They begin with a word or letter (or symbol).
|
|
|
|
account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;.
|
|
account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX)
|
|
alias chkg = assets:checking
|
|
commodity $0.00
|
|
decimal\-mark .
|
|
include /dev/null
|
|
payee Whole Foods
|
|
P 2022\-01\-01 AAAA $1.40
|
|
\[ti] monthly budget goals ; <\- 2+ spaces between period expression and description
|
|
expenses:food $400
|
|
expenses:home $1000
|
|
budgeted
|
|
|
|
###############################################################################
|
|
# 3. Transactions are what it\[aq]s all about; they are dated events,
|
|
# usually describing movements of money.
|
|
# They begin with a date.
|
|
|
|
# DATE DESCRIPTION ; This is a transaction comment.
|
|
# ACCOUNT NAME 1 AMOUNT1 ; <\- posting 1. This is a posting comment.
|
|
# ACCOUNT NAME 2 AMOUNT2 ; <\- posting 2. Postings must be indented.
|
|
# ; \[ha]\[ha] At least 2 spaces between account and amount.
|
|
# ... ; Any number of postings is allowed. The amounts must balance (sum to 0).
|
|
|
|
2022\-01\-01 opening balances are declared this way
|
|
assets:checking $1000 ; Account names can be anything. lower case is easy to type.
|
|
assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common.
|
|
assets:cash:wallet $100 ; : indicates subaccounts.
|
|
liabilities:credit card $\-200 ; liabilities, equity, revenues balances are usually negative.
|
|
equity ; One amount can be left blank; $\-1900 is inferred here.
|
|
|
|
2022\-04\-15 * (#12345) pay taxes
|
|
; There can be a ! or * after the date meaning \[dq]pending\[dq] or \[dq]cleared\[dq].
|
|
; There can be a transaction code (text in parentheses) after the date/status.
|
|
; Amounts\[aq] sign represents direction of flow, or credit/debit:
|
|
assets:checking $\-500 ; minus means removed from this account (credit)
|
|
expenses:tax:us:2021 $500 ; plus means added to this account (debit)
|
|
; revenue/expense categories are also \[dq]accounts\[dq]
|
|
|
|
2022\-01\-01 ; The description is optional.
|
|
; Any currency/commodity symbols are allowed, on either side.
|
|
assets:cash:wallet GBP \-10
|
|
expenses:clothing GBP 10
|
|
assets:gringotts \-10 gold
|
|
assets:pouch 10 gold
|
|
revenues:gifts \-2 \[dq]Liquorice Wands\[dq] ; Complex symbols
|
|
assets:bag 2 \[dq]Liquorice Wands\[dq] ; must be double\-quoted.
|
|
|
|
2022\-01\-01 Cost in another commodity can be noted with \[at] or \[at]\[at]
|
|
assets:investments 2.0 AAAA \[at] $1.50 ; \[at] means per\-unit cost
|
|
assets:investments 3.0 AAAA \[at]\[at] $4 ; \[at]\[at] means total cost
|
|
assets:checking $\-7.00
|
|
|
|
2022\-01\-02 assert balances
|
|
; Balances can be asserted for extra error checking, in any transaction.
|
|
assets:investments 0 AAAA = 5.0 AAAA
|
|
assets:pouch 0 gold = 10 gold
|
|
assets:savings $0 = $1000
|
|
|
|
1999\-12\-31 Ordering transactions by date is recommended but not required.
|
|
; Postings are not required.
|
|
|
|
2022.01.01 These date
|
|
2022/1/1 formats are
|
|
12/31 also allowed (but consistent YYYY\-MM\-DD is recommended).
|
|
.EE
|
|
.SS About journal format
|
|
hledger\[aq]s usual data source is a plain text file containing journal
|
|
entries in hledger journal format.
|
|
This file represents a standard accounting general journal.
|
|
I use file names ending in \f[CR].journal\f[R], but that\[aq]s not
|
|
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 addons 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 Editor configuration at hledger.org for the full list.
|
|
.PP
|
|
Here\[aq]s a description of each part of the file format (and
|
|
hledger\[aq]s data model).
|
|
.PP
|
|
A hledger journal file can contain three kinds of thing: file comments,
|
|
transactions, and/or directives (counting periodic transaction rules and
|
|
auto posting rules as directives).
|
|
.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].
|
|
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; or 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 and in older versions of hledger, the \[dq]unmarked\[dq]
|
|
state is called \[dq]uncleared\[dq].
|
|
As of hledger 1.3 we have renamed it to unmarked for clarity.
|
|
.PP
|
|
To replicate Ledger and old hledger\[aq]s behaviour of also matching
|
|
pending, combine \-U and \-P.
|
|
.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
|
|
A transaction\[aq]s description is the rest of the line following the
|
|
date and status mark (or until a comment begins).
|
|
Sometimes called the \[dq]narration\[dq] in traditional bookkeeping, it
|
|
can be used for whatever you wish, or left blank.
|
|
Transaction descriptions can be queried, unlike comments.
|
|
.SS Payee and note
|
|
You can optionally include a \f[CR]|\f[R] (pipe) character in
|
|
descriptions to subdivide the description into separate fields for
|
|
payee/payer name on the left (up to the first \f[CR]|\f[R]) and an
|
|
additional note field on the right (after the first \f[CR]|\f[R]).
|
|
This may be worthwhile if you need to do more precise querying and
|
|
pivoting by payee or by note.
|
|
.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 containing \f[B]single
|
|
spaces\f[R], until end of line or a double space)
|
|
.IP \[bu] 2
|
|
(optional) \f[B]two or more spaces\f[R] or tabs followed by an amount.
|
|
.PP
|
|
Positive amounts are being added to the account, negative amounts are
|
|
being removed.
|
|
.PP
|
|
The amounts within a transaction must always sum up to zero.
|
|
As a convenience, one amount may be left blank; it will be inferred so
|
|
as to balance the transaction.
|
|
.PP
|
|
Be sure to note the unusual two\-space delimiter between account name
|
|
and amount.
|
|
This makes it easy to write account names containing spaces.
|
|
But if you accidentally leave only one space (or tab) before the amount,
|
|
the amount will be considered part of the account name.
|
|
.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
|
|
borrowed from Frank\[dq] or \[dq]money spent on electricity\[dq].
|
|
.PP
|
|
You can use any account names you like, but we usually start with the
|
|
traditional accounting categories, which in english are
|
|
\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].
|
|
(You might see these referred to as A, L, E, R, X for short.)
|
|
.PP
|
|
For more precise reporting, we usually divide the top level accounts
|
|
into more detailed subaccounts, by writing a full colon between account
|
|
name parts.
|
|
For example, from the account names \f[CR]assets:bank:checking\f[R] and
|
|
\f[CR]expenses:food\f[R], hledger will infer this hierarchy of five
|
|
accounts:
|
|
.IP
|
|
.EX
|
|
assets
|
|
assets:bank
|
|
assets:bank:checking
|
|
expenses
|
|
expenses:food
|
|
.EE
|
|
.PP
|
|
Shown as an outline, the hierarchical tree structure is more clear:
|
|
.IP
|
|
.EX
|
|
assets
|
|
bank
|
|
checking
|
|
expenses
|
|
food
|
|
.EE
|
|
.PP
|
|
hledger reports can summarise the account tree to any depth, so you can
|
|
go as deep as you like with subcategories, but keeping your account
|
|
names relatively simple may be best when starting out.
|
|
.PP
|
|
Account names may be capitalised or not; they may contain letters,
|
|
numbers, symbols, or single spaces.
|
|
Note, when an account name and an amount are written on the same line,
|
|
they must be separated by \f[B]two or more spaces\f[R] (or tabs).
|
|
.PP
|
|
Parentheses or brackets enclosing the full account name indicate virtual
|
|
postings, described below.
|
|
Parentheses or brackets internal to the account name have no special
|
|
meaning.
|
|
.PP
|
|
Account names can be altered temporarily or permanently by account
|
|
aliases.
|
|
.SS Amounts
|
|
After the account name, there is usually an amount.
|
|
(Important: between account name and amount, there must be \f[B]two or
|
|
more spaces\f[R].)
|
|
.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
|
|
.SS Decimal marks, digit group 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
|
|
In the integer part of the quantity (left of the decimal mark), groups
|
|
of digits can optionally be separated by a \f[I]digit group mark\f[R] \-
|
|
a space, comma, or period (different from the decimal mark):
|
|
.IP
|
|
.EX
|
|
$1,000,000.00
|
|
EUR 2.000.000,00
|
|
INR 9,99,99,999.00
|
|
1 000 000.9455
|
|
.EE
|
|
.PP
|
|
hledger is not biased towards period or comma decimal marks, so a number
|
|
containing just one period or comma, like \f[CR]1,000\f[R] or
|
|
\f[CR]1.000\f[R], is ambiguous.
|
|
In such cases hledger assumes it is a decimal mark, parsing both of
|
|
these as 1.
|
|
.PP
|
|
To disambiguate these and ensure accurate number parsing, especially if
|
|
you use digit group marks, we recommend declaring the decimal mark.
|
|
You can declare it for each file with \f[CR]decimal\-mark\f[R]
|
|
directives, or for each commodity with \f[CR]commodity\f[R] directives
|
|
(described below).
|
|
.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
|
|
(If you are writing scripts or working with hledger\[aq]s internals,
|
|
these are the \f[CR]Amount\f[R] and \f[CR]MixedAmount\f[R] types.)
|
|
.SS Directives influencing number parsing and display
|
|
You can add \f[CR]decimal\-mark\f[R] and \f[CR]commodity\f[R] directives
|
|
to the journal, to declare and control these things more explicitly and
|
|
precisely.
|
|
These are described below, but here\[aq]s a quick example:
|
|
.IP
|
|
.EX
|
|
# the decimal mark character used by all amounts in this file (all commodities)
|
|
decimal\-mark .
|
|
|
|
# display styles 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
|
|
.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.
|
|
.PP
|
|
But 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].
|
|
.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 Other cost/lot notations
|
|
A slight digression for Ledger and Beancount users.
|
|
Ledger 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 than 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
|
|
.PP
|
|
Currently, hledger treats the above like \f[CR]\[at]\f[R] and
|
|
\f[CR]\[at]\[at]\f[R]; the parentheses are ignored.
|
|
.IP \[bu] 2
|
|
\f[CR]{=FIXEDUNITCOST}\f[R] and \f[CR]{{=FIXEDTOTALCOST}}\f[R] (fixed
|
|
price)
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
when buying, means \[dq]this cost is also the fixed price, 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], specifies an
|
|
investment lot by its cost basis; does not check if that lot is present
|
|
.RE
|
|
.IP \[bu] 2
|
|
and related: \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 accepts any or all of the above in any order after
|
|
the posting amount, but ignores them.
|
|
(This can break transaction balancing.)
|
|
.PP
|
|
For Beancount users, the notation and behaviour is different:
|
|
.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 (augmenting) or selling (reducing) a lot, combined with
|
|
\f[CR]{...}\f[R]: documents the cost/selling price (not used for
|
|
transaction balancing)
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R]
|
|
.RS 2
|
|
.IP \[bu] 2
|
|
when buying (augmenting), expresses the cost for transaction balancing,
|
|
and also creates a lot with this cost basis attached
|
|
.IP \[bu] 2
|
|
when selling (reducing),
|
|
.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
|
|
.PP
|
|
Currently, hledger accepts the
|
|
\f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation but ignores it.
|
|
.IP \[bu] 2
|
|
variations: \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] etc.
|
|
.PP
|
|
Currently, hledger rejects these.
|
|
.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 sorts an account\[aq]s postings and assertions first by date and
|
|
then (for postings on the same day) by parse order.
|
|
Note this is different from Ledger, which sorts assertions only by parse
|
|
order.
|
|
(Also, Ledger assertions do not see the accumulated effect of repeated
|
|
postings to the same account within a transaction.)
|
|
.PP
|
|
So, hledger balance assertions keep working if you reorder
|
|
differently\-dated transactions within the journal.
|
|
But if you reorder same\-dated transactions or postings, assertions
|
|
might break and require updating.
|
|
This order dependence does bring an advantage: precise control over the
|
|
order of postings and assertions within a day, so you can assert
|
|
intra\-day balances.
|
|
.SS Assertions and multiple included files
|
|
Multiple files included with the \f[CR]include\f[R] directive are
|
|
processed as if concatenated into one file, preserving their order and
|
|
the posting order within each file.
|
|
It means that balance assertions in later files will see balance from
|
|
earlier files.
|
|
.PP
|
|
And if you have multiple postings to an account on the same day, split
|
|
across multiple files, and you want to assert the account\[aq]s balance
|
|
on that day, you\[aq]ll need to put the assertion in the right file \-
|
|
the last one in the sequence, probably.
|
|
.SS Assertions and multiple \-f files
|
|
Unlike \f[CR]include\f[R], when multiple files are specified on the
|
|
command line with multiple \f[CR]\-f/\-\-file\f[R] options, balance
|
|
assertions will not see balance from earlier files.
|
|
This can be useful when you do not want problems in earlier files to
|
|
disrupt valid assertions in later files.
|
|
.PP
|
|
If you do want assertions to see balance from earlier files, use
|
|
\f[CR]include\f[R], or concatenate the files temporarily.
|
|
.SS Assertions and commodities
|
|
The asserted balance must be a simple single\-commodity amount, and in
|
|
fact the assertion checks only this commodity\[aq]s balance within the
|
|
(possibly multi\-commodity) account balance.
|
|
This is how assertions work in Ledger also.
|
|
We could call this a \[dq]partial\[dq] balance assertion.
|
|
.PP
|
|
To assert the balance of more than one commodity in an account, you can
|
|
write multiple postings, each asserting one commodity\[aq]s balance.
|
|
.PP
|
|
You can make a stronger \[dq]total\[dq] balance assertion by writing a
|
|
double equals sign (\f[CR]== EXPECTEDBALANCE\f[R]).
|
|
This asserts that there are no other commodities in the account besides
|
|
the asserted one (or at least, that their balance is 0).
|
|
.IP
|
|
.EX
|
|
2013/1/1
|
|
a $1
|
|
a 1€
|
|
b $\-1
|
|
c \-1€
|
|
|
|
2013/1/2 ; These assertions succeed
|
|
a 0 = $1
|
|
a 0 = 1€
|
|
b 0 == $\-1
|
|
c 0 == \-1€
|
|
|
|
2013/1/3 ; This assertion fails as \[aq]a\[aq] also contains 1€
|
|
a 0 == $1
|
|
.EE
|
|
.PP
|
|
It\[aq]s not yet possible to make a complete assertion about a balance
|
|
that has multiple commodities.
|
|
One workaround is to isolate each commodity into its own subaccount:
|
|
.IP
|
|
.EX
|
|
2013/1/1
|
|
a:usd $1
|
|
a:euro 1€
|
|
b
|
|
|
|
2013/1/2
|
|
a 0 == 0
|
|
a:usd 0 == $1
|
|
a:euro 0 == 1€
|
|
.EE
|
|
.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 subaccounts
|
|
The balance assertions above (\f[CR]=\f[R] and \f[CR]==\f[R]) do not
|
|
count the balance from subaccounts; they check the account\[aq]s
|
|
exclusive balance only.
|
|
You can assert the balance including subaccounts by writing
|
|
\f[CR]=*\f[R] or \f[CR]==*\f[R], eg:
|
|
.IP
|
|
.EX
|
|
2019/1/1
|
|
equity:opening balances
|
|
checking:a 5
|
|
checking:b 5
|
|
checking 1 ==* 11
|
|
.EE
|
|
.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 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 Tags
|
|
Tags are a way to add extra labels or labelled data to transactions,
|
|
postings, or accounts, which you can then search or pivot on.
|
|
.PP
|
|
They are written as a word (optionally hyphenated) immediately followed
|
|
by a full colon, in a transaction or posting or account directive\[aq]s
|
|
comment.
|
|
(This is an exception to the usual rule that things in comments are
|
|
ignored.)
|
|
Eg, here four different tags are recorded: one on the checking account,
|
|
two on the transaction, and one on the expenses posting:
|
|
.IP
|
|
.EX
|
|
account assets:checking ; accounttag:
|
|
|
|
2017/1/16 bought groceries ; transactiontag\-1:
|
|
; transactiontag\-2:
|
|
assets:checking $\-1
|
|
expenses:food $1 ; postingtag:
|
|
.EE
|
|
.PP
|
|
Postings also inherit tags from their transaction and their account.
|
|
And transactions also acquire tags from their postings (and
|
|
postings\[aq] accounts).
|
|
So in the example above, the expenses posting effectively has all four
|
|
tags (by inheriting from account and transaction), and the transaction
|
|
also has all four tags (by acquiring from the expenses posting).
|
|
.PP
|
|
You can list tag names with \f[CR]hledger tags [NAMEREGEX]\f[R], or
|
|
match by tag name with a \f[CR]tag:NAMEREGEX\f[R] query.
|
|
.SS Tag values
|
|
Tags can have a value, which is any text after the colon up until a
|
|
comma or end of line (with surrounding whitespace removed).
|
|
Note this means that hledger tag values can not contain commas.
|
|
Eg in the following posting, the three tags\[aq] values are \[dq]value
|
|
1\[dq], \[dq]value 2\[dq], and \[dq]\[dq] (empty) respectively:
|
|
.IP
|
|
.EX
|
|
expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz
|
|
.EE
|
|
.PP
|
|
Note that tags can be repeated, and are additive rather than overriding:
|
|
when the same tag name is seen again with a new value, the new
|
|
name:value pair is added to the tags.
|
|
(It is not possible to override a tag\[aq]s value or remove a tag.)
|
|
.PP
|
|
You can list a tag\[aq]s values with
|
|
\f[CR]hledger tags TAGNAME \-\-values\f[R], or match by tag value with a
|
|
\f[CR]tag:NAMEREGEX=VALUEREGEX\f[R] query.
|
|
.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 decimal mark for parsing amounts of this commodity, in the following
|
|
entries until end of current file (if there is no
|
|
\f[CR]decimal\-mark\f[R] directive) 3.
|
|
and the display style for amounts of this commodity 4.
|
|
which is also the precision to use for balanced\-transaction checking in
|
|
this commodity.
|
|
Takes precedence over \f[CR]D\f[R].
|
|
Subdirectives: \f[CR]format\f[R] (Ledger\-compatible syntax).
|
|
Command line equivalent: \f[CR]\-c/\-\-commodity\-style\f[R]
|
|
T}@T{
|
|
N,Y,N,N
|
|
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
|
|
In strict mode, they restrict which accounts may be posted to by
|
|
transactions, which helps detect typos.
|
|
.IP \[bu] 2
|
|
They control account display order in reports, allowing non\-alphabetic
|
|
sorting (eg Revenues to appear above Expenses).
|
|
.IP \[bu] 2
|
|
They help with account name completion (in hledger add, hledger\-web,
|
|
hledger\-iadd, ledger\-mode, etc.)
|
|
.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 help hledger know your accounts\[aq] types (asset, liability,
|
|
equity, revenue, expense), affecting reports like balancesheet and
|
|
incomestatement.
|
|
.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
|
|
Note, however, that accounts declared in account directives are not
|
|
allowed to have surrounding brackets and parentheses, unlike accounts
|
|
used in postings.
|
|
So the following journal will not parse:
|
|
.IP
|
|
.EX
|
|
account (assets:bank:checking)
|
|
.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 subdirectives
|
|
Ledger\-style indented subdirectives are also accepted, but currently
|
|
ignored:
|
|
.IP
|
|
.EX
|
|
account assets:bank:checking
|
|
format subdirective is ignored
|
|
.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, 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.
|
|
.SS Account display order
|
|
The order in which account directives are written influences the order
|
|
in which accounts appear in reports, hledger\-ui, hledger\-web etc.
|
|
By default accounts appear in alphabetical order, but if you add these
|
|
account directives to the journal file:
|
|
.IP
|
|
.EX
|
|
account assets
|
|
account liabilities
|
|
account equity
|
|
account revenues
|
|
account expenses
|
|
.EE
|
|
.PP
|
|
those accounts will be displayed in declaration order:
|
|
.IP
|
|
.EX
|
|
$ hledger accounts \-1
|
|
assets
|
|
liabilities
|
|
equity
|
|
revenues
|
|
expenses
|
|
.EE
|
|
.PP
|
|
Any undeclared accounts are displayed last, in alphabetical order.
|
|
.PP
|
|
Sorting is done at each level of the account tree, within each group of
|
|
sibling accounts under the same parent.
|
|
And currently, this directive:
|
|
.IP
|
|
.EX
|
|
account other:zoo
|
|
.EE
|
|
.PP
|
|
would influence the position of \f[CR]zoo\f[R] among
|
|
\f[CR]other\f[R]\[aq]s subaccounts, but not the position of
|
|
\f[CR]other\f[R] among the top\-level accounts.
|
|
This means:
|
|
.IP \[bu] 2
|
|
you will sometimes declare parent accounts (eg \f[CR]account other\f[R]
|
|
above) that you don\[aq]t intend to post to, just to customize their
|
|
display order
|
|
.IP \[bu] 2
|
|
sibling accounts stay together (you couldn\[aq]t display \f[CR]x:y\f[R]
|
|
in between \f[CR]a:b\f[R] and \f[CR]a:c\f[R]).
|
|
.SS Account types
|
|
hledger knows that accounts come in several types: assets, liabilities,
|
|
expenses and so on.
|
|
This enables easy reports like balancesheet and incomestatement, and
|
|
filtering by account type with the \f[CR]type:\f[R] query.
|
|
.PP
|
|
As a convenience, hledger will detect these account types automatically
|
|
if you are using common english\-language top\-level account names
|
|
(described below).
|
|
But generally we recommend you declare types explicitly, by adding a
|
|
\f[CR]type:\f[R] tag to your top\-level account directives.
|
|
Subaccounts will inherit the type of their parent.
|
|
The tag\[aq]s value should be one of the five main account types:
|
|
.IP \[bu] 2
|
|
\f[CR]A\f[R] or \f[CR]Asset\f[R] (things you own)
|
|
.IP \[bu] 2
|
|
\f[CR]L\f[R] or \f[CR]Liability\f[R] (things you owe)
|
|
.IP \[bu] 2
|
|
\f[CR]E\f[R] or \f[CR]Equity\f[R] (investment/ownership; balanced
|
|
counterpart of assets & liabilities)
|
|
.IP \[bu] 2
|
|
\f[CR]R\f[R] or \f[CR]Revenue\f[R] (what you received money from, AKA
|
|
income; technically part of Equity)
|
|
.IP \[bu] 2
|
|
\f[CR]X\f[R] or \f[CR]Expense\f[R] (what you spend money on; technically
|
|
part of Equity)
|
|
.PP
|
|
or, it can be (these are used less often):
|
|
.IP \[bu] 2
|
|
\f[CR]C\f[R] or \f[CR]Cash\f[R] (a subtype of Asset, indicating liquid
|
|
assets for the cashflow report)
|
|
.IP \[bu] 2
|
|
\f[CR]V\f[R] or \f[CR]Conversion\f[R] (a subtype of Equity, for
|
|
conversions (see Cost reporting).)
|
|
.PP
|
|
Here is a typical set of account type declarations:
|
|
.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
|
|
Here are some tips for working with account types.
|
|
.IP \[bu] 2
|
|
The rules for inferring types from account names are as follows.
|
|
These are just a convenience that sometimes help new users get going; if
|
|
they don\[aq]t work for you, just ignore them and declare your account
|
|
types.
|
|
See also Regular expressions.
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
If account\[aq]s name contains this (CI) 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
|
|
If you declare any account types, it\[aq]s a good idea to declare an
|
|
account for all of the account types, because a mixture of declared and
|
|
name\-inferred types can disrupt certain reports.
|
|
.IP \[bu] 2
|
|
Certain uses of account aliases can disrupt account types.
|
|
See Rewriting accounts > Aliases and account types.
|
|
.IP \[bu] 2
|
|
As mentioned above, subaccounts will inherit a type from their parent
|
|
account.
|
|
More precisely, 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
|
|
For troubleshooting, you can list accounts and their types with:
|
|
.RS 2
|
|
.IP
|
|
.EX
|
|
$ hledger accounts \-\-types [ACCTPAT] [\-DEPTH] [type:TYPECODES]
|
|
.EE
|
|
.RE
|
|
.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 \-\-alias assets=bassetts type:a
|
|
.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 the precision with which this commodity\[aq]s amounts should
|
|
be compared when checking for balanced transactions.
|
|
.IP "3." 3
|
|
It declares how this commodity\[aq]s amounts should be displayed, eg
|
|
their symbol placement, digit group mark if any, digit group sizes,
|
|
decimal mark (period or comma), and the number of decimal places.
|
|
(See Commodity display style above.)
|
|
.IP "4." 3
|
|
It sets which decimal mark (period or comma) to expect when parsing
|
|
subsequent amounts in this commodity (if there is no
|
|
\f[CR]decimal\-mark\f[R] directive in effect.
|
|
See Decimal marks, digit group marks above.
|
|
For related dev discussion, see #793.)
|
|
.PP
|
|
Declaring commodities solves several common parsing/display problems, so
|
|
we recommend it.
|
|
Generally you should put \f[CR]commodity\f[R] directives at the top of
|
|
your journal file (because function 4 is position\-sensitive).
|
|
.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 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 FILEPATH
|
|
.EE
|
|
.PP
|
|
Only journal files can include, and only journal, timeclock or timedot
|
|
files can be included (not CSV files, currently).
|
|
.PP
|
|
If the file path does not begin with a slash, it is relative to the
|
|
current file\[aq]s folder.
|
|
.PP
|
|
A tilde means home directory, eg: \f[CR]include \[ti]/main.journal\f[R].
|
|
.PP
|
|
The path may contain glob patterns to match multiple files, eg:
|
|
\f[CR]include *.journal\f[R].
|
|
.PP
|
|
There is limited support for recursive wildcards: \f[CR]**/\f[R] (the
|
|
slash is required) matches 0 or more subdirectories.
|
|
It\[aq]s not super convenient since you have to avoid include cycles and
|
|
including directories, but this can be done, eg:
|
|
\f[CR]include */**/*.journal\f[R].
|
|
.PP
|
|
The path may also be prefixed to force a specific file format,
|
|
overriding the file extension (as described in Data formats):
|
|
\f[CR]include timedot:\[ti]/notes/2023*.md\f[R].
|
|
.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(#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
|
|
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 journal.
|
|
.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.
|
|
If the year is omitted, the primary date\[aq]s year is assumed.
|
|
When running reports, the primary (left) date is used by default, but
|
|
with the \f[CR]\-\-date2\f[R] flag (or \f[CR]\-\-aux\-date\f[R] or
|
|
\f[CR]\-\-effective\f[R]), the secondary (right) date will be used
|
|
instead.
|
|
.PP
|
|
The meaning of secondary dates is up to you, but it\[aq]s best to follow
|
|
a consistent rule.
|
|
Eg \[dq]primary = the bank\[aq]s clearing date, secondary = date the
|
|
transaction was initiated, if different\[dq].
|
|
.PP
|
|
Downsides: makes your financial data more complicated, less portable,
|
|
and less trustworthy in an audit.
|
|
Keeping the meaning of the two dates consistent requires discipline, and
|
|
you have to remember which reporting mode is appropriate for a given
|
|
report.
|
|
Posting dates are simpler and better.
|
|
.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
|
|
(\f[CR](some:account)\f[R]) is called a \f[I]unbalanced virtual
|
|
posting\f[R].
|
|
Such 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.
|
|
.PP
|
|
.SH CSV
|
|
hledger can read CSV files (Character Separated Value \- usually comma,
|
|
semicolon, or tab) containing dated records, automatically converting
|
|
each record into a transaction.
|
|
.PP
|
|
(To learn about \f[I]writing\f[R] CSV, see CSV output.)
|
|
.PP
|
|
For best error messages when reading CSV/TSV/SSV files, make sure they
|
|
have a corresponding \f[CR].csv\f[R], \f[CR].tsv\f[R] or \f[CR].ssv\f[R]
|
|
file extension or use a hledger file prefix (see File Extension below).
|
|
.PP
|
|
Each CSV file must be described by a corresponding \f[I]rules file\f[R].
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
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 looks for a rules file named like the CSV file with
|
|
an extra \f[CR].rules\f[R] extension, in the same directory.
|
|
Eg when asked to read \f[CR]foo/FILE.csv\f[R], hledger looks for
|
|
\f[CR]foo/FILE.csv.rules\f[R].
|
|
You can specify a different rules file with the
|
|
\f[CR]\-\-rules\-file\f[R] option.
|
|
If no rules file is found, hledger will create a sample rules file,
|
|
which you\[aq]ll need to adjust.
|
|
.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 Importing CSV data tutorial 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]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).
|
|
.PP
|
|
These are mostly equivalent, but the second method provides some extra
|
|
features.
|
|
For one, the data file can be missing, without causing an error; it is
|
|
just considered empty.
|
|
And, you can specify a different data file by adding a \[dq]source\[dq]
|
|
rule:
|
|
.IP
|
|
.EX
|
|
source ./Checking1.csv
|
|
.EE
|
|
.PP
|
|
If you specify just a file name with no path, hledger will look for it
|
|
in your system\[aq]s downloads directory (\f[CR]\[ti]/Downloads\f[R],
|
|
currently):
|
|
.IP
|
|
.EX
|
|
source Checking1.csv
|
|
.EE
|
|
.PP
|
|
And if you specify a glob pattern, hledger will read the most recent of
|
|
the matched files (useful with repeated downloads):
|
|
.IP
|
|
.EX
|
|
source Checking1*.csv
|
|
.EE
|
|
.PP
|
|
See also \[dq]Working with CSV > Reading files specified by rule\[dq].
|
|
.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
|
|
.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.
|
|
.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 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:
|
|
.IP "1." 3
|
|
A record matcher is a word or single\-line text fragment or regular
|
|
expression (\f[CR]REGEX\f[R]), 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 is preceded with a percent sign and CSV field name
|
|
(\f[CR]%CSVFIELD REGEX\f[R]).
|
|
hledger will try to match these just within the named CSV field.
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Eg: \f[CR]%date 2023\f[R]
|
|
.PP
|
|
The regular expression 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, see \[dq]Regular expressions\[dq] in the hledger
|
|
manual (https://hledger.org/hledger.html#regular\-expressions).
|
|
.SS What matchers match
|
|
With record matchers, it\[aq]s important to know that the record matched
|
|
is not the original CSV record, but a modified one: separators will be
|
|
converted to commas, and enclosing double quotes (but not enclosing
|
|
whitespace) are removed.
|
|
So for example, when reading an SSV file, if the original record was:
|
|
.IP
|
|
.EX
|
|
2023\-01\-01; \[dq]Acme, Inc.\[dq]; 1,000
|
|
.EE
|
|
.PP
|
|
the regex would see, and try to match, this modified record text:
|
|
.IP
|
|
.EX
|
|
2023\-01\-01,Acme, Inc., 1,000
|
|
.EE
|
|
.SS Combining matchers
|
|
When an if block has multiple matchers, they are combined as follows:
|
|
.IP \[bu] 2
|
|
By default they are OR\[aq]d (any one of them can match)
|
|
.IP \[bu] 2
|
|
When a matcher is preceded by ampersand (\f[CR]&\f[R]) it will be
|
|
AND\[aq]ed with the previous matcher (both of them must match)
|
|
.IP \[bu] 2
|
|
When a matcher is preceded by an exclamation mark (\f[CR]!\f[R]), the
|
|
matcher is negated (it may not match).
|
|
.PP
|
|
Currently there is a limitation: you can\[aq]t use both \f[CR]&\f[R] and
|
|
\f[CR]!\f[R] on the same line (you can\[aq]t AND a negated matcher).
|
|
.SS Match groups
|
|
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,VALUE1,VALUE2,...
|
|
MATCHERC,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).
|
|
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
|
|
matchers; whenever a matcher succeeds, assign all of the values on that
|
|
line to the corresponding hledger fields; later lines can overrider
|
|
earlier ones.
|
|
It is equivalent to this sequence of if blocks:
|
|
.IP
|
|
.EX
|
|
if MATCHERA
|
|
HLEDGERFIELD1 VALUE1
|
|
HLEDGERFIELD2 VALUE2
|
|
...
|
|
|
|
if MATCHERB
|
|
HLEDGERFIELD1 VALUE1
|
|
HLEDGERFIELD2 VALUE2
|
|
...
|
|
|
|
if MATCHERC
|
|
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,
|
|
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 use the \f[CR]\-\-rules\-file\f[R] option, 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
|
|
Like amounts in a journal file, the amounts generated by CSV rules like
|
|
\f[CR]amount1\f[R] influence commodity display styles, such as the
|
|
number of decimal places displayed in reports.
|
|
.PP
|
|
The original amounts as written in the CSV file do not affect display
|
|
style (because we don\[aq]t yet reliably know their commodity).
|
|
.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 really need
|
|
to).
|
|
First,
|
|
.IP \[bu] 2
|
|
\f[CR]include\f[R] \- all includes are inlined, from top to bottom,
|
|
depth first.
|
|
(At each include point the file is inlined and scanned for further
|
|
includes, recursively, before proceeding.)
|
|
.PP
|
|
Then \[dq]global\[dq] rules are evaluated, top to bottom.
|
|
If a rule is repeated, the last one wins:
|
|
.IP \[bu] 2
|
|
\f[CR]skip\f[R] (at top level)
|
|
.IP \[bu] 2
|
|
\f[CR]date\-format\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]newest\-first\f[R]
|
|
.IP \[bu] 2
|
|
\f[CR]fields\f[R] \- names the CSV fields, optionally sets up initial
|
|
assignments to hledger fields
|
|
.PP
|
|
Then for each CSV record in turn:
|
|
.IP \[bu] 2
|
|
test all \f[CR]if\f[R] blocks.
|
|
If any of them contain a \f[CR]end\f[R] rule, skip all remaining CSV
|
|
records.
|
|
Otherwise if any of them contain a \f[CR]skip\f[R] rule, skip that many
|
|
CSV records.
|
|
If there are multiple matched \f[CR]skip\f[R] rules, the first one wins.
|
|
.IP \[bu] 2
|
|
collect all field assignments at top level and in matched \f[CR]if\f[R]
|
|
blocks.
|
|
When there are multiple assignments for a field, keep only the last one.
|
|
.IP \[bu] 2
|
|
compute a value for each hledger field \- either the one that was
|
|
assigned to it (and interpolate the %CSVFIELD references), or a default
|
|
.IP \[bu] 2
|
|
generate a hledger transaction (journal entry) from these values.
|
|
.PP
|
|
This is all part of the CSV reader, one of several readers hledger can
|
|
use to parse input files.
|
|
When all files have been read successfully, the transactions are passed
|
|
as input to whichever hledger command the user specified.
|
|
.PP
|
|
.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
|
|
.SH Timeclock
|
|
The time logging format of timeclock.el, as read by hledger.
|
|
.PP
|
|
hledger can read time logs in timeclock format.
|
|
As with Ledger, these are (a subset of) timeclock.el\[aq]s format,
|
|
containing clock\-in and clock\-out entries as in the example below.
|
|
The date is a simple date.
|
|
The time format is HH:MM[:SS][+\-ZZZZ].
|
|
Seconds and timezone are optional.
|
|
The timezone, if present, must be four digits and is ignored (currently
|
|
the time is always interpreted as a local time).
|
|
Lines beginning with \f[CR]#\f[R] or \f[CR];\f[R] or \f[CR]*\f[R], and
|
|
blank lines, are ignored.
|
|
.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
|
|
.EE
|
|
.PP
|
|
hledger treats each clock\-in/clock\-out pair as a transaction posting
|
|
some number of hours to an account.
|
|
Or if the session spans more than one day, it is split into several
|
|
transactions, one for each day.
|
|
For the above time log, \f[CR]hledger print\f[R] generates these journal
|
|
entries:
|
|
.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
|
|
.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 emacs and the built\-in timeclock.el, or the extended
|
|
timeclock\-x.el and perhaps the extras in ledgerutils.el
|
|
.IP \[bu] 2
|
|
at the command line, use these bash aliases:
|
|
\f[CR]shell alias ti=\[dq]echo i \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq] alias to=\[dq]echo o \[ga]date \[aq]+%Y\-%m\-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R]
|
|
.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
|
|
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.
|
|
.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 Amount formatting, parseability
|
|
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 also
|
|
Decimal marks, digit group 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
|
|
.PP
|
|
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.
|
|
.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 Time periods
|
|
.SS Report start & end date
|
|
By default, most hledger reports will show the full span of time
|
|
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 time span, such as the current
|
|
month.
|
|
You can specify a start and/or end date using \f[CR]\-b/\-\-begin\f[R],
|
|
\f[CR]\-e/\-\-end\f[R], \f[CR]\-p/\-\-period\f[R] or a \f[CR]date:\f[R]
|
|
query (described below).
|
|
All of these accept the smart date syntax (below).
|
|
.PP
|
|
Some notes:
|
|
.IP \[bu] 2
|
|
End dates are exclusive, as in Ledger, so you should write the date
|
|
\f[I]after\f[R] the last day you want to see in the report.
|
|
.IP \[bu] 2
|
|
As noted in reporting options: among start/end dates specified with
|
|
\f[I]options\f[R], the last (i.e.
|
|
right\-most) option takes precedence.
|
|
.IP \[bu] 2
|
|
The effective report start and end dates are the intersection of the
|
|
start/end dates from options and that from \f[CR]date:\f[R] queries.
|
|
That is, \f[CR]date:2019\-01 date:2019 \-p\[aq]2000 to 2030\[aq]\f[R]
|
|
yields January 2019, the smallest common time span.
|
|
.IP \[bu] 2
|
|
In some cases a report interval will adjust start/end dates to fall on
|
|
interval boundaries (see below).
|
|
.PP
|
|
Examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(12.4n) lw(57.6n).
|
|
T{
|
|
\f[CR]\-b 2016/3/17\f[R]
|
|
T}@T{
|
|
begin on St.\ Patrick\[cq]s day 2016
|
|
T}
|
|
T{
|
|
\f[CR]\-e 12/1\f[R]
|
|
T}@T{
|
|
end at the start of december 1st of the current year (11/30 will be the
|
|
last date included)
|
|
T}
|
|
T{
|
|
\f[CR]\-b thismonth\f[R]
|
|
T}@T{
|
|
all transactions on or after the 1st of the current month
|
|
T}
|
|
T{
|
|
\f[CR]\-p thismonth\f[R]
|
|
T}@T{
|
|
all transactions in the current month
|
|
T}
|
|
T{
|
|
\f[CR]date:2016/3/17..\f[R]
|
|
T}@T{
|
|
the above written as queries instead (\f[CR]..\f[R] can also be replaced
|
|
with \f[CR]\-\f[R])
|
|
T}
|
|
T{
|
|
\f[CR]date:..12/1\f[R]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[CR]date:thismonth..\f[R]
|
|
T}@T{
|
|
T}
|
|
T{
|
|
\f[CR]date:thismonth\f[R]
|
|
T}@T{
|
|
T}
|
|
.TE
|
|
.SS Smart dates
|
|
hledger\[aq]s user interfaces accept a \[dq]smart date\[dq] syntax for
|
|
added convenience.
|
|
Smart dates optionally can be relative to today\[aq]s date, be written
|
|
with english words, and have less\-significant parts omitted (missing
|
|
parts are inferred as 1).
|
|
Some examples:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(24.2n) lw(45.8n).
|
|
T{
|
|
\f[CR]2004/10/1\f[R], \f[CR]2004\-01\-01\f[R], \f[CR]2004.9.1\f[R]
|
|
T}@T{
|
|
exact date, several separators allowed.
|
|
Year is 4+ digits, month is 1\-12, day is 1\-31
|
|
T}
|
|
T{
|
|
\f[CR]2004\f[R]
|
|
T}@T{
|
|
start of year
|
|
T}
|
|
T{
|
|
\f[CR]2004/10\f[R]
|
|
T}@T{
|
|
start of month
|
|
T}
|
|
T{
|
|
\f[CR]10/1\f[R]
|
|
T}@T{
|
|
month and day in current year
|
|
T}
|
|
T{
|
|
\f[CR]21\f[R]
|
|
T}@T{
|
|
day in current month
|
|
T}
|
|
T{
|
|
\f[CR]october, oct\f[R]
|
|
T}@T{
|
|
start of month in current year
|
|
T}
|
|
T{
|
|
\f[CR]yesterday, today, tomorrow\f[R]
|
|
T}@T{
|
|
\-1, 0, 1 days from today
|
|
T}
|
|
T{
|
|
\f[CR]last/this/next day/week/month/quarter/year\f[R]
|
|
T}@T{
|
|
\-1, 0, 1 periods from the current period
|
|
T}
|
|
T{
|
|
\f[CR]in n days/weeks/months/quarters/years\f[R]
|
|
T}@T{
|
|
n periods from the current period
|
|
T}
|
|
T{
|
|
\f[CR]n days/weeks/months/quarters/years ahead\f[R]
|
|
T}@T{
|
|
n periods from the current period
|
|
T}
|
|
T{
|
|
\f[CR]n days/weeks/months/quarters/years ago\f[R]
|
|
T}@T{
|
|
\-n periods from the current period
|
|
T}
|
|
T{
|
|
\f[CR]20181201\f[R]
|
|
T}@T{
|
|
8 digit YYYYMMDD with valid year month and day
|
|
T}
|
|
T{
|
|
\f[CR]201812\f[R]
|
|
T}@T{
|
|
6 digit YYYYMM with valid year and month
|
|
T}
|
|
.TE
|
|
.PP
|
|
Some counterexamples \- malformed digit sequences might give surprising
|
|
results:
|
|
.PP
|
|
.TS
|
|
tab(@);
|
|
lw(11.4n) lw(58.6n).
|
|
T{
|
|
\f[CR]201813\f[R]
|
|
T}@T{
|
|
6 digits with an invalid month is parsed as start of 6\-digit year
|
|
T}
|
|
T{
|
|
\f[CR]20181301\f[R]
|
|
T}@T{
|
|
8 digits with an invalid month is parsed as start of 8\-digit year
|
|
T}
|
|
T{
|
|
\f[CR]20181232\f[R]
|
|
T}@T{
|
|
8 digits with an invalid day gives an error
|
|
T}
|
|
T{
|
|
\f[CR]201801012\f[R]
|
|
T}@T{
|
|
9+ digits beginning with a valid YYYYMMDD gives an error
|
|
T}
|
|
.TE
|
|
.PP
|
|
\[dq]Today\[aq]s date\[dq] can be overridden with the
|
|
\f[CR]\-\-today\f[R] option, in case it\[aq]s needed for testing or for
|
|
recreating old reports.
|
|
(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 adjustment
|
|
When there is a report interval (other than daily), report start/end
|
|
dates which have been inferred, eg from the journal, are automatically
|
|
adjusted to natural period boundaries.
|
|
This is convenient for producing simple periodic reports.
|
|
More precisely:
|
|
.IP \[bu] 2
|
|
an inferred start date will be adjusted earlier if needed to fall on a
|
|
natural period boundary
|
|
.IP \[bu] 2
|
|
an inferred end date will be adjusted later if needed to make the last
|
|
period the same length as the others.
|
|
.PP
|
|
By contrast, start/end dates which have been specified explicitly, with
|
|
\f[CR]\-b\f[R], \f[CR]\-e\f[R], \f[CR]\-p\f[R] or \f[CR]date:\f[R], will
|
|
not be adjusted (since hledger 1.29).
|
|
This makes it possible to specify non\-standard report periods, but it
|
|
also means that if you are specifying a start date, you should pick one
|
|
that\[aq]s on a period boundary if you want to see simple report period
|
|
headings.
|
|
.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]
|
|
.IP \[bu] 2
|
|
\f[CR]every Nth WEEKDAYNAME [of month]\f[R]
|
|
.PP
|
|
Yearly on a custom 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: \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:
|
|
\f[CR]depth:2\f[R], \f[CR]\-\-depth=2\f[R] or \f[CR]\-2\f[R] are
|
|
equivalent.
|
|
.SH Queries
|
|
One of hledger\[aq]s strengths is being able to quickly report on a
|
|
precise subset of your data.
|
|
Most hledger commands accept query arguments, to restrict their scope.
|
|
Multiple query terms can be provided to build up a more complex query.
|
|
.IP \[bu] 2
|
|
By default, a query term is interpreted as a case\-insensitive substring
|
|
pattern for matching account names:
|
|
.RS 2
|
|
.PP
|
|
\f[CR]car:fuel\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]dining groceries\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
|
|
These patterns are actually regular expressions, so you can add regexp
|
|
metacharacters for more precision (see \[dq]Regular expressions\[dq]
|
|
above for details):
|
|
.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 account name, add one of the query type
|
|
prefixes described in \[dq]Query types\[dq] below:
|
|
.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
|
|
.RE
|
|
.IP \[bu] 2
|
|
Add a \f[CR]not:\f[R] prefix to negate a term:
|
|
.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
|
|
Terms with different types are AND\-ed, terms with the same type are
|
|
OR\-ed (mostly; see \[dq]Combining query terms\[dq] below).
|
|
The following query:
|
|
.RS 2
|
|
.PP
|
|
\f[CR]date:2022 desc:amazon desc:amzn\f[R]
|
|
.PP
|
|
is interpreted as:
|
|
.PP
|
|
\f[I]date is in 2022 AND ( transaction description contains
|
|
\[dq]amazon\[dq] OR \[dq]amzn\[dq] )\f[R]
|
|
.RE
|
|
.SS Query types
|
|
Here are the types of query term available.
|
|
Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R] to
|
|
convert them into a negative match.
|
|
.PP
|
|
\f[B]\f[CB]acct:REGEX\f[B]\f[R] or \f[B]\f[CB]REGEX\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match account names containing this case insensitive regular expression.
|
|
This is the default query type, so we usually don\[aq]t bother writing
|
|
the \[dq]acct:\[dq] prefix.
|
|
.PP
|
|
\f[B]\f[CB]amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N\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.)
|
|
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
|
|
\f[B]\f[CB]code:REGEX\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match by transaction code (eg check number).
|
|
.PP
|
|
\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.
|
|
(For a partial match, use \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 may need one
|
|
more level of escaping.
|
|
So eg to match the dollar sign:
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
\f[CR]hledger print cur:\[rs]\[rs]$\f[R].
|
|
.PP
|
|
\f[B]\f[CB]desc:REGEX\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match transaction descriptions.
|
|
.PP
|
|
\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].
|
|
.PP
|
|
\f[B]\f[CB]date2:PERIODEXPR\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match secondary dates within the specified period (independent of the
|
|
\f[CR]\-\-date2\f[R] flag).
|
|
.PP
|
|
\f[B]\f[CB]depth:N\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match (or display, depending on command) accounts at or above this
|
|
depth.
|
|
.PP
|
|
\f[B]\f[CB]expr:\[dq]TERM AND NOT (TERM OR TERM)\[dq]\f[B]\f[R] (eg)
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match with a boolean combination of queries (which must be enclosed in
|
|
quotes).
|
|
See Combining query terms below.
|
|
.PP
|
|
\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]).
|
|
.PP
|
|
\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]).
|
|
.PP
|
|
\f[B]\f[CB]real:, real:0\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match real or virtual postings respectively.
|
|
.PP
|
|
\f[B]\f[CB]status:, status:!, status:*\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match unmarked, pending, or cleared transactions respectively.
|
|
.PP
|
|
\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.
|
|
.PP
|
|
\f[B]\f[CB]tag:REGEX[=REGEX]\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
Match by tag name, and optionally also by tag value.
|
|
(To match only by value, use \f[CR]tag:.=REGEX\f[R].)
|
|
.PP
|
|
When querying by tag, note that:
|
|
.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.
|
|
.PP
|
|
(\f[B]\f[CB]inacct:ACCTNAME\f[B]\f[R]
|
|
.PD 0
|
|
.P
|
|
.PD
|
|
A special query term used automatically in hledger\-web only: tells
|
|
hledger\-web to show the transaction register for an account.)
|
|
.SS Combining query terms
|
|
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.
|
|
.PP
|
|
We also support more complex boolean queries with the \[aq]expr:\[aq]
|
|
prefix.
|
|
This allows one to combine queries using one of three operators: AND,
|
|
OR, and NOT, where NOT is different syntax for \[aq]not:\[aq].
|
|
.PP
|
|
Examples of such queries are:
|
|
.IP \[bu] 2
|
|
Match transactions with \[aq]cool\[aq] in the description AND with the
|
|
\[aq]A\[aq] tag
|
|
.RS 2
|
|
.PP
|
|
\f[CR]expr:\[dq]desc:cool AND tag:A\[dq]\f[R]
|
|
.RE
|
|
.IP \[bu] 2
|
|
Match transactions NOT to the \[aq]expenses:food\[aq] account OR with
|
|
the \[aq]A\[aq] tag
|
|
.RS 2
|
|
.PP
|
|
\f[CR]expr:\[dq]NOT expenses:food OR tag:A\[dq]\f[R]
|
|
.RE
|
|
.IP \[bu] 2
|
|
Match transactions NOT involving the \[aq]expenses:food\[aq] account OR
|
|
with the \[aq]A\[aq] tag AND involving the \[aq]expenses:drink\[aq]
|
|
account.
|
|
(the AND is implicitly added by space\-separation, following the rules
|
|
above)
|
|
.RS 2
|
|
.PP
|
|
\f[CR]expr:\[dq]expenses:food OR (tag:A expenses:drink)\[dq]\f[R]
|
|
.RE
|
|
.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 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.0 where it\[aq]s reversed, see #1625).
|
|
.SS Querying with account aliases
|
|
When account names are rewritten with \f[CR]\-\-alias\f[R] or
|
|
\f[CR]alias\f[R], note that \f[CR]acct:\f[R] will match either the old
|
|
or the new account name.
|
|
.SS Querying with cost or value
|
|
When amounts are converted to other commodities in cost or value
|
|
reports, note that \f[CR]cur:\f[R] matches the new commodity symbol, and
|
|
not the old one, and \f[CR]amt:\f[R] matches the new quantity, and not
|
|
the old one.
|
|
Note: this changed in hledger 1.22, previously it was the reverse, see
|
|
the discussion at #1625.
|
|
.SH Pivoting
|
|
Normally, hledger groups and sums amounts within each account.
|
|
The \f[CR]\-\-pivot FIELD\f[R] option substitutes some other transaction
|
|
field for account names, causing amounts to be grouped and summed by
|
|
that field\[aq]s value instead.
|
|
FIELD can be any of the transaction fields \f[CR]acct\f[R],
|
|
\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], or a tag name.
|
|
When pivoting on a tag and a posting has multiple values of that tag,
|
|
only the first value is displayed.
|
|
Values containing \f[CR]colon:separated:parts\f[R] will be displayed
|
|
hierarchically, like account names.
|
|
Multiple, colon\-delimited fields can be pivoted simultaneously,
|
|
generating a hierarchical account name.
|
|
.PP
|
|
Some 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 pivots:
|
|
.IP
|
|
.EX
|
|
$ hledger balance Income:Dues \-\-pivot kind:member
|
|
\-2 EUR Lifetime:John Doe
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
\-2 EUR
|
|
.EE
|
|
.SH Generating data
|
|
hledger has several features for generating data, such as:
|
|
.IP \[bu] 2
|
|
Periodic transaction rules can generate single or repeating transactions
|
|
following a template.
|
|
These are usually dated in the future, eg to help with forecasting.
|
|
They are activated by the \f[CR]\-\-forecast\f[R] option.
|
|
.IP \[bu] 2
|
|
The balance command\[aq]s \f[CR]\-\-budget\f[R] option uses these same
|
|
periodic rules to generate goals for the budget report.
|
|
.IP \[bu] 2
|
|
Auto posting rules can generate extra postings on certain matched
|
|
transactions.
|
|
They are always applied to forecast transactions; with the
|
|
\f[CR]\-\-auto\f[R] flag they are applied to transactions recorded in
|
|
the journal as well.
|
|
.IP \[bu] 2
|
|
The \f[CR]\-\-infer\-equity\f[R] flag infers missing conversion equity
|
|
postings from \[at]/\[at]\[at] costs.
|
|
And the inverse \f[CR]\-\-infer\-costs\f[R] flag infers missing
|
|
\[at]/\[at]\[at] costs from conversion equity postings.
|
|
.PP
|
|
Generated data of this kind is temporary, existing only at report time.
|
|
But you can see it in the output of \f[CR]hledger print\f[R], and you
|
|
can save that to your journal, in effect converting it from temporary
|
|
generated data to permanent recorded data.
|
|
This could be useful as a data entry aid.
|
|
.PP
|
|
If you are wondering what data is being generated and why, add the
|
|
\f[CR]\-\-verbose\-tags\f[R] flag.
|
|
In \f[CR]hledger print\f[R] output you will see extra tags like
|
|
\f[CR]generated\-transaction\f[R], \f[CR]generated\-posting\f[R], and
|
|
\f[CR]modified\f[R] on generated/modified data.
|
|
Also, even without \f[CR]\-\-verbose\-tags\f[R], generated data always
|
|
has equivalen hidden tags (with an underscore prefix), so eg you could
|
|
match generated transactions with
|
|
\f[CR]tag:_generated\-transaction\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 occurence 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 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], for convenience; feel free
|
|
to mentally translate to \[dq]conversion rate\[dq] or \[dq]selling
|
|
price\[dq] if helpful.
|
|
.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.
|
|
.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
|
|
Instead of reporting amounts in their original commodity, hledger can
|
|
convert them to cost/sale amount (using the conversion rate recorded in
|
|
the transaction), and/or to market value (using some market price on a
|
|
certain date).
|
|
This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option,
|
|
which will be described below.
|
|
We also provide the simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R]
|
|
options, and often one of these is all you need:
|
|
.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 P directive date is used (even
|
|
if it\[aq]s in the future)
|
|
.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.
|
|
(Note, this has a bug in hledger\-ui <=1.31: turning on valuation with
|
|
the \f[CR]V\f[R] key always resets it to \[dq]end\[dq].)
|
|
.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 Simple 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
|
|
.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 More valuation examples
|
|
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, that shows the value as of the last day
|
|
of the journal (2000\-03\-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
|
|
Show the current value (the 2000\-04\-01 price is still in effect
|
|
today):
|
|
.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
|
|
See: 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 (and a glossary).
|
|
(It\[aq]s wide, you\[aq]ll have to scroll sideways.)
|
|
It may be useful when troubleshooting.
|
|
If you find problems, please report them, ideally with a reproducible
|
|
example.
|
|
Related: #329, #1083.
|
|
.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.
|
|
.PP
|
|
\f[B]Glossary:\f[R]
|
|
.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).
|
|
.SH PART 4: COMMANDS
|
|
.SS Commands overview
|
|
Here are the built\-in commands:
|
|
.SS DATA ENTRY
|
|
These data entry commands are the only ones which can modify your
|
|
journal file.
|
|
.IP \[bu] 2
|
|
add \- add transactions using terminal prompts
|
|
.IP \[bu] 2
|
|
import \- add new transactions from other files, eg CSV files
|
|
.SS DATA CREATION
|
|
.IP \[bu] 2
|
|
close \- generate balance\-zeroing/restoring transactions
|
|
.IP \[bu] 2
|
|
rewrite \- generate auto postings, like print \-\-auto
|
|
.SS DATA MANAGEMENT
|
|
.IP \[bu] 2
|
|
check \- check for various kinds of error in the data
|
|
.IP \[bu] 2
|
|
diff \- compare account transactions in two journal files
|
|
.SS REPORTS, FINANCIAL
|
|
.IP \[bu] 2
|
|
aregister (areg) \- show transactions in a particular account
|
|
.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
|
|
.SS REPORTS, VERSATILE
|
|
.IP \[bu] 2
|
|
balance (bal) \- show balance changes, end balances, budgets, gains..
|
|
.IP \[bu] 2
|
|
print \- show transactions or export journal data
|
|
.IP \[bu] 2
|
|
register (reg) \- show postings in one or more accounts & running total
|
|
.IP \[bu] 2
|
|
roi \- show return on investments
|
|
.SS REPORTS, BASIC
|
|
.IP \[bu] 2
|
|
accounts \- show account names
|
|
.IP \[bu] 2
|
|
activity \- show bar charts of posting counts per period
|
|
.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
|
|
.IP \[bu] 2
|
|
test \- run self tests
|
|
.SS HELP
|
|
.IP \[bu] 2
|
|
help \- show the hledger manual with info/man/pager
|
|
.IP \[bu] 2
|
|
demo \- show small hledger demos in the terminal
|
|
.PP
|
|
\
|
|
.SS ADD\-ONS
|
|
And here are some typical add\-on commands.
|
|
Some of these are installed by the hledger\-install script.
|
|
If installed, they will appear in hledger\[aq]s commands list:
|
|
.IP \[bu] 2
|
|
ui \- run hledger\[aq]s terminal UI
|
|
.IP \[bu] 2
|
|
web \- run hledger\[aq]s web UI
|
|
.IP \[bu] 2
|
|
iadd \- add transactions using a TUI (currently hard to build)
|
|
.IP \[bu] 2
|
|
interest \- generate interest transactions
|
|
.IP \[bu] 2
|
|
stockquotes \- download market prices from AlphaVantage
|
|
.IP \[bu] 2
|
|
Scripts and add\-ons \- check\-fancyassertions, edit, fifo, git, move,
|
|
pijul, plot, and more..
|
|
.PP
|
|
Next, each command is described in detail, in alphabetical order.
|
|
.SS accounts
|
|
Show account names.
|
|
.PP
|
|
This command lists account names.
|
|
By default it shows all known accounts, either used in transactions or
|
|
declared with account directives.
|
|
.PP
|
|
With query arguments, only matched account names and account names
|
|
referenced by matched postings are shown.
|
|
.PP
|
|
Or it can show just the used accounts
|
|
(\f[CR]\-\-used\f[R]/\f[CR]\-u\f[R]), the declared accounts
|
|
(\f[CR]\-\-declared\f[R]/\f[CR]\-d\f[R]), the accounts declared but not
|
|
used (\f[CR]\-\-unused\f[R]), the accounts used but not declared
|
|
(\f[CR]\-\-undeclared\f[R]), or the first account matched by an account
|
|
name pattern, if any (\f[CR]\-\-find\f[R]).
|
|
.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
|
|
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
|
|
With \f[CR]\-\-positions\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]\-\-directives\f[R], it adds the \f[CR]account\f[R] keyword,
|
|
showing valid account directives which can 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
|
|
The \f[CR]\-\-find\f[R] flag can be used to look up a single account
|
|
name, in the same way that the \f[CR]aregister\f[R] command does.
|
|
It returns the alphanumerically\-first matched account name, or if none
|
|
can be found, it fails with a non\-zero exit code.
|
|
.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 activity
|
|
Show an ascii barchart of posting counts per interval.
|
|
.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
|
|
.SS add
|
|
Prompt for transactions and add them to the journal.
|
|
Any arguments will be used as default inputs for the first N prompts.
|
|
.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
|
|
If the journal defines a default commodity, it will be added to any bare
|
|
numbers entered.
|
|
.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
|
|
Example (see https://hledger.org/add.html for a detailed tutorial):
|
|
.IP
|
|
.EX
|
|
$ hledger add
|
|
Adding transactions to journal file /src/hledger/examples/sample.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 [2015/05/22]:
|
|
Description: supermarket
|
|
Account 1: expenses:food
|
|
Amount 1: $10
|
|
Account 2: assets:checking
|
|
Amount 2 [$\-10.0]:
|
|
Account 3 (or . or enter to finish this transaction): .
|
|
2015/05/22 supermarket
|
|
expenses:food $10
|
|
assets:checking $\-10.0
|
|
|
|
Save this transaction to the journal ? [y]:
|
|
Saved.
|
|
Starting the next transaction (. or ctrl\-D/ctrl\-C to quit)
|
|
Date [2015/05/22]: <CTRL\-D> $
|
|
.EE
|
|
.PP
|
|
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.
|
|
.SS aregister
|
|
(areg)
|
|
.PP
|
|
Show the transactions and running historical balance of a single
|
|
account, with each transaction displayed as one line.
|
|
.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 always included in the
|
|
running balance (\f[CR]\-\-historical\f[R] mode is always on).
|
|
.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
|
|
\f[CR]aregister\f[R] requires one argument: the account to report on.
|
|
You can write either the full account name, or a case\-insensitive
|
|
regular expression which will select the alphabetically first matched
|
|
account.
|
|
.PP
|
|
When there are multiple matches, the alphabetically\-first choice can be
|
|
surprising; eg if you have \f[CR]assets:per:checking 1\f[R] and
|
|
\f[CR]assets:biz:checking 2\f[R] accounts,
|
|
\f[CR]hledger areg checking\f[R] would select
|
|
\f[CR]assets:biz:checking 2\f[R].
|
|
It\[aq]s just a convenience to save typing, so if in doubt, write the
|
|
full account name, or a distinctive substring that matches uniquely.
|
|
.PP
|
|
Transactions involving subaccounts of this account will also be shown.
|
|
\f[CR]aregister\f[R] ignores depth limits, so its final total will
|
|
always match a balance report with similar arguments.
|
|
.PP
|
|
Any additional arguments form a query which will filter 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
|
|
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], 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 balance
|
|
(bal)
|
|
.PP
|
|
Show accounts and their balances.
|
|
.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 higher\-level variants of the \f[CR]balance\f[R]
|
|
command with convenient defaults, which can be 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 higher\-level commands as well.
|
|
.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 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[CR]json\f[R], and (multi\-period reports only:) \f[CR]html\f[R].
|
|
In \f[CR]txt\f[R] output in a colour\-supporting terminal, negative
|
|
amounts are shown in red.
|
|
.PP
|
|
The \f[CR]\-\-related\f[R]/\f[CR]\-r\f[R] flag shows the balance of the
|
|
\f[I]other\f[R] postings in the transactions of the postings which would
|
|
normally be shown.
|
|
.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, use one of the higher\-level reports, which flip the sign
|
|
automatically.
|
|
Eg: \f[CR]hledger incomestatement \-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.
|
|
.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
|
|
Convert to a single currency with \f[CR]\-V\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 types
|
|
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 [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ...\f[R]
|
|
.SS Calculation type
|
|
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 type
|
|
How amounts should accumulate across report periods.
|
|
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, 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, cashflow\f[R])
|
|
.SS Valuation type
|
|
Which kind of value or cost conversion should be applied, if any, before
|
|
displaying the report.
|
|
It is one of:
|
|
.IP \[bu] 2
|
|
no valuation type : 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 one of the equivalent simpler flags:
|
|
.IP \[bu] 2
|
|
\f[CR]\-B/\-\-cost\f[R] : like \-\-value=cost (though, note \-\-cost and
|
|
\-\-value are independent options which can both be used at once)
|
|
.IP \[bu] 2
|
|
\f[CR]\-V/\-\-market\f[R] : like \-\-value=end
|
|
.IP \[bu] 2
|
|
\f[CR]\-X COMM/\-\-exchange COMM\f[R] : like \-\-value=end,COMM
|
|
.PP
|
|
See Cost reporting and Value reporting for more about these.
|
|
.SS Combining balance report types
|
|
Most combinations of these options 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 type 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]\-\-budget\f[R] and \f[CR]\-\-forecast\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:
|
|
.IP "1." 3
|
|
\f[CR]\-\-budget\f[R] is a command\-specific option; it selects the
|
|
\f[B]budget report\f[R].
|
|
.RS 4
|
|
.PP
|
|
\f[CR]\-\-forecast\f[R] is a general option; \f[B]forecasting works with
|
|
all reports\f[R].
|
|
.RE
|
|
.IP "2." 3
|
|
\f[CR]\-\-budget\f[R] uses \f[B]all periodic rules\f[R];
|
|
\f[CR]\-\-budget=DESCPAT\f[R] uses \f[B]just the rules matched\f[R] by
|
|
DESCPAT.
|
|
.RS 4
|
|
.PP
|
|
\f[CR]\-\-forecast\f[R] uses \f[B]all periodic rules\f[R].
|
|
.RE
|
|
.IP "3." 3
|
|
\f[CR]\-\-budget\f[R]\[aq]s budget goal transactions are invisible,
|
|
except that they produce \f[B]goal amounts\f[R].
|
|
.RS 4
|
|
.PP
|
|
\f[CR]\-\-forecast\f[R]\[aq]s forecast transactions are visible, and
|
|
\f[B]appear in reports\f[R].
|
|
.RE
|
|
.IP "4." 3
|
|
\f[CR]\-\-budget\f[R] generates budget goal transactions \f[B]throughout
|
|
the report period\f[R], optionally restricted by periods specified in
|
|
the periodic transaction rules.
|
|
.RS 4
|
|
.PP
|
|
\f[CR]\-\-forecast\f[R] generates forecast transactions from \f[B]after
|
|
the last regular transaction\f[R], to the end of the report period;
|
|
while \f[CR]\-\-forecast=PERIODEXPR\f[R] generates them \f[B]throughout
|
|
the specified period\f[R]; both optionally restricted by periods
|
|
specified in the periodic transaction rules.
|
|
.RE
|
|
.SS Balance report layout
|
|
The \f[CR]\-\-layout\f[R] option affects how balance reports show
|
|
multi\-commodity amounts and commodity symbols, which can improve
|
|
readability.
|
|
It can also normalise the data for easy consumption by other programs.
|
|
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
|
|
.PP
|
|
Here are the \f[CR]\-\-layout\f[R] modes supported by each output
|
|
format; note 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:
|
|
.IP \[bu] 2
|
|
Wide layout.
|
|
With many commodities, reports can be very wide:
|
|
.RS 2
|
|
.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
|
|
.RE
|
|
.IP \[bu] 2
|
|
Limited wide layout.
|
|
A width limit reduces the width, but some commodities will be hidden:
|
|
.RS 2
|
|
.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
|
|
.RE
|
|
.IP \[bu] 2
|
|
Tall layout.
|
|
Each commodity gets a new line (may be different in each column), and
|
|
account names are repeated:
|
|
.RS 2
|
|
.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
|
|
.RE
|
|
.IP \[bu] 2
|
|
Bare layout.
|
|
Commodity symbols are kept in one column, each commodity gets its own
|
|
report row, account names are repeated:
|
|
.RS 2
|
|
.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
|
|
.RE
|
|
.IP \[bu] 2
|
|
Bare layout also affects CSV output, which is useful for producing data
|
|
that is easier to consume, eg for making charts:
|
|
.RS 2
|
|
.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
|
|
.RE
|
|
.IP \[bu] 2
|
|
Note: 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).
|
|
.IP \[bu] 2
|
|
Tidy layout produces normalised \[dq]tidy data\[dq], where every
|
|
variable has its own column and each row represents a single data point.
|
|
See
|
|
https://cran.r\-project.org/web/packages/tidyr/vignettes/tidy\-data.html
|
|
for more.
|
|
This is the easiest kind of data for other software to consume.
|
|
Here\[aq]s how it looks:
|
|
.RS 2
|
|
.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
|
|
.RE
|
|
.SS 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 balancesheet
|
|
(bs)
|
|
.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.)
|
|
Amounts are shown with normal positive sign, as in conventional
|
|
financial statements.
|
|
.PP
|
|
This report shows accounts declared with the \f[CR]Asset\f[R],
|
|
\f[CR]Cash\f[R] or \f[CR]Liability\f[R] type (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
|
|
|
|
Assets:
|
|
$\-1 assets
|
|
$1 bank:saving
|
|
$\-2 cash
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$\-1
|
|
|
|
Liabilities:
|
|
$1 liabilities:debts
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$1
|
|
|
|
Total:
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
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[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.
|
|
.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
|
|
|
|
Assets:
|
|
$\-2 assets
|
|
$1 bank:saving
|
|
$\-3 cash
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$\-2
|
|
|
|
Liabilities:
|
|
$1 liabilities:debts
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$1
|
|
|
|
Equity:
|
|
$1 equity:owner
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$1
|
|
|
|
Total:
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
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 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 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.
|
|
.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
|
|
|
|
Cash flows:
|
|
$\-1 assets
|
|
$1 bank:saving
|
|
$\-2 cash
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$\-1
|
|
|
|
Total:
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$\-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[CR]html\f[R], and \f[CR]json\f[R].
|
|
.SS check
|
|
Check for various kinds of errors in your data.
|
|
.PP
|
|
hledger provides a number of built\-in error checks to help prevent
|
|
problems in your data.
|
|
Some of these are run automatically; or, you can use this
|
|
\f[CR]check\f[R] command to run them on demand, with no output and a
|
|
zero exit code if all is well.
|
|
Specify their names (or a prefix) as argument(s).
|
|
.PP
|
|
Some examples:
|
|
.IP
|
|
.EX
|
|
hledger check # basic checks
|
|
hledger check \-s # basic + strict checks
|
|
hledger check ordereddates payees # basic + two other checks
|
|
.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:
|
|
.SS Default checks
|
|
These checks are run automatically 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.
|
|
.IP \[bu] 2
|
|
\f[B]autobalanced\f[R] \- all transactions are balanced, after
|
|
converting to cost.
|
|
Missing amounts and missing costs are inferred automatically where
|
|
possible.
|
|
.IP \[bu] 2
|
|
\f[B]assertions\f[R] \- all balance assertions in the journal are
|
|
passing.
|
|
(This check can be disabled with
|
|
\f[CR]\-I\f[R]/\f[CR]\-\-ignore\-assertions\f[R].)
|
|
.SS Strict checks
|
|
These additional checks are run when the
|
|
\f[CR]\-s\f[R]/\f[CR]\-\-strict\f[R] (strict mode) flag is used.
|
|
Or, they can be run by giving their names as arguments to
|
|
\f[CR]check\f[R]:
|
|
.IP \[bu] 2
|
|
\f[B]balanced\f[R] \- all transactions are balanced after converting to
|
|
cost, without inferring missing costs.
|
|
If conversion costs are required, they must be explicit.
|
|
.IP \[bu] 2
|
|
\f[B]accounts\f[R] \- all account names used by transactions have been
|
|
declared
|
|
.IP \[bu] 2
|
|
\f[B]commodities\f[R] \- all commodity symbols used have been declared
|
|
.SS Other checks
|
|
These checks can be run only by giving their names as arguments to
|
|
\f[CR]check\f[R].
|
|
They are more specialised and not desirable for everyone:
|
|
.IP \[bu] 2
|
|
\f[B]ordereddates\f[R] \- transactions are ordered by date within each
|
|
file
|
|
.IP \[bu] 2
|
|
\f[B]payees\f[R] \- all payees used by transactions have been declared
|
|
.IP \[bu] 2
|
|
\f[B]recentassertions\f[R] \- all accounts with balance assertions have
|
|
a balance assertion within 7 days of their latest posting
|
|
.IP \[bu] 2
|
|
\f[B]tags\f[R] \- all tags used by transactions have been declared
|
|
.IP \[bu] 2
|
|
\f[B]uniqueleafnames\f[R] \- all account leaf names are unique
|
|
.SS Custom checks
|
|
A few more checks are are available as separate add\-on commands, in
|
|
https://github.com/simonmichael/hledger/tree/master/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
|
|
.PP
|
|
You could make similar scripts to perform your own custom checks.
|
|
See: Cookbook \-> Scripting.
|
|
.SS More about specific checks
|
|
\f[CR]hledger check recentassertions\f[R] will complain if any
|
|
balance\-asserted account has postings more than 7 days after its latest
|
|
balance assertion.
|
|
This aims to prevent the situation where you are regularly updating your
|
|
journal, but forgetting to check your balances against the real world,
|
|
then one day must dig back through months of data to find an error.
|
|
It assumes that adding a balance assertion requires/reminds you to check
|
|
the real\-world balance.
|
|
(That may not be true if you auto\-generate balance assertions from bank
|
|
data; in that case, I recommend to import transactions uncleared, and
|
|
when you manually review and clear them, also check the latest assertion
|
|
against the real\-world balance.)
|
|
.SS close
|
|
(equity)
|
|
.PP
|
|
A transaction\-generating command which generates several kinds of
|
|
\[dq]closing\[dq] and/or \[dq]opening\[dq] transactions useful in
|
|
certain situations.
|
|
It prints one or two transactions to stdout, but does not write them to
|
|
the journal file; you can append or copy them there when you are happy
|
|
with the output.
|
|
.PP
|
|
This command is most often used when migrating balances to a new journal
|
|
file, at the start of a new financial year.
|
|
It can also be used to \[dq]retain earnings\[dq] (transfer revenues and
|
|
expenses to equity), or as a sort of generic mover of balances from any
|
|
group of accounts to some other account.
|
|
So it currently has six modes, selected by a mode flag.
|
|
Use only one of these flags at a time:
|
|
.IP "1." 3
|
|
With \f[CR]\-\-close\f[R] (or no mode flag) it prints a \[dq]closing
|
|
balances\[dq] transaction that zeroes out all the asset, liability, and
|
|
equity account balances, by default (this requires inferred or declared
|
|
account types).
|
|
Or, it will zero out the accounts matched by any ACCTQUERY arguments you
|
|
provide.
|
|
All of the balances are transferred to a special \[dq]opening/closing
|
|
balances\[dq] equity account.
|
|
.IP "2." 3
|
|
With \f[CR]\-\-open\f[R], it prints an opposite \[dq]opening
|
|
balances\[dq] transaction that restores the same account balances,
|
|
starting from zero.
|
|
This mode is similar to Ledger\[aq]s equity command.
|
|
.IP "3." 3
|
|
With \f[CR]\-\-migrate\f[R], it prints both the closing and opening
|
|
transactions above.
|
|
This is a common way to migrate balances to a new file at year end; run
|
|
\f[CR]hledger close \-\-migrate \-e NEWYEAR\f[R] (\-e influences the
|
|
transaction date) and add the closing transaction at the end of the old
|
|
file, and the opening transaction at the start of the new file.
|
|
Doing this means you can include past year files in your reports at any
|
|
time without disturbing asset/liability/equity balances, because the
|
|
closing balances transaction cancels out the following opening balances
|
|
transaction.
|
|
You will sometimes need to exclude these transactions from reports, eg
|
|
to see an end of year balance sheet; a \f[CR]not:opening/closing\f[R]
|
|
query argument should do.
|
|
You should probably also use this query when \f[CR]close\f[R]\-ing, to
|
|
exclude the \[dq]opening/closing balances\[dq] account which might
|
|
otherwise cause problems.
|
|
Or you can just migrate assets and liabilities:
|
|
\f[CR]hledger close type:AL\f[R].
|
|
Most people don\[aq]t need to migrate equity.
|
|
And revenues and expenses usually should not be migrated.
|
|
.IP "4." 3
|
|
With \f[CR]\-\-assert\f[R] it prints a \[dq]closing balances\[dq]
|
|
transaction that just asserts the current balances, without changing
|
|
them.
|
|
This can be useful as documention and to guard against errors and
|
|
changes.
|
|
.IP "5." 3
|
|
With \f[CR]\-\-assign\f[R] it prints an \[dq]opening balances\[dq]
|
|
transaction that restores the account balances using balance
|
|
assignments.
|
|
Balance assignments work regardless of any previous balance, so a
|
|
preceding closing balances transaction is not needed.
|
|
This is an alternative to \f[CR]\-\-close\f[R] and \f[CR]\-\-open\f[R]:
|
|
at year end, \f[CR]hledger close \-\-assert \-e NEWYEAR\f[R] in the old
|
|
file (optional, but useful for error checking), and
|
|
\f[CR]hledger close \-\-assign \-e NEWYEAR\f[R] in the new file.
|
|
This might be more convenient, eg if you are often doing cleanups or
|
|
fixes which would break closing/opening transactions.
|
|
.IP "6." 3
|
|
With \f[CR]\-\-retain\f[R], it prints a \[dq]retain earnings\[dq]
|
|
transaction that transfers revenue and expense balances to
|
|
\f[CR]equity:retained earnings\f[R].
|
|
This is a traditional end\-of\-period bookkeeping operation also called
|
|
\[dq]closing the books\[dq]; in personal accounting you probably will
|
|
not need this but it could be useful if you want to see the accounting
|
|
equation (A=L+E) balanced.
|
|
.PP
|
|
In all modes, the following things can be overridden:
|
|
.IP \[bu] 2
|
|
the transaction descriptions can be changed with
|
|
\f[CR]\-\-close\-desc=DESC\f[R] and \f[CR]\-\-open\-desc=DESC\f[R]
|
|
.IP \[bu] 2
|
|
the account to transfer to and from can be changed with
|
|
\f[CR]\-\-close\-acct=ACCT\f[R] and \f[CR]\-\-open\-acct=ACCT\f[R]
|
|
.IP \[bu] 2
|
|
the accounts to be closed/opened can be changed with
|
|
\f[CR]ACCTQUERY\f[R] (account query arguments).
|
|
.IP \[bu] 2
|
|
the closing/opening dates can be changed with \f[CR]\-e DATE\f[R] (a
|
|
report end date)
|
|
.PP
|
|
By default just one destination/source posting will be used, with its
|
|
amount left implicit.
|
|
With \f[CR]\-\-x/\-\-explicit\f[R], the 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]\-\-show\-costs\f[R], any amount costs are shown, with
|
|
separate postings for each cost.
|
|
This is currently the best way to view investment lots.
|
|
If you have many currency conversion or investment transactions, it can
|
|
generate very large journal entries.
|
|
.PP
|
|
With \f[CR]\-\-interleaved\f[R], each individual transfer is shown with
|
|
source and destination postings next to each other.
|
|
This could be useful for troubleshooting.
|
|
.PP
|
|
The default closing date is yesterday, or the journal\[aq]s end date,
|
|
whichever is later.
|
|
You can change this by specifying a report end date with \f[CR]\-e\f[R].
|
|
The last day of the report period will be the closing date, eg
|
|
\f[CR]\-e 2024\f[R] means \[dq]close on 2023\-12\-31\[dq].
|
|
The opening date is always the day after the closing date.
|
|
.SS close and balance assertions
|
|
Balance assertions will be generated, verifying that the accounts have
|
|
been reset to zero (and then restored to their previous balances, if
|
|
there is an opening transaction).
|
|
.PP
|
|
These provide useful error checking, but you can ignore them temporarily
|
|
with \f[CR]\-I\f[R], or remove them if you prefer.
|
|
.PP
|
|
You probably should avoid filtering transactions by status or realness
|
|
(\f[CR]\-C\f[R], \f[CR]\-R\f[R], \f[CR]status:\f[R]), or generating
|
|
postings (\f[CR]\-\-auto\f[R]), with this command, since the balance
|
|
assertions would depend on these.
|
|
.PP
|
|
Note custom posting dates spanning the file boundary will 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 that you can transfer the money to and from a temporary
|
|
account, in effect 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 Example: 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
|
|
Note 2022\[aq]s income statement will now show only zeroes, because
|
|
revenues and expenses have been moved entirely to equity.
|
|
To see them again, you could exclude the retain transaction:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f 2022.journal is not:desc:\[aq]retain earnings\[aq]
|
|
.EE
|
|
.SS Example: migrate balances to a new file
|
|
Close assets/liabilities/equity on 2022\-12\-31 and re\-open them on
|
|
2023\-01\-01:
|
|
.IP
|
|
.EX
|
|
$ hledger close \-\-migrate \-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
|
|
Now 2022\[aq]s balance sheet will show only zeroes, indicating a
|
|
balanced accounting equation.
|
|
(Unless you are using \[at]/\[at]\[at] notation \- in that case, try
|
|
adding \-\-infer\-equity.)
|
|
To see the end\-of\-year balances again, you could exclude the closing
|
|
transaction:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f 2022.journal bs not:desc:\[aq]closing balances\[aq]
|
|
.EE
|
|
.SS Example: excluding closing/opening transactions
|
|
When combining many files for multi\-year reports, the closing/opening
|
|
transactions cause some noise in transaction\-oriented reports like
|
|
\f[CR]print\f[R] and \f[CR]register\f[R].
|
|
You can exclude them as shown above, but \f[CR]not:desc:...\f[R] is not
|
|
ideal as it depends on consistent descriptions; also you will want to
|
|
avoid excluding the very first opening transaction, which could be
|
|
awkward.
|
|
Here is one alternative, using tags:
|
|
.PP
|
|
Add \f[CR]clopen:\f[R] tags to all opening/closing balances transactions
|
|
except the first, like this:
|
|
.IP
|
|
.EX
|
|
; 2021.journal
|
|
2021\-06\-01 first opening balances
|
|
\&...
|
|
2021\-12\-31 closing balances ; clopen:2022
|
|
\&...
|
|
.EE
|
|
.IP
|
|
.EX
|
|
; 2022.journal
|
|
2022\-01\-01 opening balances ; clopen:2022
|
|
\&...
|
|
2022\-12\-31 closing balances ; clopen:2023
|
|
\&...
|
|
.EE
|
|
.IP
|
|
.EX
|
|
; 2023.journal
|
|
2023\-01\-01 opening balances ; clopen:2023
|
|
\&...
|
|
.EE
|
|
.PP
|
|
Now, assuming a combined journal like:
|
|
.IP
|
|
.EX
|
|
; all.journal
|
|
include 2021.journal
|
|
include 2022.journal
|
|
include 2023.journal
|
|
.EE
|
|
.PP
|
|
The \f[CR]clopen:\f[R] tag can exclude all but the first opening
|
|
transaction.
|
|
To show a clean multi\-year checking register:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f all.journal areg checking not:tag:clopen
|
|
.EE
|
|
.PP
|
|
And the year values allow more precision.
|
|
To show 2022\[aq]s year\-end balance sheet:
|
|
.IP
|
|
.EX
|
|
$ hledger \-f all.journal bs \-e2023 not:tag:clopen=2023
|
|
.EE
|
|
.SS codes
|
|
List the codes seen in transactions, in the order parsed.
|
|
.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 all commodity/currency symbols used or declared in the journal.
|
|
.SS demo
|
|
Play demos of hledger usage in the terminal, if asciinema is installed.
|
|
.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
|
|
Other asciinema options can be added following a double dash, eg
|
|
\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list
|
|
asciinema\[aq]s other options.
|
|
.PP
|
|
During playback, several keys are available: SPACE to pause/unpause, .
|
|
to step forward (while paused), CTRL\-c quit.
|
|
.PP
|
|
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
|
|
.SS descriptions
|
|
List the unique descriptions that appear in transactions.
|
|
.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 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.
|
|
.PP
|
|
More precisely, for each posting affecting this account in either file,
|
|
it looks for a corresponding posting in the other file which posts the
|
|
same amount to the same account (ignoring date, description, etc.)
|
|
Since postings not transactions are compared, this also works when
|
|
multiple bank transactions have been combined into a single journal
|
|
entry.
|
|
.PP
|
|
This 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 files
|
|
List all files included in the journal.
|
|
With a REGEX argument, only file names matching the regular expression
|
|
(case sensitive) are shown.
|
|
.SS help
|
|
Show the hledger user manual in the terminal, with \f[CR]info\f[R],
|
|
\f[CR]man\f[R], or a pager.
|
|
With a TOPIC argument, open it at that topic if possible.
|
|
TOPIC can be any heading in the manual, or a heading prefix, case
|
|
insensitive.
|
|
Eg: \f[CR]commands\f[R], \f[CR]print\f[R], \f[CR]forecast\f[R],
|
|
\f[CR]journal\f[R], \f[CR]amount\f[R],
|
|
\f[CR]\[dq]auto postings\[dq]\f[R].
|
|
.PP
|
|
This command shows the hledger manual built in to your hledger version.
|
|
It can be useful when offline, or when you prefer the terminal to a web
|
|
browser, or when the appropriate hledger manual or viewing tools are not
|
|
installed 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].
|
|
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
|
|
the command is run non\-interactively, it just prints the manual to
|
|
stdout.
|
|
.PP
|
|
If using \f[CR]info\f[R], note that version 6 or greater is needed for
|
|
TOPIC lookup.
|
|
If you are on mac you will likely have info 4.8, and should consider
|
|
installing a newer version, eg with \f[CR]brew install texinfo\f[R]
|
|
(#1770).
|
|
.PP
|
|
Examples
|
|
.IP
|
|
.EX
|
|
$ hledger help \-\-help # show how the help command works
|
|
$ hledger help # show the hledger manual with info, man or $PAGER
|
|
$ hledger help journal # show the journal topic in the hledger manual
|
|
$ hledger help \-m journal # show it with man, even if info is installed
|
|
.EE
|
|
.SS import
|
|
Read new transactions added to each FILE provided as arguments since
|
|
last run, and add them to the journal.
|
|
Or with \-\-dry\-run, just print the transactions that would be added.
|
|
Or with \-\-catchup, just mark all of the FILEs\[aq] current
|
|
transactions as imported, without importing them.
|
|
.PP
|
|
This command may append new transactions 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]add\f[R]).
|
|
.PP
|
|
Unlike other hledger commands, with \f[CR]import\f[R] the journal file
|
|
is an output file, and will be modified, though only by appending
|
|
(existing data will not be changed).
|
|
The input files are specified as arguments, so to import one or more CSV
|
|
files to your main journal, you will run
|
|
\f[CR]hledger import bank.csv\f[R] or perhaps
|
|
\f[CR]hledger import *.csv\f[R].
|
|
.PP
|
|
Note you can import from any file format, though CSV files are the most
|
|
common import source, and these docs focus on that case.
|
|
.SS Deduplication
|
|
\f[CR]import\f[R] does \f[I]time\-based deduplication\f[R], to detect
|
|
only the new transactions since the last successful import.
|
|
(This does not mean \[dq]ignore transactions that look the same\[dq],
|
|
but rather \[dq]ignore transactions that have been seen before\[dq].)
|
|
This is intended for when you are periodically importing downloaded
|
|
data, which may overlap with previous downloads.
|
|
Eg if every week (or every day) you download a bank\[aq]s last three
|
|
months of CSV data, you can safely run
|
|
\f[CR]hledger import thebank.csv\f[R] each time and only new
|
|
transactions will be imported.
|
|
.PP
|
|
Since the items being read (CSV records, eg) often do not come with
|
|
unique identifiers, hledger detects new transactions by date, assuming
|
|
that:
|
|
.IP "1." 3
|
|
new items always have the newest dates
|
|
.IP "2." 3
|
|
item dates do not change across reads
|
|
.IP "3." 3
|
|
and items with the same date remain in the same relative order across
|
|
reads.
|
|
.PP
|
|
These are often true of CSV files representing transactions, or true
|
|
enough so that it works pretty well in practice.
|
|
1 is important, but violations of 2 and 3 amongst the old transactions
|
|
won\[aq]t matter (and if you import often, the new transactions will be
|
|
few, so less likely to be the ones affected).
|
|
.PP
|
|
hledger remembers the latest date processed in each input file by saving
|
|
a hidden \[dq].latest.FILE\[dq] file in FILE\[aq]s directory (after a
|
|
succesful import).
|
|
.PP
|
|
Eg when reading \f[CR]finance/bank.csv\f[R], it will look for and update
|
|
the \f[CR]finance/.latest.bank.csv\f[R] state file.
|
|
The format is simple: one or more lines containing the same ISO\-format
|
|
date (YYYY\-MM\-DD), meaning \[dq]I have processed transactions up to
|
|
this date, and this many of them on that date.\[dq] Normally you
|
|
won\[aq]t see or manipulate these state files yourself.
|
|
But if needed, you can delete them to reset the state (making all
|
|
transactions \[dq]new\[dq]), or you can construct them to \[dq]catch
|
|
up\[dq] to a certain date.
|
|
.PP
|
|
Note deduplication (and updating of state files) can also be done by
|
|
\f[CR]print \-\-new\f[R], but this is less often used.
|
|
.PP
|
|
Related: CSV > Working with CSV > Deduplicating, importing.
|
|
.SS Import testing
|
|
With \f[CR]\-\-dry\-run\f[R], the transactions that will be imported are
|
|
printed to the terminal, without updating your journal or state files.
|
|
The output is valid journal format, like the print command, so you can
|
|
re\-parse it.
|
|
Eg, to see any importable transactions which CSV rules have not
|
|
categorised:
|
|
.IP
|
|
.EX
|
|
$ hledger import \-\-dry bank.csv | hledger \-f\- \-I print unknown
|
|
.EE
|
|
.PP
|
|
or (live updating):
|
|
.IP
|
|
.EX
|
|
$ ls bank.csv* | entr bash \-c \[aq]echo ====; hledger import \-\-dry bank.csv | hledger \-f\- \-I print unknown\[aq]
|
|
.EE
|
|
.PP
|
|
Note: when importing from multiple files at once, it\[aq]s currently
|
|
possible for some .latest files to be updated successfully, while the
|
|
actual import fails because of a problem in one of the files, leaving
|
|
them out of sync (and causing some transactions to be missed).
|
|
To prevent this, do a \-\-dry\-run first and fix any problems before the
|
|
real import.
|
|
.SS Importing balance assignments
|
|
Entries added by import will have their posting amounts made explicit
|
|
(like \f[CR]hledger print \-x\f[R]).
|
|
This means that any balance assignments in imported files must be
|
|
evaluated; but, imported files don\[aq]t get to see the main file\[aq]s
|
|
account balances.
|
|
As a result, importing entries with balance assignments (eg from an
|
|
institution that provides only balances and not posting amounts) will
|
|
probably generate incorrect posting amounts.
|
|
To avoid this problem, use print instead of import:
|
|
.IP
|
|
.EX
|
|
$ hledger print IMPORTFILE [\-\-new] >> $LEDGER_FILE
|
|
.EE
|
|
.PP
|
|
(If you think import should leave amounts implicit like print does,
|
|
please test it and send a pull request.)
|
|
.SS Commodity display styles
|
|
Imported amounts will be formatted according to the canonical commodity
|
|
styles (declared or inferred) in the main journal file.
|
|
.SS incomestatement
|
|
(is)
|
|
.PP
|
|
This command displays an income statement, showing revenues and expenses
|
|
during one or more periods.
|
|
Amounts are shown with normal positive sign, as in conventional
|
|
financial statements.
|
|
.PP
|
|
This report 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
|
|
|
|
Revenues:
|
|
$\-2 income
|
|
$\-1 gifts
|
|
$\-1 salary
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$\-2
|
|
|
|
Expenses:
|
|
$2 expenses
|
|
$1 food
|
|
$1 supplies
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
$2
|
|
|
|
Total:
|
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
|
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[CR]html\f[R], and \f[CR]json\f[R].
|
|
.SS notes
|
|
List the unique notes that appear in transactions.
|
|
.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 unique payee/payer names that appear in transactions.
|
|
.PP
|
|
This command lists unique payee/payer names which have been declared
|
|
with payee directives (\-\-declared), used in transaction descriptions
|
|
(\-\-used), or both (the default).
|
|
.PP
|
|
The payee/payer 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.
|
|
This implies \-\-used.
|
|
.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.
|
|
.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 print
|
|
Show transaction journal entries, sorted by date.
|
|
.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 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 amount style
|
|
Amounts are shown right\-aligned within each transaction (but not
|
|
aligned across all transactions; you can do that with ledger\-mode in
|
|
Emacs).
|
|
.PP
|
|
Amounts will be (mostly) normalised to their commodity display style:
|
|
their symbol placement, decimal mark, and digit group marks will be made
|
|
consistent.
|
|
By default, decimal digits are shown as they are written in the journal.
|
|
.PP
|
|
With the \f[CR]\-\-round\f[R] option, \f[CR]print\f[R] will try
|
|
increasingly hard to display decimal digits according to the commodity
|
|
display styles:
|
|
.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, formatting amounts more
|
|
consistently where it\[aq]s safe to do so.
|
|
.PP
|
|
\f[CR]hard\f[R] and \f[CR]all\f[R] can cause \f[CR]print\f[R] to show
|
|
invalid unbalanced journal entries; they may be useful eg for stronger
|
|
cleanup, with manual fixups when needed.
|
|
.SS print parseability
|
|
print\[aq]s output is usually a valid hledger journal, and you can
|
|
process it again with a second hledger command.
|
|
This can be useful for certain kinds of search (though the same can be
|
|
achieved with \f[CR]expr:\f[R] queries now):
|
|
.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
|
|
There are some situations where print\[aq]s output can become
|
|
unparseable:
|
|
.IP \[bu] 2
|
|
Value reporting affects posting amounts but not balance assertion or
|
|
balance assignment amounts, potentially causing those to fail.
|
|
.IP \[bu] 2
|
|
Auto postings can generate postings with too many missing amounts.
|
|
.IP \[bu] 2
|
|
Account aliases can generate bad account names.
|
|
.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]\-\-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.
|
|
.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[CR]csv\f[R], \f[CR]tsv\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 register
|
|
(reg)
|
|
.PP
|
|
Show postings and their running total.
|
|
.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:
|
|
.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 1h
|
|
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 uses the full terminal width by default, except on windows.
|
|
You can override this by setting the \f[CR]COLUMNS\f[R] environment
|
|
variable (not a bash shell variable) or by using 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
|
|
$ COLUMNS=100 hledger reg # set with one\-time environment variable
|
|
$ export COLUMNS=100; hledger reg # set till session end (or window resize)
|
|
$ hledger reg \-w 100,40 # set overall width 100, description width 40
|
|
$ hledger reg \-w $COLUMNS,40 # use terminal width, & 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], and \f[CR]json\f[R].
|
|
.SS rewrite
|
|
Print all transactions, rewriting the postings of matched transactions.
|
|
For now the only rewrite available is adding new postings, like print
|
|
\-\-auto.
|
|
.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.
|
|
.SS roi
|
|
Shows the time\-weighted (TWR) and money\-weighted (IRR) rate of return
|
|
on your investments.
|
|
.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
|
|
.SS stats
|
|
Show journal and performance statistics.
|
|
.PP
|
|
The stats command displays 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
|
|
At the end, it shows (in the terminal) the overall run time and number
|
|
of transactions processed per second.
|
|
Note these are approximate and will vary based on machine, current load,
|
|
data size, hledger version, haskell lib versions, GHC version..
|
|
but they may be of interest.
|
|
The \f[CR]stats\f[R] command\[aq]s run time is similar to that of a
|
|
single\-column balance report.
|
|
.PP
|
|
Example:
|
|
.IP
|
|
.EX
|
|
$ hledger stats \-f examples/1000x1000x10.journal
|
|
Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal
|
|
Included files :
|
|
Transactions span : 2000\-01\-01 to 2002\-09\-27 (1000 days)
|
|
Last transaction : 2002\-09\-26 (6995 days ago)
|
|
Transactions : 1000 (1.0 per day)
|
|
Transactions last 30 days: 0 (0.0 per day)
|
|
Transactions last 7 days : 0 (0.0 per day)
|
|
Payees/descriptions : 1000
|
|
Accounts : 1000 (depth 10)
|
|
Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)
|
|
Market prices : 1000 (A)
|
|
|
|
Run time : 0.12 s
|
|
Throughput : 8342 txns/s
|
|
.EE
|
|
.PP
|
|
This command supports the \-o/\-\-output\-file option (but not
|
|
\-O/\-\-output\-format selection).
|
|
.SS tags
|
|
List the tags used in the journal, or their values.
|
|
.PP
|
|
This command lists the tag names used in the journal, whether on
|
|
transactions, postings, or account declarations.
|
|
.PP
|
|
With a TAGREGEX argument, only tag names matching this regular
|
|
expression (case insensitive, infix matched) are shown.
|
|
.PP
|
|
With QUERY arguments, only transactions and accounts matching this query
|
|
are considered.
|
|
If the query involves transaction fields (date:, desc:, amt:, ...), the
|
|
search is restricted to the matched transactions and their accounts.
|
|
.PP
|
|
With the \-\-values flag, the tags\[aq] unique non\-empty values are
|
|
listed instead.
|
|
With \-E/\-\-empty, blank/empty values are also shown.
|
|
.PP
|
|
With \-\-parsed, tags or values are shown in the order they were parsed,
|
|
with duplicates included.
|
|
(Except, tags from account declarations are always shown first.)
|
|
.PP
|
|
Tip: remember, accounts also acquire tags from their parents, postings
|
|
also acquire tags from their account and transaction, transactions also
|
|
acquire tags from their postings.
|
|
.SS test
|
|
Run built\-in unit tests.
|
|
.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
|
|
This command also accepts tasty test runner options, written after a
|
|
\-\- (double hyphen).
|
|
Eg to run only the tests in Hledger.Data.Amount, with ANSI colour codes
|
|
disabled:
|
|
.IP
|
|
.EX
|
|
$ hledger test \-\- \-pData.Amount \-\-color=never
|
|
.EE
|
|
.PP
|
|
For help on these, see https://github.com/feuerbach/tasty#options
|
|
(\f[CR]\-\- \-\-help\f[R] currently doesn\[aq]t show them).
|
|
.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
|
|
running add\-on executables directly simplifies command line parsing
|
|
(\f[CR]hledger\-ui OPTS ARGS\f[R])
|
|
.IP \[bu] 2
|
|
enclose \[dq]problematic\[dq] args 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
|
|
How to set \f[CR]LEDGER_FILE\f[R] permanently depends on your setup:
|
|
.PP
|
|
On unix and mac, running these commands in the terminal will work for
|
|
many people; adapt as needed:
|
|
.IP
|
|
.EX
|
|
$ echo \[aq]export LEDGER_FILE=\[ti]/finance/2023.journal\[aq] >> \[ti]/.profile
|
|
$ source \[ti]/.profile
|
|
.EE
|
|
.PP
|
|
When correctly configured, in a new terminal window
|
|
\f[CR]env | grep LEDGER_FILE\f[R] will show your file, and so will
|
|
\f[CR]hledger files\f[R].
|
|
.PP
|
|
On mac, this additional step might be helpful for GUI applications (like
|
|
Emacs started from the dock): add an entry to
|
|
\f[CR]\[ti]/.MacOSX/environment.plist\f[R] like
|
|
.IP
|
|
.EX
|
|
{
|
|
\[dq]LEDGER_FILE\[dq] : \[dq]\[ti]/finance/2023.journal\[dq]
|
|
}
|
|
.EE
|
|
.PP
|
|
and then run \f[CR]killall Dock\f[R] in a terminal window (or restart
|
|
the machine).
|
|
.PP
|
|
On Windows, see https://www.java.com/en/download/help/path.html, or try
|
|
running these commands in a powershell window (let us know if it
|
|
persists across a reboot, and if you need to be an Administrator):
|
|
.IP
|
|
.EX
|
|
> CD
|
|
> MKDIR finance
|
|
> SETX LEDGER_FILE \[dq]C:\[rs]Users\[rs]USERNAME\[rs]finance\[rs]2023.journal\[dq]
|
|
.EE
|
|
.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 (shortcut:
|
|
http://bugs.hledger.org), or on the #hledger chat or hledger mail list
|
|
(https://hledger.org/support).
|
|
.PP
|
|
Some known issues and limitations:
|
|
.PP
|
|
The need to precede add\-on command options with \f[CR]\-\-\f[R] when
|
|
invoked from hledger is awkward.
|
|
(See Command options, Constructing command lines.)
|
|
.PP
|
|
A UTF\-8\-aware system locale must be configured to work with non\-ascii
|
|
data.
|
|
(See Unicode characters, Troubleshooting.)
|
|
.PP
|
|
On Microsoft Windows, depending whether you are running in a CMD window
|
|
or a Cygwin/MSYS/Mintty window and how you installed hledger, non\-ascii
|
|
characters and colours may not be supported, and the tab key may not be
|
|
supported by \f[CR]hledger add\f[R].
|
|
(Running in a WSL window should resolve these.)
|
|
.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).
|
|
.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]LANG 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
|
|
Programs compiled with GHC (hledger, haskell build tools, etc.)
|
|
need the system locale to be UTF\-8\-aware, or they will fail when they
|
|
encounter non\-ascii characters.
|
|
To fix it, set the LANG environment variable to a locale which supports
|
|
UTF\-8 and which is installed on your system.
|
|
.PP
|
|
On unix, \f[CR]locale \-a\f[R] lists the installed locales.
|
|
Look for one which mentions \f[CR]utf8\f[R], \f[CR]UTF\-8\f[R] or
|
|
similar.
|
|
Some examples: \f[CR]C.UTF\-8\f[R], \f[CR]en_US.utf\-8\f[R],
|
|
\f[CR]fr_FR.utf8\f[R].
|
|
If necessary, use your system package manager to install one.
|
|
Then select it by setting the \f[CR]LANG\f[R] environment variable.
|
|
Note, exact spelling and capitalisation of the locale name may be
|
|
important: Here\[aq]s one common way to configure this permanently for
|
|
your shell:
|
|
.IP
|
|
.EX
|
|
$ echo \[dq]export LANG=en_US.utf8\[dq] >>\[ti]/.profile
|
|
# close and re\-open terminal window
|
|
.EE
|
|
.PP
|
|
If you are using Nix (not NixOS) for GHC and Hledger, you might need to
|
|
set the \f[CR]LOCALE_ARCHIVE\f[R] variable:
|
|
.IP
|
|
.EX
|
|
$ echo \[dq]export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale\-archive\[dq] >>\[ti]/.profile
|
|
# close and re\-open terminal window
|
|
.EE
|
|
.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)
|