1HLEDGER(1) hledger User Manuals HLEDGER(1)
3
7 This is the command-line interface (CLI) for the hledger accounting
8 tool. Here we also describe hledger's concepts and file formats. This
9 manual is for hledger 1.27.
10
12 hledger
13 hledger [-f FILE] COMMAND [OPTIONS] [ARGS]
15 hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]
17
19 hledger is a reliable, cross-platform set of programs for tracking
20 money, time, or any other commodity, using double-entry accounting and
21 a simple, editable file format. hledger is inspired by and largely
22 compatible with ledger(1).
23 The basic function of the hledger CLI is to read a plain text file de‐
25 scribing financial transactions (in accounting terms, a general jour‐
26 nal) and print useful reports on standard output, or export them as
27 CSV. hledger can also read some other file formats such as CSV files,
28 translating them to journal format. Additionally, hledger lists other
29 hledger-* executables found in the user’s $PATH and can invoke them as
30 subcommands.
31 hledger reads data from one or more files in hledger journal, time‐
33 clock, timedot, or CSV format specified with -f, or $LEDGER_FILE, or
34 $HOME/.hledger.journal (on windows, perhaps
35 C:/Users/USER/.hledger.journal). If using $LEDGER_FILE, note this must
36 be a real environment variable, not a shell variable. You can specify
37 standard input with -f-.
38 Transactions are dated movements of money between two (or more) named
40 accounts, and are recorded with journal entries like this:
41 2015/10/16 bought food
43 expenses:food $10
44 assets:cash
45 Most users use a text editor to edit the journal, usually with an edi‐
47 tor mode such as ledger-mode for added convenience. hledger’s interac‐
48 tive add command is another way to record new transactions. hledger
49 never changes existing transactions.
50 To get started, you can either save some entries like the above in
52 ~/.hledger.journal, or run hledger add and follow the prompts. Then
53 try some commands like hledger print or hledger balance. Run hledger
54 with no arguments for a list of commands.
55
57 General options
58 To see general usage help, including general options which are sup‐
59 ported by most hledger commands, run hledger -h.
60 General help options:
62 -h --help
64 show general or COMMAND help
65 --man show general or COMMAND user manual with man
67 --info show general or COMMAND user manual with info
69 --version
71 show general or ADDONCMD version
72 --debug[=N]
74 show debug output (levels 1-9, default: 1)
75 General input options:
77 -f FILE --file=FILE
79 use a different input file. For stdin, use - (default:
80 $LEDGER_FILE or $HOME/.hledger.journal)
81 --rules-file=RULESFILE
83 Conversion rules file to use when reading CSV (default:
84 FILE.rules)
85 --separator=CHAR
87 Field separator to expect when reading CSV (default: ',')
88 --alias=OLD=NEW
90 rename accounts named OLD to NEW
91 --anon anonymize accounts and payees
93 --pivot FIELDNAME
95 use some other field or tag for the account name
96 -I --ignore-assertions
98 disable balance assertion checks (note: does not disable balance
99 assignments)
100 -s --strict
102 do extra error checking (check that all posted accounts are de‐
103 clared)
104 General reporting options:
106 -b --begin=DATE
108 include postings/txns on or after this date (will be adjusted to
109 preceding subperiod start when using a report interval)
110 -e --end=DATE
112 include postings/txns before this date (will be adjusted to fol‐
113 lowing subperiod end when using a report interval)
114 -D --daily
116 multiperiod/multicolumn report by day
117 -W --weekly
119 multiperiod/multicolumn report by week
120 -M --monthly
122 multiperiod/multicolumn report by month
123 -Q --quarterly
125 multiperiod/multicolumn report by quarter
126 -Y --yearly
128 multiperiod/multicolumn report by year
129 -p --period=PERIODEXP
131 set start date, end date, and/or reporting interval all at once
132 using period expressions syntax
133 --date2
135 match the secondary date instead (see command help for other ef‐
136 fects)
137 --today=DATE
139 override today's date (affects relative smart dates, for
140 tests/examples)
141 -U --unmarked
143 include only unmarked postings/txns (can combine with -P or -C)
144 -P --pending
146 include only pending postings/txns
147 -C --cleared
149 include only cleared postings/txns
150 -R --real
152 include only non-virtual postings
153 -NUM --depth=NUM
155 hide/aggregate accounts or postings more than NUM levels deep
156 -E --empty
158 show items with zero amount, normally hidden (and vice-versa in
159 hledger-ui/hledger-web)
160 -B --cost
162 convert amounts to their cost/selling amount at transaction time
163 -V --market
165 convert amounts to their market value in default valuation com‐
166 modities
167 -X --exchange=COMM
169 convert amounts to their market value in commodity COMM
170 --value
172 convert amounts to cost or market value, more flexibly than
173 -B/-V/-X
174 --infer-market-prices
176 use transaction prices (recorded with @ or @@) as additional
177 market prices, as if they were P directives
178 --auto apply automated posting rules to modify transactions.
180 --forecast
182 generate future transactions from periodic transaction rules,
183 for the next 6 months or till report end date. In hledger-ui,
184 also make ordinary future transactions visible.
185 --commodity-style
187 Override the commodity style in the output for the specified
188 commodity. For example 'EUR1.000,00'.
189 --color=WHEN (or --colour=WHEN)
191 Should color-supporting commands use ANSI color codes in text
192 output. 'auto' (default): whenever stdout seems to be a color-
193 supporting terminal. 'always' or 'yes': always, useful eg when
194 piping output into 'less -R'. 'never' or 'no': never. A
195 NO_COLOR environment variable overrides this.
196 --pretty[=WHEN]
198 Show prettier output, e.g. using unicode box-drawing charac‐
199 ters. Accepts 'yes' (the default) or 'no' ('y', 'n', 'always',
200 'never' also work). If you provide an argument you must use
201 '=', e.g. '--pretty=yes'.
202 When a reporting option appears more than once in the command line, the
204 last one takes precedence.
205 Some reporting options can also be written as query arguments.
207 Command options
209 To see options for a particular command, including command-specific op‐
210 tions, run: hledger COMMAND -h.
211 Command-specific options must be written after the command name, eg:
213 hledger print -x.
214 Additionally, if the command is an add-on, you may need to put its op‐
216 tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can
217 run the add-on executable directly: hledger-ui --watch.
218 Command arguments
220 Most hledger commands accept arguments after the command name, which
221 are often a query, filtering the data in some way.
222 You can save a set of command line options/arguments in a file, and
224 then reuse them by writing @FILENAME as a command line argument. Eg:
225 hledger bal @foo.args. (To prevent this, eg if you have an argument
226 that begins with a literal @, precede it with --, eg: hledger bal --
227 @ARG).
228 Inside the argument file, each line should contain just one option or
230 argument. Avoid the use of spaces, except inside quotes (or you'll see
231 a confusing error). Between a flag and its argument, use = (or noth‐
232 ing). Bad:
233 assets depth:2
235 -X USD
236 Good:
238 assets
240 depth:2
241 -X=USD
242 For special characters (see below), use one less level of quoting than
244 you would at the command prompt. Bad:
245 -X"$"
247 Good:
249 -X$
251 See also: Save frequently used options.
253 Special characters
255 Single escaping (shell metacharacters)
256 In shell command lines, characters significant to your shell - such as
257 spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want
258 hledger to see them. This is done by enclosing them in single or dou‐
259 ble quotes, or by writing a backslash before them. Eg to match an ac‐
260 count name containing a space:
261 $ hledger register 'credit card'
263 or:
265 $ hledger register credit\ card
267 Windows users should keep in mind that cmd treats single quote as a
269 regular character, so you should be using double quotes exclusively.
270 PowerShell treats both single and double quotes as quotes.
271 Double escaping (regular expression metacharacters)
273 Characters significant in regular expressions (described below) - such
274 as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if
275 you don't want them to be interpreted by hledger's regular expression
276 engine. This is done by writing backslashes before them, but since
277 backslash is typically also a shell metacharacter, both shell-escaping
278 and regex-escaping will be needed. Eg to match a literal $ sign while
279 using the bash shell:
280 $ hledger balance cur:'\$'
282 or:
284 $ hledger balance cur:\\$
286 Triple escaping (for add-on commands)
288 When you use hledger to run an external add-on command (described be‐
289 low), one level of shell-escaping is lost from any options or arguments
290 intended for by the add-on command, so those need an extra level of
291 shell-escaping. Eg to match a literal $ sign while using the bash
292 shell and running an add-on command (ui):
293 $ hledger ui cur:'\\$'
295 or:
297 $ hledger ui cur:\\\\$
299 If you wondered why four backslashes, perhaps this helps:
301 unescaped: $
303 escaped: \$
304 double-escaped: \\$
305 triple-escaped: \\\\$
306 Or, you can avoid the extra escaping by running the add-on executable
308 directly:
309 $ hledger-ui cur:\\$
311 Less escaping
313 Options and arguments are sometimes used in places other than the shell
314 command line, where shell-escaping is not needed, so there you should
315 use one less level of escaping. Those places include:
316 • an @argumentfile
318 • hledger-ui's filter field
320 • hledger-web's search form
322 • GHCI's prompt (used by developers).
324 Unicode characters
326 hledger is expected to handle non-ascii characters correctly:
327 • they should be parsed correctly in input files and on the command
329 line, by all hledger tools (add, iadd, hledger-web's search/add/edit
330 forms, etc.)
331 • they should be displayed correctly by all hledger tools, and on-
333 screen alignment should be preserved.
334 This requires a well-configured environment. Here are some tips:
336 • A system locale must be configured, and it must be one that can de‐
338 code the characters being used. In bash, you can set a locale like
339 this: export LANG=en_US.UTF-8. There are some more details in Trou‐
340 bleshooting. This step is essential - without it, hledger will quit
341 on encountering a non-ascii character (as with all GHC-compiled pro‐
342 grams).
343 • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
345 must support unicode
346 • the terminal must be using a font which includes the required unicode
348 glyphs
349 • the terminal should be configured to display wide characters as dou‐
351 ble width (for report alignment)
352 • on Windows, for best results you should run hledger in the same kind
354 of environment in which it was built. Eg hledger built in the stan‐
355 dard CMD.EXE environment (like the binaries on our download page)
356 might show display problems when run in a cygwin or msys terminal,
357 and vice versa. (See eg #961).
358 Regular expressions
360 hledger uses regular expressions in a number of places:
361 • query terms, on the command line and in the hledger-web search form:
363 REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
364 • CSV rules conditional blocks: if REGEX ...
366 • account alias directives and options: alias /REGEX/ = REPLACEMENT,
368 --alias /REGEX/=REPLACEMENT
369 hledger's regular expressions come from the regex-tdfa library. If
371 they're not doing what you expect, it's important to know exactly what
372 they support:
373 1. they are case insensitive
375 2. they are infix matching (they do not need to match the entire thing
377 being matched)
378 3. they are POSIX ERE (extended regular expressions)
380 4. they also support GNU word boundaries (\b, \B, \<, \>)
382 5. they do not support backreferences; if you write \1, it will match
384 the digit 1. Except when doing text replacement, eg in account
385 aliases, where backreferences can be used in the replacement string
386 to reference capturing groups in the search regexp.
387 6. they do not support mode modifiers ((?s)), character classes (\w,
389 \d), or anything else not mentioned above.
390 Some things to note:
392 • In the alias directive and --alias option, regular expressions must
394 be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
395 these are not required.
396 • In queries, to match a regular expression metacharacter like $ as a
398 literal character, prepend a backslash. Eg to search for amounts
399 with the dollar sign in hledger-web, write cur:\$.
400 • On the command line, some metacharacters like $ have a special mean‐
402 ing to the shell and so must be escaped at least once more. See Spe‐
403 cial characters.
404
406 LEDGER_FILE The journal file path when not specified with -f.
407 On unix computers, the default value is: ~/.hledger.journal.
409 A more typical value is something like ~/finance/YYYY.journal, where
411 ~/finance is a version-controlled finance directory and YYYY is the
412 current year. Or, ~/finance/current.journal, where current.journal is
413 a symbolic link to YYYY.journal.
414 The usual way to set this permanently is to add a command to one of
416 your shell's startup files (eg ~/.profile):
417 export LEDGER_FILE=~/finance/current.journal`
419 On some Mac computers, there is a more thorough way to set environment
421 variables, that will also affect applications started from the GUI (eg,
422 Emacs started from a dock icon): In ~/.MacOSX/environment.plist, add an
423 entry like:
424 {
426 "LEDGER_FILE" : "~/finance/current.journal"
427 }
428 For this to take effect you might need to killall Dock, or reboot.
430 On Windows computers, the default value is probably C:\Users\YOUR‐
432 NAME\.hledger.journal. You can change this by running a command like
433 this in a powershell window (let us know if you need to be an Adminis‐
434 trator, and if this persists across a reboot):
435 > setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"
437 Or, change it in settings: see https://www.java.com/en/down‐
439 load/help/path.html.
440 COLUMNS The screen width used by the register command. Default: the
442 full terminal width.
443 NO_COLOR If this variable exists with any value, hledger will not use
445 ANSI color codes in terminal output. This is overriden by the
446 --color/--colour option.
447
449 hledger reads transactions from one or more data files. The default
450 data file is $HOME/.hledger.journal (or on Windows, something like
451 C:\Users\YOURNAME\.hledger.journal).
452 You can override this with the $LEDGER_FILE environment variable:
454 $ setenv LEDGER_FILE ~/finance/2016.journal
456 $ hledger stats
457 or with one or more -f/--file options:
459 $ hledger -f /some/file -f another_file stats
461 The file name - means standard input:
463 $ cat some.journal | hledger -f-
465 Data formats
467 Usually the data file is in hledger's journal format, but it can be in
468 any of the supported file formats, which currently are:
469 Reader: Reads: Used for file exten‐
471 sions:
472 ─────────────────────────────────────────────────────────────────────────────
473 journal hledger journal files and some Ledger .journal .j .hledger
474 journals, for transactions .ledger
475 time‐ timeclock files, for precise time log‐ .timeclock
476 clock ging
477 timedot timedot files, for approximate time .timedot
478 logging
479 csv comma/semicolon/tab/other-separated .csv .ssv .tsv
480 values, for data import
481 These formats are described in their own sections, below.
483 hledger detects the format automatically based on the file extensions
485 shown above. If it can't recognise the file extension, it assumes
486 journal format. So for non-journal files, it's important to use a
487 recognised file extension, so as to either read successfully or to show
488 relevant error messages.
489 You can also force a specific reader/format by prefixing the file path
491 with the format and a colon. Eg, to read a .dat file as csv format:
492 $ hledger -f csv:/some/csv-file.dat stats
494 Or to read stdin (-) as timeclock format:
496 $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-
498 Multiple files
500 You can specify multiple -f options, to read multiple files as one big
501 journal. There are some limitations with this:
502 • most directives do not affect sibling files
504 • balance assertions will not see any account balances from previous
506 files
507 If you need either of those things, you can
509 • use a single parent file which includes the others
511 • or concatenate the files into one before reading, eg: cat a.journal
513 b.journal | hledger -f- CMD.
514 Strict mode
516 hledger checks input files for valid data. By default, the most impor‐
517 tant errors are detected, while still accepting easy journal files
518 without a lot of declarations:
519 • Are the input files parseable, with valid syntax ?
521 • Are all transactions balanced ?
523 • Do all balance assertions pass ?
525 With the -s/--strict flag, additional checks are performed:
527 • Are all accounts posted to, declared with an account directive ?
529 (Account error checking)
530 • Are all commodities declared with a commodity directive ? (Commodity
532 error checking)
533 • Are all commodity conversions declared explicitly ?
535 You can use the check command to run individual checks -- the ones
537 listed above and some more.
538
540 Smart dates
541 hledger's user interfaces accept a flexible "smart date" syntax. Smart
542 dates allow some english words, can be relative to today's date, and
543 can have less-significant date parts omitted (defaulting to 1).
544 Examples:
546 2004/10/1, 2004-01-01, exact date, several separators allowed. Year
548 2004.9.1 is 4+ digits, month is 1-12, day is 1-31
549 2004 start of year
550 2004/10 start of month
552 10/1 month and day in current year
553 21 day in current month
554 october, oct start of month in current year
555 yesterday, today, tomor‐ -1, 0, 1 days from today
556 row
557 last/this/next -1, 0, 1 periods from the current period
558 day/week/month/quar‐
559 ter/year
560 in n n periods from the current period
561 days/weeks/months/quar‐
562 ters/years
563 n n periods from the current period
564 days/weeks/months/quar‐
565 ters/years ahead
566 n -n periods from the current period
567 days/weeks/months/quar‐
568 ters/years ago
569 20181201 8 digit YYYYMMDD with valid year month and day
570 201812 6 digit YYYYMM with valid year and month
571 Counterexamples - malformed digit sequences might give surprising re‐
573 sults:
574 201813 6 digits with an invalid month is parsed as start of
576 6-digit year
577 20181301 8 digits with an invalid month is parsed as start of
578 8-digit year
579 20181232 8 digits with an invalid day gives an error
580 201801012 9+ digits beginning with a valid YYYYMMDD gives an error
581 Note "today's date" can be overridden with the --today option, in case
583 it's needed for testing or for recreating old reports. (Except for pe‐
584 riodic transaction rules; those are not affected by --today.)
585 Report start & end date
587 By default, most hledger reports will show the full span of time repre‐
588 sented by the journal data. The report start date will be the earliest
589 transaction or posting date, and the report end date will be the latest
590 transaction, posting, or market price date.
591 Often you will want to see a shorter time span, such as the current
593 month. You can specify a start and/or end date using -b/--begin,
594 -e/--end, -p/--period or a date: query (described below). All of these
595 accept the smart date syntax.
596 Some notes:
598 • End dates are exclusive, as in Ledger, so you should write the date
600 after the last day you want to see in the report.
601 • As noted in reporting options: among start/end dates specified with
603 options, the last (i.e. right-most) option takes precedence.
604 • The effective report start and end dates are the intersection of the
606 start/end dates from options and that from date: queries. That is,
607 date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the
608 smallest common time span.
609 • A report interval (see below) will adjust start/end dates, when
611 needed, so that they fall on subperiod boundaries.
612 Examples:
614 -b 2016/3/17 begin on St. Patrick’s day 2016
616 -e 12/1 end at the start of december 1st of the current year
617 (11/30 will be the last date included)
618 -b thismonth all transactions on or after the 1st of the current month
619 -p thismonth all transactions in the current month
621 date:2016/3/17.. the above written as queries instead (.. can also be re‐
622 placed with -)
623 date:..12/1
624 date:thismonth..
625 date:thismonth
626 Report intervals
628 A report interval can be specified so that commands like register, bal‐
629 ance and activity become multi-period, showing each subperiod as a sep‐
630 arate row or column.
631 The following "standard" report intervals can be enabled by using their
633 corresponding flag:
634 • -D/--daily
636 • -W/--weekly
638 • -M/--monthly
640 • -Q/--quarterly
642 • -Y/--yearly
644 These standard intervals always start on natural interval boundaries:
646 eg --weekly starts on mondays, --monthly starts on the first of the
647 month, --yearly always starts on January 1st, etc.
648 Certain more complex intervals, and more flexible boundary dates, can
650 be specified by -p/--period. These are described in period expres‐
651 sions, below.
652 Report intervals can only be specified by the flags above, and not by
654 query arguments, currently.
655 Report intervals have another effect: multi-period reports are always
657 expanded to fill a whole number of subperiods. So if you use a report
658 interval (other than --daily), and you have specified a start or end
659 date, you may notice those dates being overridden (ie, the report
660 starts earlier than your requested start date, or ends later than your
661 requested end date). This is done to ensure "full" first and last sub‐
662 periods, so that all subperiods' numbers are comparable.
663 To summarise:
665 • In multiperiod reports, all subperiods are forced to be the same
667 length, to simplify reporting.
668 • Reports with the standard --weekly/--monthly/--quarterly/--yearly in‐
670 tervals are required to start on the first day of a week/month/quar‐
671 ter/year. We'd like more flexibility here but it isn't supported
672 yet.
673 • --period (below) can specify more complex intervals, starting on any
675 date.
676 Period expressions
678 The -p/--period option accepts period expressions, a shorthand way of
679 expressing a start date, end date, and/or report interval all at once.
680 Here's a basic period expression specifying the first quarter of 2009.
682 Note, hledger always treats start dates as inclusive and end dates as
683 exclusive:
684 -p "from 2009/1/1 to 2009/4/1"
686 Keywords like "from" and "to" are optional, and so are the spaces, as
688 long as you don't run two dates together. "to" can also be written as
689 ".." or "-". These are equivalent to the above:
690 -p "2009/1/1 2009/4/1"
692 -p2009/1/1to2009/4/1
693 -p2009/1/1..2009/4/1
694 Dates are smart dates, so if the current year is 2009, the above can
696 also be written as:
697 -p "1/1 4/1"
699 -p "january-apr"
700 -p "this year to 4/1"
701 If you specify only one date, the missing start or end date will be the
703 earliest or latest transaction in your journal:
704 -p "from 2009/1/1" everything after january
706 1, 2009
707 -p "from 2009/1" the same
708 -p "from 2009" the same
709 -p "to 2009" everything before january
710 1, 2009
711 A single date with no "from" or "to" defines both the start and end
713 date like so:
714 -p "2009" the year 2009; equivalent
716 to “2009/1/1 to 2010/1/1”
717 -p "2009/1" the month of jan; equiva‐
718 lent to “2009/1/1 to
719 2009/2/1”
720 -p "2009/1/1" just that day; equivalent
721 to “2009/1/1 to 2009/1/2”
722 Or you can specify a single quarter like so:
724 -p "2009Q1" first quarter of 2009,
726 equivalent to “2009/1/1 to
727 2009/4/1”
728 -p "q4" fourth quarter of the cur‐
729 rent year
730 Period expressions with a report interval
732 -p/--period's argument can also begin with, or entirely consist of, a
733 report interval. This should be separated from the start/end dates (if
734 any) by a space, or the word in. The basic intervals (which can also
735 be written as command line flags) are daily, weekly, monthly, quar‐
736 terly, and yearly. Some examples:
737 -p "weekly from 2009/1/1 to 2009/4/1"
739 -p "monthly in 2008"
740 -p "quarterly"
741 As mentioned above, the weekly, monthly, quarterly and yearly intervals
743 require a report start date that is the first day of a week, month,
744 quarter or year. And, report start/end dates will be expanded if
745 needed to span a whole number of intervals.
746 For example:
748 -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon‐
750 to 2009/4/1" day
751 -p "monthly in starts on 2018/11/01
752 2008/11/25"
753 -p "quarterly from starts on 2009/04/01, ends on 2009/06/30,
754 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009
755 -p "yearly from starts on 2009/01/01, first day of 2009
756 2009-12-29"
757 More complex report intervals
759 Some more complex kinds of interval are also supported in period ex‐
760 pressions:
761 • biweekly
763 • fortnightly
765 • bimonthly
767 • every day|week|month|quarter|year
769 • every N days|weeks|months|quarters|years
771 These too will cause report start/end dates to be expanded, if needed,
773 to span a whole number of intervals. Examples:
774 -p "bimonthly from 2008" periods will have boundaries on 2008/01/01,
776 2008/03/01, ...
777 -p "every 2 weeks" starts on closest preceding Monday
778 -p "every 5 months from periods will have boundaries on 2009/03/01,
779 2009/03" 2009/08/01, ...
780 Intervals with custom start date
782 All intervals mentioned above are required to start on their natural
783 calendar boundaries, but the following intervals can start on any date:
784 Weekly on custom day:
786 • every Nth day of week (th, nd, rd, or st are all accepted after the
788 number)
789 • every WEEKDAYNAME (full or three-letter english weekday name, case
791 insensitive)
792 Monthly on custom day:
794 • every Nth day [of month]
796 • every Nth WEEKDAYNAME [of month]
798 Yearly on custom day:
800 • every MM/DD [of year] (month number and day of month number)
802 • every MONTHNAME DDth [of year] (full or three-letter english month
804 name, case insensitive, and day of month number)
805 • every DDth MONTHNAME [of year] (equivalent to the above)
807 Examples:
809 -p "every 2nd day of periods will go from Tue to Tue
811 week"
812 -p "every Tue" same
813 -p "every 15th day" period boundaries will be on 15th of each
814 month
815 -p "every 2nd Monday" period boundaries will be on second Monday of
816 each month
817 -p "every 11/05" yearly periods with boundaries on 5th of No‐
818 vember
819 -p "every 5th November" same
820 -p "every Nov 5th" same
821 Show historical balances at end of the 15th day of each month (N is an
823 end date, exclusive as always):
824 $ hledger balance -H -p "every 16th day"
826 Group postings from the start of wednesday to end of the following
828 tuesday (N is both (inclusive) start date and (exclusive) end date):
829 $ hledger register checking -p "every 3rd day of week"
831 Periods or dates ?
833 Report intervals like the above are most often used with -p|--period,
834 to divide reports into multiple subperiods - each generated date marks
835 a subperiod boundary. Here, the periods between the dates are what's
836 important.
837 But report intervals can also be used with --forecast to generate fu‐
839 ture transactions, or with balance --budget to generate budget goal-
840 setting transactions. For these, the dates themselves are what mat‐
841 ters.
842 Events on multiple weekdays
844 The every WEEKDAYNAME form has a special variant with multiple day
845 names, comma-separated. Eg: every mon,thu,sat. Also, weekday and
846 weekendday are shorthand for mon,tue,wed,thu,fri and sat,sun respec‐
847 tively.
848 This form is mainly intended for use with --forecast, to generate peri‐
850 odic transactions on arbitrary days of the week. It may be less useful
851 with -p, since it divides each week into subperiods of unequal length.
852 (Because gaps between periods are not allowed; if you'd like to change
853 this, see #1632.)
854 Examples:
856 -p "every dates will be Mon, Wed, Fri; periods will be Mon-
858 mon,wed,fri" Tue, Wed-Thu, Fri-Sun
859 -p "every weekday" dates will be Mon, Tue, Wed, Thu, Fri; periods will
860 be Mon, Tue, Wed, Thu, Fri-Sun
861 -p "every weekend‐ dates will be Sat, Sun; periods will be Sat, Sun-Fri
862 day"
863
865 With the --depth NUM option (short form: -NUM), commands like account,
866 balance and register will show only the uppermost accounts in the ac‐
867 count tree, down to level NUM. Use this when you want a summary with
868 less detail. This flag has the same effect as a depth: query argument:
869 depth:2, --depth=2 or -2 are equivalent.
870
872 One of hledger's strengths is being able to quickly report on a precise
873 subset of your data. Most hledger commands accept optional query argu‐
874 ments to restrict their scope. The syntax is as follows:
875 • Zero or more space-separated query terms. These are most often ac‐
877 count name substrings:
878 utilities food:groceries
880 • Terms with spaces or other special characters should be enclosed in
882 quotes:
883 "personal care"
885 • Regular expressions are also supported:
887 "^expenses\b" "accounts (payable|receivable)"
889 • Add a query type prefix to match other parts of the data:
891 date:202012- desc:amazon cur:USD amt:">100" status:
893 • Add a not: prefix to negate a term:
895 not:cur:USD
897 Query types
899 Here are the types of query term available. Remember these can also be
900 prefixed with not: to convert them into a negative match.
901 acct:REGEX, REGEX
903 Match account names containing this (case insensitive) regular expres‐
904 sion. This is the default query type when there is no prefix, and reg‐
905 ular expression syntax is typically not needed, so usually we just
906 write an account name substring, like expenses or food.
907 amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
909 Match postings with a single-commodity amount equal to, less than, or
910 greater than N. (Postings with multi-commodity amounts are not tested
911 and will always match.) The comparison has two modes: if N is preceded
912 by a + or - sign (or is 0), the two signed numbers are compared. Oth‐
913 erwise, the absolute magnitudes are compared, ignoring sign.
914 code:REGEX
916 Match by transaction code (eg check number).
917 cur:REGEX
919 Match postings or transactions including any amounts whose cur‐
920 rency/commodity symbol is fully matched by REGEX. (For a partial
921 match, use .*REGEX.*). Note, to match special characters which are
922 regex-significant, you need to escape them with \. And for characters
923 which are significant to your shell you may need one more level of es‐
924 caping. So eg to match the dollar sign:
925 hledger print cur:\\$.
926 desc:REGEX
928 Match transaction descriptions.
929 date:PERIODEXPR
931 Match dates (or with the --date2 flag, secondary dates) within the
932 specified period. PERIODEXPR is a period expression with no report in‐
933 terval. Examples:
934 date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter.
935 date2:PERIODEXPR
937 Match secondary dates within the specified period (independent of the
938 --date2 flag).
939 depth:N
941 Match (or display, depending on command) accounts at or above this
942 depth.
943 note:REGEX
945 Match transaction notes (the part of the description right of |, or the
946 whole description if there's no |).
947 payee:REGEX
949 Match transaction payee/payer names (the part of the description left
950 of |, or the whole description if there's no |).
951 real:, real:0
953 Match real or virtual postings respectively.
954 status:, status:!, status:*
956 Match unmarked, pending, or cleared transactions respectively.
957 type:TYPECODES
959 Match by account type (see Declaring accounts > Account types). TYPE‐
960 CODES is one or more of the single-letter account type codes ALERXCV,
961 case insensitive. Note type:A and type:E will also match their respec‐
962 tive subtypes C (Cash) and V (Conversion). Certain kinds of account
963 alias can disrupt account types, see Rewriting accounts > Aliases and
964 account types.
965 tag:REGEX[=REGEX]
967 Match by tag name, and optionally also by tag value. (To match only by
968 value, use tag:.=REGEX.)
969 When querying by tag, note that:
971 • Accounts also inherit the tags of their parent accounts
973 • Postings also inherit the tags of their account and their transaction
975 • Transactions also acquire the tags of their postings.
977 (inacct:ACCTNAME
979 A special query term used automatically in hledger-web only: tells
980 hledger-web to show the transaction register for an account.)
981 Combining query terms
983 Most commands select things which match:
984 • any of the description terms AND
986 • any of the account terms AND
988 • any of the status terms AND
990 • all the other terms.
992 while the print command shows transactions which:
994 • match any of the description terms AND
996 • have any postings matching any of the positive account terms AND
998 • have no postings matching any of the negative account terms AND
1000 • match all the other terms.
1002 You can do more powerful queries (such as AND-ing two like terms) by
1004 running a first query with print, and piping the result into a second
1005 hledger command. Eg: how much of food expenses was paid with cash ?
1006 $ hledger print assets:cash | hledger -f- -I balance expenses:food
1008 If you are interested in full boolean expressions for queries, see
1010 #203.
1011 Queries and command options
1013 Some queries can also be expressed as command-line options: depth:2 is
1014 equivalent to --depth 2, date:2020 is equivalent to -p 2020, etc. When
1015 you mix command options and query arguments, generally the resulting
1016 query is their intersection.
1017 Queries and account aliases
1019 When account names are rewritten with --alias or alias, acct: will
1020 match either the old or the new account name.
1021 Queries and valuation
1023 When amounts are converted to other commodities in cost or value re‐
1024 ports, cur: and amt: match the old commodity symbol and the old amount
1025 quantity, not the new ones (except in hledger 1.22.0 where it's re‐
1026 versed, see #1625).
1027 Querying with account aliases
1029 When account names are rewritten with --alias or alias, note that acct:
1030 will match either the old or the new account name.
1031 Querying with cost or value
1033 When amounts are converted to other commodities in cost or value re‐
1034 ports, note that cur: matches the new commodity symbol, and not the old
1035 one, and amt: matches the new quantity, and not the old one. Note:
1036 this changed in hledger 1.22, previously it was the reverse, see the
1037 discussion at #1625.
1038
1040 This section is about recording the cost of things, in transactions
1041 where one commodity is exchanged for another. Eg an exchange of cur‐
1042 rency, or a stock purchase or sale. First, a quick glossary:
1043 • Conversion - an exchange of one currency or commodity for another.
1045 Eg a foreign currency exchange, or a purchase or sale of stock or
1046 cryptocurrency.
1047 • Conversion transaction - a transaction involving one or more conver‐
1049 sions.
1050 • Conversion rate - the cost per unit of one commodity in the other, ie
1052 the exchange rate.
1053 • Cost - how much of one commodity was paid to acquire the other. And
1055 more generally, in hledger docs: the amount exchanged in the "sec‐
1056 ondary" commodity (usually your base currency), whether in a purchase
1057 or a sale, and whether expressed per unit or in total. Or, the @/@@
1058 notation used to represent this.
1059 • Transaction price - another name for the cost expressed with
1061 hledger's cost notation.
1062 -B: Convert to cost
1064 As discussed a little further on in Transaction prices, when recording
1065 a transaction you can also record the amount's cost in another commod‐
1066 ity, by adding @ UNITPRICE or @@ TOTALPRICE.
1067 Then you can see a report with amounts converted to cost, by adding the
1069 -B/--cost flag. (Mnemonic: "B" from "cost Basis", as in Ledger). Eg:
1070 2022-01-01
1072 assets:dollars $-135 ; 135 dollars is exchanged for..
1073 assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each
1074 $ hledger bal -N
1076 $-135 assets:dollars
1077 €100 assets:euros
1078 $ hledger bal -N -B
1079 $-135 assets:dollars
1080 $135 assets:euros # <- the euros' cost
1081 Notes:
1083 -B is sensitive to the order of postings when a transaction price is
1085 inferred: the inferred price will be in the commodity of the last
1086 amount. So if example 3's postings are reversed, while the transaction
1087 is equivalent, -B shows something different:
1088 2022-01-01
1090 assets:dollars $-135 ; 135 dollars sold
1091 assets:euros €100 ; for 100 euros
1092 $ hledger bal -N -B
1094 €-100 assets:dollars # <- the dollars' selling price
1095 €100 assets:euros
1096 The @/@@ cost notation is convenient, but has some drawbacks: it does
1098 not truly balance the transaction, so it disrupts the accounting equa‐
1099 tion and tends to causes a non-zero total in balance reports.
1100 Equity conversion postings
1102 By contrast, conventional double entry bookkeeping (DEB) uses a differ‐
1103 ent notation: an extra pair of equity postings to balance conversion
1104 transactions. In this style, the above entry might be written:
1105 2022-01-01 one hundred euros purchased at $1.35 each
1107 assets:dollars $-135
1108 equity:conversion $135
1109 equity:conversion €-100
1110 assets:euros €100
1111 This style is more correct, but it's also more verbose and makes cost
1113 reporting more difficult for PTA tools.
1114 Happily, current hledger can read either notation, or convert one to
1116 the other when needed, so you can use the one you prefer.
1117 Inferring equity postings from cost
1119 With --infer-equity, hledger detects transactions written with PTA cost
1120 notation and adds equity conversion postings to them (and temporarily
1121 permits the coexistence of equity conversion postings and cost nota‐
1122 tion, which normally would cause an unbalanced transaction error). Eg:
1123 2022-01-01
1125 assets:dollars -$135
1126 assets:euros €100 @ $1.35
1127 $ hledger print --infer-equity
1129 2022-01-01
1130 assets:dollars $-135
1131 assets:euros €100 @ $1.35
1132 equity:conversion:$-€:€ €-100 ; generated-posting:
1133 equity:conversion:$-€:$ $135.00 ; generated-posting:
1134 The conversion account names can be changed with the conversion account
1136 type declaration.
1137 --infer-equity is useful when when transactions have been recorded us‐
1139 ing PTA cost notation, to help preserve the accounting equation and
1140 balance reports' zero total, or to produce more conventional journal
1141 entries for sharing with non-PTA-users.
1142 Experimental
1144 Inferring cost from equity postings
1146 The reverse operation is possible using --infer-costs, which detects
1147 transactions written with equity conversion postings and adds PTA cost
1148 notation to them (and temporarily permits the coexistence of equity
1149 conversion postings and cost notation). Eg:
1150 2022-01-01
1152 assets:dollars $-135
1153 equity:conversion $135
1154 equity:conversion €-100
1155 assets:euros €100
1156 $ hledger print --infer-costs
1158 2022-01-01
1159 assets:dollars $-135 @@ €100
1160 equity:conversion $135
1161 equity:conversion €-100
1162 assets:euros €100
1163 --infer-costs is useful when combined with -B/--cost, allowing cost re‐
1165 porting even when transactions have been recorded using equity post‐
1166 ings:
1167 $ hledger print --infer-costs -B
1169 2009-01-01
1170 assets:dollars €-100
1171 assets:euros €100
1172 Notes:
1174 Postings will be recognised as equity conversion postings if they are
1176 1. to account(s) declared with type V (Conversion; or if no such ac‐
1177 counts are declared, accounts named equity:conversion, equity:trade,
1178 equity:trading, or subaccounts of these) 2. adjacent 3. and exactly
1179 matching the amounts of two non-conversion postings.
1180 The total cost is appended to the first matching posting in the trans‐
1182 action. If you need to assign it to a different posting, or if you
1183 have several different sets of conversion postings in one transaction,
1184 you may need to write the costs explicitly yourself. Eg:
1185 2022-01-01
1187 assets:dollars $-135
1188 equity:conversion €-100
1189 equity:conversion $135
1190 assets:euros €100 @@ $135
1191 or:
1193 2022-01-01
1195 assets:dollars $-235
1196 assets:euros €100 @ $1.35 ; 100 euros bought for $1.35 each
1197 equity:conversion €-100
1198 equity:conversion $135
1199 assets:pounds £80 @@ $100 ; 80 pounds bought for $100 total
1200 equity:conversion £-80
1201 equity:conversion $100
1202 --infer-equity and --infer-costs can be used together, eg if you have a
1204 mixture of both notations.
1205 Experimental
1207 When to infer cost/equity
1209 Inferring equity postings or costs is still fairly new, so not enabled
1210 by default. We're not sure yet if that should change. Here are two
1211 suggestions to try, experience reports welcome:
1212 1. When you use -B, always use --infer-costs as well. Eg: hledger bal
1214 -B --infer-costs
1215 2. Always run hledger with both flags enabled. Eg: alias hl="hledger
1217 --infer-equity --infer-costs"
1218 How to record conversions
1220 Essentially there are four ways to record a conversion transaction in
1221 hledger. Here are all of them, with pros and cons.
1222 Conversion with implicit cost
1224 Let's assume 100 EUR is converted to 120 USD. You can just record the
1225 outflow (100 EUR) and inflow (120 USD) in the appropriate asset ac‐
1226 count:
1227 2021-01-01
1229 assets:cash -100 EUR
1230 assets:cash 120 USD
1231 hledger will assume this transaction is balanced, inferring that the
1233 conversion rate must be 1 EUR = 1.20 USD. You can see the inferred
1234 rate by using hledger print -x.
1235 Pro:
1237 • Concise, easy
1239 Con:
1241 • Less error checking - typos in amounts or commodity symbols may not
1243 be detected
1244 • Conversion rate is not clear
1246 • Disturbs the accounting equation, unless you add the --infer-equity
1248 flag
1249 You can prevent accidental implicit conversions due to a mistyped com‐
1251 modity symbol, by using hledger check commodities.
1252 You can prevent implicit conversions entirely, by using hledger check
1254 balancednoautoconversion, or -s/--strict.
1255 Conversion with explicit cost
1257 You can add the conversion rate using @ notation:
1258 2021-01-01
1260 assets:cash -100 EUR @ 1.20 USD
1261 assets:cash 120 USD
1262 Now hledger will check that 100 * 1.20 = 120, and would report an error
1264 otherwise.
1265 Pro:
1267 • Still concise
1269 • Makes the conversion rate clear
1271 • Provides more error checking
1273 Con:
1275 • Disturbs the accounting equation, unless you add the --infer-equity
1277 flag
1278 Conversion with equity postings
1280 In strict double entry bookkeeping, the above transaction is not bal‐
1281 anced in EUR or in USD, since some EUR disappears, and some USD ap‐
1282 pears. This violates the accounting equation (A+L+E=0), and prevents
1283 reports like balancesheetequity from showing a zero total.
1284 The proper way to make it balance is to add a balancing posting for
1286 each commodity, using an equity account:
1287 2021-01-01
1289 assets:cash -100 EUR
1290 equity:conversion 100 EUR
1291 equity:conversion -120 USD
1292 assets:cash 120 USD
1293 Pro:
1295 • Preserves the accounting equation
1297 • Keeps track of conversions and related gains/losses in one place
1299 • Standard, works in any double entry accounting system
1301 Con:
1303 • More verbose
1305 • Conversion rate is not obvious
1307 • Cost reporting requires adding the --infer-costs flag
1309 Conversion with equity postings and explicit cost
1311 Here both equity postings and @ notation are used together. hledger
1312 will usually complain about this redundancy, but when using the --in‐
1313 fer-costs flag it is accepted.
1314 2021-01-01
1316 assets:cash -100 EUR @ 1.20 USD
1317 equity:conversion 100 EUR
1318 equity:conversion -120 USD
1319 assets:cash 120 USD
1320 Pro:
1322 • Preserves the accounting equation
1324 • Keeps track of conversions and related gains/losses in one place
1326 • Makes the conversion rate clear
1328 • Provides more error checking
1330 Con:
1332 • Most verbose
1334 • Requires the --infer-costs flag
1336 • Not compatible with ledger
1338 Cost tips
1340 • Recording the conversion rate explicitly is good because it makes
1341 that clear and helps detect errors.
1342 • Recording equity postings is good because it is correct bookkeeping
1344 and preserves the accounting equation.
1345 • Combining these is possible by using the --infer-costs flag (which
1347 requires well-ordered postings).
1348 • When you want to see the cost (or sale proceeds) of things, use -B
1350 (or --cost). If you use equity conversion postings notation, use -B
1351 --infer-costs.
1352 • If you use PTA cost notation, and you want to see a balanced balance
1354 sheet or print correct journal entries, use --infer-equity.
1355 • Conversion to cost is performed before valuation (described next).
1357
1359 Instead of reporting amounts in their original commodity, hledger can
1360 convert them to cost/sale amount (using the conversion rate recorded in
1361 the transaction), and/or to market value (using some market price on a
1362 certain date). This is controlled by the --value=TYPE[,COMMODITY] op‐
1363 tion, which will be described below. We also provide the simpler -V
1364 and -X COMMODITY options, and often one of these is all you need:
1365 -V: Value
1367 The -V/--market flag converts amounts to market value in their default
1368 valuation commodity, using the market prices in effect on the valuation
1369 date(s), if any. More on these in a minute.
1370 -X: Value in specified commodity
1372 The -X/--exchange=COMM option is like -V, except you tell it which cur‐
1373 rency you want to convert to, and it tries to convert everything to
1374 that.
1375 Valuation date
1377 Since market prices can change from day to day, market value reports
1378 have a valuation date (or more than one), which determines which market
1379 prices will be used.
1380 For single period reports, if an explicit report end date is specified,
1382 that will be used as the valuation date; otherwise the valuation date
1383 is the journal's end date.
1384 For multiperiod reports, each column/period is valued on the last day
1386 of the period, by default.
1387 Market prices
1389 To convert a commodity A to its market value in another commodity B,
1390 hledger looks for a suitable market price (exchange rate) as follows,
1391 in this order of preference :
1392 1. A declared market price or inferred market price: A's latest market
1394 price in B on or before the valuation date as declared by a P direc‐
1395 tive, or (with the --infer-market-prices flag) inferred from trans‐
1396 action prices.
1397 2. A reverse market price: the inverse of a declared or inferred market
1399 price from B to A.
1400 3. A forward chain of market prices: a synthetic price formed by com‐
1402 bining the shortest chain of "forward" (only 1 above) market prices,
1403 leading from A to B.
1404 4. Any chain of market prices: a chain of any market prices, including
1406 both forward and reverse prices (1 and 2 above), leading from A to
1407 B.
1408 There is a limit to the length of these price chains; if hledger
1410 reaches that length without finding a complete chain or exhausting all
1411 possibilities, it will give up (with a "gave up" message visible in
1412 --debug=2 output). That limit is currently 1000.
1413 Amounts for which no suitable market price can be found, are not con‐
1415 verted.
1416 --infer-market-prices: market prices from transactions
1418 Normally, market value in hledger is fully controlled by, and requires,
1419 P directives in your journal. Since adding and updating those can be a
1420 chore, and since transactions usually take place at close to market
1421 value, why not use the recorded transaction prices as additional market
1422 prices (as Ledger does) ? We could produce value reports without need‐
1423 ing P directives at all.
1424 Adding the --infer-market-prices flag to -V, -X or --value enables
1426 this. So for example, hledger bs -V --infer-market-prices will get
1427 market prices both from P directives and from transactions. (And if
1428 both occur on the same day, the P directive takes precedence).
1429 There is a downside: value reports can sometimes be affected in confus‐
1431 ing/undesired ways by your journal entries. If this happens to you,
1432 read all of this Valuation section carefully, and try adding --debug or
1433 --debug=2 to troubleshoot.
1434 --infer-market-prices can infer market prices from:
1436 • multicommodity transactions with explicit prices (@/@@)
1438 • multicommodity transactions with implicit prices (no @, two commodi‐
1440 ties, unbalanced). (With these, the order of postings matters.
1441 hledger print -x can be useful for troubleshooting.)
1442 • but not, currently, from "more correct" multicommodity transactions
1444 (no @, multiple commodities, balanced).
1445 There is another limitation (bug) currently: when a valuation commodity
1447 is not specified, prices inferred with --infer-market-prices do not
1448 help select a default valuation commodity, as P prices would. So con‐
1449 version might not happen because no valuation commodity was detected
1450 (--debug=2 will show this). To be safe, specify the valuation commmod‐
1451 ity, eg:
1452 • -X EUR --infer-market-prices, not -V --infer-market-prices
1454 • --value=then,EUR --infer-market-prices, not --value=then --infer-mar‐
1456 ket-prices
1457 Valuation commodity
1459 When you specify a valuation commodity (-X COMM or --value TYPE,COMM):
1460 hledger will convert all amounts to COMM, wherever it can find a suit‐
1461 able market price (including by reversing or chaining prices).
1462 When you leave the valuation commodity unspecified (-V or --value
1464 TYPE):
1465 For each commodity A, hledger picks a default valuation commodity as
1466 follows, in this order of preference:
1467 1. The price commodity from the latest P-declared market price for A on
1469 or before valuation date.
1470 2. The price commodity from the latest P-declared market price for A on
1472 any date. (Allows conversion to proceed when there are inferred
1473 prices before the valuation date.)
1474 3. If there are no P directives at all (any commodity or date) and the
1476 --infer-market-prices flag is used: the price commodity from the
1477 latest transaction-inferred price for A on or before valuation date.
1478 This means:
1480 • If you have P directives, they determine which commodities -V will
1482 convert, and to what.
1483 • If you have no P directives, and use the --infer-market-prices flag,
1485 transaction prices determine it.
1486 Amounts for which no valuation commodity can be found are not con‐
1488 verted.
1489 Simple valuation examples
1491 Here are some quick examples of -V:
1492 ; one euro is worth this many dollars from nov 1
1494 P 2016/11/01 € $1.10
1495 ; purchase some euros on nov 3
1497 2016/11/3
1498 assets:euros €100
1499 assets:checking
1500 ; the euro is worth fewer dollars by dec 21
1502 P 2016/12/21 € $1.03
1503 How many euros do I have ?
1505 $ hledger -f t.j bal -N euros
1507 €100 assets:euros
1508 What are they worth at end of nov 3 ?
1510 $ hledger -f t.j bal -N euros -V -e 2016/11/4
1512 $110.00 assets:euros
1513 What are they worth after 2016/12/21 ? (no report end date specified,
1515 defaults to today)
1516 $ hledger -f t.j bal -N euros -V
1518 $103.00 assets:euros
1519 --value: Flexible valuation
1521 -V and -X are special cases of the more general --value option:
1522 --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD.
1524 COMM is an optional commodity symbol.
1525 Shows amounts converted to:
1526 - default valuation commodity (or COMM) using market prices at posting dates
1527 - default valuation commodity (or COMM) using market prices at period end(s)
1528 - default valuation commodity (or COMM) using current market prices
1529 - default valuation commodity (or COMM) using market prices at some date
1530 The TYPE part selects cost or value and valuation date:
1532 --value=then
1534 Convert amounts to their value in the default valuation commod‐
1535 ity, using market prices on each posting's date.
1536 --value=end
1538 Convert amounts to their value in the default valuation commod‐
1539 ity, using market prices on the last day of the report period
1540 (or if unspecified, the journal's end date); or in multiperiod
1541 reports, market prices on the last day of each subperiod.
1542 --value=now
1544 Convert amounts to their value in the default valuation commod‐
1545 ity using current market prices (as of when report is gener‐
1546 ated).
1547 --value=YYYY-MM-DD
1549 Convert amounts to their value in the default valuation commod‐
1550 ity using market prices on this date.
1551 To select a different valuation commodity, add the optional ,COMM part:
1553 a comma, then the target commodity's symbol. Eg: --value=now,EUR.
1554 hledger will do its best to convert amounts to this commodity, deducing
1555 market prices as described above.
1556 More valuation examples
1558 Here are some examples showing the effect of --value, as seen with
1559 print:
1560 P 2000-01-01 A 1 B
1562 P 2000-02-01 A 2 B
1563 P 2000-03-01 A 3 B
1564 P 2000-04-01 A 4 B
1565 2000-01-01
1567 (a) 1 A @ 5 B
1568 2000-02-01
1570 (a) 1 A @ 6 B
1571 2000-03-01
1573 (a) 1 A @ 7 B
1574 Show the cost of each posting:
1576 $ hledger -f- print --cost
1578 2000-01-01
1579 (a) 5 B
1580 2000-02-01
1582 (a) 6 B
1583 2000-03-01
1585 (a) 7 B
1586 Show the value as of the last day of the report period (2000-02-29):
1588 $ hledger -f- print --value=end date:2000/01-2000/03
1590 2000-01-01
1591 (a) 2 B
1592 2000-02-01
1594 (a) 2 B
1595 With no report period specified, that shows the value as of the last
1597 day of the journal (2000-03-01):
1598 $ hledger -f- print --value=end
1600 2000-01-01
1601 (a) 3 B
1602 2000-02-01
1604 (a) 3 B
1605 2000-03-01
1607 (a) 3 B
1608 Show the current value (the 2000-04-01 price is still in effect today):
1610 $ hledger -f- print --value=now
1612 2000-01-01
1613 (a) 4 B
1614 2000-02-01
1616 (a) 4 B
1617 2000-03-01
1619 (a) 4 B
1620 Show the value on 2000/01/15:
1622 $ hledger -f- print --value=2000-01-15
1624 2000-01-01
1625 (a) 1 B
1626 2000-02-01
1628 (a) 1 B
1629 2000-03-01
1631 (a) 1 B
1632 You may need to explicitly set a commodity's display style, when re‐
1634 verse prices are used. Eg this output might be surprising:
1635 P 2000-01-01 A 2B
1637 2000-01-01
1639 a 1B
1640 b
1641 $ hledger print -x -X A
1643 2000-01-01
1644 a 0
1645 b 0
1646 Explanation: because there's no amount or commodity directive specify‐
1648 ing a display style for A, 0.5A gets the default style, which shows no
1649 decimal digits. Because the displayed amount looks like zero, the com‐
1650 modity symbol and minus sign are not displayed either. Adding a com‐
1651 modity directive sets a more useful display style for A:
1652 P 2000-01-01 A 2B
1654 commodity 0.00A
1655 2000-01-01
1657 a 1B
1658 b
1659 $ hledger print -X A
1661 2000-01-01
1662 a 0.50A
1663 b -0.50A
1664 Interaction of valuation and queries
1666 When matching postings based on queries in the presence of valuation,
1667 the following happens.
1668 1. The query is separated into two parts:
1670 1. the currency (cur:) or amount (amt:).
1672 2. all other parts.
1674 2. The postings are matched to the currency and amount queries based on
1676 pre-valued amounts.
1677 3. Valuation is applied to the postings.
1679 4. The postings are matched to the other parts of the query based on
1681 post-valued amounts.
1682 See: 1625
1684 Effect of valuation on reports
1686 Here is a reference for how valuation is supposed to affect each part
1687 of hledger's reports (and a glossary). (It's wide, you'll have to
1688 scroll sideways.) It may be useful when troubleshooting. If you find
1689 problems, please report them, ideally with a reproducible example. Re‐
1690 lated: #329, #1083.
1691 Report -B, --cost -V, -X --value=then --value=end --value=DATE,
1693 type --value=now
1694 ────────────────────────────────────────────────────────────────────────────────────────────
1695 print
1696 posting cost value at re‐ value at posting value at re‐ value at
1697 amounts port end or date port or DATE/today
1698 today journal end
1699 balance unchanged unchanged unchanged unchanged unchanged
1700 asser‐
1701 tions/as‐
1702 signments
1703 register
1705 starting cost value at re‐ valued at day value at re‐ value at
1706 balance port or each historical port or DATE/today
1707 (-H) journal end posting was made journal end
1708 starting cost value at day valued at day value at day value at
1709 balance before re‐ each historical before re‐ DATE/today
1710 (-H) with port or posting was made port or
1711 report journal journal
1712 interval start start
1713 posting cost value at re‐ value at posting value at re‐ value at
1714 amounts port or date port or DATE/today
1715 journal end journal end
1716 summary summarised value at pe‐ sum of postings value at pe‐ value at
1717 posting cost riod ends in interval, val‐ riod ends DATE/today
1718 amounts ued at interval
1719 with re‐ start
1720 port in‐
1721 terval
1722 running sum/average sum/average sum/average of sum/average sum/average
1723 total/av‐ of displayed of displayed displayed values of displayed of displayed
1724 erage values values values values
1725 balance
1727 (bs, bse,
1728 cf, is)
1729 balance sums of value at re‐ value at posting value at re‐ value at
1730 changes costs port end or date port or DATE/today of
1731 today of journal end sums of post‐
1732 sums of of sums of ings
1733 postings postings
1734 budget like balance like balance like balance like bal‐ like balance
1736 amounts changes changes changes ances changes
1737 (--bud‐
1738 get)
1739 grand to‐ sum of dis‐ sum of dis‐ sum of displayed sum of dis‐ sum of dis‐
1740 tal played val‐ played val‐ valued played val‐ played values
1741 ues ues ues
1742 balance
1744 (bs, bse,
1745 cf, is)
1746 with re‐
1747 port in‐
1748 terval
1749 starting sums of value at re‐ sums of values of value at re‐ sums of post‐
1750 balances costs of port start postings before port start ings before
1751 (-H) postings be‐ of sums of report start at of sums of report start
1752 fore report all postings respective post‐ all postings
1753 start before re‐ ing dates before re‐
1754 port start port start
1755 balance sums of same as sums of values of balance value at
1756 changes costs of --value=end postings in pe‐ change in DATE/today of
1757 (bal, is, postings in riod at respec‐ each period, sums of post‐
1758 bs period tive posting valued at ings
1759 --change, dates period ends
1760 cf
1761 --change)
1762 end bal‐ sums of same as sums of values of period end value at
1763 ances costs of --value=end postings from be‐ balances, DATE/today of
1764 (bal -H, postings fore period start valued at sums of post‐
1765 is --H, from before to period end at period ends ings
1766 bs, cf) report start respective post‐
1767 to period ing dates
1768 end
1769 budget like balance like balance like balance like bal‐ like balance
1770 amounts changes/end changes/end changes/end bal‐ ances changes/end
1771 (--bud‐ balances balances ances balances
1772 get)
1773 row to‐ sums, aver‐ sums, aver‐ sums, averages of sums, aver‐ sums, aver‐
1774 tals, row ages of dis‐ ages of dis‐ displayed values ages of dis‐ ages of dis‐
1775 averages played val‐ played val‐ played val‐ played values
1776 (-T, -A) ues ues ues
1777 column sums of dis‐ sums of dis‐ sums of displayed sums of dis‐ sums of dis‐
1778 totals played val‐ played val‐ values played val‐ played values
1779 ues ues ues
1780 grand to‐ sum, average sum, average sum, average of sum, average sum, average
1781 tal, of column of column column totals of column of column to‐
1782 grand av‐ totals totals totals tals
1783 erage
1784 --cumulative is omitted to save space, it works like -H but with a zero
1787 starting balance.
1788 Glossary:
1790 cost calculated using price(s) recorded in the transaction(s).
1792 value market value using available market price declarations, or the
1794 unchanged amount if no conversion rate can be found.
1795 report start
1797 the first day of the report period specified with -b or -p or
1798 date:, otherwise today.
1799 report or journal start
1801 the first day of the report period specified with -b or -p or
1802 date:, otherwise the earliest transaction date in the journal,
1803 otherwise today.
1804 report end
1806 the last day of the report period specified with -e or -p or
1807 date:, otherwise today.
1808 report or journal end
1810 the last day of the report period specified with -e or -p or
1811 date:, otherwise the latest transaction date in the journal,
1812 otherwise today.
1813 report interval
1815 a flag (-D/-W/-M/-Q/-Y) or period expression that activates the
1816 report's multi-period mode (whether showing one or many subperi‐
1817 ods).
1818
1820 Normally hledger sums amounts, and organizes them in a hierarchy, based
1821 on account name. The --pivot FIELD option causes it to sum and orga‐
1822 nize hierarchy based on the value of some other field instead. FIELD
1823 can be: status, code, description, payee, note, or the full name (case
1824 insensitive) of any tag. As with account names, values containing
1825 colon:separated:parts will be displayed hierarchically in reports.
1826 --pivot is a general option affecting all reports; you can think of
1828 hledger transforming the journal before any other processing, replacing
1829 every posting's account name with the value of the specified field on
1830 that posting, inheriting it from the transaction or using a blank value
1831 if it's not present.
1832 An example:
1834 2016/02/16 Member Fee Payment
1836 assets:bank account 2 EUR
1837 income:member fees -2 EUR ; member: John Doe
1838 Normal balance report showing account names:
1840 $ hledger balance
1842 2 EUR assets:bank account
1843 -2 EUR income:member fees
1844 --------------------
1845 0
1846 Pivoted balance report, using member: tag values instead:
1848 $ hledger balance --pivot member
1850 2 EUR
1851 -2 EUR John Doe
1852 --------------------
1853 0
1854 One way to show only amounts with a member: value (using a query, de‐
1856 scribed below):
1857 $ hledger balance --pivot member tag:member=.
1859 -2 EUR John Doe
1860 --------------------
1861 -2 EUR
1862 Another way (the acct: query matches against the pivoted "account
1864 name"):
1865 $ hledger balance --pivot member acct:.
1867 -2 EUR John Doe
1868 --------------------
1869 -2 EUR
1870
1872 Output destination
1873 hledger commands send their output to the terminal by default. You can
1874 of course redirect this, eg into a file, using standard shell syntax:
1875 $ hledger print > foo.txt
1877 Some commands (print, register, stats, the balance commands) also pro‐
1879 vide the -o/--output-file option, which does the same thing without
1880 needing the shell. Eg:
1881 $ hledger print -o foo.txt
1883 $ hledger print -o - # write to stdout (the default)
1884 hledger can optionally produce debug output (if enabled with --de‐
1886 bug=N); this goes to stderr, and is not affected by -o/--output-file.
1887 If you need to capture it, use shell redirects, eg: hledger bal --de‐
1888 bug=3 >file 2>&1.
1889 Output styling
1891 hledger commands can produce colour output when the terminal supports
1892 it. This is controlled by the --color/--colour option: - if the
1893 --color/--colour option is given a value of yes or always (or no or
1894 never), colour will (or will not) be used; - otherwise, if the NO_COLOR
1895 environment variable is set, colour will not be used; - otherwise,
1896 colour will be used if the output (terminal or file) supports it.
1897 hledger commands can also use unicode box-drawing characters to produce
1899 prettier tables and output. This is controlled by the --pretty option:
1900 - if the --pretty option is given a value of yes or always (or no or
1901 never), unicode characters will (or will not) be used; - otherwise,
1902 unicode characters will not be used.
1903 Output format
1905 Some commands offer additional output formats, other than the usual
1906 plain text terminal output. Here are those commands and the formats
1907 currently supported:
1908 - txt csv html json sql
1910 ─────────────────────────────────────────────
1911 aregister Y Y Y
1912 balance Y 1 Y 1 Y 1,2 Y
1913 bal‐ Y 1 Y 1 Y 1 Y
1914 ancesheet
1915 bal‐ Y 1 Y 1 Y 1 Y
1916 ancesheete‐
1917 quity
1918 cashflow Y 1 Y 1 Y 1 Y
1919 incomes‐ Y 1 Y 1 Y 1 Y
1920 tatement
1921 print Y Y Y Y
1922 register Y Y Y
1923 • 1 Also affected by the balance commands' --layout option.
1925 • 2 balance does not support html output without a report interval or
1927 with --budget.
1928 The output format is selected by the -O/--output-format=FMT option:
1930 $ hledger print -O csv # print CSV on stdout
1932 or by the filename extension of an output file specified with the
1934 -o/--output-file=FILE.FMT option:
1935 $ hledger balancesheet -o foo.csv # write CSV to foo.csv
1937 The -O option can be combined with -o to override the file extension,
1939 if needed:
1940 $ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt
1942 CSV output
1944 • In CSV output, digit group marks (such as thousands separators) are
1945 disabled automatically.
1946 HTML output
1948 • HTML output can be styled by an optional hledger.css file in the same
1949 directory.
1950 JSON output
1952 • Not yet much used; real-world feedback is welcome.
1953 • Our JSON is rather large and verbose, as it is quite a faithful rep‐
1955 resentation of hledger's internal data types. To understand the
1956 JSON, read the Haskell type definitions, which are mostly in
1957 https://github.com/simonmichael/hledger/blob/master/hledger-
1958 lib/Hledger/Data/Types.hs.
1959 • hledger represents quantities as Decimal values storing up to 255
1961 significant digits, eg for repeating decimals. Such numbers can
1962 arise in practice (from automatically-calculated transaction prices),
1963 and would break most JSON consumers. So in JSON, we show quantities
1964 as simple Numbers with at most 10 decimal places. We don't limit the
1965 number of integer digits, but that part is under your control. We
1966 hope this approach will not cause problems in practice; if you find
1967 otherwise, please let us know. (Cf #1195)
1968 SQL output
1970 • Not yet much used; real-world feedback is welcome.
1971 • SQL output is expected to work with sqlite, MySQL and PostgreSQL
1973 • SQL output is structured with the expectations that statements will
1975 be executed in the empty database. If you already have tables cre‐
1976 ated via SQL output of hledger, you would probably want to either
1977 clear tables of existing data (via delete or truncate SQL statements)
1978 or drop tables completely as otherwise your postings will be duped.
1979 Commodity styles
1981 The display style of a commodity/currency is inferred according to the
1982 rules described in Commodity display style. The inferred display style
1983 can be overridden by an optional -c/--commodity-style option (Excep‐
1984 tions: as is the case for inferred styles, price amounts, and all
1985 amounts displayed by the print command, will be displayed with all of
1986 their decimal digits visible, regardless of the specified precision).
1987 For example, the following will override the display style for dollars.
1988 $ hledger print -c '$1.000,0'
1990 The format specification of the style is identical to the commodity
1992 display style specification for the commodity directive. The command
1993 line option can be supplied repeatedly to override the display style
1994 for multiple commodity/currency symbols.
1995
1997 hledger provides a number of commands for producing reports and manag‐
1998 ing your data. Run hledger with no arguments to list the commands
1999 available, and hledger CMD to run a command. CMD can be the full com‐
2000 mand name, or its standard abbreviation shown in the commands list, or
2001 any unambiguous prefix of the name. Eg: hledger bal.
2002 Here are the built-in commands, with the most often-used in bold:
2004 Data entry:
2006 These data entry commands are the only ones which can modify your jour‐
2008 nal file.
2009 • add - add transactions using guided prompts
2011 • import - add any new transactions from other files (eg csv)
2013 Data management:
2015 • check - check for various kinds of issue in the data
2017 • close (equity) - generate balance-resetting transactions
2019 • diff - compare account transactions in two journal files
2021 • rewrite - generate extra postings, similar to print --auto
2023 Financial statements:
2025 • aregister (areg) - show transactions in a particular account
2027 • balancesheet (bs) - show assets, liabilities and net worth
2029 • balancesheetequity (bse) - show assets, liabilities and equity
2031 • cashflow (cf) - show changes in liquid assets
2033 • incomestatement (is) - show revenues and expenses
2035 • roi - show return on investments
2037 Miscellaneous reports:
2039 • accounts - show account names
2041 • activity - show postings-per-interval bar charts
2043 • balance (bal) - show balance changes/end balances/budgets in any ac‐
2045 counts
2046 • codes - show transaction codes
2048 • commodities - show commodity/currency symbols
2050 • descriptions - show unique transaction descriptions
2052 • files - show input file paths
2054 • help - show hledger user manuals in several formats
2056 • notes - show unique note segments of transaction descriptions
2058 • payees - show unique payee segments of transaction descriptions
2060 • prices - show market price records
2062 • print - show transactions (journal entries)
2064 • print-unique - show only transactions with unique descriptions
2066 • register (reg) - show postings in one or more accounts & running to‐
2068 tal
2069 • register-match - show a recent posting that best matches a descrip‐
2071 tion
2072 • stats - show journal statistics
2074 • tags - show tag names
2076 • test - run self tests
2078 Add-on commands:
2080 Programs or scripts named hledger-SOMETHING in your PATH are add-on
2082 commands; these appear in the commands list with a + mark. The follow‐
2083 ing add-on commands can be installed, eg by the hledger-install script:
2084 • ui - hledger's official curses-style TUI
2086 • web - hledger's official web UI
2088 • iadd - a popular alternative to hledger's add command.
2090 • interest - generates interest transactions
2092 • stockquotes - downloads market prices. (Alpha quality, needs your
2094 help.)
2095 Next, the detailed command docs, in alphabetical order.
2097 accounts
2099 accounts
2100 Show account names.
2101 This command lists account names, either declared with account direc‐
2103 tives (--declared), posted to (--used), or both (the default). With
2104 query arguments, only matched account names and account names refer‐
2105 enced by matched postings are shown.
2106 It shows a flat list by default. With --tree, it uses indentation to
2108 show the account hierarchy. In flat mode you can add --drop N to omit
2109 the first few account name components. Account names can be depth-
2110 clipped with depth:N or --depth N or -N.
2111 With --types, it also shows each account's type, if it's known. (See
2113 Declaring accounts > Account types.)
2114 With --positions, it also shows the file and line number of each ac‐
2116 count's declaration, if any, and the account's overall declaration or‐
2117 der; these may be useful when troubleshooting account display order.
2118 With --directives, it adds the account keyword, showing valid account
2120 directives which can be pasted into a journal file.
2121 Examples:
2123 $ hledger accounts
2125 assets:bank:checking
2126 assets:bank:saving
2127 assets:cash
2128 expenses:food
2129 expenses:supplies
2130 income:gifts
2131 income:salary
2132 liabilities:debts
2133 activity
2135 activity
2136 Show an ascii barchart of posting counts per interval.
2137 The activity command displays an ascii histogram showing transaction
2139 counts by day, week, month or other reporting interval (by day is the
2140 default). With query arguments, it counts only matched transactions.
2141 Examples:
2143 $ hledger activity --quarterly
2145 2008-01-01 **
2146 2008-04-01 *******
2147 2008-07-01
2148 2008-10-01 **
2149 add
2151 add
2152 Prompt for transactions and add them to the journal. Any arguments
2153 will be used as default inputs for the first N prompts.
2154 Many hledger users edit their journals directly with a text editor, or
2156 generate them from CSV. For more interactive data entry, there is the
2157 add command, which prompts interactively on the console for new trans‐
2158 actions, and appends them to the main journal file (which should be in
2159 journal format). Existing transactions are not changed. This is one
2160 of the few hledger commands that writes to the journal file (see also
2161 import).
2162 To use it, just run hledger add and follow the prompts. You can add as
2164 many transactions as you like; when you are finished, enter . or press
2165 control-d or control-c to exit.
2166 Features:
2168 • add tries to provide useful defaults, using the most similar (by de‐
2170 scription) recent transaction (filtered by the query, if any) as a
2171 template.
2172 • You can also set the initial defaults with command line arguments.
2174 • Readline-style edit keys can be used during data entry.
2176 • The tab key will auto-complete whenever possible - accounts, descrip‐
2178 tions, dates (yesterday, today, tomorrow). If the input area is
2179 empty, it will insert the default value.
2180 • If the journal defines a default commodity, it will be added to any
2182 bare numbers entered.
2183 • A parenthesised transaction code may be entered following a date.
2185 • Comments and tags may be entered following a description or amount.
2187 • If you make a mistake, enter < at any prompt to go one step backward.
2189 • Input prompts are displayed in a different colour when the terminal
2191 supports it.
2192 Example (see the tutorial for a detailed explanation):
2194 $ hledger add
2196 Adding transactions to journal file /src/hledger/examples/sample.journal
2197 Any command line arguments will be used as defaults.
2198 Use tab key to complete, readline keys to edit, enter to accept defaults.
2199 An optional (CODE) may follow transaction dates.
2200 An optional ; COMMENT may follow descriptions or amounts.
2201 If you make a mistake, enter < at any prompt to go one step backward.
2202 To end a transaction, enter . when prompted.
2203 To quit, enter . at a date prompt or press control-d or control-c.
2204 Date [2015/05/22]:
2205 Description: supermarket
2206 Account 1: expenses:food
2207 Amount 1: $10
2208 Account 2: assets:checking
2209 Amount 2 [$-10.0]:
2210 Account 3 (or . or enter to finish this transaction): .
2211 2015/05/22 supermarket
2212 expenses:food $10
2213 assets:checking $-10.0
2214 Save this transaction to the journal ? [y]:
2216 Saved.
2217 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
2218 Date [2015/05/22]: <CTRL-D> $
2219 On Microsoft Windows, the add command makes sure that no part of the
2221 file path ends with a period, as that would cause problems (#1056).
2222 aregister
2224 aregister, areg
2225 Show the transactions and running historical balance of a single ac‐
2226 count, with each transaction displayed as one line.
2227 aregister shows the overall transactions affecting a particular account
2229 (and any subaccounts). Each report line represents one transaction in
2230 this account. Transactions before the report start date are always in‐
2231 cluded in the running balance (--historical mode is always on).
2232 This is a more "real world", bank-like view than the register command
2234 (which shows individual postings, possibly from multiple accounts, not
2235 necessarily in historical mode). As a quick rule of thumb: - use areg‐
2236 ister for reviewing and reconciling real-world asset/liability accounts
2237 - use register for reviewing detailed revenues/expenses.
2238 aregister requires one argument: the account to report on. You can
2240 write either the full account name, or a case-insensitive regular ex‐
2241 pression which will select the alphabetically first matched account.
2242 (Eg if you have assets:aaa:checking and assets:bbb:checking accounts,
2243 hledger areg checking would select assets:aaa:checking.)
2244 Transactions involving subaccounts of this account will also be shown.
2246 aregister ignores depth limits, so its final total will always match a
2247 balance report with similar arguments.
2248 Any additional arguments form a query which will filter the transac‐
2250 tions shown. Note some queries will disturb the running balance, caus‐
2251 ing it to be different from the account's real-world running balance.
2252 An example: this shows the transactions and historical running balance
2254 during july, in the first account whose name contains "checking":
2255 $ hledger areg checking date:jul
2257 Each aregister line item shows:
2259 • the transaction's date (or the relevant posting's date if different,
2261 see below)
2262 • the names of all the other account(s) involved in this transaction
2264 (probably abbreviated)
2265 • the total change to this account's balance from this transaction
2267 • the account's historical running balance after this transaction.
2269 Transactions making a net change of zero are not shown by default; add
2271 the -E/--empty flag to show them.
2272 For performance reasons, column widths are chosen based on the first
2274 1000 lines; this means unusually wide values in later lines can cause
2275 visual discontinuities as column widths are adjusted. If you want to
2276 ensure perfect alignment, at the cost of more time and memory, use the
2277 --align-all flag.
2278 This command also supports the output destination and output format op‐
2280 tions. The output formats supported are txt, csv, and json.
2281 aregister and custom posting dates
2283 Transactions whose date is outside the report period can still be
2284 shown, if they have a posting to this account dated inside the report
2285 period. (And in this case it's the posting date that is shown.) This
2286 ensures that aregister can show an accurate historical running balance,
2287 matching the one shown by register -H with the same arguments.
2288 To filter strictly by transaction date instead, add the --txn-dates
2290 flag. If you use this flag and some of your postings have custom
2291 dates, it's probably best to assume the running balance is wrong.
2292 balance
2294 balance, bal
2295 Show accounts and their balances.
2296 balance is one of hledger's oldest and most versatile commands, for
2298 listing account balances, balance changes, values, value changes and
2299 more, during one time period or many. Generally it shows a table, with
2300 rows representing accounts, and columns representing periods.
2301 Note there are some higher-level variants of the balance command with
2303 convenient defaults, which can be simpler to use: balancesheet, bal‐
2304 ancesheetequity, cashflow and incomestatement. When you need more con‐
2305 trol, then use balance.
2306 balance features
2308 Here's a quick overview of the balance command's features, followed by
2309 more detailed descriptions and examples. Many of these work with the
2310 higher-level commands as well.
2311 balance can show..
2313 • accounts as a list (-l) or a tree (-t)
2315 • optionally depth-limited (-[1-9])
2317 • sorted by declaration order and name, or by amount
2319 ..and their..
2321 • balance changes (the default)
2323 • or actual and planned balance changes (--budget)
2325 • or value of balance changes (-V)
2327 • or change of balance values (--valuechange)
2329 • or unrealised capital gain/loss (--gain)
2331 ..in..
2333 • one time period (the whole journal period by default)
2335 • or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
2337 ..either..
2339 • per period (the default)
2341 • or accumulated since report start date (--cumulative)
2343 • or accumulated since account creation (--historical/-H)
2345 ..possibly converted to..
2347 • cost (--value=cost[,COMM]/--cost/-B)
2349 • or market value, as of transaction dates (--value=then[,COMM])
2351 • or at period ends (--value=end[,COMM])
2353 • or now (--value=now)
2355 • or at some other date (--value=YYYY-MM-DD)
2357 ..with..
2359 • totals (-T), averages (-A), percentages (-%), inverted sign (--in‐
2361 vert)
2362 • rows and columns swapped (--transpose)
2364 • another field used as account name (--pivot)
2366 • custom-formatted line items (single-period reports only) (--format)
2368 • commodities displayed on the same line or multiple lines (--layout)
2370 This command supports the output destination and output format options,
2372 with output formats txt, csv, json, and (multi-period reports only:)
2373 html. In txt output in a colour-supporting terminal, negative amounts
2374 are shown in red.
2375 The --related/-r flag shows the balance of the other postings in the
2377 transactions of the postings which would normally be shown.
2378 Simple balance report
2380 With no arguments, balance shows a list of all accounts and their
2381 change of balance - ie, the sum of posting amounts, both inflows and
2382 outflows - during the entire period of the journal. For real-world ac‐
2383 counts, this should also match their end balance at the end of the
2384 journal period (more on this below).
2385 Accounts are sorted by declaration order if any, and then alphabeti‐
2387 cally by account name. For instance (using examples/sample.journal):
2388 $ hledger -f examples/sample.journal bal
2390 $1 assets:bank:saving
2391 $-2 assets:cash
2392 $1 expenses:food
2393 $1 expenses:supplies
2394 $-1 income:gifts
2395 $-1 income:salary
2396 $1 liabilities:debts
2397 --------------------
2398 0
2399 Accounts with a zero balance (and no non-zero subaccounts, in tree mode
2401 - see below) are hidden by default. Use -E/--empty to show them (re‐
2402 vealing assets:bank:checking here):
2403 $ hledger -f examples/sample.journal bal -E
2405 0 assets:bank:checking
2406 $1 assets:bank:saving
2407 $-2 assets:cash
2408 $1 expenses:food
2409 $1 expenses:supplies
2410 $-1 income:gifts
2411 $-1 income:salary
2412 $1 liabilities:debts
2413 --------------------
2414 0
2415 The total of the amounts displayed is shown as the last line, unless
2417 -N/--no-total is used.
2418 Filtered balance report
2420 You can show fewer accounts, a different time period, totals from
2421 cleared transactions only, etc. by using query arguments or options to
2422 limit the postings being matched. Eg:
2423 $ hledger -f examples/sample.journal bal --cleared assets date:200806
2425 $-2 assets:cash
2426 --------------------
2427 $-2
2428 List or tree mode
2430 By default, or with -l/--flat, accounts are shown as a flat list with
2431 their full names visible, as in the examples above.
2432 With -t/--tree, the account hierarchy is shown, with subaccounts'
2434 "leaf" names indented below their parent:
2435 $ hledger -f examples/sample.journal balance
2437 $-1 assets
2438 $1 bank:saving
2439 $-2 cash
2440 $2 expenses
2441 $1 food
2442 $1 supplies
2443 $-2 income
2444 $-1 gifts
2445 $-1 salary
2446 $1 liabilities:debts
2447 --------------------
2448 0
2449 Notes:
2451 • "Boring" accounts are combined with their subaccount for more compact
2453 output, unless --no-elide is used. Boring accounts have no balance
2454 of their own and just one subaccount (eg assets:bank and liabilities
2455 above).
2456 • All balances shown are "inclusive", ie including the balances from
2458 all subaccounts. Note this means some repetition in the output,
2459 which requires explanation when sharing reports with non-plaintextac‐
2460 counting-users. A tree mode report's final total is the sum of the
2461 top-level balances shown, not of all the balances shown.
2462 • Each group of sibling accounts (ie, under a common parent) is sorted
2464 separately.
2465 Depth limiting
2467 With a depth:NUM query, or --depth NUM option, or just -NUM (eg: -3)
2468 balance reports will show accounts only to the specified depth, hiding
2469 the deeper subaccounts. This can be useful for getting an overview
2470 without too much detail.
2471 Account balances at the depth limit always include the balances from
2473 any deeper subaccounts (even in list mode). Eg, limiting to depth 1:
2474 $ hledger -f examples/sample.journal balance -1
2476 $-1 assets
2477 $2 expenses
2478 $-2 income
2479 $1 liabilities
2480 --------------------
2481 0
2482 Dropping top-level accounts
2484 You can also hide one or more top-level account name parts, using
2485 --drop NUM. This can be useful for hiding repetitive top-level account
2486 names:
2487 $ hledger -f examples/sample.journal bal expenses --drop 1
2489 $1 food
2490 $1 supplies
2491 --------------------
2492 $2
2493 Multi-period balance report
2495 With a report interval (set by the -D/--daily, -W/--weekly,
2496 -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), bal‐
2497 ance shows a tabular report, with columns representing successive time
2498 periods (and a title):
2499 $ hledger -f examples/sample.journal bal --quarterly income expenses -E
2501 Balance changes in 2008:
2502 || 2008q1 2008q2 2008q3 2008q4
2504 ===================++=================================
2505 expenses:food || 0 $1 0 0
2506 expenses:supplies || 0 $1 0 0
2507 income:gifts || 0 $-1 0 0
2508 income:salary || $-1 0 0 0
2509 -------------------++---------------------------------
2510 || $-1 $1 0 0
2511 Notes:
2513 • The report's start/end dates will be expanded, if necessary, to fully
2515 encompass the displayed subperiods (so that the first and last subpe‐
2516 riods have the same duration as the others).
2517 • Leading and trailing periods (columns) containing all zeroes are not
2519 shown, unless -E/--empty is used.
2520 • Accounts (rows) containing all zeroes are not shown, unless
2522 -E/--empty is used.
2523 • Amounts with many commodities are shown in abbreviated form, unless
2525 --no-elide is used. (experimental)
2526 • Average and/or total columns can be added with the -A/--average and
2528 -T/--row-total flags.
2529 • The --transpose flag can be used to exchange rows and columns.
2531 • The --pivot FIELD option causes a different transaction field to be
2533 used as "account name". See PIVOTING.
2534 Multi-period reports with many periods can be too wide for easy viewing
2536 in the terminal. Here are some ways to handle that:
2537 • Hide the totals row with -N/--no-total
2539 • Convert to a single currency with -V
2541 • Maximize the terminal window
2543 • Reduce the terminal's font size
2545 • View with a pager like less, eg: hledger bal -D --color=yes | less
2547 -RS
2548 • Output as CSV and use a CSV viewer like visidata (hledger bal -D -O
2550 csv | vd -f csv), Emacs' csv-mode (M-x csv-mode, C-c C-a), or a
2551 spreadsheet (hledger bal -D -o a.csv && open a.csv)
2552 • Output as HTML and view with a browser: hledger bal -D -o a.html &&
2554 open a.html
2555 Showing declared accounts
2557 With --declared, accounts which have been declared with an account di‐
2558 rective will be included in the balance report, even if they have no
2559 transactions. (Since they will have a zero balance, you will also need
2560 -E/--empty to see them.)
2561 More precisely, leaf declared accounts (with no subaccounts) will be
2563 included, since those are usually the more useful in reports.
2564 The idea of this is to be able to see a useful "complete" balance re‐
2566 port, even when you don't have transactions in all of your declared ac‐
2567 counts yet.
2568 Data layout
2570 The --layout option affects how multi-commodity amounts are displayed,
2571 and some other things, influencing the overall layout of the report
2572 data:
2573 • --layout=wide[,WIDTH]: commodities are shown on a single line, possi‐
2575 bly elided to the specified width
2576 • --layout=tall: each commodity is shown on a separate line
2578 • --layout=bare: amounts are shown as bare numbers, with commodity sym‐
2580 bols in a separate column
2581 • --layout=tidy: data is normalised to tidy form, with one row per data
2583 value. We currently support this with CSV output only. In tidy
2584 mode, totals and row averages are disabled (-N/--no-total is implied
2585 and -T/--row-total and -A/--average will be ignored).
2586 These --layout modes are supported with some but not all of the output
2588 formats:
2589 - txt csv html json sql
2591 ─────────────────────────────────────
2592 wide Y Y Y
2593 tall Y Y Y
2594 bare Y Y Y
2595 tidy Y
2596 Examples:
2598 • Wide layout. With many commodities, reports can be very wide:
2600 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
2602 Balance changes in 2012-01-01..2014-12-31:
2603 || 2012 2013 2014 Total
2605 ==================++====================================================================================================================================================================================================================
2606 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
2607 ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
2608 || 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
2609 • Limited wide layout. A width limit reduces the width, but some com‐
2611 modities will be hidden:
2612 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
2614 Balance changes in 2012-01-01..2014-12-31:
2615 || 2012 2013 2014 Total
2617 ==================++===========================================================================================================================
2618 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..
2619 ------------------++---------------------------------------------------------------------------------------------------------------------------
2620 || 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..
2621 • Tall layout. Each commodity gets a new line (may be different in
2623 each column), and account names are repeated:
2624 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall
2626 Balance changes in 2012-01-01..2014-12-31:
2627 || 2012 2013 2014 Total
2629 ==================++==================================================
2630 Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
2631 Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
2632 Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD
2633 Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
2634 Assets:US:ETrade || 18.00 VHT 294.00 VHT
2635 ------------------++--------------------------------------------------
2636 || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD
2637 || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT
2638 || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD
2639 || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA
2640 || 18.00 VHT 294.00 VHT
2641 • Bare layout. Commodity symbols are kept in one column, each commod‐
2643 ity gets its own report row, account names are repeated:
2644 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare
2646 Balance changes in 2012-01-01..2014-12-31:
2647 || Commodity 2012 2013 2014 Total
2649 ==================++=============================================
2650 Assets:US:ETrade || GLD 0 70.00 0 70.00
2651 Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00
2652 Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50
2653 Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00
2654 Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00
2655 ------------------++---------------------------------------------
2656 || GLD 0 70.00 0 70.00
2657 || ITOT 10.00 18.00 -11.00 17.00
2658 || USD 337.18 -98.12 4881.44 5120.50
2659 || VEA 12.00 10.00 14.00 36.00
2660 || VHT 106.00 18.00 170.00 294.00
2661 • Bare layout also affects CSV output, which is useful for producing
2663 data that is easier to consume, eg when making charts:
2664 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
2666 "account","commodity","balance"
2667 "Assets:US:ETrade","GLD","70.00"
2668 "Assets:US:ETrade","ITOT","17.00"
2669 "Assets:US:ETrade","USD","5120.50"
2670 "Assets:US:ETrade","VEA","36.00"
2671 "Assets:US:ETrade","VHT","294.00"
2672 "total","GLD","70.00"
2673 "total","ITOT","17.00"
2674 "total","USD","5120.50"
2675 "total","VEA","36.00"
2676 "total","VHT","294.00"
2677 • Tidy layout produces normalised "tidy data", where every variable is
2679 a column and each row represents a single data point (see
2680 https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-
2681 data.html). This kind of data is the easiest to process with other
2682 software:
2683 $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
2685 "account","period","start_date","end_date","commodity","value"
2686 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"
2687 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"
2688 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"
2689 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"
2690 "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"
2691 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"
2692 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"
2693 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"
2694 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"
2695 "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"
2696 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"
2697 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"
2698 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"
2699 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
2700 "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
2701 Sorting by amount
2703 With -S/--sort-amount, accounts with the largest (most positive) bal‐
2704 ances are shown first. Eg: hledger bal expenses -MAS shows your big‐
2705 gest averaged monthly expenses first. When more than one commodity is
2706 present, they will be sorted by the alphabetically earliest commodity
2707 first, and then by subsequent commodities (if an amount is missing a
2708 commodity, it is treated as 0).
2709 Revenues and liability balances are typically negative, however, so -S
2711 shows these in reverse order. To work around this, you can add --in‐
2712 vert to flip the signs. (Or, use one of the higher-level reports,
2713 which flip the sign automatically. Eg: hledger incomestatement -MAS).
2714 Percentages
2716 With -%/--percent, balance reports show each account's value expressed
2717 as a percentage of the (column) total:
2718 $ hledger -f examples/sample.journal bal expenses -Q -%
2720 Balance changes in 2008:
2721 || 2008Q1 2008Q2 2008Q3 2008Q4
2723 ===================++=================================
2724 expenses:food || 0 50.0 % 0 0
2725 expenses:supplies || 0 50.0 % 0 0
2726 -------------------++---------------------------------
2727 || 0 100.0 % 0 0
2728 Note it is not useful to calculate percentages if the amounts in a col‐
2730 umn have mixed signs. In this case, make a separate report for each
2731 sign, eg:
2732 $ hledger bal -% amt:`>0`
2734 $ hledger bal -% amt:`<0`
2735 Similarly, if the amounts in a column have mixed commodities, convert
2737 them to one commodity with -B, -V, -X or --value, or make a separate
2738 report for each commodity:
2739 $ hledger bal -% cur:\\$
2741 $ hledger bal -% cur:€
2742 Balance change, end balance
2744 It's important to be clear on the meaning of the numbers shown in bal‐
2745 ance reports. Here is some terminology we use:
2746 A balance change is the net amount added to, or removed from, an ac‐
2748 count during some period.
2749 An end balance is the amount accumulated in an account as of some date
2751 (and some time, but hledger doesn't store that; assume end of day in
2752 your timezone). It is the sum of previous balance changes.
2753 We call it a historical end balance if it includes all balance changes
2755 since the account was created. For a real world account, this means it
2756 will match the "historical record", eg the balances reported in your
2757 bank statements or bank web UI. (If they are correct!)
2758 In general, balance changes are what you want to see when reviewing
2760 revenues and expenses, and historical end balances are what you want to
2761 see when reviewing or reconciling asset, liability and equity accounts.
2762 balance shows balance changes by default. To see accurate historical
2764 end balances:
2765 1. Initialise account starting balances with an "opening balances"
2767 transaction (a transfer from equity to the account), unless the
2768 journal covers the account's full lifetime.
2769 2. Include all of of the account's prior postings in the report, by not
2771 specifying a report start date, or by using the -H/--historical
2772 flag. (-H causes report start date to be ignored when summing post‐
2773 ings.)
2774 Balance report types
2776 For more flexible reporting, there are three important option groups:
2777 hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]
2779 ...
2780 The first two are the most important: calculation type selects the ba‐
2782 sic calculation to perform for each table cell, while accumulation type
2783 says which postings should be included in each cell's calculation.
2784 Typically one or both of these are selected by default, so you don't
2785 need to write them explicitly. A valuation type can be added if you
2786 want to convert the basic report to value or cost.
2787 Calculation type:
2789 The basic calculation to perform for each table cell. It is one of:
2790 • --sum : sum the posting amounts (default)
2792 • --budget : like --sum but also show a goal amount
2794 • --valuechange : show the change in period-end historical balance val‐
2796 ues (caused by deposits, withdrawals, and/or market price fluctua‐
2797 tions)
2798 • --gain : show the unrealised capital gain/loss, (the current valued
2800 balance minus each amount's original cost)
2801 Accumulation type:
2803 Which postings should be included in each cell's calculation. It is
2804 one of:
2805 • --change : postings from column start to column end, ie within the
2807 cell's period. Typically used to see revenues/expenses. (default
2808 for balance, incomestatement)
2809 • --cumulative : postings from report start to column end, eg to show
2811 changes accumulated since the report's start date. Rarely used.
2812 • --historical/-H : postings from journal start to column end, ie all
2814 postings from account creation to the end of the cell's period. Typ‐
2815 ically used to see historical end balances of assets/liabilities/eq‐
2816 uity. (default for balancesheet, balancesheetequity, cashflow)
2817 Valuation type:
2819 Which kind of valuation, valuation date(s) and optionally a target val‐
2820 uation commodity to use. It is one of:
2821 • no valuation, show amounts in their original commodities (default)
2823 • --value=cost[,COMM] : no valuation, show amounts converted to cost
2825 • --value=then[,COMM] : show value at transaction dates
2827 • --value=end[,COMM] : show value at period end date(s) (default with
2829 --valuechange, --gain)
2830 • --value=now[,COMM] : show value at today's date
2832 • --value=YYYY-MM-DD[,COMM] : show value at another date
2834 or one of their aliases: --cost/-B, --market/-V or --exchange/-X.
2836 Most combinations of these options should produce reasonable reports,
2838 but if you find any that seem wrong or misleading, let us know. The
2839 following restrictions are applied:
2840 • --valuechange implies --value=end
2842 • --valuechange makes --change the default when used with the bal‐
2844 ancesheet/balancesheetequity commands
2845 • --cumulative or --historical disables --row-total/-T
2847 For reference, here is what the combinations of accumulation and valua‐
2849 tion show:
2850 Valua‐ no valuation --value= then --value= end --value= YYYY-
2852 tion: MM-DD /now
2853 >Accumu‐
2854 lation:
2855 v
2856 ────────────────────────────────────────────────────────────────────────────────────
2857 --change change in period sum of posting- period-end DATE-value of
2858 date market val‐ value of change change in pe‐
2859 ues in period in period riod
2860 --cumu‐ change from re‐ sum of posting- period-end DATE-value of
2861 lative port start to date market val‐ value of change change from
2862 period end ues from report from report report start
2863 start to period start to period to period end
2864 end end
2865 --his‐ change from sum of posting- period-end DATE-value of
2866 torical journal start to date market val‐ value of change change from
2867 /-H period end (his‐ ues from journal from journal journal start
2868 torical end bal‐ start to period start to period to period end
2869 ance) end end
2870 Useful balance reports
2872 Some frequently used balance options/reports are:
2873 • bal -M revenues expenses
2875 Show revenues/expenses in each month. Also available as the incomes‐
2876 tatement command.
2877 • bal -M -H assets liabilities
2879 Show historical asset/liability balances at each month end. Also
2880 available as the balancesheet command.
2881 • bal -M -H assets liabilities equity
2883 Show historical asset/liability/equity balances at each month end.
2884 Also available as the balancesheetequity command.
2885 • bal -M assets not:receivable
2887 Show changes to liquid assets in each month. Also available as the
2888 cashflow command.
2889 Also:
2891 • bal -M expenses -2 -SA
2893 Show monthly expenses summarised to depth 2 and sorted by average
2894 amount.
2895 • bal -M --budget expenses
2897 Show monthly expenses and budget goals.
2898 • bal -M --valuechange investments
2900 Show monthly change in market value of investment assets.
2901 • bal investments --valuechange -D date:lastweek amt:'>1000' -STA
2903 [--invert]
2904 Show top gainers [or losers] last week
2905 Budget report
2907 The --budget report type activates extra columns showing any budget
2908 goals for each account and period. The budget goals are defined by pe‐
2909 riodic transactions. This is very useful for comparing planned and ac‐
2910 tual income, expenses, time usage, etc.
2911 For example, you can take average monthly expenses in the common ex‐
2913 pense categories to construct a minimal monthly budget:
2914 ;; Budget
2916 ~ monthly
2917 income $2000
2918 expenses:food $400
2919 expenses:bus $50
2920 expenses:movies $30
2921 assets:bank:checking
2922 ;; Two months worth of expenses
2924 2017-11-01
2925 income $1950
2926 expenses:food $396
2927 expenses:bus $49
2928 expenses:movies $30
2929 expenses:supplies $20
2930 assets:bank:checking
2931 2017-12-01
2933 income $2100
2934 expenses:food $412
2935 expenses:bus $53
2936 expenses:gifts $100
2937 assets:bank:checking
2938 You can now see a monthly budget report:
2940 $ hledger balance -M --budget
2942 Budget performance in 2017/11/01-2017/12/31:
2943 || Nov Dec
2945 ======================++====================================================
2946 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2947 assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2948 assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2949 expenses || $495 [ 103% of $480] $565 [ 118% of $480]
2950 expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
2951 expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
2952 expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
2953 income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
2954 ----------------------++----------------------------------------------------
2955 || 0 [ 0] 0 [ 0]
2956 This is different from a normal balance report in several ways:
2958 • Only accounts with budget goals during the report period are shown,
2960 by default.
2961 • In each column, in square brackets after the actual amount, budget
2963 goal amounts are shown, and the actual/goal percentage. (Note: bud‐
2964 get goals should be in the same commodity as the actual amount.)
2965 • All parent accounts are always shown, even in list mode. Eg assets,
2967 assets:bank, and expenses above.
2968 • Amounts always include all subaccounts, budgeted or unbudgeted, even
2970 in list mode.
2971 This means that the numbers displayed will not always add up! Eg above,
2973 the expenses actual amount includes the gifts and supplies transac‐
2974 tions, but the expenses:gifts and expenses:supplies accounts are not
2975 shown, as they have no budget amounts declared.
2976 This can be confusing. When you need to make things clearer, use the
2978 -E/--empty flag, which will reveal all accounts including unbudgeted
2979 ones, giving the full picture. Eg:
2980 $ hledger balance -M --budget --empty
2982 Budget performance in 2017/11/01-2017/12/31:
2983 || Nov Dec
2985 ======================++====================================================
2986 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2987 assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2988 assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2989 expenses || $495 [ 103% of $480] $565 [ 118% of $480]
2990 expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
2991 expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
2992 expenses:gifts || 0 $100
2993 expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
2994 expenses:supplies || $20 0
2995 income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
2996 ----------------------++----------------------------------------------------
2997 || 0 [ 0] 0 [ 0]
2998 You can roll over unspent budgets to next period with --cumulative:
3000 $ hledger balance -M --budget --cumulative
3002 Budget performance in 2017/11/01-2017/12/31:
3003 || Nov Dec
3005 ======================++====================================================
3006 assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
3007 assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
3008 assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
3009 expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
3010 expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
3011 expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
3012 expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
3013 income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
3014 ----------------------++----------------------------------------------------
3015 || 0 [ 0] 0 [ 0]
3016 For more examples and notes, see Budgeting.
3018 Budget report start date
3020 This might be a bug, but for now: when making budget reports, it's a
3021 good idea to explicitly set the report's start date to the first day of
3022 a reporting period, because a periodic rule like ~ monthly generates
3023 its transactions on the 1st of each month, and if your journal has no
3024 regular transactions on the 1st, the default report start date could
3025 exclude that budget goal, which can be a little surprising. Eg here
3026 the default report period is just the day of 2020-01-15:
3027 ~ monthly in 2020
3029 (expenses:food) $500
3030 2020-01-15
3032 expenses:food $400
3033 assets:checking
3034 $ hledger bal expenses --budget
3036 Budget performance in 2020-01-15:
3037 || 2020-01-15
3039 ==============++============
3040 <unbudgeted> || $400
3041 --------------++------------
3042 || $400
3043 To avoid this, specify the budget report's period, or at least the
3045 start date, with -b/-e/-p/date:, to ensure it includes the budget goal
3046 transactions (periodic transactions) that you want. Eg, adding -b
3047 2020/1/1 to the above:
3048 $ hledger bal expenses --budget -b 2020/1/1
3050 Budget performance in 2020-01-01..2020-01-15:
3051 || 2020-01-01..2020-01-15
3053 ===============++========================
3054 expenses:food || $400 [80% of $500]
3055 ---------------++------------------------
3056 || $400 [80% of $500]
3057 Budgets and subaccounts
3059 You can add budgets to any account in your account hierarchy. If you
3060 have budgets on both parent account and some of its children, then bud‐
3061 get(s) of the child account(s) would be added to the budget of their
3062 parent, much like account balances behave.
3063 In the most simple case this means that once you add a budget to any
3065 account, all its parents would have budget as well.
3066 To illustrate this, consider the following budget:
3068 ~ monthly from 2019/01
3070 expenses:personal $1,000.00
3071 expenses:personal:electronics $100.00
3072 liabilities
3073 With this, monthly budget for electronics is defined to be $100 and
3075 budget for personal expenses is an additional $1000, which implicitly
3076 means that budget for both expenses:personal and expenses is $1100.
3077 Transactions in expenses:personal:electronics will be counted both to‐
3079 wards its $100 budget and $1100 of expenses:personal , and transactions
3080 in any other subaccount of expenses:personal would be counted towards
3081 only towards the budget of expenses:personal.
3082 For example, let's consider these transactions:
3084 ~ monthly from 2019/01
3086 expenses:personal $1,000.00
3087 expenses:personal:electronics $100.00
3088 liabilities
3089 2019/01/01 Google home hub
3091 expenses:personal:electronics $90.00
3092 liabilities $-90.00
3093 2019/01/02 Phone screen protector
3095 expenses:personal:electronics:upgrades $10.00
3096 liabilities
3097 2019/01/02 Weekly train ticket
3099 expenses:personal:train tickets $153.00
3100 liabilities
3101 2019/01/03 Flowers
3103 expenses:personal $30.00
3104 liabilities
3105 As you can see, we have transactions in expenses:personal:electron‐
3107 ics:upgrades and expenses:personal:train tickets, and since both of
3108 these accounts are without explicitly defined budget, these transac‐
3109 tions would be counted towards budgets of expenses:personal:electronics
3110 and expenses:personal accordingly:
3111 $ hledger balance --budget -M
3113 Budget performance in 2019/01:
3114 || Jan
3116 ===============================++===============================
3117 expenses || $283.00 [ 26% of $1100.00]
3118 expenses:personal || $283.00 [ 26% of $1100.00]
3119 expenses:personal:electronics || $100.00 [ 100% of $100.00]
3120 liabilities || $-283.00 [ 26% of $-1100.00]
3121 -------------------------------++-------------------------------
3122 || 0 [ 0]
3123 And with --empty, we can get a better picture of budget allocation and
3125 consumption:
3126 $ hledger balance --budget -M --empty
3128 Budget performance in 2019/01:
3129 || Jan
3131 ========================================++===============================
3132 expenses || $283.00 [ 26% of $1100.00]
3133 expenses:personal || $283.00 [ 26% of $1100.00]
3134 expenses:personal:electronics || $100.00 [ 100% of $100.00]
3135 expenses:personal:electronics:upgrades || $10.00
3136 expenses:personal:train tickets || $153.00
3137 liabilities || $-283.00 [ 26% of $-1100.00]
3138 ----------------------------------------++-------------------------------
3139 || 0 [ 0]
3140 Selecting budget goals
3142 The budget report evaluates periodic transaction rules to generate spe‐
3143 cial "goal transactions", which generate the goal amounts for each ac‐
3144 count in each report subperiod. When troubleshooting, you can use the
3145 print command to show these as forecasted transactions:
3146 $ hledger print --forecast=BUDGETREPORTPERIOD tag:generated
3148 By default, the budget report uses all available periodic transaction
3150 rules to generate goals. This includes rules with a different report
3151 interval from your report. Eg if you have daily, weekly and monthly
3152 periodic rules, all of these will contribute to the goals in a monthly
3153 budget report.
3154 You can select a subset of periodic rules by providing an argument to
3156 the --budget flag. --budget=DESCPAT will match all periodic rules
3157 whose description contains DESCPAT, a case-insensitive substring (not a
3158 regular expression or query). This means you can give your periodic
3159 rules descriptions (remember that two spaces are needed), and then se‐
3160 lect from multiple budgets defined in your journal.
3161 Customising single-period balance reports
3163 For single-period balance reports displayed in the terminal (only), you
3164 can use --format FMT to customise the format and content of each line.
3165 Eg:
3166 $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
3168 assets $-1
3169 bank:saving $1
3170 cash $-2
3171 expenses $2
3172 food $1
3173 supplies $1
3174 income $-2
3175 gifts $-1
3176 salary $-1
3177 liabilities:debts $1
3178 ---------------------------------
3179 0
3180 The FMT format string (plus a newline) specifies the formatting applied
3182 to each account/balance pair. It may contain any suitable text, with
3183 data fields interpolated like so:
3184 %[MIN][.MAX](FIELDNAME)
3186 • MIN pads with spaces to at least this width (optional)
3188 • MAX truncates at this width (optional)
3190 • FIELDNAME must be enclosed in parentheses, and can be one of:
3192 • depth_spacer - a number of spaces equal to the account's depth, or
3194 if MIN is specified, MIN * depth spaces.
3195 • account - the account's name
3197 • total - the account's balance/posted total, right justified
3199 Also, FMT can begin with an optional prefix to control how multi-com‐
3201 modity amounts are rendered:
3202 • %_ - render on multiple lines, bottom-aligned (the default)
3204 • %^ - render on multiple lines, top-aligned
3206 • %, - render on one line, comma-separated
3208 There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef‐
3210 fect, instead %(account) has indentation built in. Experimentation may
3211 be needed to get pleasing results.
3212 Some example formats:
3214 • %(total) - the account's total
3216 • %-20.20(account) - the account's name, left justified, padded to 20
3218 characters and clipped at 20 characters
3219 • %,%-50(account) %25(total) - account name padded to 50 characters,
3221 total padded to 20 characters, with multiple commodities rendered on
3222 one line
3223 • %20(total) %2(depth_spacer)%-(account) - the default format for the
3225 single-column balance report
3226 balancesheet
3228 balancesheet, bs
3229 This command displays a balance sheet, showing historical ending bal‐
3230 ances of asset and liability accounts. (To see equity as well, use the
3231 balancesheetequity command.) Amounts are shown with normal positive
3232 sign, as in conventional financial statements.
3233 This report shows accounts declared with the Asset, Cash or Liability
3235 type (see account types). Or if no such accounts are declared, it
3236 shows top-level accounts named asset or liability (case insensitive,
3237 plurals allowed) and their subaccounts.
3238 Example:
3240 $ hledger balancesheet
3242 Balance Sheet
3243 Assets:
3245 $-1 assets
3246 $1 bank:saving
3247 $-2 cash
3248 --------------------
3249 $-1
3250 Liabilities:
3252 $1 liabilities:debts
3253 --------------------
3254 $1
3255 Total:
3257 --------------------
3258 0
3259 This command is a higher-level variant of the balance command, and sup‐
3261 ports many of that command's features, such as multi-period reports.
3262 It is similar to hledger balance -H assets liabilities, but with
3263 smarter account detection, and liabilities displayed with their sign
3264 flipped.
3265 This command also supports the output destination and output format op‐
3267 tions The output formats supported are txt, csv, html, and (experimen‐
3268 tal) json.
3269 balancesheetequity
3271 balancesheetequity, bse
3272 This command displays a balance sheet, showing historical ending bal‐
3273 ances of asset, liability and equity accounts. Amounts are shown with
3274 normal positive sign, as in conventional financial statements.
3275 This report shows accounts declared with the Asset, Cash, Liability or
3277 Equity type (see account types). Or if no such accounts are declared,
3278 it shows top-level accounts named asset, liability or equity (case in‐
3279 sensitive, plurals allowed) and their subaccounts.
3280 Example:
3282 $ hledger balancesheetequity
3284 Balance Sheet With Equity
3285 Assets:
3287 $-2 assets
3288 $1 bank:saving
3289 $-3 cash
3290 --------------------
3291 $-2
3292 Liabilities:
3294 $1 liabilities:debts
3295 --------------------
3296 $1
3297 Equity:
3299 $1 equity:owner
3300 --------------------
3301 $1
3302 Total:
3304 --------------------
3305 0
3306 This command is a higher-level variant of the balance command, and sup‐
3308 ports many of that command's features, such as multi-period reports.
3309 It is similar to hledger balance -H assets liabilities equity, but with
3310 smarter account detection, and liabilities/equity displayed with their
3311 sign flipped.
3312 This command also supports the output destination and output format op‐
3314 tions The output formats supported are txt, csv, html, and (experimen‐
3315 tal) json.
3316 cashflow
3318 cashflow, cf
3319 This command displays a cashflow statement, showing the inflows and
3320 outflows affecting "cash" (ie, liquid, easily convertible) assets.
3321 Amounts are shown with normal positive sign, as in conventional finan‐
3322 cial statements.
3323 This report shows accounts declared with the Cash type (see account
3325 types). Or if no such accounts are declared, it shows accounts
3326 • under a top-level account named asset (case insensitive, plural al‐
3328 lowed)
3329 • whose name contains some variation of cash, bank, checking or saving.
3331 More precisely: all accounts matching this case insensitive regular ex‐
3333 pression:
3334 ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)
3336 and their subaccounts.
3338 An example cashflow report:
3340 $ hledger cashflow
3342 Cashflow Statement
3343 Cash flows:
3345 $-1 assets
3346 $1 bank:saving
3347 $-2 cash
3348 --------------------
3349 $-1
3350 Total:
3352 --------------------
3353 $-1
3354 This command is a higher-level variant of the balance command, and sup‐
3356 ports many of that command's features, such as multi-period reports.
3357 It is similar to hledger balance assets not:fixed not:investment
3358 not:receivable, but with smarter account detection.
3359 This command also supports the output destination and output format op‐
3361 tions The output formats supported are txt, csv, html, and (experimen‐
3362 tal) json.
3363 check
3365 check
3366 Check for various kinds of errors in your data.
3367 hledger provides a number of built-in error checks to help prevent
3369 problems in your data. Some of these are run automatically; or, you
3370 can use this check command to run them on demand, with no output and a
3371 zero exit code if all is well. Specify their names (or a prefix) as
3372 argument(s).
3373 Some examples:
3375 hledger check # basic checks
3377 hledger check -s # basic + strict checks
3378 hledger check ordereddates payees # basic + two other checks
3379 If you are an Emacs user, you can also configure flycheck-hledger to
3381 run these checks, providing instant feedback as you edit the journal.
3382 Here are the checks currently available:
3384 Basic checks
3386 These checks are always run automatically, by (almost) all hledger com‐
3387 mands, including check:
3388 • parseable - data files are well-formed and can be successfully parsed
3390 • balancedwithautoconversion - all transactions are balanced, inferring
3392 missing amounts where necessary, and possibly converting commodities
3393 using transaction prices or automatically-inferred transaction prices
3394 • assertions - all balance assertions in the journal are passing.
3396 (This check can be disabled with -I/--ignore-assertions.)
3397 Strict checks
3399 These additional checks are run when the -s/--strict (strict mode) flag
3400 is used. Or, they can be run by giving their names as arguments to
3401 check:
3402 • accounts - all account names used by transactions have been declared
3404 • commodities - all commodity symbols used have been declared
3406 • balancednoautoconversion - transactions are balanced, possibly using
3408 explicit transaction prices but not inferred ones
3409 Other checks
3411 These checks can be run only by giving their names as arguments to
3412 check. They are more specialised and not desirable for everyone,
3413 therefore optional:
3414 • ordereddates - transactions are ordered by date within each file
3416 • payees - all payees used by transactions have been declared
3418 • recentassertions - all accounts with balance assertions have a bal‐
3420 ance assertion no more than 7 days before their latest posting
3421 • uniqueleafnames - all account leaf names are unique
3423 Custom checks
3425 A few more checks are are available as separate add-on commands, in
3426 https://github.com/simonmichael/hledger/tree/master/bin:
3427 • hledger-check-tagfiles - all tag values containing / (a forward
3429 slash) exist as file paths
3430 • hledger-check-fancyassertions - more complex balance assertions are
3432 passing
3433 You could make similar scripts to perform your own custom checks. See:
3435 Cookbook -> Scripting.
3436 More about specific checks
3438 hledger check recentassertions will complain if any balance-asserted
3439 account does not have a balance assertion within 7 days before its lat‐
3440 est posting. This aims to prevent the situation where you are regu‐
3441 larly updating your journal, but forgetting to check your balances
3442 against the real world, then one day must dig back through months of
3443 data to find an error. It assumes that adding a balance assertion re‐
3444 quires/reminds you to check the real-world balance. That may not be
3445 true if you auto-generate balance assertions from bank data; in that
3446 case, I recommend to import transactions uncleared, then use the man‐
3447 ual-review-and-mark-cleared phase as a reminder to check the latest as‐
3448 sertions against real-world balances.
3449 close
3451 close, equity
3452 Prints a sample "closing" transaction bringing specified account bal‐
3453 ances to zero, and an inverse "opening" transaction restoring the same
3454 account balances.
3455 If like most people you split your journal files by time, eg by year:
3457 at the end of the year you can use this command to "close out" your as‐
3458 set and liability (and perhaps equity) balances in the old file, and
3459 reinitialise them in the new file. This helps ensure that report bal‐
3460 ances remain correct whether you are including old files or not. (Be‐
3461 cause all closing/opening transactions except the very first will can‐
3462 cel out - see example below.)
3463 Some people also use this command to close out revenue and expense bal‐
3465 ances at the end of an accounting period. This properly records the
3466 period's profit/loss as "retained earnings" (part of equity), and al‐
3467 lows the accounting equation (A-L=E) to balance, which you could then
3468 check by the bse report's zero total.
3469 You can print just the closing transaction by using the --close flag,
3471 or just the opening transaction with the --open flag.
3472 Their descriptions are closing balances and opening balances by de‐
3474 fault; you can customise these with the --close-desc and --open-desc
3475 options.
3476 Just one balancing equity posting is used by default, with the amount
3478 left implicit. The default account name is equity:opening/closing bal‐
3479 ances. You can customise the account name(s) with --close-acct and
3480 --open-acct. (If you specify only one of these, it will be used for
3481 both.)
3482 With --x/--explicit, the equity posting's amount will be shown explic‐
3484 itly, and if it involves multiple commodities, there will be a separate
3485 equity posting for each commodity (as in the print command).
3486 With --interleaved, each equity posting is shown next to the posting it
3488 balances (good for troubleshooting).
3489 close and prices
3491 Transaction prices are ignored (and discarded) by closing/opening
3492 transactions, by default. With --show-costs, they are preserved; there
3493 will be a separate equity posting for each cost in each commodity.
3494 This means balance -B reports will look the same after the transition.
3495 Note if you have many foreign currency or investment transactions, this
3496 will generate very large journal entries.
3497 close date
3499 The default closing date is yesterday, or the journal's end date,
3500 whichever is later.
3501 Unless you are running close on exactly the first day of the new pe‐
3503 riod, you'll want to override the closing date. This is done by speci‐
3504 fying a report end date, where "last day of the report period" will be
3505 the closing date. The opening date is always the following day. So to
3506 close on (end of) 2020-12-31 and open on (start of) 2021-01-01, any of
3507 these will work:
3508 end date argument explanation
3510 ───────────────────────────────────────────────
3511 -e 2021-01-01 end dates are exclusive
3512 -e 2021 equivalent, per smart
3513 dates
3514 -p 2020 equivalent, the period's
3515 begin date is ignored
3516 date:2020 equivalent query
3517 Example: close asset/liability accounts for file transition
3519 Carrying asset/liability balances from 2020.journal into a new file for
3520 2021:
3521 $ hledger close -f 2020.journal -p 2020 assets liabilities
3523 # copy/paste the closing transaction to the end of 2020.journal
3524 # copy/paste the opening transaction to the start of 2021.journal
3525 Or:
3527 $ hledger close -f 2020.journal -p 2020 assets liabilities --open >> 2021.journal # add 2021's first transaction
3529 $ hledger close -f 2020.journal -p 2020 assets liabilities --close >> 2020.journal # add 2020's last transaction
3530 Now,
3532 $ hledger bs -f 2021.journal # just new file - balances correct
3534 $ hledger bs -f 2020.journal -f 2021.journal # old and new files - balances correct
3535 $ hledger bs -f 2020.journal # just old files - balances are zero ?
3536 # (exclude final closing txn, see below)
3537 Hiding opening/closing transactions
3539 Although the closing/opening transactions cancel out, they will be vis‐
3540 ible in reports like print and register, creating some visual clutter.
3541 You can exclude them all with a query, like:
3542 $ hledger print not:desc:'opening|closing' # less typing
3544 $ hledger print not:'equity:opening/closing balances' # more precise
3545 But when reporting on multiple files, this can get a bit tricky; you
3547 may need to keep the earliest opening balances, for a historical regis‐
3548 ter report; or you may need to suppress a closing transaction, to see
3549 year-end balances. If you find yourself needing more precise queries,
3550 here's one solution: add more easily-matched tags to opening/closing
3551 transactions, like this:
3552 ; 2019.journal
3554 2019-01-01 opening balances ; earliest opening txn, no tag here
3555 ...
3556 2019-12-31 closing balances ; clopen:2020
3557 ...
3558 ; 2020.journal
3560 2020-01-01 opening balances ; clopen:2020
3561 ...
3562 2020-12-31 closing balances ; clopen:2021
3563 ...
3564 ; 2021.journal
3566 2021-01-01 opening balances ; clopen:2021
3567 ...
3568 Now with
3570 ; all.journal
3572 include 2019.journal
3573 include 2020.journal
3574 include 2021.journal
3575 you could do eg:
3577 $ hledger -f all.journal reg -H checking not:tag:clopen
3579 # all years checking register, hiding non-essential opening/closing txns
3580 $ hledger -f all.journal bs -p 2020 not:tag:clopen=2020
3582 # 2020 year end balances, suppressing 2020 closing txn
3583 close and balance assertions
3585 The closing and opening transactions will include balance assertions,
3586 verifying that the accounts have first been reset to zero and then re‐
3587 stored to their previous balance. These provide valuable error check‐
3588 ing, alerting you when things get out of line, but you can ignore them
3589 temporarily with -I or just remove them if you prefer.
3590 You probably shouldn't use status or realness filters (like -C or -R or
3592 status:) with close, or the generated balance assertions will depend on
3593 these flags. Likewise, if you run this command with --auto, the bal‐
3594 ance assertions would probably always require --auto.
3595 Multi-day transactions (where some postings have a different date)
3597 break the balance assertions, because the money is temporarily "invisi‐
3598 ble" while in transit:
3599 2020/12/30 a purchase made in december, cleared in the next year
3601 expenses:food 5
3602 assets:bank:checking -5 ; date: 2021/1/2
3603 To fix the assertions, you can add a temporary account to track such
3605 in-transit money (splitting the multi-day transaction into two single-
3606 day transactions):
3607 ; in 2020.journal:
3609 2020/12/30 a purchase made in december, cleared in the next year
3610 expenses:food 5
3611 liabilities:pending
3612 ; in 2021.journal:
3614 2021/1/2 clearance of last year's pending transactions
3615 liabilities:pending 5 = 0
3616 assets:bank:checking
3617 Example: close revenue/expense accounts to retained earnings
3619 For this, use --close to suppress the opening transaction, as it's not
3620 needed. Also you'll want to change the equity account name to your
3621 equivalent of "equity:retained earnings".
3622 Closing 2021's first quarter revenues/expenses:
3624 $ hledger close -f 2021.journal --close revenues expenses -p 2021Q1 \
3626 --close-acct='equity:retained earnings' >> 2021.journal
3627 The same, using the default journal and current year:
3629 $ hledger close --close revenues expenses -p Q1 \
3631 --close-acct='equity:retained earnings' >> $LEDGER_FILE
3632 Now, the first quarter's balance sheet should show a zero (unless you
3634 are using @/@@ notation without equity postings):
3635 $ hledger bse -p Q1
3637 And we must suppress the closing transaction to see the first quarter's
3639 income statement (using the description; not:'retained earnings' won't
3640 work here):
3641 $ hledger is -p Q1 not:desc:'closing balances'
3643 codes
3645 codes
3646 List the codes seen in transactions, in the order parsed.
3647 This command prints the value of each transaction's code field, in the
3649 order transactions were parsed. The transaction code is an optional
3650 value written in parentheses between the date and description, often
3651 used to store a cheque number, order number or similar.
3652 Transactions aren't required to have a code, and missing or empty codes
3654 will not be shown by default. With the -E/--empty flag, they will be
3655 printed as blank lines.
3656 You can add a query to select a subset of transactions.
3658 Examples:
3660 1/1 (123)
3662 (a) 1
3663 1/1 ()
3665 (a) 1
3666 1/1
3668 (a) 1
3669 1/1 (126)
3671 (a) 1
3672 $ hledger codes
3674 123
3675 124
3676 126
3677 $ hledger codes -E
3679 123
3680 124
3681 126
3684 commodities
3686 commodities
3687 List all commodity/currency symbols used or declared in the journal.
3688 descriptions
3690 descriptions
3691 List the unique descriptions that appear in transactions.
3692 This command lists the unique descriptions that appear in transactions,
3694 in alphabetic order. You can add a query to select a subset of trans‐
3695 actions.
3696 Example:
3698 $ hledger descriptions
3700 Store Name
3701 Gas Station | Petrol
3702 Person A
3703 diff
3705 diff
3706 Compares a particular account's transactions in two input files. It
3707 shows any transactions to this account which are in one file but not in
3708 the other.
3709 More precisely, for each posting affecting this account in either file,
3711 it looks for a corresponding posting in the other file which posts the
3712 same amount to the same account (ignoring date, description, etc.)
3713 Since postings not transactions are compared, this also works when mul‐
3714 tiple bank transactions have been combined into a single journal entry.
3715 This is useful eg if you have downloaded an account's transactions from
3717 your bank (eg as CSV data). When hledger and your bank disagree about
3718 the account balance, you can compare the bank data with your journal to
3719 find out the cause.
3720 Examples:
3722 $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro
3724 These transactions are in the first file only:
3725 2014/01/01 Opening Balances
3727 assets:bank:giro EUR ...
3728 ...
3729 equity:opening balances EUR -...
3730 These transactions are in the second file only:
3732 files
3734 files
3735 List all files included in the journal. With a REGEX argument, only
3736 file names matching the regular expression (case sensitive) are shown.
3737 help
3739 help
3740 Show the hledger user manual in the terminal, with info, man, or a
3741 pager. With a TOPIC argument, open it at that topic if possible.
3742 TOPIC can be any heading in the manual, or a heading prefix, case in‐
3743 sensitive. Eg: commands, print, forecast, journal, amount, "auto post‐
3744 ings".
3745 This command shows the hledger manual built in to your hledger version.
3747 It can be useful when offline, or when you prefer the terminal to a web
3748 browser, or when the appropriate hledger manual or viewing tools are
3749 not installed on your system.
3750 By default it chooses the best viewer found in $PATH (preferring info
3752 since the hledger manual is large). You can select a particular viewer
3753 with the -i, -m, or -p flags.
3754 Examples
3756 $ hledger help --help # show how the help command works
3758 $ hledger help # show the hledger manual with info, man or $PAGER
3759 $ hledger help journal # show the journal topic in the hledger manual
3760 import
3762 import
3763 Read new transactions added to each FILE since last run, and add them
3764 to the journal. Or with --dry-run, just print the transactions that
3765 would be added. Or with --catchup, just mark all of the FILEs' trans‐
3766 actions as imported, without actually importing any.
3767 This command may append new transactions to the main journal file
3769 (which should be in journal format). Existing transactions are not
3770 changed. This is one of the few hledger commands that writes to the
3771 journal file (see also add).
3772 Unlike other hledger commands, with import the journal file is an out‐
3774 put file, and will be modified, though only by appending (existing data
3775 will not be changed). The input files are specified as arguments, so
3776 to import one or more CSV files to your main journal, you will run
3777 hledger import bank.csv or perhaps hledger import *.csv.
3778 Note you can import from any file format, though CSV files are the most
3780 common import source, and these docs focus on that case.
3781 Deduplication
3783 As a convenience import does deduplication while reading transactions.
3784 This does not mean "ignore transactions that look the same", but rather
3785 "ignore transactions that have been seen before". This is intended for
3786 when you are periodically importing foreign data which may contain al‐
3787 ready-imported transactions. So eg, if every day you download bank CSV
3788 files containing redundant data, you can safely run hledger import
3789 bank.csv and only new transactions will be imported. (import is idem‐
3790 potent.)
3791 Since the items being read (CSV records, eg) often do not come with
3793 unique identifiers, hledger detects new transactions by date, assuming
3794 that:
3795 1. new items always have the newest dates
3797 2. item dates do not change across reads
3799 3. and items with the same date remain in the same relative order
3801 across reads.
3802 These are often true of CSV files representing transactions, or true
3804 enough so that it works pretty well in practice. 1 is important, but
3805 violations of 2 and 3 amongst the old transactions won't matter (and if
3806 you import often, the new transactions will be few, so less likely to
3807 be the ones affected).
3808 hledger remembers the latest date processed in each input file by sav‐
3810 ing a hidden ".latest" state file in the same directory. Eg when read‐
3811 ing finance/bank.csv, it will look for and update the finance/.lat‐
3812 est.bank.csv state file. The format is simple: one or more lines con‐
3813 taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro‐
3814 cessed transactions up to this date, and this many of them on that
3815 date." Normally you won't see or manipulate these state files yourself.
3816 But if needed, you can delete them to reset the state (making all
3817 transactions "new"), or you can construct them to "catch up" to a cer‐
3818 tain date.
3819 Note deduplication (and updating of state files) can also be done by
3821 print --new, but this is less often used.
3822 Import testing
3824 With --dry-run, the transactions that will be imported are printed to
3825 the terminal, without updating your journal or state files. The output
3826 is valid journal format, like the print command, so you can re-parse
3827 it. Eg, to see any importable transactions which CSV rules have not
3828 categorised:
3829 $ hledger import --dry bank.csv | hledger -f- -I print unknown
3831 or (live updating):
3833 $ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'
3835 Importing balance assignments
3837 Entries added by import will have their posting amounts made explicit
3838 (like hledger print -x). This means that any balance assignments in
3839 imported files must be evaluated; but, imported files don't get to see
3840 the main file's account balances. As a result, importing entries with
3841 balance assignments (eg from an institution that provides only balances
3842 and not posting amounts) will probably generate incorrect posting
3843 amounts. To avoid this problem, use print instead of import:
3844 $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
3846 (If you think import should leave amounts implicit like print does,
3848 please test it and send a pull request.)
3849 Commodity display styles
3851 Imported amounts will be formatted according to the canonical commodity
3852 styles (declared or inferred) in the main journal file.
3853 incomestatement
3855 incomestatement, is
3856 This command displays an income statement, showing revenues and ex‐
3857 penses during one or more periods. Amounts are shown with normal posi‐
3858 tive sign, as in conventional financial statements.
3859 This report shows accounts declared with the Revenue or Expense type
3861 (see account types). Or if no such accounts are declared, it shows
3862 top-level accounts named revenue or income or expense (case insensi‐
3863 tive, plurals allowed) and their subaccounts.
3864 Example:
3866 $ hledger incomestatement
3868 Income Statement
3869 Revenues:
3871 $-2 income
3872 $-1 gifts
3873 $-1 salary
3874 --------------------
3875 $-2
3876 Expenses:
3878 $2 expenses
3879 $1 food
3880 $1 supplies
3881 --------------------
3882 $2
3883 Total:
3885 --------------------
3886 0
3887 This command is a higher-level variant of the balance command, and sup‐
3889 ports many of that command's features, such as multi-period reports.
3890 It is similar to hledger balance '(revenues|income)' expenses, but with
3891 smarter account detection, and revenues/income displayed with their
3892 sign flipped.
3893 This command also supports the output destination and output format op‐
3895 tions The output formats supported are txt, csv, html, and (experimen‐
3896 tal) json.
3897 notes
3899 notes
3900 List the unique notes that appear in transactions.
3901 This command lists the unique notes that appear in transactions, in al‐
3903 phabetic order. You can add a query to select a subset of transac‐
3904 tions. The note is the part of the transaction description after a |
3905 character (or if there is no |, the whole description).
3906 Example:
3908 $ hledger notes
3910 Petrol
3911 Snacks
3912 payees
3914 payees
3915 List the unique payee/payer names that appear in transactions.
3916 This command lists unique payee/payer names which have been declared
3918 with payee directives (--declared), used in transaction descriptions
3919 (--used), or both (the default).
3920 The payee/payer is the part of the transaction description before a |
3922 character (or if there is no |, the whole description).
3923 You can add query arguments to select a subset of transactions. This
3925 implies --used.
3926 Example:
3928 $ hledger payees
3930 Store Name
3931 Gas Station
3932 Person A
3933 prices
3935 prices
3936 Print market price directives from the journal. With --infer-market-
3937 prices, generate additional market prices from transaction prices.
3938 With --infer-reverse-prices, also generate market prices by inverting
3939 transaction prices. Prices (and postings providing transaction prices)
3940 can be filtered by a query. Price amounts are displayed with their
3941 full precision.
3942 print
3944 print
3945 Show transaction journal entries, sorted by date.
3946 The print command displays full journal entries (transactions) from the
3948 journal file, sorted by date (or with --date2, by secondary date).
3949 Amounts are shown mostly normalised to commodity display style, eg the
3951 placement of commodity symbols will be consistent. All of their deci‐
3952 mal places are shown, as in the original journal entry (with one alter‐
3953 ation: in some cases trailing zeroes are added.)
3954 Amounts are shown right-aligned within each transaction (but not across
3956 all transactions).
3957 Directives and inter-transaction comments are not shown, currently.
3959 This means the print command is somewhat lossy, and if you are using it
3960 to reformat your journal you should take care to also copy over the di‐
3961 rectives and file-level comments.
3962 Eg:
3964 $ hledger print
3966 2008/01/01 income
3967 assets:bank:checking $1
3968 income:salary $-1
3969 2008/06/01 gift
3971 assets:bank:checking $1
3972 income:gifts $-1
3973 2008/06/02 save
3975 assets:bank:saving $1
3976 assets:bank:checking $-1
3977 2008/06/03 * eat & shop
3979 expenses:food $1
3980 expenses:supplies $1
3981 assets:cash $-2
3982 2008/12/31 * pay off
3984 liabilities:debts $1
3985 assets:bank:checking $-1
3986 print's output is usually a valid hledger journal, and you can process
3988 it again with a second hledger command. This can be useful for certain
3989 kinds of search, eg:
3990 # Show running total of food expenses paid from cash.
3992 # -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
3993 $ hledger print assets:cash | hledger -f- -I reg expenses:food
3994 There are some situations where print's output can become unparseable:
3996 • Valuation affects posting amounts but not balance assertion or bal‐
3998 ance assignment amounts, potentially causing those to fail.
3999 • Auto postings can generate postings with too many missing amounts.
4001 • Account aliases can generate bad account names.
4003 Normally, the journal entry's explicit or implicit amount style is pre‐
4005 served. For example, when an amount is omitted in the journal, it will
4006 not appear in the output. Similarly, when a transaction price is im‐
4007 plied but not written, it will not appear in the output. You can use
4008 the -x/--explicit flag to make all amounts and transaction prices ex‐
4009 plicit, which can be useful for troubleshooting or for making your
4010 journal more readable and robust against data entry errors. -x is also
4011 implied by using any of -B,-V,-X,--value.
4012 Note, -x/--explicit will cause postings with a multi-commodity amount
4014 (these can arise when a multi-commodity transaction has an implicit
4015 amount) to be split into multiple single-commodity postings, keeping
4016 the output parseable.
4017 With -B/--cost, amounts with transaction prices are converted to cost
4019 using that price. This can be used for troubleshooting.
4020 With -m/--match and a STR argument, print will show at most one trans‐
4022 action: the one one whose description is most similar to STR, and is
4023 most recent. STR should contain at least two characters. If there is
4024 no similar-enough match, no transaction will be shown.
4025 With --new, hledger prints only transactions it has not seen on a pre‐
4027 vious run. This uses the same deduplication system as the import com‐
4028 mand. (See import's docs for details.)
4029 This command also supports the output destination and output format op‐
4031 tions The output formats supported are txt, csv, and (experimental)
4032 json and sql.
4033 Here's an example of print's CSV output:
4035 $ hledger print -Ocsv
4037 "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
4038 "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
4039 "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
4040 "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
4041 "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
4042 "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
4043 "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
4044 "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
4045 "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
4046 "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
4047 "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
4048 "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
4049 • There is one CSV record per posting, with the parent transaction's
4051 fields repeated.
4052 • The "txnidx" (transaction index) field shows which postings belong to
4054 the same transaction. (This number might change if transactions are
4055 reordered within the file, files are parsed/included in a different
4056 order, etc.)
4057 • The amount is separated into "commodity" (the symbol) and "amount"
4059 (numeric quantity) fields.
4060 • The numeric amount is repeated in either the "credit" or "debit" col‐
4062 umn, for convenience. (Those names are not accurate in the account‐
4063 ing sense; it just puts negative amounts under credit and zero or
4064 greater amounts under debit.)
4065 print-unique
4067 print-unique
4068 Print transactions which do not reuse an already-seen description.
4069 Example:
4071 $ cat unique.journal
4073 1/1 test
4074 (acct:one) 1
4075 2/2 test
4076 (acct:two) 2
4077 $ LEDGER_FILE=unique.journal hledger print-unique
4078 (-f option not supported)
4079 2015/01/01 test
4080 (acct:one) 1
4081 register
4083 register, reg
4084 Show postings and their running total.
4085 The register command displays matched postings, across all accounts, in
4087 date order, with their running total or running historical balance.
4088 (See also the aregister command, which shows matched transactions in a
4089 specific account.)
4090 register normally shows line per posting, but note that multi-commodity
4092 amounts will occupy multiple lines (one line per commodity).
4093 It is typically used with a query selecting a particular account, to
4095 see that account's activity:
4096 $ hledger register checking
4098 2008/01/01 income assets:bank:checking $1 $1
4099 2008/06/01 gift assets:bank:checking $1 $2
4100 2008/06/02 save assets:bank:checking $-1 $1
4101 2008/12/31 pay off assets:bank:checking $-1 0
4102 With --date2, it shows and sorts by secondary date instead.
4104 For performance reasons, column widths are chosen based on the first
4106 1000 lines; this means unusually wide values in later lines can cause
4107 visual discontinuities as column widths are adjusted. If you want to
4108 ensure perfect alignment, at the cost of more time and memory, use the
4109 --align-all flag.
4110 The --historical/-H flag adds the balance from any undisplayed prior
4112 postings to the running total. This is useful when you want to see
4113 only recent activity, with a historically accurate running balance:
4114 $ hledger register checking -b 2008/6 --historical
4116 2008/06/01 gift assets:bank:checking $1 $2
4117 2008/06/02 save assets:bank:checking $-1 $1
4118 2008/12/31 pay off assets:bank:checking $-1 0
4119 The --depth option limits the amount of sub-account detail displayed.
4121 The --average/-A flag shows the running average posting amount instead
4123 of the running total (so, the final number displayed is the average for
4124 the whole report period). This flag implies --empty (see below). It
4125 is affected by --historical. It works best when showing just one ac‐
4126 count and one commodity.
4127 The --related/-r flag shows the other postings in the transactions of
4129 the postings which would normally be shown.
4130 The --invert flag negates all amounts. For example, it can be used on
4132 an income account where amounts are normally displayed as negative num‐
4133 bers. It's also useful to show postings on the checking account to‐
4134 gether with the related account:
4135 $ hledger register --related --invert assets:checking
4137 With a reporting interval, register shows summary postings, one per in‐
4139 terval, aggregating the postings to each account:
4140 $ hledger register --monthly income
4142 2008/01 income:salary $-1 $-1
4143 2008/06 income:gifts $-1 $-2
4144 Periods with no activity, and summary postings with a zero amount, are
4146 not shown by default; use the --empty/-E flag to see them:
4147 $ hledger register --monthly income -E
4149 2008/01 income:salary $-1 $-1
4150 2008/02 0 $-1
4151 2008/03 0 $-1
4152 2008/04 0 $-1
4153 2008/05 0 $-1
4154 2008/06 income:gifts $-1 $-2
4155 2008/07 0 $-2
4156 2008/08 0 $-2
4157 2008/09 0 $-2
4158 2008/10 0 $-2
4159 2008/11 0 $-2
4160 2008/12 0 $-2
4161 Often, you'll want to see just one line per interval. The --depth op‐
4163 tion helps with this, causing subaccounts to be aggregated:
4164 $ hledger register --monthly assets --depth 1h
4166 2008/01 assets $1 $1
4167 2008/06 assets $-1 0
4168 2008/12 assets $-1 $-1
4169 Note when using report intervals, if you specify start/end dates these
4171 will be adjusted outward if necessary to contain a whole number of in‐
4172 tervals. This ensures that the first and last intervals are full
4173 length and comparable to the others in the report.
4174 Custom register output
4176 register uses the full terminal width by default, except on windows.
4177 You can override this by setting the COLUMNS environment variable (not
4178 a bash shell variable) or by using the --width/-w option.
4179 The description and account columns normally share the space equally
4181 (about half of (width - 40) each). You can adjust this by adding a de‐
4182 scription width as part of --width's argument, comma-separated: --width
4183 W,D . Here's a diagram (won't display correctly in --help):
4184 <--------------------------------- width (W) ---------------------------------->
4186 date (10) description (D) account (W-41-D) amount (12) balance (12)
4187 DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
4188 and some examples:
4190 $ hledger reg # use terminal width (or 80 on windows)
4192 $ hledger reg -w 100 # use width 100
4193 $ COLUMNS=100 hledger reg # set with one-time environment variable
4194 $ export COLUMNS=100; hledger reg # set till session end (or window resize)
4195 $ hledger reg -w 100,40 # set overall width 100, description width 40
4196 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
4197 This command also supports the output destination and output format op‐
4199 tions The output formats supported are txt, csv, and (experimental)
4200 json.
4201 register-match
4203 register-match
4204 Print the one posting whose transaction description is closest to DESC,
4205 in the style of the register command. If there are multiple equally
4206 good matches, it shows the most recent. Query options (options, not
4207 arguments) can be used to restrict the search space. Helps ledger-au‐
4208 tosync detect already-seen transactions when importing.
4209 rewrite
4211 rewrite
4212 Print all transactions, rewriting the postings of matched transactions.
4213 For now the only rewrite available is adding new postings, like print
4214 --auto.
4215 This is a start at a generic rewriter of transaction entries. It reads
4217 the default journal and prints the transactions, like print, but adds
4218 one or more specified postings to any transactions matching QUERY. The
4219 posting amounts can be fixed, or a multiplier of the existing transac‐
4220 tion's first posting amount.
4221 Examples:
4223 $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
4225 $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
4226 $ hledger-rewrite.hs -f rewrites.hledger
4227 rewrites.hledger may consist of entries like:
4229 = ^income amt:<0 date:2017
4231 (liabilities:tax) *0.33 ; tax on income
4232 (reserve:grocery) *0.25 ; reserve 25% for grocery
4233 (reserve:) *0.25 ; reserve 25% for grocery
4234 Note the single quotes to protect the dollar sign from bash, and the
4236 two spaces between account and amount.
4237 More:
4239 $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
4241 $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
4242 $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'
4243 $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
4244 Argument for --add-posting option is a usual posting of transaction
4246 with an exception for amount specification. More precisely, you can
4247 use '*' (star symbol) before the amount to indicate that that this is a
4248 factor for an amount of original matched posting. If the amount in‐
4249 cludes a commodity name, the new posting amount will be in the new com‐
4250 modity; otherwise, it will be in the matched posting amount's commod‐
4251 ity.
4252 Re-write rules in a file
4254 During the run this tool will execute so called "Automated Transac‐
4255 tions" found in any journal it process. I.e instead of specifying this
4256 operations in command line you can put them in a journal file.
4257 $ rewrite-rules.journal
4259 Make contents look like this:
4261 = ^income
4263 (liabilities:tax) *.33
4264 = expenses:gifts
4266 budget:gifts *-1
4267 assets:budget *1
4268 Note that '=' (equality symbol) that is used instead of date in trans‐
4270 actions you usually write. It indicates the query by which you want to
4271 match the posting to add new ones.
4272 $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
4274 This is something similar to the commands pipeline:
4276 $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \
4278 | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \
4279 --add-posting 'assets:budget *1' \
4280 > rewritten-tidy-output.journal
4281 It is important to understand that relative order of such entries in
4283 journal is important. You can re-use result of previously added post‐
4284 ings.
4285 Diff output format
4287 To use this tool for batch modification of your journal files you may
4288 find useful output in form of unified diff.
4289 $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
4291 Output might look like:
4293 --- /tmp/examples/sample.journal
4295 +++ /tmp/examples/sample.journal
4296 @@ -18,3 +18,4 @@
4297 2008/01/01 income
4298 - assets:bank:checking $1
4299 + assets:bank:checking $1
4300 income:salary
4301 + (liabilities:tax) 0
4302 @@ -22,3 +23,4 @@
4303 2008/06/01 gift
4304 - assets:bank:checking $1
4305 + assets:bank:checking $1
4306 income:gifts
4307 + (liabilities:tax) 0
4308 If you'll pass this through patch tool you'll get transactions contain‐
4310 ing the posting that matches your query be updated. Note that multiple
4311 files might be update according to list of input files specified via
4312 --file options and include directives inside of these files.
4313 Be careful. Whole transaction being re-formatted in a style of output
4315 from hledger print.
4316 See also:
4318 https://github.com/simonmichael/hledger/issues/99
4320 rewrite vs. print --auto
4322 This command predates print --auto, and currently does much the same
4323 thing, but with these differences:
4324 • with multiple files, rewrite lets rules in any file affect all other
4326 files. print --auto uses standard directive scoping; rules affect
4327 only child files.
4328 • rewrite's query limits which transactions can be rewritten; all are
4330 printed. print --auto's query limits which transactions are printed.
4331 • rewrite applies rules specified on command line or in the journal.
4333 print --auto applies rules specified in the journal.
4334 roi
4336 roi
4337 Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
4338 on your investments.
4339 At a minimum, you need to supply a query (which could be just an ac‐
4341 count name) to select your investment(s) with --inv, and another query
4342 to identify your profit and loss transactions with --pnl.
4343 If you do not record changes in the value of your investment manually,
4345 or do not require computation of time-weighted return (TWR), --pnl
4346 could be an empty query (--pnl "" or --pnl STR where STR does not match
4347 any of your accounts).
4348 This command will compute and display the internalized rate of return
4350 (IRR) and time-weighted rate of return (TWR) for your investments for
4351 the time period requested. Both rates of return are annualized before
4352 display, regardless of the length of reporting interval.
4353 Price directives will be taken into account if you supply appropriate
4355 --cost or --value flags (see VALUATION).
4356 Note, in some cases this report can fail, for these reasons:
4358 • Error (NotBracketed): No solution for Internal Rate of Return (IRR).
4360 Possible causes: IRR is huge (>1000000%), balance of investment be‐
4361 comes negative at some point in time.
4362 • Error (SearchFailed): Failed to find solution for Internal Rate of
4364 Return (IRR). Either search does not converge to a solution, or con‐
4365 verges too slowly.
4366 Examples:
4368 • Using roi to compute total return of investment in stocks:
4370 https://github.com/simonmichael/hledger/blob/master/examples/invest‐
4371 ing/roi-unrealised.ledger
4372 • Cookbook > Return on Investment: https://hledger.org/roi.html
4374 Spaces and special characters in --inv and --pnl
4376 Note that --inv and --pnl's argument is a query, and queries could have
4377 several space-separated terms (see QUERIES).
4378 To indicate that all search terms form single command-line argument,
4380 you will need to put them in quotes (see Special characters):
4381 $ hledger roi --inv 'term1 term2 term3 ...'
4383 If any query terms contain spaces themselves, you will need an extra
4385 level of nested quoting, eg:
4386 $ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"
4388 Semantics of --inv and --pnl
4390 Query supplied to --inv has to match all transactions that are related
4391 to your investment. Transactions not matching --inv will be ignored.
4392 In these transactions, ROI will conside postings that match --inv to be
4394 "investment postings" and other postings (not matching --inv) will be
4395 sorted into two categories: "cash flow" and "profit and loss", as ROI
4396 needs to know which part of the investment value is your contributions
4397 and which is due to the return on investment.
4398 • "Cash flow" is depositing or withdrawing money, buying or selling as‐
4400 sets, or otherwise converting between your investment commodity and
4401 any other commodity. Example:
4402 2019-01-01 Investing in Snake Oil
4404 assets:cash -$100
4405 investment:snake oil
4406 2020-01-01 Selling my Snake Oil
4408 assets:cash $10
4409 investment:snake oil = 0
4410 • "Profit and loss" is change in the value of your investment:
4412 2019-06-01 Snake Oil falls in value
4414 investment:snake oil = $57
4415 equity:unrealized profit or loss
4416 All non-investment postings are assumed to be "cash flow", unless they
4418 match --pnl query. Changes in value of your investment due to "profit
4419 and loss" postings will be considered as part of your investment re‐
4420 turn.
4421 Example: if you use --inv snake --pnl equity:unrealized, then postings
4423 in the example below would be classifed as:
4424 2019-01-01 Snake Oil #1
4426 assets:cash -$100 ; cash flow posting
4427 investment:snake oil ; investment posting
4428 2019-03-01 Snake Oil #2
4430 equity:unrealized pnl -$100 ; profit and loss posting
4431 snake oil ; investment posting
4432 2019-07-01 Snake Oil #3
4434 equity:unrealized pnl ; profit and loss posting
4435 cash -$100 ; cash flow posting
4436 snake oil $50 ; investment posting
4437 IRR and TWR explained
4439 "ROI" stands for "return on investment". Traditionally this was com‐
4440 puted as a difference between current value of investment and its ini‐
4441 tial value, expressed in percentage of the initial value.
4442 However, this approach is only practical in simple cases, where invest‐
4444 ments receives no in-flows or out-flows of money, and where rate of
4445 growth is fixed over time. For more complex scenarios you need differ‐
4446 ent ways to compute rate of return, and this command implements two of
4447 them: IRR and TWR.
4448 Internal rate of return, or "IRR" (also called "money-weighted rate of
4450 return") takes into account effects of in-flows and out-flows.
4451 Naively, if you are withdrawing from your investment, your future gains
4452 would be smaller (in absolute numbers), and will be a smaller percent‐
4453 age of your initial investment, and if you are adding to your invest‐
4454 ment, you will receive bigger absolute gains (but probably at the same
4455 rate of return). IRR is a way to compute rate of return for each pe‐
4456 riod between in-flow or out-flow of money, and then combine them in a
4457 way that gives you a compound annual rate of return that investment is
4458 expected to generate.
4459 As mentioned before, in-flows and out-flows would be any cash that you
4461 personally put in or withdraw, and for the "roi" command, these are the
4462 postings that match the query in the--inv argument and NOT match the
4463 query in the--pnl argument.
4464 If you manually record changes in the value of your investment as
4466 transactions that balance them against "profit and loss" (or "unreal‐
4467 ized gains") account or use price directives, then in order for IRR to
4468 compute the precise effect of your in-flows and out-flows on the rate
4469 of return, you will need to record the value of your investement on or
4470 close to the days when in- or out-flows occur.
4471 In technical terms, IRR uses the same approach as computation of net
4473 present value, and tries to find a discount rate that makes net present
4474 value of all the cash flows of your investment to add up to zero. This
4475 could be hard to wrap your head around, especially if you haven't done
4476 discounted cash flow analysis before. Implementation of IRR in hledger
4477 should produce results that match the XIRR formula in Excel.
4478 Second way to compute rate of return that roi command implements is
4480 called "time-weighted rate of return" or "TWR". Like IRR, it will also
4481 break the history of your investment into periods between in-flows,
4482 out-flows and value changes, to compute rate of return per each period
4483 and then a compound rate of return. However, internal workings of TWR
4484 are quite different.
4485 TWR represents your investment as an imaginary "unit fund" where in-
4487 flows/ out-flows lead to buying or selling "units" of your investment
4488 and changes in its value change the value of "investment unit". Change
4489 in "unit price" over the reporting period gives you rate of return of
4490 your investment.
4491 References:
4493 • Explanation of rate of return
4495 • Explanation of IRR
4497 • Explanation of TWR
4499 • Examples of computing IRR and TWR and discussion of the limitations
4501 of both metrics
4502 stats
4504 stats
4505 Show journal and performance statistics.
4506 The stats command displays summary information for the whole journal,
4508 or a matched part of it. With a reporting interval, it shows a report
4509 for each report period.
4510 At the end, it shows (in the terminal) the overall run time and number
4512 of transactions processed per second. Note these are approximate and
4513 will vary based on machine, current load, data size, hledger version,
4514 haskell lib versions, GHC version.. but they may be of interest. The
4515 stats command's run time is similar to that of a single-column balance
4516 report.
4517 Example:
4519 $ hledger stats -f examples/1000x1000x10.journal
4521 Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal
4522 Included files :
4523 Transactions span : 2000-01-01 to 2002-09-27 (1000 days)
4524 Last transaction : 2002-09-26 (6995 days ago)
4525 Transactions : 1000 (1.0 per day)
4526 Transactions last 30 days: 0 (0.0 per day)
4527 Transactions last 7 days : 0 (0.0 per day)
4528 Payees/descriptions : 1000
4529 Accounts : 1000 (depth 10)
4530 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)
4531 Market prices : 1000 (A)
4532 Run time : 0.12 s
4534 Throughput : 8342 txns/s
4535 This command also supports output destination and output format selec‐
4537 tion.
4538 tags
4540 tags
4541 List the tags used in the journal, or their values.
4542 This command lists the tag names used in the journal, whether on trans‐
4544 actions, postings, or account declarations.
4545 With a TAGREGEX argument, only tag names matching this regular expres‐
4547 sion (case insensitive, infix matched) are shown.
4548 With QUERY arguments, only transactions and accounts matching this
4550 query are considered. If the query involves transaction fields (date:,
4551 desc:, amt:, ...), the search is restricted to the matched transactions
4552 and their accounts.
4553 With the --values flag, the tags' unique non-empty values are listed
4555 instead. With -E/--empty, blank/empty values are also shown.
4556 With --parsed, tags or values are shown in the order they were parsed,
4558 with duplicates included. (Except, tags from account declarations are
4559 always shown first.)
4560 Tip: remember, accounts also acquire tags from their parents, postings
4562 also acquire tags from their account and transaction, transactions also
4563 acquire tags from their postings.
4564 test
4566 test
4567 Run built-in unit tests.
4568 This command runs the unit tests built in to hledger and hledger-lib,
4570 printing the results on stdout. If any test fails, the exit code will
4571 be non-zero.
4572 This is mainly used by hledger developers, but you can also use it to
4574 sanity-check the installed hledger executable on your platform. All
4575 tests are expected to pass - if you ever see a failure, please report
4576 as a bug!
4577 This command also accepts tasty test runner options, written after a --
4579 (double hyphen). Eg to run only the tests in Hledger.Data.Amount, with
4580 ANSI colour codes disabled:
4581 $ hledger test -- -pData.Amount --color=never
4583 For help on these, see https://github.com/feuerbach/tasty#options (--
4585 --help currently doesn't show them).
4586 Add-on commands
4588 Add-on commands are programs or scripts in your PATH
4589 • whose name starts with hledger-
4591 • whose name ends with a recognised file extension: .bat,.com,.exe,
4593 .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none
4594 • and (on unix, mac) which are executable by the current user.
4596 Add-ons are a relatively easy way to add local features or experiment
4598 with new ideas. They can be written in any language, but haskell
4599 scripts have a big advantage: they can use the same hledger library
4600 functions that built-in commands use for command-line options, parsing
4601 and reporting. Some experimental/example add-on scripts can be found
4602 in the hledger repo's bin/ directory.
4603 Note in a hledger command line, add-on command flags must have a double
4605 dash (--) preceding them. Eg you must write:
4606 $ hledger web -- --serve
4608 and not:
4610 $ hledger web --serve
4612 (because the --serve flag belongs to hledger-web, not hledger).
4614 The -h/--help and --version flags don't require --.
4616 If you have any trouble with this, remember you can always run the add-
4618 on program directly, eg:
4619 $ hledger-web --serve
4621
4623 hledger's default file format, representing a General Journal.
4624 hledger's usual data source is a plain text file containing journal en‐
4626 tries in hledger journal format. This file represents a standard ac‐
4627 counting general journal. I use file names ending in .journal, but
4628 that's not required. The journal file contains a number of transaction
4629 entries, each describing a transfer of money (or any commodity) between
4630 two or more named accounts, in a simple format readable by both hledger
4631 and humans.
4632 hledger's journal format is a compatible subset, mostly, of ledger's
4634 journal format, so hledger can work with compatible ledger journal
4635 files as well. It's safe, and encouraged, to run both hledger and
4636 ledger on the same journal file, eg to validate the results you're get‐
4637 ting.
4638 You can use hledger without learning any more about this file; just use
4640 the add or web or import commands to create and update it.
4641 Many users, though, edit the journal file with a text editor, and track
4643 changes with a version control system such as git. Editor addons such
4644 as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
4645 hledger-vscode for Visual Studio Code, make this easier, adding colour,
4646 formatting, tab completion, and useful commands. See Editor configura‐
4647 tion at hledger.org for the full list.
4648 Here's a description of each part of the file format (and hledger's
4650 data model). These are mostly in the order you'll use them, but in
4651 some cases related concepts have been grouped together for easy refer‐
4652 ence, or linked before they are introduced, so feel free to skip over
4653 anything that looks unnecessary right now.
4654 Transactions
4656 Transactions are the main unit of information in a journal file. They
4657 represent events, typically a movement of some quantity of commodities
4658 between two or more named accounts.
4659 Each transaction is recorded as a journal entry, beginning with a sim‐
4661 ple date in column 0. This can be followed by any of the following op‐
4662 tional fields, separated by spaces:
4663 • a status character (empty, !, or *)
4665 • a code (any short number or text, enclosed in parentheses)
4667 • a description (any remaining text until end of line or a semicolon)
4669 • a comment (any remaining text following a semicolon until end of
4671 line, and any following indented lines beginning with a semicolon)
4672 • 0 or more indented posting lines, describing what was transferred and
4674 the accounts involved (indented comment lines are also allowed, but
4675 not blank lines or non-indented lines).
4676 Here's a simple journal file containing one transaction:
4678 2008/01/01 income
4680 assets:bank:checking $1
4681 income:salary $-1
4682 Dates
4684 Simple dates
4685 Dates in the journal file use simple dates format: YYYY-MM-DD or
4686 YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be
4687 omitted, in which case it will be inferred from the context: the cur‐
4688 rent transaction, the default year set with a default year directive,
4689 or the current date when the command is run. Some examples:
4690 2010-01-31, 2010/01/31, 2010.1.31, 1/31.
4691 (The UI also accepts simple dates, as well as the more flexible smart
4693 dates documented in the hledger manual.)
4694 Secondary dates
4696 Real-life transactions sometimes involve more than one date - eg the
4697 date you write a cheque, and the date it clears in your bank. When you
4698 want to model this, for more accurate daily balances, you can specify
4699 individual posting dates.
4700 Or, you can use the older secondary date feature (Ledger calls it aux‐
4702 iliary date or effective date). Note: we support this for compatibil‐
4703 ity, but I usually recommend avoiding this feature; posting dates are
4704 almost always clearer and simpler.
4705 A secondary date is written after the primary date, following an equals
4707 sign. If the year is omitted, the primary date's year is assumed.
4708 When running reports, the primary (left) date is used by default, but
4709 with the --date2 flag (or --aux-date or --effective), the secondary
4710 (right) date will be used instead.
4711 The meaning of secondary dates is up to you, but it's best to follow a
4713 consistent rule. Eg "primary = the bank's clearing date, secondary =
4714 date the transaction was initiated, if different", as shown here:
4715 2010/2/23=2/19 movie ticket
4717 expenses:cinema $10
4718 assets:checking
4719 $ hledger register checking
4721 2010-02-23 movie ticket assets:checking $-10 $-10
4722 $ hledger register checking --date2
4724 2010-02-19 movie ticket assets:checking $-10 $-10
4725 Posting dates
4727 You can give individual postings a different date from their parent
4728 transaction, by adding a posting comment containing a tag (see below)
4729 like date:DATE. This is probably the best way to control posting dates
4730 precisely. Eg in this example the expense should appear in May re‐
4731 ports, and the deduction from checking should be reported on 6/1 for
4732 easy bank reconciliation:
4733 2015/5/30
4735 expenses:food $10 ; food purchased on saturday 5/30
4736 assets:checking ; bank cleared it on monday, date:6/1
4737 $ hledger -f t.j register food
4739 2015-05-30 expenses:food $10 $10
4740 $ hledger -f t.j register checking
4742 2015-06-01 assets:checking $-10 $-10
4743 DATE should be a simple date; if the year is not specified it will use
4745 the year of the transaction's date. You can set the secondary date
4746 similarly, with date2:DATE2. The date: or date2: tags must have a
4747 valid simple date value if they are present, eg a date: tag with no
4748 value is not allowed.
4749 Ledger's earlier, more compact bracketed date syntax is also supported:
4751 [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any
4752 square-bracketed sequence of the 0123456789/-.= characters in this way.
4753 With this syntax, DATE infers its year from the transaction and DATE2
4754 infers its year from DATE.
4755 Status
4757 Transactions, or individual postings within a transaction, can have a
4758 status mark, which is a single character before the transaction de‐
4759 scription or posting account name, separated from it by a space, indi‐
4760 cating one of three statuses:
4761 mark status
4763 ──────────────────
4764 unmarked
4765 ! pending
4766 * cleared
4767 When reporting, you can filter by status with the -U/--unmarked,
4769 -P/--pending, and -C/--cleared flags; or the status:, status:!, and
4770 status:* queries; or the U, P, C keys in hledger-ui.
4771 Note, in Ledger and in older versions of hledger, the "unmarked" state
4773 is called "uncleared". As of hledger 1.3 we have renamed it to un‐
4774 marked for clarity.
4775 To replicate Ledger and old hledger's behaviour of also matching pend‐
4777 ing, combine -U and -P.
4778 Status marks are optional, but can be helpful eg for reconciling with
4780 real-world accounts. Some editor modes provide highlighting and short‐
4781 cuts for working with status. Eg in Emacs ledger-mode, you can toggle
4782 transaction status with C-c C-e, or posting status with C-c C-c.
4783 What "uncleared", "pending", and "cleared" actually mean is up to you.
4785 Here's one suggestion:
4786 status meaning
4788 ──────────────────────────────────────────────────────────────────────────
4789 uncleared recorded but not yet reconciled; needs review
4790 pending tentatively reconciled (if needed, eg during a big reconcil‐
4791 iation)
4792 cleared complete, reconciled as far as possible, and considered cor‐
4793 rect
4794 With this scheme, you would use -PC to see the current balance at your
4796 bank, -U to see things which will probably hit your bank soon (like un‐
4797 cashed checks), and no flags to see the most up-to-date state of your
4798 finances.
4799 Code
4801 After the status mark, but before the description, you can optionally
4802 write a transaction "code", enclosed in parentheses. This is a good
4803 place to record a check number, or some other important transaction id
4804 or reference number.
4805 Description
4807 A transaction's description is the rest of the line following the date
4808 and status mark (or until a comment begins). Sometimes called the
4809 "narration" in traditional bookkeeping, it can be used for whatever you
4810 wish, or left blank. Transaction descriptions can be queried, unlike
4811 comments.
4812 Payee and note
4814 You can optionally include a | (pipe) character in descriptions to sub‐
4815 divide the description into separate fields for payee/payer name on the
4816 left (up to the first |) and an additional note field on the right (af‐
4817 ter the first |). This may be worthwhile if you need to do more pre‐
4818 cise querying and pivoting by payee or by note.
4819 Comments
4821 Lines in the journal beginning with a semicolon (;) or hash (#) or star
4822 (*) are comments, and will be ignored. (Star comments cause org-mode
4823 nodes to be ignored, allowing emacs users to fold and navigate their
4824 journals with org-mode or orgstruct-mode.)
4825 You can attach comments to a transaction by writing them after the de‐
4827 scription and/or indented on the following lines (before the postings).
4828 Similarly, you can attach comments to an individual posting by writing
4829 them after the amount and/or indented on the following lines. Transac‐
4830 tion and posting comments must begin with a semicolon (;).
4831 Some examples:
4833 # a file comment
4835 ; another file comment
4836 * also a file comment, useful in org/orgstruct mode
4837 comment
4839 A multiline file comment, which continues
4840 until a line containing just "end comment"
4841 (or end of file).
4842 end comment
4843 2012/5/14 something ; a transaction comment
4845 ; the transaction comment, continued
4846 posting1 1 ; a comment for posting 1
4847 posting2
4848 ; a comment for posting 2
4849 ; another comment line for posting 2
4850 ; a file comment (because not indented)
4851 You can also comment larger regions of a file using comment and end
4853 comment directives.
4854 Tags
4856 Tags are a way to add extra labels or labelled data to transactions,
4857 postings, or accounts, which you can then search or pivot on.
4858 They are written as a (optionally hyphenated) word immediately followed
4860 by a full colon within a transaction or posting or account directive's
4861 comment:
4862 account assets:checking ; accounttag:
4864 2017/1/16 bought groceries ; transaction-tag:
4866 ; another-transaction-tag:
4867 assets:checking $-1
4868 expenses:food $1 ; posting-tag:
4869 Tags are inherited, as follows:
4871 • Tags on a transaction affect the transaction and all of its postings
4873 • Tags on an account affect all postings to that account.
4875 So in the example above, - the assets:checking account has one tag (ac‐
4877 counttag) - the transaction has two tags (transaction-tag, another-
4878 transaction-tag) - the assets:checking posting has three tags (transac‐
4879 tion-tag, another-transaction-tag, accounttag) - the expenses:food
4880 posting has three tags (transaction-tag, another-transaction-tag, post‐
4881 ing-tag).
4882 Tags can have a value, which is the text after the colon, until the
4884 next comma or end of line, with surrounding whitespace stripped. So
4885 here a-posting-tag's value is "the tag value", tag2's value is "foo",
4886 and tag3's value is "" (the empty string):
4887 expenses:food $10
4889 ; some text, a-posting-tag:the tag value, tag2: foo , tag3: , other text
4890 A hledger tag value may not contain a comma.
4892 Postings
4894 A posting is an addition of some amount to, or removal of some amount
4895 from, an account. Each posting line begins with at least one space or
4896 tab (2 or 4 spaces is common), followed by:
4897 • (optional) a status character (empty, !, or *), followed by a space
4899 • (required) an account name (any text, optionally containing single
4901 spaces, until end of line or a double space)
4902 • (optional) two or more spaces or tabs followed by an amount.
4904 Positive amounts are being added to the account, negative amounts are
4906 being removed.
4907 The amounts within a transaction must always sum up to zero. As a con‐
4909 venience, one amount may be left blank; it will be inferred so as to
4910 balance the transaction.
4911 Be sure to note the unusual two-space delimiter between account name
4913 and amount. This makes it easy to write account names containing spa‐
4914 ces. But if you accidentally leave only one space (or tab) before the
4915 amount, the amount will be considered part of the account name.
4916 Virtual postings
4918 A posting with a parenthesised account name is called a virtual posting
4919 or unbalanced posting, which means it is exempt from the usual rule
4920 that a transaction's postings must balance add up to zero.
4921 This is not part of double entry accounting, so you might choose to
4923 avoid this feature. Or you can use it sparingly for certain special
4924 cases where it can be convenient. Eg, you could set opening balances
4925 without using a balancing equity account:
4926 1/1 opening balances
4928 (assets:checking) $1000
4929 (assets:savings) $2000
4930 A posting with a bracketed account name is called a balanced virtual
4932 posting. The balanced virtual postings in a transaction must add up to
4933 zero (separately from other postings). Eg:
4934 1/1 buy food with cash, update budget envelope subaccounts, & something else
4936 assets:cash $-10 ; <- these balance
4937 expenses:food $7 ; <-
4938 expenses:food $3 ; <-
4939 [assets:checking:budget:food] $-10 ; <- and these balance
4940 [assets:checking:available] $10 ; <-
4941 (something:else) $5 ; <- not required to balance
4942 Ordinary non-parenthesised, non-bracketed postings are called real
4944 postings. You can exclude virtual postings from reports with the
4945 -R/--real flag or real:1 query.
4946 Account names
4948 Account names typically have several parts separated by a full colon,
4949 from which hledger derives a hierarchical chart of accounts. They can
4950 be anything you like, but in finance there are traditionally five top-
4951 level accounts: assets, liabilities, revenue, expenses, and equity.
4952 Account names may contain single spaces, eg: assets:accounts receiv‐
4954 able. Because of this, they must always be followed by two or more
4955 spaces (or newline).
4956 Account names can be aliased.
4958 Amounts
4960 After the account name, there is usually an amount. (Important: be‐
4961 tween account name and amount, there must be two or more spaces.)
4962 hledger's amount format is flexible, supporting several international
4964 formats. Here are some examples. Amounts have a number (the "quan‐
4965 tity"):
4966 1
4968 ..and usually a currency symbol or commodity name (more on this below),
4970 to the left or right of the quantity, with or without a separating
4971 space:
4972 $1
4974 4000 AAPL
4975 3 "green apples"
4976 Amounts can be preceded by a minus sign (or a plus sign, though plus is
4978 the default), The sign can be written before or after a left-side com‐
4979 modity symbol:
4980 -$1
4982 $-1
4983 One or more spaces between the sign and the number are acceptable when
4985 parsing (but they won't be displayed in output):
4986 + $1
4988 $- 1
4989 Scientific E notation is allowed:
4991 1E-6
4993 EUR 1E3
4994 Decimal marks, digit group marks
4996 A decimal mark can be written as a period or a comma:
4997 1.23
4999 1,23456780000009
5000 In the integer part of the quantity (left of the decimal mark), groups
5002 of digits can optionally be separated by a digit group mark - a space,
5003 comma, or period (different from the decimal mark):
5004 $1,000,000.00
5006 EUR 2.000.000,00
5007 INR 9,99,99,999.00
5008 1 000 000.9455
5009 Note, a number containing a single digit group mark and no decimal mark
5011 is ambiguous. Are these digit group marks or decimal marks ?
5012 1,000
5014 1.000
5015 If you don't tell it otherwise, hledger will assume both of the above
5017 are decimal marks, parsing both numbers as 1.
5018 To prevent confusing parsing mistakes and undetected typos, especially
5020 if your data contains digit group marks (eg, thousands separators), we
5021 recommend explicitly declaring the decimal mark character in each jour‐
5022 nal file, using a directive at the top of the file. The decimal-mark
5023 directive is best, otherwise commodity directives will also work.
5024 These are described detail below.
5025 Commodity
5027 Amounts in hledger have both a "quantity", which is a signed decimal
5028 number, and a "commodity", which is a currency symbol, stock ticker, or
5029 any word or phrase describing something you are tracking.
5030 If the commodity name contains non-letters (spaces, numbers, or punctu‐
5032 ation), you must always write it inside double quotes ("green apples",
5033 "ABC123").
5034 If you write just a bare number, that too will have a commodity, with
5036 name ""; we call that the "no-symbol commodity".
5037 Actually, hledger combines these single-commodity amounts into more
5039 powerful multi-commodity amounts, which are what it works with most of
5040 the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456
5041 TSLA. In practice, you will only see multi-commodity amounts in
5042 hledger's output; you can't write them directly in the journal file.
5043 (If you are writing scripts or working with hledger's internals, these
5045 are the Amount and MixedAmount types.)
5046 Directives influencing number parsing and display
5048 You can add decimal-mark and commodity directives to the journal, to
5049 declare and control these things more explicitly and precisely. These
5050 are described below, in JOURNAL FORMAT -> Declaring commodities.
5051 Here's a quick example:
5052 # the decimal mark character used by all amounts in this file (all commodities)
5054 decimal-mark .
5055 # display styles for the $, EUR, INR and no-symbol commodities:
5057 commodity $1,000.00
5058 commodity EUR 1.000,00
5059 commodity INR 9,99,99,999.00
5060 commodity 1 000 000.9455
5061 Commodity display style
5063 For the amounts in each commodity, hledger chooses a consistent display
5064 style to use in most reports. (Exceptions: price amounts, and all
5065 amounts displayed by the print command, are displayed with all of their
5066 decimal digits visible.)
5067 A commodity's display style is inferred as follows.
5069 First, if a default commodity is declared with D, this commodity and
5071 its style is applied to any no-symbol amounts in the journal.
5072 Then each commodity's style is inferred from one of the following, in
5074 order of preference:
5075 • The commodity directive for that commodity (including the no-symbol
5077 commodity), if any.
5078 • The amounts in that commodity seen in the journal's transactions.
5080 (Posting amounts only; prices and periodic or auto rules are ignored,
5081 currently.)
5082 • The built-in fallback style, which looks like this: $1000.00. (Sym‐
5084 bol on the left, period decimal mark, two decimal places.)
5085 A style is inferred from journal amounts as follows:
5087 • Use the general style (decimal mark, symbol placement) of the first
5089 amount
5090 • Use the first-seen digit group style (digit group mark, digit group
5092 sizes), if any
5093 • Use the maximum number of decimal places of all.
5095 Transaction price amounts don't affect the commodity display style di‐
5097 rectly, but occasionally they can do so indirectly (eg when a posting's
5098 amount is inferred using a transaction price). If you find this caus‐
5099 ing problems, use a commodity directive to fix the display style.
5100 To summarise: each commodity's amounts will be normalised to (a) the
5102 style declared by a commodity directive, or (b) the style of the first
5103 posting amount in the journal, with the first-seen digit group style
5104 and the maximum-seen number of decimal places. So if your reports are
5105 showing amounts in a way you don't like, eg with too many decimal
5106 places, use a commodity directive. Some examples:
5107 # declare euro, dollar, bitcoin and no-symbol commodities and set their
5109 # input number formats and output display styles:
5110 commodity EUR 1.000,
5111 commodity $1000.00
5112 commodity 1000.00000000 BTC
5113 commodity 1 000.
5114 The inferred commodity style can be overridden by supplying a command
5116 line option.
5117 Rounding
5119 Amounts are stored internally as decimal numbers with up to 255 decimal
5120 places, and displayed with the number of decimal places specified by
5121 the commodity display style. Note, hledger uses banker's rounding: it
5122 rounds to the nearest even number, eg 0.5 displayed with zero decimal
5123 places is "0"). (Guaranteed since hledger 1.17.1; in older versions
5124 this could vary if hledger was built with Decimal < 0.5.1.)
5125 Transaction prices
5127 (AKA Costs)
5128 After a posting amount, you can note its cost or selling price in an‐
5130 other commodity, by writing either @ UNITPRICE or @@ TOTALPRICE after
5131 it. This indicates a conversion transaction, where one commodity is
5132 exchanged for another.
5133 hledger docs have historically called this a "transaction price" be‐
5135 cause it is specific to one transaction, unlike market prices which are
5136 not. "Cost" is shorter and might be preferable; just remember this
5137 feature can represent either a buyer's cost, or a seller's price.
5138 Costs are usually written explicitly with @ or @@, but can also be in‐
5140 ferred automatically for simple multi-commodity transactions.
5141 As an example, here are several ways to record purchases of a foreign
5142 currency in hledger, using the cost notation either explicitly or im‐
5143 plicitly:
5144 1. Write the price per unit, as @ UNITPRICE after the amount:
5146 2009/1/1
5148 assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each
5149 assets:dollars ; balancing amount is -$135.00
5150 2. Write the total price, as @@ TOTALPRICE after the amount:
5152 2009/1/1
5154 assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot
5155 assets:dollars
5156 3. Specify amounts for all postings, using exactly two commodities, and
5158 let hledger infer the price that balances the transaction:
5159 2009/1/1
5161 assets:euros €100 ; one hundred euros purchased
5162 assets:dollars $-135 ; for $135
5163 4. Like 1, but the @ is parenthesised, i.e. (@); this is for compati‐
5165 bility with Ledger journals (Virtual posting costs), and is equiva‐
5166 lent to 1 in hledger.
5167 5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger,
5169 this is equivalent to 2.
5170 Amounts can be converted to cost at report time using the -B/--cost
5172 flag; this is discussed more in the COST section.
5173 Lot prices, lot dates
5175 Ledger allows another kind of price, lot price (four variants: {UNIT‐
5176 PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}),
5177 and/or a lot date ([DATE]) to be specified. These are normally used to
5178 select a lot when selling investments. hledger will parse these, for
5179 compatibility with Ledger journals, but currently ignores them. A
5180 transaction price, lot price and/or lot date may appear in any order,
5181 after the posting amount and before the balance assertion if any.
5182 Balance assertions
5184 hledger supports Ledger-style balance assertions in journal files.
5185 These look like, for example, = EXPECTEDBALANCE following a posting's
5186 amount. Eg here we assert the expected dollar balance in accounts a
5187 and b after each posting:
5188 2013/1/1
5190 a $1 =$1
5191 b =$-1
5192 2013/1/2
5194 a $1 =$2
5195 b $-1 =$-2
5196 After reading a journal file, hledger will check all balance assertions
5198 and report an error if any of them fail. Balance assertions can pro‐
5199 tect you from, eg, inadvertently disrupting reconciled balances while
5200 cleaning up old entries. You can disable them temporarily with the
5201 -I/--ignore-assertions flag, which can be useful for troubleshooting or
5202 for reading Ledger files. (Note: this flag currently does not disable
5203 balance assignments, below).
5204 Assertions and ordering
5206 hledger sorts an account's postings and assertions first by date and
5207 then (for postings on the same day) by parse order. Note this is dif‐
5208 ferent from Ledger, which sorts assertions only by parse order. (Also,
5209 Ledger assertions do not see the accumulated effect of repeated post‐
5210 ings to the same account within a transaction.)
5211 So, hledger balance assertions keep working if you reorder differently-
5213 dated transactions within the journal. But if you reorder same-dated
5214 transactions or postings, assertions might break and require updating.
5215 This order dependence does bring an advantage: precise control over the
5216 order of postings and assertions within a day, so you can assert intra-
5217 day balances.
5218 Assertions and multiple included files
5220 Multiple files included with the include directive are processed as if
5221 concatenated into one file, preserving their order and the posting or‐
5222 der within each file. It means that balance assertions in later files
5223 will see balance from earlier files.
5224 And if you have multiple postings to an account on the same day, split
5226 across multiple files, and you want to assert the account's balance on
5227 that day, you'll need to put the assertion in the right file - the last
5228 one in the sequence, probably.
5229 Assertions and multiple -f files
5231 Unlike include, when multiple files are specified on the command line
5232 with multiple -f/--file options, balance assertions will not see bal‐
5233 ance from earlier files. This can be useful when you do not want prob‐
5234 lems in earlier files to disrupt valid assertions in later files.
5235 If you do want assertions to see balance from earlier files, use in‐
5237 clude, or concatenate the files temporarily.
5238 Assertions and commodities
5240 The asserted balance must be a simple single-commodity amount, and in
5241 fact the assertion checks only this commodity's balance within the
5242 (possibly multi-commodity) account balance. This is how assertions
5243 work in Ledger also. We could call this a "partial" balance assertion.
5244 To assert the balance of more than one commodity in an account, you can
5246 write multiple postings, each asserting one commodity's balance.
5247 You can make a stronger "total" balance assertion by writing a double
5249 equals sign (== EXPECTEDBALANCE). This asserts that there are no other
5250 commodities in the account besides the asserted one (or at least, that
5251 their balance is 0).
5252 2013/1/1
5254 a $1
5255 a 1€
5256 b $-1
5257 c -1€
5258 2013/1/2 ; These assertions succeed
5260 a 0 = $1
5261 a 0 = 1€
5262 b 0 == $-1
5263 c 0 == -1€
5264 2013/1/3 ; This assertion fails as 'a' also contains 1€
5266 a 0 == $1
5267 It's not yet possible to make a complete assertion about a balance that
5269 has multiple commodities. One workaround is to isolate each commodity
5270 into its own subaccount:
5271 2013/1/1
5273 a:usd $1
5274 a:euro 1€
5275 b
5276 2013/1/2
5278 a 0 == 0
5279 a:usd 0 == $1
5280 a:euro 0 == 1€
5281 Assertions and prices
5283 Balance assertions ignore transaction prices, and should normally be
5284 written without one:
5285 2019/1/1
5287 (a) $1 @ €1 = $1
5288 We do allow prices to be written there, however, and print shows them,
5290 even though they don't affect whether the assertion passes or fails.
5291 This is for backward compatibility (hledger's close command used to
5292 generate balance assertions with prices), and because balance assign‐
5293 ments do use them (see below).
5294 Assertions and subaccounts
5296 The balance assertions above (= and ==) do not count the balance from
5297 subaccounts; they check the account's exclusive balance only. You can
5298 assert the balance including subaccounts by writing =* or ==*, eg:
5299 2019/1/1
5301 equity:opening balances
5302 checking:a 5
5303 checking:b 5
5304 checking 1 ==* 11
5305 Assertions and virtual postings
5307 Balance assertions always consider both real and virtual postings; they
5308 are not affected by the --real/-R flag or real: query.
5309 Assertions and auto postings
5311 Balance assertions are affected by the --auto flag, which generates
5312 auto postings, which can alter account balances. Because auto postings
5313 are optional in hledger, accounts affected by them effectively have two
5314 balances. But balance assertions can only test one or the other of
5315 these. So to avoid making fragile assertions, either:
5316 • assert the balance calculated with --auto, and always use --auto with
5318 that file
5319 • or assert the balance calculated without --auto, and never use --auto
5321 with that file
5322 • or avoid balance assertions on accounts affected by auto postings (or
5324 avoid auto postings entirely).
5325 Assertions and precision
5327 Balance assertions compare the exactly calculated amounts, which are
5328 not always what is shown by reports. Eg a commodity directive may
5329 limit the display precision, but this will not affect balance asser‐
5330 tions. Balance assertion failure messages show exact amounts.
5331 Balance assignments
5333 Ledger-style balance assignments are also supported. These are like
5334 balance assertions, but with no posting amount on the left side of the
5335 equals sign; instead it is calculated automatically so as to satisfy
5336 the assertion. This can be a convenience during data entry, eg when
5337 setting opening balances:
5338 ; starting a new journal, set asset account balances
5340 2016/1/1 opening balances
5341 assets:checking = $409.32
5342 assets:savings = $735.24
5343 assets:cash = $42
5344 equity:opening balances
5345 or when adjusting a balance to reality:
5347 ; no cash left; update balance, record any untracked spending as a generic expense
5349 2016/1/15
5350 assets:cash = $0
5351 expenses:misc
5352 The calculated amount depends on the account's balance in the commodity
5354 at that point (which depends on the previously-dated postings of the
5355 commodity to that account since the last balance assertion or assign‐
5356 ment). Note that using balance assignments makes your journal a little
5357 less explicit; to know the exact amount posted, you have to run hledger
5358 or do the calculations yourself, instead of just reading it.
5359 Balance assignments and prices
5361 A transaction price in a balance assignment will cause the calculated
5362 amount to have that price attached:
5363 2019/1/1
5365 (a) = $1 @ €2
5366 $ hledger print --explicit
5368 2019-01-01
5369 (a) $1 @ €2 = $1 @ €2
5370 Directives
5372 A directive is a line in the journal beginning with a special keyword,
5373 that influences how the journal is processed, how things are displayed,
5374 and so on. hledger's directives are based on (a subset of) Ledger's,
5375 but there are many differences, and also some differences between
5376 hledger versions. Here are some more definitions:
5377 • subdirective - Some directives support subdirectives, written in‐
5379 dented below the parent directive.
5380 • decimal mark - The character to interpret as a decimal mark (period
5382 or comma) when parsing amounts of a commodity.
5383 • display style - How to display amounts of a commodity in output: sym‐
5385 bol side and spacing, digit groups, decimal mark, and number of deci‐
5386 mal places.
5387 Directives are not required when starting out with hledger, but you
5389 will probably add some as your needs grow. Here is an overview of di‐
5390 rectives by purpose:
5391 purpose directives command line op‐
5393 tions with simi‐
5394 lar effect
5395 ─────────────────────────────────────────────────────────────────────────────
5396 READING/GENERATING DATA:
5397 Declare a commodity's or file's commodity, D, decimal-
5398 decimal mark to help parse mark
5399 amounts accurately
5400 Apply changes to the data while alias, apply account, --alias
5401 parsing comment, D, Y
5402 Inline extra data files include multiple
5403 -f/--file's
5404 Generate extra transactions or ~
5405 budget goals
5406 Generate extra postings =
5407 CHECKING FOR ERRORS:
5408 Define valid entities to allow account, commodity,
5409 stricter error checking payee
5410 DISPLAYING REPORTS:
5411 Declare accounts' display order account
5412 and accounting type
5413 Declare commodity display commodity, D -c/--commodity-
5414 styles style
5415 And here are all the directives and their precise effects:
5417 di‐ effects ends
5419 rec‐ at
5420 tive file
5421 end?
5422 ──────────────────────────────────────────────────────────────────────────────────
5423 ac‐ Declares an account, for checking all entries in all files;
5426 count and its display order and type, for reports. Subdirectives:
5427 any text, ignored.
5428 alias Rewrites account names, in following entries until end of Y
5429 current file or end aliases.
5430 apply Prepends a common parent account to all account names, in Y
5431 ac‐ following entries until end of current file or end apply ac‐
5432 count count.
5433 com‐ Ignores part of the journal file, until end of current file Y
5434 ment or end comment.
5435 com‐ Declares a commodity, for checking all entries in all files; N, Y
5436 mod‐ the decimal mark for parsing amounts of this commodity, for
5437 ity following entries until end of current file; and its display
5438 style, for reports. Takes precedence over D. Subdirectives:
5439 format (alternate syntax).
5440 D Sets a default commodity to use for no-symbol amounts, and Y
5441 its decimal mark for parsing amounts of this commodity in
5442 following entries until end of current file; and its display
5443 style, for reports.
5444 deci‐ Declares the decimal mark, for parsing amounts of all com‐ Y
5445 mal- modities in following entries until next decimal-mark or end
5446 mark of current file. Included files can override. Takes prece‐
5447 dence over commodity and D.
5448 in‐ Includes entries and directives from another file, as if they
5449 clude were written inline.
5450 payee Declares a payee name, for checking all entries in all files.
5451 P Declares a market price for a commodity on some date, for
5452 valuation reports.
5453 Y Declares a year for yearless dates, for following entries un‐ Y
5454 til end of current file.
5455 ~ Declares a periodic transaction rule that generates future
5456 (tilde) transactions with --forecast and budget goals with balance
5457 --budget.
5458 = Declares an auto posting rule that generates extra postings partly
5459 (equals) on matched transactions with --auto, in current, parent, and
5460 child files (but not sibling files, see #1212).
5461 Directives and multiple files
5463 If you use multiple -f/--file options, or the include directive,
5464 hledger will process multiple input files. But directives which affect
5465 input typically have effect only until the end of the file in which
5466 they occur (and on any included files in that region).
5467 This may seem inconvenient, but it's intentional; it makes reports sta‐
5469 ble and deterministic, independent of the order of input. Otherwise
5470 you could see different numbers if you happened to write -f options in
5471 a different order, or if you moved includes around while cleaning up
5472 your files.
5473 It can be surprising though; for example, it means that alias direc‐
5475 tives do not affect parent or sibling files (see below).
5476 Comment blocks
5478 A line containing just comment starts a commented region of the file,
5479 and a line containing just end comment (or the end of the current file)
5480 ends it. See also comments.
5481 Including other files
5483 You can pull in the content of additional files by writing an include
5484 directive, like this:
5485 include FILEPATH
5487 Only journal files can include, and only journal, timeclock or timedot
5489 files can be included (not CSV files, currently).
5490 If the file path does not begin with a slash, it is relative to the
5492 current file's folder.
5493 A tilde means home directory, eg: include ~/main.journal.
5495 The path may contain glob patterns to match multiple files, eg: include
5497 *.journal.
5498 There is limited support for recursive wildcards: **/ (the slash is re‐
5500 quired) matches 0 or more subdirectories. It's not super convenient
5501 since you have to avoid include cycles and including directories, but
5502 this can be done, eg: include */**/*.journal.
5503 The path may also be prefixed to force a specific file format, overrid‐
5505 ing the file extension (as described in hledger.1 -> Input files): in‐
5506 clude timedot:~/notes/2020*.md.
5507 Default year
5509 You can set a default year to be used for subsequent dates which don't
5510 specify a year. This is a line beginning with Y followed by the year.
5511 Eg:
5512 Y2009 ; set default year to 2009
5514 12/15 ; equivalent to 2009/12/15
5516 expenses 1
5517 assets
5518 Y2010 ; change default year to 2010
5520 2009/1/30 ; specifies the year, not affected
5522 expenses 1
5523 assets
5524 1/31 ; equivalent to 2010/1/31
5526 expenses 1
5527 assets
5528 Declaring payees
5530 The payee directive can be used to declare a limited set of payees
5531 which may appear in transaction descriptions. The "payees" check will
5532 report an error if any transaction refers to a payee that has not been
5533 declared. Eg:
5534 payee Whole Foods
5536 Declaring the decimal mark
5538 You can use a decimal-mark directive - usually one per file, at the top
5539 of the file - to declare which character represents a decimal mark when
5540 parsing amounts in this file. It can look like
5541 decimal-mark .
5543 or
5545 decimal-mark ,
5547 This prevents any ambiguity when parsing numbers in the file, so we
5549 recommend it, especially if the file contains digit group marks (eg
5550 thousands separators).
5551 Declaring commodities
5553 You can use commodity directives to declare your commodities. In fact
5554 the commodity directive performs several functions at once:
5555 1. It declares commodities which may be used in the journal. This can
5557 optionally be enforced, providing useful error checking. (Cf Com‐
5558 modity error checking)
5559 2. It declares which decimal mark character (period or comma), to ex‐
5561 pect when parsing input - useful to disambiguate international num‐
5562 ber formats in your data. Without this, hledger will parse both
5563 1,000 and 1.000 as 1. (Cf Amounts)
5564 3. It declares how to render the commodity's amounts when displaying
5566 output - the decimal mark, any digit group marks, the number of dec‐
5567 imal places, symbol placement and so on. (Cf Commodity display
5568 style)
5569 You will run into one of the problems solved by commodity directives
5571 sooner or later, so we recommend using them, for robust and predictable
5572 parsing and display.
5573 Generally you should put them at the top of your journal file (since
5575 for function 2, they affect only following amounts, cf #793).
5576 A commodity directive is just the word commodity followed by a sample
5578 amount, like this:
5579 ;commodity SAMPLEAMOUNT
5581 commodity $1000.00
5583 commodity 1,000.0000 AAAA ; optional same-line comment
5584 It may also be written on multiple lines, and use the format subdirec‐
5586 tive, as in Ledger. Note in this case the commodity symbol appears
5587 twice; it must be the same in both places:
5588 ;commodity SYMBOL
5590 ; format SAMPLEAMOUNT
5591 ; display indian rupees with currency name on the left,
5593 ; thousands, lakhs and crores comma-separated,
5594 ; period as decimal point, and two decimal places.
5595 commodity INR
5596 format INR 1,00,00,000.00
5597 Remember that if the commodity symbol contains spaces, numbers, or
5599 punctuation, it must be enclosed in double quotes (cf Commodity).
5600 The amount's quantity does not matter; only the format is significant.
5602 It must include a decimal mark - either a period or a comma - followed
5603 by 0 or more decimal digits.
5604 A few more examples:
5606 # number formats for $, EUR, INR and the no-symbol commodity:
5608 commodity $1,000.00
5609 commodity EUR 1.000,00
5610 commodity INR 9,99,99,999.0
5611 commodity 1 000 000.
5612 Note hledger normally uses banker's rounding, so 0.5 displayed with
5614 zero decimal digits is "0". (More at Commodity display style.)
5615 Even in the presence of commodity directives, the commodity display
5617 style can still be overridden by supplying a command line option.
5618 Commodity error checking
5620 In strict mode, enabled with the -s/--strict flag, hledger will report
5621 an error if a commodity symbol is used that has not been declared by a
5622 commodity directive. This works similarly to account error checking,
5623 see the notes there for more details.
5624 Note, this disallows amounts without a commodity symbol, because cur‐
5626 rently it's not possible (?) to declare the "no-symbol" commodity with
5627 a directive. This is one exception for convenience: zero amounts are
5628 always allowed to have no commodity symbol.
5629 Default commodity
5631 The D directive sets a default commodity, to be used for any subsequent
5632 commodityless amounts (ie, plain numbers) seen while parsing the jour‐
5633 nal. This effect lasts until the next D directive, or the end of the
5634 journal.
5635 For compatibility/historical reasons, D also acts like a commodity di‐
5637 rective (setting the commodity's decimal mark for parsing and display
5638 style for output).
5639 The syntax is D AMOUNT. As with commodity, the amount must include a
5641 decimal mark (either period or comma). Eg:
5642 ; commodity-less amounts should be treated as dollars
5644 ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
5645 D $1,000.00
5646 1/1
5648 a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
5649 b
5650 If both commodity and D directives are found for a commodity, commodity
5652 takes precedence for setting decimal mark and display style.
5653 If you are using D and also checking commodities, you will need to add
5655 a commodity directive similar to the D. (The hledger check commodities
5656 command expects commodity directives, and ignores D).
5657 Declaring market prices
5659 The P directive declares a market price, which is an exchange rate be‐
5660 tween two commodities on a certain date. (In Ledger, they are called
5661 "historical prices".) These are often obtained from a stock exchange,
5662 cryptocurrency exchange, or the foreign exchange market.
5663 The format is:
5665 P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT
5667 DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity
5669 being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity)
5670 of commodity 2 that one unit of commodity 1 is worth on this date. Ex‐
5671 amples:
5672 # one euro was worth $1.35 from 2009-01-01 onward:
5674 P 2009-01-01 € $1.35
5675 # and $1.40 from 2010-01-01 onward:
5677 P 2010-01-01 € $1.40
5678 The -V, -X and --value flags use these market prices to show amount
5680 values in another commodity. See Valuation.
5681 Declaring accounts
5683 account directives can be used to declare accounts (ie, the places that
5684 amounts are transferred from and to). Though not required, these dec‐
5685 larations can provide several benefits:
5686 • They can document your intended chart of accounts, providing a refer‐
5688 ence.
5689 • In strict mode, they restrict which accounts may be posted to by
5691 transactions, which helps detect typos.
5692 • They control account display order in reports, allowing non-alpha‐
5694 betic sorting (eg Revenues to appear above Expenses).
5695 • They help with account name completion (in hledger add, hledger-web,
5697 hledger-iadd, ledger-mode, etc.)
5698 • They can store additional account information as comments, or as tags
5700 which can be used to filter or pivot reports.
5701 • They can help hledger know your accounts' types (asset, liability,
5703 equity, revenue, expense), affecting reports like balancesheet and
5704 incomestatement.
5705 They are written as the word account followed by a hledger-style ac‐
5707 count name, eg:
5708 account assets:bank:checking
5710 Account comments
5712 Comments, beginning with a semicolon:
5713 • can be written on the same line, but only after two or more spaces
5715 (because ; is allowed in account names)
5716 • and/or on the next lines, indented
5718 • and may contain tags, such as the type: tag.
5720 For example:
5722 account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon
5724 ; next-line comment
5725 ; some tags - type:A, acctnum:12345
5726 Account subdirectives
5728 Ledger-style indented subdirectives are also accepted, but currently
5729 ignored:
5730 account assets:bank:checking
5732 format subdirective is ignored
5733 Account error checking
5735 By default, accounts need not be declared; they come into existence
5736 when a posting references them. This is convenient, but it means
5737 hledger can't warn you when you mis-spell an account name in the jour‐
5738 nal. Usually you'll find that error later, as an extra account in bal‐
5739 ance reports, or an incorrect balance when reconciling.
5740 In strict mode, enabled with the -s/--strict flag, hledger will report
5742 an error if any transaction uses an account name that has not been de‐
5743 clared by an account directive. Some notes:
5744 • The declaration is case-sensitive; transactions must use the correct
5746 account name capitalisation.
5747 • The account directive's scope is "whole file and below" (see direc‐
5749 tives). This means it affects all of the current file, and any files
5750 it includes, but not parent or sibling files. The position of ac‐
5751 count directives within the file does not matter, though it's usual
5752 to put them at the top.
5753 • Accounts can only be declared in journal files, but will affect in‐
5755 cluded files of all types.
5756 • It's currently not possible to declare "all possible subaccounts"
5758 with a wildcard; every account posted to must be declared.
5759 Account display order
5761 The order in which account directives are written influences the order
5762 in which accounts appear in reports, hledger-ui, hledger-web etc. By
5763 default accounts appear in alphabetical order, but if you add these ac‐
5764 count directives to the journal file:
5765 account assets
5767 account liabilities
5768 account equity
5769 account revenues
5770 account expenses
5771 those accounts will be displayed in declaration order:
5773 $ hledger accounts -1
5775 assets
5776 liabilities
5777 equity
5778 revenues
5779 expenses
5780 Any undeclared accounts are displayed last, in alphabetical order.
5782 Sorting is done at each level of the account tree, within each group of
5784 sibling accounts under the same parent. And currently, this directive:
5785 account other:zoo
5787 would influence the position of zoo among other's subaccounts, but not
5789 the position of other among the top-level accounts. This means:
5790 • you will sometimes declare parent accounts (eg account other above)
5792 that you don't intend to post to, just to customize their display or‐
5793 der
5794 • sibling accounts stay together (you couldn't display x:y in between
5796 a:b and a:c).
5797 Account types
5799 hledger knows that accounts come in several types: assets, liabilities,
5800 expenses and so on. This enables easy reports like balancesheet and
5801 incomestatement, and filtering by account type with the type: query.
5802 As a convenience, hledger will detect these account types automatically
5804 if you are using common english-language top-level account names (de‐
5805 scribed below). But generally we recommend you declare types explic‐
5806 itly, by adding a type: tag to your top-level account directives. Sub‐
5807 accounts will inherit the type of their parent. The tag's value should
5808 be one of the five main account types:
5809 • A or Asset (things you own)
5811 • L or Liability (things you owe)
5813 • E or Equity (investment/ownership; balanced counterpart of assets &
5815 liabilities)
5816 • R or Revenue (what you received money from, AKA income; technically
5818 part of Equity)
5819 • X or Expense (what you spend money on; technically part of Equity)
5821 or, it can be (these are used less often):
5823 • C or Cash (a subtype of Asset, indicating liquid assets for the cash‐
5825 flow report)
5826 • V or Conversion (a subtype of Equity, for conversions (see COST).)
5828 Here is a typical set of account type declarations:
5830 account assets ; type: A
5832 account liabilities ; type: L
5833 account equity ; type: E
5834 account revenues ; type: R
5835 account expenses ; type: X
5836 account assets:bank ; type: C
5838 account assets:cash ; type: C
5839 account equity:conversion ; type: V
5841 Here are some tips for working with account types.
5843 • The rules for inferring types from account names are as follows.
5845 These are just a convenience that sometimes help new users get going;
5846 if they don't work for you, just ignore them and declare your account
5847 types. See also Regular expressions. Note the Cash regexp changed
5848 in hledger 1.24.99.2.
5849 If account's name contains this (CI) regular expression: | its type is:
5851 --------------------------------------------------------------------|-------------
5852 ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash
5853 ^assets?(:|$) | Asset
5854 ^(debts?|liabilit(y|ies))(:|$) | Liability
5855 ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion
5856 ^equity(:|$) | Equity
5857 ^(income|revenue)s?(:|$) | Revenue
5858 ^expenses?(:|$) | Expense
5859 • If you declare any account types, it's a good idea to declare an ac‐
5861 count for all of the account types, because a mixture of declared and
5862 name-inferred types can disrupt certain reports.
5863 • Certain uses of account aliases can disrupt account types. See
5865 Rewriting accounts > Aliases and account types.
5866 • As mentioned above, subaccounts will inherit a type from their parent
5868 account. More precisely, an account's type is decided by the first
5869 of these that exists:
5870 1. A type: declaration for this account.
5872 2. A type: declaration in the parent accounts above it, preferring
5874 the nearest.
5875 3. An account type inferred from this account's name.
5877 4. An account type inferred from a parent account's name, preferring
5879 the nearest parent.
5880 5. Otherwise, it will have no type.
5882 • For troubleshooting, you can list accounts and their types with:
5884 $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]
5886 Rewriting accounts
5888 You can define account alias rules which rewrite your account names, or
5889 parts of them, before generating reports. This can be useful for:
5890 • expanding shorthand account names to their full form, allowing easier
5892 data entry and a less verbose journal
5893 • adapting old journals to your current chart of accounts
5895 • experimenting with new account organisations, like a new hierarchy
5897 • combining two accounts into one, eg to see their sum or difference on
5899 one line
5900 • customising reports
5902 Account aliases also rewrite account names in account directives. They
5904 do not affect account names being entered via hledger add or hledger-
5905 web.
5906 Account aliases are very powerful. They are generally easy to use cor‐
5908 rectly, but you can also generate invalid account names with them; more
5909 on this below.
5910 See also Rewrite account names.
5912 Basic aliases
5914 To set an account alias, use the alias directive in your journal file.
5915 This affects all subsequent journal entries in the current file or its
5916 included files (but note: not sibling or parent files). The spaces
5917 around the = are optional:
5918 alias OLD = NEW
5920 Or, you can use the --alias 'OLD=NEW' option on the command line. This
5922 affects all entries. It's useful for trying out aliases interactively.
5923 OLD and NEW are case sensitive full account names. hledger will re‐
5925 place any occurrence of the old account name with the new one. Subac‐
5926 counts are also affected. Eg:
5927 alias checking = assets:bank:wells fargo:checking
5929 ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
5930 Regex aliases
5932 There is also a more powerful variant that uses a regular expression,
5933 indicated by wrapping the pattern in forward slashes. (This is the
5934 only place where hledger requires forward slashes around a regular ex‐
5935 pression.)
5936 Eg:
5938 alias /REGEX/ = REPLACEMENT
5940 or:
5942 $ hledger --alias '/REGEX/=REPLACEMENT' ...
5944 Any part of an account name matched by REGEX will be replaced by RE‐
5946 PLACEMENT. REGEX is case-insensitive as usual.
5947 If you need to match a forward slash, escape it with a backslash, eg
5949 /\/=:.
5950 If REGEX contains parenthesised match groups, these can be referenced
5952 by the usual backslash and number in REPLACEMENT:
5953 alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
5955 ; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
5956 REPLACEMENT continues to the end of line (or on command line, to end of
5958 option argument), so it can contain trailing whitespace.
5959 Combining aliases
5961 You can define as many aliases as you like, using journal directives
5962 and/or command line options.
5963 Recursive aliases - where an account name is rewritten by one alias,
5965 then by another alias, and so on - are allowed. Each alias sees the
5966 effect of previously applied aliases.
5967 In such cases it can be important to understand which aliases will be
5969 applied and in which order. For (each account name in) each journal
5970 entry, we apply:
5971 1. alias directives preceding the journal entry, most recently parsed
5973 first (ie, reading upward from the journal entry, bottom to top)
5974 2. --alias options, in the order they appeared on the command line
5976 (left to right).
5977 In other words, for (an account name in) a given journal entry:
5979 • the nearest alias declaration before/above the entry is applied first
5981 • the next alias before/above that will be be applied next, and so on
5983 • aliases defined after/below the entry do not affect it.
5985 This gives nearby aliases precedence over distant ones, and helps pro‐
5987 vide semantic stability - aliases will keep working the same way inde‐
5988 pendent of which files are being read and in which order.
5989 In case of trouble, adding --debug=6 to the command line will show
5991 which aliases are being applied when.
5992 Aliases and multiple files
5994 As explained at Directives and multiple files, alias directives do not
5995 affect parent or sibling files. Eg in this command,
5996 hledger -f a.aliases -f b.journal
5998 account aliases defined in a.aliases will not affect b.journal. In‐
6000 cluding the aliases doesn't work either:
6001 include a.aliases
6003 2020-01-01 ; not affected by a.aliases
6005 foo 1
6006 bar
6007 This means that account aliases should usually be declared at the start
6009 of your top-most file, like this:
6010 alias foo=Foo
6012 alias bar=Bar
6013 2020-01-01 ; affected by aliases above
6015 foo 1
6016 bar
6017 include c.journal ; also affected
6019 end aliases
6021 You can clear (forget) all currently defined aliases (seen in the jour‐
6022 nal so far, or defined on the command line) with this directive:
6023 end aliases
6025 Aliases can generate bad account names
6027 Be aware that account aliases can produce malformed account names,
6028 which could cause confusing reports or invalid print output. For exam‐
6029 ple, you could erase all account names:
6030 2021-01-01
6032 a:aa 1
6033 b
6034 $ hledger print --alias '/.*/='
6036 2021-01-01
6037 1
6038 The above print output is not a valid journal. Or you could insert an
6040 illegal double space, causing print output that would give a different
6041 journal when reparsed:
6042 2021-01-01
6044 old 1
6045 other
6046 $ hledger print --alias old="new USD" | hledger -f- print
6048 2021-01-01
6049 new USD 1
6050 other
6051 Aliases and account types
6053 If an account with a type declaration (see Declaring accounts > Account
6054 types) is renamed by an alias, normally the account type remains in ef‐
6055 fect.
6056 However, renaming in a way that reshapes the account tree (eg renaming
6058 parent accounts but not their children, or vice versa) could prevent
6059 child accounts from inheriting the account type of their parents.
6060 Secondly, if an account's type is being inferred from its name, renam‐
6062 ing it by an alias could prevent or alter that.
6063 If you are using account aliases and the type: query is not matching
6065 accounts as you expect, try troubleshooting with the accounts command,
6066 eg something like:
6067 $ hledger accounts --alias assets=bassetts type:a
6069 Default parent account
6071 You can specify a parent account which will be prepended to all ac‐
6072 counts within a section of the journal. Use the apply account and end
6073 apply account directives like so:
6074 apply account home
6076 2010/1/1
6078 food $10
6079 cash
6080 end apply account
6082 which is equivalent to:
6084 2010/01/01
6086 home:food $10
6087 home:cash $-10
6088 If end apply account is omitted, the effect lasts to the end of the
6090 file. Included files are also affected, eg:
6091 apply account business
6093 include biz.journal
6094 end apply account
6095 apply account personal
6096 include personal.journal
6097 Prior to hledger 1.0, legacy account and end spellings were also sup‐
6099 ported.
6100 A default parent account also affects account directives. It does not
6102 affect account names being entered via hledger add or hledger-web. If
6103 account aliases are present, they are applied after the default parent
6104 account.
6105 Periodic transactions
6107 Periodic transaction rules describe transactions that recur. They al‐
6108 low hledger to generate temporary future transactions to help with
6109 forecasting, so you don't have to write out each one in the journal,
6110 and it's easy to try out different forecasts.
6111 Periodic transactions can be a little tricky, so before you use them,
6113 read this whole section - or at least these tips:
6114 1. Two spaces accidentally added or omitted will cause you trouble -
6116 read about this below.
6117 2. For troubleshooting, show the generated transactions with hledger
6119 print --forecast tag:generated or hledger register --forecast
6120 tag:generated.
6121 3. Forecasted transactions will begin only after the last non-fore‐
6123 casted transaction's date.
6124 4. Forecasted transactions will end 6 months from today, by default.
6126 See below for the exact start/end rules.
6127 5. period expressions can be tricky. Their documentation needs im‐
6129 provement, but is worth studying.
6130 6. Some period expressions with a repeating interval must begin on a
6132 natural boundary of that interval. Eg in weekly from DATE, DATE
6133 must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
6134 error.
6135 7. Other period expressions with an interval are automatically expanded
6137 to cover a whole number of that interval. (This is done to improve
6138 reports, but it also affects periodic transactions. Yes, it's a bit
6139 inconsistent with the above.) Eg: ~ every 10th day of month from
6140 2020/01, which is equivalent to ~ every 10th day of month from
6141 2020/01/01, will be adjusted to start on 2019/12/10.
6142 Periodic transaction rules also have a second meaning: they are used to
6144 define budget goals, shown in budget reports.
6145 Periodic rule syntax
6147 A periodic transaction rule looks like a normal journal entry, with the
6148 date replaced by a tilde (~) followed by a period expression (mnemonic:
6149 ~ looks like a recurring sine wave.):
6150 ~ monthly
6152 expenses:rent $2000
6153 assets:bank:checking
6154 There is an additional constraint on the period expression: the start
6156 date must fall on a natural boundary of the interval. Eg monthly from
6157 2018/1/1 is valid, but monthly from 2018/1/15 is not.
6158 Periodic rules and relative dates
6160 Partial or relative dates (like 12/31, 25, tomorrow, last week, next
6161 quarter) are usually not recommended in periodic rules, since the re‐
6162 sults will change as time passes. If used, they will be interpreted
6163 relative to, in order of preference:
6164 1. the first day of the default year specified by a recent Y directive
6166 2. or the date specified with --today
6168 3. or the date on which you are running the report.
6170 They will not be affected at all by report period or forecast period
6172 dates.
6173 Two spaces between period expression and description!
6175 If the period expression is followed by a transaction description,
6176 these must be separated by two or more spaces. This helps hledger know
6177 where the period expression ends, so that descriptions can not acciden‐
6178 tally alter their meaning, as in this example:
6179 ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"
6181 ; ||
6182 ; vv
6183 ~ every 2 months in 2020, we will review
6184 assets:bank:checking $1500
6185 income:acme inc
6186 So,
6188 • Do write two spaces between your period expression and your transac‐
6190 tion description, if any.
6191 • Don't accidentally write two spaces in the middle of your period ex‐
6193 pression.
6194 Forecasting with periodic transactions
6196 The --forecast flag activates any periodic transaction rules in the
6197 journal. These will generate temporary additional transactions, usu‐
6198 ally recurring and in the future, which will appear in all reports.
6199 hledger print --forecast is a good way to see them.
6200 This can be useful for estimating balances into the future, perhaps ex‐
6202 perimenting with different scenarios.
6203 It could also be useful for scripted data entry: you could describe re‐
6205 curring transactions, and every so often copy the output of print
6206 --forecast into the journal.
6207 The generated transactions will have an extra tag, like generated-
6209 transaction:~ PERIODICEXPR, indicating which periodic rule generated
6210 them. There is also a similar, hidden tag, named _generated-transac‐
6211 tion:, which you can use to reliably match transactions generated "just
6212 now" (rather than printed in the past).
6213 The forecast transactions are generated within a forecast period, which
6215 is independent of the report period. (Forecast period sets the bounds
6216 for generated transactions, report period controls which transactions
6217 are reported.) The forecast period begins on:
6218 • the start date provided within --forecast's argument, if any
6220 • otherwise, the later of
6222 • the report start date, if specified (with -b/-p/date:)
6224 • the day after the latest ordinary transaction in the journal, if
6226 any
6227 • otherwise today.
6229 It ends on:
6231 • the end date provided within --forecast's argument, if any
6233 • otherwise, the report end date, if specified (with -e/-p/date:)
6235 • otherwise 180 days (6 months) from today.
6237 Note, this means that ordinary transactions will suppress periodic
6239 transactions, by default; the periodic transactions will not start un‐
6240 til after the last ordinary transaction. This is usually convenient,
6241 but you can get around it in two ways:
6242 • If you need to record some transactions in the future, make them pe‐
6244 riodic transactions (with a single occurrence, eg: ~ YYYY-MM-DD)
6245 rather than ordinary transactions. That way they won't suppress
6246 other periodic transactions.
6247 • Or give --forecast a period expression argument. A forecast period
6249 specified this way can overlap ordinary transactions, and need not be
6250 in the future. Some things to note:
6251 • You must use = between flag and argument; a space won't work.
6253 • The period expression can specify the forecast period's start date,
6255 end date, or both. See also Report start & end date.
6256 • The period expression should not specify a report interval. (Each
6258 periodic transaction rule specifies its own interval.)
6259 Some examples: --forecast=202001-202004, --forecast=jan-, --fore‐
6261 cast=2021.
6262 Budgeting with periodic transactions
6264 With the --budget flag, currently supported by the balance command,
6265 each periodic transaction rule declares recurring budget goals for the
6266 specified accounts. Eg the first example above declares a goal of
6267 spending $2000 on rent (and also, a goal of depositing $2000 into
6268 checking) every month. Goals and actual performance can then be com‐
6269 pared in budget reports.
6270 See also: Budgeting and Forecasting.
6272 Auto postings
6274 "Automated postings" or "auto postings" are extra postings which get
6275 added automatically to transactions which match certain queries, de‐
6276 fined by "auto posting rules", when you use the --auto flag.
6277 An auto posting rule looks a bit like a transaction:
6279 = QUERY
6281 ACCOUNT AMOUNT
6282 ...
6283 ACCOUNT [AMOUNT]
6284 except the first line is an equals sign (mnemonic: = suggests match‐
6286 ing), followed by a query (which matches existing postings), and each
6287 "posting" line describes a posting to be generated, and the posting
6288 amounts can be:
6289 • a normal amount with a commodity symbol, eg $2. This will be used
6291 as-is.
6292 • a number, eg 2. The commodity symbol (if any) from the matched post‐
6294 ing will be added to this.
6295 • a numeric multiplier, eg *2 (a star followed by a number N). The
6297 matched posting's amount (and total price, if any) will be multiplied
6298 by N.
6299 • a multiplier with a commodity symbol, eg *$2 (a star, number N, and
6301 symbol S). The matched posting's amount will be multiplied by N, and
6302 its commodity symbol will be replaced with S.
6303 Any query term containing spaces must be enclosed in single or double
6305 quotes, as on the command line. Eg, note the quotes around the second
6306 query term below:
6307 = expenses:groceries 'expenses:dining out'
6309 (budget:funds:dining out) *-1
6310 Some examples:
6312 ; every time I buy food, schedule a dollar donation
6314 = expenses:food
6315 (liabilities:charity) $-1
6316 ; when I buy a gift, also deduct that amount from a budget envelope subaccount
6318 = expenses:gifts
6319 assets:checking:gifts *-1
6320 assets:checking *1
6321 2017/12/1
6323 expenses:food $10
6324 assets:checking
6325 2017/12/14
6327 expenses:gifts $20
6328 assets:checking
6329 $ hledger print --auto
6331 2017-12-01
6332 expenses:food $10
6333 assets:checking
6334 (liabilities:charity) $-1
6335 2017-12-14
6337 expenses:gifts $20
6338 assets:checking
6339 assets:checking:gifts -$20
6340 assets:checking $20
6341 Auto postings and multiple files
6343 An auto posting rule can affect any transaction in the current file, or
6344 in any parent file or child file. Note, currently it will not affect
6345 sibling files (when multiple -f/--file are used - see #1212).
6346 Auto postings and dates
6348 A posting date (or secondary date) in the matched posting, or (taking
6349 precedence) a posting date in the auto posting rule itself, will also
6350 be used in the generated posting.
6351 Auto postings and transaction balancing / inferred amounts / balance asser‐
6353 tions
6354 Currently, auto postings are added:
6355 • after missing amounts are inferred, and transactions are checked for
6357 balancedness,
6358 • but before balance assertions are checked.
6360 Note this means that journal entries must be balanced both before and
6362 after auto postings are added. This changed in hledger 1.12+; see #893
6363 for background.
6364 This also means that you cannot have more than one auto-posting with a
6366 missing amount applied to a given transaction, as it will be unable to
6367 infer amounts.
6368 Auto posting tags
6370 Automated postings will have some extra tags:
6371 • generated-posting:= QUERY - shows this was generated by an auto post‐
6373 ing rule, and the query
6374 • _generated-posting:= QUERY - a hidden tag, which does not appear in
6376 hledger's output. This can be used to match postings generated "just
6377 now", rather than generated in the past and saved to the journal.
6378 Also, any transaction that has been changed by auto posting rules will
6380 have these tags added:
6381 • modified: - this transaction was modified
6383 • _modified: - a hidden tag not appearing in the comment; this transac‐
6385 tion was modified "just now".
6386
6388 How hledger reads CSV data, and the CSV rules file format.
6389 hledger can read CSV files (Character Separated Value - usually comma,
6391 semicolon, or tab) containing dated records as if they were journal
6392 files, automatically converting each CSV record into a transaction.
6393 (To learn about writing CSV, see CSV output.)
6395 We describe each CSV file's format with a corresponding rules file. By
6397 default this is named like the CSV file with a .rules extension added.
6398 Eg when reading FILE.csv, hledger also looks for FILE.csv.rules in the
6399 same directory as FILE.csv. You can specify a different rules file
6400 with the --rules-file option. If a rules file is not found, hledger
6401 will create a sample rules file, which you'll need to adjust.
6402 This file contains rules describing the CSV data (header line, fields
6404 layout, date format etc.), and how to construct hledger journal entries
6405 (transactions) from it. Often there will also be a list of conditional
6406 rules for categorising transactions based on their descriptions.
6407 Here's an overview of the CSV rules; these are described more fully be‐
6408 low, after the examples:
6409 skip skip one or more header lines or matched CSV
6411 records
6412 fields list name CSV fields, assign them to hledger
6413 fields
6414 field assignment assign a value to one hledger field, with
6415 interpolation
6416 Field names hledger field names, used in the fields list
6417 and field assignments
6418 separator a custom field separator
6419 if block apply some rules to CSV records matched by
6420 patterns
6421 if table apply some rules to CSV records matched by
6422 patterns, alternate syntax
6423 end skip the remaining CSV records
6424 date-format how to parse dates in CSV records
6425 decimal-mark the decimal mark used in CSV amounts, if am‐
6426 biguous
6427 newest-first disambiguate record order when there's only
6428 one date
6429 include inline another CSV rules file
6430 balance-type choose which type of balance assignments to
6431 use
6432 Note, for best error messages when reading CSV files, use a .csv, .tsv
6434 or .ssv file extension or file prefix - see File Extension below.
6435 There's an introductory Importing CSV data tutorial on hledger.org.
6437 Examples
6439 Here are some sample hledger CSV rules files. See also the full col‐
6440 lection at:
6441 https://github.com/simonmichael/hledger/tree/master/examples/csv
6442 Basic
6444 At minimum, the rules file must identify the date and amount fields,
6445 and often it also specifies the date format and how many header lines
6446 there are. Here's a simple CSV file and a rules file for it:
6447 Date, Description, Id, Amount
6449 12/11/2019, Foo, 123, 10.23
6450 # basic.csv.rules
6452 skip 1
6453 fields date, description, _, amount
6454 date-format %d/%m/%Y
6455 $ hledger print -f basic.csv
6457 2019-11-12 Foo
6458 expenses:unknown 10.23
6459 income:unknown -10.23
6460 Default account names are chosen, since we didn't set them.
6462 Bank of Ireland
6464 Here's a CSV with two amount fields (Debit and Credit), and a balance
6465 field, which we can use to add balance assertions, which is not neces‐
6466 sary but provides extra error checking:
6467 Date,Details,Debit,Credit,Balance
6469 07/12/2012,LODGMENT 529898,,10.0,131.21
6470 07/12/2012,PAYMENT,5,,126
6471 # bankofireland-checking.csv.rules
6473 # skip the header line
6475 skip
6476 # name the csv fields, and assign some of them as journal entry fields
6478 fields date, description, amount-out, amount-in, balance
6479 # We generate balance assertions by assigning to "balance"
6481 # above, but you may sometimes need to remove these because:
6482 #
6483 # - the CSV balance differs from the true balance,
6484 # by up to 0.0000000000005 in my experience
6485 #
6486 # - it is sometimes calculated based on non-chronological ordering,
6487 # eg when multiple transactions clear on the same day
6488 # date is in UK/Ireland format
6490 date-format %d/%m/%Y
6491 # set the currency
6493 currency EUR
6494 # set the base account for all txns
6496 account1 assets:bank:boi:checking
6497 $ hledger -f bankofireland-checking.csv print
6499 2012-12-07 LODGMENT 529898
6500 assets:bank:boi:checking EUR10.0 = EUR131.2
6501 income:unknown EUR-10.0
6502 2012-12-07 PAYMENT
6504 assets:bank:boi:checking EUR-5.0 = EUR126.0
6505 expenses:unknown EUR5.0
6506 The balance assertions don't raise an error above, because we're read‐
6508 ing directly from CSV, but they will be checked if these entries are
6509 imported into a journal file.
6510 Amazon
6512 Here we convert amazon.com order history, and use an if block to gener‐
6513 ate a third posting if there's a fee. (In practice you'd probably get
6514 this data from your bank instead, but it's an example.)
6515 "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
6517 "Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"
6518 "Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"
6519 # amazon-orders.csv.rules
6521 # skip one header line
6523 skip 1
6524 # name the csv fields, and assign the transaction's date, amount and code.
6526 # Avoided the "status" and "amount" hledger field names to prevent confusion.
6527 fields date, _, toorfrom, name, amzstatus, amzamount, fees, code
6528 # how to parse the date
6530 date-format %b %-d, %Y
6531 # combine two fields to make the description
6533 description %toorfrom %name
6534 # save the status as a tag
6536 comment status:%amzstatus
6537 # set the base account for all transactions
6539 account1 assets:amazon
6540 # leave amount1 blank so it can balance the other(s).
6541 # I'm assuming amzamount excludes the fees, don't remember
6542 # set a generic account2
6544 account2 expenses:misc
6545 amount2 %amzamount
6546 # and maybe refine it further:
6547 #include categorisation.rules
6548 # add a third posting for fees, but only if they are non-zero.
6550 if %fees [1-9]
6551 account3 expenses:fees
6552 amount3 %fees
6553 $ hledger -f amazon-orders.csv print
6555 2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed
6556 assets:amazon
6557 expenses:misc $20.00
6558 2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed
6560 assets:amazon
6561 expenses:misc $25.00
6562 expenses:fees $1.00
6563 Paypal
6565 Here's a real-world rules file for (customised) Paypal CSV, with some
6566 Paypal-specific rules, and a second rules file included:
6567 "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"
6569 "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",""
6570 "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",""
6571 "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",""
6572 "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",""
6573 "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",""
6574 "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",""
6575 "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",""
6576 # paypal-custom.csv.rules
6578 # Tips:
6580 # Export from Activity -> Statements -> Custom -> Activity download
6581 # Suggested transaction type: "Balance affecting"
6582 # Paypal's default fields in 2018 were:
6583 # "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"
6584 # This rules file assumes the following more detailed fields, configured in "Customize report fields":
6585 # "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"
6586 fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note
6588 skip 1
6590 date-format %-m/%-d/%Y
6592 # ignore some paypal events
6594 if
6595 In Progress
6596 Temporary Hold
6597 Update to
6598 skip
6599 # add more fields to the description
6601 description %description_ %itemtitle
6602 # save some other fields as tags
6604 comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
6605 # convert to short currency symbols
6607 if %currency USD
6608 currency $
6609 if %currency EUR
6610 currency E
6611 if %currency GBP
6612 currency P
6613 # generate postings
6615 # the first posting will be the money leaving/entering my paypal account
6617 # (negative means leaving my account, in all amount fields)
6618 account1 assets:online:paypal
6619 amount1 %netamount
6620 # the second posting will be money sent to/received from other party
6622 # (account2 is set below)
6623 amount2 -%grossamount
6624 # if there's a fee, add a third posting for the money taken by paypal.
6626 if %feeamount [1-9]
6627 account3 expenses:banking:paypal
6628 amount3 -%feeamount
6629 comment3 business:
6630 # choose an account for the second posting
6632 # override the default account names:
6634 # if the amount is positive, it's income (a debit)
6635 if %grossamount ^[^-]
6636 account2 income:unknown
6637 # if negative, it's an expense (a credit)
6638 if %grossamount ^-
6639 account2 expenses:unknown
6640 # apply common rules for setting account2 & other tweaks
6642 include common.rules
6643 # apply some overrides specific to this csv
6645 # Transfers from/to bank. These are usually marked Pending,
6647 # which can be disregarded in this case.
6648 if
6649 Bank Account
6650 Bank Deposit to PP Account
6651 description %type for %referencetxnid %itemtitle
6652 account2 assets:bank:wf:pchecking
6653 account1 assets:online:paypal
6654 # Currency conversions
6656 if Currency Conversion
6657 account2 equity:currency conversion
6658 # common.rules
6660 if
6662 darcs
6663 noble benefactor
6664 account2 revenues:foss donations:darcshub
6665 comment2 business:
6666 if
6668 Calm Radio
6669 account2 expenses:online:apps
6670 if
6672 electronic frontier foundation
6673 Patreon
6674 wikimedia
6675 Advent of Code
6676 account2 expenses:dues
6677 if Google
6679 account2 expenses:online:apps
6680 description google | music
6681 $ hledger -f paypal-custom.csv print
6683 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
6684 assets:online:paypal $-6.99 = $-6.99
6685 expenses:online:apps $6.99
6686 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
6688 assets:online:paypal $6.99 = $0.00
6689 assets:bank:wf:pchecking $-6.99
6690 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
6692 assets:online:paypal $-7.00 = $-7.00
6693 expenses:dues $7.00
6694 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
6696 assets:online:paypal $7.00 = $0.00
6697 assets:bank:wf:pchecking $-7.00
6698 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
6700 assets:online:paypal $-2.00 = $-2.00
6701 expenses:dues $2.00
6702 expenses:banking:paypal ; business:
6703 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
6705 assets:online:paypal $2.00 = $0.00
6706 assets:bank:wf:pchecking $-2.00
6707 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
6709 assets:online:paypal $9.41 = $9.41
6710 revenues:foss donations:darcshub $-10.00 ; business:
6711 expenses:banking:paypal $0.59 ; business:
6712 CSV rules
6714 The following kinds of rule can appear in the rules file, in any order.
6715 Blank lines and lines beginning with # or ; are ignored.
6716 skip
6718 skip N
6719 The word "skip" followed by a number (or no number, meaning 1) tells
6721 hledger to ignore this many non-empty lines preceding the CSV data.
6722 (Empty/blank lines are skipped automatically.) You'll need this when‐
6723 ever your CSV data contains header lines.
6724 It also has a second purpose: it can be used inside if blocks to ignore
6726 certain CSV records (described below).
6727 fields list
6729 fields FIELDNAME1, FIELDNAME2, ...
6730 A fields list (the word "fields" followed by comma-separated field
6732 names) is the quick way to assign CSV field values to hledger fields.
6733 (The other way is field assignments, see below.) A fields list does
6734 does two things:
6735 1. It names the CSV fields. This is optional, but can be convenient
6737 later for interpolating them.
6738 2. Whenever you use a standard hledger field name (defined below), the
6740 CSV value is assigned to that part of the hledger transaction.
6741 Here's an example that says "use the 1st, 2nd and 4th fields as the
6743 transaction's date, description and amount; name the last two fields
6744 for later reference; and ignore the others":
6745 fields date, description, , amount, , , somefield, anotherfield
6747 Tips:
6749 • The fields list always use commas, even if your CSV data uses another
6751 separator character.
6752 • Currently there must be least two items in the list (at least one
6754 comma).
6755 • Field names may not contain spaces. Spaces before/after field names
6757 are optional.
6758 • Field names may contain _ (underscore) or - (hyphen).
6760 • If the CSV contains column headings, it's a good idea to use these,
6762 suitably modified, as the basis for your field names (eg lower-cased,
6763 with underscores instead of spaces).
6764 • If some heading names match standard hledger fields, but you don't
6766 want to set the hledger fields directly, alter those names, eg by ap‐
6767 pending an underscore.
6768 • Fields you don't care about can be given a dummy name (eg: _ ), or no
6770 name.
6771 field assignment
6773 HLEDGERFIELDNAME FIELDVALUE
6774 Field assignments are the more flexible way to assign CSV values to
6776 hledger fields. They can be used instead of or in addition to a fields
6777 list (see above).
6778 To assign a value to a hledger field, write the field name (any of the
6780 standard hledger field/pseudo-field names, defined below), a space,
6781 followed by a text value on the same line. This text value may inter‐
6782 polate CSV fields, referenced by their 1-based position in the CSV
6783 record (%N), or by the name they were given in the fields list (%CSV‐
6784 FIELDNAME).
6785 Some examples:
6787 # set the amount to the 4th CSV field, with " USD" appended
6789 amount %4 USD
6790 # combine three fields to make a comment, containing note: and date: tags
6792 comment note: %somefield - %anotherfield, date: %1
6793 Tips:
6795 • Interpolation strips outer whitespace (so a CSV value like " 1 " be‐
6797 comes 1 when interpolated) (#1051).
6798 • Interpolations always refer to a CSV field - you can't interpolate a
6800 hledger field. (See Referencing other fields below).
6801 Field names
6803 Here are the standard hledger field (and pseudo-field) names, which you
6804 can use in a fields list and in field assignments. For more about the
6805 transaction parts they refer to, see Transactions.
6806 date field
6808 Assigning to date sets the transaction date.
6809 date2 field
6811 date2 sets the transaction's secondary date, if any.
6812 status field
6814 status sets the transaction's status, if any.
6815 code field
6817 code sets the transaction's code, if any.
6818 description field
6820 description sets the transaction's description, if any.
6821 comment field
6823 comment sets the transaction's comment, if any.
6824 commentN, where N is a number, sets the Nth posting's comment.
6826 Tips:
6828 • You can assign multi-line comments by writing literal \n in the code.
6830 A comment starting with \n will begin on a new line.
6831 • Comments can contain tags, as usual.
6833 account field
6835 Assigning to accountN, where N is 1 to 99, sets the account name of the
6836 Nth posting, and causes that posting to be generated.
6837 Most often there are two postings, so you'll want to set account1 and
6839 account2. Typically account1 is associated with the CSV file, and is
6840 set once with a top-level assignment, while account2 is set based on
6841 each transaction's description, and in conditional blocks.
6842 If a posting's account name is left unset but its amount is set (see
6844 below), a default account name will be chosen (like "expenses:unknown"
6845 or "income:unknown").
6846 amount field
6848 amountN sets the amount of the Nth posting, and causes that posting to
6849 be generated. By assigning to amount1, amount2, ... etc. you can
6850 generate up to 99 postings.
6851 amountN-in and amountN-out can be used instead, if the CSV uses sepa‐
6853 rate fields for debits and credits (inflows and outflows). hledger as‐
6854 sumes both of these CSV fields are unsigned, and will automatically
6855 negate the "-out" value. If they are signed, see "Setting amounts" be‐
6856 low.
6857 amount, or amount-in and amount-out are a legacy mode, to keep pre-
6859 hledger-1.17 CSV rules files working (and for occasional convenience).
6860 They are suitable only for two-posting transactions; they set both
6861 posting 1's and posting 2's amount. Posting 2's amount will be
6862 negated, and also converted to cost if there's a transaction price.
6863 If you have an existing rules file using the unnumbered form, you might
6865 want to use the numbered form in certain conditional blocks, without
6866 having to update and retest all the old rules. To facilitate this,
6867 posting 1 ignores amount/amount-in/amount-out if any of
6868 amount1/amount1-in/amount1-out are assigned, and posting 2 ignores them
6869 if any of amount2/amount2-in/amount2-out are assigned, avoiding con‐
6870 flicts.
6871 currency field
6873 currency sets a currency symbol, to be prepended to all postings'
6874 amounts. You can use this if the CSV amounts do not have a currency
6875 symbol, eg if it is in a separate column.
6876 currencyN prepends a currency symbol to just the Nth posting's amount.
6878 balance field
6880 balanceN sets a balance assertion amount (or if the posting amount is
6881 left empty, a balance assignment) on posting N.
6882 balance is a compatibility spelling for hledger <1.17; it is equivalent
6884 to balance1.
6885 You can adjust the type of assertion/assignment with the balance-type
6887 rule (see below).
6888 See Tips below for more about setting amounts and currency.
6890 separator
6892 You can use the separator rule to read other kinds of character-sepa‐
6893 rated data. The argument is any single separator character, or the
6894 words tab or space (case insensitive). Eg, for comma-separated values
6895 (CSV):
6896 separator ,
6898 or for semicolon-separated values (SSV):
6900 separator ;
6902 or for tab-separated values (TSV):
6904 separator TAB
6906 If the input file has a .csv, .ssv or .tsv file extension (or a csv:,
6908 ssv:, tsv: prefix), the appropriate separator will be inferred automat‐
6909 ically, and you won't need this rule.
6910 if block
6912 if MATCHER
6913 RULE
6914 if
6916 MATCHER
6917 MATCHER
6918 MATCHER
6919 RULE
6920 RULE
6921 Conditional blocks ("if blocks") are a block of rules that are applied
6923 only to CSV records which match certain patterns. They are often used
6924 for customising account names based on transaction descriptions.
6925 Matching the whole record
6927 Each MATCHER can be a record matcher, which looks like this:
6928 REGEX
6930 REGEX is a case-insensitive regular expression that tries to match any‐
6932 where within the CSV record. It is a POSIX ERE (extended regular ex‐
6933 pression) that also supports GNU word boundaries (\b, \B, \<, \>), and
6934 nothing else. If you have trouble, be sure to check our doc:
6935 https://hledger.org/hledger.html#regular-expressions
6936 Important note: the record that is matched is not the original record,
6938 but a synthetic one, with any enclosing double quotes (but not enclos‐
6939 ing whitespace) removed, and always comma-separated (which means that a
6940 field containing a comma will appear like two fields). Eg, if the
6941 original record is 2020-01-01; "Acme, Inc."; 1,000, the REGEX will ac‐
6942 tually see 2020-01-01,Acme, Inc., 1,000).
6943 Matching individual fields
6945 Or, MATCHER can be a field matcher, like this:
6946 %CSVFIELD REGEX
6948 which matches just the content of a particular CSV field. CSVFIELD is
6950 a percent sign followed by the field's name or column number, like
6951 %date or %1.
6952 Combining matchers
6954 A single matcher can be written on the same line as the "if"; or multi‐
6955 ple matchers can be written on the following lines, non-indented. Mul‐
6956 tiple matchers are OR'd (any one of them can match), unless one begins
6957 with an & symbol, in which case it is AND'ed with the previous matcher.
6958 if
6960 MATCHER
6961 & MATCHER
6962 RULE
6963 Rules applied on successful match
6965 After the patterns there should be one or more rules to apply, all in‐
6966 dented by at least one space. Three kinds of rule are allowed in con‐
6967 ditional blocks:
6968 • field assignments (to set a hledger field)
6970 • skip (to skip the matched CSV record)
6972 • end (to skip all remaining CSV records).
6974 Examples:
6976 # if the CSV record contains "groceries", set account2 to "expenses:groceries"
6978 if groceries
6979 account2 expenses:groceries
6980 # if the CSV record contains any of these patterns, set account2 and comment as shown
6982 if
6983 monthly service fee
6984 atm transaction fee
6985 banking thru software
6986 account2 expenses:business:banking
6987 comment XXX deductible ? check it
6988 if table
6990 if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn
6991 MATCHER1,VALUE11,VALUE12,...,VALUE1n
6992 MATCHER2,VALUE21,VALUE22,...,VALUE2n
6993 MATCHER3,VALUE31,VALUE32,...,VALUE3n
6994 <empty line>
6995 Conditional tables ("if tables") are a different syntax to specify
6997 field assignments that will be applied only to CSV records which match
6998 certain patterns.
6999 MATCHER could be either field or record matcher, as described above.
7001 When MATCHER matches, values from that row would be assigned to the CSV
7002 fields named on the if line, in the same order.
7003 Therefore if table is exactly equivalent to a sequence of of if blocks:
7005 if MATCHER1
7007 CSVFIELDNAME1 VALUE11
7008 CSVFIELDNAME2 VALUE12
7009 ...
7010 CSVFIELDNAMEn VALUE1n
7011 if MATCHER2
7013 CSVFIELDNAME1 VALUE21
7014 CSVFIELDNAME2 VALUE22
7015 ...
7016 CSVFIELDNAMEn VALUE2n
7017 if MATCHER3
7019 CSVFIELDNAME1 VALUE31
7020 CSVFIELDNAME2 VALUE32
7021 ...
7022 CSVFIELDNAMEn VALUE3n
7023 Each line starting with MATCHER should contain enough (possibly empty)
7025 values for all the listed fields.
7026 Rules would be checked and applied in the order they are listed in the
7028 table and, like with if blocks, later rules (in the same or another ta‐
7029 ble) or if blocks could override the effect of any rule.
7030 Instead of ',' you can use a variety of other non-alphanumeric charac‐
7032 ters as a separator. First character after if is taken to be the sepa‐
7033 rator for the rest of the table. It is the responsibility of the user
7034 to ensure that separator does not occur inside MATCHERs and values -
7035 there is no way to escape separator.
7036 Example:
7038 if,account2,comment
7040 atm transaction fee,expenses:business:banking,deductible? check it
7041 %description groceries,expenses:groceries,
7042 2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
7043 end
7045 This rule can be used inside if blocks (only), to make hledger stop
7046 reading this CSV file and move on to the next input file, or to command
7047 execution. Eg:
7048 # ignore everything following the first empty record
7050 if ,,,,
7051 end
7052 date-format
7054 date-format DATEFMT
7055 This is a helper for the date (and date2) fields. If your CSV dates
7057 are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll
7058 need to add a date-format rule describing them with a strptime date
7059 parsing pattern, which must parse the CSV date value completely. Some
7060 examples:
7061 # MM/DD/YY
7063 date-format %m/%d/%y
7064 # D/M/YYYY
7066 # The - makes leading zeros optional.
7067 date-format %-d/%-m/%Y
7068 # YYYY-Mmm-DD
7070 date-format %Y-%h-%d
7071 # M/D/YYYY HH:MM AM some other junk
7073 # Note the time and junk must be fully parsed, though only the date is used.
7074 date-format %-m/%-d/%Y %l:%M %p some other junk
7075 For the supported strptime syntax, see:
7077 https://hackage.haskell.org/package/time/docs/Data-Time-For‐
7078 mat.html#v:formatTime
7079 Note that although you can parse date-times which include a time zone,
7081 that time zone is ignored; it will not change the date that is parsed.
7082 This means when reading CSV data with times not in your local time
7083 zone, dates can be "off by one".
7084 decimal-mark
7086 decimal-mark .
7087 or:
7089 decimal-mark ,
7091 hledger automatically accepts either period or comma as a decimal mark
7093 when parsing numbers (cf Amounts). However if any numbers in the CSV
7094 contain digit group marks, such as thousand-separating commas, you
7095 should declare the decimal mark explicitly with this rule, to avoid
7096 misparsed numbers.
7097 newest-first
7099 hledger always sorts the generated transactions by date. Transactions
7100 on the same date should appear in the same order as their CSV records,
7101 as hledger can usually auto-detect whether the CSV's normal order is
7102 oldest first or newest first. But if all of the following are true:
7103 • the CSV might sometimes contain just one day of data (all records
7105 having the same date)
7106 • the CSV records are normally in reverse chronological order (newest
7108 at the top)
7109 • and you care about preserving the order of same-day transactions
7111 then, you should add the newest-first rule as a hint. Eg:
7113 # tell hledger explicitly that the CSV is normally newest first
7115 newest-first
7116 include
7118 include RULESFILE
7119 This includes the contents of another CSV rules file at this point.
7121 RULESFILE is an absolute file path or a path relative to the current
7122 file's directory. This can be useful for sharing common rules between
7123 several rules files, eg:
7124 # someaccount.csv.rules
7126 ## someaccount-specific rules
7128 fields date,description,amount
7129 account1 assets:someaccount
7130 account2 expenses:misc
7131 ## common rules
7133 include categorisation.rules
7134 balance-type
7136 Balance assertions generated by assigning to balanceN are of the simple
7137 = type by default, which is a single-commodity, subaccount-excluding
7138 assertion. You may find the subaccount-including variants more useful,
7139 eg if you have created some virtual subaccounts of checking to help
7140 with budgeting. You can select a different type of assertion with the
7141 balance-type rule:
7142 # balance assertions will consider all commodities and all subaccounts
7144 balance-type ==*
7145 Here are the balance assertion types for quick reference:
7147 = single commodity, exclude subaccounts
7149 =* single commodity, include subaccounts
7150 == multi commodity, exclude subaccounts
7151 ==* multi commodity, include subaccounts
7152 Tips
7154 Rapid feedback
7155 It's a good idea to get rapid feedback while creating/troubleshooting
7156 CSV rules. Here's a good way, using entr from eradman.com/entrproject:
7157 $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
7159 A desc: query (eg) is used to select just one, or a few, transactions
7161 of interest. "bash -c" is used to run multiple commands, so we can
7162 echo a separator each time the command re-runs, making it easier to
7163 read the output.
7164 Valid CSV
7166 hledger accepts CSV conforming to RFC 4180. When CSV values are en‐
7167 closed in quotes, note:
7168 • they must be double quotes (not single quotes)
7170 • spaces outside the quotes are not allowed
7172 File Extension
7174 To help hledger identify the format and show the right error messages,
7175 CSV/SSV/TSV files should normally be named with a .csv, .ssv or .tsv
7176 filename extension. Or, the file path should be prefixed with csv:,
7177 ssv: or tsv:. Eg:
7178 $ hledger -f foo.ssv print
7180 or:
7182 $ cat foo | hledger -f ssv:- foo
7184 You can override the file extension with a separator rule if needed.
7186 See also: Input files in the hledger manual.
7187 Reading multiple CSV files
7189 If you use multiple -f options to read multiple CSV files at once,
7190 hledger will look for a correspondingly-named rules file for each CSV
7191 file. But if you use the --rules-file option, that rules file will be
7192 used for all the CSV files.
7193 Valid transactions
7195 After reading a CSV file, hledger post-processes and validates the gen‐
7196 erated journal entries as it would for a journal file - balancing them,
7197 applying balance assignments, and canonicalising amount styles. Any
7198 errors at this stage will be reported in the usual way, displaying the
7199 problem entry.
7200 There is one exception: balance assertions, if you have generated them,
7202 will not be checked, since normally these will work only when the CSV
7203 data is part of the main journal. If you do need to check balance as‐
7204 sertions generated from CSV right away, pipe into another hledger:
7205 $ hledger -f file.csv print | hledger -f- print
7207 Deduplicating, importing
7209 When you download a CSV file periodically, eg to get your latest bank
7210 transactions, the new file may overlap with the old one, containing
7211 some of the same records.
7212 The import command will (a) detect the new transactions, and (b) append
7214 just those transactions to your main journal. It is idempotent, so you
7215 don't have to remember how many times you ran it or with which version
7216 of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This
7217 is the easiest way to import CSV data. Eg:
7218 # download the latest CSV files, then run this command.
7220 # Note, no -f flags needed here.
7221 $ hledger import *.csv [--dry]
7222 This method works for most CSV files. (Where records have a stable
7224 chronological order, and new records appear only at the new end.)
7225 A number of other tools and workflows, hledger-specific and otherwise,
7227 exist for converting, deduplicating, classifying and managing CSV data.
7228 See:
7229 • https://hledger.org/cookbook.html#setups-and-workflows
7231 • https://plaintextaccounting.org -> data import/conversion
7233 Setting amounts
7235 Some tips on using the amount-setting rules discussed above.
7236 Here are the ways to set a posting's amount:
7238 1. If the CSV has a single amount field:
7240 Assign (via a fields list or a field assignment) to amountN. This sets
7241 the Nth posting's amount. N is usually 1 or 2 but can go up to 99.
7242 2. If the CSV has separate amount fields for debit & credit (in & out):
7244 a. If both fields are unsigned:
7245 Assign to amountN-in and amountN-out. This sets posting N's amount
7246 to whichever of these has a non-zero value, and negates the "-out"
7247 value.
7248 b. If either field is signed (can contain a minus sign):
7250 Use a conditional rule to flip the sign (of non-empty values).
7251 Since hledger always negates amountN-out, if it was already nega‐
7252 tive, we must undo that by negating once more (but only if the
7253 field is non-empty):
7254 fields date, description, amount1-in, amount1-out
7256 if %amount1-out [1-9]
7257 amount1-out -%amount1-out
7258 c. If both fields, or neither field, can contain a non-zero value:
7260 hledger normally expects exactly one of the fields to have a non-
7261 zero value. Eg, the amountN-in/amountN-out rules would reject
7262 value pairs like these:
7263 "", ""
7265 "0", "0"
7266 "1", "none"
7267 So, use smarter conditional rules to set the amount from the appro‐
7269 priate field. Eg, these rules would make it use only the value
7270 containing non-zero digits, handling the above:
7271 fields date, description, in, out
7273 if %in [1-9]
7274 amount1 %in
7275 if %out [1-9]
7276 amount1 %out
7277 3. If you want posting 2's amount converted to cost:
7279 Assign to amount (or to amount-in and amount-out). (This is the legacy
7280 numberless syntax, which sets amount1 and amount2 and converts amount2
7281 to cost.)
7282 4. If the CSV has the balance instead of the transaction amount:
7284 Assign to balanceN, which sets posting N's amount indirectly via a bal‐
7285 ance assignment. (Old syntax: balance, equivalent to balance1.)
7286 • If hledger guesses the wrong default account name:
7288 When setting the amount via balance assertion, hledger may guess
7289 the wrong default account name. So, set the account name explic‐
7290 itly, eg:
7291 fields date, description, balance1
7293 account1 assets:checking
7294 Amount signs
7296 There is some special handling for amount signs, to simplify parsing
7297 and sign-flipping:
7298 • If an amount value begins with a plus sign:
7300 that will be removed: +AMT becomes AMT
7301 • If an amount value is parenthesised:
7303 it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT
7304 • If an amount value has two minus signs (or two sets of parentheses,
7306 or a minus sign and parentheses):
7307 they cancel out and will be removed: --AMT or -(AMT) becomes AMT
7308 • If an amount value contains just a sign (or just a set of parenthe‐
7310 ses):
7311 that is removed, making it an empty value. "+" or "-" or "()" becomes
7312 "".
7313 Setting currency/commodity
7315 If the currency/commodity symbol is included in the CSV's amount
7316 field(s):
7317 2020-01-01,foo,$123.00
7319 you don't have to do anything special for the commodity symbol, it will
7321 be assigned as part of the amount. Eg:
7322 fields date,description,amount
7324 2020-01-01 foo
7326 expenses:unknown $123.00
7327 income:unknown $-123.00
7328 If the currency is provided as a separate CSV field:
7330 2020-01-01,foo,USD,123.00
7332 You can assign that to the currency pseudo-field, which has the special
7334 effect of prepending itself to every amount in the transaction (on the
7335 left, with no separating space):
7336 fields date,description,currency,amount
7338 2020-01-01 foo
7340 expenses:unknown USD123.00
7341 income:unknown USD-123.00
7342 Or, you can use a field assignment to construct the amount yourself,
7344 with more control. Eg to put the symbol on the right, and separated by
7345 a space:
7346 fields date,description,cur,amt
7348 amount %amt %cur
7349 2020-01-01 foo
7351 expenses:unknown 123.00 USD
7352 income:unknown -123.00 USD
7353 Note we used a temporary field name (cur) that is not currency - that
7355 would trigger the prepending effect, which we don't want here.
7356 Amount decimal places
7358 Like amounts in a journal file, the amounts generated by CSV rules like
7359 amount1 influence commodity display styles, such as the number of deci‐
7360 mal places displayed in reports.
7361 The original amounts as written in the CSV file do not affect display
7363 style (because we don't yet reliably know their commodity).
7364 Referencing other fields
7366 In field assignments, you can interpolate only CSV fields, not hledger
7367 fields. In the example below, there's both a CSV field and a hledger
7368 field named amount1, but %amount1 always means the CSV field, not the
7369 hledger field:
7370 # Name the third CSV field "amount1"
7372 fields date,description,amount1
7373 # Set hledger's amount1 to the CSV amount1 field followed by USD
7375 amount1 %amount1 USD
7376 # Set comment to the CSV amount1 (not the amount1 assigned above)
7378 comment %amount1
7379 Here, since there's no CSV amount1 field, %amount1 will produce a lit‐
7381 eral "amount1":
7382 fields date,description,csvamount
7384 amount1 %csvamount USD
7385 # Can't interpolate amount1 here
7386 comment %amount1
7387 When there are multiple field assignments to the same hledger field,
7389 only the last one takes effect. Here, comment's value will be be B, or
7390 C if "something" is matched, but never A:
7391 comment A
7393 comment B
7394 if something
7395 comment C
7396 How CSV rules are evaluated
7398 Here's how to think of CSV rules being evaluated (if you really need
7399 to). First,
7400 • include - all includes are inlined, from top to bottom, depth first.
7402 (At each include point the file is inlined and scanned for further
7403 includes, recursively, before proceeding.)
7404 Then "global" rules are evaluated, top to bottom. If a rule is re‐
7406 peated, the last one wins:
7407 • skip (at top level)
7409 • date-format
7411 • newest-first
7413 • fields - names the CSV fields, optionally sets up initial assignments
7415 to hledger fields
7416 Then for each CSV record in turn:
7418 • test all if blocks. If any of them contain a end rule, skip all re‐
7420 maining CSV records. Otherwise if any of them contain a skip rule,
7421 skip that many CSV records. If there are multiple matched skip
7422 rules, the first one wins.
7423 • collect all field assignments at top level and in matched if blocks.
7425 When there are multiple assignments for a field, keep only the last
7426 one.
7427 • compute a value for each hledger field - either the one that was as‐
7429 signed to it (and interpolate the %CSVFIELDNAME references), or a de‐
7430 fault
7431 • generate a synthetic hledger transaction from these values.
7433 This is all part of the CSV reader, one of several readers hledger can
7435 use to parse input files. When all files have been read successfully,
7436 the transactions are passed as input to whichever hledger command the
7437 user specified.
7438
7440 The time logging format of timeclock.el, as read by hledger.
7441 hledger can read time logs in timeclock format. As with Ledger, these
7443 are (a subset of) timeclock.el's format, containing clock-in and clock-
7444 out entries as in the example below. The date is a simple date. The
7445 time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional.
7446 The timezone, if present, must be four digits and is ignored (currently
7447 the time is always interpreted as a local time).
7448 i 2015/03/30 09:00:00 some:account name optional description after two spaces
7450 o 2015/03/30 09:20:00
7451 i 2015/03/31 22:21:45 another account
7452 o 2015/04/01 02:00:34
7453 hledger treats each clock-in/clock-out pair as a transaction posting
7455 some number of hours to an account. Or if the session spans more than
7456 one day, it is split into several transactions, one for each day. For
7457 the above time log, hledger print generates these journal entries:
7458 $ hledger -f t.timeclock print
7460 2015-03-30 * optional description after two spaces
7461 (some:account name) 0.33h
7462 2015-03-31 * 22:21-23:59
7464 (another account) 1.64h
7465 2015-04-01 * 00:00-02:00
7467 (another account) 2.01h
7468 Here is a sample.timeclock to download and some queries to try:
7470 $ hledger -f sample.timeclock balance # current time balances
7472 $ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009
7473 $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week
7474 To generate time logs, ie to clock in and clock out, you could:
7476 • use emacs and the built-in timeclock.el, or the extended timeclock-
7478 x.el and perhaps the extras in ledgerutils.el
7479 • at the command line, use these bash aliases: shell alias ti="echo
7481 i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o
7482 `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
7483 • or use the old ti and to scripts in the ledger 2.x repository. These
7485 rely on a "timeclock" executable which I think is just the ledger 2
7486 executable renamed.
7487
7489 timedot format is hledger's human-friendly time logging format. Com‐
7490 pared to timeclock format, it is
7491 • convenient for quick, approximate, and retroactive time logging
7493 • readable: you can see at a glance where time was spent.
7495 A timedot file contains a series of day entries, which might look like
7497 this:
7498 2021-08-04
7500 hom:errands .... ....
7501 fos:hledger:timedot .. ; docs
7502 per:admin:finance
7503 hledger reads this as three time transactions on this day, with each
7505 dot representing a quarter-hour spent:
7506 $ hledger -f a.timedot print # .timedot file extension activates the timedot reader
7508 2021-08-04 *
7509 (hom:errands) 2.00
7510 2021-08-04 *
7512 (fos:hledger:timedot) 0.50
7513 2021-08-04 *
7515 (per:admin:finance) 0
7516 A day entry begins with a date line:
7518 • a non-indented simple date (Y-M-D, Y/M/D, or Y.M.D).
7520 Optionally this can be followed on the same line by
7522 • a common transaction description for this day
7524 • a common transaction comment for this day, after a semicolon (;).
7526 After the date line are zero or more optionally-indented time transac‐
7528 tion lines, consisting of:
7529 • an account name - any word or phrase, usually a hledger-style account
7531 name.
7532 • two or more spaces - a field separator, required if there is an
7534 amount (as in journal format).
7535 • a timedot amount - dots representing quarter hours, or a number rep‐
7537 resenting hours.
7538 • an optional comment beginning with semicolon. This is ignored.
7540 In more detail, timedot amounts can be:
7542 • dots: zero or more period characters, each representing one quarter-
7544 hour. Spaces are ignored and can be used for grouping. Eg: .... ..
7545 • a number, representing hours. Eg: 1.5
7547 • a number immediately followed by a unit symbol s, m, h, d, w, mo, or
7549 y, representing seconds, minutes, hours, days weeks, months or years.
7550 Eg 1.5h or 90m. The following equivalencies are assumed:
7551 60s = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y. (This
7552 unit will not be visible in the generated transaction amount, which is
7553 always in hours.)
7554 There is some added flexibility to help with keeping time log data in
7556 the same file as your notes, todo lists, etc.:
7557 • Lines beginning with # or ;, and blank lines, are ignored.
7559 • Lines not ending with a double-space and amount are parsed as trans‐
7561 actions with zero amount. (Most hledger reports hide these by de‐
7562 fault; add -E to see them.)
7563 • One or more stars (*) followed by a space, at the start of a line, is
7565 ignored. So date lines or time transaction lines can also be Org-
7566 mode headlines.
7567 • All Org-mode headlines before the first date line are ignored.
7569 More examples:
7571 # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
7573 2016/2/1
7574 inc:client1 .... .... .... .... .... ....
7575 fos:haskell .... ..
7576 biz:research .
7577 2016/2/2
7579 inc:client1 .... ....
7580 biz:research .
7581 2016/2/3
7583 inc:client1 4
7584 fos:hledger 3
7585 biz:research 1
7586 * Time log
7588 ** 2020-01-01
7589 *** adm:time .
7590 *** adm:finance .
7591 * 2020 Work Diary
7593 ** Q1
7594 *** 2020-02-29
7595 **** DONE
7596 0700 yoga
7597 **** UNPLANNED
7598 **** BEGUN
7599 hom:chores
7600 cleaning ...
7601 water plants
7602 outdoor - one full watering can
7603 indoor - light watering
7604 **** TODO
7605 adm:planning: trip
7606 *** LATER
7607 Reporting:
7609 $ hledger -f a.timedot print date:2016/2/2
7611 2016-02-02 *
7612 (inc:client1) 2.00
7613 2016-02-02 *
7615 (biz:research) 0.25
7616 $ hledger -f a.timedot bal --daily --tree
7618 Balance changes in 2016-02-01-2016-02-03:
7619 || 2016-02-01d 2016-02-02d 2016-02-03d
7621 ============++========================================
7622 biz || 0.25 0.25 1.00
7623 research || 0.25 0.25 1.00
7624 fos || 1.50 0 3.00
7625 haskell || 1.50 0 0
7626 hledger || 0 0 3.00
7627 inc || 6.00 2.00 4.00
7628 client1 || 6.00 2.00 4.00
7629 ------------++----------------------------------------
7630 || 7.75 2.25 8.00
7631 Using period instead of colon as account name separator:
7633 2016/2/4
7635 fos.hledger.timedot 4
7636 fos.ledger ..
7637 $ hledger -f a.timedot --alias /\\./=: bal --tree
7639 4.50 fos
7640 4.00 hledger:timedot
7641 0.50 ledger
7642 --------------------
7643 4.50
7644 A sample.timedot file.
7646
7648 Here are some quick examples of how to do some basic tasks with
7649 hledger.
7650 Getting help
7652 Here's how to list commands and view options and command docs:
7653 $ hledger # show available commands
7655 $ hledger --help # show common options
7656 $ hledger CMD --help # show common options and CMD's options and documentation
7657 You can also view your hledger version's manual in several formats by
7659 using the help command. Eg:
7660 $ hledger help # show the hledger manual with info, man or $PAGER (best available)
7662 $ hledger help journal # show the journal topic in the hledger manual
7663 $ hledger help --help # show how the help command works
7664 To view manuals and introductory docs on the web, visit
7666 https://hledger.org. Chat and mail list support and discussion ar‐
7667 chives can be found at https://hledger.org/support.
7668 Constructing command lines
7670 hledger has an extensive and powerful command line interface. We
7671 strive to keep it simple and ergonomic, but you may run into one of the
7672 confusing real world details described in OPTIONS, below. If that hap‐
7673 pens, here are some tips that may help:
7674 • command-specific options must go after the command (it's fine to put
7676 all options there) (hledger CMD OPTS ARGS)
7677 • running add-on executables directly simplifies command line parsing
7679 (hledger-ui OPTS ARGS)
7680 • enclose "problematic" args in single quotes
7682 • if needed, also add a backslash to hide regular expression metachar‐
7684 acters from the shell
7685 • to see how a misbehaving command is being parsed, add --debug=2.
7687 Starting a journal file
7689 hledger looks for your accounting data in a journal file,
7690 $HOME/.hledger.journal by default:
7691 $ hledger stats
7693 The hledger journal file "/Users/simon/.hledger.journal" was not found.
7694 Please create it first, eg with "hledger add" or a text editor.
7695 Or, specify an existing journal file with -f or LEDGER_FILE.
7696 You can override this by setting the LEDGER_FILE environment variable.
7698 It's a good practice to keep this important file under version control,
7699 and to start a new file each year. So you could do something like
7700 this:
7701 $ mkdir ~/finance
7703 $ cd ~/finance
7704 $ git init
7705 Initialized empty Git repository in /Users/simon/finance/.git/
7706 $ touch 2020.journal
7707 $ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc
7708 $ source ~/.bashrc
7709 $ hledger stats
7710 Main file : /Users/simon/finance/2020.journal
7711 Included files :
7712 Transactions span : to (0 days)
7713 Last transaction : none
7714 Transactions : 0 (0.0 per day)
7715 Transactions last 30 days: 0 (0.0 per day)
7716 Transactions last 7 days : 0 (0.0 per day)
7717 Payees/descriptions : 0
7718 Accounts : 0 (depth 0)
7719 Commodities : 0 ()
7720 Market prices : 0 ()
7721 Setting opening balances
7723 Pick a starting date for which you can look up the balances of some
7724 real-world assets (bank accounts, wallet..) and liabilities (credit
7725 cards..).
7726 To avoid a lot of data entry, you may want to start with just one or
7728 two accounts, like your checking account or cash wallet; and pick a re‐
7729 cent starting date, like today or the start of the week. You can al‐
7730 ways come back later and add more accounts and older transactions, eg
7731 going back to january 1st.
7732 Add an opening balances transaction to the journal, declaring the bal‐
7734 ances on this date. Here are two ways to do it:
7735 • The first way: open the journal in any text editor and save an entry
7737 like this:
7738 2020-01-01 * opening balances
7740 assets:bank:checking $1000 = $1000
7741 assets:bank:savings $2000 = $2000
7742 assets:cash $100 = $100
7743 liabilities:creditcard $-50 = $-50
7744 equity:opening/closing balances
7745 These are start-of-day balances, ie whatever was in the account at
7747 the end of the previous day.
7748 The * after the date is an optional status flag. Here it means
7750 "cleared & confirmed".
7751 The currency symbols are optional, but usually a good idea as you'll
7753 be dealing with multiple currencies sooner or later.
7754 The = amounts are optional balance assertions, providing extra error
7756 checking.
7757 • The second way: run hledger add and follow the prompts to record a
7759 similar transaction:
7760 $ hledger add
7762 Adding transactions to journal file /Users/simon/finance/2020.journal
7763 Any command line arguments will be used as defaults.
7764 Use tab key to complete, readline keys to edit, enter to accept defaults.
7765 An optional (CODE) may follow transaction dates.
7766 An optional ; COMMENT may follow descriptions or amounts.
7767 If you make a mistake, enter < at any prompt to go one step backward.
7768 To end a transaction, enter . when prompted.
7769 To quit, enter . at a date prompt or press control-d or control-c.
7770 Date [2020-02-07]: 2020-01-01
7771 Description: * opening balances
7772 Account 1: assets:bank:checking
7773 Amount 1: $1000
7774 Account 2: assets:bank:savings
7775 Amount 2 [$-1000]: $2000
7776 Account 3: assets:cash
7777 Amount 3 [$-3000]: $100
7778 Account 4: liabilities:creditcard
7779 Amount 4 [$-3100]: $-50
7780 Account 5: equity:opening/closing balances
7781 Amount 5 [$-3050]:
7782 Account 6 (or . or enter to finish this transaction): .
7783 2020-01-01 * opening balances
7784 assets:bank:checking $1000
7785 assets:bank:savings $2000
7786 assets:cash $100
7787 liabilities:creditcard $-50
7788 equity:opening/closing balances $-3050
7789 Save this transaction to the journal ? [y]:
7791 Saved.
7792 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
7793 Date [2020-01-01]: .
7794 If you're using version control, this could be a good time to commit
7796 the journal. Eg:
7797 $ git commit -m 'initial balances' 2020.journal
7799 Recording transactions
7801 As you spend or receive money, you can record these transactions using
7802 one of the methods above (text editor, hledger add) or by using the
7803 hledger-iadd or hledger-web add-ons, or by using the import command to
7804 convert CSV data downloaded from your bank.
7805 Here are some simple transactions, see the hledger_journal(5) manual
7807 and hledger.org for more ideas:
7808 2020/1/10 * gift received
7810 assets:cash $20
7811 income:gifts
7812 2020.1.12 * farmers market
7814 expenses:food $13
7815 assets:cash
7816 2020-01-15 paycheck
7818 income:salary
7819 assets:bank:checking $1000
7820 Reconciling
7822 Periodically you should reconcile - compare your hledger-reported bal‐
7823 ances against external sources of truth, like bank statements or your
7824 bank's website - to be sure that your ledger accurately represents the
7825 real-world balances (and, that the real-world institutions have not
7826 made a mistake!). This gets easy and fast with (1) practice and (2)
7827 frequency. If you do it daily, it can take 2-10 minutes. If you let
7828 it pile up, expect it to take longer as you hunt down errors and dis‐
7829 crepancies.
7830 A typical workflow:
7832 1. Reconcile cash. Count what's in your wallet. Compare with what
7834 hledger reports (hledger bal cash). If they are different, try to
7835 remember the missing transaction, or look for the error in the al‐
7836 ready-recorded transactions. A register report can be helpful
7837 (hledger reg cash). If you can't find the error, add an adjustment
7838 transaction. Eg if you have $105 after the above, and can't explain
7839 the missing $2, it could be:
7840 2020-01-16 * adjust cash
7842 assets:cash $-2 = $105
7843 expenses:misc
7844 2. Reconcile checking. Log in to your bank's website. Compare today's
7846 (cleared) balance with hledger's cleared balance (hledger bal check‐
7847 ing -C). If they are different, track down the error or record the
7848 missing transaction(s) or add an adjustment transaction, similar to
7849 the above. Unlike the cash case, you can usually compare the trans‐
7850 action history and running balance from your bank with the one re‐
7851 ported by hledger reg checking -C. This will be easier if you gen‐
7852 erally record transaction dates quite similar to your bank's clear‐
7853 ing dates.
7854 3. Repeat for other asset/liability accounts.
7856 Tip: instead of the register command, use hledger-ui to see a live-up‐
7858 dating register while you edit the journal: hledger-ui --watch --regis‐
7859 ter checking -C
7860 After reconciling, it could be a good time to mark the reconciled
7862 transactions' status as "cleared and confirmed", if you want to track
7863 that, by adding the * marker. Eg in the paycheck transaction above,
7864 insert * between 2020-01-15 and paycheck
7865 If you're using version control, this can be another good time to com‐
7867 mit:
7868 $ git commit -m 'txns' 2020.journal
7870 Reporting
7872 Here are some basic reports.
7873 Show all transactions:
7875 $ hledger print
7877 2020-01-01 * opening balances
7878 assets:bank:checking $1000
7879 assets:bank:savings $2000
7880 assets:cash $100
7881 liabilities:creditcard $-50
7882 equity:opening/closing balances $-3050
7883 2020-01-10 * gift received
7885 assets:cash $20
7886 income:gifts
7887 2020-01-12 * farmers market
7889 expenses:food $13
7890 assets:cash
7891 2020-01-15 * paycheck
7893 income:salary
7894 assets:bank:checking $1000
7895 2020-01-16 * adjust cash
7897 assets:cash $-2 = $105
7898 expenses:misc
7899 Show account names, and their hierarchy:
7901 $ hledger accounts --tree
7903 assets
7904 bank
7905 checking
7906 savings
7907 cash
7908 equity
7909 opening/closing balances
7910 expenses
7911 food
7912 misc
7913 income
7914 gifts
7915 salary
7916 liabilities
7917 creditcard
7918 Show all account totals:
7920 $ hledger balance
7922 $4105 assets
7923 $4000 bank
7924 $2000 checking
7925 $2000 savings
7926 $105 cash
7927 $-3050 equity:opening/closing balances
7928 $15 expenses
7929 $13 food
7930 $2 misc
7931 $-1020 income
7932 $-20 gifts
7933 $-1000 salary
7934 $-50 liabilities:creditcard
7935 --------------------
7936 0
7937 Show only asset and liability balances, as a flat list, limited to
7939 depth 2:
7940 $ hledger bal assets liabilities -2
7942 $4000 assets:bank
7943 $105 assets:cash
7944 $-50 liabilities:creditcard
7945 --------------------
7946 $4055
7947 Show the same thing without negative numbers, formatted as a simple
7949 balance sheet:
7950 $ hledger bs -2
7952 Balance Sheet 2020-01-16
7953 || 2020-01-16
7955 ========================++============
7956 Assets ||
7957 ------------------------++------------
7958 assets:bank || $4000
7959 assets:cash || $105
7960 ------------------------++------------
7961 || $4105
7962 ========================++============
7963 Liabilities ||
7964 ------------------------++------------
7965 liabilities:creditcard || $50
7966 ------------------------++------------
7967 || $50
7968 ========================++============
7969 Net: || $4055
7970 The final total is your "net worth" on the end date. (Or use bse for a
7972 full balance sheet with equity.)
7973 Show income and expense totals, formatted as an income statement:
7975 hledger is
7977 Income Statement 2020-01-01-2020-01-16
7978 || 2020-01-01-2020-01-16
7980 ===============++=======================
7981 Revenues ||
7982 ---------------++-----------------------
7983 income:gifts || $20
7984 income:salary || $1000
7985 ---------------++-----------------------
7986 || $1020
7987 ===============++=======================
7988 Expenses ||
7989 ---------------++-----------------------
7990 expenses:food || $13
7991 expenses:misc || $2
7992 ---------------++-----------------------
7993 || $15
7994 ===============++=======================
7995 Net: || $1005
7996 The final total is your net income during this period.
7998 Show transactions affecting your wallet, with running total:
8000 $ hledger register cash
8002 2020-01-01 opening balances assets:cash $100 $100
8003 2020-01-10 gift received assets:cash $20 $120
8004 2020-01-12 farmers market assets:cash $-13 $107
8005 2020-01-16 adjust cash assets:cash $-2 $105
8006 Show weekly posting counts as a bar chart:
8008 $ hledger activity -W
8010 2019-12-30 *****
8011 2020-01-06 ****
8012 2020-01-13 ****
8013 Migrating to a new file
8015 At the end of the year, you may want to continue your journal in a new
8016 file, so that old transactions don't slow down or clutter your reports,
8017 and to help ensure the integrity of your accounting history. See the
8018 close command.
8019 If using version control, don't forget to git add the new file.
8021
8023 The need to precede add-on command options with -- when invoked from
8024 hledger is awkward.
8025 When input data contains non-ascii characters, a suitable system locale
8027 must be configured (or there will be an unhelpful error). Eg on POSIX,
8028 set LANG to something other than C.
8029 In a Microsoft Windows CMD window, non-ascii characters and colours are
8031 not supported.
8032 On Windows, non-ascii characters may not display correctly when running
8034 a hledger built in CMD in MSYS/CYGWIN, or vice-versa.
8035 In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
8037 add.
8038 Not all of Ledger's journal file syntax is supported. See hledger and
8040 Ledger > Differences > journal format.
8041 On large data files, hledger is slower and uses more memory than
8043 Ledger.
8044
8046 Here are some issues you might encounter when you run hledger (and re‐
8047 member you can also seek help from the IRC channel, mail list or bug
8048 tracker):
8049 Successfully installed, but "No command 'hledger' found"
8051 stack and cabal install binaries into a special directory, which should
8052 be added to your PATH environment variable. Eg on unix-like systems,
8053 that is ~/.local/bin and ~/.cabal/bin respectively.
8054 I set a custom LEDGER_FILE, but hledger is still using the default file
8056 LEDGER_FILE should be a real environment variable, not just a shell
8057 variable. The command env | grep LEDGER_FILE should show it. You may
8058 need to use export. Here's an explanation.
8059 Getting errors like "Illegal byte sequence" or "Invalid or incomplete
8061 multibyte or wide character" or "commitAndReleaseBuffer: invalid argu‐
8062 ment (invalid character)"
8063 Programs compiled with GHC (hledger, haskell build tools, etc.) need to
8064 have a UTF-8-aware locale configured in the environment, otherwise they
8065 will fail with these kinds of errors when they encounter non-ascii
8066 characters.
8067 To fix it, set the LANG environment variable to some locale which sup‐
8069 ports UTF-8. The locale you choose must be installed on your system.
8070 Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:
8072 $ file my.journal
8074 my.journal: UTF-8 Unicode text # the file is UTF8-encoded
8075 $ echo $LANG
8076 C # LANG is set to the default locale, which does not support UTF8
8077 $ locale -a # which locales are installed ?
8078 C
8079 en_US.utf8 # here's a UTF8-aware one we can use
8080 POSIX
8081 $ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command
8082 If available, C.UTF-8 will also work. If your preferred locale isn't
8084 listed by locale -a, you might need to install it. Eg on Ubuntu/De‐
8085 bian:
8086 $ apt-get install language-pack-fr
8088 $ locale -a
8089 C
8090 en_US.utf8
8091 fr_BE.utf8
8092 fr_CA.utf8
8093 fr_CH.utf8
8094 fr_FR.utf8
8095 fr_LU.utf8
8096 POSIX
8097 $ LANG=fr_FR.utf8 hledger -f my.journal print
8098 Here's how you could set it permanently, if you use a bash shell:
8100 $ echo "export LANG=en_US.utf8" >>~/.bash_profile
8102 $ bash --login
8103 Exact spelling and capitalisation may be important. Note the differ‐
8105 ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow
8106 variant spellings, but others (eg macos) require it to be exact:
8107 $ locale -a | grep -iE en_us.*utf
8109 en_US.UTF-8
8110 $ LANG=en_US.UTF-8 hledger -f my.journal print
8111
8115 Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
8116 or hledger mail list)
8117
8120 Simon Michael <simon@joyful.com> and contributors
8121
8124 Copyright (C) 2007-2020 Simon Michael.
8125 Released under GNU GPL v3 or later.
8126
8129 hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
8130hledger-1.27 September 2022 HLEDGER(1)