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.21.
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 For more about this format, see hledger_journal(5).
47 Most users use a text editor to edit the journal, usually with an edi‐
49 tor mode such as ledger-mode for added convenience. hledger’s interac‐
50 tive add command is another way to record new transactions. hledger
51 never changes existing transactions.
52 To get started, you can either save some entries like the above in
54 ~/.hledger.journal, or run hledger add and follow the prompts. Then
55 try some commands like hledger print or hledger balance. Run hledger
56 with no arguments for a list of commands.
57
59 General options
60 To see general usage help, including general options which are sup‐
61 ported by most hledger commands, run hledger -h.
62 General help options:
64 -h --help
66 show general or COMMAND help
67 --man show general or COMMAND user manual with man
69 --info show general or COMMAND user manual with info
71 --version
73 show general or ADDONCMD version
74 --debug[=N]
76 show debug output (levels 1-9, default: 1)
77 General input options:
79 -f FILE --file=FILE
81 use a different input file. For stdin, use - (default:
82 $LEDGER_FILE or $HOME/.hledger.journal)
83 --rules-file=RULESFILE
85 Conversion rules file to use when reading CSV (default:
86 FILE.rules)
87 --separator=CHAR
89 Field separator to expect when reading CSV (default: ',')
90 --alias=OLD=NEW
92 rename accounts named OLD to NEW
93 --anon anonymize accounts and payees
95 --pivot FIELDNAME
97 use some other field or tag for the account name
98 -I --ignore-assertions
100 disable balance assertion checks (note: does not disable balance
101 assignments)
102 -s --strict
104 do extra error checking (check that all posted accounts are de‐
105 clared)
106 General reporting options:
108 -b --begin=DATE
110 include postings/txns on or after this date
111 -e --end=DATE
113 include postings/txns before this date
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 -U --unmarked
139 include only unmarked postings/txns (can combine with -P or -C)
140 -P --pending
142 include only pending postings/txns
143 -C --cleared
145 include only cleared postings/txns
146 -R --real
148 include only non-virtual postings
149 -NUM --depth=NUM
151 hide/aggregate accounts or postings more than NUM levels deep
152 -E --empty
154 show items with zero amount, normally hidden (and vice-versa in
155 hledger-ui/hledger-web)
156 -B --cost
158 convert amounts to their cost/selling amount at transaction time
159 -V --market
161 convert amounts to their market value in default valuation com‐
162 modities
163 -X --exchange=COMM
165 convert amounts to their market value in commodity COMM
166 --value
168 convert amounts to cost or market value, more flexibly than
169 -B/-V/-X
170 --infer-market-prices
172 use transaction prices (recorded with @ or @@) as additional
173 market prices, as if they were P directives
174 --auto apply automated posting rules to modify transactions.
176 --forecast
178 generate future transactions from periodic transaction rules,
179 for the next 6 months or till report end date. In hledger-ui,
180 also make ordinary future transactions visible.
181 --color=WHEN (or --colour=WHEN)
183 Should color-supporting commands use ANSI color codes in text
184 output. 'auto' (default): whenever stdout seems to be a color-
185 supporting terminal. 'always' or 'yes': always, useful eg when
186 piping output into 'less -R'. 'never' or 'no': never. A
187 NO_COLOR environment variable overrides this.
188 When a reporting option appears more than once in the command line, the
190 last one takes precedence.
191 Some reporting options can also be written as query arguments.
193 Command options
195 To see options for a particular command, including command-specific op‐
196 tions, run: hledger COMMAND -h.
197 Command-specific options must be written after the command name, eg:
199 hledger print -x.
200 Additionally, if the command is an add-on, you may need to put its op‐
202 tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can
203 run the add-on executable directly: hledger-ui --watch.
204 Command arguments
206 Most hledger commands accept arguments after the command name, which
207 are often a query, filtering the data in some way.
208 You can save a set of command line options/arguments in a file, and
210 then reuse them by writing @FILENAME as a command line argument. Eg:
211 hledger bal @foo.args. (To prevent this, eg if you have an argument
212 that begins with a literal @, precede it with --, eg: hledger bal --
213 @ARG).
214 Inside the argument file, each line should contain just one option or
216 argument. Avoid the use of spaces, except inside quotes (or you'll see
217 a confusing error). Between a flag and its argument, use = (or noth‐
218 ing). Bad:
219 assets depth:2
221 -X USD
222 Good:
224 assets
226 depth:2
227 -X=USD
228 For special characters (see below), use one less level of quoting than
230 you would at the command prompt. Bad:
231 -X"$"
233 Good:
235 -X$
237 See also: Save frequently used options.
239 Special characters
241 Single escaping (shell metacharacters)
242 In shell command lines, characters significant to your shell - such as
243 spaces, <, >, (, ), |, $ and \ - should be "shell-escaped" if you want
244 hledger to see them. This is done by enclosing them in single or dou‐
245 ble quotes, or by writing a backslash before them. Eg to match an ac‐
246 count name containing a space:
247 $ hledger register 'credit card'
249 or:
251 $ hledger register credit\ card
253 Double escaping (regular expression metacharacters)
255 Characters significant in regular expressions (described below) - such
256 as ., ^, $, [, ], (, ), |, and \ - may need to be "regex-escaped" if
257 you don't want them to be interpreted by hledger's regular expression
258 engine. This is done by writing backslashes before them, but since
259 backslash is typically also a shell metacharacter, both shell-escaping
260 and regex-escaping will be needed. Eg to match a literal $ sign while
261 using the bash shell:
262 $ hledger balance cur:'\$'
264 or:
266 $ hledger balance cur:\\$
268 Triple escaping (for add-on commands)
270 When you use hledger to run an external add-on command (described be‐
271 low), one level of shell-escaping is lost from any options or arguments
272 intended for by the add-on command, so those need an extra level of
273 shell-escaping. Eg to match a literal $ sign while using the bash
274 shell and running an add-on command (ui):
275 $ hledger ui cur:'\\$'
277 or:
279 $ hledger ui cur:\\\\$
281 If you wondered why four backslashes, perhaps this helps:
283 unescaped: $
285 escaped: \$
286 double-escaped: \\$
287 triple-escaped: \\\\$
288 Or, you can avoid the extra escaping by running the add-on executable
290 directly:
291 $ hledger-ui cur:\\$
293 Less escaping
295 Options and arguments are sometimes used in places other than the shell
296 command line, where shell-escaping is not needed, so there you should
297 use one less level of escaping. Those places include:
298 • an @argumentfile
300 • hledger-ui's filter field
302 • hledger-web's search form
304 • GHCI's prompt (used by developers).
306 Unicode characters
308 hledger is expected to handle non-ascii characters correctly:
309 • they should be parsed correctly in input files and on the command
311 line, by all hledger tools (add, iadd, hledger-web's search/add/edit
312 forms, etc.)
313 • they should be displayed correctly by all hledger tools, and on-
315 screen alignment should be preserved.
316 This requires a well-configured environment. Here are some tips:
318 • A system locale must be configured, and it must be one that can de‐
320 code the characters being used. In bash, you can set a locale like
321 this: export LANG=en_US.UTF-8. There are some more details in Trou‐
322 bleshooting. This step is essential - without it, hledger will quit
323 on encountering a non-ascii character (as with all GHC-compiled pro‐
324 grams).
325 • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
327 must support unicode
328 • the terminal must be using a font which includes the required unicode
330 glyphs
331 • the terminal should be configured to display wide characters as dou‐
333 ble width (for report alignment)
334 • on Windows, for best results you should run hledger in the same kind
336 of environment in which it was built. Eg hledger built in the stan‐
337 dard CMD.EXE environment (like the binaries on our download page)
338 might show display problems when run in a cygwin or msys terminal,
339 and vice versa. (See eg #961).
340 Regular expressions
342 hledger uses regular expressions in a number of places:
343 • query terms, on the command line and in the hledger-web search form:
345 REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
346 • CSV rules conditional blocks: if REGEX ...
348 • account alias directives and options: alias /REGEX/ = REPLACEMENT,
350 --alias /REGEX/=REPLACEMENT
351 hledger's regular expressions come from the regex-tdfa library. If
353 they're not doing what you expect, it's important to know exactly what
354 they support:
355 1. they are case insensitive
357 2. they are infix matching (they do not need to match the entire thing
359 being matched)
360 3. they are POSIX ERE (extended regular expressions)
362 4. they also support GNU word boundaries (\b, \B, \<, \>)
364 5. they do not support backreferences; if you write \1, it will match
366 the digit 1. Except when doing text replacement, eg in account
367 aliases, where backreferences can be used in the replacement string
368 to reference capturing groups in the search regexp.
369 6. they do not support mode modifiers ((?s)), character classes (\w,
371 \d), or anything else not mentioned above.
372 Some things to note:
374 • In the alias directive and --alias option, regular expressions must
376 be enclosed in forward slashes (/REGEX/). Elsewhere in hledger,
377 these are not required.
378 • In queries, to match a regular expression metacharacter like $ as a
380 literal character, prepend a backslash. Eg to search for amounts
381 with the dollar sign in hledger-web, write cur:\$.
382 • On the command line, some metacharacters like $ have a special mean‐
384 ing to the shell and so must be escaped at least once more. See Spe‐
385 cial characters.
386
388 LEDGER_FILE The journal file path when not specified with -f. Default:
389 ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour‐
390 nal).
391 A typical value is ~/DIR/YYYY.journal, where DIR is a version-con‐
393 trolled finance directory and YYYY is the current year. Or ~/DIR/cur‐
394 rent.journal, where current.journal is a symbolic link to YYYY.journal.
395 On Mac computers, you can set this and other environment variables in a
397 more thorough way that also affects applications started from the GUI
398 (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en‐
399 vironment.plist file containing
400 {
402 "LEDGER_FILE" : "~/finance/current.journal"
403 }
404 To see the effect you may need to killall Dock, or reboot.
406 COLUMNS The screen width used by the register command. Default: the
408 full terminal width.
409 NO_COLOR If this variable exists with any value, hledger will not use
411 ANSI color codes in terminal output. This overrides the
412 --color/--colour option.
413
415 hledger reads transactions from one or more data files. The default
416 data file is $HOME/.hledger.journal (or on Windows, something like
417 C:/Users/USER/.hledger.journal).
418 You can override this with the $LEDGER_FILE environment variable:
420 $ setenv LEDGER_FILE ~/finance/2016.journal
422 $ hledger stats
423 or with one or more -f/--file options:
425 $ hledger -f /some/file -f another_file stats
427 The file name - means standard input:
429 $ cat some.journal | hledger -f-
431 Data formats
433 Usually the data file is in hledger's journal format, but it can be in
434 any of the supported file formats, which currently are:
435 Reader: Reads: Used for file exten‐
437 sions:
438 ─────────────────────────────────────────────────────────────────────────────
439 journal hledger journal files and some Ledger .journal .j .hledger
440 journals, for transactions .ledger
441 time‐ timeclock files, for precise time log‐ .timeclock
442 clock ging
443 timedot timedot files, for approximate time .timedot
444 logging
445 csv comma/semicolon/tab/other-separated .csv .ssv .tsv
446 values, for data import
447 These formats are described in their own sections, below.
449 hledger detects the format automatically based on the file extensions
451 shown above. If it can't recognise the file extension, it assumes
452 journal format. So for non-journal files, it's important to use a
453 recognised file extension, so as to either read successfully or to show
454 relevant error messages.
455 You can also force a specific reader/format by prefixing the file path
457 with the format and a colon. Eg, to read a .dat file as csv format:
458 $ hledger -f csv:/some/csv-file.dat stats
460 Or to read stdin (-) as timeclock format:
462 $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-
464 Multiple files
466 You can specify multiple -f options, to read multiple files as one big
467 journal. There are some limitations with this:
468 • most directives do not affect sibling files
470 • balance assertions will not see any account balances from previous
472 files
473 If you need either of those things, you can
475 • use a single parent file which includes the others
477 • or concatenate the files into one before reading, eg: cat a.journal
479 b.journal | hledger -f- CMD.
480 Strict mode
482 hledger checks input files for valid data. By default, the most impor‐
483 tant errors are detected, while still accepting easy journal files
484 without a lot of declarations:
485 • Are the input files parseable, with valid syntax ?
487 • Are all transactions balanced ?
489 • Do all balance assertions pass ?
491 With the -s/--strict flag, additional checks are performed:
493 • Are all accounts posted to, declared with an account directive ?
495 (Account error checking)
496 • Are all commodities declared with a commodity directive ? (Commodity
498 error checking)
499 See also: https://hledger.org/checking-for-errors.html
501 experimental.
503
505 Smart dates
506 hledger's user interfaces accept a flexible "smart date" syntax. Smart
507 dates allow some english words, can be relative to today's date, and
508 can have less-significant date parts omitted (defaulting to 1).
509 Examples:
511 2004/10/1, 2004-01-01, exact date, several separators allowed. Year
513 2004.9.1 is 4+ digits, month is 1-12, day is 1-31
514 2004 start of year
515 2004/10 start of month
516 10/1 month and day in current year
517 21 day in current month
518 october, oct start of month in current year
519 yesterday, today, tomor‐ -1, 0, 1 days from today
520 row
521 last/this/next -1, 0, 1 periods from the current period
522 day/week/month/quar‐
523 ter/year
524 20181201 8 digit YYYYMMDD with valid year month and day
525 201812 6 digit YYYYMM with valid year and month
526 Counterexamples - malformed digit sequences might give surprising re‐
528 sults:
529 201813 6 digits with an invalid month is parsed as start of
531 6-digit year
532 20181301 8 digits with an invalid month is parsed as start of
533 8-digit year
534 20181232 8 digits with an invalid day gives an error
535 201801012 9+ digits beginning with a valid YYYYMMDD gives an error
536 Report start & end date
538 By default, most hledger reports will show the full span of time repre‐
539 sented by the journal data. The report start date will be the earliest
540 transaction or posting date, and the report end date will be the latest
541 transaction, posting, or market price date.
542 Often you will want to see a shorter time span, such as the current
544 month. You can specify a start and/or end date using -b/--begin,
545 -e/--end, -p/--period or a date: query (described below). All of these
546 accept the smart date syntax.
547 Some notes:
549 • As in Ledger, end dates are exclusive, so you need to write the date
551 after the last day you want to include.
552 • As noted in reporting options: among start/end dates specified with
554 options, the last (i.e. right-most) option takes precedence.
555 • The effective report start and end dates are the intersection of the
557 start/end dates from options and that from date: queries. That is,
558 date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the
559 smallest common time span.
560 Examples:
562 -b 2016/3/17 begin on St. Patrick’s day 2016
564 -e 12/1 end at the start of december 1st of the current year
565 (11/30 will be the last date included)
566 -b thismonth all transactions on or after the 1st of the current month
567 -p thismonth all transactions in the current month
568 date:2016/3/17.. the above written as queries instead (.. can also be re‐
570 placed with -)
571 date:..12/1
572 date:thismonth..
573 date:thismonth
574 Report intervals
576 A report interval can be specified so that commands like register, bal‐
577 ance and activity will divide their reports into multiple subperiods.
578 The basic intervals can be selected with one of -D/--daily,
579 -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com‐
580 plex intervals may be specified with a period expression. Report in‐
581 tervals can not be specified with a query.
582 Period expressions
584 The -p/--period option accepts period expressions, a shorthand way of
585 expressing a start date, end date, and/or report interval all at once.
586 Here's a basic period expression specifying the first quarter of 2009.
588 Note, hledger always treats start dates as inclusive and end dates as
589 exclusive:
590 -p "from 2009/1/1 to 2009/4/1"
592 Keywords like "from" and "to" are optional, and so are the spaces, as
594 long as you don't run two dates together. "to" can also be written as
595 ".." or "-". These are equivalent to the above:
596 -p "2009/1/1 2009/4/1"
598 -p2009/1/1to2009/4/1
599 -p2009/1/1..2009/4/1
600 Dates are smart dates, so if the current year is 2009, the above can
602 also be written as:
603 -p "1/1 4/1"
605 -p "january-apr"
606 -p "this year to 4/1"
607 If you specify only one date, the missing start or end date will be the
609 earliest or latest transaction in your journal:
610 -p "from 2009/1/1" everything after january
612 1, 2009
613 -p "from 2009/1" the same
614 -p "from 2009" the same
615 -p "to 2009" everything before january
616 1, 2009
617 A single date with no "from" or "to" defines both the start and end
619 date like so:
620 -p "2009" the year 2009; equivalent
622 to “2009/1/1 to 2010/1/1”
623 -p "2009/1" the month of jan; equiva‐
624 lent to “2009/1/1 to
625 2009/2/1”
626 -p "2009/1/1" just that day; equivalent
627 to “2009/1/1 to 2009/1/2”
628 Or you can specify a single quarter like so:
630 -p "2009Q1" first quarter of 2009,
632 equivalent to “2009/1/1 to
633 2009/4/1”
634 -p "q4" fourth quarter of the cur‐
635 rent year
636 The argument of -p can also begin with, or be, a report interval ex‐
638 pression. The basic report intervals are daily, weekly, monthly, quar‐
639 terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y
640 flags. Between report interval and start/end dates (if any), the word
641 in is optional. Examples:
642 -p "weekly from 2009/1/1 to 2009/4/1"
644 -p "monthly in 2008"
645 -p "quarterly"
646 Note that weekly, monthly, quarterly and yearly intervals will always
648 start on the first day on week, month, quarter or year accordingly, and
649 will end on the last day of same period, even if associated period ex‐
650 pression specifies different explicit start and end date.
651 For example:
653 -p "weekly from 2009/1/1 starts on 2008/12/29, closest preceding Mon‐
655 to 2009/4/1" day
656 -p "monthly in starts on 2018/11/01
657 2008/11/25"
658 -p "quarterly from starts on 2009/04/01, ends on 2009/06/30,
659 2009-05-05 to 2009-06-01" which are first and last days of Q2 2009
660 -p "yearly from starts on 2009/01/01, first day of 2009
661 2009-12-29"
662 The following more complex report intervals are also supported: bi‐
664 weekly, fortnightly, bimonthly, every day|week|month|quarter|year, ev‐
665 ery N days|weeks|months|quarters|years.
666 All of these will start on the first day of the requested period and
668 end on the last one, as described above.
669 Examples:
671 -p "bimonthly from 2008" periods will have boundaries on 2008/01/01,
673 2008/03/01, ...
674 -p "every 2 weeks" starts on closest preceding Monday
675 -p "every 5 month from periods will have boundaries on 2009/03/01,
676 2009/03" 2009/08/01, ...
677 If you want intervals that start on arbitrary day of your choosing and
679 span a week, month or year, you need to use any of the following:
680 every Nth day of week, every WEEKDAYNAME (eg
682 mon|tue|wed|thu|fri|sat|sun), every Nth day [of month], every Nth WEEK‐
683 DAYNAME [of month], every MM/DD [of year], every Nth MMM [of year], ev‐
684 ery MMM Nth [of year].
685 Examples:
687 -p "every 2nd day of periods will go from Tue to Tue
689 week"
690 -p "every Tue" same
691 -p "every 15th day" period boundaries will be on 15th of each
692 month
693 -p "every 2nd Monday" period boundaries will be on second Monday of
694 each month
695 -p "every 11/05" yearly periods with boundaries on 5th of Nov
696 -p "every 5th Nov" same
697 -p "every Nov 5th" same
698 Show historical balances at end of 15th each month (N is exclusive end
700 date):
701 hledger balance -H -p "every 16th day"
703 Group postings from start of wednesday to end of next tuesday (N is
705 start date and exclusive end date):
706 hledger register checking -p "every 3rd day of week"
708
710 With the --depth N option (short form: -N), commands like account, bal‐
711 ance and register will show only the uppermost accounts in the account
712 tree, down to level N. Use this when you want a summary with less de‐
713 tail. This flag has the same effect as a depth: query argument (so -2,
714 --depth=2 or depth:2 are equivalent).
715
717 One of hledger's strengths is being able to quickly report on precise
718 subsets of your data. Most commands accept an optional query expres‐
719 sion, written as arguments after the command name, to filter the data
720 by date, account name or other criteria. The syntax is similar to a
721 web search: one or more space-separated search terms, quotes to enclose
722 whitespace, prefixes to match specific fields, a not: prefix to negate
723 the match.
724 We do not yet support arbitrary boolean combinations of search terms;
726 instead most commands show transactions/postings/accounts which match
727 (or negatively match):
728 • any of the description terms AND
730 • any of the account terms AND
732 • any of the status terms AND
734 • all the other terms.
736 The print command instead shows transactions which:
738 • match any of the description terms AND
740 • have any postings matching any of the positive account terms AND
742 • have no postings matching any of the negative account terms AND
744 • match all the other terms.
746 The following kinds of search terms can be used. Remember these can
748 also be prefixed with not:, eg to exclude a particular subaccount.
749 REGEX, acct:REGEX
751 match account names by this regular expression. (With no pre‐
752 fix, acct: is assumed.) same as above
753 amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
755 match postings with a single-commodity amount that is equal to,
756 less than, or greater than N. (Multi-commodity amounts are not
757 tested, and will always match.) The comparison has two modes: if
758 N is preceded by a + or - sign (or is 0), the two signed numbers
759 are compared. Otherwise, the absolute magnitudes are compared,
760 ignoring sign.
761 code:REGEX
763 match by transaction code (eg check number)
764 cur:REGEX
766 match postings or transactions including any amounts whose cur‐
767 rency/commodity symbol is fully matched by REGEX. (For a par‐
768 tial match, use .*REGEX.*). Note, to match characters which are
769 regex-significant, like the dollar sign ($), you need to prepend
770 \. And when using the command line you need to add one more
771 level of quoting to hide it from the shell, so eg do: hledger
772 print cur:'\$' or hledger print cur:\\$.
773 desc:REGEX
775 match transaction descriptions.
776 date:PERIODEXPR
778 match dates within the specified period. PERIODEXPR is a period
779 expression (with no report interval). Examples: date:2016,
780 date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the
781 --date2 command line flag is present, this matches secondary
782 dates instead.
783 date2:PERIODEXPR
785 match secondary dates within the specified period.
786 depth:N
788 match (or display, depending on command) accounts at or above
789 this depth
790 note:REGEX
792 match transaction notes (part of description right of |, or
793 whole description when there's no |)
794 payee:REGEX
796 match transaction payee/payer names (part of description left of
797 |, or whole description when there's no |)
798 real:, real:0
800 match real or virtual postings respectively
801 status:, status:!, status:*
803 match unmarked, pending, or cleared transactions respectively
804 tag:REGEX[=REGEX]
806 match by tag name, and optionally also by tag value. Note a
807 tag: query is considered to match a transaction if it matches
808 any of the postings. Also remember that postings inherit the
809 tags of their parent transaction.
810 The following special search term is used automatically in hledger-web,
812 only:
813 inacct:ACCTNAME
815 tells hledger-web to show the transaction register for this ac‐
816 count. Can be filtered further with acct etc.
817 Some of these can also be expressed as command-line options (eg depth:2
819 is equivalent to --depth 2). Generally you can mix options and query
820 arguments, and the resulting query will be their intersection (perhaps
821 excluding the -p/--period option).
822
824 The -B/--cost flag converts amounts to their cost or sale amount at
825 transaction time, if they have a transaction price specified. If this
826 flag is supplied, hledger will perform cost conversion first, and will
827 apply any market price valuations (if requested) afterwards.
828
830 Instead of reporting amounts in their original commodity, hledger can
831 convert them to cost/sale amount (using the conversion rate recorded in
832 the transaction), and/or to market value (using some market price on a
833 certain date). This is controlled by the --value=TYPE[,COMMODITY] op‐
834 tion, which will be described below. We also provide the simpler -V
835 and -X COMMODITY options, and often one of these is all you need:
836 -V: Value
838 The -V/--market flag converts amounts to market value in their default
839 valuation commodity, using the market prices in effect on the valuation
840 date(s), if any. More on these in a minute.
841 -X: Value in specified commodity
843 The -X/--exchange=COMM option is like -V, except you tell it which cur‐
844 rency you want to convert to, and it tries to convert everything to
845 that.
846 Valuation date
848 Since market prices can change from day to day, market value reports
849 have a valuation date (or more than one), which determines which market
850 prices will be used.
851 For single period reports, if an explicit report end date is specified,
853 that will be used as the valuation date; otherwise the valuation date
854 is the journal's end date.
855 For multiperiod reports, each column/period is valued on the last day
857 of the period, by default.
858 Market prices
860 To convert a commodity A to its market value in another commodity B,
861 hledger looks for a suitable market price (exchange rate) as follows,
862 in this order of preference :
863 1. A declared market price or inferred market price: A's latest market
865 price in B on or before the valuation date as declared by a P direc‐
866 tive, or (with the --infer-market-price flag) inferred from transac‐
867 tion prices.
868 2. A reverse market price: the inverse of a declared or inferred market
870 price from B to A.
871 3. A forward chain of market prices: a synthetic price formed by com‐
873 bining the shortest chain of "forward" (only 1 above) market prices,
874 leading from A to B.
875 4. Any chain of market prices: a chain of any market prices, including
877 both forward and reverse prices (1 and 2 above), leading from A to
878 B.
879 There is a limit to the length of these price chains; if hledger
881 reaches that length without finding a complete chain or exhausting all
882 possibilities, it will give up (with a "gave up" message visible in
883 --debug=2 output). That limit is currently 1000.
884 Amounts for which no suitable market price can be found, are not con‐
886 verted.
887 --infer-market-price: market prices from transactions
889 Normally, market value in hledger is fully controlled by, and requires,
890 P directives in your journal. Since adding and updating those can be a
891 chore, and since transactions usually take place at close to market
892 value, why not use the recorded transaction prices as additional market
893 prices (as Ledger does) ? We could produce value reports without need‐
894 ing P directives at all.
895 Adding the --infer-market-price flag to -V, -X or --value enables this.
897 So for example, hledger bs -V --infer-market-price will get market
898 prices both from P directives and from transactions. (And if both oc‐
899 cur on the same day, the P directive takes precedence).
900 There is a downside: value reports can sometimes be affected in confus‐
902 ing/undesired ways by your journal entries. If this happens to you,
903 read all of this Valuation section carefully, and try adding --debug or
904 --debug=2 to troubleshoot.
905 --infer-market-price can infer market prices from:
907 • multicommodity transactions with explicit prices (@/@@)
909 • multicommodity transactions with implicit prices (no @, two commodi‐
911 ties, unbalanced). (With these, the order of postings matters.
912 hledger print -x can be useful for troubleshooting.)
913 • but not, currently, from "more correct" multicommodity transactions
915 (no @, multiple commodities, balanced).
916 Valuation commodity
918 When you specify a valuation commodity (-X COMM or --value TYPE,COMM):
919 hledger will convert all amounts to COMM, wherever it can find a suit‐
920 able market price (including by reversing or chaining prices).
921 When you leave the valuation commodity unspecified (-V or --value
923 TYPE):
924 For each commodity A, hledger picks a default valuation commodity as
925 follows, in this order of preference:
926 1. The price commodity from the latest P-declared market price for A on
928 or before valuation date.
929 2. The price commodity from the latest P-declared market price for A on
931 any date. (Allows conversion to proceed when there are inferred
932 prices before the valuation date.)
933 3. If there are no P directives at all (any commodity or date) and the
935 --infer-market-price flag is used: the price commodity from the lat‐
936 est transaction-inferred price for A on or before valuation date.
937 This means:
939 • If you have P directives, they determine which commodities -V will
941 convert, and to what.
942 • If you have no P directives, and use the --infer-market-price flag,
944 transaction prices determine it.
945 Amounts for which no valuation commodity can be found are not con‐
947 verted.
948 Simple valuation examples
950 Here are some quick examples of -V:
951 ; one euro is worth this many dollars from nov 1
953 P 2016/11/01 € $1.10
954 ; purchase some euros on nov 3
956 2016/11/3
957 assets:euros €100
958 assets:checking
959 ; the euro is worth fewer dollars by dec 21
961 P 2016/12/21 € $1.03
962 How many euros do I have ?
964 $ hledger -f t.j bal -N euros
966 €100 assets:euros
967 What are they worth at end of nov 3 ?
969 $ hledger -f t.j bal -N euros -V -e 2016/11/4
971 $110.00 assets:euros
972 What are they worth after 2016/12/21 ? (no report end date specified,
974 defaults to today)
975 $ hledger -f t.j bal -N euros -V
977 $103.00 assets:euros
978 --value: Flexible valuation
980 -V and -X are special cases of the more general --value option:
981 --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD.
983 COMM is an optional commodity symbol.
984 Shows amounts converted to:
985 - default valuation commodity (or COMM) using market prices at posting dates
986 - default valuation commodity (or COMM) using market prices at period end(s)
987 - default valuation commodity (or COMM) using current market prices
988 - default valuation commodity (or COMM) using market prices at some date
989 The TYPE part selects cost or value and valuation date:
991 --value=then
993 Convert amounts to their value in the default valuation commod‐
994 ity, using market prices on each posting's date.
995 --value=end
997 Convert amounts to their value in the default valuation commod‐
998 ity, using market prices on the last day of the report period
999 (or if unspecified, the journal's end date); or in multiperiod
1000 reports, market prices on the last day of each subperiod.
1001 --value=now
1003 Convert amounts to their value in the default valuation commod‐
1004 ity using current market prices (as of when report is gener‐
1005 ated).
1006 --value=YYYY-MM-DD
1008 Convert amounts to their value in the default valuation commod‐
1009 ity using market prices on this date.
1010 To select a different valuation commodity, add the optional ,COMM part:
1012 a comma, then the target commodity's symbol. Eg: --value=now,EUR.
1013 hledger will do its best to convert amounts to this commodity, deducing
1014 market prices as described above.
1015 More valuation examples
1017 Here are some examples showing the effect of --value, as seen with
1018 print:
1019 P 2000-01-01 A 1 B
1021 P 2000-02-01 A 2 B
1022 P 2000-03-01 A 3 B
1023 P 2000-04-01 A 4 B
1024 2000-01-01
1026 (a) 1 A @ 5 B
1027 2000-02-01
1029 (a) 1 A @ 6 B
1030 2000-03-01
1032 (a) 1 A @ 7 B
1033 Show the cost of each posting:
1035 $ hledger -f- print --cost
1037 2000-01-01
1038 (a) 5 B
1039 2000-02-01
1041 (a) 6 B
1042 2000-03-01
1044 (a) 7 B
1045 Show the value as of the last day of the report period (2000-02-29):
1047 $ hledger -f- print --value=end date:2000/01-2000/03
1049 2000-01-01
1050 (a) 2 B
1051 2000-02-01
1053 (a) 2 B
1054 With no report period specified, that shows the value as of the last
1056 day of the journal (2000-03-01):
1057 $ hledger -f- print --value=end
1059 2000-01-01
1060 (a) 3 B
1061 2000-02-01
1063 (a) 3 B
1064 2000-03-01
1066 (a) 3 B
1067 Show the current value (the 2000-04-01 price is still in effect today):
1069 $ hledger -f- print --value=now
1071 2000-01-01
1072 (a) 4 B
1073 2000-02-01
1075 (a) 4 B
1076 2000-03-01
1078 (a) 4 B
1079 Show the value on 2000/01/15:
1081 $ hledger -f- print --value=2000-01-15
1083 2000-01-01
1084 (a) 1 B
1085 2000-02-01
1087 (a) 1 B
1088 2000-03-01
1090 (a) 1 B
1091 You may need to explicitly set a commodity's display style, when re‐
1093 verse prices are used. Eg this output might be surprising:
1094 P 2000-01-01 A 2B
1096 2000-01-01
1098 a 1B
1099 b
1100 $ hledger print -x -X A
1102 2000-01-01
1103 a 0
1104 b 0
1105 Explanation: because there's no amount or commodity directive specify‐
1107 ing a display style for A, 0.5A gets the default style, which shows no
1108 decimal digits. Because the displayed amount looks like zero, the com‐
1109 modity symbol and minus sign are not displayed either. Adding a com‐
1110 modity directive sets a more useful display style for A:
1111 P 2000-01-01 A 2B
1113 commodity 0.00A
1114 2000-01-01
1116 a 1B
1117 b
1118 $ hledger print -X A
1120 2000-01-01
1121 a 0.50A
1122 b -0.50A
1123 Effect of valuation on reports
1125 Here is a reference for how valuation is supposed to affect each part
1126 of hledger's reports (and a glossary). (It's wide, you'll have to
1127 scroll sideways.) It may be useful when troubleshooting. If you find
1128 problems, please report them, ideally with a reproducible example. Re‐
1129 lated: #329, #1083.
1130 Report -B, --cost -V, -X --value=then --value=end --value=DATE,
1132 type --value=now
1133 ────────────────────────────────────────────────────────────────────────────────────────────
1134 print
1135 posting cost value at re‐ value at posting value at re‐ value at
1136 amounts port end or date port or DATE/today
1137 today journal end
1138 balance unchanged unchanged unchanged unchanged unchanged
1139 asser‐
1140 tions/as‐
1141 signments
1142 register
1144 starting cost value at day valued at day value at day value at
1145 balance before re‐ each historical before re‐ DATE/today
1146 (-H) port or posting was made port or
1147 journal journal
1148 start start
1149 posting cost value at re‐ value at posting value at re‐ value at
1150 amounts port end or date port or DATE/today
1151 today journal end
1152 summary summarised value at pe‐ sum of postings value at pe‐ value at
1153 posting cost riod ends in interval, val‐ riod ends DATE/today
1154 amounts ued at interval
1155 with re‐ start
1156 port in‐
1157 terval
1158 running sum/average sum/average sum/average of sum/average sum/average
1159 total/av‐ of displayed of displayed displayed values of displayed of displayed
1160 erage values values values values
1161 balance
1163 (bs, bse,
1164 cf, is)
1165 balance sums of value at re‐ value at posting value at re‐ value at
1166 changes costs port end or date port or DATE/today of
1167 today of journal end sums of post‐
1168 sums of of sums of ings
1169 postings postings
1170 budget like balance like balance like balance like bal‐ like balance
1171 amounts changes changes changes ances changes
1172 (--bud‐
1173 get)
1174 grand to‐ sum of dis‐ sum of dis‐ sum of displayed sum of dis‐ sum of dis‐
1176 tal played val‐ played val‐ valued played val‐ played values
1177 ues ues ues
1178 balance
1180 (bs, bse,
1181 cf, is)
1182 with re‐
1183 port in‐
1184 terval
1185 starting sums of value at re‐ sums of values of value at re‐ sums of post‐
1186 balances costs of port start postings before port start ings before
1187 (-H) postings be‐ of sums of report start at of sums of report start
1188 fore report all postings respective post‐ all postings
1189 start before re‐ ing dates before re‐
1190 port start port start
1191 balance sums of same as sums of values of balance value at
1192 changes costs of --value=end postings in pe‐ change in DATE/today of
1193 (bal, is, postings in riod at respec‐ each period, sums of post‐
1194 bs period tive posting valued at ings
1195 --change, dates period ends
1196 cf
1197 --change)
1198 end bal‐ sums of same as sums of values of period end value at
1199 ances costs of --value=end postings from be‐ balances, DATE/today of
1200 (bal -H, postings fore period start valued at sums of post‐
1201 is --H, from before to period end at period ends ings
1202 bs, cf) report start respective post‐
1203 to period ing dates
1204 end
1205 budget like balance like balance like balance like bal‐ like balance
1206 amounts changes/end changes/end changes/end bal‐ ances changes/end
1207 (--bud‐ balances balances ances balances
1208 get)
1209 row to‐ sums, aver‐ sums, aver‐ sums, averages of sums, aver‐ sums, aver‐
1210 tals, row ages of dis‐ ages of dis‐ displayed values ages of dis‐ ages of dis‐
1211 averages played val‐ played val‐ played val‐ played values
1212 (-T, -A) ues ues ues
1213 column sums of dis‐ sums of dis‐ sums of displayed sums of dis‐ sums of dis‐
1214 totals played val‐ played val‐ values played val‐ played values
1215 ues ues ues
1216 grand to‐ sum, average sum, average sum, average of sum, average sum, average
1217 tal, of column of column column totals of column of column to‐
1218 grand av‐ totals totals totals tals
1219 erage
1220 --cumulative is omitted to save space, it works like -H but with a zero
1223 starting balance.
1224 Glossary:
1226 cost calculated using price(s) recorded in the transaction(s).
1228 value market value using available market price declarations, or the
1230 unchanged amount if no conversion rate can be found.
1231 report start
1233 the first day of the report period specified with -b or -p or
1234 date:, otherwise today.
1235 report or journal start
1237 the first day of the report period specified with -b or -p or
1238 date:, otherwise the earliest transaction date in the journal,
1239 otherwise today.
1240 report end
1242 the last day of the report period specified with -e or -p or
1243 date:, otherwise today.
1244 report or journal end
1246 the last day of the report period specified with -e or -p or
1247 date:, otherwise the latest transaction date in the journal,
1248 otherwise today.
1249 report interval
1251 a flag (-D/-W/-M/-Q/-Y) or period expression that activates the
1252 report's multi-period mode (whether showing one or many subperi‐
1253 ods).
1254
1256 Normally hledger sums amounts, and organizes them in a hierarchy, based
1257 on account name. The --pivot FIELD option causes it to sum and orga‐
1258 nize hierarchy based on the value of some other field instead. FIELD
1259 can be: code, description, payee, note, or the full name (case insensi‐
1260 tive) of any tag. As with account names, values containing colon:sepa‐
1261 rated:parts will be displayed hierarchically in reports.
1262 --pivot is a general option affecting all reports; you can think of
1264 hledger transforming the journal before any other processing, replacing
1265 every posting's account name with the value of the specified field on
1266 that posting, inheriting it from the transaction or using a blank value
1267 if it's not present.
1268 An example:
1270 2016/02/16 Member Fee Payment
1272 assets:bank account 2 EUR
1273 income:member fees -2 EUR ; member: John Doe
1274 Normal balance report showing account names:
1276 $ hledger balance
1278 2 EUR assets:bank account
1279 -2 EUR income:member fees
1280 --------------------
1281 0
1282 Pivoted balance report, using member: tag values instead:
1284 $ hledger balance --pivot member
1286 2 EUR
1287 -2 EUR John Doe
1288 --------------------
1289 0
1290 One way to show only amounts with a member: value (using a query, de‐
1292 scribed below):
1293 $ hledger balance --pivot member tag:member=.
1295 -2 EUR John Doe
1296 --------------------
1297 -2 EUR
1298 Another way (the acct: query matches against the pivoted "account
1300 name"):
1301 $ hledger balance --pivot member acct:.
1303 -2 EUR John Doe
1304 --------------------
1305 -2 EUR
1306
1308 Output destination
1309 hledger commands send their output to the terminal by default. You can
1310 of course redirect this, eg into a file, using standard shell syntax:
1311 $ hledger print > foo.txt
1313 Some commands (print, register, stats, the balance commands) also pro‐
1315 vide the -o/--output-file option, which does the same thing without
1316 needing the shell. Eg:
1317 $ hledger print -o foo.txt
1319 $ hledger print -o - # write to stdout (the default)
1320 Output format
1322 Some commands (print, register, the balance commands) offer a choice of
1323 output format. In addition to the usual plain text format (txt), there
1324 are CSV (csv), HTML (html), JSON (json) and SQL (sql). This is con‐
1325 trolled by the -O/--output-format option:
1326 $ hledger print -O csv
1328 or, by a file extension specified with -o/--output-file:
1330 $ hledger balancesheet -o foo.html # write HTML to foo.html
1332 The -O option can be used to override the file extension if needed:
1334 $ hledger balancesheet -o foo.txt -O html # write HTML to foo.txt
1336 Some notes about JSON output:
1338 • This feature is marked experimental, and not yet much used; you
1340 should expect our JSON to evolve. Real-world feedback is welcome.
1341 • Our JSON is rather large and verbose, as it is quite a faithful rep‐
1343 resentation of hledger's internal data types. To understand the
1344 JSON, read the Haskell type definitions, which are mostly in
1345 https://github.com/simonmichael/hledger/blob/master/hledger-
1346 lib/Hledger/Data/Types.hs.
1347 • hledger represents quantities as Decimal values storing up to 255
1349 significant digits, eg for repeating decimals. Such numbers can
1350 arise in practice (from automatically-calculated transaction prices),
1351 and would break most JSON consumers. So in JSON, we show quantities
1352 as simple Numbers with at most 10 decimal places. We don't limit the
1353 number of integer digits, but that part is under your control. We
1354 hope this approach will not cause problems in practice; if you find
1355 otherwise, please let us know. (Cf #1195)
1356 Notes about SQL output:
1358 • SQL output is also marked experimental, and much like JSON could use
1360 real-world feedback.
1361 • SQL output is expected to work with sqlite, MySQL and PostgreSQL
1363 • SQL output is structured with the expectations that statements will
1365 be executed in the empty database. If you already have tables cre‐
1366 ated via SQL output of hledger, you would probably want to either
1367 clear tables of existing data (via delete or truncate SQL statements)
1368 or drop tables completely as otherwise your postings will be duped.
1369
1371 hledger provides a number of commands for producing reports and manag‐
1372 ing your data. Run hledger with no arguments to list the commands
1373 available, and hledger CMD to run a command. CMD can be the full com‐
1374 mand name, or its standard abbreviation shown in the commands list, or
1375 any unambiguous prefix of the name. Eg: hledger bal.
1376 Here are the built-in commands, with the most often-used in bold:
1378 Data entry:
1380 These data entry commands are the only ones which can modify your jour‐
1382 nal file.
1383 • add - add transactions using guided prompts
1385 • import - add any new transactions from other files (eg csv)
1387 Data management:
1389 • check - check for various kinds of issue in the data
1391 • close (equity) - generate balance-resetting transactions
1393 • diff - compare account transactions in two journal files
1395 • rewrite - generate extra postings, similar to print --auto
1397 Financial statements:
1399 • aregister (areg) - show transactions in a particular account
1401 • balancesheet (bs) - show assets, liabilities and net worth
1403 • balancesheetequity (bse) - show assets, liabilities and equity
1405 • cashflow (cf) - show changes in liquid assets
1407 • incomestatement (is) - show revenues and expenses
1409 • roi - show return on investments
1411 Miscellaneous reports:
1413 • accounts - show account names
1415 • activity - show postings-per-interval bar charts
1417 • balance (bal) - show balance changes/end balances/budgets in any ac‐
1419 counts
1420 • codes - show transaction codes
1422 • commodities - show commodity/currency symbols
1424 • descriptions - show unique transaction descriptions
1426 • files - show input file paths
1428 • help - show hledger user manuals in several formats
1430 • notes - show unique note segments of transaction descriptions
1432 • payees - show unique payee segments of transaction descriptions
1434 • prices - show market price records
1436 • print - show transactions (journal entries)
1438 • print-unique - show only transactions with unique descriptions
1440 • register (reg) - show postings in one or more accounts & running to‐
1442 tal
1443 • register-match - show a recent posting that best matches a descrip‐
1445 tion
1446 • stats - show journal statistics
1448 • tags - show tag names
1450 • test - run self tests
1452 Add-on commands:
1454 Programs or scripts named hledger-SOMETHING in your PATH are add-on
1456 commands; these appear in the commands list with a + mark. Two of
1457 these are maintained and released with hledger:
1458 • ui - an efficient terminal interface (TUI) for hledger
1460 • web - a simple web interface (WUI) for hledger
1462 And these add-ons are maintained separately:
1464 • iadd - a more interactive alternative for the add command
1466 • interest - generates interest transactions according to various
1468 schemes
1469 • stockquotes - downloads market prices for your commodities from Al‐
1471 phaVantage (experimental)
1472 Next, the detailed command docs, in alphabetical order.
1474 accounts
1476 accounts
1477 Show account names.
1478 This command lists account names, either declared with account direc‐
1480 tives (--declared), posted to (--used), or both (the default). With
1481 query arguments, only matched account names and account names refer‐
1482 enced by matched postings are shown. It shows a flat list by default.
1483 With --tree, it uses indentation to show the account hierarchy. In
1484 flat mode you can add --drop N to omit the first few account name com‐
1485 ponents. Account names can be depth-clipped with depth:N or --depth N
1486 or -N.
1487 Examples:
1489 $ hledger accounts
1491 assets:bank:checking
1492 assets:bank:saving
1493 assets:cash
1494 expenses:food
1495 expenses:supplies
1496 income:gifts
1497 income:salary
1498 liabilities:debts
1499 activity
1501 activity
1502 Show an ascii barchart of posting counts per interval.
1503 The activity command displays an ascii histogram showing transaction
1505 counts by day, week, month or other reporting interval (by day is the
1506 default). With query arguments, it counts only matched transactions.
1507 Examples:
1509 $ hledger activity --quarterly
1511 2008-01-01 **
1512 2008-04-01 *******
1513 2008-07-01
1514 2008-10-01 **
1515 add
1517 add
1518 Prompt for transactions and add them to the journal. Any arguments
1519 will be used as default inputs for the first N prompts.
1520 Many hledger users edit their journals directly with a text editor, or
1522 generate them from CSV. For more interactive data entry, there is the
1523 add command, which prompts interactively on the console for new trans‐
1524 actions, and appends them to the journal file (if there are multiple -f
1525 FILE options, the first file is used.) Existing transactions are not
1526 changed. This is the only hledger command that writes to the journal
1527 file.
1528 To use it, just run hledger add and follow the prompts. You can add as
1530 many transactions as you like; when you are finished, enter . or press
1531 control-d or control-c to exit.
1532 Features:
1534 • add tries to provide useful defaults, using the most similar (by de‐
1536 scription) recent transaction (filtered by the query, if any) as a
1537 template.
1538 • You can also set the initial defaults with command line arguments.
1540 • Readline-style edit keys can be used during data entry.
1542 • The tab key will auto-complete whenever possible - accounts, descrip‐
1544 tions, dates (yesterday, today, tomorrow). If the input area is
1545 empty, it will insert the default value.
1546 • If the journal defines a default commodity, it will be added to any
1548 bare numbers entered.
1549 • A parenthesised transaction code may be entered following a date.
1551 • Comments and tags may be entered following a description or amount.
1553 • If you make a mistake, enter < at any prompt to go one step backward.
1555 • Input prompts are displayed in a different colour when the terminal
1557 supports it.
1558 Example (see the tutorial for a detailed explanation):
1560 $ hledger add
1562 Adding transactions to journal file /src/hledger/examples/sample.journal
1563 Any command line arguments will be used as defaults.
1564 Use tab key to complete, readline keys to edit, enter to accept defaults.
1565 An optional (CODE) may follow transaction dates.
1566 An optional ; COMMENT may follow descriptions or amounts.
1567 If you make a mistake, enter < at any prompt to go one step backward.
1568 To end a transaction, enter . when prompted.
1569 To quit, enter . at a date prompt or press control-d or control-c.
1570 Date [2015/05/22]:
1571 Description: supermarket
1572 Account 1: expenses:food
1573 Amount 1: $10
1574 Account 2: assets:checking
1575 Amount 2 [$-10.0]:
1576 Account 3 (or . or enter to finish this transaction): .
1577 2015/05/22 supermarket
1578 expenses:food $10
1579 assets:checking $-10.0
1580 Save this transaction to the journal ? [y]:
1582 Saved.
1583 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
1584 Date [2015/05/22]: <CTRL-D> $
1585 On Microsoft Windows, the add command makes sure that no part of the
1587 file path ends with a period, as that would cause problems (#1056).
1588 aregister
1590 aregister, areg
1591 Show the transactions and running historical balance in an account,
1592 with each line item representing one transaction.
1593 aregister shows the transactions affecting a particular account and its
1595 subaccounts, with each line item representing a whole transaction - as
1596 in bank statements, hledger-ui, hledger-web and other accounting apps.
1597 Note this is unlike the register command, which shows individual post‐
1599 ings and does not always show a single account or a historical balance.
1600 A reminder, "historical" balances include any balance from transactions
1602 before the report start date, so (if opening balances are recorded cor‐
1603 rectly) aregister will show the real-world balances of an account, as
1604 you would see in a bank statement.
1605 As a quick rule of thumb, use aregister for reconciling real-world as‐
1607 set/liability accounts and register for reviewing detailed revenues/ex‐
1608 penses.
1609 aregister shows the register for just one account (and its subac‐
1611 counts). This account must be specified as the first argument. You
1612 can write either the full account name, or a case-insensitive regular
1613 expression which will select the alphabetically first matched account.
1614 (Eg if you have assets:aaa:checking and assets:bbb:checking accounts,
1615 hledger areg checking would select assets:aaa:checking.)
1616 Any additional arguments form a query which will filter the transac‐
1618 tions shown.
1619 Each aregister line item shows:
1621 • the transaction's date (or the relevant posting's date if different,
1623 see below)
1624 • the names of all the other account(s) involved in this transaction
1626 (probably abbreviated)
1627 • the total change to this account's balance from this transaction
1629 • the account's historical running balance after this transaction.
1631 Transactions making a net change of zero are not shown by default; add
1633 the -E/--empty flag to show them.
1634 aregister ignores a depth limit, so its final total will always match a
1636 balance report with similar arguments.
1637 This command also supports the output destination and output format op‐
1639 tions The output formats supported are txt, csv, and json.
1640 aregister and custom posting dates
1642 Transactions whose date is outside the report period can still be
1643 shown, if they have a posting to this account dated inside the report
1644 period. (And in this case it's the posting date that is shown.) This
1645 ensures that aregister can show an accurate historical running balance,
1646 matching the one shown by register -H with the same arguments.
1647 To filter strictly by transaction date instead, add the --txn-dates
1649 flag. If you use this flag and some of your postings have custom
1650 dates, it's probably best to assume the running balance is wrong.
1651 Examples:
1653 Show all transactions and historical running balance in the first ac‐
1655 count whose name contains "checking":
1656 $ hledger areg checking
1658 Show transactions and historical running balance in all asset accounts
1660 during july:
1661 $ hledger areg assets date:jul
1663 balance
1665 balance, bal
1666 Show accounts and their balances.
1667 balance is one of hledger's oldest and most versatile commands, for
1669 listing account balances, balance changes, values, value changes and
1670 more, during one time period or many. Generally it shows a table, with
1671 rows representing accounts, and columns representing periods.
1672 Note there are some higher-level variants of the balance command with
1674 convenient defaults, which can be simpler to use: balancesheet, bal‐
1675 ancesheetequity, cashflow and incomestatement. When you need more con‐
1676 trol, then use balance.
1677 balance features
1679 Here's a quick overview of the balance command's features, followed by
1680 more detailed descriptions and examples. Many of these work with the
1681 higher-level commands as well.
1682 balance can show..
1684 • accounts as a list (-l) or a tree (-t)
1686 • optionally depth-limited (-[1-9])
1688 • sorted by declaration order and name, or by amount
1690 ..and their..
1692 • balance changes (the default)
1694 • or actual and planned balance changes (--budget)
1696 • or value of balance changes (-V)
1698 • or change of balance values (--valuechange)
1700 ..in..
1702 • one time period (the whole journal period by default)
1704 • or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
1706 ..either..
1708 • per period (the default)
1710 • or accumulated since report start date (--cumulative)
1712 • or accumulated since account creation (--historical/-H)
1714 ..possibly converted to..
1716 • cost (--value=cost[,COMM]/--cost/-B)
1718 • or market value, as of transaction dates (--value=then[,COMM])
1720 • or at period ends (--value=end[,COMM])
1722 • or now (--value=now)
1724 • or at some other date (--value=YYYY-MM-DD)
1726 ..with..
1728 • totals (-T), averages (-A), percentages (-%), inverted sign (--in‐
1730 vert)
1731 • rows and columns swapped (--transpose)
1733 • another field used as account name (--pivot)
1735 • custom-formatted line items (single-period reports only) (--format)
1737 This command supports the output destination and output format options,
1739 with output formats txt, csv, json, and (multi-period reports only:)
1740 html. In txt output in a colour-supporting terminal, negative amounts
1741 are shown in red.
1742 Simple balance report
1744 With no arguments, balance shows a list of all accounts and their
1745 change of balance - ie, the sum of posting amounts, both inflows and
1746 outflows - during the entire period of the journal. For real-world ac‐
1747 counts, this should also match their end balance at the end of the
1748 journal period (more on this below).
1749 Accounts are sorted by declaration order if any, and then alphabeti‐
1751 cally by account name. For instance, using examples/sample.journal:
1752 $ hledger bal
1754 $1 assets:bank:saving
1755 $-2 assets:cash
1756 $1 expenses:food
1757 $1 expenses:supplies
1758 $-1 income:gifts
1759 $-1 income:salary
1760 $1 liabilities:debts
1761 --------------------
1762 0
1763 Accounts with a zero balance (and no non-zero subaccounts, in tree mode
1765 - see below) are hidden by default. Use -E/--empty to show them (re‐
1766 vealing assets:bank:checking here):
1767 $ hledger -f examples/sample.journal bal -E
1769 0 assets:bank:checking
1770 $1 assets:bank:saving
1771 $-2 assets:cash
1772 $1 expenses:food
1773 $1 expenses:supplies
1774 $-1 income:gifts
1775 $-1 income:salary
1776 $1 liabilities:debts
1777 --------------------
1778 0
1779 The total of the amounts displayed is shown as the last line, unless
1781 -N/--no-total is used.
1782 Filtered balance report
1784 You can show fewer accounts, a different time period, totals from
1785 cleared transactions only, etc. by using query arguments or options to
1786 limit the postings being matched. Eg:
1787 $ hledger bal --cleared assets date:200806
1789 $-2 assets:cash
1790 --------------------
1791 $-2
1792 List or tree mode
1794 By default, or with -l/--flat, accounts are shown as a flat list with
1795 their full names visible, as in the examples above.
1796 With -t/--tree, the account hierarchy is shown, with subaccounts'
1798 "leaf" names indented below their parent:
1799 $ hledger balance
1801 $-1 assets
1802 $1 bank:saving
1803 $-2 cash
1804 $2 expenses
1805 $1 food
1806 $1 supplies
1807 $-2 income
1808 $-1 gifts
1809 $-1 salary
1810 $1 liabilities:debts
1811 --------------------
1812 0
1813 Notes:
1815 • "Boring" accounts are combined with their subaccount for more compact
1817 output, unless --no-elide is used. Boring accounts have no balance
1818 of their own and just one subaccount (eg assets:bank and liabilities
1819 above).
1820 • All balances shown are "inclusive", ie including the balances from
1822 all subaccounts. Note this means some repetition in the output,
1823 which requires explanation when sharing reports with non-plaintextac‐
1824 counting-users. A tree mode report's final total is the sum of the
1825 top-level balances shown, not of all the balances shown.
1826 • Each group of sibling accounts (ie, under a common parent) is sorted
1828 separately.
1829 Depth limiting
1831 With a depth:N query, or --depth N option, or just -N, balance reports
1832 will show accounts only to the specified depth, hiding the deeper sub‐
1833 accounts. Account balances at the depth limit always include the bal‐
1834 ances from any hidden subaccounts (even in list mode). This can be
1835 useful for getting an overview. Eg, limiting to depth 1:
1836 $ hledger balance -N -1
1838 $-1 assets
1839 $2 expenses
1840 $-2 income
1841 $1 liabilities
1842 You can also hide top-level account name parts, using --drop N. This
1844 can be useful for hiding repetitive top-level account names:
1845 $ hledger bal expenses --drop 1
1847 $1 food
1848 $1 supplies
1849 --------------------
1850 $2
1851 Multi-period balance report
1853 With a report interval (set by the -D/--daily, -W/--weekly,
1854 -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), bal‐
1855 ance shows a tabular report, with columns representing successive time
1856 periods (and a title):
1857 $ hledger balance --quarterly income expenses -E
1859 Balance changes in 2008:
1860 || 2008q1 2008q2 2008q3 2008q4
1862 ===================++=================================
1863 expenses:food || 0 $1 0 0
1864 expenses:supplies || 0 $1 0 0
1865 income:gifts || 0 $-1 0 0
1866 income:salary || $-1 0 0 0
1867 -------------------++---------------------------------
1868 || $-1 $1 0 0
1869 Notes:
1871 • The report's start/end dates will be expanded, if necessary, to fully
1873 encompass the displayed subperiods (so that the first and last subpe‐
1874 riods have the same duration as the others).
1875 • Leading and trailing periods (columns) containing all zeroes are not
1877 shown, unless -E/--empty is used.
1878 • Accounts (rows) containing all zeroes are not shown, unless
1880 -E/--empty is used.
1881 • Amounts with many commodities are shown in abbreviated form, unless
1883 --no-elide is used. (experimental)
1884 • Average and/or total columns can be added with the -A/--average and
1886 -T/--row-total flags.
1887 • The --transpose flag can be used to exchange rows and columns.
1889 • The --pivot FIELD option causes a different transaction field to be
1891 used as "account name". See PIVOTING.
1892 Multi-period reports with many periods can be too wide for easy viewing
1894 in the terminal. Here are some ways to handle that:
1895 • Hide the totals row with -N/--no-total
1897 • Convert to a single currency with -V
1899 • Maximize the terminal window
1901 • Reduce the terminal's font size
1903 • View with a pager like less, eg: hledger bal -D --color=yes | less
1905 -RS
1906 • Output as CSV and use a CSV viewer like visidata (hledger bal -D -O
1908 csv | vd -f csv), Emacs' csv-mode (M-x csv-mode, C-c C-a), or a
1909 spreadsheet (hledger bal -D -o a.csv && open a.csv)
1910 • Output as HTML and view with a browser: hledger bal -D -o a.html &&
1912 open a.html
1913 Sorting by amount
1915 With -S/--sort-amount, accounts with the largest (most positive) bal‐
1916 ances are shown first. Eg: hledger bal expenses -MAS shows your big‐
1917 gest averaged monthly expenses first.
1918 Revenues and liability balances are typically negative, however, so -S
1920 shows these in reverse order. To work around this, you can add --in‐
1921 vert to flip the signs. (Or, use one of the higher-level reports,
1922 which flip the sign automatically. Eg: hledger incomestatement -MAS).
1923 Percentages
1925 With -%/--percent, balance reports show each account's value expressed
1926 as a percentage of the (column) total:
1927 $ hledger bal expenses -Q -%
1929 Balance changes in 2008:
1930 || 2008Q1 2008Q2 2008Q3 2008Q4
1932 ===================++=================================
1933 expenses:food || 0 50.0 % 0 0
1934 expenses:supplies || 0 50.0 % 0 0
1935 -------------------++---------------------------------
1936 || 0 100.0 % 0 0
1937 Note it is not useful to calculate percentages if the amounts in a col‐
1939 umn have mixed signs. In this case, make a separate report for each
1940 sign, eg:
1941 $ hledger bal -% amt:`>0`
1943 $ hledger bal -% amt:`<0`
1944 Similarly, if the amounts in a column have mixed commodities, convert
1946 them to one commodity with -B, -V, -X or --value, or make a separate
1947 report for each commodity:
1948 $ hledger bal -% cur:\\$
1950 $ hledger bal -% cur:€
1951 Balance change, end balance
1953 It's important to be clear on the meaning of the numbers shown in bal‐
1954 ance reports. Here is some terminology we use:
1955 A balance change is the net amount added to, or removed from, an ac‐
1957 count during some period.
1958 An end balance is the amount accumulated in an account as of some date
1960 (and some time, but hledger doesn't store that; assume end of day in
1961 your timezone). It is the sum of previous balance changes.
1962 We call it a historical end balance if it includes all balance changes
1964 since the account was created. For a real world account, this means it
1965 will match the "historical record", eg the balances reported in your
1966 bank statements or bank web UI. (If they are correct!)
1967 In general, balance changes are what you want to see when reviewing
1969 revenues and expenses, and historical end balances are what you want to
1970 see when reviewing or reconciling asset, liability and equity accounts.
1971 balance shows balance changes by default. To see accurate historical
1973 end balances:
1974 1. Initialise account starting balances with an "opening balances"
1976 transaction (a transfer from equity to the account), unless the
1977 journal covers the account's full lifetime.
1978 2. Include all of of the account's prior postings in the report, by not
1980 specifying a report start date, or by using the -H/--historical
1981 flag. (-H causes report start date to be ignored when summing post‐
1982 ings.)
1983 Balance report types
1985 For more flexible reporting, there are three important option groups:
1986 hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]
1988 ...
1989 The first two are the most important: calculation type selects the ba‐
1991 sic calculation to perform for each table cell, while accumulation type
1992 says which postings should be included in each cell's calculation.
1993 Typically one or both of these are selected by default, so you don't
1994 need to write them explicitly. A valuation type can be added if you
1995 want to convert the basic report to value or cost.
1996 Calculation type:
1998 The basic calculation to perform for each table cell. It is one of:
1999 • --sum : sum the posting amounts (default)
2001 • --budget : like --sum but also show a goal amount
2003 • --valuechange : show the change in period-end historical balance val‐
2005 ues
2006 Accumulation type:
2008 Which postings should be included in each cell's calculation. It is
2009 one of:
2010 • --change : postings from column start to column end, ie within the
2012 cell's period. Typically used to see revenues/expenses. (default
2013 for balance, incomestatement)
2014 • --cumulative : postings from report start to column end, eg to show
2016 changes accumulated since the report's start date. Rarely used.
2017 • --historical/-H : postings from journal start to column end, ie all
2019 postings from account creation to the end of the cell's period. Typ‐
2020 ically used to see historical end balances of assets/liabilities/eq‐
2021 uity. (default for balancesheet, balancesheetequity, cashflow)
2022 Valuation type:
2024 Which kind of valuation, valuation date(s) and optionally a target val‐
2025 uation commodity to use. It is one of:
2026 • no valuation, show amounts in their original commodities (default)
2028 • --value=cost[,COMM] : no valuation, show amounts converted to cost
2030 • --value=then[,COMM] : show value at transaction dates
2032 • --value=end[,COMM] : show value at period end date(s) (default with
2034 --valuechange)
2035 • --value=now[,COMM] : show value at today's date
2037 • --value=YYYY-MM-DD[,COMM] : show value at another date
2039 or one of their aliases: --cost/-B, --market/-V or --exchange/-X.
2041 Most combinations of these options should produce reasonable reports,
2043 but if you find any that seem wrong or misleading, let us know. The
2044 following restrictions are applied:
2045 • --valuechange implies --value=end
2047 • --valuechange makes --change the default when used with the bal‐
2049 ancesheet/balancesheetequity commands
2050 • --cumulative or --historical disables --row-total/-T
2052 For reference, here is what the combinations of accumulation and valua‐
2054 tion show:
2055 Valua‐ no valuation --value= then --value= end --value= YYYY-
2057 tion: MM-DD /now
2058 >Accumu‐
2059 lation:
2060 v
2061 ────────────────────────────────────────────────────────────────────────────────────
2062 --change change in period sum of posting- period-end DATE-value of
2063 date market val‐ value of change change in pe‐
2064 ues in period in period riod
2065 --cumu‐ change from re‐ sum of posting- period-end DATE-value of
2066 lative port start to date market val‐ value of change change from
2067 period end ues from report from report report start
2068 start to period start to period to period end
2069 end end
2070 --his‐ change from sum of posting- period-end DATE-value of
2071 torical journal start to date market val‐ value of change change from
2072 /-H period end (his‐ ues from journal from journal journal start
2073 torical end bal‐ start to period start to period to period end
2074 ance) end end
2075 Useful balance reports
2077 Some frequently used balance options/reports are:
2078 • bal -M revenues expenses
2080 Show revenues/expenses in each month. Also available as the incomes‐
2081 tatement command.
2082 • bal -M -H assets liabilities
2084 Show historical asset/liability balances at each month end. Also
2085 available as the balancesheet command.
2086 • bal -M -H assets liabilities equity
2088 Show historical asset/liability/equity balances at each month end.
2089 Also available as the balancesheetequity command.
2090 • bal -M assets not:receivable
2092 Show changes to liquid assets in each month. Also available as the
2093 cashflow command.
2094 Also:
2096 • bal -M expenses -2 -SA
2098 Show monthly expenses summarised to depth 2 and sorted by average
2099 amount.
2100 • bal -M --budget expenses
2102 Show monthly expenses and budget goals.
2103 • bal -M --valuechange investments
2105 Show monthly change in market value of investment assets.
2106 • bal investments --valuechange -D date:lastweek amt:'>1000' -STA
2108 [--invert]
2109 Show top gainers [or losers] last week
2110 Budget report
2112 The --budget report type activates extra columns showing any budget
2113 goals for each account and period. The budget goals are defined by pe‐
2114 riodic transactions. This is very useful for comparing planned and ac‐
2115 tual income, expenses, time usage, etc.
2116 For example, you can take average monthly expenses in the common ex‐
2118 pense categories to construct a minimal monthly budget:
2119 ;; Budget
2121 ~ monthly
2122 income $2000
2123 expenses:food $400
2124 expenses:bus $50
2125 expenses:movies $30
2126 assets:bank:checking
2127 ;; Two months worth of expenses
2129 2017-11-01
2130 income $1950
2131 expenses:food $396
2132 expenses:bus $49
2133 expenses:movies $30
2134 expenses:supplies $20
2135 assets:bank:checking
2136 2017-12-01
2138 income $2100
2139 expenses:food $412
2140 expenses:bus $53
2141 expenses:gifts $100
2142 assets:bank:checking
2143 You can now see a monthly budget report:
2145 $ hledger balance -M --budget
2147 Budget performance in 2017/11/01-2017/12/31:
2148 || Nov Dec
2150 ======================++====================================================
2151 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2152 assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2153 assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2154 expenses || $495 [ 103% of $480] $565 [ 118% of $480]
2155 expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
2156 expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
2157 expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
2158 income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
2159 ----------------------++----------------------------------------------------
2160 || 0 [ 0] 0 [ 0]
2161 This is different from a normal balance report in several ways:
2163 • Only accounts with budget goals during the report period are shown,
2165 by default.
2166 • In each column, in square brackets after the actual amount, budget
2168 goal amounts are shown, and the actual/goal percentage. (Note: bud‐
2169 get goals should be in the same commodity as the actual amount.)
2170 • All parent accounts are always shown, even in list mode. Eg assets,
2172 assets:bank, and expenses above.
2173 • Amounts always include all subaccounts, budgeted or unbudgeted, even
2175 in list mode.
2176 This means that the numbers displayed will not always add up! Eg above,
2178 the expenses actual amount includes the gifts and supplies transac‐
2179 tions, but the expenses:gifts and expenses:supplies accounts are not
2180 shown, as they have no budget amounts declared.
2181 This can be confusing. When you need to make things clearer, use the
2183 -E/--empty flag, which will reveal all accounts including unbudgeted
2184 ones, giving the full picture. Eg:
2185 $ hledger balance -M --budget --empty
2187 Budget performance in 2017/11/01-2017/12/31:
2188 || Nov Dec
2190 ======================++====================================================
2191 assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2192 assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2193 assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480]
2194 expenses || $495 [ 103% of $480] $565 [ 118% of $480]
2195 expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50]
2196 expenses:food || $396 [ 99% of $400] $412 [ 103% of $400]
2197 expenses:gifts || 0 $100
2198 expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30]
2199 expenses:supplies || $20 0
2200 income || $1950 [ 98% of $2000] $2100 [ 105% of $2000]
2201 ----------------------++----------------------------------------------------
2202 || 0 [ 0] 0 [ 0]
2203 You can roll over unspent budgets to next period with --cumulative:
2205 $ hledger balance -M --budget --cumulative
2207 Budget performance in 2017/11/01-2017/12/31:
2208 || Nov Dec
2210 ======================++====================================================
2211 assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
2212 assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
2213 assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960]
2214 expenses || $495 [ 103% of $480] $1060 [ 110% of $960]
2215 expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100]
2216 expenses:food || $396 [ 99% of $400] $808 [ 101% of $800]
2217 expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60]
2218 income || $1950 [ 98% of $2000] $4050 [ 101% of $4000]
2219 ----------------------++----------------------------------------------------
2220 || 0 [ 0] 0 [ 0]
2221 For more examples and notes, see Budgeting.
2223 Budget report start date
2225 This might be a bug, but for now: when making budget reports, it's a
2226 good idea to explicitly set the report's start date to the first day of
2227 a reporting period, because a periodic rule like ~ monthly generates
2228 its transactions on the 1st of each month, and if your journal has no
2229 regular transactions on the 1st, the default report start date could
2230 exclude that budget goal, which can be a little surprising. Eg here
2231 the default report period is just the day of 2020-01-15:
2232 ~ monthly in 2020
2234 (expenses:food) $500
2235 2020-01-15
2237 expenses:food $400
2238 assets:checking
2239 $ hledger bal expenses --budget
2241 Budget performance in 2020-01-15:
2242 || 2020-01-15
2244 ==============++============
2245 <unbudgeted> || $400
2246 --------------++------------
2247 || $400
2248 To avoid this, specify the budget report's period, or at least the
2250 start date, with -b/-e/-p/date:, to ensure it includes the budget goal
2251 transactions (periodic transactions) that you want. Eg, adding -b
2252 2020/1/1 to the above:
2253 $ hledger bal expenses --budget -b 2020/1/1
2255 Budget performance in 2020-01-01..2020-01-15:
2256 || 2020-01-01..2020-01-15
2258 ===============++========================
2259 expenses:food || $400 [80% of $500]
2260 ---------------++------------------------
2261 || $400 [80% of $500]
2262 Nested budgets
2264 You can add budgets to any account in your account hierarchy. If you
2265 have budgets on both parent account and some of its children, then bud‐
2266 get(s) of the child account(s) would be added to the budget of their
2267 parent, much like account balances behave.
2268 In the most simple case this means that once you add a budget to any
2270 account, all its parents would have budget as well.
2271 To illustrate this, consider the following budget:
2273 ~ monthly from 2019/01
2275 expenses:personal $1,000.00
2276 expenses:personal:electronics $100.00
2277 liabilities
2278 With this, monthly budget for electronics is defined to be $100 and
2280 budget for personal expenses is an additional $1000, which implicitly
2281 means that budget for both expenses:personal and expenses is $1100.
2282 Transactions in expenses:personal:electronics will be counted both to‐
2284 wards its $100 budget and $1100 of expenses:personal , and transactions
2285 in any other subaccount of expenses:personal would be counted towards
2286 only towards the budget of expenses:personal.
2287 For example, let's consider these transactions:
2289 ~ monthly from 2019/01
2291 expenses:personal $1,000.00
2292 expenses:personal:electronics $100.00
2293 liabilities
2294 2019/01/01 Google home hub
2296 expenses:personal:electronics $90.00
2297 liabilities $-90.00
2298 2019/01/02 Phone screen protector
2300 expenses:personal:electronics:upgrades $10.00
2301 liabilities
2302 2019/01/02 Weekly train ticket
2304 expenses:personal:train tickets $153.00
2305 liabilities
2306 2019/01/03 Flowers
2308 expenses:personal $30.00
2309 liabilities
2310 As you can see, we have transactions in expenses:personal:electron‐
2312 ics:upgrades and expenses:personal:train tickets, and since both of
2313 these accounts are without explicitly defined budget, these transac‐
2314 tions would be counted towards budgets of expenses:personal:electronics
2315 and expenses:personal accordingly:
2316 $ hledger balance --budget -M
2318 Budget performance in 2019/01:
2319 || Jan
2321 ===============================++===============================
2322 expenses || $283.00 [ 26% of $1100.00]
2323 expenses:personal || $283.00 [ 26% of $1100.00]
2324 expenses:personal:electronics || $100.00 [ 100% of $100.00]
2325 liabilities || $-283.00 [ 26% of $-1100.00]
2326 -------------------------------++-------------------------------
2327 || 0 [ 0]
2328 And with --empty, we can get a better picture of budget allocation and
2330 consumption:
2331 $ hledger balance --budget -M --empty
2333 Budget performance in 2019/01:
2334 || Jan
2336 ========================================++===============================
2337 expenses || $283.00 [ 26% of $1100.00]
2338 expenses:personal || $283.00 [ 26% of $1100.00]
2339 expenses:personal:electronics || $100.00 [ 100% of $100.00]
2340 expenses:personal:electronics:upgrades || $10.00
2341 expenses:personal:train tickets || $153.00
2342 liabilities || $-283.00 [ 26% of $-1100.00]
2343 ----------------------------------------++-------------------------------
2344 || 0 [ 0]
2345 Customising single-period balance reports
2347 For single-period balance reports displayed in the terminal (only), you
2348 can use --format FMT to customise the format and content of each line.
2349 Eg:
2350 $ hledger balance --format "%20(account) %12(total)"
2352 assets $-1
2353 bank:saving $1
2354 cash $-2
2355 expenses $2
2356 food $1
2357 supplies $1
2358 income $-2
2359 gifts $-1
2360 salary $-1
2361 liabilities:debts $1
2362 ---------------------------------
2363 0
2364 The FMT format string (plus a newline) specifies the formatting applied
2366 to each account/balance pair. It may contain any suitable text, with
2367 data fields interpolated like so:
2368 %[MIN][.MAX](FIELDNAME)
2370 • MIN pads with spaces to at least this width (optional)
2372 • MAX truncates at this width (optional)
2374 • FIELDNAME must be enclosed in parentheses, and can be one of:
2376 • depth_spacer - a number of spaces equal to the account's depth, or
2378 if MIN is specified, MIN * depth spaces.
2379 • account - the account's name
2381 • total - the account's balance/posted total, right justified
2383 Also, FMT can begin with an optional prefix to control how multi-com‐
2385 modity amounts are rendered:
2386 • %_ - render on multiple lines, bottom-aligned (the default)
2388 • %^ - render on multiple lines, top-aligned
2390 • %, - render on one line, comma-separated
2392 There are some quirks. Eg in one-line mode, %(depth_spacer) has no ef‐
2394 fect, instead %(account) has indentation built in. Experimentation may
2395 be needed to get pleasing results.
2396 Some example formats:
2398 • %(total) - the account's total
2400 • %-20.20(account) - the account's name, left justified, padded to 20
2402 characters and clipped at 20 characters
2403 • %,%-50(account) %25(total) - account name padded to 50 characters,
2405 total padded to 20 characters, with multiple commodities rendered on
2406 one line
2407 • %20(total) %2(depth_spacer)%-(account) - the default format for the
2409 single-column balance report
2410 balancesheet
2412 balancesheet, bs
2413 This command displays a balance sheet, showing historical ending bal‐
2414 ances of asset and liability accounts. (To see equity as well, use the
2415 balancesheetequity command.) Amounts are shown with normal positive
2416 sign, as in conventional financial statements.
2417 The asset and liability accounts shown are those accounts declared with
2419 the Asset or Cash or Liability type, or otherwise all accounts under a
2420 top-level asset or liability account (case insensitive, plurals al‐
2421 lowed).
2422 Example:
2424 $ hledger balancesheet
2426 Balance Sheet
2427 Assets:
2429 $-1 assets
2430 $1 bank:saving
2431 $-2 cash
2432 --------------------
2433 $-1
2434 Liabilities:
2436 $1 liabilities:debts
2437 --------------------
2438 $1
2439 Total:
2441 --------------------
2442 0
2443 This command is a higher-level variant of the balance command, and sup‐
2445 ports many of that command's features, such as multi-period reports.
2446 It is similar to hledger balance -H assets liabilities, but with
2447 smarter account detection, and liabilities displayed with their sign
2448 flipped.
2449 This command also supports the output destination and output format op‐
2451 tions The output formats supported are txt, csv, html, and (experimen‐
2452 tal) json.
2453 balancesheetequity
2455 balancesheetequity, bse
2456 This command displays a balance sheet, showing historical ending bal‐
2457 ances of asset, liability and equity accounts. Amounts are shown with
2458 normal positive sign, as in conventional financial statements.
2459 The asset, liability and equity accounts shown are those accounts de‐
2461 clared with the Asset, Cash, Liability or Equity type, or otherwise all
2462 accounts under a top-level asset, liability or equity account (case in‐
2463 sensitive, plurals allowed).
2464 Example:
2466 $ hledger balancesheetequity
2468 Balance Sheet With Equity
2469 Assets:
2471 $-2 assets
2472 $1 bank:saving
2473 $-3 cash
2474 --------------------
2475 $-2
2476 Liabilities:
2478 $1 liabilities:debts
2479 --------------------
2480 $1
2481 Equity:
2483 $1 equity:owner
2484 --------------------
2485 $1
2486 Total:
2488 --------------------
2489 0
2490 This command is a higher-level variant of the balance command, and sup‐
2492 ports many of that command's features, such as multi-period reports.
2493 It is similar to hledger balance -H assets liabilities equity, but with
2494 smarter account detection, and liabilities/equity displayed with their
2495 sign flipped.
2496 This command also supports the output destination and output format op‐
2498 tions The output formats supported are txt, csv, html, and (experimen‐
2499 tal) json.
2500 cashflow
2502 cashflow, cf
2503 This command displays a cashflow statement, showing the inflows and
2504 outflows affecting "cash" (ie, liquid) assets. Amounts are shown with
2505 normal positive sign, as in conventional financial statements.
2506 The "cash" accounts shown are those accounts declared with the Cash
2508 type, or otherwise all accounts under a top-level asset account (case
2509 insensitive, plural allowed) which do not have fixed, investment, re‐
2510 ceivable or A/R in their name.
2511 Example:
2513 $ hledger cashflow
2515 Cashflow Statement
2516 Cash flows:
2518 $-1 assets
2519 $1 bank:saving
2520 $-2 cash
2521 --------------------
2522 $-1
2523 Total:
2525 --------------------
2526 $-1
2527 This command is a higher-level variant of the balance command, and sup‐
2529 ports many of that command's features, such as multi-period reports.
2530 It is similar to hledger balance assets not:fixed not:investment
2531 not:receivable, but with smarter account detection.
2532 This command also supports the output destination and output format op‐
2534 tions The output formats supported are txt, csv, html, and (experimen‐
2535 tal) json.
2536 check
2538 check
2539 Check for various kinds of errors in your data.
2540 hledger provides a number of built-in error checks to help prevent
2542 problems in your data. Some of these are run automatically; or, you
2543 can use this check command to run them on demand, with no output and a
2544 zero exit code if all is well. Specify their names (or a prefix) as
2545 argument(s).
2546 Some examples:
2548 hledger check # basic checks
2550 hledger check -s # basic + strict checks
2551 hledger check ordereddates payees # basic + two other checks
2552 Here are the checks currently available:
2554 Basic checks
2556 These checks are always run automatically, by (almost) all hledger com‐
2557 mands, including check:
2558 • parseable - data files are well-formed and can be successfully parsed
2560 • autobalanced - all transactions are balanced, inferring missing
2562 amounts where necessary, and possibly converting commodities using
2563 transaction prices or automatically-inferred transaction prices
2564 • assertions - all balance assertions in the journal are passing.
2566 (This check can be disabled with -I/--ignore-assertions.)
2567 Strict checks
2569 These additional checks are run when the -s/--strict (strict mode) flag
2570 is used. Or, they can be run by giving their names as arguments to
2571 check:
2572 • accounts - all account names used by transactions have been declared
2574 • commodities - all commodity symbols used have been declared
2576 Other checks
2578 These checks can be run only by giving their names as arguments to
2579 check. They are more specialised and not desirable for everyone,
2580 therefore optional:
2581 • ordereddates - transactions are ordered by date in each file
2583 • payees - all payees used by transactions have been declared
2585 • uniqueleafnames - all account leaf names are unique
2587 Custom checks
2589 A few more checks are are available as separate add-on commands, in
2590 https://github.com/simonmichael/hledger/tree/master/bin:
2591 • hledger-check-tagfiles - all tag values containing / (a forward
2593 slash) exist as file paths
2594 • hledger-check-fancyassertions - more complex balance assertions are
2596 passing
2597 You could make similar scripts to perform your own custom checks. See:
2599 Cookbook -> Scripting.
2600 close
2602 close, equity
2603 Prints a "closing balances" transaction and an "opening balances"
2604 transaction that bring account balances to and from zero, respectively.
2605 These can be added to your journal file(s), eg to bring asset/liability
2606 balances forward into a new journal file, or to close out revenues/ex‐
2607 penses to retained earnings at the end of a period.
2608 You can print just one of these transactions by using the --close or
2610 --open flag. You can customise their descriptions with the --close-
2611 desc and --open-desc options.
2612 One amountless posting to "equity:opening/closing balances" is added to
2614 balance the transactions, by default. You can customise this account
2615 name with --close-acct and --open-acct; if you specify only one of
2616 these, it will be used for both.
2617 With --x/--explicit, the equity posting's amount will be shown. And if
2619 it involves multiple commodities, a posting for each commodity will be
2620 shown, as with the print command.
2621 With --interleaved, the equity postings are shown next to the postings
2623 they balance, which makes troubleshooting easier.
2624 By default, transaction prices in the journal are ignored when generat‐
2626 ing the closing/opening transactions. With --show-costs, this cost in‐
2627 formation is preserved (balance -B reports will be unchanged after the
2628 transition). Separate postings are generated for each cost in each
2629 commodity. Note this can generate very large journal entries, if you
2630 have many foreign currency or investment transactions.
2631 close usage
2633 If you split your journal files by time (eg yearly), you will typically
2634 run this command at the end of the year, and save the closing transac‐
2635 tion as last entry of the old file, and the opening transaction as the
2636 first entry of the new file. This makes the files self contained, so
2637 that correct balances are reported no matter which of them are loaded.
2638 Ie, if you load just one file, the balances are initialised correctly;
2639 or if you load several files, the redundant closing/opening transac‐
2640 tions cancel each other out. (They will show up in print or register
2641 reports; you can exclude them with a query like not:desc:'(open‐
2642 ing|closing) balances'.)
2643 If you're running a business, you might also use this command to "close
2645 the books" at the end of an accounting period, transferring income
2646 statement account balances to retained earnings. (You may want to
2647 change the equity account name to something like "equity:retained earn‐
2648 ings".)
2649 By default, the closing transaction is dated yesterday, the balances
2651 are calculated as of end of yesterday, and the opening transaction is
2652 dated today. To close on some other date, use: hledger close -e OPEN‐
2653 INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019.
2654 You can also use -p or date:PERIOD (any starting date is ignored).
2655 Both transactions will include balance assertions for the closed/re‐
2657 opened accounts. You probably shouldn't use status or realness filters
2658 (like -C or -R or status:) with this command, or the generated balance
2659 assertions will depend on these flags. Likewise, if you run this com‐
2660 mand with --auto, the balance assertions will probably always require
2661 --auto.
2662 Examples:
2664 Carrying asset/liability balances into a new file for 2019:
2666 $ hledger close -f 2018.journal -e 2019 assets liabilities --open
2668 # (copy/paste the output to the start of your 2019 journal file)
2669 $ hledger close -f 2018.journal -e 2019 assets liabilities --close
2670 # (copy/paste the output to the end of your 2018 journal file)
2671 Now:
2673 $ hledger bs -f 2019.journal # one file - balances are correct
2675 $ hledger bs -f 2018.journal -f 2019.journal # two files - balances still correct
2676 $ hledger bs -f 2018.journal not:desc:closing # to see year-end balances, must exclude closing txn
2677 Transactions spanning the closing date can complicate matters, breaking
2679 balance assertions:
2680 2018/12/30 a purchase made in 2018, clearing the following year
2682 expenses:food 5
2683 assets:bank:checking -5 ; [2019/1/2]
2684 Here's one way to resolve that:
2686 ; in 2018.journal:
2688 2018/12/30 a purchase made in 2018, clearing the following year
2689 expenses:food 5
2690 liabilities:pending
2691 ; in 2019.journal:
2693 2019/1/2 clearance of last year's pending transactions
2694 liabilities:pending 5 = 0
2695 assets:checking
2696 codes
2698 codes
2699 List the codes seen in transactions, in the order parsed.
2700 This command prints the value of each transaction's code field, in the
2702 order transactions were parsed. The transaction code is an optional
2703 value written in parentheses between the date and description, often
2704 used to store a cheque number, order number or similar.
2705 Transactions aren't required to have a code, and missing or empty codes
2707 will not be shown by default. With the -E/--empty flag, they will be
2708 printed as blank lines.
2709 You can add a query to select a subset of transactions.
2711 Examples:
2713 1/1 (123)
2715 (a) 1
2716 1/1 ()
2718 (a) 1
2719 1/1
2721 (a) 1
2722 1/1 (126)
2724 (a) 1
2725 $ hledger codes
2727 123
2728 124
2729 126
2730 $ hledger codes -E
2732 123
2733 124
2734 126
2737 commodities
2739 commodities
2740 List all commodity/currency symbols used or declared in the journal.
2741 descriptions
2743 descriptions
2744 List the unique descriptions that appear in transactions.
2745 This command lists the unique descriptions that appear in transactions,
2747 in alphabetic order. You can add a query to select a subset of trans‐
2748 actions.
2749 Example:
2751 $ hledger descriptions
2753 Store Name
2754 Gas Station | Petrol
2755 Person A
2756 diff
2758 diff
2759 Compares a particular account's transactions in two input files. It
2760 shows any transactions to this account which are in one file but not in
2761 the other.
2762 More precisely, for each posting affecting this account in either file,
2764 it looks for a corresponding posting in the other file which posts the
2765 same amount to the same account (ignoring date, description, etc.)
2766 Since postings not transactions are compared, this also works when mul‐
2767 tiple bank transactions have been combined into a single journal entry.
2768 This is useful eg if you have downloaded an account's transactions from
2770 your bank (eg as CSV data). When hledger and your bank disagree about
2771 the account balance, you can compare the bank data with your journal to
2772 find out the cause.
2773 Examples:
2775 $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro
2777 These transactions are in the first file only:
2778 2014/01/01 Opening Balances
2780 assets:bank:giro EUR ...
2781 ...
2782 equity:opening balances EUR -...
2783 These transactions are in the second file only:
2785 files
2787 files
2788 List all files included in the journal. With a REGEX argument, only
2789 file names matching the regular expression (case sensitive) are shown.
2790 help
2792 help
2793 Show the hledger user manual in one of several formats, optionally po‐
2794 sitioned at a given TOPIC (if possible). TOPIC is any heading, or
2795 heading prefix, in the manual. Some examples: commands, print, 'auto
2796 postings', periodic.
2797 This command shows the user manual built in to this hledger version.
2799 It can be useful if the correct version of the hledger manual, or the
2800 usual viewing tools, are not installed on your system.
2801 By default it uses the best viewer it can find in $PATH, in this order:
2803 info, man, $PAGER (unless a topic is specified), less, or stdout. When
2804 run non-interactively, it always uses stdout. Or you can select a par‐
2805 ticular viewer with the -i (info), -m (man), or -p (pager) flags.
2806 import
2808 import
2809 Read new transactions added to each FILE since last run, and add them
2810 to the main journal file. Or with --dry-run, just print the transac‐
2811 tions that would be added. Or with --catchup, just mark all of the
2812 FILEs' transactions as imported, without actually importing any.
2813 Unlike other hledger commands, with import the journal file is an out‐
2815 put file, and will be modified, though only by appending (existing data
2816 will not be changed). The input files are specified as arguments, so
2817 to import one or more CSV files to your main journal, you will run
2818 hledger import bank.csv or perhaps hledger import *.csv.
2819 Note you can import from any file format, though CSV files are the most
2821 common import source, and these docs focus on that case.
2822 Deduplication
2824 As a convenience import does deduplication while reading transactions.
2825 This does not mean "ignore transactions that look the same", but rather
2826 "ignore transactions that have been seen before". This is intended for
2827 when you are periodically importing foreign data which may contain al‐
2828 ready-imported transactions. So eg, if every day you download bank CSV
2829 files containing redundant data, you can safely run hledger import
2830 bank.csv and only new transactions will be imported. (import is idem‐
2831 potent.)
2832 Since the items being read (CSV records, eg) often do not come with
2834 unique identifiers, hledger detects new transactions by date, assuming
2835 that:
2836 1. new items always have the newest dates
2838 2. item dates do not change across reads
2840 3. and items with the same date remain in the same relative order
2842 across reads.
2843 These are often true of CSV files representing transactions, or true
2845 enough so that it works pretty well in practice. 1 is important, but
2846 violations of 2 and 3 amongst the old transactions won't matter (and if
2847 you import often, the new transactions will be few, so less likely to
2848 be the ones affected).
2849 hledger remembers the latest date processed in each input file by sav‐
2851 ing a hidden ".latest" state file in the same directory. Eg when read‐
2852 ing finance/bank.csv, it will look for and update the finance/.lat‐
2853 est.bank.csv state file. The format is simple: one or more lines con‐
2854 taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro‐
2855 cessed transactions up to this date, and this many of them on that
2856 date." Normally you won't see or manipulate these state files yourself.
2857 But if needed, you can delete them to reset the state (making all
2858 transactions "new"), or you can construct them to "catch up" to a cer‐
2859 tain date.
2860 Note deduplication (and updating of state files) can also be done by
2862 print --new, but this is less often used.
2863 Import testing
2865 With --dry-run, the transactions that will be imported are printed to
2866 the terminal, without updating your journal or state files. The output
2867 is valid journal format, like the print command, so you can re-parse
2868 it. Eg, to see any importable transactions which CSV rules have not
2869 categorised:
2870 $ hledger import --dry bank.csv | hledger -f- -I print unknown
2872 or (live updating):
2874 $ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'
2876 Importing balance assignments
2878 Entries added by import will have their posting amounts made explicit
2879 (like hledger print -x). This means that any balance assignments in
2880 imported files must be evaluated; but, imported files don't get to see
2881 the main file's account balances. As a result, importing entries with
2882 balance assignments (eg from an institution that provides only balances
2883 and not posting amounts) will probably generate incorrect posting
2884 amounts. To avoid this problem, use print instead of import:
2885 $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
2887 (If you think import should leave amounts implicit like print does,
2889 please test it and send a pull request.)
2890 Commodity display styles
2892 Imported amounts will be formatted according to the canonical commodity
2893 styles (declared or inferred) in the main journal file.
2894 incomestatement
2896 incomestatement, is
2897 This command displays an income statement, showing revenues and ex‐
2898 penses during one or more periods. Amounts are shown with normal posi‐
2899 tive sign, as in conventional financial statements.
2900 The revenue and expense accounts shown are those accounts declared with
2902 the Revenue or Expense type, or otherwise all accounts under a top-
2903 level revenue or income or expense account (case insensitive, plurals
2904 allowed).
2905 Example:
2907 $ hledger incomestatement
2909 Income Statement
2910 Revenues:
2912 $-2 income
2913 $-1 gifts
2914 $-1 salary
2915 --------------------
2916 $-2
2917 Expenses:
2919 $2 expenses
2920 $1 food
2921 $1 supplies
2922 --------------------
2923 $2
2924 Total:
2926 --------------------
2927 0
2928 This command is a higher-level variant of the balance command, and sup‐
2930 ports many of that command's features, such as multi-period reports.
2931 It is similar to hledger balance '(revenues|income)' expenses, but with
2932 smarter account detection, and revenues/income displayed with their
2933 sign flipped.
2934 This command also supports the output destination and output format op‐
2936 tions The output formats supported are txt, csv, html, and (experimen‐
2937 tal) json.
2938 notes
2940 notes
2941 List the unique notes that appear in transactions.
2942 This command lists the unique notes that appear in transactions, in al‐
2944 phabetic order. You can add a query to select a subset of transac‐
2945 tions. The note is the part of the transaction description after a |
2946 character (or if there is no |, the whole description).
2947 Example:
2949 $ hledger notes
2951 Petrol
2952 Snacks
2953 payees
2955 payees
2956 List the unique payee/payer names that appear in transactions.
2957 This command lists unique payee/payer names which have been declared
2959 with payee directives (--declared), used in transaction descriptions
2960 (--used), or both (the default).
2961 The payee/payer is the part of the transaction description before a |
2963 character (or if there is no |, the whole description).
2964 You can add query arguments to select a subset of transactions. This
2966 implies --used.
2967 Example:
2969 $ hledger payees
2971 Store Name
2972 Gas Station
2973 Person A
2974 prices
2976 prices
2977 Print market price directives from the journal. With --costs, also
2978 print synthetic market prices based on transaction prices. With --in‐
2979 verted-costs, also print inverse prices based on transaction prices.
2980 Prices (and postings providing prices) can be filtered by a query.
2981 Price amounts are always displayed with their full precision.
2982 print
2984 print
2985 Show transaction journal entries, sorted by date.
2986 The print command displays full journal entries (transactions) from the
2988 journal file, sorted by date (or with --date2, by secondary date).
2989 Amounts are shown mostly normalised to commodity display style, eg the
2991 placement of commodity symbols will be consistent. All of their deci‐
2992 mal places are shown, as in the original journal entry (with one alter‐
2993 ation: in some cases trailing zeroes are added.)
2994 Amounts are shown right-aligned within each transaction (but not across
2996 all transactions).
2997 Directives and inter-transaction comments are not shown, currently.
2999 This means the print command is somewhat lossy, and if you are using it
3000 to reformat your journal you should take care to also copy over the di‐
3001 rectives and file-level comments.
3002 Eg:
3004 $ hledger print
3006 2008/01/01 income
3007 assets:bank:checking $1
3008 income:salary $-1
3009 2008/06/01 gift
3011 assets:bank:checking $1
3012 income:gifts $-1
3013 2008/06/02 save
3015 assets:bank:saving $1
3016 assets:bank:checking $-1
3017 2008/06/03 * eat & shop
3019 expenses:food $1
3020 expenses:supplies $1
3021 assets:cash $-2
3022 2008/12/31 * pay off
3024 liabilities:debts $1
3025 assets:bank:checking $-1
3026 print's output is usually a valid hledger journal, and you can process
3028 it again with a second hledger command. This can be useful for certain
3029 kinds of search, eg:
3030 # Show running total of food expenses paid from cash.
3032 # -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
3033 $ hledger print assets:cash | hledger -f- -I reg expenses:food
3034 There are some situations where print's output can become unparseable:
3036 • Valuation affects posting amounts but not balance assertion or bal‐
3038 ance assignment amounts, potentially causing those to fail.
3039 • Auto postings can generate postings with too many missing amounts.
3041 Normally, the journal entry's explicit or implicit amount style is pre‐
3043 served. For example, when an amount is omitted in the journal, it will
3044 not appear in the output. Similarly, when a transaction price is im‐
3045 plied but not written, it will not appear in the output. You can use
3046 the -x/--explicit flag to make all amounts and transaction prices ex‐
3047 plicit, which can be useful for troubleshooting or for making your
3048 journal more readable and robust against data entry errors. -x is also
3049 implied by using any of -B,-V,-X,--value.
3050 Note, -x/--explicit will cause postings with a multi-commodity amount
3052 (these can arise when a multi-commodity transaction has an implicit
3053 amount) to be split into multiple single-commodity postings, keeping
3054 the output parseable.
3055 With -B/--cost, amounts with transaction prices are converted to cost
3057 using that price. This can be used for troubleshooting.
3058 With -m/--match and a STR argument, print will show at most one trans‐
3060 action: the one one whose description is most similar to STR, and is
3061 most recent. STR should contain at least two characters. If there is
3062 no similar-enough match, no transaction will be shown.
3063 With --new, hledger prints only transactions it has not seen on a pre‐
3065 vious run. This uses the same deduplication system as the import com‐
3066 mand. (See import's docs for details.)
3067 This command also supports the output destination and output format op‐
3069 tions The output formats supported are txt, csv, and (experimental)
3070 json and sql.
3071 Here's an example of print's CSV output:
3073 $ hledger print -Ocsv
3075 "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
3076 "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
3077 "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
3078 "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
3079 "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
3080 "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
3081 "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
3082 "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
3083 "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
3084 "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
3085 "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
3086 "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
3087 • There is one CSV record per posting, with the parent transaction's
3089 fields repeated.
3090 • The "txnidx" (transaction index) field shows which postings belong to
3092 the same transaction. (This number might change if transactions are
3093 reordered within the file, files are parsed/included in a different
3094 order, etc.)
3095 • The amount is separated into "commodity" (the symbol) and "amount"
3097 (numeric quantity) fields.
3098 • The numeric amount is repeated in either the "credit" or "debit" col‐
3100 umn, for convenience. (Those names are not accurate in the account‐
3101 ing sense; it just puts negative amounts under credit and zero or
3102 greater amounts under debit.)
3103 print-unique
3105 print-unique
3106 Print transactions which do not reuse an already-seen description.
3107 Example:
3109 $ cat unique.journal
3111 1/1 test
3112 (acct:one) 1
3113 2/2 test
3114 (acct:two) 2
3115 $ LEDGER_FILE=unique.journal hledger print-unique
3116 (-f option not supported)
3117 2015/01/01 test
3118 (acct:one) 1
3119 register
3121 register, reg
3122 Show postings and their running total.
3123 The register command displays matched postings, across all accounts, in
3125 date order, with their running total or running historical balance.
3126 (See also the aregister command, which shows matched transactions in a
3127 specific account.)
3128 register normally shows line per posting, but note that multi-commodity
3130 amounts will occupy multiple lines (one line per commodity).
3131 It is typically used with a query selecting a particular account, to
3133 see that account's activity:
3134 $ hledger register checking
3136 2008/01/01 income assets:bank:checking $1 $1
3137 2008/06/01 gift assets:bank:checking $1 $2
3138 2008/06/02 save assets:bank:checking $-1 $1
3139 2008/12/31 pay off assets:bank:checking $-1 0
3140 With --date2, it shows and sorts by secondary date instead.
3142 The --historical/-H flag adds the balance from any undisplayed prior
3144 postings to the running total. This is useful when you want to see
3145 only recent activity, with a historically accurate running balance:
3146 $ hledger register checking -b 2008/6 --historical
3148 2008/06/01 gift assets:bank:checking $1 $2
3149 2008/06/02 save assets:bank:checking $-1 $1
3150 2008/12/31 pay off assets:bank:checking $-1 0
3151 The --depth option limits the amount of sub-account detail displayed.
3153 The --average/-A flag shows the running average posting amount instead
3155 of the running total (so, the final number displayed is the average for
3156 the whole report period). This flag implies --empty (see below). It
3157 is affected by --historical. It works best when showing just one ac‐
3158 count and one commodity.
3159 The --related/-r flag shows the other postings in the transactions of
3161 the postings which would normally be shown.
3162 The --invert flag negates all amounts. For example, it can be used on
3164 an income account where amounts are normally displayed as negative num‐
3165 bers. It's also useful to show postings on the checking account to‐
3166 gether with the related account:
3167 $ hledger register --related --invert assets:checking
3169 With a reporting interval, register shows summary postings, one per in‐
3171 terval, aggregating the postings to each account:
3172 $ hledger register --monthly income
3174 2008/01 income:salary $-1 $-1
3175 2008/06 income:gifts $-1 $-2
3176 Periods with no activity, and summary postings with a zero amount, are
3178 not shown by default; use the --empty/-E flag to see them:
3179 $ hledger register --monthly income -E
3181 2008/01 income:salary $-1 $-1
3182 2008/02 0 $-1
3183 2008/03 0 $-1
3184 2008/04 0 $-1
3185 2008/05 0 $-1
3186 2008/06 income:gifts $-1 $-2
3187 2008/07 0 $-2
3188 2008/08 0 $-2
3189 2008/09 0 $-2
3190 2008/10 0 $-2
3191 2008/11 0 $-2
3192 2008/12 0 $-2
3193 Often, you'll want to see just one line per interval. The --depth op‐
3195 tion helps with this, causing subaccounts to be aggregated:
3196 $ hledger register --monthly assets --depth 1h
3198 2008/01 assets $1 $1
3199 2008/06 assets $-1 0
3200 2008/12 assets $-1 $-1
3201 Note when using report intervals, if you specify start/end dates these
3203 will be adjusted outward if necessary to contain a whole number of in‐
3204 tervals. This ensures that the first and last intervals are full
3205 length and comparable to the others in the report.
3206 Custom register output
3208 register uses the full terminal width by default, except on windows.
3209 You can override this by setting the COLUMNS environment variable (not
3210 a bash shell variable) or by using the --width/-w option.
3211 The description and account columns normally share the space equally
3213 (about half of (width - 40) each). You can adjust this by adding a de‐
3214 scription width as part of --width's argument, comma-separated: --width
3215 W,D . Here's a diagram (won't display correctly in --help):
3216 <--------------------------------- width (W) ---------------------------------->
3218 date (10) description (D) account (W-41-D) amount (12) balance (12)
3219 DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA
3220 and some examples:
3222 $ hledger reg # use terminal width (or 80 on windows)
3224 $ hledger reg -w 100 # use width 100
3225 $ COLUMNS=100 hledger reg # set with one-time environment variable
3226 $ export COLUMNS=100; hledger reg # set till session end (or window resize)
3227 $ hledger reg -w 100,40 # set overall width 100, description width 40
3228 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
3229 This command also supports the output destination and output format op‐
3231 tions The output formats supported are txt, csv, and (experimental)
3232 json.
3233 register-match
3235 register-match
3236 Print the one posting whose transaction description is closest to DESC,
3237 in the style of the register command. If there are multiple equally
3238 good matches, it shows the most recent. Query options (options, not
3239 arguments) can be used to restrict the search space. Helps ledger-au‐
3240 tosync detect already-seen transactions when importing.
3241 rewrite
3243 rewrite
3244 Print all transactions, rewriting the postings of matched transactions.
3245 For now the only rewrite available is adding new postings, like print
3246 --auto.
3247 This is a start at a generic rewriter of transaction entries. It reads
3249 the default journal and prints the transactions, like print, but adds
3250 one or more specified postings to any transactions matching QUERY. The
3251 posting amounts can be fixed, or a multiplier of the existing transac‐
3252 tion's first posting amount.
3253 Examples:
3255 $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
3257 $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
3258 $ hledger-rewrite.hs -f rewrites.hledger
3259 rewrites.hledger may consist of entries like:
3261 = ^income amt:<0 date:2017
3263 (liabilities:tax) *0.33 ; tax on income
3264 (reserve:grocery) *0.25 ; reserve 25% for grocery
3265 (reserve:) *0.25 ; reserve 25% for grocery
3266 Note the single quotes to protect the dollar sign from bash, and the
3268 two spaces between account and amount.
3269 More:
3271 $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...
3273 $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'
3274 $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'
3275 $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'
3276 Argument for --add-posting option is a usual posting of transaction
3278 with an exception for amount specification. More precisely, you can
3279 use '*' (star symbol) before the amount to indicate that that this is a
3280 factor for an amount of original matched posting. If the amount in‐
3281 cludes a commodity name, the new posting amount will be in the new com‐
3282 modity; otherwise, it will be in the matched posting amount's commod‐
3283 ity.
3284 Re-write rules in a file
3286 During the run this tool will execute so called "Automated Transac‐
3287 tions" found in any journal it process. I.e instead of specifying this
3288 operations in command line you can put them in a journal file.
3289 $ rewrite-rules.journal
3291 Make contents look like this:
3293 = ^income
3295 (liabilities:tax) *.33
3296 = expenses:gifts
3298 budget:gifts *-1
3299 assets:budget *1
3300 Note that '=' (equality symbol) that is used instead of date in trans‐
3302 actions you usually write. It indicates the query by which you want to
3303 match the posting to add new ones.
3304 $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
3306 This is something similar to the commands pipeline:
3308 $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \
3310 | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \
3311 --add-posting 'assets:budget *1' \
3312 > rewritten-tidy-output.journal
3313 It is important to understand that relative order of such entries in
3315 journal is important. You can re-use result of previously added post‐
3316 ings.
3317 Diff output format
3319 To use this tool for batch modification of your journal files you may
3320 find useful output in form of unified diff.
3321 $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'
3323 Output might look like:
3325 --- /tmp/examples/sample.journal
3327 +++ /tmp/examples/sample.journal
3328 @@ -18,3 +18,4 @@
3329 2008/01/01 income
3330 - assets:bank:checking $1
3331 + assets:bank:checking $1
3332 income:salary
3333 + (liabilities:tax) 0
3334 @@ -22,3 +23,4 @@
3335 2008/06/01 gift
3336 - assets:bank:checking $1
3337 + assets:bank:checking $1
3338 income:gifts
3339 + (liabilities:tax) 0
3340 If you'll pass this through patch tool you'll get transactions contain‐
3342 ing the posting that matches your query be updated. Note that multiple
3343 files might be update according to list of input files specified via
3344 --file options and include directives inside of these files.
3345 Be careful. Whole transaction being re-formatted in a style of output
3347 from hledger print.
3348 See also:
3350 https://github.com/simonmichael/hledger/issues/99
3352 rewrite vs. print --auto
3354 This command predates print --auto, and currently does much the same
3355 thing, but with these differences:
3356 • with multiple files, rewrite lets rules in any file affect all other
3358 files. print --auto uses standard directive scoping; rules affect
3359 only child files.
3360 • rewrite's query limits which transactions can be rewritten; all are
3362 printed. print --auto's query limits which transactions are printed.
3363 • rewrite applies rules specified on command line or in the journal.
3365 print --auto applies rules specified in the journal.
3366 roi
3368 roi
3369 Shows the time-weighted (TWR) and money-weighted (IRR) rate of return
3370 on your investments.
3371 At a minimum, you need to supply a query (which could be just an ac‐
3373 count name) to select your investment(s) with --inv, and another query
3374 to identify your profit and loss transactions with --pnl.
3375 If you do not record changes in the value of your investment manually,
3377 or do not require computation of time-weighted return (TWR), --pnl
3378 could be an empty query (--pnl "" or --pnl STR where STR does not match
3379 any of your accounts).
3380 This command will compute and display the internalized rate of return
3382 (IRR) and time-weighted rate of return (TWR) for your investments for
3383 the time period requested. Both rates of return are annualized before
3384 display, regardless of the length of reporting interval.
3385 Price directives will be taken into account if you supply appropriate
3387 --cost or --value flags (see VALUATION).
3388 Note, in some cases this report can fail, for these reasons:
3390 • Error (NotBracketed): No solution for Internal Rate of Return (IRR).
3392 Possible causes: IRR is huge (>1000000%), balance of investment be‐
3393 comes negative at some point in time.
3394 • Error (SearchFailed): Failed to find solution for Internal Rate of
3396 Return (IRR). Either search does not converge to a solution, or con‐
3397 verges too slowly.
3398 Examples:
3400 • Using roi to compute total return of investment in stocks:
3402 https://github.com/simonmichael/hledger/blob/master/examples/roi-un‐
3403 realised.ledger
3404 • Cookbook -> Return on Investment
3406 Semantics of --inv and --pnl
3408 Query supplied to --inv has to match all transactions that are related
3409 to your investment. Transactions not matching --inv will be ignored.
3410 In these transactions, ROI will conside postings that match --inv to be
3412 "investment postings" and other postings (not matching --inv) will be
3413 sorted into two categories: "cash flow" and "profit and loss", as ROI
3414 needs to know which part of the investment value is your contributions
3415 and which is due to the return on investment.
3416 • "Cash flow" is depositing or withdrawing money, buying or selling as‐
3418 sets, or otherwise converting between your investment commodity and
3419 any other commodity. Example:
3420 2019-01-01 Investing in Snake Oil
3422 assets:cash -$100
3423 investment:snake oil
3424 2020-01-01 Selling my Snake Oil
3426 assets:cash $10
3427 investment:snake oil = 0
3428 • "Profit and loss" is change in the value of your investment:
3430 2019-06-01 Snake Oil falls in value
3432 investment:snake oil = $57
3433 equity:unrealized profit or loss
3434 All non-investment postings are assumed to be "cash flow", unless they
3436 match --pnl query. Changes in value of your investment due to "profit
3437 and loss" postings will be considered as part of your investment re‐
3438 turn.
3439 Example: if you use --inv snake --pnl equity:unrealized, then postings
3441 in the example below would be classifed as:
3442 2019-01-01 Snake Oil #1
3444 assets:cash -$100 ; cash flow posting
3445 investment:snake oil ; investment posting
3446 2019-03-01 Snake Oil #2
3448 equity:unrealized pnl -$100 ; profit and loss posting
3449 snake oil ; investment posting
3450 2019-07-01 Snake Oil #3
3452 equity:unrealized pnl ; profit and loss posting
3453 cash -$100 ; cash flow posting
3454 snake oil $50 ; investment posting
3455 IRR and TWR explained
3457 "ROI" stands for "return on investment". Traditionally this was com‐
3458 puted as a difference between current value of investment and its ini‐
3459 tial value, expressed in percentage of the initial value.
3460 However, this approach is only practical in simple cases, where invest‐
3462 ments receives no in-flows or out-flows of money, and where rate of
3463 growth is fixed over time. For more complex scenarios you need differ‐
3464 ent ways to compute rate of return, and this command implements two of
3465 them: IRR and TWR.
3466 Internal rate of return, or "IRR" (also called "money-weighted rate of
3468 return") takes into account effects of in-flows and out-flows.
3469 Naively, if you are withdrawing from your investment, your future gains
3470 would be smaller (in absolute numbers), and will be a smaller percent‐
3471 age of your initial investment, and if you are adding to your invest‐
3472 ment, you will receive bigger absolute gains (but probably at the same
3473 rate of return). IRR is a way to compute rate of return for each pe‐
3474 riod between in-flow or out-flow of money, and then combine them in a
3475 way that gives you a compound annual rate of return that investment is
3476 expected to generate.
3477 As mentioned before, in-flows and out-flows would be any cash that you
3479 personally put in or withdraw, and for the "roi" command, these are the
3480 postings that match the query in the--inv argument and NOT match the
3481 query in the--pnl argument.
3482 If you manually record changes in the value of your investment as
3484 transactions that balance them against "profit and loss" (or "unreal‐
3485 ized gains") account or use price directives, then in order for IRR to
3486 compute the precise effect of your in-flows and out-flows on the rate
3487 of return, you will need to record the value of your investement on or
3488 close to the days when in- or out-flows occur.
3489 In technical terms, IRR uses the same approach as computation of net
3491 present value, and tries to find a discount rate that makes net present
3492 value of all the cash flows of your investment to add up to zero. This
3493 could be hard to wrap your head around, especially if you haven't done
3494 discounted cash flow analysis before. Implementation of IRR in hledger
3495 should produce results that match the XIRR formula in Excel.
3496 Second way to compute rate of return that roi command implements is
3498 called "time-weighted rate of return" or "TWR". Like IRR, it will also
3499 break the history of your investment into periods between in-flows,
3500 out-flows and value changes, to compute rate of return per each period
3501 and then a compound rate of return. However, internal workings of TWR
3502 are quite different.
3503 TWR represents your investment as an imaginary "unit fund" where in-
3505 flows/ out-flows lead to buying or selling "units" of your investment
3506 and changes in its value change the value of "investment unit". Change
3507 in "unit price" over the reporting period gives you rate of return of
3508 your investment.
3509 References: * Explanation of rate of return * Explanation of IRR * Ex‐
3511 planation of TWR * Examples of computing IRR and TWR and discussion of
3512 the limitations of both metrics
3513 stats
3515 stats
3516 Show some journal statistics.
3517 The stats command displays summary information for the whole journal,
3519 or a matched part of it. With a reporting interval, it shows a report
3520 for each report period.
3521 Example:
3523 $ hledger stats
3525 Main journal file : /src/hledger/examples/sample.journal
3526 Included journal files :
3527 Transactions span : 2008-01-01 to 2009-01-01 (366 days)
3528 Last transaction : 2008-12-31 (2333 days ago)
3529 Transactions : 5 (0.0 per day)
3530 Transactions last 30 days: 0 (0.0 per day)
3531 Transactions last 7 days : 0 (0.0 per day)
3532 Payees/descriptions : 5
3533 Accounts : 8 (depth 3)
3534 Commodities : 1 ($)
3535 Market prices : 12 ($)
3536 This command also supports output destination and output format selec‐
3538 tion.
3539 tags
3541 tags
3542 List the unique tag names used in the journal. With a TAGREGEX argu‐
3543 ment, only tag names matching the regular expression (case insensitive)
3544 are shown. With QUERY arguments, only transactions matching the query
3545 are considered.
3546 With the --values flag, the tags' unique values are listed instead.
3548 With --parsed flag, all tags or values are shown in the order they are
3550 parsed from the input data, including duplicates.
3551 With -E/--empty, any blank/empty values will also be shown, otherwise
3553 they are omitted.
3554 test
3556 test
3557 Run built-in unit tests.
3558 This command runs the unit tests built in to hledger and hledger-lib,
3560 printing the results on stdout. If any test fails, the exit code will
3561 be non-zero.
3562 This is mainly used by hledger developers, but you can also use it to
3564 sanity-check the installed hledger executable on your platform. All
3565 tests are expected to pass - if you ever see a failure, please report
3566 as a bug!
3567 This command also accepts tasty test runner options, written after a --
3569 (double hyphen). Eg to run only the tests in Hledger.Data.Amount, with
3570 ANSI colour codes disabled:
3571 $ hledger test -- -pData.Amount --color=never
3573 For help on these, see https://github.com/feuerbach/tasty#options (--
3575 --help currently doesn't show them).
3576 About add-on commands
3578 Add-on commands are programs or scripts in your PATH
3579 • whose name starts with hledger-
3581 • whose name ends with a recognised file extension: .bat,.com,.exe,
3583 .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none
3584 • and (on unix, mac) which are executable by the current user.
3586 Add-ons are a relatively easy way to add local features or experiment
3588 with new ideas. They can be written in any language, but haskell
3589 scripts have a big advantage: they can use the same hledger library
3590 functions that built-in commands use for command-line options, parsing
3591 and reporting. Some experimental/example add-on scripts can be found
3592 in the hledger repo's bin/ directory.
3593 Note in a hledger command line, add-on command flags must have a double
3595 dash (--) preceding them. Eg you must write:
3596 $ hledger web -- --serve
3598 and not:
3600 $ hledger web --serve
3602 (because the --serve flag belongs to hledger-web, not hledger).
3604 The -h/--help and --version flags don't require --.
3606 If you have any trouble with this, remember you can always run the add-
3608 on program directly, eg:
3609 $ hledger-web --serve
3611
3613 hledger's default file format, representing a General Journal.
3614 hledger's usual data source is a plain text file containing journal en‐
3616 tries in hledger journal format. This file represents a standard ac‐
3617 counting general journal. I use file names ending in .journal, but
3618 that's not required. The journal file contains a number of transaction
3619 entries, each describing a transfer of money (or any commodity) between
3620 two or more named accounts, in a simple format readable by both hledger
3621 and humans.
3622 hledger's journal format is a compatible subset, mostly, of ledger's
3624 journal format, so hledger can work with compatible ledger journal
3625 files as well. It's safe, and encouraged, to run both hledger and
3626 ledger on the same journal file, eg to validate the results you're get‐
3627 ting.
3628 You can use hledger without learning any more about this file; just use
3630 the add or web or import commands to create and update it.
3631 Many users, though, edit the journal file with a text editor, and track
3633 changes with a version control system such as git. Editor addons such
3634 as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
3635 hledger-vscode for Visual Studio Code, make this easier, adding colour,
3636 formatting, tab completion, and useful commands. See Editor configura‐
3637 tion at hledger.org for the full list.
3638 Here's a description of each part of the file format (and hledger's
3640 data model). These are mostly in the order you'll use them, but in
3641 some cases related concepts have been grouped together for easy refer‐
3642 ence, or linked before they are introduced, so feel free to skip over
3643 anything that looks unnecessary right now.
3644 Transactions
3646 Transactions are the main unit of information in a journal file. They
3647 represent events, typically a movement of some quantity of commodities
3648 between two or more named accounts.
3649 Each transaction is recorded as a journal entry, beginning with a sim‐
3651 ple date in column 0. This can be followed by any of the following op‐
3652 tional fields, separated by spaces:
3653 • a status character (empty, !, or *)
3655 • a code (any short number or text, enclosed in parentheses)
3657 • a description (any remaining text until end of line or a semicolon)
3659 • a comment (any remaining text following a semicolon until end of
3661 line, and any following indented lines beginning with a semicolon)
3662 • 0 or more indented posting lines, describing what was transferred and
3664 the accounts involved (indented comment lines are also allowed, but
3665 not blank lines or non-indented lines).
3666 Here's a simple journal file containing one transaction:
3668 2008/01/01 income
3670 assets:bank:checking $1
3671 income:salary $-1
3672 Dates
3674 Simple dates
3675 Dates in the journal file use simple dates format: YYYY-MM-DD or
3676 YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be
3677 omitted, in which case it will be inferred from the context: the cur‐
3678 rent transaction, the default year set with a default year directive,
3679 or the current date when the command is run. Some examples:
3680 2010-01-31, 2010/01/31, 2010.1.31, 1/31.
3681 (The UI also accepts simple dates, as well as the more flexible smart
3683 dates documented in the hledger manual.)
3684 Secondary dates
3686 Real-life transactions sometimes involve more than one date - eg the
3687 date you write a cheque, and the date it clears in your bank. When you
3688 want to model this, for more accurate daily balances, you can specify
3689 individual posting dates.
3690 Or, you can use the older secondary date feature (Ledger calls it aux‐
3692 iliary date or effective date). Note: we support this for compatibil‐
3693 ity, but I usually recommend avoiding this feature; posting dates are
3694 almost always clearer and simpler.
3695 A secondary date is written after the primary date, following an equals
3697 sign. If the year is omitted, the primary date's year is assumed.
3698 When running reports, the primary (left) date is used by default, but
3699 with the --date2 flag (or --aux-date or --effective), the secondary
3700 (right) date will be used instead.
3701 The meaning of secondary dates is up to you, but it's best to follow a
3703 consistent rule. Eg "primary = the bank's clearing date, secondary =
3704 date the transaction was initiated, if different", as shown here:
3705 2010/2/23=2/19 movie ticket
3707 expenses:cinema $10
3708 assets:checking
3709 $ hledger register checking
3711 2010-02-23 movie ticket assets:checking $-10 $-10
3712 $ hledger register checking --date2
3714 2010-02-19 movie ticket assets:checking $-10 $-10
3715 Posting dates
3717 You can give individual postings a different date from their parent
3718 transaction, by adding a posting comment containing a tag (see below)
3719 like date:DATE. This is probably the best way to control posting dates
3720 precisely. Eg in this example the expense should appear in May re‐
3721 ports, and the deduction from checking should be reported on 6/1 for
3722 easy bank reconciliation:
3723 2015/5/30
3725 expenses:food $10 ; food purchased on saturday 5/30
3726 assets:checking ; bank cleared it on monday, date:6/1
3727 $ hledger -f t.j register food
3729 2015-05-30 expenses:food $10 $10
3730 $ hledger -f t.j register checking
3732 2015-06-01 assets:checking $-10 $-10
3733 DATE should be a simple date; if the year is not specified it will use
3735 the year of the transaction's date. You can set the secondary date
3736 similarly, with date2:DATE2. The date: or date2: tags must have a
3737 valid simple date value if they are present, eg a date: tag with no
3738 value is not allowed.
3739 Ledger's earlier, more compact bracketed date syntax is also supported:
3741 [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any
3742 square-bracketed sequence of the 0123456789/-.= characters in this way.
3743 With this syntax, DATE infers its year from the transaction and DATE2
3744 infers its year from DATE.
3745 Status
3747 Transactions, or individual postings within a transaction, can have a
3748 status mark, which is a single character before the transaction de‐
3749 scription or posting account name, separated from it by a space, indi‐
3750 cating one of three statuses:
3751 mark status
3753 ──────────────────
3754 unmarked
3755 ! pending
3756 * cleared
3757 When reporting, you can filter by status with the -U/--unmarked,
3759 -P/--pending, and -C/--cleared flags; or the status:, status:!, and
3760 status:* queries; or the U, P, C keys in hledger-ui.
3761 Note, in Ledger and in older versions of hledger, the "unmarked" state
3763 is called "uncleared". As of hledger 1.3 we have renamed it to un‐
3764 marked for clarity.
3765 To replicate Ledger and old hledger's behaviour of also matching pend‐
3767 ing, combine -U and -P.
3768 Status marks are optional, but can be helpful eg for reconciling with
3770 real-world accounts. Some editor modes provide highlighting and short‐
3771 cuts for working with status. Eg in Emacs ledger-mode, you can toggle
3772 transaction status with C-c C-e, or posting status with C-c C-c.
3773 What "uncleared", "pending", and "cleared" actually mean is up to you.
3775 Here's one suggestion:
3776 status meaning
3778 ──────────────────────────────────────────────────────────────────────────
3779 uncleared recorded but not yet reconciled; needs review
3780 pending tentatively reconciled (if needed, eg during a big reconcil‐
3781 iation)
3782 cleared complete, reconciled as far as possible, and considered cor‐
3783 rect
3784 With this scheme, you would use -PC to see the current balance at your
3786 bank, -U to see things which will probably hit your bank soon (like un‐
3787 cashed checks), and no flags to see the most up-to-date state of your
3788 finances.
3789 Description
3791 A transaction's description is the rest of the line following the date
3792 and status mark (or until a comment begins). Sometimes called the
3793 "narration" in traditional bookkeeping, it can be used for whatever you
3794 wish, or left blank. Transaction descriptions can be queried, unlike
3795 comments.
3796 Payee and note
3798 You can optionally include a | (pipe) character in descriptions to sub‐
3799 divide the description into separate fields for payee/payer name on the
3800 left (up to the first |) and an additional note field on the right (af‐
3801 ter the first |). This may be worthwhile if you need to do more pre‐
3802 cise querying and pivoting by payee or by note.
3803 Comments
3805 Lines in the journal beginning with a semicolon (;) or hash (#) or star
3806 (*) are comments, and will be ignored. (Star comments cause org-mode
3807 nodes to be ignored, allowing emacs users to fold and navigate their
3808 journals with org-mode or orgstruct-mode.)
3809 You can attach comments to a transaction by writing them after the de‐
3811 scription and/or indented on the following lines (before the postings).
3812 Similarly, you can attach comments to an individual posting by writing
3813 them after the amount and/or indented on the following lines. Transac‐
3814 tion and posting comments must begin with a semicolon (;).
3815 Some examples:
3817 # a file comment
3819 ; another file comment
3820 * also a file comment, useful in org/orgstruct mode
3821 comment
3823 A multiline file comment, which continues
3824 until a line containing just "end comment"
3825 (or end of file).
3826 end comment
3827 2012/5/14 something ; a transaction comment
3829 ; the transaction comment, continued
3830 posting1 1 ; a comment for posting 1
3831 posting2
3832 ; a comment for posting 2
3833 ; another comment line for posting 2
3834 ; a file comment (because not indented)
3835 You can also comment larger regions of a file using comment and end
3837 comment directives.
3838 Tags
3840 Tags are a way to add extra labels or labelled data to postings and
3841 transactions, which you can then search or pivot on.
3842 A simple tag is a word (which may contain hyphens) followed by a full
3844 colon, written inside a transaction or posting comment line:
3845 2017/1/16 bought groceries ; sometag:
3847 Tags can have a value, which is the text after the colon, up to the
3849 next comma or end of line, with leading/trailing whitespace removed:
3850 expenses:food $10 ; a-posting-tag: the tag value
3852 Note this means hledger's tag values can not contain commas or new‐
3854 lines. Ending at commas means you can write multiple short tags on one
3855 line, comma separated:
3856 assets:checking ; a comment containing tag1:, tag2: some value ...
3858 Here,
3860 • "a comment containing" is just comment text, not a tag
3862 • "tag1" is a tag with no value
3864 • "tag2" is another tag, whose value is "some value ..."
3866 Tags in a transaction comment affect the transaction and all of its
3868 postings, while tags in a posting comment affect only that posting.
3869 For example, the following transaction has three tags (A, TAG2, third-
3870 tag) and the posting has four (those plus posting-tag):
3871 1/1 a transaction ; A:, TAG2:
3873 ; third-tag: a third transaction tag, <- with a value
3874 (a) $1 ; posting-tag:
3875 Tags are like Ledger's metadata feature, except hledger's tag values
3877 are simple strings.
3878 Postings
3880 A posting is an addition of some amount to, or removal of some amount
3881 from, an account. Each posting line begins with at least one space or
3882 tab (2 or 4 spaces is common), followed by:
3883 • (optional) a status character (empty, !, or *), followed by a space
3885 • (required) an account name (any text, optionally containing single
3887 spaces, until end of line or a double space)
3888 • (optional) two or more spaces or tabs followed by an amount.
3890 Positive amounts are being added to the account, negative amounts are
3892 being removed.
3893 The amounts within a transaction must always sum up to zero. As a con‐
3895 venience, one amount may be left blank; it will be inferred so as to
3896 balance the transaction.
3897 Be sure to note the unusual two-space delimiter between account name
3899 and amount. This makes it easy to write account names containing spa‐
3900 ces. But if you accidentally leave only one space (or tab) before the
3901 amount, the amount will be considered part of the account name.
3902 Virtual postings
3904 A posting with a parenthesised account name is called a virtual posting
3905 or unbalanced posting, which means it is exempt from the usual rule
3906 that a transaction's postings must balance add up to zero.
3907 This is not part of double entry accounting, so you might choose to
3909 avoid this feature. Or you can use it sparingly for certain special
3910 cases where it can be convenient. Eg, you could set opening balances
3911 without using a balancing equity account:
3912 1/1 opening balances
3914 (assets:checking) $1000
3915 (assets:savings) $2000
3916 A posting with a bracketed account name is called a balanced virtual
3918 posting. The balanced virtual postings in a transaction must add up to
3919 zero (separately from other postings). Eg:
3920 1/1 buy food with cash, update budget envelope subaccounts, & something else
3922 assets:cash $-10 ; <- these balance
3923 expenses:food $7 ; <-
3924 expenses:food $3 ; <-
3925 [assets:checking:budget:food] $-10 ; <- and these balance
3926 [assets:checking:available] $10 ; <-
3927 (something:else) $5 ; <- not required to balance
3928 Ordinary non-parenthesised, non-bracketed postings are called real
3930 postings. You can exclude virtual postings from reports with the
3931 -R/--real flag or real:1 query.
3932 Account names
3934 Account names typically have several parts separated by a full colon,
3935 from which hledger derives a hierarchical chart of accounts. They can
3936 be anything you like, but in finance there are traditionally five top-
3937 level accounts: assets, liabilities, revenue, expenses, and equity.
3938 Account names may contain single spaces, eg: assets:accounts receiv‐
3940 able. Because of this, they must always be followed by two or more
3941 spaces (or newline).
3942 Account names can be aliased.
3944 Amounts
3946 After the account name, there is usually an amount. (Important: be‐
3947 tween account name and amount, there must be two or more spaces.)
3948 hledger's amount format is flexible, supporting several international
3950 formats. Here are some examples. Amounts have a number (the "quan‐
3951 tity"):
3952 1
3954 ..and usually a currency or commodity name (the "commodity"). This is
3956 a symbol, word, or phrase, to the left or right of the quantity, with
3957 or without a separating space:
3958 $1
3960 4000 AAPL
3961 If the commodity name contains spaces, numbers, or punctuation, it must
3963 be enclosed in double quotes:
3964 3 "no. 42 green apples"
3966 Amounts can be preceded by a minus sign (or a plus sign, though plus is
3968 the default), The sign can be written before or after a left-side com‐
3969 modity symbol:
3970 -$1
3972 $-1
3973 One or more spaces between the sign and the number are acceptable when
3975 parsing (but they won't be displayed in output):
3976 + $1
3978 $- 1
3979 Scientific E notation is allowed:
3981 1E-6
3983 EUR 1E3
3984 Decimal marks, digit group marks
3986 A decimal mark can be written as a period or a comma:
3987 1.23
3989 1,23456780000009
3990 In the integer part of the quantity (left of the decimal mark), groups
3992 of digits can optionally be separated by a "digit group mark" - a
3993 space, comma, or period (different from the decimal mark):
3994 $1,000,000.00
3996 EUR 2.000.000,00
3997 INR 9,99,99,999.00
3998 1 000 000.9455
3999 Note, a number containing a single digit group mark and no decimal mark
4001 is ambiguous. Are these digit group marks or decimal marks ?
4002 1,000
4004 1.000
4005 If you don't tell it otherwise, hledger will assume both of the above
4007 are decimal marks, parsing both numbers as 1. To prevent confusion and
4008 undetected typos, especially if your data contains digit group marks,
4009 we recommend you explicitly declare the decimal mark (and optionally a
4010 digit group mark), for each commodity, using commodity directives (de‐
4011 scribed below):
4012 # number formats for $, EUR, INR and the no-symbol commodity:
4014 commodity $1,000.00
4015 commodity EUR 1.000,00
4016 commodity INR 9,99,99,999.00
4017 commodity 1 000 000.9455
4018 Note, commodity directives declare both the number format for parsing
4020 input, and the display style for showing output. For the former, they
4021 are position-sensitive, affecting only following amounts, so commodity
4022 directives should be at the top of your journal file. This is dis‐
4023 cussed more on #793.
4024 Commodity display style
4026 For the amounts in each commodity, hledger chooses a consistent display
4027 style to use in most reports. (Except for price amounts, which are al‐
4028 ways displayed as written). The display style is inferred as follows.
4029 First, if a default commodity is declared with D, this commodity and
4031 its style is applied to any no-symbol amounts in the journal.
4032 Then each commodity's style is inferred from one of the following, in
4034 order of preference:
4035 • The commodity directive for that commodity (including the no-symbol
4037 commodity), if any.
4038 • The amounts in that commodity seen in the journal's transactions.
4040 (Posting amounts only; prices and periodic or auto rules are ignored,
4041 currently.)
4042 • The built-in fallback style, which looks like this: $1000.00. (Sym‐
4044 bol on the left, period decimal mark, two decimal places.)
4045 A style is inferred from journal amounts as follows:
4047 • Use the general style (decimal mark, symbol placement) of the first
4049 amount
4050 • Use the first-seen digit group style (digit group mark, digit group
4052 sizes), if any
4053 • Use the maximum number of decimal places of all.
4055 Transaction price amounts don't affect the commodity display style di‐
4057 rectly, but occasionally they can do so indirectly (eg when a posting's
4058 amount is inferred using a transaction price). If you find this caus‐
4059 ing problems, use a commodity directive to fix the display style.
4060 To summarise: each commodity's amounts will be normalised to (a) the
4062 style declared by a commodity directive, or (b) the style of the first
4063 posting amount in the journal, with the first-seen digit group style
4064 and the maximum-seen number of decimal places. So if your reports are
4065 showing amounts in a way you don't like, eg with too many decimal
4066 places, use a commodity directive. Some examples:
4067 # declare euro, dollar, bitcoin and no-symbol commodities and set their
4069 # input number formats and output display styles:
4070 commodity EUR 1.000,
4071 commodity $1000.00
4072 commodity 1000.00000000 BTC
4073 commodity 1 000.
4074 Rounding
4076 Amounts are stored internally as decimal numbers with up to 255 decimal
4077 places, and displayed with the number of decimal places specified by
4078 the commodity display style. Note, hledger uses banker's rounding: it
4079 rounds to the nearest even number, eg 0.5 displayed with zero decimal
4080 places is "0"). (Guaranteed since hledger 1.17.1; in older versions
4081 this could vary if hledger was built with Decimal < 0.5.1.)
4082 Transaction prices
4084 Within a transaction, you can note an amount's price in another commod‐
4085 ity. This can be used to document the cost (in a purchase) or selling
4086 price (in a sale). For example, transaction prices are useful to
4087 record purchases of a foreign currency. Note transaction prices are
4088 fixed at the time of the transaction, and do not change over time. See
4089 also market prices, which represent prevailing exchange rates on a cer‐
4090 tain date.
4091 There are several ways to record a transaction price:
4093 1. Write the price per unit, as @ UNITPRICE after the amount:
4095 2009/1/1
4097 assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each
4098 assets:dollars ; balancing amount is -$135.00
4099 2. Write the total price, as @@ TOTALPRICE after the amount:
4101 2009/1/1
4103 assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot
4104 assets:dollars
4105 3. Specify amounts for all postings, using exactly two commodities, and
4107 let hledger infer the price that balances the transaction:
4108 2009/1/1
4110 assets:euros €100 ; one hundred euros purchased
4111 assets:dollars $-135 ; for $135
4112 4. Like 1, but the @ is parenthesised, i.e. (@); this is for compati‐
4114 bility with Ledger journals (Virtual posting costs), and is equiva‐
4115 lent to 1 in hledger.
4116 5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger,
4118 this is equivalent to 2.
4119 Use the -B/--cost flag to convert amounts to their transaction price's
4121 commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger).
4122 Eg here is how -B affects the balance report for the example above:
4123 $ hledger bal -N --flat
4125 $-135 assets:dollars
4126 €100 assets:euros
4127 $ hledger bal -N --flat -B
4128 $-135 assets:dollars
4129 $135 assets:euros # <- the euros' cost
4130 Note -B is sensitive to the order of postings when a transaction price
4132 is inferred: the inferred price will be in the commodity of the last
4133 amount. So if example 3's postings are reversed, while the transaction
4134 is equivalent, -B shows something different:
4135 2009/1/1
4137 assets:dollars $-135 ; 135 dollars sold
4138 assets:euros €100 ; for 100 euros
4139 $ hledger bal -N --flat -B
4141 €-100 assets:dollars # <- the dollars' selling price
4142 €100 assets:euros
4143 Lot prices, lot dates
4145 Ledger allows another kind of price, lot price (four variants: {UNIT‐
4146 PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}),
4147 and/or a lot date ([DATE]) to be specified. These are normally used to
4148 select a lot when selling investments. hledger will parse these, for
4149 compatibility with Ledger journals, but currently ignores them. A
4150 transaction price, lot price and/or lot date may appear in any order,
4151 after the posting amount and before the balance assertion if any.
4152 Balance assertions
4154 hledger supports Ledger-style balance assertions in journal files.
4155 These look like, for example, = EXPECTEDBALANCE following a posting's
4156 amount. Eg here we assert the expected dollar balance in accounts a
4157 and b after each posting:
4158 2013/1/1
4160 a $1 =$1
4161 b =$-1
4162 2013/1/2
4164 a $1 =$2
4165 b $-1 =$-2
4166 After reading a journal file, hledger will check all balance assertions
4168 and report an error if any of them fail. Balance assertions can pro‐
4169 tect you from, eg, inadvertently disrupting reconciled balances while
4170 cleaning up old entries. You can disable them temporarily with the
4171 -I/--ignore-assertions flag, which can be useful for troubleshooting or
4172 for reading Ledger files. (Note: this flag currently does not disable
4173 balance assignments, below).
4174 Assertions and ordering
4176 hledger sorts an account's postings and assertions first by date and
4177 then (for postings on the same day) by parse order. Note this is dif‐
4178 ferent from Ledger, which sorts assertions only by parse order. (Also,
4179 Ledger assertions do not see the accumulated effect of repeated post‐
4180 ings to the same account within a transaction.)
4181 So, hledger balance assertions keep working if you reorder differently-
4183 dated transactions within the journal. But if you reorder same-dated
4184 transactions or postings, assertions might break and require updating.
4185 This order dependence does bring an advantage: precise control over the
4186 order of postings and assertions within a day, so you can assert intra-
4187 day balances.
4188 Assertions and included files
4190 With included files, things are a little more complicated. Including
4191 preserves the ordering of postings and assertions. If you have multi‐
4192 ple postings to an account on the same day, split across different
4193 files, and you also want to assert the account's balance on the same
4194 day, you'll have to put the assertion in the right file.
4195 Assertions and multiple -f options
4197 Balance assertions don't work well across files specified with multiple
4198 -f options. Use include or concatenate the files instead.
4199 Assertions and commodities
4201 The asserted balance must be a simple single-commodity amount, and in
4202 fact the assertion checks only this commodity's balance within the
4203 (possibly multi-commodity) account balance. This is how assertions
4204 work in Ledger also. We could call this a "partial" balance assertion.
4205 To assert the balance of more than one commodity in an account, you can
4207 write multiple postings, each asserting one commodity's balance.
4208 You can make a stronger "total" balance assertion by writing a double
4210 equals sign (== EXPECTEDBALANCE). This asserts that there are no other
4211 unasserted commodities in the account (or, that their balance is 0).
4212 2013/1/1
4214 a $1
4215 a 1€
4216 b $-1
4217 c -1€
4218 2013/1/2 ; These assertions succeed
4220 a 0 = $1
4221 a 0 = 1€
4222 b 0 == $-1
4223 c 0 == -1€
4224 2013/1/3 ; This assertion fails as 'a' also contains 1€
4226 a 0 == $1
4227 It's not yet possible to make a complete assertion about a balance that
4229 has multiple commodities. One workaround is to isolate each commodity
4230 into its own subaccount:
4231 2013/1/1
4233 a:usd $1
4234 a:euro 1€
4235 b
4236 2013/1/2
4238 a 0 == 0
4239 a:usd 0 == $1
4240 a:euro 0 == 1€
4241 Assertions and prices
4243 Balance assertions ignore transaction prices, and should normally be
4244 written without one:
4245 2019/1/1
4247 (a) $1 @ €1 = $1
4248 We do allow prices to be written there, however, and print shows them,
4250 even though they don't affect whether the assertion passes or fails.
4251 This is for backward compatibility (hledger's close command used to
4252 generate balance assertions with prices), and because balance assign‐
4253 ments do use them (see below).
4254 Assertions and subaccounts
4256 The balance assertions above (= and ==) do not count the balance from
4257 subaccounts; they check the account's exclusive balance only. You can
4258 assert the balance including subaccounts by writing =* or ==*, eg:
4259 2019/1/1
4261 equity:opening balances
4262 checking:a 5
4263 checking:b 5
4264 checking 1 ==* 11
4265 Assertions and virtual postings
4267 Balance assertions are checked against all postings, both real and vir‐
4268 tual. They are not affected by the --real/-R flag or real: query.
4269 Assertions and precision
4271 Balance assertions compare the exactly calculated amounts, which are
4272 not always what is shown by reports. Eg a commodity directive may
4273 limit the display precision, but this will not affect balance asser‐
4274 tions. Balance assertion failure messages show exact amounts.
4275 Balance assignments
4277 Ledger-style balance assignments are also supported. These are like
4278 balance assertions, but with no posting amount on the left side of the
4279 equals sign; instead it is calculated automatically so as to satisfy
4280 the assertion. This can be a convenience during data entry, eg when
4281 setting opening balances:
4282 ; starting a new journal, set asset account balances
4284 2016/1/1 opening balances
4285 assets:checking = $409.32
4286 assets:savings = $735.24
4287 assets:cash = $42
4288 equity:opening balances
4289 or when adjusting a balance to reality:
4291 ; no cash left; update balance, record any untracked spending as a generic expense
4293 2016/1/15
4294 assets:cash = $0
4295 expenses:misc
4296 The calculated amount depends on the account's balance in the commodity
4298 at that point (which depends on the previously-dated postings of the
4299 commodity to that account since the last balance assertion or assign‐
4300 ment). Note that using balance assignments makes your journal a little
4301 less explicit; to know the exact amount posted, you have to run hledger
4302 or do the calculations yourself, instead of just reading it.
4303 Balance assignments and prices
4305 A transaction price in a balance assignment will cause the calculated
4306 amount to have that price attached:
4307 2019/1/1
4309 (a) = $1 @ €2
4310 $ hledger print --explicit
4312 2019-01-01
4313 (a) $1 @ €2 = $1 @ €2
4314 Directives
4316 A directive is a line in the journal beginning with a special keyword,
4317 that influences how the journal is processed. hledger's directives are
4318 based on a subset of Ledger's, but there are many differences (and also
4319 some differences between hledger versions).
4320 Directives' behaviour and interactions can get a little bit complex, so
4322 here is a table summarising the directives and their effects, with
4323 links to more detailed docs. Note part of this table is hidden when
4324 viewed in a web browser - scroll it sideways to see more.
4325 direc‐ end di‐ subdi‐ purpose can affect (as of
4327 tive rective rec‐ 2018/06)
4328 tives
4329 ────────────────────────────────────────────────────────────────────────────────────
4330 account any document account names, de‐ all entries in all
4331 text clare account types & dis‐ files, before or
4332 play order after
4333 alias end rewrite account names following entries
4334 aliases until end of cur‐
4335 rent file or end
4336 directive
4337 apply end apply prepend a common parent to following entries
4338 account account account names until end of cur‐
4339 rent file or end
4340 directive
4341 comment end com‐ ignore part of journal following entries
4342 ment until end of cur‐
4343 rent file or end
4344 directive
4345 commod‐ format declare a commodity and its number notation:
4346 ity number notation & display following entries
4347 style in that commodity
4348 in all files ; dis‐
4349 play style: amounts
4350 of that commodity
4351 in reports
4352 D declare a commodity to be default commodity:
4353 used for commodityless following commod‐
4354 amounts, and its number no‐ ityless entries un‐
4355 tation & display style til end of current
4356 file; number nota‐
4357 tion: following en‐
4358 tries in that com‐
4359 modity until end of
4360 current file; dis‐
4361 play style: amounts
4362 of that commodity
4363 in reports
4364 include include entries/directives what the included
4365 from another file directives affect
4366 [payee] declare a payee name following entries
4367 until end of cur‐
4368 rent file
4369 P declare a market price for a amounts of that
4370 commodity commodity in re‐
4371 ports, when -V is
4372 used
4373 Y declare a year for yearless following entries
4374 dates until end of cur‐
4375 rent file
4376 = declare an auto posting all entries in par‐
4377 rule, adding postings to ent/current/child
4378 other transactions files (but not sib‐
4379 ling files, see
4380 #1212)
4381 And some definitions:
4383 subdi‐ optional indented directive line immediately following a parent
4385 rec‐ directive
4386 tive
4387 number how to interpret numbers when parsing journal entries (the iden‐
4388 nota‐ tity of the decimal separator character). (Currently each com‐
4389 tion modity can have its own notation, even in the same file.)
4390 dis‐ how to display amounts of a commodity in reports (symbol side
4391 play and spacing, digit groups, decimal separator, decimal places)
4392 style
4393 direc‐ which entries and (when there are multiple files) which files
4394 tive are affected by a directive
4395 scope
4396 As you can see, directives vary in which journal entries and files they
4398 affect, and whether they are focussed on input (parsing) or output (re‐
4399 ports). Some directives have multiple effects.
4400 Directives and multiple files
4402 If you use multiple -f/--file options, or the include directive,
4403 hledger will process multiple input files. But note that directives
4404 which affect input (see above) typically last only until the end of the
4405 file in which they occur.
4406 This may seem inconvenient, but it's intentional; it makes reports sta‐
4408 ble and deterministic, independent of the order of input. Otherwise
4409 you could see different numbers if you happened to write -f options in
4410 a different order, or if you moved includes around while cleaning up
4411 your files.
4412 It can be surprising though; for example, it means that alias direc‐
4414 tives do not affect parent or sibling files (see below).
4415 Comment blocks
4417 A line containing just comment starts a commented region of the file,
4418 and a line containing just end comment (or the end of the current file)
4419 ends it. See also comments.
4420 Including other files
4422 You can pull in the content of additional files by writing an include
4423 directive, like this:
4424 include FILEPATH
4426 Only journal files can include, and only journal, timeclock or timedot
4428 files can be included (not CSV files, currently).
4429 If the file path does not begin with a slash, it is relative to the
4431 current file's folder.
4432 A tilde means home directory, eg: include ~/main.journal.
4434 The path may contain glob patterns to match multiple files, eg: include
4436 *.journal.
4437 There is limited support for recursive wildcards: **/ (the slash is re‐
4439 quired) matches 0 or more subdirectories. It's not super convenient
4440 since you have to avoid include cycles and including directories, but
4441 this can be done, eg: include */**/*.journal.
4442 The path may also be prefixed to force a specific file format, overrid‐
4444 ing the file extension (as described in hledger.1 -> Input files): in‐
4445 clude timedot:~/notes/2020*.md.
4446 Default year
4448 You can set a default year to be used for subsequent dates which don't
4449 specify a year. This is a line beginning with Y followed by the year.
4450 Eg:
4451 Y2009 ; set default year to 2009
4453 12/15 ; equivalent to 2009/12/15
4455 expenses 1
4456 assets
4457 Y2010 ; change default year to 2010
4459 2009/1/30 ; specifies the year, not affected
4461 expenses 1
4462 assets
4463 1/31 ; equivalent to 2010/1/31
4465 expenses 1
4466 assets
4467 Declaring payees
4469 The payee directive can be used to declare a limited set of payees
4470 which may appear in transaction descriptions. The "payees" check will
4471 report an error if any transaction refers to a payee that has not been
4472 declared. Eg:
4473 payee Whole Foods
4475 Declaring commodities
4477 The commodity directive has several functions:
4478 1. It declares commodities which may be used in the journal. This is
4480 currently not enforced, but can serve as documentation.
4481 2. It declares what decimal mark character (period or comma) to expect
4483 when parsing input - useful to disambiguate international number
4484 formats in your data. (Without this, hledger will parse both 1,000
4485 and 1.000 as 1).
4486 3. It declares a commodity's display style in output - decimal and
4488 digit group marks, number of decimal places, symbol placement etc.
4489 You are likely to run into one of the problems solved by commodity di‐
4491 rectives, sooner or later, so it's a good idea to just always use them
4492 to declare your commodities.
4493 A commodity directive is just the word commodity followed by an amount.
4495 It may be written on a single line, like this:
4496 ; commodity EXAMPLEAMOUNT
4498 ; display AAAA amounts with the symbol on the right, space-separated,
4500 ; using period as decimal point, with four decimal places, and
4501 ; separating thousands with comma.
4502 commodity 1,000.0000 AAAA
4503 or on multiple lines, using the "format" subdirective. (In this case
4505 the commodity symbol appears twice and should be the same in both
4506 places.):
4507 ; commodity SYMBOL
4509 ; format EXAMPLEAMOUNT
4510 ; display indian rupees with currency name on the left,
4512 ; thousands, lakhs and crores comma-separated,
4513 ; period as decimal point, and two decimal places.
4514 commodity INR
4515 format INR 1,00,00,000.00
4516 The quantity of the amount does not matter; only the format is signifi‐
4518 cant. The number must include a decimal mark: either a period or a
4519 comma, followed by 0 or more decimal digits.
4520 Note hledger normally uses banker's rounding, so 0.5 displayed with
4522 zero decimal digits is "0". (More at Commodity display style.)
4523 Commodity error checking
4525 In strict mode, enabled with the -s/--strict flag, hledger will report
4526 an error if a commodity symbol is used that has not been declared by a
4527 commodity directive. This works similarly to account error checking,
4528 see the notes there for more details.
4529 Default commodity
4531 The D directive sets a default commodity, to be used for amounts with‐
4532 out a commodity symbol (ie, plain numbers). This commodity will be ap‐
4533 plied to all subsequent commodity-less amounts, or until the next D di‐
4534 rective. (Note, this is different from Ledger's D.)
4535 For compatibility/historical reasons, D also acts like a commodity di‐
4537 rective, setting the commodity's display style (for output) and decimal
4538 mark (for parsing input). As with commodity, the amount must always be
4539 written with a decimal mark (period or comma). If both directives are
4540 used, commodity's style takes precedence.
4541 The syntax is D AMOUNT. Eg:
4543 ; commodity-less amounts should be treated as dollars
4545 ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
4546 D $1,000.00
4547 1/1
4549 a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
4550 b
4551 Declaring market prices
4553 The P directive declares a market price, which is an exchange rate be‐
4554 tween two commodities on a certain date. (In Ledger, they are called
4555 "historical prices".) These are often obtained from a stock exchange,
4556 cryptocurrency exchange, or the foreign exchange market.
4557 Here is the format:
4559 P DATE COMMODITYA COMMODITYBAMOUNT
4561 • DATE is a simple date
4563 • COMMODITYA is the symbol of the commodity being priced
4565 • COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com‐
4567 modity, giving the price in commodity B of one unit of commodity A.
4568 These two market price directives say that one euro was worth 1.35 US
4570 dollars during 2009, and $1.40 from 2010 onward:
4571 P 2009/1/1 € $1.35
4573 P 2010/1/1 € $1.40
4574 The -V, -X and --value flags use these market prices to show amount
4576 values in another commodity. See Valuation.
4577 Declaring accounts
4579 account directives can be used to declare accounts (ie, the places that
4580 amounts are transferred from and to). Though not required, these dec‐
4581 larations can provide several benefits:
4582 • They can document your intended chart of accounts, providing a refer‐
4584 ence.
4585 • They can help hledger know your accounts' types (asset, liability,
4587 equity, revenue, expense), useful for reports like balancesheet and
4588 incomestatement.
4589 • They control account display order in reports, allowing non-alpha‐
4591 betic sorting (eg Revenues to appear above Expenses).
4592 • They can store extra information about accounts (account numbers,
4594 notes, etc.)
4595 • They help with account name completion in the add command, hledger-
4597 iadd, hledger-web, ledger-mode etc.
4598 • In strict mode, they restrict which accounts may be posted to by
4600 transactions, which helps detect typos.
4601 The simplest form is just the word account followed by a hledger-style
4603 account name, eg this account directive declares the assets:bank:check‐
4604 ing account:
4605 account assets:bank:checking
4607 Account error checking
4609 By default, accounts come into existence when a transaction references
4610 them by name. This is convenient, but it means hledger can't warn you
4611 when you mis-spell an account name in the journal. Usually you'll find
4612 the error later, as an extra account in balance reports, or an incor‐
4613 rect balance when reconciling.
4614 In strict mode, enabled with the -s/--strict flag, hledger will report
4616 an error if any transaction uses an account name that has not been de‐
4617 clared by an account directive. Some notes:
4618 • The declaration is case-sensitive; transactions must use the correct
4620 account name capitalisation.
4621 • The account directive's scope is "whole file and below" (see direc‐
4623 tives). This means it affects all of the current file, and any files
4624 it includes, but not parent or sibling files. The position of ac‐
4625 count directives within the file does not matter, though it's usual
4626 to put them at the top.
4627 • Accounts can only be declared in journal files (but will affect in‐
4629 cluded files in other formats).
4630 • It's currently not possible to declare "all possible subaccounts"
4632 with a wildcard; every account posted to must be declared.
4633 Account comments
4635 Comments, beginning with a semicolon, can be added:
4636 • on the same line, after two or more spaces (because ; is allowed in
4638 account names)
4639 • on the next lines, indented
4641 An example of both:
4643 account assets:bank:checking ; same-line comment, note 2+ spaces before ;
4645 ; next-line comment
4646 ; another with tag, acctno:12345 (not used yet)
4647 Same-line comments are not supported by Ledger, or hledger <1.13.
4649 Account subdirectives
4651 We also allow (and ignore) Ledger-style indented subdirectives, just
4652 for compatibility.:
4653 account assets:bank:checking
4655 format blah blah ; <- subdirective, ignored
4656 Here is the full syntax of account directives:
4658 account ACCTNAME [ACCTTYPE] [;COMMENT]
4660 [;COMMENTS]
4661 [LEDGER-STYLE SUBDIRECTIVES, IGNORED]
4662 Account types
4664 hledger recognises five main types of account, corresponding to the ac‐
4665 count classes in the accounting equation:
4666 Asset, Liability, Equity, Revenue, Expense.
4668 These account types are important for controlling which accounts appear
4670 in the balancesheet, balancesheetequity, incomestatement reports (and
4671 probably for other things in future).
4672 Additionally, we recognise the Cash type, which is also an Asset, and
4674 which causes accounts to appear in the cashflow report. ("Cash" here
4675 means liquid assets, eg bank balances but typically not investments or
4676 receivables.)
4677 Declaring account types
4679 Generally, to make these reports work you should declare your top-level
4680 accounts and their types, using account directives with type: tags.
4681 The tag's value should be one of: Asset, Liability, Equity, Revenue,
4683 Expense, Cash, A, L, E, R, X, C (all case insensitive). The type is
4684 inherited by all subaccounts except where they override it. Here's a
4685 complete example:
4686 account assets ; type: Asset
4688 account assets:bank ; type: Cash
4689 account assets:cash ; type: Cash
4690 account liabilities ; type: Liability
4691 account equity ; type: Equity
4692 account revenues ; type: Revenue
4693 account expenses ; type: Expense
4694 Auto-detected account types
4696 If you happen to use common english top-level account names, you may
4697 not need to declare account types, as they will be detected automati‐
4698 cally using the following rules:
4699 If name matches regular account type is:
4701 expression:
4702 ──────────────────────────────────────────────
4703 ^assets?(:|$) Asset
4704 ^(debts?|lia‐ Liability
4705 bilit(y|ies))(:|$)
4706 ^equity(:|$) Equity
4707 ^(income|revenue)s?(:|$) Revenue
4708 ^expenses?(:|$) Expense
4709 If account type is Asset and name does not contain regu‐ account type
4711 lar expression: is:
4712 ──────────────────────────────────────────────────────────────────────────
4713 (investment|receivable|:A/R|:fixed) Cash
4714 Even so, explicit declarations may be a good idea, for clarity and pre‐
4716 dictability.
4717 Interference from auto-detected account types
4719 If you assign any account type, it's a good idea to assign all of them,
4720 to prevent any confusion from mixing declared and auto-detected types.
4721 Although it's unlikely to happen in real life, here's an example: with
4722 the following journal, balancesheetequity shows "liabilities" in both
4723 Liabilities and Equity sections. Declaring another account as type:Li‐
4724 ability would fix it:
4725 account liabilities ; type:Equity
4727 2020-01-01
4729 assets 1
4730 liabilities 1
4731 equity -2
4732 Old account type syntax
4734 In some hledger journals you might instead see this old syntax (the
4735 letters ALERX, separated from the account name by two or more spaces);
4736 this is deprecated and may be removed soon:
4737 account assets A
4739 account liabilities L
4740 account equity E
4741 account revenues R
4742 account expenses X
4743 Account display order
4745 Account directives also set the order in which accounts are displayed,
4746 eg in reports, the hledger-ui accounts screen, and the hledger-web
4747 sidebar. By default accounts are listed in alphabetical order. But if
4748 you have these account directives in the journal:
4749 account assets
4751 account liabilities
4752 account equity
4753 account revenues
4754 account expenses
4755 you'll see those accounts displayed in declaration order, not alphabet‐
4757 ically:
4758 $ hledger accounts -1
4760 assets
4761 liabilities
4762 equity
4763 revenues
4764 expenses
4765 Undeclared accounts, if any, are displayed last, in alphabetical order.
4767 Note that sorting is done at each level of the account tree (within
4769 each group of sibling accounts under the same parent). And currently,
4770 this directive:
4771 account other:zoo
4773 would influence the position of zoo among other's subaccounts, but not
4775 the position of other among the top-level accounts. This means:
4776 • you will sometimes declare parent accounts (eg account other above)
4778 that you don't intend to post to, just to customize their display or‐
4779 der
4780 • sibling accounts stay together (you couldn't display x:y in between
4782 a:b and a:c).
4783 Rewriting accounts
4785 You can define account alias rules which rewrite your account names, or
4786 parts of them, before generating reports. This can be useful for:
4787 • expanding shorthand account names to their full form, allowing easier
4789 data entry and a less verbose journal
4790 • adapting old journals to your current chart of accounts
4792 • experimenting with new account organisations, like a new hierarchy or
4794 combining two accounts into one
4795 • customising reports
4797 Account aliases also rewrite account names in account directives. They
4799 do not affect account names being entered via hledger add or hledger-
4800 web.
4801 See also Rewrite account names.
4803 Basic aliases
4805 To set an account alias, use the alias directive in your journal file.
4806 This affects all subsequent journal entries in the current file or its
4807 included files. The spaces around the = are optional:
4808 alias OLD = NEW
4810 Or, you can use the --alias 'OLD=NEW' option on the command line. This
4812 affects all entries. It's useful for trying out aliases interactively.
4813 OLD and NEW are case sensitive full account names. hledger will re‐
4815 place any occurrence of the old account name with the new one. Subac‐
4816 counts are also affected. Eg:
4817 alias checking = assets:bank:wells fargo:checking
4819 ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
4820 Regex aliases
4822 There is also a more powerful variant that uses a regular expression,
4823 indicated by the forward slashes:
4824 alias /REGEX/ = REPLACEMENT
4826 or --alias '/REGEX/=REPLACEMENT'.
4828 REGEX is a case-insensitive regular expression. Anywhere it matches
4830 inside an account name, the matched part will be replaced by REPLACE‐
4831 MENT. If REGEX contains parenthesised match groups, these can be ref‐
4832 erenced by the usual numeric backreferences in REPLACEMENT. Eg:
4833 alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
4835 ; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
4836 Also note that REPLACEMENT continues to the end of line (or on command
4838 line, to end of option argument), so it can contain trailing white‐
4839 space.
4840 Combining aliases
4842 You can define as many aliases as you like, using journal directives
4843 and/or command line options.
4844 Recursive aliases - where an account name is rewritten by one alias,
4846 then by another alias, and so on - are allowed. Each alias sees the
4847 effect of previously applied aliases.
4848 In such cases it can be important to understand which aliases will be
4850 applied and in which order. For (each account name in) each journal
4851 entry, we apply:
4852 1. alias directives preceding the journal entry, most recently parsed
4854 first (ie, reading upward from the journal entry, bottom to top)
4855 2. --alias options, in the order they appeared on the command line
4857 (left to right).
4858 In other words, for (an account name in) a given journal entry:
4860 • the nearest alias declaration before/above the entry is applied first
4862 • the next alias before/above that will be be applied next, and so on
4864 • aliases defined after/below the entry do not affect it.
4866 This gives nearby aliases precedence over distant ones, and helps pro‐
4868 vide semantic stability - aliases will keep working the same way inde‐
4869 pendent of which files are being read and in which order.
4870 In case of trouble, adding --debug=6 to the command line will show
4872 which aliases are being applied when.
4873 Aliases and multiple files
4875 As explained at Directives and multiple files, alias directives do not
4876 affect parent or sibling files. Eg in this command,
4877 hledger -f a.aliases -f b.journal
4879 account aliases defined in a.aliases will not affect b.journal. In‐
4881 cluding the aliases doesn't work either:
4882 include a.aliases
4884 2020-01-01 ; not affected by a.aliases
4886 foo 1
4887 bar
4888 This means that account aliases should usually be declared at the start
4890 of your top-most file, like this:
4891 alias foo=Foo
4893 alias bar=Bar
4894 2020-01-01 ; affected by aliases above
4896 foo 1
4897 bar
4898 include c.journal ; also affected
4900 end aliases
4902 You can clear (forget) all currently defined aliases with the end
4903 aliases directive:
4904 end aliases
4906 Default parent account
4908 You can specify a parent account which will be prepended to all ac‐
4909 counts within a section of the journal. Use the apply account and end
4910 apply account directives like so:
4911 apply account home
4913 2010/1/1
4915 food $10
4916 cash
4917 end apply account
4919 which is equivalent to:
4921 2010/01/01
4923 home:food $10
4924 home:cash $-10
4925 If end apply account is omitted, the effect lasts to the end of the
4927 file. Included files are also affected, eg:
4928 apply account business
4930 include biz.journal
4931 end apply account
4932 apply account personal
4933 include personal.journal
4934 Prior to hledger 1.0, legacy account and end spellings were also sup‐
4936 ported.
4937 A default parent account also affects account directives. It does not
4939 affect account names being entered via hledger add or hledger-web. If
4940 account aliases are present, they are applied after the default parent
4941 account.
4942 Periodic transactions
4944 Periodic transaction rules describe transactions that recur. They al‐
4945 low hledger to generate temporary future transactions to help with
4946 forecasting, so you don't have to write out each one in the journal,
4947 and it's easy to try out different forecasts.
4948 Periodic transactions can be a little tricky, so before you use them,
4950 read this whole section - or at least these tips:
4951 1. Two spaces accidentally added or omitted will cause you trouble -
4953 read about this below.
4954 2. For troubleshooting, show the generated transactions with hledger
4956 print --forecast tag:generated or hledger register --forecast
4957 tag:generated.
4958 3. Forecasted transactions will begin only after the last non-fore‐
4960 casted transaction's date.
4961 4. Forecasted transactions will end 6 months from today, by default.
4963 See below for the exact start/end rules.
4964 5. period expressions can be tricky. Their documentation needs im‐
4966 provement, but is worth studying.
4967 6. Some period expressions with a repeating interval must begin on a
4969 natural boundary of that interval. Eg in weekly from DATE, DATE
4970 must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
4971 error.
4972 7. Other period expressions with an interval are automatically expanded
4974 to cover a whole number of that interval. (This is done to improve
4975 reports, but it also affects periodic transactions. Yes, it's a bit
4976 inconsistent with the above.) Eg: ~ every 10th day of month from
4977 2020/01, which is equivalent to ~ every 10th day of month from
4978 2020/01/01, will be adjusted to start on 2019/12/10.
4979 Periodic transaction rules also have a second meaning: they are used to
4981 define budget goals, shown in budget reports.
4982 Periodic rule syntax
4984 A periodic transaction rule looks like a normal journal entry, with the
4985 date replaced by a tilde (~) followed by a period expression (mnemonic:
4986 ~ looks like a recurring sine wave.):
4987 ~ monthly
4989 expenses:rent $2000
4990 assets:bank:checking
4991 There is an additional constraint on the period expression: the start
4993 date must fall on a natural boundary of the interval. Eg monthly from
4994 2018/1/1 is valid, but monthly from 2018/1/15 is not.
4995 Partial or relative dates (M/D, D, tomorrow, last week) in the period
4997 expression can work (useful or not). They will be relative to today's
4998 date, unless a Y default year directive is in effect, in which case
4999 they will be relative to Y/1/1.
5000 Two spaces between period expression and description!
5002 If the period expression is followed by a transaction description,
5003 these must be separated by two or more spaces. This helps hledger know
5004 where the period expression ends, so that descriptions can not acciden‐
5005 tally alter their meaning, as in this example:
5006 ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"
5008 ; ||
5009 ; vv
5010 ~ every 2 months in 2020, we will review
5011 assets:bank:checking $1500
5012 income:acme inc
5013 So,
5015 • Do write two spaces between your period expression and your transac‐
5017 tion description, if any.
5018 • Don't accidentally write two spaces in the middle of your period ex‐
5020 pression.
5021 Forecasting with periodic transactions
5023 The --forecast flag activates any periodic transaction rules in the
5024 journal. They will generate temporary recurring transactions, which
5025 are not saved in the journal, but will appear in all reports (eg
5026 print). This can be useful for estimating balances into the future, or
5027 experimenting with different scenarios. Or, it can be used as a data
5028 entry aid: describe recurring transactions, and every so often copy the
5029 output of print --forecast into the journal.
5030 These transactions will have an extra tag indicating which periodic
5032 rule generated them: generated-transaction:~ PERIODICEXPR. And a simi‐
5033 lar, hidden tag (beginning with an underscore) which, because it's
5034 never displayed by print, can be used to match transactions generated
5035 "just now": _generated-transaction:~ PERIODICEXPR.
5036 Periodic transactions are generated within some forecast period. By
5038 default, this
5039 • begins on the later of
5041 • the report start date if specified with -b/-p/date:
5043 • the day after the latest normal (non-periodic) transaction in the
5045 journal, or today if there are no normal transactions.
5046 • ends on the report end date if specified with -e/-p/date:, or 6
5048 months (180 days) from today.
5049 This means that periodic transactions will begin only after the latest
5051 recorded transaction. And a recorded transaction dated in the future
5052 can prevent generation of periodic transactions. (You can avoid that
5053 by writing the future transaction as a one-time periodic rule instead -
5054 put tilde before the date, eg ~ YYYY-MM-DD ...).
5055 Or, you can set your own arbitrary "forecast period", which can overlap
5057 recorded transactions, and need not be in the future, by providing an
5058 option argument, like --forecast=PERIODEXPR. Note the equals sign is
5059 required, a space won't work. PERIODEXPR is a period expression, which
5060 can specify the start date, end date, or both, like in a date: query.
5061 (See also hledger.1 -> Report start & end date). Some examples:
5062 --forecast=202001-202004, --forecast=jan-, --forecast=2020.
5063 Budgeting with periodic transactions
5065 With the --budget flag, currently supported by the balance command,
5066 each periodic transaction rule declares recurring budget goals for the
5067 specified accounts. Eg the first example above declares a goal of
5068 spending $2000 on rent (and also, a goal of depositing $2000 into
5069 checking) every month. Goals and actual performance can then be com‐
5070 pared in budget reports.
5071 See also: Budgeting and Forecasting.
5073 Auto postings
5075 "Automated postings" or "auto postings" are extra postings which get
5076 added automatically to transactions which match certain queries, de‐
5077 fined by "auto posting rules", when you use the --auto flag.
5078 An auto posting rule looks a bit like a transaction:
5080 = QUERY
5082 ACCOUNT AMOUNT
5083 ...
5084 ACCOUNT [AMOUNT]
5085 except the first line is an equals sign (mnemonic: = suggests match‐
5087 ing), followed by a query (which matches existing postings), and each
5088 "posting" line describes a posting to be generated, and the posting
5089 amounts can be:
5090 • a normal amount with a commodity symbol, eg $2. This will be used
5092 as-is.
5093 • a number, eg 2. The commodity symbol (if any) from the matched post‐
5095 ing will be added to this.
5096 • a numeric multiplier, eg *2 (a star followed by a number N). The
5098 matched posting's amount (and total price, if any) will be multiplied
5099 by N.
5100 • a multiplier with a commodity symbol, eg *$2 (a star, number N, and
5102 symbol S). The matched posting's amount will be multiplied by N, and
5103 its commodity symbol will be replaced with S.
5104 Any query term containing spaces must be enclosed in single or double
5106 quotes, as on the command line. Eg, note the quotes around the second
5107 query term below:
5108 = expenses:groceries 'expenses:dining out'
5110 (budget:funds:dining out) *-1
5111 Some examples:
5113 ; every time I buy food, schedule a dollar donation
5115 = expenses:food
5116 (liabilities:charity) $-1
5117 ; when I buy a gift, also deduct that amount from a budget envelope subaccount
5119 = expenses:gifts
5120 assets:checking:gifts *-1
5121 assets:checking *1
5122 2017/12/1
5124 expenses:food $10
5125 assets:checking
5126 2017/12/14
5128 expenses:gifts $20
5129 assets:checking
5130 $ hledger print --auto
5132 2017-12-01
5133 expenses:food $10
5134 assets:checking
5135 (liabilities:charity) $-1
5136 2017-12-14
5138 expenses:gifts $20
5139 assets:checking
5140 assets:checking:gifts -$20
5141 assets:checking $20
5142 Auto postings and multiple files
5144 An auto posting rule can affect any transaction in the current file, or
5145 in any parent file or child file. Note, currently it will not affect
5146 sibling files (when multiple -f/--file are used - see #1212).
5147 Auto postings and dates
5149 A posting date (or secondary date) in the matched posting, or (taking
5150 precedence) a posting date in the auto posting rule itself, will also
5151 be used in the generated posting.
5152 Auto postings and transaction balancing / inferred amounts / balance asser‐
5154 tions
5155 Currently, auto postings are added:
5156 • after missing amounts are inferred, and transactions are checked for
5158 balancedness,
5159 • but before balance assertions are checked.
5161 Note this means that journal entries must be balanced both before and
5163 after auto postings are added. This changed in hledger 1.12+; see #893
5164 for background.
5165 Auto posting tags
5167 Automated postings will have some extra tags:
5168 • generated-posting:= QUERY - shows this was generated by an auto post‐
5170 ing rule, and the query
5171 • _generated-posting:= QUERY - a hidden tag, which does not appear in
5173 hledger's output. This can be used to match postings generated "just
5174 now", rather than generated in the past and saved to the journal.
5175 Also, any transaction that has been changed by auto posting rules will
5177 have these tags added:
5178 • modified: - this transaction was modified
5180 • _modified: - a hidden tag not appearing in the comment; this transac‐
5182 tion was modified "just now".
5183
5185 How hledger reads CSV data, and the CSV rules file format.
5186 hledger can read CSV files (Character Separated Value - usually comma,
5188 semicolon, or tab) containing dated records as if they were journal
5189 files, automatically converting each CSV record into a transaction.
5190 (To learn about writing CSV, see CSV output.)
5192 We describe each CSV file's format with a corresponding rules file. By
5194 default this is named like the CSV file with a .rules extension added.
5195 Eg when reading FILE.csv, hledger also looks for FILE.csv.rules in the
5196 same directory as FILE.csv. You can specify a different rules file
5197 with the --rules-file option. If a rules file is not found, hledger
5198 will create a sample rules file, which you'll need to adjust.
5199 This file contains rules describing the CSV data (header line, fields
5201 layout, date format etc.), and how to construct hledger journal entries
5202 (transactions) from it. Often there will also be a list of conditional
5203 rules for categorising transactions based on their descriptions.
5204 Here's an overview of the CSV rules; these are described more fully be‐
5205 low, after the examples:
5206 skip skip one or more header lines or matched
5208 CSV records
5209 fields name CSV fields, assign them to hledger
5210 fields
5211 field assignment assign a value to one hledger field,
5212 with interpolation
5213 separator a custom field separator
5214 if block apply some rules to CSV records matched
5215 by patterns
5216 if table apply some rules to CSV records matched
5217 by patterns, alternate syntax
5218 end skip the remaining CSV records
5219 date-format how to parse dates in CSV records
5220 decimal-mark the decimal mark used in CSV amounts, if
5221 ambiguous
5222 newest-first disambiguate record order when there's
5223 only one date
5224 include inline another CSV rules file
5225 balance-type choose which type of balance assignments
5226 to use
5227 Note, for best error messages when reading CSV files, use a .csv, .tsv
5229 or .ssv file extension or file prefix - see File Extension below.
5230 There's an introductory Convert CSV files tutorial on hledger.org.
5232 Examples
5234 Here are some sample hledger CSV rules files. See also the full col‐
5235 lection at:
5236 https://github.com/simonmichael/hledger/tree/master/examples/csv
5237 Basic
5239 At minimum, the rules file must identify the date and amount fields,
5240 and often it also specifies the date format and how many header lines
5241 there are. Here's a simple CSV file and a rules file for it:
5242 Date, Description, Id, Amount
5244 12/11/2019, Foo, 123, 10.23
5245 # basic.csv.rules
5247 skip 1
5248 fields date, description, _, amount
5249 date-format %d/%m/%Y
5250 $ hledger print -f basic.csv
5252 2019-11-12 Foo
5253 expenses:unknown 10.23
5254 income:unknown -10.23
5255 Default account names are chosen, since we didn't set them.
5257 Bank of Ireland
5259 Here's a CSV with two amount fields (Debit and Credit), and a balance
5260 field, which we can use to add balance assertions, which is not neces‐
5261 sary but provides extra error checking:
5262 Date,Details,Debit,Credit,Balance
5264 07/12/2012,LODGMENT 529898,,10.0,131.21
5265 07/12/2012,PAYMENT,5,,126
5266 # bankofireland-checking.csv.rules
5268 # skip the header line
5270 skip
5271 # name the csv fields, and assign some of them as journal entry fields
5273 fields date, description, amount-out, amount-in, balance
5274 # We generate balance assertions by assigning to "balance"
5276 # above, but you may sometimes need to remove these because:
5277 #
5278 # - the CSV balance differs from the true balance,
5279 # by up to 0.0000000000005 in my experience
5280 #
5281 # - it is sometimes calculated based on non-chronological ordering,
5282 # eg when multiple transactions clear on the same day
5283 # date is in UK/Ireland format
5285 date-format %d/%m/%Y
5286 # set the currency
5288 currency EUR
5289 # set the base account for all txns
5291 account1 assets:bank:boi:checking
5292 $ hledger -f bankofireland-checking.csv print
5294 2012-12-07 LODGMENT 529898
5295 assets:bank:boi:checking EUR10.0 = EUR131.2
5296 income:unknown EUR-10.0
5297 2012-12-07 PAYMENT
5299 assets:bank:boi:checking EUR-5.0 = EUR126.0
5300 expenses:unknown EUR5.0
5301 The balance assertions don't raise an error above, because we're read‐
5303 ing directly from CSV, but they will be checked if these entries are
5304 imported into a journal file.
5305 Amazon
5307 Here we convert amazon.com order history, and use an if block to gener‐
5308 ate a third posting if there's a fee. (In practice you'd probably get
5309 this data from your bank instead, but it's an example.)
5310 "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
5312 "Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"
5313 "Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"
5314 # amazon-orders.csv.rules
5316 # skip one header line
5318 skip 1
5319 # name the csv fields, and assign the transaction's date, amount and code.
5321 # Avoided the "status" and "amount" hledger field names to prevent confusion.
5322 fields date, _, toorfrom, name, amzstatus, amzamount, fees, code
5323 # how to parse the date
5325 date-format %b %-d, %Y
5326 # combine two fields to make the description
5328 description %toorfrom %name
5329 # save the status as a tag
5331 comment status:%amzstatus
5332 # set the base account for all transactions
5334 account1 assets:amazon
5335 # leave amount1 blank so it can balance the other(s).
5336 # I'm assuming amzamount excludes the fees, don't remember
5337 # set a generic account2
5339 account2 expenses:misc
5340 amount2 %amzamount
5341 # and maybe refine it further:
5342 #include categorisation.rules
5343 # add a third posting for fees, but only if they are non-zero.
5345 if %fees [1-9]
5346 account3 expenses:fees
5347 amount3 %fees
5348 $ hledger -f amazon-orders.csv print
5350 2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed
5351 assets:amazon
5352 expenses:misc $20.00
5353 2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed
5355 assets:amazon
5356 expenses:misc $25.00
5357 expenses:fees $1.00
5358 Paypal
5360 Here's a real-world rules file for (customised) Paypal CSV, with some
5361 Paypal-specific rules, and a second rules file included:
5362 "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"
5364 "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",""
5365 "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",""
5366 "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",""
5367 "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",""
5368 "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",""
5369 "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",""
5370 "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",""
5371 # paypal-custom.csv.rules
5373 # Tips:
5375 # Export from Activity -> Statements -> Custom -> Activity download
5376 # Suggested transaction type: "Balance affecting"
5377 # Paypal's default fields in 2018 were:
5378 # "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"
5379 # This rules file assumes the following more detailed fields, configured in "Customize report fields":
5380 # "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"
5381 fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note
5383 skip 1
5385 date-format %-m/%-d/%Y
5387 # ignore some paypal events
5389 if
5390 In Progress
5391 Temporary Hold
5392 Update to
5393 skip
5394 # add more fields to the description
5396 description %description_ %itemtitle
5397 # save some other fields as tags
5399 comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
5400 # convert to short currency symbols
5402 if %currency USD
5403 currency $
5404 if %currency EUR
5405 currency E
5406 if %currency GBP
5407 currency P
5408 # generate postings
5410 # the first posting will be the money leaving/entering my paypal account
5412 # (negative means leaving my account, in all amount fields)
5413 account1 assets:online:paypal
5414 amount1 %netamount
5415 # the second posting will be money sent to/received from other party
5417 # (account2 is set below)
5418 amount2 -%grossamount
5419 # if there's a fee, add a third posting for the money taken by paypal.
5421 if %feeamount [1-9]
5422 account3 expenses:banking:paypal
5423 amount3 -%feeamount
5424 comment3 business:
5425 # choose an account for the second posting
5427 # override the default account names:
5429 # if the amount is positive, it's income (a debit)
5430 if %grossamount ^[^-]
5431 account2 income:unknown
5432 # if negative, it's an expense (a credit)
5433 if %grossamount ^-
5434 account2 expenses:unknown
5435 # apply common rules for setting account2 & other tweaks
5437 include common.rules
5438 # apply some overrides specific to this csv
5440 # Transfers from/to bank. These are usually marked Pending,
5442 # which can be disregarded in this case.
5443 if
5444 Bank Account
5445 Bank Deposit to PP Account
5446 description %type for %referencetxnid %itemtitle
5447 account2 assets:bank:wf:pchecking
5448 account1 assets:online:paypal
5449 # Currency conversions
5451 if Currency Conversion
5452 account2 equity:currency conversion
5453 # common.rules
5455 if
5457 darcs
5458 noble benefactor
5459 account2 revenues:foss donations:darcshub
5460 comment2 business:
5461 if
5463 Calm Radio
5464 account2 expenses:online:apps
5465 if
5467 electronic frontier foundation
5468 Patreon
5469 wikimedia
5470 Advent of Code
5471 account2 expenses:dues
5472 if Google
5474 account2 expenses:online:apps
5475 description google | music
5476 $ hledger -f paypal-custom.csv print
5478 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
5479 assets:online:paypal $-6.99 = $-6.99
5480 expenses:online:apps $6.99
5481 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
5483 assets:online:paypal $6.99 = $0.00
5484 assets:bank:wf:pchecking $-6.99
5485 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
5487 assets:online:paypal $-7.00 = $-7.00
5488 expenses:dues $7.00
5489 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
5491 assets:online:paypal $7.00 = $0.00
5492 assets:bank:wf:pchecking $-7.00
5493 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
5495 assets:online:paypal $-2.00 = $-2.00
5496 expenses:dues $2.00
5497 expenses:banking:paypal ; business:
5498 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
5500 assets:online:paypal $2.00 = $0.00
5501 assets:bank:wf:pchecking $-2.00
5502 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
5504 assets:online:paypal $9.41 = $9.41
5505 revenues:foss donations:darcshub $-10.00 ; business:
5506 expenses:banking:paypal $0.59 ; business:
5507 CSV rules
5509 The following kinds of rule can appear in the rules file, in any order.
5510 Blank lines and lines beginning with # or ; are ignored.
5511 skip
5513 skip N
5514 The word "skip" followed by a number (or no number, meaning 1) tells
5516 hledger to ignore this many non-empty lines preceding the CSV data.
5517 (Empty/blank lines are skipped automatically.) You'll need this when‐
5518 ever your CSV data contains header lines.
5519 It also has a second purpose: it can be used inside if blocks to ignore
5521 certain CSV records (described below).
5522 fields
5524 fields FIELDNAME1, FIELDNAME2, ...
5525 A fields list (the word "fields" followed by comma-separated field
5527 names) is the quick way to assign CSV field values to hledger fields.
5528 It does two things:
5529 1. it names the CSV fields. This is optional, but can be convenient
5531 later for interpolating them.
5532 2. when you use a standard hledger field name, it assigns the CSV value
5534 to that part of the hledger transaction.
5535 Here's an example that says "use the 1st, 2nd and 4th fields as the
5537 transaction's date, description and amount; name the last two fields
5538 for later reference; and ignore the others":
5539 fields date, description, , amount, , , somefield, anotherfield
5541 Field names may not contain whitespace. Fields you don't care about
5543 can be left unnamed. Currently there must be least two items (there
5544 must be at least one comma).
5545 Note, always use comma in the fields list, even if your CSV uses an‐
5547 other separator character.
5548 Here are the standard hledger field/pseudo-field names. For more about
5550 the transaction parts they refer to, see the manual for hledger's jour‐
5551 nal format.
5552 Transaction field names
5554 date, date2, status, code, description, comment can be used to form the
5555 transaction's first line.
5556 Posting field names
5558 account
5559 accountN, where N is 1 to 99, causes a posting to be generated, with
5560 that account name.
5561 Most often there are two postings, so you'll want to set account1 and
5563 account2. Typically account1 is associated with the CSV file, and is
5564 set once with a top-level assignment, while account2 is set based on
5565 each transaction's description, and in conditional blocks.
5566 If a posting's account name is left unset but its amount is set (see
5568 below), a default account name will be chosen (like "expenses:unknown"
5569 or "income:unknown").
5570 amount
5572 amountN sets posting N's amount. If the CSV uses separate fields for
5573 inflows and outflows, you can use amountN-in and amountN-out instead.
5574 By assigning to amount1, amount2, ... etc. you can generate anywhere
5575 from 0 to 99 postings.
5576 There is also an older, unnumbered form of these names, suitable for
5578 2-posting transactions, which sets both posting 1's and (negated) post‐
5579 ing 2's amount: amount, or amount-in and amount-out. This is still
5580 supported because it keeps pre-hledger-1.17 csv rules files working,
5581 and because it can be more succinct, and because it converts posting
5582 2's amount to cost if there's a transaction price, which can be useful.
5583 If you have an existing rules file using the unnumbered form, you might
5585 want to use the numbered form in certain conditional blocks, without
5586 having to update and retest all the old rules. To facilitate this,
5587 posting 1 ignores amount/amount-in/amount-out if any of
5588 amount1/amount1-in/amount1-out are assigned, and posting 2 ignores them
5589 if any of amount2/amount2-in/amount2-out are assigned, avoiding con‐
5590 flicts.
5591 currency
5593 If the CSV has the currency symbol in a separate field (ie, not part of
5594 the amount field), you can use currencyN to prepend it to posting N's
5595 amount. Or, currency with no number affects all postings.
5596 balance
5598 balanceN sets a balance assertion amount (or if the posting amount is
5599 left empty, a balance assignment) on posting N.
5600 Also, for compatibility with hledger <1.17: balance with no number is
5602 equivalent to balance1.
5603 You can adjust the type of assertion/assignment with the balance-type
5605 rule (see below).
5606 comment
5608 Finally, commentN sets a comment on the Nth posting. Comments can also
5609 contain tags, as usual.
5610 See TIPS below for more about setting amounts and currency.
5612 field assignment
5614 HLEDGERFIELDNAME FIELDVALUE
5615 Instead of or in addition to a fields list, you can use a "field as‐
5617 signment" rule to set the value of a single hledger field, by writing
5618 its name (any of the standard hledger field names above) followed by a
5619 text value. The value may contain interpolated CSV fields, referenced
5620 by their 1-based position in the CSV record (%N), or by the name they
5621 were given in the fields list (%CSVFIELDNAME). Some examples:
5622 # set the amount to the 4th CSV field, with " USD" appended
5624 amount %4 USD
5625 # combine three fields to make a comment, containing note: and date: tags
5627 comment note: %somefield - %anotherfield, date: %1
5628 Interpolation strips outer whitespace (so a CSV value like " 1 " be‐
5630 comes 1 when interpolated) (#1051). See TIPS below for more about ref‐
5631 erencing other fields.
5632 separator
5634 You can use the separator rule to read other kinds of character-sepa‐
5635 rated data. The argument is any single separator character, or the
5636 words tab or space (case insensitive). Eg, for comma-separated values
5637 (CSV):
5638 separator ,
5640 or for semicolon-separated values (SSV):
5642 separator ;
5644 or for tab-separated values (TSV):
5646 separator TAB
5648 If the input file has a .csv, .ssv or .tsv file extension (or a csv:,
5650 ssv:, tsv: prefix), the appropriate separator will be inferred automat‐
5651 ically, and you won't need this rule.
5652 if block
5654 if MATCHER
5655 RULE
5656 if
5658 MATCHER
5659 MATCHER
5660 MATCHER
5661 RULE
5662 RULE
5663 Conditional blocks ("if blocks") are a block of rules that are applied
5665 only to CSV records which match certain patterns. They are often used
5666 for customising account names based on transaction descriptions.
5667 Matching the whole record
5669 Each MATCHER can be a record matcher, which looks like this:
5670 REGEX
5672 REGEX is a case-insensitive regular expression which tries to match
5674 anywhere within the CSV record. It is a POSIX ERE (extended regular
5675 expression) that also supports GNU word boundaries (\b, \B, \<, \>),
5676 and nothing else. If you have trouble, be sure to check our
5677 https://hledger.org/hledger.html#regular-expressions doc.
5678 Important note: the record that is matched is not the original record,
5680 but a synthetic one, with any enclosing double quotes (but not enclos‐
5681 ing whitespace) removed, and always comma-separated (which means that a
5682 field containing a comma will appear like two fields). Eg, if the
5683 original record is 2020-01-01; "Acme, Inc."; 1,000, the REGEX will ac‐
5684 tually see 2020-01-01,Acme, Inc., 1,000).
5685 Matching individual fields
5687 Or, MATCHER can be a field matcher, like this:
5688 %CSVFIELD REGEX
5690 which matches just the content of a particular CSV field. CSVFIELD is
5692 a percent sign followed by the field's name or column number, like
5693 %date or %1.
5694 Combining matchers
5696 A single matcher can be written on the same line as the "if"; or multi‐
5697 ple matchers can be written on the following lines, non-indented. Mul‐
5698 tiple matchers are OR'd (any one of them can match), unless one begins
5699 with an & symbol, in which case it is AND'ed with the previous matcher.
5700 if
5702 MATCHER
5703 & MATCHER
5704 RULE
5705 Rules applied on successful match
5707 After the patterns there should be one or more rules to apply, all in‐
5708 dented by at least one space. Three kinds of rule are allowed in con‐
5709 ditional blocks:
5710 • field assignments (to set a hledger field)
5712 • skip (to skip the matched CSV record)
5714 • end (to skip all remaining CSV records).
5716 Examples:
5718 # if the CSV record contains "groceries", set account2 to "expenses:groceries"
5720 if groceries
5721 account2 expenses:groceries
5722 # if the CSV record contains any of these patterns, set account2 and comment as shown
5724 if
5725 monthly service fee
5726 atm transaction fee
5727 banking thru software
5728 account2 expenses:business:banking
5729 comment XXX deductible ? check it
5730 if table
5732 if,CSVFIELDNAME1,CSVFIELDNAME2,...,CSVFIELDNAMEn
5733 MATCHER1,VALUE11,VALUE12,...,VALUE1n
5734 MATCHER2,VALUE21,VALUE22,...,VALUE2n
5735 MATCHER3,VALUE31,VALUE32,...,VALUE3n
5736 <empty line>
5737 Conditional tables ("if tables") are a different syntax to specify
5739 field assignments that will be applied only to CSV records which match
5740 certain patterns.
5741 MATCHER could be either field or record matcher, as described above.
5743 When MATCHER matches, values from that row would be assigned to the CSV
5744 fields named on the if line, in the same order.
5745 Therefore if table is exactly equivalent to a sequence of of if blocks:
5747 if MATCHER1
5749 CSVFIELDNAME1 VALUE11
5750 CSVFIELDNAME2 VALUE12
5751 ...
5752 CSVFIELDNAMEn VALUE1n
5753 if MATCHER2
5755 CSVFIELDNAME1 VALUE21
5756 CSVFIELDNAME2 VALUE22
5757 ...
5758 CSVFIELDNAMEn VALUE2n
5759 if MATCHER3
5761 CSVFIELDNAME1 VALUE31
5762 CSVFIELDNAME2 VALUE32
5763 ...
5764 CSVFIELDNAMEn VALUE3n
5765 Each line starting with MATCHER should contain enough (possibly empty)
5767 values for all the listed fields.
5768 Rules would be checked and applied in the order they are listed in the
5770 table and, like with if blocks, later rules (in the same or another ta‐
5771 ble) or if blocks could override the effect of any rule.
5772 Instead of ',' you can use a variety of other non-alphanumeric charac‐
5774 ters as a separator. First character after if is taken to be the sepa‐
5775 rator for the rest of the table. It is the responsibility of the user
5776 to ensure that separator does not occur inside MATCHERs and values -
5777 there is no way to escape separator.
5778 Example:
5780 if,account2,comment
5782 atm transaction fee,expenses:business:banking,deductible? check it
5783 %description groceries,expenses:groceries,
5784 2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
5785 end
5787 This rule can be used inside if blocks (only), to make hledger stop
5788 reading this CSV file and move on to the next input file, or to command
5789 execution. Eg:
5790 # ignore everything following the first empty record
5792 if ,,,,
5793 end
5794 date-format
5796 date-format DATEFMT
5797 This is a helper for the date (and date2) fields. If your CSV dates
5799 are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll
5800 need to add a date-format rule describing them with a strptime date
5801 parsing pattern, which must parse the CSV date value completely. Some
5802 examples:
5803 # MM/DD/YY
5805 date-format %m/%d/%y
5806 # D/M/YYYY
5808 # The - makes leading zeros optional.
5809 date-format %-d/%-m/%Y
5810 # YYYY-Mmm-DD
5812 date-format %Y-%h-%d
5813 # M/D/YYYY HH:MM AM some other junk
5815 # Note the time and junk must be fully parsed, though only the date is used.
5816 date-format %-m/%-d/%Y %l:%M %p some other junk
5817 For the supported strptime syntax, see:
5819 https://hackage.haskell.org/package/time/docs/Data-Time-For‐
5820 mat.html#v:formatTime
5821 decimal-mark
5823 decimal-mark .
5824 or:
5826 decimal-mark ,
5828 hledger automatically accepts either period or comma as a decimal mark
5830 when parsing numbers (cf Amounts). However if any numbers in the CSV
5831 contain digit group marks, such as thousand-separating commas, you
5832 should declare the decimal mark explicitly with this rule, to avoid
5833 misparsed numbers.
5834 newest-first
5836 hledger always sorts the generated transactions by date. Transactions
5837 on the same date should appear in the same order as their CSV records,
5838 as hledger can usually auto-detect whether the CSV's normal order is
5839 oldest first or newest first. But if all of the following are true:
5840 • the CSV might sometimes contain just one day of data (all records
5842 having the same date)
5843 • the CSV records are normally in reverse chronological order (newest
5845 at the top)
5846 • and you care about preserving the order of same-day transactions
5848 then, you should add the newest-first rule as a hint. Eg:
5850 # tell hledger explicitly that the CSV is normally newest first
5852 newest-first
5853 include
5855 include RULESFILE
5856 This includes the contents of another CSV rules file at this point.
5858 RULESFILE is an absolute file path or a path relative to the current
5859 file's directory. This can be useful for sharing common rules between
5860 several rules files, eg:
5861 # someaccount.csv.rules
5863 ## someaccount-specific rules
5865 fields date,description,amount
5866 account1 assets:someaccount
5867 account2 expenses:misc
5868 ## common rules
5870 include categorisation.rules
5871 balance-type
5873 Balance assertions generated by assigning to balanceN are of the simple
5874 = type by default, which is a single-commodity, subaccount-excluding
5875 assertion. You may find the subaccount-including variants more useful,
5876 eg if you have created some virtual subaccounts of checking to help
5877 with budgeting. You can select a different type of assertion with the
5878 balance-type rule:
5879 # balance assertions will consider all commodities and all subaccounts
5881 balance-type ==*
5882 Here are the balance assertion types for quick reference:
5884 = single commodity, exclude subaccounts
5886 =* single commodity, include subaccounts
5887 == multi commodity, exclude subaccounts
5888 ==* multi commodity, include subaccounts
5889 Tips
5891 Rapid feedback
5892 It's a good idea to get rapid feedback while creating/troubleshooting
5893 CSV rules. Here's a good way, using entr from http://eradman.com/entr‐
5894 project :
5895 $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
5897 A desc: query (eg) is used to select just one, or a few, transactions
5899 of interest. "bash -c" is used to run multiple commands, so we can
5900 echo a separator each time the command re-runs, making it easier to
5901 read the output.
5902 Valid CSV
5904 hledger accepts CSV conforming to RFC 4180. When CSV values are en‐
5905 closed in quotes, note:
5906 • they must be double quotes (not single quotes)
5908 • spaces outside the quotes are not allowed
5910 File Extension
5912 To help hledger identify the format and show the right error messages,
5913 CSV/SSV/TSV files should normally be named with a .csv, .ssv or .tsv
5914 filename extension. Or, the file path should be prefixed with csv:,
5915 ssv: or tsv:. Eg:
5916 $ hledger -f foo.ssv print
5918 or:
5920 $ cat foo | hledger -f ssv:- foo
5922 You can override the file extension with a separator rule if needed.
5924 See also: Input files in the hledger manual.
5925 Reading multiple CSV files
5927 If you use multiple -f options to read multiple CSV files at once,
5928 hledger will look for a correspondingly-named rules file for each CSV
5929 file. But if you use the --rules-file option, that rules file will be
5930 used for all the CSV files.
5931 Valid transactions
5933 After reading a CSV file, hledger post-processes and validates the gen‐
5934 erated journal entries as it would for a journal file - balancing them,
5935 applying balance assignments, and canonicalising amount styles. Any
5936 errors at this stage will be reported in the usual way, displaying the
5937 problem entry.
5938 There is one exception: balance assertions, if you have generated them,
5940 will not be checked, since normally these will work only when the CSV
5941 data is part of the main journal. If you do need to check balance as‐
5942 sertions generated from CSV right away, pipe into another hledger:
5943 $ hledger -f file.csv print | hledger -f- print
5945 Deduplicating, importing
5947 When you download a CSV file periodically, eg to get your latest bank
5948 transactions, the new file may overlap with the old one, containing
5949 some of the same records.
5950 The import command will (a) detect the new transactions, and (b) append
5952 just those transactions to your main journal. It is idempotent, so you
5953 don't have to remember how many times you ran it or with which version
5954 of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This
5955 is the easiest way to import CSV data. Eg:
5956 # download the latest CSV files, then run this command.
5958 # Note, no -f flags needed here.
5959 $ hledger import *.csv [--dry]
5960 This method works for most CSV files. (Where records have a stable
5962 chronological order, and new records appear only at the new end.)
5963 A number of other tools and workflows, hledger-specific and otherwise,
5965 exist for converting, deduplicating, classifying and managing CSV data.
5966 See:
5967 • https://hledger.org -> sidebar -> real world setups
5969 • https://plaintextaccounting.org -> data import/conversion
5971 Setting amounts
5973 Some tips on using the amount-setting rules discussed above.
5974 Here are the ways to set a posting's amount:
5976 1. If the CSV has a single amount field:
5978 Assign (via a fields list or a field assignment) to amountN. This sets
5979 the Nth posting's amount. N is usually 1 or 2 but can go up to 99.
5980 2. If the CSV has separate Debit and Credit amount fields:
5982 Assign to amountN-in and amountN-out. This sets posting N's amount to
5983 whichever of these has a non-zero value, guessing an appropriate sign.
5984 • If hledger guesses the wrong sign:
5986 Prepend a minus sign to flip it. Eg:
5987 fields date, description, amount-in, amount-out
5989 amount-out -%amount-out
5990 • If both fields contain a non-zero value:
5992 The amountN-in/amountN-out rules require that each CSV record has a
5993 non-zero value in exactly one of the two fields, so that hledger
5994 knows which to choose. So these would all be rejected:
5995 "", ""
5997 "0", "0"
5998 "1", "none"
5999 If your CSV has amount values like this, use conditional rules
6001 instead. For example, to make hledger to choose the value con‐
6002 taining non-zero digits:
6003 fields date, description, in, out
6005 if %in [1-9]
6006 amount1 %in
6007 if %out [1-9]
6008 amount1 %out
6009 3. Using the old numberless syntax:
6011 Assign to amount (or to amount-in and amount-out). This sets posting
6012 1's and posting 2's amounts (and converts posting 2's amount to cost).
6013 This is supported for backwards compatibility (and occasional conve‐
6014 nience).
6015 4. If the CSV has the balance instead of the transaction amount:
6017 Assign to balanceN, which sets posting N's amount indirectly via a bal‐
6018 ance assignment. (Old syntax: balance, equivalent to balance1.)
6019 • If hledger guesses the wrong default account name:
6021 When setting the amount via balance assertion, hledger may guess
6022 the wrong default account name. So, set the account name explic‐
6023 itly, eg:
6024 fields date, description, balance1
6026 account1 assets:checking
6027 Amount signs
6029 There is some special handling for amount signs, to simplify parsing
6030 and sign-flipping:
6031 • If an amount value begins with a plus sign:
6033 that will be removed: +AMT becomes AMT
6034 • If an amount value is parenthesised:
6036 it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT
6037 • If an amount value has two minus signs (or two sets of parentheses,
6039 or a minus sign and parentheses):
6040 they cancel out and will be removed: --AMT or -(AMT) becomes AMT
6041 • If an amount value contains just a sign (or just a set of parenthe‐
6043 ses):
6044 that is removed, making it an empty value. "+" or "-" or "()" becomes
6045 "".
6046 Setting currency/commodity
6048 If the currency/commodity symbol is included in the CSV's amount
6049 field(s):
6050 2020-01-01,foo,$123.00
6052 you don't have to do anything special for the commodity symbol, it will
6054 be assigned as part of the amount. Eg:
6055 fields date,description,amount
6057 2020-01-01 foo
6059 expenses:unknown $123.00
6060 income:unknown $-123.00
6061 If the currency is provided as a separate CSV field:
6063 2020-01-01,foo,USD,123.00
6065 You can assign that to the currency pseudo-field, which has the special
6067 effect of prepending itself to every amount in the transaction (on the
6068 left, with no separating space):
6069 fields date,description,currency,amount
6071 2020-01-01 foo
6073 expenses:unknown USD123.00
6074 income:unknown USD-123.00
6075 Or, you can use a field assignment to construct the amount yourself,
6077 with more control. Eg to put the symbol on the right, and separated by
6078 a space:
6079 fields date,description,cur,amt
6081 amount %amt %cur
6082 2020-01-01 foo
6084 expenses:unknown 123.00 USD
6085 income:unknown -123.00 USD
6086 Note we used a temporary field name (cur) that is not currency - that
6088 would trigger the prepending effect, which we don't want here.
6089 Amount decimal places
6091 Like amounts in a journal file, the amounts generated by CSV rules like
6092 amount1 influence commodity display styles, such as the number of deci‐
6093 mal places displayed in reports.
6094 The original amounts as written in the CSV file do not affect display
6096 style (because we don't yet reliably know their commodity).
6097 Referencing other fields
6099 In field assignments, you can interpolate only CSV fields, not hledger
6100 fields. In the example below, there's both a CSV field and a hledger
6101 field named amount1, but %amount1 always means the CSV field, not the
6102 hledger field:
6103 # Name the third CSV field "amount1"
6105 fields date,description,amount1
6106 # Set hledger's amount1 to the CSV amount1 field followed by USD
6108 amount1 %amount1 USD
6109 # Set comment to the CSV amount1 (not the amount1 assigned above)
6111 comment %amount1
6112 Here, since there's no CSV amount1 field, %amount1 will produce a lit‐
6114 eral "amount1":
6115 fields date,description,csvamount
6117 amount1 %csvamount USD
6118 # Can't interpolate amount1 here
6119 comment %amount1
6120 When there are multiple field assignments to the same hledger field,
6122 only the last one takes effect. Here, comment's value will be be B, or
6123 C if "something" is matched, but never A:
6124 comment A
6126 comment B
6127 if something
6128 comment C
6129 How CSV rules are evaluated
6131 Here's how to think of CSV rules being evaluated (if you really need
6132 to). First,
6133 • include - all includes are inlined, from top to bottom, depth first.
6135 (At each include point the file is inlined and scanned for further
6136 includes, recursively, before proceeding.)
6137 Then "global" rules are evaluated, top to bottom. If a rule is re‐
6139 peated, the last one wins:
6140 • skip (at top level)
6142 • date-format
6144 • newest-first
6146 • fields - names the CSV fields, optionally sets up initial assignments
6148 to hledger fields
6149 Then for each CSV record in turn:
6151 • test all if blocks. If any of them contain a end rule, skip all re‐
6153 maining CSV records. Otherwise if any of them contain a skip rule,
6154 skip that many CSV records. If there are multiple matched skip
6155 rules, the first one wins.
6156 • collect all field assignments at top level and in matched if blocks.
6158 When there are multiple assignments for a field, keep only the last
6159 one.
6160 • compute a value for each hledger field - either the one that was as‐
6162 signed to it (and interpolate the %CSVFIELDNAME references), or a de‐
6163 fault
6164 • generate a synthetic hledger transaction from these values.
6166 This is all part of the CSV reader, one of several readers hledger can
6168 use to parse input files. When all files have been read successfully,
6169 the transactions are passed as input to whichever hledger command the
6170 user specified.
6171
6173 The time logging format of timeclock.el, as read by hledger.
6174 hledger can read time logs in timeclock format. As with Ledger, these
6176 are (a subset of) timeclock.el's format, containing clock-in and clock-
6177 out entries as in the example below. The date is a simple date. The
6178 time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional.
6179 The timezone, if present, must be four digits and is ignored (currently
6180 the time is always interpreted as a local time).
6181 i 2015/03/30 09:00:00 some:account name optional description after two spaces
6183 o 2015/03/30 09:20:00
6184 i 2015/03/31 22:21:45 another account
6185 o 2015/04/01 02:00:34
6186 hledger treats each clock-in/clock-out pair as a transaction posting
6188 some number of hours to an account. Or if the session spans more than
6189 one day, it is split into several transactions, one for each day. For
6190 the above time log, hledger print generates these journal entries:
6191 $ hledger -f t.timeclock print
6193 2015-03-30 * optional description after two spaces
6194 (some:account name) 0.33h
6195 2015-03-31 * 22:21-23:59
6197 (another account) 1.64h
6198 2015-04-01 * 00:00-02:00
6200 (another account) 2.01h
6201 Here is a sample.timeclock to download and some queries to try:
6203 $ hledger -f sample.timeclock balance # current time balances
6205 $ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009
6206 $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week
6207 To generate time logs, ie to clock in and clock out, you could:
6209 • use emacs and the built-in timeclock.el, or the extended timeclock-
6211 x.el and perhaps the extras in ledgerutils.el
6212 • at the command line, use these bash aliases: shell alias ti="echo
6214 i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o
6215 `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
6216 • or use the old ti and to scripts in the ledger 2.x repository. These
6218 rely on a "timeclock" executable which I think is just the ledger 2
6219 executable renamed.
6220
6222 hledger's human-friendly time logging format.
6223 Timedot is a plain text format for logging dated, categorised quanti‐
6225 ties (of time, usually), supported by hledger. It is convenient for
6226 approximate and retroactive time logging, eg when the real-time clock-
6227 in/out required with a timeclock file is too precise or too interrup‐
6228 tive. It can be formatted like a bar chart, making clear at a glance
6229 where time was spent.
6230 Though called "timedot", this format is read by hledger as commodity‐
6232 less quantities, so it could be used to represent dated quantities
6233 other than time. In the docs below we'll assume it's time.
6234 A timedot file contains a series of day entries. A day entry begins
6236 with a non-indented hledger-style simple date (Y-M-D, Y/M/D, Y.M.D..)
6237 Any additional text on the same line is used as a transaction descrip‐
6238 tion for this day.
6239 This is followed by optionally-indented timelog items for that day, one
6241 per line. Each timelog item is a note, usually a hledger:style:ac‐
6242 count:name representing a time category, followed by two or more spa‐
6243 ces, and a quantity. Each timelog item generates a hledger transac‐
6244 tion.
6245 Quantities can be written as:
6247 • dots: a sequence of dots (.) representing quarter hours. Spaces may
6249 optionally be used for grouping. Eg: .... ..
6250 • an integral or decimal number, representing hours. Eg: 1.5
6252 • an integral or decimal number immediately followed by a unit symbol
6254 s, m, h, d, w, mo, or y, representing seconds, minutes, hours, days
6255 weeks, months or years respectively. Eg: 90m. The following equiva‐
6256 lencies are assumed, currently: 1m = 60s, 1h = 60m, 1d = 24h, 1w =
6257 7d, 1mo = 30d, 1y=365d.
6258 There is some flexibility allowing notes and todo lists to be kept
6260 right in the time log, if needed:
6261 • Blank lines and lines beginning with # or ; are ignored.
6263 • Lines not ending with a double-space and quantity are parsed as items
6265 taking no time, which will not appear in balance reports by default.
6266 (Add -E to see them.)
6267 • Org mode headlines (lines beginning with one or more * followed by a
6269 space) can be used as date lines or timelog items (the stars are ig‐
6270 nored). Also all org headlines before the first date line are ig‐
6271 nored. This means org users can manage their timelog as an org out‐
6272 line (eg using org-mode/orgstruct-mode in Emacs), for organisation,
6273 faster navigation, controlling visibility etc.
6274 Examples:
6276 # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
6278 2016/2/1
6279 inc:client1 .... .... .... .... .... ....
6280 fos:haskell .... ..
6281 biz:research .
6282 2016/2/2
6284 inc:client1 .... ....
6285 biz:research .
6286 2016/2/3
6288 inc:client1 4
6289 fos:hledger 3
6290 biz:research 1
6291 * Time log
6293 ** 2020-01-01
6294 *** adm:time .
6295 *** adm:finance .
6296 * 2020 Work Diary
6298 ** Q1
6299 *** 2020-02-29
6300 **** DONE
6301 0700 yoga
6302 **** UNPLANNED
6303 **** BEGUN
6304 hom:chores
6305 cleaning ...
6306 water plants
6307 outdoor - one full watering can
6308 indoor - light watering
6309 **** TODO
6310 adm:planning: trip
6311 *** LATER
6312 Reporting:
6314 $ hledger -f t.timedot print date:2016/2/2
6316 2016-02-02 *
6317 (inc:client1) 2.00
6318 2016-02-02 *
6320 (biz:research) 0.25
6321 $ hledger -f t.timedot bal --daily --tree
6323 Balance changes in 2016-02-01-2016-02-03:
6324 || 2016-02-01d 2016-02-02d 2016-02-03d
6326 ============++========================================
6327 biz || 0.25 0.25 1.00
6328 research || 0.25 0.25 1.00
6329 fos || 1.50 0 3.00
6330 haskell || 1.50 0 0
6331 hledger || 0 0 3.00
6332 inc || 6.00 2.00 4.00
6333 client1 || 6.00 2.00 4.00
6334 ------------++----------------------------------------
6335 || 7.75 2.25 8.00
6336 I prefer to use period for separating account components. We can make
6338 this work with an account alias:
6339 2016/2/4
6341 fos.hledger.timedot 4
6342 fos.ledger ..
6343 $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4 --tree
6345 4.50 fos
6346 4.00 hledger:timedot
6347 0.50 ledger
6348 --------------------
6349 4.50
6350 Here is a sample.timedot.
6352
6354 Here are some quick examples of how to do some basic tasks with
6355 hledger. For more details, see the reference section below, the
6356 hledger_journal(5) manual, or the more extensive docs at
6357 https://hledger.org.
6358 Getting help
6360 $ hledger # show available commands
6361 $ hledger --help # show common options
6362 $ hledger CMD --help # show common and command options, and command help
6363 $ hledger help # show available manuals/topics
6364 $ hledger help hledger # show hledger manual as info/man/text (auto-chosen)
6365 $ hledger help journal --man # show the journal manual as a man page
6366 $ hledger help --help # show more detailed help for the help command
6367 Find more docs, chat, mail list, reddit, issue tracker:
6369 https://hledger.org#help-feedback
6370 Constructing command lines
6372 hledger has an extensive and powerful command line interface. We
6373 strive to keep it simple and ergonomic, but you may run into one of the
6374 confusing real world details described in OPTIONS, below. If that hap‐
6375 pens, here are some tips that may help:
6376 • command-specific options must go after the command (it's fine to put
6378 all options there) (hledger CMD OPTS ARGS)
6379 • running add-on executables directly simplifies command line parsing
6381 (hledger-ui OPTS ARGS)
6382 • enclose "problematic" args in single quotes
6384 • if needed, also add a backslash to hide regular expression metachar‐
6386 acters from the shell
6387 • to see how a misbehaving command is being parsed, add --debug=2.
6389 Starting a journal file
6391 hledger looks for your accounting data in a journal file,
6392 $HOME/.hledger.journal by default:
6393 $ hledger stats
6395 The hledger journal file "/Users/simon/.hledger.journal" was not found.
6396 Please create it first, eg with "hledger add" or a text editor.
6397 Or, specify an existing journal file with -f or LEDGER_FILE.
6398 You can override this by setting the LEDGER_FILE environment variable.
6400 It's a good practice to keep this important file under version control,
6401 and to start a new file each year. So you could do something like
6402 this:
6403 $ mkdir ~/finance
6405 $ cd ~/finance
6406 $ git init
6407 Initialized empty Git repository in /Users/simon/finance/.git/
6408 $ touch 2020.journal
6409 $ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc
6410 $ source ~/.bashrc
6411 $ hledger stats
6412 Main file : /Users/simon/finance/2020.journal
6413 Included files :
6414 Transactions span : to (0 days)
6415 Last transaction : none
6416 Transactions : 0 (0.0 per day)
6417 Transactions last 30 days: 0 (0.0 per day)
6418 Transactions last 7 days : 0 (0.0 per day)
6419 Payees/descriptions : 0
6420 Accounts : 0 (depth 0)
6421 Commodities : 0 ()
6422 Market prices : 0 ()
6423 Setting opening balances
6425 Pick a starting date for which you can look up the balances of some
6426 real-world assets (bank accounts, wallet..) and liabilities (credit
6427 cards..).
6428 To avoid a lot of data entry, you may want to start with just one or
6430 two accounts, like your checking account or cash wallet; and pick a re‐
6431 cent starting date, like today or the start of the week. You can al‐
6432 ways come back later and add more accounts and older transactions, eg
6433 going back to january 1st.
6434 Add an opening balances transaction to the journal, declaring the bal‐
6436 ances on this date. Here are two ways to do it:
6437 • The first way: open the journal in any text editor and save an entry
6439 like this:
6440 2020-01-01 * opening balances
6442 assets:bank:checking $1000 = $1000
6443 assets:bank:savings $2000 = $2000
6444 assets:cash $100 = $100
6445 liabilities:creditcard $-50 = $-50
6446 equity:opening/closing balances
6447 These are start-of-day balances, ie whatever was in the account at
6449 the end of the previous day.
6450 The * after the date is an optional status flag. Here it means
6452 "cleared & confirmed".
6453 The currency symbols are optional, but usually a good idea as you'll
6455 be dealing with multiple currencies sooner or later.
6456 The = amounts are optional balance assertions, providing extra error
6458 checking.
6459 • The second way: run hledger add and follow the prompts to record a
6461 similar transaction:
6462 $ hledger add
6464 Adding transactions to journal file /Users/simon/finance/2020.journal
6465 Any command line arguments will be used as defaults.
6466 Use tab key to complete, readline keys to edit, enter to accept defaults.
6467 An optional (CODE) may follow transaction dates.
6468 An optional ; COMMENT may follow descriptions or amounts.
6469 If you make a mistake, enter < at any prompt to go one step backward.
6470 To end a transaction, enter . when prompted.
6471 To quit, enter . at a date prompt or press control-d or control-c.
6472 Date [2020-02-07]: 2020-01-01
6473 Description: * opening balances
6474 Account 1: assets:bank:checking
6475 Amount 1: $1000
6476 Account 2: assets:bank:savings
6477 Amount 2 [$-1000]: $2000
6478 Account 3: assets:cash
6479 Amount 3 [$-3000]: $100
6480 Account 4: liabilities:creditcard
6481 Amount 4 [$-3100]: $-50
6482 Account 5: equity:opening/closing balances
6483 Amount 5 [$-3050]:
6484 Account 6 (or . or enter to finish this transaction): .
6485 2020-01-01 * opening balances
6486 assets:bank:checking $1000
6487 assets:bank:savings $2000
6488 assets:cash $100
6489 liabilities:creditcard $-50
6490 equity:opening/closing balances $-3050
6491 Save this transaction to the journal ? [y]:
6493 Saved.
6494 Starting the next transaction (. or ctrl-D/ctrl-C to quit)
6495 Date [2020-01-01]: .
6496 If you're using version control, this could be a good time to commit
6498 the journal. Eg:
6499 $ git commit -m 'initial balances' 2020.journal
6501 Recording transactions
6503 As you spend or receive money, you can record these transactions using
6504 one of the methods above (text editor, hledger add) or by using the
6505 hledger-iadd or hledger-web add-ons, or by using the import command to
6506 convert CSV data downloaded from your bank.
6507 Here are some simple transactions, see the hledger_journal(5) manual
6509 and hledger.org for more ideas:
6510 2020/1/10 * gift received
6512 assets:cash $20
6513 income:gifts
6514 2020.1.12 * farmers market
6516 expenses:food $13
6517 assets:cash
6518 2020-01-15 paycheck
6520 income:salary
6521 assets:bank:checking $1000
6522 Reconciling
6524 Periodically you should reconcile - compare your hledger-reported bal‐
6525 ances against external sources of truth, like bank statements or your
6526 bank's website - to be sure that your ledger accurately represents the
6527 real-world balances (and, that the real-world institutions have not
6528 made a mistake!). This gets easy and fast with (1) practice and (2)
6529 frequency. If you do it daily, it can take 2-10 minutes. If you let
6530 it pile up, expect it to take longer as you hunt down errors and dis‐
6531 crepancies.
6532 A typical workflow:
6534 1. Reconcile cash. Count what's in your wallet. Compare with what
6536 hledger reports (hledger bal cash). If they are different, try to
6537 remember the missing transaction, or look for the error in the al‐
6538 ready-recorded transactions. A register report can be helpful
6539 (hledger reg cash). If you can't find the error, add an adjustment
6540 transaction. Eg if you have $105 after the above, and can't explain
6541 the missing $2, it could be:
6542 2020-01-16 * adjust cash
6544 assets:cash $-2 = $105
6545 expenses:misc
6546 2. Reconcile checking. Log in to your bank's website. Compare today's
6548 (cleared) balance with hledger's cleared balance (hledger bal check‐
6549 ing -C). If they are different, track down the error or record the
6550 missing transaction(s) or add an adjustment transaction, similar to
6551 the above. Unlike the cash case, you can usually compare the trans‐
6552 action history and running balance from your bank with the one re‐
6553 ported by hledger reg checking -C. This will be easier if you gen‐
6554 erally record transaction dates quite similar to your bank's clear‐
6555 ing dates.
6556 3. Repeat for other asset/liability accounts.
6558 Tip: instead of the register command, use hledger-ui to see a live-up‐
6560 dating register while you edit the journal: hledger-ui --watch --regis‐
6561 ter checking -C
6562 After reconciling, it could be a good time to mark the reconciled
6564 transactions' status as "cleared and confirmed", if you want to track
6565 that, by adding the * marker. Eg in the paycheck transaction above,
6566 insert * between 2020-01-15 and paycheck
6567 If you're using version control, this can be another good time to com‐
6569 mit:
6570 $ git commit -m 'txns' 2020.journal
6572 Reporting
6574 Here are some basic reports.
6575 Show all transactions:
6577 $ hledger print
6579 2020-01-01 * opening balances
6580 assets:bank:checking $1000
6581 assets:bank:savings $2000
6582 assets:cash $100
6583 liabilities:creditcard $-50
6584 equity:opening/closing balances $-3050
6585 2020-01-10 * gift received
6587 assets:cash $20
6588 income:gifts
6589 2020-01-12 * farmers market
6591 expenses:food $13
6592 assets:cash
6593 2020-01-15 * paycheck
6595 income:salary
6596 assets:bank:checking $1000
6597 2020-01-16 * adjust cash
6599 assets:cash $-2 = $105
6600 expenses:misc
6601 Show account names, and their hierarchy:
6603 $ hledger accounts --tree
6605 assets
6606 bank
6607 checking
6608 savings
6609 cash
6610 equity
6611 opening/closing balances
6612 expenses
6613 food
6614 misc
6615 income
6616 gifts
6617 salary
6618 liabilities
6619 creditcard
6620 Show all account totals:
6622 $ hledger balance
6624 $4105 assets
6625 $4000 bank
6626 $2000 checking
6627 $2000 savings
6628 $105 cash
6629 $-3050 equity:opening/closing balances
6630 $15 expenses
6631 $13 food
6632 $2 misc
6633 $-1020 income
6634 $-20 gifts
6635 $-1000 salary
6636 $-50 liabilities:creditcard
6637 --------------------
6638 0
6639 Show only asset and liability balances, as a flat list, limited to
6641 depth 2:
6642 $ hledger bal assets liabilities --flat -2
6644 $4000 assets:bank
6645 $105 assets:cash
6646 $-50 liabilities:creditcard
6647 --------------------
6648 $4055
6649 Show the same thing without negative numbers, formatted as a simple
6651 balance sheet:
6652 $ hledger bs --flat -2
6654 Balance Sheet 2020-01-16
6655 || 2020-01-16
6657 ========================++============
6658 Assets ||
6659 ------------------------++------------
6660 assets:bank || $4000
6661 assets:cash || $105
6662 ------------------------++------------
6663 || $4105
6664 ========================++============
6665 Liabilities ||
6666 ------------------------++------------
6667 liabilities:creditcard || $50
6668 ------------------------++------------
6669 || $50
6670 ========================++============
6671 Net: || $4055
6672 The final total is your "net worth" on the end date. (Or use bse for a
6674 full balance sheet with equity.)
6675 Show income and expense totals, formatted as an income statement:
6677 hledger is
6679 Income Statement 2020-01-01-2020-01-16
6680 || 2020-01-01-2020-01-16
6682 ===============++=======================
6683 Revenues ||
6684 ---------------++-----------------------
6685 income:gifts || $20
6686 income:salary || $1000
6687 ---------------++-----------------------
6688 || $1020
6689 ===============++=======================
6690 Expenses ||
6691 ---------------++-----------------------
6692 expenses:food || $13
6693 expenses:misc || $2
6694 ---------------++-----------------------
6695 || $15
6696 ===============++=======================
6697 Net: || $1005
6698 The final total is your net income during this period.
6700 Show transactions affecting your wallet, with running total:
6702 $ hledger register cash
6704 2020-01-01 opening balances assets:cash $100 $100
6705 2020-01-10 gift received assets:cash $20 $120
6706 2020-01-12 farmers market assets:cash $-13 $107
6707 2020-01-16 adjust cash assets:cash $-2 $105
6708 Show weekly posting counts as a bar chart:
6710 $ hledger activity -W
6712 2019-12-30 *****
6713 2020-01-06 ****
6714 2020-01-13 ****
6715 Migrating to a new file
6717 At the end of the year, you may want to continue your journal in a new
6718 file, so that old transactions don't slow down or clutter your reports,
6719 and to help ensure the integrity of your accounting history. See the
6720 close command.
6721 If using version control, don't forget to git add the new file.
6723
6725 The need to precede add-on command options with -- when invoked from
6726 hledger is awkward.
6727 When input data contains non-ascii characters, a suitable system locale
6729 must be configured (or there will be an unhelpful error). Eg on POSIX,
6730 set LANG to something other than C.
6731 In a Microsoft Windows CMD window, non-ascii characters and colours are
6733 not supported.
6734 On Windows, non-ascii characters may not display correctly when running
6736 a hledger built in CMD in MSYS/CYGWIN, or vice-versa.
6737 In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
6739 add.
6740 Not all of Ledger's journal file syntax is supported. See file format
6742 differences.
6743 On large data files, hledger is slower and uses more memory than
6745 Ledger.
6746
6748 Here are some issues you might encounter when you run hledger (and re‐
6749 member you can also seek help from the IRC channel, mail list or bug
6750 tracker):
6751 Successfully installed, but "No command 'hledger' found"
6753 stack and cabal install binaries into a special directory, which should
6754 be added to your PATH environment variable. Eg on unix-like systems,
6755 that is ~/.local/bin and ~/.cabal/bin respectively.
6756 I set a custom LEDGER_FILE, but hledger is still using the default file
6758 LEDGER_FILE should be a real environment variable, not just a shell
6759 variable. The command env | grep LEDGER_FILE should show it. You may
6760 need to use export. Here's an explanation.
6761 Getting errors like "Illegal byte sequence" or "Invalid or incomplete
6763 multibyte or wide character" or "commitAndReleaseBuffer: invalid argu‐
6764 ment (invalid character)"
6765 Programs compiled with GHC (hledger, haskell build tools, etc.) need to
6766 have a UTF-8-aware locale configured in the environment, otherwise they
6767 will fail with these kinds of errors when they encounter non-ascii
6768 characters.
6769 To fix it, set the LANG environment variable to some locale which sup‐
6771 ports UTF-8. The locale you choose must be installed on your system.
6772 Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:
6774 $ file my.journal
6776 my.journal: UTF-8 Unicode text # the file is UTF8-encoded
6777 $ echo $LANG
6778 C # LANG is set to the default locale, which does not support UTF8
6779 $ locale -a # which locales are installed ?
6780 C
6781 en_US.utf8 # here's a UTF8-aware one we can use
6782 POSIX
6783 $ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command
6784 If available, C.UTF-8 will also work. If your preferred locale isn't
6786 listed by locale -a, you might need to install it. Eg on Ubuntu/De‐
6787 bian:
6788 $ apt-get install language-pack-fr
6790 $ locale -a
6791 C
6792 en_US.utf8
6793 fr_BE.utf8
6794 fr_CA.utf8
6795 fr_CH.utf8
6796 fr_FR.utf8
6797 fr_LU.utf8
6798 POSIX
6799 $ LANG=fr_FR.utf8 hledger -f my.journal print
6800 Here's how you could set it permanently, if you use a bash shell:
6802 $ echo "export LANG=en_US.utf8" >>~/.bash_profile
6804 $ bash --login
6805 Exact spelling and capitalisation may be important. Note the differ‐
6807 ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow
6808 variant spellings, but others (eg macos) require it to be exact:
6809 $ locale -a | grep -iE en_us.*utf
6811 en_US.UTF-8
6812 $ LANG=en_US.UTF-8 hledger -f my.journal print
6813
6817 Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
6818 or hledger mail list)
6819
6822 Simon Michael <simon@joyful.com> and contributors
6823
6826 Copyright (C) 2007-2020 Simon Michael.
6827 Released under GNU GPL v3 or later.
6828
6831 hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
6832hledger-1.21 December 2020 HLEDGER(1)