8934 lines
386 KiB
Plaintext
8934 lines
386 KiB
Plaintext
|
|
HLEDGER(1) hledger User Manuals HLEDGER(1)
|
|
|
|
NAME
|
|
hledger - robust, friendly plain text accounting (CLI version)
|
|
|
|
SYNOPSIS
|
|
hledger
|
|
hledger COMMAND [OPTS] [ARGS]
|
|
hledger ADDONCMD -- [OPTS] [ARGS]
|
|
|
|
DESCRIPTION
|
|
hledger is a robust, user-friendly, cross-platform set of programs for
|
|
tracking money, time, or any other commodity, using double-entry ac-
|
|
counting 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.32.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 de-
|
|
scribing financial transactions, crunch the numbers, and print a useful
|
|
report on the terminal (or save it as HTML, CSV, JSON or SQL). Many
|
|
reports are available, as subcommands. hledger will also detect other
|
|
hledger-* executables as extra subcommands.
|
|
|
|
hledger usually reads from (and appends to) a journal file specified by
|
|
the LEDGER_FILE environment variable (defaulting to
|
|
$HOME/.hledger.journal); or you can specify files with -f options. It
|
|
can also read timeclock files, timedot files, or any CSV/SSV/TSV file
|
|
with a date field.
|
|
|
|
Here is a small journal file describing one transaction:
|
|
|
|
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
|
|
Input
|
|
hledger reads one or more data files, each time you run it. You can
|
|
specify a file with -f, like so
|
|
|
|
$ hledger -f FILE print
|
|
|
|
Files are most often in hledger's journal format, with the .journal
|
|
file extension (.hledger or .j also work); these files describe trans-
|
|
actions, like an accounting general journal.
|
|
|
|
When no file is specified, hledger looks for .hledger.journal in your
|
|
home directory.
|
|
|
|
But most people prefer to keep financial files in a dedicated folder,
|
|
perhaps with version control. Also, starting a new journal file each
|
|
year is common (it's not required, but helps keep things fast and or-
|
|
ganised). So we usually configure a different journal file, by setting
|
|
the LEDGER_FILE environment variable, to something like ~/fi-
|
|
nance/2023.journal. For more about how to do that on your system, see
|
|
Common tasks > Setting LEDGER_FILE.
|
|
|
|
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 extensions:
|
|
-----------------------------------------------------------------------------
|
|
journal hledger journal files and some .journal .j .hledger .ledger
|
|
Ledger journals, for transac-
|
|
tions
|
|
timeclock timeclock files, for precise .timeclock
|
|
time logging
|
|
timedot timedot files, for approximate .timedot
|
|
time logging
|
|
csv CSV/SSV/TSV/character-sepa- .csv .ssv .tsv .csv.rules
|
|
rated values, for data import .ssv.rules .tsv.rules
|
|
|
|
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
|
|
|
|
Standard input
|
|
The file name - means standard input:
|
|
|
|
$ cat FILE | hledger -f- print
|
|
|
|
If reading non-journal data in this way, you'll need to add a file for-
|
|
mat prefix, like:
|
|
|
|
$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
|
|
|
|
Multiple files
|
|
You can specify multiple -f options, to read multiple files as one big
|
|
journal. When doing this, note that certain features (described below)
|
|
will be affected:
|
|
|
|
o Balance assertions will not see the effect of transactions in previ-
|
|
ous files. (Usually this doesn't matter as each file will set the
|
|
corresponding opening balances.)
|
|
|
|
o Some directives will not affect previous or subsequent files.
|
|
|
|
If needed, you can work around these by using a single parent file
|
|
which includes the others, or concatenating the files into one, 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 various subcommands for getting things done. Most of
|
|
these commands do not change the journal file; they just read it and
|
|
output a report. A few commands assist with adding data and file man-
|
|
agement.
|
|
|
|
To show the commands list, run hledger with no arguments. The commands
|
|
are described in detail in PART 4: COMMANDS, below.
|
|
|
|
To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS],
|
|
|
|
o CMD is the full command name, or its standard abbreviation shown in
|
|
the commands list, or any unambiguous prefix of the name.
|
|
|
|
o CMDOPTS are command-specific options, if any. Command-specific op-
|
|
tions must be written after the command name. Eg: hledger print -x.
|
|
|
|
o CMDARGS are additional arguments to the command, if any. Most
|
|
hledger commands accept arguments representing a query, to limit the
|
|
data in some way. Eg: hledger reg assets:checking.
|
|
|
|
To list a command's options, arguments, and documentation in the termi-
|
|
nal, run hledger CMD -h. Eg: hledger bal -h.
|
|
|
|
Add-on commands
|
|
In addition to the built-in commands, you can install add-on commands:
|
|
programs or scripts named "hledger-SOMETHING", which will also appear
|
|
in hledger's commands list. If you used the hledger-install script,
|
|
you will have several add-ons installed already. Some more can be
|
|
found in hledger's bin/ directory, documented at
|
|
https://hledger.org/scripts.html.
|
|
|
|
More precisely, add-on commands are programs or scripts in your shell's
|
|
PATH, whose name starts with "hledger-" and ends with no extension or a
|
|
recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs",
|
|
".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix
|
|
and mac) which has executable permission for the current user.
|
|
|
|
You can run add-on commands using hledger, much like built-in commands:
|
|
hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double
|
|
hyphen argument, required before add-on-specific options. Eg: hledger
|
|
ui -- --watch or hledger web -- --serve. If this causes difficulty,
|
|
you can always run the add-on directly, without using hledger:
|
|
hledger-ui --watch or hledger-web --serve.
|
|
|
|
Options
|
|
Run hledger -h to see general command line help, and general options
|
|
which are common to most hledger commands. These options can be writ-
|
|
ten anywhere on the command line. They can be grouped into help, in-
|
|
put, and reporting options:
|
|
|
|
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
|
|
|
|
--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 de-
|
|
clared)
|
|
|
|
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 ef-
|
|
fects)
|
|
|
|
--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-equity
|
|
infer conversion equity postings from costs
|
|
|
|
--infer-costs
|
|
infer costs from conversion equity postings
|
|
|
|
--infer-market-prices
|
|
use costs as additional market prices, as if they were P direc-
|
|
tives
|
|
|
|
--forecast
|
|
generate transactions from periodic rules, between the latest
|
|
recorded txn and 6 months from today, or during the specified
|
|
PERIOD (= is required). Auto posting rules will be applied to
|
|
these transactions as well. Also, in hledger-ui make fu-
|
|
ture-dated transactions visible.
|
|
|
|
--auto generate extra postings by applying auto posting rules to all
|
|
txns (not just forecast txns)
|
|
|
|
--verbose-tags
|
|
add visible tags indicating transactions or postings which have
|
|
been generated/modified
|
|
|
|
--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 line tips
|
|
Here are some details useful to know about for hledger command lines
|
|
(and elsewhere). Feel free to skip this section until you need it.
|
|
|
|
Option repetition
|
|
If options are repeated in a command line, hledger will generally use
|
|
the last (right-most) occurence.
|
|
|
|
Special characters
|
|
Single escaping (shell metacharacters)
|
|
In shell command lines, characters significant to your shell - such as
|
|
spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want
|
|
hledger to see them. This is done by enclosing them in single or dou-
|
|
ble quotes, or by writing a backslash before them. Eg to match an ac-
|
|
count 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 be-
|
|
low), one level of shell-escaping is lost from any options or arguments
|
|
intended for by the add-on command, so those need an extra level of
|
|
shell-escaping. Eg to match a literal $ sign while using the bash
|
|
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 de-
|
|
code the characters being used. In bash, you can set a locale like
|
|
this: export LANG=en_US.UTF-8. There are some more details in Trou-
|
|
bleshooting. This step is essential - without it, hledger will quit
|
|
on encountering a non-ascii character (as with all GHC-compiled pro-
|
|
grams).
|
|
|
|
o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
|
|
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
|
|
A regular expression (regexp) is a small piece of text where certain
|
|
characters (like ., ^, $, +, *, (), |, [], \) have special meanings,
|
|
forming a tiny language for matching text precisely - very useful in
|
|
hledger and elsewhere. To learn all about them, visit regular-expres-
|
|
sions.info.
|
|
|
|
hledger supports regexps whenever you are entering a pattern to match
|
|
something, eg in query arguments, account aliases, CSV if rules,
|
|
hledger-web's search form, hledger-ui's / search, etc. You may need to
|
|
wrap them in quotes, especially at the command line (see Special char-
|
|
acters above). Here are some examples:
|
|
|
|
Account name queries (quoted for command line use):
|
|
|
|
Regular expression: Matches:
|
|
------------------- ------------------------------------------------------------
|
|
bank assets:bank, assets:bank:savings, expenses:art:banksy, ...
|
|
:bank assets:bank:savings, expenses:art:banksy
|
|
:bank: assets:bank:savings
|
|
'^bank' none of those ( ^ matches beginning of text )
|
|
'bank$' assets:bank ( $ matches end of text )
|
|
'big \$ bank' big $ bank ( \ disables following character's special meaning )
|
|
'\bbank\b' assets:bank, assets:bank:savings ( \b matches word boundaries )
|
|
'(sav|check)ing' saving or checking ( (|) matches either alternative )
|
|
'saving|checking' saving or checking ( outer parentheses are not needed )
|
|
'savings?' saving or savings ( ? matches 0 or 1 of the preceding thing )
|
|
'my +bank' my bank, my bank, ... ( + matches 1 or more of the preceding thing )
|
|
'my *bank' mybank, my bank, my bank, ... ( * matches 0 or more of the preceding thing )
|
|
'b.nk' bank, bonk, b nk, ... ( . matches any character )
|
|
|
|
Some other queries:
|
|
|
|
desc:'amazon|amzn|audible' Amazon transactions
|
|
cur:EUR amounts with commodity symbol containing EUR
|
|
cur:'\$' amounts with commodity symbol containing $
|
|
cur:'^\$$' only $ amounts, not eg AU$ or CA$
|
|
cur:....? amounts with 4-or-more-character symbols
|
|
tag:.=202[1-3] things with any tag whose value contains 2021, 2022 or 2023
|
|
|
|
Account name aliases: accept . instead of : as account separator:
|
|
|
|
alias /\./=: replaces all periods in account names with colons
|
|
|
|
Show multiple top-level accounts combined as one:
|
|
|
|
--alias='/^[^:]+/=combined' ( [^:] matches any character other than : )
|
|
|
|
Show accounts with the second-level part removed:
|
|
|
|
--alias '/^([^:]+):[^:]+/ = \1'
|
|
match a top-level account and a second-level account
|
|
and replace those with just the top-level account
|
|
( \1 in the replacement text means "whatever was matched
|
|
by the first parenthesised part of the regexp"
|
|
|
|
CSV rules: match CSV records containing dining-related MCC codes:
|
|
|
|
if \?MCC581[124]
|
|
|
|
Match CSV records with a specific amount around the end/start of month:
|
|
|
|
if %amount \b3\.99
|
|
& %date (29|30|31|01|02|03)$
|
|
|
|
hledger's regular expressions
|
|
hledger's regular expressions come from the regex-tdfa library. If
|
|
they're not doing what you expect, it's important to know exactly what
|
|
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. backreferences are supported when doing text replacement in account
|
|
aliases or CSV rules, where backreferences can be used in the re-
|
|
placement string to reference capturing groups in the search regexp.
|
|
Otherwise, if you write \1, it will match the digit 1.
|
|
|
|
6. they do not support mode modifiers ((?s)), character classes (\w,
|
|
\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.
|
|
|
|
Argument files
|
|
You can save a set of command line options and arguments in a file, and
|
|
then reuse them by writing @FILENAME as a command line argument. Eg:
|
|
hledger bal @foo.args.
|
|
|
|
Inside the argument file, each line should contain just one option or
|
|
argument. Don't use spaces except inside quotes (or you'll see a con-
|
|
fusing error); write = (or nothing) between a flag and its argument.
|
|
For the special characters mentioned above, use one less level of quot-
|
|
ing than you would at the command prompt.
|
|
|
|
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/tsv 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
|
|
balancesheete- Y 1 Y 1 Y 1 Y
|
|
quity
|
|
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/mas-
|
|
ter/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 at least with SQLite, MySQL and Post-
|
|
gres.
|
|
|
|
o For SQLite, it will be more useful if you modify the generated id
|
|
field to be a PRIMARY KEY. Eg:
|
|
|
|
$ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...
|
|
|
|
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 (ex-
|
|
cept for cost amounts and amounts displayed by the print command, which
|
|
are always displayed with all decimal digits). For example, the fol-
|
|
lowing 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.
|
|
|
|
hledger will occasionally make some additional adjustments to number
|
|
formatting, eg adding a trailing decimal mark to disambiguate numbers
|
|
with digit group marks; for details, see Amount formatting, parseabil-
|
|
ity.
|
|
|
|
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.
|
|
|
|
Paging
|
|
When showing long output in the terminal, hledger will try to use the
|
|
pager specified by the PAGER environment variable, or less, or more.
|
|
(A pager is a helper program that shows one page at a time rather than
|
|
scrolling everything off screen). Currently it does this only for help
|
|
output, not for reports; specifically,
|
|
|
|
o when listing commands, with hledger
|
|
|
|
o when showing help with hledger [CMD] --help,
|
|
|
|
o when viewing manuals with hledger help or hledger --man.
|
|
|
|
Note the pager is expected to handle ANSI codes, which hledger uses eg
|
|
for bold emphasis. For the common pager less (and its more compatibil-
|
|
ity mode), we add R to the LESS and MORE environment variables to make
|
|
this work. If you use a different pager, you might need to configure
|
|
it similarly, to avoid seeing junk on screen (let us know). Otherwise,
|
|
you can set the NO_COLOR environment variable to 1 to disable all ANSI
|
|
output (see Colour).
|
|
|
|
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 re-
|
|
veal 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
|
|
|
|
Environment
|
|
These environment variables affect hledger:
|
|
|
|
COLUMNS This is normally set by your terminal; some hledger commands
|
|
(register) will format their output to this width. If not set, they
|
|
will try to use the available terminal width.
|
|
|
|
LEDGER_FILE The main journal file to use when not specified with
|
|
-f/--file. Default: $HOME/.hledger.journal.
|
|
|
|
NO_COLOR If this environment variable is set (with any value), hledger
|
|
will not use ANSI color codes in terminal output, unless overridden by
|
|
an explicit --color/--colour option.
|
|
|
|
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"
|
|
|
|
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 en-
|
|
tries in hledger journal format. This file represents a standard ac-
|
|
counting 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 compatible with most of Ledger's journal
|
|
format, but not all of it. The differences and interoperation tips are
|
|
described at hledger and Ledger. With some care, and by avoiding in-
|
|
compatible features, you can keep your hledger journal readable by
|
|
Ledger and vice versa. This can useful eg for comparing the behaviour
|
|
of one app against the other.
|
|
|
|
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 re-
|
|
gions 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 op-
|
|
tional 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 re-
|
|
ports, 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 de-
|
|
scription or posting account name, separated from it by a space, indi-
|
|
cating 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 un-
|
|
marked 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 un-
|
|
cashed 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 (af-
|
|
ter the first |). This may be worthwhile if you need to do more pre-
|
|
cise 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
|
|
spaces. 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: be-
|
|
tween 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,23
|
|
|
|
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
|
|
|
|
hledger is not biased towards period or comma decimal marks, so a num-
|
|
ber containing just one period or comma, like 1,000 or 1.000, is am-
|
|
biguous. In such cases hledger assumes it is a decimal mark, parsing
|
|
both of these as 1.
|
|
|
|
To disambiguate these and ensure accurate number parsing, especially if
|
|
you use digit group marks, we recommend declaring the decimal mark.
|
|
You can declare it for each file with decimal-mark directives, or for
|
|
each commodity with commodity directives (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 (symbol placement, decimal mark and digit group marks, number of
|
|
decimal digits) to use in most reports. This is inferred as follows:
|
|
|
|
First, if there's a D directive declaring a default commodity, that
|
|
commodity symbol and amount format is applied to all no-symbol amounts
|
|
in the journal.
|
|
|
|
Then each commodity's display style is determined from its commodity
|
|
directive. We recommend always declaring commodities with commodity
|
|
directives, since they help ensure consistent display styles and preci-
|
|
sions, and bring other benefits such as error checking for commodity
|
|
symbols.
|
|
|
|
But if a commodity directive is not present, hledger infers a commod-
|
|
ity's display styles from its amounts as they are written in the jour-
|
|
nal (excluding cost amounts and amounts in periodic transaction rules
|
|
or auto posting rules). It uses
|
|
|
|
o the symbol placement and decimal mark of the first amount seen
|
|
|
|
o the digit group marks of the first amount with digit group marks
|
|
|
|
o and the maximum number of decimal digits seen across all amounts.
|
|
|
|
And as fallback if no applicable amounts are found, it would use a de-
|
|
fault style, like $1000.00 (symbol on the left with no space, period as
|
|
decimal mark, and two decimal digits).
|
|
|
|
Finally, commodity styles can be overridden by the -c/--commodity-style
|
|
command line option.
|
|
|
|
Rounding
|
|
Amounts are stored internally as decimal numbers with up to 255 decimal
|
|
places. They are displayed with their original journal precisions by
|
|
print and print-like reports, and rounded to their display precision
|
|
(the number of decimal digits specified by the commodity display style)
|
|
by other reports. When rounding, hledger uses banker's rounding (it
|
|
rounds to the nearest even digit). So eg 0.5 displayed with zero deci-
|
|
mal digits appears as "0".
|
|
|
|
Number format
|
|
hledger will occasionally make some additional adjustments to number
|
|
formatting, eg adding a trailing decimal mark to disambiguate numbers
|
|
with digit group marks; for details, see Amount formatting, parseabil-
|
|
ity.
|
|
|
|
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 in-
|
|
ferred 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 im-
|
|
plicitly:
|
|
|
|
1. Write the price per unit, as @ UNITPRICE after the amount:
|
|
|
|
2009/1/1
|
|
assets:euros 100 @ $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 100 @@ $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 100 @@ $135, as in example 2:
|
|
|
|
2009/1/1
|
|
assets:euros 100 ; 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.
|
|
|
|
Note that the cost normally should be a positive amount, though it's
|
|
not required to be. This can be a little confusing, see discussion at
|
|
--infer-market-prices: market prices from transactions.
|
|
|
|
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 differ-
|
|
ently-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 con-
|
|
trol 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 or-
|
|
der 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 in-
|
|
clude, 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 1
|
|
b $-1
|
|
c -1
|
|
|
|
2013/1/2 ; These assertions succeed
|
|
a 0 = $1
|
|
a 0 = 1
|
|
b 0 == $-1
|
|
c 0 == -1
|
|
|
|
2013/1/3 ; This assertion fails as 'a' also contains 1
|
|
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 1
|
|
b
|
|
|
|
2013/1/2
|
|
a 0 == 0
|
|
a:usd 0 == $1
|
|
a:euro 0 == 1
|
|
|
|
Assertions and costs
|
|
Balance assertions ignore costs, and should normally be written without
|
|
one:
|
|
|
|
2019/1/1
|
|
(a) $1 @ 1 = $1
|
|
|
|
We do allow costs to be written in balance assertion amounts, however,
|
|
and print shows them, but 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 costs), and because
|
|
balance assignments do use costs (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.) You can write multiple tags separated by comma,
|
|
and/or you can add more comment lines and write more tags there.
|
|
|
|
Here five different tags are recorded: one on the checking account, two
|
|
on the transaction, and two on the expenses posting:
|
|
|
|
account assets:checking ; accounttag:
|
|
|
|
2017/1/16 bought groceries ; transactiontag-1:
|
|
; transactiontag-2:
|
|
assets:checking $-1
|
|
expenses:food $1 ; postingtag:, another-posting-tag:
|
|
|
|
You can list tag names with hledger tags [NAMEREGEX], or match by tag
|
|
name with a tag:NAMEREGEX query.
|
|
|
|
Tag inheritance
|
|
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 five tags (by inheriting from the account and transaction), and
|
|
the transaction also has all five tags (by acquiring from the expenses
|
|
posting).
|
|
|
|
Tag names
|
|
Tag names are currently not very clearly specified; any sequence of
|
|
non-whitespace characters followed by a colon may work.
|
|
|
|
The following tag names are generated by hledger or have special sig-
|
|
nificance to hledger, so you may want to avoid using them yourself:
|
|
|
|
o balances -- a balance assertions transaction generated by close
|
|
|
|
o retain -- a retain earnings transaction generated by close
|
|
|
|
o start -- a opening balances, closing balances or balance assignment
|
|
transaction generated by close
|
|
|
|
o generated-transaction -- a transaction generated by --forecast
|
|
|
|
o generated-posting -- a posting generated by --auto
|
|
|
|
o modified -- a transaction which has had postings added by --auto
|
|
|
|
o type -- declares an account's type in an account declaration
|
|
|
|
o t -- stores the (user defined, single letter) type of a 15m unit of
|
|
time parsed from timedot format
|
|
|
|
Some additional tag names with an underscore prefix are used internally
|
|
and not displayed in reports (but can be matched by queries):
|
|
|
|
o _generated-transaction
|
|
|
|
o _generated-posting
|
|
|
|
o _modified
|
|
|
|
o _conversion-matched
|
|
|
|
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
|
|
Besides transactions, there is something else you can put in a journal
|
|
file: directives. These are declarations, beginning with a keyword,
|
|
that modify hledger's behaviour. Some directives can have more spe-
|
|
cific subdirectives, indented below them. hledger's directives are
|
|
similar to Ledger's in many cases, but there are also many differences.
|
|
Directives are not required, but can be useful. Here are the main di-
|
|
rectives:
|
|
|
|
purpose directive
|
|
--------------------------------------------------------------------------
|
|
READING DATA:
|
|
Rewrite account names alias
|
|
Comment out sections of the file comment
|
|
Declare file's decimal mark, to help decimal-mark
|
|
parse amounts accurately
|
|
Include other data files include
|
|
GENERATING DATA:
|
|
Generate recurring transactions or bud- ~
|
|
get goals
|
|
Generate extra postings on existing =
|
|
transactions
|
|
CHECKING FOR ERRORS:
|
|
Define valid entities to provide more account, commodity, payee, tag
|
|
error checking
|
|
REPORTING:
|
|
Declare accounts' type and display order account
|
|
Declare commodity display styles commodity
|
|
Declare market prices P
|
|
|
|
Directives and multiple files
|
|
Directives vary in their scope, ie which journal entries and which in-
|
|
put files they affect. Most often, a directive will affect the follow-
|
|
ing entries and included files if any, until the end of the current
|
|
file - and no further. You might find this inconvenient! For example,
|
|
alias directives do not affect parent or sibling files. But there are
|
|
usually workarounds; for example, put alias directives in your top-most
|
|
file, before including other files.
|
|
|
|
The restriction, though it may be annoying at first, is in a good
|
|
cause; it allows reports to be stable and deterministic, independent of
|
|
the order of input. Without it, reports could show different numbers
|
|
depending on the order of -f options, or the positions of include di-
|
|
rectives in your files.
|
|
|
|
Directive effects
|
|
Here are all hledger's directives, with their effects and scope sum-
|
|
marised - nine main directives, plus four others which we consider
|
|
non-essential:
|
|
|
|
di- what it does ends
|
|
rec- at
|
|
tive file
|
|
end?
|
|
--------------------------------------------------------------------------------------
|
|
ac- Declares an account, for checking all entries in all files; and N
|
|
count 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
|
|
com- Ignores part of the journal file, until end of current file or Y
|
|
ment end comment.
|
|
com- Declares up to four things: 1. a commodity symbol, for checking N,Y,N,N
|
|
mod- all amounts in all files 2. the decimal mark for parsing
|
|
ity 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-mark ties in following entries until next decimal-mark or end of cur-
|
|
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 ig-
|
|
Ledger nored.
|
|
direc-
|
|
tives
|
|
|
|
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 ac-
|
|
count name, eg:
|
|
|
|
account assets:bank:checking
|
|
|
|
Note, however, that accounts declared in account directives are not al-
|
|
lowed 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 de-
|
|
clared 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 ac-
|
|
count 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 in-
|
|
cluded 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 ac-
|
|
count 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 or-
|
|
der
|
|
|
|
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 (de-
|
|
scribed below). But generally we recommend you declare types explic-
|
|
itly, by adding a type: tag to your top-level account directives. Sub-
|
|
accounts 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 re-
|
|
porting).)
|
|
|
|
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 ac-
|
|
count 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 re-
|
|
place any occurrence of the old account name with the new one. Subac-
|
|
counts 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 ex-
|
|
pression.)
|
|
|
|
Eg:
|
|
|
|
alias /REGEX/ = REPLACEMENT
|
|
|
|
or:
|
|
|
|
$ hledger --alias '/REGEX/=REPLACEMENT' ...
|
|
|
|
Any part of an account name matched by REGEX will be replaced by RE-
|
|
PLACEMENT. 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. In-
|
|
cluding the aliases doesn't work either:
|
|
|
|
include a.aliases
|
|
|
|
2023-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
|
|
|
|
2023-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 ef-
|
|
fect.
|
|
|
|
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
|
|
The commodity directive performs several functions:
|
|
|
|
1. It declares which commodity symbols may be used in the journal, en-
|
|
abling useful error checking with strict mode or the check command.
|
|
(See Commodity error checking below.)
|
|
|
|
2. It declares the precision with which this commodity's amounts should
|
|
be compared when checking for balanced transactions.
|
|
|
|
3. It declares how this commodity's amounts should be displayed, eg
|
|
their symbol placement, digit group mark if any, digit group sizes,
|
|
decimal mark (period or comma), and the number of decimal places.
|
|
(See Commodity display style above.)
|
|
|
|
4. It sets which decimal mark (period or comma) to expect when parsing
|
|
subsequent amounts in this commodity (if there is no decimal-mark
|
|
directive in effect. See Decimal marks, digit group marks above.
|
|
For related dev discussion, see #793.)
|
|
|
|
Declaring commodities solves several common parsing/display problems,
|
|
so we recommend it. Generally you should put commodity directives at
|
|
the top of your journal file (because function 4 is position-sensi-
|
|
tive).
|
|
|
|
Commodity directive syntax
|
|
A commodity directive is normally the word commodity followed by a sam-
|
|
ple amount (and optionally a comment). Only the amount's symbol and
|
|
format is significant. Eg:
|
|
|
|
commodity $1000.00
|
|
commodity 1.000,00 EUR
|
|
commodity 1 000 000.0000 ; the no-symbol commodity
|
|
|
|
Commodities do not have tags (tags in the comment will be ignored).
|
|
|
|
A commodity directive's sample amount must always include a period or
|
|
comma decimal mark (this rule helps disambiguate decimal marks and
|
|
digit group marks). If you don't want to show any decimal digits,
|
|
write the decimal mark at the end:
|
|
|
|
commodity 1000. AAAA ; show AAAA with no decimals
|
|
|
|
Commodity symbols containing spaces, numbers, or punctuation must be
|
|
enclosed in double quotes, as usual:
|
|
|
|
commodity 1.0000 "AAAA 2023"
|
|
|
|
Commodity directives normally include a sample amount, but can declare
|
|
only a symbol (ie, just function 1 above):
|
|
|
|
commodity $
|
|
commodity INR
|
|
commodity "AAAA 2023"
|
|
commodity "" ; the no-symbol commodity
|
|
|
|
Commodity directives may also be written with an indented format subdi-
|
|
rective, as in Ledger. The symbol is repeated and must be the same in
|
|
both places. Other subdirectives are currently ignored:
|
|
|
|
; display indian rupees with currency name on the left,
|
|
; thousands, lakhs and crores comma-separated,
|
|
; period as decimal point, and two decimal places.
|
|
commodity INR
|
|
format INR 1,00,00,000.00
|
|
an unsupported subdirective ; ignored by hledger
|
|
|
|
Commodity error checking
|
|
In strict mode (-s/--strict) (or when you run hledger check commodi-
|
|
ties), hledger will report an error if an undeclared commodity symbol
|
|
is used. (With one exception: zero amounts are always allowed to have
|
|
no commodity symbol.) It works like account error checking (described
|
|
above).
|
|
|
|
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 re-
|
|
quired) matches 0 or more subdirectories. It's not super convenient
|
|
since you have to avoid include cycles and including directories, but
|
|
this can be done, eg: include */**/*.journal.
|
|
|
|
The path may also be prefixed to force a specific file format, overrid-
|
|
ing the file extension (as described in Data formats): include time-
|
|
dot:~/notes/2023*.md.
|
|
|
|
P directive
|
|
The P directive declares a market price, which is a conversion rate be-
|
|
tween 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. Ex-
|
|
amples:
|
|
|
|
# one euro was worth $1.35 from 2009-01-01 onward:
|
|
P 2009-01-01 $1.35
|
|
|
|
# and $1.40 from 2010-01-01 onward:
|
|
P 2010-01-01 $1.40
|
|
|
|
The -V, -X and --value flags use these market prices to show amount
|
|
values in another commodity. See Value reporting.
|
|
|
|
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 ; a comment
|
|
|
|
Payees do not have tags (tags in the comment will be ignored).
|
|
|
|
To declare the empty payee name, use "".
|
|
|
|
payee ""
|
|
|
|
Ledger-style indented subdirectives, if any, are currently ignored.
|
|
|
|
tag directive
|
|
tag TAGNAME
|
|
|
|
This directive can be used to declare a limited set of tag names al-
|
|
lowed 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 a "periodic rule" which generates temporary
|
|
extra transactions, usually recurring at some interval, when hledger is
|
|
run with the --forecast flag. These "forecast transactions" are useful
|
|
for forecasting future activity. They exist only for the duration of
|
|
the report, and only when --forecast is used; they are not saved in the
|
|
journal file by hledger.
|
|
|
|
Periodic rules also have a second use: with the --budget flag they set
|
|
budget goals for budgeting.
|
|
|
|
Periodic rules can be a little tricky, so before you use them, read
|
|
this whole section, or at least the following 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 im-
|
|
provement, 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
|
|
2023/01, which is equivalent to ~ every 10th day of month from
|
|
2023/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-pe-
|
|
riod 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 re-
|
|
sults 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 2023"
|
|
; ||
|
|
; vv
|
|
~ every 2 months in 2023, 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 ex-
|
|
pression.
|
|
|
|
Auto postings
|
|
The = directive declares an "auto posting rule", which adds extra post-
|
|
ings to existing transactions. (Remember, postings are the account
|
|
name & amount lines below a transaction's date & description.)
|
|
|
|
In the journal, an auto posting rule looks quite like a transaction,
|
|
but instead of date and description it has = (mnemonic: "match") and a
|
|
query, like this:
|
|
|
|
= QUERY
|
|
ACCOUNT AMOUNT
|
|
...
|
|
|
|
Queries are just like command line queries; an account name substring
|
|
is most common. Query terms containing spaces should be enclosed in
|
|
single or double quotes.
|
|
|
|
Each = rule works like this: when hledger is run with the --auto flag,
|
|
wherever the QUERY matches a posting in the journal, the rule's post-
|
|
ings are added to that transaction, immediately below the matched post-
|
|
ing. Note these generated postings are temporary, existing only for
|
|
the duration of the report, and only when --auto is used; they are not
|
|
saved in the journal file by hledger.
|
|
|
|
Generated postings' amounts can depend on the matched posting's amount.
|
|
So auto postings can be useful for, eg, adding tax postings with a
|
|
standard percentage. AMOUNT can be:
|
|
|
|
o a number with no commodity symbol, like 2. The matched posting's
|
|
commodity symbol will be added to this.
|
|
|
|
o a normal amount with a commodity symbol, like $2. This will be used
|
|
as-is.
|
|
|
|
o an asterisk followed by a number, like *2. This will multiply the
|
|
matched posting's amount (and total price, if any) by the number.
|
|
|
|
o an asterisk followed by an amount with commodity symbol, like *$2.
|
|
This multiplies and also replaces the commodity symbol with this new
|
|
one.
|
|
|
|
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
|
|
|
|
Note that depending fully on generated data such as this has some draw-
|
|
backs - it's less portable, less future-proof, less auditable by oth-
|
|
ers, and less robust (eg your balance assertions will depend on whether
|
|
you use or don't use --auto). An alternative is to use auto postings
|
|
in "one time" fashion - use them to help build a complex journal entry,
|
|
view it with hledger print --auto, and then copy that output into the
|
|
journal file to make it permanent.
|
|
|
|
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".
|
|
|
|
Auto postings on forecast transactions only
|
|
Tip: you can can make auto postings that will apply to forecast trans-
|
|
actions but not recorded transactions, by adding tag:_generated-trans-
|
|
action to their QUERY. This can be useful when generating new journal
|
|
entries to be saved in the journal.
|
|
|
|
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.
|
|
|
|
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 fi-
|
|
nancial data less portable, less future-proof, and less trustworthy in
|
|
an audit.
|
|
|
|
Balance assignments and costs
|
|
A cost in a balance assignment will cause the calculated amount to have
|
|
that cost attached:
|
|
|
|
2019/1/1
|
|
(a) = $1 @ 2
|
|
|
|
$ hledger print --explicit
|
|
2019-01-01
|
|
(a) $1 @ 2 = $1 @ 2
|
|
|
|
Balance assignments and multiple files
|
|
Balance assignments handle multiple files like balance assertions.
|
|
They see balance from other files previously included from the current
|
|
file, but not from previous sibling or parent files.
|
|
|
|
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 di-
|
|
rective (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 di-
|
|
rective 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
|
|
portable, 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, al-
|
|
lowing 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 ((some:account)) is
|
|
called a unbalanced virtual posting. Such postings do not participate
|
|
in transaction balancing. (And if you write them without an amount, a
|
|
zero amount is always inferred.) These can occasionally be convenient
|
|
for special circumstances, but they violate double entry bookkeeping
|
|
and make your data less portable across applications, so many people
|
|
avoid using them at all.
|
|
|
|
A posting with brackets around the account name ([some:account]) is
|
|
called a balanced virtual posting. The balanced virtual postings in a
|
|
transaction must add up to zero, just like ordinary postings, but sepa-
|
|
rately from them. These are not part of double entry bookkeeping ei-
|
|
ther, but they are at least balanced. An example:
|
|
|
|
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
|
|
|
|
Ordinary 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.
|
|
|
|
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 at-
|
|
tributes.
|
|
|
|
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.)
|
|
|
|
source optionally declare which file to read data
|
|
from
|
|
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 op-
|
|
tionally 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 assertions/as-
|
|
signments to generate
|
|
include inline another CSV rules file
|
|
|
|
Working with CSV tips can be found below, including How CSV rules are
|
|
evaluated.
|
|
|
|
source
|
|
If you tell hledger to read a csv file with -f foo.csv, it will look
|
|
for rules in foo.csv.rules. Or, you can tell it to read the rules
|
|
file, with -f foo.csv.rules, and it will look for data in foo.csv
|
|
(since 1.30).
|
|
|
|
These are mostly equivalent, but the second method provides some extra
|
|
features. For one, the data file can be missing, without causing an
|
|
error; it is just considered empty. And, you can specify a different
|
|
data file by adding a "source" rule:
|
|
|
|
source ./Checking1.csv
|
|
|
|
If you specify just a file name with no path, hledger will look for it
|
|
in your system's downloads directory (~/Downloads, currently):
|
|
|
|
source Checking1.csv
|
|
|
|
And if you specify a glob pattern, hledger will read the most recent of
|
|
the matched files (useful with repeated downloads):
|
|
|
|
source Checking1*.csv
|
|
|
|
See also "Working with CSV > Reading files specified by rule".
|
|
|
|
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. You'll need this whenever your CSV data contains header lines.
|
|
Note, empty and blank lines are skipped automatically, so you don't
|
|
need to count those.
|
|
|
|
skip has a second meaning: it can be used inside if blocks (described
|
|
below), to skip one or more records whenever the condition is true.
|
|
Records skipped in this way are ignored, except they are still required
|
|
to be valid CSV.
|
|
|
|
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 same-day transactions. Usually it can
|
|
auto-detect how the CSV records are ordered. But if it encounters CSV
|
|
where all records are on the same date, it assumes that the records are
|
|
oldest first. If in fact the CSV'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
|
|
If CSV records within a single day are ordered opposite to the overall
|
|
record order, you can add the intra-day-reversed rule to improve the
|
|
order of journal entries. Eg, here the overall record order is newest
|
|
first, but same-day records are oldest first:
|
|
|
|
2022-10-02, txn 3...
|
|
2022-10-02, txn 4...
|
|
2022-10-01, txn 1...
|
|
2022-10-01, txn 2...
|
|
|
|
# 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 re-
|
|
placed 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 either by their 1-based position in the
|
|
CSV record (%N) or by the name they were given in the fields list
|
|
(%CSVFIELD), and regular expression match groups (\N).
|
|
|
|
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 " be-
|
|
comes 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 as-
|
|
signment, 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 ways to set posting amounts from CSV, useful in dif-
|
|
ferent situations.
|
|
|
|
1. amount is the oldest and simplest. Assigning to this sets the
|
|
amount of the first and second postings. In the second posting, the
|
|
amount will be negated; also, if it has a cost attached, it will be
|
|
converted to cost.
|
|
|
|
2. amount-in and amount-out work exactly like the above, but should be
|
|
used when the CSV has two amount fields (such as "Debit" and
|
|
"Credit", or "Inflow" and "Outflow"). Whichever field has a
|
|
non-zero value will be used as the amount of the first and second
|
|
postings. Here are some tips to avoid confusion:
|
|
|
|
o It's not "amount-in for posting 1 and amount-out for posting 2",
|
|
it is "extract a single amount from the amount-in or amount-out
|
|
field, and use that for posting 1 and (negated) for posting 2".
|
|
|
|
o Don't use both amount and amount-in/amount-out in the same rules
|
|
file; choose based on whether the amount is in a single CSV field
|
|
or spread across two fields.
|
|
|
|
o In each record, at most one of the two CSV fields should contain
|
|
a non-zero amount; the other field must contain a zero or noth-
|
|
ing.
|
|
|
|
o hledger assumes both CSV fields contain unsigned numbers, and it
|
|
automatically negates the amount-out values.
|
|
|
|
o If the data doesn't fit these requirements, you'll probably need
|
|
an if rule (see below).
|
|
|
|
3. amountN (where N is a number from 1 to 99) sets the amount of only a
|
|
single posting: the Nth posting in the transaction. You'll usually
|
|
need at least two such assignments to make a balanced transaction.
|
|
You can also generate more than two postings, to represent more com-
|
|
plex transactions. The posting numbers don't have to be consecu-
|
|
tive; with if rules, higher posting numbers can be useful to ensure
|
|
a certain order of postings.
|
|
|
|
4. amountN-in and amountN-out work exactly like the above, but should
|
|
be used when the CSV has two amount fields. This is analogous to
|
|
amount-in and amount-out, and those tips also apply here.
|
|
|
|
5. Remember that a fields list can also do assignments. So in a fields
|
|
list if you name a CSV field "amount", that counts as assigning to
|
|
amount. (If you don't want that, call it something else in the
|
|
fields list, like "amount_".)
|
|
|
|
6. The above don't handle every situation; if you need more flexibil-
|
|
ity, use an if rule to set amounts conditionally. See "Working with
|
|
CSV > Setting amounts" below for more on this and on amount-setting
|
|
generally.
|
|
|
|
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 ap-
|
|
plied. 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).
|
|
|
|
What matchers match
|
|
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:
|
|
|
|
2023-01-01; "Acme, Inc."; 1,000
|
|
|
|
the regex would see, and try to match, this modified record text:
|
|
|
|
2023-01-01,Acme, Inc., 1,000
|
|
|
|
Combining matchers
|
|
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)
|
|
|
|
o Added in 1.32 When a matcher is preceded by an exclamation mark (!),
|
|
the matcher is negated (it may not match).
|
|
|
|
Currently there is a limitation: you can't use both & and ! on the same
|
|
line (you can't AND a negated matcher).
|
|
|
|
Match groups
|
|
Added in 1.32
|
|
|
|
Matchers can define match groups: parenthesised portions of the regular
|
|
expression which are available for reference in field assignments.
|
|
Groups are enclosed in regular parentheses (( and )) and can be nested.
|
|
Each group is available in field assignments using the token \N, where
|
|
N is an index into the match groups for this conditional block (e.g.
|
|
\1, \2, etc.).
|
|
|
|
Example: Warp credit card payment postings to the beginning of the
|
|
billing period (Month start), to match how they are presented in state-
|
|
ments, using posting dates:
|
|
|
|
if %date (....-..)-..
|
|
comment2 date:\1-01
|
|
|
|
Another example: Read the expense account from the CSV field, but throw
|
|
away a prefix:
|
|
|
|
if %account1 liabilities:family:(expenses:.*)
|
|
account1 \1
|
|
|
|
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 this if table's field sepa-
|
|
rator. It is unrelated to the separator used in the CSV file. It
|
|
should be a non-alphanumeric character like , or | that does not appear
|
|
anywhere else in the table (it should not be used in field names or
|
|
matchers or values, and it cannot be escaped with a backslash).
|
|
|
|
Each line must contain the same number of separators; empty values are
|
|
allowed. Whitespace can be used in the matcher lines for readability
|
|
(but not in the if line, currently). The table must be terminated by
|
|
an empty line (or end of file).
|
|
|
|
An if table like the above is interpreted as follows: try all of the
|
|
matchers; whenever a matcher succeeds, assign all of the values on that
|
|
line to the corresponding hledger fields; later lines can overrider
|
|
earlier ones. It is equivalent to this sequence of if blocks:
|
|
|
|
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,
|
|
2023/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.
|
|
|
|
Reading files specified by rule
|
|
Instead of specifying a CSV file in the command line, you can specify a
|
|
rules file, as in hledger -f foo.csv.rules CMD. By default this will
|
|
read data from foo.csv in the same directory, but you can add a source
|
|
rule to specify a different data file, perhaps located in your web
|
|
browser's download directory.
|
|
|
|
This feature was added in hledger 1.30, so you won't see it in most CSV
|
|
rules examples. But it helps remove some of the busywork of managing
|
|
CSV downloads. Most of your financial institutions's default CSV file-
|
|
names are different and can be recognised by a glob pattern. So you
|
|
can put a rule like source Checking1*.csv in foo-checking.csv.rules,
|
|
and then periodically follow a workflow like:
|
|
|
|
1. Download CSV from Foo's website, using your browser's defaults
|
|
|
|
2. Run hledger import foo-checking.csv.rules to import any new transac-
|
|
tions
|
|
|
|
After import, you can: discard the CSV, or leave it where it is for a
|
|
while, or move it into your archives, as you prefer. If you do noth-
|
|
ing, next time your browser will save something like Checking1-2.csv,
|
|
and hledger will use that because of the * wild card and because it is
|
|
the most recent.
|
|
|
|
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 as-
|
|
sertions 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 for amount-set-
|
|
ting:
|
|
|
|
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 two CSV fields (such as Debit and Credit, or In
|
|
and Out):
|
|
a. If both fields are unsigned:
|
|
Assign one field to amountN-in and the other to amountN-out.
|
|
hledger will automatically negate the "out" field, and will use
|
|
whichever field value is non-zero as posting N's amount.
|
|
|
|
b. If either field is signed:
|
|
You will probably need to override hledger's sign for one or the
|
|
other field, as in the following example:
|
|
|
|
# Negate the -out value, but only if it is not empty:
|
|
fields date, description, amount1-in, amount1-out
|
|
if %amount1-out [1-9]
|
|
amount1-out -%amount1-out
|
|
|
|
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 con-
|
|
taining 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 making it easier to parse and to reverse
|
|
amount signs. (This only works for whole amounts, not for cost amounts
|
|
such as COST in amount1 AMT @ COST):
|
|
|
|
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
|
|
"".
|
|
|
|
It's not possible (without preprocessing the CSV) to set an amount to
|
|
its absolute value, ie discard its sign.
|
|
|
|
Setting currency/commodity
|
|
If the currency/commodity symbol is included in the CSV's amount
|
|
field(s):
|
|
|
|
2023-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
|
|
|
|
2023-01-01 foo
|
|
expenses:unknown $123.00
|
|
income:unknown $-123.00
|
|
|
|
If the currency is provided as a separate CSV field:
|
|
|
|
2023-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
|
|
|
|
2023-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
|
|
|
|
2023-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 re-
|
|
peated, 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 re-
|
|
maining 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 as-
|
|
signed 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 op-
|
|
tional. The timezone, if present, must be four digits and is ignored
|
|
(currently the time is always interpreted as a local time). Lines be-
|
|
ginning with # or ; or *, and blank lines, are ignored.
|
|
|
|
i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags:
|
|
o 2015/03/30 09:20:00
|
|
i 2015/03/31 22:21:45 another:account
|
|
o 2015/04/01 02:00:34
|
|
|
|
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 2 spaces ; optional comment, tags:
|
|
(some account) 0.33h
|
|
|
|
2015-03-31 * 22:21-23:59
|
|
(another:account) 1.64h
|
|
|
|
2015-04-01 * 00:00-02:00
|
|
(another:account) 2.01h
|
|
|
|
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 time-
|
|
clock-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 more convenient for quick, approxi-
|
|
mate, and retroactive time logging, and more human-readable (you can
|
|
see at a glance where time was spent). A quick example:
|
|
|
|
2023-05-01
|
|
hom:errands .... .... ; two hours; the space is ignored
|
|
fos:hledger:timedot .. ; half an hour
|
|
per:admin:finance ; no time spent yet
|
|
|
|
hledger reads this as a transaction on this day with three (unbalanced)
|
|
postings, where each dot represents "0.25". No commodity symbol is as-
|
|
sumed, but we typically interpret it as hours.
|
|
|
|
$ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required
|
|
2023-05-01 *
|
|
(hom:errands) 2.00 ; two hours
|
|
(fos:hledger:timedot) 0.50 ; half an hour
|
|
(per:admin:finance) 0
|
|
|
|
A timedot file contains a series of transactions (usually one per day).
|
|
Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be
|
|
followed on the same line by a transaction description, and/or a trans-
|
|
action comment following a semicolon.
|
|
|
|
After the date line are zero or more time postings, consisting of:
|
|
|
|
o An account name - any hledger-style account name, optionally in-
|
|
dented.
|
|
|
|
o Two or more spaces - required if there is an amount (as in journal
|
|
format).
|
|
|
|
o A timedot amount, which can be
|
|
|
|
o empty (representing zero)
|
|
|
|
o a number, optionally followed by a unit s, m, h, d, w, mo, or y,
|
|
representing a precise number of seconds, minutes, hours, days
|
|
weeks, months or years (hours is assumed by default), which will be
|
|
converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d =
|
|
1w, 30d = 1mo, 365d = 1y.
|
|
|
|
o one or more dots (period characters), each representing 0.25.
|
|
These are the dots in "timedot". Spaces are ignored and can be
|
|
used for grouping/alignment.
|
|
|
|
o Added in 1.32 one or more letters. These are like dots but they
|
|
also generate a tag t: (short for "type") with the letter as its
|
|
value, and a separate posting for each of the values. This pro-
|
|
vides a second dimension of categorisation, viewable in reports
|
|
with --pivot t.
|
|
|
|
o An optional comment following a semicolon (a hledger-style posting
|
|
comment).
|
|
|
|
There is some flexibility to help with keeping time log data and notes
|
|
in the same file:
|
|
|
|
o Blank lines and lines beginning with # or ; are ignored.
|
|
|
|
o After the first date line, lines which do not contain a double space
|
|
are parsed as postings with zero amount. (hledger's register reports
|
|
will show these if you add -E).
|
|
|
|
o Before the first date line, lines beginning with * (eg org headings)
|
|
are ignored. And from the first date line onward, Emacs org mode
|
|
heading prefixes at the start of lines (one or more *'s followed by a
|
|
space) will be ignored. This means the time log can also be a org
|
|
outline.
|
|
|
|
Timedot examples
|
|
Numbers:
|
|
|
|
2016/2/3
|
|
inc:client1 4
|
|
fos:hledger 3h
|
|
biz:research 60m
|
|
|
|
Dots:
|
|
|
|
# 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 .
|
|
|
|
$ 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
|
|
|
|
Letters:
|
|
|
|
# Activity types:
|
|
# c cleanup/catchup/repair
|
|
# e enhancement
|
|
# s support
|
|
# l learning/research
|
|
|
|
2023-11-01
|
|
work:adm ccecces
|
|
|
|
$ hledger -f a.timedot print
|
|
2023-11-01
|
|
(work:adm) 1 ; t:c
|
|
(work:adm) 0.5 ; t:e
|
|
(work:adm) 0.25 ; t:s
|
|
|
|
$ hledger -f a.timedot bal
|
|
1.75 work:adm
|
|
--------------------
|
|
1.75
|
|
|
|
$ hledger -f a.timedot bal --pivot t
|
|
1.00 c
|
|
0.50 e
|
|
0.25 s
|
|
--------------------
|
|
1.75
|
|
|
|
Org:
|
|
|
|
* 2023 Work Diary
|
|
** Q1
|
|
*** 2023-02-29
|
|
**** DONE
|
|
0700 yoga
|
|
**** UNPLANNED
|
|
**** BEGUN
|
|
hom:chores
|
|
cleaning ...
|
|
water plants
|
|
outdoor - one full watering can
|
|
indoor - light watering
|
|
**** TODO
|
|
adm:planning: trip
|
|
*** LATER
|
|
|
|
Using . as account name separator:
|
|
|
|
2016/2/4
|
|
fos.hledger.timedot 4h
|
|
fos.ledger ..
|
|
|
|
$ hledger -f a.timedot --alias '/\./=:' bal -t
|
|
4.50 fos
|
|
4.00 hledger:timedot
|
|
0.50 ledger
|
|
--------------------
|
|
4.50
|
|
|
|
PART 3: REPORTING CONCEPTS
|
|
Amount formatting, parseability
|
|
If you're wondering why your print report sometimes shows trailing dec-
|
|
imal marks, with no decimal digits; it does this when showing amounts
|
|
that have digit group marks but no decimal digits, to disambiguate them
|
|
and allow them to be re-parsed reliably (see also Decimal marks, digit
|
|
group marks. Eg:
|
|
|
|
commodity $1,000.00
|
|
|
|
2023-01-02
|
|
(a) $1000
|
|
|
|
$ hledger print
|
|
2023-01-02
|
|
(a) $1,000.
|
|
|
|
If this is a problem (eg when exporting to Ledger), you can avoid it by
|
|
disabling digit group marks, eg with -c/--commodity (for each affected
|
|
commodity):
|
|
|
|
$ hledger print -c '$1000.00'
|
|
2023-01-02
|
|
(a) $1000
|
|
|
|
or by forcing print to always show decimal digits, with --round:
|
|
|
|
$ hledger print -c '$1,000.00' --round=soft
|
|
2023-01-02
|
|
(a) $1,000.00
|
|
|
|
More generally: hledger output falls into three rough categories, which
|
|
format amounts a little bit differently to suit different consumers:
|
|
|
|
1. "hledger-readable output" - should be readable by hledger (and by
|
|
humans)
|
|
|
|
o This is produced by reports that show full journal entries: print,
|
|
import, close, rewrite etc.
|
|
|
|
o It shows amounts with their original journal precisions, which may
|
|
not be consistent.
|
|
|
|
o It adds a trailing decimal mark when needed to avoid showing ambigu-
|
|
ous amounts.
|
|
|
|
o It can be parsed reliably (by hledger and ledger2beancount at least,
|
|
but perhaps not by Ledger..)
|
|
|
|
2. "human-readable output" - usually for humans
|
|
|
|
o This is produced by all other reports.
|
|
|
|
o It shows amounts with standard display precisions, which will be con-
|
|
sistent within each commodity.
|
|
|
|
o It shows ambiguous amounts unmodified.
|
|
|
|
o It can be parsed reliably in the context of a known report (when you
|
|
know decimals are consistently not being shown, you can assume a sin-
|
|
gle mark is a digit group mark).
|
|
|
|
3. "machine-readable output" - usually for other software
|
|
|
|
o This is produced by all reports when an output format like csv, tsv,
|
|
json, or sql is selected.
|
|
|
|
o It shows amounts as 1 or 2 do, but without digit group marks.
|
|
|
|
o It can be parsed reliably (if needed, the decimal mark can be changed
|
|
with -c/--commodity-style).
|
|
|
|
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 re-
|
|
placed 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
|
|
When there is a report interval (other than daily), report start/end
|
|
dates which have been inferred, eg from the journal, are automatically
|
|
adjusted to natural period boundaries. This is convenient for produc-
|
|
ing simple periodic reports. More precisely:
|
|
|
|
o an inferred start date will be adjusted earlier if needed to fall on
|
|
a natural period boundary
|
|
|
|
o an inferred end date will be adjusted later if needed to make the
|
|
last period the same length as the others.
|
|
|
|
By contrast, start/end dates which have been specified explicitly, with
|
|
-b, -e, -p or date:, will not be adjusted (since hledger 1.29). This
|
|
makes it possible to specify non-standard report periods, but it also
|
|
means that if you are specifying a start date, you should pick one
|
|
that's on a period boundary if you want to see simple report period
|
|
headings.
|
|
|
|
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
|
|
spaces 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,wed,fri" Mon-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 ac-
|
|
counts 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 query arguments, to
|
|
restrict their scope. Multiple query terms can be provided to build up
|
|
a more complex query.
|
|
|
|
o By default, a query term is interpreted as a case-insensitive sub-
|
|
string pattern for matching account names:
|
|
|
|
car:fuel
|
|
dining groceries
|
|
o Patterns containing spaces or other special characters must be en-
|
|
closed in single or double quotes:
|
|
|
|
'personal care'
|
|
o These patterns are actually regular expressions, so you can add reg-
|
|
exp metacharacters for more precision (see "Regular expressions"
|
|
above for details):
|
|
|
|
'^expenses\b'
|
|
'food$'
|
|
'fuel|repair'
|
|
'accounts (payable|receivable)'
|
|
o To match something other than account name, add one of the query type
|
|
prefixes described in "Query types" below:
|
|
|
|
date:202312-
|
|
status:
|
|
desc:amazon
|
|
cur:USD
|
|
cur:\\$
|
|
amt:'>0'
|
|
o Add a not: prefix to negate a term:
|
|
|
|
not:status:'*'
|
|
not:desc:'opening|closing'
|
|
not:cur:USD
|
|
o Terms with different types are AND-ed, terms with the same type are
|
|
OR-ed (mostly; see "Combining query terms" below). The following
|
|
query:
|
|
|
|
date:2022 desc:amazon desc:amzn
|
|
|
|
is interpreted as:
|
|
|
|
date is in 2022 AND ( transaction description contains "amazon" OR
|
|
"amzn" )
|
|
|
|
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 or REGEX
|
|
Match account names containing this case insensitive regular expres-
|
|
sion. This is the default query type, so we usually don't bother writ-
|
|
ing the "acct:" prefix.
|
|
|
|
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 es-
|
|
caping. 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 in-
|
|
terval. 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.
|
|
|
|
expr:"TERM AND NOT (TERM OR TERM)" (eg)
|
|
Match with a boolean combination of queries (which must be enclosed in
|
|
quotes). See Combining query terms below.
|
|
|
|
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 space-separated 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.
|
|
|
|
We also support more complex boolean queries with the 'expr:' prefix.
|
|
This allows one to combine queries using one of three operators: AND,
|
|
OR, and NOT, where NOT is different syntax for 'not:'.
|
|
|
|
Examples of such queries are:
|
|
|
|
o Match transactions with 'cool' in the description AND with the 'A'
|
|
tag
|
|
|
|
expr:"desc:cool AND tag:A"
|
|
|
|
o Match transactions NOT to the 'expenses:food' account OR with the 'A'
|
|
tag
|
|
|
|
expr:"NOT expenses:food OR tag:A"
|
|
|
|
o Match transactions NOT involving the 'expenses:food' account OR with
|
|
the 'A' tag AND involving the 'expenses:drink' account. (the AND is
|
|
implicitly added by space-separation, following the rules above)
|
|
|
|
expr:"expenses:food OR (tag:A expenses:drink)"
|
|
|
|
Queries and command options
|
|
Some queries can also be expressed as command-line options: depth:2 is
|
|
equivalent to --depth 2, date:2023 is equivalent to -p 2023, 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 re-
|
|
ports, 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 re-
|
|
versed, 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 re-
|
|
ports, 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 ac-
|
|
count names, causing amounts to be grouped and summed by that field's
|
|
value instead. FIELD can be any of the transaction fields acct, sta-
|
|
tus, code, desc, 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. Multiple, colon-delimited fields
|
|
can be pivoted simultaneously, generating a hierarchical account name.
|
|
|
|
Some examples:
|
|
|
|
2016/02/16 Yearly Dues Payment
|
|
assets:bank account 2 EUR
|
|
income:dues -2 EUR ; member: John Doe, kind: Lifetime
|
|
|
|
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
|
|
|
|
Hierarchical reports can be generated with multiple pivots:
|
|
|
|
$ hledger balance Income:Dues --pivot kind:member
|
|
-2 EUR Lifetime:John Doe
|
|
--------------------
|
|
-2 EUR
|
|
|
|
Generating data
|
|
hledger has several features for generating data, such as:
|
|
|
|
o Periodic transaction rules can generate single or repeating transac-
|
|
tions following a template. These are usually dated in the future,
|
|
eg to help with forecasting. They are activated by the --forecast
|
|
option.
|
|
|
|
o The balance command's --budget option uses these same periodic rules
|
|
to generate goals for the budget report.
|
|
|
|
o Auto posting rules can generate extra postings on certain matched
|
|
transactions. They are always applied to forecast transactions; with
|
|
the --auto flag they are applied to transactions recorded in the
|
|
journal as well.
|
|
|
|
o The --infer-equity flag infers missing conversion equity postings
|
|
from @/@@ costs. And the inverse --infer-costs flag infers missing
|
|
@/@@ costs from conversion equity postings.
|
|
|
|
Generated data of this kind is temporary, existing only at report time.
|
|
But you can see it in the output of hledger print, and you can save
|
|
that to your journal, in effect converting it from temporary generated
|
|
data to permanent recorded data. This could be useful as a data entry
|
|
aid.
|
|
|
|
If you are wondering what data is being generated and why, add the
|
|
--verbose-tags flag. In hledger print output you will see extra tags
|
|
like generated-transaction, generated-posting, and modified on gener-
|
|
ated/modified data. Also, even without --verbose-tags, generated data
|
|
always has equivalen hidden tags (with an underscore prefix), so eg you
|
|
could match generated transactions with tag:_generated-transaction.
|
|
|
|
Forecasting
|
|
Forecasting, or speculative future reporting, can be useful for esti-
|
|
mating future balances, or for exploring different future scenarios.
|
|
|
|
The simplest and most flexible way to do it with hledger is to manually
|
|
record a bunch of future-dated transactions. You could keep these in a
|
|
separate future.journal and include that with -f only when you want to
|
|
see them.
|
|
|
|
--forecast
|
|
There is another way: with the --forecast option, hledger can generate
|
|
temporary "forecast transactions" for reporting purposes, according to
|
|
periodic transaction rules defined in the journal. Each rule can gen-
|
|
erate multiple recurring transactions, so by changing one rule you can
|
|
change many forecasted transactions.
|
|
|
|
Forecast transactions usually start after ordinary transactions end.
|
|
By default, they begin after your latest-dated ordinary transaction, or
|
|
today, whichever is later, and they end six months from today. (The
|
|
exact rules are a little more complicated, and are given below.)
|
|
|
|
This is the "forecast period", which need not be the same as the report
|
|
period. You can override it - eg to forecast farther into the future,
|
|
or to force forecast transactions to overlap your ordinary transactions
|
|
- by giving the --forecast option a period expression argument, like
|
|
--forecast=..2099 or --forecast=2023-02-15... Note that the = is re-
|
|
quired.
|
|
|
|
Inspecting forecast transactions
|
|
print is the best command for inspecting and troubleshooting forecast
|
|
transactions. Eg:
|
|
|
|
~ monthly from 2022-12-20 rent
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
|
|
$ hledger print --forecast --today=2023/4/21
|
|
2023-05-20 rent
|
|
; generated-transaction: ~ monthly from 2022-12-20
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
|
|
2023-06-20 rent
|
|
; generated-transaction: ~ monthly from 2022-12-20
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
|
|
2023-07-20 rent
|
|
; generated-transaction: ~ monthly from 2022-12-20
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
|
|
2023-08-20 rent
|
|
; generated-transaction: ~ monthly from 2022-12-20
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
|
|
2023-09-20 rent
|
|
; generated-transaction: ~ monthly from 2022-12-20
|
|
assets:bank:checking
|
|
expenses:rent $1000
|
|
|
|
Here there are no ordinary transactions, so the forecasted transactions
|
|
begin on the first occurence after today's date. (You won't normally
|
|
use --today; it's just to make these examples reproducible.)
|
|
|
|
Forecast reports
|
|
Forecast transactions affect all reports, as you would expect. Eg:
|
|
|
|
$ hledger areg rent --forecast --today=2023/4/21
|
|
Transactions in expenses:rent and subaccounts:
|
|
2023-05-20 rent as:ba:checking $1000 $1000
|
|
2023-06-20 rent as:ba:checking $1000 $2000
|
|
2023-07-20 rent as:ba:checking $1000 $3000
|
|
2023-08-20 rent as:ba:checking $1000 $4000
|
|
2023-09-20 rent as:ba:checking $1000 $5000
|
|
|
|
$ hledger bal -M expenses --forecast --today=2023/4/21
|
|
Balance changes in 2023-05-01..2023-09-30:
|
|
|
|
|| May Jun Jul Aug Sep
|
|
===============++===================================
|
|
expenses:rent || $1000 $1000 $1000 $1000 $1000
|
|
---------------++-----------------------------------
|
|
|| $1000 $1000 $1000 $1000 $1000
|
|
|
|
Forecast tags
|
|
Forecast transactions generated by --forecast have a hidden tag, _gen-
|
|
erated-transaction. So if you ever need to match forecast transac-
|
|
tions, you could use tag:_generated-transaction (or just tag:generated)
|
|
in a query.
|
|
|
|
For troubleshooting, you can add the --verbose-tags flag. Then, visi-
|
|
ble generated-transaction tags will be added also, so you can view them
|
|
with the print command. Their value indicates which periodic rule was
|
|
responsible.
|
|
|
|
Forecast period, in detail
|
|
Forecast start/end dates are chosen so as to do something useful by de-
|
|
fault in almost all situations, while also being flexible. Here are
|
|
(with luck) the exact rules, to help with troubleshooting:
|
|
|
|
The forecast period starts on:
|
|
|
|
o the later of
|
|
|
|
o the start date in the periodic transaction rule
|
|
|
|
o the start date in --forecast's argument
|
|
|
|
o otherwise (if those are not available): the later of
|
|
|
|
o the report start date specified with -b/-p/date:
|
|
|
|
o the day after the latest ordinary transaction in the journal
|
|
|
|
o otherwise (if none of these are available): today.
|
|
|
|
The forecast period ends on:
|
|
|
|
o the earlier of
|
|
|
|
o the end date in the periodic transaction rule
|
|
|
|
o the end date in --forecast's argument
|
|
|
|
o otherwise: the report end date specified with -e/-p/date:
|
|
|
|
o otherwise: 180 days (~6 months) from today.
|
|
|
|
Forecast troubleshooting
|
|
When --forecast is not doing what you expect, one of these tips should
|
|
help:
|
|
|
|
o Remember to use the --forecast option.
|
|
|
|
o Remember to have at least one periodic transaction rule in your jour-
|
|
nal.
|
|
|
|
o Test with print --forecast.
|
|
|
|
o Check for typos or too-restrictive start/end dates in your periodic
|
|
transaction rule.
|
|
|
|
o Leave at least 2 spaces between the rule's period expression and de-
|
|
scription fields.
|
|
|
|
o Check for future-dated ordinary transactions suppressing forecasted
|
|
transactions.
|
|
|
|
o Try setting explicit report start and/or end dates with -b, -e, -p or
|
|
date:
|
|
|
|
o Try adding the -E flag to encourage display of empty periods/zero
|
|
transactions.
|
|
|
|
o Try setting explicit forecast start and/or end dates with --fore-
|
|
cast=START..END
|
|
|
|
o Consult Forecast period, in detail, above.
|
|
|
|
o Check inside the engine: add --debug=2 (eg).
|
|
|
|
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.
|
|
|
|
You can generate budget goals and forecast transactions at the same
|
|
time, from the same or different periodic transaction rules: hledger
|
|
bal -M --budget --forecast ...
|
|
|
|
See also: Budgeting and Forecasting.
|
|
|
|
Cost reporting
|
|
In some transactions - for example a currency conversion, or a purchase
|
|
or sale of stock - one commodity is exchanged for another. In these
|
|
transactions there is a conversion rate, also called the cost (when
|
|
buying) or selling price (when selling). In hledger docs we just say
|
|
"cost", for convenience; feel free to mentally translate to "conversion
|
|
rate" or "selling price" if helpful.
|
|
|
|
Recording costs
|
|
We'll explore several ways of recording transactions involving costs.
|
|
These are also summarised at hledger Cookbook > Cost notation.
|
|
|
|
Costs can be recorded explicitly in the journal, using the @ UNITCOST
|
|
or @@ TOTALCOST notation described in Journal > Costs:
|
|
|
|
Variant 1
|
|
|
|
2022-01-01
|
|
assets:dollars $-135
|
|
assets:euros 100 @ $1.35 ; $1.35 per euro (unit cost)
|
|
|
|
Variant 2
|
|
|
|
2022-01-01
|
|
assets:dollars $-135
|
|
assets:euros 100 @@ $135 ; $135 total cost
|
|
|
|
Typically, writing the unit cost (variant 1) is preferable; it can be
|
|
more effort, requiring more attention to decimal digits; but it reveals
|
|
the per-unit cost basis, and makes stock sales easier.
|
|
|
|
Costs can also be left implicit, and hledger will infer the cost that
|
|
is consistent with a balanced transaction:
|
|
|
|
Variant 3
|
|
|
|
2022-01-01
|
|
assets:dollars $-135
|
|
assets:euros 100
|
|
|
|
Here, hledger will attach a @@ 100 cost to the first amount (you can
|
|
see it with hledger print -x). This form looks convenient, but there
|
|
are downsides:
|
|
|
|
o It sacrifices some error checking. For example, if you accidentally
|
|
wrote 10 instead of 100, hledger would not be able to detect the mis-
|
|
take.
|
|
|
|
o It is sensitive to the order of postings - if they were reversed, a
|
|
different entry would be inferred and reports would be different.
|
|
|
|
o The per-unit cost basis is not easy to read.
|
|
|
|
So generally this kind of entry is not recommended. You can make sure
|
|
you have none of these by using -s (strict mode), or by running hledger
|
|
check balanced.
|
|
|
|
Reporting at cost
|
|
Now when you add the -B/--cost flag to reports ("B" is from Ledger's
|
|
-B/--basis/--cost flag), any amounts which have been annotated with
|
|
costs will be converted to their cost's commodity (in the report out-
|
|
put). Ie they will be displayed "at cost" or "at sale price".
|
|
|
|
Some things to note:
|
|
|
|
o Costs are attached to specific posting amounts in specific transac-
|
|
tions, and once recorded they do not change. This contrasts with
|
|
market prices, which are ambient and fluctuating.
|
|
|
|
o Conversion to cost is performed before conversion to market value
|
|
(described below).
|
|
|
|
Equity conversion postings
|
|
There is a problem with the entries above - they are not conventional
|
|
Double Entry Bookkeeping (DEB) notation, and because of the "magical"
|
|
transformation of one commodity into another, they cause an imbalance
|
|
in the Accounting Equation. This shows up as a non-zero grand total in
|
|
balance reports like hledger bse.
|
|
|
|
For most hledger users, this doesn't matter in practice and can safely
|
|
be ignored ! But if you'd like to learn more, keep reading.
|
|
|
|
Conventional DEB uses an extra pair of equity postings to balance the
|
|
transaction. Of course you can do this in hledger as well:
|
|
|
|
Variant 4
|
|
|
|
2022-01-01
|
|
assets:dollars $-135
|
|
assets:euros 100
|
|
equity:conversion $135
|
|
equity:conversion -100
|
|
|
|
Now the transaction is perfectly balanced according to standard DEB,
|
|
and hledger bse's total will not be disrupted.
|
|
|
|
And, hledger can still infer the cost for cost reporting, but it's not
|
|
done by default - you must add the --infer-costs flag like so:
|
|
|
|
$ hledger print --infer-costs
|
|
2022-01-01 one hundred euros purchased at $1.35 each
|
|
assets:dollars $-135 @@ 100
|
|
assets:euros 100
|
|
equity:conversion $135
|
|
equity:conversion -100
|
|
|
|
$ hledger bal --infer-costs -B
|
|
-100 assets:dollars
|
|
100 assets:euros
|
|
--------------------
|
|
0
|
|
|
|
Here are some downsides of this kind of entry:
|
|
|
|
o The per-unit cost basis is not easy to read.
|
|
|
|
o Instead of -B you must remember to type -B --infer-costs.
|
|
|
|
o --infer-costs works only where hledger can identify the two eq-
|
|
uity:conversion postings and match them up with the two non-equity
|
|
postings. So writing the journal entry in a particular format be-
|
|
comes more important. More on this below.
|
|
|
|
Inferring equity conversion postings
|
|
Can we go in the other direction ? Yes, if you have transactions writ-
|
|
ten with the @/@@ cost notation, hledger can infer the missing equity
|
|
postings, if you add the --infer-equity flag. Eg:
|
|
|
|
2022-01-01
|
|
assets:dollars -$135
|
|
assets:euros 100 @ $1.35
|
|
|
|
$ hledger print --infer-equity
|
|
2022-01-01
|
|
assets:dollars $-135
|
|
assets:euros 100 @ $1.35
|
|
equity:conversion:$-: -100
|
|
equity:conversion:$-:$ $135.00
|
|
|
|
The equity account names will be "equity:conversion:A-B:A" and "eq-
|
|
uity:conversion:A-B:B" where A is the alphabetically first commodity
|
|
symbol. You can customise the "equity:conversion" part by declaring an
|
|
account with the V/Conversion account type.
|
|
|
|
Combining costs and equity conversion postings
|
|
Finally, you can use both the @/@@ cost notation and equity postings at
|
|
the same time. This in theory gives the best of all worlds - preserv-
|
|
ing the accounting equation, revealing the per-unit cost basis, and
|
|
providing more flexibility in how you write the entry:
|
|
|
|
Variant 5
|
|
|
|
2022-01-01 one hundred euros purchased at $1.35 each
|
|
assets:dollars $-135
|
|
equity:conversion $135
|
|
equity:conversion -100
|
|
assets:euros 100 @ $1.35
|
|
|
|
All the other variants above can (usually) be rewritten to this final
|
|
form with:
|
|
|
|
$ hledger print -x --infer-costs --infer-equity
|
|
|
|
Downsides:
|
|
|
|
o The precise format of the journal entry becomes more important. If
|
|
hledger can't detect and match up the cost and equity postings, it
|
|
will give a transaction balancing error.
|
|
|
|
o The add command does not yet accept this kind of entry (#2056).
|
|
|
|
o This is the most verbose form.
|
|
|
|
Requirements for detecting equity conversion postings
|
|
--infer-costs has certain requirements (unlike --infer-equity, which
|
|
always works). It will infer costs only in transactions with:
|
|
|
|
o Two non-equity postings, in different commodities. Their order is
|
|
significant: the cost will be added to the first of them.
|
|
|
|
o Two postings to equity conversion accounts, next to one another,
|
|
which balance the two non-equity postings. This balancing is checked
|
|
to the same precision (number of decimal places) used in the conver-
|
|
sion posting's amount. Equity conversion accounts are:
|
|
|
|
o any accounts declared with account type V/Conversion, or their sub-
|
|
accounts
|
|
|
|
o otherwise, accounts named equity:conversion, equity:trade, or eq-
|
|
uity:trading, or their subaccounts.
|
|
|
|
And multiple such four-posting groups can coexist within a single
|
|
transaction. When --infer-costs fails, it does not infer a cost in
|
|
that transaction, and does not raise an error (ie, it infers costs
|
|
where it can).
|
|
|
|
Reading variant 5 journal entries, combining cost notation and equity
|
|
postings, has all the same requirements. When reading such an entry
|
|
fails, hledger raises an "unbalanced transaction" error.
|
|
|
|
Infer cost and equity by default ?
|
|
Should --infer-costs and --infer-equity be enabled by default ? Try
|
|
using them always, eg with a shell alias:
|
|
|
|
alias h="hledger --infer-equity --infer-costs"
|
|
|
|
and let us know what problems you find.
|
|
|
|
Value reporting
|
|
Instead of reporting amounts in their original commodity, hledger can
|
|
convert them to cost/sale amount (using the conversion rate recorded in
|
|
the transaction), and/or to market value (using some market price on a
|
|
certain date). This is controlled by the --value=TYPE[,COMMODITY] op-
|
|
tion, 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
|
|
Market prices can change from day to day. hledger will use the prices
|
|
on a particular valuation date (or on more than one date). By default
|
|
hledger uses "end" dates for valuation. More specifically:
|
|
|
|
o For single period reports (including normal print and register re-
|
|
ports):
|
|
|
|
o If an explicit report end date is specified, that is used
|
|
|
|
o Otherwise the latest transaction date or P directive date is used
|
|
(even if it's in the future)
|
|
|
|
o For multiperiod reports, each period is valued on its last day.
|
|
|
|
This can be customised with the --value option described below, which
|
|
can select either "then", "end", "now", or "custom" dates. (Note, this
|
|
has a bug in hledger-ui <=1.31: turning on valuation with the V key al-
|
|
ways resets it to "end".)
|
|
|
|
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 Value reporting 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 $1.10
|
|
|
|
; purchase some euros on nov 3
|
|
2016/11/3
|
|
assets:euros 100
|
|
assets:checking
|
|
|
|
; the euro is worth fewer dollars by dec 21
|
|
P 2016/12/21 $1.03
|
|
|
|
How many euros do I have ?
|
|
|
|
$ hledger -f t.j bal -N euros
|
|
100 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
|
|
|
|
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. Re-
|
|
lated: #329, #1083.
|
|
|
|
Report -B, --cost -V, -X --value=then --value=end --value=DATE,
|
|
type --value=now
|
|
--------------------------------------------------------------------------------------------
|
|
print
|
|
posting cost value at re- value at posting value at re- value at
|
|
amounts port end or date port or DATE/today
|
|
today journal end
|
|
balance unchanged unchanged unchanged unchanged unchanged
|
|
asser-
|
|
tions/as-
|
|
signments
|
|
|
|
register
|
|
starting cost value at re- valued at day value at re- value at
|
|
balance port or each historical port or DATE/today
|
|
(-H) journal end posting was made journal end
|
|
starting cost value at day valued at day value at day value at
|
|
balance before re- each historical before re- DATE/today
|
|
(-H) with port or posting was made port or
|
|
report journal journal
|
|
interval start start
|
|
posting cost value at re- value at posting value at re- value at
|
|
amounts port or date port or DATE/today
|
|
journal end journal end
|
|
summary summarised value at pe- sum of postings value at pe- value at
|
|
posting cost riod ends in interval, val- riod ends DATE/today
|
|
amounts ued at interval
|
|
with re- start
|
|
port in-
|
|
terval
|
|
running sum/average sum/average sum/average of sum/average sum/average
|
|
total/av- of displayed of displayed displayed values of displayed of displayed
|
|
erage values values values values
|
|
|
|
balance
|
|
(bs, bse,
|
|
cf, is)
|
|
balance sums of value at re- value at posting value at re- value at
|
|
changes costs port end or date port or DATE/today of
|
|
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
|
|
(--bud-
|
|
get)
|
|
grand to- sum of dis- sum of dis- sum of displayed sum of dis- sum of dis-
|
|
tal played val- played val- valued played val- played values
|
|
ues ues ues
|
|
|
|
balance
|
|
(bs, bse,
|
|
cf, is)
|
|
with re-
|
|
port in-
|
|
terval
|
|
starting sums of value at re- sums of values of value at re- sums of post-
|
|
balances costs of port start postings before port start ings before
|
|
(-H) postings be- of sums of report start at of sums of report start
|
|
fore report all postings respective post- all postings
|
|
start before re- ing dates before re-
|
|
port start port start
|
|
balance sums of same as sums of values of balance value at
|
|
changes costs of --value=end postings in pe- change in DATE/today of
|
|
(bal, is, postings in riod at respec- each period, sums of post-
|
|
bs period tive posting valued at ings
|
|
--change, dates period ends
|
|
cf
|
|
--change)
|
|
end bal- sums of same as sums of values of period end value at
|
|
ances costs of --value=end postings from be- balances, DATE/today of
|
|
(bal -H, postings fore period start valued at sums of post-
|
|
is --H, from before to period end at period ends ings
|
|
bs, cf) report start respective post-
|
|
to period ing dates
|
|
end
|
|
budget like balance like balance like balance like bal- like balance
|
|
amounts changes/end changes/end changes/end bal- ances changes/end
|
|
(--bud- balances balances ances balances
|
|
get)
|
|
row to- sums, aver- sums, aver- sums, averages of sums, aver- sums, aver-
|
|
tals, row ages of dis- ages of dis- displayed values ages of dis- ages of dis-
|
|
averages played val- played val- played val- played values
|
|
(-T, -A) ues ues ues
|
|
column sums of dis- sums of dis- sums of displayed sums of dis- sums of dis-
|
|
totals played val- played val- values played val- played values
|
|
ues ues ues
|
|
grand to- sum, average sum, average sum, average of sum, average sum, average
|
|
tal, of column of column column totals of column of column to-
|
|
grand av- totals totals totals tals
|
|
erage
|
|
|
|
|
|
--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 to-
|
|
tal
|
|
|
|
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 ac-
|
|
counts, 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 ac-
|
|
counts (--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 ac-
|
|
count's declaration, if any, and the account's overall declaration or-
|
|
der; 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 to-
|
|
gether 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 de-
|
|
scription) 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> $
|
|
|
|
If you enter a number with no commodity symbol, and you have declared a
|
|
default commodity with a D directive, you might expect add to add this
|
|
symbol for you. It does not do this; we assume that if you are using a
|
|
D directive you prefer not to see the commodity symbol repeated on
|
|
amounts in the journal.
|
|
|
|
aregister
|
|
(areg)
|
|
|
|
Show the transactions and running historical balance of a single ac-
|
|
count, 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 in-
|
|
cluded 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 ex-
|
|
pression 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 op-
|
|
tions. The output formats supported are txt, csv, tsv (Added in 1.32),
|
|
and json.
|
|
|
|
aregister and posting dates
|
|
aregister always shows one line (and date and amount) per transaction.
|
|
But sometimes transactions have postings with different dates. Also,
|
|
not all of a transaction's postings may be within the report period.
|
|
To resolve this, aregister shows the earliest of the transaction's date
|
|
and posting dates that is in-period, and the sum of the in-period post-
|
|
ings. In other words it will show a combined line item with just the
|
|
earliest date, and the running balance will (temporarily, until the
|
|
transaction's last posting) be inaccurate. Use register -H if you need
|
|
to see the individual postings.
|
|
|
|
There is also a --txn-dates flag, which filters strictly by transaction
|
|
date, ignoring posting dates. This too can cause an inaccurate running
|
|
balance.
|
|
|
|
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)
|
|
|
|
o or postings count (--count)
|
|
|
|
..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 (--in-
|
|
vert)
|
|
|
|
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, tsv (Added in 1.32), json, and (multi-pe-
|
|
riod reports only:) html. In txt output in a colour-supporting termi-
|
|
nal, 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 (re-
|
|
vealing 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 ac-
|
|
count/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 ef-
|
|
fect, 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 di-
|
|
rective 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 re-
|
|
port, even when you don't have transactions in all of your declared ac-
|
|
counts 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
|
|
biggest averaged monthly expenses first. When more than one commodity
|
|
is present, they will be sorted by the alphabetically earliest commod-
|
|
ity 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 --in-
|
|
vert 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:
|
|
|
|
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.
|
|
|
|
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 ac-
|
|
count 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 take time and ex-
|
|
perimentation to get familiar with all the 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)
|
|
|
|
o --count : show the count of postings
|
|
|
|
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 as-
|
|
sets/liabilities/equity. (default for balancesheet, balancesheete-
|
|
quity, cashflow)
|
|
|
|
Valuation type
|
|
Which kind of value or cost conversion should be applied, if any, be-
|
|
fore 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 an-
|
|
other 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 Value reporting 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=
|
|
tion:> YYYY-MM-DD
|
|
Accumu- /now
|
|
lation:v
|
|
-----------------------------------------------------------------------------------
|
|
--change change in period sum of post- period-end DATE-value of
|
|
ing-date market value of change change in pe-
|
|
values in period in period riod
|
|
--cumu- change from re- sum of post- period-end DATE-value of
|
|
lative port start to ing-date market value of change change from
|
|
period end values from re- from report report start
|
|
port start to pe- start to period to period end
|
|
riod end end
|
|
--his- change from sum of post- period-end DATE-value of
|
|
torical journal start to ing-date market value of change change from
|
|
/-H period end (his- values from jour- from journal journal start
|
|
torical end bal- nal start to pe- start to period to period end
|
|
ance) riod end end
|
|
|
|
Budget report
|
|
The --budget report type is like a regular balance report, but with two
|
|
main differences:
|
|
|
|
o Budget goals and performance percentages are also shown, in brackets
|
|
|
|
o Accounts which don't have budget goals are hidden by default.
|
|
|
|
This is useful for comparing planned and actual income, expenses, time
|
|
usage, etc.
|
|
|
|
Periodic transaction rules are used to define budget goals. For exam-
|
|
ple, here's a periodic rule defining monthly goals for bus travel and
|
|
food expenses:
|
|
|
|
;; Budget
|
|
~ monthly
|
|
(expenses:bus) $30
|
|
(expenses:food) $400
|
|
|
|
After recording some actual expenses,
|
|
|
|
;; Two months worth of expenses
|
|
2017-11-01
|
|
income $-1950
|
|
expenses:bus $35
|
|
expenses:food:groceries $310
|
|
expenses:food:dining $42
|
|
expenses:movies $38
|
|
assets:bank:checking
|
|
|
|
2017-12-01
|
|
income $-2100
|
|
expenses:bus $53
|
|
expenses:food:groceries $380
|
|
expenses:food:dining $32
|
|
expenses:gifts $100
|
|
assets:bank:checking
|
|
|
|
we can see a budget report like this:
|
|
|
|
$ hledger bal -M --budget
|
|
Budget performance in 2017-11-01..2017-12-31:
|
|
|
|
|| Nov Dec
|
|
===============++============================================
|
|
<unbudgeted> || $-425 $-565
|
|
expenses || $425 [ 99% of $430] $565 [131% of $430]
|
|
expenses:bus || $35 [117% of $30] $53 [177% of $30]
|
|
expenses:food || $352 [ 88% of $400] $412 [103% of $400]
|
|
---------------++--------------------------------------------
|
|
|| 0 [ 0% of $430] 0 [ 0% of $430]
|
|
|
|
This is "goal-based budgeting"; you define goals for accounts and peri-
|
|
ods, often recurring, and hledger shows performance relative to the
|
|
goals. This contrasts with "envelope budgeting", which is more de-
|
|
tailed and strict - useful when cash is tight, but also quite a bit
|
|
more work. https://plaintextaccounting.org/Budgeting has more on this
|
|
topic.
|
|
|
|
Using the budget report
|
|
Historically this report has been confusing and fragile. hledger's
|
|
version should be relatively robust and intuitive, but you may still
|
|
find surprises. Here are more notes to help with learning and trou-
|
|
bleshooting.
|
|
|
|
o In the above example, expenses:bus and expenses:food are shown be-
|
|
cause they have budget goals during the report period.
|
|
|
|
o Their parent expenses is also shown, with budget goals aggregated
|
|
from the children.
|
|
|
|
o The subaccounts expenses:food:groceries and expenses:food:dining are
|
|
not shown since they have no budget goal of their own, but they con-
|
|
tribute to expenses:food's actual amount.
|
|
|
|
o Unbudgeted accounts expenses:movies and expenses:gifts are also not
|
|
shown, but they contribute to expenses's actual amount.
|
|
|
|
o The other unbudgeted accounts income and assets:bank:checking are
|
|
grouped as <unbudgeted>.
|
|
|
|
o --depth or depth: can be used to limit report depth in the usual way
|
|
(but will not reveal unbudgeted subaccounts).
|
|
|
|
o Amounts are always inclusive of subaccounts (even in -l/--list mode).
|
|
|
|
o Numbers displayed in a --budget report will not always agree with the
|
|
totals, because of hidden unbudgeted accounts; this is normal.
|
|
-E/--empty can be used to reveal the hidden accounts.
|
|
|
|
o In the periodic rules used for setting budget goals, unbalanced post-
|
|
ings are convenient.
|
|
|
|
o You can filter budget reports with the usual queries, eg to focus on
|
|
particular accounts. It's common to restrict them to just expenses.
|
|
(The <unbudgeted> account is occasionally hard to exclude; this is
|
|
because of date surprises, discussed below.)
|
|
|
|
o When you have multiple currencies, you may want to convert them to
|
|
one (-X COMM --infer-market-prices) and/or show just one at a time
|
|
(cur:COMM). If you do need to show multiple currencies at once,
|
|
--layout bare can be helpful.
|
|
|
|
o You can "roll over" amounts (actual and budgeted) to the next period
|
|
with --cumulative.
|
|
|
|
See also: https://hledger.org/budgeting.html.
|
|
|
|
Budget date surprises
|
|
With small data, or when starting out, some of the generated budget
|
|
goal transaction dates might fall outside the report periods. Eg with
|
|
the following journal and report, the first period appears to have no
|
|
expenses:food budget. (Also the <unbudgeted> account should be ex-
|
|
cluded by the expenses query, but isn't.):
|
|
|
|
~ monthly in 2020
|
|
(expenses:food) $500
|
|
|
|
2020-01-15
|
|
expenses:food $400
|
|
assets:checking
|
|
|
|
$ hledger bal --budget expenses
|
|
Budget performance in 2020-01-15:
|
|
|
|
|| 2020-01-15
|
|
===============++====================
|
|
<unbudgeted> || $400
|
|
expenses:food || 0 [ 0% of $500]
|
|
---------------++--------------------
|
|
|| $400 [80% of $500]
|
|
|
|
In this case, the budget goal transactions are generated on first days
|
|
of of month (this can be seen with hledger print --forecast tag:gener-
|
|
ated expenses). Whereas the report period defaults to just the 15th
|
|
day of january (this can be seen from the report table's column head-
|
|
ings).
|
|
|
|
To fix this kind of thing, be more explicit about the report period
|
|
(and/or the periodic rules' dates). In this case, adding -b 2020 does
|
|
the trick.
|
|
|
|
Selecting budget goals
|
|
By default, the budget report uses all available periodic transaction
|
|
rules to generate goals. This includes rules with a different report
|
|
interval from your report. Eg if you have daily, weekly and monthly
|
|
periodic rules, all of these will contribute to the goals in a monthly
|
|
budget report.
|
|
|
|
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 between period
|
|
expression and description), and then select from multiple budgets de-
|
|
fined in your journal.
|
|
|
|
Budgeting vs forecasting
|
|
--budget and --forecast both use the periodic transaction rules in the
|
|
journal to generate temporary transactions for reporting purposes.
|
|
However they are separate features - though you can use both at the
|
|
same time if you want. Here are some differences between them:
|
|
|
|
1. --budget is a command-specific option; it selects the budget report.
|
|
|
|
--forecast is a general option; forecasting works with all reports.
|
|
|
|
2. --budget uses all periodic rules; --budget=DESCPAT uses just the
|
|
rules matched by DESCPAT.
|
|
|
|
--forecast uses all periodic rules.
|
|
|
|
3. --budget's budget goal transactions are invisible, except that they
|
|
produce goal amounts.
|
|
|
|
--forecast's forecast transactions are visible, and appear in re-
|
|
ports.
|
|
|
|
4. --budget generates budget goal transactions throughout the report
|
|
period, optionally restricted by periods specified in the periodic
|
|
transaction rules.
|
|
|
|
--forecast generates forecast transactions from after the last reg-
|
|
ular transaction, to the end of the report period; while --fore-
|
|
cast=PERIODEXPR generates them throughout the specified period;
|
|
both optionally restricted by periods specified in the periodic
|
|
transaction rules.
|
|
|
|
Balance report 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, op-
|
|
tionally 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 Note: bare layout will sometimes display an extra row for the no-sym-
|
|
bol commodity, because of zero amounts (hledger treats zeroes as com-
|
|
modity-less, usually). This can break hledger-bar confusingly
|
|
(workaround: add a cur: query to exclude the no-symbol row).
|
|
|
|
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/vi-
|
|
gnettes/tidy-data.html for more. This is the easiest kind of data
|
|
for other software 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 op-
|
|
tions The output formats supported are txt, csv, tsv (Added in 1.32),
|
|
html, and 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 in-
|
|
sensitive, 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 op-
|
|
tions The output formats supported are txt, csv, tsv, html, and 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 al-
|
|
lowed)
|
|
|
|
o whose name contains some variation of cash, bank, checking or saving.
|
|
|
|
More precisely: all accounts matching this case insensitive regular ex-
|
|
pression:
|
|
|
|
^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 op-
|
|
tions The output formats supported are txt, csv, tsv (Added in 1.32),
|
|
html, and 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:
|
|
|
|
Default checks
|
|
These checks are run automatically by (almost) all hledger commands:
|
|
|
|
o parseable - data files are in a supported format, with no syntax er-
|
|
rors and no invalid include directives.
|
|
|
|
o autobalanced - all transactions are balanced, after converting to
|
|
cost. Missing amounts and missing costs are inferred automatically
|
|
where possible.
|
|
|
|
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 balanced - all transactions are balanced after converting to cost,
|
|
without inferring missing costs. If conversion costs are required,
|
|
they must be explicit.
|
|
|
|
o accounts - all account names used by transactions have been declared
|
|
|
|
o commodities - all commodity symbols used have been declared
|
|
|
|
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:
|
|
|
|
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 within 7 days of 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 has postings more than 7 days after its latest balance asser-
|
|
tion. This aims to prevent the situation where you are regularly up-
|
|
dating 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 recom-
|
|
mend to import transactions uncleared, and when you manually review and
|
|
clear them, also check the latest assertion against the real-world bal-
|
|
ance.)
|
|
|
|
close
|
|
(equity)
|
|
|
|
close generates several kinds of "closing" and/or "opening" transac-
|
|
tions, useful in certain situations, including migrating balances to a
|
|
new journal file, retaining earnings into equity, consolidating bal-
|
|
ances, or viewing lots. Like print, it prints valid journal entries.
|
|
You can append or copy these to your journal file(s) when you are happy
|
|
with how they look.
|
|
|
|
close currently has six modes, selected by a single mode flag:
|
|
|
|
close --migrate
|
|
This is the most common mode. It prints a "closing balances" transac-
|
|
tion that zeroes out all asset and liability balances (by default), and
|
|
an opposite "opening balances" transaction that restores them again.
|
|
The balancing account will be equity:opening/closing balances (or an-
|
|
other specified by --close-acct or --open-acct).
|
|
|
|
This is useful when migrating balances to a new journal file at the
|
|
start of a new year. Essentially, you run hledger close --mi-
|
|
grate=NEWYEAR -e NEWYEAR and then copy the closing transaction to the
|
|
end of the old file and the opening transaction to the start of the new
|
|
file. The opening transaction sets correct starting balances in the
|
|
new file when it is used alone, and the closing transaction keeps bal-
|
|
ances correct when you use both old and new files together, by can-
|
|
celling out the following opening transaction and preventing buildup of
|
|
duplicated opening balances. Think of the closing/opening pair as
|
|
"moving the balances into the next file".
|
|
|
|
You can close a different set of accounts by providing a query. Eg if
|
|
you want to include equity, you can add assets liabilities equity or
|
|
type:ALE arguments. (The balancing account is always excluded.) Rev-
|
|
enues and expenses usually are not migrated to a new file directly; see
|
|
--retain below.
|
|
|
|
The generated transactions will have a start: tag, with its value set
|
|
to --migrate's NEW argument if any, for easier matching or exclusion.
|
|
When NEW is not specified, it will be inferred if possible by incre-
|
|
menting a number (eg a year number) within the default journal's main
|
|
file name. The other modes behave similarly.
|
|
|
|
close --close
|
|
This prints just the closing balances transaction of --migrate. It is
|
|
the default behaviour if you specify no mode flag. Using the customi-
|
|
sation options below, you can move balances from any set of accounts to
|
|
a different account.
|
|
|
|
close --open
|
|
This prints just the opening balances transaction of --migrate. It is
|
|
similar to Ledger's equity command.
|
|
|
|
close --assert
|
|
This prints a "closing balances" transaction (with balances: tag), that
|
|
just declares balance assertions for the current balances without
|
|
changing them. It could be useful as documention and to guard against
|
|
changes.
|
|
|
|
close --assign
|
|
This prints an "opening balances" transaction that restores the account
|
|
balances using balance assignments. Balance assignments work regard-
|
|
less of any previous balance, so a preceding closing balances transac-
|
|
tion is not needed.
|
|
|
|
However, omitting the closing balances transaction would unbalance eq-
|
|
uity. This is relatively harmless for personal reports, but it dis-
|
|
turbs the accounting equation, removing a source of error detection.
|
|
So --migrate is generally the best way to set to set balances in new
|
|
files, for now.
|
|
|
|
close --retain
|
|
This is like --close with different defaults: it prints a "retain earn-
|
|
ings" transaction (with retain: tag), that transfers revenue and ex-
|
|
pense balances to equity:retained earnings.
|
|
|
|
This is a different kind of closing, called "retaining earnings" or
|
|
"closing the books"; it is traditionally performed by businesses at the
|
|
end of each accounting period, to consolidate revenues and expenses
|
|
into the main equity balance. ("Revenues" and "expenses" are actually
|
|
equity by another name, kept separate temporarily for reporting pur-
|
|
poses.)
|
|
|
|
In personal accounting you generally don't need to do this, unless you
|
|
want the balancesheetequity report to show a zero total, demonstrating
|
|
that the accounting equation (A-L=E) is satisfied.
|
|
|
|
close customisation
|
|
In all modes, the following things can be overridden:
|
|
|
|
o the accounts to be closed/opened, with account query arguments
|
|
|
|
o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
|
|
|
|
o the transaction descriptions, with --close-desc=DESC and
|
|
--open-desc=DESC
|
|
|
|
o the transaction's tag value, with a --MODE=NEW option argument
|
|
|
|
o the closing/opening dates, with -e OPENDATE
|
|
|
|
By default, the closing date is yesterday, or the journal's end date,
|
|
whichever is later; and the opening date is always one day after the
|
|
closing date. You can change these by specifying a report end date;
|
|
the closing date will be the last day of the report period. Eg -e 2024
|
|
means "close on 2023-12-31, open on 2024-01-01".
|
|
|
|
With --x/--explicit, the balancing amount will be shown explicitly, and
|
|
if it involves multiple commodities, a separate posting will be gener-
|
|
ated for each of them (similar to print -x).
|
|
|
|
With --interleaved, each individual transfer is shown with source and
|
|
destination postings next to each other (perhaps useful for trou-
|
|
bleshooting).
|
|
|
|
With --show-costs, balances' costs are also shown, with different costs
|
|
kept separate. This may generate very large journal entries, if you
|
|
have many currency conversions or investment transactions. close
|
|
--show-costs is currently the best way to view investment lots with
|
|
hledger. (To move or dispose of lots, see the more capable
|
|
hledger-move script.)
|
|
|
|
close and balance assertions
|
|
close adds balance assertions verifying that the accounts have been re-
|
|
set to zero in a closing transaction or restored to their previous bal-
|
|
ances in an opening transaction. These provide useful error checking,
|
|
but you can ignore them temporarily with -I, or remove them if you pre-
|
|
fer.
|
|
|
|
When running close you should probably avoid using -C, -R, status:
|
|
(filtering by status or realness) or --auto (generating postings),
|
|
since the generated balance assertions would then require these.
|
|
|
|
Transactions with multiple dates (eg posting dates) spanning the file
|
|
boundary also can 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 this you can transfer the money to and from a temporary ac-
|
|
count, splitting the multi-day transaction into two single-day transac-
|
|
tions:
|
|
|
|
; 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
|
|
|
|
close examples
|
|
Retain earnings
|
|
Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap-
|
|
pending the generated transaction to the journal:
|
|
|
|
$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
|
|
|
|
After this, to see 2022's revenues and expenses you must exclude the
|
|
retain earnings transaction:
|
|
|
|
$ hledger -f 2022.journal is not:desc:'retain earnings'
|
|
|
|
Migrate balances to a new file
|
|
Close assets/liabilities 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
|
|
|
|
After this, to see 2022's end-of-year balances you must exclude the
|
|
closing balances transaction:
|
|
|
|
$ hledger -f 2022.journal bs not:desc:'closing balances'
|
|
|
|
For more flexibility, it helps to tag closing and opening transactions
|
|
with eg start:NEWYEAR, then you can ensure correct balances by exclud-
|
|
ing all opening/closing transactions except the first, like so:
|
|
|
|
$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start'
|
|
$ hledger bs -Y -f 2021.j -f 2022.j expr:'tag:start=2021 or not tag:start'
|
|
$ hledger bs -Y -f 2022.j -f 2023.j expr:'tag:start=2022 or not tag:start'
|
|
$ hledger bs -Y -f 2021.j expr:'tag:start=2021 or not tag:start'
|
|
$ hledger bs -Y -f 2022.j expr:'tag:start=2022 or not tag:start'
|
|
$ hledger bs -Y -f 2023.j # unclosed file, no query needed
|
|
|
|
More detailed close examples
|
|
See examples/multi-year.
|
|
|
|
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.
|
|
|
|
Use the -s/--speed SPEED option to set your preferred playback speed,
|
|
eg -s4 to play at 4x original speed or -s.5 to play at half speed. The
|
|
default speed is 2x.
|
|
|
|
Other asciinema options can be added following a double dash, eg --
|
|
-i.1 to limit pauses or -- -h to list asciinema's other options.
|
|
|
|
During playback, several keys are available: SPACE to pause/unpause, .
|
|
to step forward (while paused), CTRL-c quit.
|
|
|
|
Examples:
|
|
|
|
$ hledger demo # list available demos
|
|
$ hledger demo 1 # play the first demo at default speed (2x)
|
|
$ hledger demo install -s4 # play the "install" demo at 4x speed
|
|
|
|
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 in-
|
|
sensitive. Eg: commands, print, forecast, journal, amount, "auto post-
|
|
ings".
|
|
|
|
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, trying (in this
|
|
order): info, man, $PAGER, less, more. You can force the use of info,
|
|
man, or a pager with the -i, -m, or -p flags, If no viewer can be
|
|
found, or the command is run non-interactively, it just prints the man-
|
|
ual to stdout.
|
|
|
|
If using info, note that version 6 or greater is needed for TOPIC
|
|
lookup. If you are on mac you will likely have info 4.8, and should
|
|
consider installing a newer version, eg with brew install texinfo
|
|
(#1770).
|
|
|
|
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
|
|
$ hledger help -m journal # show it with man, even if info is installed
|
|
|
|
import
|
|
Read new transactions added to each FILE provided as arguments since
|
|
last run, and add them to the journal. Or with --dry-run, just print
|
|
the transactions that would be added. Or with --catchup, just mark all
|
|
of the FILEs' current transactions as imported, without importing them.
|
|
|
|
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
|
|
import does time-based deduplication, to detect only the new transac-
|
|
tions since the last successful import. (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 periodi-
|
|
cally importing downloaded data, which may overlap with previous down-
|
|
loads. Eg if every week (or every day) you download a bank's last
|
|
three months of CSV data, you can safely run hledger import thebank.csv
|
|
each time and only new transactions will be imported.
|
|
|
|
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.FILE" file in FILE's directory (after a succesful
|
|
import).
|
|
|
|
Eg when reading finance/bank.csv, it will look for and update the fi-
|
|
nance/.latest.bank.csv state file. The format is simple: one or more
|
|
lines containing the same ISO-format date (YYYY-MM-DD), meaning "I have
|
|
processed 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.
|
|
|
|
Related: CSV > Working with CSV > Deduplicating, importing.
|
|
|
|
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 ex-
|
|
penses during one or more periods. Amounts are shown with normal posi-
|
|
tive 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 op-
|
|
tions The output formats supported are txt, csv, tsv (Added in 1.32),
|
|
html, and json.
|
|
|
|
notes
|
|
List the unique notes that appear in transactions.
|
|
|
|
This command lists the unique notes that appear in transactions, in al-
|
|
phabetic 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 the market prices declared with P directives. With --infer-mar-
|
|
ket-prices, also show any additional prices inferred from costs. With
|
|
--show-reverse, also show additional prices inferred by reversing known
|
|
prices.
|
|
|
|
Price amounts are always displayed with their full precision, except
|
|
for reverse prices which are limited to 8 decimal digits.
|
|
|
|
Prices can be filtered by a date:, cur: or amt: query.
|
|
|
|
Generally if you run this command with --infer-market-prices --show-re-
|
|
verse, it will show the same prices used internally to calculate value
|
|
reports. But if in doubt, you can inspect those directly by running
|
|
the value report with --debug=2.
|
|
|
|
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).
|
|
|
|
Directives and inter-transaction comments are not shown, currently.
|
|
This means the print command is somewhat lossy, and if you are using it
|
|
to reformat/regenerate your journal you should take care to also copy
|
|
over the directives and inter-transaction comments.
|
|
|
|
Eg:
|
|
|
|
$ hledger print -f examples/sample.journal date:200806
|
|
2008/06/01 gift
|
|
assets:bank:checking $1
|
|
income:gifts $-1
|
|
|
|
2008/06/02 save
|
|
assets:bank:saving $1
|
|
assets:bank:checking $-1
|
|
|
|
2008/06/03 * eat & shop
|
|
expenses:food $1
|
|
expenses:supplies $1
|
|
assets:cash $-2
|
|
|
|
print explicitness
|
|
Normally, whether posting amounts are implicit or explicit is pre-
|
|
served. For example, when an amount is omitted in the journal, it will
|
|
not appear in the output. Similarly, if a conversion cost is implied
|
|
but not written, it will not appear in the output.
|
|
|
|
You can use the -x/--explicit flag to force explicit display of all
|
|
amounts and costs. This can be useful for troubleshooting or for mak-
|
|
ing your journal more readable and robust against data entry errors.
|
|
-x is also implied by using any of -B,-V,-X,--value.
|
|
|
|
The -x/--explicit flag will cause any postings with a multi-commodity
|
|
amount (which can arise when a multi-commodity transaction has an im-
|
|
plicit amount) to be split into multiple single-commodity postings,
|
|
keeping the output parseable.
|
|
|
|
print amount style
|
|
Amounts are shown right-aligned within each transaction (but not
|
|
aligned across all transactions; you can do that with ledger-mode in
|
|
Emacs).
|
|
|
|
Amounts will be (mostly) normalised to their commodity display style:
|
|
their symbol placement, decimal mark, and digit group marks will be
|
|
made consistent. By default, decimal digits are shown as they are
|
|
written in the journal.
|
|
|
|
With the --round (Added in 1.32) option, print will try increasingly
|
|
hard to display decimal digits according to the commodity display
|
|
styles:
|
|
|
|
o --round=none show amounts with original precisions (default)
|
|
|
|
o --round=soft add/remove decimal zeros in amounts (except costs)
|
|
|
|
o --round=hard round amounts (except costs), possibly hiding signifi-
|
|
cant digits
|
|
|
|
o --round=all round all amounts and costs
|
|
|
|
soft is good for non-lossy cleanup, formatting amounts more consis-
|
|
tently where it's safe to do so.
|
|
|
|
hard and all can cause print to show invalid unbalanced journal en-
|
|
tries; they may be useful eg for stronger cleanup, with manual fixups
|
|
when needed.
|
|
|
|
print parseability
|
|
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 (though the same can be achieved with expr: queries
|
|
now):
|
|
|
|
# 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 Value reporting affects posting amounts but not balance assertion or
|
|
balance 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.
|
|
|
|
print, other features
|
|
With -B/--cost, amounts with costs are shown converted to cost.
|
|
|
|
With --new, print shows only transactions it has not seen on a previous
|
|
run. This uses the same deduplication system as the import command.
|
|
(See import's docs for details.)
|
|
|
|
With -m DESC/--match=DESC, print shows one recent transaction whose de-
|
|
scription 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.
|
|
|
|
print output format
|
|
This command also supports the output destination and output format op-
|
|
tions The output formats supported are txt, beancount (Added in 1.32),
|
|
csv, tsv (Added in 1.32), json and sql.
|
|
|
|
The beancount format tries to produce Beancount-compatible output, as
|
|
follows:
|
|
|
|
o Transaction and postings with unmarked status are converted to
|
|
cleared (*) status.
|
|
|
|
o Transactions' payee and note are backslash-escaped and dou-
|
|
ble-quote-escaped and wrapped in double quotes.
|
|
|
|
o Transaction tags are copied to Beancount #tag format.
|
|
|
|
o Commodity symbols are converted to upper case, and a small number of
|
|
currency symbols like $ are converted to the corresponding currency
|
|
names.
|
|
|
|
o Account name parts are capitalised and unsupported characters are re-
|
|
placed with -. If an account name part does not begin with a letter,
|
|
or if the first part is not Assets, Liabilities, Equity, Income, or
|
|
Expenses, an error is raised. (Use --alias options to bring your ac-
|
|
counts into compliance.)
|
|
|
|
o An open directive is generated for each account used, on the earliest
|
|
transaction date.
|
|
|
|
Some limitations:
|
|
|
|
o Balance assertions are removed.
|
|
|
|
o Balance assignments become missing amounts.
|
|
|
|
o Virtual and balanced virtual postings become regular postings.
|
|
|
|
o Directives are not converted.
|
|
|
|
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 ac-
|
|
count 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 to-
|
|
gether with the related account:
|
|
|
|
$ hledger register --related --invert assets:checking
|
|
|
|
With a reporting interval, register shows summary postings, one per in-
|
|
terval, 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 op-
|
|
tion 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 in-
|
|
tervals. 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 de-
|
|
scription 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 op-
|
|
tions The output formats supported are txt, csv, tsv (Added in 1.32),
|
|
and 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 in-
|
|
cludes a commodity name, the new posting amount will be in the new com-
|
|
modity; otherwise, it will be in the matched posting amount's commod-
|
|
ity.
|
|
|
|
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 ac-
|
|
count 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, also known as money-weighted rate of return) and time-weighted
|
|
rate of return (TWR) for your investments for the time period re-
|
|
quested. IRR is always annualized due to the way it is computed, but
|
|
TWR is reported both as a rate over the chosen reporting period and as
|
|
an annual rate.
|
|
|
|
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 be-
|
|
comes 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 as-
|
|
sets, 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 re-
|
|
turn.
|
|
|
|
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, and the
|
|
time between them. Investment at a particular fixed interest rate is
|
|
going to give you more interest than the same amount invested at the
|
|
same interest rate, but made later in time. If you are withdrawing
|
|
from your investment, your future gains would be smaller (in absolute
|
|
numbers), and will be a smaller percentage of your initial investment,
|
|
so your IRR will be smaller. And if you are adding to your investment,
|
|
you will receive bigger absolute gains, which will be a bigger percent-
|
|
age of your initial investment, so your IRR will be larger.
|
|
|
|
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 ac-
|
|
count for the effect of your in-flows and out-flows, but unlike IRR it
|
|
will try to compute the true rate of return of the underlying asset,
|
|
compensating for the effect that deposits and withdrawas have on the
|
|
apparent rate of growth of your investment.
|
|
|
|
TWR represents your investment as an imaginary "unit fund" where
|
|
in-flows/ out-flows lead to buying or selling "units" of your invest-
|
|
ment and changes in its value change the value of "investment unit".
|
|
Change in "unit price" over the reporting period gives you rate of re-
|
|
turn of your investment, and make TWR less sensitive than IRR to the
|
|
effects of cash in-flows and out-flows.
|
|
|
|
References:
|
|
|
|
o Explanation of rate of return
|
|
|
|
o Explanation of IRR
|
|
|
|
o Explanation of TWR
|
|
|
|
o IRR vs 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/--out-
|
|
put-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
|
|
archives 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 de-
|
|
scribed 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
|
|
(see below). 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 2023.journal
|
|
$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile
|
|
$ source ~/.profile
|
|
$ hledger stats
|
|
Main file : /Users/simon/finance/2023.journal
|
|
Included files :
|
|
Transactions span : to (0 days)
|
|
Last transaction : none
|
|
Transactions : 0 (0.0 per day)
|
|
Transactions last 30 days: 0 (0.0 per day)
|
|
Transactions last 7 days : 0 (0.0 per day)
|
|
Payees/descriptions : 0
|
|
Accounts : 0 (depth 0)
|
|
Commodities : 0 ()
|
|
Market prices : 0 ()
|
|
|
|
Setting LEDGER_FILE
|
|
How to set LEDGER_FILE permanently depends on your setup:
|
|
|
|
On unix and mac, running these commands in the terminal will work for
|
|
many people; adapt as needed:
|
|
|
|
$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile
|
|
$ source ~/.profile
|
|
|
|
When correctly configured, in a new terminal window env | grep
|
|
LEDGER_FILE will show your file, and so will hledger files.
|
|
|
|
On mac, this additional step might be helpful for GUI applications
|
|
(like Emacs started from the dock): add an entry to ~/.MacOSX/environ-
|
|
ment.plist like
|
|
|
|
{
|
|
"LEDGER_FILE" : "~/finance/2023.journal"
|
|
}
|
|
|
|
and then run killall Dock in a terminal window (or restart the ma-
|
|
chine).
|
|
|
|
On Windows, see https://www.java.com/en/download/help/path.html, or try
|
|
running these commands in a powershell window (let us know if it per-
|
|
sists across a reboot, and if you need to be an Administrator):
|
|
|
|
> CD
|
|
> MKDIR finance
|
|
> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"
|
|
|
|
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 re-
|
|
cent starting date, like today or the start of the week. You can al-
|
|
ways 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:
|
|
|
|
2023-01-01 * opening balances
|
|
assets:bank:checking $1000 = $1000
|
|
assets:bank:savings $2000 = $2000
|
|
assets:cash $100 = $100
|
|
liabilities:creditcard $-50 = $-50
|
|
equity:opening/closing balances
|
|
|
|
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/2023.journal
|
|
Any command line arguments will be used as defaults.
|
|
Use tab key to complete, readline keys to edit, enter to accept defaults.
|
|
An optional (CODE) may follow transaction dates.
|
|
An optional ; COMMENT may follow descriptions or amounts.
|
|
If you make a mistake, enter < at any prompt to go one step backward.
|
|
To end a transaction, enter . when prompted.
|
|
To quit, enter . at a date prompt or press control-d or control-c.
|
|
Date [2023-02-07]: 2023-01-01
|
|
Description: * opening balances
|
|
Account 1: assets:bank:checking
|
|
Amount 1: $1000
|
|
Account 2: assets:bank:savings
|
|
Amount 2 [$-1000]: $2000
|
|
Account 3: assets:cash
|
|
Amount 3 [$-3000]: $100
|
|
Account 4: liabilities:creditcard
|
|
Amount 4 [$-3100]: $-50
|
|
Account 5: equity:opening/closing balances
|
|
Amount 5 [$-3050]:
|
|
Account 6 (or . or enter to finish this transaction): .
|
|
2023-01-01 * opening balances
|
|
assets:bank:checking $1000
|
|
assets:bank:savings $2000
|
|
assets:cash $100
|
|
liabilities:creditcard $-50
|
|
equity:opening/closing balances $-3050
|
|
|
|
Save this transaction to the journal ? [y]:
|
|
Saved.
|
|
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
|
|
Date [2023-01-01]: .
|
|
|
|
If you're using version control, this could be a good time to commit
|
|
the journal. Eg:
|
|
|
|
$ git commit -m 'initial balances' 2023.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:
|
|
|
|
2023/1/10 * gift received
|
|
assets:cash $20
|
|
income:gifts
|
|
|
|
2023.1.12 * farmers market
|
|
expenses:food $13
|
|
assets:cash
|
|
|
|
2023-01-15 paycheck
|
|
income:salary
|
|
assets:bank:checking $1000
|
|
|
|
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 al-
|
|
ready-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:
|
|
|
|
2023-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 re-
|
|
ported by hledger reg checking -C. This will be easier if you gen-
|
|
erally record transaction dates quite similar to your bank's clear-
|
|
ing dates.
|
|
|
|
3. Repeat for other asset/liability accounts.
|
|
|
|
Tip: instead of the register command, use hledger-ui to see a live-up-
|
|
dating register while you edit the journal: hledger-ui --watch --regis-
|
|
ter 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 2023-01-15 and paycheck
|
|
|
|
If you're using version control, this can be another good time to com-
|
|
mit:
|
|
|
|
$ git commit -m 'txns' 2023.journal
|
|
|
|
Reporting
|
|
Here are some basic reports.
|
|
|
|
Show all transactions:
|
|
|
|
$ hledger print
|
|
2023-01-01 * opening balances
|
|
assets:bank:checking $1000
|
|
assets:bank:savings $2000
|
|
assets:cash $100
|
|
liabilities:creditcard $-50
|
|
equity:opening/closing balances $-3050
|
|
|
|
2023-01-10 * gift received
|
|
assets:cash $20
|
|
income:gifts
|
|
|
|
2023-01-12 * farmers market
|
|
expenses:food $13
|
|
assets:cash
|
|
|
|
2023-01-15 * paycheck
|
|
income:salary
|
|
assets:bank:checking $1000
|
|
|
|
2023-01-16 * adjust cash
|
|
assets:cash $-2 = $105
|
|
expenses:misc
|
|
|
|
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 2023-01-16
|
|
|
|
|| 2023-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 2023-01-01-2023-01-16
|
|
|
|
|| 2023-01-01-2023-01-16
|
|
===============++=======================
|
|
Revenues ||
|
|
---------------++-----------------------
|
|
income:gifts || $20
|
|
income:salary || $1000
|
|
---------------++-----------------------
|
|
|| $1020
|
|
===============++=======================
|
|
Expenses ||
|
|
---------------++-----------------------
|
|
expenses:food || $13
|
|
expenses:misc || $2
|
|
---------------++-----------------------
|
|
|| $15
|
|
===============++=======================
|
|
Net: || $1005
|
|
|
|
The final total is your net income during this period.
|
|
|
|
Show transactions affecting your wallet, with running total:
|
|
|
|
$ hledger register cash
|
|
2023-01-01 opening balances assets:cash $100 $100
|
|
2023-01-10 gift received assets:cash $20 $120
|
|
2023-01-12 farmers market assets:cash $-13 $107
|
|
2023-01-16 adjust cash assets:cash $-2 $105
|
|
|
|
Show weekly posting counts as a bar chart:
|
|
|
|
$ hledger activity -W
|
|
2019-12-30 *****
|
|
2023-01-06 ****
|
|
2023-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.
|
|
|
|
BUGS
|
|
We welcome bug reports in the hledger issue tracker (shortcut:
|
|
http://bugs.hledger.org), or on the #hledger chat or hledger mail list
|
|
(https://hledger.org/support).
|
|
|
|
Some known issues and limitations:
|
|
|
|
The need to precede add-on command options with -- when invoked from
|
|
hledger is awkward. (See Command options, Constructing command lines.)
|
|
|
|
A UTF-8-aware system locale must be configured to work with non-ascii
|
|
data. (See Unicode characters, Troubleshooting.)
|
|
|
|
On Microsoft Windows, depending whether you are running in a CMD window
|
|
or a Cygwin/MSYS/Mintty window and how you installed hledger, non-ascii
|
|
characters and colours may not be supported, and the tab key may not be
|
|
supported by hledger add. (Running in a WSL window should resolve
|
|
these.)
|
|
|
|
When processing large data files, hledger uses more memory than Ledger.
|
|
|
|
Troubleshooting
|
|
Here are some common issues you might encounter when you run hledger,
|
|
and how to resolve them (and remember also you can usually get quick
|
|
Support):
|
|
|
|
PATH issues: I get an error like "No command 'hledger' found"
|
|
Depending how you installed hledger, the executables may not be in your
|
|
shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo-
|
|
cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one
|
|
of these directories to your shell's PATH, and/or open a new terminal
|
|
window.
|
|
|
|
LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using
|
|
it
|
|
o LEDGER_FILE should be a real environment variable, not just a shell
|
|
variable. Eg on unix, the command env | grep LEDGER_FILE should show
|
|
it. You may need to use export (see https://stackover-
|
|
flow.com/a/7411509).
|
|
|
|
o You may need to force your shell to see the new configuration. A
|
|
simple way is to close your terminal window and open a new one.
|
|
|
|
LANG issues: I get errors like "Illegal byte sequence" or "Invalid or
|
|
incomplete multibyte or wide character" or "commitAndReleaseBuffer: in-
|
|
valid argument (invalid character)"
|
|
Programs compiled with GHC (hledger, haskell build tools, etc.) need
|
|
the system locale to be UTF-8-aware, or they will fail when they en-
|
|
counter non-ascii characters. To fix it, set the LANG environment
|
|
variable to a locale which supports UTF-8 and which is installed on
|
|
your system.
|
|
|
|
On unix, locale -a lists the installed locales. Look for one which
|
|
mentions utf8, UTF-8 or similar. Some examples: C.UTF-8, en_US.utf-8,
|
|
fr_FR.utf8. If necessary, use your system package manager to install
|
|
one. Then select it by setting the LANG environment variable. Note,
|
|
exact spelling and capitalisation of the locale name may be important:
|
|
Here's one common way to configure this permanently for your shell:
|
|
|
|
$ echo "export LANG=en_US.utf8" >>~/.profile
|
|
# close and re-open terminal window
|
|
|
|
If you are using Nix (not NixOS) for GHC and Hledger, you might need to
|
|
set the LOCALE_ARCHIVE variable:
|
|
|
|
$ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile
|
|
# close and re-open terminal window
|
|
|
|
COMPATIBILITY ISSUES: hledger gives an error with my Ledger file
|
|
Not all of Ledger's journal file syntax or feature set is supported.
|
|
See hledger and Ledger for full details.
|
|
|
|
|
|
|
|
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.32.99 January 2024 HLEDGER(1)
|