8682 lines
369 KiB
Plaintext
8682 lines
369 KiB
Plaintext
|
|
HLEDGER(1) hledger User Manuals HLEDGER(1)
|
|
|
|
|
|
|
|
NAME
|
|
hledger - robust, friendly plain text accounting (CLI version)
|
|
|
|
SYNOPSIS
|
|
hledger
|
|
hledger [-f FILE] COMMAND [OPTS] [ARGS]
|
|
hledger [-f FILE] ADDONCMD -- [OPTS] [ARGS]
|
|
|
|
INTRODUCTION
|
|
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).
|
|
|
|
This manual is for hledger's command line interface, version 1.29.99.
|
|
It also describes the common options, file formats and concepts used by
|
|
all hledger programs. It might accidentally teach you some bookkeep-
|
|
ing/accounting as well! You don't need to know everything in here to
|
|
use hledger productively, but when you have a question about function-
|
|
ality, this doc should answer it. It is detailed, so do skip ahead or
|
|
skim when needed. You can read it on hledger.org, or as an info manual
|
|
or man page on your system. You can also get it from hledger itself
|
|
with
|
|
hledger --man, hledger --info or hledger help [TOPIC].
|
|
|
|
The main function of the hledger CLI is to read plain text files
|
|
describing financial transactions, crunch the numbers, and print a use-
|
|
ful report on the terminal (or save it as HTML, CSV, JSON or SQL).
|
|
Many reports are available, as subcommands. hledger will also detect
|
|
other hledger-* executables as extra subcommands.
|
|
|
|
hledger reads data from one or more files in journal, timeclock, time-
|
|
dot, or CSV format. The default file is .hledger.journal in your home
|
|
directory; this can be overridden with one or more -f FILE options, or
|
|
the LEDGER_FILE environment variable. hledger CLI can also read from
|
|
stdin with -f-; more on that below.
|
|
|
|
Here is a small but valid hledger journal file describing one transac-
|
|
tion:
|
|
|
|
2015-10-16 bought food
|
|
expenses:food $10
|
|
assets:cash
|
|
|
|
Transactions are dated movements of money (etc.) between two or more
|
|
accounts: bank accounts, your wallet, revenue/expense categories, peo-
|
|
ple, etc. You can choose any account names you wish, using : to indi-
|
|
cate subaccounts. There must be at least two spaces between account
|
|
name and amount. Positive amounts are inflow to that account (debit),
|
|
negatives are outflow from it (credit). (Some reports show revenue,
|
|
liability and equity account balances as negative numbers as a result;
|
|
this is normal.)
|
|
|
|
hledger's add command can help you add transactions, or you can install
|
|
other data entry UIs like hledger-web or hledger-iadd. For more exten-
|
|
sive/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).
|
|
|
|
To get started, run hledger add and follow the prompts, or save some
|
|
entries like the above in $HOME/.hledger.journal, then try commands
|
|
like:
|
|
hledger print -x
|
|
hledger aregister assets
|
|
hledger balance
|
|
hledger balancesheet
|
|
hledger incomestatement.
|
|
Run hledger to list the commands. See also the "Starting a journal
|
|
file" and "Setting opening balances" sections in PART 5: COMMON TASKS.
|
|
|
|
PART 1: USER INTERFACE
|
|
Options
|
|
General options
|
|
To see general usage help, including general options which are sup-
|
|
ported by most hledger commands, run hledger -h.
|
|
|
|
General help options:
|
|
|
|
-h --help
|
|
show general or COMMAND help
|
|
|
|
--man show general or COMMAND user manual with man
|
|
|
|
--info show general or COMMAND user manual with info
|
|
|
|
--version
|
|
show general or ADDONCMD version
|
|
|
|
--debug[=N]
|
|
show debug output (levels 1-9, default: 1)
|
|
|
|
General input options:
|
|
|
|
-f FILE --file=FILE
|
|
use a different input file. For stdin, use - (default:
|
|
$LEDGER_FILE or $HOME/.hledger.journal)
|
|
|
|
--rules-file=RULESFILE
|
|
Conversion rules file to use when reading CSV (default:
|
|
FILE.rules)
|
|
|
|
--separator=CHAR
|
|
Field separator to expect when reading CSV (default: ',')
|
|
|
|
--alias=OLD=NEW
|
|
rename accounts named OLD to NEW
|
|
|
|
--anon anonymize accounts and payees
|
|
|
|
--pivot FIELDNAME
|
|
use some other field or tag for the account name
|
|
|
|
-I --ignore-assertions
|
|
disable balance assertion checks (note: does not disable balance
|
|
assignments)
|
|
|
|
-s --strict
|
|
do extra error checking (check that all posted accounts are
|
|
declared)
|
|
|
|
General reporting options:
|
|
|
|
-b --begin=DATE
|
|
include postings/txns on or after this date (will be adjusted to
|
|
preceding subperiod start when using a report interval)
|
|
|
|
-e --end=DATE
|
|
include postings/txns before this date (will be adjusted to fol-
|
|
lowing subperiod end when using a report interval)
|
|
|
|
-D --daily
|
|
multiperiod/multicolumn report by day
|
|
|
|
-W --weekly
|
|
multiperiod/multicolumn report by week
|
|
|
|
-M --monthly
|
|
multiperiod/multicolumn report by month
|
|
|
|
-Q --quarterly
|
|
multiperiod/multicolumn report by quarter
|
|
|
|
-Y --yearly
|
|
multiperiod/multicolumn report by year
|
|
|
|
-p --period=PERIODEXP
|
|
set start date, end date, and/or reporting interval all at once
|
|
using period expressions syntax
|
|
|
|
--date2
|
|
match the secondary date instead (see command help for other
|
|
effects)
|
|
|
|
--today=DATE
|
|
override today's date (affects relative smart dates, for
|
|
tests/examples)
|
|
|
|
-U --unmarked
|
|
include only unmarked postings/txns (can combine with -P or -C)
|
|
|
|
-P --pending
|
|
include only pending postings/txns
|
|
|
|
-C --cleared
|
|
include only cleared postings/txns
|
|
|
|
-R --real
|
|
include only non-virtual postings
|
|
|
|
-NUM --depth=NUM
|
|
hide/aggregate accounts or postings more than NUM levels deep
|
|
|
|
-E --empty
|
|
show items with zero amount, normally hidden (and vice-versa in
|
|
hledger-ui/hledger-web)
|
|
|
|
-B --cost
|
|
convert amounts to their cost/selling amount at transaction time
|
|
|
|
-V --market
|
|
convert amounts to their market value in default valuation com-
|
|
modities
|
|
|
|
-X --exchange=COMM
|
|
convert amounts to their market value in commodity COMM
|
|
|
|
--value
|
|
convert amounts to cost or market value, more flexibly than
|
|
-B/-V/-X
|
|
|
|
--infer-market-prices
|
|
use transaction prices (recorded with @ or @@) as additional
|
|
market prices, as if they were P directives
|
|
|
|
--auto apply automated posting rules to modify transactions.
|
|
|
|
--forecast
|
|
generate future transactions from periodic transaction rules,
|
|
for the next 6 months or till report end date. In hledger-ui,
|
|
also make ordinary future transactions visible.
|
|
|
|
--commodity-style
|
|
Override the commodity style in the output for the specified
|
|
commodity. For example 'EUR1.000,00'.
|
|
|
|
--color=WHEN (or --colour=WHEN)
|
|
Should color-supporting commands use ANSI color codes in text
|
|
output. 'auto' (default): whenever stdout seems to be a color-
|
|
supporting terminal. 'always' or 'yes': always, useful eg when
|
|
piping output into 'less -R'. 'never' or 'no': never. A
|
|
NO_COLOR environment variable overrides this.
|
|
|
|
--pretty[=WHEN]
|
|
Show prettier output, e.g. using unicode box-drawing charac-
|
|
ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
|
|
'never' also work). If you provide an argument you must use
|
|
'=', e.g. '--pretty=yes'.
|
|
|
|
When a reporting option appears more than once in the command line, the
|
|
last one takes precedence.
|
|
|
|
Some reporting options can also be written as query arguments.
|
|
|
|
Command options
|
|
To see options for a particular command, including command-specific
|
|
options, run: hledger COMMAND -h.
|
|
|
|
Command-specific options must be written after the command name, eg:
|
|
hledger print -x.
|
|
|
|
Additionally, if the command is an add-on, you may need to put its
|
|
options after a double-hyphen, eg: hledger ui -- --watch. Or, you can
|
|
run the add-on executable directly: hledger-ui --watch.
|
|
|
|
Command arguments
|
|
Most hledger commands accept arguments after the command name, which
|
|
are often a query, filtering the data in some way.
|
|
|
|
You can save a set of command line options/arguments in a file, and
|
|
then reuse them by writing @FILENAME as a command line argument. Eg:
|
|
hledger bal @foo.args. (To prevent this, eg if you have an argument
|
|
that begins with a literal @, precede it with --, eg: hledger bal --
|
|
@ARG).
|
|
|
|
Inside the argument file, each line should contain just one option or
|
|
argument. Avoid the use of spaces, except inside quotes (or you'll see
|
|
a confusing error). Between a flag and its argument, use = (or noth-
|
|
ing). Bad:
|
|
|
|
assets depth:2
|
|
-X USD
|
|
|
|
Good:
|
|
|
|
assets
|
|
depth:2
|
|
-X=USD
|
|
|
|
For special characters (see below), use one less level of quoting than
|
|
you would at the command prompt. Bad:
|
|
|
|
-X"$"
|
|
|
|
Good:
|
|
|
|
-X$
|
|
|
|
See also: Save frequently used options.
|
|
|
|
Special characters
|
|
Single escaping (shell metacharacters)
|
|
In shell command lines, characters significant to your shell - such as
|
|
spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want
|
|
hledger to see them. This is done by enclosing them in single or dou-
|
|
ble quotes, or by writing a backslash before them. Eg to match an
|
|
account name containing a space:
|
|
|
|
$ hledger register 'credit card'
|
|
|
|
or:
|
|
|
|
$ hledger register credit\ card
|
|
|
|
Windows users should keep in mind that cmd treats single quote as a
|
|
regular character, so you should be using double quotes exclusively.
|
|
PowerShell treats both single and double quotes as quotes.
|
|
|
|
Double escaping (regular expression metacharacters)
|
|
Characters significant in regular expressions (described below) - such
|
|
as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if
|
|
you don't want them to be interpreted by hledger's regular expression
|
|
engine. This is done by writing backslashes before them, but since
|
|
backslash is typically also a shell metacharacter, both shell-escaping
|
|
and regex-escaping will be needed. Eg to match a literal $ sign while
|
|
using the bash shell:
|
|
|
|
$ hledger balance cur:'\$'
|
|
|
|
or:
|
|
|
|
$ hledger balance cur:\\$
|
|
|
|
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 argu-
|
|
ments intended for by the add-on command, so those need an extra level
|
|
of shell-escaping. Eg to match a literal $ sign while using the bash
|
|
shell and running an add-on command (ui):
|
|
|
|
$ hledger ui cur:'\\$'
|
|
|
|
or:
|
|
|
|
$ hledger ui cur:\\\\$
|
|
|
|
If you wondered why four backslashes, perhaps this helps:
|
|
|
|
|
|
unescaped: $
|
|
escaped: \$
|
|
double-escaped: \\$
|
|
triple-escaped: \\\\$
|
|
|
|
Or, you can avoid the extra escaping by running the add-on executable
|
|
directly:
|
|
|
|
$ hledger-ui cur:\\$
|
|
|
|
Less escaping
|
|
Options and arguments are sometimes used in places other than the shell
|
|
command line, where shell-escaping is not needed, so there you should
|
|
use one less level of escaping. Those places include:
|
|
|
|
o an @argumentfile
|
|
|
|
o hledger-ui's filter field
|
|
|
|
o hledger-web's search form
|
|
|
|
o GHCI's prompt (used by developers).
|
|
|
|
Unicode characters
|
|
hledger is expected to handle non-ascii characters correctly:
|
|
|
|
o they should be parsed correctly in input files and on the command
|
|
line, by all hledger tools (add, iadd, hledger-web's search/add/edit
|
|
forms, etc.)
|
|
|
|
o they should be displayed correctly by all hledger tools, and on-
|
|
screen alignment should be preserved.
|
|
|
|
This requires a well-configured environment. Here are some tips:
|
|
|
|
o 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: export LANG=en_US.UTF-8. There are some more details in Trou-
|
|
bleshooting. This step is essential - without it, hledger will quit
|
|
on encountering a non-ascii character (as with all GHC-compiled pro-
|
|
grams).
|
|
|
|
o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
|
|
must support unicode
|
|
|
|
o the terminal must be using a font which includes the required unicode
|
|
glyphs
|
|
|
|
o the terminal should be configured to display wide characters as dou-
|
|
ble width (for report alignment)
|
|
|
|
o on Windows, for best results you should run hledger in the same kind
|
|
of environment in which it was built. Eg hledger built in the stan-
|
|
dard CMD.EXE environment (like the binaries on our download page)
|
|
might show display problems when run in a cygwin or msys terminal,
|
|
and vice versa. (See eg #961).
|
|
|
|
Regular expressions
|
|
hledger uses regular expressions in a number of places:
|
|
|
|
o query terms, on the command line and in the hledger-web search form:
|
|
REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
|
|
|
|
o CSV rules conditional blocks: if REGEX ...
|
|
|
|
o account alias directive and --alias option: alias /REGEX/ = REPLACE-
|
|
MENT, --alias /REGEX/=REPLACEMENT
|
|
|
|
hledger's regular expressions come from the regex-tdfa library. If
|
|
they're not doing what you expect, it's important to know exactly what
|
|
they support:
|
|
|
|
1. they are case insensitive
|
|
|
|
2. they are infix matching (they do not need to match the entire thing
|
|
being matched)
|
|
|
|
3. they are POSIX ERE (extended regular expressions)
|
|
|
|
4. they also support GNU word boundaries (\b, \B, \<, \>)
|
|
|
|
5. they do not support backreferences; if you write \1, it will match
|
|
the digit 1. Except when doing text replacement, eg in account
|
|
aliases, where backreferences can be used in the replacement string
|
|
to reference capturing groups in the search regexp.
|
|
|
|
6. they do not support mode modifiers ((?s)), character classes (\w,
|
|
\d), or anything else not mentioned above.
|
|
|
|
Some things to note:
|
|
|
|
o In the alias directive and --alias option, regular expressions must
|
|
be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
|
|
these are not required.
|
|
|
|
o In queries, to match a regular expression metacharacter like $ as a
|
|
literal character, prepend a backslash. Eg to search for amounts
|
|
with the dollar sign in hledger-web, write cur:\$.
|
|
|
|
o On the command line, some metacharacters like $ have a special mean-
|
|
ing to the shell and so must be escaped at least once more. See Spe-
|
|
cial characters.
|
|
|
|
Environment
|
|
LEDGER_FILE The journal file path when not specified with -f.
|
|
|
|
On unix computers, the default value is: ~/.hledger.journal.
|
|
|
|
A more typical value is something like ~/finance/YYYY.journal, where
|
|
~/finance is a version-controlled finance directory and YYYY is the
|
|
current year. Or, ~/finance/current.journal, where current.journal is
|
|
a symbolic link to YYYY.journal.
|
|
|
|
The usual way to set this permanently is to add a command to one of
|
|
your shell's startup files (eg ~/.profile):
|
|
|
|
export LEDGER_FILE=~/finance/current.journal`
|
|
|
|
On some Mac computers, there is a more thorough way to set environment
|
|
variables, that will also affect applications started from the GUI (eg,
|
|
Emacs started from a dock icon): In ~/.MacOSX/environment.plist, add an
|
|
entry like:
|
|
|
|
{
|
|
"LEDGER_FILE" : "~/finance/current.journal"
|
|
}
|
|
|
|
For this to take effect you might need to killall Dock, or reboot.
|
|
|
|
On Windows computers, the default value is probably C:\Users\YOUR-
|
|
NAME\.hledger.journal. You can change this by running a command like
|
|
this in a powershell window (let us know if you need to be an Adminis-
|
|
trator, and if this persists across a reboot):
|
|
|
|
> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"
|
|
|
|
Or, change it in settings: see https://www.java.com/en/down-
|
|
load/help/path.html.
|
|
|
|
COLUMNS The screen width used by the register command. Default: the
|
|
full terminal width.
|
|
|
|
NO_COLOR If this variable exists with any value, hledger will not use
|
|
ANSI color codes in terminal output. This is overriden by the
|
|
--color/--colour option.
|
|
|
|
Input
|
|
hledger reads transactions from one or more data files. The default
|
|
data file is $HOME/.hledger.journal (or on Windows, something like
|
|
C:\Users\YOURNAME\.hledger.journal).
|
|
|
|
You can override this with the $LEDGER_FILE environment variable:
|
|
|
|
$ setenv LEDGER_FILE ~/finance/2016.journal
|
|
$ hledger stats
|
|
|
|
or with one or more -f/--file options:
|
|
|
|
$ hledger -f /some/file -f another_file stats
|
|
|
|
The file name - means standard input:
|
|
|
|
$ cat some.journal | hledger -f-
|
|
|
|
Data formats
|
|
Usually the data file is in hledger's journal format, but it can be in
|
|
any of the supported file formats, which currently are:
|
|
|
|
|
|
Reader: Reads: Used for file exten-
|
|
sions:
|
|
-----------------------------------------------------------------------------
|
|
journal hledger journal files and some Ledger .journal .j .hledger
|
|
journals, for transactions .ledger
|
|
time- timeclock files, for precise time log- .timeclock
|
|
clock ging
|
|
timedot timedot files, for approximate time .timedot
|
|
logging
|
|
csv comma/semicolon/tab/other-separated .csv .ssv .tsv
|
|
values, for data import
|
|
|
|
These formats are described in more detail below.
|
|
|
|
hledger detects the format automatically based on the file extensions
|
|
shown above. If it can't recognise the file extension, it assumes
|
|
journal format. So for non-journal files, it's important to use a
|
|
recognised file extension, so as to either read successfully or to show
|
|
relevant error messages.
|
|
|
|
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:
|
|
|
|
$ hledger -f csv:/some/csv-file.dat stats
|
|
|
|
Or to read stdin (-) as timeclock format:
|
|
|
|
$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-
|
|
|
|
Multiple files
|
|
You can specify multiple -f options, to read multiple files as one big
|
|
journal. There are some limitations with this:
|
|
|
|
o most directives do not affect sibling files
|
|
|
|
o balance assertions will not see any account balances from previous
|
|
files
|
|
|
|
If you need either of those things, you can
|
|
|
|
o use a single parent file which includes the others
|
|
|
|
o or concatenate the files into one before reading, eg: cat a.journal
|
|
b.journal | hledger -f- CMD.
|
|
|
|
Strict mode
|
|
hledger checks input files for valid data. By default, the most impor-
|
|
tant errors are detected, while still accepting easy journal files
|
|
without a lot of declarations:
|
|
|
|
o Are the input files parseable, with valid syntax ?
|
|
|
|
o Are all transactions balanced ?
|
|
|
|
o Do all balance assertions pass ?
|
|
|
|
With the -s/--strict flag, additional checks are performed:
|
|
|
|
o Are all accounts posted to, declared with an account directive ?
|
|
(Account error checking)
|
|
|
|
o Are all commodities declared with a commodity directive ? (Commodity
|
|
error checking)
|
|
|
|
o Are all commodity conversions declared explicitly ?
|
|
|
|
You can use the check command to run individual checks -- the ones
|
|
listed above and some more.
|
|
|
|
Commands
|
|
hledger provides a number of built-in subcommands (described below).
|
|
Most of these read your data without changing it, and display a report.
|
|
A few assist with data entry and management.
|
|
|
|
Run hledger with no arguments to list the commands available, and
|
|
hledger CMD to run a command. CMD can be the full command name, or its
|
|
standard abbreviation shown in the commands list, or any unambiguous
|
|
prefix of the name. Eg: hledger bal.
|
|
|
|
Add-on commands
|
|
Add-on commands are extra subcommands provided by programs or scripts
|
|
in your PATH
|
|
|
|
o whose name starts with hledger-
|
|
|
|
o whose name ends with a recognised file extension: .bat,.com,.exe,
|
|
.hs,.lhs,.pl,.py,.rb,.rkt,.sh or none
|
|
|
|
o and (on unix, mac) which are executable by the current user.
|
|
|
|
Addons can be written in any language, but haskell scripts or programs
|
|
have a big advantage: they can use hledger's library code, for command-
|
|
line options, parsing and reporting.
|
|
|
|
Several add-on commands are installed by the hledger-install script.
|
|
See https://hledger.org/scripts.html for more details.
|
|
|
|
Note in a hledger command line, add-on command flags must have a double
|
|
dash (--) preceding them. Eg you must write:
|
|
|
|
$ hledger web -- --serve
|
|
|
|
and not:
|
|
|
|
$ hledger web --serve
|
|
|
|
(because the --serve flag belongs to hledger-web, not hledger).
|
|
|
|
The -h/--help and --version flags don't require --.
|
|
|
|
If you have any trouble with this, remember you can always run the add-
|
|
on program directly, eg:
|
|
|
|
$ hledger-web --serve
|
|
|
|
Output
|
|
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:
|
|
|
|
$ hledger print > foo.txt
|
|
|
|
Some commands (print, register, stats, the balance commands) also pro-
|
|
vide the -o/--output-file option, which does the same thing without
|
|
needing the shell. Eg:
|
|
|
|
$ hledger print -o foo.txt
|
|
$ hledger print -o - # write to stdout (the default)
|
|
|
|
Output format
|
|
Some commands offer other kinds of output, not just text on the termi-
|
|
nal. Here are those commands and the formats currently supported:
|
|
|
|
|
|
- txt csv html json sql
|
|
--------------------------------------------------------------------------------------
|
|
aregister Y Y Y Y
|
|
balance Y 1 Y 1 Y 1,2 Y
|
|
balancesheet Y 1 Y 1 Y 1 Y
|
|
balancesheetequity Y 1 Y 1 Y 1 Y
|
|
cashflow Y 1 Y 1 Y 1 Y
|
|
incomestatement Y 1 Y 1 Y 1 Y
|
|
print Y Y Y Y
|
|
register Y Y Y
|
|
|
|
o 1 Also affected by the balance commands' --layout option.
|
|
|
|
o 2 balance does not support html output without a report interval or
|
|
with --budget.
|
|
|
|
The output format is selected by the -O/--output-format=FMT option:
|
|
|
|
$ hledger print -O csv # print CSV on stdout
|
|
|
|
or by the filename extension of an output file specified with the
|
|
-o/--output-file=FILE.FMT option:
|
|
|
|
$ hledger balancesheet -o foo.csv # write CSV to foo.csv
|
|
|
|
The -O option can be combined with -o to override the file extension,
|
|
if needed:
|
|
|
|
$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt
|
|
|
|
Some notes about the various output formats:
|
|
|
|
CSV output
|
|
o In CSV output, digit group marks (such as thousands separators) are
|
|
disabled automatically.
|
|
|
|
HTML output
|
|
o HTML output can be styled by an optional hledger.css file in the same
|
|
directory.
|
|
|
|
JSON output
|
|
o This is not yet much used; real-world feedback is welcome.
|
|
|
|
o Our JSON is rather large and verbose, since it is a faithful repre-
|
|
sentation of hledger'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.
|
|
|
|
o 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'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)
|
|
|
|
SQL output
|
|
o This is not yet much used; real-world feedback is welcome.
|
|
|
|
o SQL output is expected to work with sqlite, MySQL and PostgreSQL
|
|
|
|
o SQL output is structured with the expectations that statements will
|
|
be executed in the empty database. If you already have tables cre-
|
|
ated via SQL output of hledger, you would probably want to either
|
|
clear tables of existing data (via delete or truncate SQL statements)
|
|
or drop tables completely as otherwise your postings will be duped.
|
|
|
|
Commodity styles
|
|
When displaying amounts, hledger infers a standard display style for
|
|
each commodity/currency, as described below in Commodity display style.
|
|
|
|
If needed, this can be overridden by a -c/--commodity-style option
|
|
(except for cost amounts and amounts displayed by the print command,
|
|
which are always displayed with all decimal digits). For example, the
|
|
following will force dollar amounts to be displayed as shown:
|
|
|
|
$ hledger print -c '$1.000,0'
|
|
|
|
This option can repeated to set the display style for multiple commodi-
|
|
ties/currencies. Its argument is as described in the commodity direc-
|
|
tive.
|
|
|
|
Colour
|
|
In terminal output, some commands can produce colour when the terminal
|
|
supports it:
|
|
|
|
o if the --color/--colour option is given a value of yes or always (or
|
|
no or never), colour will (or will not) be used;
|
|
|
|
o otherwise, if the NO_COLOR environment variable is set, colour will
|
|
not be used;
|
|
|
|
o otherwise, colour will be used if the output (terminal or file) sup-
|
|
ports it.
|
|
|
|
Box-drawing
|
|
In terminal output, you can enable unicode box-drawing characters to
|
|
render prettier tables:
|
|
|
|
o if the --pretty option is given a value of yes or always (or no or
|
|
never), unicode characters will (or will not) be used;
|
|
|
|
o otherwise, unicode characters will not be used.
|
|
|
|
Debug output
|
|
We intend hledger to be relatively easy to troubleshoot, introspect and
|
|
develop. You can add --debug[=N] 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 -o/--output-file (unless you redirect stderr to stdout, eg:
|
|
2>&1). 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:
|
|
|
|
hledger bal --debug=3 2>hledger.log
|
|
|
|
Limitations
|
|
The need to precede add-on command options with -- when invoked from
|
|
hledger is awkward.
|
|
|
|
When input data contains non-ascii characters, a suitable system locale
|
|
must be configured (or there will be an unhelpful error). Eg on POSIX,
|
|
set LANG to something other than C.
|
|
|
|
In a Microsoft Windows CMD window, non-ascii characters and colours are
|
|
not supported.
|
|
|
|
On Windows, non-ascii characters may not display correctly when running
|
|
a hledger built in CMD in MSYS/CYGWIN, or vice-versa.
|
|
|
|
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
|
|
add.
|
|
|
|
Not all of Ledger's journal file syntax is supported. See hledger and
|
|
Ledger > Differences > journal format.
|
|
|
|
On large data files, hledger is slower and uses more memory than
|
|
Ledger.
|
|
|
|
Troubleshooting
|
|
Here are some issues you might encounter when you run hledger (and
|
|
remember you can also seek help from the IRC channel, mail list or bug
|
|
tracker):
|
|
|
|
Successfully installed, but "No command 'hledger' found"
|
|
stack and cabal install binaries into a special directory, which should
|
|
be added to your PATH environment variable. Eg on unix-like systems,
|
|
that is ~/.local/bin and ~/.cabal/bin respectively.
|
|
|
|
I set a custom LEDGER_FILE, but hledger is still using the default file
|
|
LEDGER_FILE should be a real environment variable, not just a shell
|
|
variable. The command env | grep LEDGER_FILE should show it. You may
|
|
need to use export. Here's an explanation.
|
|
|
|
Getting errors like "Illegal byte sequence" or "Invalid or incomplete
|
|
multibyte or wide character" or "commitAndReleaseBuffer: invalid argu-
|
|
ment (invalid character)"
|
|
Programs compiled with GHC (hledger, haskell build tools, etc.) need
|
|
to have a UTF-8-aware locale configured in the environment, otherwise
|
|
they will fail with these kinds of errors when they encounter non-ascii
|
|
characters.
|
|
|
|
To fix it, set the LANG environment variable to some locale which sup-
|
|
ports UTF-8. The locale you choose must be installed on your system.
|
|
|
|
Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:
|
|
|
|
$ file my.journal
|
|
my.journal: UTF-8 Unicode text # the file is UTF8-encoded
|
|
$ echo $LANG
|
|
C # LANG is set to the default locale, which does not support UTF8
|
|
$ locale -a # which locales are installed ?
|
|
C
|
|
en_US.utf8 # here's a UTF8-aware one we can use
|
|
POSIX
|
|
$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command
|
|
|
|
If available, C.UTF-8 will also work. If your preferred locale isn't
|
|
listed by locale -a, you might need to install it. Eg on
|
|
Ubuntu/Debian:
|
|
|
|
$ apt-get install language-pack-fr
|
|
$ locale -a
|
|
C
|
|
en_US.utf8
|
|
fr_BE.utf8
|
|
fr_CA.utf8
|
|
fr_CH.utf8
|
|
fr_FR.utf8
|
|
fr_LU.utf8
|
|
POSIX
|
|
$ LANG=fr_FR.utf8 hledger -f my.journal print
|
|
|
|
Here's how you could set it permanently, if you use a bash shell:
|
|
|
|
$ echo "export LANG=en_US.utf8" >>~/.bash_profile
|
|
$ bash --login
|
|
|
|
Exact spelling and capitalisation may be important. Note the differ-
|
|
ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow
|
|
variant spellings, but others (eg macos) require it to be exact:
|
|
|
|
$ locale -a | grep -iE en_us.*utf
|
|
en_US.UTF-8
|
|
$ LANG=en_US.UTF-8 hledger -f my.journal print
|
|
|
|
PART 2: DATA FORMATS
|
|
Journal
|
|
hledger's default file format, representing a General Journal. Here's
|
|
a cheatsheet/mini-tutorial, or you can skip ahead to About journal for-
|
|
mat.
|
|
|
|
Journal cheatsheet
|
|
# Here is the main syntax of hledger'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 "comment".
|
|
|
|
# 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
|
|
~ monthly budget goals ; <- 2+ spaces between period expression and description
|
|
expenses:food $400
|
|
expenses:home $1000
|
|
budgeted
|
|
|
|
###############################################################################
|
|
# 3. Transactions are what it'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.
|
|
# ; ^^ 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 "pending" or "cleared".
|
|
; There can be a transaction code (text in parentheses) after the date/status.
|
|
; Amounts' 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 "accounts"
|
|
|
|
Kv
|
|
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 "Liquorice Wands" ; Complex symbols
|
|
assets:bag 2 "Liquorice Wands" ; must be double-quoted.
|
|
|
|
2022-01-01 Cost in another commodity can be noted with @ or @@
|
|
assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost
|
|
assets:investments 3.0 AAAA @@ $4 ; @@ 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).
|
|
|
|
About journal format
|
|
hledger'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 .journal, but
|
|
that'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.
|
|
|
|
hledger's journal format is a compatible subset, mostly, of ledger's
|
|
journal format, so hledger can work with compatible ledger journal
|
|
files as well. It's safe, and encouraged, to run both hledger and
|
|
ledger on the same journal file, eg to validate the results you're get-
|
|
ting.
|
|
|
|
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.
|
|
|
|
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 configura-
|
|
tion at hledger.org for the full list.
|
|
|
|
Here's a description of each part of the file format (and hledger's
|
|
data model).
|
|
|
|
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).
|
|
|
|
Comments
|
|
Lines in the journal will be ignored if they begin with a hash (#) or a
|
|
semicolon (;). (See also Other syntax.) hledger will also ignore
|
|
regions beginning with a comment line and ending with an end comment
|
|
line (or file end). Here's a suggestion for choosing between them:
|
|
|
|
o # for top-level notes
|
|
|
|
o ; for commenting out things temporarily
|
|
|
|
o comment for quickly commenting large regions (remember it's there, or
|
|
you might get confused)
|
|
|
|
Eg:
|
|
|
|
# a comment line
|
|
; another commentline
|
|
comment
|
|
A multi-line comment block,
|
|
continuing until "end comment" directive
|
|
or the end of the current file.
|
|
end comment
|
|
|
|
Some hledger entries can have same-line comments attached to them, from
|
|
; (semicolon) to end of line. See Transaction comments, Posting com-
|
|
ments, and Account comments below.
|
|
|
|
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.
|
|
|
|
Each transaction is recorded as a journal entry, beginning with a sim-
|
|
ple date in column 0. This can be followed by any of the following
|
|
optional fields, separated by spaces:
|
|
|
|
o a status character (empty, !, or *)
|
|
|
|
o a code (any short number or text, enclosed in parentheses)
|
|
|
|
o a description (any remaining text until end of line or a semicolon)
|
|
|
|
o a comment (any remaining text following a semicolon until end of
|
|
line, and any following indented lines beginning with a semicolon)
|
|
|
|
o 0 or more indented posting lines, describing what was transferred and
|
|
the accounts involved (indented comment lines are also allowed, but
|
|
not blank lines or non-indented lines).
|
|
|
|
Here's a simple journal file containing one transaction:
|
|
|
|
2008/01/01 income
|
|
assets:bank:checking $1
|
|
income:salary $-1
|
|
|
|
Dates
|
|
Simple dates
|
|
Dates in the journal file use simple dates format: YYYY-MM-DD or
|
|
YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be
|
|
omitted, in which case it will be inferred from the context: the cur-
|
|
rent transaction, the default year set with a Y directive, or the cur-
|
|
rent date when the command is run. Some examples: 2010-01-31,
|
|
2010/01/31, 2010.1.31, 1/31.
|
|
|
|
(The UI also accepts simple dates, as well as the more flexible smart
|
|
dates documented in the hledger manual.)
|
|
|
|
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 date:DATE. 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:
|
|
|
|
2015/5/30
|
|
expenses:food $10 ; food purchased on saturday 5/30
|
|
assets:checking ; bank cleared it on monday, date:6/1
|
|
|
|
$ hledger -f t.j register food
|
|
2015-05-30 expenses:food $10 $10
|
|
|
|
$ hledger -f t.j register checking
|
|
2015-06-01 assets:checking $-10 $-10
|
|
|
|
DATE should be a simple date; if the year is not specified it will use
|
|
the year of the transaction's date.
|
|
The date: tag must have a valid simple date value if it is present, eg
|
|
a date: tag with no value is not allowed.
|
|
|
|
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:
|
|
|
|
|
|
mark status
|
|
------------------
|
|
unmarked
|
|
! pending
|
|
* cleared
|
|
|
|
When reporting, you can filter by status with the -U/--unmarked,
|
|
-P/--pending, and -C/--cleared flags; or the status:, status:!, and
|
|
status:* queries; or the U, P, C keys in hledger-ui.
|
|
|
|
Note, in Ledger and in older versions of hledger, the "unmarked" state
|
|
is called "uncleared". As of hledger 1.3 we have renamed it to
|
|
unmarked for clarity.
|
|
|
|
To replicate Ledger and old hledger's behaviour of also matching pend-
|
|
ing, combine -U and -P.
|
|
|
|
Status marks are optional, but can be helpful eg for reconciling with
|
|
real-world accounts. Some editor modes provide highlighting and short-
|
|
cuts 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.
|
|
|
|
What "uncleared", "pending", and "cleared" actually mean is up to you.
|
|
Here's one suggestion:
|
|
|
|
|
|
status meaning
|
|
--------------------------------------------------------------------------
|
|
uncleared recorded but not yet reconciled; needs review
|
|
pending tentatively reconciled (if needed, eg during a big reconcil-
|
|
iation)
|
|
cleared complete, reconciled as far as possible, and considered cor-
|
|
rect
|
|
|
|
With this scheme, you would use -PC to see the current balance at your
|
|
bank, -U 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.
|
|
|
|
Code
|
|
After the status mark, but before the description, you can optionally
|
|
write a transaction "code", enclosed in parentheses. This is a good
|
|
place to record a check number, or some other important transaction id
|
|
or reference number.
|
|
|
|
Description
|
|
A transaction's description is the rest of the line following the date
|
|
and status mark (or until a comment begins). Sometimes called the
|
|
"narration" in traditional bookkeeping, it can be used for whatever you
|
|
wish, or left blank. Transaction descriptions can be queried, unlike
|
|
comments.
|
|
|
|
Payee and note
|
|
You can optionally include a | (pipe) character in descriptions to sub-
|
|
divide the description into separate fields for payee/payer name on the
|
|
left (up to the first |) and an additional note field on the right
|
|
(after the first |). This may be worthwhile if you need to do more
|
|
precise querying and pivoting by payee or by note.
|
|
|
|
Transaction comments
|
|
Text following ;, after a transaction description, and/or on indented
|
|
lines immediately below it, form comments for that transaction. They
|
|
are reproduced by print but otherwise ignored, except they may contain
|
|
tags, which are not ignored.
|
|
|
|
2012-01-01 something ; a transaction comment
|
|
; a second line of transaction comment
|
|
expenses 1
|
|
assets
|
|
|
|
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:
|
|
|
|
o (optional) a status character (empty, !, or *), followed by a space
|
|
|
|
o (required) an account name (any text, optionally containing single
|
|
spaces, until end of line or a double space)
|
|
|
|
o (optional) two or more spaces or tabs followed by an amount.
|
|
|
|
Positive amounts are being added to the account, negative amounts are
|
|
being removed.
|
|
|
|
The amounts within a transaction must always sum up to zero. As a con-
|
|
venience, one amount may be left blank; it will be inferred so as to
|
|
balance the transaction.
|
|
|
|
Be sure to note the unusual two-space delimiter between account name
|
|
and amount. This makes it easy to write account names containing spa-
|
|
ces. But if you accidentally leave only one space (or tab) before the
|
|
amount, the amount will be considered part of the account name.
|
|
|
|
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 "money borrowed
|
|
from Frank" or "money spent on electricity".
|
|
|
|
You can use any account names you like, but we usually start with the
|
|
traditional accounting categories, which in english are assets, liabil-
|
|
ities, equity, revenues, expenses. (You might see these referred to as
|
|
A, L, E, R, X for short.)
|
|
|
|
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 assets:bank:checking
|
|
and expenses:food, hledger will infer this hierarchy of five accounts:
|
|
|
|
assets
|
|
assets:bank
|
|
assets:bank:checking
|
|
expenses
|
|
expenses:food
|
|
|
|
Shown as an outline, the hierarchical tree structure is more clear:
|
|
|
|
assets
|
|
bank
|
|
checking
|
|
expenses
|
|
food
|
|
|
|
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.
|
|
|
|
Account names may be capitalised or not; they may contain letters, num-
|
|
bers, symbols, or single spaces. Note, when an account name and an
|
|
amount are written on the same line, they must be separated by two or
|
|
more spaces (or tabs).
|
|
|
|
Parentheses or brackets enclosing the full account name indicate vir-
|
|
tual postings, described below. Parentheses or brackets internal to
|
|
the account name have no special meaning.
|
|
|
|
Account names can be altered temporarily or permanently by account
|
|
aliases.
|
|
|
|
Amounts
|
|
After the account name, there is usually an amount. (Important:
|
|
between account name and amount, there must be two or more spaces.)
|
|
|
|
hledger's amount format is flexible, supporting several international
|
|
formats. Here are some examples. Amounts have a number (the "quan-
|
|
tity"):
|
|
|
|
1
|
|
|
|
..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:
|
|
|
|
$1
|
|
4000 AAPL
|
|
3 "green apples"
|
|
|
|
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 com-
|
|
modity symbol:
|
|
|
|
-$1
|
|
$-1
|
|
|
|
One or more spaces between the sign and the number are acceptable when
|
|
parsing (but they won't be displayed in output):
|
|
|
|
+ $1
|
|
$- 1
|
|
|
|
Scientific E notation is allowed:
|
|
|
|
1E-6
|
|
EUR 1E3
|
|
|
|
Decimal marks, digit group marks
|
|
A decimal mark can be written as a period or a comma:
|
|
|
|
1.23
|
|
1,23456780000009
|
|
|
|
In the integer part of the quantity (left of the decimal mark), groups
|
|
of digits can optionally be separated by a digit group mark - a space,
|
|
comma, or period (different from the decimal mark):
|
|
|
|
$1,000,000.00
|
|
EUR 2.000.000,00
|
|
INR 9,99,99,999.00
|
|
1 000 000.9455
|
|
|
|
Note, a number containing a single digit group mark and no decimal mark
|
|
is ambiguous. Are these digit group marks or decimal marks ?
|
|
|
|
1,000
|
|
1.000
|
|
|
|
If you don't tell it otherwise, hledger will assume both of the above
|
|
are decimal marks, parsing both numbers as 1.
|
|
|
|
To prevent confusing parsing mistakes and undetected typos, especially
|
|
if your data contains digit group marks (eg, thousands separators), we
|
|
recommend explicitly declaring the decimal mark character in each jour-
|
|
nal file, using a directive at the top of the file. The decimal-mark
|
|
directive is best, otherwise commodity directives will also work.
|
|
These are described below.
|
|
|
|
Commodity
|
|
Amounts in hledger have both a "quantity", which is a signed decimal
|
|
number, and a "commodity", which is a currency symbol, stock ticker, or
|
|
any word or phrase describing something you are tracking.
|
|
|
|
If the commodity name contains non-letters (spaces, numbers, or punctu-
|
|
ation), you must always write it inside double quotes ("green apples",
|
|
"ABC123").
|
|
|
|
If you write just a bare number, that too will have a commodity, with
|
|
name ""; we call that the "no-symbol commodity".
|
|
|
|
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: 1 USD, 2 EUR, 3.456
|
|
TSLA. In practice, you will only see multi-commodity amounts in
|
|
hledger's output; you can't write them directly in the journal file.
|
|
|
|
(If you are writing scripts or working with hledger's internals, these
|
|
are the Amount and MixedAmount types.)
|
|
|
|
Directives influencing number parsing and display
|
|
You can add decimal-mark and commodity directives to the journal, to
|
|
declare and control these things more explicitly and precisely. These
|
|
are described below, but here's a quick example:
|
|
|
|
# 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
|
|
|
|
|
|
Commodity display style
|
|
For the amounts in each commodity, hledger chooses a consistent display
|
|
style to use in most reports. (Exceptions: price amounts, and all
|
|
amounts displayed by the print command, are displayed with all of their
|
|
decimal digits visible.)
|
|
|
|
A commodity's display style is inferred as follows.
|
|
|
|
First, if a default commodity is declared with D, this commodity and
|
|
its style is applied to any no-symbol amounts in the journal.
|
|
|
|
Then each commodity's style is inferred from one of the following, in
|
|
order of preference:
|
|
|
|
o The commodity directive for that commodity (including the no-symbol
|
|
commodity), if any.
|
|
|
|
o The amounts in that commodity seen in the journal's transactions.
|
|
(Posting amounts only; prices and periodic or auto rules are ignored,
|
|
currently.)
|
|
|
|
o The built-in fallback style, which looks like this: $1000.00. (Sym-
|
|
bol on the left, period decimal mark, two decimal places.)
|
|
|
|
A style is inferred from journal amounts as follows:
|
|
|
|
o Use the general style (decimal mark, symbol placement) of the first
|
|
amount
|
|
|
|
o Use the first-seen digit group style (digit group mark, digit group
|
|
sizes), if any
|
|
|
|
o Use the maximum number of decimal places of all.
|
|
|
|
Cost amounts don't affect the commodity display style directly, but
|
|
occasionally they can do so indirectly (eg when a posting's amount is
|
|
inferred using a cost). If you find this causing problems, use a com-
|
|
modity directive to fix the display style.
|
|
|
|
To summarise: each commodity's amounts will be normalised to (a) the
|
|
style declared by a commodity directive, or (b) the style of the first
|
|
posting amount in the journal, with the first-seen digit group style
|
|
and the maximum-seen number of decimal places. So if your reports are
|
|
showing amounts in a way you don't like, eg with too many decimal
|
|
places, use a commodity directive. Some examples:
|
|
|
|
# declare euro, dollar, bitcoin and no-symbol commodities and set their
|
|
# input number formats and output display styles:
|
|
commodity EUR 1.000,
|
|
commodity $1000.00
|
|
commodity 1000.00000000 BTC
|
|
commodity 1 000.
|
|
|
|
The inferred commodity style can be overridden by supplying a command
|
|
line option.
|
|
|
|
Rounding
|
|
Amounts are stored internally as decimal numbers with up to 255 decimal
|
|
places, and displayed with the number of decimal places specified by
|
|
the commodity display style. Note, hledger uses banker's rounding: it
|
|
rounds to the nearest even number, eg 0.5 displayed with zero decimal
|
|
places is "0").
|
|
|
|
|
|
Costs
|
|
After a posting amount, you can note its cost (when buying) or selling
|
|
price (when selling) in another commodity, by writing either @ UNIT-
|
|
PRICE or @@ TOTALPRICE after it. This indicates a conversion transac-
|
|
tion, where one commodity is exchanged for another.
|
|
|
|
(You might also see this called "transaction price" 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
|
|
"cost", with the understanding that the transaction could be a purchase
|
|
or a sale.)
|
|
|
|
Costs are usually written explicitly with @ or @@, 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.
|
|
|
|
As an example, here are several ways to record purchases of a foreign
|
|
currency in hledger, using the cost notation either explicitly or
|
|
implicitly:
|
|
|
|
1. Write the price per unit, as @ UNITPRICE after the amount:
|
|
|
|
2009/1/1
|
|
assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each
|
|
assets:dollars ; balancing amount is -$135.00
|
|
|
|
2. Write the total price, as @@ TOTALPRICE after the amount:
|
|
|
|
2009/1/1
|
|
assets:euros EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot
|
|
assets:dollars
|
|
|
|
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 EUR100 @@ $135, as in example 2:
|
|
|
|
2009/1/1
|
|
assets:euros EUR100 ; one hundred euros purchased
|
|
assets:dollars $-135 ; for $135
|
|
|
|
Amounts can be converted to cost at report time using the -B/--cost
|
|
flag; this is discussed more in the COST REPORTING section.
|
|
|
|
Other cost/lot notations
|
|
A slight digression for Ledger and Beancount users. Ledger has a num-
|
|
ber of cost/lot-related notations:
|
|
|
|
o @ UNITCOST and @@ TOTALCOST
|
|
|
|
o expresses a conversion rate, as in hledger
|
|
|
|
o when buying, also creates a lot than can be selected at selling
|
|
time
|
|
|
|
o (@) UNITCOST and (@@) TOTALCOST (virtual cost)
|
|
|
|
o like the above, but also means "this cost was exceptional, don't
|
|
use it when inferring market prices".
|
|
|
|
Currently, hledger treats the above like @ and @@; the parentheses are
|
|
ignored.
|
|
|
|
o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price)
|
|
|
|
o when buying, means "this cost is also the fixed price, don't let it
|
|
fluctuate in value reports"
|
|
|
|
o {UNITCOST} and {{TOTALCOST}} (lot price)
|
|
|
|
o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre-
|
|
ates a lot
|
|
|
|
o when selling, combined with @ ..., specifies an investment lot by
|
|
its cost basis; does not check if that lot is present
|
|
|
|
o and related: [YYYY/MM/DD] (lot date)
|
|
|
|
o when buying, attaches this acquisition date to the lot
|
|
|
|
o when selling, selects a lot by its acquisition date
|
|
|
|
o (SOME TEXT) (lot note)
|
|
|
|
o when buying, attaches this note to the lot
|
|
|
|
o when selling, selects a lot by its note
|
|
|
|
Currently, hledger accepts any or all of the above in any order after
|
|
the posting amount, but ignores them. (This can break transaction bal-
|
|
ancing.)
|
|
|
|
For Beancount users, the notation and behaviour is different:
|
|
|
|
o @ UNITCOST and @@ TOTALCOST
|
|
|
|
o expresses a cost without creating a lot, as in hledger
|
|
|
|
o when buying (augmenting) or selling (reducing) a lot, combined with
|
|
{...}: documents the cost/selling price (not used for transaction
|
|
balancing)
|
|
|
|
o {UNITCOST} and {{TOTALCOST}}
|
|
|
|
o when buying (augmenting), expresses the cost for transaction bal-
|
|
ancing, and also creates a lot with this cost basis attached
|
|
|
|
o when selling (reducing),
|
|
|
|
o selects a lot by its cost basis
|
|
|
|
o raises an error if that lot is not present or can not be selected
|
|
unambiguously (depending on booking method configured)
|
|
|
|
o expresses the selling price for transaction balancing
|
|
|
|
Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but
|
|
ignores it.
|
|
|
|
o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT-
|
|
COST, YYYY-MM-DD, "LABEL"} etc.
|
|
|
|
Currently, hledger rejects these.
|
|
|
|
Balance assertions
|
|
hledger supports Ledger-style balance assertions in journal files.
|
|
These look like, for example, = EXPECTEDBALANCE following a posting's
|
|
amount. Eg here we assert the expected dollar balance in accounts a
|
|
and b after each posting:
|
|
|
|
2013/1/1
|
|
a $1 =$1
|
|
b =$-1
|
|
|
|
2013/1/2
|
|
a $1 =$2
|
|
b $-1 =$-2
|
|
|
|
After reading a journal file, hledger will check all balance assertions
|
|
and report an error if any of them fail. Balance assertions can pro-
|
|
tect you from, eg, inadvertently disrupting reconciled balances while
|
|
cleaning up old entries. You can disable them temporarily with the
|
|
-I/--ignore-assertions flag, which can be useful for troubleshooting or
|
|
for reading Ledger files. (Note: this flag currently does not disable
|
|
balance assignments, described below).
|
|
|
|
Assertions and ordering
|
|
hledger sorts an account's postings and assertions first by date and
|
|
then (for postings on the same day) by parse order. Note this is dif-
|
|
ferent from Ledger, which sorts assertions only by parse order. (Also,
|
|
Ledger assertions do not see the accumulated effect of repeated post-
|
|
ings to the same account within a transaction.)
|
|
|
|
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.
|
|
|
|
Assertions and multiple included files
|
|
Multiple files included with the include 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.
|
|
|
|
And if you have multiple postings to an account on the same day, split
|
|
across multiple files, and you want to assert the account's balance on
|
|
that day, you'll need to put the assertion in the right file - the last
|
|
one in the sequence, probably.
|
|
|
|
Assertions and multiple -f files
|
|
Unlike include, when multiple files are specified on the command line
|
|
with multiple -f/--file options, balance assertions will not see bal-
|
|
ance from earlier files. This can be useful when you do not want prob-
|
|
lems in earlier files to disrupt valid assertions in later files.
|
|
|
|
If you do want assertions to see balance from earlier files, use
|
|
include, or concatenate the files temporarily.
|
|
|
|
Assertions and commodities
|
|
The asserted balance must be a simple single-commodity amount, and in
|
|
fact the assertion checks only this commodity's balance within the
|
|
(possibly multi-commodity) account balance. This is how assertions
|
|
work in Ledger also. We could call this a "partial" balance assertion.
|
|
|
|
To assert the balance of more than one commodity in an account, you can
|
|
write multiple postings, each asserting one commodity's balance.
|
|
|
|
You can make a stronger "total" balance assertion by writing a double
|
|
equals sign (== EXPECTEDBALANCE). This asserts that there are no other
|
|
commodities in the account besides the asserted one (or at least, that
|
|
their balance is 0).
|
|
|
|
2013/1/1
|
|
a $1
|
|
a 1EUR
|
|
b $-1
|
|
c -1EUR
|
|
|
|
2013/1/2 ; These assertions succeed
|
|
a 0 = $1
|
|
a 0 = 1EUR
|
|
b 0 == $-1
|
|
c 0 == -1EUR
|
|
|
|
2013/1/3 ; This assertion fails as 'a' also contains 1EUR
|
|
a 0 == $1
|
|
|
|
It'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:
|
|
|
|
2013/1/1
|
|
a:usd $1
|
|
a:euro 1EUR
|
|
b
|
|
|
|
2013/1/2
|
|
a 0 == 0
|
|
a:usd 0 == $1
|
|
a:euro 0 == 1EUR
|
|
|
|
Assertions and prices
|
|
Balance assertions ignore costs, and should normally be written without
|
|
one:
|
|
|
|
2019/1/1
|
|
(a) $1 @ EUR1 = $1
|
|
|
|
We do allow prices to be written there, however, and print shows them,
|
|
even though they don't affect whether the assertion passes or fails.
|
|
This is for backward compatibility (hledger's close command used to
|
|
generate balance assertions with prices), and because balance assign-
|
|
ments do use them (see below).
|
|
|
|
Assertions and subaccounts
|
|
The balance assertions above (= and ==) do not count the balance from
|
|
subaccounts; they check the account's exclusive balance only. You can
|
|
assert the balance including subaccounts by writing =* or ==*, eg:
|
|
|
|
2019/1/1
|
|
equity:opening balances
|
|
checking:a 5
|
|
checking:b 5
|
|
checking 1 ==* 11
|
|
|
|
Assertions and virtual postings
|
|
Balance assertions always consider both real and virtual postings; they
|
|
are not affected by the --real/-R flag or real: query.
|
|
|
|
Assertions and auto postings
|
|
Balance assertions are affected by the --auto 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:
|
|
|
|
o assert the balance calculated with --auto, and always use --auto with
|
|
that file
|
|
|
|
o or assert the balance calculated without --auto, and never use --auto
|
|
with that file
|
|
|
|
o or avoid balance assertions on accounts affected by auto postings (or
|
|
avoid auto postings entirely).
|
|
|
|
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 asser-
|
|
tions. Balance assertion failure messages show exact amounts.
|
|
|
|
Posting comments
|
|
Text following ;, at the end of a posting line, and/or on indented
|
|
lines immediately below it, form comments for that posting. They are
|
|
reproduced by print but otherwise ignored, except they may contain
|
|
tags, which are not ignored.
|
|
|
|
2012-01-01
|
|
expenses 1 ; a comment for posting 1
|
|
assets
|
|
; a comment for posting 2
|
|
; a second comment line for posting 2
|
|
|
|
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.
|
|
|
|
They are written as a word (optionally hyphenated) immediately followed
|
|
by a full colon, in a transaction or posting or account directive's
|
|
comment. (This is an exception to the usual rule that things in com-
|
|
ments are ignored.) Eg, here four different tags are recorded: one on
|
|
the checking account, two on the transaction, and one on the expenses
|
|
posting:
|
|
|
|
account assets:checking ; accounttag:
|
|
|
|
2017/1/16 bought groceries ; transactiontag-1:
|
|
; transactiontag-2:
|
|
assets:checking $-1
|
|
expenses:food $1 ; postingtag:
|
|
|
|
Postings also inherit tags from their transaction and their account.
|
|
And transactions also acquire tags from their postings (and postings'
|
|
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).
|
|
|
|
You can list tag names with hledger tags [NAMEREGEX], or match by tag
|
|
name with a tag:NAMEREGEX query.
|
|
|
|
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 fol-
|
|
lowing posting, the three tags' values are "value 1", "value 2", and ""
|
|
(empty) respectively:
|
|
|
|
expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz
|
|
|
|
Note that tags can be repeated, and are additive rather than overrid-
|
|
ing: 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's value or remove a tag.)
|
|
|
|
You can list a tag's values with hledger tags TAGNAME --values, or
|
|
match by tag value with a tag:NAMEREGEX=VALUEREGEX query.
|
|
|
|
Directives
|
|
A directive is a line in the journal beginning with a special keyword,
|
|
that influences how the journal is processed, how things are displayed,
|
|
and so on. hledger's directives are based on (a subset of) Ledger's,
|
|
but there are many differences, and also some differences between
|
|
hledger versions. Here are some more definitions:
|
|
|
|
o subdirective - Some directives support subdirectives, written
|
|
indented below the parent directive.
|
|
|
|
o decimal mark - The character to interpret as a decimal mark (period
|
|
or comma) when parsing amounts of a commodity.
|
|
|
|
o display style - How to display amounts of a commodity in output: sym-
|
|
bol side and spacing, digit groups, decimal mark, and number of deci-
|
|
mal places.
|
|
|
|
Directives are not required when starting out with hledger, but you
|
|
will probably want to add some as your needs grow. Here some key
|
|
directives for particular needs:
|
|
|
|
|
|
purpose directives
|
|
--------------------------------------------------------------------------
|
|
READING DATA:
|
|
Declare file's decimal mark to help parse decimal-mark
|
|
amounts accurately
|
|
Rewrite account names alias
|
|
Comment out sections of the data comment
|
|
Include extra data files include
|
|
GENERATING DATA:
|
|
Generate recurring transactions or budget ~
|
|
goals
|
|
Generate extra postings on transactions =
|
|
CHECKING FOR ERRORS:
|
|
Define valid entities to provide more error account, commodity, payee
|
|
checking
|
|
REPORTING:
|
|
Declare accounts' type and display order account
|
|
Declare commodity display styles commodity
|
|
Declare market prices P
|
|
|
|
Directive effects
|
|
And here is what each directive does, and which files and journal
|
|
entries (transactions) it affects:
|
|
|
|
|
|
|
|
|
|
direc- what it does ends
|
|
tive at
|
|
file
|
|
end?
|
|
--------------------------------------------------------------------------------------
|
|
account Declares an account, for checking all entries in all files; and N
|
|
its display order and type. Subdirectives: any text, ignored.
|
|
alias Rewrites account names, in following entries until end of cur- Y
|
|
rent file or end aliases. Command line equivalent: --alias
|
|
comment Ignores part of the journal file, until end of current file or Y
|
|
end comment.
|
|
commod- Declares up to four things: 1. a commodity symbol, for checking N,Y,N,N
|
|
ity 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 decimal-mark 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 D. Subdirectives: format
|
|
(Ledger-compatible syntax). Command line equivalent: -c/--com-
|
|
modity-style
|
|
deci- Declares the decimal mark, for parsing amounts of all commodi- Y
|
|
mal- ties in following entries until next decimal-mark or end of cur-
|
|
mark rent file. Included files can override. Takes precedence over
|
|
commodity and D.
|
|
include Includes entries and directives from another file, as if they N
|
|
were written inline. Command line alternative: multiple
|
|
-f/--file
|
|
payee Declares a payee name, for checking all entries in all files. N
|
|
P Declares the market price of a commodity on some date, for value N
|
|
reports.
|
|
~ Declares a periodic transaction rule that generates future N
|
|
(tilde) transactions with --forecast and budget goals with balance
|
|
--budget.
|
|
Other
|
|
syntax:
|
|
apply Prepends a common parent account to all account names, in fol- Y
|
|
account lowing entries until end of current file or end apply account.
|
|
D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N
|
|
there is no commodity directive for this commodity: its decimal
|
|
mark, balancing precision, and display style, as above.
|
|
Y Sets a default year to use for any yearless dates, in following Y
|
|
entries until end of current file.
|
|
= Declares an auto posting rule that generates extra postings on partly
|
|
(equals) matched transactions with --auto, in current, parent, and child
|
|
files (but not sibling files, see #1212).
|
|
Other Other directives from Ledger's file format are accepted but
|
|
Ledger ignored.
|
|
direc-
|
|
tives
|
|
|
|
Directives and multiple files
|
|
If you use multiple -f/--file options, or the include directive,
|
|
hledger will process multiple input files. But directives which affect
|
|
input typically have effect only until the end of the file in which
|
|
they occur (and on any included files in that region).
|
|
|
|
This may seem inconvenient, but it's intentional; it makes reports sta-
|
|
ble and deterministic, independent of the order of input. Otherwise
|
|
you could see different numbers if you happened to write -f options in
|
|
a different order, or if you moved includes around while cleaning up
|
|
your files.
|
|
|
|
It can be surprising though; for example, it means that alias direc-
|
|
tives do not affect parent or sibling files (see below).
|
|
|
|
account directive
|
|
account directives can be used to declare accounts (ie, the places that
|
|
amounts are transferred from and to). Though not required, these dec-
|
|
larations can provide several benefits:
|
|
|
|
o They can document your intended chart of accounts, providing a refer-
|
|
ence.
|
|
|
|
o In strict mode, they restrict which accounts may be posted to by
|
|
transactions, which helps detect typos.
|
|
|
|
o They control account display order in reports, allowing non-alpha-
|
|
betic sorting (eg Revenues to appear above Expenses).
|
|
|
|
o They help with account name completion (in hledger add, hledger-web,
|
|
hledger-iadd, ledger-mode, etc.)
|
|
|
|
o They can store additional account information as comments, or as tags
|
|
which can be used to filter or pivot reports.
|
|
|
|
o They can help hledger know your accounts' types (asset, liability,
|
|
equity, revenue, expense), affecting reports like balancesheet and
|
|
incomestatement.
|
|
|
|
They are written as the word account followed by a hledger-style
|
|
account name, eg:
|
|
|
|
account assets:bank:checking
|
|
|
|
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:
|
|
|
|
account (assets:bank:checking)
|
|
|
|
Account comments
|
|
Text following two or more spaces and ; at the end of an account direc-
|
|
tive line, and/or following ; on indented lines immediately below it,
|
|
form comments for that account. They are ignored except they may con-
|
|
tain tags, which are not ignored.
|
|
|
|
The two-space requirement for same-line account comments is because ;
|
|
is allowed in account names.
|
|
|
|
account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon
|
|
; next-line comment
|
|
; some tags - type:A, acctnum:12345
|
|
|
|
Account subdirectives
|
|
Ledger-style indented subdirectives are also accepted, but currently
|
|
ignored:
|
|
|
|
account assets:bank:checking
|
|
format subdirective is ignored
|
|
|
|
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't warn you when you mis-spell an account name in the jour-
|
|
nal. Usually you'll find that error later, as an extra account in bal-
|
|
ance reports, or an incorrect balance when reconciling.
|
|
|
|
In strict mode, enabled with the -s/--strict flag, hledger will report
|
|
an error if any transaction uses an account name that has not been
|
|
declared by an account directive. Some notes:
|
|
|
|
o The declaration is case-sensitive; transactions must use the correct
|
|
account name capitalisation.
|
|
|
|
o The account directive's scope is "whole file and below" (see direc-
|
|
tives). 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's usual
|
|
to put them at the top.
|
|
|
|
o Accounts can only be declared in journal files, but will affect
|
|
included files of all types.
|
|
|
|
o It's currently not possible to declare "all possible subaccounts"
|
|
with a wildcard; every account posted to must be declared.
|
|
|
|
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:
|
|
|
|
account assets
|
|
account liabilities
|
|
account equity
|
|
account revenues
|
|
account expenses
|
|
|
|
those accounts will be displayed in declaration order:
|
|
|
|
$ hledger accounts -1
|
|
assets
|
|
liabilities
|
|
equity
|
|
revenues
|
|
expenses
|
|
|
|
Any undeclared accounts are displayed last, in alphabetical order.
|
|
|
|
Sorting is done at each level of the account tree, within each group of
|
|
sibling accounts under the same parent. And currently, this directive:
|
|
|
|
account other:zoo
|
|
|
|
would influence the position of zoo among other's subaccounts, but not
|
|
the position of other among the top-level accounts. This means:
|
|
|
|
o you will sometimes declare parent accounts (eg account other above)
|
|
that you don't intend to post to, just to customize their display
|
|
order
|
|
|
|
o sibling accounts stay together (you couldn't display x:y in between
|
|
a:b and a:c).
|
|
|
|
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 type: query.
|
|
|
|
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 type: tag to your top-level account directives.
|
|
Subaccounts will inherit the type of their parent. The tag's value
|
|
should be one of the five main account types:
|
|
|
|
o A or Asset (things you own)
|
|
|
|
o L or Liability (things you owe)
|
|
|
|
o E or Equity (investment/ownership; balanced counterpart of assets &
|
|
liabilities)
|
|
|
|
o R or Revenue (what you received money from, AKA income; technically
|
|
part of Equity)
|
|
|
|
o X or Expense (what you spend money on; technically part of Equity)
|
|
|
|
or, it can be (these are used less often):
|
|
|
|
o C or Cash (a subtype of Asset, indicating liquid assets for the cash-
|
|
flow report)
|
|
|
|
o V or Conversion (a subtype of Equity, for conversions (see COST
|
|
REPORTING).)
|
|
|
|
Here is a typical set of account type declarations:
|
|
|
|
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
|
|
|
|
Here are some tips for working with account types.
|
|
|
|
o 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't work for you, just ignore them and declare your account
|
|
types. See also Regular expressions.
|
|
|
|
If account's name contains this (CI) regular expression: | its type is:
|
|
--------------------------------------------------------------------|-------------
|
|
^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash
|
|
^assets?(:|$) | Asset
|
|
^(debts?|liabilit(y|ies))(:|$) | Liability
|
|
^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion
|
|
^equity(:|$) | Equity
|
|
^(income|revenue)s?(:|$) | Revenue
|
|
^expenses?(:|$) | Expense
|
|
|
|
o If you declare any account types, it'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.
|
|
|
|
o Certain uses of account aliases can disrupt account types. See
|
|
Rewriting accounts > Aliases and account types.
|
|
|
|
o As mentioned above, subaccounts will inherit a type from their parent
|
|
account. More precisely, an account's type is decided by the first
|
|
of these that exists:
|
|
|
|
1. A type: declaration for this account.
|
|
|
|
2. A type: declaration in the parent accounts above it, preferring
|
|
the nearest.
|
|
|
|
3. An account type inferred from this account's name.
|
|
|
|
4. An account type inferred from a parent account's name, preferring
|
|
the nearest parent.
|
|
|
|
5. Otherwise, it will have no type.
|
|
|
|
o For troubleshooting, you can list accounts and their types with:
|
|
|
|
$ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]
|
|
|
|
alias directive
|
|
You can define account alias rules which rewrite your account names, or
|
|
parts of them, before generating reports. This can be useful for:
|
|
|
|
o expanding shorthand account names to their full form, allowing easier
|
|
data entry and a less verbose journal
|
|
|
|
o adapting old journals to your current chart of accounts
|
|
|
|
o experimenting with new account organisations, like a new hierarchy
|
|
|
|
o combining two accounts into one, eg to see their sum or difference on
|
|
one line
|
|
|
|
o customising reports
|
|
|
|
Account aliases also rewrite account names in account directives. They
|
|
do not affect account names being entered via hledger add or hledger-
|
|
web.
|
|
|
|
Account aliases are very powerful. They are generally easy to use cor-
|
|
rectly, but you can also generate invalid account names with them; more
|
|
on this below.
|
|
|
|
See also Rewrite account names.
|
|
|
|
Basic aliases
|
|
To set an account alias, use the alias 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:
|
|
|
|
alias OLD = NEW
|
|
|
|
Or, you can use the --alias 'OLD=NEW' option on the command line. This
|
|
affects all entries. It's useful for trying out aliases interactively.
|
|
|
|
OLD and NEW are case sensitive full account names. hledger will
|
|
replace any occurrence of the old account name with the new one. Sub-
|
|
accounts are also affected. Eg:
|
|
|
|
alias checking = assets:bank:wells fargo:checking
|
|
; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
|
|
|
|
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.)
|
|
|
|
Eg:
|
|
|
|
alias /REGEX/ = REPLACEMENT
|
|
|
|
or:
|
|
|
|
$ hledger --alias '/REGEX/=REPLACEMENT' ...
|
|
|
|
Any part of an account name matched by REGEX will be replaced by
|
|
REPLACEMENT. REGEX is case-insensitive as usual.
|
|
|
|
If you need to match a forward slash, escape it with a backslash, eg
|
|
/\/=:.
|
|
|
|
If REGEX contains parenthesised match groups, these can be referenced
|
|
by the usual backslash and number in REPLACEMENT:
|
|
|
|
alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
|
|
; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
|
|
|
|
REPLACEMENT continues to the end of line (or on command line, to end of
|
|
option argument), so it can contain trailing whitespace.
|
|
|
|
Combining aliases
|
|
You can define as many aliases as you like, using journal directives
|
|
and/or command line options.
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
1. alias directives preceding the journal entry, most recently parsed
|
|
first (ie, reading upward from the journal entry, bottom to top)
|
|
|
|
2. --alias options, in the order they appeared on the command line
|
|
(left to right).
|
|
|
|
In other words, for (an account name in) a given journal entry:
|
|
|
|
o the nearest alias declaration before/above the entry is applied first
|
|
|
|
o the next alias before/above that will be be applied next, and so on
|
|
|
|
o aliases defined after/below the entry do not affect it.
|
|
|
|
This gives nearby aliases precedence over distant ones, and helps pro-
|
|
vide semantic stability - aliases will keep working the same way inde-
|
|
pendent of which files are being read and in which order.
|
|
|
|
In case of trouble, adding --debug=6 to the command line will show
|
|
which aliases are being applied when.
|
|
|
|
Aliases and multiple files
|
|
As explained at Directives and multiple files, alias directives do not
|
|
affect parent or sibling files. Eg in this command,
|
|
|
|
hledger -f a.aliases -f b.journal
|
|
|
|
account aliases defined in a.aliases will not affect b.journal.
|
|
Including the aliases doesn't work either:
|
|
|
|
include a.aliases
|
|
|
|
2020-01-01 ; not affected by a.aliases
|
|
foo 1
|
|
bar
|
|
|
|
This means that account aliases should usually be declared at the start
|
|
of your top-most file, like this:
|
|
|
|
alias foo=Foo
|
|
alias bar=Bar
|
|
|
|
2020-01-01 ; affected by aliases above
|
|
foo 1
|
|
bar
|
|
|
|
include c.journal ; also affected
|
|
|
|
end aliases directive
|
|
You can clear (forget) all currently defined aliases (seen in the jour-
|
|
nal so far, or defined on the command line) with this directive:
|
|
|
|
end aliases
|
|
|
|
Aliases can generate bad account names
|
|
Be aware that account aliases can produce malformed account names,
|
|
which could cause confusing reports or invalid print output. For exam-
|
|
ple, you could erase all account names:
|
|
|
|
2021-01-01
|
|
a:aa 1
|
|
b
|
|
|
|
$ hledger print --alias '/.*/='
|
|
2021-01-01
|
|
1
|
|
|
|
The above print output is not a valid journal. Or you could insert an
|
|
illegal double space, causing print output that would give a different
|
|
journal when reparsed:
|
|
|
|
2021-01-01
|
|
old 1
|
|
other
|
|
|
|
$ hledger print --alias old="new USD" | hledger -f- print
|
|
2021-01-01
|
|
new USD 1
|
|
other
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Secondly, if an account's type is being inferred from its name, renam-
|
|
ing it by an alias could prevent or alter that.
|
|
|
|
If you are using account aliases and the type: query is not matching
|
|
accounts as you expect, try troubleshooting with the accounts command,
|
|
eg something like:
|
|
|
|
$ hledger accounts --alias assets=bassetts type:a
|
|
|
|
commodity directive
|
|
You can use commodity directives to declare your commodities. In fact
|
|
the commodity directive performs several functions at once:
|
|
|
|
1. It declares commodities which may be used in the journal. This can
|
|
optionally be enforced, providing useful error checking. (Cf Com-
|
|
modity error checking)
|
|
|
|
2. It declares which decimal mark character (period or comma), to
|
|
expect when parsing input - useful to disambiguate international
|
|
number formats in your data. Without this, hledger will parse both
|
|
1,000 and 1.000 as 1. (Cf Amounts)
|
|
|
|
3. It declares how to render the commodity's amounts when displaying
|
|
output - the decimal mark, any digit group marks, the number of dec-
|
|
imal places, symbol placement and so on. (Cf Commodity display
|
|
style)
|
|
|
|
You will run into one of the problems solved by commodity directives
|
|
sooner or later, so we recommend using them, for robust and predictable
|
|
parsing and display.
|
|
|
|
Generally you should put them at the top of your journal file (since
|
|
for function 2, they affect only following amounts, cf #793).
|
|
|
|
A commodity directive is just the word commodity followed by a sample
|
|
amount, like this:
|
|
|
|
;commodity SAMPLEAMOUNT
|
|
|
|
commodity $1000.00
|
|
commodity 1,000.0000 AAAA ; optional same-line comment
|
|
|
|
It may also be written on multiple lines, and use the format subdirec-
|
|
tive, as in Ledger. Note in this case the commodity symbol appears
|
|
twice; it must be the same in both places:
|
|
|
|
;commodity SYMBOL
|
|
; format SAMPLEAMOUNT
|
|
|
|
; 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
|
|
|
|
Other indented subdirectives are currently ignored.
|
|
|
|
Remember that if the commodity symbol contains spaces, numbers, or
|
|
punctuation, it must be enclosed in double quotes (cf Commodity).
|
|
|
|
The amount's quantity does not matter; only the format is significant.
|
|
It must include a decimal mark - either a period or a comma - followed
|
|
by 0 or more decimal digits.
|
|
|
|
A few more examples:
|
|
|
|
# number formats for $, EUR, INR and the no-symbol commodity:
|
|
commodity $1,000.00
|
|
commodity EUR 1.000,00
|
|
commodity INR 9,99,99,999.0
|
|
commodity 1 000 000.
|
|
|
|
Note hledger normally uses banker's rounding, so 0.5 displayed with
|
|
zero decimal digits is "0". (More at Commodity display style.)
|
|
|
|
Even in the presence of commodity directives, the commodity display
|
|
style can still be overridden by supplying a command line option.
|
|
|
|
Commodity error checking
|
|
In strict mode, enabled with the -s/--strict flag, hledger will report
|
|
an error if a commodity symbol is used that has not been declared by a
|
|
commodity directive. This works similarly to account error checking,
|
|
see the notes there for more details.
|
|
|
|
Note, this disallows amounts without a commodity symbol, because cur-
|
|
rently it's not possible (?) to declare the "no-symbol" commodity with
|
|
a directive. This is one exception for convenience: zero amounts are
|
|
always allowed to have no commodity symbol.
|
|
|
|
decimal-mark directive
|
|
You can use a decimal-mark 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
|
|
|
|
decimal-mark .
|
|
|
|
or
|
|
|
|
decimal-mark ,
|
|
|
|
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).
|
|
|
|
include directive
|
|
You can pull in the content of additional files by writing an include
|
|
directive, like this:
|
|
|
|
include FILEPATH
|
|
|
|
Only journal files can include, and only journal, timeclock or timedot
|
|
files can be included (not CSV files, currently).
|
|
|
|
If the file path does not begin with a slash, it is relative to the
|
|
current file's folder.
|
|
|
|
A tilde means home directory, eg: include ~/main.journal.
|
|
|
|
The path may contain glob patterns to match multiple files, eg: include
|
|
*.journal.
|
|
|
|
There is limited support for recursive wildcards: **/ (the slash is
|
|
required) matches 0 or more subdirectories. It's not super convenient
|
|
since you have to avoid include cycles and including directories, but
|
|
this can be done, eg: include */**/*.journal.
|
|
|
|
The path may also be prefixed to force a specific file format, overrid-
|
|
ing the file extension (as described in hledger.1 -> Input files):
|
|
include timedot:~/notes/2020*.md.
|
|
|
|
P directive
|
|
The P 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.
|
|
|
|
The format is:
|
|
|
|
P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT
|
|
|
|
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:
|
|
|
|
# one euro was worth $1.35 from 2009-01-01 onward:
|
|
P 2009-01-01 EUR $1.35
|
|
|
|
# and $1.40 from 2010-01-01 onward:
|
|
P 2010-01-01 EUR $1.40
|
|
|
|
The -V, -X and --value flags use these market prices to show amount
|
|
values in another commodity. See Valuation.
|
|
|
|
|
|
payee directive
|
|
payee PAYEE NAME
|
|
|
|
This directive can be used to declare a limited set of payees which may
|
|
appear in transaction descriptions. The "payees" check will report an
|
|
error if any transaction refers to a payee that has not been declared.
|
|
Eg:
|
|
|
|
payee Whole Foods
|
|
|
|
Any indented subdirectives are currently ignored.
|
|
|
|
tag directive
|
|
tag TAGNAME
|
|
|
|
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:
|
|
|
|
tag item-id
|
|
|
|
Any indented subdirectives are currently ignored.
|
|
|
|
The "tags" 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 .
|
|
|
|
Periodic transactions
|
|
The ~ directive declares recurring transactions. Such directives allow
|
|
hledger to generate temporary future transactions (visible in reports,
|
|
not in the journal file) to help with forecasting or budgeting.
|
|
|
|
Periodic transactions can be a little tricky, so before you use them,
|
|
read this whole section, or at least these tips:
|
|
|
|
1. Two spaces accidentally added or omitted will cause you trouble -
|
|
read about this below.
|
|
|
|
2. For troubleshooting, show the generated transactions with hledger
|
|
print --forecast tag:generated or hledger register --forecast
|
|
tag:generated.
|
|
|
|
3. Forecasted transactions will begin only after the last non-fore-
|
|
casted transaction's date.
|
|
|
|
4. Forecasted transactions will end 6 months from today, by default.
|
|
See below for the exact start/end rules.
|
|
|
|
5. period expressions can be tricky. Their documentation needs
|
|
improvement, but is worth studying.
|
|
|
|
6. Some period expressions with a repeating interval must begin on a
|
|
natural boundary of that interval. Eg in weekly from DATE, DATE
|
|
must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
|
|
error.
|
|
|
|
7. 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's a bit
|
|
inconsistent with the above.) Eg: ~ every 10th day of month from
|
|
2020/01, which is equivalent to ~ every 10th day of month from
|
|
2020/01/01, will be adjusted to start on 2019/12/10.
|
|
|
|
Periodic rule syntax
|
|
A periodic transaction rule looks like a normal journal entry, with the
|
|
date replaced by a tilde (~) followed by a period expression (mnemonic:
|
|
~ looks like a recurring sine wave.):
|
|
|
|
# every first of month
|
|
~ monthly
|
|
expenses:rent $2000
|
|
assets:bank:checking
|
|
|
|
# every 15th of month in 2023's first quarter:
|
|
~ monthly from 2023-04-15 to 2023-06-16
|
|
expenses:utilities $400
|
|
assets:bank:checking
|
|
|
|
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' start
|
|
dates).
|
|
|
|
Periodic rules and relative dates
|
|
Partial or relative dates (like 12/31, 25, tomorrow, last week, next
|
|
quarter) 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:
|
|
|
|
1. the first day of the default year specified by a recent Y directive
|
|
|
|
2. or the date specified with --today
|
|
|
|
3. or the date on which you are running the report.
|
|
|
|
They will not be affected at all by report period or forecast period
|
|
dates.
|
|
|
|
Two spaces between period expression and description!
|
|
If the period expression is followed by a transaction description,
|
|
these must be separated by two or more spaces. This helps hledger know
|
|
where the period expression ends, so that descriptions can not acciden-
|
|
tally alter their meaning, as in this example:
|
|
|
|
; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"
|
|
; ||
|
|
; vv
|
|
~ every 2 months in 2020, we will review
|
|
assets:bank:checking $1500
|
|
income:acme inc
|
|
|
|
So,
|
|
|
|
o Do write two spaces between your period expression and your transac-
|
|
tion description, if any.
|
|
|
|
o Don't accidentally write two spaces in the middle of your period
|
|
expression.
|
|
|
|
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.
|
|
|
|
Auto postings
|
|
The = directive declares a rule for automatically adding temporary
|
|
extra postings (visible in reports, not in the journal file) to all
|
|
transactions matched by a certain query, when you use the --auto flag.
|
|
|
|
Downsides: depending on generated data for your reports makes your
|
|
financial data less portable, less future-proof, and less trustworthy
|
|
in an audit. Also, because the feature is optional, other features
|
|
like balance assertions can break depending on whether it is on or off.
|
|
|
|
An auto posting rule looks a bit like a transaction:
|
|
|
|
= QUERY
|
|
ACCOUNT AMOUNT
|
|
...
|
|
ACCOUNT [AMOUNT]
|
|
|
|
except the first line is an equals sign (mnemonic: = suggests match-
|
|
ing), followed by a query (which matches existing postings), and each
|
|
"posting" line describes a posting to be generated, and the posting
|
|
amounts can be:
|
|
|
|
o a normal amount with a commodity symbol, eg $2. This will be used
|
|
as-is.
|
|
|
|
o a number, eg 2. The commodity symbol (if any) from the matched post-
|
|
ing will be added to this.
|
|
|
|
o a numeric multiplier, eg *2 (a star followed by a number N). The
|
|
matched posting's amount (and total price, if any) will be multiplied
|
|
by N.
|
|
|
|
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
|
|
symbol S). The matched posting's amount will be multiplied by N, and
|
|
its commodity symbol will be replaced with S.
|
|
|
|
Any query term containing spaces must be enclosed in single or double
|
|
quotes, as on the command line. Eg, note the quotes around the second
|
|
query term below:
|
|
|
|
= expenses:groceries 'expenses:dining out'
|
|
(budget:funds:dining out) *-1
|
|
|
|
Some examples:
|
|
|
|
; 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
|
|
|
|
$ 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
|
|
|
|
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/--file are used - see #1212).
|
|
|
|
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.
|
|
|
|
Auto postings and transaction balancing / inferred amounts / balance asser-
|
|
tions
|
|
Currently, auto postings are added:
|
|
|
|
o after missing amounts are inferred, and transactions are checked for
|
|
balancedness,
|
|
|
|
o but before balance assertions are checked.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Auto posting tags
|
|
Automated postings will have some extra tags:
|
|
|
|
o generated-posting:= QUERY - shows this was generated by an auto post-
|
|
ing rule, and the query
|
|
|
|
o _generated-posting:= QUERY - a hidden tag, which does not appear in
|
|
hledger's output. This can be used to match postings generated "just
|
|
now", rather than generated in the past and saved to the journal.
|
|
|
|
Also, any transaction that has been changed by auto posting rules will
|
|
have these tags added:
|
|
|
|
o modified: - this transaction was modified
|
|
|
|
o _modified: - a hidden tag not appearing in the comment; this transac-
|
|
tion was modified "just now".
|
|
|
|
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:
|
|
|
|
; 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
|
|
|
|
or when adjusting a balance to reality:
|
|
|
|
; no cash left; update balance, record any untracked spending as a generic expense
|
|
2016/1/15
|
|
assets:cash = $0
|
|
expenses:misc
|
|
|
|
The calculated amount depends on the account'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 assign-
|
|
ment).
|
|
|
|
Downsides: using balance assignments makes your journal less explicit;
|
|
to know the exact amount posted, you have to run hledger or do the cal-
|
|
culations yourself, instead of just reading it. Also balance assign-
|
|
ments' forcing of balances can hide errors. These things make your
|
|
financial data less portable, less future-proof, and less trustworthy
|
|
in an audit.
|
|
|
|
Balance assignments and prices
|
|
A cost in a balance assignment will cause the calculated amount to have
|
|
that price attached:
|
|
|
|
2019/1/1
|
|
(a) = $1 @ EUR2
|
|
|
|
$ hledger print --explicit
|
|
2019-01-01
|
|
(a) $1 @ EUR2 = $1 @ EUR2
|
|
|
|
Bracketed posting dates
|
|
For setting posting dates and secondary posting dates, Ledger's brack-
|
|
eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in
|
|
posting comments. hledger will attempt to parse any square-bracketed
|
|
sequence of the 0123456789/-.= characters in this way. With this syn-
|
|
tax, DATE infers its year from the transaction and DATE2 infers its
|
|
year from DATE.
|
|
|
|
Downsides: another syntax to learn, redundant with hledger's
|
|
date:/date2: tags, and confusingly similar to Ledger's lot date syntax.
|
|
|
|
D directive
|
|
D AMOUNT
|
|
|
|
This directive sets a default commodity, to be used for any subsequent
|
|
commodityless amounts (ie, plain numbers) seen while parsing the jour-
|
|
nal. This effect lasts until the next D directive, or the end of the
|
|
journal.
|
|
|
|
For compatibility/historical reasons, D also acts like a commodity
|
|
directive (setting the commodity'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 deci-
|
|
mal mark (either period or comma). Eg:
|
|
|
|
; 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
|
|
|
|
Interactions with other directives:
|
|
|
|
For setting a commodity's display style, a commodity directive has
|
|
highest priority, then a D directive.
|
|
|
|
For detecting a commodity's decimal mark during parsing, decimal-mark
|
|
has highest priority, then commodity, then D.
|
|
|
|
For checking commodity symbols with the check command, a commodity
|
|
directive is required (hledger check commodities ignores D directives).
|
|
|
|
Downsides: omitting commodity symbols makes your financial data less
|
|
explicit, less portable, and less trustworthy in an audit. It is usu-
|
|
ally an unsustainable shortcut; sooner or later you will want to track
|
|
multiple commodities. D is overloaded with functions redundant with
|
|
commodity and decimal-mark. And it works differently from Ledger's D.
|
|
|
|
apply account directive
|
|
This directive sets a default parent account, which will be prepended
|
|
to all accounts in following entries, until an end apply account direc-
|
|
tive or end of current file. Eg:
|
|
|
|
apply account home
|
|
|
|
2010/1/1
|
|
food $10
|
|
cash
|
|
|
|
end apply account
|
|
|
|
is equivalent to:
|
|
|
|
2010/01/01
|
|
home:food $10
|
|
home:cash $-10
|
|
|
|
account directives are also affected, and so is any included content.
|
|
|
|
Account names entered via hledger add or hledger-web are not affected.
|
|
|
|
Account aliases, if any, are applied after the parent account is
|
|
prepended.
|
|
|
|
Downsides: this can make your financial data less explicit, less porta-
|
|
ble, and less trustworthy in an audit.
|
|
|
|
Y directive
|
|
Y YEAR
|
|
|
|
or (deprecated backward-compatible forms):
|
|
|
|
year YEAR apply year YEAR
|
|
|
|
The space is optional. This sets a default year to be used for subse-
|
|
quent dates which don't specify a year. Eg:
|
|
|
|
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
|
|
|
|
Downsides: omitting the year (from primary transaction dates, at least)
|
|
makes your financial data less explicit, less portable, and less trust-
|
|
worthy in an audit. Such dates can get separated from their corre-
|
|
sponding Y directive, eg when evaluating a region of the journal in
|
|
your editor. A missing Y directive makes reports dependent on today's
|
|
date.
|
|
|
|
Secondary dates
|
|
A secondary date is written after the primary date, following an equals
|
|
sign. If the year is omitted, the primary date's year is assumed.
|
|
When running reports, the primary (left) date is used by default, but
|
|
with the --date2 flag (or --aux-date or --effective), the secondary
|
|
(right) date will be used instead.
|
|
|
|
The meaning of secondary dates is up to you, but it's best to follow a
|
|
consistent rule. Eg "primary = the bank's clearing date, secondary =
|
|
date the transaction was initiated, if different".
|
|
|
|
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 report-
|
|
ing mode is appropriate for a given report. Posting dates are simpler
|
|
and better.
|
|
|
|
Star comments
|
|
Lines beginning with * (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.
|
|
|
|
Downsides: another, unconventional comment syntax to learn. Decreases
|
|
your journal'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's features.
|
|
|
|
Valuation expressions
|
|
Ledger allows a valuation function or value to be written in double
|
|
parentheses after an amount. hledger ignores these.
|
|
|
|
Virtual postings
|
|
A posting with parentheses around the account name is called a virtual
|
|
posting or unbalanced posting, which means it is exempt from the usual
|
|
rule that a transaction's postings must balance add up to zero.
|
|
|
|
This is not part of double entry bookkeeping, so you might choose to
|
|
avoid this feature. Or you can use it sparingly for certain special
|
|
cases where it can be convenient. Eg, you could set opening balances
|
|
without using a balancing equity account:
|
|
|
|
2022-01-01 opening balances
|
|
(assets:checking) $1000
|
|
(assets:savings) $2000
|
|
|
|
A posting with brackets around the account name is called a balanced
|
|
virtual posting. The balanced virtual postings in a transaction must
|
|
add up to zero (separately from other postings). Eg:
|
|
|
|
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
|
|
|
|
Postings whose account names are neither parenthesised nor bracketed
|
|
are called real postings. You can exclude virtual postings from
|
|
reports with the -R/--real flag or a real:1 query.
|
|
|
|
Downsides: violates double entry bookkeeping, can be used to avoid fig-
|
|
uring out correct entries, makes your financial data less portable and
|
|
less trustworthy in an audit.
|
|
|
|
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's
|
|
reports may differ from Ledger's if you use these.
|
|
|
|
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
|
|
|
|
See also https://hledger.org/ledger.html for a detailed hledger/Ledger
|
|
syntax comparison.
|
|
|
|
|
|
CSV
|
|
hledger can read CSV files (Character Separated Value - usually comma,
|
|
semicolon, or tab) containing dated records, automatically converting
|
|
each record into a transaction.
|
|
|
|
(To learn about writing CSV, see CSV output.)
|
|
|
|
For best error messages when reading CSV/TSV/SSV files, make sure they
|
|
have a corresponding .csv, .tsv or .ssv file extension or use a hledger
|
|
file prefix (see File Extension below).
|
|
|
|
Each CSV file must be described by a corresponding rules file.
|
|
This contains rules describing the CSV data (header line, fields lay-
|
|
out, date format etc.), how to construct hledger transactions from it,
|
|
and how to categorise transactions based on description or other
|
|
attributes.
|
|
|
|
By default hledger looks for a rules file named like the CSV file with
|
|
an extra .rules extension, in the same directory. Eg when asked to
|
|
read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. You can spec-
|
|
ify a different rules file with the --rules-file option. If no rules
|
|
file is found, hledger will create a sample rules file, which you'll
|
|
need to adjust.
|
|
|
|
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's a simple CSV file and a rules file for it:
|
|
|
|
Date, Description, Id, Amount
|
|
12/11/2019, Foo, 123, 10.23
|
|
|
|
# basic.csv.rules
|
|
skip 1
|
|
fields date, description, , amount
|
|
date-format %d/%m/%Y
|
|
|
|
$ hledger print -f basic.csv
|
|
2019-11-12 Foo
|
|
expenses:unknown 10.23
|
|
income:unknown -10.23
|
|
|
|
There'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.
|
|
|
|
CSV rules cheatsheet
|
|
The following kinds of rule can appear in the rules file, in any order.
|
|
(Blank lines and lines beginning with # or ; or * are ignored.)
|
|
|
|
|
|
separator declare the field separator, instead of rely-
|
|
ing on file extension
|
|
skip skip one or more header lines at start of file
|
|
date-format declare how to parse CSV dates/date-times
|
|
timezone declare the time zone of ambiguous CSV date-
|
|
times
|
|
newest-first improve txn order when: there are multiple
|
|
records, newest first, all with the same date
|
|
intra-day-reversed improve txn order when: same-day txns are in
|
|
opposite order to the overall file
|
|
decimal-mark declare the decimal mark used in CSV amounts,
|
|
when ambiguous
|
|
fields list name CSV fields for easy reference, and
|
|
optionally assign their values to hledger
|
|
fields
|
|
Field assignment assign a CSV value or interpolated text value
|
|
to a hledger field
|
|
|
|
if block conditionally assign values to hledger fields,
|
|
or skip a record or end (skip rest of file)
|
|
if table conditionally assign values to hledger fields,
|
|
using compact syntax
|
|
balance-type select which type of balance asser-
|
|
tions/assignments to generate
|
|
include inline another CSV rules file
|
|
|
|
Working with CSV tips can be found below, including How CSV rules are
|
|
evaluated.
|
|
|
|
separator
|
|
You can use the separator rule to read other kinds of character-sepa-
|
|
rated data. The argument is any single separator character, or the
|
|
words tab or space (case insensitive). Eg, for comma-separated values
|
|
(CSV):
|
|
|
|
separator ,
|
|
|
|
or for semicolon-separated values (SSV):
|
|
|
|
separator ;
|
|
|
|
or for tab-separated values (TSV):
|
|
|
|
separator TAB
|
|
|
|
If the input file has a .csv, .ssv or .tsv file extension (or a csv:,
|
|
ssv:, tsv: prefix), the appropriate separator will be inferred automat-
|
|
ically, and you won't need this rule.
|
|
|
|
skip
|
|
skip N
|
|
|
|
The word skip 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. (Empty/blank lines are skipped automatically, so you don't need
|
|
to count those.) You'll need this whenever your CSV data contains
|
|
header lines. Header lines skipped in this way are ignored, and not
|
|
parsed as CSV.
|
|
|
|
skip can also be used inside if blocks (described below), to skip indi-
|
|
vidual data records. Note records skipped in this way are still
|
|
required to be valid CSV, even though otherwise ignored.
|
|
|
|
date-format
|
|
date-format DATEFMT
|
|
|
|
This is a helper for the date (and date2) fields. If your CSV dates
|
|
are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll
|
|
need to add a date-format rule describing them with a strptime-style
|
|
date parsing pattern - see https://hackage.haskell.org/pack-
|
|
age/time/docs/Data-Time-Format.html#v:formatTime. The pattern must
|
|
parse the CSV date value completely. Some examples:
|
|
|
|
# MM/DD/YY
|
|
date-format %m/%d/%y
|
|
|
|
# D/M/YYYY
|
|
# The - makes leading zeros optional.
|
|
date-format %-d/%-m/%Y
|
|
|
|
# YYYY-Mmm-DD
|
|
date-format %Y-%h-%d
|
|
|
|
# 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
|
|
|
|
timezone
|
|
timezone TIMEZONE
|
|
|
|
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's native time zone, which helps
|
|
prevent off-by-one dates.
|
|
|
|
When the CSV date-times do contain time zone information, you don't
|
|
need this rule; instead, use %Z in date-format (or %z, %EZ, %Ez; see
|
|
the formatTime link above).
|
|
|
|
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:
|
|
|
|
$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv
|
|
|
|
timezone currently does not understand timezone names, except "UTC",
|
|
"GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". For
|
|
others, use numeric format: +HHMM or -HHMM.
|
|
|
|
newest-first
|
|
hledger tries to ensure that the generated transactions will be ordered
|
|
chronologically, including intra-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's records are normally newest first,
|
|
like:
|
|
|
|
2022-10-01, txn 3...
|
|
2022-10-01, txn 2...
|
|
2022-10-01, txn 1...
|
|
|
|
you can add the newest-first rule to help hledger generate the transac-
|
|
tions in correct order.
|
|
|
|
# same-day CSV records are newest first
|
|
newest-first
|
|
|
|
intra-day-reversed
|
|
CSV records for each day are sometimes ordered in reverse compared to
|
|
the overall date order. Eg, here dates are newest first, but the
|
|
transactions on each date are oldest first:
|
|
|
|
2022-10-02, txn 3...
|
|
2022-10-02, txn 4...
|
|
2022-10-01, txn 1...
|
|
2022-10-01, txn 2...
|
|
|
|
In this situation, add the intra-day-reversed rule, and hledger will
|
|
compensate, improving the order of transactions.
|
|
|
|
# transactions within each day are reversed with respect to the overall date order
|
|
intra-day-reversed
|
|
|
|
decimal-mark
|
|
decimal-mark .
|
|
|
|
or:
|
|
|
|
decimal-mark ,
|
|
|
|
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.
|
|
|
|
fields list
|
|
fields FIELDNAME1, FIELDNAME2, ...
|
|
|
|
A fields list (the word fields followed by comma-separated field names)
|
|
is optional, but convenient. It does two things:
|
|
|
|
1. It names the CSV field in each column. This can be convenient if
|
|
you are referencing them in other rules, so you can say %SomeField
|
|
instead of remembering %13.
|
|
|
|
2. 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's fields and
|
|
build a transaction.
|
|
|
|
Here's an example that says "use the 1st, 2nd and 4th fields as the
|
|
transaction's date, description and amount; name the last two fields
|
|
for later reference; and ignore the others":
|
|
|
|
fields date, description, , amount, , , somefield, anotherfield
|
|
|
|
In a fields list, the separator is always comma; it is unrelated to the
|
|
CSV file's separator. Also:
|
|
|
|
o There must be least two items in the list (at least one comma).
|
|
|
|
o Field names may not contain spaces. Spaces before/after field names
|
|
are optional.
|
|
|
|
o Field names may contain _ (underscore) or - (hyphen).
|
|
|
|
o Fields you don't care about can be given a dummy name or an empty
|
|
name.
|
|
|
|
If the CSV contains column headings, it's convenient to use these for
|
|
your field names, suitably modified (eg lower-cased with spaces
|
|
replaced by underscores).
|
|
|
|
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's "bal-
|
|
ance" field balance_ to avoid directly setting hledger's balance field
|
|
(and generating a balance assertion).
|
|
|
|
Field assignment
|
|
HLEDGERFIELD FIELDVALUE
|
|
|
|
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).
|
|
|
|
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 inter-
|
|
polate CSV fields, referenced by their 1-based position in the CSV
|
|
record (%N), or by the name they were given in the fields list (%CSV-
|
|
FIELD).
|
|
|
|
Some examples:
|
|
|
|
# set the amount to the 4th CSV field, with " USD" appended
|
|
amount %4 USD
|
|
|
|
# combine three fields to make a comment, containing note: and date: tags
|
|
comment note: %somefield - %anotherfield, date: %1
|
|
|
|
Tips:
|
|
|
|
o Interpolation strips outer whitespace (so a CSV value like " 1 "
|
|
becomes 1 when interpolated) (#1051).
|
|
|
|
o Interpolations always refer to a CSV field - you can't interpolate a
|
|
hledger field. (See Referencing other fields below).
|
|
|
|
Field names
|
|
Note the two kinds of field names mentioned here, and used only in
|
|
hledger CSV rules files:
|
|
|
|
1. CSV field names (CSVFIELD in these docs): you can optionally name
|
|
the CSV columns for easy reference (since hledger doesn't yet auto-
|
|
matically recognise column headings in a CSV file), by writing arbi-
|
|
trary names in a fields list, eg:
|
|
|
|
fields When, What, Some_Id, Net, Total, Foo, Bar
|
|
|
|
2. Special hledger field names (HLEDGERFIELD 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:
|
|
|
|
date %When
|
|
code %Some_Id
|
|
description %What
|
|
comment %Foo %Bar
|
|
amount1 $ %Total
|
|
|
|
or directly in a fields list:
|
|
|
|
fields date, description, code, , amount1, Foo, Bar
|
|
currency $
|
|
comment %Foo %Bar
|
|
|
|
Here are all the special hledger field names available, and what hap-
|
|
pens when you assign values to them:
|
|
|
|
date field
|
|
Assigning to date sets the transaction date.
|
|
|
|
date2 field
|
|
date2 sets the transaction's secondary date, if any.
|
|
|
|
status field
|
|
status sets the transaction's status, if any.
|
|
|
|
code field
|
|
code sets the transaction's code, if any.
|
|
|
|
description field
|
|
description sets the transaction's description, if any.
|
|
|
|
comment field
|
|
comment sets the transaction's comment, if any.
|
|
|
|
commentN, where N is a number, sets the Nth posting's comment.
|
|
|
|
You can assign multi-line comments by writing literal \n in the code.
|
|
A comment starting with \n will begin on a new line.
|
|
|
|
Comments can contain tags, as usual.
|
|
|
|
account field
|
|
Assigning to accountN, where N is 1 to 99, sets the account name of the
|
|
Nth posting, and causes that posting to be generated.
|
|
|
|
Most often there are two postings, so you'll want to set account1 and
|
|
account2. Typically account1 is associated with the CSV file, and is
|
|
set once with a top-level assignment, while account2 is set based on
|
|
each transaction's description, in conditional rules.
|
|
|
|
If a posting's account name is left unset but its amount is set (see
|
|
below), a default account name will be chosen (like "expenses:unknown"
|
|
or "income:unknown").
|
|
|
|
amount field
|
|
There are several "amount" field name variants, useful for different
|
|
situations:
|
|
|
|
o amountN sets the amount of the Nth posting, and causes that posting
|
|
to be generated. By assigning to amount1, amount2, ... etc. you
|
|
can generate up to 99 postings. Posting numbers don't have to be
|
|
consecutive; in certain situations using a high number might be help-
|
|
ful to influence the layout of postings.
|
|
|
|
o amountN-in and amountN-out should be used instead, as a pair, when
|
|
and only when the amount must be obtained from two CSV fields. Eg
|
|
when the CSV has separate Debit and Credit fields instead of a single
|
|
Amount field. Note:
|
|
|
|
o Don't think "-in is for the first posting and -out is for the sec-
|
|
ond posting" - that's not correct. Think: "amountN-in and amountN-
|
|
out together detect the amount for posting N, by inspecting two CSV
|
|
fields at once."
|
|
|
|
o hledger assumes both CSV fields are unsigned, and will automati-
|
|
cally negate the -out value.
|
|
|
|
o It also expects that at least one of the values is empty or zero,
|
|
so it knows which one to ignore. If that's not the case you'll
|
|
need an if rule (see Setting amounts below).
|
|
|
|
o amount, with no posting number (and similarly, amount-in and amount-
|
|
out with no number) are an older syntax. We keep them for backwards
|
|
compatibility, and because they have special behaviour that is some-
|
|
times convenient:
|
|
|
|
o They set the amount of posting 1 and (negated) the amount of post-
|
|
ing 2.
|
|
|
|
o Posting 2's amount will be converted to cost if it has a cost
|
|
price.
|
|
|
|
o Any of the newer rules for posting 1 or 2 (like amount1, or
|
|
amount2-in and amount2-out) will take precedence. This allows
|
|
incrementally migrating old rules files to the new syntax.
|
|
|
|
There's more to say about amount-setting that doesn't fit here; please
|
|
see also "Setting amounts" below.
|
|
|
|
currency field
|
|
currency sets a currency symbol, to be prepended to all postings'
|
|
amounts. You can use this if the CSV amounts do not have a currency
|
|
symbol, eg if it is in a separate column.
|
|
|
|
currencyN prepends a currency symbol to just the Nth posting's amount.
|
|
|
|
balance field
|
|
balanceN sets a balance assertion amount (or if the posting amount is
|
|
left empty, a balance assignment) on posting N.
|
|
|
|
balance is a compatibility spelling for hledger <1.17; it is equivalent
|
|
to balance1.
|
|
|
|
You can adjust the type of assertion/assignment with the balance-type
|
|
rule (see below).
|
|
|
|
See Tips below for more about setting amounts and currency.
|
|
|
|
if block
|
|
Rules can be applied conditionally, depending on patterns in the CSV
|
|
data. This allows flexibility; in particular, it is how you can cate-
|
|
gorise transactions, selecting an appropriate account name based on
|
|
their description (for example). There are two ways to write condi-
|
|
tional rules: "if blocks", described here, and "if tables", described
|
|
below.
|
|
|
|
An if block is the word if and one or more "matcher" 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,
|
|
|
|
if MATCHER
|
|
RULE
|
|
|
|
or
|
|
|
|
if
|
|
MATCHER
|
|
MATCHER
|
|
MATCHER
|
|
RULE
|
|
RULE
|
|
|
|
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:
|
|
|
|
o skip - skips the matched CSV record (generating no transaction from
|
|
it)
|
|
|
|
o end - skips the rest of the current CSV file.
|
|
|
|
Some examples:
|
|
|
|
# if the record contains "groceries", set account2 to "expenses:groceries"
|
|
if groceries
|
|
account2 expenses:groceries
|
|
|
|
# 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
|
|
|
|
# if an empty record is seen (assuming five fields), ignore the rest of the CSV file
|
|
if ,,,,
|
|
end
|
|
|
|
Matchers
|
|
There are two kinds:
|
|
|
|
1. A record matcher is a word or single-line text fragment or regular
|
|
expression (REGEX), which hledger will try to match case-insensi-
|
|
tively anywhere within the CSV record.
|
|
Eg: whole foods
|
|
|
|
2. A field matcher is preceded with a percent sign and CSV field name
|
|
(%CSVFIELD REGEX). hledger will try to match these just within the
|
|
named CSV field.
|
|
Eg: %date 2023
|
|
|
|
The regular expression is (as usual in hledger) a POSIX extended regu-
|
|
lar expression, that also supports GNU word boundaries (\b, \B, \<,
|
|
\>), and nothing else. If you have trouble, see "Regular expressions"
|
|
in the hledger manual (https://hledger.org/hledger.html#regular-expres-
|
|
sions).
|
|
|
|
With record matchers, it'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:
|
|
|
|
2020-01-01; "Acme, Inc."; 1,000
|
|
|
|
the regex would see, and try to match, this modified record text:
|
|
|
|
2020-01-01,Acme, Inc., 1,000
|
|
|
|
When an if block has multiple matchers, they are combined as follows:
|
|
|
|
o By default they are OR'd (any one of them can match)
|
|
|
|
o When a matcher is preceded by ampersand (&) it will be AND'ed with
|
|
the previous matcher (both of them must match).
|
|
|
|
There's not yet an easy syntax to negate a matcher.
|
|
|
|
if table
|
|
"if tables" are an alternative to if blocks; they can express many
|
|
matchers and field assignments in a more compact tabular format, like
|
|
this:
|
|
|
|
if,HLEDGERFIELD1,HLEDGERFIELD2,...
|
|
MATCHERA,VALUE1,VALUE2,...
|
|
MATCHERB,VALUE1,VALUE2,...
|
|
MATCHERC,VALUE1,VALUE2,...
|
|
<empty line>
|
|
|
|
The first character after if is taken to be the separator for the rest
|
|
of the table. It should be a non-alphanumeric character like , or |
|
|
that does not appear anywhere else in the table. (Note: it is unre-
|
|
lated to the CSV file's separator.) 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). Each line
|
|
must contain the same number of separators; empty values are allowed.
|
|
|
|
The above means: 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:
|
|
|
|
if MATCHERA
|
|
HLEDGERFIELD1 VALUE1
|
|
HLEDGERFIELD2 VALUE2
|
|
...
|
|
|
|
if MATCHERB
|
|
HLEDGERFIELD1 VALUE1
|
|
HLEDGERFIELD2 VALUE2
|
|
...
|
|
|
|
if MATCHERC
|
|
HLEDGERFIELD1 VALUE1
|
|
HLEDGERFIELD2 VALUE2
|
|
...
|
|
|
|
Example:
|
|
|
|
if,account2,comment
|
|
atm transaction fee,expenses:business:banking,deductible? check it
|
|
%description groceries,expenses:groceries,
|
|
2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
|
|
|
|
balance-type
|
|
Balance assertions generated by assigning to balanceN are of the simple
|
|
= 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
|
|
balance-type rule:
|
|
|
|
# balance assertions will consider all commodities and all subaccounts
|
|
balance-type ==*
|
|
|
|
Here are the balance assertion types for quick reference:
|
|
|
|
= single commodity, exclude subaccounts
|
|
=* single commodity, include subaccounts
|
|
== multi commodity, exclude subaccounts
|
|
==* multi commodity, include subaccounts
|
|
|
|
include
|
|
include RULESFILE
|
|
|
|
This includes the contents of another CSV rules file at this point.
|
|
RULESFILE is an absolute file path or a path relative to the current
|
|
file's directory. This can be useful for sharing common rules between
|
|
several rules files, eg:
|
|
|
|
# someaccount.csv.rules
|
|
|
|
## someaccount-specific rules
|
|
fields date,description,amount
|
|
account1 assets:someaccount
|
|
account2 expenses:misc
|
|
|
|
## common rules
|
|
include categorisation.rules
|
|
|
|
Working with CSV
|
|
Some tips:
|
|
|
|
Rapid feedback
|
|
It's a good idea to get rapid feedback while creating/troubleshooting
|
|
CSV rules. Here's a good way, using entr from eradman.com/entrproject:
|
|
|
|
$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
|
|
|
|
A desc: query (eg) is used to select just one, or a few, transactions
|
|
of interest. "bash -c" 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.
|
|
|
|
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:
|
|
|
|
o Values may be enclosed in double quotes, or not. Enclosing in single
|
|
quotes is not allowed. (Eg 'A','B' is rejected.)
|
|
|
|
o When values are enclosed in double quotes, spaces outside the quotes
|
|
are not allowed. (Eg "A", "B" is rejected.)
|
|
|
|
o When values are not enclosed in quotes, they may not contain double
|
|
quotes. (Eg A"A, B is rejected.)
|
|
|
|
If your CSV/SSV/TSV is not valid in this sense, you'll need to trans-
|
|
form it before reading with hledger. Try using sed, or a more permis-
|
|
sive CSV parser like python's csv lib.
|
|
|
|
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's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv
|
|
filename extension. (More about this at Data formats.)
|
|
|
|
When reading files with the "wrong" extension, you can ensure the CSV
|
|
reader (and the default field separator) by prefixing the file path
|
|
with csv:, ssv: or tsv:: Eg:
|
|
|
|
$ hledger -f ssv:foo.dat print
|
|
|
|
You can also override the default field separator with a separator rule
|
|
if needed.
|
|
|
|
Reading CSV from standard input
|
|
You'll need the file format prefix when reading CSV from stdin also,
|
|
since hledger assumes journal format by default. Eg:
|
|
|
|
$ cat foo.dat | hledger -f ssv:- print
|
|
|
|
Reading multiple CSV files
|
|
If you use multiple -f options to read multiple CSV files at once,
|
|
hledger will look for a correspondingly-named rules file for each CSV
|
|
file. But if you use the --rules-file option, that rules file will be
|
|
used for all the CSV files.
|
|
|
|
Valid transactions
|
|
After reading a CSV file, hledger post-processes and validates the gen-
|
|
erated 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.
|
|
|
|
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:
|
|
|
|
$ hledger -f file.csv print | hledger -f- print
|
|
|
|
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.
|
|
|
|
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't have to remember how many times you ran it or with which version
|
|
of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This
|
|
is the easiest way to import CSV data. Eg:
|
|
|
|
# download the latest CSV files, then run this command.
|
|
# Note, no -f flags needed here.
|
|
$ hledger import *.csv [--dry]
|
|
|
|
This method works for most CSV files. (Where records have a stable
|
|
chronological order, and new records appear only at the new end.)
|
|
|
|
A number of other tools and workflows, hledger-specific and otherwise,
|
|
exist for converting, deduplicating, classifying and managing CSV data.
|
|
See:
|
|
|
|
o https://hledger.org/cookbook.html#setups-and-workflows
|
|
|
|
o https://plaintextaccounting.org -> data import/conversion
|
|
|
|
Setting amounts
|
|
Continuing from amount field above, here are more tips on handling var-
|
|
ious amount-setting situations:
|
|
|
|
1. If the amount is in a single CSV field:
|
|
|
|
a. If its sign indicates direction of flow:
|
|
Assign it to amountN, to set the Nth posting's amount. N is usu-
|
|
ally 1 or 2 but can go up to 99.
|
|
|
|
b. If another field indicates direction of flow:
|
|
Use one or more conditional rules to set the appropriate amount
|
|
sign. Eg:
|
|
|
|
# assume a withdrawal unless Type contains "deposit":
|
|
amount1 -%Amount
|
|
if %Type deposit
|
|
amount1 %Amount
|
|
|
|
2. If the amount is in one of two CSV fields (eg Debit and Credit):
|
|
|
|
a. If both fields are unsigned:
|
|
Assign the fields to amountN-in and amountN-out. This sets posting
|
|
N's amount to whichever of these has a non-zero value. If it's the
|
|
-out value, the amount will be negated.
|
|
|
|
b. If either field is signed:
|
|
Use a conditional rule to flip the sign when needed. Eg below, the
|
|
-out value already has a minus sign so we undo hledger's automatic
|
|
negating by negating once more (but only if the field is non-empty,
|
|
so that we don't leave a minus sign by itself):
|
|
|
|
fields date, description, amount1-in, amount1-out
|
|
if %amount1-out [1-9]
|
|
amount1-out -%amount1-out
|
|
|
|
c. If both fields can contain a non-zero value (or both can be
|
|
empty):
|
|
The -in/-out rules normally choose the value which is non-zero/non-
|
|
empty. Some value pairs can be ambiguous, such as 1 and none. 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:
|
|
|
|
fields date, description, in, out
|
|
if %in [1-9]
|
|
amount1 %in
|
|
if %out [1-9]
|
|
amount1 %out
|
|
|
|
3. If you want posting 2's amount converted to cost:
|
|
Use the unnumbered amount (or amount-in and amount-out) syntax.
|
|
|
|
4. If the CSV has only balance amounts, not transaction amounts:
|
|
Assign to balanceN, to set a balance assignment on the Nth posting,
|
|
causing the posting's amount to be calculated automatically. balance
|
|
with no number is equivalent to balance1. In this situation hledger is
|
|
more likely to guess the wrong default account name, so you may need to
|
|
set that explicitly.
|
|
|
|
Amount signs
|
|
There is some special handling for amount signs, to simplify parsing
|
|
and sign-flipping:
|
|
|
|
o If an amount value begins with a plus sign:
|
|
that will be removed: +AMT becomes AMT
|
|
|
|
o If an amount value is parenthesised:
|
|
it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT
|
|
|
|
o If an amount value has two minus signs (or two sets of parentheses,
|
|
or a minus sign and parentheses):
|
|
they cancel out and will be removed: --AMT or -(AMT) becomes AMT
|
|
|
|
o If an amount value contains just a sign (or just a set of parenthe-
|
|
ses):
|
|
that is removed, making it an empty value. "+" or "-" or "()" becomes
|
|
"".
|
|
|
|
Setting currency/commodity
|
|
If the currency/commodity symbol is included in the CSV's amount
|
|
field(s):
|
|
|
|
2020-01-01,foo,$123.00
|
|
|
|
you don't have to do anything special for the commodity symbol, it will
|
|
be assigned as part of the amount. Eg:
|
|
|
|
fields date,description,amount
|
|
|
|
2020-01-01 foo
|
|
expenses:unknown $123.00
|
|
income:unknown $-123.00
|
|
|
|
If the currency is provided as a separate CSV field:
|
|
|
|
2020-01-01,foo,USD,123.00
|
|
|
|
You can assign that to the currency pseudo-field, which has the special
|
|
effect of prepending itself to every amount in the transaction (on the
|
|
left, with no separating space):
|
|
|
|
fields date,description,currency,amount
|
|
|
|
2020-01-01 foo
|
|
expenses:unknown USD123.00
|
|
income:unknown USD-123.00
|
|
|
|
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:
|
|
|
|
fields date,description,cur,amt
|
|
amount %amt %cur
|
|
|
|
2020-01-01 foo
|
|
expenses:unknown 123.00 USD
|
|
income:unknown -123.00 USD
|
|
|
|
Note we used a temporary field name (cur) that is not currency - that
|
|
would trigger the prepending effect, which we don't want here.
|
|
|
|
Amount decimal places
|
|
Like amounts in a journal file, the amounts generated by CSV rules like
|
|
amount1 influence commodity display styles, such as the number of deci-
|
|
mal places displayed in reports.
|
|
|
|
The original amounts as written in the CSV file do not affect display
|
|
style (because we don't yet reliably know their commodity).
|
|
|
|
Referencing other fields
|
|
In field assignments, you can interpolate only CSV fields, not hledger
|
|
fields. In the example below, there's both a CSV field and a hledger
|
|
field named amount1, but %amount1 always means the CSV field, not the
|
|
hledger field:
|
|
|
|
# Name the third CSV field "amount1"
|
|
fields date,description,amount1
|
|
|
|
# Set hledger'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
|
|
|
|
Here, since there's no CSV amount1 field, %amount1 will produce a lit-
|
|
eral "amount1":
|
|
|
|
fields date,description,csvamount
|
|
amount1 %csvamount USD
|
|
# Can't interpolate amount1 here
|
|
comment %amount1
|
|
|
|
When there are multiple field assignments to the same hledger field,
|
|
only the last one takes effect. Here, comment's value will be be B, or
|
|
C if "something" is matched, but never A:
|
|
|
|
comment A
|
|
comment B
|
|
if something
|
|
comment C
|
|
|
|
How CSV rules are evaluated
|
|
Here's how to think of CSV rules being evaluated (if you really need
|
|
to). First,
|
|
|
|
o include - 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.)
|
|
|
|
Then "global" rules are evaluated, top to bottom. If a rule is
|
|
repeated, the last one wins:
|
|
|
|
o skip (at top level)
|
|
|
|
o date-format
|
|
|
|
o newest-first
|
|
|
|
o fields - names the CSV fields, optionally sets up initial assignments
|
|
to hledger fields
|
|
|
|
Then for each CSV record in turn:
|
|
|
|
o test all if blocks. If any of them contain a end rule, skip all
|
|
remaining CSV records. Otherwise if any of them contain a skip rule,
|
|
skip that many CSV records. If there are multiple matched skip
|
|
rules, the first one wins.
|
|
|
|
o collect all field assignments at top level and in matched if blocks.
|
|
When there are multiple assignments for a field, keep only the last
|
|
one.
|
|
|
|
o compute a value for each hledger field - either the one that was
|
|
assigned to it (and interpolate the %CSVFIELD references), or a
|
|
default
|
|
|
|
o generate a hledger transaction (journal entry) from these values.
|
|
|
|
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.
|
|
|
|
|
|
Well factored rules
|
|
Some things than can help reduce duplication and complexity in rules
|
|
files:
|
|
|
|
o Extracting common rules usable with multiple CSV files into a com-
|
|
mon.rules, and adding include common.rules to each CSV's rules file.
|
|
|
|
o Splitting if blocks into smaller if blocks, extracting the frequently
|
|
used parts.
|
|
|
|
CSV rules examples
|
|
Bank of Ireland
|
|
Here'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 neces-
|
|
sary but provides extra error checking:
|
|
|
|
Date,Details,Debit,Credit,Balance
|
|
07/12/2012,LODGMENT 529898,,10.0,131.21
|
|
07/12/2012,PAYMENT,5,,126
|
|
|
|
# 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 "balance"
|
|
# 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
|
|
|
|
$ 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
|
|
|
|
The balance assertions don't raise an error above, because we're read-
|
|
ing directly from CSV, but they will be checked if these entries are
|
|
imported into a journal file.
|
|
|
|
Coinbase
|
|
A simple example with some CSV from Coinbase. The spot price is
|
|
recorded using cost notation. The legacy amount field name conve-
|
|
niently sets amount 2 (posting 2's amount) to the total cost.
|
|
|
|
# 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,"","","","Received 100.00 USDC from an external account"
|
|
|
|
# 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 @ %Spot_Price_at_Transaction %Spot_Price_Currency
|
|
|
|
$ hledger print -f coinbase.csv
|
|
2021-12-30 Received 100.00 USDC from an external account
|
|
assets:coinbase:cc 100 USDC @ 0.740000 GBP
|
|
income:unknown -74.000000 GBP
|
|
|
|
Amazon
|
|
Here we convert amazon.com order history, and use an if block to gener-
|
|
ate a third posting if there's a fee. (In practice you'd probably get
|
|
this data from your bank instead, but it's an example.)
|
|
|
|
"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
|
|
"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"
|
|
"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"
|
|
|
|
# amazon-orders.csv.rules
|
|
|
|
# skip one header line
|
|
skip 1
|
|
|
|
# name the csv fields, and assign the transaction's date, amount and code.
|
|
# Avoided the "status" and "amount" 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'm assuming amzamount excludes the fees, don'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
|
|
|
|
$ 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
|
|
|
|
Paypal
|
|
Here's a real-world rules file for (customised) Paypal CSV, with some
|
|
Paypal-specific rules, and a second rules file included:
|
|
|
|
"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
|
|
"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""
|
|
"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""
|
|
"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""
|
|
"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""
|
|
"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""
|
|
"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""
|
|
"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""
|
|
|
|
# paypal-custom.csv.rules
|
|
|
|
# Tips:
|
|
# Export from Activity -> Statements -> Custom -> Activity download
|
|
# Suggested transaction type: "Balance affecting"
|
|
# Paypal's default fields in 2018 were:
|
|
# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"
|
|
# This rules file assumes the following more detailed fields, configured in "Customize report fields":
|
|
# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
|
|
|
|
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'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's income (a debit)
|
|
if %grossamount ^[^-]
|
|
account2 income:unknown
|
|
# if negative, it's an expense (a credit)
|
|
if %grossamount ^-
|
|
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
|
|
|
|
# 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
|
|
|
|
$ 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@joyful.com, toemail:memberships@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@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@joyful.com, toemail:support@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@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@joyful.com, toemail:tle@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@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@bene.fac.tor, toemail:simon@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:
|
|
|
|
Timeclock
|
|
The time logging format of timeclock.el, as read by hledger.
|
|
|
|
hledger can read time logs in timeclock format. As with Ledger, these
|
|
are (a subset of) timeclock.el'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
|
|
# or ; or *, and blank lines, are ignored.
|
|
|
|
i 2015/03/30 09:00:00 some:account name optional description after two spaces
|
|
o 2015/03/30 09:20:00
|
|
i 2015/03/31 22:21:45 another account
|
|
o 2015/04/01 02:00:34
|
|
|
|
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, hledger print generates these journal entries:
|
|
|
|
$ hledger -f t.timeclock print
|
|
2015-03-30 * optional description after two spaces
|
|
(some:account name) 0.33h
|
|
|
|
2015-03-31 * 22:21-23:59
|
|
(another account) 1.64h
|
|
|
|
2015-04-01 * 00:00-02:00
|
|
(another account) 2.01h
|
|
|
|
Here is a sample.timeclock to download and some queries to try:
|
|
|
|
$ 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
|
|
|
|
To generate time logs, ie to clock in and clock out, you could:
|
|
|
|
o use emacs and the built-in timeclock.el, or the extended timeclock-
|
|
x.el and perhaps the extras in ledgerutils.el
|
|
|
|
o at the command line, use these bash aliases: shell alias ti="echo
|
|
i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o
|
|
`date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
|
|
|
|
o or use the old ti and to scripts in the ledger 2.x repository. These
|
|
rely on a "timeclock" executable which I think is just the ledger 2
|
|
executable renamed.
|
|
|
|
|
|
Timedot
|
|
timedot format is hledger's human-friendly time logging format. Com-
|
|
pared to timeclock format, it is
|
|
|
|
o convenient for quick, approximate, and retroactive time logging
|
|
|
|
o readable: you can see at a glance where time was spent.
|
|
|
|
A timedot file contains a series of day entries, which might look like
|
|
this:
|
|
|
|
2021-08-04
|
|
hom:errands .... ....
|
|
fos:hledger:timedot .. ; docs
|
|
per:admin:finance
|
|
|
|
hledger reads this as three time transactions on this day, with each
|
|
dot representing a quarter-hour spent:
|
|
|
|
$ hledger -f a.timedot print # .timedot file extension activates the timedot reader
|
|
2021-08-04 *
|
|
(hom:errands) 2.00
|
|
|
|
2021-08-04 *
|
|
(fos:hledger:timedot) 0.50
|
|
|
|
2021-08-04 *
|
|
(per:admin:finance) 0
|
|
|
|
A day entry begins with a date line:
|
|
|
|
o a non-indented simple date (Y-M-D, Y/M/D, or Y.M.D).
|
|
|
|
Optionally this can be followed on the same line by
|
|
|
|
o a common transaction description for this day
|
|
|
|
o a common transaction comment for this day, after a semicolon (;).
|
|
|
|
After the date line are zero or more optionally-indented time transac-
|
|
tion lines, consisting of:
|
|
|
|
o an account name - any word or phrase, usually a hledger-style account
|
|
name.
|
|
|
|
o two or more spaces - a field separator, required if there is an
|
|
amount (as in journal format).
|
|
|
|
o a timedot amount - dots representing quarter hours, or a number rep-
|
|
resenting hours.
|
|
|
|
o an optional comment beginning with semicolon. This is ignored.
|
|
|
|
In more detail, timedot amounts can be:
|
|
|
|
o dots: zero or more period characters, each representing one quarter-
|
|
hour. Spaces are ignored and can be used for grouping. Eg: .... ..
|
|
|
|
o a number, representing hours. Eg: 1.5
|
|
|
|
o a number immediately followed by a unit symbol s, m, h, d, w, mo, or
|
|
y, representing seconds, minutes, hours, days weeks, months or years.
|
|
Eg 1.5h or 90m. The following equivalencies are assumed:
|
|
60s = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. (This
|
|
unit will not be visible in the generated transaction amount, which is
|
|
always in hours.)
|
|
|
|
There is some added flexibility to help with keeping time log data in
|
|
the same file as your notes, todo lists, etc.:
|
|
|
|
o Blank lines and lines beginning with # or ; are ignored.
|
|
|
|
o Before the first date line, lines beginning with * are ignored. From
|
|
the first date line onward, a sequence of *'s followed by a space at
|
|
beginning of lines (ie, the headline prefix used by Emacs Org mode)
|
|
is ignored. This means the time log can be kept under an Org head-
|
|
line, and date lines or time transaction lines can be Org headlines.
|
|
|
|
o Lines not ending with a double-space and amount are parsed as trans-
|
|
actions with zero amount. (Most hledger reports hide these by
|
|
default; add -E to see them.)
|
|
|
|
More examples:
|
|
|
|
# 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 .
|
|
|
|
2016/2/3
|
|
inc:client1 4
|
|
fos:hledger 3
|
|
biz:research 1
|
|
|
|
* Time log
|
|
** 2020-01-01
|
|
*** adm:time .
|
|
*** adm:finance .
|
|
|
|
* 2020 Work Diary
|
|
** Q1
|
|
*** 2020-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
|
|
|
|
Reporting:
|
|
|
|
$ hledger -f a.timedot print date:2016/2/2
|
|
2016-02-02 *
|
|
(inc:client1) 2.00
|
|
|
|
2016-02-02 *
|
|
(biz:research) 0.25
|
|
|
|
$ 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
|
|
|
|
Using period instead of colon as account name separator:
|
|
|
|
2016/2/4
|
|
fos.hledger.timedot 4
|
|
fos.ledger ..
|
|
|
|
$ hledger -f a.timedot --alias /\\./=: bal --tree
|
|
4.50 fos
|
|
4.00 hledger:timedot
|
|
0.50 ledger
|
|
--------------------
|
|
4.50
|
|
|
|
A sample.timedot file.
|
|
|
|
PART 3: REPORTING CONCEPTS
|
|
Time periods
|
|
Report start & end date
|
|
By default, most hledger reports will show the full span of time repre-
|
|
sented 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.
|
|
|
|
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 -b/--begin,
|
|
-e/--end, -p/--period or a date: query (described below). All of these
|
|
accept the smart date syntax (below).
|
|
|
|
Some notes:
|
|
|
|
o End dates are exclusive, as in Ledger, so you should write the date
|
|
after the last day you want to see in the report.
|
|
|
|
o As noted in reporting options: among start/end dates specified with
|
|
options, the last (i.e. right-most) option takes precedence.
|
|
|
|
o The effective report start and end dates are the intersection of the
|
|
start/end dates from options and that from date: queries. That is,
|
|
date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the
|
|
smallest common time span.
|
|
|
|
o In some cases a report interval will adjust start/end dates to fall
|
|
on interval boundaries (see below).
|
|
|
|
Examples:
|
|
|
|
|
|
-b 2016/3/17 begin on St. Patrick's day 2016
|
|
-e 12/1 end at the start of december 1st of the current year
|
|
(11/30 will be the last date included)
|
|
-b thismonth all transactions on or after the 1st of the current month
|
|
-p thismonth all transactions in the current month
|
|
date:2016/3/17.. the above written as queries instead (.. can also be
|
|
replaced with -)
|
|
date:..12/1
|
|
date:thismonth..
|
|
date:thismonth
|
|
|
|
Smart dates
|
|
hledger's user interfaces accept a "smart date" syntax for added conve-
|
|
nience. Smart dates optionally can be relative to today's date, be
|
|
written with english words, and have less-significant parts omitted
|
|
(missing parts are inferred as 1). Some examples:
|
|
|
|
|
|
2004/10/1, 2004-01-01, exact date, several separators allowed. Year
|
|
2004.9.1 is 4+ digits, month is 1-12, day is 1-31
|
|
2004 start of year
|
|
2004/10 start of month
|
|
10/1 month and day in current year
|
|
21 day in current month
|
|
october, oct start of month in current year
|
|
yesterday, today, tomor- -1, 0, 1 days from today
|
|
row
|
|
last/this/next -1, 0, 1 periods from the current period
|
|
day/week/month/quar-
|
|
ter/year
|
|
in n n periods from the current period
|
|
days/weeks/months/quar-
|
|
ters/years
|
|
n n periods from the current period
|
|
days/weeks/months/quar-
|
|
ters/years ahead
|
|
n -n periods from the current period
|
|
days/weeks/months/quar-
|
|
ters/years ago
|
|
20181201 8 digit YYYYMMDD with valid year month and day
|
|
201812 6 digit YYYYMM with valid year and month
|
|
|
|
Some counterexamples - malformed digit sequences might give surprising
|
|
results:
|
|
|
|
|
|
201813 6 digits with an invalid month is parsed as start of
|
|
6-digit year
|
|
20181301 8 digits with an invalid month is parsed as start of
|
|
8-digit year
|
|
20181232 8 digits with an invalid day gives an error
|
|
201801012 9+ digits beginning with a valid YYYYMMDD gives an error
|
|
|
|
"Today's date" can be overridden with the --today option, in case it's
|
|
needed for testing or for recreating old reports. (Except for periodic
|
|
transaction rules, which are not affected by --today.)
|
|
|
|
Report intervals
|
|
A report interval can be specified so that reports like register, bal-
|
|
ance or activity become multi-period, showing each subperiod as a sepa-
|
|
rate row or column.
|
|
|
|
The following standard intervals can be enabled with command-line
|
|
flags:
|
|
|
|
o -D/--daily
|
|
|
|
o -W/--weekly
|
|
|
|
o -M/--monthly
|
|
|
|
o -Q/--quarterly
|
|
|
|
o -Y/--yearly
|
|
|
|
More complex intervals can be specified using -p/--period, described
|
|
below.
|
|
|
|
Date adjustment
|
|
With a report interval (other than daily), report start / end dates
|
|
which have not been specified explicitly and in full (eg not -b
|
|
2023-01-01, but -b 2023-01 or -b 2023 or unspecified) are considered
|
|
flexible:
|
|
|
|
o A flexible start date will be automatically adjusted earlier if
|
|
needed to fall on a natural interval boundary.
|
|
|
|
o Similarly, a flexible end date will be adjusted later if needed to
|
|
make the last period a whole interval (the same length as the oth-
|
|
ers).
|
|
|
|
This is convenient for producing clean periodic reports (this is tradi-
|
|
tional hledger behaviour). By contrast, fully-specified exact dates
|
|
will not be adjusted (this is new in hledger 1.29).
|
|
|
|
An example: with a journal whose first date is 2023-01-10 and last date
|
|
is 2023-03-20:
|
|
|
|
o hledger bal -M -b 2023/1/15 -e 2023/3/10
|
|
The report periods will begin on the 15th day of each month, starting
|
|
from 2023-01-15, and the last period's last day will be 2023-03-09.
|
|
(Exact start and end dates, neither is adjusted.)
|
|
|
|
o hledger bal -M -b 2023-01 -e 2023-04 or hledger bal -M
|
|
The report periods will begin on the 1st of each month, starting from
|
|
2023-01-01, and the last period's last day will be 2023-03-31. (Flexi-
|
|
ble start and end dates, both are adjusted.)
|
|
|
|
Period expressions
|
|
The -p/--period option specifies a period expression, which is a com-
|
|
pact way of expressing a start date, end date, and/or report interval.
|
|
|
|
Here's a period expression with a start and end date (specifying the
|
|
first quarter of 2009):
|
|
|
|
|
|
-p "from 2009/1/1 to 2009/4/1"
|
|
|
|
Several keywords like "from" and "to" are supported for readability;
|
|
these are optional. "to" can also be written as ".." or "-". The spa-
|
|
ces are also optional, as long as you don't run two dates together. So
|
|
the following are equivalent to the above:
|
|
|
|
|
|
-p "2009/1/1 2009/4/1"
|
|
-p2009/1/1to2009/4/1
|
|
-p2009/1/1..2009/4/1
|
|
|
|
Dates are smart dates, so if the current year is 2009, these are also
|
|
equivalent to the above:
|
|
|
|
|
|
-p "1/1 4/1"
|
|
-p "jan-apr"
|
|
-p "this year to 4/1"
|
|
|
|
If you specify only one date, the missing start or end date will be the
|
|
earliest or latest transaction date in the journal:
|
|
|
|
|
|
|
|
|
|
-p "from 2009/1/1" everything after january
|
|
1, 2009
|
|
-p "since 2009/1" the same, since is a syn-
|
|
onym
|
|
-p "from 2009" the same
|
|
-p "to 2009" everything before january
|
|
1, 2009
|
|
|
|
You can also specify a period by writing a single partial or full date:
|
|
|
|
|
|
-p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1"
|
|
-p "2009/1" the month of january 2009; equivalent to "2009/1/1 to
|
|
2009/2/1"
|
|
-p "2009/1/1" the first day of 2009; equivalent to "2009/1/1 to
|
|
2009/1/2"
|
|
|
|
or by using the "Q" quarter-year syntax (case insensitive):
|
|
|
|
|
|
-p "2009Q1" first quarter of 2009, equivalent to "2009/1/1 to
|
|
2009/4/1"
|
|
-p "q4" fourth quarter of the current year
|
|
|
|
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 in:
|
|
|
|
|
|
-p "weekly from 2009/1/1 to 2009/4/1"
|
|
-p "monthly in 2008"
|
|
-p "quarterly"
|
|
|
|
More complex report intervals
|
|
Some more complex intervals can be specified within period expressions,
|
|
such as:
|
|
|
|
o biweekly (every two weeks)
|
|
|
|
o fortnightly
|
|
|
|
o bimonthly (every two months)
|
|
|
|
o every day|week|month|quarter|year
|
|
|
|
o every N days|weeks|months|quarters|years
|
|
|
|
Weekly on a custom day:
|
|
|
|
o every Nth day of week (th, nd, rd, or st are all accepted after the
|
|
number)
|
|
|
|
o every WEEKDAYNAME (full or three-letter english weekday name, case
|
|
insensitive)
|
|
|
|
Monthly on a custom day:
|
|
|
|
o every Nth day [of month]
|
|
|
|
o every Nth WEEKDAYNAME [of month]
|
|
|
|
Yearly on a custom day:
|
|
|
|
o every MM/DD [of year] (month number and day of month number)
|
|
|
|
o every MONTHNAME DDth [of year] (full or three-letter english month
|
|
name, case insensitive, and day of month number)
|
|
|
|
o every DDth MONTHNAME [of year] (equivalent to the above)
|
|
|
|
Examples:
|
|
|
|
|
|
-p "bimonthly from 2008"
|
|
|
|
-p "every 2 weeks"
|
|
-p "every 5 months from
|
|
2009/03"
|
|
-p "every 2nd day of week" periods will go from Tue to Tue
|
|
-p "every Tue" same
|
|
-p "every 15th day" period boundaries will be on 15th of each
|
|
month
|
|
-p "every 2nd Monday" period boundaries will be on second Monday
|
|
of each month
|
|
-p "every 11/05" yearly periods with boundaries on 5th of
|
|
November
|
|
-p "every 5th November" same
|
|
-p "every Nov 5th" same
|
|
|
|
Show historical balances at end of the 15th day of each month (N is an
|
|
end date, exclusive as always):
|
|
|
|
$ hledger balance -H -p "every 16th day"
|
|
|
|
Group postings from the start of wednesday to end of the following
|
|
tuesday (N is both (inclusive) start date and (exclusive) end date):
|
|
|
|
$ hledger register checking -p "every 3rd day of week"
|
|
|
|
Multiple weekday intervals
|
|
This special form is also supported:
|
|
|
|
o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week-
|
|
day names, case insensitive)
|
|
|
|
Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and
|
|
sat,sun.
|
|
|
|
This is mainly intended for use with --forecast, to generate periodic
|
|
transactions on arbitrary days of the week. It may be less useful with
|
|
-p, since it divides each week into subperiods of unequal length, which
|
|
is unusual. (Related: #1632)
|
|
|
|
Examples:
|
|
|
|
|
|
-p "every dates will be Mon, Wed, Fri; periods will be Mon-
|
|
mon,wed,fri" Tue, Wed-Thu, Fri-Sun
|
|
-p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will
|
|
be Mon, Tue, Wed, Thu, Fri-Sun
|
|
-p "every weekend- dates will be Sat, Sun; periods will be Sat, Sun-Fri
|
|
day"
|
|
|
|
Depth
|
|
With the --depth NUM option (short form: -NUM), 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 depth: query argument: depth:2, --depth=2 or -2 are equiva-
|
|
lent.
|
|
|
|
Queries
|
|
One of hledger's strengths is being able to quickly report on a precise
|
|
subset of your data. Most hledger commands accept optional query argu-
|
|
ments to restrict their scope. The syntax is as follows:
|
|
|
|
o Zero or more space-separated query terms. These are most often
|
|
account name substrings:
|
|
|
|
utilities food:groceries
|
|
|
|
o Terms with spaces or other special characters should be enclosed in
|
|
quotes:
|
|
|
|
"personal care"
|
|
|
|
o Regular expressions are also supported:
|
|
|
|
"^expenses\b" "accounts (payable|receivable)"
|
|
|
|
o Add a query type prefix to match other parts of the data:
|
|
|
|
date:202012- desc:amazon cur:USD amt:">100" status:
|
|
|
|
o Add a not: prefix to negate a term:
|
|
|
|
not:cur:USD
|
|
|
|
Query types
|
|
Here are the types of query term available. Remember these can also be
|
|
prefixed with not: to convert them into a negative match.
|
|
|
|
acct:REGEX, REGEX
|
|
Match account names containing this (case insensitive) regular expres-
|
|
sion. This is the default query type when there is no prefix, and reg-
|
|
ular expression syntax is typically not needed, so usually we just
|
|
write an account name substring, like expenses or food.
|
|
|
|
amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
|
|
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. Oth-
|
|
erwise, the absolute magnitudes are compared, ignoring sign.
|
|
|
|
code:REGEX
|
|
Match by transaction code (eg check number).
|
|
|
|
cur:REGEX
|
|
Match postings or transactions including any amounts whose cur-
|
|
rency/commodity symbol is fully matched by REGEX. (For a partial
|
|
match, use .*REGEX.*). Note, to match special characters which are
|
|
regex-significant, you need to escape them with \. And for characters
|
|
which are significant to your shell you may need one more level of
|
|
escaping. So eg to match the dollar sign:
|
|
hledger print cur:\\$.
|
|
|
|
desc:REGEX
|
|
Match transaction descriptions.
|
|
|
|
date:PERIODEXPR
|
|
Match dates (or with the --date2 flag, secondary dates) within the
|
|
specified period. PERIODEXPR is a period expression with no report
|
|
interval. Examples:
|
|
date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter.
|
|
|
|
date2:PERIODEXPR
|
|
Match secondary dates within the specified period (independent of the
|
|
--date2 flag).
|
|
|
|
depth:N
|
|
Match (or display, depending on command) accounts at or above this
|
|
depth.
|
|
|
|
note:REGEX
|
|
Match transaction notes (the part of the description right of |, or the
|
|
whole description if there's no |).
|
|
|
|
payee:REGEX
|
|
Match transaction payee/payer names (the part of the description left
|
|
of |, or the whole description if there's no |).
|
|
|
|
real:, real:0
|
|
Match real or virtual postings respectively.
|
|
|
|
status:, status:!, status:*
|
|
Match unmarked, pending, or cleared transactions respectively.
|
|
|
|
type:TYPECODES
|
|
Match by account type (see Declaring accounts > Account types). TYPE-
|
|
CODES is one or more of the single-letter account type codes ALERXCV,
|
|
case insensitive. Note type:A and type:E will also match their respec-
|
|
tive subtypes C (Cash) and V (Conversion). Certain kinds of account
|
|
alias can disrupt account types, see Rewriting accounts > Aliases and
|
|
account types.
|
|
|
|
tag:REGEX[=REGEX]
|
|
Match by tag name, and optionally also by tag value. (To match only by
|
|
value, use tag:.=REGEX.)
|
|
|
|
When querying by tag, note that:
|
|
|
|
o Accounts also inherit the tags of their parent accounts
|
|
|
|
o Postings also inherit the tags of their account and their transaction
|
|
|
|
o Transactions also acquire the tags of their postings.
|
|
|
|
(inacct:ACCTNAME
|
|
A special query term used automatically in hledger-web only: tells
|
|
hledger-web to show the transaction register for an account.)
|
|
|
|
Combining query terms
|
|
When given multiple query terms, most commands select things which
|
|
match:
|
|
|
|
o any of the description terms AND
|
|
|
|
o any of the account terms AND
|
|
|
|
o any of the status terms AND
|
|
|
|
o all the other terms.
|
|
|
|
The print command is a little different, showing transactions which:
|
|
|
|
o match any of the description terms AND
|
|
|
|
o have any postings matching any of the positive account terms AND
|
|
|
|
o have no postings matching any of the negative account terms AND
|
|
|
|
o match all the other terms.
|
|
|
|
Although these fixed rules are enough for many needs, we do not support
|
|
full boolean expressions (#203), (and you should not write AND or OR in
|
|
your queries). This makes certain queries hard to express, but here
|
|
are some tricks that can help:
|
|
|
|
1. Use a doubled not: prefix. Eg, to print only the food expenses paid
|
|
with cash:
|
|
|
|
$ hledger print food not:not:cash
|
|
|
|
2. Or pre-filter the transactions with print, piping the result into a
|
|
second hledger command (with balance assertions disabled):
|
|
|
|
$ hledger print cash | hledger -f- -I balance food
|
|
|
|
Queries and command options
|
|
Some queries can also be expressed as command-line options: depth:2 is
|
|
equivalent to --depth 2, date:2020 is equivalent to -p 2020, etc. When
|
|
you mix command options and query arguments, generally the resulting
|
|
query is their intersection.
|
|
|
|
Queries and valuation
|
|
When amounts are converted to other commodities in cost or value
|
|
reports, cur: and amt: match the old commodity symbol and the old
|
|
amount quantity, not the new ones (except in hledger 1.22.0 where it's
|
|
reversed, see #1625).
|
|
|
|
Querying with account aliases
|
|
When account names are rewritten with --alias or alias, note that acct:
|
|
will match either the old or the new account name.
|
|
|
|
Querying with cost or value
|
|
When amounts are converted to other commodities in cost or value
|
|
reports, note that cur: matches the new commodity symbol, and not the
|
|
old one, and amt: 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.
|
|
|
|
Pivoting
|
|
Normally, hledger groups and sums amounts within each account. The
|
|
--pivot FIELD option substitutes some other transaction field for
|
|
account names, causing amounts to be grouped and summed by that field's
|
|
value instead. FIELD can be any of the transaction fields status,
|
|
code, description, payee, note, 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 colon:separated:parts will be displayed
|
|
hierarchically, like account names.
|
|
|
|
Some examples:
|
|
|
|
2016/02/16 Yearly Dues Payment
|
|
assets:bank account 2 EUR
|
|
income:dues -2 EUR ; member: John Doe
|
|
|
|
Normal balance report showing account names:
|
|
|
|
$ hledger balance
|
|
2 EUR assets:bank account
|
|
-2 EUR income:dues
|
|
--------------------
|
|
0
|
|
|
|
Pivoted balance report, using member: tag values instead:
|
|
|
|
$ hledger balance --pivot member
|
|
2 EUR
|
|
-2 EUR John Doe
|
|
--------------------
|
|
0
|
|
|
|
One way to show only amounts with a member: value (using a query):
|
|
|
|
$ hledger balance --pivot member tag:member=.
|
|
-2 EUR John Doe
|
|
--------------------
|
|
-2 EUR
|
|
|
|
Another way (the acct: query matches against the pivoted "account
|
|
name"):
|
|
|
|
$ hledger balance --pivot member acct:.
|
|
-2 EUR John Doe
|
|
--------------------
|
|
-2 EUR
|
|
|
|
Generating data
|
|
Two features for generating transient data (visible only at report
|
|
time) are built in to hledger's journal format:
|
|
|
|
o Auto posting rules can generate extra postings on certain transac-
|
|
tions. They are activated by the --auto flag.
|
|
|
|
o Periodic transaction rules can generate repeating transactions, usu-
|
|
ally dated in the future, to help with forecasting or budgeting.
|
|
They are activated by the --forecast or balance --budget options,
|
|
described next.
|
|
|
|
Forecasting
|
|
The --forecast flag activates any periodic transaction rules in the
|
|
journal. These will generate temporary additional transactions, usu-
|
|
ally recurring and in the future, which will appear in all reports.
|
|
hledger print --forecast is a good way to see them.
|
|
|
|
This can be useful for estimating balances into the future, perhaps
|
|
experimenting with different scenarios.
|
|
|
|
It could also be useful for scripted data entry: you could describe
|
|
recurring transactions, and every so often copy the output of print
|
|
--forecast into the journal.
|
|
|
|
The generated transactions will have an extra tag, like generated-
|
|
transaction:~ PERIODICEXPR, indicating which periodic rule generated
|
|
them. There is also a similar, hidden tag, named _generated-transac-
|
|
tion:, which you can use to reliably match transactions generated "just
|
|
now" (rather than printed in the past).
|
|
|
|
The forecast transactions are generated within a forecast period, which
|
|
is independent of the report period. (Forecast period sets the bounds
|
|
for generated transactions, report period controls which transactions
|
|
are reported.) The forecast period begins on:
|
|
|
|
o the start date provided within --forecast's argument, if any
|
|
|
|
o otherwise, the later of
|
|
|
|
o the report start date, if specified (with -b/-p/date:)
|
|
|
|
o the day after the latest ordinary transaction in the journal, if
|
|
any
|
|
|
|
o otherwise today.
|
|
|
|
It ends on:
|
|
|
|
o the end date provided within --forecast's argument, if any
|
|
|
|
o otherwise, the report end date, if specified (with -e/-p/date:)
|
|
|
|
o otherwise 180 days (6 months) from today.
|
|
|
|
Note, this means that ordinary transactions will suppress periodic
|
|
transactions, by default; the periodic transactions will not start
|
|
until after the last ordinary transaction. This is usually convenient,
|
|
but you can get around it in two ways:
|
|
|
|
o If you need to record some transactions in the future, make them
|
|
periodic transactions (with a single occurrence, eg: ~ YYYY-MM-DD)
|
|
rather than ordinary transactions. That way they won't suppress
|
|
other periodic transactions.
|
|
|
|
o Or give --forecast a period expression argument. A forecast period
|
|
specified this way can overlap ordinary transactions, and need not be
|
|
in the future. Some things to note:
|
|
|
|
o You must use = between flag and argument; a space won't work.
|
|
|
|
o The period expression can specify the forecast period's start date,
|
|
end date, or both. See also Report start & end date.
|
|
|
|
o The period expression should not specify a report interval. (Each
|
|
periodic transaction rule specifies its own interval.)
|
|
|
|
Some examples: --forecast=202001-202004, --forecast=jan-, --fore-
|
|
cast=2021.
|
|
|
|
Budgeting
|
|
With the balance command's --budget report, each periodic transaction
|
|
rule generates recurring budget goals in specified accounts, and goals
|
|
and actual performance can be compared. See the balance command's doc
|
|
below.
|
|
|
|
See also: Budgeting and Forecasting.
|
|
|
|
Cost reporting
|
|
This section is about recording the cost of things, in transactions
|
|
where one commodity is exchanged for another. Eg an exchange of cur-
|
|
rency, or a stock purchase or sale. First, a quick glossary:
|
|
|
|
o Conversion - an exchange of one currency or commodity for another.
|
|
Eg a foreign currency exchange, or a purchase or sale of stock or
|
|
cryptocurrency.
|
|
|
|
o Conversion transaction - a transaction involving one or more conver-
|
|
sions.
|
|
|
|
o Conversion rate - the cost per unit of one commodity in the other, ie
|
|
the exchange rate.
|
|
|
|
o Cost - how much of one commodity was paid to acquire the other. And
|
|
more generally, in hledger docs: the amount exchanged in the "sec-
|
|
ondary" commodity (usually your base currency), whether in a purchase
|
|
or a sale, and whether expressed per unit or in total. Also, the
|
|
"@/@@ PRICE" notation used to represent this.
|
|
|
|
-B: Convert to cost
|
|
As discussed in JOURNAL > Costs, when recording a transaction you can
|
|
also record the amount's cost in another commodity, by adding @ UNIT-
|
|
PRICE or @@ TOTALPRICE.
|
|
|
|
Then you can see a report with amounts converted to cost, by adding the
|
|
-B/--cost flag. (Mnemonic: "B" from "cost Basis", as in Ledger). Eg:
|
|
|
|
2022-01-01
|
|
assets:dollars $-135 ; 135 dollars is exchanged for..
|
|
assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each
|
|
|
|
$ hledger bal -N
|
|
$-135 assets:dollars
|
|
EUR100 assets:euros
|
|
$ hledger bal -N -B
|
|
$-135 assets:dollars
|
|
$135 assets:euros # <- the euros' cost
|
|
|
|
Notes:
|
|
|
|
-B is sensitive to the order of postings when a cost is inferred: the
|
|
inferred price will be in the commodity of the last amount. So if
|
|
example 3's postings are reversed, while the transaction is equivalent,
|
|
-B shows something different:
|
|
|
|
2022-01-01
|
|
assets:dollars $-135 ; 135 dollars sold
|
|
assets:euros EUR100 ; for 100 euros
|
|
|
|
$ hledger bal -N -B
|
|
EUR-100 assets:dollars # <- the dollars' selling price
|
|
EUR100 assets:euros
|
|
|
|
The @/@@ cost notation is convenient, but has some drawbacks: it does
|
|
not truly balance the transaction, so it disrupts the accounting equa-
|
|
tion and tends to causes a non-zero total in balance reports.
|
|
|
|
Equity conversion postings
|
|
By contrast, conventional double entry bookkeeping (DEB) uses a differ-
|
|
ent notation: an extra pair of equity postings to balance conversion
|
|
transactions. In this style, the above entry might be written:
|
|
|
|
2022-01-01 one hundred euros purchased at $1.35 each
|
|
assets:dollars $-135
|
|
equity:conversion $135
|
|
equity:conversion EUR-100
|
|
assets:euros EUR100
|
|
|
|
This style is more correct, but it's also more verbose and makes cost
|
|
reporting more difficult for PTA tools.
|
|
|
|
Happily, current hledger can read either notation, or convert one to
|
|
the other when needed, so you can use the one you prefer.
|
|
|
|
You can even use cost notation and equivalent conversion postings at
|
|
the same time, for clarity. hledger will ignore the redundancy. But
|
|
be sure the cost and conversion posting amounts match, or you'll see a
|
|
not-so-clear transaction balancing error message.
|
|
|
|
Inferring equity postings from cost
|
|
With --infer-equity, hledger detects transactions written with PTA cost
|
|
notation and adds equity conversion postings to them:
|
|
|
|
2022-01-01
|
|
assets:dollars -$135
|
|
assets:euros EUR100 @ $1.35
|
|
|
|
$ hledger print --infer-equity
|
|
2022-01-01
|
|
assets:dollars $-135
|
|
assets:euros EUR100 @ $1.35
|
|
equity:conversion:$-EUR:EUR EUR-100 ; generated-posting:
|
|
equity:conversion:$-EUR:$ $135.00 ; generated-posting:
|
|
|
|
The conversion account names can be changed with the conversion account
|
|
type declaration.
|
|
|
|
--infer-equity is useful when when transactions have been recorded
|
|
using cost notation, to help preserve the accounting equation and bal-
|
|
ance reports' zero total, or to produce more conventional journal
|
|
entries for sharing with non-PTA-users.
|
|
|
|
Inferring cost from equity postings
|
|
The reverse operation is possible using --infer-costs, which detects
|
|
transactions written with equity conversion postings and adds cost
|
|
notation to them:
|
|
|
|
2022-01-01
|
|
assets:dollars $-135
|
|
equity:conversion $135
|
|
equity:conversion EUR-100
|
|
assets:euros EUR100
|
|
|
|
$ hledger print --infer-costs
|
|
2022-01-01
|
|
assets:dollars $-135 @@ EUR100
|
|
equity:conversion $135
|
|
equity:conversion EUR-100
|
|
assets:euros EUR100
|
|
|
|
--infer-costs is useful when combined with -B/--cost, allowing cost
|
|
reporting even when transactions have been recorded using equity post-
|
|
ings:
|
|
|
|
$ hledger print --infer-costs -B
|
|
2009-01-01
|
|
assets:dollars EUR-100
|
|
assets:euros EUR100
|
|
|
|
Notes:
|
|
|
|
For --infer-costs to work, an exchange must consist of four postings:
|
|
|
|
1. two non-equity postings
|
|
|
|
2. two equity postings, next to one another
|
|
|
|
3. the equity accounts must be declared, with account type V/Conversion
|
|
(or if they are not declared, they must be named equity:conversion,
|
|
equity:trade, equity:trading or subaccounts of these)
|
|
|
|
4. the equity postings' amounts must exactly match the non-equity post-
|
|
ings' amounts.
|
|
|
|
Multiple such exchanges can coexist within a single transaction.
|
|
|
|
When inferring cost, the order of postings matters: the cost is added
|
|
to the first of the non-equity postings involved in the exchange, in
|
|
the commodity of the last non-equity posting involved in the exchange.
|
|
If you don't want to write your postings in the required order, you can
|
|
use explicit cost notation instead.
|
|
|
|
--infer-equity and --infer-costs can be used together, if you have a
|
|
mixture of both notations in your journal.
|
|
|
|
When to infer cost/equity
|
|
Inferring equity postings or costs is still fairly new, so not enabled
|
|
by default. We're not sure yet if that should change. Here are two
|
|
suggestions to try, experience reports welcome:
|
|
|
|
1. When you use -B, always use --infer-costs as well. Eg: hledger bal
|
|
-B --infer-costs
|
|
|
|
2. Always run hledger with both flags enabled. Eg: alias hl="hledger
|
|
--infer-equity --infer-costs"
|
|
|
|
How to record conversions
|
|
Essentially there are four ways to record a conversion transaction in
|
|
hledger. Here are all of them, with pros and cons.
|
|
|
|
Conversion with implicit cost
|
|
Let's assume 100 EUR is converted to 120 USD. You can just record the
|
|
outflow (100 EUR) and inflow (120 USD) in the appropriate asset
|
|
account:
|
|
|
|
2021-01-01
|
|
assets:cash -100 EUR
|
|
assets:cash 120 USD
|
|
|
|
hledger will assume this transaction is balanced, inferring that the
|
|
conversion rate must be 1 EUR = 1.20 USD. You can see the inferred
|
|
rate by using hledger print -x.
|
|
|
|
Pro:
|
|
|
|
o Concise, easy
|
|
|
|
Con:
|
|
|
|
o Less error checking - typos in amounts or commodity symbols may not
|
|
be detected
|
|
|
|
o Conversion rate is not clear
|
|
|
|
o Disturbs the accounting equation, unless you add the --infer-equity
|
|
flag
|
|
|
|
You can prevent accidental implicit conversions due to a mistyped com-
|
|
modity symbol, by using hledger check commodities.
|
|
|
|
You can prevent implicit conversions entirely, by using hledger check
|
|
balancednoautoconversion, or -s/--strict.
|
|
|
|
Conversion with explicit cost
|
|
You can add the conversion rate using @ notation:
|
|
|
|
2021-01-01
|
|
assets:cash -100 EUR @ 1.20 USD
|
|
assets:cash 120 USD
|
|
|
|
Now hledger will check that 100 * 1.20 = 120, and would report an error
|
|
otherwise.
|
|
|
|
Pro:
|
|
|
|
o Still concise
|
|
|
|
o Makes the conversion rate clear
|
|
|
|
o Provides more error checking
|
|
|
|
Con:
|
|
|
|
o Disturbs the accounting equation, unless you add the --infer-equity
|
|
flag
|
|
|
|
Conversion with equity postings
|
|
In strict double entry bookkeeping, the above transaction is not bal-
|
|
anced in EUR or in USD, since some EUR disappears, and some USD
|
|
appears. This violates the accounting equation (A+L+E=0), and prevents
|
|
reports like balancesheetequity from showing a zero total.
|
|
|
|
The proper way to make it balance is to add a balancing posting for
|
|
each commodity, using an equity account:
|
|
|
|
2021-01-01
|
|
assets:cash -100 EUR
|
|
equity:conversion 100 EUR
|
|
equity:conversion -120 USD
|
|
assets:cash 120 USD
|
|
|
|
Pro:
|
|
|
|
o Preserves the accounting equation
|
|
|
|
o Keeps track of conversions and related gains/losses in one place
|
|
|
|
o Standard, works in any double entry accounting system
|
|
|
|
Con:
|
|
|
|
o More verbose
|
|
|
|
o Conversion rate is not obvious
|
|
|
|
o Cost reporting requires adding the --infer-costs flag
|
|
|
|
Conversion with equity postings and explicit cost
|
|
Here both equity postings and @ notation are used together.
|
|
|
|
2021-01-01
|
|
assets:cash -100 EUR @ 1.20 USD
|
|
equity:conversion 100 EUR
|
|
equity:conversion -120 USD
|
|
assets:cash 120 USD
|
|
|
|
Pro:
|
|
|
|
o Preserves the accounting equation
|
|
|
|
o Keeps track of conversions and related gains/losses in one place
|
|
|
|
o Makes the conversion rate clear
|
|
|
|
o Provides more error checking
|
|
|
|
Con:
|
|
|
|
o Most verbose
|
|
|
|
o Not compatible with ledger
|
|
|
|
Cost tips
|
|
o Recording the cost/conversion rate explicitly is good because it
|
|
makes that clear and helps detect errors.
|
|
|
|
o Recording equity postings is good because it is correct bookkeeping
|
|
and preserves the accounting equation.
|
|
|
|
o Combining these is possible.
|
|
|
|
o When you want to see the cost (or sale proceeds) of things, use -B
|
|
(short form of --cost).
|
|
|
|
o If you use conversion postings without cost notation, add --infer-
|
|
costs also.
|
|
|
|
o If you use cost notation without conversion postings, and you want to
|
|
see a balanced balance sheet or print correct journal entries, use
|
|
--infer-equity.
|
|
|
|
o Conversion to cost is performed before valuation (described next).
|
|
|
|
Valuation
|
|
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 --value=TYPE[,COMMODITY]
|
|
option, which will be described below. We also provide the simpler -V
|
|
and -X COMMODITY options, and often one of these is all you need:
|
|
|
|
-V: Value
|
|
The -V/--market flag converts amounts to market value in their default
|
|
valuation commodity, using the market prices in effect on the valuation
|
|
date(s), if any. More on these in a minute.
|
|
|
|
-X: Value in specified commodity
|
|
The -X/--exchange=COMM option is like -V, except you tell it which cur-
|
|
rency you want to convert to, and it tries to convert everything to
|
|
that.
|
|
|
|
Valuation date
|
|
Since market prices can change from day to day, market value reports
|
|
have a valuation date (or more than one), which determines which market
|
|
prices will be used.
|
|
|
|
For single period reports, if an explicit report end date is specified,
|
|
that will be used as the valuation date; otherwise the valuation date
|
|
is the journal's end date.
|
|
|
|
For multiperiod reports, each column/period is valued on the last day
|
|
of the period, by default.
|
|
|
|
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 :
|
|
|
|
1. A declared market price or inferred market price: A's latest market
|
|
price in B on or before the valuation date as declared by a P direc-
|
|
tive, or (with the --infer-market-prices flag) inferred from costs.
|
|
|
|
2. A reverse market price: the inverse of a declared or inferred market
|
|
price from B to A.
|
|
|
|
3. A forward chain of market prices: a synthetic price formed by com-
|
|
bining the shortest chain of "forward" (only 1 above) market prices,
|
|
leading from A to B.
|
|
|
|
4. Any chain of market prices: a chain of any market prices, including
|
|
both forward and reverse prices (1 and 2 above), leading from A to
|
|
B.
|
|
|
|
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 "gave up" message visible in
|
|
--debug=2 output). That limit is currently 1000.
|
|
|
|
Amounts for which no suitable market price can be found, are not con-
|
|
verted.
|
|
|
|
--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 --infer-market-prices flag to -V, -X or
|
|
--value enables this.
|
|
|
|
So for example, hledger bs -V --infer-market-prices will get market
|
|
prices both from P directives and from transactions. If both occur on
|
|
the same day, the P directive takes precedence.
|
|
|
|
There is a downside: value reports can sometimes be affected in confus-
|
|
ing/undesired ways by your journal entries. If this happens to you,
|
|
read all of this Valuation section carefully, and try adding --debug or
|
|
--debug=2 to troubleshoot.
|
|
|
|
--infer-market-prices can infer market prices from:
|
|
|
|
o multicommodity transactions with explicit prices (@/@@)
|
|
|
|
o multicommodity transactions with implicit prices (no @, two commodi-
|
|
ties, unbalanced). (With these, the order of postings matters.
|
|
hledger print -x can be useful for troubleshooting.)
|
|
|
|
o multicommodity transactions with equity postings, if cost is inferred
|
|
with --infer-costs.
|
|
|
|
There is a limitation (bug) currently: when a valuation commodity is
|
|
not specified, prices inferred with --infer-market-prices do not help
|
|
select a default valuation commodity, as P prices would. So conversion
|
|
might not happen because no valuation commodity was detected (--debug=2
|
|
will show this). To be safe, specify the valuation commmodity, eg:
|
|
|
|
o -X EUR --infer-market-prices, not -V --infer-market-prices
|
|
|
|
o --value=then,EUR --infer-market-prices, not --value=then --infer-mar-
|
|
ket-prices
|
|
|
|
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.)
|
|
|
|
2022-01-01 Positive Unit prices
|
|
a A 1
|
|
b B -1 @ A 1
|
|
|
|
2022-01-01 Positive Total prices
|
|
a A 1
|
|
b B -1 @@ A 1
|
|
|
|
|
|
2022-01-02 Negative unit prices
|
|
a A 1
|
|
b B 1 @ A -1
|
|
|
|
2022-01-02 Negative total prices
|
|
a A 1
|
|
b B 1 @@ A -1
|
|
|
|
|
|
2022-01-03 Double Negative unit prices
|
|
a A -1
|
|
b B -1 @ A -1
|
|
|
|
2022-01-03 Double Negative total prices
|
|
a A -1
|
|
b B -1 @@ A -1
|
|
|
|
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:
|
|
|
|
$ 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
|
|
|
|
Valuation commodity
|
|
When you specify a valuation commodity (-X COMM or --value TYPE,COMM):
|
|
hledger will convert all amounts to COMM, wherever it can find a suit-
|
|
able market price (including by reversing or chaining prices).
|
|
|
|
When you leave the valuation commodity unspecified (-V or --value
|
|
TYPE):
|
|
For each commodity A, hledger picks a default valuation commodity as
|
|
follows, in this order of preference:
|
|
|
|
1. The price commodity from the latest P-declared market price for A on
|
|
or before valuation date.
|
|
|
|
2. 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.)
|
|
|
|
3. If there are no P directives at all (any commodity or date) and the
|
|
--infer-market-prices flag is used: the price commodity from the
|
|
latest transaction-inferred price for A on or before valuation date.
|
|
|
|
This means:
|
|
|
|
o If you have P directives, they determine which commodities -V will
|
|
convert, and to what.
|
|
|
|
o If you have no P directives, and use the --infer-market-prices flag,
|
|
costs determine it.
|
|
|
|
Amounts for which no valuation commodity can be found are not con-
|
|
verted.
|
|
|
|
Simple valuation examples
|
|
Here are some quick examples of -V:
|
|
|
|
; one euro is worth this many dollars from nov 1
|
|
P 2016/11/01 EUR $1.10
|
|
|
|
; purchase some euros on nov 3
|
|
2016/11/3
|
|
assets:euros EUR100
|
|
assets:checking
|
|
|
|
; the euro is worth fewer dollars by dec 21
|
|
P 2016/12/21 EUR $1.03
|
|
|
|
How many euros do I have ?
|
|
|
|
$ hledger -f t.j bal -N euros
|
|
EUR100 assets:euros
|
|
|
|
What are they worth at end of nov 3 ?
|
|
|
|
$ hledger -f t.j bal -N euros -V -e 2016/11/4
|
|
$110.00 assets:euros
|
|
|
|
What are they worth after 2016/12/21 ? (no report end date specified,
|
|
defaults to today)
|
|
|
|
$ hledger -f t.j bal -N euros -V
|
|
$103.00 assets:euros
|
|
|
|
--value: Flexible valuation
|
|
-V and -X are special cases of the more general --value option:
|
|
|
|
--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
|
|
|
|
The TYPE part selects cost or value and valuation date:
|
|
|
|
--value=then
|
|
Convert amounts to their value in the default valuation commod-
|
|
ity, using market prices on each posting's date.
|
|
|
|
--value=end
|
|
Convert amounts to their value in the default valuation commod-
|
|
ity, using market prices on the last day of the report period
|
|
(or if unspecified, the journal's end date); or in multiperiod
|
|
reports, market prices on the last day of each subperiod.
|
|
|
|
--value=now
|
|
Convert amounts to their value in the default valuation commod-
|
|
ity using current market prices (as of when report is gener-
|
|
ated).
|
|
|
|
--value=YYYY-MM-DD
|
|
Convert amounts to their value in the default valuation commod-
|
|
ity using market prices on this date.
|
|
|
|
To select a different valuation commodity, add the optional ,COMM part:
|
|
a comma, then the target commodity's symbol. Eg: --value=now,EUR.
|
|
hledger will do its best to convert amounts to this commodity, deducing
|
|
market prices as described above.
|
|
|
|
More valuation examples
|
|
Here are some examples showing the effect of --value, as seen with
|
|
print:
|
|
|
|
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 @ 5 B
|
|
|
|
2000-02-01
|
|
(a) 1 A @ 6 B
|
|
|
|
2000-03-01
|
|
(a) 1 A @ 7 B
|
|
|
|
Show the cost of each posting:
|
|
|
|
$ hledger -f- print --cost
|
|
2000-01-01
|
|
(a) 5 B
|
|
|
|
2000-02-01
|
|
(a) 6 B
|
|
|
|
2000-03-01
|
|
(a) 7 B
|
|
|
|
Show the value as of the last day of the report period (2000-02-29):
|
|
|
|
$ hledger -f- print --value=end date:2000/01-2000/03
|
|
2000-01-01
|
|
(a) 2 B
|
|
|
|
2000-02-01
|
|
(a) 2 B
|
|
|
|
With no report period specified, that shows the value as of the last
|
|
day of the journal (2000-03-01):
|
|
|
|
$ hledger -f- print --value=end
|
|
2000-01-01
|
|
(a) 3 B
|
|
|
|
2000-02-01
|
|
(a) 3 B
|
|
|
|
2000-03-01
|
|
(a) 3 B
|
|
|
|
Show the current value (the 2000-04-01 price is still in effect today):
|
|
|
|
$ hledger -f- print --value=now
|
|
2000-01-01
|
|
(a) 4 B
|
|
|
|
2000-02-01
|
|
(a) 4 B
|
|
|
|
2000-03-01
|
|
(a) 4 B
|
|
|
|
Show the value on 2000/01/15:
|
|
|
|
$ 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
|
|
|
|
You may need to explicitly set a commodity's display style, when
|
|
reverse prices are used. Eg this output might be surprising:
|
|
|
|
P 2000-01-01 A 2B
|
|
|
|
2000-01-01
|
|
a 1B
|
|
b
|
|
|
|
$ hledger print -x -X A
|
|
2000-01-01
|
|
a 0
|
|
b 0
|
|
|
|
Explanation: because there's no amount or commodity directive specify-
|
|
ing a display style for A, 0.5A gets the default style, which shows no
|
|
decimal digits. Because the displayed amount looks like zero, the com-
|
|
modity symbol and minus sign are not displayed either. Adding a com-
|
|
modity directive sets a more useful display style for A:
|
|
|
|
P 2000-01-01 A 2B
|
|
commodity 0.00A
|
|
|
|
2000-01-01
|
|
a 1B
|
|
b
|
|
|
|
$ hledger print -X A
|
|
2000-01-01
|
|
a 0.50A
|
|
b -0.50A
|
|
|
|
Interaction of valuation and queries
|
|
When matching postings based on queries in the presence of valuation,
|
|
the following happens.
|
|
|
|
1. The query is separated into two parts:
|
|
|
|
1. the currency (cur:) or amount (amt:).
|
|
|
|
2. all other parts.
|
|
|
|
2. The postings are matched to the currency and amount queries based on
|
|
pre-valued amounts.
|
|
|
|
3. Valuation is applied to the postings.
|
|
|
|
4. The postings are matched to the other parts of the query based on
|
|
post-valued amounts.
|
|
|
|
See: 1625
|
|
|
|
Effect of valuation on reports
|
|
Here is a reference for how valuation is supposed to affect each part
|
|
of hledger's reports (and a glossary). (It's wide, you'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.
|
|
|
|
|
|
Report -B, --cost -V, -X --value=then --value=end --value=DATE,
|
|
type --value=now
|
|
-----------------------------------------------------------------------------------------------
|
|
print
|
|
posting cost value at value at posting value at value at
|
|
amounts report end date report or DATE/today
|
|
or today journal end
|
|
balance unchanged unchanged unchanged unchanged unchanged
|
|
asser-
|
|
tions/assign-
|
|
ments
|
|
|
|
register
|
|
starting bal- cost value at valued at day value at value at
|
|
ance (-H) report or each historical report or DATE/today
|
|
journal end posting was made journal end
|
|
starting bal- cost value at day valued at day value at day value at
|
|
ance (-H) before each historical before DATE/today
|
|
with report report or posting was made report or
|
|
interval journal journal
|
|
start start
|
|
posting cost value at value at posting value at value at
|
|
amounts report or date report or DATE/today
|
|
journal end journal end
|
|
summary post- summarised value at sum of postings value at value at
|
|
ing amounts cost period ends in interval, val- period ends DATE/today
|
|
with report ued at interval
|
|
interval start
|
|
running sum/average sum/average sum/average of sum/average sum/average
|
|
total/average of displayed of displayed displayed values of displayed of displayed
|
|
values values values values
|
|
|
|
balance (bs,
|
|
bse, cf, is)
|
|
balance sums of value at value at posting value at value at
|
|
changes costs report end date report or DATE/today of
|
|
or today of journal end sums of post-
|
|
sums of of sums of ings
|
|
postings postings
|
|
budget like balance like balance like balance like bal- like balance
|
|
amounts changes changes changes ances changes
|
|
(--budget)
|
|
grand total sum of dis- sum of dis- sum of displayed sum of dis- sum of dis-
|
|
played val- played val- valued played val- played values
|
|
ues ues ues
|
|
|
|
balance (bs,
|
|
bse, cf, is)
|
|
with report
|
|
interval
|
|
starting bal- sums of value at sums of values of value at sums of post-
|
|
ances (-H) costs of report start postings before report start ings before
|
|
postings of sums of report start at of sums of report start
|
|
before all postings respective post- all postings
|
|
report start before ing dates before
|
|
report start report start
|
|
balance sums of same as sums of values of balance value at
|
|
changes (bal, costs of --value=end postings in change in DATE/today of
|
|
is, bs postings in period at respec- each period, sums of post-
|
|
--change, cf period tive posting valued at ings
|
|
--change) dates period ends
|
|
|
|
|
|
|
|
|
|
end balances sums of same as sums of values of period end value at
|
|
(bal -H, is costs of --value=end postings from balances, DATE/today of
|
|
--H, bs, cf) postings before period valued at sums of post-
|
|
from before start to period period ends ings
|
|
report start end at respective
|
|
to period posting dates
|
|
end
|
|
budget like balance like balance like balance like bal- like balance
|
|
amounts changes/end changes/end changes/end bal- ances changes/end
|
|
(--budget) balances balances ances balances
|
|
row totals, sums, aver- sums, aver- sums, averages of sums, aver- sums, aver-
|
|
row averages ages of dis- ages of dis- displayed values ages of dis- ages of dis-
|
|
(-T, -A) played val- played val- played val- played values
|
|
ues ues ues
|
|
column totals sums of dis- sums of dis- sums of displayed sums of dis- sums of dis-
|
|
played val- played val- values played val- played values
|
|
ues ues ues
|
|
grand total, sum, average sum, average sum, average of sum, average sum, average
|
|
grand average of column of column column totals of column of column
|
|
totals totals totals totals
|
|
|
|
|
|
--cumulative is omitted to save space, it works like -H but with a zero
|
|
starting balance.
|
|
|
|
Glossary:
|
|
|
|
cost calculated using price(s) recorded in the transaction(s).
|
|
|
|
value market value using available market price declarations, or the
|
|
unchanged amount if no conversion rate can be found.
|
|
|
|
report start
|
|
the first day of the report period specified with -b or -p or
|
|
date:, otherwise today.
|
|
|
|
report or journal start
|
|
the first day of the report period specified with -b or -p or
|
|
date:, otherwise the earliest transaction date in the journal,
|
|
otherwise today.
|
|
|
|
report end
|
|
the last day of the report period specified with -e or -p or
|
|
date:, otherwise today.
|
|
|
|
report or journal end
|
|
the last day of the report period specified with -e or -p or
|
|
date:, otherwise the latest transaction date in the journal,
|
|
otherwise today.
|
|
|
|
report interval
|
|
a flag (-D/-W/-M/-Q/-Y) or period expression that activates the
|
|
report's multi-period mode (whether showing one or many subperi-
|
|
ods).
|
|
|
|
PART 4: COMMANDS
|
|
Commands overview
|
|
Here are the built-in commands:
|
|
|
|
DATA ENTRY
|
|
These data entry commands are the only ones which can modify your jour-
|
|
nal file.
|
|
|
|
o add - add transactions using terminal prompts
|
|
|
|
o import - add new transactions from other files, eg CSV files
|
|
|
|
DATA CREATION
|
|
o close - generate balance-zeroing/restoring transactions
|
|
|
|
o rewrite - generate auto postings, like print --auto
|
|
|
|
DATA MANAGEMENT
|
|
o check - check for various kinds of error in the data
|
|
|
|
o diff - compare account transactions in two journal files
|
|
|
|
REPORTS, FINANCIAL
|
|
o aregister (areg) - show transactions in a particular account
|
|
|
|
o balancesheet (bs) - show assets, liabilities and net worth
|
|
|
|
o balancesheetequity (bse) - show assets, liabilities and equity
|
|
|
|
o cashflow (cf) - show changes in liquid assets
|
|
|
|
o incomestatement (is) - show revenues and expenses
|
|
|
|
REPORTS, VERSATILE
|
|
o balance (bal) - show balance changes, end balances, budgets, gains..
|
|
|
|
o print - show transactions or export journal data
|
|
|
|
o register (reg) - show postings in one or more accounts & running
|
|
total
|
|
|
|
o roi - show return on investments
|
|
|
|
REPORTS, BASIC
|
|
o accounts - show account names
|
|
|
|
o activity - show bar charts of posting counts per period
|
|
|
|
o codes - show transaction codes
|
|
|
|
o commodities - show commodity/currency symbols
|
|
|
|
o descriptions - show transaction descriptions
|
|
|
|
o files - show input file paths
|
|
|
|
o notes - show note parts of transaction descriptions
|
|
|
|
o payees - show payee parts of transaction descriptions
|
|
|
|
o prices - show market prices
|
|
|
|
o stats - show journal statistics
|
|
|
|
o tags - show tag names
|
|
|
|
o test - run self tests
|
|
|
|
HELP
|
|
o help - show the hledger manual with info/man/pager
|
|
|
|
o demo - show small hledger demos in the terminal
|
|
|
|
|
|
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's commands list:
|
|
|
|
o ui - run hledger's terminal UI
|
|
|
|
o web - run hledger's web UI
|
|
|
|
o iadd - add transactions using a TUI (currently hard to build)
|
|
|
|
o interest - generate interest transactions
|
|
|
|
o stockquotes - download market prices from AlphaVantage
|
|
|
|
o Scripts and add-ons - check-fancyassertions, edit, fifo, git, move,
|
|
pijul, plot, and more..
|
|
|
|
Next, each command is described in detail, in alphabetical order.
|
|
|
|
accounts
|
|
Show account names.
|
|
|
|
This command lists account names. By default it shows all known
|
|
accounts, either used in transactions or declared with account direc-
|
|
tives.
|
|
|
|
With query arguments, only matched account names and account names ref-
|
|
erenced by matched postings are shown.
|
|
|
|
Or it can show just the used accounts (--used/-u), the declared
|
|
accounts (--declared/-d), the accounts declared but not used
|
|
(--unused), the accounts used but not declared (--undeclared), or the
|
|
first account matched by an account name pattern, if any (--find).
|
|
|
|
It shows a flat list by default. With --tree, it uses indentation to
|
|
show the account hierarchy. In flat mode you can add --drop N to omit
|
|
the first few account name components. Account names can be depth-
|
|
clipped with depth:N or --depth N or -N.
|
|
|
|
With --types, it also shows each account's type, if it's known. (See
|
|
Declaring accounts > Account types.)
|
|
|
|
With --positions, it also shows the file and line number of each
|
|
account's declaration, if any, and the account's overall declaration
|
|
order; these may be useful when troubleshooting account display order.
|
|
|
|
With --directives, it adds the account keyword, showing valid account
|
|
directives which can be pasted into a journal file. This is useful
|
|
together with --undeclared when updating your account declarations to
|
|
satisfy hledger check accounts.
|
|
|
|
The --find flag can be used to look up a single account name, in the
|
|
same way that the aregister command does. It returns the alphanumeri-
|
|
cally-first matched account name, or if none can be found, it fails
|
|
with a non-zero exit code.
|
|
|
|
Examples:
|
|
|
|
$ hledger accounts
|
|
assets:bank:checking
|
|
assets:bank:saving
|
|
assets:cash
|
|
expenses:food
|
|
expenses:supplies
|
|
income:gifts
|
|
income:salary
|
|
liabilities:debts
|
|
|
|
$ hledger accounts --undeclared --directives >> $LEDGER_FILE
|
|
$ hledger check accounts
|
|
|
|
activity
|
|
Show an ascii barchart of posting counts per interval.
|
|
|
|
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.
|
|
|
|
Examples:
|
|
|
|
$ hledger activity --quarterly
|
|
2008-01-01 **
|
|
2008-04-01 *******
|
|
2008-07-01
|
|
2008-10-01 **
|
|
|
|
add
|
|
Prompt for transactions and add them to the journal. Any arguments
|
|
will be used as default inputs for the first N prompts.
|
|
|
|
Many hledger users edit their journals directly with a text editor, or
|
|
generate them from CSV. For more interactive data entry, there is the
|
|
add command, which prompts interactively on the console for new trans-
|
|
actions, 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
|
|
import).
|
|
|
|
To use it, just run hledger add and follow the prompts. You can add as
|
|
many transactions as you like; when you are finished, enter . or press
|
|
control-d or control-c to exit.
|
|
|
|
Features:
|
|
|
|
o add tries to provide useful defaults, using the most similar (by
|
|
description) recent transaction (filtered by the query, if any) as a
|
|
template.
|
|
|
|
o You can also set the initial defaults with command line arguments.
|
|
|
|
o Readline-style edit keys can be used during data entry.
|
|
|
|
o The tab key will auto-complete whenever possible - accounts, pay-
|
|
ees/descriptions, dates (yesterday, today, tomorrow). If the input
|
|
area is empty, it will insert the default value.
|
|
|
|
o If the journal defines a default commodity, it will be added to any
|
|
bare numbers entered.
|
|
|
|
o A parenthesised transaction code may be entered following a date.
|
|
|
|
o Comments and tags may be entered following a description or amount.
|
|
|
|
o If you make a mistake, enter < at any prompt to go one step backward.
|
|
|
|
o Input prompts are displayed in a different colour when the terminal
|
|
supports it.
|
|
|
|
Example (see https://hledger.org/add.html for a detailed tutorial):
|
|
|
|
$ 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> $
|
|
|
|
On Microsoft Windows, the add command makes sure that no part of the
|
|
file path ends with a period, as that would cause problems (#1056).
|
|
|
|
aregister
|
|
(areg)
|
|
|
|
Show the transactions and running historical balance of a single
|
|
account, with each transaction displayed as one line.
|
|
|
|
aregister 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 (--historical mode is always on).
|
|
|
|
This is a more "real world", bank-like view than the register command
|
|
(which shows individual postings, possibly from multiple accounts, not
|
|
necessarily in historical mode). As a quick rule of thumb: - use areg-
|
|
ister for reviewing and reconciling real-world asset/liability accounts
|
|
- use register for reviewing detailed revenues/expenses.
|
|
|
|
aregister 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.
|
|
|
|
When there are multiple matches, the alphabetically-first choice can be
|
|
surprising; eg if you have assets:per:checking 1 and assets:biz:check-
|
|
ing 2 accounts, hledger areg checking would select assets:biz:checking
|
|
2. It's just a convenience to save typing, so if in doubt, write the
|
|
full account name, or a distinctive substring that matches uniquely.
|
|
|
|
Transactions involving subaccounts of this account will also be shown.
|
|
aregister ignores depth limits, so its final total will always match a
|
|
balance report with similar arguments.
|
|
|
|
Any additional arguments form a query which will filter the transac-
|
|
tions shown. Note some queries will disturb the running balance, caus-
|
|
ing it to be different from the account's real-world running balance.
|
|
|
|
An example: this shows the transactions and historical running balance
|
|
during july, in the first account whose name contains "checking":
|
|
|
|
$ hledger areg checking date:jul
|
|
|
|
Each aregister line item shows:
|
|
|
|
o the transaction's date (or the relevant posting's date if different,
|
|
see below)
|
|
|
|
o the names of all the other account(s) involved in this transaction
|
|
(probably abbreviated)
|
|
|
|
o the total change to this account's balance from this transaction
|
|
|
|
o the account's historical running balance after this transaction.
|
|
|
|
Transactions making a net change of zero are not shown by default; add
|
|
the -E/--empty flag to show them.
|
|
|
|
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
|
|
--align-all flag.
|
|
|
|
This command also supports the output destination and output format
|
|
options. The output formats supported are txt, csv, and json.
|
|
|
|
aregister and custom posting dates
|
|
Transactions whose date is outside the report period can still be
|
|
shown, if they have a posting to this account dated inside the report
|
|
period. (And in this case it's the posting date that is shown.) This
|
|
ensures that aregister can show an accurate historical running balance,
|
|
matching the one shown by register -H with the same arguments.
|
|
|
|
To filter strictly by transaction date instead, add the --txn-dates
|
|
flag. If you use this flag and some of your postings have custom
|
|
dates, it's probably best to assume the running balance is wrong.
|
|
|
|
balance
|
|
(bal)
|
|
|
|
Show accounts and their balances.
|
|
|
|
balance is one of hledger'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.
|
|
|
|
Note there are some higher-level variants of the balance command with
|
|
convenient defaults, which can be simpler to use: balancesheet, bal-
|
|
ancesheetequity, cashflow and incomestatement. When you need more con-
|
|
trol, then use balance.
|
|
|
|
balance features
|
|
Here's a quick overview of the balance command's features, followed by
|
|
more detailed descriptions and examples. Many of these work with the
|
|
higher-level commands as well.
|
|
|
|
balance can show..
|
|
|
|
o accounts as a list (-l) or a tree (-t)
|
|
|
|
o optionally depth-limited (-[1-9])
|
|
|
|
o sorted by declaration order and name, or by amount
|
|
|
|
..and their..
|
|
|
|
o balance changes (the default)
|
|
|
|
o or actual and planned balance changes (--budget)
|
|
|
|
o or value of balance changes (-V)
|
|
|
|
o or change of balance values (--valuechange)
|
|
|
|
o or unrealised capital gain/loss (--gain)
|
|
|
|
..in..
|
|
|
|
o one time period (the whole journal period by default)
|
|
|
|
o or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
|
|
|
|
..either..
|
|
|
|
o per period (the default)
|
|
|
|
o or accumulated since report start date (--cumulative)
|
|
|
|
o or accumulated since account creation (--historical/-H)
|
|
|
|
..possibly converted to..
|
|
|
|
o cost (--value=cost[,COMM]/--cost/-B)
|
|
|
|
o or market value, as of transaction dates (--value=then[,COMM])
|
|
|
|
o or at period ends (--value=end[,COMM])
|
|
|
|
o or now (--value=now)
|
|
|
|
o or at some other date (--value=YYYY-MM-DD)
|
|
|
|
..with..
|
|
|
|
o totals (-T), averages (-A), percentages (-%), inverted sign
|
|
(--invert)
|
|
|
|
o rows and columns swapped (--transpose)
|
|
|
|
o another field used as account name (--pivot)
|
|
|
|
o custom-formatted line items (single-period reports only) (--format)
|
|
|
|
o commodities displayed on the same line or multiple lines (--layout)
|
|
|
|
This command supports the output destination and output format options,
|
|
with output formats txt, csv, json, and (multi-period reports only:)
|
|
html. In txt output in a colour-supporting terminal, negative amounts
|
|
are shown in red.
|
|
|
|
The --related/-r flag shows the balance of the other postings in the
|
|
transactions of the postings which would normally be shown.
|
|
|
|
Simple balance report
|
|
With no arguments, balance 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. ("Simple" here
|
|
means just one column of numbers, covering a single period. You can
|
|
also have multi-period reports, described later.)
|
|
|
|
For real-world accounts, these numbers will normally be their end bal-
|
|
ance at the end of the journal period; more on this below.
|
|
|
|
Accounts are sorted by declaration order if any, and then alphabeti-
|
|
cally by account name. For instance (using examples/sample.journal):
|
|
|
|
$ 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
|
|
|
|
Accounts with a zero balance (and no non-zero subaccounts, in tree mode
|
|
- see below) are hidden by default. Use -E/--empty to show them
|
|
(revealing assets:bank:checking here):
|
|
|
|
$ 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
|
|
|
|
The total of the amounts displayed is shown as the last line, unless
|
|
-N/--no-total is used.
|
|
|
|
Balance report line format
|
|
For single-period balance reports displayed in the terminal (only), you
|
|
can use --format FMT to customise the format and content of each line.
|
|
Eg:
|
|
|
|
$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
|
|
assets $-1
|
|
bank:saving $1
|
|
cash $-2
|
|
expenses $2
|
|
food $1
|
|
supplies $1
|
|
income $-2
|
|
gifts $-1
|
|
salary $-1
|
|
liabilities:debts $1
|
|
---------------------------------
|
|
0
|
|
|
|
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:
|
|
|
|
%[MIN][.MAX](FIELDNAME)
|
|
|
|
o MIN pads with spaces to at least this width (optional)
|
|
|
|
o MAX truncates at this width (optional)
|
|
|
|
o FIELDNAME must be enclosed in parentheses, and can be one of:
|
|
|
|
o depth_spacer - a number of spaces equal to the account's depth, or
|
|
if MIN is specified, MIN * depth spaces.
|
|
|
|
o account - the account's name
|
|
|
|
o total - the account's balance/posted total, right justified
|
|
|
|
Also, FMT can begin with an optional prefix to control how multi-com-
|
|
modity amounts are rendered:
|
|
|
|
o %_ - render on multiple lines, bottom-aligned (the default)
|
|
|
|
o %^ - render on multiple lines, top-aligned
|
|
|
|
o %, - render on one line, comma-separated
|
|
|
|
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
|
|
effect, instead %(account) has indentation built in. Experimentation
|
|
may be needed to get pleasing results.
|
|
|
|
Some example formats:
|
|
|
|
o %(total) - the account's total
|
|
|
|
o %-20.20(account) - the account's name, left justified, padded to 20
|
|
characters and clipped at 20 characters
|
|
|
|
o %,%-50(account) %25(total) - account name padded to 50 characters,
|
|
total padded to 20 characters, with multiple commodities rendered on
|
|
one line
|
|
|
|
o %20(total) %2(depth_spacer)%-(account) - the default format for the
|
|
single-column balance report
|
|
|
|
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:
|
|
|
|
$ hledger -f examples/sample.journal bal --cleared assets date:200806
|
|
$-2 assets:cash
|
|
--------------------
|
|
$-2
|
|
|
|
List or tree mode
|
|
By default, or with -l/--flat, accounts are shown as a flat list with
|
|
their full names visible, as in the examples above.
|
|
|
|
With -t/--tree, the account hierarchy is shown, with subaccounts'
|
|
"leaf" names indented below their parent:
|
|
|
|
$ 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
|
|
|
|
Notes:
|
|
|
|
o "Boring" accounts are combined with their subaccount for more compact
|
|
output, unless --no-elide is used. Boring accounts have no balance
|
|
of their own and just one subaccount (eg assets:bank and liabilities
|
|
above).
|
|
|
|
o All balances shown are "inclusive", ie including the balances from
|
|
all subaccounts. Note this means some repetition in the output,
|
|
which requires explanation when sharing reports with non-plaintextac-
|
|
counting-users. A tree mode report's final total is the sum of the
|
|
top-level balances shown, not of all the balances shown.
|
|
|
|
o Each group of sibling accounts (ie, under a common parent) is sorted
|
|
separately.
|
|
|
|
Depth limiting
|
|
With a depth:NUM query, or --depth NUM option, or just -NUM (eg: -3)
|
|
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.
|
|
|
|
Account balances at the depth limit always include the balances from
|
|
any deeper subaccounts (even in list mode). Eg, limiting to depth 1:
|
|
|
|
$ hledger -f examples/sample.journal balance -1
|
|
$-1 assets
|
|
$2 expenses
|
|
$-2 income
|
|
$1 liabilities
|
|
--------------------
|
|
0
|
|
|
|
Dropping top-level accounts
|
|
You can also hide one or more top-level account name parts, using
|
|
--drop NUM. This can be useful for hiding repetitive top-level account
|
|
names:
|
|
|
|
$ hledger -f examples/sample.journal bal expenses --drop 1
|
|
$1 food
|
|
$1 supplies
|
|
--------------------
|
|
$2
|
|
|
|
|
|
Showing declared accounts
|
|
With --declared, 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
|
|
-E/--empty to see them.)
|
|
|
|
More precisely, leaf declared accounts (with no subaccounts) will be
|
|
included, since those are usually the more useful in reports.
|
|
|
|
The idea of this is to be able to see a useful "complete" balance
|
|
report, even when you don't have transactions in all of your declared
|
|
accounts yet.
|
|
|
|
Sorting by amount
|
|
With -S/--sort-amount, accounts with the largest (most positive) bal-
|
|
ances are shown first. Eg: hledger bal expenses -MAS shows your big-
|
|
gest 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).
|
|
|
|
Revenues and liability balances are typically negative, however, so -S
|
|
shows these in reverse order. To work around this, you can add
|
|
--invert to flip the signs. (Or, use one of the higher-level reports,
|
|
which flip the sign automatically. Eg: hledger incomestatement -MAS).
|
|
|
|
|
|
Percentages
|
|
With -%/--percent, balance reports show each account's value expressed
|
|
as a percentage of the (column) total.
|
|
|
|
Note it is not useful to calculate percentages if the amounts in a col-
|
|
umn have mixed signs. In this case, make a separate report for each
|
|
sign, eg:
|
|
|
|
$ hledger bal -% amt:`>0`
|
|
$ hledger bal -% amt:`<0`
|
|
|
|
Similarly, if the amounts in a column have mixed commodities, convert
|
|
them to one commodity with -B, -V, -X or --value, or make a separate
|
|
report for each commodity:
|
|
|
|
$ hledger bal -% cur:\\$
|
|
$ hledger bal -% cur:EUR
|
|
|
|
Multi-period balance report
|
|
With a report interval (set by the -D/--daily, -W/--weekly,
|
|
-M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), bal-
|
|
ance shows a tabular report, with columns representing successive time
|
|
periods (and a title):
|
|
|
|
$ 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
|
|
|
|
Notes:
|
|
|
|
o The report's start/end dates will be expanded, if necessary, to fully
|
|
encompass the displayed subperiods (so that the first and last subpe-
|
|
riods have the same duration as the others).
|
|
|
|
o Leading and trailing periods (columns) containing all zeroes are not
|
|
shown, unless -E/--empty is used.
|
|
|
|
o Accounts (rows) containing all zeroes are not shown, unless
|
|
-E/--empty is used.
|
|
|
|
o Amounts with many commodities are shown in abbreviated form, unless
|
|
--no-elide is used. (experimental)
|
|
|
|
o Average and/or total columns can be added with the -A/--average and
|
|
-T/--row-total flags.
|
|
|
|
o The --transpose flag can be used to exchange rows and columns.
|
|
|
|
o The --pivot FIELD option causes a different transaction field to be
|
|
used as "account name". See PIVOTING.
|
|
|
|
Multi-period reports with many periods can be too wide for easy viewing
|
|
in the terminal. Here are some ways to handle that:
|
|
|
|
o Hide the totals row with -N/--no-total
|
|
|
|
o Convert to a single currency with -V
|
|
|
|
o Maximize the terminal window
|
|
|
|
o Reduce the terminal's font size
|
|
|
|
o View with a pager like less, eg: hledger bal -D --color=yes | less
|
|
-RS
|
|
|
|
o Output as CSV and use a CSV viewer like visidata (hledger bal -D -O
|
|
csv | vd -f csv), Emacs' csv-mode (M-x csv-mode, C-c C-a), or a
|
|
spreadsheet (hledger bal -D -o a.csv && open a.csv)
|
|
|
|
o Output as HTML and view with a browser: hledger bal -D -o a.html &&
|
|
open a.html
|
|
|
|
Balance change, end balance
|
|
It's important to be clear on the meaning of the numbers shown in bal-
|
|
ance reports. Here is some terminology we use:
|
|
|
|
A balance change is the net amount added to, or removed from, an
|
|
account during some period.
|
|
|
|
An end balance is the amount accumulated in an account as of some date
|
|
(and some time, but hledger doesn't store that; assume end of day in
|
|
your timezone). It is the sum of previous balance changes.
|
|
|
|
We call it a historical end balance if it includes all balance changes
|
|
since the account was created. For a real world account, this means it
|
|
will match the "historical record", eg the balances reported in your
|
|
bank statements or bank web UI. (If they are correct!)
|
|
|
|
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.
|
|
|
|
balance shows balance changes by default. To see accurate historical
|
|
end balances:
|
|
|
|
1. Initialise account starting balances with an "opening balances"
|
|
transaction (a transfer from equity to the account), unless the
|
|
journal covers the account's full lifetime.
|
|
|
|
2. Include all of of the account's prior postings in the report, by not
|
|
specifying a report start date, or by using the -H/--historical
|
|
flag. (-H causes report start date to be ignored when summing post-
|
|
ings.)
|
|
|
|
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't
|
|
worry - this is for advanced reporting, and it does typically take some
|
|
time and experimentation to get clear on all these report modes.
|
|
|
|
There are three important option groups:
|
|
|
|
hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]
|
|
...
|
|
|
|
Calculation type
|
|
The basic calculation to perform for each table cell. It is one of:
|
|
|
|
o --sum : sum the posting amounts (default)
|
|
|
|
o --budget : sum the amounts, but also show the budget goal amount (for
|
|
each account/period)
|
|
|
|
o --valuechange : show the change in period-end historical balance val-
|
|
ues (caused by deposits, withdrawals, and/or market price fluctua-
|
|
tions)
|
|
|
|
o --gain : show the unrealised capital gain/loss, (the current valued
|
|
balance minus each amount's original cost)
|
|
|
|
Accumulation type
|
|
How amounts should accumulate across report periods. Another way to
|
|
say it: which time period's postings should contribute to each cell's
|
|
calculation. It is one of:
|
|
|
|
o --change : calculate with postings from column start to column end,
|
|
ie "just this column". Typically used to see revenues/expenses.
|
|
(default for balance, incomestatement)
|
|
|
|
o --cumulative : calculate with postings from report start to column
|
|
end, ie "previous columns plus this column". Typically used to show
|
|
changes accumulated since the report's start date. Not often used.
|
|
|
|
o --historical/-H : calculate with postings from journal start to col-
|
|
umn end, ie "all postings from before report start date until this
|
|
column's end". Typically used to see historical end balances of
|
|
assets/liabilities/equity. (default for balancesheet, balancesheete-
|
|
quity, cashflow)
|
|
|
|
Valuation type
|
|
Which kind of value or cost conversion should be applied, if any,
|
|
before displaying the report. It is one of:
|
|
|
|
o no valuation type : don't convert to cost or value (default)
|
|
|
|
o --value=cost[,COMM] : convert amounts to cost (then optionally to
|
|
some other commodity)
|
|
|
|
o --value=then[,COMM] : convert amounts to market value on transaction
|
|
dates
|
|
|
|
o --value=end[,COMM] : convert amounts to market value on period end
|
|
date(s)
|
|
(default with --valuechange, --gain)
|
|
|
|
o --value=now[,COMM] : convert amounts to market value on today's date
|
|
|
|
o --value=YYYY-MM-DD[,COMM] : convert amounts to market value on
|
|
another date
|
|
|
|
or one of the equivalent simpler flags:
|
|
|
|
o -B/--cost : like --value=cost (though, note --cost and --value are
|
|
independent options which can both be used at once)
|
|
|
|
o -V/--market : like --value=end
|
|
|
|
o -X COMM/--exchange COMM : like --value=end,COMM
|
|
|
|
See Cost reporting and Valuation for more about these.
|
|
|
|
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:
|
|
|
|
o --valuechange implies --value=end
|
|
|
|
o --valuechange makes --change the default when used with the bal-
|
|
ancesheet/balancesheetequity commands
|
|
|
|
o --cumulative or --historical disables --row-total/-T
|
|
|
|
For reference, here is what the combinations of accumulation and valua-
|
|
tion show:
|
|
|
|
|
|
Valua- no valuation --value= then --value= end --value= YYYY-
|
|
tion:> MM-DD /now
|
|
Accumu-
|
|
lation:v
|
|
-----------------------------------------------------------------------------------
|
|
--change change in period sum of posting- period-end DATE-value of
|
|
date market val- value of change change in
|
|
ues in period in period period
|
|
--cumu- change from sum of posting- period-end DATE-value of
|
|
lative report start to date market val- value of change change from
|
|
period end ues from report from report report start
|
|
start to period start to period to period end
|
|
end end
|
|
--his- change from sum of posting- period-end DATE-value of
|
|
torical journal start to date market val- value of change change from
|
|
/-H period end (his- ues from journal from journal journal start
|
|
torical end bal- start to period start to period to period end
|
|
ance) end end
|
|
|
|
Budget report
|
|
The --budget report type activates extra columns showing any budget
|
|
goals for each account and period. The budget goals are defined by
|
|
periodic transactions. This is useful for comparing planned and actual
|
|
income, expenses, time usage, etc.
|
|
|
|
For example, you can take average monthly expenses in the common
|
|
expense categories to construct a minimal monthly budget:
|
|
|
|
;; Budget
|
|
~ monthly
|
|
income $2000
|
|
expenses:food $400
|
|
expenses:bus $50
|
|
expenses:movies $30
|
|
assets:bank:checking
|
|
|
|
;; Two months worth of expenses
|
|
2017-11-01
|
|
income $1950
|
|
expenses:food $396
|
|
expenses:bus $49
|
|
expenses:movies $30
|
|
expenses:supplies $20
|
|
assets:bank:checking
|
|
|
|
2017-12-01
|
|
income $2100
|
|
expenses:food $412
|
|
expenses:bus $53
|
|
expenses:gifts $100
|
|
assets:bank:checking
|
|
|
|
You can now see a monthly budget report:
|
|
|
|
$ hledger balance -M --budget
|
|
Budget performance in 2017/11/01-2017/12/31:
|
|
|
|
|| Nov Dec
|
|
======================++====================================================
|
|
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
|
|
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
|
|
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
|
|
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
|
|
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
|
|
----------------------++----------------------------------------------------
|
|
|| 0 [ 0] 0 [ 0]
|
|
|
|
This is different from a normal balance report in several ways:
|
|
|
|
o Only accounts with budget goals during the report period are shown,
|
|
by default.
|
|
|
|
o In each column, in square brackets after the actual amount, budget
|
|
goal amounts are shown, and the actual/goal percentage. (Note: bud-
|
|
get goals should be in the same commodity as the actual amount.)
|
|
|
|
o All parent accounts are always shown, even in list mode. Eg assets,
|
|
assets:bank, and expenses above.
|
|
|
|
o Amounts always include all subaccounts, budgeted or unbudgeted, even
|
|
in list mode.
|
|
|
|
This means that the numbers displayed will not always add up! Eg
|
|
above, the expenses actual amount includes the gifts and supplies
|
|
transactions, but the expenses:gifts and expenses:supplies accounts are
|
|
not shown, as they have no budget amounts declared.
|
|
|
|
This can be confusing. When you need to make things clearer, use the
|
|
-E/--empty flag, which will reveal all accounts including unbudgeted
|
|
ones, giving the full picture. Eg:
|
|
|
|
$ hledger balance -M --budget --empty
|
|
Budget performance in 2017/11/01-2017/12/31:
|
|
|
|
|| Nov Dec
|
|
======================++====================================================
|
|
assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
|
|
expenses || $495 [ 103% of $480] $565 [ 118% of $480]
|
|
expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
|
|
expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
|
|
expenses:gifts || 0 $100
|
|
expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
|
|
expenses:supplies || $20 0
|
|
income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
|
|
----------------------++----------------------------------------------------
|
|
|| 0 [ 0] 0 [ 0]
|
|
|
|
You can roll over unspent budgets to next period with --cumulative:
|
|
|
|
$ hledger balance -M --budget --cumulative
|
|
Budget performance in 2017/11/01-2017/12/31:
|
|
|
|
|| Nov Dec
|
|
======================++====================================================
|
|
assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
|
|
assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
|
|
assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
|
|
expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
|
|
expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
|
|
expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
|
|
expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
|
|
income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
|
|
----------------------++----------------------------------------------------
|
|
|| 0 [ 0] 0 [ 0]
|
|
|
|
It's common to limit budgets/budget reports to just expenses
|
|
|
|
hledger bal -M --budget expenses
|
|
|
|
or just revenues and expenses (eg, using account types):
|
|
|
|
hledger bal -M --budget type:rx
|
|
|
|
It's also common to limit or convert them to a single currency
|
|
(cur:COMM or -X COMM [--infer-market-prices]). If showing multiple
|
|
currencies, --layout bare or --layout tall can help.
|
|
|
|
For more examples and notes, see Budgeting.
|
|
|
|
Budget report start date
|
|
This might be a bug, but for now: when making budget reports, it's a
|
|
good idea to explicitly set the report's start date to the first day of
|
|
a reporting period, because a periodic rule like ~ monthly generates
|
|
its transactions on the 1st of each month, and if your journal has no
|
|
regular transactions on the 1st, the default report start date could
|
|
exclude that budget goal, which can be a little surprising. Eg here
|
|
the default report period is just the day of 2020-01-15:
|
|
|
|
~ monthly in 2020
|
|
(expenses:food) $500
|
|
|
|
2020-01-15
|
|
expenses:food $400
|
|
assets:checking
|
|
|
|
$ hledger bal expenses --budget
|
|
Budget performance in 2020-01-15:
|
|
|
|
|| 2020-01-15
|
|
==============++============
|
|
<unbudgeted> || $400
|
|
--------------++------------
|
|
|| $400
|
|
|
|
To avoid this, specify the budget report's period, or at least the
|
|
start date, with -b/-e/-p/date:, to ensure it includes the budget goal
|
|
transactions (periodic transactions) that you want. Eg, adding -b
|
|
2020/1/1 to the above:
|
|
|
|
$ hledger bal expenses --budget -b 2020/1/1
|
|
Budget performance in 2020-01-01..2020-01-15:
|
|
|
|
|| 2020-01-01..2020-01-15
|
|
===============++========================
|
|
expenses:food || $400 [80% of $500]
|
|
---------------++------------------------
|
|
|| $400 [80% of $500]
|
|
|
|
Budgets and subaccounts
|
|
You can add budgets to any account in your account hierarchy. If you
|
|
have budgets on both parent account and some of its children, then bud-
|
|
get(s) of the child account(s) would be added to the budget of their
|
|
parent, much like account balances behave.
|
|
|
|
In the most simple case this means that once you add a budget to any
|
|
account, all its parents would have budget as well.
|
|
|
|
To illustrate this, consider the following budget:
|
|
|
|
~ monthly from 2019/01
|
|
expenses:personal $1,000.00
|
|
expenses:personal:electronics $100.00
|
|
liabilities
|
|
|
|
With this, monthly budget for electronics is defined to be $100 and
|
|
budget for personal expenses is an additional $1000, which implicitly
|
|
means that budget for both expenses:personal and expenses is $1100.
|
|
|
|
Transactions in expenses:personal:electronics will be counted both
|
|
towards its $100 budget and $1100 of expenses:personal , and transac-
|
|
tions in any other subaccount of expenses:personal would be counted
|
|
towards only towards the budget of expenses:personal.
|
|
|
|
For example, let's consider these transactions:
|
|
|
|
~ monthly from 2019/01
|
|
expenses:personal $1,000.00
|
|
expenses:personal:electronics $100.00
|
|
liabilities
|
|
|
|
2019/01/01 Google home hub
|
|
expenses:personal:electronics $90.00
|
|
liabilities $-90.00
|
|
|
|
2019/01/02 Phone screen protector
|
|
expenses:personal:electronics:upgrades $10.00
|
|
liabilities
|
|
|
|
2019/01/02 Weekly train ticket
|
|
expenses:personal:train tickets $153.00
|
|
liabilities
|
|
|
|
2019/01/03 Flowers
|
|
expenses:personal $30.00
|
|
liabilities
|
|
|
|
As you can see, we have transactions in expenses:personal:electron-
|
|
ics:upgrades and expenses:personal:train tickets, and since both of
|
|
these accounts are without explicitly defined budget, these transac-
|
|
tions would be counted towards budgets of expenses:personal:electronics
|
|
and expenses:personal accordingly:
|
|
|
|
$ hledger balance --budget -M
|
|
Budget performance in 2019/01:
|
|
|
|
|| Jan
|
|
===============================++===============================
|
|
expenses || $283.00 [ 26% of $1100.00]
|
|
expenses:personal || $283.00 [ 26% of $1100.00]
|
|
expenses:personal:electronics || $100.00 [ 100% of $100.00]
|
|
liabilities || $-283.00 [ 26% of $-1100.00]
|
|
-------------------------------++-------------------------------
|
|
|| 0 [ 0]
|
|
|
|
And with --empty, we can get a better picture of budget allocation and
|
|
consumption:
|
|
|
|
$ hledger balance --budget -M --empty
|
|
Budget performance in 2019/01:
|
|
|
|
|| Jan
|
|
========================================++===============================
|
|
expenses || $283.00 [ 26% of $1100.00]
|
|
expenses:personal || $283.00 [ 26% of $1100.00]
|
|
expenses:personal:electronics || $100.00 [ 100% of $100.00]
|
|
expenses:personal:electronics:upgrades || $10.00
|
|
expenses:personal:train tickets || $153.00
|
|
liabilities || $-283.00 [ 26% of $-1100.00]
|
|
----------------------------------------++-------------------------------
|
|
|| 0 [ 0]
|
|
|
|
Selecting budget goals
|
|
The budget report evaluates periodic transaction rules to generate spe-
|
|
cial "goal transactions", which generate the goal amounts for each
|
|
account in each report subperiod. When troubleshooting, you can use
|
|
print --forecast to show these as forecasted transactions:
|
|
|
|
$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
|
|
|
|
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.
|
|
|
|
You can select a subset of periodic rules by providing an argument to
|
|
the --budget flag. --budget=DESCPAT 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), and then
|
|
select from multiple budgets defined in your journal.
|
|
|
|
Budget vs forecast
|
|
hledger --forecast ... and hledger balance --budget ... are separate
|
|
features, though both of them use the periodic transaction rules
|
|
defined in the journal, and both of them generate temporary transac-
|
|
tions for reporting purposes ("forecast transactions" and "budget goal
|
|
transactions", respectively). You can use both features at the same
|
|
time if you want. Here are some differences between them, as of
|
|
hledger 1.29:
|
|
|
|
CLI:
|
|
|
|
o --forecast is a general hledger option, usable with any command
|
|
|
|
o --budget is a balance command option, usable only with that command.
|
|
|
|
Visibility of generated transactions:
|
|
|
|
o forecast transactions are visible in any report, like ordinary trans-
|
|
actions
|
|
|
|
o budget goal transactions are invisible except for the goal amounts
|
|
they produce in --budget reports.
|
|
|
|
Periodic transaction rules:
|
|
|
|
o --forecast uses all available periodic transaction rules
|
|
|
|
o --budget uses all periodic rules (--budget) or a selected subset
|
|
(--budget=DESCPAT)
|
|
|
|
Period of generated transactions:
|
|
|
|
o --forecast generates forecast transactions
|
|
|
|
o from after the last regular transaction to the end of the report
|
|
period (--forecast)
|
|
|
|
o or, during a specified period (--forecast=PERIODEXPR)
|
|
|
|
o possibly further restricted by a period specified in the periodic
|
|
transaction rule
|
|
|
|
o and always restricted within the bounds of the report period
|
|
|
|
o --budget generates budget goal transactions
|
|
|
|
o throughout the report period
|
|
|
|
o possibly restricted by a period specified in the periodic transac-
|
|
tion rule.
|
|
|
|
Data layout
|
|
The --layout 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:
|
|
|
|
o --layout=wide[,WIDTH]: commodities are shown on a single line,
|
|
optionally elided to WIDTH
|
|
|
|
o --layout=tall: each commodity is shown on a separate line
|
|
|
|
o --layout=bare: commodity symbols are in their own column, amounts are
|
|
bare numbers
|
|
|
|
o --layout=tidy: data is normalised to easily-consumed "tidy" form,
|
|
with one row per data value
|
|
|
|
Here are the --layout modes supported by each output format; note only
|
|
CSV output supports all of them:
|
|
|
|
|
|
- txt csv html json sql
|
|
-------------------------------------
|
|
wide Y Y Y
|
|
tall Y Y Y
|
|
bare Y Y Y
|
|
tidy Y
|
|
|
|
Examples:
|
|
|
|
o Wide layout. With many commodities, reports can be very wide:
|
|
|
|
$ 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
|
|
|
|
o Limited wide layout. A width limit reduces the width, but some com-
|
|
modities will be hidden:
|
|
|
|
$ 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..
|
|
|
|
o Tall layout. Each commodity gets a new line (may be different in
|
|
each column), and account names are repeated:
|
|
|
|
$ 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
|
|
|
|
o Bare layout. Commodity symbols are kept in one column, each commod-
|
|
ity gets its own report row, account names are repeated:
|
|
|
|
$ 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
|
|
|
|
o Bare layout also affects CSV output, which is useful for producing
|
|
data that is easier to consume, eg for making charts:
|
|
|
|
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
|
|
"account","commodity","balance"
|
|
"Assets:US:ETrade","GLD","70.00"
|
|
"Assets:US:ETrade","ITOT","17.00"
|
|
"Assets:US:ETrade","USD","5120.50"
|
|
"Assets:US:ETrade","VEA","36.00"
|
|
"Assets:US:ETrade","VHT","294.00"
|
|
"total","GLD","70.00"
|
|
"total","ITOT","17.00"
|
|
"total","USD","5120.50"
|
|
"total","VEA","36.00"
|
|
"total","VHT","294.00"
|
|
|
|
o Tidy layout produces normalised "tidy data", 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 soft-
|
|
ware to consume. Here's how it looks:
|
|
|
|
$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
|
|
"account","period","start_date","end_date","commodity","value"
|
|
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"
|
|
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"
|
|
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"
|
|
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"
|
|
"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"
|
|
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"
|
|
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"
|
|
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"
|
|
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"
|
|
"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"
|
|
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"
|
|
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"
|
|
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"
|
|
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
|
|
"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
|
|
|
|
Useful balance reports
|
|
Some frequently used balance options/reports are:
|
|
|
|
o bal -M revenues expenses
|
|
Show revenues/expenses in each month. Also available as the incomes-
|
|
tatement command.
|
|
|
|
o bal -M -H assets liabilities
|
|
Show historical asset/liability balances at each month end. Also
|
|
available as the balancesheet command.
|
|
|
|
o bal -M -H assets liabilities equity
|
|
Show historical asset/liability/equity balances at each month end.
|
|
Also available as the balancesheetequity command.
|
|
|
|
o bal -M assets not:receivable
|
|
Show changes to liquid assets in each month. Also available as the
|
|
cashflow command.
|
|
|
|
Also:
|
|
|
|
o bal -M expenses -2 -SA
|
|
Show monthly expenses summarised to depth 2 and sorted by average
|
|
amount.
|
|
|
|
o bal -M --budget expenses
|
|
Show monthly expenses and budget goals.
|
|
|
|
o bal -M --valuechange investments
|
|
Show monthly change in market value of investment assets.
|
|
|
|
o bal investments --valuechange -D date:lastweek amt:'>1000' -STA
|
|
[--invert]
|
|
Show top gainers [or losers] last week
|
|
|
|
balancesheet
|
|
(bs)
|
|
|
|
This command displays a balance sheet, showing historical ending bal-
|
|
ances 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.
|
|
|
|
This report shows accounts declared with the Asset, Cash or Liability
|
|
type (see account types). Or if no such accounts are declared, it
|
|
shows top-level accounts named asset or liability (case insensitive,
|
|
plurals allowed) and their subaccounts.
|
|
|
|
Example:
|
|
|
|
$ hledger balancesheet
|
|
Balance Sheet
|
|
|
|
Assets:
|
|
$-1 assets
|
|
$1 bank:saving
|
|
$-2 cash
|
|
--------------------
|
|
$-1
|
|
|
|
Liabilities:
|
|
$1 liabilities:debts
|
|
--------------------
|
|
$1
|
|
|
|
Total:
|
|
--------------------
|
|
0
|
|
|
|
This command is a higher-level variant of the balance command, and sup-
|
|
ports many of that command's features, such as multi-period reports.
|
|
It is similar to hledger balance -H assets liabilities, but with
|
|
smarter account detection, and liabilities displayed with their sign
|
|
flipped.
|
|
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are txt, csv, html, and (experi-
|
|
mental) json.
|
|
|
|
balancesheetequity
|
|
(bse)
|
|
|
|
This command displays a balance sheet, showing historical ending bal-
|
|
ances of asset, liability and equity accounts. Amounts are shown with
|
|
normal positive sign, as in conventional financial statements.
|
|
|
|
This report shows accounts declared with the Asset, Cash, Liability or
|
|
Equity type (see account types). Or if no such accounts are declared,
|
|
it shows top-level accounts named asset, liability or equity (case
|
|
insensitive, plurals allowed) and their subaccounts.
|
|
|
|
Example:
|
|
|
|
$ 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
|
|
|
|
This command is a higher-level variant of the balance command, and sup-
|
|
ports many of that command's features, such as multi-period reports.
|
|
It is similar to hledger balance -H assets liabilities equity, but with
|
|
smarter account detection, and liabilities/equity displayed with their
|
|
sign flipped.
|
|
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are txt, csv, html, and (experi-
|
|
mental) json.
|
|
|
|
cashflow
|
|
(cf)
|
|
|
|
This command displays a cashflow statement, showing the inflows and
|
|
outflows affecting "cash" (ie, liquid, easily convertible) assets.
|
|
Amounts are shown with normal positive sign, as in conventional finan-
|
|
cial statements.
|
|
|
|
This report shows accounts declared with the Cash type (see account
|
|
types). Or if no such accounts are declared, it shows accounts
|
|
|
|
o under a top-level account named asset (case insensitive, plural
|
|
allowed)
|
|
|
|
o whose name contains some variation of cash, bank, checking or saving.
|
|
|
|
More precisely: all accounts matching this case insensitive regular
|
|
expression:
|
|
|
|
^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)
|
|
|
|
and their subaccounts.
|
|
|
|
An example cashflow report:
|
|
|
|
$ hledger cashflow
|
|
Cashflow Statement
|
|
|
|
Cash flows:
|
|
$-1 assets
|
|
$1 bank:saving
|
|
$-2 cash
|
|
--------------------
|
|
$-1
|
|
|
|
Total:
|
|
--------------------
|
|
$-1
|
|
|
|
This command is a higher-level variant of the balance command, and sup-
|
|
ports many of that command's features, such as multi-period reports.
|
|
It is similar to hledger balance assets not:fixed not:investment
|
|
not:receivable, but with smarter account detection.
|
|
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are txt, csv, html, and (experi-
|
|
mental) json.
|
|
|
|
check
|
|
Check for various kinds of errors in your data.
|
|
|
|
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 check 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).
|
|
|
|
Some examples:
|
|
|
|
hledger check # basic checks
|
|
hledger check -s # basic + strict checks
|
|
hledger check ordereddates payees # basic + two other checks
|
|
|
|
If you are an Emacs user, you can also configure flycheck-hledger to
|
|
run these checks, providing instant feedback as you edit the journal.
|
|
|
|
Here are the checks currently available:
|
|
|
|
Basic checks
|
|
These checks are always run automatically, by (almost) all hledger com-
|
|
mands, including check:
|
|
|
|
o parseable - data files are well-formed and can be successfully parsed
|
|
|
|
o balancedwithautoconversion - all transactions are balanced, inferring
|
|
missing amounts where necessary, and possibly converting commodities
|
|
using costs or automatically-inferred costs
|
|
|
|
o assertions - all balance assertions in the journal are passing.
|
|
(This check can be disabled with -I/--ignore-assertions.)
|
|
|
|
Strict checks
|
|
These additional checks are run when the -s/--strict (strict mode) flag
|
|
is used. Or, they can be run by giving their names as arguments to
|
|
check:
|
|
|
|
o accounts - all account names used by transactions have been declared
|
|
|
|
o commodities - all commodity symbols used have been declared
|
|
|
|
o balancednoautoconversion - transactions are balanced, possibly using
|
|
explicit costs but not inferred ones
|
|
|
|
Other checks
|
|
These checks can be run only by giving their names as arguments to
|
|
check. They are more specialised and not desirable for everyone,
|
|
therefore optional:
|
|
|
|
o ordereddates - transactions are ordered by date within each file
|
|
|
|
o payees - all payees used by transactions have been declared
|
|
|
|
o recentassertions - all accounts with balance assertions have a bal-
|
|
ance assertion no more than 7 days before their latest posting
|
|
|
|
o tags - all tags used by transactions have been declared
|
|
|
|
o uniqueleafnames - all account leaf names are unique
|
|
|
|
Custom checks
|
|
A few more checks are are available as separate add-on commands, in
|
|
https://github.com/simonmichael/hledger/tree/master/bin:
|
|
|
|
o hledger-check-tagfiles - all tag values containing / (a forward
|
|
slash) exist as file paths
|
|
|
|
o hledger-check-fancyassertions - more complex balance assertions are
|
|
passing
|
|
|
|
You could make similar scripts to perform your own custom checks. See:
|
|
Cookbook -> Scripting.
|
|
|
|
More about specific checks
|
|
hledger check recentassertions will complain if any balance-asserted
|
|
account does not have a balance assertion within 7 days before its lat-
|
|
est posting. This aims to prevent the situation where you are regu-
|
|
larly 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, then use the man-
|
|
ual-review-and-mark-cleared phase as a reminder to check the latest
|
|
assertions against real-world balances.
|
|
|
|
close
|
|
close [--retain | --migrate | --open] [QUERY]
|
|
|
|
By default: prints a transaction that zeroes out ("closes") all
|
|
accounts, transferring their balances to an equity account. Query
|
|
arguments can be added to override the accounts selection. Three other
|
|
modes are supported:
|
|
|
|
--retain: prints a transaction closing revenue and expense balances.
|
|
This is traditionally done by businesses at the end of each accounting
|
|
period; it is less necessary in personal and computer-based accounting,
|
|
but it can help balance the accounting equation A=L+E.
|
|
|
|
--migrate: prints a transaction to close asset, liability and most
|
|
equity balances, and another transaction to re-open them. This can be
|
|
useful when starting a new file (for performance or data protection).
|
|
Adding the closing transaction to the old file allows old and new files
|
|
to be combined.
|
|
|
|
--open: as above, but prints just the opening transaction. This can be
|
|
useful for starting a new file, leaving the old file unchanged. Simi-
|
|
lar to Ledger's equity command.
|
|
|
|
You can change the equity account name with --close-acct ACCT. It
|
|
defaults to equity:retained earnings with --retain, or equity:open-
|
|
ing/closing balances otherwise.
|
|
|
|
You can change the transaction description(s) with --close-desc 'DESC'
|
|
and --open-desc 'DESC'. It defaults to retain earnings with --retain,
|
|
or closing balances and opening balances otherwise.
|
|
|
|
Just one posting to the equity account will be used by default, with an
|
|
implicit amount.
|
|
|
|
With --x/--explicit the amount will be shown explicitly, and if it
|
|
involves multiple commodities, a separate posting will be generated for
|
|
each commodity.
|
|
|
|
With --interleaved, each equity posting is shown next to the corre-
|
|
sponding source/destination posting.
|
|
|
|
The default closing date is yesterday, or the journal's end date,
|
|
whichever is later. You can change this by specifying a report end
|
|
date; (The report start date does not matter.) The last day of the
|
|
report period will be the closing date; eg -e 2022 means "close on
|
|
2022-12-31". The opening date is always the day after the closing
|
|
date.
|
|
|
|
close and costs
|
|
With --show-costs, any amount costs are shown, with separate postings
|
|
for each cost. (This currently the best way to view investment assets,
|
|
showing lots and cost bases.) If you have many currency conversion or
|
|
investment transactions, it can generate very large journal entries.
|
|
|
|
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).
|
|
|
|
These provide useful error checking, but you can ignore them temporar-
|
|
ily with -I, or remove them if you prefer.
|
|
|
|
You probably should avoid filtering transactions by status or realness
|
|
(-C, -R, status:), or generating postings (--auto), with this command,
|
|
since the balance assertions would depend on these.
|
|
|
|
Note custom posting dates spanning the file boundary will disrupt the
|
|
balance assertions:
|
|
|
|
2023-12-30 a purchase made in december, cleared in january
|
|
expenses:food 5
|
|
assets:bank:checking -5 ; date: 2023-01-02
|
|
|
|
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:
|
|
|
|
; 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's transaction cleared
|
|
equity:pending 5 = 0
|
|
assets:bank:checking -5
|
|
|
|
Example: retain earnings
|
|
Record 2022's revenues/expenses as retained earnings on 2022-12-31,
|
|
appending the generated transaction to the journal:
|
|
|
|
$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
|
|
|
|
Now 2022's income statement will show only zeroes. To see it again,
|
|
exclude the retain transaction. Eg:
|
|
|
|
$ hledger -f 2022.journal is not:desc:'retain earnings'
|
|
|
|
Example: migrate balances to a new file
|
|
Close assets/liabilities/equity on 2022-12-31 and re-open them on
|
|
2023-01-01:
|
|
|
|
$ 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
|
|
|
|
Now 2022's balance sheet will show only zeroes, indicating a balanced
|
|
accounting equation. (Unless you are using @/@@ notation - in that
|
|
case, try adding --infer-equity.) To see it again, exclude the closing
|
|
transaction. Eg:
|
|
|
|
$ hledger -f 2022.journal bs not:desc:'closing balances'
|
|
|
|
Example: excluding closing/opening transactions
|
|
When combining many files for multi-year reports, the closing/opening
|
|
transactions cause some noise in reports like print and register. You
|
|
can exclude them as shown above, but not:desc:... could be fragile, and
|
|
also you will need to avoid excluding the very first opening transac-
|
|
tion, which can be awkward. Here is a way to do it, using tags: add
|
|
clopen: tags to all opening/closing balances transactions except the
|
|
first, like this:
|
|
|
|
; 2021.journal
|
|
2021-06-01 first opening balances
|
|
...
|
|
2021-12-31 closing balances ; clopen:2022
|
|
...
|
|
|
|
; 2022.journal
|
|
2022-01-01 opening balances ; clopen:2022
|
|
...
|
|
2022-12-31 closing balances ; clopen:2023
|
|
...
|
|
|
|
; 2023.journal
|
|
2023-01-01 opening balances ; clopen:2023
|
|
...
|
|
|
|
Now, assuming a combined journal like:
|
|
|
|
; all.journal
|
|
include 2021.journal
|
|
include 2022.journal
|
|
include 2023.journal
|
|
|
|
The clopen: tag can exclude all but the first opening transaction. To
|
|
show a clean multi-year checking register:
|
|
|
|
$ hledger -f all.journal areg checking not:tag:clopen
|
|
|
|
And the year values allow more precision. To show 2022's year-end bal-
|
|
ance sheet:
|
|
|
|
$ hledger -f all.journal bs -e2023 not:tag:clopen=2023
|
|
|
|
codes
|
|
List the codes seen in transactions, in the order parsed.
|
|
|
|
This command prints the value of each transaction'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.
|
|
|
|
Transactions aren't required to have a code, and missing or empty codes
|
|
will not be shown by default. With the -E/--empty flag, they will be
|
|
printed as blank lines.
|
|
|
|
You can add a query to select a subset of transactions.
|
|
|
|
Examples:
|
|
|
|
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
|
|
|
|
$ hledger codes
|
|
123
|
|
124
|
|
126
|
|
|
|
$ hledger codes -E
|
|
123
|
|
124
|
|
|
|
126
|
|
|
|
commodities
|
|
List all commodity/currency symbols used or declared in the journal.
|
|
|
|
demo
|
|
Play demos of hledger usage in the terminal, if asciinema is installed.
|
|
|
|
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:
|
|
|
|
Make your terminal window large enough to see the demo clearly.
|
|
|
|
During playback, several keys are available: SPACE to pause/unpause, .
|
|
to step forward (while paused), CTRL-c quit.
|
|
|
|
asciinema options can be added following a double dash, such as -s N to
|
|
adjust speed and -i SECS to limit pauses. Run asciinema -h to list
|
|
these options.
|
|
|
|
Examples:
|
|
|
|
$ hledger demo # list available demos
|
|
$ hledger demo 1 # play the first demo
|
|
$ hledger demo install -- -s5 -i.5 # play the install demo at 5x speed,
|
|
# with pauses limited to half a second
|
|
|
|
descriptions
|
|
List the unique descriptions that appear in transactions.
|
|
|
|
This command lists the unique descriptions that appear in transactions,
|
|
in alphabetic order. You can add a query to select a subset of trans-
|
|
actions.
|
|
|
|
Example:
|
|
|
|
$ hledger descriptions
|
|
Store Name
|
|
Gas Station | Petrol
|
|
Person A
|
|
|
|
diff
|
|
Compares a particular account's transactions in two input files. It
|
|
shows any transactions to this account which are in one file but not in
|
|
the other.
|
|
|
|
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 mul-
|
|
tiple bank transactions have been combined into a single journal entry.
|
|
|
|
This is useful eg if you have downloaded an account'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.
|
|
|
|
Examples:
|
|
|
|
$ 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:
|
|
|
|
files
|
|
List all files included in the journal. With a REGEX argument, only
|
|
file names matching the regular expression (case sensitive) are shown.
|
|
|
|
help
|
|
Show the hledger user manual in the terminal, with info, man, 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: commands, print, forecast, journal, amount, "auto
|
|
postings".
|
|
|
|
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.
|
|
|
|
By default it chooses the best viewer found in $PATH (preferring info
|
|
since the hledger manual is large). You can select a particular viewer
|
|
with the -i, -m, or -p flags.
|
|
|
|
Examples
|
|
|
|
$ 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
|
|
|
|
import
|
|
Read new transactions added to each FILE 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' trans-
|
|
actions as imported, without actually importing any.
|
|
|
|
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 add).
|
|
|
|
Unlike other hledger commands, with import the journal file is an out-
|
|
put 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
|
|
hledger import bank.csv or perhaps hledger import *.csv.
|
|
|
|
Note you can import from any file format, though CSV files are the most
|
|
common import source, and these docs focus on that case.
|
|
|
|
Deduplication
|
|
As a convenience import does deduplication while reading transactions.
|
|
This does not mean "ignore transactions that look the same", but rather
|
|
"ignore transactions that have been seen before". This is intended for
|
|
when you are periodically importing foreign data which may contain
|
|
already-imported transactions. So eg, if every day you download bank
|
|
CSV files containing redundant data, you can safely run hledger import
|
|
bank.csv and only new transactions will be imported. (import is idem-
|
|
potent.)
|
|
|
|
Since the items being read (CSV records, eg) often do not come with
|
|
unique identifiers, hledger detects new transactions by date, assuming
|
|
that:
|
|
|
|
1. new items always have the newest dates
|
|
|
|
2. item dates do not change across reads
|
|
|
|
3. and items with the same date remain in the same relative order
|
|
across reads.
|
|
|
|
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't matter (and if
|
|
you import often, the new transactions will be few, so less likely to
|
|
be the ones affected).
|
|
|
|
hledger remembers the latest date processed in each input file by sav-
|
|
ing a hidden ".latest" state file in the same directory. Eg when read-
|
|
ing finance/bank.csv, it will look for and update the finance/.lat-
|
|
est.bank.csv state file. The format is simple: one or more lines con-
|
|
taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro-
|
|
cessed transactions up to this date, and this many of them on that
|
|
date." Normally you won't see or manipulate these state files yourself.
|
|
But if needed, you can delete them to reset the state (making all
|
|
transactions "new"), or you can construct them to "catch up" to a cer-
|
|
tain date.
|
|
|
|
Note deduplication (and updating of state files) can also be done by
|
|
print --new, but this is less often used.
|
|
|
|
Import testing
|
|
With --dry-run, 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:
|
|
|
|
$ hledger import --dry bank.csv | hledger -f- -I print unknown
|
|
|
|
or (live updating):
|
|
|
|
$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'
|
|
|
|
Note: when importing from multiple files at once, it's currently possi-
|
|
ble 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.
|
|
|
|
Importing balance assignments
|
|
Entries added by import will have their posting amounts made explicit
|
|
(like hledger print -x). This means that any balance assignments in
|
|
imported files must be evaluated; but, imported files don't get to see
|
|
the main file'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:
|
|
|
|
$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
|
|
|
|
(If you think import should leave amounts implicit like print does,
|
|
please test it and send a pull request.)
|
|
|
|
Commodity display styles
|
|
Imported amounts will be formatted according to the canonical commodity
|
|
styles (declared or inferred) in the main journal file.
|
|
|
|
incomestatement
|
|
(is)
|
|
|
|
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.
|
|
|
|
This report shows accounts declared with the Revenue or Expense type
|
|
(see account types). Or if no such accounts are declared, it shows
|
|
top-level accounts named revenue or income or expense (case insensi-
|
|
tive, plurals allowed) and their subaccounts.
|
|
|
|
Example:
|
|
|
|
$ hledger incomestatement
|
|
Income Statement
|
|
|
|
Revenues:
|
|
$-2 income
|
|
$-1 gifts
|
|
$-1 salary
|
|
--------------------
|
|
$-2
|
|
|
|
Expenses:
|
|
$2 expenses
|
|
$1 food
|
|
$1 supplies
|
|
--------------------
|
|
$2
|
|
|
|
Total:
|
|
--------------------
|
|
0
|
|
|
|
This command is a higher-level variant of the balance command, and sup-
|
|
ports many of that command's features, such as multi-period reports.
|
|
It is similar to hledger balance '(revenues|income)' expenses, but with
|
|
smarter account detection, and revenues/income displayed with their
|
|
sign flipped.
|
|
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are txt, csv, html, and (experi-
|
|
mental) json.
|
|
|
|
notes
|
|
List the unique notes that appear in transactions.
|
|
|
|
This command lists the unique notes that appear in transactions, in
|
|
alphabetic order. You can add a query to select a subset of transac-
|
|
tions. The note is the part of the transaction description after a |
|
|
character (or if there is no |, the whole description).
|
|
|
|
Example:
|
|
|
|
$ hledger notes
|
|
Petrol
|
|
Snacks
|
|
|
|
payees
|
|
List the unique payee/payer names that appear in transactions.
|
|
|
|
This command lists unique payee/payer names which have been declared
|
|
with payee directives (--declared), used in transaction descriptions
|
|
(--used), or both (the default).
|
|
|
|
The payee/payer is the part of the transaction description before a |
|
|
character (or if there is no |, the whole description).
|
|
|
|
You can add query arguments to select a subset of transactions. This
|
|
implies --used.
|
|
|
|
Example:
|
|
|
|
$ hledger payees
|
|
Store Name
|
|
Gas Station
|
|
Person A
|
|
|
|
prices
|
|
Print market price directives from the journal. With --infer-market-
|
|
prices, generate additional market prices from costs. With --infer-
|
|
reverse-prices, also generate market prices by inverting known prices.
|
|
Prices can be filtered by a query. Price amounts are displayed with
|
|
their full precision.
|
|
|
|
print
|
|
Show transaction journal entries, sorted by date.
|
|
|
|
The print command displays full journal entries (transactions) from the
|
|
journal file, sorted by date (or with --date2, by secondary date).
|
|
|
|
Amounts are shown mostly normalised to commodity display style, eg the
|
|
placement of commodity symbols will be consistent. All of their deci-
|
|
mal places are shown, as in the original journal entry (with one alter-
|
|
ation: in some cases trailing zeroes are added.)
|
|
|
|
Amounts are shown right-aligned within each transaction (but not across
|
|
all transactions).
|
|
|
|
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 your journal you should take care to also copy over the
|
|
directives and file-level comments.
|
|
|
|
Eg:
|
|
|
|
$ hledger print
|
|
2008/01/01 income
|
|
assets:bank:checking $1
|
|
income:salary $-1
|
|
|
|
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
|
|
|
|
2008/12/31 * pay off
|
|
liabilities:debts $1
|
|
assets:bank:checking $-1
|
|
|
|
print'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, eg:
|
|
|
|
# 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
|
|
|
|
There are some situations where print's output can become unparseable:
|
|
|
|
o Valuation affects posting amounts but not balance assertion or bal-
|
|
ance assignment amounts, potentially causing those to fail.
|
|
|
|
o Auto postings can generate postings with too many missing amounts.
|
|
|
|
o Account aliases can generate bad account names.
|
|
|
|
Normally, the journal entry's explicit or implicit amount style is pre-
|
|
served. For example, when an amount is omitted in the journal, it will
|
|
not appear in the output. Similarly, when a cost is implied but not
|
|
written, it will not appear in the output. You can use the
|
|
-x/--explicit flag to make all amounts and costs explicit, which can be
|
|
useful for troubleshooting or for making your journal more readable and
|
|
robust against data entry errors. -x is also implied by using any of
|
|
-B,-V,-X,--value.
|
|
|
|
Note, -x/--explicit will cause postings with a multi-commodity amount
|
|
(these can arise when a multi-commodity transaction has an implicit
|
|
amount) to be split into multiple single-commodity postings, keeping
|
|
the output parseable.
|
|
|
|
With -B/--cost, amounts with costs are converted to cost using that
|
|
price. This can be used for troubleshooting.
|
|
|
|
With -m DESC/--match=DESC, print does a fuzzy search for 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.
|
|
|
|
With --new, hledger prints only transactions it has not seen on a pre-
|
|
vious run. This uses the same deduplication system as the import com-
|
|
mand. (See import's docs for details.)
|
|
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are txt, csv, and (experimental)
|
|
json and sql.
|
|
|
|
Here's an example of print's CSV output:
|
|
|
|
$ hledger print -Ocsv
|
|
"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
|
|
"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
|
|
"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
|
|
"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
|
|
"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
|
|
"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
|
|
"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
|
|
"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
|
|
"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
|
|
"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
|
|
"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
|
|
"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
|
|
|
|
o There is one CSV record per posting, with the parent transaction's
|
|
fields repeated.
|
|
|
|
o The "txnidx" (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.)
|
|
|
|
o The amount is separated into "commodity" (the symbol) and "amount"
|
|
(numeric quantity) fields.
|
|
|
|
o The numeric amount is repeated in either the "credit" or "debit" col-
|
|
umn, for convenience. (Those names are not accurate in the account-
|
|
ing sense; it just puts negative amounts under credit and zero or
|
|
greater amounts under debit.)
|
|
|
|
register
|
|
(reg)
|
|
|
|
Show postings and their running total.
|
|
|
|
The register command displays matched postings, across all accounts, in
|
|
date order, with their running total or running historical balance.
|
|
(See also the aregister command, which shows matched transactions in a
|
|
specific account.)
|
|
|
|
register normally shows line per posting, but note that multi-commodity
|
|
amounts will occupy multiple lines (one line per commodity).
|
|
|
|
It is typically used with a query selecting a particular account, to
|
|
see that account's activity:
|
|
|
|
$ 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
|
|
|
|
With --date2, it shows and sorts by secondary date instead.
|
|
|
|
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
|
|
--align-all flag.
|
|
|
|
The --historical/-H 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:
|
|
|
|
$ 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
|
|
|
|
The --depth option limits the amount of sub-account detail displayed.
|
|
|
|
The --average/-A 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 --empty (see below). It
|
|
is affected by --historical. It works best when showing just one
|
|
account and one commodity.
|
|
|
|
The --related/-r flag shows the other postings in the transactions of
|
|
the postings which would normally be shown.
|
|
|
|
The --invert flag negates all amounts. For example, it can be used on
|
|
an income account where amounts are normally displayed as negative num-
|
|
bers. It's also useful to show postings on the checking account
|
|
together with the related account:
|
|
|
|
$ hledger register --related --invert assets:checking
|
|
|
|
With a reporting interval, register shows summary postings, one per
|
|
interval, aggregating the postings to each account:
|
|
|
|
$ hledger register --monthly income
|
|
2008/01 income:salary $-1 $-1
|
|
2008/06 income:gifts $-1 $-2
|
|
|
|
Periods with no activity, and summary postings with a zero amount, are
|
|
not shown by default; use the --empty/-E flag to see them:
|
|
|
|
$ 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
|
|
|
|
Often, you'll want to see just one line per interval. The --depth
|
|
option helps with this, causing subaccounts to be aggregated:
|
|
|
|
$ hledger register --monthly assets --depth 1h
|
|
2008/01 assets $1 $1
|
|
2008/06 assets $-1 0
|
|
2008/12 assets $-1 $-1
|
|
|
|
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.
|
|
|
|
With -m DESC/--match=DESC, 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 post-
|
|
ing will be shown and the program exit code will be non-zero.
|
|
|
|
Custom register output
|
|
register uses the full terminal width by default, except on windows.
|
|
You can override this by setting the COLUMNS environment variable (not
|
|
a bash shell variable) or by using the --width/-w option.
|
|
|
|
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's argument, comma-separated:
|
|
--width W,D . Here's a diagram (won't display correctly in --help):
|
|
|
|
<--------------------------------- width (W) ---------------------------------->
|
|
date (10) description (D) account (W-41-D) amount (12) balance (12)
|
|
DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
|
|
|
|
and some examples:
|
|
|
|
$ 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
|
|
|
|
This command also supports the output destination and output format
|
|
options The output formats supported are txt, csv, and (experimental)
|
|
json.
|
|
|
|
rewrite
|
|
Print all transactions, rewriting the postings of matched transactions.
|
|
For now the only rewrite available is adding new postings, like print
|
|
--auto.
|
|
|
|
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 transac-
|
|
tion's first posting amount.
|
|
|
|
Examples:
|
|
|
|
$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
|
|
$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
|
|
$ hledger-rewrite.hs -f rewrites.hledger
|
|
|
|
rewrites.hledger may consist of entries like:
|
|
|
|
= ^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
|
|
|
|
Note the single quotes to protect the dollar sign from bash, and the
|
|
two spaces between account and amount.
|
|
|
|
More:
|
|
|
|
$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
|
|
$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
|
|
$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'
|
|
$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
|
|
|
|
Argument for --add-posting option is a usual posting of transaction
|
|
with an exception for amount specification. More precisely, you can
|
|
use '*' (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's com-
|
|
modity.
|
|
|
|
Re-write rules in a file
|
|
During the run this tool will execute so called "Automated Transac-
|
|
tions" found in any journal it process. I.e instead of specifying this
|
|
operations in command line you can put them in a journal file.
|
|
|
|
$ rewrite-rules.journal
|
|
|
|
Make contents look like this:
|
|
|
|
= ^income
|
|
(liabilities:tax) *.33
|
|
|
|
= expenses:gifts
|
|
budget:gifts *-1
|
|
assets:budget *1
|
|
|
|
Note that '=' (equality symbol) that is used instead of date in trans-
|
|
actions you usually write. It indicates the query by which you want to
|
|
match the posting to add new ones.
|
|
|
|
$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
|
|
|
|
This is something similar to the commands pipeline:
|
|
|
|
$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \
|
|
| hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \
|
|
--add-posting 'assets:budget *1' \
|
|
> rewritten-tidy-output.journal
|
|
|
|
It is important to understand that relative order of such entries in
|
|
journal is important. You can re-use result of previously added post-
|
|
ings.
|
|
|
|
Diff output format
|
|
To use this tool for batch modification of your journal files you may
|
|
find useful output in form of unified diff.
|
|
|
|
$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
|
|
|
|
Output might look like:
|
|
|
|
--- /tmp/examples/sample.journal
|
|
+++ /tmp/examples/sample.journal
|
|
@@ -18,3 +18,4 @@
|
|
2008/01/01 income
|
|
- assets:bank:checking $1
|
|
+ assets:bank:checking $1
|
|
income:salary
|
|
+ (liabilities:tax) 0
|
|
@@ -22,3 +23,4 @@
|
|
2008/06/01 gift
|
|
- assets:bank:checking $1
|
|
+ assets:bank:checking $1
|
|
income:gifts
|
|
+ (liabilities:tax) 0
|
|
|
|
If you'll pass this through patch tool you'll get transactions contain-
|
|
ing the posting that matches your query be updated. Note that multiple
|
|
files might be update according to list of input files specified via
|
|
--file options and include directives inside of these files.
|
|
|
|
Be careful. Whole transaction being re-formatted in a style of output
|
|
from hledger print.
|
|
|
|
See also:
|
|
|
|
https://github.com/simonmichael/hledger/issues/99
|
|
|
|
rewrite vs. print --auto
|
|
This command predates print --auto, and currently does much the same
|
|
thing, but with these differences:
|
|
|
|
o with multiple files, rewrite lets rules in any file affect all other
|
|
files. print --auto uses standard directive scoping; rules affect
|
|
only child files.
|
|
|
|
o rewrite's query limits which transactions can be rewritten; all are
|
|
printed. print --auto's query limits which transactions are printed.
|
|
|
|
o rewrite applies rules specified on command line or in the journal.
|
|
print --auto applies rules specified in the journal.
|
|
|
|
roi
|
|
Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
|
|
on your investments.
|
|
|
|
At a minimum, you need to supply a query (which could be just an
|
|
account name) to select your investment(s) with --inv, and another
|
|
query to identify your profit and loss transactions with --pnl.
|
|
|
|
If you do not record changes in the value of your investment manually,
|
|
or do not require computation of time-weighted return (TWR), --pnl
|
|
could be an empty query (--pnl "" or --pnl STR where STR does not match
|
|
any of your accounts).
|
|
|
|
This command will compute and display the internalized rate of return
|
|
(IRR) and time-weighted rate of return (TWR) for your investments for
|
|
the time period requested. Both rates of return are annualized before
|
|
display, regardless of the length of reporting interval.
|
|
|
|
Price directives will be taken into account if you supply appropriate
|
|
--cost or --value flags (see VALUATION).
|
|
|
|
Note, in some cases this report can fail, for these reasons:
|
|
|
|
o 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.
|
|
|
|
o Error (SearchFailed): Failed to find solution for Internal Rate of
|
|
Return (IRR). Either search does not converge to a solution, or con-
|
|
verges too slowly.
|
|
|
|
Examples:
|
|
|
|
o Using roi to compute total return of investment in stocks:
|
|
https://github.com/simonmichael/hledger/blob/master/examples/invest-
|
|
ing/roi-unrealised.ledger
|
|
|
|
o Cookbook > Return on Investment: https://hledger.org/roi.html
|
|
|
|
Spaces and special characters in --inv and --pnl
|
|
Note that --inv and --pnl's argument is a query, and queries could have
|
|
several space-separated terms (see QUERIES).
|
|
|
|
To indicate that all search terms form single command-line argument,
|
|
you will need to put them in quotes (see Special characters):
|
|
|
|
$ hledger roi --inv 'term1 term2 term3 ...'
|
|
|
|
If any query terms contain spaces themselves, you will need an extra
|
|
level of nested quoting, eg:
|
|
|
|
$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"
|
|
|
|
Semantics of --inv and --pnl
|
|
Query supplied to --inv has to match all transactions that are related
|
|
to your investment. Transactions not matching --inv will be ignored.
|
|
|
|
In these transactions, ROI will conside postings that match --inv to be
|
|
"investment postings" and other postings (not matching --inv) will be
|
|
sorted into two categories: "cash flow" and "profit and loss", as ROI
|
|
needs to know which part of the investment value is your contributions
|
|
and which is due to the return on investment.
|
|
|
|
o "Cash flow" is depositing or withdrawing money, buying or selling
|
|
assets, or otherwise converting between your investment commodity and
|
|
any other commodity. Example:
|
|
|
|
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
|
|
|
|
o "Profit and loss" is change in the value of your investment:
|
|
|
|
2019-06-01 Snake Oil falls in value
|
|
investment:snake oil = $57
|
|
equity:unrealized profit or loss
|
|
|
|
All non-investment postings are assumed to be "cash flow", unless they
|
|
match --pnl query. Changes in value of your investment due to "profit
|
|
and loss" postings will be considered as part of your investment
|
|
return.
|
|
|
|
Example: if you use --inv snake --pnl equity:unrealized, then postings
|
|
in the example below would be classifed as:
|
|
|
|
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
|
|
|
|
IRR and TWR explained
|
|
"ROI" stands for "return on investment". Traditionally this was com-
|
|
puted as a difference between current value of investment and its ini-
|
|
tial value, expressed in percentage of the initial value.
|
|
|
|
However, this approach is only practical in simple cases, where invest-
|
|
ments receives no in-flows or out-flows of money, and where rate of
|
|
growth is fixed over time. For more complex scenarios you need differ-
|
|
ent ways to compute rate of return, and this command implements two of
|
|
them: IRR and TWR.
|
|
|
|
Internal rate of return, or "IRR" (also called "money-weighted rate of
|
|
return") takes into account effects of in-flows and out-flows.
|
|
Naively, if you are withdrawing from your investment, your future gains
|
|
would be smaller (in absolute numbers), and will be a smaller percent-
|
|
age of your initial investment, and if you are adding to your invest-
|
|
ment, you will receive bigger absolute gains (but probably at the same
|
|
rate of return). IRR is a way to compute rate of return for each
|
|
period between in-flow or out-flow of money, and then combine them in a
|
|
way that gives you a compound annual rate of return that investment is
|
|
expected to generate.
|
|
|
|
As mentioned before, in-flows and out-flows would be any cash that you
|
|
personally put in or withdraw, and for the "roi" command, these are the
|
|
postings that match the query in the--inv argument and NOT match the
|
|
query in the--pnl argument.
|
|
|
|
If you manually record changes in the value of your investment as
|
|
transactions that balance them against "profit and loss" (or "unreal-
|
|
ized gains") 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.
|
|
|
|
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't done
|
|
discounted cash flow analysis before. Implementation of IRR in hledger
|
|
should produce results that match the XIRR formula in Excel.
|
|
|
|
Second way to compute rate of return that roi command implements is
|
|
called "time-weighted rate of return" or "TWR". Like IRR, it will also
|
|
break the history of your investment into periods between in-flows,
|
|
out-flows and value changes, to compute rate of return per each period
|
|
and then a compound rate of return. However, internal workings of TWR
|
|
are quite different.
|
|
|
|
TWR represents your investment as an imaginary "unit fund" where in-
|
|
flows/ out-flows lead to buying or selling "units" of your investment
|
|
and changes in its value change the value of "investment unit". Change
|
|
in "unit price" over the reporting period gives you rate of return of
|
|
your investment.
|
|
|
|
References:
|
|
|
|
o Explanation of rate of return
|
|
|
|
o Explanation of IRR
|
|
|
|
o Explanation of TWR
|
|
|
|
o Examples of computing IRR and TWR and discussion of the limitations
|
|
of both metrics
|
|
|
|
stats
|
|
Show journal and performance statistics.
|
|
|
|
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.
|
|
|
|
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
|
|
stats command's run time is similar to that of a single-column balance
|
|
report.
|
|
|
|
Example:
|
|
|
|
$ 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
|
|
|
|
This command supports the -o/--output-file option (but not -O/--output-
|
|
format selection).
|
|
|
|
tags
|
|
List the tags used in the journal, or their values.
|
|
|
|
This command lists the tag names used in the journal, whether on trans-
|
|
actions, postings, or account declarations.
|
|
|
|
With a TAGREGEX argument, only tag names matching this regular expres-
|
|
sion (case insensitive, infix matched) are shown.
|
|
|
|
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.
|
|
|
|
With the --values flag, the tags' unique non-empty values are listed
|
|
instead. With -E/--empty, blank/empty values are also shown.
|
|
|
|
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.)
|
|
|
|
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.
|
|
|
|
test
|
|
Run built-in unit tests.
|
|
|
|
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.
|
|
|
|
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!
|
|
|
|
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:
|
|
|
|
$ hledger test -- -pData.Amount --color=never
|
|
|
|
For help on these, see https://github.com/feuerbach/tasty#options (--
|
|
--help currently doesn't show them).
|
|
|
|
|
|
PART 5: COMMON TASKS
|
|
Here are some quick examples of how to do some basic tasks with
|
|
hledger.
|
|
|
|
Getting help
|
|
Here's how to list commands and view options and command docs:
|
|
|
|
$ hledger # show available commands
|
|
$ hledger --help # show common options
|
|
$ hledger CMD --help # show CMD's options, common options and CMD's documentation
|
|
|
|
You can also view your hledger version's manual in several formats by
|
|
using the help command. Eg:
|
|
|
|
$ 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
|
|
|
|
To view manuals and introductory docs on the web, visit
|
|
https://hledger.org. Chat and mail list support and discussion ar-
|
|
chives can be found at https://hledger.org/support.
|
|
|
|
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:
|
|
|
|
o command-specific options must go after the command (it's fine to put
|
|
common options there too: hledger CMD OPTS ARGS)
|
|
|
|
o running add-on executables directly simplifies command line parsing
|
|
(hledger-ui OPTS ARGS)
|
|
|
|
o enclose "problematic" args in single quotes
|
|
|
|
o if needed, also add a backslash to hide regular expression metachar-
|
|
acters from the shell
|
|
|
|
o to see how a misbehaving command line is being parsed, add --debug=2.
|
|
|
|
Starting a journal file
|
|
hledger looks for your accounting data in a journal file,
|
|
$HOME/.hledger.journal by default:
|
|
|
|
$ hledger stats
|
|
The hledger journal file "/Users/simon/.hledger.journal" was not found.
|
|
Please create it first, eg with "hledger add" or a text editor.
|
|
Or, specify an existing journal file with -f or LEDGER_FILE.
|
|
|
|
You can override this by setting the LEDGER_FILE environment variable.
|
|
It'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:
|
|
|
|
$ mkdir ~/finance
|
|
$ cd ~/finance
|
|
$ git init
|
|
Initialized empty Git repository in /Users/simon/finance/.git/
|
|
$ touch 2020.journal
|
|
$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc
|
|
$ source ~/.bashrc
|
|
$ hledger stats
|
|
Main file : /Users/simon/finance/2020.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 ()
|
|
|
|
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..).
|
|
|
|
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.
|
|
|
|
Add an opening balances transaction to the journal, declaring the bal-
|
|
ances on this date. Here are two ways to do it:
|
|
|
|
o The first way: open the journal in any text editor and save an entry
|
|
like this:
|
|
|
|
2020-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
|
|
|
|
These are start-of-day balances, ie whatever was in the account at
|
|
the end of the previous day.
|
|
|
|
The * after the date is an optional status flag. Here it means
|
|
"cleared & confirmed".
|
|
|
|
The currency symbols are optional, but usually a good idea as you'll
|
|
be dealing with multiple currencies sooner or later.
|
|
|
|
The = amounts are optional balance assertions, providing extra error
|
|
checking.
|
|
|
|
o The second way: run hledger add and follow the prompts to record a
|
|
similar transaction:
|
|
|
|
$ hledger add
|
|
Adding transactions to journal file /Users/simon/finance/2020.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 [2020-02-07]: 2020-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): .
|
|
2020-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 [2020-01-01]: .
|
|
|
|
If you're using version control, this could be a good time to commit
|
|
the journal. Eg:
|
|
|
|
$ git commit -m 'initial balances' 2020.journal
|
|
|
|
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.
|
|
|
|
Here are some simple transactions, see the hledger_journal(5) manual
|
|
and hledger.org for more ideas:
|
|
|
|
2020/1/10 * gift received
|
|
assets:cash $20
|
|
income:gifts
|
|
|
|
2020.1.12 * farmers market
|
|
expenses:food $13
|
|
assets:cash
|
|
|
|
2020-01-15 paycheck
|
|
income:salary
|
|
assets:bank:checking $1000
|
|
|
|
Reconciling
|
|
Periodically you should reconcile - compare your hledger-reported bal-
|
|
ances against external sources of truth, like bank statements or your
|
|
bank'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 dis-
|
|
crepancies.
|
|
|
|
A typical workflow:
|
|
|
|
1. Reconcile cash. Count what's in your wallet. Compare with what
|
|
hledger reports (hledger bal cash). 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
|
|
(hledger reg cash). If you can't find the error, add an adjustment
|
|
transaction. Eg if you have $105 after the above, and can't explain
|
|
the missing $2, it could be:
|
|
|
|
2020-01-16 * adjust cash
|
|
assets:cash $-2 = $105
|
|
expenses:misc
|
|
|
|
2. Reconcile checking. Log in to your bank's website. Compare today's
|
|
(cleared) balance with hledger's cleared balance (hledger bal check-
|
|
ing -C). 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 trans-
|
|
action history and running balance from your bank with the one
|
|
reported by hledger reg checking -C. This will be easier if you
|
|
generally record transaction dates quite similar to your bank's
|
|
clearing dates.
|
|
|
|
3. Repeat for other asset/liability accounts.
|
|
|
|
Tip: instead of the register command, use hledger-ui to see a live-
|
|
updating register while you edit the journal: hledger-ui --watch --reg-
|
|
ister checking -C
|
|
|
|
After reconciling, it could be a good time to mark the reconciled
|
|
transactions' status as "cleared and confirmed", if you want to track
|
|
that, by adding the * marker. Eg in the paycheck transaction above,
|
|
insert * between 2020-01-15 and paycheck
|
|
|
|
If you're using version control, this can be another good time to com-
|
|
mit:
|
|
|
|
$ git commit -m 'txns' 2020.journal
|
|
|
|
Reporting
|
|
Here are some basic reports.
|
|
|
|
Show all transactions:
|
|
|
|
$ hledger print
|
|
2020-01-01 * opening balances
|
|
assets:bank:checking $1000
|
|
assets:bank:savings $2000
|
|
assets:cash $100
|
|
liabilities:creditcard $-50
|
|
equity:opening/closing balances $-3050
|
|
|
|
2020-01-10 * gift received
|
|
assets:cash $20
|
|
income:gifts
|
|
|
|
2020-01-12 * farmers market
|
|
expenses:food $13
|
|
assets:cash
|
|
|
|
2020-01-15 * paycheck
|
|
income:salary
|
|
assets:bank:checking $1000
|
|
|
|
2020-01-16 * adjust cash
|
|
assets:cash $-2 = $105
|
|
expenses:misc
|
|
|
|
Show account names, and their hierarchy:
|
|
|
|
$ hledger accounts --tree
|
|
assets
|
|
bank
|
|
checking
|
|
savings
|
|
cash
|
|
equity
|
|
opening/closing balances
|
|
expenses
|
|
food
|
|
misc
|
|
income
|
|
gifts
|
|
salary
|
|
liabilities
|
|
creditcard
|
|
|
|
Show all account totals:
|
|
|
|
$ 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
|
|
|
|
Show only asset and liability balances, as a flat list, limited to
|
|
depth 2:
|
|
|
|
$ hledger bal assets liabilities -2
|
|
$4000 assets:bank
|
|
$105 assets:cash
|
|
$-50 liabilities:creditcard
|
|
--------------------
|
|
$4055
|
|
|
|
Show the same thing without negative numbers, formatted as a simple
|
|
balance sheet:
|
|
|
|
$ hledger bs -2
|
|
Balance Sheet 2020-01-16
|
|
|
|
|| 2020-01-16
|
|
========================++============
|
|
Assets ||
|
|
------------------------++------------
|
|
assets:bank || $4000
|
|
assets:cash || $105
|
|
------------------------++------------
|
|
|| $4105
|
|
========================++============
|
|
Liabilities ||
|
|
------------------------++------------
|
|
liabilities:creditcard || $50
|
|
------------------------++------------
|
|
|| $50
|
|
========================++============
|
|
Net: || $4055
|
|
|
|
The final total is your "net worth" on the end date. (Or use bse for a
|
|
full balance sheet with equity.)
|
|
|
|
Show income and expense totals, formatted as an income statement:
|
|
|
|
hledger is
|
|
Income Statement 2020-01-01-2020-01-16
|
|
|
|
|| 2020-01-01-2020-01-16
|
|
===============++=======================
|
|
Revenues ||
|
|
---------------++-----------------------
|
|
income:gifts || $20
|
|
income:salary || $1000
|
|
---------------++-----------------------
|
|
|| $1020
|
|
===============++=======================
|
|
Expenses ||
|
|
---------------++-----------------------
|
|
expenses:food || $13
|
|
expenses:misc || $2
|
|
---------------++-----------------------
|
|
|| $15
|
|
===============++=======================
|
|
Net: || $1005
|
|
|
|
The final total is your net income during this period.
|
|
|
|
Show transactions affecting your wallet, with running total:
|
|
|
|
$ hledger register cash
|
|
2020-01-01 opening balances assets:cash $100 $100
|
|
2020-01-10 gift received assets:cash $20 $120
|
|
2020-01-12 farmers market assets:cash $-13 $107
|
|
2020-01-16 adjust cash assets:cash $-2 $105
|
|
|
|
Show weekly posting counts as a bar chart:
|
|
|
|
$ hledger activity -W
|
|
2019-12-30 *****
|
|
2020-01-06 ****
|
|
2020-01-13 ****
|
|
|
|
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't slow down or clutter your reports,
|
|
and to help ensure the integrity of your accounting history. See the
|
|
close command.
|
|
|
|
If using version control, don't forget to git add the new file.
|
|
|
|
|
|
|
|
REPORTING BUGS
|
|
Report bugs at http://bugs.hledger.org (or on the #hledger chat or
|
|
hledger mail list)
|
|
|
|
|
|
AUTHORS
|
|
Simon Michael <simon@joyful.com> and contributors.
|
|
See http://hledger.org/CREDITS.html
|
|
|
|
|
|
COPYRIGHT
|
|
Copyright 2007-2023 Simon Michael and contributors.
|
|
|
|
|
|
LICENSE
|
|
Released under GNU GPL v3 or later.
|
|
|
|
|
|
SEE ALSO
|
|
hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
|
|
|
|
|
|
|
|
hledger-1.29.99 March 2023 HLEDGER(1)
|