1HLEDGER(1) hledger User Manuals HLEDGER(1)
3
7 hledger - robust, friendly plain text accounting (CLI version)
8
10 hledger
11 hledger COMMAND [OPTS] [ARGS]
12 hledger ADDONCMD -- [OPTS] [ARGS]
13
15 hledger is a robust, user-friendly, cross-platform set of programs for
16 tracking money, time, or any other commodity, using double-entry ac‐
17 counting and a simple, editable file format. hledger is inspired by
18 and largely compatible with ledger(1), and largely interconvertible
19 with beancount(1).
20 This manual is for hledger's command line interface, version 1.30.1.
22 It also describes the common options, file formats and concepts used by
23 all hledger programs. It might accidentally teach you some bookkeep‐
24 ing/accounting as well! You don't need to know everything in here to
25 use hledger productively, but when you have a question about function‐
26 ality, this doc should answer it. It is detailed, so do skip ahead or
27 skim when needed. You can read it on hledger.org, or as an info manual
28 or man page on your system. You can also get it from hledger itself
29 with
30 hledger --man, hledger --info or hledger help [TOPIC].
31 The main function of the hledger CLI is to read plain text files de‐
33 scribing financial transactions, crunch the numbers, and print a useful
34 report on the terminal (or save it as HTML, CSV, JSON or SQL). Many
35 reports are available, as subcommands. hledger will also detect other
36 hledger-* executables as extra subcommands.
37 hledger usually reads from (and appends to) a journal file specified by
39 the LEDGER_FILE environment variable (defaulting to
40 $HOME/.hledger.journal); or you can specify files with -f options. It
41 can also read timeclock files, timedot files, or any CSV/SSV/TSV file
42 with a date field.
43 Here is a small journal file describing one transaction:
45 2015-10-16 bought food
47 expenses:food $10
48 assets:cash
49 Transactions are dated movements of money (etc.) between two or more
51 accounts: bank accounts, your wallet, revenue/expense categories, peo‐
52 ple, etc. You can choose any account names you wish, using : to indi‐
53 cate subaccounts. There must be at least two spaces between account
54 name and amount. Positive amounts are inflow to that account (debit),
55 negatives are outflow from it (credit). (Some reports show revenue,
56 liability and equity account balances as negative numbers as a result;
57 this is normal.)
58 hledger’s add command can help you add transactions, or you can install
60 other data entry UIs like hledger-web or hledger-iadd. For more exten‐
61 sive/efficient changes, use a text editor: Emacs + ledger-mode, VIM +
62 vim-ledger, or VS Code + hledger-vscode are some good choices (see
63 https://hledger.org/editors.html).
64 To get started, run hledger add and follow the prompts, or save some
66 entries like the above in $HOME/.hledger.journal, then try commands
67 like:
68 hledger print -x
69 hledger aregister assets
70 hledger balance
71 hledger balancesheet
72 hledger incomestatement.
73 Run hledger to list the commands. See also the "Starting a journal
74 file" and "Setting opening balances" sections in PART 5: COMMON TASKS.
75
78 hledger reads one or more data files, each time you run it. You can
79 specify a file with -f, like so
80 $ hledger -f FILE print
82 Files are most often in hledger's journal format, with the .journal
84 file extension (.hledger or .j also work); these files describe trans‐
85 actions, like an accounting general journal.
86 When no file is specified, hledger looks for .hledger.journal in your
88 home directory.
89 But most people prefer to keep financial files in a dedicated folder,
91 perhaps with version control. Also, starting a new journal file each
92 year is common (it's not required, but helps keep things fast and or‐
93 ganised). So we usually configure a different journal file, by setting
94 the LEDGER_FILE environment variable, to something like ~/fi‐
95 nance/2023.journal. For more about how to do that on your system, see
96 Common tasks > Setting LEDGER_FILE.
97 Data formats
99 Usually the data file is in hledger's journal format, but it can be in
100 any of the supported file formats, which currently are:
101 Reader: Reads: Used for file exten‐
103 sions:
104 ─────────────────────────────────────────────────────────────────────────────
105 journal hledger journal files and some Ledger .journal .j .hledger
106 journals, for transactions .ledger
107 time‐ timeclock files, for precise time log‐ .timeclock
108 clock ging
109 timedot timedot files, for approximate time .timedot
110 logging
111 csv CSV/SSV/TSV/character-separated values, .csv .ssv .tsv
112 for data import .csv.rules .ssv.rules
113 .tsv.rules
114 These formats are described in more detail below.
116 hledger detects the format automatically based on the file extensions
118 shown above. If it can't recognise the file extension, it assumes
119 journal format. So for non-journal files, it's important to use a
120 recognised file extension, so as to either read successfully or to show
121 relevant error messages.
122 You can also force a specific reader/format by prefixing the file path
124 with the format and a colon. Eg, to read a .dat file as csv format:
125 $ hledger -f csv:/some/csv-file.dat stats
127 Standard input
129 The file name - means standard input:
130 $ cat FILE | hledger -f- print
132 If reading non-journal data in this way, you'll need to add a file for‐
134 mat prefix, like:
135 $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
137 Multiple files
139 You can specify multiple -f options, to read multiple files as one big
140 journal. When doing this, note that certain features (described below)
141 will be affected:
142 • Balance assertions will not see the effect of transactions in previ‐
144 ous files. (Usually this doesn't matter as each file will set the
145 corresponding opening balances.)
146 • Some directives will not affect previous or subsequent files.
148 If needed, you can work around these by using a single parent file
150 which includes the others, or concatenating the files into one, eg: cat
151 a.journal b.journal | hledger -f- CMD.
152 Strict mode
154 hledger checks input files for valid data. By default, the most impor‐
155 tant errors are detected, while still accepting easy journal files
156 without a lot of declarations:
157 • Are the input files parseable, with valid syntax ?
159 • Are all transactions balanced ?
161 • Do all balance assertions pass ?
163 With the -s/--strict flag, additional checks are performed:
165 • Are all accounts posted to, declared with an account directive ?
167 (Account error checking)
168 • Are all commodities declared with a commodity directive ? (Commodity
170 error checking)
171 • Are all commodity conversions declared explicitly ?
173 You can use the check command to run individual checks -- the ones
175 listed above and some more.
176
178 hledger provides various subcommands for getting things done. Most of
179 these commands do not change the journal file; they just read it and
180 output a report. A few commands assist with adding data and file man‐
181 agement.
182 To show the commands list, run hledger with no arguments. The commands
184 are described in detail in PART 4: COMMANDS, below.
185 To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS],
187 • CMD is the full command name, or its standard abbreviation shown in
189 the commands list, or any unambiguous prefix of the name.
190 • CMDOPTS are command-specific options, if any. Command-specific op‐
192 tions must be written after the command name. Eg: hledger print -x.
193 • CMDARGS are additional arguments to the command, if any. Most
195 hledger commands accept arguments representing a query, to limit the
196 data in some way. Eg: hledger reg assets:checking.
197 To list a command's options, arguments, and documentation in the termi‐
199 nal, run hledger CMD -h. Eg: hledger bal -h.
200 Add-on commands
202 In addition to the built-in commands, you can install add-on commands:
203 programs or scripts named "hledger-SOMETHING", which will also appear
204 in hledger's commands list. If you used the hledger-install script,
205 you will have several add-ons installed already. Some more can be
206 found in hledger's bin/ directory, documented at
207 https://hledger.org/scripts.html.
208 More precisely, add-on commands are programs or scripts in your shell's
210 PATH, whose name starts with "hledger-" and ends with no extension or a
211 recognised extension (".bat", ".com", ".exe", ".hs", ".js", ".lhs",
212 ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"), and (on unix
213 and mac) which has executable permission for the current user.
214 You can run add-on commands using hledger, much like built-in commands:
216 hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]. But note the double
217 hyphen argument, required before add-on-specific options. Eg: hledger
218 ui -- --watch or hledger web -- --serve. If this causes difficulty,
219 you can always run the add-on directly, without using hledger: hledger-
220 ui --watch or hledger-web --serve.
221
223 Run hledger -h to see general command line help, and general options
224 which are common to most hledger commands. These options can be writ‐
225 ten anywhere on the command line. They can be grouped into help, in‐
226 put, and reporting options:
227 General help options
229 -h --help
230 show general or COMMAND help
231 --man show general or COMMAND user manual with man
233 --info show general or COMMAND user manual with info
235 --version
237 show general or ADDONCMD version
238 --debug[=N]
240 show debug output (levels 1-9, default: 1)
241 General input options
243 -f FILE --file=FILE
244 use a different input file. For stdin, use - (default:
245 $LEDGER_FILE or $HOME/.hledger.journal)
246 --rules-file=RULESFILE
248 Conversion rules file to use when reading CSV (default:
249 FILE.rules)
250 --separator=CHAR
252 Field separator to expect when reading CSV (default: ',')
253 --alias=OLD=NEW
255 rename accounts named OLD to NEW
256 --anon anonymize accounts and payees
258 --pivot FIELDNAME
260 use some other field or tag for the account name
261 -I --ignore-assertions
263 disable balance assertion checks (note: does not disable balance
264 assignments)
265 -s --strict
267 do extra error checking (check that all posted accounts are de‐
268 clared)
269 General reporting options
271 -b --begin=DATE
272 include postings/txns on or after this date (will be adjusted to
273 preceding subperiod start when using a report interval)
274 -e --end=DATE
276 include postings/txns before this date (will be adjusted to fol‐
277 lowing subperiod end when using a report interval)
278 -D --daily
280 multiperiod/multicolumn report by day
281 -W --weekly
283 multiperiod/multicolumn report by week
284 -M --monthly
286 multiperiod/multicolumn report by month
287 -Q --quarterly
289 multiperiod/multicolumn report by quarter
290 -Y --yearly
292 multiperiod/multicolumn report by year
293 -p --period=PERIODEXP
295 set start date, end date, and/or reporting interval all at once
296 using period expressions syntax
297 --date2
299 match the secondary date instead (see command help for other ef‐
300 fects)
301 --today=DATE
303 override today's date (affects relative smart dates, for
304 tests/examples)
305 -U --unmarked
307 include only unmarked postings/txns (can combine with -P or -C)
308 -P --pending
310 include only pending postings/txns
311 -C --cleared
313 include only cleared postings/txns
314 -R --real
316 include only non-virtual postings
317 -NUM --depth=NUM
319 hide/aggregate accounts or postings more than NUM levels deep
320 -E --empty
322 show items with zero amount, normally hidden (and vice-versa in
323 hledger-ui/hledger-web)
324 -B --cost
326 convert amounts to their cost/selling amount at transaction time
327 -V --market
329 convert amounts to their market value in default valuation com‐
330 modities
331 -X --exchange=COMM
333 convert amounts to their market value in commodity COMM
334 --value
336 convert amounts to cost or market value, more flexibly than
337 -B/-V/-X
338 --infer-equity
340 infer conversion equity postings from costs
341 --infer-costs
343 infer costs from conversion equity postings
344 --infer-market-prices
346 use costs as additional market prices, as if they were P direc‐
347 tives
348 --forecast
350 generate transactions from periodic rules, between the latest
351 recorded txn and 6 months from today, or during the specified
352 PERIOD (= is required). Auto posting rules will be applied to
353 these transactions as well. Also, in hledger-ui make future-
354 dated transactions visible.
355 --auto generate extra postings by applying auto posting rules to all
357 txns (not just forecast txns)
358 --verbose-tags
360 add visible tags indicating transactions or postings which have
361 been generated/modified
362 --commodity-style
364 Override the commodity style in the output for the specified
365 commodity. For example 'EUR1.000,00'.
366 --color=WHEN (or --colour=WHEN)
368 Should color-supporting commands use ANSI color codes in text
369 output. 'auto' (default): whenever stdout seems to be a color-
370 supporting terminal. 'always' or 'yes': always, useful eg when
371 piping output into 'less -R'. 'never' or 'no': never. A
372 NO_COLOR environment variable overrides this.
373 --pretty[=WHEN]
375 Show prettier output, e.g. using unicode box-drawing charac‐
376 ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
377 'never' also work). If you provide an argument you must use
378 '=', e.g. '--pretty=yes'.
379 When a reporting option appears more than once in the command line, the
381 last one takes precedence.
382 Some reporting options can also be written as query arguments.
384
386 Here are some details useful to know about for hledger command lines
387 (and elsewhere). Feel free to skip this section until you need it.
388 Option repetition
390 If options are repeated in a command line, hledger will generally use
391 the last (right-most) occurence.
392 Special characters
394 Single escaping (shell metacharacters)
395 In shell command lines, characters significant to your shell - such as
396 spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want
397 hledger to see them. This is done by enclosing them in single or dou‐
398 ble quotes, or by writing a backslash before them. Eg to match an ac‐
399 count name containing a space:
400 $ hledger register 'credit card'
402 or:
404 $ hledger register credit\ card
406 Windows users should keep in mind that cmd treats single quote as a
408 regular character, so you should be using double quotes exclusively.
409 PowerShell treats both single and double quotes as quotes.
410 Double escaping (regular expression metacharacters)
412 Characters significant in regular expressions (described below) - such
413 as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if
414 you don't want them to be interpreted by hledger's regular expression
415 engine. This is done by writing backslashes before them, but since
416 backslash is typically also a shell metacharacter, both shell-escaping
417 and regex-escaping will be needed. Eg to match a literal $ sign while
418 using the bash shell:
419 $ hledger balance cur:'\$'
421 or:
423 $ hledger balance cur:\\$
425 Triple escaping (for add-on commands)
427 When you use hledger to run an external add-on command (described be‐
428 low), one level of shell-escaping is lost from any options or arguments
429 intended for by the add-on command, so those need an extra level of
430 shell-escaping. Eg to match a literal $ sign while using the bash
431 shell and running an add-on command (ui):
432 $ hledger ui cur:'\\$'
434 or:
436 $ hledger ui cur:\\\\$
438 If you wondered why four backslashes, perhaps this helps:
440 unescaped: $
442 escaped: \$
443 double-escaped: \\$
444 triple-escaped: \\\\$
445 Or, you can avoid the extra escaping by running the add-on executable
447 directly:
448 $ hledger-ui cur:\\$
450 Less escaping
452 Options and arguments are sometimes used in places other than the shell
453 command line, where shell-escaping is not needed, so there you should
454 use one less level of escaping. Those places include:
455 • an @argumentfile
457 • hledger-ui's filter field
459 • hledger-web's search form
461 • GHCI's prompt (used by developers).
463 Unicode characters
465 hledger is expected to handle non-ascii characters correctly:
466 • they should be parsed correctly in input files and on the command
468 line, by all hledger tools (add, iadd, hledger-web's search/add/edit
469 forms, etc.)
470 • they should be displayed correctly by all hledger tools, and on-
472 screen alignment should be preserved.
473 This requires a well-configured environment. Here are some tips:
475 • A system locale must be configured, and it must be one that can de‐
477 code the characters being used. In bash, you can set a locale like
478 this: export LANG=en_US.UTF-8. There are some more details in Trou‐
479 bleshooting. This step is essential - without it, hledger will quit
480 on encountering a non-ascii character (as with all GHC-compiled pro‐
481 grams).
482 • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
484 must support unicode
485 • the terminal must be using a font which includes the required unicode
487 glyphs
488 • the terminal should be configured to display wide characters as dou‐
490 ble width (for report alignment)
491 • on Windows, for best results you should run hledger in the same kind
493 of environment in which it was built. Eg hledger built in the stan‐
494 dard CMD.EXE environment (like the binaries on our download page)
495 might show display problems when run in a cygwin or msys terminal,
496 and vice versa. (See eg #961).
497 Regular expressions
499 hledger uses regular expressions in a number of places:
500 • query terms, on the command line and in the hledger-web search form:
502 REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
503 • CSV rules conditional blocks: if REGEX ...
505 • account alias directive and --alias option: alias /REGEX/ = REPLACE‐
507 MENT, --alias /REGEX/=REPLACEMENT
508 hledger's regular expressions come from the regex-tdfa library. If
510 they're not doing what you expect, it's important to know exactly what
511 they support:
512 1. they are case insensitive
514 2. they are infix matching (they do not need to match the entire thing
516 being matched)
517 3. they are POSIX ERE (extended regular expressions)
519 4. they also support GNU word boundaries (\b, \B, \<, \>)
521 5. they do not support backreferences; if you write \1, it will match
523 the digit 1. Except when doing text replacement, eg in account
524 aliases, where backreferences can be used in the replacement string
525 to reference capturing groups in the search regexp.
526 6. they do not support mode modifiers ((?s)), character classes (\w,
528 \d), or anything else not mentioned above.
529 Some things to note:
531 • In the alias directive and --alias option, regular expressions must
533 be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
534 these are not required.
535 • In queries, to match a regular expression metacharacter like $ as a
537 literal character, prepend a backslash. Eg to search for amounts
538 with the dollar sign in hledger-web, write cur:\$.
539 • On the command line, some metacharacters like $ have a special mean‐
541 ing to the shell and so must be escaped at least once more. See Spe‐
542 cial characters.
543 Argument files
545 You can save a set of command line options and arguments in a file, and
546 then reuse them by writing @FILENAME as a command line argument. Eg:
547 hledger bal @foo.args.
548 Inside the argument file, each line should contain just one option or
550 argument. Don't use spaces except inside quotes (or you'll see a con‐
551 fusing error); write = (or nothing) between a flag and its argument.
552 For the special characters mentioned above, use one less level of quot‐
553 ing than you would at the command prompt.
554
556 Output destination
557 hledger commands send their output to the terminal by default. You can
558 of course redirect this, eg into a file, using standard shell syntax:
559 $ hledger print > foo.txt
561 Some commands (print, register, stats, the balance commands) also pro‐
563 vide the -o/--output-file option, which does the same thing without
564 needing the shell. Eg:
565 $ hledger print -o foo.txt
567 $ hledger print -o - # write to stdout (the default)
568 Output format
570 Some commands offer other kinds of output, not just text on the termi‐
571 nal. Here are those commands and the formats currently supported:
572 - txt csv html json sql
574 ──────────────────────────────────────────────────────────────────────────────────────
575 aregister Y Y Y Y
576 balance Y 1 Y 1 Y 1,2 Y
577 balancesheet Y 1 Y 1 Y 1 Y
578 balancesheetequity Y 1 Y 1 Y 1 Y
579 cashflow Y 1 Y 1 Y 1 Y
580 incomestatement Y 1 Y 1 Y 1 Y
581 print Y Y Y Y
582 register Y Y Y
583 • 1 Also affected by the balance commands' --layout option.
585 • 2 balance does not support html output without a report interval or
587 with --budget.
588 The output format is selected by the -O/--output-format=FMT option:
590 $ hledger print -O csv # print CSV on stdout
592 or by the filename extension of an output file specified with the
594 -o/--output-file=FILE.FMT option:
595 $ hledger balancesheet -o foo.csv # write CSV to foo.csv
597 The -O option can be combined with -o to override the file extension,
599 if needed:
600 $ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt
602 Some notes about the various output formats:
604 CSV output
606 • In CSV output, digit group marks (such as thousands separators) are
607 disabled automatically.
608 HTML output
610 • HTML output can be styled by an optional hledger.css file in the same
611 directory.
612 JSON output
614 • This is not yet much used; real-world feedback is welcome.
615 • Our JSON is rather large and verbose, since it is a faithful repre‐
617 sentation of hledger's internal data types. To understand the JSON,
618 read the Haskell type definitions, which are mostly in
619 https://github.com/simonmichael/hledger/blob/master/hledger-
620 lib/Hledger/Data/Types.hs.
621 • hledger represents quantities as Decimal values storing up to 255
623 significant digits, eg for repeating decimals. Such numbers can
624 arise in practice (from automatically-calculated transaction prices),
625 and would break most JSON consumers. So in JSON, we show quantities
626 as simple Numbers with at most 10 decimal places. We don't limit the
627 number of integer digits, but that part is under your control. We
628 hope this approach will not cause problems in practice; if you find
629 otherwise, please let us know. (Cf #1195)
630 SQL output
632 • This is not yet much used; real-world feedback is welcome.
633 • SQL output is expected to work at least with SQLite, MySQL and Post‐
635 gres.
636 • For SQLite, it will be more useful if you modify the generated id
638 field to be a PRIMARY KEY. Eg:
639 $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...
641 • SQL output is structured with the expectations that statements will
643 be executed in the empty database. If you already have tables cre‐
644 ated via SQL output of hledger, you would probably want to either
645 clear tables of existing data (via delete or truncate SQL statements)
646 or drop tables completely as otherwise your postings will be duped.
647 Commodity styles
649 When displaying amounts, hledger infers a standard display style for
650 each commodity/currency, as described below in Commodity display style.
651 If needed, this can be overridden by a -c/--commodity-style option (ex‐
653 cept for cost amounts and amounts displayed by the print command, which
654 are always displayed with all decimal digits). For example, the fol‐
655 lowing will force dollar amounts to be displayed as shown:
656 $ hledger print -c '$1.000,0'
658 This option can repeated to set the display style for multiple commodi‐
660 ties/currencies. Its argument is as described in the commodity direc‐
661 tive.
662 Colour
664 In terminal output, some commands can produce colour when the terminal
665 supports it:
666 • if the --color/--colour option is given a value of yes or always (or
668 no or never), colour will (or will not) be used;
669 • otherwise, if the NO_COLOR environment variable is set, colour will
671 not be used;
672 • otherwise, colour will be used if the output (terminal or file) sup‐
674 ports it.
675 Box-drawing
677 In terminal output, you can enable unicode box-drawing characters to
678 render prettier tables:
679 • if the --pretty option is given a value of yes or always (or no or
681 never), unicode characters will (or will not) be used;
682 • otherwise, unicode characters will not be used.
684 Paging
686 When showing long output in the terminal, hledger will try to use the
687 pager specified by the PAGER environment variable, or less, or more.
688 (A pager is a helper program that shows one page at a time rather than
689 scrolling everything off screen). Currently it does this only for help
690 output, not for reports; specifically,
691 • when listing commands, with hledger
693 • when showing help with hledger [CMD] --help,
695 • when viewing manuals with hledger help or hledger --man.
697 Note the pager is expected to handle ANSI codes, which hledger uses eg
699 for bold emphasis. For the common pager less (and its more compatibil‐
700 ity mode), we add R to the LESS and MORE environment variables to make
701 this work. If you use a different pager, you might need to configure
702 it similarly, to avoid seeing junk on screen (let us know). Otherwise,
703 you can set the NO_COLOR environment variable to 1 to disable all ANSI
704 output (see Colour).
705 Debug output
707 We intend hledger to be relatively easy to troubleshoot, introspect and
708 develop. You can add --debug[=N] to any hledger command line to see
709 additional debug output. N ranges from 1 (least output, the default)
710 to 9 (maximum output). Typically you would start with 1 and increase
711 until you are seeing enough. Debug output goes to stderr, and is not
712 affected by -o/--output-file (unless you redirect stderr to stdout, eg:
713 2>&1). It will be interleaved with normal output, which can help re‐
714 veal when parts of the code are evaluated. To capture debug output in
715 a log file instead, you can usually redirect stderr, eg:
716 hledger bal --debug=3 2>hledger.log
718
720 These environment variables affect hledger:
721 COLUMNS This is normally set by your terminal; some hledger commands
723 (register) will format their output to this width. If not set, they
724 will try to use the available terminal width.
725 LEDGER_FILE The main journal file to use when not specified with
727 -f/--file. Default: $HOME/.hledger.journal.
728 NO_COLOR If this environment variable is set (with any value), hledger
730 will not use ANSI color codes in terminal output, unless overridden by
731 an explicit --color/--colour option.
732
735 hledger's default file format, representing a General Journal. Here's
736 a cheatsheet/mini-tutorial, or you can skip ahead to About journal for‐
737 mat.
738 Journal cheatsheet
740 # Here is the main syntax of hledger's journal format
741 # (omitting extra Ledger compatibility syntax).
742 # hledger journals contain comments, directives, and transactions, in any order:
743 ###############################################################################
745 # 1. Comment lines are for notes or temporarily disabling things.
746 # They begin with #, ;, or a line containing the word "comment".
747 # hash comment line
749 ; semicolon comment line
750 comment
751 These lines
752 are commented.
753 end comment
754 # Some but not all hledger entries can have same-line comments attached to them,
756 # from ; (semicolon) to end of line.
757 ###############################################################################
759 # 2. Directives modify parsing or reports in some way.
760 # They begin with a word or letter (or symbol).
761 account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;.
763 account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX)
764 alias chkg = assets:checking
765 commodity $0.00
766 decimal-mark .
767 include /dev/null
768 payee Whole Foods
769 P 2022-01-01 AAAA $1.40
770 ~ monthly budget goals ; <- 2+ spaces between period expression and description
771 expenses:food $400
772 expenses:home $1000
773 budgeted
774 ###############################################################################
776 # 3. Transactions are what it's all about; they are dated events,
777 # usually describing movements of money.
778 # They begin with a date.
779 # DATE DESCRIPTION ; This is a transaction comment.
781 # ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment.
782 # ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented.
783 # ; ^^ At least 2 spaces between account and amount.
784 # ... ; Any number of postings is allowed. The amounts must balance (sum to 0).
785 2022-01-01 opening balances are declared this way
787 assets:checking $1000 ; Account names can be anything. lower case is easy to type.
788 assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common.
789 assets:cash:wallet $100 ; : indicates subaccounts.
790 liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative.
791 equity ; One amount can be left blank; $-1900 is inferred here.
792 2022-04-15 * (#12345) pay taxes
794 ; There can be a ! or * after the date meaning "pending" or "cleared".
795 ; There can be a transaction code (text in parentheses) after the date/status.
796 ; Amounts' sign represents direction of flow, or credit/debit:
797 assets:checking $-500 ; minus means removed from this account (credit)
798 expenses:tax:us:2021 $500 ; plus means added to this account (debit)
799 ; revenue/expense categories are also "accounts"
800 2022-01-01 ; The description is optional.
802 ; Any currency/commodity symbols are allowed, on either side.
803 assets:cash:wallet GBP -10
804 expenses:clothing GBP 10
805 assets:gringotts -10 gold
806 assets:pouch 10 gold
807 revenues:gifts -2 "Liquorice Wands" ; Complex symbols
808 assets:bag 2 "Liquorice Wands" ; must be double-quoted.
809 2022-01-01 Cost in another commodity can be noted with @ or @@
811 assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost
812 assets:investments 3.0 AAAA @@ $4 ; @@ means total cost
813 assets:checking $-7.00
814 2022-01-02 assert balances
816 ; Balances can be asserted for extra error checking, in any transaction.
817 assets:investments 0 AAAA = 5.0 AAAA
818 assets:pouch 0 gold = 10 gold
819 assets:savings $0 = $1000
820 1999-12-31 Ordering transactions by date is recommended but not required.
822 ; Postings are not required.
823 2022.01.01 These date
825 2022/1/1 formats are
826 12/31 also allowed (but consistent YYYY-MM-DD is recommended).
827 About journal format
829 hledger's usual data source is a plain text file containing journal en‐
830 tries in hledger journal format. This file represents a standard ac‐
831 counting general journal. I use file names ending in .journal, but
832 that's not required. The journal file contains a number of transaction
833 entries, each describing a transfer of money (or any commodity) between
834 two or more named accounts, in a simple format readable by both hledger
835 and humans.
836 hledger's journal format is compatible with most of Ledger's journal
838 format, but not all of it. The differences and interoperation tips are
839 described at hledger and Ledger. With some care, and by avoiding in‐
840 compatible features, you can keep your hledger journal readable by
841 Ledger and vice versa. This can useful eg for comparing the behaviour
842 of one app against the other.
843 You can use hledger without learning any more about this file; just use
845 the add or web or import commands to create and update it.
846 Many users, though, edit the journal file with a text editor, and track
848 changes with a version control system such as git. Editor addons such
849 as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
850 hledger-vscode for Visual Studio Code, make this easier, adding colour,
851 formatting, tab completion, and useful commands. See Editor configura‐
852 tion at hledger.org for the full list.
853 Here's a description of each part of the file format (and hledger's
855 data model).
856 A hledger journal file can contain three kinds of thing: file comments,
858 transactions, and/or directives (counting periodic transaction rules
859 and auto posting rules as directives).
860 Comments
862 Lines in the journal will be ignored if they begin with a hash (#) or a
863 semicolon (;). (See also Other syntax.) hledger will also ignore re‐
864 gions beginning with a comment line and ending with an end comment line
865 (or file end). Here's a suggestion for choosing between them:
866 • # for top-level notes
868 • ; for commenting out things temporarily
870 • comment for quickly commenting large regions (remember it's there, or
872 you might get confused)
873 Eg:
875 # a comment line
877 ; another commentline
878 comment
879 A multi-line comment block,
880 continuing until "end comment" directive
881 or the end of the current file.
882 end comment
883 Some hledger entries can have same-line comments attached to them, from
885 ; (semicolon) to end of line. See Transaction comments, Posting com‐
886 ments, and Account comments below.
887 Transactions
889 Transactions are the main unit of information in a journal file. They
890 represent events, typically a movement of some quantity of commodities
891 between two or more named accounts.
892 Each transaction is recorded as a journal entry, beginning with a sim‐
894 ple date in column 0. This can be followed by any of the following op‐
895 tional fields, separated by spaces:
896 • a status character (empty, !, or *)
898 • a code (any short number or text, enclosed in parentheses)
900 • a description (any remaining text until end of line or a semicolon)
902 • a comment (any remaining text following a semicolon until end of
904 line, and any following indented lines beginning with a semicolon)
905 • 0 or more indented posting lines, describing what was transferred and
907 the accounts involved (indented comment lines are also allowed, but
908 not blank lines or non-indented lines).
909 Here's a simple journal file containing one transaction:
911 2008/01/01 income
913 assets:bank:checking $1
914 income:salary $-1
915 Dates
917 Simple dates
918 Dates in the journal file use simple dates format: YYYY-MM-DD or
919 YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be
920 omitted, in which case it will be inferred from the context: the cur‐
921 rent transaction, the default year set with a Y directive, or the cur‐
922 rent date when the command is run. Some examples: 2010-01-31,
923 2010/01/31, 2010.1.31, 1/31.
924 (The UI also accepts simple dates, as well as the more flexible smart
926 dates documented in the hledger manual.)
927 Posting dates
929 You can give individual postings a different date from their parent
930 transaction, by adding a posting comment containing a tag (see below)
931 like date:DATE. This is probably the best way to control posting dates
932 precisely. Eg in this example the expense should appear in May re‐
933 ports, and the deduction from checking should be reported on 6/1 for
934 easy bank reconciliation:
935 2015/5/30
937 expenses:food $10 ; food purchased on saturday 5/30
938 assets:checking ; bank cleared it on monday, date:6/1
939 $ hledger -f t.j register food
941 2015-05-30 expenses:food $10 $10
942 $ hledger -f t.j register checking
944 2015-06-01 assets:checking $-10 $-10
945 DATE should be a simple date; if the year is not specified it will use
947 the year of the transaction's date.
948 The date: tag must have a valid simple date value if it is present, eg
949 a date: tag with no value is not allowed.
950 Status
952 Transactions, or individual postings within a transaction, can have a
953 status mark, which is a single character before the transaction de‐
954 scription or posting account name, separated from it by a space, indi‐
955 cating one of three statuses:
956 mark status
958 ──────────────────
959 unmarked
960 ! pending
961 * cleared
962 When reporting, you can filter by status with the -U/--unmarked,
964 -P/--pending, and -C/--cleared flags; or the status:, status:!, and
965 status:* queries; or the U, P, C keys in hledger-ui.
966 Note, in Ledger and in older versions of hledger, the "unmarked" state
968 is called "uncleared". As of hledger 1.3 we have renamed it to un‐
969 marked for clarity.
970 To replicate Ledger and old hledger's behaviour of also matching pend‐
972 ing, combine -U and -P.
973 Status marks are optional, but can be helpful eg for reconciling with
975 real-world accounts. Some editor modes provide highlighting and short‐
976 cuts for working with status. Eg in Emacs ledger-mode, you can toggle
977 transaction status with C-c C-e, or posting status with C-c C-c.
978 What "uncleared", "pending", and "cleared" actually mean is up to you.
980 Here's one suggestion:
981 status meaning
983 ──────────────────────────────────────────────────────────────────────────
984 uncleared recorded but not yet reconciled; needs review
985 pending tentatively reconciled (if needed, eg during a big reconcil‐
986 iation)
987 cleared complete, reconciled as far as possible, and considered cor‐
988 rect
989 With this scheme, you would use -PC to see the current balance at your
991 bank, -U to see things which will probably hit your bank soon (like un‐
992 cashed checks), and no flags to see the most up-to-date state of your
993 finances.
994 Code
996 After the status mark, but before the description, you can optionally
997 write a transaction "code", enclosed in parentheses. This is a good
998 place to record a check number, or some other important transaction id
999 or reference number.
1000 Description
1002 A transaction's description is the rest of the line following the date
1003 and status mark (or until a comment begins). Sometimes called the
1004 "narration" in traditional bookkeeping, it can be used for whatever you
1005 wish, or left blank. Transaction descriptions can be queried, unlike
1006 comments.
1007 Payee and note
1009 You can optionally include a | (pipe) character in descriptions to sub‐
1010 divide the description into separate fields for payee/payer name on the
1011 left (up to the first |) and an additional note field on the right (af‐
1012 ter the first |). This may be worthwhile if you need to do more pre‐
1013 cise querying and pivoting by payee or by note.
1014 Transaction comments
1016 Text following ;, after a transaction description, and/or on indented
1017 lines immediately below it, form comments for that transaction. They
1018 are reproduced by print but otherwise ignored, except they may contain
1019 tags, which are not ignored.
1020 2012-01-01 something ; a transaction comment
1022 ; a second line of transaction comment
1023 expenses 1
1024 assets
1025 Postings
1027 A posting is an addition of some amount to, or removal of some amount
1028 from, an account. Each posting line begins with at least one space or
1029 tab (2 or 4 spaces is common), followed by:
1030 • (optional) a status character (empty, !, or *), followed by a space
1032 • (required) an account name (any text, optionally containing single
1034 spaces, until end of line or a double space)
1035 • (optional) two or more spaces or tabs followed by an amount.
1037 Positive amounts are being added to the account, negative amounts are
1039 being removed.
1040 The amounts within a transaction must always sum up to zero. As a con‐
1042 venience, one amount may be left blank; it will be inferred so as to
1043 balance the transaction.
1044 Be sure to note the unusual two-space delimiter between account name
1046 and amount. This makes it easy to write account names containing spa‐
1047 ces. But if you accidentally leave only one space (or tab) before the
1048 amount, the amount will be considered part of the account name.
1049 Account names
1051 Accounts are the main way of categorising things in hledger. As in
1052 Double Entry Bookkeeping, they can represent real world accounts (such
1053 as a bank account), or more abstract categories such as "money borrowed
1054 from Frank" or "money spent on electricity".
1055 You can use any account names you like, but we usually start with the
1057 traditional accounting categories, which in english are assets, liabil‐
1058 ities, equity, revenues, expenses. (You might see these referred to as
1059 A, L, E, R, X for short.)
1060 For more precise reporting, we usually divide the top level accounts
1062 into more detailed subaccounts, by writing a full colon between account
1063 name parts. For example, from the account names assets:bank:checking
1064 and expenses:food, hledger will infer this hierarchy of five accounts:
1065 assets
1067 assets:bank
1068 assets:bank:checking
1069 expenses
1070 expenses:food
1071 Shown as an outline, the hierarchical tree structure is more clear:
1073 assets
1075 bank
1076 checking
1077 expenses
1078 food
1079 hledger reports can summarise the account tree to any depth, so you can
1081 go as deep as you like with subcategories, but keeping your account
1082 names relatively simple may be best when starting out.
1083 Account names may be capitalised or not; they may contain letters, num‐
1085 bers, symbols, or single spaces. Note, when an account name and an
1086 amount are written on the same line, they must be separated by two or
1087 more spaces (or tabs).
1088 Parentheses or brackets enclosing the full account name indicate vir‐
1090 tual postings, described below. Parentheses or brackets internal to
1091 the account name have no special meaning.
1092 Account names can be altered temporarily or permanently by account
1094 aliases.
1095 Amounts
1097 After the account name, there is usually an amount. (Important: be‐
1098 tween account name and amount, there must be two or more spaces.)
1099 hledger's amount format is flexible, supporting several international
1101 formats. Here are some examples. Amounts have a number (the "quan‐
1102 tity"):
1103 1
1105 ..and usually a currency symbol or commodity name (more on this below),
1107 to the left or right of the quantity, with or without a separating
1108 space:
1109 $1
1111 4000 AAPL
1112 3 "green apples"
1113 Amounts can be preceded by a minus sign (or a plus sign, though plus is
1115 the default), The sign can be written before or after a left-side com‐
1116 modity symbol:
1117 -$1
1119 $-1
1120 One or more spaces between the sign and the number are acceptable when
1122 parsing (but they won't be displayed in output):
1123 + $1
1125 $- 1
1126 Scientific E notation is allowed:
1128 1E-6
1130 EUR 1E3
1131 Decimal marks, digit group marks
1133 A decimal mark can be written as a period or a comma:
1134 1.23
1136 1,23456780000009
1137 In the integer part of the quantity (left of the decimal mark), groups
1139 of digits can optionally be separated by a digit group mark - a space,
1140 comma, or period (different from the decimal mark):
1141 $1,000,000.00
1143 EUR 2.000.000,00
1144 INR 9,99,99,999.00
1145 1 000 000.9455
1146 Note, a number containing a single digit group mark and no decimal mark
1148 is ambiguous. Are these digit group marks or decimal marks ?
1149 1,000
1151 1.000
1152 If you don't tell it otherwise, hledger will assume both of the above
1154 are decimal marks, parsing both numbers as 1.
1155 To prevent confusing parsing mistakes and undetected typos, especially
1157 if your data contains digit group marks (eg, thousands separators), we
1158 recommend explicitly declaring the decimal mark character in each jour‐
1159 nal file, using a directive at the top of the file. The decimal-mark
1160 directive is best, otherwise commodity directives will also work.
1161 These are described below.
1162 Commodity
1164 Amounts in hledger have both a "quantity", which is a signed decimal
1165 number, and a "commodity", which is a currency symbol, stock ticker, or
1166 any word or phrase describing something you are tracking.
1167 If the commodity name contains non-letters (spaces, numbers, or punctu‐
1169 ation), you must always write it inside double quotes ("green apples",
1170 "ABC123").
1171 If you write just a bare number, that too will have a commodity, with
1173 name ""; we call that the "no-symbol commodity".
1174 Actually, hledger combines these single-commodity amounts into more
1176 powerful multi-commodity amounts, which are what it works with most of
1177 the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456
1178 TSLA. In practice, you will only see multi-commodity amounts in
1179 hledger's output; you can't write them directly in the journal file.
1180 (If you are writing scripts or working with hledger's internals, these
1182 are the Amount and MixedAmount types.)
1183 Directives influencing number parsing and display
1185 You can add decimal-mark and commodity directives to the journal, to
1186 declare and control these things more explicitly and precisely. These
1187 are described below, but here's a quick example:
1188 # the decimal mark character used by all amounts in this file (all commodities)
1190 decimal-mark .
1191 # display styles for the $, EUR, INR and no-symbol commodities:
1193 commodity $1,000.00
1194 commodity EUR 1.000,00
1195 commodity INR 9,99,99,999.00
1196 commodity 1 000 000.9455
1197 Commodity display style
1199 For the amounts in each commodity, hledger chooses a consistent display
1200 style to use in most reports. (Exceptions: price amounts, and all
1201 amounts displayed by the print command, are displayed with all of their
1202 decimal digits visible.)
1203 A commodity's display style is inferred as follows.
1205 First, if a default commodity is declared with D, this commodity and
1207 its style is applied to any no-symbol amounts in the journal.
1208 Then each commodity's style is inferred from one of the following, in
1210 order of preference:
1211 • The commodity directive for that commodity (including the no-symbol
1213 commodity), if any.
1214 • The amounts in that commodity seen in the journal's transactions.
1216 (Posting amounts only; prices and periodic or auto rules are ignored,
1217 currently.)
1218 • The built-in fallback style, which looks like this: $1000.00. (Sym‐
1220 bol on the left, period decimal mark, two decimal places.)
1221 A style is inferred from journal amounts as follows:
1223 • Use the general style (decimal mark, symbol placement) of the first
1225 amount
1226 • Use the first-seen digit group style (digit group mark, digit group
1228 sizes), if any
1229 • Use the maximum number of decimal places of all.
1231 Cost amounts don't affect the commodity display style directly, but oc‐
1233 casionally they can do so indirectly (eg when a posting's amount is in‐
1234 ferred using a cost). If you find this causing problems, use a commod‐
1235 ity directive to fix the display style.
1236 To summarise: each commodity's amounts will be normalised to (a) the
1238 style declared by a commodity directive, or (b) the style of the first
1239 posting amount in the journal, with the first-seen digit group style
1240 and the maximum-seen number of decimal places. So if your reports are
1241 showing amounts in a way you don't like, eg with too many decimal
1242 places, use a commodity directive. Some examples:
1243 # declare euro, dollar, bitcoin and no-symbol commodities and set their
1245 # input number formats and output display styles:
1246 commodity EUR 1.000,
1247 commodity $1000.00
1248 commodity 1000.00000000 BTC
1249 commodity 1 000.
1250 The inferred commodity style can be overridden by supplying a command
1252 line option.
1253 Rounding
1255 Amounts are stored internally as decimal numbers with up to 255 decimal
1256 places, and displayed with the number of decimal places specified by
1257 the commodity display style. Note, hledger uses banker's rounding: it
1258 rounds to the nearest even number, eg 0.5 displayed with zero decimal
1259 places is "0").
1260 Costs
1262 After a posting amount, you can note its cost (when buying) or selling
1263 price (when selling) in another commodity, by writing either @ UNIT‐
1264 PRICE or @@ TOTALPRICE after it. This indicates a conversion transac‐
1265 tion, where one commodity is exchanged for another.
1266 (You might also see this called "transaction price" in hledger docs,
1268 discussions, or code; that term was directionally neutral and reminded
1269 that it is a price specific to a transaction, but we now just call it
1270 "cost", with the understanding that the transaction could be a purchase
1271 or a sale.)
1272 Costs are usually written explicitly with @ or @@, but can also be in‐
1274 ferred automatically for simple multi-commodity transactions. Note, if
1275 costs are inferred, the order of postings is significant; the first
1276 posting will have a cost attached, in the commodity of the second.
1277 As an example, here are several ways to record purchases of a foreign
1279 currency in hledger, using the cost notation either explicitly or im‐
1280 plicitly:
1281 1. Write the price per unit, as @ UNITPRICE after the amount:
1283 2009/1/1
1285 assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each
1286 assets:dollars ; balancing amount is -$135.00
1287 2. Write the total price, as @@ TOTALPRICE after the amount:
1289 2009/1/1
1291 assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot
1292 assets:dollars
1293 3. Specify amounts for all postings, using exactly two commodities, and
1295 let hledger infer the price that balances the transaction. Note the
1296 effect of posting order: the price is added to first posting, making
1297 it €100 @@ $135, as in example 2:
1298 2009/1/1
1300 assets:euros €100 ; one hundred euros purchased
1301 assets:dollars $-135 ; for $135
1302 Amounts can be converted to cost at report time using the -B/--cost
1304 flag; this is discussed more in the ˜COST REPORTING section.
1305 Note that the cost normally should be a positive amount, though it's
1307 not required to be. This can be a little confusing, see discussion at
1308 --infer-market-prices: market prices from transactions.
1309 Other cost/lot notations
1311 A slight digression for Ledger and Beancount users. Ledger has a num‐
1312 ber of cost/lot-related notations:
1313 • @ UNITCOST and @@ TOTALCOST
1315 • expresses a conversion rate, as in hledger
1317 • when buying, also creates a lot than can be selected at selling
1319 time
1320 • (@) UNITCOST and (@@) TOTALCOST (virtual cost)
1322 • like the above, but also means "this cost was exceptional, don't
1324 use it when inferring market prices".
1325 Currently, hledger treats the above like @ and @@; the parentheses are
1327 ignored.
1328 • {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price)
1330 • when buying, means "this cost is also the fixed price, don't let it
1332 fluctuate in value reports"
1333 • {UNITCOST} and {{TOTALCOST}} (lot price)
1335 • can be used identically to @ UNITCOST and @@ TOTALCOST, also cre‐
1337 ates a lot
1338 • when selling, combined with @ ..., specifies an investment lot by
1340 its cost basis; does not check if that lot is present
1341 • and related: [YYYY/MM/DD] (lot date)
1343 • when buying, attaches this acquisition date to the lot
1345 • when selling, selects a lot by its acquisition date
1347 • (SOME TEXT) (lot note)
1349 • when buying, attaches this note to the lot
1351 • when selling, selects a lot by its note
1353 Currently, hledger accepts any or all of the above in any order after
1355 the posting amount, but ignores them. (This can break transaction bal‐
1356 ancing.)
1357 For Beancount users, the notation and behaviour is different:
1359 • @ UNITCOST and @@ TOTALCOST
1361 • expresses a cost without creating a lot, as in hledger
1363 • when buying (augmenting) or selling (reducing) a lot, combined with
1365 {...}: documents the cost/selling price (not used for transaction
1366 balancing)
1367 • {UNITCOST} and {{TOTALCOST}}
1369 • when buying (augmenting), expresses the cost for transaction bal‐
1371 ancing, and also creates a lot with this cost basis attached
1372 • when selling (reducing),
1374 • selects a lot by its cost basis
1376 • raises an error if that lot is not present or can not be selected
1378 unambiguously (depending on booking method configured)
1379 • expresses the selling price for transaction balancing
1381 Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but
1383 ignores it.
1384 • variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT‐
1386 COST, YYYY-MM-DD, "LABEL"} etc.
1387 Currently, hledger rejects these.
1389 Balance assertions
1391 hledger supports Ledger-style balance assertions in journal files.
1392 These look like, for example, = EXPECTEDBALANCE following a posting's
1393 amount. Eg here we assert the expected dollar balance in accounts a
1394 and b after each posting:
1395 2013/1/1
1397 a $1 =$1
1398 b =$-1
1399 2013/1/2
1401 a $1 =$2
1402 b $-1 =$-2
1403 After reading a journal file, hledger will check all balance assertions
1405 and report an error if any of them fail. Balance assertions can pro‐
1406 tect you from, eg, inadvertently disrupting reconciled balances while
1407 cleaning up old entries. You can disable them temporarily with the
1408 -I/--ignore-assertions flag, which can be useful for troubleshooting or
1409 for reading Ledger files. (Note: this flag currently does not disable
1410 balance assignments, described below).
1411 Assertions and ordering
1413 hledger sorts an account's postings and assertions first by date and
1414 then (for postings on the same day) by parse order. Note this is dif‐
1415 ferent from Ledger, which sorts assertions only by parse order. (Also,
1416 Ledger assertions do not see the accumulated effect of repeated post‐
1417 ings to the same account within a transaction.)
1418 So, hledger balance assertions keep working if you reorder differently-
1420 dated transactions within the journal. But if you reorder same-dated
1421 transactions or postings, assertions might break and require updating.
1422 This order dependence does bring an advantage: precise control over the
1423 order of postings and assertions within a day, so you can assert intra-
1424 day balances.
1425 Assertions and multiple included files
1427 Multiple files included with the include directive are processed as if
1428 concatenated into one file, preserving their order and the posting or‐
1429 der within each file. It means that balance assertions in later files
1430 will see balance from earlier files.
1431 And if you have multiple postings to an account on the same day, split
1433 across multiple files, and you want to assert the account's balance on
1434 that day, you'll need to put the assertion in the right file - the last
1435 one in the sequence, probably.
1436 Assertions and multiple -f files
1438 Unlike include, when multiple files are specified on the command line
1439 with multiple -f/--file options, balance assertions will not see bal‐
1440 ance from earlier files. This can be useful when you do not want prob‐
1441 lems in earlier files to disrupt valid assertions in later files.
1442 If you do want assertions to see balance from earlier files, use in‐
1444 clude, or concatenate the files temporarily.
1445 Assertions and commodities
1447 The asserted balance must be a simple single-commodity amount, and in
1448 fact the assertion checks only this commodity's balance within the
1449 (possibly multi-commodity) account balance. This is how assertions
1450 work in Ledger also. We could call this a "partial" balance assertion.
1451 To assert the balance of more than one commodity in an account, you can
1453 write multiple postings, each asserting one commodity's balance.
1454 You can make a stronger "total" balance assertion by writing a double
1456 equals sign (== EXPECTEDBALANCE). This asserts that there are no other
1457 commodities in the account besides the asserted one (or at least, that
1458 their balance is 0).
1459 2013/1/1
1461 a $1
1462 a 1€
1463 b $-1
1464 c -1€
1465 2013/1/2 ; These assertions succeed
1467 a 0 = $1
1468 a 0 = 1€
1469 b 0 == $-1
1470 c 0 == -1€
1471 2013/1/3 ; This assertion fails as 'a' also contains 1€
1473 a 0 == $1
1474 It's not yet possible to make a complete assertion about a balance that
1476 has multiple commodities. One workaround is to isolate each commodity
1477 into its own subaccount:
1478 2013/1/1
1480 a:usd $1
1481 a:euro 1€
1482 b
1483 2013/1/2
1485 a 0 == 0
1486 a:usd 0 == $1
1487 a:euro 0 == 1€
1488 Assertions and prices
1490 Balance assertions ignore costs, and should normally be written without
1491 one:
1492 2019/1/1
1494 (a) $1 @ €1 = $1
1495 We do allow prices to be written there, however, and print shows them,
1497 even though they don't affect whether the assertion passes or fails.
1498 This is for backward compatibility (hledger's close command used to
1499 generate balance assertions with prices), and because balance assign‐
1500 ments do use them (see below).
1501 Assertions and subaccounts
1503 The balance assertions above (= and ==) do not count the balance from
1504 subaccounts; they check the account's exclusive balance only. You can
1505 assert the balance including subaccounts by writing =* or ==*, eg:
1506 2019/1/1
1508 equity:opening balances
1509 checking:a 5
1510 checking:b 5
1511 checking 1 ==* 11
1512 Assertions and virtual postings
1514 Balance assertions always consider both real and virtual postings; they
1515 are not affected by the --real/-R flag or real: query.
1516 Assertions and auto postings
1518 Balance assertions are affected by the --auto flag, which generates
1519 auto postings, which can alter account balances. Because auto postings
1520 are optional in hledger, accounts affected by them effectively have two
1521 balances. But balance assertions can only test one or the other of
1522 these. So to avoid making fragile assertions, either:
1523 • assert the balance calculated with --auto, and always use --auto with
1525 that file
1526 • or assert the balance calculated without --auto, and never use --auto
1528 with that file
1529 • or avoid balance assertions on accounts affected by auto postings (or
1531 avoid auto postings entirely).
1532 Assertions and precision
1534 Balance assertions compare the exactly calculated amounts, which are
1535 not always what is shown by reports. Eg a commodity directive may
1536 limit the display precision, but this will not affect balance asser‐
1537 tions. Balance assertion failure messages show exact amounts.
1538 Posting comments
1540 Text following ;, at the end of a posting line, and/or on indented
1541 lines immediately below it, form comments for that posting. They are
1542 reproduced by print but otherwise ignored, except they may contain
1543 tags, which are not ignored.
1544 2012-01-01
1546 expenses 1 ; a comment for posting 1
1547 assets
1548 ; a comment for posting 2
1549 ; a second comment line for posting 2
1550 Tags
1552 Tags are a way to add extra labels or labelled data to transactions,
1553 postings, or accounts, which you can then search or pivot on.
1554 They are written as a word (optionally hyphenated) immediately followed
1556 by a full colon, in a transaction or posting or account directive's
1557 comment. (This is an exception to the usual rule that things in com‐
1558 ments are ignored.) Eg, here four different tags are recorded: one on
1559 the checking account, two on the transaction, and one on the expenses
1560 posting:
1561 account assets:checking ; accounttag:
1563 2017/1/16 bought groceries ; transactiontag-1:
1565 ; transactiontag-2:
1566 assets:checking $-1
1567 expenses:food $1 ; postingtag:
1568 Postings also inherit tags from their transaction and their account.
1570 And transactions also acquire tags from their postings (and postings'
1571 accounts). So in the example above, the expenses posting effectively
1572 has all four tags (by inheriting from account and transaction), and the
1573 transaction also has all four tags (by acquiring from the expenses
1574 posting).
1575 You can list tag names with hledger tags [NAMEREGEX], or match by tag
1577 name with a tag:NAMEREGEX query.
1578 Tag values
1580 Tags can have a value, which is any text after the colon up until a
1581 comma or end of line (with surrounding whitespace removed). Note this
1582 means that hledger tag values can not contain commas. Eg in the fol‐
1583 lowing posting, the three tags' values are "value 1", "value 2", and ""
1584 (empty) respectively:
1585 expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz
1587 Note that tags can be repeated, and are additive rather than overrid‐
1589 ing: when the same tag name is seen again with a new value, the new
1590 name:value pair is added to the tags. (It is not possible to override
1591 a tag's value or remove a tag.)
1592 You can list a tag's values with hledger tags TAGNAME --values, or
1594 match by tag value with a tag:NAMEREGEX=VALUEREGEX query.
1595 Directives
1597 Besides transactions, there is something else you can put in a journal
1598 file: directives. These are declarations, beginning with a keyword,
1599 that modify hledger's behaviour. Some directives can have more spe‐
1600 cific subdirectives, indented below them. hledger's directives are
1601 similar to Ledger's in many cases, but there are also many differences.
1602 Directives are not required, but can be useful. Here are the main di‐
1603 rectives:
1604 purpose directive
1606 ──────────────────────────────────────────────────────────────────────────
1607 READING DATA:
1608 Rewrite account names alias
1609 Comment out sections of the file comment
1610 Declare file's decimal mark, to help decimal-mark
1611 parse amounts accurately
1612 Include other data files include
1613 GENERATING DATA:
1614 Generate recurring transactions or bud‐ ~
1615 get goals
1616 Generate extra postings on existing =
1617 transactions
1618 CHECKING FOR ERRORS:
1619 Define valid entities to provide more account, commodity, payee, tag
1620 error checking
1621 REPORTING:
1622 Declare accounts' type and display order account
1623 Declare commodity display styles commodity
1624 Declare market prices P
1625 Directives and multiple files
1627 Directives vary in their scope, ie which journal entries and which in‐
1628 put files they affect. Most often, a directive will affect the follow‐
1629 ing entries and included files if any, until the end of the current
1630 file - and no further. You might find this inconvenient! For example,
1631 alias directives do not affect parent or sibling files. But there are
1632 usually workarounds; for example, put alias directives in your top-most
1633 file, before including other files.
1634 The restriction, though it may be annoying at first, is in a good
1636 cause; it allows reports to be stable and deterministic, independent of
1637 the order of input. Without it, reports could show different numbers
1638 depending on the order of -f options, or the positions of include di‐
1639 rectives in your files.
1640 Directive effects
1642 Here are all hledger's directives, with their effects and scope sum‐
1643 marised - nine main directives, plus four others which we consider non-
1644 essential:
1645 di‐ what it does ends
1647 rec‐ at
1648 tive file
1649 end?
1650 ──────────────────────────────────────────────────────────────────────────────────────
1651 ac‐ Declares an account, for checking all entries in all files; and N
1652 count its display order and type. Subdirectives: any text, ignored.
1653 alias Rewrites account names, in following entries until end of cur‐ Y
1654 rent file or end aliases. Command line equivalent: --alias
1655 com‐ Ignores part of the journal file, until end of current file or Y
1656 ment end comment.
1657 com‐ Declares up to four things: 1. a commodity symbol, for checking N,Y,N,N
1666 mod‐ all amounts in all files 2. the decimal mark for parsing
1667 ity amounts of this commodity, in the following entries until end of
1668 current file (if there is no decimal-mark directive) 3. and the
1669 display style for amounts of this commodity 4. which is also
1670 the precision to use for balanced-transaction checking in this
1671 commodity. Takes precedence over D. Subdirectives: format
1672 (Ledger-compatible syntax). Command line equivalent: -c/--com‐
1673 modity-style
1674 deci‐ Declares the decimal mark, for parsing amounts of all commodi‐ Y
1675 mal- ties in following entries until next decimal-mark or end of cur‐
1676 mark rent file. Included files can override. Takes precedence over
1677 commodity and D.
1678 in‐ Includes entries and directives from another file, as if they N
1679 clude were written inline. Command line alternative: multiple
1680 -f/--file
1681 payee Declares a payee name, for checking all entries in all files. N
1682 P Declares the market price of a commodity on some date, for value N
1683 reports.
1684 ~ Declares a periodic transaction rule that generates future N
1685 (tilde) transactions with --forecast and budget goals with balance
1686 --budget.
1687 Other
1688 syntax:
1689 apply Prepends a common parent account to all account names, in fol‐ Y
1690 account lowing entries until end of current file or end apply account.
1691 D Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N
1692 there is no commodity directive for this commodity: its decimal
1693 mark, balancing precision, and display style, as above.
1694 Y Sets a default year to use for any yearless dates, in following Y
1695 entries until end of current file.
1696 = Declares an auto posting rule that generates extra postings on partly
1697 (equals) matched transactions with --auto, in current, parent, and child
1698 files (but not sibling files, see #1212).
1699 Other Other directives from Ledger's file format are accepted but ig‐
1700 Ledger nored.
1701 direc‐
1702 tives
1703 account directive
1705 account directives can be used to declare accounts (ie, the places that
1706 amounts are transferred from and to). Though not required, these dec‐
1707 larations can provide several benefits:
1708 • They can document your intended chart of accounts, providing a refer‐
1710 ence.
1711 • In strict mode, they restrict which accounts may be posted to by
1713 transactions, which helps detect typos.
1714 • They control account display order in reports, allowing non-alpha‐
1716 betic sorting (eg Revenues to appear above Expenses).
1717 • They help with account name completion (in hledger add, hledger-web,
1719 hledger-iadd, ledger-mode, etc.)
1720 • They can store additional account information as comments, or as tags
1722 which can be used to filter or pivot reports.
1723 • They can help hledger know your accounts' types (asset, liability,
1725 equity, revenue, expense), affecting reports like balancesheet and
1726 incomestatement.
1727 They are written as the word account followed by a hledger-style ac‐
1729 count name, eg:
1730 account assets:bank:checking
1732 Note, however, that accounts declared in account directives are not al‐
1734 lowed to have surrounding brackets and parentheses, unlike accounts
1735 used in postings. So the following journal will not parse:
1736 account (assets:bank:checking)
1738 Account comments
1740 Text following two or more spaces and ; at the end of an account direc‐
1741 tive line, and/or following ; on indented lines immediately below it,
1742 form comments for that account. They are ignored except they may con‐
1743 tain tags, which are not ignored.
1744 The two-space requirement for same-line account comments is because ;
1746 is allowed in account names.
1747 account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon
1749 ; next-line comment
1750 ; some tags - type:A, acctnum:12345
1751 Account subdirectives
1753 Ledger-style indented subdirectives are also accepted, but currently
1754 ignored:
1755 account assets:bank:checking
1757 format subdirective is ignored
1758 Account error checking
1760 By default, accounts need not be declared; they come into existence
1761 when a posting references them. This is convenient, but it means
1762 hledger can't warn you when you mis-spell an account name in the jour‐
1763 nal. Usually you'll find that error later, as an extra account in bal‐
1764 ance reports, or an incorrect balance when reconciling.
1765 In strict mode, enabled with the -s/--strict flag, hledger will report
1767 an error if any transaction uses an account name that has not been de‐
1768 clared by an account directive. Some notes:
1769 • The declaration is case-sensitive; transactions must use the correct
1771 account name capitalisation.
1772 • The account directive's scope is "whole file and below" (see direc‐
1774 tives). This means it affects all of the current file, and any files
1775 it includes, but not parent or sibling files. The position of ac‐
1776 count directives within the file does not matter, though it's usual
1777 to put them at the top.
1778 • Accounts can only be declared in journal files, but will affect in‐
1780 cluded files of all types.
1781 • It's currently not possible to declare "all possible subaccounts"
1783 with a wildcard; every account posted to must be declared.
1784 Account display order
1786 The order in which account directives are written influences the order
1787 in which accounts appear in reports, hledger-ui, hledger-web etc. By
1788 default accounts appear in alphabetical order, but if you add these ac‐
1789 count directives to the journal file:
1790 account assets
1792 account liabilities
1793 account equity
1794 account revenues
1795 account expenses
1796 those accounts will be displayed in declaration order:
1798 $ hledger accounts -1
1800 assets
1801 liabilities
1802 equity
1803 revenues
1804 expenses
1805 Any undeclared accounts are displayed last, in alphabetical order.
1807 Sorting is done at each level of the account tree, within each group of
1809 sibling accounts under the same parent. And currently, this directive:
1810 account other:zoo
1812 would influence the position of zoo among other's subaccounts, but not
1814 the position of other among the top-level accounts. This means:
1815 • you will sometimes declare parent accounts (eg account other above)
1817 that you don't intend to post to, just to customize their display or‐
1818 der
1819 • sibling accounts stay together (you couldn't display x:y in between
1821 a:b and a:c).
1822 Account types
1824 hledger knows that accounts come in several types: assets, liabilities,
1825 expenses and so on. This enables easy reports like balancesheet and
1826 incomestatement, and filtering by account type with the type: query.
1827 As a convenience, hledger will detect these account types automatically
1829 if you are using common english-language top-level account names (de‐
1830 scribed below). But generally we recommend you declare types explic‐
1831 itly, by adding a type: tag to your top-level account directives. Sub‐
1832 accounts will inherit the type of their parent. The tag's value should
1833 be one of the five main account types:
1834 • A or Asset (things you own)
1836 • L or Liability (things you owe)
1838 • E or Equity (investment/ownership; balanced counterpart of assets &
1840 liabilities)
1841 • R or Revenue (what you received money from, AKA income; technically
1843 part of Equity)
1844 • X or Expense (what you spend money on; technically part of Equity)
1846 or, it can be (these are used less often):
1848 • C or Cash (a subtype of Asset, indicating liquid assets for the cash‐
1850 flow report)
1851 • V or Conversion (a subtype of Equity, for conversions (see COST RE‐
1853 PORTING).)
1854 Here is a typical set of account type declarations:
1856 account assets ; type: A
1858 account liabilities ; type: L
1859 account equity ; type: E
1860 account revenues ; type: R
1861 account expenses ; type: X
1862 account assets:bank ; type: C
1864 account assets:cash ; type: C
1865 account equity:conversion ; type: V
1867 Here are some tips for working with account types.
1869 • The rules for inferring types from account names are as follows.
1871 These are just a convenience that sometimes help new users get going;
1872 if they don't work for you, just ignore them and declare your account
1873 types. See also Regular expressions.
1874 If account's name contains this (CI) regular expression: | its type is:
1876 --------------------------------------------------------------------|-------------
1877 ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash
1878 ^assets?(:|$) | Asset
1879 ^(debts?|liabilit(y|ies))(:|$) | Liability
1880 ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion
1881 ^equity(:|$) | Equity
1882 ^(income|revenue)s?(:|$) | Revenue
1883 ^expenses?(:|$) | Expense
1884 • If you declare any account types, it's a good idea to declare an ac‐
1886 count for all of the account types, because a mixture of declared and
1887 name-inferred types can disrupt certain reports.
1888 • Certain uses of account aliases can disrupt account types. See
1890 Rewriting accounts > Aliases and account types.
1891 • As mentioned above, subaccounts will inherit a type from their parent
1893 account. More precisely, an account's type is decided by the first
1894 of these that exists:
1895 1. A type: declaration for this account.
1897 2. A type: declaration in the parent accounts above it, preferring
1899 the nearest.
1900 3. An account type inferred from this account's name.
1902 4. An account type inferred from a parent account's name, preferring
1904 the nearest parent.
1905 5. Otherwise, it will have no type.
1907 • For troubleshooting, you can list accounts and their types with:
1909 $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]
1911 alias directive
1913 You can define account alias rules which rewrite your account names, or
1914 parts of them, before generating reports. This can be useful for:
1915 • expanding shorthand account names to their full form, allowing easier
1917 data entry and a less verbose journal
1918 • adapting old journals to your current chart of accounts
1920 • experimenting with new account organisations, like a new hierarchy
1922 • combining two accounts into one, eg to see their sum or difference on
1924 one line
1925 • customising reports
1927 Account aliases also rewrite account names in account directives. They
1929 do not affect account names being entered via hledger add or hledger-
1930 web.
1931 Account aliases are very powerful. They are generally easy to use cor‐
1933 rectly, but you can also generate invalid account names with them; more
1934 on this below.
1935 See also Rewrite account names.
1937 Basic aliases
1939 To set an account alias, use the alias directive in your journal file.
1940 This affects all subsequent journal entries in the current file or its
1941 included files (but note: not sibling or parent files). The spaces
1942 around the = are optional:
1943 alias OLD = NEW
1945 Or, you can use the --alias 'OLD=NEW' option on the command line. This
1947 affects all entries. It's useful for trying out aliases interactively.
1948 OLD and NEW are case sensitive full account names. hledger will re‐
1950 place any occurrence of the old account name with the new one. Subac‐
1951 counts are also affected. Eg:
1952 alias checking = assets:bank:wells fargo:checking
1954 ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
1955 Regex aliases
1957 There is also a more powerful variant that uses a regular expression,
1958 indicated by wrapping the pattern in forward slashes. (This is the
1959 only place where hledger requires forward slashes around a regular ex‐
1960 pression.)
1961 Eg:
1963 alias /REGEX/ = REPLACEMENT
1965 or:
1967 $ hledger --alias '/REGEX/=REPLACEMENT' ...
1969 Any part of an account name matched by REGEX will be replaced by RE‐
1971 PLACEMENT. REGEX is case-insensitive as usual.
1972 If you need to match a forward slash, escape it with a backslash, eg
1974 /\/=:.
1975 If REGEX contains parenthesised match groups, these can be referenced
1977 by the usual backslash and number in REPLACEMENT:
1978 alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
1980 ; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
1981 REPLACEMENT continues to the end of line (or on command line, to end of
1983 option argument), so it can contain trailing whitespace.
1984 Combining aliases
1986 You can define as many aliases as you like, using journal directives
1987 and/or command line options.
1988 Recursive aliases - where an account name is rewritten by one alias,
1990 then by another alias, and so on - are allowed. Each alias sees the
1991 effect of previously applied aliases.
1992 In such cases it can be important to understand which aliases will be
1994 applied and in which order. For (each account name in) each journal
1995 entry, we apply:
1996 1. alias directives preceding the journal entry, most recently parsed
1998 first (ie, reading upward from the journal entry, bottom to top)
1999 2. --alias options, in the order they appeared on the command line
2001 (left to right).
2002 In other words, for (an account name in) a given journal entry:
2004 • the nearest alias declaration before/above the entry is applied first
2006 • the next alias before/above that will be be applied next, and so on
2008 • aliases defined after/below the entry do not affect it.
2010 This gives nearby aliases precedence over distant ones, and helps pro‐
2012 vide semantic stability - aliases will keep working the same way inde‐
2013 pendent of which files are being read and in which order.
2014 In case of trouble, adding --debug=6 to the command line will show
2016 which aliases are being applied when.
2017 Aliases and multiple files
2019 As explained at Directives and multiple files, alias directives do not
2020 affect parent or sibling files. Eg in this command,
2021 hledger -f a.aliases -f b.journal
2023 account aliases defined in a.aliases will not affect b.journal. In‐
2025 cluding the aliases doesn't work either:
2026 include a.aliases
2028 2023-01-01 ; not affected by a.aliases
2030 foo 1
2031 bar
2032 This means that account aliases should usually be declared at the start
2034 of your top-most file, like this:
2035 alias foo=Foo
2037 alias bar=Bar
2038 2023-01-01 ; affected by aliases above
2040 foo 1
2041 bar
2042 include c.journal ; also affected
2044 end aliases directive
2046 You can clear (forget) all currently defined aliases (seen in the jour‐
2047 nal so far, or defined on the command line) with this directive:
2048 end aliases
2050 Aliases can generate bad account names
2052 Be aware that account aliases can produce malformed account names,
2053 which could cause confusing reports or invalid print output. For exam‐
2054 ple, you could erase all account names:
2055 2021-01-01
2057 a:aa 1
2058 b
2059 $ hledger print --alias '/.*/='
2061 2021-01-01
2062 1
2063 The above print output is not a valid journal. Or you could insert an
2065 illegal double space, causing print output that would give a different
2066 journal when reparsed:
2067 2021-01-01
2069 old 1
2070 other
2071 $ hledger print --alias old="new USD" | hledger -f- print
2073 2021-01-01
2074 new USD 1
2075 other
2076 Aliases and account types
2078 If an account with a type declaration (see Declaring accounts > Account
2079 types) is renamed by an alias, normally the account type remains in ef‐
2080 fect.
2081 However, renaming in a way that reshapes the account tree (eg renaming
2083 parent accounts but not their children, or vice versa) could prevent
2084 child accounts from inheriting the account type of their parents.
2085 Secondly, if an account's type is being inferred from its name, renam‐
2087 ing it by an alias could prevent or alter that.
2088 If you are using account aliases and the type: query is not matching
2090 accounts as you expect, try troubleshooting with the accounts command,
2091 eg something like:
2092 $ hledger accounts --alias assets=bassetts type:a
2094 commodity directive
2096 You can use commodity directives to declare your commodities. In fact
2097 the commodity directive performs several functions at once:
2098 1. It declares commodities which may be used in the journal. This can
2100 optionally be enforced, providing useful error checking. (Cf Com‐
2101 modity error checking)
2102 2. It declares which decimal mark character (period or comma), to ex‐
2104 pect when parsing input - useful to disambiguate international num‐
2105 ber formats in your data. Without this, hledger will parse both
2106 1,000 and 1.000 as 1. (Cf Amounts)
2107 3. It declares how to render the commodity's amounts when displaying
2109 output - the decimal mark, any digit group marks, the number of dec‐
2110 imal places, symbol placement and so on. (Cf Commodity display
2111 style)
2112 You will run into one of the problems solved by commodity directives
2114 sooner or later, so we recommend using them, for robust and predictable
2115 parsing and display.
2116 Generally you should put them at the top of your journal file (since
2118 for function 2, they affect only following amounts, cf #793).
2119 A commodity directive is just the word commodity followed by a sample
2121 amount, like this:
2122 ;commodity SAMPLEAMOUNT
2124 commodity $1000.00
2126 commodity 1,000.0000 AAAA ; optional same-line comment
2127 It may also be written on multiple lines, and use the format subdirec‐
2129 tive, as in Ledger. Note in this case the commodity symbol appears
2130 twice; it must be the same in both places:
2131 ;commodity SYMBOL
2133 ; format SAMPLEAMOUNT
2134 ; display indian rupees with currency name on the left,
2136 ; thousands, lakhs and crores comma-separated,
2137 ; period as decimal point, and two decimal places.
2138 commodity INR
2139 format INR 1,00,00,000.00
2140 Other indented subdirectives are currently ignored.
2142 Remember that if the commodity symbol contains spaces, numbers, or
2144 punctuation, it must be enclosed in double quotes (cf Commodity).
2145 The amount's quantity does not matter; only the format is significant.
2147 It must include a decimal mark - either a period or a comma - followed
2148 by 0 or more decimal digits.
2149 A few more examples:
2151 # number formats for $, EUR, INR and the no-symbol commodity:
2153 commodity $1,000.00
2154 commodity EUR 1.000,00
2155 commodity INR 9,99,99,999.0
2156 commodity 1 000 000.
2157 Note hledger normally uses banker's rounding, so 0.5 displayed with
2159 zero decimal digits is "0". (More at Commodity display style.)
2160 Even in the presence of commodity directives, the commodity display
2162 style can still be overridden by supplying a command line option.
2163 Commodity error checking
2165 In strict mode, enabled with the -s/--strict flag, hledger will report
2166 an error if a commodity symbol is used that has not been declared by a
2167 commodity directive. This works similarly to account error checking,
2168 see the notes there for more details.
2169 Note, this disallows amounts without a commodity symbol, because cur‐
2171 rently it's not possible (?) to declare the "no-symbol" commodity with
2172 a directive. This is one exception for convenience: zero amounts are
2173 always allowed to have no commodity symbol.
2174 decimal-mark directive
2176 You can use a decimal-mark directive - usually one per file, at the top
2177 of the file - to declare which character represents a decimal mark when
2178 parsing amounts in this file. It can look like
2179 decimal-mark .
2181 or
2183 decimal-mark ,
2185 This prevents any ambiguity when parsing numbers in the file, so we
2187 recommend it, especially if the file contains digit group marks (eg
2188 thousands separators).
2189 include directive
2191 You can pull in the content of additional files by writing an include
2192 directive, like this:
2193 include FILEPATH
2195 Only journal files can include, and only journal, timeclock or timedot
2197 files can be included (not CSV files, currently).
2198 If the file path does not begin with a slash, it is relative to the
2200 current file's folder.
2201 A tilde means home directory, eg: include ~/main.journal.
2203 The path may contain glob patterns to match multiple files, eg: include
2205 *.journal.
2206 There is limited support for recursive wildcards: **/ (the slash is re‐
2208 quired) matches 0 or more subdirectories. It's not super convenient
2209 since you have to avoid include cycles and including directories, but
2210 this can be done, eg: include */**/*.journal.
2211 The path may also be prefixed to force a specific file format, overrid‐
2213 ing the file extension (as described in hledger.1 -> Input files): in‐
2214 clude timedot:~/notes/2023*.md.
2215 P directive
2217 The P directive declares a market price, which is a conversion rate be‐
2218 tween two commodities on a certain date. This allows value reports to
2219 convert amounts of one commodity to their value in another, on or after
2220 that date. These prices are often obtained from a stock exchange,
2221 cryptocurrency exchange, the or foreign exchange market.
2222 The format is:
2224 P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT
2226 DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity
2228 being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity)
2229 of commodity 2 that one unit of commodity 1 is worth on this date. Ex‐
2230 amples:
2231 # one euro was worth $1.35 from 2009-01-01 onward:
2233 P 2009-01-01 € $1.35
2234 # and $1.40 from 2010-01-01 onward:
2236 P 2010-01-01 € $1.40
2237 The -V, -X and --value flags use these market prices to show amount
2239 values in another commodity. See Valuation.
2240 payee directive
2242 payee PAYEE NAME
2243 This directive can be used to declare a limited set of payees which may
2245 appear in transaction descriptions. The "payees" check will report an
2246 error if any transaction refers to a payee that has not been declared.
2247 Eg:
2248 payee Whole Foods
2250 Any indented subdirectives are currently ignored.
2252 tag directive
2254 tag TAGNAME
2255 This directive can be used to declare a limited set of tag names al‐
2257 lowed in tags. TAGNAME should be a valid tag name (no spaces). Eg:
2258 tag item-id
2260 Any indented subdirectives are currently ignored.
2262 The "tags" check will report an error if any undeclared tag name is
2264 used. It is quite easy to accidentally create a tag through normal use
2265 of colons in comments(#comments]; if you want to prevent this, you can
2266 declare and check your tags .
2267 Periodic transactions
2269 The ~ directive declares recurring transactions. Such directives allow
2270 hledger to generate temporary future transactions (visible in reports,
2271 not in the journal file) to help with forecasting or budgeting.
2272 Periodic transactions can be a little tricky, so before you use them,
2274 read this whole section, or at least these tips:
2275 1. Two spaces accidentally added or omitted will cause you trouble -
2277 read about this below.
2278 2. For troubleshooting, show the generated transactions with hledger
2280 print --forecast tag:generated or hledger register --forecast
2281 tag:generated.
2282 3. Forecasted transactions will begin only after the last non-fore‐
2284 casted transaction's date.
2285 4. Forecasted transactions will end 6 months from today, by default.
2287 See below for the exact start/end rules.
2288 5. period expressions can be tricky. Their documentation needs im‐
2290 provement, but is worth studying.
2291 6. Some period expressions with a repeating interval must begin on a
2293 natural boundary of that interval. Eg in weekly from DATE, DATE
2294 must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
2295 error.
2296 7. Other period expressions with an interval are automatically expanded
2298 to cover a whole number of that interval. (This is done to improve
2299 reports, but it also affects periodic transactions. Yes, it's a bit
2300 inconsistent with the above.) Eg: ~ every 10th day of month from
2301 2023/01, which is equivalent to ~ every 10th day of month from
2302 2023/01/01, will be adjusted to start on 2019/12/10.
2303 Periodic rule syntax
2305 A periodic transaction rule looks like a normal journal entry, with the
2306 date replaced by a tilde (~) followed by a period expression (mnemonic:
2307 ~ looks like a recurring sine wave.):
2308 # every first of month
2310 ~ monthly
2311 expenses:rent $2000
2312 assets:bank:checking
2313 # every 15th of month in 2023's first quarter:
2315 ~ monthly from 2023-04-15 to 2023-06-16
2316 expenses:utilities $400
2317 assets:bank:checking
2318 The period expression is the same syntax used for specifying multi-pe‐
2320 riod reports, just interpreted differently; there, it specifies report
2321 periods; here it specifies recurrence dates (the periods' start dates).
2322 Periodic rules and relative dates
2324 Partial or relative dates (like 12/31, 25, tomorrow, last week, next
2325 quarter) are usually not recommended in periodic rules, since the re‐
2326 sults will change as time passes. If used, they will be interpreted
2327 relative to, in order of preference:
2328 1. the first day of the default year specified by a recent Y directive
2330 2. or the date specified with --today
2332 3. or the date on which you are running the report.
2334 They will not be affected at all by report period or forecast period
2336 dates.
2337 Two spaces between period expression and description!
2339 If the period expression is followed by a transaction description,
2340 these must be separated by two or more spaces. This helps hledger know
2341 where the period expression ends, so that descriptions can not acciden‐
2342 tally alter their meaning, as in this example:
2343 ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023"
2345 ; ||
2346 ; vv
2347 ~ every 2 months in 2023, we will review
2348 assets:bank:checking $1500
2349 income:acme inc
2350 So,
2352 • Do write two spaces between your period expression and your transac‐
2354 tion description, if any.
2355 • Don't accidentally write two spaces in the middle of your period ex‐
2357 pression.
2358 Auto postings
2360 The = directive declares a rule for generating temporary extra postings
2361 on transactions. Wherever the rule matches an existing posting, it can
2362 add one or more companion postings below that one, optionally influ‐
2363 enced by the matched posting's amount. This can be useful for generat‐
2364 ing tax postings with a standard percentage, for example.
2365 Note that depending on generated data is not ideal for financial
2367 records (it's less portable, less future-proof, less auditable by oth‐
2368 ers, and less robust, since other features like balance assertions will
2369 depend on using or not using --auto).
2370 An auto posting rule looks a bit like a transaction:
2372 = QUERY
2374 ACCOUNT AMOUNT
2375 ...
2376 ACCOUNT [AMOUNT]
2377 except the first line is an equals sign (mnemonic: = suggests match‐
2379 ing), followed by a query (which matches existing postings), and each
2380 "posting" line describes a posting to be generated, and the posting
2381 amounts can be:
2382 • a normal amount with a commodity symbol, eg $2. This will be used
2384 as-is.
2385 • a number, eg 2. The commodity symbol (if any) from the matched post‐
2387 ing will be added to this.
2388 • a numeric multiplier, eg *2 (a star followed by a number N). The
2390 matched posting's amount (and total price, if any) will be multiplied
2391 by N.
2392 • a multiplier with a commodity symbol, eg *$2 (a star, number N, and
2394 symbol S). The matched posting's amount will be multiplied by N, and
2395 its commodity symbol will be replaced with S.
2396 Any query term containing spaces must be enclosed in single or double
2398 quotes, as on the command line. Eg, note the quotes around the second
2399 query term below:
2400 = expenses:groceries 'expenses:dining out'
2402 (budget:funds:dining out) *-1
2403 Some examples:
2405 ; every time I buy food, schedule a dollar donation
2407 = expenses:food
2408 (liabilities:charity) $-1
2409 ; when I buy a gift, also deduct that amount from a budget envelope subaccount
2411 = expenses:gifts
2412 assets:checking:gifts *-1
2413 assets:checking *1
2414 2017/12/1
2416 expenses:food $10
2417 assets:checking
2418 2017/12/14
2420 expenses:gifts $20
2421 assets:checking
2422 $ hledger print --auto
2424 2017-12-01
2425 expenses:food $10
2426 assets:checking
2427 (liabilities:charity) $-1
2428 2017-12-14
2430 expenses:gifts $20
2431 assets:checking
2432 assets:checking:gifts -$20
2433 assets:checking $20
2434 Auto postings and multiple files
2436 An auto posting rule can affect any transaction in the current file, or
2437 in any parent file or child file. Note, currently it will not affect
2438 sibling files (when multiple -f/--file are used - see #1212).
2439 Auto postings and dates
2441 A posting date (or secondary date) in the matched posting, or (taking
2442 precedence) a posting date in the auto posting rule itself, will also
2443 be used in the generated posting.
2444 Auto postings and transaction balancing / inferred amounts / balance asser‐
2446 tions
2447 Currently, auto postings are added:
2448 • after missing amounts are inferred, and transactions are checked for
2450 balancedness,
2451 • but before balance assertions are checked.
2453 Note this means that journal entries must be balanced both before and
2455 after auto postings are added. This changed in hledger 1.12+; see #893
2456 for background.
2457 This also means that you cannot have more than one auto-posting with a
2459 missing amount applied to a given transaction, as it will be unable to
2460 infer amounts.
2461 Auto posting tags
2463 Automated postings will have some extra tags:
2464 • generated-posting:= QUERY - shows this was generated by an auto post‐
2466 ing rule, and the query
2467 • _generated-posting:= QUERY - a hidden tag, which does not appear in
2469 hledger's output. This can be used to match postings generated "just
2470 now", rather than generated in the past and saved to the journal.
2471 Also, any transaction that has been changed by auto posting rules will
2473 have these tags added:
2474 • modified: - this transaction was modified
2476 • _modified: - a hidden tag not appearing in the comment; this transac‐
2478 tion was modified "just now".
2479 Auto postings on forecast transactions only
2481 Tip: you can can make auto postings that will apply to forecast trans‐
2482 actions but not recorded transactions, by adding tag:_generated-trans‐
2483 action to their QUERY. This can be useful when generating new journal
2484 entries to be saved in the journal.
2485 Other syntax
2487 hledger journal format supports quite a few other features, mainly to
2488 make interoperating with or converting from Ledger easier. Note some
2489 of the features below are powerful and can be useful in special cases,
2490 but in general, features in this section are considered less important
2491 or even not recommended for most users. Downsides are mentioned to
2492 help you decide if you want to use them.
2493 Balance assignments
2495 Ledger-style balance assignments are also supported. These are like
2496 balance assertions, but with no posting amount on the left side of the
2497 equals sign; instead it is calculated automatically so as to satisfy
2498 the assertion. This can be a convenience during data entry, eg when
2499 setting opening balances:
2500 ; starting a new journal, set asset account balances
2502 2016/1/1 opening balances
2503 assets:checking = $409.32
2504 assets:savings = $735.24
2505 assets:cash = $42
2506 equity:opening balances
2507 or when adjusting a balance to reality:
2509 ; no cash left; update balance, record any untracked spending as a generic expense
2511 2016/1/15
2512 assets:cash = $0
2513 expenses:misc
2514 The calculated amount depends on the account's balance in the commodity
2516 at that point (which depends on the previously-dated postings of the
2517 commodity to that account since the last balance assertion or assign‐
2518 ment).
2519 Downsides: using balance assignments makes your journal less explicit;
2521 to know the exact amount posted, you have to run hledger or do the cal‐
2522 culations yourself, instead of just reading it. Also balance assign‐
2523 ments' forcing of balances can hide errors. These things make your fi‐
2524 nancial data less portable, less future-proof, and less trustworthy in
2525 an audit.
2526 Balance assignments and prices
2528 A cost in a balance assignment will cause the calculated amount to have
2529 that price attached:
2530 2019/1/1
2532 (a) = $1 @ €2
2533 $ hledger print --explicit
2535 2019-01-01
2536 (a) $1 @ €2 = $1 @ €2
2537 Bracketed posting dates
2539 For setting posting dates and secondary posting dates, Ledger's brack‐
2540 eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in
2541 posting comments. hledger will attempt to parse any square-bracketed
2542 sequence of the 0123456789/-.= characters in this way. With this syn‐
2543 tax, DATE infers its year from the transaction and DATE2 infers its
2544 year from DATE.
2545 Downsides: another syntax to learn, redundant with hledger's
2547 date:/date2: tags, and confusingly similar to Ledger's lot date syntax.
2548 D directive
2550 D AMOUNT
2551 This directive sets a default commodity, to be used for any subsequent
2553 commodityless amounts (ie, plain numbers) seen while parsing the jour‐
2554 nal. This effect lasts until the next D directive, or the end of the
2555 journal.
2556 For compatibility/historical reasons, D also acts like a commodity di‐
2558 rective (setting the commodity's decimal mark for parsing and display
2559 style for output). So its argument is not just a commodity symbol, but
2560 a full amount demonstrating the style. The amount must include a deci‐
2561 mal mark (either period or comma). Eg:
2562 ; commodity-less amounts should be treated as dollars
2564 ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
2565 D $1,000.00
2566 1/1
2568 a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
2569 b
2570 Interactions with other directives:
2572 For setting a commodity's display style, a commodity directive has
2574 highest priority, then a D directive.
2575 For detecting a commodity's decimal mark during parsing, decimal-mark
2577 has highest priority, then commodity, then D.
2578 For checking commodity symbols with the check command, a commodity di‐
2580 rective is required (hledger check commodities ignores D directives).
2581 Downsides: omitting commodity symbols makes your financial data less
2583 explicit, less portable, and less trustworthy in an audit. It is usu‐
2584 ally an unsustainable shortcut; sooner or later you will want to track
2585 multiple commodities. D is overloaded with functions redundant with
2586 commodity and decimal-mark. And it works differently from Ledger's D.
2587 apply account directive
2589 This directive sets a default parent account, which will be prepended
2590 to all accounts in following entries, until an end apply account direc‐
2591 tive or end of current file. Eg:
2592 apply account home
2594 2010/1/1
2596 food $10
2597 cash
2598 end apply account
2600 is equivalent to:
2602 2010/01/01
2604 home:food $10
2605 home:cash $-10
2606 account directives are also affected, and so is any included content.
2608 Account names entered via hledger add or hledger-web are not affected.
2610 Account aliases, if any, are applied after the parent account is
2612 prepended.
2613 Downsides: this can make your financial data less explicit, less porta‐
2615 ble, and less trustworthy in an audit.
2616 Y directive
2618 Y YEAR
2619 or (deprecated backward-compatible forms):
2621 year YEAR apply year YEAR
2623 The space is optional. This sets a default year to be used for subse‐
2625 quent dates which don't specify a year. Eg:
2626 Y2009 ; set default year to 2009
2628 12/15 ; equivalent to 2009/12/15
2630 expenses 1
2631 assets
2632 year 2010 ; change default year to 2010
2634 2009/1/30 ; specifies the year, not affected
2636 expenses 1
2637 assets
2638 1/31 ; equivalent to 2010/1/31
2640 expenses 1
2641 assets
2642 Downsides: omitting the year (from primary transaction dates, at least)
2644 makes your financial data less explicit, less portable, and less trust‐
2645 worthy in an audit. Such dates can get separated from their corre‐
2646 sponding Y directive, eg when evaluating a region of the journal in
2647 your editor. A missing Y directive makes reports dependent on today's
2648 date.
2649 Secondary dates
2651 A secondary date is written after the primary date, following an equals
2652 sign. If the year is omitted, the primary date's year is assumed.
2653 When running reports, the primary (left) date is used by default, but
2654 with the --date2 flag (or --aux-date or --effective), the secondary
2655 (right) date will be used instead.
2656 The meaning of secondary dates is up to you, but it's best to follow a
2658 consistent rule. Eg "primary = the bank's clearing date, secondary =
2659 date the transaction was initiated, if different".
2660 Downsides: makes your financial data more complicated, less portable,
2662 and less trustworthy in an audit. Keeping the meaning of the two dates
2663 consistent requires discipline, and you have to remember which report‐
2664 ing mode is appropriate for a given report. Posting dates are simpler
2665 and better.
2666 Star comments
2668 Lines beginning with * (star/asterisk) are also comment lines. This
2669 feature allows Emacs users to insert org headings in their journal, al‐
2670 lowing them to fold/unfold/navigate it like an outline when viewed with
2671 org mode.
2672 Downsides: another, unconventional comment syntax to learn. Decreases
2674 your journal's portability. And switching to Emacs org mode just for
2675 folding/unfolding meant losing the benefits of ledger mode; nowadays
2676 you can add outshine mode to ledger mode to get folding without losing
2677 ledger mode's features.
2678 Valuation expressions
2680 Ledger allows a valuation function or value to be written in double
2681 parentheses after an amount. hledger ignores these.
2682 Virtual postings
2684 A posting with parentheses around the account name ((some:account)) is
2685 called a unbalanced virtual posting. Such postings do not participate
2686 in transaction balancing. (And if you write them without an amount, a
2687 zero amount is always inferred.) These can occasionally be convenient
2688 for special circumstances, but they violate double entry bookkeeping
2689 and make your data less portable across applications, so many people
2690 avoid using them at all.
2691 A posting with brackets around the account name ([some:account]) is
2693 called a balanced virtual posting. The balanced virtual postings in a
2694 transaction must add up to zero, just like ordinary postings, but sepa‐
2695 rately from them. These are not part of double entry bookkeeping ei‐
2696 ther, but they are at least balanced. An example:
2697 2022-01-01 buy food with cash, update budget envelope subaccounts, & something else
2699 assets:cash $-10 ; <- these balance each other
2700 expenses:food $7 ; <-
2701 expenses:food $3 ; <-
2702 [assets:checking:budget:food] $-10 ; <- and these balance each other
2703 [assets:checking:available] $10 ; <-
2704 (something:else) $5 ; <- this is not required to balance
2705 Ordinary postings, whose account names are neither parenthesised nor
2707 bracketed, are called real postings. You can exclude virtual postings
2708 from reports with the -R/--real flag or a real:1 query.
2709 Other Ledger directives
2711 These other Ledger directives are currently accepted but ignored. This
2712 allows hledger to read more Ledger files, but be aware that hledger's
2713 reports may differ from Ledger's if you use these.
2714 apply fixed COMM AMT
2716 apply tag TAG
2717 assert EXPR
2718 bucket / A ACCT
2719 capture ACCT REGEX
2720 check EXPR
2721 define VAR=EXPR
2722 end apply fixed
2723 end apply tag
2724 end apply year
2725 end tag
2726 eval / expr EXPR
2727 python
2728 PYTHONCODE
2729 tag NAME
2730 value EXPR
2731 --command-line-flags
2732 See also https://hledger.org/ledger.html for a detailed hledger/Ledger
2734 syntax comparison.
2735
2737 hledger can read CSV files (Character Separated Value - usually comma,
2738 semicolon, or tab) containing dated records, automatically converting
2739 each record into a transaction.
2740 (To learn about writing CSV, see CSV output.)
2742 For best error messages when reading CSV/TSV/SSV files, make sure they
2744 have a corresponding .csv, .tsv or .ssv file extension or use a hledger
2745 file prefix (see File Extension below).
2746 Each CSV file must be described by a corresponding rules file.
2748 This contains rules describing the CSV data (header line, fields lay‐
2749 out, date format etc.), how to construct hledger transactions from it,
2750 and how to categorise transactions based on description or other at‐
2751 tributes.
2752 By default hledger looks for a rules file named like the CSV file with
2754 an extra .rules extension, in the same directory. Eg when asked to
2755 read foo/FILE.csv, hledger looks for foo/FILE.csv.rules. You can spec‐
2756 ify a different rules file with the --rules-file option. If no rules
2757 file is found, hledger will create a sample rules file, which you'll
2758 need to adjust.
2759 At minimum, the rules file must identify the date and amount fields,
2761 and often it also specifies the date format and how many header lines
2762 there are. Here's a simple CSV file and a rules file for it:
2763 Date, Description, Id, Amount
2765 12/11/2019, Foo, 123, 10.23
2766 # basic.csv.rules
2768 skip 1
2769 fields date, description, , amount
2770 date-format %d/%m/%Y
2771 $ hledger print -f basic.csv
2773 2019-11-12 Foo
2774 expenses:unknown 10.23
2775 income:unknown -10.23
2776 There's an introductory Importing CSV data tutorial on hledger.org, and
2778 more CSV rules examples below, and a larger collection at
2779 https://github.com/simonmichael/hledger/tree/master/examples/csv.
2780 CSV rules cheatsheet
2782 The following kinds of rule can appear in the rules file, in any order.
2783 (Blank lines and lines beginning with # or ; or * are ignored.)
2784 source optionally declare which file to read data
2786 from
2787 separator declare the field separator, instead of rely‐
2788 ing on file extension
2789 skip skip one or more header lines at start of file
2790 date-format declare how to parse CSV dates/date-times
2791 timezone declare the time zone of ambiguous CSV date-
2792 times
2793 newest-first improve txn order when: there are multiple
2794 records, newest first, all with the same date
2795 intra-day-reversed improve txn order when: same-day txns are in
2796 opposite order to the overall file
2797 decimal-mark declare the decimal mark used in CSV amounts,
2798 when ambiguous
2799 fields list name CSV fields for easy reference, and op‐
2800 tionally assign their values to hledger fields
2801 Field assignment assign a CSV value or interpolated text value
2802 to a hledger field
2803 if block conditionally assign values to hledger fields,
2804 or skip a record or end (skip rest of file)
2805 if table conditionally assign values to hledger fields,
2806 using compact syntax
2807 balance-type select which type of balance assertions/as‐
2808 signments to generate
2809 include inline another CSV rules file
2810 Working with CSV tips can be found below, including How CSV rules are
2812 evaluated.
2813 source
2815 If you tell hledger to read a csv file with -f foo.csv, it will look
2816 for rules in foo.csv.rules. Or, you can tell it to read the rules
2817 file, with -f foo.csv.rules, and it will look for data in foo.csv
2818 (since 1.30).
2819 These are mostly equivalent, but the second method provides some extra
2821 features. For one, the data file can be missing, without causing an
2822 error; it is just considered empty. And, you can specify a different
2823 data file by adding a "source" rule:
2824 source ./Checking1.csv
2826 If you specify just a file name with no path, hledger will look for it
2828 in your system's downloads directory (~/Downloads, currently):
2829 source Checking1.csv
2831 And if you specify a glob pattern, hledger will read the most recent of
2833 the matched files (useful with repeated downloads):
2834 source Checking1*.csv
2836 See also "Working with CSV > Reading files specified by rule".
2838 separator
2840 You can use the separator rule to read other kinds of character-sepa‐
2841 rated data. The argument is any single separator character, or the
2842 words tab or space (case insensitive). Eg, for comma-separated values
2843 (CSV):
2844 separator ,
2846 or for semicolon-separated values (SSV):
2848 separator ;
2850 or for tab-separated values (TSV):
2852 separator TAB
2854 If the input file has a .csv, .ssv or .tsv file extension (or a csv:,
2856 ssv:, tsv: prefix), the appropriate separator will be inferred automat‐
2857 ically, and you won't need this rule.
2858 skip
2860 skip N
2861 The word skip followed by a number (or no number, meaning 1) tells
2863 hledger to ignore this many non-empty lines at the start of the input
2864 data. You'll need this whenever your CSV data contains header lines.
2865 Note, empty and blank lines are skipped automatically, so you don't
2866 need to count those.
2867 skip has a second meaning: it can be used inside if blocks (described
2869 below), to skip one or more records whenever the condition is true.
2870 Records skipped in this way are ignored, except they are still required
2871 to be valid CSV.
2872 date-format
2874 date-format DATEFMT
2875 This is a helper for the date (and date2) fields. If your CSV dates
2877 are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll
2878 need to add a date-format rule describing them with a strptime-style
2879 date parsing pattern - see https://hackage.haskell.org/pack‐
2880 age/time/docs/Data-Time-Format.html#v:formatTime. The pattern must
2881 parse the CSV date value completely. Some examples:
2882 # MM/DD/YY
2884 date-format %m/%d/%y
2885 # D/M/YYYY
2887 # The - makes leading zeros optional.
2888 date-format %-d/%-m/%Y
2889 # YYYY-Mmm-DD
2891 date-format %Y-%h-%d
2892 # M/D/YYYY HH:MM AM some other junk
2894 # Note the time and junk must be fully parsed, though only the date is used.
2895 date-format %-m/%-d/%Y %l:%M %p some other junk
2896 timezone
2898 timezone TIMEZONE
2899 When CSV contains date-times that are implicitly in some time zone
2901 other than yours, but containing no explicit time zone information, you
2902 can use this rule to declare the CSV's native time zone, which helps
2903 prevent off-by-one dates.
2904 When the CSV date-times do contain time zone information, you don't
2906 need this rule; instead, use %Z in date-format (or %z, %EZ, %Ez; see
2907 the formatTime link above).
2908 In either of these cases, hledger will do a time-zone-aware conversion,
2910 localising the CSV date-times to your current system time zone. If you
2911 prefer to localise to some other time zone, eg for reproducibility, you
2912 can (on unix at least) set the output timezone with the TZ environment
2913 variable, eg:
2914 $ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv
2916 timezone currently does not understand timezone names, except "UTC",
2918 "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT". For
2919 others, use numeric format: +HHMM or -HHMM.
2920 newest-first
2922 hledger tries to ensure that the generated transactions will be ordered
2923 chronologically, including intra-day transactions. Usually it can
2924 auto-detect how the CSV records are ordered. But if it encounters CSV
2925 where all records are on the same date, it assumes that the records are
2926 oldest first. If in fact the CSV's records are normally newest first,
2927 like:
2928 2022-10-01, txn 3...
2930 2022-10-01, txn 2...
2931 2022-10-01, txn 1...
2932 you can add the newest-first rule to help hledger generate the transac‐
2934 tions in correct order.
2935 # same-day CSV records are newest first
2937 newest-first
2938 intra-day-reversed
2940 CSV records for each day are sometimes ordered in reverse compared to
2941 the overall date order. Eg, here dates are newest first, but the
2942 transactions on each date are oldest first:
2943 2022-10-02, txn 3...
2945 2022-10-02, txn 4...
2946 2022-10-01, txn 1...
2947 2022-10-01, txn 2...
2948 In this situation, add the intra-day-reversed rule, and hledger will
2950 compensate, improving the order of transactions.
2951 # transactions within each day are reversed with respect to the overall date order
2953 intra-day-reversed
2954 decimal-mark
2956 decimal-mark .
2957 or:
2959 decimal-mark ,
2961 hledger automatically accepts either period or comma as a decimal mark
2963 when parsing numbers (cf Amounts). However if any numbers in the CSV
2964 contain digit group marks, such as thousand-separating commas, you
2965 should declare the decimal mark explicitly with this rule, to avoid
2966 misparsed numbers.
2967 fields list
2969 fields FIELDNAME1, FIELDNAME2, ...
2970 A fields list (the word fields followed by comma-separated field names)
2972 is optional, but convenient. It does two things:
2973 1. It names the CSV field in each column. This can be convenient if
2975 you are referencing them in other rules, so you can say %SomeField
2976 instead of remembering %13.
2977 2. Whenever you use one of the special hledger field names (described
2979 below), it assigns the CSV value in this position to that hledger
2980 field. This is the quickest way to populate hledger's fields and
2981 build a transaction.
2982 Here's an example that says "use the 1st, 2nd and 4th fields as the
2984 transaction's date, description and amount; name the last two fields
2985 for later reference; and ignore the others":
2986 fields date, description, , amount, , , somefield, anotherfield
2988 In a fields list, the separator is always comma; it is unrelated to the
2990 CSV file's separator. Also:
2991 • There must be least two items in the list (at least one comma).
2993 • Field names may not contain spaces. Spaces before/after field names
2995 are optional.
2996 • Field names may contain _ (underscore) or - (hyphen).
2998 • Fields you don't care about can be given a dummy name or an empty
3000 name.
3001 If the CSV contains column headings, it's convenient to use these for
3003 your field names, suitably modified (eg lower-cased with spaces re‐
3004 placed by underscores).
3005 Sometimes you may want to alter a CSV field name to avoid assigning to
3007 a hledger field with the same name. Eg you could call the CSV's "bal‐
3008 ance" field balance_ to avoid directly setting hledger's balance field
3009 (and generating a balance assertion).
3010 Field assignment
3012 HLEDGERFIELD FIELDVALUE
3013 Field assignments are the more flexible way to assign CSV values to
3015 hledger fields. They can be used instead of or in addition to a fields
3016 list (see above).
3017 To assign a value to a hledger field, write the field name (any of the
3019 standard hledger field/pseudo-field names, defined below), a space,
3020 followed by a text value on the same line. This text value may inter‐
3021 polate CSV fields, referenced by their 1-based position in the CSV
3022 record (%N), or by the name they were given in the fields list (%CSV‐
3023 FIELD).
3024 Some examples:
3026 # set the amount to the 4th CSV field, with " USD" appended
3028 amount %4 USD
3029 # combine three fields to make a comment, containing note: and date: tags
3031 comment note: %somefield - %anotherfield, date: %1
3032 Tips:
3034 • Interpolation strips outer whitespace (so a CSV value like " 1 " be‐
3036 comes 1 when interpolated) (#1051).
3037 • Interpolations always refer to a CSV field - you can't interpolate a
3039 hledger field. (See Referencing other fields below).
3040 Field names
3042 Note the two kinds of field names mentioned here, and used only in
3043 hledger CSV rules files:
3044 1. CSV field names (CSVFIELD in these docs): you can optionally name
3046 the CSV columns for easy reference (since hledger doesn't yet auto‐
3047 matically recognise column headings in a CSV file), by writing arbi‐
3048 trary names in a fields list, eg:
3049 fields When, What, Some_Id, Net, Total, Foo, Bar
3051 2. Special hledger field names (HLEDGERFIELD in these docs): you must
3053 set at least some of these to generate the hledger transaction from
3054 a CSV record, by writing them as the left hand side of a field as‐
3055 signment, eg:
3056 date %When
3058 code %Some_Id
3059 description %What
3060 comment %Foo %Bar
3061 amount1 $ %Total
3062 or directly in a fields list:
3064 fields date, description, code, , amount1, Foo, Bar
3066 currency $
3067 comment %Foo %Bar
3068 Here are all the special hledger field names available, and what hap‐
3070 pens when you assign values to them:
3071 date field
3073 Assigning to date sets the transaction date.
3074 date2 field
3076 date2 sets the transaction's secondary date, if any.
3077 status field
3079 status sets the transaction's status, if any.
3080 code field
3082 code sets the transaction's code, if any.
3083 description field
3085 description sets the transaction's description, if any.
3086 comment field
3088 comment sets the transaction's comment, if any.
3089 commentN, where N is a number, sets the Nth posting's comment.
3091 You can assign multi-line comments by writing literal \n in the code.
3093 A comment starting with \n will begin on a new line.
3094 Comments can contain tags, as usual.
3096 account field
3098 Assigning to accountN, where N is 1 to 99, sets the account name of the
3099 Nth posting, and causes that posting to be generated.
3100 Most often there are two postings, so you'll want to set account1 and
3102 account2. Typically account1 is associated with the CSV file, and is
3103 set once with a top-level assignment, while account2 is set based on
3104 each transaction's description, in conditional rules.
3105 If a posting's account name is left unset but its amount is set (see
3107 below), a default account name will be chosen (like "expenses:unknown"
3108 or "income:unknown").
3109 amount field
3111 Amount setting can get a bit complex. Assigning to amount is suffi‐
3112 cient for simple transactions, but there are four field name variants
3113 you can use for different situations:
3114 • amountN sets a specific posting's amount from one CSV field or arbi‐
3116 trary value.
3117 Assigning to amountN sets the amount of the Nth posting - and also
3118 causes that posting to be generated. N is most often 1 or 2 but can go
3119 up to 99, potentially generating a 99-posting transaction. (Posting
3120 numbers don't have to be consecutive; higher posting numbers can some‐
3121 times be useful with conditional rules, to ensure a certain ordering of
3122 postings.)
3123 • amountN-in/-out sets a specific posting's amount from two CSV fields.
3125 When the amount is provided as two CSV fields - "Debit"/"Credit", "De‐
3126 posit"/"Withdrawal", "Money In"/"Money Out" or similar - assign those
3127 fields to amountN-in and amountN-out respectively (or possibly the
3128 other way round, depending on signs). This will set the Nth posting's
3129 amount to whichever of the two CSV field values is non-zero. Some
3130 notes:
3131 • Don't mix amountN and amountN-in/-out. When you have one CSV
3133 amount field, use amountN. When you have two CSV amount fields,
3134 use amountN-in/amountN-out.
3135 • amountN-in and amountN-out are always used together, as a pair.
3137 Assign to both of them.
3138 • They do not generate two separate postings; rather, they generate
3140 the Nth posting's single amount, from the value found in one or
3141 other of the two CSV fields.
3142 • In each record, at least one of the two CSV fields must contain a
3144 zero amount or be empty.
3145 • hledger assumes the two CSV fields contain unsigned numbers, and it
3147 will automatically negate the -out amount.
3148 • This variant can be convenient, but it doesn't handle every two-
3150 amount-field situation; if you need more flexibility, use an if
3151 rule (see "Setting amounts" below).
3152 The other two variants are older and considered legacy syntax, but can
3154 still be convenient sometimes:
3155 • amount sets posting 1 and 2's amounts from one CSV field or value.
3157 Assigning to amount, with no posting number,
3158 • sets posting 1's amount (like amount1)
3160 • sets posting 2's amount to the same amount but with opposite sign;
3162 and also converts it to cost if it has a cost price
3163 • can be overridden by amount1 and/or amount2 assignments. (This
3165 helps with incremental migration of old rules files to the newer
3166 syntax.)
3167 • amount-in/-out sets posting 1 and 2's amounts from two CSV fields.
3169 Assigning amount-in and amount-out, with no posting numbers, to two CSV
3170 fields reads whichever of the two values is non-zero as the amount, and
3171 then sets the first two posting amounts as above.
3172 We recommend using only one of these variants within a rules file,
3174 rather than mixing them. And remember that a fields list can also do
3175 assignments, so eg naming a CSV field "amount" counts as an assignment
3176 to amount; if you don't want that, call it something else, like
3177 "amount_".
3178 In addition to this section, please see also the tips beginning at
3180 "Working with CSV > Setting amounts" below.
3181 currency field
3183 currency sets a currency symbol, to be prepended to all postings'
3184 amounts. You can use this if the CSV amounts do not have a currency
3185 symbol, eg if it is in a separate column.
3186 currencyN prepends a currency symbol to just the Nth posting's amount.
3188 balance field
3190 balanceN sets a balance assertion amount (or if the posting amount is
3191 left empty, a balance assignment) on posting N.
3192 balance is a compatibility spelling for hledger <1.17; it is equivalent
3194 to balance1.
3195 You can adjust the type of assertion/assignment with the balance-type
3197 rule (see below).
3198 See Tips below for more about setting amounts and currency.
3200 if block
3202 Rules can be applied conditionally, depending on patterns in the CSV
3203 data. This allows flexibility; in particular, it is how you can cate‐
3204 gorise transactions, selecting an appropriate account name based on
3205 their description (for example). There are two ways to write condi‐
3206 tional rules: "if blocks", described here, and "if tables", described
3207 below.
3208 An if block is the word if and one or more "matcher" expressions (can
3210 be a word or phrase), one per line, starting either on the same or next
3211 line; followed by one or more indented rules. Eg,
3212 if MATCHER
3214 RULE
3215 or
3217 if
3219 MATCHER
3220 MATCHER
3221 MATCHER
3222 RULE
3223 RULE
3224 If any of the matchers succeeds, all of the indented rules will be ap‐
3226 plied. They are usually field assignments, but the following special
3227 rules may also be used within an if block:
3228 • skip - skips the matched CSV record (generating no transaction from
3230 it)
3231 • end - skips the rest of the current CSV file.
3233 Some examples:
3235 # if the record contains "groceries", set account2 to "expenses:groceries"
3237 if groceries
3238 account2 expenses:groceries
3239 # if the record contains any of these phrases, set account2 and a transaction comment as shown
3241 if
3242 monthly service fee
3243 atm transaction fee
3244 banking thru software
3245 account2 expenses:business:banking
3246 comment XXX deductible ? check it
3247 # if an empty record is seen (assuming five fields), ignore the rest of the CSV file
3249 if ,,,,
3250 end
3251 Matchers
3253 There are two kinds:
3254 1. A record matcher is a word or single-line text fragment or regular
3256 expression (REGEX), which hledger will try to match case-insensi‐
3257 tively anywhere within the CSV record.
3258 Eg: whole foods
3259 2. A field matcher is preceded with a percent sign and CSV field name
3261 (%CSVFIELD REGEX). hledger will try to match these just within the
3262 named CSV field.
3263 Eg: %date 2023
3264 The regular expression is (as usual in hledger) a POSIX extended regu‐
3266 lar expression, that also supports GNU word boundaries (\b, \B, \<,
3267 \>), and nothing else. If you have trouble, see "Regular expressions"
3268 in the hledger manual (https://hledger.org/hledger.html#regular-expres‐
3269 sions).
3270 With record matchers, it's important to know that the record matched is
3272 not the original CSV record, but a modified one: separators will be
3273 converted to commas, and enclosing double quotes (but not enclosing
3274 whitespace) are removed. So for example, when reading an SSV file, if
3275 the original record was:
3276 2023-01-01; "Acme, Inc."; 1,000
3278 the regex would see, and try to match, this modified record text:
3280 2023-01-01,Acme, Inc., 1,000
3282 When an if block has multiple matchers, they are combined as follows:
3284 • By default they are OR'd (any one of them can match)
3286 • When a matcher is preceded by ampersand (&) it will be AND'ed with
3288 the previous matcher (both of them must match).
3289 There's not yet an easy syntax to negate a matcher.
3291 if table
3293 "if tables" are an alternative to if blocks; they can express many
3294 matchers and field assignments in a more compact tabular format, like
3295 this:
3296 if,HLEDGERFIELD1,HLEDGERFIELD2,...
3298 MATCHERA,VALUE1,VALUE2,...
3299 MATCHERB,VALUE1,VALUE2,...
3300 MATCHERC,VALUE1,VALUE2,...
3301 <empty line>
3302 The first character after if is taken to be the separator for the rest
3304 of the table. It should be a non-alphanumeric character like , or |
3305 that does not appear anywhere else in the table. (Note: it is unre‐
3306 lated to the CSV file's separator.) Whitespace can be used in the
3307 matcher lines for readability, but not in the if line currently. The
3308 table must be terminated by an empty line (or end of file). Each line
3309 must contain the same number of separators; empty values are allowed.
3310 The above means: try all of the matchers; whenever a matcher succeeds,
3312 assign all of the values on that line to the corresponding hledger
3313 fields; later lines can overrider earlier ones. It is equivalent to
3314 this sequence of if blocks:
3315 if MATCHERA
3317 HLEDGERFIELD1 VALUE1
3318 HLEDGERFIELD2 VALUE2
3319 ...
3320 if MATCHERB
3322 HLEDGERFIELD1 VALUE1
3323 HLEDGERFIELD2 VALUE2
3324 ...
3325 if MATCHERC
3327 HLEDGERFIELD1 VALUE1
3328 HLEDGERFIELD2 VALUE2
3329 ...
3330 Example:
3332 if,account2,comment
3334 atm transaction fee,expenses:business:banking,deductible? check it
3335 %description groceries,expenses:groceries,
3336 2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
3337 balance-type
3339 Balance assertions generated by assigning to balanceN are of the simple
3340 = type by default, which is a single-commodity, subaccount-excluding
3341 assertion. You may find the subaccount-including variants more useful,
3342 eg if you have created some virtual subaccounts of checking to help
3343 with budgeting. You can select a different type of assertion with the
3344 balance-type rule:
3345 # balance assertions will consider all commodities and all subaccounts
3347 balance-type ==*
3348 Here are the balance assertion types for quick reference:
3350 = single commodity, exclude subaccounts
3352 =* single commodity, include subaccounts
3353 == multi commodity, exclude subaccounts
3354 ==* multi commodity, include subaccounts
3355 include
3357 include RULESFILE
3358 This includes the contents of another CSV rules file at this point.
3360 RULESFILE is an absolute file path or a path relative to the current
3361 file's directory. This can be useful for sharing common rules between
3362 several rules files, eg:
3363 # someaccount.csv.rules
3365 ## someaccount-specific rules
3367 fields date,description,amount
3368 account1 assets:someaccount
3369 account2 expenses:misc
3370 ## common rules
3372 include categorisation.rules
3373 Working with CSV
3375 Some tips:
3376 Rapid feedback
3378 It's a good idea to get rapid feedback while creating/troubleshooting
3379 CSV rules. Here's a good way, using entr from eradman.com/entrproject:
3380 $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
3382 A desc: query (eg) is used to select just one, or a few, transactions
3384 of interest. "bash -c" is used to run multiple commands, so we can
3385 echo a separator each time the command re-runs, making it easier to
3386 read the output.
3387 Valid CSV
3389 Note that hledger will only accept valid CSV conforming to RFC 4180,
3390 and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or
3391 tab as separators). This means, eg:
3392 • Values may be enclosed in double quotes, or not. Enclosing in single
3394 quotes is not allowed. (Eg 'A','B' is rejected.)
3395 • When values are enclosed in double quotes, spaces outside the quotes
3397 are not allowed. (Eg "A", "B" is rejected.)
3398 • When values are not enclosed in quotes, they may not contain double
3400 quotes. (Eg A"A, B is rejected.)
3401 If your CSV/SSV/TSV is not valid in this sense, you'll need to trans‐
3403 form it before reading with hledger. Try using sed, or a more permis‐
3404 sive CSV parser like python's csv lib.
3405 File Extension
3407 To help hledger choose the CSV file reader and show the right error
3408 messages (and choose the right field separator character by default),
3409 it's best if CSV/SSV/TSV files are named with a .csv, .ssv or .tsv
3410 filename extension. (More about this at Data formats.)
3411 When reading files with the "wrong" extension, you can ensure the CSV
3413 reader (and the default field separator) by prefixing the file path
3414 with csv:, ssv: or tsv:: Eg:
3415 $ hledger -f ssv:foo.dat print
3417 You can also override the default field separator with a separator rule
3419 if needed.
3420 Reading CSV from standard input
3422 You'll need the file format prefix when reading CSV from stdin also,
3423 since hledger assumes journal format by default. Eg:
3424 $ cat foo.dat | hledger -f ssv:- print
3426 Reading multiple CSV files
3428 If you use multiple -f options to read multiple CSV files at once,
3429 hledger will look for a correspondingly-named rules file for each CSV
3430 file. But if you use the --rules-file option, that rules file will be
3431 used for all the CSV files.
3432 Reading files specified by rule
3434 Instead of specifying a CSV file in the command line, you can specify a
3435 rules file, as in hledger -f foo.csv.rules CMD. By default this will
3436 read data from foo.csv in the same directory, but you can add a source
3437 rule to specify a different data file, perhaps located in your web
3438 browser's download directory.
3439 This feature was added in hledger 1.30, so you won't see it in most CSV
3441 rules examples. But it helps remove some of the busywork of managing
3442 CSV downloads. Most of your financial institutions's default CSV file‐
3443 names are different and can be recognised by a glob pattern. So you
3444 can put a rule like source Checking1*.csv in foo-checking.csv.rules,
3445 and then periodically follow a workflow like:
3446 1. Download CSV from Foo's website, using your browser's defaults
3448 2. Run hledger import foo-checking.csv.rules to import any new transac‐
3450 tions
3451 After import, you can: discard the CSV, or leave it where it is for a
3453 while, or move it into your archives, as you prefer. If you do noth‐
3454 ing, next time your browser will save something like Checking1-2.csv,
3455 and hledger will use that because of the * wild card and because it is
3456 the most recent.
3457 Valid transactions
3459 After reading a CSV file, hledger post-processes and validates the gen‐
3460 erated journal entries as it would for a journal file - balancing them,
3461 applying balance assignments, and canonicalising amount styles. Any
3462 errors at this stage will be reported in the usual way, displaying the
3463 problem entry.
3464 There is one exception: balance assertions, if you have generated them,
3466 will not be checked, since normally these will work only when the CSV
3467 data is part of the main journal. If you do need to check balance as‐
3468 sertions generated from CSV right away, pipe into another hledger:
3469 $ hledger -f file.csv print | hledger -f- print
3471 Deduplicating, importing
3473 When you download a CSV file periodically, eg to get your latest bank
3474 transactions, the new file may overlap with the old one, containing
3475 some of the same records.
3476 The import command will (a) detect the new transactions, and (b) append
3478 just those transactions to your main journal. It is idempotent, so you
3479 don't have to remember how many times you ran it or with which version
3480 of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This
3481 is the easiest way to import CSV data. Eg:
3482 # download the latest CSV files, then run this command.
3484 # Note, no -f flags needed here.
3485 $ hledger import *.csv [--dry]
3486 This method works for most CSV files. (Where records have a stable
3488 chronological order, and new records appear only at the new end.)
3489 A number of other tools and workflows, hledger-specific and otherwise,
3491 exist for converting, deduplicating, classifying and managing CSV data.
3492 See:
3493 • https://hledger.org/cookbook.html#setups-and-workflows
3495 • https://plaintextaccounting.org -> data import/conversion
3497 Setting amounts
3499 Continuing from amount field above, here are more tips on handling var‐
3500 ious amount-setting situations:
3501 1. If the amount is in a single CSV field:
3503 a. If its sign indicates direction of flow:
3504 Assign it to amountN, to set the Nth posting's amount. N is usu‐
3505 ally 1 or 2 but can go up to 99.
3506 b. If another field indicates direction of flow:
3508 Use one or more conditional rules to set the appropriate amount
3509 sign. Eg:
3510 # assume a withdrawal unless Type contains "deposit":
3512 amount1 -%Amount
3513 if %Type deposit
3514 amount1 %Amount
3515 2. If the amount is in one of two CSV fields (eg Debit and Credit):
3517 a. If both fields are unsigned:
3518 Assign the fields to amountN-in and amountN-out. This sets posting
3519 N's amount to whichever of these has a non-zero value. If it's the
3520 -out value, the amount will be negated.
3521 b. If either field is signed:
3523 Use a conditional rule to flip the sign when needed. Eg below, the
3524 -out value already has a minus sign so we undo hledger's automatic
3525 negating by negating once more (but only if the field is non-empty,
3526 so that we don't leave a minus sign by itself):
3527 fields date, description, amount1-in, amount1-out
3529 if %amount1-out [1-9]
3530 amount1-out -%amount1-out
3531 c. If both fields can contain a non-zero value (or both can be
3533 empty):
3534 The -in/-out rules normally choose the value which is non-zero/non-
3535 empty. Some value pairs can be ambiguous, such as 1 and none. For
3536 such cases, use conditional rules to help select the amount. Eg,
3537 to handle the above you could select the value containing non-zero
3538 digits:
3539 fields date, description, in, out
3541 if %in [1-9]
3542 amount1 %in
3543 if %out [1-9]
3544 amount1 %out
3545 3. If you want posting 2's amount converted to cost:
3547 Use the unnumbered amount (or amount-in and amount-out) syntax.
3548 4. If the CSV has only balance amounts, not transaction amounts:
3550 Assign to balanceN, to set a balance assignment on the Nth posting,
3551 causing the posting's amount to be calculated automatically. balance
3552 with no number is equivalent to balance1. In this situation hledger is
3553 more likely to guess the wrong default account name, so you may need to
3554 set that explicitly.
3555 Amount signs
3557 There is some special handling making it easier to parse and to reverse
3558 amount signs. (This only works for whole amounts, not for cost amounts
3559 such as COST in amount1 AMT @ COST):
3560 • If an amount value begins with a plus sign:
3562 that will be removed: +AMT becomes AMT
3563 • If an amount value is parenthesised:
3565 it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT
3566 • If an amount value has two minus signs (or two sets of parentheses,
3568 or a minus sign and parentheses):
3569 they cancel out and will be removed: --AMT or -(AMT) becomes AMT
3570 • If an amount value contains just a sign (or just a set of parenthe‐
3572 ses):
3573 that is removed, making it an empty value. "+" or "-" or "()" becomes
3574 "".
3575 It's not possible (without preprocessing the CSV) to set an amount to
3577 its absolute value, ie discard its sign.
3578 Setting currency/commodity
3580 If the currency/commodity symbol is included in the CSV's amount
3581 field(s):
3582 2023-01-01,foo,$123.00
3584 you don't have to do anything special for the commodity symbol, it will
3586 be assigned as part of the amount. Eg:
3587 fields date,description,amount
3589 2023-01-01 foo
3591 expenses:unknown $123.00
3592 income:unknown $-123.00
3593 If the currency is provided as a separate CSV field:
3595 2023-01-01,foo,USD,123.00
3597 You can assign that to the currency pseudo-field, which has the special
3599 effect of prepending itself to every amount in the transaction (on the
3600 left, with no separating space):
3601 fields date,description,currency,amount
3603 2023-01-01 foo
3605 expenses:unknown USD123.00
3606 income:unknown USD-123.00
3607 Or, you can use a field assignment to construct the amount yourself,
3609 with more control. Eg to put the symbol on the right, and separated by
3610 a space:
3611 fields date,description,cur,amt
3613 amount %amt %cur
3614 2023-01-01 foo
3616 expenses:unknown 123.00 USD
3617 income:unknown -123.00 USD
3618 Note we used a temporary field name (cur) that is not currency - that
3620 would trigger the prepending effect, which we don't want here.
3621 Amount decimal places
3623 Like amounts in a journal file, the amounts generated by CSV rules like
3624 amount1 influence commodity display styles, such as the number of deci‐
3625 mal places displayed in reports.
3626 The original amounts as written in the CSV file do not affect display
3628 style (because we don't yet reliably know their commodity).
3629 Referencing other fields
3631 In field assignments, you can interpolate only CSV fields, not hledger
3632 fields. In the example below, there's both a CSV field and a hledger
3633 field named amount1, but %amount1 always means the CSV field, not the
3634 hledger field:
3635 # Name the third CSV field "amount1"
3637 fields date,description,amount1
3638 # Set hledger's amount1 to the CSV amount1 field followed by USD
3640 amount1 %amount1 USD
3641 # Set comment to the CSV amount1 (not the amount1 assigned above)
3643 comment %amount1
3644 Here, since there's no CSV amount1 field, %amount1 will produce a lit‐
3646 eral "amount1":
3647 fields date,description,csvamount
3649 amount1 %csvamount USD
3650 # Can't interpolate amount1 here
3651 comment %amount1
3652 When there are multiple field assignments to the same hledger field,
3654 only the last one takes effect. Here, comment's value will be be B, or
3655 C if "something" is matched, but never A:
3656 comment A
3658 comment B
3659 if something
3660 comment C
3661 How CSV rules are evaluated
3663 Here's how to think of CSV rules being evaluated (if you really need
3664 to). First,
3665 • include - all includes are inlined, from top to bottom, depth first.
3667 (At each include point the file is inlined and scanned for further
3668 includes, recursively, before proceeding.)
3669 Then "global" rules are evaluated, top to bottom. If a rule is re‐
3671 peated, the last one wins:
3672 • skip (at top level)
3674 • date-format
3676 • newest-first
3678 • fields - names the CSV fields, optionally sets up initial assignments
3680 to hledger fields
3681 Then for each CSV record in turn:
3683 • test all if blocks. If any of them contain a end rule, skip all re‐
3685 maining CSV records. Otherwise if any of them contain a skip rule,
3686 skip that many CSV records. If there are multiple matched skip
3687 rules, the first one wins.
3688 • collect all field assignments at top level and in matched if blocks.
3690 When there are multiple assignments for a field, keep only the last
3691 one.
3692 • compute a value for each hledger field - either the one that was as‐
3694 signed to it (and interpolate the %CSVFIELD references), or a default
3695 • generate a hledger transaction (journal entry) from these values.
3697 This is all part of the CSV reader, one of several readers hledger can
3699 use to parse input files. When all files have been read successfully,
3700 the transactions are passed as input to whichever hledger command the
3701 user specified.
3702 Well factored rules
3704 Some things than can help reduce duplication and complexity in rules
3705 files:
3706 • Extracting common rules usable with multiple CSV files into a com‐
3708 mon.rules, and adding include common.rules to each CSV's rules file.
3709 • Splitting if blocks into smaller if blocks, extracting the frequently
3711 used parts.
3712 CSV rules examples
3714 Bank of Ireland
3715 Here's a CSV with two amount fields (Debit and Credit), and a balance
3716 field, which we can use to add balance assertions, which is not neces‐
3717 sary but provides extra error checking:
3718 Date,Details,Debit,Credit,Balance
3720 07/12/2012,LODGMENT 529898,,10.0,131.21
3721 07/12/2012,PAYMENT,5,,126
3722 # bankofireland-checking.csv.rules
3724 # skip the header line
3726 skip
3727 # name the csv fields, and assign some of them as journal entry fields
3729 fields date, description, amount-out, amount-in, balance
3730 # We generate balance assertions by assigning to "balance"
3732 # above, but you may sometimes need to remove these because:
3733 #
3734 # - the CSV balance differs from the true balance,
3735 # by up to 0.0000000000005 in my experience
3736 #
3737 # - it is sometimes calculated based on non-chronological ordering,
3738 # eg when multiple transactions clear on the same day
3739 # date is in UK/Ireland format
3741 date-format %d/%m/%Y
3742 # set the currency
3744 currency EUR
3745 # set the base account for all txns
3747 account1 assets:bank:boi:checking
3748 $ hledger -f bankofireland-checking.csv print
3750 2012-12-07 LODGMENT 529898
3751 assets:bank:boi:checking EUR10.0 = EUR131.2
3752 income:unknown EUR-10.0
3753 2012-12-07 PAYMENT
3755 assets:bank:boi:checking EUR-5.0 = EUR126.0
3756 expenses:unknown EUR5.0
3757 The balance assertions don't raise an error above, because we're read‐
3759 ing directly from CSV, but they will be checked if these entries are
3760 imported into a journal file.
3761 Coinbase
3763 A simple example with some CSV from Coinbase. The spot price is
3764 recorded using cost notation. The legacy amount field name conve‐
3765 niently sets amount 2 (posting 2's amount) to the total cost.
3766 # 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
3768 # 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"
3769 # coinbase.csv.rules
3771 skip 1
3772 fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes
3773 date %Timestamp
3774 date-format %Y-%m-%dT%T%Z
3775 description %Notes
3776 account1 assets:coinbase:cc
3777 amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency
3778 $ hledger print -f coinbase.csv
3780 2021-12-30 Received 100.00 USDC from an external account
3781 assets:coinbase:cc 100 USDC @ 0.740000 GBP
3782 income:unknown -74.000000 GBP
3783 Amazon
3785 Here we convert amazon.com order history, and use an if block to gener‐
3786 ate a third posting if there's a fee. (In practice you'd probably get
3787 this data from your bank instead, but it's an example.)
3788 "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
3790 "Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"
3791 "Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"
3792 # amazon-orders.csv.rules
3794 # skip one header line
3796 skip 1
3797 # name the csv fields, and assign the transaction's date, amount and code.
3799 # Avoided the "status" and "amount" hledger field names to prevent confusion.
3800 fields date, _, toorfrom, name, amzstatus, amzamount, fees, code
3801 # how to parse the date
3803 date-format %b %-d, %Y
3804 # combine two fields to make the description
3806 description %toorfrom %name
3807 # save the status as a tag
3809 comment status:%amzstatus
3810 # set the base account for all transactions
3812 account1 assets:amazon
3813 # leave amount1 blank so it can balance the other(s).
3814 # I'm assuming amzamount excludes the fees, don't remember
3815 # set a generic account2
3817 account2 expenses:misc
3818 amount2 %amzamount
3819 # and maybe refine it further:
3820 #include categorisation.rules
3821 # add a third posting for fees, but only if they are non-zero.
3823 if %fees [1-9]
3824 account3 expenses:fees
3825 amount3 %fees
3826 $ hledger -f amazon-orders.csv print
3828 2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed
3829 assets:amazon
3830 expenses:misc $20.00
3831 2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed
3833 assets:amazon
3834 expenses:misc $25.00
3835 expenses:fees $1.00
3836 Paypal
3838 Here's a real-world rules file for (customised) Paypal CSV, with some
3839 Paypal-specific rules, and a second rules file included:
3840 "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"
3842 "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",""
3843 "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",""
3844 "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",""
3845 "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",""
3846 "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",""
3847 "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",""
3848 "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",""
3849 # paypal-custom.csv.rules
3851 # Tips:
3853 # Export from Activity -> Statements -> Custom -> Activity download
3854 # Suggested transaction type: "Balance affecting"
3855 # Paypal's default fields in 2018 were:
3856 # "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"
3857 # This rules file assumes the following more detailed fields, configured in "Customize report fields":
3858 # "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"
3859 fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note
3861 skip 1
3863 date-format %-m/%-d/%Y
3865 # ignore some paypal events
3867 if
3868 In Progress
3869 Temporary Hold
3870 Update to
3871 skip
3872 # add more fields to the description
3874 description %description_ %itemtitle
3875 # save some other fields as tags
3877 comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
3878 # convert to short currency symbols
3880 if %currency USD
3881 currency $
3882 if %currency EUR
3883 currency E
3884 if %currency GBP
3885 currency P
3886 # generate postings
3888 # the first posting will be the money leaving/entering my paypal account
3890 # (negative means leaving my account, in all amount fields)
3891 account1 assets:online:paypal
3892 amount1 %netamount
3893 # the second posting will be money sent to/received from other party
3895 # (account2 is set below)
3896 amount2 -%grossamount
3897 # if there's a fee, add a third posting for the money taken by paypal.
3899 if %feeamount [1-9]
3900 account3 expenses:banking:paypal
3901 amount3 -%feeamount
3902 comment3 business:
3903 # choose an account for the second posting
3905 # override the default account names:
3907 # if the amount is positive, it's income (a debit)
3908 if %grossamount ^[^-]
3909 account2 income:unknown
3910 # if negative, it's an expense (a credit)
3911 if %grossamount ^-
3912 account2 expenses:unknown
3913 # apply common rules for setting account2 & other tweaks
3915 include common.rules
3916 # apply some overrides specific to this csv
3918 # Transfers from/to bank. These are usually marked Pending,
3920 # which can be disregarded in this case.
3921 if
3922 Bank Account
3923 Bank Deposit to PP Account
3924 description %type for %referencetxnid %itemtitle
3925 account2 assets:bank:wf:pchecking
3926 account1 assets:online:paypal
3927 # Currency conversions
3929 if Currency Conversion
3930 account2 equity:currency conversion
3931 # common.rules
3933 if
3935 darcs
3936 noble benefactor
3937 account2 revenues:foss donations:darcshub
3938 comment2 business:
3939 if
3941 Calm Radio
3942 account2 expenses:online:apps
3943 if
3945 electronic frontier foundation
3946 Patreon
3947 wikimedia
3948 Advent of Code
3949 account2 expenses:dues
3950 if Google
3952 account2 expenses:online:apps
3953 description google | music
3954 $ hledger -f paypal-custom.csv print
3956 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
3957 assets:online:paypal $-6.99 = $-6.99
3958 expenses:online:apps $6.99
3959 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
3961 assets:online:paypal $6.99 = $0.00
3962 assets:bank:wf:pchecking $-6.99
3963 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
3965 assets:online:paypal $-7.00 = $-7.00
3966 expenses:dues $7.00
3967 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
3969 assets:online:paypal $7.00 = $0.00
3970 assets:bank:wf:pchecking $-7.00
3971 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
3973 assets:online:paypal $-2.00 = $-2.00
3974 expenses:dues $2.00
3975 expenses:banking:paypal ; business:
3976 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
3978 assets:online:paypal $2.00 = $0.00
3979 assets:bank:wf:pchecking $-2.00
3980 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
3982 assets:online:paypal $9.41 = $9.41
3983 revenues:foss donations:darcshub $-10.00 ; business:
3984 expenses:banking:paypal $0.59 ; business:
3985
3987 The time logging format of timeclock.el, as read by hledger.
3988 hledger can read time logs in timeclock format. As with Ledger, these
3990 are (a subset of) timeclock.el's format, containing clock-in and clock-
3991 out entries as in the example below. The date is a simple date. The
3992 time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional.
3993 The timezone, if present, must be four digits and is ignored (currently
3994 the time is always interpreted as a local time). Lines beginning with
3995 # or ; or *, and blank lines, are ignored.
3996 i 2015/03/30 09:00:00 some account optional description after 2 spaces ; optional comment, tags:
3998 o 2015/03/30 09:20:00
3999 i 2015/03/31 22:21:45 another:account
4000 o 2015/04/01 02:00:34
4001 hledger treats each clock-in/clock-out pair as a transaction posting
4003 some number of hours to an account. Or if the session spans more than
4004 one day, it is split into several transactions, one for each day. For
4005 the above time log, hledger print generates these journal entries:
4006 $ hledger -f t.timeclock print
4008 2015-03-30 * optional description after 2 spaces ; optional comment, tags:
4009 (some account) 0.33h
4010 2015-03-31 * 22:21-23:59
4012 (another:account) 1.64h
4013 2015-04-01 * 00:00-02:00
4015 (another:account) 2.01h
4016 Here is a sample.timeclock to download and some queries to try:
4018 $ hledger -f sample.timeclock balance # current time balances
4020 $ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009
4021 $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week
4022 To generate time logs, ie to clock in and clock out, you could:
4024 • use emacs and the built-in timeclock.el, or the extended timeclock-
4026 x.el and perhaps the extras in ledgerutils.el
4027 • at the command line, use these bash aliases: shell alias ti="echo
4029 i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o
4030 `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
4031 • or use the old ti and to scripts in the ledger 2.x repository. These
4033 rely on a "timeclock" executable which I think is just the ledger 2
4034 executable renamed.
4035
4037 timedot format is hledger's human-friendly time logging format. Com‐
4038 pared to timeclock format, it is
4039 • convenient for quick, approximate, and retroactive time logging
4041 • readable: you can see at a glance where time was spent.
4043 A timedot file contains a series of day entries, which might look like
4045 this:
4046 2023-05-01
4048 hom:errands .... .... ; two hours
4049 fos:hledger:timedot .. ; half an hour
4050 per:admin:finance
4051 hledger reads this as a transaction on this day with three (unbalanced)
4053 postings, where each dot represents "0.25". No commodity is assumed,
4054 but normally we interpret it as hours, with each dot representing a
4055 quarter-hour. It's convenient, though not required, to group the dots
4056 in fours for easy reading.
4057 $ hledger -f a.timedot print # .timedot file extension (or timedot: prefix) is required
4059 2023-05-01 *
4060 (hom:errands) 2.00 ; two hours
4061 (fos:hledger:timedot) 0.50 ; half an hour
4062 (per:admin:finance) 0
4063 A transaction begins with a non-indented simple date (Y-M-D, Y/M/D, or
4065 Y.M.D). It can optionally be preceded by one or more stars and a
4066 space, for Emacs org mode compatibility. It can optionally be followed
4067 on the same line by a transaction description, and/or a transaction
4068 comment following a semicolon.
4069 After the date line are zero or more time postings, consisting of:
4071 • an account name - any hledger-style account name, optionally hierar‐
4073 chical, optionally indented.
4074 • two or more spaces - a field separator, required if there is an
4076 amount (as in journal format).
4077 • an optional timedot amount - dots representing quarter hours, or a
4079 number representing hours, optionally with a unit suffix.
4080 • an optional posting comment following a semicolon.
4082 Timedot amounts can be:
4084 • dots: zero or more period characters (.), each representing 0.25.
4086 Spaces are ignored and can be used for grouping. Eg: .... ..
4087 • or a number. Eg: 1.5
4089 • or a number immediately followed by a unit symbol s, m, h, d, w, mo,
4091 or y. These are interpreted as seconds, minutes, hours, days weeks,
4092 months or years, and converted to hours, assuming:
4093 60s = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. Eg 90m is
4094 parsed as 1.5.
4095 There is some added flexibility to help with keeping time log data in
4097 the same file as your notes, todo lists, etc.:
4098 • Blank lines and lines beginning with # or ; are ignored.
4100 • Before the first date line, lines beginning with * are ignored.
4102 • From the first date line onward, one or more *'s followed by a space
4104 at beginning of lines (ie, the headline prefix used by Emacs Org
4105 mode) is ignored. This means the time log can be kept under an Org
4106 headline, and date lines or time transaction lines can be Org head‐
4107 lines.
4108 • Lines not ending with a double-space and amount are parsed as post‐
4110 ings with zero amount. Note hledger's register reports hide these by
4111 default (add -E to see them).
4112 More examples:
4114 # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
4116 2016/2/1
4117 inc:client1 .... .... .... .... .... ....
4118 fos:haskell .... ..
4119 biz:research .
4120 2016/2/2
4122 inc:client1 .... ....
4123 biz:research .
4124 2016/2/3
4126 inc:client1 4
4127 fos:hledger 3
4128 biz:research 1
4129 * Time log
4131 ** 2023-01-01
4132 *** adm:time .
4133 *** adm:finance .
4134 * 2023 Work Diary
4136 ** Q1
4137 *** 2023-02-29
4138 **** DONE
4139 0700 yoga
4140 **** UNPLANNED
4141 **** BEGUN
4142 hom:chores
4143 cleaning ...
4144 water plants
4145 outdoor - one full watering can
4146 indoor - light watering
4147 **** TODO
4148 adm:planning: trip
4149 *** LATER
4150 Reporting:
4152 $ hledger -f a.timedot print date:2016/2/2
4154 2016-02-02 *
4155 (inc:client1) 2.00
4156 2016-02-02 *
4158 (biz:research) 0.25
4159 $ hledger -f a.timedot bal --daily --tree
4161 Balance changes in 2016-02-01-2016-02-03:
4162 || 2016-02-01d 2016-02-02d 2016-02-03d
4164 ============++========================================
4165 biz || 0.25 0.25 1.00
4166 research || 0.25 0.25 1.00
4167 fos || 1.50 0 3.00
4168 haskell || 1.50 0 0
4169 hledger || 0 0 3.00
4170 inc || 6.00 2.00 4.00
4171 client1 || 6.00 2.00 4.00
4172 ------------++----------------------------------------
4173 || 7.75 2.25 8.00
4174 Using period instead of colon as account name separator:
4176 2016/2/4
4178 fos.hledger.timedot 4
4179 fos.ledger ..
4180 $ hledger -f a.timedot --alias /\\./=: bal --tree
4182 4.50 fos
4183 4.00 hledger:timedot
4184 0.50 ledger
4185 --------------------
4186 4.50
4187 A sample.timedot file.
4189
4192 Report start & end date
4193 By default, most hledger reports will show the full span of time repre‐
4194 sented by the journal. The report start date will be the earliest
4195 transaction or posting date, and the report end date will be the latest
4196 transaction, posting, or market price date.
4197 Often you will want to see a shorter time span, such as the current
4199 month. You can specify a start and/or end date using -b/--begin,
4200 -e/--end, -p/--period or a date: query (described below). All of these
4201 accept the smart date syntax (below).
4202 Some notes:
4204 • End dates are exclusive, as in Ledger, so you should write the date
4206 after the last day you want to see in the report.
4207 • As noted in reporting options: among start/end dates specified with
4209 options, the last (i.e. right-most) option takes precedence.
4210 • The effective report start and end dates are the intersection of the
4212 start/end dates from options and that from date: queries. That is,
4213 date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the
4214 smallest common time span.
4215 • In some cases a report interval will adjust start/end dates to fall
4217 on interval boundaries (see below).
4218 Examples:
4220 -b 2016/3/17 begin on St. Patrick’s day 2016
4222 -e 12/1 end at the start of december 1st of the current year
4223 (11/30 will be the last date included)
4224 -b thismonth all transactions on or after the 1st of the current month
4225 -p thismonth all transactions in the current month
4226 date:2016/3/17.. the above written as queries instead (.. can also be re‐
4227 placed with -)
4228 date:..12/1
4229 date:thismonth..
4230 date:thismonth
4231 Smart dates
4233 hledger's user interfaces accept a "smart date" syntax for added conve‐
4234 nience. Smart dates optionally can be relative to today's date, be
4235 written with english words, and have less-significant parts omitted
4236 (missing parts are inferred as 1). Some examples:
4237 2004/10/1, 2004-01-01, exact date, several separators allowed. Year
4239 2004.9.1 is 4+ digits, month is 1-12, day is 1-31
4240 2004 start of year
4241 2004/10 start of month
4242 10/1 month and day in current year
4243 21 day in current month
4244 october, oct start of month in current year
4245 yesterday, today, tomor‐ -1, 0, 1 days from today
4246 row
4247 last/this/next -1, 0, 1 periods from the current period
4251 day/week/month/quar‐
4252 ter/year
4253 in n n periods from the current period
4254 days/weeks/months/quar‐
4255 ters/years
4256 n n periods from the current period
4257 days/weeks/months/quar‐
4258 ters/years ahead
4259 n -n periods from the current period
4260 days/weeks/months/quar‐
4261 ters/years ago
4262 20181201 8 digit YYYYMMDD with valid year month and day
4263 201812 6 digit YYYYMM with valid year and month
4264 Some counterexamples - malformed digit sequences might give surprising
4266 results:
4267 201813 6 digits with an invalid month is parsed as start of
4269 6-digit year
4270 20181301 8 digits with an invalid month is parsed as start of
4271 8-digit year
4272 20181232 8 digits with an invalid day gives an error
4273 201801012 9+ digits beginning with a valid YYYYMMDD gives an error
4274 "Today's date" can be overridden with the --today option, in case it's
4276 needed for testing or for recreating old reports. (Except for periodic
4277 transaction rules, which are not affected by --today.)
4278 Report intervals
4280 A report interval can be specified so that reports like register, bal‐
4281 ance or activity become multi-period, showing each subperiod as a sepa‐
4282 rate row or column.
4283 The following standard intervals can be enabled with command-line
4285 flags:
4286 • -D/--daily
4288 • -W/--weekly
4290 • -M/--monthly
4292 • -Q/--quarterly
4294 • -Y/--yearly
4296 More complex intervals can be specified using -p/--period, described
4298 below.
4299 Date adjustment
4301 When there is a report interval (other than daily), report start/end
4302 dates which have been inferred, eg from the journal, are automatically
4303 adjusted to natural period boundaries. This is convenient for produc‐
4304 ing simple periodic reports. More precisely:
4305 • an inferred start date will be adjusted earlier if needed to fall on
4307 a natural period boundary
4308 • an inferred end date will be adjusted later if needed to make the
4310 last period the same length as the others.
4311 By contrast, start/end dates which have been specified explicitly, with
4313 -b, -e, -p or date:, will not be adjusted (since hledger 1.29). This
4314 makes it possible to specify non-standard report periods, but it also
4315 means that if you are specifying a start date, you should pick one
4316 that's on a period boundary if you want to see simple report period
4317 headings.
4318 Period expressions
4320 The -p/--period option specifies a period expression, which is a com‐
4321 pact way of expressing a start date, end date, and/or report interval.
4322 Here's a period expression with a start and end date (specifying the
4324 first quarter of 2009):
4325 -p "from 2009/1/1 to 2009/4/1"
4327 Several keywords like "from" and "to" are supported for readability;
4329 these are optional. "to" can also be written as ".." or "-". The spa‐
4330 ces are also optional, as long as you don't run two dates together. So
4331 the following are equivalent to the above:
4332 -p "2009/1/1 2009/4/1"
4334 -p2009/1/1to2009/4/1
4335 -p2009/1/1..2009/4/1
4336 Dates are smart dates, so if the current year is 2009, these are also
4338 equivalent to the above:
4339 -p "1/1 4/1"
4341 -p "jan-apr"
4342 -p "this year to 4/1"
4343 If you specify only one date, the missing start or end date will be the
4345 earliest or latest transaction date in the journal:
4346 -p "from 2009/1/1" everything after january
4348 1, 2009
4349 -p "since 2009/1" the same, since is a syn‐
4350 onym
4351 -p "from 2009" the same
4352 -p "to 2009" everything before january
4353 1, 2009
4354 You can also specify a period by writing a single partial or full date:
4356 -p "2009" the year 2009; equivalent to “2009/1/1 to 2010/1/1”
4358 -p "2009/1" the month of january 2009; equivalent to “2009/1/1 to
4359 2009/2/1”
4360 -p "2009/1/1" the first day of 2009; equivalent to “2009/1/1 to
4361 2009/1/2”
4362 or by using the "Q" quarter-year syntax (case insensitive):
4364 -p "2009Q1" first quarter of 2009, equivalent to “2009/1/1 to
4366 2009/4/1”
4367 -p "q4" fourth quarter of the current year
4368 Period expressions with a report interval
4370 A period expression can also begin with a report interval, separated
4371 from the start/end dates (if any) by a space or the word in:
4372 -p "weekly from 2009/1/1 to 2009/4/1"
4374 -p "monthly in 2008"
4375 -p "quarterly"
4376 More complex report intervals
4378 Some more complex intervals can be specified within period expressions,
4379 such as:
4380 • biweekly (every two weeks)
4382 • fortnightly
4384 • bimonthly (every two months)
4386 • every day|week|month|quarter|year
4388 • every N days|weeks|months|quarters|years
4390 Weekly on a custom day:
4392 • every Nth day of week (th, nd, rd, or st are all accepted after the
4394 number)
4395 • every WEEKDAYNAME (full or three-letter english weekday name, case
4397 insensitive)
4398 Monthly on a custom day:
4400 • every Nth day [of month]
4402 • every Nth WEEKDAYNAME [of month]
4404 Yearly on a custom day:
4406 • every MM/DD [of year] (month number and day of month number)
4408 • every MONTHNAME DDth [of year] (full or three-letter english month
4410 name, case insensitive, and day of month number)
4411 • every DDth MONTHNAME [of year] (equivalent to the above)
4413 Examples:
4415 -p "bimonthly from 2008"
4417 -p "every 2 weeks"
4418 -p "every 5 months from
4419 2009/03"
4420 -p "every 2nd day of week" periods will go from Tue to Tue
4421 -p "every Tue" same
4422 -p "every 15th day" period boundaries will be on 15th of each
4423 month
4424 -p "every 2nd Monday" period boundaries will be on second Monday
4425 of each month
4426 -p "every 11/05" yearly periods with boundaries on 5th of
4427 November
4428 -p "every 5th November" same
4429 -p "every Nov 5th" same
4430 Show historical balances at end of the 15th day of each month (N is an
4432 end date, exclusive as always):
4433 $ hledger balance -H -p "every 16th day"
4435 Group postings from the start of wednesday to end of the following
4437 tuesday (N is both (inclusive) start date and (exclusive) end date):
4438 $ hledger register checking -p "every 3rd day of week"
4440 Multiple weekday intervals
4442 This special form is also supported:
4443 • every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week‐
4445 day names, case insensitive)
4446 Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri and
4448 sat,sun.
4449 This is mainly intended for use with --forecast, to generate periodic
4451 transactions on arbitrary days of the week. It may be less useful with
4452 -p, since it divides each week into subperiods of unequal length, which
4453 is unusual. (Related: #1632)
4454 Examples:
4456 -p "every dates will be Mon, Wed, Fri; periods will be Mon-
4458 mon,wed,fri" Tue, Wed-Thu, Fri-Sun
4459 -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will
4460 be Mon, Tue, Wed, Thu, Fri-Sun
4461 -p "every weekend‐ dates will be Sat, Sun; periods will be Sat, Sun-Fri
4462 day"
4463
4465 With the --depth NUM option (short form: -NUM), reports will show ac‐
4466 counts only to the specified depth, hiding deeper subaccounts. Use
4467 this when you want a summary with less detail. This flag has the same
4468 effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva‐
4469 lent.
4470
4472 One of hledger's strengths is being able to quickly report on a precise
4473 subset of your data. Most hledger commands accept optional query argu‐
4474 ments to restrict their scope. The syntax is as follows:
4475 • Zero or more space-separated query terms. These are most often ac‐
4477 count name substrings:
4478 utilities food:groceries
4480 • Terms with spaces or other special characters should be enclosed in
4482 quotes:
4483 "personal care"
4485 • Regular expressions are also supported:
4487 "^expenses\b" "accounts (payable|receivable)"
4489 • Add a query type prefix to match other parts of the data:
4491 date:202312- desc:amazon cur:USD amt:">100" status:
4493 • Add a not: prefix to negate a term:
4495 not:cur:USD
4497 Query types
4499 Here are the types of query term available. Remember these can also be
4500 prefixed with not: to convert them into a negative match.
4501 acct:REGEX, REGEX
4503 Match account names containing this (case insensitive) regular expres‐
4504 sion. This is the default query type when there is no prefix, and reg‐
4505 ular expression syntax is typically not needed, so usually we just
4506 write an account name substring, like expenses or food.
4507 amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
4509 Match postings with a single-commodity amount equal to, less than, or
4510 greater than N. (Postings with multi-commodity amounts are not tested
4511 and will always match.) The comparison has two modes: if N is preceded
4512 by a + or - sign (or is 0), the two signed numbers are compared. Oth‐
4513 erwise, the absolute magnitudes are compared, ignoring sign.
4514 code:REGEX
4516 Match by transaction code (eg check number).
4517 cur:REGEX
4519 Match postings or transactions including any amounts whose cur‐
4520 rency/commodity symbol is fully matched by REGEX. (For a partial
4521 match, use .*REGEX.*). Note, to match special characters which are
4522 regex-significant, you need to escape them with \. And for characters
4523 which are significant to your shell you may need one more level of es‐
4524 caping. So eg to match the dollar sign:
4525 hledger print cur:\\$.
4526 desc:REGEX
4528 Match transaction descriptions.
4529 date:PERIODEXPR
4531 Match dates (or with the --date2 flag, secondary dates) within the
4532 specified period. PERIODEXPR is a period expression with no report in‐
4533 terval. Examples:
4534 date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter.
4535 date2:PERIODEXPR
4537 Match secondary dates within the specified period (independent of the
4538 --date2 flag).
4539 depth:N
4541 Match (or display, depending on command) accounts at or above this
4542 depth.
4543 note:REGEX
4545 Match transaction notes (the part of the description right of |, or the
4546 whole description if there's no |).
4547 payee:REGEX
4549 Match transaction payee/payer names (the part of the description left
4550 of |, or the whole description if there's no |).
4551 real:, real:0
4553 Match real or virtual postings respectively.
4554 status:, status:!, status:*
4556 Match unmarked, pending, or cleared transactions respectively.
4557 type:TYPECODES
4559 Match by account type (see Declaring accounts > Account types). TYPE‐
4560 CODES is one or more of the single-letter account type codes ALERXCV,
4561 case insensitive. Note type:A and type:E will also match their respec‐
4562 tive subtypes C (Cash) and V (Conversion). Certain kinds of account
4563 alias can disrupt account types, see Rewriting accounts > Aliases and
4564 account types.
4565 tag:REGEX[=REGEX]
4567 Match by tag name, and optionally also by tag value. (To match only by
4568 value, use tag:.=REGEX.)
4569 When querying by tag, note that:
4571 • Accounts also inherit the tags of their parent accounts
4573 • Postings also inherit the tags of their account and their transaction
4575 • Transactions also acquire the tags of their postings.
4577 (inacct:ACCTNAME
4579 A special query term used automatically in hledger-web only: tells
4580 hledger-web to show the transaction register for an account.)
4581 Combining query terms
4583 When given multiple space-separated query terms, most commands select
4584 things which match:
4585 • any of the description terms AND
4587 • any of the account terms AND
4589 • any of the status terms AND
4591 • all the other terms.
4593 The print command is a little different, showing transactions which:
4595 • match any of the description terms AND
4597 • have any postings matching any of the positive account terms AND
4599 • have no postings matching any of the negative account terms AND
4601 • match all the other terms.
4603 We also support more complex boolean queries with the 'expr:' prefix.
4605 This allows one to combine queries using one of three operators: AND,
4606 OR, and NOT, where NOT is different syntax for 'not:'.
4607 Examples of such queries are:
4609 • Match transactions with 'cool' in the description AND with the 'A'
4611 tag
4612 expr:"desc:cool AND tag:A"
4614 • Match transactions NOT to the 'expenses:food' account OR with the 'A'
4616 tag
4617 expr:"NOT expenses:food OR tag:A"
4619 • Match transactions NOT involving the 'expenses:food' account OR with
4621 the 'A' tag AND involving the 'expenses:drink' account. (the AND is
4622 implicitly added by space-separation, following the rules above)
4623 expr:"expenses:food OR (tag:A expenses:drink)"
4625 Queries and command options
4627 Some queries can also be expressed as command-line options: depth:2 is
4628 equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc. When
4629 you mix command options and query arguments, generally the resulting
4630 query is their intersection.
4631 Queries and valuation
4633 When amounts are converted to other commodities in cost or value re‐
4634 ports, cur: and amt: match the old commodity symbol and the old amount
4635 quantity, not the new ones (except in hledger 1.22.0 where it's re‐
4636 versed, see #1625).
4637 Querying with account aliases
4639 When account names are rewritten with --alias or alias, note that acct:
4640 will match either the old or the new account name.
4641 Querying with cost or value
4643 When amounts are converted to other commodities in cost or value re‐
4644 ports, note that cur: matches the new commodity symbol, and not the old
4645 one, and amt: matches the new quantity, and not the old one. Note:
4646 this changed in hledger 1.22, previously it was the reverse, see the
4647 discussion at #1625.
4648
4650 Normally, hledger groups and sums amounts within each account. The
4651 --pivot FIELD option substitutes some other transaction field for ac‐
4652 count names, causing amounts to be grouped and summed by that field's
4653 value instead. FIELD can be any of the transaction fields status,
4654 code, description, payee, note, or a tag name. When pivoting on a tag
4655 and a posting has multiple values of that tag, only the first value is
4656 displayed. Values containing colon:separated:parts will be displayed
4657 hierarchically, like account names.
4658 Some examples:
4660 2016/02/16 Yearly Dues Payment
4662 assets:bank account 2 EUR
4663 income:dues -2 EUR ; member: John Doe
4664 Normal balance report showing account names:
4666 $ hledger balance
4668 2 EUR assets:bank account
4669 -2 EUR income:dues
4670 --------------------
4671 0
4672 Pivoted balance report, using member: tag values instead:
4674 $ hledger balance --pivot member
4676 2 EUR
4677 -2 EUR John Doe
4678 --------------------
4679 0
4680 One way to show only amounts with a member: value (using a query):
4682 $ hledger balance --pivot member tag:member=.
4684 -2 EUR John Doe
4685 --------------------
4686 -2 EUR
4687 Another way (the acct: query matches against the pivoted "account
4689 name"):
4690 $ hledger balance --pivot member acct:.
4692 -2 EUR John Doe
4693 --------------------
4694 -2 EUR
4695
4697 hledger has several features for generating data, such as:
4698 • Periodic transaction rules can generate single or repeating transac‐
4700 tions following a template. These are usually dated in the future,
4701 eg to help with forecasting. They are activated by the --forecast
4702 option.
4703 • The balance command's --budget option uses these same periodic rules
4705 to generate goals for the budget report.
4706 • Auto posting rules can generate extra postings on certain matched
4708 transactions. They are always applied to forecast transactions; with
4709 the --auto flag they are applied to transactions recorded in the
4710 journal as well.
4711 • The --infer-equity flag infers missing conversion equity postings
4713 from @/@@ costs. And the inverse --infer-costs flag infers missing
4714 @/@@ costs from conversion equity postings.
4715 Generated data of this kind is temporary, existing only at report time.
4717 But you can see it in the output of hledger print, and you can save
4718 that to your journal, in effect converting it from temporary generated
4719 data to permanent recorded data. This could be useful as a data entry
4720 aid.
4721 If you are wondering what data is being generated and why, add the
4723 --verbose-tags flag. In hledger print output you will see extra tags
4724 like generated-transaction, generated-posting, and modified on gener‐
4725 ated/modified data. Also, even without --verbose-tags, generated data
4726 always has equivalen hidden tags (with an underscore prefix), so eg you
4727 could match generated transactions with tag:_generated-transaction.
4728
4730 Forecasting, or speculative future reporting, can be useful for esti‐
4731 mating future balances, or for exploring different future scenarios.
4732 The simplest and most flexible way to do it with hledger is to manually
4734 record a bunch of future-dated transactions. You could keep these in a
4735 separate future.journal and include that with -f only when you want to
4736 see them.
4737 --forecast
4739 There is another way: with the --forecast option, hledger can generate
4740 temporary "forecast transactions" for reporting purposes, according to
4741 periodic transaction rules defined in the journal. Each rule can gen‐
4742 erate multiple recurring transactions, so by changing one rule you can
4743 change many forecasted transactions. (These same rules can also gener‐
4744 ate budget goals, described in Budgeting.)
4745 Forecast transactions usually start after ordinary transactions end.
4747 By default, they begin after your latest-dated ordinary transaction, or
4748 today, whichever is later, and they end six months from today. (The
4749 exact rules are a little more complicated, and are given below.)
4750 This is the "forecast period", which need not be the same as the report
4752 period. You can override it - eg to forecast farther into the future,
4753 or to force forecast transactions to overlap your ordinary transactions
4754 - by giving the --forecast option a period expression argument, like
4755 --forecast=..2099 or --forecast=2023-02-15... Note that the = is re‐
4756 quired.
4757 Inspecting forecast transactions
4759 print is the best command for inspecting and troubleshooting forecast
4760 transactions. Eg:
4761 ~ monthly from 2022-12-20 rent
4763 assets:bank:checking
4764 expenses:rent $1000
4765 $ hledger print --forecast --today=2023/4/21
4767 2023-05-20 rent
4768 ; generated-transaction: ~ monthly from 2022-12-20
4769 assets:bank:checking
4770 expenses:rent $1000
4771 2023-06-20 rent
4773 ; generated-transaction: ~ monthly from 2022-12-20
4774 assets:bank:checking
4775 expenses:rent $1000
4776 2023-07-20 rent
4778 ; generated-transaction: ~ monthly from 2022-12-20
4779 assets:bank:checking
4780 expenses:rent $1000
4781 2023-08-20 rent
4783 ; generated-transaction: ~ monthly from 2022-12-20
4784 assets:bank:checking
4785 expenses:rent $1000
4786 2023-09-20 rent
4788 ; generated-transaction: ~ monthly from 2022-12-20
4789 assets:bank:checking
4790 expenses:rent $1000
4791 Here there are no ordinary transactions, so the forecasted transactions
4793 begin on the first occurence after today's date. (You won't normally
4794 use --today; it's just to make these examples reproducible.)
4795 Forecast reports
4797 Forecast transactions affect all reports, as you would expect. Eg:
4798 $ hledger areg rent --forecast --today=2023/4/21
4800 Transactions in expenses:rent and subaccounts:
4801 2023-05-20 rent as:ba:checking $1000 $1000
4802 2023-06-20 rent as:ba:checking $1000 $2000
4803 2023-07-20 rent as:ba:checking $1000 $3000
4804 2023-08-20 rent as:ba:checking $1000 $4000
4805 2023-09-20 rent as:ba:checking $1000 $5000
4806 $ hledger bal -M expenses --forecast --today=2023/4/21
4808 Balance changes in 2023-05-01..2023-09-30:
4809 || May Jun Jul Aug Sep
4811 ===============++===================================
4812 expenses:rent || $1000 $1000 $1000 $1000 $1000
4813 ---------------++-----------------------------------
4814 || $1000 $1000 $1000 $1000 $1000
4815 Forecast tags
4817 Forecast transactions generated by --forecast have a hidden tag, _gen‐
4818 erated-transaction. So if you ever need to match forecast transac‐
4819 tions, you could use tag:_generated-transaction (or just tag:generated)
4820 in a query.
4821 For troubleshooting, you can add the --verbose-tags flag. Then, visi‐
4823 ble generated-transaction tags will be added also, so you can view them
4824 with the print command. Their value indicates which periodic rule was
4825 responsible.
4826 Forecast period, in detail
4828 Forecast start/end dates are chosen so as to do something useful by de‐
4829 fault in almost all situations, while also being flexible. Here are
4830 (with luck) the exact rules, to help with troubleshooting:
4831 The forecast period starts on:
4833 • the later of
4835 • the start date in the periodic transaction rule
4837 • the start date in --forecast's argument
4839 • otherwise (if those are not available): the later of
4841 • the report start date specified with -b/-p/date:
4843 • the day after the latest ordinary transaction in the journal
4845 • otherwise (if none of these are available): today.
4847 The forecast period ends on:
4849 • the earlier of
4851 • the end date in the periodic transaction rule
4853 • the end date in --forecast's argument
4855 • otherwise: the report end date specified with -e/-p/date:
4857 • otherwise: 180 days (~6 months) from today.
4859 Forecast troubleshooting
4861 When --forecast is not doing what you expect, one of these tips should
4862 help:
4863 • Remember to use the --forecast option.
4865 • Remember to have at least one periodic transaction rule in your jour‐
4867 nal.
4868 • Test with print --forecast.
4870 • Check for typos or too-restrictive start/end dates in your periodic
4872 transaction rule.
4873 • Leave at least 2 spaces between the rule's period expression and de‐
4875 scription fields.
4876 • Check for future-dated ordinary transactions suppressing forecasted
4878 transactions.
4879 • Try setting explicit report start and/or end dates with -b, -e, -p or
4881 date:
4882 • Try adding the -E flag to encourage display of empty periods/zero
4884 transactions.
4885 • Try setting explicit forecast start and/or end dates with --fore‐
4887 cast=START..END
4888 • Consult Forecast period, in detail, above.
4890 • Check inside the engine: add --debug=2 (eg).
4892
4894 With the balance command's --budget report, each periodic transaction
4895 rule generates recurring budget goals in specified accounts, and goals
4896 and actual performance can be compared. See the balance command's doc
4897 below.
4898 You can generate budget goals and forecast transactions at the same
4900 time, from the same or different periodic transaction rules: hledger
4901 bal -M --budget --forecast ...
4902 See also: Budgeting and Forecasting.
4904
4906 This section is about recording the cost of things, in transactions
4907 where one commodity is exchanged for another. Eg an exchange of cur‐
4908 rency, or a stock purchase or sale. First, a quick glossary:
4909 • Conversion - an exchange of one currency or commodity for another.
4911 Eg a foreign currency exchange, or a purchase or sale of stock or
4912 cryptocurrency.
4913 • Conversion transaction - a transaction involving one or more conver‐
4915 sions.
4916 • Conversion rate - the cost per unit of one commodity in the other, ie
4918 the exchange rate.
4919 • Cost - how much of one commodity was paid to acquire the other. And
4921 more generally, in hledger docs: the amount exchanged in the "sec‐
4922 ondary" commodity (usually your base currency), whether in a purchase
4923 or a sale, and whether expressed per unit or in total. Also, the
4924 "@/@@ PRICE" notation used to represent this.
4925 -B: Convert to cost
4927 As discussed in JOURNAL > Costs, when recording a transaction you can
4928 also record the amount's cost in another commodity, by adding @ UNIT‐
4929 PRICE or @@ TOTALPRICE.
4930 Then you can see a report with amounts converted to cost, by adding the
4932 -B/--cost flag. (Mnemonic: "B" from "cost Basis", as in Ledger). Eg:
4933 2022-01-01
4935 assets:dollars $-135 ; 135 dollars is exchanged for..
4936 assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each
4937 $ hledger bal -N
4939 $-135 assets:dollars
4940 €100 assets:euros
4941 $ hledger bal -N -B
4942 $-135 assets:dollars
4943 $135 assets:euros # <- the euros' cost
4944 Notes:
4946 -B is sensitive to the order of postings when a cost is inferred: the
4948 inferred price will be in the commodity of the last amount. So if ex‐
4949 ample 3's postings are reversed, while the transaction is equivalent,
4950 -B shows something different:
4951 2022-01-01
4953 assets:dollars $-135 ; 135 dollars sold
4954 assets:euros €100 ; for 100 euros
4955 $ hledger bal -N -B
4957 €-100 assets:dollars # <- the dollars' selling price
4958 €100 assets:euros
4959 The @/@@ cost notation is convenient, but has some drawbacks: it does
4961 not truly balance the transaction, so it disrupts the accounting equa‐
4962 tion and tends to causes a non-zero total in balance reports.
4963 Equity conversion postings
4965 By contrast, conventional double entry bookkeeping (DEB) uses a differ‐
4966 ent notation: an extra pair of equity postings to balance conversion
4967 transactions. In this style, the above entry might be written:
4968 2022-01-01 one hundred euros purchased at $1.35 each
4970 assets:dollars $-135
4971 equity:conversion $135
4972 equity:conversion €-100
4973 assets:euros €100
4974 This style is more correct, but it's also more verbose and makes cost
4976 reporting more difficult for PTA tools.
4977 Happily, current hledger can read either notation, or convert one to
4979 the other when needed, so you can use the one you prefer.
4980 You can even use cost notation and equivalent conversion postings at
4982 the same time, for clarity. hledger will ignore the redundancy. But
4983 be sure the cost and conversion posting amounts match, or you'll see a
4984 not-so-clear transaction balancing error message.
4985 Inferring equity postings from cost
4987 With --infer-equity, hledger detects transactions written with PTA cost
4988 notation and adds equity conversion postings to them:
4989 2022-01-01
4991 assets:dollars -$135
4992 assets:euros €100 @ $1.35
4993 $ hledger print --infer-equity
4995 2022-01-01
4996 assets:dollars $-135
4997 assets:euros €100 @ $1.35
4998 equity:conversion:$-€:€ €-100 ; generated-posting:
4999 equity:conversion:$-€:$ $135.00 ; generated-posting:
5000 The conversion account names can be changed with the conversion account
5002 type declaration.
5003 --infer-equity is useful when when transactions have been recorded us‐
5005 ing cost notation, to help preserve the accounting equation and balance
5006 reports' zero total, or to produce more conventional journal entries
5007 for sharing with non-PTA-users.
5008 Inferring cost from equity postings
5010 The reverse operation is possible using --infer-costs, which detects
5011 transactions written with equity conversion postings and adds cost no‐
5012 tation to them:
5013 2022-01-01
5015 assets:dollars $-135
5016 equity:conversion $135
5017 equity:conversion €-100
5018 assets:euros €100
5019 $ hledger print --infer-costs
5021 2022-01-01
5022 assets:dollars $-135 @@ €100
5023 equity:conversion $135
5024 equity:conversion €-100
5025 assets:euros €100
5026 --infer-costs is useful when combined with -B/--cost, allowing cost re‐
5028 porting even when transactions have been recorded using equity post‐
5029 ings:
5030 $ hledger print --infer-costs -B
5032 2009-01-01
5033 assets:dollars €-100
5034 assets:euros €100
5035 Notes:
5037 For --infer-costs to work, an exchange must consist of four postings:
5039 1. two non-equity postings
5041 2. two equity postings, next to one another
5043 3. the equity accounts must be declared, with account type V/Conversion
5045 (or if they are not declared, they must be named equity:conversion,
5046 equity:trade, equity:trading or subaccounts of these)
5047 4. the equity postings' amounts must exactly match the non-equity post‐
5049 ings' amounts.
5050 Multiple such exchanges can coexist within a single transaction.
5052 When inferring cost, the order of postings matters: the cost is added
5054 to the first of the non-equity postings involved in the exchange, in
5055 the commodity of the last non-equity posting involved in the exchange.
5056 If you don't want to write your postings in the required order, you can
5057 use explicit cost notation instead.
5058 --infer-equity and --infer-costs can be used together, if you have a
5060 mixture of both notations in your journal.
5061 When to infer cost/equity
5063 Inferring equity postings or costs is still fairly new, so not enabled
5064 by default. We're not sure yet if that should change. Here are two
5065 suggestions to try, experience reports welcome:
5066 1. When you use -B, always use --infer-costs as well. Eg: hledger bal
5068 -B --infer-costs
5069 2. Always run hledger with both flags enabled. Eg: alias hl="hledger
5071 --infer-equity --infer-costs"
5072 How to record conversions
5074 Essentially there are four ways to record a conversion transaction in
5075 hledger. Here are all of them, with pros and cons.
5076 Conversion with implicit cost
5078 Let's assume 100 EUR is converted to 120 USD. You can just record the
5079 outflow (100 EUR) and inflow (120 USD) in the appropriate asset ac‐
5080 count:
5081 2021-01-01
5083 assets:cash -100 EUR
5084 assets:cash 120 USD
5085 hledger will assume this transaction is balanced, inferring that the
5087 conversion rate must be 1 EUR = 1.20 USD. You can see the inferred
5088 rate by using hledger print -x.
5089 Pro:
5091 • Concise, easy
5093 Con:
5095 • Less error checking - typos in amounts or commodity symbols may not
5097 be detected
5098 • Conversion rate is not clear
5100 • Disturbs the accounting equation, unless you add the --infer-equity
5102 flag
5103 You can prevent accidental implicit conversions due to a mistyped com‐
5105 modity symbol, by using hledger check commodities.
5106 You can prevent implicit conversions entirely, by using hledger check
5108 balancednoautoconversion, or -s/--strict.
5109 Conversion with explicit cost
5111 You can add the conversion rate using @ notation:
5112 2021-01-01
5114 assets:cash -100 EUR @ 1.20 USD
5115 assets:cash 120 USD
5116 Now hledger will check that 100 * 1.20 = 120, and would report an error
5118 otherwise.
5119 Pro:
5121 • Still concise
5123 • Makes the conversion rate clear
5125 • Provides more error checking
5127 Con:
5129 • Disturbs the accounting equation, unless you add the --infer-equity
5131 flag
5132 Conversion with equity postings
5134 In strict double entry bookkeeping, the above transaction is not bal‐
5135 anced in EUR or in USD, since some EUR disappears, and some USD ap‐
5136 pears. This violates the accounting equation (A+L+E=0), and prevents
5137 reports like balancesheetequity from showing a zero total.
5138 The proper way to make it balance is to add a balancing posting for
5140 each commodity, using an equity account:
5141 2021-01-01
5143 assets:cash -100 EUR
5144 equity:conversion 100 EUR
5145 equity:conversion -120 USD
5146 assets:cash 120 USD
5147 Pro:
5149 • Preserves the accounting equation
5151 • Keeps track of conversions and related gains/losses in one place
5153 • Standard, works in any double entry accounting system
5155 Con:
5157 • More verbose
5159 • Conversion rate is not obvious
5161 • Cost reporting requires adding the --infer-costs flag
5163 Conversion with equity postings and explicit cost
5165 Here both equity postings and @ notation are used together.
5166 2021-01-01
5168 assets:cash -100 EUR @ 1.20 USD
5169 equity:conversion 100 EUR
5170 equity:conversion -120 USD
5171 assets:cash 120 USD
5172 Pro:
5174 • Preserves the accounting equation
5176 • Keeps track of conversions and related gains/losses in one place
5178 • Makes the conversion rate clear
5180 • Provides more error checking
5182 Con:
5184 • Most verbose
5186 • Not compatible with ledger
5188 Cost tips
5190 • Recording the cost/conversion rate explicitly is good because it
5191 makes that clear and helps detect errors.
5192 • Recording equity postings is good because it is correct bookkeeping
5194 and preserves the accounting equation.
5195 • Combining these is possible.
5197 • When you want to see the cost (or sale proceeds) of things, use -B
5199 (short form of --cost).
5200 • If you use conversion postings without cost notation, add --infer-
5202 costs also.
5203 • If you use cost notation without conversion postings, and you want to
5205 see a balanced balance sheet or print correct journal entries, use
5206 --infer-equity.
5207 • Conversion to cost is performed before valuation (described next).
5209
5211 Instead of reporting amounts in their original commodity, hledger can
5212 convert them to cost/sale amount (using the conversion rate recorded in
5213 the transaction), and/or to market value (using some market price on a
5214 certain date). This is controlled by the --value=TYPE[,COMMODITY] op‐
5215 tion, which will be described below. We also provide the simpler -V
5216 and -X COMMODITY options, and often one of these is all you need:
5217 -V: Value
5219 The -V/--market flag converts amounts to market value in their default
5220 valuation commodity, using the market prices in effect on the valuation
5221 date(s), if any. More on these in a minute.
5222 -X: Value in specified commodity
5224 The -X/--exchange=COMM option is like -V, except you tell it which cur‐
5225 rency you want to convert to, and it tries to convert everything to
5226 that.
5227 Valuation date
5229 Since market prices can change from day to day, market value reports
5230 have a valuation date (or more than one), which determines which market
5231 prices will be used.
5232 For single period reports, if an explicit report end date is specified,
5234 that will be used as the valuation date; otherwise the valuation date
5235 is the journal's end date.
5236 For multiperiod reports, each column/period is valued on the last day
5238 of the period, by default.
5239 Finding market price
5241 To convert a commodity A to its market value in another commodity B,
5242 hledger looks for a suitable market price (exchange rate) as follows,
5243 in this order of preference :
5244 1. A declared market price or inferred market price: A's latest market
5246 price in B on or before the valuation date as declared by a P direc‐
5247 tive, or (with the --infer-market-prices flag) inferred from costs.
5248 2. A reverse market price: the inverse of a declared or inferred market
5250 price from B to A.
5251 3. A forward chain of market prices: a synthetic price formed by com‐
5253 bining the shortest chain of "forward" (only 1 above) market prices,
5254 leading from A to B.
5255 4. Any chain of market prices: a chain of any market prices, including
5257 both forward and reverse prices (1 and 2 above), leading from A to
5258 B.
5259 There is a limit to the length of these price chains; if hledger
5261 reaches that length without finding a complete chain or exhausting all
5262 possibilities, it will give up (with a "gave up" message visible in
5263 --debug=2 output). That limit is currently 1000.
5264 Amounts for which no suitable market price can be found, are not con‐
5266 verted.
5267 --infer-market-prices: market prices from transactions
5269 Normally, market value in hledger is fully controlled by, and requires,
5270 P directives in your journal. Since adding and updating those can be a
5271 chore, and since transactions usually take place at close to market
5272 value, why not use the recorded costs as additional market prices (as
5273 Ledger does) ? Adding the --infer-market-prices flag to -V, -X or
5274 --value enables this.
5275 So for example, hledger bs -V --infer-market-prices will get market
5277 prices both from P directives and from transactions. If both occur on
5278 the same day, the P directive takes precedence.
5279 There is a downside: value reports can sometimes be affected in confus‐
5281 ing/undesired ways by your journal entries. If this happens to you,
5282 read all of this Valuation section carefully, and try adding --debug or
5283 --debug=2 to troubleshoot.
5284 --infer-market-prices can infer market prices from:
5286 • multicommodity transactions with explicit prices (@/@@)
5288 • multicommodity transactions with implicit prices (no @, two commodi‐
5290 ties, unbalanced). (With these, the order of postings matters.
5291 hledger print -x can be useful for troubleshooting.)
5292 • multicommodity transactions with equity postings, if cost is inferred
5294 with --infer-costs.
5295 There is a limitation (bug) currently: when a valuation commodity is
5297 not specified, prices inferred with --infer-market-prices do not help
5298 select a default valuation commodity, as P prices would. So conversion
5299 might not happen because no valuation commodity was detected (--debug=2
5300 will show this). To be safe, specify the valuation commmodity, eg:
5301 • -X EUR --infer-market-prices, not -V --infer-market-prices
5303 • --value=then,EUR --infer-market-prices, not --value=then --infer-mar‐
5305 ket-prices
5306 Signed costs and market prices can be confusing. For reference, here
5308 is the current behaviour, since hledger 1.25. (If you think it should
5309 work differently, see #1870.)
5310 2022-01-01 Positive Unit prices
5312 a A 1
5313 b B -1 @ A 1
5314 2022-01-01 Positive Total prices
5316 a A 1
5317 b B -1 @@ A 1
5318 2022-01-02 Negative unit prices
5321 a A 1
5322 b B 1 @ A -1
5323 2022-01-02 Negative total prices
5325 a A 1
5326 b B 1 @@ A -1
5327 2022-01-03 Double Negative unit prices
5330 a A -1
5331 b B -1 @ A -1
5332 2022-01-03 Double Negative total prices
5334 a A -1
5335 b B -1 @@ A -1
5336 All of the transactions above are considered balanced (and on each day,
5338 the two transactions are considered equivalent). Here are the market
5339 prices inferred for B:
5340 $ hledger -f- --infer-market-prices prices
5342 P 2022-01-01 B A 1
5343 P 2022-01-01 B A 1.0
5344 P 2022-01-02 B A -1
5345 P 2022-01-02 B A -1.0
5346 P 2022-01-03 B A -1
5347 P 2022-01-03 B A -1.0
5348 Valuation commodity
5350 When you specify a valuation commodity (-X COMM or --value TYPE,COMM):
5351 hledger will convert all amounts to COMM, wherever it can find a suit‐
5352 able market price (including by reversing or chaining prices).
5353 When you leave the valuation commodity unspecified (-V or --value
5355 TYPE):
5356 For each commodity A, hledger picks a default valuation commodity as
5357 follows, in this order of preference:
5358 1. The price commodity from the latest P-declared market price for A on
5360 or before valuation date.
5361 2. The price commodity from the latest P-declared market price for A on
5363 any date. (Allows conversion to proceed when there are inferred
5364 prices before the valuation date.)
5365 3. If there are no P directives at all (any commodity or date) and the
5367 --infer-market-prices flag is used: the price commodity from the
5368 latest transaction-inferred price for A on or before valuation date.
5369 This means:
5371 • If you have P directives, they determine which commodities -V will
5373 convert, and to what.
5374 • If you have no P directives, and use the --infer-market-prices flag,
5376 costs determine it.
5377 Amounts for which no valuation commodity can be found are not con‐
5379 verted.
5380 Simple valuation examples
5382 Here are some quick examples of -V:
5383 ; one euro is worth this many dollars from nov 1
5385 P 2016/11/01 € $1.10
5386 ; purchase some euros on nov 3
5388 2016/11/3
5389 assets:euros €100
5390 assets:checking
5391 ; the euro is worth fewer dollars by dec 21
5393 P 2016/12/21 € $1.03
5394 How many euros do I have ?
5396 $ hledger -f t.j bal -N euros
5398 €100 assets:euros
5399 What are they worth at end of nov 3 ?
5401 $ hledger -f t.j bal -N euros -V -e 2016/11/4
5403 $110.00 assets:euros
5404 What are they worth after 2016/12/21 ? (no report end date specified,
5406 defaults to today)
5407 $ hledger -f t.j bal -N euros -V
5409 $103.00 assets:euros
5410 --value: Flexible valuation
5412 -V and -X are special cases of the more general --value option:
5413 --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD.
5415 COMM is an optional commodity symbol.
5416 Shows amounts converted to:
5417 - default valuation commodity (or COMM) using market prices at posting dates
5418 - default valuation commodity (or COMM) using market prices at period end(s)
5419 - default valuation commodity (or COMM) using current market prices
5420 - default valuation commodity (or COMM) using market prices at some date
5421 The TYPE part selects cost or value and valuation date:
5423 --value=then
5425 Convert amounts to their value in the default valuation commod‐
5426 ity, using market prices on each posting's date.
5427 --value=end
5429 Convert amounts to their value in the default valuation commod‐
5430 ity, using market prices on the last day of the report period
5431 (or if unspecified, the journal's end date); or in multiperiod
5432 reports, market prices on the last day of each subperiod.
5433 --value=now
5435 Convert amounts to their value in the default valuation commod‐
5436 ity using current market prices (as of when report is gener‐
5437 ated).
5438 --value=YYYY-MM-DD
5440 Convert amounts to their value in the default valuation commod‐
5441 ity using market prices on this date.
5442 To select a different valuation commodity, add the optional ,COMM part:
5444 a comma, then the target commodity's symbol. Eg: --value=now,EUR.
5445 hledger will do its best to convert amounts to this commodity, deducing
5446 market prices as described above.
5447 More valuation examples
5449 Here are some examples showing the effect of --value, as seen with
5450 print:
5451 P 2000-01-01 A 1 B
5453 P 2000-02-01 A 2 B
5454 P 2000-03-01 A 3 B
5455 P 2000-04-01 A 4 B
5456 2000-01-01
5458 (a) 1 A @ 5 B
5459 2000-02-01
5461 (a) 1 A @ 6 B
5462 2000-03-01
5464 (a) 1 A @ 7 B
5465 Show the cost of each posting:
5467 $ hledger -f- print --cost
5469 2000-01-01
5470 (a) 5 B
5471 2000-02-01
5473 (a) 6 B
5474 2000-03-01
5476 (a) 7 B
5477 Show the value as of the last day of the report period (2000-02-29):
5479 $ hledger -f- print --value=end date:2000/01-2000/03
5481 2000-01-01
5482 (a) 2 B
5483 2000-02-01
5485 (a) 2 B
5486 With no report period specified, that shows the value as of the last
5488 day of the journal (2000-03-01):
5489 $ hledger -f- print --value=end
5491 2000-01-01
5492 (a) 3 B
5493 2000-02-01
5495 (a) 3 B
5496 2000-03-01
5498 (a) 3 B
5499 Show the current value (the 2000-04-01 price is still in effect today):
5501 $ hledger -f- print --value=now
5503 2000-01-01
5504 (a) 4 B
5505 2000-02-01
5507 (a) 4 B
5508 2000-03-01
5510 (a) 4 B
5511 Show the value on 2000/01/15:
5513 $ hledger -f- print --value=2000-01-15
5515 2000-01-01
5516 (a) 1 B
5517 2000-02-01
5519 (a) 1 B
5520 2000-03-01
5522 (a) 1 B
5523 You may need to explicitly set a commodity's display style, when re‐
5525 verse prices are used. Eg this output might be surprising:
5526 P 2000-01-01 A 2B
5528 2000-01-01
5530 a 1B
5531 b
5532 $ hledger print -x -X A
5534 2000-01-01
5535 a 0
5536 b 0
5537 Explanation: because there's no amount or commodity directive specify‐
5539 ing a display style for A, 0.5A gets the default style, which shows no
5540 decimal digits. Because the displayed amount looks like zero, the com‐
5541 modity symbol and minus sign are not displayed either. Adding a com‐
5542 modity directive sets a more useful display style for A:
5543 P 2000-01-01 A 2B
5545 commodity 0.00A
5546 2000-01-01
5548 a 1B
5549 b
5550 $ hledger print -X A
5552 2000-01-01
5553 a 0.50A
5554 b -0.50A
5555 Interaction of valuation and queries
5557 When matching postings based on queries in the presence of valuation,
5558 the following happens.
5559 1. The query is separated into two parts:
5561 1. the currency (cur:) or amount (amt:).
5563 2. all other parts.
5565 2. The postings are matched to the currency and amount queries based on
5567 pre-valued amounts.
5568 3. Valuation is applied to the postings.
5570 4. The postings are matched to the other parts of the query based on
5572 post-valued amounts.
5573 See: 1625
5575 Effect of valuation on reports
5577 Here is a reference for how valuation is supposed to affect each part
5578 of hledger's reports (and a glossary). (It's wide, you'll have to
5579 scroll sideways.) It may be useful when troubleshooting. If you find
5580 problems, please report them, ideally with a reproducible example. Re‐
5581 lated: #329, #1083.
5582 Report -B, --cost -V, -X --value=then --value=end --value=DATE,
5584 type --value=now
5585 ────────────────────────────────────────────────────────────────────────────────────────────
5586 print
5587 posting cost value at re‐ value at posting value at re‐ value at
5588 amounts port end or date port or DATE/today
5589 today journal end
5590 balance unchanged unchanged unchanged unchanged unchanged
5591 asser‐
5592 tions/as‐
5593 signments
5594 register
5596 starting cost value at re‐ valued at day value at re‐ value at
5597 balance port or each historical port or DATE/today
5598 (-H) journal end posting was made journal end
5599 starting cost value at day valued at day value at day value at
5600 balance before re‐ each historical before re‐ DATE/today
5601 (-H) with port or posting was made port or
5602 report journal journal
5603 interval start start
5604 posting cost value at re‐ value at posting value at re‐ value at
5605 amounts port or date port or DATE/today
5606 journal end journal end
5607 summary summarised value at pe‐ sum of postings value at pe‐ value at
5608 posting cost riod ends in interval, val‐ riod ends DATE/today
5609 amounts ued at interval
5610 with re‐ start
5611 port in‐
5612 terval
5613 running sum/average sum/average sum/average of sum/average sum/average
5614 total/av‐ of displayed of displayed displayed values of displayed of displayed
5615 erage values values values values
5616 balance
5618 (bs, bse,
5619 cf, is)
5620 balance sums of value at re‐ value at posting value at re‐ value at
5625 changes costs port end or date port or DATE/today of
5626 today of journal end sums of post‐
5627 sums of of sums of ings
5628 postings postings
5629 budget like balance like balance like balance like bal‐ like balance
5630 amounts changes changes changes ances changes
5631 (--bud‐
5632 get)
5633 grand to‐ sum of dis‐ sum of dis‐ sum of displayed sum of dis‐ sum of dis‐
5634 tal played val‐ played val‐ valued played val‐ played values
5635 ues ues ues
5636 balance
5638 (bs, bse,
5639 cf, is)
5640 with re‐
5641 port in‐
5642 terval
5643 starting sums of value at re‐ sums of values of value at re‐ sums of post‐
5644 balances costs of port start postings before port start ings before
5645 (-H) postings be‐ of sums of report start at of sums of report start
5646 fore report all postings respective post‐ all postings
5647 start before re‐ ing dates before re‐
5648 port start port start
5649 balance sums of same as sums of values of balance value at
5650 changes costs of --value=end postings in pe‐ change in DATE/today of
5651 (bal, is, postings in riod at respec‐ each period, sums of post‐
5652 bs period tive posting valued at ings
5653 --change, dates period ends
5654 cf
5655 --change)
5656 end bal‐ sums of same as sums of values of period end value at
5657 ances costs of --value=end postings from be‐ balances, DATE/today of
5658 (bal -H, postings fore period start valued at sums of post‐
5659 is --H, from before to period end at period ends ings
5660 bs, cf) report start respective post‐
5661 to period ing dates
5662 end
5663 budget like balance like balance like balance like bal‐ like balance
5664 amounts changes/end changes/end changes/end bal‐ ances changes/end
5665 (--bud‐ balances balances ances balances
5666 get)
5667 row to‐ sums, aver‐ sums, aver‐ sums, averages of sums, aver‐ sums, aver‐
5668 tals, row ages of dis‐ ages of dis‐ displayed values ages of dis‐ ages of dis‐
5669 averages played val‐ played val‐ played val‐ played values
5670 (-T, -A) ues ues ues
5671 column sums of dis‐ sums of dis‐ sums of displayed sums of dis‐ sums of dis‐
5672 totals played val‐ played val‐ values played val‐ played values
5673 ues ues ues
5674 grand to‐ sum, average sum, average sum, average of sum, average sum, average
5675 tal, of column of column column totals of column of column to‐
5676 grand av‐ totals totals totals tals
5677 erage
5678 --cumulative is omitted to save space, it works like -H but with a zero
5681 starting balance.
5682 Glossary:
5684 cost calculated using price(s) recorded in the transaction(s).
5686 value market value using available market price declarations, or the
5688 unchanged amount if no conversion rate can be found.
5689 report start
5691 the first day of the report period specified with -b or -p or
5692 date:, otherwise today.
5693 report or journal start
5695 the first day of the report period specified with -b or -p or
5696 date:, otherwise the earliest transaction date in the journal,
5697 otherwise today.
5698 report end
5700 the last day of the report period specified with -e or -p or
5701 date:, otherwise today.
5702 report or journal end
5704 the last day of the report period specified with -e or -p or
5705 date:, otherwise the latest transaction date in the journal,
5706 otherwise today.
5707 report interval
5709 a flag (-D/-W/-M/-Q/-Y) or period expression that activates the
5710 report's multi-period mode (whether showing one or many subperi‐
5711 ods).
5712
5714 Commands overview
5715 Here are the built-in commands:
5716 DATA ENTRY
5718 These data entry commands are the only ones which can modify your jour‐
5719 nal file.
5720 • add - add transactions using terminal prompts
5722 • import - add new transactions from other files, eg CSV files
5724 DATA CREATION
5726 • close - generate balance-zeroing/restoring transactions
5727 • rewrite - generate auto postings, like print --auto
5729 DATA MANAGEMENT
5731 • check - check for various kinds of error in the data
5732 • diff - compare account transactions in two journal files
5734 REPORTS, FINANCIAL
5736 • aregister (areg) - show transactions in a particular account
5737 • balancesheet (bs) - show assets, liabilities and net worth
5739 • balancesheetequity (bse) - show assets, liabilities and equity
5741 • cashflow (cf) - show changes in liquid assets
5743 • incomestatement (is) - show revenues and expenses
5745 REPORTS, VERSATILE
5747 • balance (bal) - show balance changes, end balances, budgets, gains..
5748 • print - show transactions or export journal data
5750 • register (reg) - show postings in one or more accounts & running to‐
5752 tal
5753 • roi - show return on investments
5755 REPORTS, BASIC
5757 • accounts - show account names
5758 • activity - show bar charts of posting counts per period
5760 • codes - show transaction codes
5762 • commodities - show commodity/currency symbols
5764 • descriptions - show transaction descriptions
5766 • files - show input file paths
5768 • notes - show note parts of transaction descriptions
5770 • payees - show payee parts of transaction descriptions
5772 • prices - show market prices
5774 • stats - show journal statistics
5776 • tags - show tag names
5778 • test - run self tests
5780 HELP
5782 • help - show the hledger manual with info/man/pager
5783 • demo - show small hledger demos in the terminal
5785 ADD-ONS
5787 And here are some typical add-on commands. Some of these are installed
5788 by the hledger-install script. If installed, they will appear in
5789 hledger's commands list:
5790 • ui - run hledger's terminal UI
5792 • web - run hledger's web UI
5794 • iadd - add transactions using a TUI (currently hard to build)
5796 • interest - generate interest transactions
5798 • stockquotes - download market prices from AlphaVantage
5800 • Scripts and add-ons - check-fancyassertions, edit, fifo, git, move,
5802 pijul, plot, and more..
5803 Next, each command is described in detail, in alphabetical order.
5805 accounts
5807 Show account names.
5808 This command lists account names. By default it shows all known ac‐
5810 counts, either used in transactions or declared with account direc‐
5811 tives.
5812 With query arguments, only matched account names and account names ref‐
5814 erenced by matched postings are shown.
5815 Or it can show just the used accounts (--used/-u), the declared ac‐
5817 counts (--declared/-d), the accounts declared but not used (--unused),
5818 the accounts used but not declared (--undeclared), or the first account
5819 matched by an account name pattern, if any (--find).
5820 It shows a flat list by default. With --tree, it uses indentation to
5822 show the account hierarchy. In flat mode you can add --drop N to omit
5823 the first few account name components. Account names can be depth-
5824 clipped with depth:N or --depth N or -N.
5825 With --types, it also shows each account's type, if it's known. (See
5827 Declaring accounts > Account types.)
5828 With --positions, it also shows the file and line number of each ac‐
5830 count's declaration, if any, and the account's overall declaration or‐
5831 der; these may be useful when troubleshooting account display order.
5832 With --directives, it adds the account keyword, showing valid account
5834 directives which can be pasted into a journal file. This is useful to‐
5835 gether with --undeclared when updating your account declarations to
5836 satisfy hledger check accounts.
5837 The --find flag can be used to look up a single account name, in the
5839 same way that the aregister command does. It returns the alphanumeri‐
5840 cally-first matched account name, or if none can be found, it fails
5841 with a non-zero exit code.
5842 Examples:
5844 $ hledger accounts
5846 assets:bank:checking
5847 assets:bank:saving
5848 assets:cash
5849 expenses:food
5850 expenses:supplies
5851 income:gifts
5852 income:salary
5853 liabilities:debts
5854 $ hledger accounts --undeclared --directives >> $LEDGER_FILE
5856 $ hledger check accounts
5857 activity
5859 Show an ascii barchart of posting counts per interval.
5860 The activity command displays an ascii histogram showing transaction
5862 counts by day, week, month or other reporting interval (by day is the
5863 default). With query arguments, it counts only matched transactions.
5864 Examples:
5866 $ hledger activity --quarterly
5868 2008-01-01 **
5869 2008-04-01 *******
5870 2008-07-01
5871 2008-10-01 **
5872 add
5874 Prompt for transactions and add them to the journal. Any arguments
5875 will be used as default inputs for the first N prompts.
5876 Many hledger users edit their journals directly with a text editor, or
5878 generate them from CSV. For more interactive data entry, there is the
5879 add command, which prompts interactively on the console for new trans‐
5880 actions, and appends them to the main journal file (which should be in
5881 journal format). Existing transactions are not changed. This is one
5882 of the few hledger commands that writes to the journal file (see also
5883 import).
5884 To use it, just run hledger add and follow the prompts. You can add as
5886 many transactions as you like; when you are finished, enter . or press
5887 control-d or control-c to exit.
5888 Features:
5890 • add tries to provide useful defaults, using the most similar (by de‐
5892 scription) recent transaction (filtered by the query, if any) as a
5893 template.
5894 • You can also set the initial defaults with command line arguments.
5896 • Readline-style edit keys can be used during data entry.
5898 • The tab key will auto-complete whenever possible - accounts, pay‐
5900 ees/descriptions, dates (yesterday, today, tomorrow). If the input
5901 area is empty, it will insert the default value.
5902 • If the journal defines a default commodity, it will be added to any
5904 bare numbers entered.
5905 • A parenthesised transaction code may be entered following a date.
5907 • Comments and tags may be entered following a description or amount.
5909 • If you make a mistake, enter < at any prompt to go one step backward.
5911 • Input prompts are displayed in a different colour when the terminal
5913 supports it.
5914 Example (see https://hledger.org/add.html for a detailed tutorial):
5916 $ hledger add
5918 Adding transactions to journal file /src/hledger/examples/sample.journal
5919 Any command line arguments will be used as defaults.
5920 Use tab key to complete, readline keys to edit, enter to accept defaults.
5921 An optional (CODE) may follow transaction dates.
5922 An optional ; COMMENT may follow descriptions or amounts.
5923 If you make a mistake, enter < at any prompt to go one step backward.
5924 To end a transaction, enter . when prompted.
5925 To quit, enter . at a date prompt or press control-d or control-c.
5926 Date [2015/05/22]:
5927 Description: supermarket
5928 Account 1: expenses:food
5929 Amount 1: $10
5930 Account 2: assets:checking
5931 Amount 2 [$-10.0]:
5932 Account 3 (or . or enter to finish this transaction): .
5933 2015/05/22 supermarket
5934 expenses:food $10
5935 assets:checking $-10.0
5936 Save this transaction to the journal ? [y]:
5938 Saved.
5939 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
5940 Date [2015/05/22]: <CTRL-D> $
5941 On Microsoft Windows, the add command makes sure that no part of the
5943 file path ends with a period, as that would cause problems (#1056).
5944 aregister
5946 (areg)
5947 Show the transactions and running historical balance of a single ac‐
5949 count, with each transaction displayed as one line.
5950 aregister shows the overall transactions affecting a particular account
5952 (and any subaccounts). Each report line represents one transaction in
5953 this account. Transactions before the report start date are always in‐
5954 cluded in the running balance (--historical mode is always on).
5955 This is a more "real world", bank-like view than the register command
5957 (which shows individual postings, possibly from multiple accounts, not
5958 necessarily in historical mode). As a quick rule of thumb: - use areg‐
5959 ister for reviewing and reconciling real-world asset/liability accounts
5960 - use register for reviewing detailed revenues/expenses.
5961 aregister requires one argument: the account to report on. You can
5963 write either the full account name, or a case-insensitive regular ex‐
5964 pression which will select the alphabetically first matched account.
5965 When there are multiple matches, the alphabetically-first choice can be
5967 surprising; eg if you have assets:per:checking 1 and assets:biz:check‐
5968 ing 2 accounts, hledger areg checking would select assets:biz:checking
5969 2. It's just a convenience to save typing, so if in doubt, write the
5970 full account name, or a distinctive substring that matches uniquely.
5971 Transactions involving subaccounts of this account will also be shown.
5973 aregister ignores depth limits, so its final total will always match a
5974 balance report with similar arguments.
5975 Any additional arguments form a query which will filter the transac‐
5977 tions shown. Note some queries will disturb the running balance, caus‐
5978 ing it to be different from the account's real-world running balance.
5979 An example: this shows the transactions and historical running balance
5981 during july, in the first account whose name contains "checking":
5982 $ hledger areg checking date:jul
5984 Each aregister line item shows:
5986 • the transaction's date (or the relevant posting's date if different,
5988 see below)
5989 • the names of all the other account(s) involved in this transaction
5991 (probably abbreviated)
5992 • the total change to this account's balance from this transaction
5994 • the account's historical running balance after this transaction.
5996 Transactions making a net change of zero are not shown by default; add
5998 the -E/--empty flag to show them.
5999 For performance reasons, column widths are chosen based on the first
6001 1000 lines; this means unusually wide values in later lines can cause
6002 visual discontinuities as column widths are adjusted. If you want to
6003 ensure perfect alignment, at the cost of more time and memory, use the
6004 --align-all flag.
6005 This command also supports the output destination and output format op‐
6007 tions. The output formats supported are txt, csv, and json.
6008 aregister and custom posting dates
6010 Transactions whose date is outside the report period can still be
6011 shown, if they have a posting to this account dated inside the report
6012 period. (And in this case it's the posting date that is shown.) This
6013 ensures that aregister can show an accurate historical running balance,
6014 matching the one shown by register -H with the same arguments.
6015 To filter strictly by transaction date instead, add the --txn-dates
6017 flag. If you use this flag and some of your postings have custom
6018 dates, it's probably best to assume the running balance is wrong.
6019 balance
6021 (bal)
6022 Show accounts and their balances.
6024 balance is one of hledger's oldest and most versatile commands, for
6026 listing account balances, balance changes, values, value changes and
6027 more, during one time period or many. Generally it shows a table, with
6028 rows representing accounts, and columns representing periods.
6029 Note there are some higher-level variants of the balance command with
6031 convenient defaults, which can be simpler to use: balancesheet, bal‐
6032 ancesheetequity, cashflow and incomestatement. When you need more con‐
6033 trol, then use balance.
6034 balance features
6036 Here's a quick overview of the balance command's features, followed by
6037 more detailed descriptions and examples. Many of these work with the
6038 higher-level commands as well.
6039 balance can show..
6041 • accounts as a list (-l) or a tree (-t)
6043 • optionally depth-limited (-[1-9])
6045 • sorted by declaration order and name, or by amount
6047 ..and their..
6049 • balance changes (the default)
6051 • or actual and planned balance changes (--budget)
6053 • or value of balance changes (-V)
6055 • or change of balance values (--valuechange)
6057 • or unrealised capital gain/loss (--gain)
6059 • or postings count (--count)
6061 ..in..
6063 • one time period (the whole journal period by default)
6065 • or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
6067 ..either..
6069 • per period (the default)
6071 • or accumulated since report start date (--cumulative)
6073 • or accumulated since account creation (--historical/-H)
6075 ..possibly converted to..
6077 • cost (--value=cost[,COMM]/--cost/-B)
6079 • or market value, as of transaction dates (--value=then[,COMM])
6081 • or at period ends (--value=end[,COMM])
6083 • or now (--value=now)
6085 • or at some other date (--value=YYYY-MM-DD)
6087 ..with..
6089 • totals (-T), averages (-A), percentages (-%), inverted sign (--in‐
6091 vert)
6092 • rows and columns swapped (--transpose)
6094 • another field used as account name (--pivot)
6096 • custom-formatted line items (single-period reports only) (--format)
6098 • commodities displayed on the same line or multiple lines (--layout)
6100 This command supports the output destination and output format options,
6102 with output formats txt, csv, json, and (multi-period reports only:)
6103 html. In txt output in a colour-supporting terminal, negative amounts
6104 are shown in red.
6105 The --related/-r flag shows the balance of the other postings in the
6107 transactions of the postings which would normally be shown.
6108 Simple balance report
6110 With no arguments, balance shows a list of all accounts and their
6111 change of balance - ie, the sum of posting amounts, both inflows and
6112 outflows - during the entire period of the journal. ("Simple" here
6113 means just one column of numbers, covering a single period. You can
6114 also have multi-period reports, described later.)
6115 For real-world accounts, these numbers will normally be their end bal‐
6117 ance at the end of the journal period; more on this below.
6118 Accounts are sorted by declaration order if any, and then alphabeti‐
6120 cally by account name. For instance (using examples/sample.journal):
6121 $ hledger -f examples/sample.journal bal
6123 $1 assets:bank:saving
6124 $-2 assets:cash
6125 $1 expenses:food
6126 $1 expenses:supplies
6127 $-1 income:gifts
6128 $-1 income:salary
6129 $1 liabilities:debts
6130 --------------------
6131 0
6132 Accounts with a zero balance (and no non-zero subaccounts, in tree mode
6134 - see below) are hidden by default. Use -E/--empty to show them (re‐
6135 vealing assets:bank:checking here):
6136 $ hledger -f examples/sample.journal bal -E
6138 0 assets:bank:checking
6139 $1 assets:bank:saving
6140 $-2 assets:cash
6141 $1 expenses:food
6142 $1 expenses:supplies
6143 $-1 income:gifts
6144 $-1 income:salary
6145 $1 liabilities:debts
6146 --------------------
6147 0
6148 The total of the amounts displayed is shown as the last line, unless
6150 -N/--no-total is used.
6151 Balance report line format
6153 For single-period balance reports displayed in the terminal (only), you
6154 can use --format FMT to customise the format and content of each line.
6155 Eg:
6156 $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
6158 assets $-1
6159 bank:saving $1
6160 cash $-2
6161 expenses $2
6162 food $1
6163 supplies $1
6164 income $-2
6165 gifts $-1
6166 salary $-1
6167 liabilities:debts $1
6168 ---------------------------------
6169 0
6170 The FMT format string specifies the formatting applied to each ac‐
6172 count/balance pair. It may contain any suitable text, with data fields
6173 interpolated like so:
6174 %[MIN][.MAX](FIELDNAME)
6176 • MIN pads with spaces to at least this width (optional)
6178 • MAX truncates at this width (optional)
6180 • FIELDNAME must be enclosed in parentheses, and can be one of:
6182 • depth_spacer - a number of spaces equal to the account's depth, or
6184 if MIN is specified, MIN * depth spaces.
6185 • account - the account's name
6187 • total - the account's balance/posted total, right justified
6189 Also, FMT can begin with an optional prefix to control how multi-com‐
6191 modity amounts are rendered:
6192 • %_ - render on multiple lines, bottom-aligned (the default)
6194 • %^ - render on multiple lines, top-aligned
6196 • %, - render on one line, comma-separated
6198 There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef‐
6200 fect, instead %(account) has indentation built in. Experimentation may
6201 be needed to get pleasing results.
6202 Some example formats:
6204 • %(total) - the account's total
6206 • %-20.20(account) - the account's name, left justified, padded to 20
6208 characters and clipped at 20 characters
6209 • %,%-50(account) %25(total) - account name padded to 50 characters,
6211 total padded to 20 characters, with multiple commodities rendered on
6212 one line
6213 • %20(total) %2(depth_spacer)%-(account) - the default format for the
6215 single-column balance report
6216 Filtered balance report
6218 You can show fewer accounts, a different time period, totals from
6219 cleared transactions only, etc. by using query arguments or options to
6220 limit the postings being matched. Eg:
6221 $ hledger -f examples/sample.journal bal --cleared assets date:200806
6223 $-2 assets:cash
6224 --------------------
6225 $-2
6226 List or tree mode
6228 By default, or with -l/--flat, accounts are shown as a flat list with
6229 their full names visible, as in the examples above.
6230 With -t/--tree, the account hierarchy is shown, with subaccounts'
6232 "leaf" names indented below their parent:
6233 $ hledger -f examples/sample.journal balance
6235 $-1 assets
6236 $1 bank:saving
6237 $-2 cash
6238 $2 expenses
6239 $1 food
6240 $1 supplies
6241 $-2 income
6242 $-1 gifts
6243 $-1 salary
6244 $1 liabilities:debts
6245 --------------------
6246 0
6247 Notes:
6249 • "Boring" accounts are combined with their subaccount for more compact
6251 output, unless --no-elide is used. Boring accounts have no balance
6252 of their own and just one subaccount (eg assets:bank and liabilities
6253 above).
6254 • All balances shown are "inclusive", ie including the balances from
6256 all subaccounts. Note this means some repetition in the output,
6257 which requires explanation when sharing reports with non-plaintextac‐
6258 counting-users. A tree mode report's final total is the sum of the
6259 top-level balances shown, not of all the balances shown.
6260 • Each group of sibling accounts (ie, under a common parent) is sorted
6262 separately.
6263 Depth limiting
6265 With a depth:NUM query, or --depth NUM option, or just -NUM (eg: -3)
6266 balance reports will show accounts only to the specified depth, hiding
6267 the deeper subaccounts. This can be useful for getting an overview
6268 without too much detail.
6269 Account balances at the depth limit always include the balances from
6271 any deeper subaccounts (even in list mode). Eg, limiting to depth 1:
6272 $ hledger -f examples/sample.journal balance -1
6274 $-1 assets
6275 $2 expenses
6276 $-2 income
6277 $1 liabilities
6278 --------------------
6279 0
6280 Dropping top-level accounts
6282 You can also hide one or more top-level account name parts, using
6283 --drop NUM. This can be useful for hiding repetitive top-level account
6284 names:
6285 $ hledger -f examples/sample.journal bal expenses --drop 1
6287 $1 food
6288 $1 supplies
6289 --------------------
6290 $2
6291 Showing declared accounts
6293 With --declared, accounts which have been declared with an account di‐
6294 rective will be included in the balance report, even if they have no
6295 transactions. (Since they will have a zero balance, you will also need
6296 -E/--empty to see them.)
6297 More precisely, leaf declared accounts (with no subaccounts) will be
6299 included, since those are usually the more useful in reports.
6300 The idea of this is to be able to see a useful "complete" balance re‐
6302 port, even when you don't have transactions in all of your declared ac‐
6303 counts yet.
6304 Sorting by amount
6306 With -S/--sort-amount, accounts with the largest (most positive) bal‐
6307 ances are shown first. Eg: hledger bal expenses -MAS shows your big‐
6308 gest averaged monthly expenses first. When more than one commodity is
6309 present, they will be sorted by the alphabetically earliest commodity
6310 first, and then by subsequent commodities (if an amount is missing a
6311 commodity, it is treated as 0).
6312 Revenues and liability balances are typically negative, however, so -S
6314 shows these in reverse order. To work around this, you can add --in‐
6315 vert to flip the signs. (Or, use one of the higher-level reports,
6316 which flip the sign automatically. Eg: hledger incomestatement -MAS).
6317 Percentages
6319 With -%/--percent, balance reports show each account's value expressed
6320 as a percentage of the (column) total.
6321 Note it is not useful to calculate percentages if the amounts in a col‐
6323 umn have mixed signs. In this case, make a separate report for each
6324 sign, eg:
6325 $ hledger bal -% amt:`>0`
6327 $ hledger bal -% amt:`<0`
6328 Similarly, if the amounts in a column have mixed commodities, convert
6330 them to one commodity with -B, -V, -X or --value, or make a separate
6331 report for each commodity:
6332 $ hledger bal -% cur:\\$
6334 $ hledger bal -% cur:€
6335 Multi-period balance report
6337 With a report interval (set by the -D/--daily, -W/--weekly,
6338 -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), bal‐
6339 ance shows a tabular report, with columns representing successive time
6340 periods (and a title):
6341 $ hledger -f examples/sample.journal bal --quarterly income expenses -E
6343 Balance changes in 2008:
6344 || 2008q1 2008q2 2008q3 2008q4
6346 ===================++=================================
6347 expenses:food || 0 $1 0 0
6348 expenses:supplies || 0 $1 0 0
6349 income:gifts || 0 $-1 0 0
6350 income:salary || $-1 0 0 0
6351 -------------------++---------------------------------
6352 || $-1 $1 0 0
6353 Notes:
6355 • The report's start/end dates will be expanded, if necessary, to fully
6357 encompass the displayed subperiods (so that the first and last subpe‐
6358 riods have the same duration as the others).
6359 • Leading and trailing periods (columns) containing all zeroes are not
6361 shown, unless -E/--empty is used.
6362 • Accounts (rows) containing all zeroes are not shown, unless
6364 -E/--empty is used.
6365 • Amounts with many commodities are shown in abbreviated form, unless
6367 --no-elide is used. (experimental)
6368 • Average and/or total columns can be added with the -A/--average and
6370 -T/--row-total flags.
6371 • The --transpose flag can be used to exchange rows and columns.
6373 • The --pivot FIELD option causes a different transaction field to be
6375 used as "account name". See PIVOTING.
6376 Multi-period reports with many periods can be too wide for easy viewing
6378 in the terminal. Here are some ways to handle that:
6379 • Hide the totals row with -N/--no-total
6381 • Convert to a single currency with -V
6383 • Maximize the terminal window
6385 • Reduce the terminal's font size
6387 • View with a pager like less, eg: hledger bal -D --color=yes | less
6389 -RS
6390 • Output as CSV and use a CSV viewer like visidata (hledger bal -D -O
6392 csv | vd -f csv), Emacs' csv-mode (M-x csv-mode, C-c C-a), or a
6393 spreadsheet (hledger bal -D -o a.csv && open a.csv)
6394 • Output as HTML and view with a browser: hledger bal -D -o a.html &&
6396 open a.html
6397 Balance change, end balance
6399 It's important to be clear on the meaning of the numbers shown in bal‐
6400 ance reports. Here is some terminology we use:
6401 A balance change is the net amount added to, or removed from, an ac‐
6403 count during some period.
6404 An end balance is the amount accumulated in an account as of some date
6406 (and some time, but hledger doesn't store that; assume end of day in
6407 your timezone). It is the sum of previous balance changes.
6408 We call it a historical end balance if it includes all balance changes
6410 since the account was created. For a real world account, this means it
6411 will match the "historical record", eg the balances reported in your
6412 bank statements or bank web UI. (If they are correct!)
6413 In general, balance changes are what you want to see when reviewing
6415 revenues and expenses, and historical end balances are what you want to
6416 see when reviewing or reconciling asset, liability and equity accounts.
6417 balance shows balance changes by default. To see accurate historical
6419 end balances:
6420 1. Initialise account starting balances with an "opening balances"
6422 transaction (a transfer from equity to the account), unless the
6423 journal covers the account's full lifetime.
6424 2. Include all of of the account's prior postings in the report, by not
6426 specifying a report start date, or by using the -H/--historical
6427 flag. (-H causes report start date to be ignored when summing post‐
6428 ings.)
6429 Balance report types
6431 The balance command is quite flexible; here is the full detail on how
6432 to control what it reports. If the following seems complicated, don't
6433 worry - this is for advanced reporting, and it does take time and ex‐
6434 perimentation to get familiar with all the report modes.
6435 There are three important option groups:
6437 hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]
6439 ...
6440 Calculation type
6442 The basic calculation to perform for each table cell. It is one of:
6443 • --sum : sum the posting amounts (default)
6445 • --budget : sum the amounts, but also show the budget goal amount (for
6447 each account/period)
6448 • --valuechange : show the change in period-end historical balance val‐
6450 ues (caused by deposits, withdrawals, and/or market price fluctua‐
6451 tions)
6452 • --gain : show the unrealised capital gain/loss, (the current valued
6454 balance minus each amount's original cost)
6455 • --count : show the count of postings
6457 Accumulation type
6459 How amounts should accumulate across report periods. Another way to
6460 say it: which time period's postings should contribute to each cell's
6461 calculation. It is one of:
6462 • --change : calculate with postings from column start to column end,
6464 ie "just this column". Typically used to see revenues/expenses.
6465 (default for balance, incomestatement)
6466 • --cumulative : calculate with postings from report start to column
6468 end, ie "previous columns plus this column". Typically used to show
6469 changes accumulated since the report's start date. Not often used.
6470 • --historical/-H : calculate with postings from journal start to col‐
6472 umn end, ie "all postings from before report start date until this
6473 column's end". Typically used to see historical end balances of as‐
6474 sets/liabilities/equity. (default for balancesheet, balancesheete‐
6475 quity, cashflow)
6476 Valuation type
6478 Which kind of value or cost conversion should be applied, if any, be‐
6479 fore displaying the report. It is one of:
6480 • no valuation type : don't convert to cost or value (default)
6482 • --value=cost[,COMM] : convert amounts to cost (then optionally to
6484 some other commodity)
6485 • --value=then[,COMM] : convert amounts to market value on transaction
6487 dates
6488 • --value=end[,COMM] : convert amounts to market value on period end
6490 date(s)
6491 (default with --valuechange, --gain)
6492 • --value=now[,COMM] : convert amounts to market value on today's date
6494 • --value=YYYY-MM-DD[,COMM] : convert amounts to market value on an‐
6496 other date
6497 or one of the equivalent simpler flags:
6499 • -B/--cost : like --value=cost (though, note --cost and --value are
6501 independent options which can both be used at once)
6502 • -V/--market : like --value=end
6504 • -X COMM/--exchange COMM : like --value=end,COMM
6506 See Cost reporting and Valuation for more about these.
6508 Combining balance report types
6510 Most combinations of these options should produce reasonable reports,
6511 but if you find any that seem wrong or misleading, let us know. The
6512 following restrictions are applied:
6513 • --valuechange implies --value=end
6515 • --valuechange makes --change the default when used with the bal‐
6517 ancesheet/balancesheetequity commands
6518 • --cumulative or --historical disables --row-total/-T
6520 For reference, here is what the combinations of accumulation and valua‐
6522 tion show:
6523 Valua‐ no valuation --value= then --value= end --value= YYYY-
6525 tion:> MM-DD /now
6526 Accumu‐
6527 lation:v
6528 ───────────────────────────────────────────────────────────────────────────────────
6529 --change change in period sum of posting- period-end DATE-value of
6530 date market val‐ value of change change in pe‐
6531 ues in period in period riod
6532 --cumu‐ change from re‐ sum of posting- period-end DATE-value of
6533 lative port start to date market val‐ value of change change from
6534 period end ues from report from report report start
6535 start to period start to period to period end
6536 end end
6537 --his‐ change from sum of posting- period-end DATE-value of
6541 torical journal start to date market val‐ value of change change from
6542 /-H period end (his‐ ues from journal from journal journal start
6543 torical end bal‐ start to period start to period to period end
6544 ance) end end
6545 Budget report
6547 The --budget report type activates extra columns showing any budget
6548 goals for each account and period. The budget goals are defined by pe‐
6549 riodic transactions. This is useful for comparing planned and actual
6550 income, expenses, time usage, etc.
6551 For example, you can take average monthly expenses in the common ex‐
6553 pense categories to construct a minimal monthly budget:
6554 ;; Budget
6556 ~ monthly
6557 income $2000
6558 expenses:food $400
6559 expenses:bus $50
6560 expenses:movies $30
6561 assets:bank:checking
6562 ;; Two months worth of expenses
6564 2017-11-01
6565 income $1950
6566 expenses:food $396
6567 expenses:bus $49
6568 expenses:movies $30
6569 expenses:supplies $20
6570 assets:bank:checking
6571 2017-12-01
6573 income $2100
6574 expenses:food $412
6575 expenses:bus $53
6576 expenses:gifts $100
6577 assets:bank:checking
6578 You can now see a monthly budget report:
6580 $ hledger balance -M --budget
6582 Budget performance in 2017/11/01-2017/12/31:
6583 || Nov Dec
6585 ======================++====================================================
6586 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
6587 assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
6588 assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
6589 expenses || $495 [ 103% of $480] $565 [ 118% of $480]
6590 expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
6591 expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
6592 expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
6593 income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
6594 ----------------------++----------------------------------------------------
6595 || 0 [ 0] 0 [ 0]
6596 This is different from a normal balance report in several ways. Cur‐
6598 rently:
6599 • Accounts with budget goals during the report period, and their par‐
6601 ents, are shown.
6602 • Their subaccounts are not shown (regardless of the depth setting).
6604 • Accounts without budget goals, if any, are aggregated and shown as
6606 "<unbudgeted>".
6607 • Amounts are always inclusive (subaccount-including), even in list
6609 mode.
6610 • After each actual amount, the corresponding goal amount and percent‐
6612 age of goal reached are also shown, in square brackets.
6613 This means that the numbers displayed will not always add up! Eg
6615 above, the expenses actual amount includes the gifts and supplies
6616 transactions, but the expenses:gifts and expenses:supplies accounts are
6617 not shown, as they have no budget amounts declared.
6618 This can be confusing. When you need to make things clearer, use the
6620 -E/--empty flag, which will reveal all accounts including unbudgeted
6621 ones, giving the full picture. Eg:
6622 $ hledger balance -M --budget --empty
6624 Budget performance in 2017/11/01-2017/12/31:
6625 || Nov Dec
6627 ======================++====================================================
6628 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
6629 assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
6630 assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
6631 expenses || $495 [ 103% of $480] $565 [ 118% of $480]
6632 expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
6633 expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
6634 expenses:gifts || 0 $100
6635 expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
6636 expenses:supplies || $20 0
6637 income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
6638 ----------------------++----------------------------------------------------
6639 || 0 [ 0] 0 [ 0]
6640 You can roll over unspent budgets to next period with --cumulative:
6642 $ hledger balance -M --budget --cumulative
6644 Budget performance in 2017/11/01-2017/12/31:
6645 || Nov Dec
6647 ======================++====================================================
6648 assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
6649 assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
6650 assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
6651 expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
6652 expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
6653 expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
6654 expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
6655 income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
6656 ----------------------++----------------------------------------------------
6657 || 0 [ 0] 0 [ 0]
6658 It's common to limit budgets/budget reports to just expenses
6660 hledger bal -M --budget expenses
6662 or just revenues and expenses (eg, using account types):
6664 hledger bal -M --budget type:rx
6666 It's also common to limit or convert them to a single currency
6668 (cur:COMM or -X COMM [--infer-market-prices]). If showing multiple
6669 currencies, --layout bare or --layout tall can help.
6670 For more examples and notes, see Budgeting.
6672 Budget report start date
6674 This might be a bug, but for now: when making budget reports, it's a
6675 good idea to explicitly set the report's start date to the first day of
6676 a reporting period, because a periodic rule like ~ monthly generates
6677 its transactions on the 1st of each month, and if your journal has no
6678 regular transactions on the 1st, the default report start date could
6679 exclude that budget goal, which can be a little surprising. Eg here
6680 the default report period is just the day of 2020-01-15:
6681 ~ monthly in 2020
6683 (expenses:food) $500
6684 2020-01-15
6686 expenses:food $400
6687 assets:checking
6688 $ hledger bal expenses --budget
6690 Budget performance in 2020-01-15:
6691 || 2020-01-15
6693 ==============++============
6694 <unbudgeted> || $400
6695 --------------++------------
6696 || $400
6697 To avoid this, specify the budget report's period, or at least the
6699 start date, with -b/-e/-p/date:, to ensure it includes the budget goal
6700 transactions (periodic transactions) that you want. Eg, adding -b
6701 2020/1/1 to the above:
6702 $ hledger bal expenses --budget -b 2020/1/1
6704 Budget performance in 2020-01-01..2020-01-15:
6705 || 2020-01-01..2020-01-15
6707 ===============++========================
6708 expenses:food || $400 [80% of $500]
6709 ---------------++------------------------
6710 || $400 [80% of $500]
6711 Budgets and subaccounts
6713 You can add budgets to any account in your account hierarchy. If you
6714 have budgets on both parent account and some of its children, then bud‐
6715 get(s) of the child account(s) would be added to the budget of their
6716 parent, much like account balances behave.
6717 In the most simple case this means that once you add a budget to any
6719 account, all its parents would have budget as well.
6720 To illustrate this, consider the following budget:
6722 ~ monthly from 2019/01
6724 expenses:personal $1,000.00
6725 expenses:personal:electronics $100.00
6726 liabilities
6727 With this, monthly budget for electronics is defined to be $100 and
6729 budget for personal expenses is an additional $1000, which implicitly
6730 means that budget for both expenses:personal and expenses is $1100.
6731 Transactions in expenses:personal:electronics will be counted both to‐
6733 wards its $100 budget and $1100 of expenses:personal , and transactions
6734 in any other subaccount of expenses:personal would be counted towards
6735 only towards the budget of expenses:personal.
6736 For example, let's consider these transactions:
6738 ~ monthly from 2019/01
6740 expenses:personal $1,000.00
6741 expenses:personal:electronics $100.00
6742 liabilities
6743 2019/01/01 Google home hub
6745 expenses:personal:electronics $90.00
6746 liabilities $-90.00
6747 2019/01/02 Phone screen protector
6749 expenses:personal:electronics:upgrades $10.00
6750 liabilities
6751 2019/01/02 Weekly train ticket
6753 expenses:personal:train tickets $153.00
6754 liabilities
6755 2019/01/03 Flowers
6757 expenses:personal $30.00
6758 liabilities
6759 As you can see, we have transactions in expenses:personal:electron‐
6761 ics:upgrades and expenses:personal:train tickets, and since both of
6762 these accounts are without explicitly defined budget, these transac‐
6763 tions would be counted towards budgets of expenses:personal:electronics
6764 and expenses:personal accordingly:
6765 $ hledger balance --budget -M
6767 Budget performance in 2019/01:
6768 || Jan
6770 ===============================++===============================
6771 expenses || $283.00 [ 26% of $1100.00]
6772 expenses:personal || $283.00 [ 26% of $1100.00]
6773 expenses:personal:electronics || $100.00 [ 100% of $100.00]
6774 liabilities || $-283.00 [ 26% of $-1100.00]
6775 -------------------------------++-------------------------------
6776 || 0 [ 0]
6777 And with --empty, we can get a better picture of budget allocation and
6779 consumption:
6780 $ hledger balance --budget -M --empty
6782 Budget performance in 2019/01:
6783 || Jan
6785 ========================================++===============================
6786 expenses || $283.00 [ 26% of $1100.00]
6787 expenses:personal || $283.00 [ 26% of $1100.00]
6788 expenses:personal:electronics || $100.00 [ 100% of $100.00]
6789 expenses:personal:electronics:upgrades || $10.00
6790 expenses:personal:train tickets || $153.00
6791 liabilities || $-283.00 [ 26% of $-1100.00]
6792 ----------------------------------------++-------------------------------
6793 || 0 [ 0]
6794 Selecting budget goals
6796 The budget report evaluates periodic transaction rules to generate spe‐
6797 cial "goal transactions", which generate the goal amounts for each ac‐
6798 count in each report subperiod. When troubleshooting, you can use
6799 print --forecast to show these as forecasted transactions:
6800 $ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
6802 By default, the budget report uses all available periodic transaction
6804 rules to generate goals. This includes rules with a different report
6805 interval from your report. Eg if you have daily, weekly and monthly
6806 periodic rules, all of these will contribute to the goals in a monthly
6807 budget report.
6808 You can select a subset of periodic rules by providing an argument to
6810 the --budget flag. --budget=DESCPAT will match all periodic rules
6811 whose description contains DESCPAT, a case-insensitive substring (not a
6812 regular expression or query). This means you can give your periodic
6813 rules descriptions (remember that two spaces are needed), and then se‐
6814 lect from multiple budgets defined in your journal.
6815 Budget vs forecast
6817 hledger --forecast ... and hledger balance --budget ... are separate
6818 features, though both of them use the periodic transaction rules de‐
6819 fined in the journal, and both of them generate temporary transactions
6820 for reporting purposes ("forecast transactions" and "budget goal trans‐
6821 actions", respectively). You can use both features at the same time if
6822 you want. Here are some differences between them, as of hledger 1.29:
6823 CLI:
6825 • --forecast is a general hledger option, usable with any command
6827 • --budget is a balance command option, usable only with that command.
6829 Visibility of generated transactions:
6831 • forecast transactions are visible in any report, like ordinary trans‐
6833 actions
6834 • budget goal transactions are invisible except for the goal amounts
6836 they produce in --budget reports.
6837 Periodic transaction rules:
6839 • --forecast uses all available periodic transaction rules
6841 • --budget uses all periodic rules (--budget) or a selected subset
6843 (--budget=DESCPAT)
6844 Period of generated transactions:
6846 • --forecast generates forecast transactions
6848 • from after the last regular transaction to the end of the report
6850 period (--forecast)
6851 • or, during a specified period (--forecast=PERIODEXPR)
6853 • possibly further restricted by a period specified in the periodic
6855 transaction rule
6856 • and always restricted within the bounds of the report period
6858 • --budget generates budget goal transactions
6860 • throughout the report period
6862 • possibly restricted by a period specified in the periodic transac‐
6864 tion rule.
6865 Data layout
6867 The --layout option affects how balance reports show multi-commodity
6868 amounts and commodity symbols, which can improve readability. It can
6869 also normalise the data for easy consumption by other programs. It has
6870 four possible values:
6871 • --layout=wide[,WIDTH]: commodities are shown on a single line, op‐
6873 tionally elided to WIDTH
6874 • --layout=tall: each commodity is shown on a separate line
6876 • --layout=bare: commodity symbols are in their own column, amounts are
6878 bare numbers
6879 • --layout=tidy: data is normalised to easily-consumed "tidy" form,
6881 with one row per data value
6882 Here are the --layout modes supported by each output format; note only
6884 CSV output supports all of them:
6885 - txt csv html json sql
6887 ─────────────────────────────────────
6888 wide Y Y Y
6889 tall Y Y Y
6890 bare Y Y Y
6891 tidy Y
6892 Examples:
6894 • Wide layout. With many commodities, reports can be very wide:
6896 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
6898 Balance changes in 2012-01-01..2014-12-31:
6899 || 2012 2013 2014 Total
6901 ==================++====================================================================================================================================================================================================================
6902 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
6903 ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
6904 || 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
6905 • Limited wide layout. A width limit reduces the width, but some com‐
6907 modities will be hidden:
6908 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
6910 Balance changes in 2012-01-01..2014-12-31:
6911 || 2012 2013 2014 Total
6913 ==================++===========================================================================================================================
6914 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..
6915 ------------------++---------------------------------------------------------------------------------------------------------------------------
6916 || 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..
6917 • Tall layout. Each commodity gets a new line (may be different in
6919 each column), and account names are repeated:
6920 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall
6922 Balance changes in 2012-01-01..2014-12-31:
6923 || 2012 2013 2014 Total
6925 ==================++==================================================
6926 Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
6927 Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
6928 Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD
6929 Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
6930 Assets:US:ETrade || 18.00 VHT 294.00 VHT
6931 ------------------++--------------------------------------------------
6932 || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
6933 || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
6934 || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD
6935 || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
6936 || 18.00 VHT 294.00 VHT
6937 • Bare layout. Commodity symbols are kept in one column, each commod‐
6939 ity gets its own report row, account names are repeated:
6940 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare
6942 Balance changes in 2012-01-01..2014-12-31:
6943 || Commodity 2012 2013 2014 Total
6945 ==================++=============================================
6946 Assets:US:ETrade || GLD 0 70.00 0 70.00
6947 Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00
6948 Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50
6949 Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00
6950 Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00
6951 ------------------++---------------------------------------------
6952 || GLD 0 70.00 0 70.00
6953 || ITOT 10.00 18.00 -11.00 17.00
6954 || USD 337.18 -98.12 4881.44 5120.50
6955 || VEA 12.00 10.00 14.00 36.00
6956 || VHT 106.00 18.00 170.00 294.00
6957 • Bare layout also affects CSV output, which is useful for producing
6959 data that is easier to consume, eg for making charts:
6960 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
6962 "account","commodity","balance"
6963 "Assets:US:ETrade","GLD","70.00"
6964 "Assets:US:ETrade","ITOT","17.00"
6965 "Assets:US:ETrade","USD","5120.50"
6966 "Assets:US:ETrade","VEA","36.00"
6967 "Assets:US:ETrade","VHT","294.00"
6968 "total","GLD","70.00"
6969 "total","ITOT","17.00"
6970 "total","USD","5120.50"
6971 "total","VEA","36.00"
6972 "total","VHT","294.00"
6973 • Tidy layout produces normalised "tidy data", where every variable has
6975 its own column and each row represents a single data point. See
6976 https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-
6977 data.html for more. This is the easiest kind of data for other soft‐
6978 ware to consume. Here's how it looks:
6979 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
6981 "account","period","start_date","end_date","commodity","value"
6982 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"
6983 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"
6984 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"
6985 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"
6986 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"
6987 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"
6988 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"
6989 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"
6990 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"
6991 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"
6992 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"
6993 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"
6994 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"
6995 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
6996 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
6997 Useful balance reports
6999 Some frequently used balance options/reports are:
7000 • bal -M revenues expenses
7002 Show revenues/expenses in each month. Also available as the incomes‐
7003 tatement command.
7004 • bal -M -H assets liabilities
7006 Show historical asset/liability balances at each month end. Also
7007 available as the balancesheet command.
7008 • bal -M -H assets liabilities equity
7010 Show historical asset/liability/equity balances at each month end.
7011 Also available as the balancesheetequity command.
7012 • bal -M assets not:receivable
7014 Show changes to liquid assets in each month. Also available as the
7015 cashflow command.
7016 Also:
7018 • bal -M expenses -2 -SA
7020 Show monthly expenses summarised to depth 2 and sorted by average
7021 amount.
7022 • bal -M --budget expenses
7024 Show monthly expenses and budget goals.
7025 • bal -M --valuechange investments
7027 Show monthly change in market value of investment assets.
7028 • bal investments --valuechange -D date:lastweek amt:'>1000' -STA
7030 [--invert]
7031 Show top gainers [or losers] last week
7032 balancesheet
7034 (bs)
7035 This command displays a balance sheet, showing historical ending bal‐
7037 ances of asset and liability accounts. (To see equity as well, use the
7038 balancesheetequity command.) Amounts are shown with normal positive
7039 sign, as in conventional financial statements.
7040 This report shows accounts declared with the Asset, Cash or Liability
7042 type (see account types). Or if no such accounts are declared, it
7043 shows top-level accounts named asset or liability (case insensitive,
7044 plurals allowed) and their subaccounts.
7045 Example:
7047 $ hledger balancesheet
7049 Balance Sheet
7050 Assets:
7052 $-1 assets
7053 $1 bank:saving
7054 $-2 cash
7055 --------------------
7056 $-1
7057 Liabilities:
7059 $1 liabilities:debts
7060 --------------------
7061 $1
7062 Total:
7064 --------------------
7065 0
7066 This command is a higher-level variant of the balance command, and sup‐
7068 ports many of that command's features, such as multi-period reports.
7069 It is similar to hledger balance -H assets liabilities, but with
7070 smarter account detection, and liabilities displayed with their sign
7071 flipped.
7072 This command also supports the output destination and output format op‐
7074 tions The output formats supported are txt, csv, html, and (experimen‐
7075 tal) json.
7076 balancesheetequity
7078 (bse)
7079 This command displays a balance sheet, showing historical ending bal‐
7081 ances of asset, liability and equity accounts. Amounts are shown with
7082 normal positive sign, as in conventional financial statements.
7083 This report shows accounts declared with the Asset, Cash, Liability or
7085 Equity type (see account types). Or if no such accounts are declared,
7086 it shows top-level accounts named asset, liability or equity (case in‐
7087 sensitive, plurals allowed) and their subaccounts.
7088 Example:
7090 $ hledger balancesheetequity
7092 Balance Sheet With Equity
7093 Assets:
7095 $-2 assets
7096 $1 bank:saving
7097 $-3 cash
7098 --------------------
7099 $-2
7100 Liabilities:
7102 $1 liabilities:debts
7103 --------------------
7104 $1
7105 Equity:
7107 $1 equity:owner
7108 --------------------
7109 $1
7110 Total:
7112 --------------------
7113 0
7114 This command is a higher-level variant of the balance command, and sup‐
7116 ports many of that command's features, such as multi-period reports.
7117 It is similar to hledger balance -H assets liabilities equity, but with
7118 smarter account detection, and liabilities/equity displayed with their
7119 sign flipped.
7120 This command also supports the output destination and output format op‐
7122 tions The output formats supported are txt, csv, html, and (experimen‐
7123 tal) json.
7124 cashflow
7126 (cf)
7127 This command displays a cashflow statement, showing the inflows and
7129 outflows affecting "cash" (ie, liquid, easily convertible) assets.
7130 Amounts are shown with normal positive sign, as in conventional finan‐
7131 cial statements.
7132 This report shows accounts declared with the Cash type (see account
7134 types). Or if no such accounts are declared, it shows accounts
7135 • under a top-level account named asset (case insensitive, plural al‐
7137 lowed)
7138 • whose name contains some variation of cash, bank, checking or saving.
7140 More precisely: all accounts matching this case insensitive regular ex‐
7142 pression:
7143 ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)
7145 and their subaccounts.
7147 An example cashflow report:
7149 $ hledger cashflow
7151 Cashflow Statement
7152 Cash flows:
7154 $-1 assets
7155 $1 bank:saving
7156 $-2 cash
7157 --------------------
7158 $-1
7159 Total:
7161 --------------------
7162 $-1
7163 This command is a higher-level variant of the balance command, and sup‐
7165 ports many of that command's features, such as multi-period reports.
7166 It is similar to hledger balance assets not:fixed not:investment
7167 not:receivable, but with smarter account detection.
7168 This command also supports the output destination and output format op‐
7170 tions The output formats supported are txt, csv, html, and (experimen‐
7171 tal) json.
7172 check
7174 Check for various kinds of errors in your data.
7175 hledger provides a number of built-in error checks to help prevent
7177 problems in your data. Some of these are run automatically; or, you
7178 can use this check command to run them on demand, with no output and a
7179 zero exit code if all is well. Specify their names (or a prefix) as
7180 argument(s).
7181 Some examples:
7183 hledger check # basic checks
7185 hledger check -s # basic + strict checks
7186 hledger check ordereddates payees # basic + two other checks
7187 If you are an Emacs user, you can also configure flycheck-hledger to
7189 run these checks, providing instant feedback as you edit the journal.
7190 Here are the checks currently available:
7192 Basic checks
7194 These checks are always run automatically, by (almost) all hledger com‐
7195 mands, including check:
7196 • parseable - data files are well-formed and can be successfully parsed
7198 • balancedwithautoconversion - all transactions are balanced, inferring
7200 missing amounts where necessary, and possibly converting commodities
7201 using costs or automatically-inferred costs
7202 • assertions - all balance assertions in the journal are passing.
7204 (This check can be disabled with -I/--ignore-assertions.)
7205 Strict checks
7207 These additional checks are run when the -s/--strict (strict mode) flag
7208 is used. Or, they can be run by giving their names as arguments to
7209 check:
7210 • accounts - all account names used by transactions have been declared
7212 • commodities - all commodity symbols used have been declared
7214 • balancednoautoconversion - transactions are balanced, possibly using
7216 explicit costs but not inferred ones
7217 Other checks
7219 These checks can be run only by giving their names as arguments to
7220 check. They are more specialised and not desirable for everyone,
7221 therefore optional:
7222 • ordereddates - transactions are ordered by date within each file
7224 • payees - all payees used by transactions have been declared
7226 • recentassertions - all accounts with balance assertions have a bal‐
7228 ance assertion no more than 7 days before their latest posting
7229 • tags - all tags used by transactions have been declared
7231 • uniqueleafnames - all account leaf names are unique
7233 Custom checks
7235 A few more checks are are available as separate add-on commands, in
7236 https://github.com/simonmichael/hledger/tree/master/bin:
7237 • hledger-check-tagfiles - all tag values containing / (a forward
7239 slash) exist as file paths
7240 • hledger-check-fancyassertions - more complex balance assertions are
7242 passing
7243 You could make similar scripts to perform your own custom checks. See:
7245 Cookbook -> Scripting.
7246 More about specific checks
7248 hledger check recentassertions will complain if any balance-asserted
7249 account does not have a balance assertion within 7 days before its lat‐
7250 est posting. This aims to prevent the situation where you are regu‐
7251 larly updating your journal, but forgetting to check your balances
7252 against the real world, then one day must dig back through months of
7253 data to find an error. It assumes that adding a balance assertion re‐
7254 quires/reminds you to check the real-world balance. That may not be
7255 true if you auto-generate balance assertions from bank data; in that
7256 case, I recommend to import transactions uncleared, then use the man‐
7257 ual-review-and-mark-cleared phase as a reminder to check the latest as‐
7258 sertions against real-world balances.
7259 close
7261 (equity)
7262 Generate transactions which transfer account balances to and/or from
7264 another account (typically equity). This can be useful for migrating
7265 balances to a new journal file, or for merging earnings into equity at
7266 end of accounting period.
7267 By default, it prints a transaction that zeroes out ALE accounts (as‐
7269 set, liability, equity accounts; this requires account types to be con‐
7270 figured); or if ACCTQUERY is provided, the accounts matched by that.
7271 (experimental)
7273 This command has four main modes, corresponding to the most common use
7275 cases:
7276 1. With --close (default), it prints a "closing balances" transaction
7278 that zeroes out ALE (asset, liability, equity) accounts by default
7279 (this requires account types to be inferred or declared); or, the
7280 accounts matched by the provided ACCTQUERY arguments.
7281 2. With --open, it prints an opposite "opening balances" transaction
7283 that restores those balances from zero. This is similar to Ledger's
7284 equity command.
7285 3. With --migrate, it prints both the closing and opening transactions.
7287 This is the preferred way to migrate balances to a new file: run
7288 hledger close --migrate, add the closing transaction at the end of
7289 the old file, and add the opening transaction at the start of the
7290 new file. The matching closing/opening transactions cancel each
7291 other out, preserving correct balances during multi-file reporting.
7292 4. With --retain, it prints a "retain earnings" transaction that trans‐
7294 fers RX (revenue and expense) balances to equity:retained earnings.
7295 Businesses traditionally do this at the end of each accounting pe‐
7296 riod; it is less necessary with computer-based accounting, but it
7297 could still be useful if you want to see the accounting equation
7298 (A=L+E) satisfied.
7299 In all modes, the defaults can be overridden:
7301 • the transaction descriptions can be changed with --close-desc=DESC
7303 and --open-desc=DESC
7304 • the account to transfer to/from can be changed with --close-acct=ACCT
7306 and --open-acct=ACCT
7307 • the accounts to be closed/opened can be changed with ACCTQUERY (ac‐
7309 count query arguments).
7310 • the closing/opening dates can be changed with -e DATE (a report end
7312 date)
7313 By default just one destination/source posting will be used, with its
7315 amount left implicit. With --x/--explicit, the amount will be shown
7316 explicitly, and if it involves multiple commodities, a separate posting
7317 will be generated for each of them (similar to print -x).
7318 With --show-costs, any amount costs are shown, with separate postings
7320 for each cost. This is currently the best way to view investment lots.
7321 If you have many currency conversion or investment transactions, it can
7322 generate very large journal entries.
7323 With --interleaved, each individual transfer is shown with source and
7325 destination postings next to each other. This could be useful for
7326 troubleshooting.
7327 The default closing date is yesterday, or the journal's end date,
7329 whichever is later. You can change this by specifying a report end
7330 date with -e. The last day of the report period will be the closing
7331 date, eg -e 2024 means "close on 2023-12-31". The opening date is al‐
7332 ways the day after the closing date.
7333 close and balance assertions
7335 Balance assertions will be generated, verifying that the accounts have
7336 been reset to zero (and then restored to their previous balances, if
7337 there is an opening transaction).
7338 These provide useful error checking, but you can ignore them temporar‐
7340 ily with -I, or remove them if you prefer.
7341 You probably should avoid filtering transactions by status or realness
7343 (-C, -R, status:), or generating postings (--auto), with this command,
7344 since the balance assertions would depend on these.
7345 Note custom posting dates spanning the file boundary will disrupt the
7347 balance assertions:
7348 2023-12-30 a purchase made in december, cleared in january
7350 expenses:food 5
7351 assets:bank:checking -5 ; date: 2023-01-02
7352 To solve that you can transfer the money to and from a temporary ac‐
7354 count, in effect splitting the multi-day transaction into two single-
7355 day transactions:
7356 ; in 2022.journal:
7358 2022-12-30 a purchase made in december, cleared in january
7359 expenses:food 5
7360 equity:pending -5
7361 ; in 2023.journal:
7363 2023-01-02 last year's transaction cleared
7364 equity:pending 5 = 0
7365 assets:bank:checking -5
7366 Example: retain earnings
7368 Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap‐
7369 pending the generated transaction to the journal:
7370 $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
7372 Note 2022's income statement will now show only zeroes, because rev‐
7374 enues and expenses have been moved entirely to equity. To see them
7375 again, you could exclude the retain transaction:
7376 $ hledger -f 2022.journal is not:desc:'retain earnings'
7378 Example: migrate balances to a new file
7380 Close assets/liabilities/equity on 2022-12-31 and re-open them on
7381 2023-01-01:
7382 $ hledger close --migrate -f 2022.journal -p 2022
7384 # copy/paste the closing transaction to the end of 2022.journal
7385 # copy/paste the opening transaction to the start of 2023.journal
7386 Now 2022's balance sheet will show only zeroes, indicating a balanced
7388 accounting equation. (Unless you are using @/@@ notation - in that
7389 case, try adding --infer-equity.) To see the end-of-year balances
7390 again, you could exclude the closing transaction:
7391 $ hledger -f 2022.journal bs not:desc:'closing balances'
7393 Example: excluding closing/opening transactions
7395 When combining many files for multi-year reports, the closing/opening
7396 transactions cause some noise in transaction-oriented reports like
7397 print and register. You can exclude them as shown above, but
7398 not:desc:... is not ideal as it depends on consistent descriptions;
7399 also you will want to avoid excluding the very first opening transac‐
7400 tion, which could be awkward. Here is one alternative, using tags:
7401 Add clopen: tags to all opening/closing balances transactions except
7403 the first, like this:
7404 ; 2021.journal
7406 2021-06-01 first opening balances
7407 ...
7408 2021-12-31 closing balances ; clopen:2022
7409 ...
7410 ; 2022.journal
7412 2022-01-01 opening balances ; clopen:2022
7413 ...
7414 2022-12-31 closing balances ; clopen:2023
7415 ...
7416 ; 2023.journal
7418 2023-01-01 opening balances ; clopen:2023
7419 ...
7420 Now, assuming a combined journal like:
7422 ; all.journal
7424 include 2021.journal
7425 include 2022.journal
7426 include 2023.journal
7427 The clopen: tag can exclude all but the first opening transaction. To
7429 show a clean multi-year checking register:
7430 $ hledger -f all.journal areg checking not:tag:clopen
7432 And the year values allow more precision. To show 2022's year-end bal‐
7434 ance sheet:
7435 $ hledger -f all.journal bs -e2023 not:tag:clopen=2023
7437 codes
7439 List the codes seen in transactions, in the order parsed.
7440 This command prints the value of each transaction's code field, in the
7442 order transactions were parsed. The transaction code is an optional
7443 value written in parentheses between the date and description, often
7444 used to store a cheque number, order number or similar.
7445 Transactions aren't required to have a code, and missing or empty codes
7447 will not be shown by default. With the -E/--empty flag, they will be
7448 printed as blank lines.
7449 You can add a query to select a subset of transactions.
7451 Examples:
7453 2022/1/1 (123) Supermarket
7455 Food $5.00
7456 Checking
7457 2022/1/2 (124) Post Office
7459 Postage $8.32
7460 Checking
7461 2022/1/3 Supermarket
7463 Food $11.23
7464 Checking
7465 2022/1/4 (126) Post Office
7467 Postage $3.21
7468 Checking
7469 $ hledger codes
7471 123
7472 124
7473 126
7474 $ hledger codes -E
7476 123
7477 124
7478 126
7480 commodities
7482 List all commodity/currency symbols used or declared in the journal.
7483 demo
7485 Play demos of hledger usage in the terminal, if asciinema is installed.
7486 Run this command with no argument to list the demos. To play a demo,
7488 write its number or a prefix or substring of its title. Tips:
7489 Make your terminal window large enough to see the demo clearly.
7491 Use the -s/--speed SPEED option to set your preferred playback speed,
7493 eg -s4 to play at 4x original speed or -s.5 to play at half speed. The
7494 default speed is 2x.
7495 Other asciinema options can be added following a double dash, eg --
7497 -i.1 to limit pauses or -- -h to list asciinema's other options.
7498 During playback, several keys are available: SPACE to pause/unpause, .
7500 to step forward (while paused), CTRL-c quit.
7501 Examples:
7503 $ hledger demo # list available demos
7505 $ hledger demo 1 # play the first demo at default speed (2x)
7506 $ hledger demo install -s4 # play the "install" demo at 4x speed
7507 descriptions
7509 List the unique descriptions that appear in transactions.
7510 This command lists the unique descriptions that appear in transactions,
7512 in alphabetic order. You can add a query to select a subset of trans‐
7513 actions.
7514 Example:
7516 $ hledger descriptions
7518 Store Name
7519 Gas Station | Petrol
7520 Person A
7521 diff
7523 Compares a particular account's transactions in two input files. It
7524 shows any transactions to this account which are in one file but not in
7525 the other.
7526 More precisely, for each posting affecting this account in either file,
7528 it looks for a corresponding posting in the other file which posts the
7529 same amount to the same account (ignoring date, description, etc.)
7530 Since postings not transactions are compared, this also works when mul‐
7531 tiple bank transactions have been combined into a single journal entry.
7532 This is useful eg if you have downloaded an account's transactions from
7534 your bank (eg as CSV data). When hledger and your bank disagree about
7535 the account balance, you can compare the bank data with your journal to
7536 find out the cause.
7537 Examples:
7539 $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro
7541 These transactions are in the first file only:
7542 2014/01/01 Opening Balances
7544 assets:bank:giro EUR ...
7545 ...
7546 equity:opening balances EUR -...
7547 These transactions are in the second file only:
7549 files
7551 List all files included in the journal. With a REGEX argument, only
7552 file names matching the regular expression (case sensitive) are shown.
7553 help
7555 Show the hledger user manual in the terminal, with info, man, or a
7556 pager. With a TOPIC argument, open it at that topic if possible.
7557 TOPIC can be any heading in the manual, or a heading prefix, case in‐
7558 sensitive. Eg: commands, print, forecast, journal, amount, "auto post‐
7559 ings".
7560 This command shows the hledger manual built in to your hledger version.
7562 It can be useful when offline, or when you prefer the terminal to a web
7563 browser, or when the appropriate hledger manual or viewing tools are
7564 not installed on your system.
7565 By default it chooses the best viewer found in $PATH, trying (in this
7567 order): info, man, $PAGER, less, more. You can force the use of info,
7568 man, or a pager with the -i, -m, or -p flags, If no viewer can be
7569 found, or the command is run non-interactively, it just prints the man‐
7570 ual to stdout.
7571 If using info, note that version 6 or greater is needed for TOPIC
7573 lookup. If you are on mac you will likely have info 4.8, and should
7574 consider installing a newer version, eg with brew install texinfo
7575 (#1770).
7576 Examples
7578 $ hledger help --help # show how the help command works
7580 $ hledger help # show the hledger manual with info, man or $PAGER
7581 $ hledger help journal # show the journal topic in the hledger manual
7582 $ hledger help -m journal # show it with man, even if info is installed
7583 import
7585 Read new transactions added to each FILE since last run, and add them
7586 to the journal. Or with --dry-run, just print the transactions that
7587 would be added. Or with --catchup, just mark all of the FILEs' trans‐
7588 actions as imported, without actually importing any.
7589 This command may append new transactions to the main journal file
7591 (which should be in journal format). Existing transactions are not
7592 changed. This is one of the few hledger commands that writes to the
7593 journal file (see also add).
7594 Unlike other hledger commands, with import the journal file is an out‐
7596 put file, and will be modified, though only by appending (existing data
7597 will not be changed). The input files are specified as arguments, so
7598 to import one or more CSV files to your main journal, you will run
7599 hledger import bank.csv or perhaps hledger import *.csv.
7600 Note you can import from any file format, though CSV files are the most
7602 common import source, and these docs focus on that case.
7603 Deduplication
7605 As a convenience import does deduplication while reading transactions.
7606 This does not mean "ignore transactions that look the same", but rather
7607 "ignore transactions that have been seen before". This is intended for
7608 when you are periodically importing foreign data which may contain al‐
7609 ready-imported transactions. So eg, if every day you download bank CSV
7610 files containing redundant data, you can safely run hledger import
7611 bank.csv and only new transactions will be imported. (import is idem‐
7612 potent.)
7613 Since the items being read (CSV records, eg) often do not come with
7615 unique identifiers, hledger detects new transactions by date, assuming
7616 that:
7617 1. new items always have the newest dates
7619 2. item dates do not change across reads
7621 3. and items with the same date remain in the same relative order
7623 across reads.
7624 These are often true of CSV files representing transactions, or true
7626 enough so that it works pretty well in practice. 1 is important, but
7627 violations of 2 and 3 amongst the old transactions won't matter (and if
7628 you import often, the new transactions will be few, so less likely to
7629 be the ones affected).
7630 hledger remembers the latest date processed in each input file by sav‐
7632 ing a hidden ".latest" state file in the same directory. Eg when read‐
7633 ing finance/bank.csv, it will look for and update the finance/.lat‐
7634 est.bank.csv state file. The format is simple: one or more lines con‐
7635 taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro‐
7636 cessed transactions up to this date, and this many of them on that
7637 date." Normally you won't see or manipulate these state files yourself.
7638 But if needed, you can delete them to reset the state (making all
7639 transactions "new"), or you can construct them to "catch up" to a cer‐
7640 tain date.
7641 Note deduplication (and updating of state files) can also be done by
7643 print --new, but this is less often used.
7644 Import testing
7646 With --dry-run, the transactions that will be imported are printed to
7647 the terminal, without updating your journal or state files. The output
7648 is valid journal format, like the print command, so you can re-parse
7649 it. Eg, to see any importable transactions which CSV rules have not
7650 categorised:
7651 $ hledger import --dry bank.csv | hledger -f- -I print unknown
7653 or (live updating):
7655 $ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'
7657 Note: when importing from multiple files at once, it's currently possi‐
7659 ble for some .latest files to be updated successfully, while the actual
7660 import fails because of a problem in one of the files, leaving them out
7661 of sync (and causing some transactions to be missed). To prevent this,
7662 do a --dry-run first and fix any problems before the real import.
7663 Importing balance assignments
7665 Entries added by import will have their posting amounts made explicit
7666 (like hledger print -x). This means that any balance assignments in
7667 imported files must be evaluated; but, imported files don't get to see
7668 the main file's account balances. As a result, importing entries with
7669 balance assignments (eg from an institution that provides only balances
7670 and not posting amounts) will probably generate incorrect posting
7671 amounts. To avoid this problem, use print instead of import:
7672 $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
7674 (If you think import should leave amounts implicit like print does,
7676 please test it and send a pull request.)
7677 Commodity display styles
7679 Imported amounts will be formatted according to the canonical commodity
7680 styles (declared or inferred) in the main journal file.
7681 incomestatement
7683 (is)
7684 This command displays an income statement, showing revenues and ex‐
7686 penses during one or more periods. Amounts are shown with normal posi‐
7687 tive sign, as in conventional financial statements.
7688 This report shows accounts declared with the Revenue or Expense type
7690 (see account types). Or if no such accounts are declared, it shows
7691 top-level accounts named revenue or income or expense (case insensi‐
7692 tive, plurals allowed) and their subaccounts.
7693 Example:
7695 $ hledger incomestatement
7697 Income Statement
7698 Revenues:
7700 $-2 income
7701 $-1 gifts
7702 $-1 salary
7703 --------------------
7704 $-2
7705 Expenses:
7707 $2 expenses
7708 $1 food
7709 $1 supplies
7710 --------------------
7711 $2
7712 Total:
7714 --------------------
7715 0
7716 This command is a higher-level variant of the balance command, and sup‐
7718 ports many of that command's features, such as multi-period reports.
7719 It is similar to hledger balance '(revenues|income)' expenses, but with
7720 smarter account detection, and revenues/income displayed with their
7721 sign flipped.
7722 This command also supports the output destination and output format op‐
7724 tions The output formats supported are txt, csv, html, and (experimen‐
7725 tal) json.
7726 notes
7728 List the unique notes that appear in transactions.
7729 This command lists the unique notes that appear in transactions, in al‐
7731 phabetic order. You can add a query to select a subset of transac‐
7732 tions. The note is the part of the transaction description after a |
7733 character (or if there is no |, the whole description).
7734 Example:
7736 $ hledger notes
7738 Petrol
7739 Snacks
7740 payees
7742 List the unique payee/payer names that appear in transactions.
7743 This command lists unique payee/payer names which have been declared
7745 with payee directives (--declared), used in transaction descriptions
7746 (--used), or both (the default).
7747 The payee/payer is the part of the transaction description before a |
7749 character (or if there is no |, the whole description).
7750 You can add query arguments to select a subset of transactions. This
7752 implies --used.
7753 Example:
7755 $ hledger payees
7757 Store Name
7758 Gas Station
7759 Person A
7760 prices
7762 Print market price directives from the journal. With --infer-market-
7763 prices, generate additional market prices from costs. With --infer-re‐
7764 verse-prices, also generate market prices by inverting known prices.
7765 Prices can be filtered by a query. Price amounts are displayed with
7766 their full precision.
7767 print
7769 Show transaction journal entries, sorted by date.
7770 The print command displays full journal entries (transactions) from the
7772 journal file, sorted by date (or with --date2, by secondary date).
7773 Amounts are shown mostly normalised to commodity display style, eg the
7775 placement of commodity symbols will be consistent. All of their deci‐
7776 mal places are shown, as in the original journal entry (with one alter‐
7777 ation: in some cases trailing zeroes are added.)
7778 Amounts are shown right-aligned within each transaction (but not across
7780 all transactions).
7781 Directives and inter-transaction comments are not shown, currently.
7783 This means the print command is somewhat lossy, and if you are using it
7784 to reformat your journal you should take care to also copy over the di‐
7785 rectives and file-level comments.
7786 Eg:
7788 $ hledger print
7790 2008/01/01 income
7791 assets:bank:checking $1
7792 income:salary $-1
7793 2008/06/01 gift
7795 assets:bank:checking $1
7796 income:gifts $-1
7797 2008/06/02 save
7799 assets:bank:saving $1
7800 assets:bank:checking $-1
7801 2008/06/03 * eat & shop
7803 expenses:food $1
7804 expenses:supplies $1
7805 assets:cash $-2
7806 2008/12/31 * pay off
7808 liabilities:debts $1
7809 assets:bank:checking $-1
7810 print's output is usually a valid hledger journal, and you can process
7812 it again with a second hledger command. This can be useful for certain
7813 kinds of search, eg:
7814 # Show running total of food expenses paid from cash.
7816 # -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
7817 $ hledger print assets:cash | hledger -f- -I reg expenses:food
7818 There are some situations where print's output can become unparseable:
7820 • Valuation affects posting amounts but not balance assertion or bal‐
7822 ance assignment amounts, potentially causing those to fail.
7823 • Auto postings can generate postings with too many missing amounts.
7825 • Account aliases can generate bad account names.
7827 Normally, the journal entry's explicit or implicit amount style is pre‐
7829 served. For example, when an amount is omitted in the journal, it will
7830 not appear in the output. Similarly, when a cost is implied but not
7831 written, it will not appear in the output. You can use the -x/--ex‐
7832 plicit flag to make all amounts and costs explicit, which can be useful
7833 for troubleshooting or for making your journal more readable and robust
7834 against data entry errors. -x is also implied by using any of
7835 -B,-V,-X,--value.
7836 Note, -x/--explicit will cause postings with a multi-commodity amount
7838 (these can arise when a multi-commodity transaction has an implicit
7839 amount) to be split into multiple single-commodity postings, keeping
7840 the output parseable.
7841 With -B/--cost, amounts with costs are converted to cost using that
7843 price. This can be used for troubleshooting.
7844 With -m DESC/--match=DESC, print does a fuzzy search for one recent
7846 transaction whose description is most similar to DESC. DESC should
7847 contain at least two characters. If there is no similar-enough match,
7848 no transaction will be shown and the program exit code will be non-
7849 zero.
7850 With --new, hledger prints only transactions it has not seen on a pre‐
7852 vious run. This uses the same deduplication system as the import com‐
7853 mand. (See import's docs for details.)
7854 This command also supports the output destination and output format op‐
7856 tions The output formats supported are txt, csv, and (experimental)
7857 json and sql.
7858 Here's an example of print's CSV output:
7860 $ hledger print -Ocsv
7862 "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
7863 "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
7864 "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
7865 "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
7866 "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
7867 "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
7868 "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
7869 "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
7870 "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
7871 "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
7872 "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
7873 "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
7874 • There is one CSV record per posting, with the parent transaction's
7876 fields repeated.
7877 • The "txnidx" (transaction index) field shows which postings belong to
7879 the same transaction. (This number might change if transactions are
7880 reordered within the file, files are parsed/included in a different
7881 order, etc.)
7882 • The amount is separated into "commodity" (the symbol) and "amount"
7884 (numeric quantity) fields.
7885 • The numeric amount is repeated in either the "credit" or "debit" col‐
7887 umn, for convenience. (Those names are not accurate in the account‐
7888 ing sense; it just puts negative amounts under credit and zero or
7889 greater amounts under debit.)
7890 register
7892 (reg)
7893 Show postings and their running total.
7895 The register command displays matched postings, across all accounts, in
7897 date order, with their running total or running historical balance.
7898 (See also the aregister command, which shows matched transactions in a
7899 specific account.)
7900 register normally shows line per posting, but note that multi-commodity
7902 amounts will occupy multiple lines (one line per commodity).
7903 It is typically used with a query selecting a particular account, to
7905 see that account's activity:
7906 $ hledger register checking
7908 2008/01/01 income assets:bank:checking $1 $1
7909 2008/06/01 gift assets:bank:checking $1 $2
7910 2008/06/02 save assets:bank:checking $-1 $1
7911 2008/12/31 pay off assets:bank:checking $-1 0
7912 With --date2, it shows and sorts by secondary date instead.
7914 For performance reasons, column widths are chosen based on the first
7916 1000 lines; this means unusually wide values in later lines can cause
7917 visual discontinuities as column widths are adjusted. If you want to
7918 ensure perfect alignment, at the cost of more time and memory, use the
7919 --align-all flag.
7920 The --historical/-H flag adds the balance from any undisplayed prior
7922 postings to the running total. This is useful when you want to see
7923 only recent activity, with a historically accurate running balance:
7924 $ hledger register checking -b 2008/6 --historical
7926 2008/06/01 gift assets:bank:checking $1 $2
7927 2008/06/02 save assets:bank:checking $-1 $1
7928 2008/12/31 pay off assets:bank:checking $-1 0
7929 The --depth option limits the amount of sub-account detail displayed.
7931 The --average/-A flag shows the running average posting amount instead
7933 of the running total (so, the final number displayed is the average for
7934 the whole report period). This flag implies --empty (see below). It
7935 is affected by --historical. It works best when showing just one ac‐
7936 count and one commodity.
7937 The --related/-r flag shows the other postings in the transactions of
7939 the postings which would normally be shown.
7940 The --invert flag negates all amounts. For example, it can be used on
7942 an income account where amounts are normally displayed as negative num‐
7943 bers. It's also useful to show postings on the checking account to‐
7944 gether with the related account:
7945 $ hledger register --related --invert assets:checking
7947 With a reporting interval, register shows summary postings, one per in‐
7949 terval, aggregating the postings to each account:
7950 $ hledger register --monthly income
7952 2008/01 income:salary $-1 $-1
7953 2008/06 income:gifts $-1 $-2
7954 Periods with no activity, and summary postings with a zero amount, are
7956 not shown by default; use the --empty/-E flag to see them:
7957 $ hledger register --monthly income -E
7959 2008/01 income:salary $-1 $-1
7960 2008/02 0 $-1
7961 2008/03 0 $-1
7962 2008/04 0 $-1
7963 2008/05 0 $-1
7964 2008/06 income:gifts $-1 $-2
7965 2008/07 0 $-2
7966 2008/08 0 $-2
7967 2008/09 0 $-2
7968 2008/10 0 $-2
7969 2008/11 0 $-2
7970 2008/12 0 $-2
7971 Often, you'll want to see just one line per interval. The --depth op‐
7973 tion helps with this, causing subaccounts to be aggregated:
7974 $ hledger register --monthly assets --depth 1h
7976 2008/01 assets $1 $1
7977 2008/06 assets $-1 0
7978 2008/12 assets $-1 $-1
7979 Note when using report intervals, if you specify start/end dates these
7981 will be adjusted outward if necessary to contain a whole number of in‐
7982 tervals. This ensures that the first and last intervals are full
7983 length and comparable to the others in the report.
7984 With -m DESC/--match=DESC, register does a fuzzy search for one recent
7986 posting whose description is most similar to DESC. DESC should contain
7987 at least two characters. If there is no similar-enough match, no post‐
7988 ing will be shown and the program exit code will be non-zero.
7989 Custom register output
7991 register uses the full terminal width by default, except on windows.
7992 You can override this by setting the COLUMNS environment variable (not
7993 a bash shell variable) or by using the --width/-w option.
7994 The description and account columns normally share the space equally
7996 (about half of (width - 40) each). You can adjust this by adding a de‐
7997 scription width as part of --width's argument, comma-separated: --width
7998 W,D . Here's a diagram (won't display correctly in --help):
7999 <--------------------------------- width (W) ---------------------------------->
8001 date (10) description (D) account (W-41-D) amount (12) balance (12)
8002 DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
8003 and some examples:
8005 $ hledger reg # use terminal width (or 80 on windows)
8007 $ hledger reg -w 100 # use width 100
8008 $ COLUMNS=100 hledger reg # set with one-time environment variable
8009 $ export COLUMNS=100; hledger reg # set till session end (or window resize)
8010 $ hledger reg -w 100,40 # set overall width 100, description width 40
8011 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
8012 This command also supports the output destination and output format op‐
8014 tions The output formats supported are txt, csv, and (experimental)
8015 json.
8016 rewrite
8018 Print all transactions, rewriting the postings of matched transactions.
8019 For now the only rewrite available is adding new postings, like print
8020 --auto.
8021 This is a start at a generic rewriter of transaction entries. It reads
8023 the default journal and prints the transactions, like print, but adds
8024 one or more specified postings to any transactions matching QUERY. The
8025 posting amounts can be fixed, or a multiplier of the existing transac‐
8026 tion's first posting amount.
8027 Examples:
8029 $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
8031 $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
8032 $ hledger-rewrite.hs -f rewrites.hledger
8033 rewrites.hledger may consist of entries like:
8035 = ^income amt:<0 date:2017
8037 (liabilities:tax) *0.33 ; tax on income
8038 (reserve:grocery) *0.25 ; reserve 25% for grocery
8039 (reserve:) *0.25 ; reserve 25% for grocery
8040 Note the single quotes to protect the dollar sign from bash, and the
8042 two spaces between account and amount.
8043 More:
8045 $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
8047 $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
8048 $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'
8049 $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
8050 Argument for --add-posting option is a usual posting of transaction
8052 with an exception for amount specification. More precisely, you can
8053 use '*' (star symbol) before the amount to indicate that that this is a
8054 factor for an amount of original matched posting. If the amount in‐
8055 cludes a commodity name, the new posting amount will be in the new com‐
8056 modity; otherwise, it will be in the matched posting amount's commod‐
8057 ity.
8058 Re-write rules in a file
8060 During the run this tool will execute so called "Automated Transac‐
8061 tions" found in any journal it process. I.e instead of specifying this
8062 operations in command line you can put them in a journal file.
8063 $ rewrite-rules.journal
8065 Make contents look like this:
8067 = ^income
8069 (liabilities:tax) *.33
8070 = expenses:gifts
8072 budget:gifts *-1
8073 assets:budget *1
8074 Note that '=' (equality symbol) that is used instead of date in trans‐
8076 actions you usually write. It indicates the query by which you want to
8077 match the posting to add new ones.
8078 $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
8080 This is something similar to the commands pipeline:
8082 $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \
8084 | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \
8085 --add-posting 'assets:budget *1' \
8086 > rewritten-tidy-output.journal
8087 It is important to understand that relative order of such entries in
8089 journal is important. You can re-use result of previously added post‐
8090 ings.
8091 Diff output format
8093 To use this tool for batch modification of your journal files you may
8094 find useful output in form of unified diff.
8095 $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
8097 Output might look like:
8099 --- /tmp/examples/sample.journal
8101 +++ /tmp/examples/sample.journal
8102 @@ -18,3 +18,4 @@
8103 2008/01/01 income
8104 - assets:bank:checking $1
8105 + assets:bank:checking $1
8106 income:salary
8107 + (liabilities:tax) 0
8108 @@ -22,3 +23,4 @@
8109 2008/06/01 gift
8110 - assets:bank:checking $1
8111 + assets:bank:checking $1
8112 income:gifts
8113 + (liabilities:tax) 0
8114 If you'll pass this through patch tool you'll get transactions contain‐
8116 ing the posting that matches your query be updated. Note that multiple
8117 files might be update according to list of input files specified via
8118 --file options and include directives inside of these files.
8119 Be careful. Whole transaction being re-formatted in a style of output
8121 from hledger print.
8122 See also:
8124 https://github.com/simonmichael/hledger/issues/99
8126 rewrite vs. print --auto
8128 This command predates print --auto, and currently does much the same
8129 thing, but with these differences:
8130 • with multiple files, rewrite lets rules in any file affect all other
8132 files. print --auto uses standard directive scoping; rules affect
8133 only child files.
8134 • rewrite's query limits which transactions can be rewritten; all are
8136 printed. print --auto's query limits which transactions are printed.
8137 • rewrite applies rules specified on command line or in the journal.
8139 print --auto applies rules specified in the journal.
8140 roi
8142 Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
8143 on your investments.
8144 At a minimum, you need to supply a query (which could be just an ac‐
8146 count name) to select your investment(s) with --inv, and another query
8147 to identify your profit and loss transactions with --pnl.
8148 If you do not record changes in the value of your investment manually,
8150 or do not require computation of time-weighted return (TWR), --pnl
8151 could be an empty query (--pnl "" or --pnl STR where STR does not match
8152 any of your accounts).
8153 This command will compute and display the internalized rate of return
8155 (IRR) and time-weighted rate of return (TWR) for your investments for
8156 the time period requested. Both rates of return are annualized before
8157 display, regardless of the length of reporting interval.
8158 Price directives will be taken into account if you supply appropriate
8160 --cost or --value flags (see VALUATION).
8161 Note, in some cases this report can fail, for these reasons:
8163 • Error (NotBracketed): No solution for Internal Rate of Return (IRR).
8165 Possible causes: IRR is huge (>1000000%), balance of investment be‐
8166 comes negative at some point in time.
8167 • Error (SearchFailed): Failed to find solution for Internal Rate of
8169 Return (IRR). Either search does not converge to a solution, or con‐
8170 verges too slowly.
8171 Examples:
8173 • Using roi to compute total return of investment in stocks:
8175 https://github.com/simonmichael/hledger/blob/master/examples/invest‐
8176 ing/roi-unrealised.ledger
8177 • Cookbook > Return on Investment: https://hledger.org/roi.html
8179 Spaces and special characters in --inv and --pnl
8181 Note that --inv and --pnl's argument is a query, and queries could have
8182 several space-separated terms (see QUERIES).
8183 To indicate that all search terms form single command-line argument,
8185 you will need to put them in quotes (see Special characters):
8186 $ hledger roi --inv 'term1 term2 term3 ...'
8188 If any query terms contain spaces themselves, you will need an extra
8190 level of nested quoting, eg:
8191 $ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"
8193 Semantics of --inv and --pnl
8195 Query supplied to --inv has to match all transactions that are related
8196 to your investment. Transactions not matching --inv will be ignored.
8197 In these transactions, ROI will conside postings that match --inv to be
8199 "investment postings" and other postings (not matching --inv) will be
8200 sorted into two categories: "cash flow" and "profit and loss", as ROI
8201 needs to know which part of the investment value is your contributions
8202 and which is due to the return on investment.
8203 • "Cash flow" is depositing or withdrawing money, buying or selling as‐
8205 sets, or otherwise converting between your investment commodity and
8206 any other commodity. Example:
8207 2019-01-01 Investing in Snake Oil
8209 assets:cash -$100
8210 investment:snake oil
8211 2020-01-01 Selling my Snake Oil
8213 assets:cash $10
8214 investment:snake oil = 0
8215 • "Profit and loss" is change in the value of your investment:
8217 2019-06-01 Snake Oil falls in value
8219 investment:snake oil = $57
8220 equity:unrealized profit or loss
8221 All non-investment postings are assumed to be "cash flow", unless they
8223 match --pnl query. Changes in value of your investment due to "profit
8224 and loss" postings will be considered as part of your investment re‐
8225 turn.
8226 Example: if you use --inv snake --pnl equity:unrealized, then postings
8228 in the example below would be classifed as:
8229 2019-01-01 Snake Oil #1
8231 assets:cash -$100 ; cash flow posting
8232 investment:snake oil ; investment posting
8233 2019-03-01 Snake Oil #2
8235 equity:unrealized pnl -$100 ; profit and loss posting
8236 snake oil ; investment posting
8237 2019-07-01 Snake Oil #3
8239 equity:unrealized pnl ; profit and loss posting
8240 cash -$100 ; cash flow posting
8241 snake oil $50 ; investment posting
8242 IRR and TWR explained
8244 "ROI" stands for "return on investment". Traditionally this was com‐
8245 puted as a difference between current value of investment and its ini‐
8246 tial value, expressed in percentage of the initial value.
8247 However, this approach is only practical in simple cases, where invest‐
8249 ments receives no in-flows or out-flows of money, and where rate of
8250 growth is fixed over time. For more complex scenarios you need differ‐
8251 ent ways to compute rate of return, and this command implements two of
8252 them: IRR and TWR.
8253 Internal rate of return, or "IRR" (also called "money-weighted rate of
8255 return") takes into account effects of in-flows and out-flows.
8256 Naively, if you are withdrawing from your investment, your future gains
8257 would be smaller (in absolute numbers), and will be a smaller percent‐
8258 age of your initial investment, and if you are adding to your invest‐
8259 ment, you will receive bigger absolute gains (but probably at the same
8260 rate of return). IRR is a way to compute rate of return for each pe‐
8261 riod between in-flow or out-flow of money, and then combine them in a
8262 way that gives you a compound annual rate of return that investment is
8263 expected to generate.
8264 As mentioned before, in-flows and out-flows would be any cash that you
8266 personally put in or withdraw, and for the "roi" command, these are the
8267 postings that match the query in the--inv argument and NOT match the
8268 query in the--pnl argument.
8269 If you manually record changes in the value of your investment as
8271 transactions that balance them against "profit and loss" (or "unreal‐
8272 ized gains") account or use price directives, then in order for IRR to
8273 compute the precise effect of your in-flows and out-flows on the rate
8274 of return, you will need to record the value of your investement on or
8275 close to the days when in- or out-flows occur.
8276 In technical terms, IRR uses the same approach as computation of net
8278 present value, and tries to find a discount rate that makes net present
8279 value of all the cash flows of your investment to add up to zero. This
8280 could be hard to wrap your head around, especially if you haven't done
8281 discounted cash flow analysis before. Implementation of IRR in hledger
8282 should produce results that match the XIRR formula in Excel.
8283 Second way to compute rate of return that roi command implements is
8285 called "time-weighted rate of return" or "TWR". Like IRR, it will also
8286 break the history of your investment into periods between in-flows,
8287 out-flows and value changes, to compute rate of return per each period
8288 and then a compound rate of return. However, internal workings of TWR
8289 are quite different.
8290 TWR represents your investment as an imaginary "unit fund" where in-
8292 flows/ out-flows lead to buying or selling "units" of your investment
8293 and changes in its value change the value of "investment unit". Change
8294 in "unit price" over the reporting period gives you rate of return of
8295 your investment.
8296 References:
8298 • Explanation of rate of return
8300 • Explanation of IRR
8302 • Explanation of TWR
8304 • Examples of computing IRR and TWR and discussion of the limitations
8306 of both metrics
8307 stats
8309 Show journal and performance statistics.
8310 The stats command displays summary information for the whole journal,
8312 or a matched part of it. With a reporting interval, it shows a report
8313 for each report period.
8314 At the end, it shows (in the terminal) the overall run time and number
8316 of transactions processed per second. Note these are approximate and
8317 will vary based on machine, current load, data size, hledger version,
8318 haskell lib versions, GHC version.. but they may be of interest. The
8319 stats command's run time is similar to that of a single-column balance
8320 report.
8321 Example:
8323 $ hledger stats -f examples/1000x1000x10.journal
8325 Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal
8326 Included files :
8327 Transactions span : 2000-01-01 to 2002-09-27 (1000 days)
8328 Last transaction : 2002-09-26 (6995 days ago)
8329 Transactions : 1000 (1.0 per day)
8330 Transactions last 30 days: 0 (0.0 per day)
8331 Transactions last 7 days : 0 (0.0 per day)
8332 Payees/descriptions : 1000
8333 Accounts : 1000 (depth 10)
8334 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)
8335 Market prices : 1000 (A)
8336 Run time : 0.12 s
8338 Throughput : 8342 txns/s
8339 This command supports the -o/--output-file option (but not -O/--output-
8341 format selection).
8342 tags
8344 List the tags used in the journal, or their values.
8345 This command lists the tag names used in the journal, whether on trans‐
8347 actions, postings, or account declarations.
8348 With a TAGREGEX argument, only tag names matching this regular expres‐
8350 sion (case insensitive, infix matched) are shown.
8351 With QUERY arguments, only transactions and accounts matching this
8353 query are considered. If the query involves transaction fields (date:,
8354 desc:, amt:, ...), the search is restricted to the matched transactions
8355 and their accounts.
8356 With the --values flag, the tags' unique non-empty values are listed
8358 instead. With -E/--empty, blank/empty values are also shown.
8359 With --parsed, tags or values are shown in the order they were parsed,
8361 with duplicates included. (Except, tags from account declarations are
8362 always shown first.)
8363 Tip: remember, accounts also acquire tags from their parents, postings
8365 also acquire tags from their account and transaction, transactions also
8366 acquire tags from their postings.
8367 test
8369 Run built-in unit tests.
8370 This command runs the unit tests built in to hledger and hledger-lib,
8372 printing the results on stdout. If any test fails, the exit code will
8373 be non-zero.
8374 This is mainly used by hledger developers, but you can also use it to
8376 sanity-check the installed hledger executable on your platform. All
8377 tests are expected to pass - if you ever see a failure, please report
8378 as a bug!
8379 This command also accepts tasty test runner options, written after a --
8381 (double hyphen). Eg to run only the tests in Hledger.Data.Amount, with
8382 ANSI colour codes disabled:
8383 $ hledger test -- -pData.Amount --color=never
8385 For help on these, see https://github.com/feuerbach/tasty#options (--
8387 --help currently doesn't show them).
8388
8390 Here are some quick examples of how to do some basic tasks with
8391 hledger.
8392 Getting help
8394 Here's how to list commands and view options and command docs:
8395 $ hledger # show available commands
8397 $ hledger --help # show common options
8398 $ hledger CMD --help # show CMD's options, common options and CMD's documentation
8399 You can also view your hledger version's manual in several formats by
8401 using the help command. Eg:
8402 $ hledger help # show the hledger manual with info, man or $PAGER (best available)
8404 $ hledger help journal # show the journal topic in the hledger manual
8405 $ hledger help --help # find out more about the help command
8406 To view manuals and introductory docs on the web, visit
8408 https://hledger.org. Chat and mail list support and discussion ar‐
8409 chives can be found at https://hledger.org/support.
8410 Constructing command lines
8412 hledger has a flexible command line interface. We strive to keep it
8413 simple and ergonomic, but if you run into one of the sharp edges de‐
8414 scribed in OPTIONS, here are some tips that might help:
8415 • command-specific options must go after the command (it's fine to put
8417 common options there too: hledger CMD OPTS ARGS)
8418 • running add-on executables directly simplifies command line parsing
8420 (hledger-ui OPTS ARGS)
8421 • enclose "problematic" args in single quotes
8423 • if needed, also add a backslash to hide regular expression metachar‐
8425 acters from the shell
8426 • to see how a misbehaving command line is being parsed, add --debug=2.
8428 Starting a journal file
8430 hledger looks for your accounting data in a journal file,
8431 $HOME/.hledger.journal by default:
8432 $ hledger stats
8434 The hledger journal file "/Users/simon/.hledger.journal" was not found.
8435 Please create it first, eg with "hledger add" or a text editor.
8436 Or, specify an existing journal file with -f or LEDGER_FILE.
8437 You can override this by setting the LEDGER_FILE environment variable
8439 (see below). It's a good practice to keep this important file under
8440 version control, and to start a new file each year. So you could do
8441 something like this:
8442 $ mkdir ~/finance
8444 $ cd ~/finance
8445 $ git init
8446 Initialized empty Git repository in /Users/simon/finance/.git/
8447 $ touch 2023.journal
8448 $ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile
8449 $ source ~/.profile
8450 $ hledger stats
8451 Main file : /Users/simon/finance/2023.journal
8452 Included files :
8453 Transactions span : to (0 days)
8454 Last transaction : none
8455 Transactions : 0 (0.0 per day)
8456 Transactions last 30 days: 0 (0.0 per day)
8457 Transactions last 7 days : 0 (0.0 per day)
8458 Payees/descriptions : 0
8459 Accounts : 0 (depth 0)
8460 Commodities : 0 ()
8461 Market prices : 0 ()
8462 Setting LEDGER_FILE
8464 How to set LEDGER_FILE permanently depends on your setup:
8465 On unix and mac, running these commands in the terminal will work for
8467 many people; adapt as needed:
8468 $ echo 'export LEDGER_FILE=~/finance/2023.journal` >> ~/.profile
8470 $ source ~/.profile
8471 When correctly configured, in a new terminal window env | grep
8473 LEDGER_FILE will show your file, and so will hledger files.
8474 On mac, this additional step might be helpful for GUI applications
8476 (like Emacs started from the dock): add an entry to ~/.MacOSX/environ‐
8477 ment.plist like
8478 {
8480 "LEDGER_FILE" : "~/finance/2023.journal"
8481 }
8482 and then run killall Dock in a terminal window (or restart the ma‐
8484 chine).
8485 On Windows, see https://www.java.com/en/download/help/path.html, or try
8487 running these commands in a powershell window (let us know if it per‐
8488 sists across a reboot, and if you need to be an Administrator):
8489 > CD
8491 > MKDIR finance
8492 > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"
8493 Setting opening balances
8495 Pick a starting date for which you can look up the balances of some
8496 real-world assets (bank accounts, wallet..) and liabilities (credit
8497 cards..).
8498 To avoid a lot of data entry, you may want to start with just one or
8500 two accounts, like your checking account or cash wallet; and pick a re‐
8501 cent starting date, like today or the start of the week. You can al‐
8502 ways come back later and add more accounts and older transactions, eg
8503 going back to january 1st.
8504 Add an opening balances transaction to the journal, declaring the bal‐
8506 ances on this date. Here are two ways to do it:
8507 • The first way: open the journal in any text editor and save an entry
8509 like this:
8510 2023-01-01 * opening balances
8512 assets:bank:checking $1000 = $1000
8513 assets:bank:savings $2000 = $2000
8514 assets:cash $100 = $100
8515 liabilities:creditcard $-50 = $-50
8516 equity:opening/closing balances
8517 These are start-of-day balances, ie whatever was in the account at
8519 the end of the previous day.
8520 The * after the date is an optional status flag. Here it means
8522 "cleared & confirmed".
8523 The currency symbols are optional, but usually a good idea as you'll
8525 be dealing with multiple currencies sooner or later.
8526 The = amounts are optional balance assertions, providing extra error
8528 checking.
8529 • The second way: run hledger add and follow the prompts to record a
8531 similar transaction:
8532 $ hledger add
8534 Adding transactions to journal file /Users/simon/finance/2023.journal
8535 Any command line arguments will be used as defaults.
8536 Use tab key to complete, readline keys to edit, enter to accept defaults.
8537 An optional (CODE) may follow transaction dates.
8538 An optional ; COMMENT may follow descriptions or amounts.
8539 If you make a mistake, enter < at any prompt to go one step backward.
8540 To end a transaction, enter . when prompted.
8541 To quit, enter . at a date prompt or press control-d or control-c.
8542 Date [2023-02-07]: 2023-01-01
8543 Description: * opening balances
8544 Account 1: assets:bank:checking
8545 Amount 1: $1000
8546 Account 2: assets:bank:savings
8547 Amount 2 [$-1000]: $2000
8548 Account 3: assets:cash
8549 Amount 3 [$-3000]: $100
8550 Account 4: liabilities:creditcard
8551 Amount 4 [$-3100]: $-50
8552 Account 5: equity:opening/closing balances
8553 Amount 5 [$-3050]:
8554 Account 6 (or . or enter to finish this transaction): .
8555 2023-01-01 * opening balances
8556 assets:bank:checking $1000
8557 assets:bank:savings $2000
8558 assets:cash $100
8559 liabilities:creditcard $-50
8560 equity:opening/closing balances $-3050
8561 Save this transaction to the journal ? [y]:
8563 Saved.
8564 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
8565 Date [2023-01-01]: .
8566 If you're using version control, this could be a good time to commit
8568 the journal. Eg:
8569 $ git commit -m 'initial balances' 2023.journal
8571 Recording transactions
8573 As you spend or receive money, you can record these transactions using
8574 one of the methods above (text editor, hledger add) or by using the
8575 hledger-iadd or hledger-web add-ons, or by using the import command to
8576 convert CSV data downloaded from your bank.
8577 Here are some simple transactions, see the hledger_journal(5) manual
8579 and hledger.org for more ideas:
8580 2023/1/10 * gift received
8582 assets:cash $20
8583 income:gifts
8584 2023.1.12 * farmers market
8586 expenses:food $13
8587 assets:cash
8588 2023-01-15 paycheck
8590 income:salary
8591 assets:bank:checking $1000
8592 Reconciling
8594 Periodically you should reconcile - compare your hledger-reported bal‐
8595 ances against external sources of truth, like bank statements or your
8596 bank's website - to be sure that your ledger accurately represents the
8597 real-world balances (and, that the real-world institutions have not
8598 made a mistake!). This gets easy and fast with (1) practice and (2)
8599 frequency. If you do it daily, it can take 2-10 minutes. If you let
8600 it pile up, expect it to take longer as you hunt down errors and dis‐
8601 crepancies.
8602 A typical workflow:
8604 1. Reconcile cash. Count what's in your wallet. Compare with what
8606 hledger reports (hledger bal cash). If they are different, try to
8607 remember the missing transaction, or look for the error in the al‐
8608 ready-recorded transactions. A register report can be helpful
8609 (hledger reg cash). If you can't find the error, add an adjustment
8610 transaction. Eg if you have $105 after the above, and can't explain
8611 the missing $2, it could be:
8612 2023-01-16 * adjust cash
8614 assets:cash $-2 = $105
8615 expenses:misc
8616 2. Reconcile checking. Log in to your bank's website. Compare today's
8618 (cleared) balance with hledger's cleared balance (hledger bal check‐
8619 ing -C). If they are different, track down the error or record the
8620 missing transaction(s) or add an adjustment transaction, similar to
8621 the above. Unlike the cash case, you can usually compare the trans‐
8622 action history and running balance from your bank with the one re‐
8623 ported by hledger reg checking -C. This will be easier if you gen‐
8624 erally record transaction dates quite similar to your bank's clear‐
8625 ing dates.
8626 3. Repeat for other asset/liability accounts.
8628 Tip: instead of the register command, use hledger-ui to see a live-up‐
8630 dating register while you edit the journal: hledger-ui --watch --regis‐
8631 ter checking -C
8632 After reconciling, it could be a good time to mark the reconciled
8634 transactions' status as "cleared and confirmed", if you want to track
8635 that, by adding the * marker. Eg in the paycheck transaction above,
8636 insert * between 2023-01-15 and paycheck
8637 If you're using version control, this can be another good time to com‐
8639 mit:
8640 $ git commit -m 'txns' 2023.journal
8642 Reporting
8644 Here are some basic reports.
8645 Show all transactions:
8647 $ hledger print
8649 2023-01-01 * opening balances
8650 assets:bank:checking $1000
8651 assets:bank:savings $2000
8652 assets:cash $100
8653 liabilities:creditcard $-50
8654 equity:opening/closing balances $-3050
8655 2023-01-10 * gift received
8657 assets:cash $20
8658 income:gifts
8659 2023-01-12 * farmers market
8661 expenses:food $13
8662 assets:cash
8663 2023-01-15 * paycheck
8665 income:salary
8666 assets:bank:checking $1000
8667 2023-01-16 * adjust cash
8669 assets:cash $-2 = $105
8670 expenses:misc
8671 Show account names, and their hierarchy:
8673 $ hledger accounts --tree
8675 assets
8676 bank
8677 checking
8678 savings
8679 cash
8680 equity
8681 opening/closing balances
8682 expenses
8683 food
8684 misc
8685 income
8686 gifts
8687 salary
8688 liabilities
8689 creditcard
8690 Show all account totals:
8692 $ hledger balance
8694 $4105 assets
8695 $4000 bank
8696 $2000 checking
8697 $2000 savings
8698 $105 cash
8699 $-3050 equity:opening/closing balances
8700 $15 expenses
8701 $13 food
8702 $2 misc
8703 $-1020 income
8704 $-20 gifts
8705 $-1000 salary
8706 $-50 liabilities:creditcard
8707 --------------------
8708 0
8709 Show only asset and liability balances, as a flat list, limited to
8711 depth 2:
8712 $ hledger bal assets liabilities -2
8714 $4000 assets:bank
8715 $105 assets:cash
8716 $-50 liabilities:creditcard
8717 --------------------
8718 $4055
8719 Show the same thing without negative numbers, formatted as a simple
8721 balance sheet:
8722 $ hledger bs -2
8724 Balance Sheet 2023-01-16
8725 || 2023-01-16
8727 ========================++============
8728 Assets ||
8729 ------------------------++------------
8730 assets:bank || $4000
8731 assets:cash || $105
8732 ------------------------++------------
8733 || $4105
8734 ========================++============
8735 Liabilities ||
8736 ------------------------++------------
8737 liabilities:creditcard || $50
8738 ------------------------++------------
8739 || $50
8740 ========================++============
8741 Net: || $4055
8742 The final total is your "net worth" on the end date. (Or use bse for a
8744 full balance sheet with equity.)
8745 Show income and expense totals, formatted as an income statement:
8747 hledger is
8749 Income Statement 2023-01-01-2023-01-16
8750 || 2023-01-01-2023-01-16
8752 ===============++=======================
8753 Revenues ||
8754 ---------------++-----------------------
8755 income:gifts || $20
8756 income:salary || $1000
8757 ---------------++-----------------------
8758 || $1020
8759 ===============++=======================
8760 Expenses ||
8761 ---------------++-----------------------
8762 expenses:food || $13
8763 expenses:misc || $2
8764 ---------------++-----------------------
8765 || $15
8766 ===============++=======================
8767 Net: || $1005
8768 The final total is your net income during this period.
8770 Show transactions affecting your wallet, with running total:
8772 $ hledger register cash
8774 2023-01-01 opening balances assets:cash $100 $100
8775 2023-01-10 gift received assets:cash $20 $120
8776 2023-01-12 farmers market assets:cash $-13 $107
8777 2023-01-16 adjust cash assets:cash $-2 $105
8778 Show weekly posting counts as a bar chart:
8780 $ hledger activity -W
8782 2019-12-30 *****
8783 2023-01-06 ****
8784 2023-01-13 ****
8785 Migrating to a new file
8787 At the end of the year, you may want to continue your journal in a new
8788 file, so that old transactions don't slow down or clutter your reports,
8789 and to help ensure the integrity of your accounting history. See the
8790 close command.
8791 If using version control, don't forget to git add the new file.
8793
8795 We welcome bug reports in the hledger issue tracker (shortcut:
8796 http://bugs.hledger.org), or on the #hledger chat or hledger mail list
8797 (https://hledger.org/support).
8798 Some known issues and limitations:
8800 The need to precede add-on command options with -- when invoked from
8802 hledger is awkward. (See Command options, Constructing command lines.)
8803 A UTF-8-aware system locale must be configured to work with non-ascii
8805 data. (See Unicode characters, Troubleshooting.)
8806 On Microsoft Windows, depending whether you are running in a CMD window
8808 or a Cygwin/MSYS/Mintty window and how you installed hledger, non-ascii
8809 characters and colours may not be supported, and the tab key may not be
8810 supported by hledger add. (Running in a WSL window should resolve
8811 these.)
8812 When processing large data files, hledger uses more memory than Ledger.
8814 Troubleshooting
8816 Here are some common issues you might encounter when you run hledger,
8817 and how to resolve them (and remember also you can usually get quick
8818 Support):
8819 PATH issues: I get an error like "No command 'hledger' found"
8821 Depending how you installed hledger, the executables may not be in your
8822 shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo‐
8823 cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one
8824 of these directories to your shell's PATH, and/or open a new terminal
8825 window.
8826 LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using
8828 it
8829 • LEDGER_FILE should be a real environment variable, not just a shell
8830 variable. Eg on unix, the command env | grep LEDGER_FILE should show
8831 it. You may need to use export (see https://stackover‐
8832 flow.com/a/7411509).
8833 • You may need to force your shell to see the new configuration. A
8835 simple way is to close your terminal window and open a new one.
8836 LANG issues: I get errors like "Illegal byte sequence" or "Invalid or
8838 incomplete multibyte or wide character" or "commitAndReleaseBuffer: in‐
8839 valid argument (invalid character)"
8840 Programs compiled with GHC (hledger, haskell build tools, etc.) need
8841 the system locale to be UTF-8-aware, or they will fail when they en‐
8842 counter non-ascii characters. To fix it, set the LANG environment
8843 variable to a locale which supports UTF-8 and which is installed on
8844 your system.
8845 On unix, locale -a lists the installed locales. Look for one which
8847 mentions utf8, UTF-8 or similar. Some examples: C.UTF-8, en_US.utf-8,
8848 fr_FR.utf8. If necessary, use your system package manager to install
8849 one. Then select it by setting the LANG environment variable. Note,
8850 exact spelling and capitalisation of the locale name may be important:
8851 Here's one common way to configure this permanently for your shell:
8852 $ echo "export LANG=en_US.utf8" >>~/.profile
8854 # close and re-open terminal window
8855 COMPATIBILITY ISSUES: hledger gives an error with my Ledger file
8857 Not all of Ledger's journal file syntax or feature set is supported.
8858 See hledger and Ledger for full details.
8859
8863 Simon Michael <simon@joyful.com> and contributors.
8864 See http://hledger.org/CREDITS.html
8865
8868 Copyright 2007-2023 Simon Michael and contributors.
8869
8872 Released under GNU GPL v3 or later.
8873
8876 hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
8877hledger-1.30.1 June 2023 HLEDGER(1)