diff --git a/hledger-lib/.date.m4 b/hledger-lib/.date.m4 index fbc3c51ab..89541032f 100644 --- a/hledger-lib/.date.m4 +++ b/hledger-lib/.date.m4 @@ -1,2 +1,2 @@ m4_dnl Date to show in man pages. Updated by "Shake manuals" -m4_define({{_monthyear_}}, {{January 2024}})m4_dnl +m4_define({{_monthyear_}}, {{February 2024}})m4_dnl diff --git a/hledger-ui/.date.m4 b/hledger-ui/.date.m4 index fbc3c51ab..89541032f 100644 --- a/hledger-ui/.date.m4 +++ b/hledger-ui/.date.m4 @@ -1,2 +1,2 @@ m4_dnl Date to show in man pages. Updated by "Shake manuals" -m4_define({{_monthyear_}}, {{January 2024}})m4_dnl +m4_define({{_monthyear_}}, {{February 2024}})m4_dnl diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 4c10310d9..378bc5c3f 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER\-UI" "1" "January 2024" "hledger-ui-1.32.99 " "hledger User Manuals" +.TH "HLEDGER\-UI" "1" "February 2024" "hledger-ui-1.32.99 " "hledger User Manuals" diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index 69618b1cc..82aa78f85 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -673,44 +673,44 @@ Tag Table: Node: Top221 Node: OPTIONS1830 Ref: #options1928 -Node: General help options2951 -Ref: #general-help-options3100 -Node: General input options3382 -Ref: #general-input-options3567 -Node: General reporting options4224 -Ref: #general-reporting-options4388 -Node: MOUSE7778 -Ref: #mouse7873 -Node: KEYS8110 -Ref: #keys8203 -Node: SCREENS12858 -Ref: #screens12956 -Node: Menu13536 -Ref: #menu13629 -Node: Cash accounts13824 -Ref: #cash-accounts13966 -Node: Balance sheet accounts14150 -Ref: #balance-sheet-accounts14331 -Node: Income statement accounts14451 -Ref: #income-statement-accounts14637 -Node: All accounts14801 -Ref: #all-accounts14947 -Node: Register15129 -Ref: #register15253 -Node: Transaction17537 -Ref: #transaction17660 -Node: Error19077 -Ref: #error19171 -Node: TIPS19415 -Ref: #tips19514 -Node: Watch mode19556 -Ref: #watch-mode19663 -Node: Debug output21122 -Ref: #debug-output21233 -Node: ENVIRONMENT21445 -Ref: #environment21555 -Node: BUGS21746 -Ref: #bugs21829 +Node: General help options2956 +Ref: #general-help-options3105 +Node: General input options3387 +Ref: #general-input-options3572 +Node: General reporting options4229 +Ref: #general-reporting-options4393 +Node: MOUSE7783 +Ref: #mouse7878 +Node: KEYS8115 +Ref: #keys8208 +Node: SCREENS12863 +Ref: #screens12961 +Node: Menu13541 +Ref: #menu13634 +Node: Cash accounts13829 +Ref: #cash-accounts13971 +Node: Balance sheet accounts14155 +Ref: #balance-sheet-accounts14336 +Node: Income statement accounts14456 +Ref: #income-statement-accounts14642 +Node: All accounts14806 +Ref: #all-accounts14952 +Node: Register15134 +Ref: #register15258 +Node: Transaction17542 +Ref: #transaction17665 +Node: Error19082 +Ref: #error19176 +Node: TIPS19420 +Ref: #tips19519 +Node: Watch mode19561 +Ref: #watch-mode19668 +Node: Debug output21127 +Ref: #debug-output21238 +Node: ENVIRONMENT21450 +Ref: #environment21560 +Node: BUGS21751 +Ref: #bugs21834  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 906545538..b0b25f907 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -535,4 +535,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-ui-1.32.99 January 2024 HLEDGER-UI(1) +hledger-ui-1.32.99 February 2024 HLEDGER-UI(1) diff --git a/hledger-web/.date.m4 b/hledger-web/.date.m4 index fbc3c51ab..89541032f 100644 --- a/hledger-web/.date.m4 +++ b/hledger-web/.date.m4 @@ -1,2 +1,2 @@ m4_dnl Date to show in man pages. Updated by "Shake manuals" -m4_define({{_monthyear_}}, {{January 2024}})m4_dnl +m4_define({{_monthyear_}}, {{February 2024}})m4_dnl diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 3c76d9ebd..c6369a6fb 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -1,5 +1,5 @@ -.TH "HLEDGER\-WEB" "1" "January 2024" "hledger-web-1.32.99 " "hledger User Manuals" +.TH "HLEDGER\-WEB" "1" "February 2024" "hledger-web-1.32.99 " "hledger User Manuals" diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 13607090a..7001d2f2b 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -549,4 +549,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-web-1.32.99 January 2024 HLEDGER-WEB(1) +hledger-web-1.32.99 February 2024 HLEDGER-WEB(1) diff --git a/hledger/.date.m4 b/hledger/.date.m4 index fbc3c51ab..89541032f 100644 --- a/hledger/.date.m4 +++ b/hledger/.date.m4 @@ -1,2 +1,2 @@ m4_dnl Date to show in man pages. Updated by "Shake manuals" -m4_define({{_monthyear_}}, {{January 2024}})m4_dnl +m4_define({{_monthyear_}}, {{February 2024}})m4_dnl diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 315d43a9c..8e2f803b7 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "January 2024" "hledger-1.32.99 " "hledger User Manuals" +.TH "HLEDGER" "1" "February 2024" "hledger-1.32.99 " "hledger User Manuals" @@ -141,13 +141,13 @@ in any of the supported file formats, which currently are: .PP .TS tab(@); -lw(12.3n) lw(30.0n) lw(27.7n). +lw(13.5n) lw(33.0n) lw(23.5n). T{ Reader: T}@T{ Reads: T}@T{ -Used for file extensions: +Automatically used for files with extensions: T} _ T{ @@ -174,10 +174,30 @@ T} T{ \f[CR]csv\f[R] T}@T{ -CSV/SSV/TSV/character\-separated values, for data import +Comma or other character separated values, for data import T}@T{ -\f[CR].csv\f[R] \f[CR].ssv\f[R] \f[CR].tsv\f[R] \f[CR].csv.rules\f[R] -\f[CR].ssv.rules\f[R] \f[CR].tsv.rules\f[R] +\f[CR].csv\f[R] +T} +T{ +\f[CR]ssv\f[R] +T}@T{ +Semicolon separated values +T}@T{ +\f[CR].ssv\f[R] +T} +T{ +\f[CR]tsv\f[R] +T}@T{ +Tab separated values +T}@T{ +\f[CR].tsv\f[R] +T} +T{ +\f[CR]rules\f[R] +T}@T{ +CSV/SSV/TSV/other separated values, alternate way +T}@T{ +\f[CR].rules\f[R] T} .TE .PP @@ -193,10 +213,10 @@ messages. .PP You can also force a specific reader/format by prefixing the file path with the format and a colon. -Eg, to read a .dat file as csv format: +Eg, to read a .dat file containing tab separated values: .IP .EX -$ hledger \-f csv:/some/csv\-file.dat stats +$ hledger \-f tsv:/some/file.dat stats .EE .SS Standard input The file name \f[CR]\-\f[R] means standard input: @@ -1403,18 +1423,43 @@ write a transaction \[dq]code\[dq], enclosed in parentheses. This is a good place to record a check number, or some other important transaction id or reference number. .SS Description -A transaction\[aq]s description is the rest of the line following the -date and status mark (or until a comment begins). -Sometimes called the \[dq]narration\[dq] in traditional bookkeeping, it -can be used for whatever you wish, or left blank. -Transaction descriptions can be queried, unlike comments. +After the date, status mark and/or code fields, the rest of the line (or +until a comment is begun with \f[CR];\f[R]) is the transaction\[aq]s +description. +Here you can describe the transaction (called the \[dq]narration\[dq] in +traditional bookkeeping), or you can record a payee/payer name, or you +can leave it empty. +.PP +Transaction descriptions show up in print output and in register +reports, and can be listed with the descriptions command. +.PP +You can query by description with \f[CR]desc:DESCREGEX\f[R], or pivot on +description with \f[CR]\-\-pivot desc\f[R]. .SS Payee and note -You can optionally include a \f[CR]|\f[R] (pipe) character in -descriptions to subdivide the description into separate fields for -payee/payer name on the left (up to the first \f[CR]|\f[R]) and an -additional note field on the right (after the first \f[CR]|\f[R]). -This may be worthwhile if you need to do more precise querying and -pivoting by payee or by note. +Sometimes people want a dedicated payee/payer field that can be queried +and checked more strictly. +If you want that, you can write a \f[CR]|\f[R] (pipe) character in the +description. +This divides it into a \[dq]payee\[dq] field on the left, and a +\[dq]note\[dq] field on the right. +(Either can be empty.) +.PP +You can query these with \f[CR]payee:PAYEEREGEX\f[R] and +\f[CR]note:NOTEREGEX\f[R], list their values with the payees and notes +commands, or pivot on \f[CR]payee\f[R] or \f[CR]note\f[R]. +.PP +Note: in transactions with no \f[CR]|\f[R] character, description, +payee, and note all have the same value. +Once a \f[CR]|\f[R] is added, they become distinct. +(If you\[aq]d like to change this behaviour, please propose it on the +mail list.) +.PP +If you want more strict error checking, you can declare the valid payee +names with \f[CR]payee\f[R] directives, and then enforce these with +\f[CR]hledger check payees\f[R]. +Note: because of the above, for this you\[aq]ll need to ensure every +transaction description contains a \f[CR]|\f[R] and therefore a +checkable payee name (even if it\[aq]s empty). .SS Transaction comments Text following \f[CR];\f[R], after a transaction description, and/or on indented lines immediately below it, form comments for that transaction. @@ -2017,19 +2062,22 @@ they may contain tags, which are not ignored. ; a second comment line for posting 2 .EE .SS Tags -Tags are a way to add extra labels or labelled data to transactions, +Tags are a way to add extra labels or data fields to transactions, postings, or accounts, which you can then search or pivot on. .PP -They are written as a word (optionally hyphenated) immediately followed -by a full colon, in a transaction or posting or account directive\[aq]s -comment. -(This is an exception to the usual rule that things in comments are -ignored.) -You can write multiple tags separated by comma, and/or you can add more -comment lines and write more tags there. +A tag is a word, optionally hyphenated, immediately followed by a full +colon, in the comment of a transaction, a posting, or an account +directive. +Eg: \f[CR]2024\-01\-01 a transaction ; foo:\f[R] Note this is an +exception to the usual rule that things in comments are ignored. .PP -Here five different tags are recorded: one on the checking account, two -on the transaction, and two on the expenses posting: +You can write multiple tags on one line, separated by comma. +Or you can write each tag on its own comment line (no comma needed in +this case). +.PP +For example, here are five different tags: one on the +\f[CR]assets:checking\f[R] account, two on the transaction, and two on +the \f[CR]expenses:food\f[R] posting: .IP .EX account assets:checking ; accounttag: @@ -2040,9 +2088,6 @@ account assets:checking ; accounttag: expenses:food $1 ; postingtag:, another\-posting\-tag: .EE .PP -You can list tag names with \f[CR]hledger tags [NAMEREGEX]\f[R], or -match by tag name with a \f[CR]tag:NAMEREGEX\f[R] query. -.SS Tag inheritance Postings also inherit tags from their transaction and their account. And transactions also acquire tags from their postings (and postings\[aq] accounts). @@ -2051,48 +2096,65 @@ tags (by inheriting from the account and transaction), and the transaction also has all five tags (by acquiring from the expenses posting). .SS Tag names -Tag names are currently not very clearly specified; any sequence of -non\-whitespace characters followed by a colon may work. +Most non\-whitespace characters are allowed in tag names. +Eg \f[CR]😀:\f[R] is a valid tag. .PP -The following tag names are generated by hledger or have special -significance to hledger, so you may want to avoid using them yourself: -.IP \[bu] 2 -\f[CR]balances\f[R] \-\- a balance assertions transaction generated by -close -.IP \[bu] 2 -\f[CR]retain\f[R] \-\- a retain earnings transaction generated by close -.IP \[bu] 2 -\f[CR]start\f[R] \-\- a opening balances, closing balances or balance -assignment transaction generated by close -.IP \[bu] 2 -\f[CR]generated\-transaction\f[R] \-\- a transaction generated by -\-\-forecast -.IP \[bu] 2 -\f[CR]generated\-posting\f[R] \-\- a posting generated by \-\-auto -.IP \[bu] 2 -\f[CR]modified\f[R] \-\- a transaction which has had postings added by -\-\-auto -.IP \[bu] 2 -\f[CR]type\f[R] \-\- declares an account\[aq]s type in an account -declaration -.IP \[bu] 2 -\f[CR]t\f[R] \-\- stores the (user defined, single letter) type of a 15m -unit of time parsed from timedot format +You can list the tag names used in your journal with the tags command: +.PD 0 +.P +.PD +\f[CR]hledger tags [NAMEREGEX]\f[R] .PP -Some additional tag names with an underscore prefix are used internally -and not displayed in reports (but can be matched by queries): -.IP \[bu] 2 -\f[CR]_generated\-transaction\f[R] -.IP \[bu] 2 -\f[CR]_generated\-posting\f[R] -.IP \[bu] 2 -\f[CR]_modified\f[R] -.IP \[bu] 2 -\f[CR]_conversion\-matched\f[R] +In commands which use a query, you can match by tag name. +Eg: +.PD 0 +.P +.PD +\f[CR]hledger print tag:NAMEREGEX\f[R] +.PP +You can declare valid tag names with the tag directive and then check +them with the check command. +.SS Special tags +Some tag names have special significance to hledger. +There\[aq]s not much harm in using them yourself, but some could produce +an error message, particularly the \f[CR]date:\f[R] tag. +They are explained elsewhere, but here is a quick list for reference: +.PP +Tags you can set to influence hledger\[aq]s behaviour: +.IP +.EX + date \-\- overrides a posting\[aq]s date + date2 \-\- overrides a posting\[aq]s secondary date + type \-\- declares an account\[aq]s type +.EE +.PP +Tags hledger adds to indicate generated data: +.IP +.EX + t \-\- appears on postings generated by timedot letters + assert \-\- appears on txns generated by close \-\-assert + retain \-\- appears on txns generated by close \-\-retain + start \-\- appears on txns generated by close \-\-migrate/\-\-close/\-\-open/\-\-assign + generated\-transaction \-\- appears on generated periodic txns (with \-\-verbose\-tags) + generated\-posting \-\- appears on generated auto postings (with \-\-verbose\-tags) + modified \-\- appears on txns which have had auto postings added (with \-\-verbose\-tags) +Not displayed, but queryable: + _generated\-transaction \-\- exists on generated periodic txns (always) + _generated\-posting \-\- exists on generated auto postings (always) + _modified \-\- exists on txns which have had auto postings added (always) +.EE +.PP +Tags hledger uses internally: +.IP +.EX + _conversion\-matched \-\- exists on postings which have been matched with a nearby \[at]/\[at]\[at] cost annotation +.EE .SS Tag values Tags can have a value, which is any text after the colon up until a -comma or end of line (with surrounding whitespace removed). -Note this means that hledger tag values can not contain commas. +comma or end of line, with surrounding whitespace removed. +Ending at comma allows us to write multiple tags on one line, but also +means that tag values can not contain commas. +.PP Eg in the following posting, the three tags\[aq] values are \[dq]value 1\[dq], \[dq]value 2\[dq], and \[dq]\[dq] (empty) respectively: .IP @@ -2100,14 +2162,21 @@ Eg in the following posting, the three tags\[aq] values are \[dq]value expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz .EE .PP -Note that tags can be repeated, and are additive rather than overriding: +Multiple tags with the same name are additive rather than overriding: when the same tag name is seen again with a new value, the new name:value pair is added to the tags. -(It is not possible to override a tag\[aq]s value or remove a tag.) +It is not possible to override a previous tag\[aq]s value or remove a +tag. .PP -You can list a tag\[aq]s values with -\f[CR]hledger tags TAGNAME \-\-values\f[R], or match by tag value with a -\f[CR]tag:NAMEREGEX=VALUEREGEX\f[R] query. +You can list all the values used for a particular tag in the journal +with +.PD 0 +.P +.PD +\f[CR]hledger tags TAGNAME \-\-values\f[R] +.PP +You can match on tag values with a query like +\f[CR]tag:NAMEREGEX=VALUEREGEX\f[R] .SS Directives Besides transactions, there is something else you can put in a \f[CR]journal\f[R] file: directives. @@ -2370,36 +2439,35 @@ Though not required, these declarations can provide several benefits: They can document your intended chart of accounts, providing a reference. .IP \[bu] 2 -In strict mode, they restrict which accounts may be posted to by -transactions, which helps detect typos. -.IP \[bu] 2 -They control account display order in reports, allowing non\-alphabetic -sorting (eg Revenues to appear above Expenses). -.IP \[bu] 2 -They help with account name completion (in hledger add, hledger\-web, -hledger\-iadd, ledger\-mode, etc.) -.IP \[bu] 2 They can store additional account information as comments, or as tags which can be used to filter or pivot reports. .IP \[bu] 2 +They can restrict which accounts may be posted to by transactions, eg in +strict mode, which helps prevent errors. +.IP \[bu] 2 +They influence account display order in reports, allowing +non\-alphabetic sorting (eg Revenues to appear above Expenses). +.IP \[bu] 2 They can help hledger know your accounts\[aq] types (asset, liability, -equity, revenue, expense), affecting reports like balancesheet and +equity, revenue, expense), enabling reports like balancesheet and incomestatement. +.IP \[bu] 2 +They help with account name completion (in hledger add, hledger\-web, +hledger\-iadd, ledger\-mode, etc.) .PP They are written as the word \f[CR]account\f[R] followed by a -hledger\-style account name, eg: +hledger\-style account name. +Eg: .IP .EX account assets:bank:checking .EE .PP -Note, however, that accounts declared in account directives are not -allowed to have surrounding brackets and parentheses, unlike accounts -used in postings. -So the following journal will not parse: +Ledger\-style indented subdirectives are also accepted, but ignored: .IP .EX -account (assets:bank:checking) +account assets:bank:checking + format subdirective ; currently ignored .EE .SS Account comments Text following \f[B]two or more spaces\f[R] and \f[CR];\f[R] at the end @@ -2415,14 +2483,6 @@ account assets:bank:checking ; same\-line comment, at least 2 spaces before t ; next\-line comment ; some tags \- type:A, acctnum:12345 .EE -.SS Account subdirectives -Ledger\-style indented subdirectives are also accepted, but currently -ignored: -.IP -.EX -account assets:bank:checking - format subdirective is ignored -.EE .SS Account error checking By default, accounts need not be declared; they come into existence when a posting references them. @@ -2453,10 +2513,9 @@ It\[aq]s currently not possible to declare \[dq]all possible subaccounts\[dq] with a wildcard; every account posted to must be declared. .SS Account display order -The order in which account directives are written influences the order -in which accounts appear in reports, hledger\-ui, hledger\-web etc. -By default accounts appear in alphabetical order, but if you add these -account directives to the journal file: +Account directives also cause hledger to display accounts in a +particular order, not just alphabetically. +Eg, here is a conventional ordering for the top\-level accounts: .IP .EX account assets @@ -2466,10 +2525,10 @@ account revenues account expenses .EE .PP -those accounts will be displayed in declaration order: +Now hledger displays them in that order: .IP .EX -$ hledger accounts \-1 +$ hledger accounts assets liabilities equity @@ -2477,27 +2536,23 @@ revenues expenses .EE .PP -Any undeclared accounts are displayed last, in alphabetical order. +If there are undeclared accounts, those will be displayed last, in +alphabetical order. .PP -Sorting is done at each level of the account tree, within each group of -sibling accounts under the same parent. -And currently, this directive: -.IP -.EX -account other:zoo -.EE +Sorting is done within each group of sibling accounts, at each level of +the account tree. +Eg, a declaration like \f[CR]account parent:child\f[R] influences +\f[CR]child\f[R]\[aq]s position among its siblings. .PP -would influence the position of \f[CR]zoo\f[R] among -\f[CR]other\f[R]\[aq]s subaccounts, but not the position of -\f[CR]other\f[R] among the top\-level accounts. -This means: -.IP \[bu] 2 -you will sometimes declare parent accounts (eg \f[CR]account other\f[R] -above) that you don\[aq]t intend to post to, just to customize their -display order -.IP \[bu] 2 -sibling accounts stay together (you couldn\[aq]t display \f[CR]x:y\f[R] -in between \f[CR]a:b\f[R] and \f[CR]a:c\f[R]). +Note, it does not affect \f[CR]parent\f[R]\[aq]s position; for that, you +need an \f[CR]account parent\f[R] declaration. +.PP +Sibling accounts are always displayed together; hledger won\[aq]t +display \f[CR]x:y\f[R] in between \f[CR]a:b\f[R] and \f[CR]a:c\f[R]. +.PP +An account directive both declares an account as a valid posting target, +and declares its display order; you can\[aq]t easily do one without the +other. .SS Account types hledger knows that accounts come in several types: assets, liabilities, expenses and so on. @@ -2507,9 +2562,8 @@ filtering by account type with the \f[CR]type:\f[R] query. As a convenience, hledger will detect these account types automatically if you are using common english\-language top\-level account names (described below). -But generally we recommend you declare types explicitly, by adding a -\f[CR]type:\f[R] tag to your top\-level account directives. -Subaccounts will inherit the type of their parent. +But it\[aq]s more robust to declare accounts\[aq] types explicitly, by +adding \f[CR]type:\f[R] tags to their account directives. The tag\[aq]s value should be one of the five main account types: .IP \[bu] 2 \f[CR]A\f[R] or \f[CR]Asset\f[R] (things you own) @@ -2533,6 +2587,7 @@ assets for the cashflow report) \f[CR]V\f[R] or \f[CR]Conversion\f[R] (a subtype of Equity, for conversions (see Cost reporting).) .PP +Subaccounts inherit their parent\[aq]s type, or they can override it. Here is a typical set of account type declarations: .IP .EX @@ -3017,8 +3072,8 @@ Any indented subdirectives are currently ignored. The \[dq]tags\[dq] check will report an error if any undeclared tag name is used. It is quite easy to accidentally create a tag through normal use of -colons in comments(#comments]; if you want to prevent this, you can -declare and check your tags . +colons in comments; if you want to prevent this, you can declare and +check your tags . .SS Periodic transactions The \f[CR]\[ti]\f[R] directive declares a \[dq]periodic rule\[dq] which generates temporary extra transactions, usually recurring at some diff --git a/hledger/hledger.info b/hledger/hledger.info index 1a18c28f9..001a914dc 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -155,18 +155,23 @@ File: hledger.info, Node: Data formats, Next: Standard input, Up: Input Usually the data file is in hledger's journal format, but it can be in any of the supported file formats, which currently are: -Reader: Reads: Used for file extensions: ----------------------------------------------------------------------------- -'journal' hledger journal files and '.journal' '.j' '.hledger' - some Ledger journals, for '.ledger' - transactions -'timeclock' timeclock files, for precise '.timeclock' - time logging -'timedot' timedot files, for '.timedot' - approximate time logging -'csv' CSV/SSV/TSV/character-separated '.csv' '.ssv' '.tsv' - values, for data import '.csv.rules' '.ssv.rules' - '.tsv.rules' +Reader: Reads: Automatically used for + files with extensions: +--------------------------------------------------------------------------- +'journal' hledger journal files and some '.journal' '.j' + Ledger journals, for '.hledger' '.ledger' + transactions +'timeclock' timeclock files, for precise '.timeclock' + time logging +'timedot' timedot files, for approximate '.timedot' + time logging +'csv' Comma or other character '.csv' + separated values, for data + import +'ssv' Semicolon separated values '.ssv' +'tsv' Tab separated values '.tsv' +'rules' CSV/SSV/TSV/other separated '.rules' + values, alternate way These formats are described in more detail below. @@ -177,10 +182,10 @@ recognised file extension, so as to either read successfully or to show relevant error messages. You can also force a specific reader/format by prefixing the file -path with the format and a colon. Eg, to read a .dat file as csv -format: +path with the format and a colon. Eg, to read a .dat file containing +tab separated values: -$ hledger -f csv:/some/csv-file.dat stats +$ hledger -f tsv:/some/file.dat stats  File: hledger.info, Node: Standard input, Next: Multiple files, Prev: Data formats, Up: Input @@ -1403,11 +1408,17 @@ File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code 9.8 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. +After the date, status mark and/or code fields, the rest of the line (or +until a comment is begun with ';') is the transaction's description. +Here you can describe the transaction (called the "narration" in +traditional bookkeeping), or you can record a payee/payer name, or you +can leave it empty. + + Transaction descriptions show up in print output and in register +reports, and can be listed with the descriptions command. + + You can query by description with 'desc:DESCREGEX', or pivot on +description with '--pivot desc'. * Menu: @@ -1419,11 +1430,25 @@ File: hledger.info, Node: Payee and note, Up: Description 9.8.1 Payee and note -------------------- -You can optionally include a '|' (pipe) character in descriptions to -subdivide 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. +Sometimes people want a dedicated payee/payer field that can be queried +and checked more strictly. If you want that, you can write a '|' (pipe) +character in the description. This divides it into a "payee" field on +the left, and a "note" field on the right. (Either can be empty.) + + You can query these with 'payee:PAYEEREGEX' and 'note:NOTEREGEX', +list their values with the payees and notes commands, or pivot on +'payee' or 'note'. + + Note: in transactions with no '|' character, description, payee, and +note all have the same value. Once a '|' is added, they become +distinct. (If you'd like to change this behaviour, please propose it on +the mail list.) + + If you want more strict error checking, you can declare the valid +payee names with 'payee' directives, and then enforce these with +'hledger check payees'. Note: because of the above, for this you'll +need to ensure every transaction description contains a '|' and +therefore a checkable payee name (even if it's empty).  File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal @@ -2067,18 +2092,21 @@ File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up 9.16 Tags ========= -Tags are a way to add extra labels or labelled data to transactions, +Tags are a way to add extra labels or data fields to transactions, postings, or accounts, which you can then search or pivot on. - They are written as a word (optionally hyphenated) immediately -followed by a full colon, in a transaction or posting or account -directive's comment. (This is an exception to the usual rule that -things in comments are ignored.) You can write multiple tags separated -by comma, and/or you can add more comment lines and write more tags -there. + A tag is a word, optionally hyphenated, immediately followed by a +full colon, in the comment of a transaction, a posting, or an account +directive. Eg: '2024-01-01 a transaction ; foo:' Note this is an +exception to the usual rule that things in comments are ignored. - Here five different tags are recorded: one on the checking account, -two on the transaction, and two on the expenses posting: + You can write multiple tags on one line, separated by comma. Or you +can write each tag on its own comment line (no comma needed in this +case). + + For example, here are five different tags: one on the +'assets:checking' account, two on the transaction, and two on the +'expenses:food' posting: account assets:checking ; accounttag: @@ -2087,80 +2115,100 @@ account assets:checking ; accounttag: assets:checking $-1 expenses:food $1 ; postingtag:, another-posting-tag: - You can list tag names with 'hledger tags [NAMEREGEX]', or match by -tag name with a 'tag:NAMEREGEX' query. - -* Menu: - -* Tag inheritance:: -* Tag names:: -* Tag values:: - - -File: hledger.info, Node: Tag inheritance, Next: Tag names, Up: Tags - -9.16.1 Tag inheritance ----------------------- - -Postings also inherit tags from their transaction and their account. + Postings also inherit tags from their transaction and their account. And transactions also acquire tags from their postings (and postings' accounts). So in the example above, the expenses posting effectively has all five tags (by inheriting from the account and transaction), and the transaction also has all five tags (by acquiring from the expenses posting). - -File: hledger.info, Node: Tag names, Next: Tag values, Prev: Tag inheritance, Up: Tags +* Menu: -9.16.2 Tag names +* Tag names:: +* Special tags:: +* Tag values:: + + +File: hledger.info, Node: Tag names, Next: Special tags, Up: Tags + +9.16.1 Tag names ---------------- -Tag names are currently not very clearly specified; any sequence of -non-whitespace characters followed by a colon may work. +Most non-whitespace characters are allowed in tag names. Eg '😀:' is a +valid tag. - The following tag names are generated by hledger or have special -significance to hledger, so you may want to avoid using them yourself: + You can list the tag names used in your journal with the tags +command: +'hledger tags [NAMEREGEX]' - * 'balances' - a balance assertions transaction generated by close - * 'retain' - a retain earnings transaction generated by close - * 'start' - a opening balances, closing balances or balance - assignment transaction generated by close - * 'generated-transaction' - a transaction generated by -forecast - * 'generated-posting' - a posting generated by -auto - * 'modified' - a transaction which has had postings added by -auto - * 'type' - declares an account's type in an account declaration - * 't' - stores the (user defined, single letter) type of a 15m unit - of time parsed from timedot format + In commands which use a query, you can match by tag name. Eg: +'hledger print tag:NAMEREGEX' - Some additional tag names with an underscore prefix are used -internally and not displayed in reports (but can be matched by queries): - - * '_generated-transaction' - * '_generated-posting' - * '_modified' - * '_conversion-matched' + You can declare valid tag names with the tag directive and then check +them with the check command.  -File: hledger.info, Node: Tag values, Prev: Tag names, Up: Tags +File: hledger.info, Node: Special tags, Next: Tag values, Prev: Tag names, Up: Tags + +9.16.2 Special tags +------------------- + +Some tag names have special significance to hledger. There's not much +harm in using them yourself, but some could produce an error message, +particularly the 'date:' tag. They are explained elsewhere, but here is +a quick list for reference: + + Tags you can set to influence hledger's behaviour: + + date -- overrides a posting's date + date2 -- overrides a posting's secondary date + type -- declares an account's type + + Tags hledger adds to indicate generated data: + + t -- appears on postings generated by timedot letters + assert -- appears on txns generated by close --assert + retain -- appears on txns generated by close --retain + start -- appears on txns generated by close --migrate/--close/--open/--assign + generated-transaction -- appears on generated periodic txns (with --verbose-tags) + generated-posting -- appears on generated auto postings (with --verbose-tags) + modified -- appears on txns which have had auto postings added (with --verbose-tags) +Not displayed, but queryable: + _generated-transaction -- exists on generated periodic txns (always) + _generated-posting -- exists on generated auto postings (always) + _modified -- exists on txns which have had auto postings added (always) + + Tags hledger uses internally: + + _conversion-matched -- exists on postings which have been matched with a nearby @/@@ cost annotation + + +File: hledger.info, Node: Tag values, Prev: Special tags, Up: Tags 9.16.3 Tag values ----------------- Tags can have a value, which is any text after the colon up until a -comma or end of line (with surrounding whitespace removed). Note this -means that hledger tag values can not contain commas. Eg in the -following posting, the three tags' values are "value 1", "value 2", and -"" (empty) respectively: +comma or end of line, with surrounding whitespace removed. Ending at +comma allows us to write multiple tags on one line, but also means that +tag values can not contain commas. + + Eg in the following posting, the three tags' values are "value 1", +"value 2", and "" (empty) respectively: expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz - Note that tags can be repeated, and are additive rather than -overriding: when the same tag name is seen again with a new value, the -new name:value pair is added to the tags. (It is not possible to -override a tag's value or remove a tag.) + Multiple tags with the same name are additive rather than overriding: +when the same tag name is seen again with a new value, the new +name:value pair is added to the tags. It is not possible to override a +previous tag's value or remove a tag. - You can list a tag's values with 'hledger tags TAGNAME --values', or -match by tag value with a 'tag:NAMEREGEX=VALUEREGEX' query. + You can list all the values used for a particular tag in the journal +with +'hledger tags TAGNAME --values' + + You can match on tag values with a query like +'tag:NAMEREGEX=VALUEREGEX'  File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal @@ -2295,39 +2343,37 @@ declarations can provide several benefits: * They can document your intended chart of accounts, providing a reference. - * In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. - * They control account display order in reports, allowing - non-alphabetic sorting (eg Revenues to appear above Expenses). - * They help with account name completion (in hledger add, - hledger-web, hledger-iadd, ledger-mode, etc.) * They can store additional account information as comments, or as tags which can be used to filter or pivot reports. + * They can restrict which accounts may be posted to by transactions, + eg in strict mode, which helps prevent errors. + * They influence account display order in reports, allowing + non-alphabetic sorting (eg Revenues to appear above Expenses). * They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), affecting reports like balancesheet and + equity, revenue, expense), enabling reports like balancesheet and incomestatement. + * They help with account name completion (in hledger add, + hledger-web, hledger-iadd, ledger-mode, etc.) They are written as the word 'account' followed by a hledger-style -account name, eg: +account name. Eg: account assets:bank:checking - Note, however, that accounts declared in account directives are not -allowed to have surrounding brackets and parentheses, unlike accounts -used in postings. So the following journal will not parse: + Ledger-style indented subdirectives are also accepted, but ignored: -account (assets:bank:checking) +account assets:bank:checking + format subdirective ; currently ignored * Menu: * Account comments:: -* Account subdirectives:: * Account error checking:: * Account display order:: * Account types::  -File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive +File: hledger.info, Node: Account comments, Next: Account error checking, Up: account directive 9.18.1 Account comments ----------------------- @@ -2345,21 +2391,9 @@ account assets:bank:checking ; same-line comment, at least 2 spaces before th ; some tags - type:A, acctnum:12345  -File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive +File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account comments, Up: account directive -9.18.2 Account subdirectives ----------------------------- - -Ledger-style indented subdirectives are also accepted, but currently -ignored: - -account assets:bank:checking - format subdirective is ignored - - -File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive - -9.18.3 Account error checking +9.18.2 Account error checking ----------------------------- By default, accounts need not be declared; they come into existence when @@ -2387,13 +2421,12 @@ been declared by an account directive. Some notes:  File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive -9.18.4 Account display order +9.18.3 Account display order ---------------------------- -The order in which account directives are written influences the order -in which accounts appear in reports, hledger-ui, hledger-web etc. By -default accounts appear in alphabetical order, but if you add these -account directives to the journal file: +Account directives also cause hledger to display accounts in a +particular order, not just alphabetically. Eg, here is a conventional +ordering for the top-level accounts: account assets account liabilities @@ -2401,37 +2434,36 @@ account equity account revenues account expenses - those accounts will be displayed in declaration order: + Now hledger displays them in that order: -$ hledger accounts -1 +$ hledger accounts assets liabilities equity revenues expenses - Any undeclared accounts are displayed last, in alphabetical order. + If there are undeclared accounts, those will be displayed last, in +alphabetical order. - Sorting is done at each level of the account tree, within each group -of sibling accounts under the same parent. And currently, this -directive: + Sorting is done within each group of sibling accounts, at each level +of the account tree. Eg, a declaration like 'account parent:child' +influences 'child''s position among its siblings. -account other:zoo + Note, it does not affect 'parent''s position; for that, you need an +'account parent' declaration. - would influence the position of 'zoo' among 'other''s subaccounts, -but not the position of 'other' among the top-level accounts. This -means: + Sibling accounts are always displayed together; hledger won't display +'x:y' in between 'a:b' and 'a:c'. - * you will sometimes declare parent accounts (eg 'account other' - above) that you don't intend to post to, just to customize their - display order - * sibling accounts stay together (you couldn't display 'x:y' in - between 'a:b' and 'a:c'). + An account directive both declares an account as a valid posting +target, and declares its display order; you can't easily do one without +the other.  File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive -9.18.5 Account types +9.18.4 Account types -------------------- hledger knows that accounts come in several types: assets, liabilities, @@ -2440,10 +2472,9 @@ incomestatement, and filtering by account type with the 'type:' query. As a convenience, hledger will detect these account types automatically if you are using common english-language top-level account -names (described below). But generally we recommend you declare types -explicitly, by adding a 'type:' tag to your top-level account -directives. Subaccounts will inherit the type of their parent. The -tag's value should be one of the five main account types: +names (described below). But it's more robust to declare accounts' +types explicitly, by adding 'type:' tags to their account directives. +The tag's value should be one of the five main account types: * 'A' or 'Asset' (things you own) * 'L' or 'Liability' (things you owe) @@ -2461,7 +2492,8 @@ tag's value should be one of the five main account types: * 'V' or 'Conversion' (a subtype of Equity, for conversions (see Cost reporting).) - Here is a typical set of account type declarations: + Subaccounts inherit their parent's type, or they can override it. +Here is a typical set of account type declarations: account assets ; type: A account liabilities ; type: L @@ -2958,8 +2990,8 @@ tag item-id The "tags" check will report an error if any undeclared tag name is used. It is quite easy to accidentally create a tag through normal use -of colons in comments(#comments]; if you want to prevent this, you can -declare and check your tags . +of colons in comments; if you want to prevent this, you can declare and +check your tags .  File: hledger.info, Node: Periodic transactions, Next: Auto postings, Prev: tag directive, Up: Journal @@ -10921,674 +10953,672 @@ Node: Input3960 Ref: #input4070 Node: Data formats5019 Ref: #data-formats5132 -Node: Standard input6494 -Ref: #standard-input6634 -Node: Multiple files6861 -Ref: #multiple-files7000 -Node: Strict mode7598 -Ref: #strict-mode7708 -Node: Commands8432 -Ref: #commands8534 -Node: Add-on commands9601 -Ref: #add-on-commands9703 -Node: Options10819 -Ref: #options10931 -Node: General help options11259 -Ref: #general-help-options11405 -Node: General input options11687 -Ref: #general-input-options11869 -Node: General reporting options12526 -Ref: #general-reporting-options12687 -Node: Command line tips16077 -Ref: #command-line-tips16207 -Node: Option repetition16466 -Ref: #option-repetition16610 -Node: Special characters16714 -Ref: #special-characters16887 -Node: Single escaping shell metacharacters17050 -Ref: #single-escaping-shell-metacharacters17291 -Node: Double escaping regular expression metacharacters17894 -Ref: #double-escaping-regular-expression-metacharacters18205 -Node: Triple escaping for add-on commands18731 -Ref: #triple-escaping-for-add-on-commands18991 -Node: Less escaping19635 -Ref: #less-escaping19789 -Node: Unicode characters20113 -Ref: #unicode-characters20288 -Node: Regular expressions21700 -Ref: #regular-expressions21873 -Node: hledger's regular expressions24969 -Ref: #hledgers-regular-expressions25128 -Node: Argument files26514 -Ref: #argument-files26650 -Node: Output27147 -Ref: #output27259 -Node: Output destination27386 -Ref: #output-destination27517 -Node: Output format27942 -Ref: #output-format28088 -Node: CSV output29685 -Ref: #csv-output29801 -Node: HTML output29904 -Ref: #html-output30042 -Node: JSON output30136 -Ref: #json-output30274 -Node: SQL output31196 -Ref: #sql-output31312 -Node: Commodity styles32047 -Ref: #commodity-styles32187 -Node: Colour33003 -Ref: #colour33121 -Node: Box-drawing33525 -Ref: #box-drawing33643 -Node: Paging33933 -Ref: #paging34047 -Node: Debug output35000 -Ref: #debug-output35106 -Node: Environment35769 -Ref: #environment35893 -Node: PART 2 DATA FORMATS36437 -Ref: #part-2-data-formats36580 -Node: Journal36580 -Ref: #journal36689 -Node: Journal cheatsheet37346 -Ref: #journal-cheatsheet37485 -Node: About journal format41470 -Ref: #about-journal-format41630 -Node: Comments43246 -Ref: #comments43376 -Node: Transactions44192 -Ref: #transactions44315 -Node: Dates45329 -Ref: #dates45436 -Node: Simple dates45481 -Ref: #simple-dates45597 -Node: Posting dates46097 -Ref: #posting-dates46215 -Node: Status47184 -Ref: #status47285 -Node: Code48993 -Ref: #code49096 -Node: Description49328 -Ref: #description49459 -Node: Payee and note49779 -Ref: #payee-and-note49885 -Node: Transaction comments50220 -Ref: #transaction-comments50373 -Node: Postings50736 -Ref: #postings50869 -Node: Account names51864 -Ref: #account-names51994 -Node: Amounts53668 -Ref: #amounts53783 -Node: Decimal marks digit group marks54786 -Ref: #decimal-marks-digit-group-marks54961 -Node: Commodity55820 -Ref: #commodity56007 -Node: Directives influencing number parsing and display56959 -Ref: #directives-influencing-number-parsing-and-display57218 -Node: Commodity display style57670 -Ref: #commodity-display-style57876 -Node: Rounding59286 -Ref: #rounding59426 -Node: Number format59876 -Ref: #number-format59994 -Node: Costs60208 -Ref: #costs60324 -Node: Other cost/lot notations62520 -Ref: #other-costlot-notations62652 -Node: Balance assertions65241 -Ref: #balance-assertions65392 -Node: Assertions and ordering66474 -Ref: #assertions-and-ordering66663 -Node: Assertions and multiple included files67363 -Ref: #assertions-and-multiple-included-files67623 -Node: Assertions and multiple -f files68123 -Ref: #assertions-and-multiple--f-files68374 -Node: Assertions and commodities68771 -Ref: #assertions-and-commodities68992 -Node: Assertions and costs70172 -Ref: #assertions-and-costs70375 -Node: Assertions and subaccounts70816 -Ref: #assertions-and-subaccounts71036 -Node: Assertions and virtual postings71360 -Ref: #assertions-and-virtual-postings71598 -Node: Assertions and auto postings71730 -Ref: #assertions-and-auto-postings71960 -Node: Assertions and precision72605 -Ref: #assertions-and-precision72787 -Node: Posting comments73054 -Ref: #posting-comments73200 -Node: Tags73577 -Ref: #tags73691 -Node: Tag inheritance74691 -Ref: #tag-inheritance74813 -Node: Tag names75176 -Ref: #tag-names75305 -Node: Tag values76427 -Ref: #tag-values76534 -Node: Directives77293 -Ref: #directives77420 -Node: Directives and multiple files78750 -Ref: #directives-and-multiple-files78928 -Node: Directive effects79695 -Ref: #directive-effects79849 -Node: account directive82862 -Ref: #account-directive83018 -Node: Account comments84416 -Ref: #account-comments84566 -Node: Account subdirectives85074 -Ref: #account-subdirectives85265 -Node: Account error checking85407 -Ref: #account-error-checking85605 -Node: Account display order86794 -Ref: #account-display-order86982 -Node: Account types88083 -Ref: #account-types88224 -Node: alias directive91851 -Ref: #alias-directive92012 -Node: Basic aliases93062 -Ref: #basic-aliases93193 -Node: Regex aliases93937 -Ref: #regex-aliases94094 -Node: Combining aliases94984 -Ref: #combining-aliases95162 -Node: Aliases and multiple files96438 -Ref: #aliases-and-multiple-files96642 -Node: end aliases directive97221 -Ref: #end-aliases-directive97440 -Node: Aliases can generate bad account names97589 -Ref: #aliases-can-generate-bad-account-names97837 -Node: Aliases and account types98422 -Ref: #aliases-and-account-types98614 -Node: commodity directive99310 -Ref: #commodity-directive99484 -Node: Commodity directive syntax100669 -Ref: #commodity-directive-syntax100854 -Node: Commodity error checking102305 -Ref: #commodity-error-checking102486 -Node: decimal-mark directive102780 -Ref: #decimal-mark-directive102962 -Node: include directive103359 -Ref: #include-directive103523 -Node: P directive104435 -Ref: #p-directive104580 -Node: payee directive105469 -Ref: #payee-directive105618 -Node: tag directive106091 -Ref: #tag-directive106246 -Node: Periodic transactions106714 -Ref: #periodic-transactions106879 -Node: Periodic rule syntax108868 -Ref: #periodic-rule-syntax109046 -Node: Periodic rules and relative dates109691 -Ref: #periodic-rules-and-relative-dates109957 -Node: Two spaces between period expression and description!110468 -Ref: #two-spaces-between-period-expression-and-description110745 -Node: Auto postings111429 -Ref: #auto-postings111577 -Node: Auto postings and multiple files114407 -Ref: #auto-postings-and-multiple-files114571 -Node: Auto postings and dates114972 -Ref: #auto-postings-and-dates115220 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions115395 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions115751 -Node: Auto posting tags116254 -Ref: #auto-posting-tags116536 -Node: Auto postings on forecast transactions only117172 -Ref: #auto-postings-on-forecast-transactions-only117418 -Node: Other syntax117665 -Ref: #other-syntax117781 -Node: Balance assignments118408 -Ref: #balance-assignments118564 -Node: Balance assignments and costs119936 -Ref: #balance-assignments-and-costs120148 -Node: Balance assignments and multiple files120358 -Ref: #balance-assignments-and-multiple-files120588 -Node: Bracketed posting dates120781 -Ref: #bracketed-posting-dates120965 -Node: D directive121479 -Ref: #d-directive121647 -Node: apply account directive123247 -Ref: #apply-account-directive123427 -Node: Y directive124114 -Ref: #y-directive124274 -Node: Secondary dates125102 -Ref: #secondary-dates125256 -Node: Star comments126070 -Ref: #star-comments126230 -Node: Valuation expressions126762 -Ref: #valuation-expressions126939 -Node: Virtual postings127061 -Ref: #virtual-postings127238 -Node: Other Ledger directives128675 -Ref: #other-ledger-directives128838 -Node: CSV129404 -Ref: #csv129497 -Node: CSV rules cheatsheet131577 -Ref: #csv-rules-cheatsheet131706 -Node: source133504 -Ref: #source133627 -Node: separator134507 -Ref: #separator134620 -Node: skip135160 -Ref: #skip135268 -Node: date-format135812 -Ref: #date-format135933 -Node: timezone136657 -Ref: #timezone136780 -Node: newest-first137785 -Ref: #newest-first137923 -Node: intra-day-reversed138500 -Ref: #intra-day-reversed138654 -Node: decimal-mark139102 -Ref: #decimal-mark139243 -Node: fields list139582 -Ref: #fields-list139721 -Node: Field assignment141392 -Ref: #field-assignment141536 -Node: Field names142613 -Ref: #field-names142744 -Node: date field143947 -Ref: #date-field144065 -Node: date2 field144113 -Ref: #date2-field144254 -Node: status field144310 -Ref: #status-field144453 -Node: code field144502 -Ref: #code-field144647 -Node: description field144692 -Ref: #description-field144852 -Node: comment field144911 -Ref: #comment-field145066 -Node: account field145359 -Ref: #account-field145509 -Node: amount field146079 -Ref: #amount-field146228 -Node: currency field148920 -Ref: #currency-field149073 -Node: balance field149330 -Ref: #balance-field149462 -Node: if block149834 -Ref: #if-block149955 -Node: Matchers151363 -Ref: #matchers151477 -Node: What matchers match152274 -Ref: #what-matchers-match152423 -Node: Combining matchers152863 -Ref: #combining-matchers153031 -Node: Match groups153533 -Ref: #match-groups153661 -Node: if table154429 -Ref: #if-table154551 -Node: balance-type156113 -Ref: #balance-type156242 -Node: include156942 -Ref: #include157069 -Node: Working with CSV157513 -Ref: #working-with-csv157660 -Node: Rapid feedback158067 -Ref: #rapid-feedback158200 -Node: Valid CSV158652 -Ref: #valid-csv158798 -Node: File Extension159530 -Ref: #file-extension159703 -Node: Reading CSV from standard input160267 -Ref: #reading-csv-from-standard-input160491 -Node: Reading multiple CSV files160655 -Ref: #reading-multiple-csv-files160886 -Node: Reading files specified by rule161127 -Ref: #reading-files-specified-by-rule161355 -Node: Valid transactions162526 -Ref: #valid-transactions162725 -Node: Deduplicating importing163353 -Ref: #deduplicating-importing163548 -Node: Setting amounts164584 -Ref: #setting-amounts164755 -Node: Amount signs167113 -Ref: #amount-signs167283 -Node: Setting currency/commodity168180 -Ref: #setting-currencycommodity168384 -Node: Amount decimal places169558 -Ref: #amount-decimal-places169764 -Node: Referencing other fields170076 -Ref: #referencing-other-fields170289 -Node: How CSV rules are evaluated171186 -Ref: #how-csv-rules-are-evaluated171403 -Node: Well factored rules172856 -Ref: #well-factored-rules173024 -Node: CSV rules examples173348 -Ref: #csv-rules-examples173483 -Node: Bank of Ireland173548 -Ref: #bank-of-ireland173685 -Node: Coinbase175147 -Ref: #coinbase175285 -Node: Amazon176332 -Ref: #amazon176457 -Node: Paypal178176 -Ref: #paypal178284 -Node: Timeclock185928 -Ref: #timeclock186033 -Node: Timedot188211 -Ref: #timedot188334 -Node: Timedot examples191455 -Ref: #timedot-examples191561 -Node: PART 3 REPORTING CONCEPTS193732 -Ref: #part-3-reporting-concepts193914 -Node: Amount formatting parseability193914 -Ref: #amount-formatting-parseability194111 -Node: Time periods196316 -Ref: #time-periods196455 -Node: Report start & end date196573 -Ref: #report-start-end-date196725 -Node: Smart dates198384 -Ref: #smart-dates198537 -Node: Report intervals200405 -Ref: #report-intervals200560 -Node: Date adjustment200978 -Ref: #date-adjustment201138 -Node: Period expressions201989 -Ref: #period-expressions202130 -Node: Period expressions with a report interval203894 -Ref: #period-expressions-with-a-report-interval204128 -Node: More complex report intervals204342 -Ref: #more-complex-report-intervals204587 -Node: Multiple weekday intervals206388 -Ref: #multiple-weekday-intervals206577 -Node: Depth207399 -Ref: #depth207501 -Node: Queries207797 -Ref: #queries207899 -Node: Query types209529 -Ref: #query-types209650 -Node: Combining query terms212884 -Ref: #combining-query-terms213061 -Node: Queries and command options214329 -Ref: #queries-and-command-options214528 -Node: Queries and valuation214777 -Ref: #queries-and-valuation214972 -Node: Querying with account aliases215201 -Ref: #querying-with-account-aliases215412 -Node: Querying with cost or value215542 -Ref: #querying-with-cost-or-value215719 -Node: Pivoting216020 -Ref: #pivoting216134 -Node: Generating data217911 -Ref: #generating-data218043 -Node: Forecasting219626 -Ref: #forecasting219751 -Node: --forecast220282 -Ref: #forecast220413 -Node: Inspecting forecast transactions221383 -Ref: #inspecting-forecast-transactions221585 -Node: Forecast reports222715 -Ref: #forecast-reports222888 -Node: Forecast tags223824 -Ref: #forecast-tags223984 -Node: Forecast period in detail224444 -Ref: #forecast-period-in-detail224638 -Node: Forecast troubleshooting225532 -Ref: #forecast-troubleshooting225700 -Node: Budgeting226603 -Ref: #budgeting226723 -Node: Cost reporting227160 -Ref: #cost-reporting227294 -Node: Recording costs227955 -Ref: #recording-costs228091 -Node: Reporting at cost229682 -Ref: #reporting-at-cost229857 -Node: Equity conversion postings230447 -Ref: #equity-conversion-postings230661 -Node: Inferring equity conversion postings233092 -Ref: #inferring-equity-conversion-postings233355 -Node: Combining costs and equity conversion postings234107 -Ref: #combining-costs-and-equity-conversion-postings234417 -Node: Requirements for detecting equity conversion postings235332 -Ref: #requirements-for-detecting-equity-conversion-postings235654 -Node: Infer cost and equity by default ?236854 -Ref: #infer-cost-and-equity-by-default237083 -Node: Value reporting237291 -Ref: #value-reporting237433 -Node: -V Value238207 -Ref: #v-value238339 -Node: -X Value in specified commodity238534 -Ref: #x-value-in-specified-commodity238735 -Node: Valuation date238884 -Ref: #valuation-date239061 -Node: Finding market price239844 -Ref: #finding-market-price240055 -Node: --infer-market-prices market prices from transactions241224 -Ref: #infer-market-prices-market-prices-from-transactions241506 -Node: Valuation commodity244268 -Ref: #valuation-commodity244487 -Node: Simple valuation examples245700 -Ref: #simple-valuation-examples245904 -Node: --value Flexible valuation246563 -Ref: #value-flexible-valuation246773 -Node: More valuation examples248417 -Ref: #more-valuation-examples248632 -Node: Interaction of valuation and queries249902 -Ref: #interaction-of-valuation-and-queries250149 -Node: Effect of valuation on reports250621 -Ref: #effect-of-valuation-on-reports250824 -Node: PART 4 COMMANDS258521 -Ref: #part-4-commands258670 -Node: Commands overview259049 -Ref: #commands-overview259183 -Node: DATA ENTRY259362 -Ref: #data-entry259486 -Node: DATA CREATION259685 -Ref: #data-creation259839 -Node: DATA MANAGEMENT259957 -Ref: #data-management260122 -Node: REPORTS FINANCIAL260243 -Ref: #reports-financial260418 -Node: REPORTS VERSATILE260723 -Ref: #reports-versatile260896 -Node: REPORTS BASIC261149 -Ref: #reports-basic261301 -Node: HELP261810 -Ref: #help261932 -Node: ADD-ONS262042 -Ref: #add-ons262148 -Node: accounts262727 -Ref: #accounts262860 -Node: activity264747 -Ref: #activity264866 -Node: add265240 -Ref: #add265350 -Node: aregister268336 -Ref: #aregister268457 -Node: aregister and posting dates271363 -Ref: #aregister-and-posting-dates271508 -Node: balance272264 -Ref: #balance272390 -Node: balance features273375 -Ref: #balance-features273515 -Node: Simple balance report275499 -Ref: #simple-balance-report275684 -Node: Balance report line format277309 -Ref: #balance-report-line-format277511 -Node: Filtered balance report279669 -Ref: #filtered-balance-report279861 -Node: List or tree mode280188 -Ref: #list-or-tree-mode280356 -Node: Depth limiting281701 -Ref: #depth-limiting281867 -Node: Dropping top-level accounts282468 -Ref: #dropping-top-level-accounts282668 -Node: Showing declared accounts282978 -Ref: #showing-declared-accounts283177 -Node: Sorting by amount283708 -Ref: #sorting-by-amount283875 -Node: Percentages284545 -Ref: #percentages284704 -Node: Multi-period balance report285252 -Ref: #multi-period-balance-report285452 -Node: Balance change end balance287709 -Ref: #balance-change-end-balance287918 -Node: Balance report types289346 -Ref: #balance-report-types289527 -Node: Calculation type290025 -Ref: #calculation-type290180 -Node: Accumulation type290729 -Ref: #accumulation-type290909 -Node: Valuation type291811 -Ref: #valuation-type291999 -Node: Combining balance report types293000 -Ref: #combining-balance-report-types293194 -Node: Budget report295032 -Ref: #budget-report295194 -Node: Using the budget report297337 -Ref: #using-the-budget-report297510 -Node: Budget date surprises299613 -Ref: #budget-date-surprises299813 -Node: Selecting budget goals300977 -Ref: #selecting-budget-goals301180 -Node: Budgeting vs forecasting301925 -Ref: #budgeting-vs-forecasting302102 -Node: Balance report layout303373 -Ref: #balance-report-layout303553 -Node: Useful balance reports311738 -Ref: #useful-balance-reports311898 -Node: balancesheet312983 -Ref: #balancesheet313128 -Node: balancesheetequity314458 -Ref: #balancesheetequity314616 -Node: cashflow315997 -Ref: #cashflow316128 -Node: check317566 -Ref: #check317680 -Node: Default checks318484 -Ref: #default-checks318610 -Node: Strict checks319107 -Ref: #strict-checks319252 -Node: Other checks319732 -Ref: #other-checks319874 -Node: Custom checks320407 -Ref: #custom-checks320564 -Node: More about specific checks320981 -Ref: #more-about-specific-checks321143 -Node: close321849 -Ref: #close321960 -Node: close --migrate322613 -Ref: #close---migrate322740 -Node: close --close324379 -Ref: #close---close324523 -Node: close --open324759 -Ref: #close---open324900 -Node: close --assert325010 -Ref: #close---assert325156 -Node: close --assign325377 -Ref: #close---assign325525 -Node: close --retain326051 -Ref: #close---retain326204 -Node: close customisation326949 -Ref: #close-customisation327128 -Node: close and balance assertions328595 -Ref: #close-and-balance-assertions328792 -Node: close examples329968 -Ref: #close-examples330109 -Node: Retain earnings330207 -Ref: #retain-earnings330366 -Node: Migrate balances to a new file330712 -Ref: #migrate-balances-to-a-new-file330938 -Node: More detailed close examples332066 -Ref: #more-detailed-close-examples332264 -Node: codes332290 -Ref: #codes332407 -Node: commodities333271 -Ref: #commodities333399 -Node: demo333469 -Ref: #demo333590 -Node: descriptions334506 -Ref: #descriptions334636 -Node: diff334927 -Ref: #diff335042 -Node: files336084 -Ref: #files336193 -Node: help336334 -Ref: #help-1336443 -Node: import337816 -Ref: #import337939 -Node: Deduplication339047 -Ref: #deduplication339172 -Node: Import testing341191 -Ref: #import-testing341356 -Node: Importing balance assignments342199 -Ref: #importing-balance-assignments342405 -Node: Commodity display styles343054 -Ref: #commodity-display-styles343227 -Node: incomestatement343356 -Ref: #incomestatement343498 -Node: notes344829 -Ref: #notes344951 -Node: payees345313 -Ref: #payees345428 -Node: prices345947 -Ref: #prices346062 -Node: print346715 -Ref: #print346830 -Node: print explicitness347806 -Ref: #print-explicitness347949 -Node: print amount style348728 -Ref: #print-amount-style348898 -Node: print parseability349968 -Ref: #print-parseability350140 -Node: print other features350889 -Ref: #print-other-features351068 -Node: print output format351589 -Ref: #print-output-format351737 -Node: register354876 -Ref: #register354998 -Node: Custom register output360029 -Ref: #custom-register-output360160 -Node: rewrite361507 -Ref: #rewrite361625 -Node: Re-write rules in a file363523 -Ref: #re-write-rules-in-a-file363686 -Node: Diff output format364835 -Ref: #diff-output-format365018 -Node: rewrite vs print --auto366110 -Ref: #rewrite-vs.-print---auto366270 -Node: roi366826 -Ref: #roi366933 -Node: Spaces and special characters in --inv and --pnl368745 -Ref: #spaces-and-special-characters-in---inv-and---pnl368985 -Node: Semantics of --inv and --pnl369473 -Ref: #semantics-of---inv-and---pnl369712 -Node: IRR and TWR explained371562 -Ref: #irr-and-twr-explained371722 -Node: stats374975 -Ref: #stats375083 -Node: tags376470 -Ref: #tags-1376577 -Node: test377586 -Ref: #test377679 -Node: PART 5 COMMON TASKS378421 -Ref: #part-5-common-tasks378567 -Node: Getting help378865 -Ref: #getting-help379006 -Node: Constructing command lines379766 -Ref: #constructing-command-lines379967 -Node: Starting a journal file380624 -Ref: #starting-a-journal-file380826 -Node: Setting LEDGER_FILE382028 -Ref: #setting-ledger_file382220 -Node: Setting opening balances383177 -Ref: #setting-opening-balances383378 -Node: Recording transactions386519 -Ref: #recording-transactions386708 -Node: Reconciling387264 -Ref: #reconciling387416 -Node: Reporting389673 -Ref: #reporting389822 -Node: Migrating to a new file393807 -Ref: #migrating-to-a-new-file393964 -Node: BUGS394263 -Ref: #bugs394353 -Node: Troubleshooting395232 -Ref: #troubleshooting395332 +Node: Standard input6721 +Ref: #standard-input6861 +Node: Multiple files7088 +Ref: #multiple-files7227 +Node: Strict mode7825 +Ref: #strict-mode7935 +Node: Commands8659 +Ref: #commands8761 +Node: Add-on commands9828 +Ref: #add-on-commands9930 +Node: Options11046 +Ref: #options11158 +Node: General help options11486 +Ref: #general-help-options11632 +Node: General input options11914 +Ref: #general-input-options12096 +Node: General reporting options12753 +Ref: #general-reporting-options12914 +Node: Command line tips16304 +Ref: #command-line-tips16434 +Node: Option repetition16693 +Ref: #option-repetition16837 +Node: Special characters16941 +Ref: #special-characters17114 +Node: Single escaping shell metacharacters17277 +Ref: #single-escaping-shell-metacharacters17518 +Node: Double escaping regular expression metacharacters18121 +Ref: #double-escaping-regular-expression-metacharacters18432 +Node: Triple escaping for add-on commands18958 +Ref: #triple-escaping-for-add-on-commands19218 +Node: Less escaping19862 +Ref: #less-escaping20016 +Node: Unicode characters20340 +Ref: #unicode-characters20515 +Node: Regular expressions21927 +Ref: #regular-expressions22100 +Node: hledger's regular expressions25196 +Ref: #hledgers-regular-expressions25355 +Node: Argument files26741 +Ref: #argument-files26877 +Node: Output27374 +Ref: #output27486 +Node: Output destination27613 +Ref: #output-destination27744 +Node: Output format28169 +Ref: #output-format28315 +Node: CSV output29912 +Ref: #csv-output30028 +Node: HTML output30131 +Ref: #html-output30269 +Node: JSON output30363 +Ref: #json-output30501 +Node: SQL output31423 +Ref: #sql-output31539 +Node: Commodity styles32274 +Ref: #commodity-styles32414 +Node: Colour33230 +Ref: #colour33348 +Node: Box-drawing33752 +Ref: #box-drawing33870 +Node: Paging34160 +Ref: #paging34274 +Node: Debug output35227 +Ref: #debug-output35333 +Node: Environment35996 +Ref: #environment36120 +Node: PART 2 DATA FORMATS36664 +Ref: #part-2-data-formats36807 +Node: Journal36807 +Ref: #journal36916 +Node: Journal cheatsheet37573 +Ref: #journal-cheatsheet37712 +Node: About journal format41697 +Ref: #about-journal-format41857 +Node: Comments43473 +Ref: #comments43603 +Node: Transactions44419 +Ref: #transactions44542 +Node: Dates45556 +Ref: #dates45663 +Node: Simple dates45708 +Ref: #simple-dates45824 +Node: Posting dates46324 +Ref: #posting-dates46442 +Node: Status47411 +Ref: #status47512 +Node: Code49220 +Ref: #code49323 +Node: Description49555 +Ref: #description49686 +Node: Payee and note50242 +Ref: #payee-and-note50348 +Node: Transaction comments51336 +Ref: #transaction-comments51489 +Node: Postings51852 +Ref: #postings51985 +Node: Account names52980 +Ref: #account-names53110 +Node: Amounts54784 +Ref: #amounts54899 +Node: Decimal marks digit group marks55902 +Ref: #decimal-marks-digit-group-marks56077 +Node: Commodity56936 +Ref: #commodity57123 +Node: Directives influencing number parsing and display58075 +Ref: #directives-influencing-number-parsing-and-display58334 +Node: Commodity display style58786 +Ref: #commodity-display-style58992 +Node: Rounding60402 +Ref: #rounding60542 +Node: Number format60992 +Ref: #number-format61110 +Node: Costs61324 +Ref: #costs61440 +Node: Other cost/lot notations63636 +Ref: #other-costlot-notations63768 +Node: Balance assertions66357 +Ref: #balance-assertions66508 +Node: Assertions and ordering67590 +Ref: #assertions-and-ordering67779 +Node: Assertions and multiple included files68479 +Ref: #assertions-and-multiple-included-files68739 +Node: Assertions and multiple -f files69239 +Ref: #assertions-and-multiple--f-files69490 +Node: Assertions and commodities69887 +Ref: #assertions-and-commodities70108 +Node: Assertions and costs71288 +Ref: #assertions-and-costs71491 +Node: Assertions and subaccounts71932 +Ref: #assertions-and-subaccounts72152 +Node: Assertions and virtual postings72476 +Ref: #assertions-and-virtual-postings72714 +Node: Assertions and auto postings72846 +Ref: #assertions-and-auto-postings73076 +Node: Assertions and precision73721 +Ref: #assertions-and-precision73903 +Node: Posting comments74170 +Ref: #posting-comments74316 +Node: Tags74693 +Ref: #tags74807 +Node: Tag names76150 +Ref: #tag-names76257 +Node: Special tags76645 +Ref: #special-tags76777 +Node: Tag values78277 +Ref: #tag-values78387 +Node: Directives79259 +Ref: #directives79386 +Node: Directives and multiple files80716 +Ref: #directives-and-multiple-files80894 +Node: Directive effects81661 +Ref: #directive-effects81815 +Node: account directive84828 +Ref: #account-directive84984 +Node: Account comments86278 +Ref: #account-comments86429 +Node: Account error checking86937 +Ref: #account-error-checking87130 +Node: Account display order88319 +Ref: #account-display-order88507 +Node: Account types89517 +Ref: #account-types89658 +Node: alias directive93291 +Ref: #alias-directive93452 +Node: Basic aliases94502 +Ref: #basic-aliases94633 +Node: Regex aliases95377 +Ref: #regex-aliases95534 +Node: Combining aliases96424 +Ref: #combining-aliases96602 +Node: Aliases and multiple files97878 +Ref: #aliases-and-multiple-files98082 +Node: end aliases directive98661 +Ref: #end-aliases-directive98880 +Node: Aliases can generate bad account names99029 +Ref: #aliases-can-generate-bad-account-names99277 +Node: Aliases and account types99862 +Ref: #aliases-and-account-types100054 +Node: commodity directive100750 +Ref: #commodity-directive100924 +Node: Commodity directive syntax102109 +Ref: #commodity-directive-syntax102294 +Node: Commodity error checking103745 +Ref: #commodity-error-checking103926 +Node: decimal-mark directive104220 +Ref: #decimal-mark-directive104402 +Node: include directive104799 +Ref: #include-directive104963 +Node: P directive105875 +Ref: #p-directive106020 +Node: payee directive106909 +Ref: #payee-directive107058 +Node: tag directive107531 +Ref: #tag-directive107686 +Node: Periodic transactions108143 +Ref: #periodic-transactions108308 +Node: Periodic rule syntax110297 +Ref: #periodic-rule-syntax110475 +Node: Periodic rules and relative dates111120 +Ref: #periodic-rules-and-relative-dates111386 +Node: Two spaces between period expression and description!111897 +Ref: #two-spaces-between-period-expression-and-description112174 +Node: Auto postings112858 +Ref: #auto-postings113006 +Node: Auto postings and multiple files115836 +Ref: #auto-postings-and-multiple-files116000 +Node: Auto postings and dates116401 +Ref: #auto-postings-and-dates116649 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions116824 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions117180 +Node: Auto posting tags117683 +Ref: #auto-posting-tags117965 +Node: Auto postings on forecast transactions only118601 +Ref: #auto-postings-on-forecast-transactions-only118847 +Node: Other syntax119094 +Ref: #other-syntax119210 +Node: Balance assignments119837 +Ref: #balance-assignments119993 +Node: Balance assignments and costs121365 +Ref: #balance-assignments-and-costs121577 +Node: Balance assignments and multiple files121787 +Ref: #balance-assignments-and-multiple-files122017 +Node: Bracketed posting dates122210 +Ref: #bracketed-posting-dates122394 +Node: D directive122908 +Ref: #d-directive123076 +Node: apply account directive124676 +Ref: #apply-account-directive124856 +Node: Y directive125543 +Ref: #y-directive125703 +Node: Secondary dates126531 +Ref: #secondary-dates126685 +Node: Star comments127499 +Ref: #star-comments127659 +Node: Valuation expressions128191 +Ref: #valuation-expressions128368 +Node: Virtual postings128490 +Ref: #virtual-postings128667 +Node: Other Ledger directives130104 +Ref: #other-ledger-directives130267 +Node: CSV130833 +Ref: #csv130926 +Node: CSV rules cheatsheet133006 +Ref: #csv-rules-cheatsheet133135 +Node: source134933 +Ref: #source135056 +Node: separator135936 +Ref: #separator136049 +Node: skip136589 +Ref: #skip136697 +Node: date-format137241 +Ref: #date-format137362 +Node: timezone138086 +Ref: #timezone138209 +Node: newest-first139214 +Ref: #newest-first139352 +Node: intra-day-reversed139929 +Ref: #intra-day-reversed140083 +Node: decimal-mark140531 +Ref: #decimal-mark140672 +Node: fields list141011 +Ref: #fields-list141150 +Node: Field assignment142821 +Ref: #field-assignment142965 +Node: Field names144042 +Ref: #field-names144173 +Node: date field145376 +Ref: #date-field145494 +Node: date2 field145542 +Ref: #date2-field145683 +Node: status field145739 +Ref: #status-field145882 +Node: code field145931 +Ref: #code-field146076 +Node: description field146121 +Ref: #description-field146281 +Node: comment field146340 +Ref: #comment-field146495 +Node: account field146788 +Ref: #account-field146938 +Node: amount field147508 +Ref: #amount-field147657 +Node: currency field150349 +Ref: #currency-field150502 +Node: balance field150759 +Ref: #balance-field150891 +Node: if block151263 +Ref: #if-block151384 +Node: Matchers152792 +Ref: #matchers152906 +Node: What matchers match153703 +Ref: #what-matchers-match153852 +Node: Combining matchers154292 +Ref: #combining-matchers154460 +Node: Match groups154962 +Ref: #match-groups155090 +Node: if table155858 +Ref: #if-table155980 +Node: balance-type157542 +Ref: #balance-type157671 +Node: include158371 +Ref: #include158498 +Node: Working with CSV158942 +Ref: #working-with-csv159089 +Node: Rapid feedback159496 +Ref: #rapid-feedback159629 +Node: Valid CSV160081 +Ref: #valid-csv160227 +Node: File Extension160959 +Ref: #file-extension161132 +Node: Reading CSV from standard input161696 +Ref: #reading-csv-from-standard-input161920 +Node: Reading multiple CSV files162084 +Ref: #reading-multiple-csv-files162315 +Node: Reading files specified by rule162556 +Ref: #reading-files-specified-by-rule162784 +Node: Valid transactions163955 +Ref: #valid-transactions164154 +Node: Deduplicating importing164782 +Ref: #deduplicating-importing164977 +Node: Setting amounts166013 +Ref: #setting-amounts166184 +Node: Amount signs168542 +Ref: #amount-signs168712 +Node: Setting currency/commodity169609 +Ref: #setting-currencycommodity169813 +Node: Amount decimal places170987 +Ref: #amount-decimal-places171193 +Node: Referencing other fields171505 +Ref: #referencing-other-fields171718 +Node: How CSV rules are evaluated172615 +Ref: #how-csv-rules-are-evaluated172832 +Node: Well factored rules174285 +Ref: #well-factored-rules174453 +Node: CSV rules examples174777 +Ref: #csv-rules-examples174912 +Node: Bank of Ireland174977 +Ref: #bank-of-ireland175114 +Node: Coinbase176576 +Ref: #coinbase176714 +Node: Amazon177761 +Ref: #amazon177886 +Node: Paypal179605 +Ref: #paypal179713 +Node: Timeclock187357 +Ref: #timeclock187462 +Node: Timedot189640 +Ref: #timedot189763 +Node: Timedot examples192884 +Ref: #timedot-examples192990 +Node: PART 3 REPORTING CONCEPTS195161 +Ref: #part-3-reporting-concepts195343 +Node: Amount formatting parseability195343 +Ref: #amount-formatting-parseability195540 +Node: Time periods197745 +Ref: #time-periods197884 +Node: Report start & end date198002 +Ref: #report-start-end-date198154 +Node: Smart dates199813 +Ref: #smart-dates199966 +Node: Report intervals201834 +Ref: #report-intervals201989 +Node: Date adjustment202407 +Ref: #date-adjustment202567 +Node: Period expressions203418 +Ref: #period-expressions203559 +Node: Period expressions with a report interval205323 +Ref: #period-expressions-with-a-report-interval205557 +Node: More complex report intervals205771 +Ref: #more-complex-report-intervals206016 +Node: Multiple weekday intervals207817 +Ref: #multiple-weekday-intervals208006 +Node: Depth208828 +Ref: #depth208930 +Node: Queries209226 +Ref: #queries209328 +Node: Query types210958 +Ref: #query-types211079 +Node: Combining query terms214313 +Ref: #combining-query-terms214490 +Node: Queries and command options215758 +Ref: #queries-and-command-options215957 +Node: Queries and valuation216206 +Ref: #queries-and-valuation216401 +Node: Querying with account aliases216630 +Ref: #querying-with-account-aliases216841 +Node: Querying with cost or value216971 +Ref: #querying-with-cost-or-value217148 +Node: Pivoting217449 +Ref: #pivoting217563 +Node: Generating data219340 +Ref: #generating-data219472 +Node: Forecasting221055 +Ref: #forecasting221180 +Node: --forecast221711 +Ref: #forecast221842 +Node: Inspecting forecast transactions222812 +Ref: #inspecting-forecast-transactions223014 +Node: Forecast reports224144 +Ref: #forecast-reports224317 +Node: Forecast tags225253 +Ref: #forecast-tags225413 +Node: Forecast period in detail225873 +Ref: #forecast-period-in-detail226067 +Node: Forecast troubleshooting226961 +Ref: #forecast-troubleshooting227129 +Node: Budgeting228032 +Ref: #budgeting228152 +Node: Cost reporting228589 +Ref: #cost-reporting228723 +Node: Recording costs229384 +Ref: #recording-costs229520 +Node: Reporting at cost231111 +Ref: #reporting-at-cost231286 +Node: Equity conversion postings231876 +Ref: #equity-conversion-postings232090 +Node: Inferring equity conversion postings234521 +Ref: #inferring-equity-conversion-postings234784 +Node: Combining costs and equity conversion postings235536 +Ref: #combining-costs-and-equity-conversion-postings235846 +Node: Requirements for detecting equity conversion postings236761 +Ref: #requirements-for-detecting-equity-conversion-postings237083 +Node: Infer cost and equity by default ?238283 +Ref: #infer-cost-and-equity-by-default238512 +Node: Value reporting238720 +Ref: #value-reporting238862 +Node: -V Value239636 +Ref: #v-value239768 +Node: -X Value in specified commodity239963 +Ref: #x-value-in-specified-commodity240164 +Node: Valuation date240313 +Ref: #valuation-date240490 +Node: Finding market price241273 +Ref: #finding-market-price241484 +Node: --infer-market-prices market prices from transactions242653 +Ref: #infer-market-prices-market-prices-from-transactions242935 +Node: Valuation commodity245697 +Ref: #valuation-commodity245916 +Node: Simple valuation examples247129 +Ref: #simple-valuation-examples247333 +Node: --value Flexible valuation247992 +Ref: #value-flexible-valuation248202 +Node: More valuation examples249846 +Ref: #more-valuation-examples250061 +Node: Interaction of valuation and queries251331 +Ref: #interaction-of-valuation-and-queries251578 +Node: Effect of valuation on reports252050 +Ref: #effect-of-valuation-on-reports252253 +Node: PART 4 COMMANDS259950 +Ref: #part-4-commands260099 +Node: Commands overview260478 +Ref: #commands-overview260612 +Node: DATA ENTRY260791 +Ref: #data-entry260915 +Node: DATA CREATION261114 +Ref: #data-creation261268 +Node: DATA MANAGEMENT261386 +Ref: #data-management261551 +Node: REPORTS FINANCIAL261672 +Ref: #reports-financial261847 +Node: REPORTS VERSATILE262152 +Ref: #reports-versatile262325 +Node: REPORTS BASIC262578 +Ref: #reports-basic262730 +Node: HELP263239 +Ref: #help263361 +Node: ADD-ONS263471 +Ref: #add-ons263577 +Node: accounts264156 +Ref: #accounts264289 +Node: activity266176 +Ref: #activity266295 +Node: add266669 +Ref: #add266779 +Node: aregister269765 +Ref: #aregister269886 +Node: aregister and posting dates272792 +Ref: #aregister-and-posting-dates272937 +Node: balance273693 +Ref: #balance273819 +Node: balance features274804 +Ref: #balance-features274944 +Node: Simple balance report276928 +Ref: #simple-balance-report277113 +Node: Balance report line format278738 +Ref: #balance-report-line-format278940 +Node: Filtered balance report281098 +Ref: #filtered-balance-report281290 +Node: List or tree mode281617 +Ref: #list-or-tree-mode281785 +Node: Depth limiting283130 +Ref: #depth-limiting283296 +Node: Dropping top-level accounts283897 +Ref: #dropping-top-level-accounts284097 +Node: Showing declared accounts284407 +Ref: #showing-declared-accounts284606 +Node: Sorting by amount285137 +Ref: #sorting-by-amount285304 +Node: Percentages285974 +Ref: #percentages286133 +Node: Multi-period balance report286681 +Ref: #multi-period-balance-report286881 +Node: Balance change end balance289138 +Ref: #balance-change-end-balance289347 +Node: Balance report types290775 +Ref: #balance-report-types290956 +Node: Calculation type291454 +Ref: #calculation-type291609 +Node: Accumulation type292158 +Ref: #accumulation-type292338 +Node: Valuation type293240 +Ref: #valuation-type293428 +Node: Combining balance report types294429 +Ref: #combining-balance-report-types294623 +Node: Budget report296461 +Ref: #budget-report296623 +Node: Using the budget report298766 +Ref: #using-the-budget-report298939 +Node: Budget date surprises301042 +Ref: #budget-date-surprises301242 +Node: Selecting budget goals302406 +Ref: #selecting-budget-goals302609 +Node: Budgeting vs forecasting303354 +Ref: #budgeting-vs-forecasting303531 +Node: Balance report layout304802 +Ref: #balance-report-layout304982 +Node: Useful balance reports313167 +Ref: #useful-balance-reports313327 +Node: balancesheet314412 +Ref: #balancesheet314557 +Node: balancesheetequity315887 +Ref: #balancesheetequity316045 +Node: cashflow317426 +Ref: #cashflow317557 +Node: check318995 +Ref: #check319109 +Node: Default checks319913 +Ref: #default-checks320039 +Node: Strict checks320536 +Ref: #strict-checks320681 +Node: Other checks321161 +Ref: #other-checks321303 +Node: Custom checks321836 +Ref: #custom-checks321993 +Node: More about specific checks322410 +Ref: #more-about-specific-checks322572 +Node: close323278 +Ref: #close323389 +Node: close --migrate324042 +Ref: #close---migrate324169 +Node: close --close325808 +Ref: #close---close325952 +Node: close --open326188 +Ref: #close---open326329 +Node: close --assert326439 +Ref: #close---assert326585 +Node: close --assign326806 +Ref: #close---assign326954 +Node: close --retain327480 +Ref: #close---retain327633 +Node: close customisation328378 +Ref: #close-customisation328557 +Node: close and balance assertions330024 +Ref: #close-and-balance-assertions330221 +Node: close examples331397 +Ref: #close-examples331538 +Node: Retain earnings331636 +Ref: #retain-earnings331795 +Node: Migrate balances to a new file332141 +Ref: #migrate-balances-to-a-new-file332367 +Node: More detailed close examples333495 +Ref: #more-detailed-close-examples333693 +Node: codes333719 +Ref: #codes333836 +Node: commodities334700 +Ref: #commodities334828 +Node: demo334898 +Ref: #demo335019 +Node: descriptions335935 +Ref: #descriptions336065 +Node: diff336356 +Ref: #diff336471 +Node: files337513 +Ref: #files337622 +Node: help337763 +Ref: #help-1337872 +Node: import339245 +Ref: #import339368 +Node: Deduplication340476 +Ref: #deduplication340601 +Node: Import testing342620 +Ref: #import-testing342785 +Node: Importing balance assignments343628 +Ref: #importing-balance-assignments343834 +Node: Commodity display styles344483 +Ref: #commodity-display-styles344656 +Node: incomestatement344785 +Ref: #incomestatement344927 +Node: notes346258 +Ref: #notes346380 +Node: payees346742 +Ref: #payees346857 +Node: prices347376 +Ref: #prices347491 +Node: print348144 +Ref: #print348259 +Node: print explicitness349235 +Ref: #print-explicitness349378 +Node: print amount style350157 +Ref: #print-amount-style350327 +Node: print parseability351397 +Ref: #print-parseability351569 +Node: print other features352318 +Ref: #print-other-features352497 +Node: print output format353018 +Ref: #print-output-format353166 +Node: register356305 +Ref: #register356427 +Node: Custom register output361458 +Ref: #custom-register-output361589 +Node: rewrite362936 +Ref: #rewrite363054 +Node: Re-write rules in a file364952 +Ref: #re-write-rules-in-a-file365115 +Node: Diff output format366264 +Ref: #diff-output-format366447 +Node: rewrite vs print --auto367539 +Ref: #rewrite-vs.-print---auto367699 +Node: roi368255 +Ref: #roi368362 +Node: Spaces and special characters in --inv and --pnl370174 +Ref: #spaces-and-special-characters-in---inv-and---pnl370414 +Node: Semantics of --inv and --pnl370902 +Ref: #semantics-of---inv-and---pnl371141 +Node: IRR and TWR explained372991 +Ref: #irr-and-twr-explained373151 +Node: stats376404 +Ref: #stats376512 +Node: tags377899 +Ref: #tags-1378006 +Node: test379015 +Ref: #test379108 +Node: PART 5 COMMON TASKS379850 +Ref: #part-5-common-tasks379996 +Node: Getting help380294 +Ref: #getting-help380435 +Node: Constructing command lines381195 +Ref: #constructing-command-lines381396 +Node: Starting a journal file382053 +Ref: #starting-a-journal-file382255 +Node: Setting LEDGER_FILE383457 +Ref: #setting-ledger_file383649 +Node: Setting opening balances384606 +Ref: #setting-opening-balances384807 +Node: Recording transactions387948 +Ref: #recording-transactions388137 +Node: Reconciling388693 +Ref: #reconciling388845 +Node: Reporting391102 +Ref: #reporting391251 +Node: Migrating to a new file395236 +Ref: #migrating-to-a-new-file395393 +Node: BUGS395692 +Ref: #bugs395782 +Node: Troubleshooting396661 +Ref: #troubleshooting396761  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 23a023d80..36d44c88e 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -97,30 +97,35 @@ Input Usually the data file is in hledger's journal format, but it can be in any of the supported file formats, which currently are: - Reader: Reads: Used for file extensions: + Reader: Reads: Automatically used for + files with extensions: ----------------------------------------------------------------------------- - journal hledger journal files and some .journal .j .hledger .ledger - Ledger journals, for transac- - tions - timeclock timeclock files, for precise .timeclock - time logging - timedot timedot files, for approximate .timedot - time logging - csv CSV/SSV/TSV/character-sepa- .csv .ssv .tsv .csv.rules - rated values, for data import .ssv.rules .tsv.rules + journal hledger journal files and some .journal .j .hledger + Ledger journals, for transactions .ledger + timeclock timeclock files, for precise time .timeclock + logging + timedot timedot files, for approximate .timedot + time logging + csv Comma or other character sepa- .csv + rated values, for data import + ssv Semicolon separated values .ssv + tsv Tab separated values .tsv + rules CSV/SSV/TSV/other separated val- .rules + ues, alternate way These formats are described in more detail below. - hledger detects the format automatically based on the file extensions - shown above. If it can't recognise the file extension, it assumes - journal format. So for non-journal files, it's important to use a + hledger detects the format automatically based on the file extensions + shown above. If it can't recognise the file extension, it assumes + journal format. So for non-journal files, it's important to use a recognised file extension, so as to either read successfully or to show relevant error messages. - You can also force a specific reader/format by prefixing the file path - with the format and a colon. Eg, to read a .dat file as csv format: + You can also force a specific reader/format by prefixing the file path + with the format and a colon. Eg, to read a .dat file containing tab + separated values: - $ hledger -f csv:/some/csv-file.dat stats + $ hledger -f tsv:/some/file.dat stats Standard input The file name - means standard input: @@ -1055,23 +1060,43 @@ Journal or reference number. 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. + After the date, status mark and/or code fields, the rest of the line + (or until a comment is begun with ;) is the transaction's description. + Here you can describe the transaction (called the "narration" in tradi- + tional bookkeeping), or you can record a payee/payer name, or you can + leave it empty. + + Transaction descriptions show up in print output and in register re- + ports, and can be listed with the descriptions command. + + You can query by description with desc:DESCREGEX, or pivot on descrip- + tion with --pivot desc. 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 (af- - ter the first |). This may be worthwhile if you need to do more pre- - cise querying and pivoting by payee or by note. + Sometimes people want a dedicated payee/payer field that can be queried + and checked more strictly. If you want that, you can write a | (pipe) + character in the description. This divides it into a "payee" field on + the left, and a "note" field on the right. (Either can be empty.) + + You can query these with payee:PAYEEREGEX and note:NOTEREGEX, list + their values with the payees and notes commands, or pivot on payee or + note. + + Note: in transactions with no | character, description, payee, and note + all have the same value. Once a | is added, they become distinct. (If + you'd like to change this behaviour, please propose it on the mail + list.) + + If you want more strict error checking, you can declare the valid payee + names with payee directives, and then enforce these with hledger check + payees. Note: because of the above, for this you'll need to ensure + every transaction description contains a | and therefore a checkable + payee name (even if it's empty). Transaction comments - Text following ;, after a transaction description, and/or on indented - lines immediately below it, form comments for that transaction. They - are reproduced by print but otherwise ignored, except they may contain + Text following ;, after a transaction description, and/or on indented + lines immediately below it, form comments for that transaction. They + are reproduced by print but otherwise ignored, except they may contain tags, which are not ignored. 2012-01-01 something ; a transaction comment @@ -1080,43 +1105,43 @@ Journal assets 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 + 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 + 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 + 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 + 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 - spaces. But if you accidentally leave only one space (or tab) before + Be sure to note the unusual two-space delimiter between account name + and amount. This makes it easy to write account names containing + spaces. But if you accidentally leave only one space (or tab) before the amount, the amount will be considered part of the account name. Account names - Accounts are the main way of categorising things in hledger. As in - Double Entry Bookkeeping, they can represent real world accounts (such + Accounts are the main way of categorising things in hledger. As in + Double Entry Bookkeeping, they can represent real world accounts (such as a bank account), or more abstract categories such as "money borrowed from Frank" or "money spent on electricity". - You can use any account names you like, but we usually start with the + You can use any account names you like, but we usually start with the traditional accounting categories, which in english are assets, liabil- ities, equity, revenues, expenses. (You might see these referred to as A, L, E, R, X for short.) - For more precise reporting, we usually divide the top level accounts + For more precise reporting, we usually divide the top level accounts into more detailed subaccounts, by writing a full colon between account - name parts. For example, from the account names assets:bank:checking + name parts. For example, from the account names assets:bank:checking and expenses:food, hledger will infer this hierarchy of five accounts: assets @@ -1134,33 +1159,33 @@ Journal food hledger reports can summarise the account tree to any depth, so you can - go as deep as you like with subcategories, but keeping your account + go as deep as you like with subcategories, but keeping your account names relatively simple may be best when starting out. Account names may be capitalised or not; they may contain letters, num- - bers, symbols, or single spaces. Note, when an account name and an - amount are written on the same line, they must be separated by two or + bers, symbols, or single spaces. Note, when an account name and an + amount are written on the same line, they must be separated by two or more spaces (or tabs). - Parentheses or brackets enclosing the full account name indicate vir- - tual postings, described below. Parentheses or brackets internal to + Parentheses or brackets enclosing the full account name indicate vir- + tual postings, described below. Parentheses or brackets internal to the account name have no special meaning. - Account names can be altered temporarily or permanently by account + Account names can be altered temporarily or permanently by account aliases. Amounts - After the account name, there is usually an amount. (Important: be- + After the account name, there is usually an amount. (Important: be- tween 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- + 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 symbol or commodity name (more on this below), - to the left or right of the quantity, with or without a separating + to the left or right of the quantity, with or without a separating space: $1 @@ -1168,13 +1193,13 @@ Journal 3 "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- + 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 + One or more spaces between the sign and the number are acceptable when parsing (but they won't be displayed in output): + $1 @@ -1191,8 +1216,8 @@ Journal 1.23 1,23 - 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, + 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 @@ -1200,40 +1225,40 @@ Journal INR 9,99,99,999.00 1 000 000.9455 - hledger is not biased towards period or comma decimal marks, so a num- - ber containing just one period or comma, like 1,000 or 1.000, is am- - biguous. In such cases hledger assumes it is a decimal mark, parsing + hledger is not biased towards period or comma decimal marks, so a num- + ber containing just one period or comma, like 1,000 or 1.000, is am- + biguous. In such cases hledger assumes it is a decimal mark, parsing both of these as 1. To disambiguate these and ensure accurate number parsing, especially if - you use digit group marks, we recommend declaring the decimal mark. - You can declare it for each file with decimal-mark directives, or for + you use digit group marks, we recommend declaring the decimal mark. + You can declare it for each file with decimal-mark directives, or for each commodity with commodity directives (described below). Commodity - Amounts in hledger have both a "quantity", which is a signed decimal + Amounts in hledger have both a "quantity", which is a signed decimal number, and a "commodity", which is a currency symbol, stock ticker, or any word or phrase describing something you are tracking. If the commodity name contains non-letters (spaces, numbers, or punctu- - ation), you must always write it inside double quotes ("green apples", + ation), you must always write it inside double quotes ("green apples", "ABC123"). - If you write just a bare number, that too will have a commodity, with + If you write just a bare number, that too will have a commodity, with name ""; we call that the "no-symbol commodity". - Actually, hledger combines these single-commodity amounts into more - powerful multi-commodity amounts, which are what it works with most of - the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 - TSLA. In practice, you will only see multi-commodity amounts in + Actually, hledger combines these single-commodity amounts into more + powerful multi-commodity amounts, which are what it works with most of + the time. A multi-commodity amount could be, eg: 1 USD, 2 EUR, 3.456 + TSLA. In practice, you will only see multi-commodity amounts in hledger's output; you can't write them directly in the journal file. - (If you are writing scripts or working with hledger's internals, these + (If you are writing scripts or working with hledger's internals, these are the Amount and MixedAmount types.) Directives influencing number parsing and display - You can add decimal-mark and commodity directives to the journal, to - declare and control these things more explicitly and precisely. These + You can add decimal-mark and commodity directives to the journal, to + declare and control these things more explicitly and precisely. These are described below, but here's a quick example: # the decimal mark character used by all amounts in this file (all commodities) @@ -1247,22 +1272,22 @@ Journal Commodity display style For the amounts in each commodity, hledger chooses a consistent display - style (symbol placement, decimal mark and digit group marks, number of + style (symbol placement, decimal mark and digit group marks, number of decimal digits) to use in most reports. This is inferred as follows: - First, if there's a D directive declaring a default commodity, that - commodity symbol and amount format is applied to all no-symbol amounts + First, if there's a D directive declaring a default commodity, that + commodity symbol and amount format is applied to all no-symbol amounts in the journal. - Then each commodity's display style is determined from its commodity - directive. We recommend always declaring commodities with commodity + Then each commodity's display style is determined from its commodity + directive. We recommend always declaring commodities with commodity directives, since they help ensure consistent display styles and preci- - sions, and bring other benefits such as error checking for commodity + sions, and bring other benefits such as error checking for commodity symbols. - But if a commodity directive is not present, hledger infers a commod- - ity's display styles from its amounts as they are written in the jour- - nal (excluding cost amounts and amounts in periodic transaction rules + But if a commodity directive is not present, hledger infers a commod- + ity's display styles from its amounts as they are written in the jour- + nal (excluding cost amounts and amounts in periodic transaction rules or auto posting rules). It uses o the symbol placement and decimal mark of the first amount seen @@ -1271,7 +1296,7 @@ Journal o and the maximum number of decimal digits seen across all amounts. - And as fallback if no applicable amounts are found, it would use a de- + And as fallback if no applicable amounts are found, it would use a de- fault style, like $1000.00 (symbol on the left with no space, period as decimal mark, and two decimal digits). @@ -1280,38 +1305,38 @@ Journal Rounding Amounts are stored internally as decimal numbers with up to 255 decimal - places. They are displayed with their original journal precisions by - print and print-like reports, and rounded to their display precision + places. They are displayed with their original journal precisions by + print and print-like reports, and rounded to their display precision (the number of decimal digits specified by the commodity display style) - by other reports. When rounding, hledger uses banker's rounding (it + by other reports. When rounding, hledger uses banker's rounding (it rounds to the nearest even digit). So eg 0.5 displayed with zero deci- mal digits appears as "0". Number format - hledger will occasionally make some additional adjustments to number - formatting, eg adding a trailing decimal mark to disambiguate numbers - with digit group marks; for details, see Amount formatting, parseabil- + hledger will occasionally make some additional adjustments to number + formatting, eg adding a trailing decimal mark to disambiguate numbers + with digit group marks; for details, see Amount formatting, parseabil- ity. Costs - After a posting amount, you can note its cost (when buying) or selling - price (when selling) in another commodity, by writing either @ UNIT- - PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- + After a posting amount, you can note its cost (when buying) or selling + price (when selling) in another commodity, by writing either @ UNIT- + PRICE or @@ TOTALPRICE after it. This indicates a conversion transac- tion, where one commodity is exchanged for another. - (You might also see this called "transaction price" in hledger docs, - discussions, or code; that term was directionally neutral and reminded - that it is a price specific to a transaction, but we now just call it + (You might also see this called "transaction price" in hledger docs, + discussions, or code; that term was directionally neutral and reminded + that it is a price specific to a transaction, but we now just call it "cost", with the understanding that the transaction could be a purchase or a sale.) - Costs are usually written explicitly with @ or @@, but can also be in- + Costs are usually written explicitly with @ or @@, but can also be in- ferred automatically for simple multi-commodity transactions. Note, if - costs are inferred, the order of postings is significant; the first + costs are inferred, the order of postings is significant; the first posting will have a cost attached, in the commodity of the second. - As an example, here are several ways to record purchases of a foreign - currency in hledger, using the cost notation either explicitly or im- + As an example, here are several ways to record purchases of a foreign + currency in hledger, using the cost notation either explicitly or im- plicitly: 1. Write the price per unit, as @ UNITPRICE after the amount: @@ -1335,30 +1360,30 @@ Journal assets:euros 100 ; one hundred euros purchased assets:dollars $-135 ; for $135 - Amounts can be converted to cost at report time using the -B/--cost + Amounts can be converted to cost at report time using the -B/--cost flag; this is discussed more in the Cost reporting section. - Note that the cost normally should be a positive amount, though it's - not required to be. This can be a little confusing, see discussion at + Note that the cost normally should be a positive amount, though it's + not required to be. This can be a little confusing, see discussion at --infer-market-prices: market prices from transactions. Other cost/lot notations - A slight digression for Ledger and Beancount users. Ledger has a num- + A slight digression for Ledger and Beancount users. Ledger has a num- ber of cost/lot-related notations: o @ UNITCOST and @@ TOTALCOST o expresses a conversion rate, as in hledger - o when buying, also creates a lot than can be selected at selling + o when buying, also creates a lot than can be selected at selling time o (@) UNITCOST and (@@) TOTALCOST (virtual cost) - o like the above, but also means "this cost was exceptional, don't + o like the above, but also means "this cost was exceptional, don't use it when inferring market prices". - Currently, hledger treats the above like @ and @@; the parentheses are + Currently, hledger treats the above like @ and @@; the parentheses are ignored. o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price) @@ -1368,10 +1393,10 @@ Journal o {UNITCOST} and {{TOTALCOST}} (lot price) - o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- + o can be used identically to @ UNITCOST and @@ TOTALCOST, also cre- ates a lot - o when selling, combined with @ ..., specifies an investment lot by + o when selling, combined with @ ..., specifies an investment lot by its cost basis; does not check if that lot is present o and related: [YYYY/MM/DD] (lot date) @@ -1386,7 +1411,7 @@ Journal o when selling, selects a lot by its note - Currently, hledger accepts any or all of the above in any order after + Currently, hledger accepts any or all of the above in any order after the posting amount, but ignores them. (This can break transaction bal- ancing.) @@ -1397,12 +1422,12 @@ Journal o expresses a cost without creating a lot, as in hledger o when buying (augmenting) or selling (reducing) a lot, combined with - {...}: documents the cost/selling price (not used for transaction + {...}: documents the cost/selling price (not used for transaction balancing) o {UNITCOST} and {{TOTALCOST}} - o when buying (augmenting), expresses the cost for transaction bal- + o when buying (augmenting), expresses the cost for transaction bal- ancing, and also creates a lot with this cost basis attached o when selling (reducing), @@ -1414,18 +1439,18 @@ Journal o expresses the selling price for transaction balancing - Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but + Currently, hledger accepts the {UNITCOST}/{{TOTALCOST}} notation but ignores it. - o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- + o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"}, {UNIT- COST, YYYY-MM-DD, "LABEL"} etc. Currently, hledger rejects these. 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 + 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 @@ -1437,59 +1462,59 @@ Journal 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 + 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 + for reading Ledger files. (Note: this flag currently does not disable balance assignments, described 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- + 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- + 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 differ- - ently-dated transactions within the journal. But if you reorder + So, hledger balance assertions keep working if you reorder differ- + ently-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 con- + updating. This order dependence does bring an advantage: precise con- trol over the order of postings and assertions within a day, so you can assert intra-day balances. Assertions and multiple included files - Multiple files included with the include directive are processed as if - concatenated into one file, preserving their order and the posting or- - der within each file. It means that balance assertions in later files + Multiple files included with the include directive are processed as if + concatenated into one file, preserving their order and the posting or- + der within each file. It means that balance assertions in later files will see balance from earlier files. - And if you have multiple postings to an account on the same day, split - across multiple files, and you want to assert the account's balance on + And if you have multiple postings to an account on the same day, split + across multiple files, and you want to assert the account's balance on that day, you'll need to put the assertion in the right file - the last one in the sequence, probably. Assertions and multiple -f files - Unlike include, when multiple files are specified on the command line - with multiple -f/--file options, balance assertions will not see bal- + Unlike include, when multiple files are specified on the command line + with multiple -f/--file options, balance assertions will not see bal- ance from earlier files. This can be useful when you do not want prob- lems in earlier files to disrupt valid assertions in later files. - If you do want assertions to see balance from earlier files, use in- + If you do want assertions to see balance from earlier files, use in- clude, or concatenate the files temporarily. 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 + 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 + You can make a stronger "total" balance assertion by writing a double equals sign (== EXPECTEDBALANCE). This asserts that there are no other - commodities in the account besides the asserted one (or at least, that + commodities in the account besides the asserted one (or at least, that their balance is 0). 2013/1/1 @@ -1508,7 +1533,7 @@ Journal 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 + has multiple commodities. One workaround is to isolate each commodity into its own subaccount: 2013/1/1 @@ -1528,15 +1553,15 @@ Journal 2019/1/1 (a) $1 @ 1 = $1 - We do allow costs to be written in balance assertion amounts, however, - and print shows them, but 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 costs), and because + We do allow costs to be written in balance assertion amounts, however, + and print shows them, but 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 costs), and because balance assignments do use costs (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 + 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 @@ -1550,10 +1575,10 @@ Journal are not affected by the --real/-R flag or real: query. Assertions and auto postings - Balance assertions are affected by the --auto flag, which generates + Balance assertions are affected by the --auto flag, which generates auto postings, which can alter account balances. Because auto postings are optional in hledger, accounts affected by them effectively have two - balances. But balance assertions can only test one or the other of + balances. But balance assertions can only test one or the other of these. So to avoid making fragile assertions, either: o assert the balance calculated with --auto, and always use --auto with @@ -1566,15 +1591,15 @@ Journal avoid auto postings entirely). 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- + 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. Posting comments - Text following ;, at the end of a posting line, and/or on indented - lines immediately below it, form comments for that posting. They are - reproduced by print but otherwise ignored, except they may contain + Text following ;, at the end of a posting line, and/or on indented + lines immediately below it, form comments for that posting. They are + reproduced by print but otherwise ignored, except they may contain tags, which are not ignored. 2012-01-01 @@ -1584,17 +1609,20 @@ Journal ; a second comment line for posting 2 Tags - Tags are a way to add extra labels or labelled data to transactions, + Tags are a way to add extra labels or data fields to transactions, postings, or accounts, which you can then search or pivot on. - They are written as a word (optionally hyphenated) immediately followed - by a full colon, in a transaction or posting or account directive's - comment. (This is an exception to the usual rule that things in com- - ments are ignored.) You can write multiple tags separated by comma, - and/or you can add more comment lines and write more tags there. + A tag is a word, optionally hyphenated, immediately followed by a full + colon, in the comment of a transaction, a posting, or an account direc- + tive. Eg: 2024-01-01 a transaction ; foo: Note this is an exception + to the usual rule that things in comments are ignored. - Here five different tags are recorded: one on the checking account, two - on the transaction, and two on the expenses posting: + You can write multiple tags on one line, separated by comma. Or you + can write each tag on its own comment line (no comma needed in this + case). + + For example, here are five different tags: one on the assets:checking + account, two on the transaction, and two on the expenses:food posting: account assets:checking ; accounttag: @@ -1603,10 +1631,6 @@ Journal assets:checking $-1 expenses:food $1 ; postingtag:, another-posting-tag: - You can list tag names with hledger tags [NAMEREGEX], or match by tag - name with a tag:NAMEREGEX query. - - Tag inheritance Postings also inherit tags from their transaction and their account. And transactions also acquire tags from their postings (and postings' accounts). So in the example above, the expenses posting effectively @@ -1615,57 +1639,69 @@ Journal posting). Tag names - Tag names are currently not very clearly specified; any sequence of - non-whitespace characters followed by a colon may work. + Most non-whitespace characters are allowed in tag names. Eg : is a + valid tag. - The following tag names are generated by hledger or have special sig- - nificance to hledger, so you may want to avoid using them yourself: + You can list the tag names used in your journal with the tags command: + hledger tags [NAMEREGEX] - o balances -- a balance assertions transaction generated by close + In commands which use a query, you can match by tag name. Eg: + hledger print tag:NAMEREGEX - o retain -- a retain earnings transaction generated by close + You can declare valid tag names with the tag directive and then check + them with the check command. - o start -- a opening balances, closing balances or balance assignment - transaction generated by close + Special tags + Some tag names have special significance to hledger. There's not much + harm in using them yourself, but some could produce an error message, + particularly the date: tag. They are explained elsewhere, but here is + a quick list for reference: - o generated-transaction -- a transaction generated by --forecast + Tags you can set to influence hledger's behaviour: - o generated-posting -- a posting generated by --auto + date -- overrides a posting's date + date2 -- overrides a posting's secondary date + type -- declares an account's type - o modified -- a transaction which has had postings added by --auto + Tags hledger adds to indicate generated data: - o type -- declares an account's type in an account declaration + t -- appears on postings generated by timedot letters + assert -- appears on txns generated by close --assert + retain -- appears on txns generated by close --retain + start -- appears on txns generated by close --migrate/--close/--open/--assign + generated-transaction -- appears on generated periodic txns (with --verbose-tags) + generated-posting -- appears on generated auto postings (with --verbose-tags) + modified -- appears on txns which have had auto postings added (with --verbose-tags) + Not displayed, but queryable: + _generated-transaction -- exists on generated periodic txns (always) + _generated-posting -- exists on generated auto postings (always) + _modified -- exists on txns which have had auto postings added (always) - o t -- stores the (user defined, single letter) type of a 15m unit of - time parsed from timedot format + Tags hledger uses internally: - Some additional tag names with an underscore prefix are used internally - and not displayed in reports (but can be matched by queries): - - o _generated-transaction - - o _generated-posting - - o _modified - - o _conversion-matched + _conversion-matched -- exists on postings which have been matched with a nearby @/@@ cost annotation Tag values - Tags can have a value, which is any text after the colon up until a - comma or end of line (with surrounding whitespace removed). Note this - means that hledger tag values can not contain commas. Eg in the fol- - lowing posting, the three tags' values are "value 1", "value 2", and "" - (empty) respectively: + Tags can have a value, which is any text after the colon up until a + comma or end of line, with surrounding whitespace removed. Ending at + comma allows us to write multiple tags on one line, but also means that + tag values can not contain commas. + + Eg in the following posting, the three tags' values are "value 1", + "value 2", and "" (empty) respectively: expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz - Note that tags can be repeated, and are additive rather than overrid- - ing: when the same tag name is seen again with a new value, the new - name:value pair is added to the tags. (It is not possible to override - a tag's value or remove a tag.) + Multiple tags with the same name are additive rather than overriding: + when the same tag name is seen again with a new value, the new + name:value pair is added to the tags. It is not possible to override a + previous tag's value or remove a tag. - You can list a tag's values with hledger tags TAGNAME --values, or - match by tag value with a tag:NAMEREGEX=VALUEREGEX query. + You can list all the values used for a particular tag in the journal + with + hledger tags TAGNAME --values + + You can match on tag values with a query like tag:NAMEREGEX=VALUEREGEX Directives Besides transactions, there is something else you can put in a journal @@ -1775,53 +1811,45 @@ Journal o They can document your intended chart of accounts, providing a refer- ence. - o In strict mode, they restrict which accounts may be posted to by - transactions, which helps detect typos. + o They can store additional account information as comments, or as tags + which can be used to filter or pivot reports. - o They control account display order in reports, allowing non-alpha- + o They can restrict which accounts may be posted to by transactions, eg + in strict mode, which helps prevent errors. + + o They influence account display order in reports, allowing non-alpha- betic sorting (eg Revenues to appear above Expenses). + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), enabling reports like balancesheet and in- + comestatement. + o They help with account name completion (in hledger add, hledger-web, hledger-iadd, ledger-mode, etc.) - o They can store additional account information as comments, or as tags - which can be used to filter or pivot reports. - - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), affecting reports like balancesheet and - incomestatement. - They are written as the word account followed by a hledger-style ac- - count name, eg: + count name. Eg: account assets:bank:checking - Note, however, that accounts declared in account directives are not al- - lowed to have surrounding brackets and parentheses, unlike accounts - used in postings. So the following journal will not parse: + Ledger-style indented subdirectives are also accepted, but ignored: - account (assets:bank:checking) + account assets:bank:checking + format subdirective ; currently ignored Account comments Text following two or more spaces and ; at the end of an account direc- - tive line, and/or following ; on indented lines immediately below it, - form comments for that account. They are ignored except they may con- + tive line, and/or following ; on indented lines immediately below it, + form comments for that account. They are ignored except they may con- tain tags, which are not ignored. - The two-space requirement for same-line account comments is because ; + The two-space requirement for same-line account comments is because ; is allowed in account names. account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon ; next-line comment ; some tags - type:A, acctnum:12345 - Account subdirectives - Ledger-style indented subdirectives are also accepted, but currently - ignored: - - account assets:bank:checking - format subdirective is ignored - Account error checking By default, accounts need not be declared; they come into existence when a posting references them. This is convenient, but it means @@ -1849,10 +1877,9 @@ Journal with a wildcard; every account posted to must be declared. Account display order - The order in which account directives are written influences the order - in which accounts appear in reports, hledger-ui, hledger-web etc. By - default accounts appear in alphabetical order, but if you add these ac- - count directives to the journal file: + Account directives also cause hledger to display accounts in a particu- + lar order, not just alphabetically. Eg, here is a conventional order- + ing for the top-level accounts: account assets account liabilities @@ -1860,31 +1887,31 @@ Journal account revenues account expenses - those accounts will be displayed in declaration order: + Now hledger displays them in that order: - $ hledger accounts -1 + $ hledger accounts assets liabilities equity revenues expenses - Any undeclared accounts are displayed last, in alphabetical order. + If there are undeclared accounts, those will be displayed last, in al- + phabetical order. - Sorting is done at each level of the account tree, within each group of - sibling accounts under the same parent. And currently, this directive: + Sorting is done within each group of sibling accounts, at each level of + the account tree. Eg, a declaration like account parent:child influ- + ences child's position among its siblings. - account other:zoo + Note, it does not affect parent's position; for that, you need an ac- + count parent declaration. - would influence the position of zoo among other's subaccounts, but not - the position of other among the top-level accounts. This means: + Sibling accounts are always displayed together; hledger won't display + x:y in between a:b and a:c. - o you will sometimes declare parent accounts (eg account other above) - that you don't intend to post to, just to customize their display or- - der - - o sibling accounts stay together (you couldn't display x:y in between - a:b and a:c). + An account directive both declares an account as a valid posting tar- + get, and declares its display order; you can't easily do one without + the other. Account types hledger knows that accounts come in several types: assets, liabilities, @@ -1893,19 +1920,18 @@ Journal As a convenience, hledger will detect these account types automatically if you are using common english-language top-level account names (de- - scribed below). But generally we recommend you declare types explic- - itly, by adding a type: tag to your top-level account directives. Sub- - accounts will inherit the type of their parent. The tag's value should - be one of the five main account types: + scribed below). But it's more robust to declare accounts' types ex- + plicitly, by adding type: tags to their account directives. The tag's + value should be one of the five main account types: o A or Asset (things you own) o L or Liability (things you owe) - o E or Equity (investment/ownership; balanced counterpart of assets & + o E or Equity (investment/ownership; balanced counterpart of assets & liabilities) - o R or Revenue (what you received money from, AKA income; technically + o R or Revenue (what you received money from, AKA income; technically part of Equity) o X or Expense (what you spend money on; technically part of Equity) @@ -1915,10 +1941,11 @@ Journal o C or Cash (a subtype of Asset, indicating liquid assets for the cash- flow report) - o V or Conversion (a subtype of Equity, for conversions (see Cost re- + o V or Conversion (a subtype of Equity, for conversions (see Cost re- porting).) - Here is a typical set of account type declarations: + Subaccounts inherit their parent's type, or they can override it. Here + is a typical set of account type declarations: account assets ; type: A account liabilities ; type: L @@ -1933,7 +1960,7 @@ Journal Here are some tips for working with account types. - o The rules for inferring types from account names are as follows. + o The rules for inferring types from account names are as follows. These are just a convenience that sometimes help new users get going; if they don't work for you, just ignore them and declare your account types. See also Regular expressions. @@ -1948,25 +1975,25 @@ Journal ^(income|revenue)s?(:|$) | Revenue ^expenses?(:|$) | Expense - o If you declare any account types, it's a good idea to declare an ac- + o If you declare any account types, it's a good idea to declare an ac- count for all of the account types, because a mixture of declared and name-inferred types can disrupt certain reports. - o Certain uses of account aliases can disrupt account types. See + o Certain uses of account aliases can disrupt account types. See Rewriting accounts > Aliases and account types. o As mentioned above, subaccounts will inherit a type from their parent - account. More precisely, an account's type is decided by the first + account. More precisely, an account's type is decided by the first of these that exists: 1. A type: declaration for this account. - 2. A type: declaration in the parent accounts above it, preferring + 2. A type: declaration in the parent accounts above it, preferring the nearest. 3. An account type inferred from this account's name. - 4. An account type inferred from a parent account's name, preferring + 4. An account type inferred from a parent account's name, preferring the nearest parent. 5. Otherwise, it will have no type. @@ -1992,7 +2019,7 @@ Journal o customising reports Account aliases also rewrite account names in account directives. They - do not affect account names being entered via hledger add or + do not affect account names being entered via hledger add or hledger-web. Account aliases are very powerful. They are generally easy to use cor- @@ -2002,9 +2029,9 @@ Journal 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 (but note: not sibling or parent files). The spaces + 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 (but note: not sibling or parent files). The spaces around the = are optional: alias OLD = NEW @@ -2012,17 +2039,17 @@ Journal 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 re- - place any occurrence of the old account name with the new one. Subac- + OLD and NEW are case sensitive full account names. hledger will re- + place any occurrence of the old account name with the new one. Subac- counts 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 wrapping the pattern in forward slashes. (This is the - only place where hledger requires forward slashes around a regular ex- + There is also a more powerful variant that uses a regular expression, + indicated by wrapping the pattern in forward slashes. (This is the + only place where hledger requires forward slashes around a regular ex- pression.) Eg: @@ -2033,13 +2060,13 @@ Journal $ hledger --alias '/REGEX/=REPLACEMENT' ... - Any part of an account name matched by REGEX will be replaced by RE- + Any part of an account name matched by REGEX will be replaced by RE- PLACEMENT. REGEX is case-insensitive as usual. - If you need to match a forward slash, escape it with a backslash, eg + If you need to match a forward slash, escape it with a backslash, eg /\/=:. - If REGEX contains parenthesised match groups, these can be referenced + If REGEX contains parenthesised match groups, these can be referenced by the usual backslash and number in REPLACEMENT: alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3 @@ -2049,21 +2076,21 @@ Journal option argument), so it can contain trailing whitespace. Combining aliases - You can define as many aliases as you like, using journal directives + 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 + 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 + 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 + 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 + 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: @@ -2074,20 +2101,20 @@ Journal 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- + 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 + 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 + 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. In- + account aliases defined in a.aliases will not affect b.journal. In- cluding the aliases doesn't work either: include a.aliases @@ -2115,7 +2142,7 @@ Journal end aliases Aliases can generate bad account names - Be aware that account aliases can produce malformed account names, + Be aware that account aliases can produce malformed account names, which could cause confusing reports or invalid print output. For exam- ple, you could erase all account names: @@ -2127,8 +2154,8 @@ Journal 2021-01-01 1 - The above print output is not a valid journal. Or you could insert an - illegal double space, causing print output that would give a different + The above print output is not a valid journal. Or you could insert an + illegal double space, causing print output that would give a different journal when reparsed: 2021-01-01 @@ -2145,15 +2172,15 @@ Journal types) is renamed by an alias, normally the account type remains in ef- fect. - However, renaming in a way that reshapes the account tree (eg renaming - parent accounts but not their children, or vice versa) could prevent + However, renaming in a way that reshapes the account tree (eg renaming + parent accounts but not their children, or vice versa) could prevent child accounts from inheriting the account type of their parents. - Secondly, if an account's type is being inferred from its name, renam- + Secondly, if an account's type is being inferred from its name, renam- ing it by an alias could prevent or alter that. - If you are using account aliases and the type: query is not matching - accounts as you expect, try troubleshooting with the accounts command, + If you are using account aliases and the type: query is not matching + accounts as you expect, try troubleshooting with the accounts command, eg something like: $ hledger accounts --alias assets=bassetts type:a @@ -2161,31 +2188,31 @@ Journal commodity directive The commodity directive performs several functions: - 1. It declares which commodity symbols may be used in the journal, en- - abling useful error checking with strict mode or the check command. + 1. It declares which commodity symbols may be used in the journal, en- + abling useful error checking with strict mode or the check command. (See Commodity error checking below.) 2. It declares the precision with which this commodity's amounts should be compared when checking for balanced transactions. - 3. It declares how this commodity's amounts should be displayed, eg - their symbol placement, digit group mark if any, digit group sizes, - decimal mark (period or comma), and the number of decimal places. + 3. It declares how this commodity's amounts should be displayed, eg + their symbol placement, digit group mark if any, digit group sizes, + decimal mark (period or comma), and the number of decimal places. (See Commodity display style above.) - 4. It sets which decimal mark (period or comma) to expect when parsing - subsequent amounts in this commodity (if there is no decimal-mark - directive in effect. See Decimal marks, digit group marks above. + 4. It sets which decimal mark (period or comma) to expect when parsing + subsequent amounts in this commodity (if there is no decimal-mark + directive in effect. See Decimal marks, digit group marks above. For related dev discussion, see #793.) - Declaring commodities solves several common parsing/display problems, - so we recommend it. Generally you should put commodity directives at - the top of your journal file (because function 4 is position-sensi- + Declaring commodities solves several common parsing/display problems, + so we recommend it. Generally you should put commodity directives at + the top of your journal file (because function 4 is position-sensi- tive). Commodity directive syntax A commodity directive is normally the word commodity followed by a sam- - ple amount (and optionally a comment). Only the amount's symbol and + ple amount (and optionally a comment). Only the amount's symbol and format is significant. Eg: commodity $1000.00 @@ -2194,19 +2221,19 @@ Journal Commodities do not have tags (tags in the comment will be ignored). - A commodity directive's sample amount must always include a period or - comma decimal mark (this rule helps disambiguate decimal marks and - digit group marks). If you don't want to show any decimal digits, + A commodity directive's sample amount must always include a period or + comma decimal mark (this rule helps disambiguate decimal marks and + digit group marks). If you don't want to show any decimal digits, write the decimal mark at the end: commodity 1000. AAAA ; show AAAA with no decimals - Commodity symbols containing spaces, numbers, or punctuation must be + Commodity symbols containing spaces, numbers, or punctuation must be enclosed in double quotes, as usual: commodity 1.0000 "AAAA 2023" - Commodity directives normally include a sample amount, but can declare + Commodity directives normally include a sample amount, but can declare only a symbol (ie, just function 1 above): commodity $ @@ -2215,7 +2242,7 @@ Journal commodity "" ; the no-symbol commodity Commodity directives may also be written with an indented format subdi- - rective, as in Ledger. The symbol is repeated and must be the same in + rective, as in Ledger. The symbol is repeated and must be the same in both places. Other subdirectives are currently ignored: ; display indian rupees with currency name on the left, @@ -2226,10 +2253,10 @@ Journal an unsupported subdirective ; ignored by hledger Commodity error checking - In strict mode (-s/--strict) (or when you run hledger check commodi- - ties), hledger will report an error if an undeclared commodity symbol - is used. (With one exception: zero amounts are always allowed to have - no commodity symbol.) It works like account error checking (described + In strict mode (-s/--strict) (or when you run hledger check commodi- + ties), hledger will report an error if an undeclared commodity symbol + is used. (With one exception: zero amounts are always allowed to have + no commodity symbol.) It works like account error checking (described above). decimal-mark directive @@ -2243,20 +2270,20 @@ Journal decimal-mark , - This prevents any ambiguity when parsing numbers in the file, so we - recommend it, especially if the file contains digit group marks (eg + This prevents any ambiguity when parsing numbers in the file, so we + recommend it, especially if the file contains digit group marks (eg thousands separators). include directive - You can pull in the content of additional files by writing an include + 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 + 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 + 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. @@ -2265,27 +2292,27 @@ Journal *.journal. There is limited support for recursive wildcards: **/ (the slash is re- - quired) matches 0 or more subdirectories. It's not super convenient - since you have to avoid include cycles and including directories, but + quired) 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 Data formats): include time- + ing the file extension (as described in Data formats): include time- dot:~/notes/2023*.md. P directive The P directive declares a market price, which is a conversion rate be- - tween two commodities on a certain date. This allows value reports to + tween two commodities on a certain date. This allows value reports to convert amounts of one commodity to their value in another, on or after - that date. These prices are often obtained from a stock exchange, + that date. These prices are often obtained from a stock exchange, cryptocurrency exchange, the or foreign exchange market. The format is: P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT - DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity - being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity) + DATE is a simple date, COMMODITY1SYMBOL is the symbol of the commodity + being priced, and COMMODITY2AMOUNT is the amount (symbol and quantity) of commodity 2 that one unit of commodity 1 is worth on this date. Ex- amples: @@ -2295,15 +2322,15 @@ Journal # and $1.40 from 2010-01-01 onward: P 2010-01-01 $1.40 - The -V, -X and --value flags use these market prices to show amount + The -V, -X and --value flags use these market prices to show amount values in another commodity. See Value reporting. payee directive payee PAYEE NAME This directive can be used to declare a limited set of payees which may - appear in transaction descriptions. The "payees" check will report an - error if any transaction refers to a payee that has not been declared. + appear in transaction descriptions. The "payees" check will report an + error if any transaction refers to a payee that has not been declared. Eg: payee Whole Foods ; a comment @@ -2319,17 +2346,17 @@ Journal tag directive tag TAGNAME - This directive can be used to declare a limited set of tag names al- + This directive can be used to declare a limited set of tag names al- lowed in tags. TAGNAME should be a valid tag name (no spaces). Eg: tag item-id Any indented subdirectives are currently ignored. - The "tags" check will report an error if any undeclared tag name is + The "tags" check will report an error if any undeclared tag name is used. It is quite easy to accidentally create a tag through normal use - of colons in comments(#comments]; if you want to prevent this, you can - declare and check your tags . + of colons in comments; if you want to prevent this, you can declare and + check your tags . Periodic transactions The ~ directive declares a "periodic rule" which generates temporary @@ -8930,4 +8957,4 @@ LICENSE SEE ALSO hledger(1), hledger-ui(1), hledger-web(1), ledger(1) -hledger-1.32.99 January 2024 HLEDGER(1) +hledger-1.32.99 February 2024 HLEDGER(1)