summaryrefslogtreecommitdiff
path: root/hledger_journal.txt
blob: 210741d52c159f883ae66c27748fe415e57c5e04 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597

HLEDGER_JOURNAL(5)           hledger User Manuals           HLEDGER_JOURNAL(5)



NAME
       hledger's default file format, representing a General Journal.

DESCRIPTION
       hledger's  usual  data  source  is a plain text file containing journal
       entries in hledger journal format.  This  file  represents  a  standard
       accounting  general  journal.  I use file names ending in .journal, but
       that's not required.  The journal file contains a number of transaction
       entries, each describing a transfer of money (or any commodity) between
       two or more named accounts, in a simple format readable by both hledger
       and humans.

       hledger's  journal  format  is a compatible subset, mostly, of ledger's
       journal format, so hledger can  work  with  compatible  ledger  journal
       files  as  well.   It's  safe,  and encouraged, to run both hledger and
       ledger on the same journal file, eg to validate the results you're get-
       ting.

       You can use hledger without learning any more about this file; just use
       the add or web or import commands to create and update it.

       Many users, though, edit the journal file with a text editor, and track
       changes  with a version control system such as git.  Editor addons such
       as ledger-mode or hledger-mode  for  Emacs,  vim-ledger  for  Vim,  and
       hledger-vscode for Visual Studio Code, make this easier, adding colour,
       formatting, tab completion, and useful commands.  See Editor configura-
       tion at hledger.org for the full list.

       Here's  a  description  of  each part of the file format (and hledger's
       data model).  These are mostly in the order you'll  use  them,  but  in
       some  cases related concepts have been grouped together for easy refer-
       ence, or linked before they are introduced, so feel free to  skip  over
       anything that looks unnecessary right now.

TRANSACTIONS
       Transactions  are the main unit of information in a journal file.  They
       represent events, typically a movement of some quantity of  commodities
       between two or more named accounts.

       Each  transaction is recorded as a journal entry, beginning with a sim-
       ple date in column 0.  This can be followed by  any  of  the  following
       optional fields, separated by spaces:

       o a status character (empty, !, or *)

       o a code (any short number or text, enclosed in parentheses)

       o a description (any remaining text until end of line or a semicolon)

       o a  comment  (any  remaining  text  following a semicolon until end of
         line, and any following indented lines beginning with a semicolon)

       o 0 or more indented posting lines, describing what was transferred and
         the  accounts  involved (indented comment lines are also allowed, but
         not blank lines or non-indented lines).

       Here's a simple journal file containing one transaction:

              2008/01/01 income
                assets:bank:checking   $1
                income:salary         $-1

DATES
   Simple dates
       Dates in the journal  file  use  simple  dates  format:  YYYY-MM-DD  or
       YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional.  The year may be
       omitted, in which case it will be inferred from the context:  the  cur-
       rent  transaction,  the default year set with a default year directive,
       or  the  current  date  when  the  command  is  run.   Some   examples:
       2010-01-31, 2010/01/31, 2010.1.31, 1/31.

       (The  UI  also accepts simple dates, as well as the more flexible smart
       dates documented in the hledger manual.)

   Secondary dates
       Real-life transactions sometimes involve more than one date  -  eg  the
       date you write a cheque, and the date it clears in your bank.  When you
       want to model this, for more accurate daily balances, you  can  specify
       individual posting dates.

       Or,  you can use the older secondary date feature (Ledger calls it aux-
       iliary date or effective date).  Note: we support this for  compatibil-
       ity,  but  I usually recommend avoiding this feature; posting dates are
       almost always clearer and simpler.

       A secondary date is written after the primary date, following an equals
       sign.   If  the  year  is  omitted, the primary date's year is assumed.
       When running reports, the primary (left) date is used by  default,  but
       with  the  --date2  flag  (or --aux-date or --effective), the secondary
       (right) date will be used instead.

       The meaning of secondary dates is up to you, but it's best to follow  a
       consistent  rule.   Eg "primary = the bank's clearing date, secondary =
       date the transaction was initiated, if different", as shown here:

              2010/2/23=2/19 movie ticket
                expenses:cinema                   $10
                assets:checking

              $ hledger register checking
              2010-02-23 movie ticket         assets:checking                $-10         $-10

              $ hledger register checking --date2
              2010-02-19 movie ticket         assets:checking                $-10         $-10

   Posting dates
       You can give individual postings a different  date  from  their  parent
       transaction,  by  adding a posting comment containing a tag (see below)
       like date:DATE.  This is probably the best way to control posting dates
       precisely.   Eg  in  this  example  the  expense  should  appear in May
       reports, and the deduction from checking should be reported on 6/1  for
       easy bank reconciliation:

              2015/5/30
                  expenses:food     $10  ; food purchased on saturday 5/30
                  assets:checking        ; bank cleared it on monday, date:6/1

              $ hledger -f t.j register food
              2015-05-30                      expenses:food                  $10           $10

              $ hledger -f t.j register checking
              2015-06-01                      assets:checking               $-10          $-10

       DATE  should be a simple date; if the year is not specified it will use
       the year of the transaction's date.  You can  set  the  secondary  date
       similarly,  with  date2:DATE2.   The  date:  or date2: tags must have a
       valid simple date value if they are present, eg a  date:  tag  with  no
       value is not allowed.

       Ledger's earlier, more compact bracketed date syntax is also supported:
       [DATE], [DATE=DATE2] or [=DATE2].  hledger will attempt  to  parse  any
       square-bracketed sequence of the 0123456789/-.= characters in this way.
       With this syntax, DATE infers its year from the transaction  and  DATE2
       infers its year from DATE.

STATUS
       Transactions,  or  individual postings within a transaction, can have a
       status mark,  which  is  a  single  character  before  the  transaction
       description  or  posting  account  name,  separated from it by a space,
       indicating one of three statuses:


       mark     status
       ------------------
                unmarked
       !        pending
       *        cleared

       When reporting, you  can  filter  by  status  with  the  -U/--unmarked,
       -P/--pending,  and  -C/--cleared  flags;  or the status:, status:!, and
       status:* queries; or the U, P, C keys in hledger-ui.

       Note, in Ledger and in older versions of hledger, the "unmarked"  state
       is  called  "uncleared".   As  of  hledger  1.3  we  have renamed it to
       unmarked for clarity.

       To replicate Ledger and old hledger's behaviour of also matching  pend-
       ing, combine -U and -P.

       Status  marks  are optional, but can be helpful eg for reconciling with
       real-world accounts.  Some editor modes provide highlighting and short-
       cuts  for working with status.  Eg in Emacs ledger-mode, you can toggle
       transaction status with C-c C-e, or posting status with C-c C-c.

       What "uncleared", "pending", and "cleared" actually mean is up to  you.
       Here's one suggestion:


       status       meaning
       --------------------------------------------------------------------------
       uncleared    recorded but not yet reconciled; needs review
       pending      tentatively reconciled (if needed, eg during a big reconcil-
                    iation)
       cleared      complete, reconciled as far as possible, and considered cor-
                    rect

       With  this scheme, you would use -PC to see the current balance at your
       bank, -U to see things which will probably hit  your  bank  soon  (like
       uncashed checks), and no flags to see the most up-to-date state of your
       finances.

DESCRIPTION
       A transaction's description is the rest of the line following the  date
       and  status  mark  (or  until  a comment begins).  Sometimes called the
       "narration" in traditional bookkeeping, it can be used for whatever you
       wish,  or  left blank.  Transaction descriptions can be queried, unlike
       comments.

   Payee and note
       You can optionally include a | (pipe) character in descriptions to sub-
       divide the description into separate fields for payee/payer name on the
       left (up to the first |) and an additional  note  field  on  the  right
       (after  the  first  |).   This may be worthwhile if you need to do more
       precise querying and pivoting by payee or by note.

COMMENTS
       Lines in the journal beginning with a semicolon (;) or hash (#) or star
       (*)  are  comments, and will be ignored.  (Star comments cause org-mode
       nodes to be ignored, allowing emacs users to fold  and  navigate  their
       journals with org-mode or orgstruct-mode.)

       You  can  attach  comments  to  a transaction by writing them after the
       description and/or indented on the following lines  (before  the  post-
       ings).   Similarly, you can attach comments to an individual posting by
       writing them after the amount and/or indented on the  following  lines.
       Transaction and posting comments must begin with a semicolon (;).

       Some examples:

              # a file comment
              ; another file comment
              * also a file comment, useful in org/orgstruct mode

              comment
              A multiline file comment, which continues
              until a line containing just "end comment"
              (or end of file).
              end comment

              2012/5/14 something  ; a transaction comment
                  ; the transaction comment, continued
                  posting1  1  ; a comment for posting 1
                  posting2
                  ; a comment for posting 2
                  ; another comment line for posting 2
              ; a file comment (because not indented)

       You  can  also  comment  larger regions of a file using comment and end
       comment directives.

TAGS
       Tags are a way to add extra labels or labelled  data  to  postings  and
       transactions, which you can then search or pivot on.

       A  simple  tag is a word (which may contain hyphens) followed by a full
       colon, written inside a transaction or posting comment line:

              2017/1/16 bought groceries  ; sometag:

       Tags can have a value, which is the text after the  colon,  up  to  the
       next comma or end of line, with leading/trailing whitespace removed:

                  expenses:food    $10 ; a-posting-tag: the tag value

       Note  this  means  hledger's  tag values can not contain commas or new-
       lines.  Ending at commas means you can write multiple short tags on one
       line, comma separated:

                  assets:checking  ; a comment containing tag1:, tag2: some value ...

       Here,

       o "a comment containing" is just comment text, not a tag

       o "tag1" is a tag with no value

       o "tag2" is another tag, whose value is "some value ..."

       Tags  in  a  transaction  comment affect the transaction and all of its
       postings, while tags in a posting comment  affect  only  that  posting.
       For  example, the following transaction has three tags (A, TAG2, third-
       tag) and the posting has four (those plus posting-tag):

              1/1 a transaction  ; A:, TAG2:
                  ; third-tag: a third transaction tag, <- with a value
                  (a)  $1  ; posting-tag:

       Tags are like Ledger's metadata feature, except  hledger's  tag  values
       are simple strings.

POSTINGS
       A  posting  is an addition of some amount to, or removal of some amount
       from, an account.  Each posting line begins with at least one space  or
       tab (2 or 4 spaces is common), followed by:

       o (optional) a status character (empty, !, or *), followed by a space

       o (required)  an  account  name (any text, optionally containing single
         spaces, until end of line or a double space)

       o (optional) two or more spaces or tabs followed by an amount.

       Positive amounts are being added to the account, negative  amounts  are
       being removed.

       The amounts within a transaction must always sum up to zero.  As a con-
       venience, one amount may be left blank; it will be inferred  so  as  to
       balance the transaction.

       Be  sure  to  note the unusual two-space delimiter between account name
       and amount.  This makes it easy to write account names containing  spa-
       ces.   But if you accidentally leave only one space (or tab) before the
       amount, the amount will be considered part of the account name.

   Virtual postings
       A posting with a parenthesised account name is called a virtual posting
       or  unbalanced  posting,  which  means it is exempt from the usual rule
       that a transaction's postings must balance add up to zero.

       This is not part of double entry accounting, so  you  might  choose  to
       avoid  this  feature.   Or you can use it sparingly for certain special
       cases where it can be convenient.  Eg, you could set  opening  balances
       without using a balancing equity account:

              1/1 opening balances
                (assets:checking)   $1000
                (assets:savings)    $2000

       A  posting  with  a bracketed account name is called a balanced virtual
       posting.  The balanced virtual postings in a transaction must add up to
       zero (separately from other postings).  Eg:

              1/1 buy food with cash, update budget envelope subaccounts, & something else
                assets:cash                    $-10 ; <- these balance
                expenses:food                    $7 ; <-
                expenses:food                    $3 ; <-
                [assets:checking:budget:food]  $-10    ; <- and these balance
                [assets:checking:available]     $10    ; <-
                (something:else)                 $5       ; <- not required to balance

       Ordinary  non-parenthesised,  non-bracketed  postings  are  called real
       postings.  You can exclude  virtual  postings  from  reports  with  the
       -R/--real flag or real:1 query.

ACCOUNT NAMES
       Account  names  typically have several parts separated by a full colon,
       from which hledger derives a hierarchical chart of accounts.  They  can
       be  anything you like, but in finance there are traditionally five top-
       level accounts: assets, liabilities, income, expenses, and equity.

       Account names may contain single spaces,  eg:  assets:accounts  receiv-
       able.   Because  of  this,  they must always be followed by two or more
       spaces (or newline).

       Account names can be aliased.

AMOUNTS
       After the account  name,  there  is  usually  an  amount.   (Important:
       between account name and amount, there must be two or more spaces.)

       hledger's  amount  format is flexible, supporting several international
       formats.  Here are some examples.  Amounts have a  number  (the  "quan-
       tity"):

              1

       ..and  usually a currency or commodity name (the "commodity").  This is
       a symbol, word, or phrase, to the left or right of the  quantity,  with
       or without a separating space:

              $1
              4000 AAPL

       If the commodity name contains spaces, numbers, or punctuation, it must
       be enclosed in double quotes:

              3 "no. 42 green apples"

       Amounts can be preceded by a minus sign (or a plus sign, though plus is
       the  default), The sign can be written before or after a left-side com-
       modity symbol:

              -$1
              $-1

       One or more spaces between the sign and the number are acceptable  when
       parsing (but they won't be displayed in output):

              + $1
              $-      1

       Scientific E notation is allowed:

              1E-6
              EUR 1E3

       A decimal mark can be written as a period or a comma:

              1.23
              1,23456780000009

   Digit group marks
       In  the integer part of the quantity (left of the decimal mark), groups
       of digits can optionally be separated by  a  "digit  group  mark"  -  a
       space, comma, or period (different from the decimal mark):

                   $1,000,000.00
                EUR 2.000.000,00
              INR 9,99,99,999.00
                    1 000 000.9455

       Note,  a  number  containing a single group mark and no decimal mark is
       ambiguous.  Are these group marks or decimal marks ?

              1,000
              1.000

       hledger will treat them both as decimal marks by default (cf #793).  If
       you use digit group marks, to prevent confusion and undetected typos we
       recommend you write commodity directives at the  top  of  the  file  to
       explicitly  declare  the  decimal  mark  (and  optionally a digit group
       mark).  Note, these formats ("amount styles") are specific to each com-
       modity, so if your data uses multiple formats, hledger can handle it:

              commodity $1,000.00
              commodity EUR 1.000,00
              commodity INR 9,99,99,999.00
              commodity       1 000 000.9455


   Commodity display style
       For each commodity, hledger chooses a consistent style to use when dis-
       playing amounts.  (Except price amounts, which are always displayed  as
       written).  The display style is chosen as follows:

       o If  there  is  a commodity directive (or default commodity directive)
         for the commodity, its style is used (see examples above).

       o Otherwise the style is inferred from the amounts  in  that  commodity
         seen in the journal.

       o Or  if  there  are no such amounts in the journal, a default style is
         used (like $1000.00).

       A style is inferred from the journal amounts in a commodity as follows:

       o Use  the  general style (decimal mark, symbol placement) of the first
         amount

       o Use the first-seen digit group style (digit group mark,  digit  group
         sizes), if any

       o Use the maximum number of decimal places of all.

       Transaction  price  amounts  don't  affect  the commodity display style
       directly, but occasionally they can do so indirectly (eg when  a  post-
       ing's  amount is inferred using a transaction price).  If you find this
       causing problems, use a commodity directive to fix the display style.

       In summary, each commodity's amounts will be normalised to

       o the style declared by a commodity directive

       o or, the style of the first posting amount in the  journal,  with  the
         first-seen  digit  group style and the maximum-seen number of decimal
         places.

       If reports are showing amounts in a way you don't like  (eg,  with  too
       many  decimal  places), use a commodity directive to set your preferred
       style.

   Rounding
       Amounts are stored internally as decimal numbers with up to 255 decimal
       places,  and  displayed  with the number of decimal places specified by
       the commodity display style.  Note, hledger uses banker's rounding:  it
       rounds  to  the nearest even number, eg 0.5 displayed with zero decimal
       places is "0").  (Guaranteed since hledger 1.17.1;  in  older  versions
       this could vary if hledger was built with Decimal < 0.5.1.)

TRANSACTION PRICES
       Within a transaction, you can note an amount's price in another commod-
       ity.  This can be used to document the cost (in a purchase) or  selling
       price  (in  a  sale).   For  example,  transaction prices are useful to
       record purchases of a foreign currency.  Note  transaction  prices  are
       fixed at the time of the transaction, and do not change over time.  See
       also market prices, which represent prevailing exchange rates on a cer-
       tain date.

       There are several ways to record a transaction price:

       1. Write the price per unit, as @ UNITPRICE after the amount:

                  2009/1/1
                    assets:euros     EUR100 @ $1.35  ; one hundred euros purchased at $1.35 each
                    assets:dollars                 ; balancing amount is -$135.00

       2. Write the total price, as @@ TOTALPRICE after the amount:

                  2009/1/1
                    assets:euros     EUR100 @@ $135  ; one hundred euros purchased at $135 for the lot
                    assets:dollars

       3. Specify amounts for all postings, using exactly two commodities, and
          let hledger infer the price that balances the transaction:

                  2009/1/1
                    assets:euros     EUR100          ; one hundred euros purchased
                    assets:dollars  $-135          ; for $135

       4. Like 1, but the @ is parenthesised, i.e.  (@); this is for  compati-
          bility  with Ledger journals (Virtual posting costs), and is equiva-
          lent to 1 in hledger.

       5. Like 2, but as in 4 the @@ is parenthesised, i.e.  (@@); in hledger,
          this is equivalent to 2.

       Use  the -B/--cost flag to convert amounts to their transaction price's
       commodity, if any.  (mnemonic: "B" is from "cost Basis", as in Ledger).
       Eg here is how -B affects the balance report for the example above:

              $ hledger bal -N --flat
                             $-135  assets:dollars
                              EUR100  assets:euros
              $ hledger bal -N --flat -B
                             $-135  assets:dollars
                              $135  assets:euros    # <- the euros' cost

       Note  -B is sensitive to the order of postings when a transaction price
       is inferred: the inferred price will be in the commodity  of  the  last
       amount.  So if example 3's postings are reversed, while the transaction
       is equivalent, -B shows something different:

              2009/1/1
                assets:dollars  $-135              ; 135 dollars sold
                assets:euros     EUR100              ; for 100 euros

              $ hledger bal -N --flat -B
                             EUR-100  assets:dollars  # <- the dollars' selling price
                              EUR100  assets:euros

LOT PRICES, LOT DATES
       Ledger allows another kind of price, lot price (four  variants:  {UNIT-
       PRICE},   {{TOTALPRICE}},   {=FIXEDUNITPRICE},   {{=FIXEDTOTALPRICE}}),
       and/or a lot date ([DATE]) to be specified.  These are normally used to
       select  a  lot when selling investments.  hledger will parse these, for
       compatibility with Ledger journals,  but  currently  ignores  them.   A
       transaction  price,  lot price and/or lot date may appear in any order,
       after the posting amount and before the balance assertion if any.

BALANCE ASSERTIONS
       hledger supports Ledger-style  balance  assertions  in  journal  files.
       These  look  like, for example, = EXPECTEDBALANCE following a posting's
       amount.  Eg here we assert the expected dollar balance  in  accounts  a
       and b after each posting:

              2013/1/1
                a   $1  =$1
                b       =$-1

              2013/1/2
                a   $1  =$2
                b  $-1  =$-2

       After reading a journal file, hledger will check all balance assertions
       and report an error if any of them fail.  Balance assertions  can  pro-
       tect  you  from, eg, inadvertently disrupting reconciled balances while
       cleaning up old entries.  You can disable  them  temporarily  with  the
       -I/--ignore-assertions flag, which can be useful for troubleshooting or
       for reading Ledger files.  (Note: this flag currently does not  disable
       balance assignments, below).

   Assertions and ordering
       hledger  sorts  an  account's postings and assertions first by date and
       then (for postings on the same day) by parse order.  Note this is  dif-
       ferent from Ledger, which sorts assertions only by parse order.  (Also,
       Ledger assertions do not see the accumulated effect of  repeated  post-
       ings to the same account within a transaction.)

       So, hledger balance assertions keep working if you reorder differently-
       dated transactions within the journal.  But if you  reorder  same-dated
       transactions  or postings, assertions might break and require updating.
       This order dependence does bring an advantage: precise control over the
       order of postings and assertions within a day, so you can assert intra-
       day balances.

   Assertions and included files
       With included files, things are a little more  complicated.   Including
       preserves  the ordering of postings and assertions.  If you have multi-
       ple postings to an account on the  same  day,  split  across  different
       files,  and  you  also want to assert the account's balance on the same
       day, you'll have to put the assertion in the right file.

   Assertions and multiple -f options
       Balance assertions don't work well across files specified with multiple
       -f options.  Use include or concatenate the files instead.

   Assertions and commodities
       The  asserted  balance must be a simple single-commodity amount, and in
       fact the assertion checks only  this  commodity's  balance  within  the
       (possibly  multi-commodity)  account  balance.   This is how assertions
       work in Ledger also.  We could call this a "partial" balance assertion.

       To assert the balance of more than one commodity in an account, you can
       write multiple postings, each asserting one commodity's balance.

       You can make a stronger "total" balance assertion by writing  a  double
       equals sign (== EXPECTEDBALANCE).  This asserts that there are no other
       unasserted commodities in the account (or, that their balance is 0).

              2013/1/1
                a   $1
                a    1EUR
                b  $-1
                c   -1EUR

              2013/1/2  ; These assertions succeed
                a    0  =  $1
                a    0  =   1EUR
                b    0 == $-1
                c    0 ==  -1EUR

              2013/1/3  ; This assertion fails as 'a' also contains 1EUR
                a    0 ==  $1

       It's not yet possible to make a complete assertion about a balance that
       has  multiple commodities.  One workaround is to isolate each commodity
       into its own subaccount:

              2013/1/1
                a:usd   $1
                a:euro   1EUR
                b

              2013/1/2
                a        0 ==  0
                a:usd    0 == $1
                a:euro   0 ==  1EUR

   Assertions and prices
       Balance assertions ignore transaction prices, and  should  normally  be
       written without one:

              2019/1/1
                (a)     $1 @ EUR1 = $1

       We  do allow prices to be written there, however, and print shows them,
       even though they don't affect whether the assertion  passes  or  fails.
       This  is  for  backward  compatibility (hledger's close command used to
       generate balance assertions with prices), and because  balance  assign-
       ments do use them (see below).

   Assertions and subaccounts
       The  balance  assertions above (= and ==) do not count the balance from
       subaccounts; they check the account's exclusive balance only.  You  can
       assert the balance including subaccounts by writing =* or ==*, eg:

              2019/1/1
                equity:opening balances
                checking:a       5
                checking:b       5
                checking         1  ==* 11

   Assertions and virtual postings
       Balance assertions are checked against all postings, both real and vir-
       tual.  They are not affected by the --real/-R flag or real: query.

   Assertions and precision
       Balance assertions compare the exactly calculated  amounts,  which  are
       not  always  what  is  shown  by reports.  Eg a commodity directive may
       limit the display precision, but this will not  affect  balance  asser-
       tions.  Balance assertion failure messages show exact amounts.

BALANCE ASSIGNMENTS
       Ledger-style  balance  assignments  are also supported.  These are like
       balance assertions, but with no posting amount on the left side of  the
       equals  sign;  instead  it is calculated automatically so as to satisfy
       the assertion.  This can be a convenience during data  entry,  eg  when
       setting opening balances:

              ; starting a new journal, set asset account balances
              2016/1/1 opening balances
                assets:checking            = $409.32
                assets:savings             = $735.24
                assets:cash                 = $42
                equity:opening balances

       or when adjusting a balance to reality:

              ; no cash left; update balance, record any untracked spending as a generic expense
              2016/1/15
                assets:cash    = $0
                expenses:misc

       The calculated amount depends on the account's balance in the commodity
       at that point (which depends on the previously-dated  postings  of  the
       commodity  to  that account since the last balance assertion or assign-
       ment).  Note that using balance assignments makes your journal a little
       less explicit; to know the exact amount posted, you have to run hledger
       or do the calculations yourself, instead of just reading it.

   Balance assignments and prices
       A transaction price in a balance assignment will cause  the  calculated
       amount to have that price attached:

              2019/1/1
                (a)             = $1 @ EUR2

              $ hledger print --explicit
              2019-01-01
                  (a)         $1 @ EUR2 = $1 @ EUR2

DIRECTIVES
       A  directive is a line in the journal beginning with a special keyword,
       that influences how the journal is processed.  hledger's directives are
       based on a subset of Ledger's, but there are many differences (and also
       some differences between hledger versions).

       Directives' behaviour and interactions can get a little bit complex, so
       here  is  a  table  summarising  the directives and their effects, with
       links to more detailed docs.  Note part of this table  is  hidden  when
       viewed in a web browser - scroll it sideways to see more.


       direc-     end         subdi-    purpose                        can affect  (as  of
       tive       directive   rec-                                     2018/06)
                              tives
       ------------------------------------------------------------------------------------
       account                any       document   account    names,   all entries in  all
                              text      declare account types & dis-   files,   before  or
                                        play order                     after
       alias      end                   rewrite account names          following   entries
                  aliases                                              until end  of  cur-
                                                                       rent  file  or  end
                                                                       directive
       apply      end apply             prepend a common  parent  to   following   entries
       account    account               account names                  until end  of  cur-
                                                                       rent  file  or  end
                                                                       directive
       comment    end  com-             ignore part of journal         following   entries
                  ment                                                 until end  of  cur-
                                                                       rent  file  or  end
                                                                       directive
       commod-                format    declare  a commodity and its   number    notation:
       ity                              number  notation  &  display   following   entries
                                        style                          in  that  commodity
                                                                       in all files ; dis-
                                                                       play style: amounts
                                                                       of  that  commodity
                                                                       in reports












       D                                declare  a  commodity  to be   default  commodity:
                                        used    for    commodityless   following   commod-
                                        amounts,   and   its  number   ityless     entries
                                        notation & display style       until  end  of cur-
                                                                       rent  file;  number
                                                                       notation: following
                                                                       entries   in   that
                                                                       commodity until end
                                                                       of  current   file;
                                                                       display      style:
                                                                       amounts   of   that
                                                                       commodity        in
                                                                       reports
       include                          include   entries/directives   what  the  included
                                        from another file              directives affect
       P                                declare a market price for a   amounts   of   that
                                        commodity                      commodity        in
                                                                       reports, when -V is
                                                                       used
       Y                                declare a year for  yearless   following   entries
                                        dates                          until end  of  cur-
                                                                       rent file
       =                                declare   an   auto  posting   all entries in par-
                                        rule,  adding  postings   to   ent/current/child
                                        other transactions             files (but not sib-
                                                                       ling   files,   see
                                                                       #1212)

       And some definitions:


       subdi-   optional  indented directive line immediately following a parent
       rec-     directive
       tive
       number   how to interpret numbers when parsing journal entries (the iden-
       nota-    tity  of the decimal separator character).  (Currently each com-
       tion     modity can have its own notation, even in the same file.)
       dis-     how to display amounts of a commodity in  reports  (symbol  side
       play     and spacing, digit groups, decimal separator, decimal places)
       style
       direc-   which  entries  and  (when there are multiple files) which files
       tive     are affected by a directive
       scope

       As you can see, directives vary in which journal entries and files they
       affect,  and  whether  they  are  focussed on input (parsing) or output
       (reports).  Some directives have multiple effects.

   Directives and multiple files
       If you use  multiple  -f/--file  options,  or  the  include  directive,
       hledger  will  process  multiple input files.  But note that directives
       which affect input (see above) typically last only until the end of the
       file in which they occur.

       This may seem inconvenient, but it's intentional; it makes reports sta-
       ble and deterministic, independent of the order  of  input.   Otherwise
       you  could see different numbers if you happened to write -f options in
       a different order, or if you moved includes around  while  cleaning  up
       your files.

       It  can  be  surprising though; for example, it means that alias direc-
       tives do not affect parent or sibling files (see below).

   Comment blocks
       A line containing just comment starts a commented region of  the  file,
       and a line containing just end comment (or the end of the current file)
       ends it.  See also comments.

   Including other files
       You can pull in the content of additional files by writing  an  include
       directive, like this:

              include FILEPATH

       Only  journal files can include, and only journal, timeclock or timedot
       files can be included (not CSV files, currently).

       If the file path does not begin with a slash, it  is  relative  to  the
       current file's folder.

       A tilde means home directory, eg: include ~/main.journal.

       The path may contain glob patterns to match multiple files, eg: include
       *.journal.

       There is limited support for recursive wildcards:  **/  (the  slash  is
       required)  matches 0 or more subdirectories.  It's not super convenient
       since you have to avoid include cycles and including  directories,  but
       this can be done, eg: include */**/*.journal.

       The path may also be prefixed to force a specific file format, overrid-
       ing the file extension (as described  in  hledger.1  ->  Input  files):
       include timedot:~/notes/2020*.md.

   Default year
       You  can set a default year to be used for subsequent dates which don't
       specify a year.  This is a line beginning with Y followed by the  year.
       Eg:

              Y2009  ; set default year to 2009

              12/15  ; equivalent to 2009/12/15
                expenses  1
                assets

              Y2010  ; change default year to 2010

              2009/1/30  ; specifies the year, not affected
                expenses  1
                assets

              1/31   ; equivalent to 2010/1/31
                expenses  1
                assets

   Declaring commodities
       The commodity directive has several functions:

       1. It  declares  commodities which may be used in the journal.  This is
          currently not enforced, but can serve as documentation.

       2. It declares what decimal mark character (period or comma) to  expect
          when  parsing  input  -  useful to disambiguate international number
          formats in your data.  (Without this, hledger will parse both  1,000
          and 1.000 as 1).

       3. It  declares  a  commodity's  display  style in output - decimal and
          digit group marks, number of decimal places, symbol placement etc.

       You are likely to run into one of  the  problems  solved  by  commodity
       directives,  sooner  or  later,  so it's a good idea to just always use
       them to declare your commodities.

       A commodity directive is just the word commodity followed by an amount.
       It may be written on a single line, like this:

              ; commodity EXAMPLEAMOUNT

              ; display AAAA amounts with the symbol on the right, space-separated,
              ; using period as decimal point, with four decimal places, and
              ; separating thousands with comma.
              commodity 1,000.0000 AAAA

       or  on  multiple lines, using the "format" subdirective.  (In this case
       the commodity symbol appears twice and  should  be  the  same  in  both
       places.):

              ; commodity SYMBOL
              ;   format EXAMPLEAMOUNT

              ; display indian rupees with currency name on the left,
              ; thousands, lakhs and crores comma-separated,
              ; period as decimal point, and two decimal places.
              commodity INR
                format INR 1,00,00,000.00

       The quantity of the amount does not matter; only the format is signifi-
       cant.  The number must include a decimal mark: either  a  period  or  a
       comma, followed by 0 or more decimal digits.

       Note  hledger  normally  uses  banker's rounding, so 0.5 displayed with
       zero decimal digits is "0".  (More at Commodity display style.)

   Commodity error checking
       In strict mode, enabled with the -s/--strict flag, hledger will  report
       an  error if a commodity symbol is used that has not been declared by a
       commodity directive.  This works similarly to account  error  checking,
       see the notes there for more details.

   Default commodity
       The  D directive sets a default commodity, to be used for amounts with-
       out a commodity symbol (ie, plain numbers).   This  commodity  will  be
       applied  to  all subsequent commodity-less amounts, or until the next D
       directive.  (Note, this is different from Ledger's D.)

       For compatibility/historical reasons, D  also  acts  like  a  commodity
       directive, setting the commodity's display style (for output) and deci-
       mal mark (for parsing input).   As  with  commodity,  the  amount  must
       always  be  written  with  a  decimal  mark (period or comma).  If both
       directives are used, commodity's style takes precedence.

       The syntax is D AMOUNT.  Eg:

              ; commodity-less amounts should be treated as dollars
              ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
              D $1,000.00

              1/1
                a     5  ; <- commodity-less amount, parsed as $5 and displayed as $5.00
                b

   Declaring market prices
       The P directive declares a market price,  which  is  an  exchange  rate
       between two commodities on a certain date.  (In Ledger, they are called
       "historical prices".) These are often obtained from a  stock  exchange,
       cryptocurrency exchange, or the foreign exchange market.

       Here is the format:

              P DATE COMMODITYA COMMODITYBAMOUNT

       o DATE is a simple date

       o COMMODITYA is the symbol of the commodity being priced

       o COMMODITYBAMOUNT  is an amount (symbol and quantity) in a second com-
         modity, giving the price in commodity B of one unit of commodity A.

       These two market price directives say that one euro was worth  1.35  US
       dollars during 2009, and $1.40 from 2010 onward:

              P 2009/1/1 EUR $1.35
              P 2010/1/1 EUR $1.40

       The  -V,  -X  and  --value flags use these market prices to show amount
       values in another commodity.  See Valuation.

   Declaring accounts
       account directives can be used to declare accounts (ie, the places that
       amounts  are transferred from and to).  Though not required, these dec-
       larations can provide several benefits:

       o They can document your intended chart of accounts, providing a refer-
         ence.

       o They  can  help  hledger know your accounts' types (asset, liability,
         equity, revenue, expense), useful for reports like  balancesheet  and
         incomestatement.

       o They  control  account  display order in reports, allowing non-alpha-
         betic sorting (eg Revenues to appear above Expenses).

       o They can store extra information  about  accounts  (account  numbers,
         notes, etc.)

       o They  help  with account name completion in the add command, hledger-
         iadd, hledger-web, ledger-mode etc.

       o In strict mode, they restrict which accounts  may  be  posted  to  by
         transactions, which helps detect typos.

       The  simplest form is just the word account followed by a hledger-style
       account name, eg this account directive declares the assets:bank:check-
       ing account:

              account assets:bank:checking

   Account error checking
       By  default, accounts come into existence when a transaction references
       them by name.  This is convenient, but it means hledger can't warn  you
       when you mis-spell an account name in the journal.  Usually you'll find
       the error later, as an extra account in balance reports, or  an  incor-
       rect balance when reconciling.

       In  strict mode, enabled with the -s/--strict flag, hledger will report
       an error if any transaction uses an account  name  that  has  not  been
       declared by an account directive.  Some notes:

       o The  declaration is case-sensitive; transactions must use the correct
         account name capitalisation.

       o The account directive's scope is "whole file and below"  (see  direc-
         tives).  This means it affects all of the current file, and any files
         it includes, but not  parent  or  sibling  files.   The  position  of
         account directives within the file does not matter, though it's usual
         to put them at the top.

       o Accounts can only be declared  in  journal  files  (but  will  affect
         included files in other formats).

       o It's  currently  not  possible  to declare "all possible subaccounts"
         with a wildcard; every account posted to must be declared.

   Account comments
       Comments, beginning with a semicolon, can be added:

       o on the same line, after two or more spaces (because ; is  allowed  in
         account names)

       o on the next lines, indented

       An example of both:

              account assets:bank:checking  ; same-line comment, note 2+ spaces before ;
                ; next-line comment
                ; another with tag, acctno:12345 (not used yet)

       Same-line comments are not supported by Ledger, or hledger <1.13.

   Account subdirectives
       We  also  allow  (and ignore) Ledger-style indented subdirectives, just
       for compatibility.:

              account assets:bank:checking
                format blah blah  ; <- subdirective, ignored

       Here is the full syntax of account directives:

              account ACCTNAME  [ACCTTYPE] [;COMMENT]
                [;COMMENTS]
                [LEDGER-STYLE SUBDIRECTIVES, IGNORED]

   Account types
       hledger recognises five main types of  account,  corresponding  to  the
       account classes in the accounting equation:

       Asset, Liability, Equity, Revenue, Expense.

       These account types are important for controlling which accounts appear
       in the balancesheet, balancesheetequity, incomestatement  reports  (and
       probably for other things in future).

       Additionally,  we  recognise the Cash type, which is also an Asset, and
       which causes accounts to appear in the cashflow report.   ("Cash"  here
       means  liquid assets, eg bank balances but typically not investments or
       receivables.)

   Declaring account types
       Generally, to make these reports work you should declare your top-level
       accounts and their types, using account directives with type: tags.

       The  tag's  value  should be one of: Asset, Liability, Equity, Revenue,
       Expense, Cash, A, L, E, R, X, C (all case insensitive).   The  type  is
       inherited  by  all subaccounts except where they override it.  Here's a
       complete example:

              account assets       ; type: Asset
              account assets:bank  ; type: Cash
              account assets:cash  ; type: Cash
              account liabilities  ; type: Liability
              account equity       ; type: Equity
              account revenues     ; type: Revenue
              account expenses     ; type: Expense

   Auto-detected account types
       If you happen to use common english top-level account  names,  you  may
       not  need  to declare account types, as they will be detected automati-
       cally using the following rules:


       If  name  matches  regular   account type is:
       expression:
       ----------------------------------------------
       ^assets?(:|$)                Asset
       ^(debts?|lia-                Liability
       bilit(y|ies))(:|$)
       ^equity(:|$)                 Equity
       ^(income|revenue)s?(:|$)     Revenue
       ^expenses?(:|$)              Expense


       If account type is Asset and name does not contain  regu-   account  type
       lar expression:                                             is:
       --------------------------------------------------------------------------
       (investment|receivable|:A/R|:fixed)                         Cash

       Even so, explicit declarations may be a good idea, for clarity and pre-
       dictability.

   Interference from auto-detected account types
       If you assign any account type, it's a good idea to assign all of them,
       to prevent any confusion from mixing declared and auto-detected  types.
       Although  it's unlikely to happen in real life, here's an example: with
       the following journal, balancesheetequity shows "liabilities"  in  both
       Liabilities   and   Equity  sections.   Declaring  another  account  as
       type:Liability would fix it:

              account liabilities  ; type:Equity

              2020-01-01
                assets        1
                liabilities   1
                equity       -2

   Old account type syntax
       In some hledger journals you might instead see  this  old  syntax  (the
       letters  ALERX, separated from the account name by two or more spaces);
       this is deprecated and may be removed soon:

              account assets       A
              account liabilities  L
              account equity       E
              account revenues     R
              account expenses     X

   Account display order
       Account directives also set the order in which accounts are  displayed,
       eg  in  reports,  the  hledger-ui  accounts screen, and the hledger-web
       sidebar.  By default accounts are listed in alphabetical order.  But if
       you have these account directives in the journal:

              account assets
              account liabilities
              account equity
              account revenues
              account expenses

       you'll see those accounts displayed in declaration order, not alphabet-
       ically:

              $ hledger accounts -1
              assets
              liabilities
              equity
              revenues
              expenses

       Undeclared accounts, if any, are displayed last, in alphabetical order.

       Note  that  sorting  is  done at each level of the account tree (within
       each group of sibling accounts under the same parent).  And  currently,
       this directive:

              account other:zoo

       would  influence the position of zoo among other's subaccounts, but not
       the position of other among the top-level accounts.  This means:

       o you will sometimes declare parent accounts (eg account  other  above)
         that  you  don't  intend  to post to, just to customize their display
         order

       o sibling accounts stay together (you couldn't display x:y  in  between
         a:b and a:c).

   Rewriting accounts
       You can define account alias rules which rewrite your account names, or
       parts of them, before generating reports.  This can be useful for:

       o expanding shorthand account names to their full form, allowing easier
         data entry and a less verbose journal

       o adapting old journals to your current chart of accounts

       o experimenting with new account organisations, like a new hierarchy or
         combining two accounts into one

       o customising reports

       Account aliases also rewrite account names in account directives.  They
       do  not  affect account names being entered via hledger add or hledger-
       web.

       See also Rewrite account names.

   Basic aliases
       To set an account alias, use the alias directive in your journal  file.
       This  affects all subsequent journal entries in the current file or its
       included files.  The spaces around the = are optional:

              alias OLD = NEW

       Or, you can use the --alias 'OLD=NEW' option on the command line.  This
       affects all entries.  It's useful for trying out aliases interactively.

       OLD and NEW are  case  sensitive  full  account  names.   hledger  will
       replace  any occurrence of the old account name with the new one.  Sub-
       accounts are also affected.  Eg:

              alias checking = assets:bank:wells fargo:checking
              ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"

   Regex aliases
       There is also a more powerful variant that uses a  regular  expression,
       indicated by the forward slashes:

              alias /REGEX/ = REPLACEMENT

       or --alias '/REGEX/=REPLACEMENT'.

       REGEX  is  a  case-insensitive regular expression.  Anywhere it matches
       inside an account name, the matched part will be replaced  by  REPLACE-
       MENT.   If REGEX contains parenthesised match groups, these can be ref-
       erenced by the usual numeric backreferences in REPLACEMENT.  Eg:

              alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
              ; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"

       Also note that REPLACEMENT continues to the end of line (or on  command
       line,  to  end  of  option argument), so it can contain trailing white-
       space.

   Combining aliases
       You can define as many aliases as you like,  using  journal  directives
       and/or command line options.

       Recursive  aliases  -  where an account name is rewritten by one alias,
       then by another alias, and so on - are allowed.  Each  alias  sees  the
       effect of previously applied aliases.

       In  such  cases it can be important to understand which aliases will be
       applied and in which order.  For (each account name  in)  each  journal
       entry, we apply:

       1. alias  directives  preceding the journal entry, most recently parsed
          first (ie, reading upward from the journal entry, bottom to top)

       2. --alias options, in the order they  appeared  on  the  command  line
          (left to right).

       In other words, for (an account name in) a given journal entry:

       o the nearest alias declaration before/above the entry is applied first

       o the next alias before/above that will be be applied next, and so on

       o aliases defined after/below the entry do not affect it.

       This gives nearby aliases precedence over distant ones, and helps  pro-
       vide  semantic stability - aliases will keep working the same way inde-
       pendent of which files are being read and in which order.

       In case of trouble, adding --debug=6 to  the  command  line  will  show
       which aliases are being applied when.

   Aliases and multiple files
       As  explained at Directives and multiple files, alias directives do not
       affect parent or sibling files.  Eg in this command,

              hledger -f a.aliases -f b.journal

       account  aliases  defined  in  a.aliases  will  not  affect  b.journal.
       Including the aliases doesn't work either:

              include a.aliases

              2020-01-01  ; not affected by a.aliases
                foo  1
                bar

       This means that account aliases should usually be declared at the start
       of your top-most file, like this:

              alias foo=Foo
              alias bar=Bar

              2020-01-01  ; affected by aliases above
                foo  1
                bar

              include c.journal  ; also affected

   end aliases
       You can clear (forget) all  currently  defined  aliases  with  the  end
       aliases directive:

              end aliases

   Default parent account
       You  can  specify  a  parent  account  which  will  be prepended to all
       accounts within a section of the journal.  Use the  apply  account  and
       end apply account directives like so:

              apply account home

              2010/1/1
                  food    $10
                  cash

              end apply account

       which is equivalent to:

              2010/01/01
                  home:food           $10
                  home:cash          $-10

       If  end  apply  account  is omitted, the effect lasts to the end of the
       file.  Included files are also affected, eg:

              apply account business
              include biz.journal
              end apply account
              apply account personal
              include personal.journal

       Prior to hledger 1.0, legacy account and end spellings were  also  sup-
       ported.

       A  default parent account also affects account directives.  It does not
       affect account names being entered via hledger add or hledger-web.   If
       account  aliases are present, they are applied after the default parent
       account.

PERIODIC TRANSACTIONS
       Periodic transaction rules  describe  transactions  that  recur.   They
       allow  hledger  to  generate temporary future transactions to help with
       forecasting, so you don't have to write out each one  in  the  journal,
       and it's easy to try out different forecasts.

       Periodic  transactions  can be a little tricky, so before you use them,
       read this whole section - or at least these tips:

       1. Two spaces accidentally added or omitted will cause  you  trouble  -
          read about this below.

       2. For  troubleshooting,  show  the generated transactions with hledger
          print  --forecast  tag:generated  or  hledger  register   --forecast
          tag:generated.

       3. Forecasted  transactions  will  begin  only after the last non-fore-
          casted transaction's date.

       4. Forecasted transactions will end 6 months from  today,  by  default.
          See below for the exact start/end rules.

       5. period   expressions  can  be  tricky.   Their  documentation  needs
          improvement, but is worth studying.

       6. Some period expressions with a repeating interval must  begin  on  a
          natural  boundary  of  that  interval.  Eg in weekly from DATE, DATE
          must be a monday.  ~ weekly from 2019/10/1 (a tuesday) will give  an
          error.

       7. Other period expressions with an interval are automatically expanded
          to cover a whole number of that interval.  (This is done to  improve
          reports, but it also affects periodic transactions.  Yes, it's a bit
          inconsistent with the above.) Eg: ~ every 10th  day  of  month  from
          2020/01,  which  is  equivalent  to  ~  every 10th day of month from
          2020/01/01, will be adjusted to start on 2019/12/10.

       Periodic transaction rules also have a second meaning: they are used to
       define budget goals, shown in budget reports.

   Periodic rule syntax
       A periodic transaction rule looks like a normal journal entry, with the
       date replaced by a tilde (~) followed by a period expression (mnemonic:
       ~ looks like a recurring sine wave.):

              ~ monthly
                  expenses:rent          $2000
                  assets:bank:checking

       There  is  an additional constraint on the period expression: the start
       date must fall on a natural boundary of the interval.  Eg monthly  from
       2018/1/1 is valid, but monthly from 2018/1/15 is not.

       Partial  or  relative dates (M/D, D, tomorrow, last week) in the period
       expression can work (useful or not).  They will be relative to  today's
       date,  unless  a  Y  default year directive is in effect, in which case
       they will be relative to Y/1/1.

   Two spaces between period expression and description!
       If the period expression is  followed  by  a  transaction  description,
       these must be separated by two or more spaces.  This helps hledger know
       where the period expression ends, so that descriptions can not acciden-
       tally alter their meaning, as in this example:

              ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"
              ;               ||
              ;               vv
              ~ every 2 months  in 2020, we will review
                  assets:bank:checking   $1500
                  income:acme inc

       So,

       o Do  write two spaces between your period expression and your transac-
         tion description, if any.

       o Don't accidentally write two spaces in  the  middle  of  your  period
         expression.

   Forecasting with periodic transactions
       The  --forecast  flag  activates  any periodic transaction rules in the
       journal.  They will generate temporary  recurring  transactions,  which
       are  not  saved  in  the  journal,  but  will appear in all reports (eg
       print).  This can be useful for estimating balances into the future, or
       experimenting  with  different scenarios.  Or, it can be used as a data
       entry aid: describe recurring transactions, and every so often copy the
       output of print --forecast into the journal.

       These  transactions  will  have  an extra tag indicating which periodic
       rule generated them: generated-transaction:~ PERIODICEXPR.  And a simi-
       lar,  hidden  tag  (beginning  with  an underscore) which, because it's
       never displayed by print, can be used to match  transactions  generated
       "just now": _generated-transaction:~ PERIODICEXPR.

       Periodic  transactions  are  generated within some forecast period.  By
       default, this

       o begins on the later of

         o the report start date if specified with -b/-p/date:

         o the day after the latest normal (non-periodic) transaction  in  the
           journal, or today if there are no normal transactions.

       o ends  on  the  report  end  date  if specified with -e/-p/date:, or 6
         months (180 days) from today.

       This means that periodic transactions will begin only after the  latest
       recorded  transaction.   And a recorded transaction dated in the future
       can prevent generation of periodic transactions.  (You can  avoid  that
       by writing the future transaction as a one-time periodic rule instead -
       put tilde before the date, eg ~ YYYY-MM-DD ...).

       Or, you can set your own arbitrary "forecast period", which can overlap
       recorded  transactions,  and need not be in the future, by providing an
       option argument, like --forecast=PERIODEXPR.  Note the equals  sign  is
       required, a space won't work.  PERIODEXPR is a period expression, which
       can specify the start date, end date, or both, like in a  date:  query.
       (See  also  hledger.1  ->  Report  start  &  end date).  Some examples:
       --forecast=202001-202004, --forecast=jan-, --forecast=2020.

   Budgeting with periodic transactions
       With the --budget flag, currently supported  by  the  balance  command,
       each  periodic transaction rule declares recurring budget goals for the
       specified accounts.  Eg the first example  above  declares  a  goal  of
       spending  $2000  on  rent  (and  also,  a goal of depositing $2000 into
       checking) every month.  Goals and actual performance can then  be  com-
       pared in budget reports.

       See also: Budgeting and Forecasting.


AUTO POSTINGS
       "Automated  postings"  or  "auto postings" are extra postings which get
       added  automatically  to  transactions  which  match  certain  queries,
       defined by "auto posting rules", when you use the --auto flag.

       An auto posting rule looks a bit like a transaction:

              = QUERY
                  ACCOUNT  AMOUNT
                  ...
                  ACCOUNT  [AMOUNT]

       except  the  first  line is an equals sign (mnemonic: = suggests match-
       ing), followed by a query (which matches existing postings),  and  each
       "posting"  line  describes  a  posting to be generated, and the posting
       amounts can be:

       o a normal amount with a commodity symbol, eg $2.  This  will  be  used
         as-is.

       o a number, eg 2.  The commodity symbol (if any) from the matched post-
         ing will be added to this.

       o a numeric multiplier, eg *2 (a star followed by  a  number  N).   The
         matched posting's amount (and total price, if any) will be multiplied
         by N.

       o a multiplier with a commodity symbol, eg *$2 (a star, number  N,  and
         symbol S).  The matched posting's amount will be multiplied by N, and
         its commodity symbol will be replaced with S.

       Any query term containing spaces must be enclosed in single  or  double
       quotes,  as on the command line.  Eg, note the quotes around the second
       query term below:

              = expenses:groceries 'expenses:dining out'
                  (budget:funds:dining out)                 *-1

       Some examples:

              ; every time I buy food, schedule a dollar donation
              = expenses:food
                  (liabilities:charity)   $-1

              ; when I buy a gift, also deduct that amount from a budget envelope subaccount
              = expenses:gifts
                  assets:checking:gifts  *-1
                  assets:checking         *1

              2017/12/1
                expenses:food    $10
                assets:checking

              2017/12/14
                expenses:gifts   $20
                assets:checking

              $ hledger print --auto
              2017-12-01
                  expenses:food              $10
                  assets:checking
                  (liabilities:charity)      $-1

              2017-12-14
                  expenses:gifts             $20
                  assets:checking
                  assets:checking:gifts     -$20
                  assets:checking            $20

   Auto postings and multiple files
       An auto posting rule can affect any transaction in the current file, or
       in  any  parent file or child file.  Note, currently it will not affect
       sibling files (when multiple -f/--file are used - see #1212).

   Auto postings and dates
       A posting date (or secondary date) in the matched posting,  or  (taking
       precedence)  a  posting date in the auto posting rule itself, will also
       be used in the generated posting.

   Auto postings and transaction balancing / inferred amounts / balance asser-
       tions
       Currently, auto postings are added:

       o after  missing amounts are inferred, and transactions are checked for
         balancedness,

       o but before balance assertions are checked.

       Note this means that journal entries must be balanced both  before  and
       after auto postings are added.  This changed in hledger 1.12+; see #893
       for background.

   Auto posting tags
       Automated postings will have some extra tags:

       o generated-posting:= QUERY - shows this was generated by an auto post-
         ing rule, and the query

       o _generated-posting:=  QUERY  - a hidden tag, which does not appear in
         hledger's output.  This can be used to match postings generated "just
         now", rather than generated in the past and saved to the journal.

       Also,  any transaction that has been changed by auto posting rules will
       have these tags added:

       o modified: - this transaction was modified

       o _modified: - a hidden tag not appearing in the comment; this transac-
         tion was modified "just now".



REPORTING BUGS
       Report  bugs at http://bugs.hledger.org (or on the #hledger IRC channel
       or hledger mail list)


AUTHORS
       Simon Michael <simon@joyful.com> and contributors


COPYRIGHT
       Copyright (C) 2007-2020 Simon Michael.
       Released under GNU GPL v3 or later.


SEE ALSO
       hledger(1), hledger-ui(1), hledger-web(1), ledger(1)

       hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_time-
       dot(5)



hledger-lib-1.20.4               December 2020              HLEDGER_JOURNAL(5)