1
2HLEDGER(1)                   hledger User Manuals                   HLEDGER(1)
3
4
5

NAME

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

SYNOPSIS

12       hledger
13
14       hledger [-f FILE] COMMAND [OPTIONS] [ARGS]
15
16       hledger [-f FILE] ADDONCMD -- [OPTIONS] [ARGS]
17

DESCRIPTION

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
24       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
32       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
39       Transactions  are  dated movements of money between two (or more) named
40       accounts, and are recorded with journal entries like this:
41
42              2015/10/16 bought food
43               expenses:food          $10
44               assets:cash
45
46       For more about this format, see hledger_journal(5).
47
48       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
53       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

OPTIONS

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
63       General help options:
64
65       -h --help
66              show general or COMMAND help
67
68       --man  show general or COMMAND user manual with man
69
70       --info show general or COMMAND user manual with info
71
72       --version
73              show general or ADDONCMD version
74
75       --debug[=N]
76              show debug output (levels 1-9, default: 1)
77
78       General input options:
79
80       -f FILE --file=FILE
81              use  a  different  input  file.   For  stdin,  use  -  (default:
82              $LEDGER_FILE or $HOME/.hledger.journal)
83
84       --rules-file=RULESFILE
85              Conversion  rules  file  to  use  when  reading  CSV   (default:
86              FILE.rules)
87
88       --separator=CHAR
89              Field separator to expect when reading CSV (default: ',')
90
91       --alias=OLD=NEW
92              rename accounts named OLD to NEW
93
94       --anon anonymize accounts and payees
95
96       --pivot FIELDNAME
97              use some other field or tag for the account name
98
99       -I --ignore-assertions
100              disable balance assertion checks (note: does not disable balance
101              assignments)
102
103       -s --strict
104              do extra error checking (check that all posted accounts are  de‐
105              clared)
106
107       General reporting options:
108
109       -b --begin=DATE
110              include postings/txns on or after this date
111
112       -e --end=DATE
113              include postings/txns before this date
114
115       -D --daily
116              multiperiod/multicolumn report by day
117
118       -W --weekly
119              multiperiod/multicolumn report by week
120
121       -M --monthly
122              multiperiod/multicolumn report by month
123
124       -Q --quarterly
125              multiperiod/multicolumn report by quarter
126
127       -Y --yearly
128              multiperiod/multicolumn report by year
129
130       -p --period=PERIODEXP
131              set  start date, end date, and/or reporting interval all at once
132              using period expressions syntax
133
134       --date2
135              match the secondary date instead (see command help for other ef‐
136              fects)
137
138       -U --unmarked
139              include only unmarked postings/txns (can combine with -P or -C)
140
141       -P --pending
142              include only pending postings/txns
143
144       -C --cleared
145              include only cleared postings/txns
146
147       -R --real
148              include only non-virtual postings
149
150       -NUM --depth=NUM
151              hide/aggregate accounts or postings more than NUM levels deep
152
153       -E --empty
154              show  items with zero amount, normally hidden (and vice-versa in
155              hledger-ui/hledger-web)
156
157       -B --cost
158              convert amounts to their cost/selling amount at transaction time
159
160       -V --market
161              convert amounts to their market value in default valuation  com‐
162              modities
163
164       -X --exchange=COMM
165              convert amounts to their market value in commodity COMM
166
167       --value
168              convert  amounts  to  cost  or  market value, more flexibly than
169              -B/-V/-X
170
171       --infer-market-prices
172              use transaction prices (recorded with @  or  @@)  as  additional
173              market prices, as if they were P directives
174
175       --auto apply automated posting rules to modify transactions.
176
177       --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
182       --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
189       When a reporting option appears more than once in the command line, the
190       last one takes precedence.
191
192       Some reporting options can also be written as query arguments.
193
194   Command options
195       To see options for a particular command, including command-specific op‐
196       tions, run: hledger COMMAND -h.
197
198       Command-specific  options  must  be written after the command name, eg:
199       hledger print -x.
200
201       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
205   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
209       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
215       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
220              assets depth:2
221              -X USD
222
223       Good:
224
225              assets
226              depth:2
227              -X=USD
228
229       For special characters (see below), use one less level of quoting  than
230       you would at the command prompt.  Bad:
231
232              -X"$"
233
234       Good:
235
236              -X$
237
238       See also: Save frequently used options.
239
240   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
248              $ hledger register 'credit card'
249
250       or:
251
252              $ hledger register credit\ card
253
254   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
263              $ hledger balance cur:'\$'
264
265       or:
266
267              $ hledger balance cur:\\$
268
269   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
276              $ hledger ui cur:'\\$'
277
278       or:
279
280              $ hledger ui cur:\\\\$
281
282       If you wondered why four backslashes, perhaps this helps:
283
284       unescaped:        $
285       escaped:          \$
286       double-escaped:   \\$
287       triple-escaped:   \\\\$
288
289       Or,  you  can avoid the extra escaping by running the add-on executable
290       directly:
291
292              $ hledger-ui cur:\\$
293
294   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
299       • an @argumentfile
300
301       • hledger-ui's filter field
302
303       • hledger-web's search form
304
305       • GHCI's prompt (used by developers).
306
307   Unicode characters
308       hledger is expected to handle non-ascii characters correctly:
309
310       • 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
314       • they should be displayed correctly by  all  hledger  tools,  and  on-
315         screen alignment should be preserved.
316
317       This requires a well-configured environment.  Here are some tips:
318
319       • 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
326       • your terminal software (eg  Terminal.app,  iTerm,  CMD.exe,  xterm..)
327         must support unicode
328
329       • the terminal must be using a font which includes the required unicode
330         glyphs
331
332       • the terminal should be configured to display wide characters as  dou‐
333         ble width (for report alignment)
334
335       • 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
341   Regular expressions
342       hledger uses regular expressions in a number of places:
343
344       • query  terms, on the command line and in the hledger-web search form:
345         REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX
346
347       • CSV rules conditional blocks: if REGEX ...
348
349       • account alias directives and options: alias  /REGEX/  =  REPLACEMENT,
350         --alias /REGEX/=REPLACEMENT
351
352       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
356       1. they are case insensitive
357
358       2. they  are infix matching (they do not need to match the entire thing
359          being matched)
360
361       3. they are POSIX ERE (extended regular expressions)
362
363       4. they also support GNU word boundaries (\b, \B, \<, \>)
364
365       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
370       6. they  do  not  support mode modifiers ((?s)), character classes (\w,
371          \d), or anything else not mentioned above.
372
373       Some things to note:
374
375       • 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
379       • 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
383       • 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

ENVIRONMENT

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
392       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
396       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
401              {
402                "LEDGER_FILE" : "~/finance/current.journal"
403              }
404
405       To see the effect you may need to killall Dock, or reboot.
406
407       COLUMNS  The  screen  width used by the register command.  Default: the
408       full terminal width.
409
410       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

DATA FILES

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
419       You can override this with the $LEDGER_FILE environment variable:
420
421              $ setenv LEDGER_FILE ~/finance/2016.journal
422              $ hledger stats
423
424       or with one or more -f/--file options:
425
426              $ hledger -f /some/file -f another_file stats
427
428       The file name - means standard input:
429
430              $ cat some.journal | hledger -f-
431
432   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
436       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
448       These formats are described in their own sections, below.
449
450       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
456       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
459              $ hledger -f csv:/some/csv-file.dat stats
460
461       Or to read stdin (-) as timeclock format:
462
463              $ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-
464
465   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
469       • most directives do not affect sibling files
470
471       • balance assertions will not see any account  balances  from  previous
472         files
473
474       If you need either of those things, you can
475
476       • use a single parent file which includes the others
477
478       • or  concatenate  the files into one before reading, eg: cat a.journal
479         b.journal | hledger -f- CMD.
480
481   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
486       • Are the input files parseable, with valid syntax ?
487
488       • Are all transactions balanced ?
489
490       • Do all balance assertions pass ?
491
492       With the -s/--strict flag, additional checks are performed:
493
494       • Are all accounts posted to, declared  with  an  account  directive  ?
495         (Account error checking)
496
497       • Are all commodities declared with a commodity directive ?  (Commodity
498         error checking)
499
500       See also: https://hledger.org/checking-for-errors.html
501
502       experimental.
503

TIME PERIODS

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
510       Examples:
511
512       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
527       Counterexamples  -  malformed digit sequences might give surprising re‐
528       sults:
529
530       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
537   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
543       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
548       Some notes:
549
550       • As in Ledger, end dates are exclusive, so you need to write the  date
551         after the last day you want to include.
552
553       • As  noted  in reporting options: among start/end dates specified with
554         options, the last (i.e.  right-most) option takes precedence.
555
556       • 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
561       Examples:
562
563       -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
569       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
575   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
583   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
587       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
591       -p "from 2009/1/1 to 2009/4/1"
592
593       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
597       -p "2009/1/1 2009/4/1"
598       -p2009/1/1to2009/4/1
599       -p2009/1/1..2009/4/1
600
601       Dates are smart dates, so if the current year is 2009,  the  above  can
602       also be written as:
603
604       -p "1/1 4/1"
605       -p "january-apr"
606       -p "this year to 4/1"
607
608       If you specify only one date, the missing start or end date will be the
609       earliest or latest transaction in your journal:
610
611       -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
618       A single date with no "from" or "to" defines both  the  start  and  end
619       date like so:
620
621       -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
629       Or you can specify a single quarter like so:
630
631       -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
637       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
643       -p "weekly from 2009/1/1 to 2009/4/1"
644       -p "monthly in 2008"
645       -p "quarterly"
646
647       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
652       For example:
653
654       -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
663       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
667       All  of  these  will start on the first day of the requested period and
668       end on the last one, as described above.
669
670       Examples:
671
672       -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
678       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
681       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
686       Examples:
687
688       -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
699       Show historical balances at end of 15th each month (N is exclusive  end
700       date):
701
702       hledger balance -H -p "every 16th day"
703
704       Group  postings  from  start  of wednesday to end of next tuesday (N is
705       start date and exclusive end date):
706
707       hledger register checking -p "every 3rd day of week"
708

DEPTH

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

QUERIES

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
725       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
729       • any of the description terms AND
730
731       • any of the account terms AND
732
733       • any of the status terms AND
734
735       • all the other terms.
736
737       The print command instead shows transactions which:
738
739       • match any of the description terms AND
740
741       • have any postings matching any of the positive account terms AND
742
743       • have no postings matching any of the negative account terms AND
744
745       • match all the other terms.
746
747       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
750       REGEX, acct:REGEX
751              match  account  names by this regular expression.  (With no pre‐
752              fix, acct: is assumed.)  same as above
753
754       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
762       code:REGEX
763              match by transaction code (eg check number)
764
765       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
774       desc:REGEX
775              match transaction descriptions.
776
777       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
784       date2:PERIODEXPR
785              match secondary dates within the specified period.
786
787       depth:N
788              match  (or  display,  depending on command) accounts at or above
789              this depth
790
791       note:REGEX
792              match transaction notes (part of  description  right  of  |,  or
793              whole description when there's no |)
794
795       payee:REGEX
796              match transaction payee/payer names (part of description left of
797              |, or whole description when there's no |)
798
799       real:, real:0
800              match real or virtual postings respectively
801
802       status:, status:!, status:*
803              match unmarked, pending, or cleared transactions respectively
804
805       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
811       The following special search term is used automatically in hledger-web,
812       only:
813
814       inacct:ACCTNAME
815              tells hledger-web to show the transaction register for this  ac‐
816              count.  Can be filtered further with acct etc.
817
818       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

COSTING

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

VALUATION

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
837   -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
842   -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
847   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
852       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
856       For multiperiod reports, each column/period is valued on the  last  day
857       of the period, by default.
858
859   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
864       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
869       2. A reverse market price: the inverse of a declared or inferred market
870          price from B to A.
871
872       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
876       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
880       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
885       Amounts for which no suitable market price can be found, are  not  con‐
886       verted.
887
888   --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
896       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
901       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
906       --infer-market-price can infer market prices from:
907
908       • multicommodity transactions with explicit prices (@/@@)
909
910       • 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
914       • but not, currently, from "more correct"  multicommodity  transactions
915         (no @, multiple commodities, balanced).
916
917   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
922       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
927       1. The price commodity from the latest P-declared market price for A on
928          or before valuation date.
929
930       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
934       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
938       This means:
939
940       • If  you  have  P directives, they determine which commodities -V will
941         convert, and to what.
942
943       • If you have no P directives, and use the  --infer-market-price  flag,
944         transaction prices determine it.
945
946       Amounts  for  which  no  valuation  commodity can be found are not con‐
947       verted.
948
949   Simple valuation examples
950       Here are some quick examples of -V:
951
952              ; one euro is worth this many dollars from nov 1
953              P 2016/11/01 € $1.10
954
955              ; purchase some euros on nov 3
956              2016/11/3
957                  assets:euros        €100
958                  assets:checking
959
960              ; the euro is worth fewer dollars by dec 21
961              P 2016/12/21 € $1.03
962
963       How many euros do I have ?
964
965              $ hledger -f t.j bal -N euros
966                              €100  assets:euros
967
968       What are they worth at end of nov 3 ?
969
970              $ hledger -f t.j bal -N euros -V -e 2016/11/4
971                           $110.00  assets:euros
972
973       What are they worth after 2016/12/21 ?  (no report end date  specified,
974       defaults to today)
975
976              $ hledger -f t.j bal -N euros -V
977                           $103.00  assets:euros
978
979   --value: Flexible valuation
980       -V and -X are special cases of the more general --value option:
981
982               --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
990       The TYPE part selects cost or value and valuation date:
991
992       --value=then
993              Convert  amounts to their value in the default valuation commod‐
994              ity, using market prices on each posting's date.
995
996       --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
1002       --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
1007       --value=YYYY-MM-DD
1008              Convert  amounts to their value in the default valuation commod‐
1009              ity using market prices on this date.
1010
1011       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
1016   More valuation examples
1017       Here  are  some  examples  showing  the effect of --value, as seen with
1018       print:
1019
1020              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
1025              2000-01-01
1026                (a)      1 A @ 5 B
1027
1028              2000-02-01
1029                (a)      1 A @ 6 B
1030
1031              2000-03-01
1032                (a)      1 A @ 7 B
1033
1034       Show the cost of each posting:
1035
1036              $ hledger -f- print --cost
1037              2000-01-01
1038                  (a)             5 B
1039
1040              2000-02-01
1041                  (a)             6 B
1042
1043              2000-03-01
1044                  (a)             7 B
1045
1046       Show the value as of the last day of the report period (2000-02-29):
1047
1048              $ hledger -f- print --value=end date:2000/01-2000/03
1049              2000-01-01
1050                  (a)             2 B
1051
1052              2000-02-01
1053                  (a)             2 B
1054
1055       With no report period specified, that shows the value as  of  the  last
1056       day of the journal (2000-03-01):
1057
1058              $ hledger -f- print --value=end
1059              2000-01-01
1060                  (a)             3 B
1061
1062              2000-02-01
1063                  (a)             3 B
1064
1065              2000-03-01
1066                  (a)             3 B
1067
1068       Show the current value (the 2000-04-01 price is still in effect today):
1069
1070              $ hledger -f- print --value=now
1071              2000-01-01
1072                  (a)             4 B
1073
1074              2000-02-01
1075                  (a)             4 B
1076
1077              2000-03-01
1078                  (a)             4 B
1079
1080       Show the value on 2000/01/15:
1081
1082              $ hledger -f- print --value=2000-01-15
1083              2000-01-01
1084                  (a)             1 B
1085
1086              2000-02-01
1087                  (a)             1 B
1088
1089              2000-03-01
1090                  (a)             1 B
1091
1092       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
1095              P 2000-01-01 A 2B
1096
1097              2000-01-01
1098                a  1B
1099                b
1100
1101              $ hledger print -x -X A
1102              2000-01-01
1103                  a               0
1104                  b               0
1105
1106       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
1112              P 2000-01-01 A 2B
1113              commodity 0.00A
1114
1115              2000-01-01
1116                a  1B
1117                b
1118
1119              $ hledger print -X A
1120              2000-01-01
1121                  a           0.50A
1122                  b          -0.50A
1123
1124   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
1131       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
1143       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
1162       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
1175       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
1179       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
1221
1222       --cumulative is omitted to save space, it works like -H but with a zero
1223       starting balance.
1224
1225       Glossary:
1226
1227       cost   calculated using price(s) recorded in the transaction(s).
1228
1229       value  market value using available market price declarations,  or  the
1230              unchanged amount if no conversion rate can be found.
1231
1232       report start
1233              the  first  day  of the report period specified with -b or -p or
1234              date:, otherwise today.
1235
1236       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
1241       report end
1242              the last day of the report period specified with  -e  or  -p  or
1243              date:, otherwise today.
1244
1245       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
1250       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

PIVOTING

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
1263       --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
1269       An example:
1270
1271              2016/02/16 Member Fee Payment
1272                  assets:bank account                    2 EUR
1273                  income:member fees                    -2 EUR  ; member: John Doe
1274
1275       Normal balance report showing account names:
1276
1277              $ hledger balance
1278                             2 EUR  assets:bank account
1279                            -2 EUR  income:member fees
1280              --------------------
1281                                 0
1282
1283       Pivoted balance report, using member: tag values instead:
1284
1285              $ hledger balance --pivot member
1286                             2 EUR
1287                            -2 EUR  John Doe
1288              --------------------
1289                                 0
1290
1291       One way to show only amounts with a member: value (using a  query,  de‐
1292       scribed below):
1293
1294              $ hledger balance --pivot member tag:member=.
1295                            -2 EUR  John Doe
1296              --------------------
1297                            -2 EUR
1298
1299       Another  way  (the  acct:  query  matches  against the pivoted "account
1300       name"):
1301
1302              $ hledger balance --pivot member acct:.
1303                            -2 EUR  John Doe
1304              --------------------
1305                            -2 EUR
1306

OUTPUT

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
1312              $ hledger print > foo.txt
1313
1314       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
1318              $ hledger print -o foo.txt
1319              $ hledger print -o -        # write to stdout (the default)
1320
1321   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
1327              $ hledger print -O csv
1328
1329       or, by a file extension specified with -o/--output-file:
1330
1331              $ hledger balancesheet -o foo.html   # write HTML to foo.html
1332
1333       The -O option can be used to override the file extension if needed:
1334
1335              $ hledger balancesheet -o foo.txt -O html   # write HTML to foo.txt
1336
1337       Some notes about JSON output:
1338
1339       • This feature is marked experimental,  and  not  yet  much  used;  you
1340         should expect our JSON to evolve.  Real-world feedback is welcome.
1341
1342       • 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
1348       • 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
1357       Notes about SQL output:
1358
1359       • SQL output is also marked experimental, and much like JSON could  use
1360         real-world feedback.
1361
1362       • SQL output is expected to work with sqlite, MySQL and PostgreSQL
1363
1364       • 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

COMMANDS

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
1377       Here are the built-in commands, with the most often-used in bold:
1378
1379       Data entry:
1380
1381       These data entry commands are the only ones which can modify your jour‐
1382       nal file.
1383
1384add - add transactions using guided prompts
1385
1386import - add any new transactions from other files (eg csv)
1387
1388       Data management:
1389
1390       • check - check for various kinds of issue in the data
1391
1392       • close (equity) - generate balance-resetting transactions
1393
1394       • diff - compare account transactions in two journal files
1395
1396       • rewrite - generate extra postings, similar to print --auto
1397
1398       Financial statements:
1399
1400aregister (areg) - show transactions in a particular account
1401
1402balancesheet (bs) - show assets, liabilities and net worth
1403
1404       • balancesheetequity (bse) - show assets, liabilities and equity
1405
1406       • cashflow (cf) - show changes in liquid assets
1407
1408incomestatement (is) - show revenues and expenses
1409
1410       • roi - show return on investments
1411
1412       Miscellaneous reports:
1413
1414       • accounts - show account names
1415
1416       • activity - show postings-per-interval bar charts
1417
1418balance (bal) - show balance changes/end balances/budgets in any  ac‐
1419         counts
1420
1421       • codes - show transaction codes
1422
1423       • commodities - show commodity/currency symbols
1424
1425       • descriptions - show unique transaction descriptions
1426
1427       • files - show input file paths
1428
1429       • help - show hledger user manuals in several formats
1430
1431       • notes - show unique note segments of transaction descriptions
1432
1433       • payees - show unique payee segments of transaction descriptions
1434
1435       • prices - show market price records
1436
1437print - show transactions (journal entries)
1438
1439       • print-unique - show only transactions with unique descriptions
1440
1441register  (reg) - show postings in one or more accounts & running to‐
1442         tal
1443
1444       • register-match - show a recent posting that best matches  a  descrip‐
1445         tion
1446
1447       • stats - show journal statistics
1448
1449       • tags - show tag names
1450
1451       • test - run self tests
1452
1453       Add-on commands:
1454
1455       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
1459ui - an efficient terminal interface (TUI) for hledger
1460
1461web - a simple web interface (WUI) for hledger
1462
1463       And these add-ons are maintained separately:
1464
1465       • iadd - a more interactive alternative for the add command
1466
1467       • interest  -  generates  interest  transactions  according  to various
1468         schemes
1469
1470       • stockquotes - downloads market prices for your commodities  from  Al‐
1471         phaVantage (experimental)
1472
1473       Next, the detailed command docs, in alphabetical order.
1474
1475   accounts
1476       accounts
1477       Show account names.
1478
1479       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
1488       Examples:
1489
1490              $ 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
1500   activity
1501       activity
1502       Show an ascii barchart of posting counts per interval.
1503
1504       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
1508       Examples:
1509
1510              $ hledger activity --quarterly
1511              2008-01-01 **
1512              2008-04-01 *******
1513              2008-07-01
1514              2008-10-01 **
1515
1516   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
1521       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
1529       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
1533       Features:
1534
1535       • 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
1539       • You can also set the initial defaults with command line arguments.
1540
1541       • Readline-style edit keys can be used during data entry.
1542
1543       • 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
1547       • If  the  journal defines a default commodity, it will be added to any
1548         bare numbers entered.
1549
1550       • A parenthesised transaction code may be entered following a date.
1551
1552       • Comments and tags may be entered following a description or amount.
1553
1554       • If you make a mistake, enter < at any prompt to go one step backward.
1555
1556       • Input prompts are displayed in a different colour when  the  terminal
1557         supports it.
1558
1559       Example (see the tutorial for a detailed explanation):
1560
1561              $ 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
1581              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
1586       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
1589   aregister
1590       aregister, areg
1591       Show the transactions and running historical  balance  in  an  account,
1592       with each line item representing one transaction.
1593
1594       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
1598       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
1601       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
1606       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
1610       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
1617       Any additional arguments form a query which will  filter  the  transac‐
1618       tions shown.
1619
1620       Each aregister line item shows:
1621
1622       • the  transaction's date (or the relevant posting's date if different,
1623         see below)
1624
1625       • the names of all the other account(s) involved  in  this  transaction
1626         (probably abbreviated)
1627
1628       • the total change to this account's balance from this transaction
1629
1630       • the account's historical running balance after this transaction.
1631
1632       Transactions  making a net change of zero are not shown by default; add
1633       the -E/--empty flag to show them.
1634
1635       aregister ignores a depth limit, so its final total will always match a
1636       balance report with similar arguments.
1637
1638       This command also supports the output destination and output format op‐
1639       tions The output formats supported are txt, csv, and json.
1640
1641   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
1648       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
1652       Examples:
1653
1654       Show all transactions and historical running balance in the  first  ac‐
1655       count whose name contains "checking":
1656
1657              $ hledger areg checking
1658
1659       Show  transactions and historical running balance in all asset accounts
1660       during july:
1661
1662              $ hledger areg assets date:jul
1663
1664   balance
1665       balance, bal
1666       Show accounts and their balances.
1667
1668       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
1673       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
1678   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
1683       balance can show..
1684
1685       • accounts as a list (-l) or a tree (-t)
1686
1687       • optionally depth-limited (-[1-9])
1688
1689       • sorted by declaration order and name, or by amount
1690
1691       ..and their..
1692
1693       • balance changes (the default)
1694
1695       • or actual and planned balance changes (--budget)
1696
1697       • or value of balance changes (-V)
1698
1699       • or change of balance values (--valuechange)
1700
1701       ..in..
1702
1703       • one time period (the whole journal period by default)
1704
1705       • or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
1706
1707       ..either..
1708
1709       • per period (the default)
1710
1711       • or accumulated since report start date (--cumulative)
1712
1713       • or accumulated since account creation (--historical/-H)
1714
1715       ..possibly converted to..
1716
1717       • cost (--value=cost[,COMM]/--cost/-B)
1718
1719       • or market value, as of transaction dates (--value=then[,COMM])
1720
1721       • or at period ends (--value=end[,COMM])
1722
1723       • or now (--value=now)
1724
1725       • or at some other date (--value=YYYY-MM-DD)
1726
1727       ..with..
1728
1729       • totals (-T), averages (-A), percentages (-%),  inverted  sign  (--in‐
1730         vert)
1731
1732       • rows and columns swapped (--transpose)
1733
1734       • another field used as account name (--pivot)
1735
1736       • custom-formatted line items (single-period reports only) (--format)
1737
1738       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
1743   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
1750       Accounts are sorted by declaration order if any,  and  then  alphabeti‐
1751       cally by account name.  For instance, using examples/sample.journal:
1752
1753              $ 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
1764       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
1768              $ 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
1780       The  total  of  the amounts displayed is shown as the last line, unless
1781       -N/--no-total is used.
1782
1783   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
1788              $ hledger bal --cleared assets date:200806
1789                               $-2  assets:cash
1790              --------------------
1791                               $-2
1792
1793   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
1797       With  -t/--tree,  the  account  hierarchy  is  shown, with subaccounts'
1798       "leaf" names indented below their parent:
1799
1800              $ 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
1814       Notes:
1815
1816       • "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
1821       • 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
1827       • Each  group of sibling accounts (ie, under a common parent) is sorted
1828         separately.
1829
1830   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
1837              $ hledger balance -N -1
1838                               $-1  assets
1839                                $2  expenses
1840                               $-2  income
1841                                $1  liabilities
1842
1843       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
1846              $ hledger bal expenses --drop 1
1847                                $1  food
1848                                $1  supplies
1849              --------------------
1850                                $2
1851
1852   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
1858              $ hledger balance --quarterly income expenses -E
1859              Balance changes in 2008:
1860
1861                                 ||  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
1870       Notes:
1871
1872       • 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
1876       • Leading and trailing periods (columns) containing all zeroes are  not
1877         shown, unless -E/--empty is used.
1878
1879       • Accounts   (rows)   containing  all  zeroes  are  not  shown,  unless
1880         -E/--empty is used.
1881
1882       • Amounts with many commodities are shown in abbreviated  form,  unless
1883         --no-elide is used.  (experimental)
1884
1885       • Average  and/or  total columns can be added with the -A/--average and
1886         -T/--row-total flags.
1887
1888       • The --transpose flag can be used to exchange rows and columns.
1889
1890       • The --pivot FIELD option causes a different transaction field  to  be
1891         used as "account name".  See PIVOTING.
1892
1893       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
1896       • Hide the totals row with -N/--no-total
1897
1898       • Convert to a single currency with -V
1899
1900       • Maximize the terminal window
1901
1902       • Reduce the terminal's font size
1903
1904       • View with a pager like less, eg: hledger bal -D  --color=yes  |  less
1905         -RS
1906
1907       • 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
1911       • Output  as  HTML and view with a browser: hledger bal -D -o a.html &&
1912         open a.html
1913
1914   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
1919       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
1924   Percentages
1925       With  -%/--percent, balance reports show each account's value expressed
1926       as a percentage of the (column) total:
1927
1928              $ hledger bal expenses -Q -%
1929              Balance changes in 2008:
1930
1931                                 || 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
1938       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
1942              $ hledger bal -% amt:`>0`
1943              $ hledger bal -% amt:`<0`
1944
1945       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
1949              $ hledger bal -% cur:\\$
1950              $ hledger bal -% cur:€
1951
1952   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
1956       A  balance  change  is the net amount added to, or removed from, an ac‐
1957       count during some period.
1958
1959       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
1963       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
1968       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
1972       balance  shows  balance changes by default.  To see accurate historical
1973       end balances:
1974
1975       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
1979       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
1984   Balance report types
1985       For more flexible reporting, there are three important option groups:
1986
1987       hledger  balance  [CALCULATIONTYPE]  [ACCUMULATIONTYPE] [VALUATIONTYPE]
1988       ...
1989
1990       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
1997       Calculation type:
1998       The basic calculation to perform for each table cell.  It is one of:
1999
2000       • --sum : sum the posting amounts (default)
2001
2002       • --budget : like --sum but also show a goal amount
2003
2004       • --valuechange : show the change in period-end historical balance val‐
2005         ues
2006
2007       Accumulation type:
2008       Which postings should be included in each cell's  calculation.   It  is
2009       one of:
2010
2011       • --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
2015       • --cumulative  :  postings from report start to column end, eg to show
2016         changes accumulated since the report's start date.  Rarely used.
2017
2018       • --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
2023       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
2027       • no valuation, show amounts in their original commodities (default)
2028
2029       • --value=cost[,COMM] : no valuation, show amounts converted to cost
2030
2031       • --value=then[,COMM] : show value at transaction dates
2032
2033       • --value=end[,COMM] : show value at period end date(s)  (default  with
2034         --valuechange)
2035
2036       • --value=now[,COMM] : show value at today's date
2037
2038       • --value=YYYY-MM-DD[,COMM] : show value at another date
2039
2040       or one of their aliases: --cost/-B, --market/-V or --exchange/-X.
2041
2042       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
2046       • --valuechange implies --value=end
2047
2048       • --valuechange  makes  --change  the  default  when used with the bal‐
2049         ancesheet/balancesheetequity commands
2050
2051       • --cumulative or --historical disables --row-total/-T
2052
2053       For reference, here is what the combinations of accumulation and valua‐
2054       tion show:
2055
2056       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
2076   Useful balance reports
2077       Some frequently used balance options/reports are:
2078
2079       • bal -M revenues expenses
2080       Show  revenues/expenses  in each month.  Also available as the incomes‐
2081       tatement command.
2082
2083       • bal -M -H assets liabilities
2084       Show historical asset/liability  balances  at  each  month  end.   Also
2085       available as the balancesheet command.
2086
2087       • 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
2091       • bal -M assets not:receivable
2092       Show changes to liquid assets in each month.   Also  available  as  the
2093       cashflow command.
2094
2095       Also:
2096
2097       • bal -M expenses -2 -SA
2098       Show  monthly  expenses  summarised  to  depth  2 and sorted by average
2099       amount.
2100
2101       • bal -M --budget expenses
2102       Show monthly expenses and budget goals.
2103
2104       • bal -M --valuechange investments
2105       Show monthly change in market value of investment assets.
2106
2107       • bal  investments  --valuechange  -D  date:lastweek  amt:'>1000'  -STA
2108         [--invert]
2109       Show top gainers [or losers] last week
2110
2111   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
2117       For example, you can take average monthly expenses in  the  common  ex‐
2118       pense categories to construct a minimal monthly budget:
2119
2120              ;; Budget
2121              ~ monthly
2122                income  $2000
2123                expenses:food    $400
2124                expenses:bus     $50
2125                expenses:movies  $30
2126                assets:bank:checking
2127
2128              ;; 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
2137              2017-12-01
2138                income  $2100
2139                expenses:food    $412
2140                expenses:bus     $53
2141                expenses:gifts   $100
2142                assets:bank:checking
2143
2144       You can now see a monthly budget report:
2145
2146              $ hledger balance -M --budget
2147              Budget performance in 2017/11/01-2017/12/31:
2148
2149                                    ||                      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
2162       This is different from a normal balance report in several ways:
2163
2164       • Only  accounts  with budget goals during the report period are shown,
2165         by default.
2166
2167       • 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
2171       • All parent accounts are always shown, even in list mode.  Eg  assets,
2172         assets:bank, and expenses above.
2173
2174       • Amounts  always include all subaccounts, budgeted or unbudgeted, even
2175         in list mode.
2176
2177       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
2182       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
2186              $ hledger balance -M --budget --empty
2187              Budget performance in 2017/11/01-2017/12/31:
2188
2189                                    ||                      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
2204       You can roll over unspent budgets to next period with --cumulative:
2205
2206              $ hledger balance -M --budget --cumulative
2207              Budget performance in 2017/11/01-2017/12/31:
2208
2209                                    ||                      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
2222       For more examples and notes, see Budgeting.
2223
2224   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
2233              ~ monthly in 2020
2234                (expenses:food)  $500
2235
2236              2020-01-15
2237                expenses:food    $400
2238                assets:checking
2239
2240              $ hledger bal expenses --budget
2241              Budget performance in 2020-01-15:
2242
2243                            || 2020-01-15
2244              ==============++============
2245               <unbudgeted> ||       $400
2246              --------------++------------
2247                            ||       $400
2248
2249       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
2254              $ hledger bal expenses --budget -b 2020/1/1
2255              Budget performance in 2020-01-01..2020-01-15:
2256
2257                             || 2020-01-01..2020-01-15
2258              ===============++========================
2259               expenses:food ||     $400 [80% of $500]
2260              ---------------++------------------------
2261                             ||     $400 [80% of $500]
2262
2263   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
2269       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
2272       To illustrate this, consider the following budget:
2273
2274              ~ monthly from 2019/01
2275                  expenses:personal             $1,000.00
2276                  expenses:personal:electronics    $100.00
2277                  liabilities
2278
2279       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
2283       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
2288       For example, let's consider these transactions:
2289
2290              ~ monthly from 2019/01
2291                  expenses:personal             $1,000.00
2292                  expenses:personal:electronics    $100.00
2293                  liabilities
2294
2295              2019/01/01 Google home hub
2296                  expenses:personal:electronics          $90.00
2297                  liabilities                           $-90.00
2298
2299              2019/01/02 Phone screen protector
2300                  expenses:personal:electronics:upgrades          $10.00
2301                  liabilities
2302
2303              2019/01/02 Weekly train ticket
2304                  expenses:personal:train tickets       $153.00
2305                  liabilities
2306
2307              2019/01/03 Flowers
2308                  expenses:personal          $30.00
2309                  liabilities
2310
2311       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
2317              $ hledger balance --budget -M
2318              Budget performance in 2019/01:
2319
2320                                             ||                           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
2329       And  with --empty, we can get a better picture of budget allocation and
2330       consumption:
2331
2332              $ hledger balance --budget -M --empty
2333              Budget performance in 2019/01:
2334
2335                                                      ||                           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
2346   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
2351              $ 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
2365       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
2369       %[MIN][.MAX](FIELDNAME)
2370
2371       • MIN pads with spaces to at least this width (optional)
2372
2373       • MAX truncates at this width (optional)
2374
2375       • FIELDNAME must be enclosed in parentheses, and can be one of:
2376
2377         • depth_spacer - a number of spaces equal to the account's depth,  or
2378           if MIN is specified, MIN * depth spaces.
2379
2380         • account - the account's name
2381
2382         • total - the account's balance/posted total, right justified
2383
2384       Also,  FMT  can begin with an optional prefix to control how multi-com‐
2385       modity amounts are rendered:
2386
2387       • %_ - render on multiple lines, bottom-aligned (the default)
2388
2389       • %^ - render on multiple lines, top-aligned
2390
2391       • %, - render on one line, comma-separated
2392
2393       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
2397       Some example formats:
2398
2399       • %(total) - the account's total
2400
2401       • %-20.20(account) - the account's name, left justified, padded  to  20
2402         characters and clipped at 20 characters
2403
2404       • %,%-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
2408       • %20(total)   %2(depth_spacer)%-(account) - the default format for the
2409         single-column balance report
2410
2411   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
2418       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
2423       Example:
2424
2425              $ hledger balancesheet
2426              Balance Sheet
2427
2428              Assets:
2429                               $-1  assets
2430                                $1    bank:saving
2431                               $-2    cash
2432              --------------------
2433                               $-1
2434
2435              Liabilities:
2436                                $1  liabilities:debts
2437              --------------------
2438                                $1
2439
2440              Total:
2441              --------------------
2442                                 0
2443
2444       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
2450       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
2454   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
2460       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
2465       Example:
2466
2467              $ hledger balancesheetequity
2468              Balance Sheet With Equity
2469
2470              Assets:
2471                               $-2  assets
2472                                $1    bank:saving
2473                               $-3    cash
2474              --------------------
2475                               $-2
2476
2477              Liabilities:
2478                                $1  liabilities:debts
2479              --------------------
2480                                $1
2481
2482              Equity:
2483                        $1  equity:owner
2484              --------------------
2485                        $1
2486
2487              Total:
2488              --------------------
2489                                 0
2490
2491       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
2497       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
2501   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
2507       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
2512       Example:
2513
2514              $ hledger cashflow
2515              Cashflow Statement
2516
2517              Cash flows:
2518                               $-1  assets
2519                                $1    bank:saving
2520                               $-2    cash
2521              --------------------
2522                               $-1
2523
2524              Total:
2525              --------------------
2526                               $-1
2527
2528       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
2533       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
2537   check
2538       check
2539       Check for various kinds of errors in your data.
2540
2541       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
2547       Some examples:
2548
2549              hledger check      # basic checks
2550              hledger check -s   # basic + strict checks
2551              hledger check ordereddates payees  # basic + two other checks
2552
2553       Here are the checks currently available:
2554
2555   Basic checks
2556       These checks are always run automatically, by (almost) all hledger com‐
2557       mands, including check:
2558
2559parseable - data files are well-formed and can be successfully parsed
2560
2561autobalanced -  all  transactions  are  balanced,  inferring  missing
2562         amounts  where  necessary,  and possibly converting commodities using
2563         transaction prices or automatically-inferred transaction prices
2564
2565assertions - all balance  assertions  in  the  journal  are  passing.
2566         (This check can be disabled with -I/--ignore-assertions.)
2567
2568   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
2573accounts - all account names used by transactions have been declared
2574
2575commodities - all commodity symbols used have been declared
2576
2577   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
2582ordereddates - transactions are ordered by date in each file
2583
2584payees - all payees used by transactions have been declared
2585
2586uniqueleafnames - all account leaf names are unique
2587
2588   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
2592hledger-check-tagfiles - all  tag  values  containing  /  (a  forward
2593         slash) exist as file paths
2594
2595hledger-check-fancyassertions  -  more complex balance assertions are
2596         passing
2597
2598       You could make similar scripts to perform your own custom checks.  See:
2599       Cookbook -> Scripting.
2600
2601   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
2609       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
2613       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
2618       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
2622       With --interleaved, the equity postings are shown next to the  postings
2623       they balance, which makes troubleshooting easier.
2624
2625       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
2632   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
2644       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
2650       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
2656       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
2663       Examples:
2664
2665       Carrying asset/liability balances into a new file for 2019:
2666
2667              $ 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
2672       Now:
2673
2674              $ 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
2678       Transactions spanning the closing date can complicate matters, breaking
2679       balance assertions:
2680
2681              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
2685       Here's one way to resolve that:
2686
2687              ; in 2018.journal:
2688              2018/12/30 a purchase made in 2018, clearing the following year
2689                  expenses:food          5
2690                  liabilities:pending
2691
2692              ; in 2019.journal:
2693              2019/1/2 clearance of last year's pending transactions
2694                  liabilities:pending    5 = 0
2695                  assets:checking
2696
2697   codes
2698       codes
2699       List the codes seen in transactions, in the order parsed.
2700
2701       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
2706       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
2710       You can add a query to select a subset of transactions.
2711
2712       Examples:
2713
2714              1/1 (123)
2715               (a)  1
2716
2717              1/1 ()
2718               (a)  1
2719
2720              1/1
2721               (a)  1
2722
2723              1/1 (126)
2724               (a)  1
2725
2726              $ hledger codes
2727              123
2728              124
2729              126
2730
2731              $ hledger codes -E
2732              123
2733              124
2734
2735
2736              126
2737
2738   commodities
2739       commodities
2740       List all commodity/currency symbols used or declared in the journal.
2741
2742   descriptions
2743       descriptions
2744       List the unique descriptions that appear in transactions.
2745
2746       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
2750       Example:
2751
2752              $ hledger descriptions
2753              Store Name
2754              Gas Station | Petrol
2755              Person A
2756
2757   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
2763       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
2769       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
2774       Examples:
2775
2776              $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro
2777              These transactions are in the first file only:
2778
2779              2014/01/01 Opening Balances
2780                  assets:bank:giro              EUR ...
2781                  ...
2782                  equity:opening balances       EUR -...
2783
2784              These transactions are in the second file only:
2785
2786   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
2791   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
2798       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
2802       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
2807   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
2814       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
2820       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
2823   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
2833       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
2837       1. new items always have the newest dates
2838
2839       2. item dates do not change across reads
2840
2841       3. and  items  with  the  same  date  remain in the same relative order
2842          across reads.
2843
2844       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
2850       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
2861       Note  deduplication  (and  updating of state files) can also be done by
2862       print --new, but this is less often used.
2863
2864   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
2871              $ hledger import --dry bank.csv | hledger -f- -I print unknown
2872
2873       or (live updating):
2874
2875              $ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'
2876
2877   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
2886              $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
2887
2888       (If you think import should leave amounts  implicit  like  print  does,
2889       please test it and send a pull request.)
2890
2891   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
2895   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
2901       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
2906       Example:
2907
2908              $ hledger incomestatement
2909              Income Statement
2910
2911              Revenues:
2912                               $-2  income
2913                               $-1    gifts
2914                               $-1    salary
2915              --------------------
2916                               $-2
2917
2918              Expenses:
2919                                $2  expenses
2920                                $1    food
2921                                $1    supplies
2922              --------------------
2923                                $2
2924
2925              Total:
2926              --------------------
2927                                 0
2928
2929       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
2935       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
2939   notes
2940       notes
2941       List the unique notes that appear in transactions.
2942
2943       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
2948       Example:
2949
2950              $ hledger notes
2951              Petrol
2952              Snacks
2953
2954   payees
2955       payees
2956       List the unique payee/payer names that appear in transactions.
2957
2958       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
2962       The payee/payer is the part of the transaction description before  a  |
2963       character (or if there is no |, the whole description).
2964
2965       You  can  add query arguments to select a subset of transactions.  This
2966       implies --used.
2967
2968       Example:
2969
2970              $ hledger payees
2971              Store Name
2972              Gas Station
2973              Person A
2974
2975   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
2983   print
2984       print
2985       Show transaction journal entries, sorted by date.
2986
2987       The print command displays full journal entries (transactions) from the
2988       journal file, sorted by date (or with --date2, by secondary date).
2989
2990       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
2995       Amounts are shown right-aligned within each transaction (but not across
2996       all transactions).
2997
2998       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
3003       Eg:
3004
3005              $ hledger print
3006              2008/01/01 income
3007                  assets:bank:checking            $1
3008                  income:salary                  $-1
3009
3010              2008/06/01 gift
3011                  assets:bank:checking            $1
3012                  income:gifts                   $-1
3013
3014              2008/06/02 save
3015                  assets:bank:saving              $1
3016                  assets:bank:checking           $-1
3017
3018              2008/06/03 * eat & shop
3019                  expenses:food                $1
3020                  expenses:supplies            $1
3021                  assets:cash                 $-2
3022
3023              2008/12/31 * pay off
3024                  liabilities:debts               $1
3025                  assets:bank:checking           $-1
3026
3027       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
3031              # 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
3035       There are some situations where print's output can become unparseable:
3036
3037       • Valuation affects posting amounts but not balance assertion  or  bal‐
3038         ance assignment amounts, potentially causing those to fail.
3039
3040       • Auto postings can generate postings with too many missing amounts.
3041
3042       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
3051       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
3056       With  -B/--cost,  amounts with transaction prices are converted to cost
3057       using that price.  This can be used for troubleshooting.
3058
3059       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
3064       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
3068       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
3072       Here's an example of print's CSV output:
3073
3074              $ 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
3088       • There  is  one  CSV record per posting, with the parent transaction's
3089         fields repeated.
3090
3091       • 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
3096       • The  amount  is  separated into "commodity" (the symbol) and "amount"
3097         (numeric quantity) fields.
3098
3099       • 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
3104   print-unique
3105       print-unique
3106       Print transactions which do not reuse an already-seen description.
3107
3108       Example:
3109
3110              $ 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
3120   register
3121       register, reg
3122       Show postings and their running total.
3123
3124       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
3129       register normally shows line per posting, but note that multi-commodity
3130       amounts will occupy multiple lines (one line per commodity).
3131
3132       It  is  typically  used with a query selecting a particular account, to
3133       see that account's activity:
3134
3135              $ 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
3141       With --date2, it shows and sorts by secondary date instead.
3142
3143       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
3147              $ 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
3152       The --depth option limits the amount of sub-account detail displayed.
3153
3154       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
3160       The --related/-r flag shows the other postings in the  transactions  of
3161       the postings which would normally be shown.
3162
3163       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
3168              $ hledger register --related --invert assets:checking
3169
3170       With a reporting interval, register shows summary postings, one per in‐
3171       terval, aggregating the postings to each account:
3172
3173              $ hledger register --monthly income
3174              2008/01                 income:salary                          $-1          $-1
3175              2008/06                 income:gifts                           $-1          $-2
3176
3177       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
3180              $ 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
3194       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
3197              $ 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
3202       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
3207   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
3212       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
3217              <--------------------------------- width (W) ---------------------------------->
3218              date (10)  description (D)       account (W-41-D)     amount (12)   balance (12)
3219              DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA
3220
3221       and some examples:
3222
3223              $ 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
3230       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
3234   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
3242   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
3248       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
3254       Examples:
3255
3256              $ 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
3260       rewrites.hledger may consist of entries like:
3261
3262              = ^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
3267       Note  the  single  quotes to protect the dollar sign from bash, and the
3268       two spaces between account and amount.
3269
3270       More:
3271
3272              $ 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
3277       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
3285   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
3290              $ rewrite-rules.journal
3291
3292       Make contents look like this:
3293
3294              = ^income
3295                  (liabilities:tax)  *.33
3296
3297              = expenses:gifts
3298                  budget:gifts  *-1
3299                  assets:budget  *1
3300
3301       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
3305              $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
3306
3307       This is something similar to the commands pipeline:
3308
3309              $ 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
3314       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
3318   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
3322              $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'
3323
3324       Output might look like:
3325
3326              --- /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
3341       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
3346       Be careful.  Whole transaction being re-formatted in a style of  output
3347       from hledger print.
3348
3349       See also:
3350
3351       https://github.com/simonmichael/hledger/issues/99
3352
3353   rewrite vs. print --auto
3354       This  command  predates  print --auto, and currently does much the same
3355       thing, but with these differences:
3356
3357       • 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
3361       • rewrite's query limits which transactions can be rewritten;  all  are
3362         printed.  print --auto's query limits which transactions are printed.
3363
3364       • rewrite  applies  rules  specified on command line or in the journal.
3365         print --auto applies rules specified in the journal.
3366
3367   roi
3368       roi
3369       Shows the time-weighted (TWR) and money-weighted (IRR) rate  of  return
3370       on your investments.
3371
3372       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
3376       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
3381       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
3386       Price  directives  will be taken into account if you supply appropriate
3387       --cost or --value flags (see VALUATION).
3388
3389       Note, in some cases this report can fail, for these reasons:
3390
3391       • 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
3395       • 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
3399       Examples:
3400
3401       • 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
3405       • Cookbook -> Return on Investment
3406
3407   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
3411       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
3417       • "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
3421                2019-01-01 Investing in Snake Oil
3422                  assets:cash          -$100
3423                  investment:snake oil
3424
3425                2020-01-01 Selling my Snake Oil
3426                  assets:cash           $10
3427                  investment:snake oil  = 0
3428
3429       • "Profit and loss" is change in the value of your investment:
3430
3431                2019-06-01 Snake Oil falls in value
3432                  investment:snake oil  = $57
3433                  equity:unrealized profit or loss
3434
3435       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
3440       Example: if you use --inv snake --pnl equity:unrealized, then  postings
3441       in the example below would be classifed as:
3442
3443              2019-01-01 Snake Oil #1
3444                assets:cash          -$100   ; cash flow posting
3445                investment:snake oil         ; investment posting
3446
3447              2019-03-01 Snake Oil #2
3448                equity:unrealized pnl  -$100 ; profit and loss posting
3449                snake oil                    ; investment posting
3450
3451              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
3456   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
3461       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
3467       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
3478       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
3483       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
3490       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
3497       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
3504       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
3510       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
3514   stats
3515       stats
3516       Show some journal statistics.
3517
3518       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
3522       Example:
3523
3524              $ 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
3537       This command also supports output destination and output format  selec‐
3538       tion.
3539
3540   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
3547       With the --values flag, the tags' unique values are listed instead.
3548
3549       With --parsed flag, all tags or values are shown in the order they  are
3550       parsed from the input data, including duplicates.
3551
3552       With  -E/--empty,  any blank/empty values will also be shown, otherwise
3553       they are omitted.
3554
3555   test
3556       test
3557       Run built-in unit tests.
3558
3559       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
3563       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
3568       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
3572              $ hledger test -- -pData.Amount --color=never
3573
3574       For  help  on these, see https://github.com/feuerbach/tasty#options (--
3575       --help currently doesn't show them).
3576
3577   About add-on commands
3578       Add-on commands are programs or scripts in your PATH
3579
3580       • whose name starts with hledger-
3581
3582       • whose name ends with a  recognised  file  extension:  .bat,.com,.exe,
3583         .hs,.lhs,.pl,.py,.rb,.rkt,.sh or none
3584
3585       • and (on unix, mac) which are executable by the current user.
3586
3587       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
3594       Note in a hledger command line, add-on command flags must have a double
3595       dash (--) preceding them.  Eg you must write:
3596
3597              $ hledger web -- --serve
3598
3599       and not:
3600
3601              $ hledger web --serve
3602
3603       (because the --serve flag belongs to hledger-web, not hledger).
3604
3605       The -h/--help and --version flags don't require --.
3606
3607       If you have any trouble with this, remember you can always run the add-
3608       on program directly, eg:
3609
3610              $ hledger-web --serve
3611

JOURNAL FORMAT

3613       hledger's default file format, representing a General Journal.
3614
3615       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
3623       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
3629       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
3632       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
3639       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
3645   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
3650       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
3654       • a status character (empty, !, or *)
3655
3656       • a code (any short number or text, enclosed in parentheses)
3657
3658       • a description (any remaining text until end of line or a semicolon)
3659
3660       • a comment (any remaining text following  a  semicolon  until  end  of
3661         line, and any following indented lines beginning with a semicolon)
3662
3663       • 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
3667       Here's a simple journal file containing one transaction:
3668
3669              2008/01/01 income
3670                assets:bank:checking   $1
3671                income:salary         $-1
3672
3673   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
3682       (The UI also accepts simple dates, as well as the more  flexible  smart
3683       dates documented in the hledger manual.)
3684
3685   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
3691       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
3696       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
3702       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
3706              2010/2/23=2/19 movie ticket
3707                expenses:cinema                   $10
3708                assets:checking
3709
3710              $ hledger register checking
3711              2010-02-23 movie ticket         assets:checking                $-10         $-10
3712
3713              $ hledger register checking --date2
3714              2010-02-19 movie ticket         assets:checking                $-10         $-10
3715
3716   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
3724              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
3728              $ hledger -f t.j register food
3729              2015-05-30                      expenses:food                  $10           $10
3730
3731              $ hledger -f t.j register checking
3732              2015-06-01                      assets:checking               $-10          $-10
3733
3734       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
3740       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
3746   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
3752       mark     status
3753       ──────────────────
3754                unmarked
3755       !        pending
3756       *        cleared
3757
3758       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
3762       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
3766       To  replicate Ledger and old hledger's behaviour of also matching pend‐
3767       ing, combine -U and -P.
3768
3769       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
3774       What  "uncleared", "pending", and "cleared" actually mean is up to you.
3775       Here's one suggestion:
3776
3777       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
3785       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
3790   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
3797   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
3804   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
3810       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
3816       Some examples:
3817
3818              # a file comment
3819              ; another file comment
3820              * also a file comment, useful in org/orgstruct mode
3821
3822              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
3828              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
3836       You can also comment larger regions of a file  using  comment  and  end
3837       comment directives.
3838
3839   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
3843       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
3846              2017/1/16 bought groceries  ; sometag:
3847
3848       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
3851                  expenses:food    $10 ; a-posting-tag: the tag value
3852
3853       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
3857                  assets:checking  ; a comment containing tag1:, tag2: some value ...
3858
3859       Here,
3860
3861       • "a comment containing" is just comment text, not a tag
3862
3863       • "tag1" is a tag with no value
3864
3865       • "tag2" is another tag, whose value is "some value ..."
3866
3867       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
3872              1/1 a transaction  ; A:, TAG2:
3873                  ; third-tag: a third transaction tag, <- with a value
3874                  (a)  $1  ; posting-tag:
3875
3876       Tags  are  like  Ledger's metadata feature, except hledger's tag values
3877       are simple strings.
3878
3879   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
3884       • (optional) a status character (empty, !, or *), followed by a space
3885
3886       • (required) an account name (any text,  optionally  containing  single
3887         spaces, until end of line or a double space)
3888
3889       • (optional) two or more spaces or tabs followed by an amount.
3890
3891       Positive  amounts  are being added to the account, negative amounts are
3892       being removed.
3893
3894       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
3898       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
3903   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
3908       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
3913              1/1 opening balances
3914                (assets:checking)   $1000
3915                (assets:savings)    $2000
3916
3917       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
3921              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
3929       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
3933   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
3939       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
3943       Account names can be aliased.
3944
3945   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
3949       hledger's amount format is flexible, supporting  several  international
3950       formats.   Here  are  some examples.  Amounts have a number (the "quan‐
3951       tity"):
3952
3953              1
3954
3955       ..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
3959              $1
3960              4000 AAPL
3961
3962       If the commodity name contains spaces, numbers, or punctuation, it must
3963       be enclosed in double quotes:
3964
3965              3 "no. 42 green apples"
3966
3967       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
3971              -$1
3972              $-1
3973
3974       One  or more spaces between the sign and the number are acceptable when
3975       parsing (but they won't be displayed in output):
3976
3977              + $1
3978              $-      1
3979
3980       Scientific E notation is allowed:
3981
3982              1E-6
3983              EUR 1E3
3984
3985   Decimal marks, digit group marks
3986       A decimal mark can be written as a period or a comma:
3987
3988              1.23
3989              1,23456780000009
3990
3991       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
3995                   $1,000,000.00
3996                EUR 2.000.000,00
3997              INR 9,99,99,999.00
3998                    1 000 000.9455
3999
4000       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
4003              1,000
4004              1.000
4005
4006       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
4013              # 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
4019       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
4025   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
4030       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
4033       Then  each  commodity's style is inferred from one of the following, in
4034       order of preference:
4035
4036       • The commodity directive for that commodity (including  the  no-symbol
4037         commodity), if any.
4038
4039       • 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
4043       • The  built-in fallback style, which looks like this: $1000.00.  (Sym‐
4044         bol on the left, period decimal mark, two decimal places.)
4045
4046       A style is inferred from journal amounts as follows:
4047
4048       • Use the general style (decimal mark, symbol placement) of  the  first
4049         amount
4050
4051       • Use  the  first-seen digit group style (digit group mark, digit group
4052         sizes), if any
4053
4054       • Use the maximum number of decimal places of all.
4055
4056       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
4061       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
4068              # 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
4075   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
4083   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
4092       There are several ways to record a transaction price:
4093
4094       1. Write the price per unit, as @ UNITPRICE after the amount:
4095
4096                  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
4100       2. Write the total price, as @@ TOTALPRICE after the amount:
4101
4102                  2009/1/1
4103                    assets:euros     €100 @@ $135  ; one hundred euros purchased at $135 for the lot
4104                    assets:dollars
4105
4106       3. Specify amounts for all postings, using exactly two commodities, and
4107          let hledger infer the price that balances the transaction:
4108
4109                  2009/1/1
4110                    assets:euros     €100          ; one hundred euros purchased
4111                    assets:dollars  $-135          ; for $135
4112
4113       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
4117       5. Like 2, but as in 4 the @@ is parenthesised, i.e.  (@@); in hledger,
4118          this is equivalent to 2.
4119
4120       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
4124              $ 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
4131       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
4136              2009/1/1
4137                assets:dollars  $-135              ; 135 dollars sold
4138                assets:euros     €100              ; for 100 euros
4139
4140              $ hledger bal -N --flat -B
4141                             €-100  assets:dollars  # <- the dollars' selling price
4142                              €100  assets:euros
4143
4144   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
4153   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
4159              2013/1/1
4160                a   $1  =$1
4161                b       =$-1
4162
4163              2013/1/2
4164                a   $1  =$2
4165                b  $-1  =$-2
4166
4167       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
4175   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
4182       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
4189   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
4196   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
4200   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
4206       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
4209       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
4213              2013/1/1
4214                a   $1
4215                a    1€
4216                b  $-1
4217                c   -1€
4218
4219              2013/1/2  ; These assertions succeed
4220                a    0  =  $1
4221                a    0  =   1€
4222                b    0 == $-1
4223                c    0 ==  -1€
4224
4225              2013/1/3  ; This assertion fails as 'a' also contains 1€
4226                a    0 ==  $1
4227
4228       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
4232              2013/1/1
4233                a:usd   $1
4234                a:euro   1€
4235                b
4236
4237              2013/1/2
4238                a        0 ==  0
4239                a:usd    0 == $1
4240                a:euro   0 ==  1€
4241
4242   Assertions and prices
4243       Balance  assertions  ignore  transaction prices, and should normally be
4244       written without one:
4245
4246              2019/1/1
4247                (a)     $1 @ €1 = $1
4248
4249       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
4255   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
4260              2019/1/1
4261                equity:opening balances
4262                checking:a       5
4263                checking:b       5
4264                checking         1  ==* 11
4265
4266   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
4270   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
4276   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
4283              ; 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
4290       or when adjusting a balance to reality:
4291
4292              ; 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
4297       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
4304   Balance assignments and prices
4305       A  transaction  price in a balance assignment will cause the calculated
4306       amount to have that price attached:
4307
4308              2019/1/1
4309                (a)             = $1 @ €2
4310
4311              $ hledger print --explicit
4312              2019-01-01
4313                  (a)         $1 @ €2 = $1 @ €2
4314
4315   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
4321       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
4326       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
4382       And some definitions:
4383
4384       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
4397       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
4401   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
4407       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
4413       It can be surprising though; for example, it means  that  alias  direc‐
4414       tives do not affect parent or sibling files (see below).
4415
4416   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
4421   Including other files
4422       You  can  pull in the content of additional files by writing an include
4423       directive, like this:
4424
4425              include FILEPATH
4426
4427       Only journal files can include, and only journal, timeclock or  timedot
4428       files can be included (not CSV files, currently).
4429
4430       If  the  file  path  does not begin with a slash, it is relative to the
4431       current file's folder.
4432
4433       A tilde means home directory, eg: include ~/main.journal.
4434
4435       The path may contain glob patterns to match multiple files, eg: include
4436       *.journal.
4437
4438       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
4443       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
4447   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
4452              Y2009  ; set default year to 2009
4453
4454              12/15  ; equivalent to 2009/12/15
4455                expenses  1
4456                assets
4457
4458              Y2010  ; change default year to 2010
4459
4460              2009/1/30  ; specifies the year, not affected
4461                expenses  1
4462                assets
4463
4464              1/31   ; equivalent to 2010/1/31
4465                expenses  1
4466                assets
4467
4468   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
4474              payee Whole Foods
4475
4476   Declaring commodities
4477       The commodity directive has several functions:
4478
4479       1. It  declares  commodities which may be used in the journal.  This is
4480          currently not enforced, but can serve as documentation.
4481
4482       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
4487       3. It  declares  a  commodity's  display  style in output - decimal and
4488          digit group marks, number of decimal places, symbol placement etc.
4489
4490       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
4494       A commodity directive is just the word commodity followed by an amount.
4495       It may be written on a single line, like this:
4496
4497              ; commodity EXAMPLEAMOUNT
4498
4499              ; 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
4504       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
4508              ; commodity SYMBOL
4509              ;   format EXAMPLEAMOUNT
4510
4511              ; 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
4517       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
4521       Note  hledger  normally  uses  banker's rounding, so 0.5 displayed with
4522       zero decimal digits is "0".  (More at Commodity display style.)
4523
4524   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
4530   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
4536       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
4542       The syntax is D AMOUNT.  Eg:
4543
4544              ; 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
4548              1/1
4549                a     5  ; <- commodity-less amount, parsed as $5 and displayed as $5.00
4550                b
4551
4552   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
4558       Here is the format:
4559
4560              P DATE COMMODITYA COMMODITYBAMOUNT
4561
4562       • DATE is a simple date
4563
4564       • COMMODITYA is the symbol of the commodity being priced
4565
4566       • 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
4569       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
4572              P 2009/1/1 € $1.35
4573              P 2010/1/1 € $1.40
4574
4575       The  -V,  -X  and  --value flags use these market prices to show amount
4576       values in another commodity.  See Valuation.
4577
4578   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
4583       • They can document your intended chart of accounts, providing a refer‐
4584         ence.
4585
4586       • They  can  help  hledger know your accounts' types (asset, liability,
4587         equity, revenue, expense), useful for reports like  balancesheet  and
4588         incomestatement.
4589
4590       • They  control  account  display order in reports, allowing non-alpha‐
4591         betic sorting (eg Revenues to appear above Expenses).
4592
4593       • They can store extra information  about  accounts  (account  numbers,
4594         notes, etc.)
4595
4596       • They  help  with account name completion in the add command, hledger-
4597         iadd, hledger-web, ledger-mode etc.
4598
4599       • In strict mode, they restrict which accounts  may  be  posted  to  by
4600         transactions, which helps detect typos.
4601
4602       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
4606              account assets:bank:checking
4607
4608   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
4615       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
4619       • The  declaration is case-sensitive; transactions must use the correct
4620         account name capitalisation.
4621
4622       • 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
4628       • Accounts can only be declared in journal files (but will  affect  in‐
4629         cluded files in other formats).
4630
4631       • It's  currently  not  possible  to declare "all possible subaccounts"
4632         with a wildcard; every account posted to must be declared.
4633
4634   Account comments
4635       Comments, beginning with a semicolon, can be added:
4636
4637       • on the same line, after two or more spaces (because ; is  allowed  in
4638         account names)
4639
4640       • on the next lines, indented
4641
4642       An example of both:
4643
4644              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
4648       Same-line comments are not supported by Ledger, or hledger <1.13.
4649
4650   Account subdirectives
4651       We  also  allow  (and ignore) Ledger-style indented subdirectives, just
4652       for compatibility.:
4653
4654              account assets:bank:checking
4655                format blah blah  ; <- subdirective, ignored
4656
4657       Here is the full syntax of account directives:
4658
4659              account ACCTNAME  [ACCTTYPE] [;COMMENT]
4660                [;COMMENTS]
4661                [LEDGER-STYLE SUBDIRECTIVES, IGNORED]
4662
4663   Account types
4664       hledger recognises five main types of account, corresponding to the ac‐
4665       count classes in the accounting equation:
4666
4667       Asset, Liability, Equity, Revenue, Expense.
4668
4669       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
4673       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
4678   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
4682       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
4687              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
4695   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
4700       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
4710       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
4715       Even so, explicit declarations may be a good idea, for clarity and pre‐
4716       dictability.
4717
4718   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
4726              account liabilities  ; type:Equity
4727
4728              2020-01-01
4729                assets        1
4730                liabilities   1
4731                equity       -2
4732
4733   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
4738              account assets       A
4739              account liabilities  L
4740              account equity       E
4741              account revenues     R
4742              account expenses     X
4743
4744   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
4750              account assets
4751              account liabilities
4752              account equity
4753              account revenues
4754              account expenses
4755
4756       you'll see those accounts displayed in declaration order, not alphabet‐
4757       ically:
4758
4759              $ hledger accounts -1
4760              assets
4761              liabilities
4762              equity
4763              revenues
4764              expenses
4765
4766       Undeclared accounts, if any, are displayed last, in alphabetical order.
4767
4768       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
4772              account other:zoo
4773
4774       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
4777       • 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
4781       • sibling  accounts  stay together (you couldn't display x:y in between
4782         a:b and a:c).
4783
4784   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
4788       • expanding shorthand account names to their full form, allowing easier
4789         data entry and a less verbose journal
4790
4791       • adapting old journals to your current chart of accounts
4792
4793       • experimenting with new account organisations, like a new hierarchy or
4794         combining two accounts into one
4795
4796       • customising reports
4797
4798       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
4802       See also Rewrite account names.
4803
4804   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
4809              alias OLD = NEW
4810
4811       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
4814       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
4818              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
4821   Regex aliases
4822       There is also a more powerful variant that uses a  regular  expression,
4823       indicated by the forward slashes:
4824
4825              alias /REGEX/ = REPLACEMENT
4826
4827       or --alias '/REGEX/=REPLACEMENT'.
4828
4829       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
4834              alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
4835              ; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"
4836
4837       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
4841   Combining aliases
4842       You can define as many aliases as you like,  using  journal  directives
4843       and/or command line options.
4844
4845       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
4849       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
4853       1. alias  directives  preceding the journal entry, most recently parsed
4854          first (ie, reading upward from the journal entry, bottom to top)
4855
4856       2. --alias options, in the order they  appeared  on  the  command  line
4857          (left to right).
4858
4859       In other words, for (an account name in) a given journal entry:
4860
4861       • the nearest alias declaration before/above the entry is applied first
4862
4863       • the next alias before/above that will be be applied next, and so on
4864
4865       • aliases defined after/below the entry do not affect it.
4866
4867       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
4871       In  case  of  trouble,  adding  --debug=6 to the command line will show
4872       which aliases are being applied when.
4873
4874   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
4878              hledger -f a.aliases -f b.journal
4879
4880       account  aliases  defined  in a.aliases will not affect b.journal.  In‐
4881       cluding the aliases doesn't work either:
4882
4883              include a.aliases
4884
4885              2020-01-01  ; not affected by a.aliases
4886                foo  1
4887                bar
4888
4889       This means that account aliases should usually be declared at the start
4890       of your top-most file, like this:
4891
4892              alias foo=Foo
4893              alias bar=Bar
4894
4895              2020-01-01  ; affected by aliases above
4896                foo  1
4897                bar
4898
4899              include c.journal  ; also affected
4900
4901   end aliases
4902       You  can  clear  (forget)  all  currently  defined aliases with the end
4903       aliases directive:
4904
4905              end aliases
4906
4907   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
4912              apply account home
4913
4914              2010/1/1
4915                  food    $10
4916                  cash
4917
4918              end apply account
4919
4920       which is equivalent to:
4921
4922              2010/01/01
4923                  home:food           $10
4924                  home:cash          $-10
4925
4926       If end apply account is omitted, the effect lasts to  the  end  of  the
4927       file.  Included files are also affected, eg:
4928
4929              apply account business
4930              include biz.journal
4931              end apply account
4932              apply account personal
4933              include personal.journal
4934
4935       Prior  to  hledger 1.0, legacy account and end spellings were also sup‐
4936       ported.
4937
4938       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
4943   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
4949       Periodic transactions can be a little tricky, so before you  use  them,
4950       read this whole section - or at least these tips:
4951
4952       1. Two  spaces  accidentally  added or omitted will cause you trouble -
4953          read about this below.
4954
4955       2. For troubleshooting, show the generated  transactions  with  hledger
4956          print   --forecast  tag:generated  or  hledger  register  --forecast
4957          tag:generated.
4958
4959       3. Forecasted transactions will begin only  after  the  last  non-fore‐
4960          casted transaction's date.
4961
4962       4. Forecasted  transactions  will  end 6 months from today, by default.
4963          See below for the exact start/end rules.
4964
4965       5. period expressions can be tricky.   Their  documentation  needs  im‐
4966          provement, but is worth studying.
4967
4968       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
4973       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
4980       Periodic transaction rules also have a second meaning: they are used to
4981       define budget goals, shown in budget reports.
4982
4983   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
4988              ~ monthly
4989                  expenses:rent          $2000
4990                  assets:bank:checking
4991
4992       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
4996       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
5001   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
5007              ; 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
5014       So,
5015
5016       • Do write two spaces between your period expression and your  transac‐
5017         tion description, if any.
5018
5019       • Don't  accidentally write two spaces in the middle of your period ex‐
5020         pression.
5021
5022   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
5031       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
5037       Periodic transactions are generated within some  forecast  period.   By
5038       default, this
5039
5040       • begins on the later of
5041
5042         • the report start date if specified with -b/-p/date:
5043
5044         • the  day  after the latest normal (non-periodic) transaction in the
5045           journal, or today if there are no normal transactions.
5046
5047       • ends on the report end date  if  specified  with  -e/-p/date:,  or  6
5048         months (180 days) from today.
5049
5050       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
5056       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
5064   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
5072       See also: Budgeting and Forecasting.
5073
5074   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
5079       An auto posting rule looks a bit like a transaction:
5080
5081              = QUERY
5082                  ACCOUNT  AMOUNT
5083                  ...
5084                  ACCOUNT  [AMOUNT]
5085
5086       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
5091       • a  normal  amount  with a commodity symbol, eg $2.  This will be used
5092         as-is.
5093
5094       • a number, eg 2.  The commodity symbol (if any) from the matched post‐
5095         ing will be added to this.
5096
5097       • 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
5101       • 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
5105       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
5109              = expenses:groceries 'expenses:dining out'
5110                  (budget:funds:dining out)                 *-1
5111
5112       Some examples:
5113
5114              ; every time I buy food, schedule a dollar donation
5115              = expenses:food
5116                  (liabilities:charity)   $-1
5117
5118              ; 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
5123              2017/12/1
5124                expenses:food    $10
5125                assets:checking
5126
5127              2017/12/14
5128                expenses:gifts   $20
5129                assets:checking
5130
5131              $ hledger print --auto
5132              2017-12-01
5133                  expenses:food              $10
5134                  assets:checking
5135                  (liabilities:charity)      $-1
5136
5137              2017-12-14
5138                  expenses:gifts             $20
5139                  assets:checking
5140                  assets:checking:gifts     -$20
5141                  assets:checking            $20
5142
5143   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
5148   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
5153   Auto postings and transaction balancing / inferred amounts / balance asser‐
5154       tions
5155       Currently, auto postings are added:
5156
5157       • after missing amounts are inferred, and transactions are checked  for
5158         balancedness,
5159
5160       • but before balance assertions are checked.
5161
5162       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
5166   Auto posting tags
5167       Automated postings will have some extra tags:
5168
5169       • generated-posting:= QUERY - shows this was generated by an auto post‐
5170         ing rule, and the query
5171
5172       • _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
5176       Also, any transaction that has been changed by auto posting rules  will
5177       have these tags added:
5178
5179       • modified: - this transaction was modified
5180
5181       • _modified: - a hidden tag not appearing in the comment; this transac‐
5182         tion was modified "just now".
5183

CSV FORMAT

5185       How hledger reads CSV data, and the CSV rules file format.
5186
5187       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
5191       (To learn about writing CSV, see CSV output.)
5192
5193       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
5200       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
5207       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
5228       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
5231       There's an introductory Convert CSV files tutorial on hledger.org.
5232
5233   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
5238   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
5243              Date, Description, Id, Amount
5244              12/11/2019, Foo, 123, 10.23
5245
5246              # basic.csv.rules
5247              skip         1
5248              fields       date, description, _, amount
5249              date-format  %d/%m/%Y
5250
5251              $ hledger print -f basic.csv
5252              2019-11-12 Foo
5253                  expenses:unknown           10.23
5254                  income:unknown            -10.23
5255
5256       Default account names are chosen, since we didn't set them.
5257
5258   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
5263              Date,Details,Debit,Credit,Balance
5264              07/12/2012,LODGMENT       529898,,10.0,131.21
5265              07/12/2012,PAYMENT,5,,126
5266
5267              # bankofireland-checking.csv.rules
5268
5269              # skip the header line
5270              skip
5271
5272              # name the csv fields, and assign some of them as journal entry fields
5273              fields  date, description, amount-out, amount-in, balance
5274
5275              # 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
5284              # date is in UK/Ireland format
5285              date-format  %d/%m/%Y
5286
5287              # set the currency
5288              currency  EUR
5289
5290              # set the base account for all txns
5291              account1  assets:bank:boi:checking
5292
5293              $ 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
5298              2012-12-07 PAYMENT
5299                  assets:bank:boi:checking         EUR-5.0 = EUR126.0
5300                  expenses:unknown                  EUR5.0
5301
5302       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
5306   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
5311              "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
5315              # amazon-orders.csv.rules
5316
5317              # skip one header line
5318              skip 1
5319
5320              # 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
5324              # how to parse the date
5325              date-format %b %-d, %Y
5326
5327              # combine two fields to make the description
5328              description %toorfrom %name
5329
5330              # save the status as a tag
5331              comment     status:%amzstatus
5332
5333              # 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
5338              # set a generic account2
5339              account2    expenses:misc
5340              amount2     %amzamount
5341              # and maybe refine it further:
5342              #include categorisation.rules
5343
5344              # 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
5349              $ hledger -f amazon-orders.csv print
5350              2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo.  ; status:Completed
5351                  assets:amazon
5352                  expenses:misc          $20.00
5353
5354              2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc.  ; status:Completed
5355                  assets:amazon
5356                  expenses:misc          $25.00
5357                  expenses:fees           $1.00
5358
5359   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
5363              "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
5372              # paypal-custom.csv.rules
5373
5374              # 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
5382              fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note
5383
5384              skip  1
5385
5386              date-format  %-m/%-d/%Y
5387
5388              # ignore some paypal events
5389              if
5390              In Progress
5391              Temporary Hold
5392              Update to
5393               skip
5394
5395              # add more fields to the description
5396              description %description_ %itemtitle
5397
5398              # save some other fields as tags
5399              comment  itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
5400
5401              # 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
5409              # generate postings
5410
5411              # 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
5416              # the second posting will be money sent to/received from other party
5417              # (account2 is set below)
5418              amount2  -%grossamount
5419
5420              # 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
5426              # choose an account for the second posting
5427
5428              # 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
5436              # apply common rules for setting account2 & other tweaks
5437              include common.rules
5438
5439              # apply some overrides specific to this csv
5440
5441              # 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
5450              # Currency conversions
5451              if Currency Conversion
5452               account2 equity:currency conversion
5453
5454              # common.rules
5455
5456              if
5457              darcs
5458              noble benefactor
5459               account2 revenues:foss donations:darcshub
5460               comment2 business:
5461
5462              if
5463              Calm Radio
5464               account2 expenses:online:apps
5465
5466              if
5467              electronic frontier foundation
5468              Patreon
5469              wikimedia
5470              Advent of Code
5471               account2 expenses:dues
5472
5473              if Google
5474               account2 expenses:online:apps
5475               description google | music
5476
5477              $ 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
5482              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
5486              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
5490              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
5494              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
5499              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
5503              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
5508   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
5512   skip
5513              skip N
5514
5515       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
5520       It also has a second purpose: it can be used inside if blocks to ignore
5521       certain CSV records (described below).
5522
5523   fields
5524              fields FIELDNAME1, FIELDNAME2, ...
5525
5526       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
5530       1. it names the CSV fields.  This is optional, but  can  be  convenient
5531          later for interpolating them.
5532
5533       2. when you use a standard hledger field name, it assigns the CSV value
5534          to that part of the hledger transaction.
5535
5536       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
5540              fields date, description, , amount, , , somefield, anotherfield
5541
5542       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
5546       Note, always use comma in the fields list, even if your  CSV  uses  an‐
5547       other separator character.
5548
5549       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
5553   Transaction field names
5554       date, date2, status, code, description, comment can be used to form the
5555       transaction's first line.
5556
5557   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
5562       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
5567       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
5571   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
5577       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
5584       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
5592   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
5597   balance
5598       balanceN sets a balance assertion amount (or if the posting  amount  is
5599       left empty, a balance assignment) on posting N.
5600
5601       Also,  for  compatibility with hledger <1.17: balance with no number is
5602       equivalent to balance1.
5603
5604       You can adjust the type of assertion/assignment with  the  balance-type
5605       rule (see below).
5606
5607   comment
5608       Finally, commentN sets a comment on the Nth posting.  Comments can also
5609       contain tags, as usual.
5610
5611       See TIPS below for more about setting amounts and currency.
5612
5613   field assignment
5614              HLEDGERFIELDNAME FIELDVALUE
5615
5616       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
5623              # set the amount to the 4th CSV field, with " USD" appended
5624              amount %4 USD
5625
5626              # combine three fields to make a comment, containing note: and date: tags
5627              comment note: %somefield - %anotherfield, date: %1
5628
5629       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
5633   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
5639              separator ,
5640
5641       or for semicolon-separated values (SSV):
5642
5643              separator ;
5644
5645       or for tab-separated values (TSV):
5646
5647              separator TAB
5648
5649       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
5653   if block
5654              if MATCHER
5655               RULE
5656
5657              if
5658              MATCHER
5659              MATCHER
5660              MATCHER
5661               RULE
5662               RULE
5663
5664       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
5668   Matching the whole record
5669       Each MATCHER can be a record matcher, which looks like this:
5670
5671              REGEX
5672
5673       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
5679       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
5686   Matching individual fields
5687       Or, MATCHER can be a field matcher, like this:
5688
5689              %CSVFIELD REGEX
5690
5691       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
5695   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
5701              if
5702              MATCHER
5703              & MATCHER
5704               RULE
5705
5706   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
5711       • field assignments (to set a hledger field)
5712
5713       • skip (to skip the matched CSV record)
5714
5715       • end (to skip all remaining CSV records).
5716
5717       Examples:
5718
5719              # if the CSV record contains "groceries", set account2 to "expenses:groceries"
5720              if groceries
5721               account2 expenses:groceries
5722
5723              # 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
5731   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
5738       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
5742       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
5746       Therefore if table is exactly equivalent to a sequence of of if blocks:
5747
5748              if MATCHER1
5749                CSVFIELDNAME1 VALUE11
5750                CSVFIELDNAME2 VALUE12
5751                ...
5752                CSVFIELDNAMEn VALUE1n
5753
5754              if MATCHER2
5755                CSVFIELDNAME1 VALUE21
5756                CSVFIELDNAME2 VALUE22
5757                ...
5758                CSVFIELDNAMEn VALUE2n
5759
5760              if MATCHER3
5761                CSVFIELDNAME1 VALUE31
5762                CSVFIELDNAME2 VALUE32
5763                ...
5764                CSVFIELDNAMEn VALUE3n
5765
5766       Each line starting with MATCHER should contain enough (possibly  empty)
5767       values for all the listed fields.
5768
5769       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
5773       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
5779       Example:
5780
5781              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
5786   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
5791              # ignore everything following the first empty record
5792              if ,,,,
5793               end
5794
5795   date-format
5796              date-format DATEFMT
5797
5798       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
5804              # MM/DD/YY
5805              date-format %m/%d/%y
5806
5807              # D/M/YYYY
5808              # The - makes leading zeros optional.
5809              date-format %-d/%-m/%Y
5810
5811              # YYYY-Mmm-DD
5812              date-format %Y-%h-%d
5813
5814              # 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
5818       For the supported strptime syntax, see:
5819       https://hackage.haskell.org/package/time/docs/Data-Time-For
5820       mat.html#v:formatTime
5821
5822   decimal-mark
5823              decimal-mark .
5824
5825       or:
5826
5827              decimal-mark ,
5828
5829       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
5835   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
5841       • the  CSV  might  sometimes  contain just one day of data (all records
5842         having the same date)
5843
5844       • the CSV records are normally in reverse chronological  order  (newest
5845         at the top)
5846
5847       • and you care about preserving the order of same-day transactions
5848
5849       then, you should add the newest-first rule as a hint.  Eg:
5850
5851              # tell hledger explicitly that the CSV is normally newest first
5852              newest-first
5853
5854   include
5855              include RULESFILE
5856
5857       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
5862              # someaccount.csv.rules
5863
5864              ## someaccount-specific rules
5865              fields   date,description,amount
5866              account1 assets:someaccount
5867              account2 expenses:misc
5868
5869              ## common rules
5870              include categorisation.rules
5871
5872   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
5880              # balance assertions will consider all commodities and all subaccounts
5881              balance-type ==*
5882
5883       Here are the balance assertion types for quick reference:
5884
5885              =    single commodity, exclude subaccounts
5886              =*   single commodity, include subaccounts
5887              ==   multi commodity,  exclude subaccounts
5888              ==*  multi commodity,  include subaccounts
5889
5890   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
5896              $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
5897
5898       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
5903   Valid CSV
5904       hledger accepts CSV conforming to RFC 4180.  When CSV  values  are  en‐
5905       closed in quotes, note:
5906
5907       • they must be double quotes (not single quotes)
5908
5909       • spaces outside the quotes are not allowed
5910
5911   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
5917              $ hledger -f foo.ssv print
5918
5919       or:
5920
5921              $ cat foo | hledger -f ssv:- foo
5922
5923       You can override the file extension with a separator  rule  if  needed.
5924       See also: Input files in the hledger manual.
5925
5926   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
5932   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
5939       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
5944              $ hledger -f file.csv print | hledger -f- print
5945
5946   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
5951       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
5957              # download the latest CSV files, then run this command.
5958              # Note, no -f flags needed here.
5959              $ hledger import *.csv [--dry]
5960
5961       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
5964       A number of other tools and workflows, hledger-specific and  otherwise,
5965       exist for converting, deduplicating, classifying and managing CSV data.
5966       See:
5967
5968https://hledger.org -> sidebar -> real world setups
5969
5970https://plaintextaccounting.org -> data import/conversion
5971
5972   Setting amounts
5973       Some tips on using the amount-setting rules discussed above.
5974
5975       Here are the ways to set a posting's amount:
5976
5977       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
5981       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
5985If hledger guesses the wrong sign:
5986           Prepend a minus sign to flip it.  Eg:
5987
5988                    fields date, description, amount-in, amount-out
5989                    amount-out -%amount-out
5990
5991If 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
5996                    "",  ""
5997                    "0", "0"
5998                    "1", "none"
5999
6000             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
6004                    fields date, description, in, out
6005                    if %in [1-9]
6006                     amount1 %in
6007                    if %out [1-9]
6008                     amount1 %out
6009
6010       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
6016       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
6020If 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
6025                    fields date, description, balance1
6026                    account1 assets:checking
6027
6028   Amount signs
6029       There is some special handling for amount signs,  to  simplify  parsing
6030       and sign-flipping:
6031
6032If an amount value begins with a plus sign:
6033       that will be removed: +AMT becomes AMT
6034
6035If an amount value is parenthesised:
6036       it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT
6037
6038If  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
6042If 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
6047   Setting currency/commodity
6048       If the currency/commodity  symbol  is  included  in  the  CSV's  amount
6049       field(s):
6050
6051              2020-01-01,foo,$123.00
6052
6053       you don't have to do anything special for the commodity symbol, it will
6054       be assigned as part of the amount.  Eg:
6055
6056              fields date,description,amount
6057
6058              2020-01-01 foo
6059                  expenses:unknown         $123.00
6060                  income:unknown          $-123.00
6061
6062       If the currency is provided as a separate CSV field:
6063
6064              2020-01-01,foo,USD,123.00
6065
6066       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
6070              fields date,description,currency,amount
6071
6072              2020-01-01 foo
6073                  expenses:unknown       USD123.00
6074                  income:unknown        USD-123.00
6075
6076       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
6080              fields date,description,cur,amt
6081              amount %amt %cur
6082
6083              2020-01-01 foo
6084                  expenses:unknown        123.00 USD
6085                  income:unknown         -123.00 USD
6086
6087       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
6090   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
6095       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
6098   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
6104              # Name the third CSV field "amount1"
6105              fields date,description,amount1
6106
6107              # Set hledger's amount1 to the CSV amount1 field followed by USD
6108              amount1 %amount1 USD
6109
6110              # Set comment to the CSV amount1 (not the amount1 assigned above)
6111              comment %amount1
6112
6113       Here,  since there's no CSV amount1 field, %amount1 will produce a lit‐
6114       eral "amount1":
6115
6116              fields date,description,csvamount
6117              amount1 %csvamount USD
6118              # Can't interpolate amount1 here
6119              comment %amount1
6120
6121       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
6125              comment A
6126              comment B
6127              if something
6128               comment C
6129
6130   How CSV rules are evaluated
6131       Here's how to think of CSV rules being evaluated (if  you  really  need
6132       to).  First,
6133
6134       • 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
6138       Then  "global"  rules  are  evaluated, top to bottom.  If a rule is re‐
6139       peated, the last one wins:
6140
6141       • skip (at top level)
6142
6143       • date-format
6144
6145       • newest-first
6146
6147       • fields - names the CSV fields, optionally sets up initial assignments
6148         to hledger fields
6149
6150       Then for each CSV record in turn:
6151
6152       • 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
6157       • 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
6161       • 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
6165       • generate a synthetic hledger transaction from these values.
6166
6167       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

TIMECLOCK FORMAT

6173       The time logging format of timeclock.el, as read by hledger.
6174
6175       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
6182              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
6187       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
6192              $ hledger -f t.timeclock print
6193              2015-03-30 * optional description after two spaces
6194                  (some:account name)         0.33h
6195
6196              2015-03-31 * 22:21-23:59
6197                  (another account)         1.64h
6198
6199              2015-04-01 * 00:00-02:00
6200                  (another account)         2.01h
6201
6202       Here is a sample.timeclock to download and some queries to try:
6203
6204              $ 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
6208       To generate time logs, ie to clock in and clock out, you could:
6209
6210       • use  emacs  and the built-in timeclock.el, or the extended timeclock-
6211         x.el and perhaps the extras in ledgerutils.el
6212
6213       • 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
6217       • 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

TIMEDOT FORMAT

6222       hledger's human-friendly time logging format.
6223
6224       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
6231       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
6235       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
6240       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
6246       Quantities can be written as:
6247
6248       • dots: a sequence of dots (.) representing quarter hours.  Spaces  may
6249         optionally be used for grouping.  Eg: ....  ..
6250
6251       • an integral or decimal number, representing hours.  Eg: 1.5
6252
6253       • 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
6259       There  is  some  flexibility  allowing  notes and todo lists to be kept
6260       right in the time log, if needed:
6261
6262       • Blank lines and lines beginning with # or ; are ignored.
6263
6264       • 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
6268       • 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
6275       Examples:
6276
6277              # 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
6283              2016/2/2
6284              inc:client1   .... ....
6285              biz:research  .
6286
6287              2016/2/3
6288              inc:client1   4
6289              fos:hledger   3
6290              biz:research  1
6291
6292              * Time log
6293              ** 2020-01-01
6294              *** adm:time  .
6295              *** adm:finance  .
6296
6297              * 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
6313       Reporting:
6314
6315              $ hledger -f t.timedot print date:2016/2/2
6316              2016-02-02 *
6317                  (inc:client1)          2.00
6318
6319              2016-02-02 *
6320                  (biz:research)          0.25
6321
6322              $ hledger -f t.timedot bal --daily --tree
6323              Balance changes in 2016-02-01-2016-02-03:
6324
6325                          ||  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
6337       I  prefer to use period for separating account components.  We can make
6338       this work with an account alias:
6339
6340              2016/2/4
6341              fos.hledger.timedot  4
6342              fos.ledger           ..
6343
6344              $ 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
6351       Here is a sample.timedot.
6352

COMMON TASKS

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
6359   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
6368       Find   more   docs,   chat,   mail   list,   reddit,   issue   tracker:
6369       https://hledger.org#help-feedback
6370
6371   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
6377       • command-specific  options must go after the command (it's fine to put
6378         all options there) (hledger CMD OPTS ARGS)
6379
6380       • running add-on executables directly simplifies command  line  parsing
6381         (hledger-ui OPTS ARGS)
6382
6383       • enclose "problematic" args in single quotes
6384
6385       • if  needed, also add a backslash to hide regular expression metachar‐
6386         acters from the shell
6387
6388       • to see how a misbehaving command is being parsed, add --debug=2.
6389
6390   Starting a journal file
6391       hledger  looks  for  your  accounting   data   in   a   journal   file,
6392       $HOME/.hledger.journal by default:
6393
6394              $ 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
6399       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
6404              $ 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
6424   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
6429       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
6435       Add an opening balances transaction to the journal, declaring the  bal‐
6436       ances on this date.  Here are two ways to do it:
6437
6438       • The  first way: open the journal in any text editor and save an entry
6439         like this:
6440
6441                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
6448         These are start-of-day balances, ie whatever was in  the  account  at
6449         the end of the previous day.
6450
6451         The  *  after  the  date  is  an optional status flag.  Here it means
6452         "cleared & confirmed".
6453
6454         The currency symbols are optional, but usually a good idea as  you'll
6455         be dealing with multiple currencies sooner or later.
6456
6457         The  = amounts are optional balance assertions, providing extra error
6458         checking.
6459
6460       • The second way: run hledger add and follow the prompts  to  record  a
6461         similar transaction:
6462
6463                $ 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
6492                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
6497       If  you're  using  version control, this could be a good time to commit
6498       the journal.  Eg:
6499
6500              $ git commit -m 'initial balances' 2020.journal
6501
6502   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
6508       Here  are  some  simple transactions, see the hledger_journal(5) manual
6509       and hledger.org for more ideas:
6510
6511              2020/1/10 * gift received
6512                assets:cash   $20
6513                income:gifts
6514
6515              2020.1.12 * farmers market
6516                expenses:food    $13
6517                assets:cash
6518
6519              2020-01-15 paycheck
6520                income:salary
6521                assets:bank:checking    $1000
6522
6523   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
6533       A typical workflow:
6534
6535       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
6543                  2020-01-16 * adjust cash
6544                      assets:cash    $-2 = $105
6545                      expenses:misc
6546
6547       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
6557       3. Repeat for other asset/liability accounts.
6558
6559       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
6563       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
6568       If you're using version control, this can be another good time to  com‐
6569       mit:
6570
6571              $ git commit -m 'txns' 2020.journal
6572
6573   Reporting
6574       Here are some basic reports.
6575
6576       Show all transactions:
6577
6578              $ 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
6586              2020-01-10 * gift received
6587                  assets:cash              $20
6588                  income:gifts
6589
6590              2020-01-12 * farmers market
6591                  expenses:food             $13
6592                  assets:cash
6593
6594              2020-01-15 * paycheck
6595                  income:salary
6596                  assets:bank:checking           $1000
6597
6598              2020-01-16 * adjust cash
6599                  assets:cash               $-2 = $105
6600                  expenses:misc
6601
6602       Show account names, and their hierarchy:
6603
6604              $ 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
6621       Show all account totals:
6622
6623              $ 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
6640       Show  only  asset  and  liability  balances, as a flat list, limited to
6641       depth 2:
6642
6643              $ hledger bal assets liabilities --flat -2
6644                             $4000  assets:bank
6645                              $105  assets:cash
6646                              $-50  liabilities:creditcard
6647              --------------------
6648                             $4055
6649
6650       Show the same thing without negative numbers,  formatted  as  a  simple
6651       balance sheet:
6652
6653              $ hledger bs --flat -2
6654              Balance Sheet 2020-01-16
6655
6656                                      || 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
6673       The final total is your "net worth" on the end date.  (Or use bse for a
6674       full balance sheet with equity.)
6675
6676       Show income and expense totals, formatted as an income statement:
6677
6678              hledger is
6679              Income Statement 2020-01-01-2020-01-16
6680
6681                             || 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
6699       The final total is your net income during this period.
6700
6701       Show transactions affecting your wallet, with running total:
6702
6703              $ 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
6709       Show weekly posting counts as a bar chart:
6710
6711              $ hledger activity -W
6712              2019-12-30 *****
6713              2020-01-06 ****
6714              2020-01-13 ****
6715
6716   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
6722       If using version control, don't forget to git add the new file.
6723

LIMITATIONS

6725       The  need  to  precede add-on command options with -- when invoked from
6726       hledger is awkward.
6727
6728       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
6732       In a Microsoft Windows CMD window, non-ascii characters and colours are
6733       not supported.
6734
6735       On Windows, non-ascii characters may not display correctly when running
6736       a hledger built in CMD in MSYS/CYGWIN, or vice-versa.
6737
6738       In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
6739       add.
6740
6741       Not  all of Ledger's journal file syntax is supported.  See file format
6742       differences.
6743
6744       On large data files, hledger  is  slower  and  uses  more  memory  than
6745       Ledger.
6746

TROUBLESHOOTING

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
6752       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
6757       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
6762       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
6770       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
6773       Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux:
6774
6775              $ 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
6785       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
6789              $ 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
6801       Here's how you could set it permanently, if you use a bash shell:
6802
6803              $ echo "export LANG=en_US.utf8" >>~/.bash_profile
6804              $ bash --login
6805
6806       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
6810              $ locale -a | grep -iE en_us.*utf
6811              en_US.UTF-8
6812              $ LANG=en_US.UTF-8 hledger -f my.journal print
6813
6814
6815

REPORTING BUGS

6817       Report  bugs at http://bugs.hledger.org (or on the #hledger IRC channel
6818       or hledger mail list)
6819
6820

AUTHORS

6822       Simon Michael <simon@joyful.com> and contributors
6823
6824
6826       Copyright (C) 2007-2020 Simon Michael.
6827       Released under GNU GPL v3 or later.
6828
6829

SEE ALSO

6831       hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
6832
6833
6834
6835hledger-1.21                     December 2020                      HLEDGER(1)
Impressum