From 06a54f70b0bf6022fd6b6c00e46ae43f5e55a0d9 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 29 Jan 2020 08:27:29 -0800 Subject: [PATCH] ;doc: regen manuals [ci skip] --- hledger-lib/hledger_journal.5 | 663 ++++++++-------- hledger-lib/hledger_journal.info | 1249 +++++++++++++++--------------- hledger-lib/hledger_journal.txt | 1040 ++++++++++++------------- 3 files changed, 1449 insertions(+), 1503 deletions(-) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index c150bf3c5..4b71c628e 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -30,120 +30,91 @@ the add or web commands to create and update it. Many users, though, also edit the journal file directly with a text editor, perhaps assisted by the helper modes for emacs or vim. .PP -Here\[aq]s an example: +Helper modes exist for popular text editors, which make working with +journal files easier. +They add colour, formatting, tab completion, and helpful commands, and +are quite recommended if you edit your journal with a text editor. +They include ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, +hledger-vscode for Visual Studio Code, and others. +See the Editor configuration at hledger.org for the latest information. +.SH FILE FORMAT +.PP +Here\[aq]s a description of each part of the file format (and +hledger\[aq]s data model). +These are mostly in the order you\[aq]ll use them, but in some cases +related concepts have been grouped together for easy reference, or +linked before they are introduced, so feel free to skip over anything +that looks unnecessary right now. +.SS Transactions +.PP +Transactions are the main unit of information in a journal file. +They represent events, typically a movement of some quantity of +commodities between two or more named accounts. +.PP +Each transaction is recorded as a journal entry, beginning with a simple +date in column 0. +This can be followed by any of the following optional fields, separated +by spaces: +.IP \[bu] 2 +a status character (empty, \f[C]!\f[R], or \f[C]*\f[R]) +.IP \[bu] 2 +a code (any short number or text, enclosed in parentheses) +.IP \[bu] 2 +a description (any remaining text until end of line or a semicolon) +.IP \[bu] 2 +a comment (any remaining text following a semicolon until end of line, +and any following indented lines beginning with a semicolon) +.IP \[bu] 2 +0 or more indented \f[I]posting\f[R] lines, describing what was +transferred and the accounts involved. +.PP +Here\[aq]s a simple journal file containing one transaction: .IP .nf \f[C] -; A sample journal file. This is a comment. - -2008/01/01 income ; <- transaction\[aq]s first line starts in column 0, contains date and description - assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name - income:salary $-1 ; followed by at least two spaces and an amount - -2008/06/01 gift - assets:bank:checking $1 ; <- at least two postings in a transaction - income:gifts $-1 ; <- their amounts must balance to 0 - -2008/06/02 save - assets:bank:saving $1 - assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred - -2008/06/03 eat & shop ; <- description can be anything - expenses:food $1 - expenses:supplies $1 ; <- this transaction debits two expense accounts - assets:cash ; <- $-2 inferred - -2008/10/01 take a loan - assets:bank:checking $1 - liabilities:debts $-1 - -2008/12/31 * pay off ; <- an optional * or ! after the date means \[dq]cleared\[dq] (or anything you want) - liabilities:debts $1 - assets:bank:checking +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 \f[R] .fi -.SH FILE FORMAT -.SS Transactions -.PP -Transactions are movements of some quantity of commodities between named -accounts. -Each transaction is represented by a journal entry beginning with a -simple date in column 0. -This can be followed by any of the following, separated by spaces: -.IP \[bu] 2 -(optional) a status character (empty, \f[C]!\f[R], or \f[C]*\f[R]) -.IP \[bu] 2 -(optional) a transaction code (any short number or text, enclosed in -parentheses) -.IP \[bu] 2 -(optional) a transaction description (any remaining text until end of -line or a semicolon) -.IP \[bu] 2 -(optional) a transaction comment (any remaining text following a -semicolon until end of line) -.PP -Then comes zero or more (but usually at least 2) indented lines -representing... -.SS Postings -.PP -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: -.IP \[bu] 2 -(optional) a status character (empty, \f[C]!\f[R], or \f[C]*\f[R]), -followed by a space -.IP \[bu] 2 -(required) an account name (any text, optionally containing \f[B]single -spaces\f[R], until end of line or a double space) -.IP \[bu] 2 -(optional) \f[B]two or more spaces\f[R] or tabs followed by an amount. -.PP -Positive amounts are being added to the account, negative amounts are -being removed. -.PP -The amounts within a transaction must always sum up to zero. -As a convenience, one amount may be left blank; it will be inferred so -as to balance the transaction. -.PP -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. .SS Dates .SS Simple dates .PP -Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) -Leading zeros are optional. +Dates in the journal file use \f[I]simple dates\f[R] format: +\f[C]YYYY-MM-DD\f[R] or \f[C]YYYY/MM/DD\f[R] or \f[C]YYYY.MM.DD\f[R], +with leading zeros optional. The year may be omitted, in which case it will be inferred from the -context - the current transaction, the default year set with a default +context: the current transaction, the default year set with a default year directive, or the current date when the command is run. -Some examples: \f[C]2010/01/31\f[R], \f[C]1/31\f[R], -\f[C]2010-01-31\f[R], \f[C]2010.1.31\f[R]. +Some examples: \f[C]2010-01-31\f[R], \f[C]2010/01/31\f[R], +\f[C]2010.1.31\f[R], \f[C]1/31\f[R]. +.PP +(The UI also accepts simple dates, as well as the more flexible smart +dates documented in the hledger manual.) .SS Secondary dates .PP Real-life transactions sometimes involve more than one date - eg the date you write a cheque, and the date it clears in your bank. When you want to model this, eg for more accurate balances, you can -specify individual posting dates, which I recommend. -Or, you can use the secondary dates (aka auxiliary/effective dates) -feature, supported for compatibility with Ledger. +specify individual posting dates. .PP -A secondary date can be written after the primary date, separated by an -equals sign. -The primary date, on the left, is used by default; the secondary date, -on the right, is used when the \f[C]--date2\f[R] flag is specified -(\f[C]--aux-date\f[R] or \f[C]--effective\f[R] also work). +Or, you can use the older \f[I]secondary date\f[R] feature. +(Ledger calls it auxiliary date or effective date.) But I would +recommend avoiding this feature; posting dates are almost always clearer +and simpler. +We support it mainly for compatibility. +.PP +A secondary date is written after the primary date, following an equals +sign. +The primary date\[aq]s year will be used if the year is omitted. +When running reports, the primary (left) date is used by default, but +with the \f[C]--date2\f[R] flag (or \f[C]--aux-date\f[R] or +\f[C]--effective\f[R]), the secondary (right) date will be used instead. .PP The meaning of secondary dates is up to you, but it\[aq]s best to follow a consistent rule. -Eg write the bank\[aq]s clearing date as primary, and when needed, the -date the transaction was initiated as secondary. -.PP -Here\[aq]s an example. -Note that a secondary date will use the year of the primary date if -unspecified. +Eg \[dq]primary = the bank\[aq]s clearing date, secondary = date the +transaction was initiated, if different\[dq], as shown here: .IP .nf \f[C] @@ -166,12 +137,6 @@ $ hledger register checking --date2 2010-02-19 movie ticket assets:checking $-10 $-10 \f[R] .fi -.PP -Secondary dates require some effort; you must use them consistently in -your journal entries and remember whether to use or not use the -\f[C]--date2\f[R] flag for your reports. -They are included in hledger for Ledger compatibility, but posting dates -are a more powerful and less confusing alternative. .SS Posting dates .PP You can give individual postings a different date from their parent @@ -320,6 +285,178 @@ payee/payer name on the left (up to the first \f[C]|\f[R]) and an additional note field on the right (after the first \f[C]|\f[R]). This may be worthwhile if you need to do more precise querying and pivoting by payee or by note. +.SS Comments +.PP +Lines in the journal beginning with a semicolon (\f[C];\f[R]) or hash +(\f[C]#\f[R]) or star (\f[C]*\f[R]) are comments, and will be ignored. +(Star comments cause org-mode nodes to be ignored, allowing emacs users +to fold and navigate their journals with org-mode or orgstruct-mode.) +.PP +You can attach comments to a transaction by writing them after the +description and/or indented on the following lines (before the +postings). +Similarly, you can attach comments to an individual posting by writing +them after the amount and/or indented on the following lines. +Transaction and posting comments must begin with a semicolon +(\f[C];\f[R]). +.PP +Some examples: +.IP +.nf +\f[C] +# a file comment + +; also a file comment + +comment +This is a multiline file comment, +which continues until a line +where the \[dq]end comment\[dq] string +appears on its own (or end of file). +end comment + +2012/5/14 something ; a transaction comment + ; the transaction comment, continued + posting1 1 ; a comment for posting 1 + posting2 + ; a comment for posting 2 + ; another comment line for posting 2 +; a file comment (because not indented) +\f[R] +.fi +.PP +You can also comment larger regions of a file using \f[C]comment\f[R] +and \f[C]end comment\f[R] directives. +.SS Tags +.PP +Tags are a way to add extra labels or labelled data to postings and +transactions, which you can then search or pivot on. +.PP +A simple tag is a word (which may contain hyphens) followed by a full +colon, written inside a transaction or posting comment line: +.IP +.nf +\f[C] +2017/1/16 bought groceries ; sometag: +\f[R] +.fi +.PP +Tags can have a value, which is the text after the colon, up to the next +comma or end of line, with leading/trailing whitespace removed: +.IP +.nf +\f[C] + expenses:food $10 ; a-posting-tag: the tag value +\f[R] +.fi +.PP +Note this means hledger\[aq]s tag values can not contain commas or +newlines. +Ending at commas means you can write multiple short tags on one line, +comma separated: +.IP +.nf +\f[C] + assets:checking ; a comment containing tag1:, tag2: some value ... +\f[R] +.fi +.PP +Here, +.IP \[bu] 2 +\[dq]\f[C]a comment containing\f[R]\[dq] is just comment text, not a tag +.IP \[bu] 2 +\[dq]\f[C]tag1\f[R]\[dq] is a tag with no value +.IP \[bu] 2 +\[dq]\f[C]tag2\f[R]\[dq] is another tag, whose value is +\[dq]\f[C]some value ...\f[R]\[dq] +.PP +Tags in a transaction comment affect the transaction and all of its +postings, while tags in a posting comment affect only that posting. +For example, the following transaction has three tags (\f[C]A\f[R], +\f[C]TAG2\f[R], \f[C]third-tag\f[R]) and the posting has four (those +plus \f[C]posting-tag\f[R]): +.IP +.nf +\f[C] +1/1 a transaction ; A:, TAG2: + ; third-tag: a third transaction tag, <- with a value + (a) $1 ; posting-tag: +\f[R] +.fi +.PP +Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag +values are simple strings. +.SS Postings +.PP +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: +.IP \[bu] 2 +(optional) a status character (empty, \f[C]!\f[R], or \f[C]*\f[R]), +followed by a space +.IP \[bu] 2 +(required) an account name (any text, optionally containing \f[B]single +spaces\f[R], until end of line or a double space) +.IP \[bu] 2 +(optional) \f[B]two or more spaces\f[R] or tabs followed by an amount. +.PP +Positive amounts are being added to the account, negative amounts are +being removed. +.PP +The amounts within a transaction must always sum up to zero. +As a convenience, one amount may be left blank; it will be inferred so +as to balance the transaction. +.PP +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. +.SS Virtual Postings +.PP +A posting with a parenthesised account name is called a \f[I]virtual +posting\f[R] or \f[I]unbalanced posting\f[R], which means it is exempt +from the usual rule that a transaction\[aq]s postings must balance add +up to zero. +.PP +This is not part of double entry accounting, so you might choose to +avoid this feature. +Or you can use it sparingly for certain special cases where it can be +convenient. +Eg, you could set opening balances without using a balancing equity +account: +.IP +.nf +\f[C] +1/1 opening balances + (assets:checking) $1000 + (assets:savings) $2000 +\f[R] +.fi +.PP +A posting with a bracketed account name is called a \f[I]balanced +virtual posting\f[R]. +The balanced virtual postings in a transaction must add up to zero +(separately from other postings). +Eg: +.IP +.nf +\f[C] +1/1 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- not required to balance +\f[R] +.fi +.PP +Ordinary non-parenthesised, non-bracketed postings are called \f[I]real +postings\f[R]. +You can exclude virtual postings from reports with the +\f[C]-R/--real\f[R] flag or \f[C]real:1\f[R] query. .SS Account names .PP Account names typically have several parts separated by a full colon, @@ -465,47 +602,99 @@ indirectly. amount, or when an amountless posting is balanced using a price\[aq]s commodity, or when -V is used.) If you find this causing problems, use a commodity directive to set the display format. -.SS Virtual Postings +.SS Transaction prices .PP -When you parenthesise the account name in a posting, we call that a -\f[I]virtual posting\f[R], which means: -.IP \[bu] 2 -it is ignored when checking that the transaction is balanced -.IP \[bu] 2 -it is excluded from reports when the \f[C]--real/-R\f[R] flag is used, -or the \f[C]real:1\f[R] query. +Within a transaction, you can note an amount\[aq]s price in another +commodity. +This can be used to document the cost (in a purchase) or selling price +(in a sale). +For example, transaction prices are useful to record purchases of a +foreign currency. +Note transaction prices are fixed at the time of the transaction, and do +not change over time. +See also market prices, which represent prevailing exchange rates on a +certain date. .PP -You could use this, eg, to set an account\[aq]s opening balance without -needing to use the \f[C]equity:opening balances\f[R] account: +There are several ways to record a transaction price: +.IP "1." 3 +Write the price per unit, as \f[C]\[at] UNITPRICE\f[R] after the amount: +.RS 4 .IP .nf \f[C] -1/1 special unbalanced posting to set initial balance - (assets:checking) $1000 +2009/1/1 + assets:euros \[Eu]100 \[at] $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 \f[R] .fi -.PP -When the account name is bracketed, we call it a \f[I]balanced virtual -posting\f[R]. -This is like an ordinary virtual posting except the balanced virtual -postings in a transaction must balance to 0, like the real postings (but -separately from them). -Balanced virtual postings are also excluded by \f[C]--real/-R\f[R] or -\f[C]real:1\f[R]. +.RE +.IP "2." 3 +Write the total price, as \f[C]\[at]\[at] TOTALPRICE\f[R] after the +amount: +.RS 4 .IP .nf \f[C] -1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere - expenses:food $10 - assets:cash $-10 - [assets:checking:available] $10 - [assets:checking:budget:food] $-10 +2009/1/1 + assets:euros \[Eu]100 \[at]\[at] $135 ; one hundred euros purchased at $135 for the lot + assets:dollars +\f[R] +.fi +.RE +.IP "3." 3 +Specify amounts for all postings, using exactly two commodities, and let +hledger infer the price that balances the transaction: +.RS 4 +.IP +.nf +\f[C] +2009/1/1 + assets:euros \[Eu]100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 +\f[R] +.fi +.RE +.PP +(Ledger users: Ledger uses a different syntax for fixed prices, +\f[C]{=UNITPRICE}\f[R], which hledger currently ignores). +.PP +Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction +price\[aq]s commodity, if any. +(mnemonic: \[dq]B\[dq] is from \[dq]cost Basis\[dq], as in Ledger). +Eg here is how -B affects the balance report for the example above: +.IP +.nf +\f[C] +$ hledger bal -N --flat + $-135 assets:dollars + \[Eu]100 assets:euros +$ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros\[aq] cost \f[R] .fi .PP -Virtual postings have some legitimate uses, but those are few. -You can usually find an equivalent journal entry using real postings, -which is more correct and provides better error checking. +Note -B is sensitive to the order of postings when a transaction price +is inferred: the inferred price will be in the commodity of the last +amount. +So if example 3\[aq]s postings are reversed, while the transaction is +equivalent, -B shows something different: +.IP +.nf +\f[C] +2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros \[Eu]100 ; for 100 euros +\f[R] +.fi +.IP +.nf +\f[C] +$ hledger bal -N --flat -B + \[Eu]-100 assets:dollars # <- the dollars\[aq] selling price + \[Eu]100 assets:euros +\f[R] +.fi .SS Balance Assertions .PP hledger supports Ledger-style balance assertions in journal files. @@ -722,200 +911,6 @@ $ hledger print --explicit (a) $1 \[at] \[Eu]2 = $1 \[at] \[Eu]2 \f[R] .fi -.SS Transaction prices -.PP -Within a transaction, you can note an amount\[aq]s price in another -commodity. -This can be used to document the cost (in a purchase) or selling price -(in a sale). -For example, transaction prices are useful to record purchases of a -foreign currency. -Note transaction prices are fixed at the time of the transaction, and do -not change over time. -See also market prices, which represent prevailing exchange rates on a -certain date. -.PP -There are several ways to record a transaction price: -.IP "1." 3 -Write the price per unit, as \f[C]\[at] UNITPRICE\f[R] after the amount: -.RS 4 -.IP -.nf -\f[C] -2009/1/1 - assets:euros \[Eu]100 \[at] $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 -\f[R] -.fi -.RE -.IP "2." 3 -Write the total price, as \f[C]\[at]\[at] TOTALPRICE\f[R] after the -amount: -.RS 4 -.IP -.nf -\f[C] -2009/1/1 - assets:euros \[Eu]100 \[at]\[at] $135 ; one hundred euros purchased at $135 for the lot - assets:dollars -\f[R] -.fi -.RE -.IP "3." 3 -Specify amounts for all postings, using exactly two commodities, and let -hledger infer the price that balances the transaction: -.RS 4 -.IP -.nf -\f[C] -2009/1/1 - assets:euros \[Eu]100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 -\f[R] -.fi -.RE -.PP -(Ledger users: Ledger uses a different syntax for fixed prices, -\f[C]{=UNITPRICE}\f[R], which hledger currently ignores). -.PP -Use the \f[C]-B/--cost\f[R] flag to convert amounts to their transaction -price\[aq]s commodity, if any. -(mnemonic: \[dq]B\[dq] is from \[dq]cost Basis\[dq], as in Ledger). -Eg here is how -B affects the balance report for the example above: -.IP -.nf -\f[C] -$ hledger bal -N --flat - $-135 assets:dollars - \[Eu]100 assets:euros -$ hledger bal -N --flat -B - $-135 assets:dollars - $135 assets:euros # <- the euros\[aq] cost -\f[R] -.fi -.PP -Note -B is sensitive to the order of postings when a transaction price -is inferred: the inferred price will be in the commodity of the last -amount. -So if example 3\[aq]s postings are reversed, while the transaction is -equivalent, -B shows something different: -.IP -.nf -\f[C] -2009/1/1 - assets:dollars $-135 ; 135 dollars sold - assets:euros \[Eu]100 ; for 100 euros -\f[R] -.fi -.IP -.nf -\f[C] -$ hledger bal -N --flat -B - \[Eu]-100 assets:dollars # <- the dollars\[aq] selling price - \[Eu]100 assets:euros -\f[R] -.fi -.SS Comments -.PP -Lines in the journal beginning with a semicolon (\f[C];\f[R]) or hash -(\f[C]#\f[R]) or star (\f[C]*\f[R]) are comments, and will be ignored. -(Star comments cause org-mode nodes to be ignored, allowing emacs users -to fold and navigate their journals with org-mode or orgstruct-mode.) -.PP -You can attach comments to a transaction by writing them after the -description and/or indented on the following lines (before the -postings). -Similarly, you can attach comments to an individual posting by writing -them after the amount and/or indented on the following lines. -Transaction and posting comments must begin with a semicolon -(\f[C];\f[R]). -.PP -Some examples: -.IP -.nf -\f[C] -# a file comment - -; also a file comment - -comment -This is a multiline file comment, -which continues until a line -where the \[dq]end comment\[dq] string -appears on its own (or end of file). -end comment - -2012/5/14 something ; a transaction comment - ; the transaction comment, continued - posting1 1 ; a comment for posting 1 - posting2 - ; a comment for posting 2 - ; another comment line for posting 2 -; a file comment (because not indented) -\f[R] -.fi -.PP -You can also comment larger regions of a file using \f[C]comment\f[R] -and \f[C]end comment\f[R] directives. -.SS Tags -.PP -Tags are a way to add extra labels or labelled data to postings and -transactions, which you can then search or pivot on. -.PP -A simple tag is a word (which may contain hyphens) followed by a full -colon, written inside a transaction or posting comment line: -.IP -.nf -\f[C] -2017/1/16 bought groceries ; sometag: -\f[R] -.fi -.PP -Tags can have a value, which is the text after the colon, up to the next -comma or end of line, with leading/trailing whitespace removed: -.IP -.nf -\f[C] - expenses:food $10 ; a-posting-tag: the tag value -\f[R] -.fi -.PP -Note this means hledger\[aq]s tag values can not contain commas or -newlines. -Ending at commas means you can write multiple short tags on one line, -comma separated: -.IP -.nf -\f[C] - assets:checking ; a comment containing tag1:, tag2: some value ... -\f[R] -.fi -.PP -Here, -.IP \[bu] 2 -\[dq]\f[C]a comment containing\f[R]\[dq] is just comment text, not a tag -.IP \[bu] 2 -\[dq]\f[C]tag1\f[R]\[dq] is a tag with no value -.IP \[bu] 2 -\[dq]\f[C]tag2\f[R]\[dq] is another tag, whose value is -\[dq]\f[C]some value ...\f[R]\[dq] -.PP -Tags in a transaction comment affect the transaction and all of its -postings, while tags in a posting comment affect only that posting. -For example, the following transaction has three tags (\f[C]A\f[R], -\f[C]TAG2\f[R], \f[C]third-tag\f[R]) and the posting has four (those -plus \f[C]posting-tag\f[R]): -.IP -.nf -\f[C] -1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, <- with a value - (a) $1 ; posting-tag: -\f[R] -.fi -.PP -Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag -values are simple strings. .SS Directives .PP A directive is a line in the journal beginning with a special keyword, @@ -1421,11 +1416,14 @@ account other:zoo would influence the position of \f[C]zoo\f[R] among \f[C]other\f[R]\[aq]s subaccounts, but not the position of \f[C]other\f[R] among the top-level accounts. -This means: - you will sometimes declare parent accounts (eg -\f[C]account other\f[R] above) that you don\[aq]t intend to post to, -just to customize their display order - sibling accounts stay together -(you couldn\[aq]t display \f[C]x:y\f[R] in between \f[C]a:b\f[R] and -\f[C]a:c\f[R]). +This means: +.IP \[bu] 2 +you will sometimes declare parent accounts (eg \f[C]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[C]x:y\f[R] +in between \f[C]a:b\f[R] and \f[C]a:c\f[R]). .SS Rewriting accounts .PP You can define account alias rules which rewrite your account names, or @@ -1876,15 +1874,6 @@ rules will have these tags added: .IP \[bu] 2 \f[C]_modified:\f[R] - a hidden tag not appearing in the comment; this transaction was modified \[dq]just now\[dq]. -.SH EDITOR SUPPORT -.PP -Helper modes exist for popular text editors, which make working with -journal files easier. -They add colour, formatting, tab completion, and helpful commands, and -are quite recommended if you edit your journal with a text editor. -They include ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, -hledger-vscode for Visual Studio Code, and others. -See the Editor configuration at hledger.org for the latest information. .SH "REPORTING BUGS" diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 7425605f7..8ab1c5be6 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -2,7 +2,7 @@ This is hledger_journal.info, produced by makeinfo version 6.7 from stdin.  -File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir) +File: hledger_journal.info, Node: Top, Up: (dir) hledger_journal(5) hledger 1.16.99 ********************************** @@ -27,119 +27,72 @@ use the add or web commands to create and update it. Many users, though, also edit the journal file directly with a text editor, perhaps assisted by the helper modes for emacs or vim. - Here's an example: + Helper modes exist for popular text editors, which make working with +journal files easier. They add colour, formatting, tab completion, and +helpful commands, and are quite recommended if you edit your journal +with a text editor. They include ledger-mode or hledger-mode for Emacs, +vim-ledger for Vim, hledger-vscode for Visual Studio Code, and others. +See the Editor configuration at hledger.org for the latest information. -; A sample journal file. This is a comment. - -2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description - assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name - income:salary $-1 ; followed by at least two spaces and an amount - -2008/06/01 gift - assets:bank:checking $1 ; <- at least two postings in a transaction - income:gifts $-1 ; <- their amounts must balance to 0 - -2008/06/02 save - assets:bank:saving $1 - assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred - -2008/06/03 eat & shop ; <- description can be anything - expenses:food $1 - expenses:supplies $1 ; <- this transaction debits two expense accounts - assets:cash ; <- $-2 inferred - -2008/10/01 take a loan - assets:bank:checking $1 - liabilities:debts $-1 - -2008/12/31 * pay off ; <- an optional * or ! after the date means "cleared" (or anything you want) - liabilities:debts $1 - assets:bank:checking - -* Menu: - -* FILE FORMAT:: -* EDITOR SUPPORT:: - - -File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: Top, Up: Top - -1 FILE FORMAT -************* + Here's a description of each part of the file format (and hledger's +data model). These are mostly in the order you'll use them, but in some +cases related concepts have been grouped together for easy reference, or +linked before they are introduced, so feel free to skip over anything +that looks unnecessary right now. * Menu: * Transactions:: -* Postings:: + + +File: hledger_journal.info, Node: Transactions, Up: Top + +1 Transactions +************** + +Transactions are the main unit of information in a journal file. They +represent events, typically a movement of some quantity of commodities +between two or more named accounts. + + Each transaction is recorded as a journal entry, beginning with a +simple date in column 0. This can be followed by any of the following +optional fields, separated by spaces: + + * a status character (empty, '!', or '*') + * a code (any short number or text, enclosed in parentheses) + * a description (any remaining text until end of line or a semicolon) + * a comment (any remaining text following a semicolon until end of + line, and any following indented lines beginning with a semicolon) + * 0 or more indented _posting_ lines, describing what was transferred + and the accounts involved. + + Here's a simple journal file containing one transaction: + +2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + +* Menu: + * Dates:: * Status:: * Description:: -* Account names:: -* Amounts:: -* Virtual Postings:: -* Balance Assertions:: -* Balance Assignments:: -* Transaction prices:: * Comments:: * Tags:: +* Postings:: +* Account names:: +* Amounts:: +* Transaction prices:: +* Balance Assertions:: +* Balance Assignments:: * Directives:: * Periodic transactions:: * Auto postings / transaction modifiers::  -File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT +File: hledger_journal.info, Node: Dates, Next: Status, Up: Transactions -1.1 Transactions -================ - -Transactions are movements of some quantity of commodities between named -accounts. Each transaction is represented by a journal entry beginning -with a simple date in column 0. This can be followed by any of the -following, separated by spaces: - - * (optional) a status character (empty, '!', or '*') - * (optional) a transaction code (any short number or text, enclosed - in parentheses) - * (optional) a transaction description (any remaining text until end - of line or a semicolon) - * (optional) a transaction comment (any remaining text following a - semicolon until end of line) - - Then comes zero or more (but usually at least 2) indented lines -representing... - - -File: hledger_journal.info, Node: Postings, Next: Dates, Prev: Transactions, Up: FILE FORMAT - -1.2 Postings -============ - -A posting is an addition of some amount to, or removal of some amount -from, an account. Each posting line begins with at least one space or -tab (2 or 4 spaces is common), followed by: - - * (optional) a status character (empty, '!', or '*'), followed by a - space - * (required) an account name (any text, optionally containing *single - spaces*, until end of line or a double space) - * (optional) *two or more spaces* or tabs followed by an amount. - - Positive amounts are being added to the account, negative amounts are -being removed. - - The amounts within a transaction must always sum up to zero. As a -convenience, 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 -the amount, the amount will be considered part of the account name. - - -File: hledger_journal.info, Node: Dates, Next: Status, Prev: Postings, Up: FILE FORMAT - -1.3 Dates +1.1 Dates ========= * Menu: @@ -151,40 +104,44 @@ File: hledger_journal.info, Node: Dates, Next: Status, Prev: Postings, Up: F  File: hledger_journal.info, Node: Simple dates, Next: Secondary dates, Up: Dates -1.3.1 Simple dates +1.1.1 Simple dates ------------------ -Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) -Leading zeros are optional. The year may be omitted, in which case it -will be inferred from the context - the current transaction, the default -year set with a default year directive, or the current date when the -command is run. Some examples: '2010/01/31', '1/31', '2010-01-31', -'2010.1.31'. +Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or +'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional. The year may +be omitted, in which case it will be inferred from the context: the +current transaction, the default year set with a default year directive, +or the current date when the command is run. Some examples: +'2010-01-31', '2010/01/31', '2010.1.31', '1/31'. + + (The UI also accepts simple dates, as well as the more flexible smart +dates documented in the hledger manual.)  File: hledger_journal.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates -1.3.2 Secondary dates +1.1.2 Secondary dates --------------------- Real-life transactions sometimes involve more than one date - eg the date you write a cheque, and the date it clears in your bank. When you want to model this, eg for more accurate balances, you can specify -individual posting dates, which I recommend. Or, you can use the -secondary dates (aka auxiliary/effective dates) feature, supported for -compatibility with Ledger. +individual posting dates. - A secondary date can be written after the primary date, separated by -an equals sign. The primary date, on the left, is used by default; the -secondary date, on the right, is used when the '--date2' flag is -specified ('--aux-date' or '--effective' also work). + Or, you can use the older _secondary date_ feature. (Ledger calls it +auxiliary date or effective date.) But I would recommend avoiding this +feature; posting dates are almost always clearer and simpler. We +support it mainly for compatibility. + + A secondary date is written after the primary date, following an +equals sign. The primary date's year will be used if the year is +omitted. When running reports, the primary (left) date is used by +default, but with the '--date2' flag (or '--aux-date' or '--effective'), +the secondary (right) date will be used instead. The meaning of secondary dates is up to you, but it's best to follow -a consistent rule. Eg write the bank's clearing date as primary, and -when needed, the date the transaction was initiated as secondary. - - Here's an example. Note that a secondary date will use the year of -the primary date if unspecified. +a consistent rule. Eg "primary = the bank's clearing date, secondary = +date the transaction was initiated, if different", as shown here: 2010/2/23=2/19 movie ticket expenses:cinema $10 @@ -196,16 +153,10 @@ $ hledger register checking $ hledger register checking --date2 2010-02-19 movie ticket assets:checking $-10 $-10 - Secondary dates require some effort; you must use them consistently -in your journal entries and remember whether to use or not use the -'--date2' flag for your reports. They are included in hledger for -Ledger compatibility, but posting dates are a more powerful and less -confusing alternative. -  File: hledger_journal.info, Node: Posting dates, Prev: Secondary dates, Up: Dates -1.3.3 Posting dates +1.1.3 Posting dates ------------------- You can give individual postings a different date from their parent @@ -238,9 +189,9 @@ characters in this way. With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE.  -File: hledger_journal.info, Node: Status, Next: Description, Prev: Dates, Up: FILE FORMAT +File: hledger_journal.info, Node: Status, Next: Description, Prev: Dates, Up: Transactions -1.4 Status +1.2 Status ========== Transactions, or individual postings within a transaction, can have a @@ -288,9 +239,9 @@ your bank, '-U' to see things which will probably hit your bank soon your finances.  -File: hledger_journal.info, Node: Description, Next: Account names, Prev: Status, Up: FILE FORMAT +File: hledger_journal.info, Node: Description, Next: Comments, Prev: Status, Up: Transactions -1.5 Description +1.3 Description =============== A transaction's description is the rest of the line following the date @@ -306,7 +257,7 @@ comments.  File: hledger_journal.info, Node: Payee and note, Up: Description -1.5.1 Payee and note +1.3.1 Payee and note -------------------- You can optionally include a '|' (pipe) character in descriptions to @@ -316,9 +267,160 @@ the left (up to the first '|') and an additional note field on the right precise querying and pivoting by payee or by note.  -File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Description, Up: FILE FORMAT +File: hledger_journal.info, Node: Comments, Next: Tags, Prev: Description, Up: Transactions -1.6 Account names +1.4 Comments +============ + +Lines in the journal beginning with a semicolon (';') or hash ('#') or +star ('*') are comments, and will be ignored. (Star comments cause +org-mode nodes to be ignored, allowing emacs users to fold and navigate +their journals with org-mode or orgstruct-mode.) + + You can attach comments to a transaction by writing them after the +description and/or indented on the following lines (before the +postings). Similarly, you can attach comments to an individual posting +by writing them after the amount and/or indented on the following lines. +Transaction and posting comments must begin with a semicolon (';'). + + Some examples: + +# a file comment + +; also a file comment + +comment +This is a multiline file comment, +which continues until a line +where the "end comment" string +appears on its own (or end of file). +end comment + +2012/5/14 something ; a transaction comment + ; the transaction comment, continued + posting1 1 ; a comment for posting 1 + posting2 + ; a comment for posting 2 + ; another comment line for posting 2 +; a file comment (because not indented) + + You can also comment larger regions of a file using 'comment' and +'end comment' directives. + + +File: hledger_journal.info, Node: Tags, Next: Postings, Prev: Comments, Up: Transactions + +1.5 Tags +======== + +Tags are a way to add extra labels or labelled data to postings and +transactions, which you can then search or pivot on. + + A simple tag is a word (which may contain hyphens) followed by a full +colon, written inside a transaction or posting comment line: + +2017/1/16 bought groceries ; sometag: + + Tags can have a value, which is the text after the colon, up to the +next comma or end of line, with leading/trailing whitespace removed: + + expenses:food $10 ; a-posting-tag: the tag value + + Note this means hledger's tag values can not contain commas or +newlines. Ending at commas means you can write multiple short tags on +one line, comma separated: + + assets:checking ; a comment containing tag1:, tag2: some value ... + + Here, + + * "'a comment containing'" is just comment text, not a tag + * "'tag1'" is a tag with no value + * "'tag2'" is another tag, whose value is "'some value ...'" + + Tags in a transaction comment affect the transaction and all of its +postings, while tags in a posting comment affect only that posting. For +example, the following transaction has three tags ('A', 'TAG2', +'third-tag') and the posting has four (those plus 'posting-tag'): + +1/1 a transaction ; A:, TAG2: + ; third-tag: a third transaction tag, <- with a value + (a) $1 ; posting-tag: + + Tags are like Ledger's metadata feature, except hledger's tag values +are simple strings. + + +File: hledger_journal.info, Node: Postings, Next: Account names, Prev: Tags, Up: Transactions + +1.6 Postings +============ + +A posting is an addition of some amount to, or removal of some amount +from, an account. Each posting line begins with at least one space or +tab (2 or 4 spaces is common), followed by: + + * (optional) a status character (empty, '!', or '*'), followed by a + space + * (required) an account name (any text, optionally containing *single + spaces*, until end of line or a double space) + * (optional) *two or more spaces* or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are +being removed. + + The amounts within a transaction must always sum up to zero. As a +convenience, 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 +the amount, the amount will be considered part of the account name. + +* Menu: + +* Virtual Postings:: + + +File: hledger_journal.info, Node: Virtual Postings, Up: Postings + +1.6.1 Virtual Postings +---------------------- + +A posting with a parenthesised account name is called a _virtual +posting_ or _unbalanced posting_, which means it is exempt from the +usual rule that a transaction's postings must balance add up to zero. + + This is not part of double entry accounting, so you might choose to +avoid this feature. Or you can use it sparingly for certain special +cases where it can be convenient. Eg, you could set opening balances +without using a balancing equity account: + +1/1 opening balances + (assets:checking) $1000 + (assets:savings) $2000 + + A posting with a bracketed account name is called a _balanced virtual +posting_. The balanced virtual postings in a transaction must add up to +zero (separately from other postings). Eg: + +1/1 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- not required to balance + + Ordinary non-parenthesised, non-bracketed postings are called _real +postings_. You can exclude virtual postings from reports with the +'-R/--real' flag or 'real:1' query. + + +File: hledger_journal.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Transactions + +1.7 Account names ================= Account names typically have several parts separated by a full colon, @@ -334,9 +436,9 @@ more spaces* (or newline). Account names can be aliased.  -File: hledger_journal.info, Node: Amounts, Next: Virtual Postings, Prev: Account names, Up: FILE FORMAT +File: hledger_journal.info, Node: Amounts, Next: Transaction prices, Prev: Account names, Up: Transactions -1.7 Amounts +1.8 Amounts =========== After the account name, there is usually an amount. (Important: between @@ -385,7 +487,7 @@ comma:  File: hledger_journal.info, Node: Digit group marks, Next: Amount display format, Up: Amounts -1.7.1 Digit group marks +1.8.1 Digit group marks ----------------------- In the integer part of the quantity (left of the decimal mark), groups @@ -418,7 +520,7 @@ commodity 1 000 000.9455  File: hledger_journal.info, Node: Amount display format, Prev: Digit group marks, Up: Amounts -1.7.2 Amount display format +1.8.2 Amount display format --------------------------- For each commodity, hledger chooses a consistent format to use when @@ -444,282 +546,11 @@ when -V is used.) If you find this causing problems, use a commodity directive to set the display format.  -File: hledger_journal.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT +File: hledger_journal.info, Node: Transaction prices, Next: Balance Assertions, Prev: Amounts, Up: Transactions -1.8 Virtual Postings -==================== - -When you parenthesise the account name in a posting, we call that a -_virtual posting_, which means: - - * it is ignored when checking that the transaction is balanced - * it is excluded from reports when the '--real/-R' flag is used, or - the 'real:1' query. - - You could use this, eg, to set an account's opening balance without -needing to use the 'equity:opening balances' account: - -1/1 special unbalanced posting to set initial balance - (assets:checking) $1000 - - When the account name is bracketed, we call it a _balanced virtual -posting_. This is like an ordinary virtual posting except the balanced -virtual postings in a transaction must balance to 0, like the real -postings (but separately from them). Balanced virtual postings are also -excluded by '--real/-R' or 'real:1'. - -1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere - expenses:food $10 - assets:cash $-10 - [assets:checking:available] $10 - [assets:checking:budget:food] $-10 - - Virtual postings have some legitimate uses, but those are few. You -can usually find an equivalent journal entry using real postings, which -is more correct and provides better error checking. - - -File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Virtual Postings, Up: FILE FORMAT - -1.9 Balance Assertions +1.9 Transaction prices ====================== -hledger supports Ledger-style balance assertions in journal files. -These look like, for example, '= EXPECTEDBALANCE' following a posting's -amount. Eg here we assert the expected dollar balance in accounts a and -b after each posting: - -2013/1/1 - a $1 =$1 - b =$-1 - -2013/1/2 - a $1 =$2 - b $-1 =$-2 - - After reading a journal file, hledger will check all balance -assertions and report an error if any of them fail. Balance assertions -can protect you from, eg, inadvertently disrupting reconciled balances -while cleaning up old entries. You can disable them temporarily with -the '-I/--ignore-assertions' flag, which can be useful for -troubleshooting or for reading Ledger files. (Note: this flag currently -does not disable balance assignments, below). - -* Menu: - -* Assertions and ordering:: -* Assertions and included files:: -* Assertions and multiple -f options:: -* Assertions and commodities:: -* Assertions and prices:: -* Assertions and subaccounts:: -* Assertions and virtual postings:: -* Assertions and precision:: - - -File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions - -1.9.1 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 -different from Ledger, which sorts assertions only by parse order. -(Also, Ledger assertions do not see the accumulated effect of repeated -postings to the same account within a transaction.) - - So, hledger balance assertions keep working if you reorder -differently-dated transactions within the journal. But if you reorder -same-dated transactions or postings, assertions might break and require -updating. This order dependence does bring an advantage: precise -control over the order of postings and assertions within a day, so you -can assert intra-day balances. - - -File: hledger_journal.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance Assertions - -1.9.2 Assertions and included files ------------------------------------ - -With included files, things are a little more complicated. Including -preserves the ordering of postings and assertions. If you have multiple -postings to an account on the same day, split across different files, -and you also want to assert the account's balance on the same day, -you'll have to put the assertion in the right file. - - -File: hledger_journal.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance Assertions - -1.9.3 Assertions and multiple -f options ----------------------------------------- - -Balance assertions don't work well across files specified with multiple --f options. Use include or concatenate the files instead. - - -File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f options, Up: Balance Assertions - -1.9.4 Assertions and commodities --------------------------------- - -The asserted balance must be a simple single-commodity amount, and in -fact the assertion checks only this commodity's balance within the -(possibly multi-commodity) account balance. -This is how assertions work in Ledger also. We could call this a -"partial" balance assertion. - - To assert the balance of more than one commodity in an account, you -can write multiple postings, each asserting one commodity's balance. - - You can make a stronger "total" balance assertion by writing a double -equals sign ('== EXPECTEDBALANCE'). This asserts that there are no -other unasserted commodities in the account (or, that their balance is -0). - -2013/1/1 - a $1 - a 1€ - b $-1 - c -1€ - -2013/1/2 ; These assertions succeed - a 0 = $1 - a 0 = 1€ - b 0 == $-1 - c 0 == -1€ - -2013/1/3 ; This assertion fails as 'a' also contains 1€ - a 0 == $1 - - It's not yet possible to make a complete assertion about a balance -that has multiple commodities. One workaround is to isolate each -commodity into its own subaccount: - -2013/1/1 - a:usd $1 - a:euro 1€ - b - -2013/1/2 - a 0 == 0 - a:usd 0 == $1 - a:euro 0 == 1€ - - -File: hledger_journal.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance Assertions - -1.9.5 Assertions and prices ---------------------------- - -Balance assertions ignore transaction prices, and should normally be -written without one: - -2019/1/1 - (a) $1 @ €1 = $1 - - We do allow prices to be written there, however, and print shows -them, even though they don't affect whether the assertion passes or -fails. This is for backward compatibility (hledger's close command used -to generate balance assertions with prices), and because balance -_assignments_ do use them (see below). - - -File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance Assertions - -1.9.6 Assertions and subaccounts --------------------------------- - -The balance assertions above ('=' and '==') do not count the balance -from subaccounts; they check the account's exclusive balance only. You -can assert the balance including subaccounts by writing '=*' or '==*', -eg: - -2019/1/1 - equity:opening balances - checking:a 5 - checking:b 5 - checking 1 ==* 11 - - -File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions - -1.9.7 Assertions and virtual postings -------------------------------------- - -Balance assertions are checked against all postings, both real and -virtual. They are not affected by the '--real/-R' flag or 'real:' -query. - - -File: hledger_journal.info, Node: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance Assertions - -1.9.8 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 assertions. Balance -assertion failure messages show exact amounts. - - -File: hledger_journal.info, Node: Balance Assignments, Next: Transaction prices, Prev: Balance Assertions, Up: FILE FORMAT - -1.10 Balance Assignments -======================== - -Ledger-style balance assignments are also supported. These are like -balance assertions, but with no posting amount on the left side of the -equals sign; instead it is calculated automatically so as to satisfy the -assertion. This can be a convenience during data entry, eg when setting -opening balances: - -; starting a new journal, set asset account balances -2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - -; no cash left; update balance, record any untracked spending as a generic expense -2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the -commodity at that point (which depends on the previously-dated postings -of the commodity to that account since the last balance assertion or -assignment). Note that using balance assignments makes your journal a -little less explicit; to know the exact amount posted, you have to run -hledger or do the calculations yourself, instead of just reading it. - -* Menu: - -* Balance assignments and prices:: - - -File: hledger_journal.info, Node: Balance assignments and prices, Up: Balance Assignments - -1.10.1 Balance assignments and prices -------------------------------------- - -A transaction price in a balance assignment will cause the calculated -amount to have that price attached: - -2019/1/1 - (a) = $1 @ €2 - -$ hledger print --explicit -2019-01-01 - (a) $1 @ €2 = $1 @ €2 - - -File: hledger_journal.info, Node: Transaction prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT - -1.11 Transaction prices -======================= - Within a transaction, you can note an amount's price in another commodity. This can be used to document the cost (in a purchase) or selling price (in a sale). For example, transaction prices are useful @@ -778,93 +609,245 @@ $ hledger bal -N --flat -B €100 assets:euros  -File: hledger_journal.info, Node: Comments, Next: Tags, Prev: Transaction prices, Up: FILE FORMAT +File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignments, Prev: Transaction prices, Up: Transactions -1.12 Comments -============= +1.10 Balance Assertions +======================= -Lines in the journal beginning with a semicolon (';') or hash ('#') or -star ('*') are comments, and will be ignored. (Star comments cause -org-mode nodes to be ignored, allowing emacs users to fold and navigate -their journals with org-mode or orgstruct-mode.) +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: - You can attach comments to a transaction by writing them after the -description and/or indented on the following lines (before the -postings). Similarly, you can attach comments to an individual posting -by writing them after the amount and/or indented on the following lines. -Transaction and posting comments must begin with a semicolon (';'). +2013/1/1 + a $1 =$1 + b =$-1 - Some examples: +2013/1/2 + a $1 =$2 + b $-1 =$-2 -# a file comment + After reading a journal file, hledger will check all balance +assertions and report an error if any of them fail. Balance assertions +can protect you from, eg, inadvertently disrupting reconciled balances +while cleaning up old entries. You can disable them temporarily with +the '-I/--ignore-assertions' flag, which can be useful for +troubleshooting or for reading Ledger files. (Note: this flag currently +does not disable balance assignments, below). -; also a file comment +* Menu: -comment -This is a multiline file comment, -which continues until a line -where the "end comment" string -appears on its own (or end of file). -end comment - -2012/5/14 something ; a transaction comment - ; the transaction comment, continued - posting1 1 ; a comment for posting 1 - posting2 - ; a comment for posting 2 - ; another comment line for posting 2 -; a file comment (because not indented) - - You can also comment larger regions of a file using 'comment' and -'end comment' directives. +* Assertions and ordering:: +* Assertions and included files:: +* Assertions and multiple -f options:: +* Assertions and commodities:: +* Assertions and prices:: +* Assertions and subaccounts:: +* Assertions and virtual postings:: +* Assertions and precision::  -File: hledger_journal.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT +File: hledger_journal.info, Node: Assertions and ordering, Next: Assertions and included files, Up: Balance Assertions -1.13 Tags -========= +1.10.1 Assertions and ordering +------------------------------ -Tags are a way to add extra labels or labelled data to postings and -transactions, which you can then search or pivot on. +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 +different from Ledger, which sorts assertions only by parse order. +(Also, Ledger assertions do not see the accumulated effect of repeated +postings to the same account within a transaction.) - A simple tag is a word (which may contain hyphens) followed by a full -colon, written inside a transaction or posting comment line: - -2017/1/16 bought groceries ; sometag: - - Tags can have a value, which is the text after the colon, up to the -next comma or end of line, with leading/trailing whitespace removed: - - expenses:food $10 ; a-posting-tag: the tag value - - Note this means hledger's tag values can not contain commas or -newlines. Ending at commas means you can write multiple short tags on -one line, comma separated: - - assets:checking ; a comment containing tag1:, tag2: some value ... - - Here, - - * "'a comment containing'" is just comment text, not a tag - * "'tag1'" is a tag with no value - * "'tag2'" is another tag, whose value is "'some value ...'" - - Tags in a transaction comment affect the transaction and all of its -postings, while tags in a posting comment affect only that posting. For -example, the following transaction has three tags ('A', 'TAG2', -'third-tag') and the posting has four (those plus 'posting-tag'): - -1/1 a transaction ; A:, TAG2: - ; third-tag: a third transaction tag, <- with a value - (a) $1 ; posting-tag: - - Tags are like Ledger's metadata feature, except hledger's tag values -are simple strings. + So, hledger balance assertions keep working if you reorder +differently-dated transactions within the journal. But if you reorder +same-dated transactions or postings, assertions might break and require +updating. This order dependence does bring an advantage: precise +control over the order of postings and assertions within a day, so you +can assert intra-day balances.  -File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Prev: Tags, Up: FILE FORMAT +File: hledger_journal.info, Node: Assertions and included files, Next: Assertions and multiple -f options, Prev: Assertions and ordering, Up: Balance Assertions -1.14 Directives +1.10.2 Assertions and included files +------------------------------------ + +With included files, things are a little more complicated. Including +preserves the ordering of postings and assertions. If you have multiple +postings to an account on the same day, split across different files, +and you also want to assert the account's balance on the same day, +you'll have to put the assertion in the right file. + + +File: hledger_journal.info, Node: Assertions and multiple -f options, Next: Assertions and commodities, Prev: Assertions and included files, Up: Balance Assertions + +1.10.3 Assertions and multiple -f options +----------------------------------------- + +Balance assertions don't work well across files specified with multiple +-f options. Use include or concatenate the files instead. + + +File: hledger_journal.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f options, Up: Balance Assertions + +1.10.4 Assertions and commodities +--------------------------------- + +The asserted balance must be a simple single-commodity amount, and in +fact the assertion checks only this commodity's balance within the +(possibly multi-commodity) account balance. +This is how assertions work in Ledger also. We could call this a +"partial" balance assertion. + + To assert the balance of more than one commodity in an account, you +can write multiple postings, each asserting one commodity's balance. + + You can make a stronger "total" balance assertion by writing a double +equals sign ('== EXPECTEDBALANCE'). This asserts that there are no +other unasserted commodities in the account (or, that their balance is +0). + +2013/1/1 + a $1 + a 1€ + b $-1 + c -1€ + +2013/1/2 ; These assertions succeed + a 0 = $1 + a 0 = 1€ + b 0 == $-1 + c 0 == -1€ + +2013/1/3 ; This assertion fails as 'a' also contains 1€ + a 0 == $1 + + It's not yet possible to make a complete assertion about a balance +that has multiple commodities. One workaround is to isolate each +commodity into its own subaccount: + +2013/1/1 + a:usd $1 + a:euro 1€ + b + +2013/1/2 + a 0 == 0 + a:usd 0 == $1 + a:euro 0 == 1€ + + +File: hledger_journal.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance Assertions + +1.10.5 Assertions and prices +---------------------------- + +Balance assertions ignore transaction prices, and should normally be +written without one: + +2019/1/1 + (a) $1 @ €1 = $1 + + We do allow prices to be written there, however, and print shows +them, even though they don't affect whether the assertion passes or +fails. This is for backward compatibility (hledger's close command used +to generate balance assertions with prices), and because balance +_assignments_ do use them (see below). + + +File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance Assertions + +1.10.6 Assertions and subaccounts +--------------------------------- + +The balance assertions above ('=' and '==') do not count the balance +from subaccounts; they check the account's exclusive balance only. You +can assert the balance including subaccounts by writing '=*' or '==*', +eg: + +2019/1/1 + equity:opening balances + checking:a 5 + checking:b 5 + checking 1 ==* 11 + + +File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions + +1.10.7 Assertions and virtual postings +-------------------------------------- + +Balance assertions are checked against all postings, both real and +virtual. They are not affected by the '--real/-R' flag or 'real:' +query. + + +File: hledger_journal.info, Node: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance Assertions + +1.10.8 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 assertions. Balance +assertion failure messages show exact amounts. + + +File: hledger_journal.info, Node: Balance Assignments, Next: Directives, Prev: Balance Assertions, Up: Transactions + +1.11 Balance Assignments +======================== + +Ledger-style balance assignments are also supported. These are like +balance assertions, but with no posting amount on the left side of the +equals sign; instead it is calculated automatically so as to satisfy the +assertion. This can be a convenience during data entry, eg when setting +opening balances: + +; starting a new journal, set asset account balances +2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + +; no cash left; update balance, record any untracked spending as a generic expense +2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the +commodity at that point (which depends on the previously-dated postings +of the commodity to that account since the last balance assertion or +assignment). Note that using balance assignments makes your journal a +little less explicit; to know the exact amount posted, you have to run +hledger or do the calculations yourself, instead of just reading it. + +* Menu: + +* Balance assignments and prices:: + + +File: hledger_journal.info, Node: Balance assignments and prices, Up: Balance Assignments + +1.11.1 Balance assignments and prices +------------------------------------- + +A transaction price in a balance assignment will cause the calculated +amount to have that price attached: + +2019/1/1 + (a) = $1 @ €2 + +$ hledger print --explicit +2019-01-01 + (a) $1 @ €2 = $1 @ €2 + + +File: hledger_journal.info, Node: Directives, Next: Periodic transactions, Prev: Balance Assignments, Up: Transactions + +1.12 Directives =============== A directive is a line in the journal beginning with a special keyword, @@ -970,7 +953,7 @@ times though.  File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Up: Directives -1.14.1 Comment blocks +1.12.1 Comment blocks --------------------- A line containing just 'comment' starts a commented region of the file, @@ -980,7 +963,7 @@ file) ends it. See also comments.  File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives -1.14.2 Including other files +1.12.2 Including other files ---------------------------- You can pull in the content of additional files by writing an include @@ -998,7 +981,7 @@ include journal, timeclock or timedot files, but not CSV files.  File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives -1.14.3 Default year +1.12.3 Default year ------------------- You can set a default year to be used for subsequent dates which don't @@ -1024,7 +1007,7 @@ Y2010 ; change default year to 2010  File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives -1.14.4 Declaring commodities +1.12.4 Declaring commodities ---------------------------- The 'commodity' directive has several functions: @@ -1075,7 +1058,7 @@ a comma, followed by 0 or more decimal digits.  File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives -1.14.5 Default commodity +1.12.5 Default commodity ------------------------ The 'D' directive sets a default commodity (and display format), to be @@ -1098,7 +1081,7 @@ with a decimal point.  File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives -1.14.6 Market prices +1.12.6 Market prices -------------------- The 'P' directive declares a market price, which is an exchange rate @@ -1128,7 +1111,7 @@ another commodity using these prices.  File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Market prices, Up: Directives -1.14.7 Declaring accounts +1.12.7 Declaring accounts ------------------------- 'account' directives can be used to pre-declare accounts. Though not @@ -1161,7 +1144,7 @@ account assets:bank:checking  File: hledger_journal.info, Node: Account comments, Next: Account subdirectives, Up: Declaring accounts -1.14.7.1 Account comments +1.12.7.1 Account comments ......................... Comments, beginning with a semicolon, can be added: @@ -1181,7 +1164,7 @@ account assets:bank:checking ; same-line comment, note 2+ spaces before ;  File: hledger_journal.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts -1.14.7.2 Account subdirectives +1.12.7.2 Account subdirectives .............................. We also allow (and ignore) Ledger-style indented subdirectives, just for @@ -1199,7 +1182,7 @@ account ACCTNAME [ACCTTYPE] [;COMMENT]  File: hledger_journal.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts -1.14.7.3 Account types +1.12.7.3 Account types ...................... hledger recognises five types (or classes) of account: Asset, Liability, @@ -1244,7 +1227,7 @@ account - ; type:L  File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts -1.14.7.4 Account display order +1.12.7.4 Account display order .............................. Account directives also set the order in which accounts are displayed, @@ -1279,15 +1262,18 @@ account other:zoo would influence the position of 'zoo' among 'other''s subaccounts, but not the position of 'other' among the top-level accounts. This -means: - 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'). +means: + + * 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').  File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives -1.14.8 Rewriting accounts +1.12.8 Rewriting accounts ------------------------- You can define account alias rules which rewrite your account names, or @@ -1316,7 +1302,7 @@ hledger-web.  File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts -1.14.8.1 Basic aliases +1.12.8.1 Basic aliases ...................... To set an account alias, use the 'alias' directive in your journal file. @@ -1339,7 +1325,7 @@ alias checking = assets:bank:wells fargo:checking  File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts -1.14.8.2 Regex aliases +1.12.8.2 Regex aliases ...................... There is also a more powerful variant that uses a regular expression, @@ -1364,7 +1350,7 @@ whitespace.  File: hledger_journal.info, Node: Combining aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts -1.14.8.3 Combining aliases +1.12.8.3 Combining aliases .......................... You can define as many aliases as you like, using journal directives @@ -1401,7 +1387,7 @@ which aliases are being applied when.  File: hledger_journal.info, Node: end aliases, Prev: Combining aliases, Up: Rewriting accounts -1.14.8.4 'end aliases' +1.12.8.4 'end aliases' ...................... You can clear (forget) all currently defined aliases with the 'end @@ -1412,7 +1398,7 @@ end aliases  File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives -1.14.9 Default parent account +1.12.9 Default parent account ----------------------------- You can specify a parent account which will be prepended to all accounts @@ -1451,9 +1437,9 @@ If account aliases are present, they are applied after the default parent account.  -File: hledger_journal.info, Node: Periodic transactions, Next: Auto postings / transaction modifiers, Prev: Directives, Up: FILE FORMAT +File: hledger_journal.info, Node: Periodic transactions, Next: Auto postings / transaction modifiers, Prev: Directives, Up: Transactions -1.15 Periodic transactions +1.13 Periodic transactions ========================== Periodic transaction rules describe transactions that recur. They allow @@ -1498,7 +1484,7 @@ read this whole section - or at least these tips:  File: hledger_journal.info, Node: Periodic rule syntax, Next: Two spaces between period expression and description!, Up: Periodic transactions -1.15.1 Periodic rule syntax +1.13.1 Periodic rule syntax --------------------------- A periodic transaction rule looks like a normal journal entry, with the @@ -1521,7 +1507,7 @@ will be relative to Y/1/1.  File: hledger_journal.info, Node: Two spaces between period expression and description!, Next: Forecasting with periodic transactions, Prev: Periodic rule syntax, Up: Periodic transactions -1.15.2 Two spaces between period expression and description! +1.13.2 Two spaces between period expression and description! ------------------------------------------------------------ If the period expression is followed by a transaction description, these @@ -1546,7 +1532,7 @@ accidentally alter their meaning, as in this example:  File: hledger_journal.info, Node: Forecasting with periodic transactions, Next: Budgeting with periodic transactions, Prev: Two spaces between period expression and description!, Up: Periodic transactions -1.15.3 Forecasting with periodic transactions +1.13.3 Forecasting with periodic transactions --------------------------------------------- With the '--forecast' flag, each periodic transaction rule generates @@ -1599,7 +1585,7 @@ disables forecast transactions on previous dates.)  File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: Periodic transactions -1.15.4 Budgeting with periodic transactions +1.13.4 Budgeting with periodic transactions ------------------------------------------- With the '--budget' flag, currently supported by the balance command, @@ -1613,9 +1599,9 @@ compared in budget reports. Forecasting.  -File: hledger_journal.info, Node: Auto postings / transaction modifiers, Prev: Periodic transactions, Up: FILE FORMAT +File: hledger_journal.info, Node: Auto postings / transaction modifiers, Prev: Periodic transactions, Up: Transactions -1.16 Auto postings / transaction modifiers +1.14 Auto postings / transaction modifiers ========================================== Transaction modifier rules, AKA auto posting rules, describe changes to @@ -1692,7 +1678,7 @@ $ hledger print --auto  File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers -1.16.1 Auto postings and dates +1.14.1 Auto postings and dates ------------------------------ A posting date (or secondary date) in the matched posting, or (taking @@ -1702,7 +1688,7 @@ used in the generated posting.  File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings / transaction modifiers -1.16.2 Auto postings and transaction balancing / inferred amounts / +1.14.2 Auto postings and transaction balancing / inferred amounts / ------------------------------------------------------------------- balance assertions Currently, transaction modifiers are applied / auto @@ -1719,7 +1705,7 @@ for background.  File: hledger_journal.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers -1.16.3 Auto posting tags +1.14.3 Auto posting tags ------------------------ Postings added by transaction modifiers will have some extra tags: @@ -1738,136 +1724,119 @@ rules will have these tags added: * '_modified:' - a hidden tag not appearing in the comment; this transaction was modified "just now". - -File: hledger_journal.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top - -2 EDITOR SUPPORT -**************** - -Helper modes exist for popular text editors, which make working with -journal files easier. They add colour, formatting, tab completion, and -helpful commands, and are quite recommended if you edit your journal -with a text editor. They include ledger-mode or hledger-mode for Emacs, -vim-ledger for Vim, hledger-vscode for Visual Studio Code, and others. -See the Editor configuration at hledger.org for the latest information. -  Tag Table: Node: Top76 -Node: FILE FORMAT2434 -Ref: #file-format2558 -Node: Transactions2861 -Ref: #transactions2982 -Node: Postings3666 -Ref: #postings3793 -Node: Dates4788 -Ref: #dates4903 -Node: Simple dates4968 -Ref: #simple-dates5094 -Node: Secondary dates5460 -Ref: #secondary-dates5614 -Node: Posting dates7177 -Ref: #posting-dates7306 -Node: Status8678 -Ref: #status8798 -Node: Description10506 -Ref: #description10644 -Node: Payee and note10964 -Ref: #payee-and-note11078 -Node: Account names11413 -Ref: #account-names11556 -Node: Amounts12043 -Ref: #amounts12179 -Node: Digit group marks13112 -Ref: #digit-group-marks13261 -Node: Amount display format14199 -Ref: #amount-display-format14356 -Node: Virtual Postings15381 -Ref: #virtual-postings15540 -Node: Balance Assertions16760 -Ref: #balance-assertions16935 -Node: Assertions and ordering17968 -Ref: #assertions-and-ordering18154 -Node: Assertions and included files18854 -Ref: #assertions-and-included-files19095 -Node: Assertions and multiple -f options19428 -Ref: #assertions-and-multiple--f-options19682 -Node: Assertions and commodities19814 -Ref: #assertions-and-commodities20044 -Node: Assertions and prices21200 -Ref: #assertions-and-prices21412 -Node: Assertions and subaccounts21852 -Ref: #assertions-and-subaccounts22079 -Node: Assertions and virtual postings22403 -Ref: #assertions-and-virtual-postings22643 -Node: Assertions and precision22785 -Ref: #assertions-and-precision22976 -Node: Balance Assignments23243 -Ref: #balance-assignments23424 -Node: Balance assignments and prices24589 -Ref: #balance-assignments-and-prices24761 -Node: Transaction prices24985 -Ref: #transaction-prices25154 -Node: Comments27420 -Ref: #comments27554 -Node: Tags28724 -Ref: #tags28842 -Node: Directives30235 -Ref: #directives30378 -Node: Comment blocks36057 -Ref: #comment-blocks36202 -Node: Including other files36378 -Ref: #including-other-files36558 -Node: Default year36966 -Ref: #default-year37135 -Node: Declaring commodities37542 -Ref: #declaring-commodities37725 -Node: Default commodity39386 -Ref: #default-commodity39562 -Node: Market prices40196 -Ref: #market-prices40361 -Node: Declaring accounts41202 -Ref: #declaring-accounts41378 -Node: Account comments42303 -Ref: #account-comments42466 -Node: Account subdirectives42890 -Ref: #account-subdirectives43085 -Node: Account types43398 -Ref: #account-types43582 -Node: Account display order45224 -Ref: #account-display-order45394 -Node: Rewriting accounts46523 -Ref: #rewriting-accounts46708 -Node: Basic aliases47434 -Ref: #basic-aliases47580 -Node: Regex aliases48284 -Ref: #regex-aliases48456 -Node: Combining aliases49174 -Ref: #combining-aliases49352 -Node: end aliases50628 -Ref: #end-aliases50776 -Node: Default parent account50877 -Ref: #default-parent-account51043 -Node: Periodic transactions51927 -Ref: #periodic-transactions52125 -Node: Periodic rule syntax53997 -Ref: #periodic-rule-syntax54203 -Node: Two spaces between period expression and description!54907 -Ref: #two-spaces-between-period-expression-and-description55226 -Node: Forecasting with periodic transactions55910 -Ref: #forecasting-with-periodic-transactions56215 -Node: Budgeting with periodic transactions58241 -Ref: #budgeting-with-periodic-transactions58480 -Node: Auto postings / transaction modifiers58929 -Ref: #auto-postings-transaction-modifiers59140 -Node: Auto postings and dates61369 -Ref: #auto-postings-and-dates61626 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions61801 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62176 -Node: Auto posting tags62554 -Ref: #auto-posting-tags62793 -Node: EDITOR SUPPORT63458 -Ref: #editor-support63576 +Node: Transactions2033 +Ref: #transactions2125 +Node: Dates3314 +Ref: #dates3413 +Node: Simple dates3478 +Ref: #simple-dates3604 +Node: Secondary dates4113 +Ref: #secondary-dates4267 +Node: Posting dates5601 +Ref: #posting-dates5730 +Node: Status7102 +Ref: #status7223 +Node: Description8931 +Ref: #description9065 +Node: Payee and note9385 +Ref: #payee-and-note9499 +Node: Comments9834 +Ref: #comments9960 +Node: Tags11130 +Ref: #tags11245 +Node: Postings12638 +Ref: #postings12766 +Node: Virtual Postings13792 +Ref: #virtual-postings13909 +Node: Account names15215 +Ref: #account-names15356 +Node: Amounts15843 +Ref: #amounts15982 +Node: Digit group marks16915 +Ref: #digit-group-marks17064 +Node: Amount display format18002 +Ref: #amount-display-format18159 +Node: Transaction prices19184 +Ref: #transaction-prices19350 +Node: Balance Assertions21616 +Ref: #balance-assertions21796 +Node: Assertions and ordering22829 +Ref: #assertions-and-ordering23017 +Node: Assertions and included files23717 +Ref: #assertions-and-included-files23960 +Node: Assertions and multiple -f options24293 +Ref: #assertions-and-multiple--f-options24549 +Node: Assertions and commodities24681 +Ref: #assertions-and-commodities24913 +Node: Assertions and prices26069 +Ref: #assertions-and-prices26283 +Node: Assertions and subaccounts26723 +Ref: #assertions-and-subaccounts26952 +Node: Assertions and virtual postings27276 +Ref: #assertions-and-virtual-postings27518 +Node: Assertions and precision27660 +Ref: #assertions-and-precision27853 +Node: Balance Assignments28120 +Ref: #balance-assignments28294 +Node: Balance assignments and prices29459 +Ref: #balance-assignments-and-prices29631 +Node: Directives29855 +Ref: #directives30014 +Node: Comment blocks35693 +Ref: #comment-blocks35838 +Node: Including other files36014 +Ref: #including-other-files36194 +Node: Default year36602 +Ref: #default-year36771 +Node: Declaring commodities37178 +Ref: #declaring-commodities37361 +Node: Default commodity39022 +Ref: #default-commodity39198 +Node: Market prices39832 +Ref: #market-prices39997 +Node: Declaring accounts40838 +Ref: #declaring-accounts41014 +Node: Account comments41939 +Ref: #account-comments42102 +Node: Account subdirectives42526 +Ref: #account-subdirectives42721 +Node: Account types43034 +Ref: #account-types43218 +Node: Account display order44860 +Ref: #account-display-order45030 +Node: Rewriting accounts46181 +Ref: #rewriting-accounts46366 +Node: Basic aliases47092 +Ref: #basic-aliases47238 +Node: Regex aliases47942 +Ref: #regex-aliases48114 +Node: Combining aliases48832 +Ref: #combining-aliases49010 +Node: end aliases50286 +Ref: #end-aliases50434 +Node: Default parent account50535 +Ref: #default-parent-account50701 +Node: Periodic transactions51585 +Ref: #periodic-transactions51784 +Node: Periodic rule syntax53656 +Ref: #periodic-rule-syntax53862 +Node: Two spaces between period expression and description!54566 +Ref: #two-spaces-between-period-expression-and-description54885 +Node: Forecasting with periodic transactions55569 +Ref: #forecasting-with-periodic-transactions55874 +Node: Budgeting with periodic transactions57900 +Ref: #budgeting-with-periodic-transactions58139 +Node: Auto postings / transaction modifiers58588 +Ref: #auto-postings-transaction-modifiers58800 +Node: Auto postings and dates61029 +Ref: #auto-postings-and-dates61286 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions61461 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61836 +Node: Auto posting tags62214 +Ref: #auto-posting-tags62453  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 18a74f98e..9c42aa1db 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -26,108 +26,80 @@ DESCRIPTION also edit the journal file directly with a text editor, perhaps as- sisted by the helper modes for emacs or vim. - Here's an example: - - ; A sample journal file. This is a comment. - - 2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description - assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name - income:salary $-1 ; followed by at least two spaces and an amount - - 2008/06/01 gift - assets:bank:checking $1 ; <- at least two postings in a transaction - income:gifts $-1 ; <- their amounts must balance to 0 - - 2008/06/02 save - assets:bank:saving $1 - assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred - - 2008/06/03 eat & shop ; <- description can be anything - expenses:food $1 - expenses:supplies $1 ; <- this transaction debits two expense accounts - assets:cash ; <- $-2 inferred - - 2008/10/01 take a loan - assets:bank:checking $1 - liabilities:debts $-1 - - 2008/12/31 * pay off ; <- an optional * or ! after the date means "cleared" (or anything you want) - liabilities:debts $1 - assets:bank:checking + Helper modes exist for popular text editors, which make working with + journal files easier. They add colour, formatting, tab completion, and + helpful commands, and are quite recommended if you edit your journal + with a text editor. They include ledger-mode or hledger-mode for + Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and + others. See the Editor configuration at hledger.org for the latest in- + formation. FILE FORMAT + Here's a description of each part of the file format (and hledger's + data model). These are mostly in the order you'll use them, but in + some cases related concepts have been grouped together for easy refer- + ence, or linked before they are introduced, so feel free to skip over + anything that looks unnecessary right now. + Transactions - Transactions are movements of some quantity of commodities between - named accounts. Each transaction is represented by a journal entry be- - ginning with a simple date in column 0. This can be followed by any of - the following, separated by spaces: + Transactions are the main unit of information in a journal file. They + represent events, typically a movement of some quantity of commodities + between two or more named accounts. - o (optional) a status character (empty, !, or *) + Each transaction is recorded as a journal entry, beginning with a sim- + ple date in column 0. This can be followed by any of the following op- + tional fields, separated by spaces: - o (optional) a transaction code (any short number or text, enclosed in - parentheses) + o a status character (empty, !, or *) - o (optional) a transaction description (any remaining text until end of - line or a semicolon) + o a code (any short number or text, enclosed in parentheses) - o (optional) a transaction comment (any remaining text following a - semicolon until end of line) + o a description (any remaining text until end of line or a semicolon) - Then comes zero or more (but usually at least 2) indented lines repre- - senting... + o a comment (any remaining text following a semicolon until end of + line, and any following indented lines beginning with a semicolon) - Postings - A posting is an addition of some amount to, or removal of some amount - from, an account. Each posting line begins with at least one space or - tab (2 or 4 spaces is common), followed by: + o 0 or more indented posting lines, describing what was transferred and + the accounts involved. - o (optional) a status character (empty, !, or *), followed by a space + Here's a simple journal file containing one transaction: - o (required) an account name (any text, optionally containing single - spaces, until end of line or a double space) - - o (optional) two or more spaces or tabs followed by an amount. - - Positive amounts are being added to the account, negative amounts are - being removed. - - The amounts within a transaction must always sum up to zero. As a con- - venience, one amount may be left blank; it will be inferred so as to - balance the transaction. - - Be sure to note the unusual two-space delimiter between account name - and amount. This makes it easy to write account names containing spa- - ces. But if you accidentally leave only one space (or tab) before the - amount, the amount will be considered part of the account name. + 2008/01/01 income + assets:bank:checking $1 + income:salary $-1 Dates Simple dates - Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) - Leading zeros are optional. The year may be omitted, in which case it - will be inferred from the context - the current transaction, the de- - fault year set with a default year directive, or the current date when - the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31, - 2010.1.31. + Dates in the journal file use simple dates format: YYYY-MM-DD or + YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be + omitted, in which case it will be inferred from the context: the cur- + rent transaction, the default year set with a default year directive, + or the current date when the command is run. Some examples: + 2010-01-31, 2010/01/31, 2010.1.31, 1/31. + + (The UI also accepts simple dates, as well as the more flexible smart + dates documented in the hledger manual.) Secondary dates - Real-life transactions sometimes involve more than one date - eg the + Real-life transactions sometimes involve more than one date - eg the date you write a cheque, and the date it clears in your bank. When you - want to model this, eg for more accurate balances, you can specify in- - dividual posting dates, which I recommend. Or, you can use the sec- - ondary dates (aka auxiliary/effective dates) feature, supported for - compatibility with Ledger. + want to model this, eg for more accurate balances, you can specify in- + dividual posting dates. - A secondary date can be written after the primary date, separated by an - equals sign. The primary date, on the left, is used by default; the - secondary date, on the right, is used when the --date2 flag is speci- - fied (--aux-date or --effective also work). + Or, you can use the older secondary date feature. (Ledger calls it + auxiliary date or effective date.) But I would recommend avoiding this + feature; posting dates are almost always clearer and simpler. We sup- + port it mainly for compatibility. - The meaning of secondary dates is up to you, but it's best to follow a - consistent rule. Eg write the bank's clearing date as primary, and - when needed, the date the transaction was initiated as secondary. + A secondary date is written after the primary date, following an equals + sign. The primary date's year will be used if the year is omitted. + When running reports, the primary (left) date is used by default, but + with the --date2 flag (or --aux-date or --effective), the secondary + (right) date will be used instead. - Here's an example. Note that a secondary date will use the year of the - primary date if unspecified. + The meaning of secondary dates is up to you, but it's best to follow a + consistent rule. Eg "primary = the bank's clearing date, secondary = + date the transaction was initiated, if different", as shown here: 2010/2/23=2/19 movie ticket expenses:cinema $10 @@ -139,12 +111,6 @@ FILE FORMAT $ hledger register checking --date2 2010-02-19 movie ticket assets:checking $-10 $-10 - Secondary dates require some effort; you must use them consistently in - your journal entries and remember whether to use or not use the --date2 - flag for your reports. They are included in hledger for Ledger compat- - ibility, but posting dates are a more powerful and less confusing al- - ternative. - Posting dates You can give individual postings a different date from their parent transaction, by adding a posting comment containing a tag (see below) @@ -233,358 +199,6 @@ FILE FORMAT ter the first |). This may be worthwhile if you need to do more pre- cise querying and pivoting by payee or by note. - Account names - Account names typically have several parts separated by a full colon, - from which hledger derives a hierarchical chart of accounts. They can - be anything you like, but in finance there are traditionally five top- - level accounts: assets, liabilities, income, expenses, and equity. - - Account names may contain single spaces, eg: assets:accounts receiv- - able. Because of this, they must always be followed by two or more - spaces (or newline). - - Account names can be aliased. - - Amounts - After the account name, there is usually an amount. (Important: 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- - tity"): - - 1 - - ..and usually a currency or commodity name (the "commodity"). This is - a symbol, word, or phrase, to the left or right of the quantity, with - or without a separating space: - - $1 - 4000 AAPL - - If the commodity name contains spaces, numbers, or punctuation, it must - be enclosed in double quotes: - - 3 "no. 42 green apples" - - Amounts can be negative. The minus sign can be written before or after - a left-side commodity symbol: - - -$1 - $-1 - - Scientific E notation is allowed: - - 1E-6 - EUR 1E3 - - A decimal mark (decimal point) can be written with a period or a comma: - - 1.23 - 1,23456780000009 - - Digit group marks - In the integer part of the quantity (left of the decimal mark), groups - of digits can optionally be separated by a "digit group mark" - a - space, comma, or period (different from the decimal mark): - - $1,000,000.00 - EUR 2.000.000,00 - INR 9,99,99,999.00 - 1 000 000.9455 - - Note, a number containing a single group mark and no decimal mark is - ambiguous. Are these group marks or decimal marks ? - - 1,000 - 1.000 - - hledger will treat them both as decimal marks by default (cf #793). If - you use digit group marks, to prevent confusion and undetected typos we - recommend you write commodity directives at the top of the file to ex- - plicitly declare the decimal mark (and optionally a digit group mark). - Note, these formats ("amount styles") are specific to each commodity, - so if your data uses multiple formats, hledger can handle it: - - commodity $1,000.00 - commodity EUR 1.000,00 - commodity INR 9,99,99,999.00 - commodity 1 000 000.9455 - - Amount display format - For each commodity, hledger chooses a consistent format to use when - displaying amounts. (Except price amounts, which are always displayed - as written). The display format is chosen as follows: - - o If there is a commodity directive for the commodity, that format is - used (see examples above). - - o Otherwise the format of the first posting amount in that commodity - seen in the journal is used. But the number of decimal places ("pre- - cision") will be the maximum from all posting amounts in that comm- - modity. - - o Or if there are no such amounts in the journal, a default format is - used (like $1000.00). - - Price amounts, and amounts in D directives don't affect the amount dis- - play format directly, but occasionally they can do so indirectly. (Eg - when D's default commodity is applied to a commodity-less amount, or - when an amountless posting is balanced using a price's commodity, or - when -V is used.) If you find this causing problems, use a commodity - directive to set the display format. - - Virtual Postings - When you parenthesise the account name in a posting, we call that a - virtual posting, which means: - - o it is ignored when checking that the transaction is balanced - - o it is excluded from reports when the --real/-R flag is used, or the - real:1 query. - - You could use this, eg, to set an account's opening balance without - needing to use the equity:opening balances account: - - 1/1 special unbalanced posting to set initial balance - (assets:checking) $1000 - - When the account name is bracketed, we call it a balanced virtual post- - ing. This is like an ordinary virtual posting except the balanced vir- - tual postings in a transaction must balance to 0, like the real post- - ings (but separately from them). Balanced virtual postings are also - excluded by --real/-R or real:1. - - 1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere - expenses:food $10 - assets:cash $-10 - [assets:checking:available] $10 - [assets:checking:budget:food] $-10 - - Virtual postings have some legitimate uses, but those are few. You can - usually find an equivalent journal entry using real postings, which is - more correct and provides better error checking. - - Balance Assertions - hledger supports Ledger-style balance assertions in journal files. - These look like, for example, = EXPECTEDBALANCE following a posting's - amount. Eg here we assert the expected dollar balance in accounts a - and b after each posting: - - 2013/1/1 - a $1 =$1 - b =$-1 - - 2013/1/2 - a $1 =$2 - b $-1 =$-2 - - After reading a journal file, hledger will check all balance assertions - and report an error if any of them fail. Balance assertions can pro- - tect you from, eg, inadvertently disrupting reconciled balances while - cleaning up old entries. You can disable them temporarily with the - -I/--ignore-assertions flag, which can be useful for troubleshooting or - for reading Ledger files. (Note: this flag currently does not disable - balance assignments, below). - - Assertions and ordering - hledger sorts an account's postings and assertions first by date and - then (for postings on the same day) by parse order. Note this is dif- - ferent from Ledger, which sorts assertions only by parse order. (Also, - Ledger assertions do not see the accumulated effect of repeated post- - ings to the same account within a transaction.) - - So, hledger balance assertions keep working if you reorder differently- - dated transactions within the journal. But if you reorder same-dated - transactions or postings, assertions might break and require updating. - This order dependence does bring an advantage: precise control over the - order of postings and assertions within a day, so you can assert intra- - day balances. - - Assertions and included files - With included files, things are a little more complicated. Including - preserves the ordering of postings and assertions. If you have multi- - ple postings to an account on the same day, split across different - files, and you also want to assert the account's balance on the same - day, you'll have to put the assertion in the right file. - - Assertions and multiple -f options - Balance assertions don't work well across files specified with multiple - -f options. Use include or concatenate the files instead. - - Assertions and commodities - The asserted balance must be a simple single-commodity amount, and in - fact the assertion checks only this commodity's balance within the - (possibly multi-commodity) account balance. - This is how assertions work in Ledger also. We could call this a "par- - tial" balance assertion. - - To assert the balance of more than one commodity in an account, you can - write multiple postings, each asserting one commodity's balance. - - You can make a stronger "total" balance assertion by writing a double - equals sign (== EXPECTEDBALANCE). This asserts that there are no other - unasserted commodities in the account (or, that their balance is 0). - - 2013/1/1 - a $1 - a 1EUR - b $-1 - c -1EUR - - 2013/1/2 ; These assertions succeed - a 0 = $1 - a 0 = 1EUR - b 0 == $-1 - c 0 == -1EUR - - 2013/1/3 ; This assertion fails as 'a' also contains 1EUR - a 0 == $1 - - It's not yet possible to make a complete assertion about a balance that - has multiple commodities. One workaround is to isolate each commodity - into its own subaccount: - - 2013/1/1 - a:usd $1 - a:euro 1EUR - b - - 2013/1/2 - a 0 == 0 - a:usd 0 == $1 - a:euro 0 == 1EUR - - Assertions and prices - Balance assertions ignore transaction prices, and should normally be - written without one: - - 2019/1/1 - (a) $1 @ EUR1 = $1 - - We do allow prices to be written there, however, and print shows them, - even though they don't affect whether the assertion passes or fails. - This is for backward compatibility (hledger's close command used to - generate balance assertions with prices), and because balance assign- - ments do use them (see below). - - Assertions and subaccounts - The balance assertions above (= and ==) do not count the balance from - subaccounts; they check the account's exclusive balance only. You can - assert the balance including subaccounts by writing =* or ==*, eg: - - 2019/1/1 - equity:opening balances - checking:a 5 - checking:b 5 - checking 1 ==* 11 - - Assertions and virtual postings - Balance assertions are checked against all postings, both real and vir- - tual. They are not affected by the --real/-R flag or real: query. - - Assertions and precision - Balance assertions compare the exactly calculated amounts, which are - not always what is shown by reports. Eg a commodity directive may - limit the display precision, but this will not affect balance asser- - tions. Balance assertion failure messages show exact amounts. - - Balance Assignments - Ledger-style balance assignments are also supported. These are like - balance assertions, but with no posting amount on the left side of the - equals sign; instead it is calculated automatically so as to satisfy - the assertion. This can be a convenience during data entry, eg when - setting opening balances: - - ; starting a new journal, set asset account balances - 2016/1/1 opening balances - assets:checking = $409.32 - assets:savings = $735.24 - assets:cash = $42 - equity:opening balances - - or when adjusting a balance to reality: - - ; no cash left; update balance, record any untracked spending as a generic expense - 2016/1/15 - assets:cash = $0 - expenses:misc - - The calculated amount depends on the account's balance in the commodity - at that point (which depends on the previously-dated postings of the - commodity to that account since the last balance assertion or assign- - ment). Note that using balance assignments makes your journal a little - less explicit; to know the exact amount posted, you have to run hledger - or do the calculations yourself, instead of just reading it. - - Balance assignments and prices - A transaction price in a balance assignment will cause the calculated - amount to have that price attached: - - 2019/1/1 - (a) = $1 @ EUR2 - - $ hledger print --explicit - 2019-01-01 - (a) $1 @ EUR2 = $1 @ EUR2 - - Transaction prices - Within a transaction, you can note an amount's price in another commod- - ity. This can be used to document the cost (in a purchase) or selling - price (in a sale). For example, transaction prices are useful to - record purchases of a foreign currency. Note transaction prices are - fixed at the time of the transaction, and do not change over time. See - also market prices, which represent prevailing exchange rates on a cer- - tain date. - - There are several ways to record a transaction price: - - 1. Write the price per unit, as @ UNITPRICE after the amount: - - 2009/1/1 - assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each - assets:dollars ; balancing amount is -$135.00 - - 2. Write the total price, as @@ TOTALPRICE after the amount: - - 2009/1/1 - assets:euros EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot - assets:dollars - - 3. Specify amounts for all postings, using exactly two commodities, and - let hledger infer the price that balances the transaction: - - 2009/1/1 - assets:euros EUR100 ; one hundred euros purchased - assets:dollars $-135 ; for $135 - - (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- - PRICE}, which hledger currently ignores). - - Use the -B/--cost flag to convert amounts to their transaction price's - commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). - Eg here is how -B affects the balance report for the example above: - - $ hledger bal -N --flat - $-135 assets:dollars - EUR100 assets:euros - $ hledger bal -N --flat -B - $-135 assets:dollars - $135 assets:euros # <- the euros' cost - - Note -B is sensitive to the order of postings when a transaction price - is inferred: the inferred price will be in the commodity of the last - amount. So if example 3's postings are reversed, while the transaction - is equivalent, -B shows something different: - - 2009/1/1 - assets:dollars $-135 ; 135 dollars sold - assets:euros EUR100 ; for 100 euros - - $ hledger bal -N --flat -B - EUR-100 assets:dollars # <- the dollars' selling price - EUR100 assets:euros - Comments Lines in the journal beginning with a semicolon (;) or hash (#) or star (*) are comments, and will be ignored. (Star comments cause org-mode @@ -661,75 +275,455 @@ FILE FORMAT Tags are like Ledger's metadata feature, except hledger's tag values are simple strings. + Postings + A posting is an addition of some amount to, or removal of some amount + from, an account. Each posting line begins with at least one space or + tab (2 or 4 spaces is common), followed by: + + o (optional) a status character (empty, !, or *), followed by a space + + o (required) an account name (any text, optionally containing single + spaces, until end of line or a double space) + + o (optional) two or more spaces or tabs followed by an amount. + + Positive amounts are being added to the account, negative amounts are + being removed. + + The amounts within a transaction must always sum up to zero. As a con- + venience, one amount may be left blank; it will be inferred so as to + balance the transaction. + + Be sure to note the unusual two-space delimiter between account name + and amount. This makes it easy to write account names containing spa- + ces. But if you accidentally leave only one space (or tab) before the + amount, the amount will be considered part of the account name. + + Virtual Postings + A posting with a parenthesised account name is called a virtual posting + or unbalanced posting, which means it is exempt from the usual rule + that a transaction's postings must balance add up to zero. + + This is not part of double entry accounting, so you might choose to + avoid this feature. Or you can use it sparingly for certain special + cases where it can be convenient. Eg, you could set opening balances + without using a balancing equity account: + + 1/1 opening balances + (assets:checking) $1000 + (assets:savings) $2000 + + A posting with a bracketed account name is called a balanced virtual + posting. The balanced virtual postings in a transaction must add up to + zero (separately from other postings). Eg: + + 1/1 buy food with cash, update budget envelope subaccounts, & something else + assets:cash $-10 ; <- these balance + expenses:food $7 ; <- + expenses:food $3 ; <- + [assets:checking:budget:food] $-10 ; <- and these balance + [assets:checking:available] $10 ; <- + (something:else) $5 ; <- not required to balance + + Ordinary non-parenthesised, non-bracketed postings are called real + postings. You can exclude virtual postings from reports with the + -R/--real flag or real:1 query. + + Account names + Account names typically have several parts separated by a full colon, + from which hledger derives a hierarchical chart of accounts. They can + be anything you like, but in finance there are traditionally five top- + level accounts: assets, liabilities, income, expenses, and equity. + + Account names may contain single spaces, eg: assets:accounts receiv- + able. Because of this, they must always be followed by two or more + spaces (or newline). + + Account names can be aliased. + + Amounts + After the account name, there is usually an amount. (Important: 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- + tity"): + + 1 + + ..and usually a currency or commodity name (the "commodity"). This is + a symbol, word, or phrase, to the left or right of the quantity, with + or without a separating space: + + $1 + 4000 AAPL + + If the commodity name contains spaces, numbers, or punctuation, it must + be enclosed in double quotes: + + 3 "no. 42 green apples" + + Amounts can be negative. The minus sign can be written before or after + a left-side commodity symbol: + + -$1 + $-1 + + Scientific E notation is allowed: + + 1E-6 + EUR 1E3 + + A decimal mark (decimal point) can be written with a period or a comma: + + 1.23 + 1,23456780000009 + + Digit group marks + In the integer part of the quantity (left of the decimal mark), groups + of digits can optionally be separated by a "digit group mark" - a + space, comma, or period (different from the decimal mark): + + $1,000,000.00 + EUR 2.000.000,00 + INR 9,99,99,999.00 + 1 000 000.9455 + + Note, a number containing a single group mark and no decimal mark is + ambiguous. Are these group marks or decimal marks ? + + 1,000 + 1.000 + + hledger will treat them both as decimal marks by default (cf #793). If + you use digit group marks, to prevent confusion and undetected typos we + recommend you write commodity directives at the top of the file to ex- + plicitly declare the decimal mark (and optionally a digit group mark). + Note, these formats ("amount styles") are specific to each commodity, + so if your data uses multiple formats, hledger can handle it: + + commodity $1,000.00 + commodity EUR 1.000,00 + commodity INR 9,99,99,999.00 + commodity 1 000 000.9455 + + Amount display format + For each commodity, hledger chooses a consistent format to use when + displaying amounts. (Except price amounts, which are always displayed + as written). The display format is chosen as follows: + + o If there is a commodity directive for the commodity, that format is + used (see examples above). + + o Otherwise the format of the first posting amount in that commodity + seen in the journal is used. But the number of decimal places ("pre- + cision") will be the maximum from all posting amounts in that comm- + modity. + + o Or if there are no such amounts in the journal, a default format is + used (like $1000.00). + + Price amounts, and amounts in D directives don't affect the amount dis- + play format directly, but occasionally they can do so indirectly. (Eg + when D's default commodity is applied to a commodity-less amount, or + when an amountless posting is balanced using a price's commodity, or + when -V is used.) If you find this causing problems, use a commodity + directive to set the display format. + + Transaction prices + Within a transaction, you can note an amount's price in another commod- + ity. This can be used to document the cost (in a purchase) or selling + price (in a sale). For example, transaction prices are useful to + record purchases of a foreign currency. Note transaction prices are + fixed at the time of the transaction, and do not change over time. See + also market prices, which represent prevailing exchange rates on a cer- + tain date. + + There are several ways to record a transaction price: + + 1. Write the price per unit, as @ UNITPRICE after the amount: + + 2009/1/1 + assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each + assets:dollars ; balancing amount is -$135.00 + + 2. Write the total price, as @@ TOTALPRICE after the amount: + + 2009/1/1 + assets:euros EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot + assets:dollars + + 3. Specify amounts for all postings, using exactly two commodities, and + let hledger infer the price that balances the transaction: + + 2009/1/1 + assets:euros EUR100 ; one hundred euros purchased + assets:dollars $-135 ; for $135 + + (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- + PRICE}, which hledger currently ignores). + + Use the -B/--cost flag to convert amounts to their transaction price's + commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger). + Eg here is how -B affects the balance report for the example above: + + $ hledger bal -N --flat + $-135 assets:dollars + EUR100 assets:euros + $ hledger bal -N --flat -B + $-135 assets:dollars + $135 assets:euros # <- the euros' cost + + Note -B is sensitive to the order of postings when a transaction price + is inferred: the inferred price will be in the commodity of the last + amount. So if example 3's postings are reversed, while the transaction + is equivalent, -B shows something different: + + 2009/1/1 + assets:dollars $-135 ; 135 dollars sold + assets:euros EUR100 ; for 100 euros + + $ hledger bal -N --flat -B + EUR-100 assets:dollars # <- the dollars' selling price + EUR100 assets:euros + + Balance Assertions + hledger supports Ledger-style balance assertions in journal files. + These look like, for example, = EXPECTEDBALANCE following a posting's + amount. Eg here we assert the expected dollar balance in accounts a + and b after each posting: + + 2013/1/1 + a $1 =$1 + b =$-1 + + 2013/1/2 + a $1 =$2 + b $-1 =$-2 + + After reading a journal file, hledger will check all balance assertions + and report an error if any of them fail. Balance assertions can pro- + tect you from, eg, inadvertently disrupting reconciled balances while + cleaning up old entries. You can disable them temporarily with the + -I/--ignore-assertions flag, which can be useful for troubleshooting or + for reading Ledger files. (Note: this flag currently does not disable + balance assignments, below). + + Assertions and ordering + hledger sorts an account's postings and assertions first by date and + then (for postings on the same day) by parse order. Note this is dif- + ferent from Ledger, which sorts assertions only by parse order. (Also, + Ledger assertions do not see the accumulated effect of repeated post- + ings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder differently- + dated transactions within the journal. But if you reorder same-dated + transactions or postings, assertions might break and require updating. + This order dependence does bring an advantage: precise control over the + order of postings and assertions within a day, so you can assert intra- + day balances. + + Assertions and included files + With included files, things are a little more complicated. Including + preserves the ordering of postings and assertions. If you have multi- + ple postings to an account on the same day, split across different + files, and you also want to assert the account's balance on the same + day, you'll have to put the assertion in the right file. + + Assertions and multiple -f options + Balance assertions don't work well across files specified with multiple + -f options. Use include or concatenate the files instead. + + Assertions and commodities + The asserted balance must be a simple single-commodity amount, and in + fact the assertion checks only this commodity's balance within the + (possibly multi-commodity) account balance. + This is how assertions work in Ledger also. We could call this a "par- + tial" balance assertion. + + To assert the balance of more than one commodity in an account, you can + write multiple postings, each asserting one commodity's balance. + + You can make a stronger "total" balance assertion by writing a double + equals sign (== EXPECTEDBALANCE). This asserts that there are no other + unasserted commodities in the account (or, that their balance is 0). + + 2013/1/1 + a $1 + a 1EUR + b $-1 + c -1EUR + + 2013/1/2 ; These assertions succeed + a 0 = $1 + a 0 = 1EUR + b 0 == $-1 + c 0 == -1EUR + + 2013/1/3 ; This assertion fails as 'a' also contains 1EUR + a 0 == $1 + + It's not yet possible to make a complete assertion about a balance that + has multiple commodities. One workaround is to isolate each commodity + into its own subaccount: + + 2013/1/1 + a:usd $1 + a:euro 1EUR + b + + 2013/1/2 + a 0 == 0 + a:usd 0 == $1 + a:euro 0 == 1EUR + + Assertions and prices + Balance assertions ignore transaction prices, and should normally be + written without one: + + 2019/1/1 + (a) $1 @ EUR1 = $1 + + We do allow prices to be written there, however, and print shows them, + even though they don't affect whether the assertion passes or fails. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance assign- + ments do use them (see below). + + Assertions and subaccounts + The balance assertions above (= and ==) do not count the balance from + subaccounts; they check the account's exclusive balance only. You can + assert the balance including subaccounts by writing =* or ==*, eg: + + 2019/1/1 + equity:opening balances + checking:a 5 + checking:b 5 + checking 1 ==* 11 + + Assertions and virtual postings + Balance assertions are checked against all postings, both real and vir- + tual. They are not affected by the --real/-R flag or real: query. + + Assertions and precision + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- + tions. Balance assertion failure messages show exact amounts. + + Balance Assignments + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when + setting opening balances: + + ; starting a new journal, set asset account balances + 2016/1/1 opening balances + assets:checking = $409.32 + assets:savings = $735.24 + assets:cash = $42 + equity:opening balances + + or when adjusting a balance to reality: + + ; no cash left; update balance, record any untracked spending as a generic expense + 2016/1/15 + assets:cash = $0 + expenses:misc + + The calculated amount depends on the account's balance in the commodity + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- + ment). Note that using balance assignments makes your journal a little + less explicit; to know the exact amount posted, you have to run hledger + or do the calculations yourself, instead of just reading it. + + Balance assignments and prices + A transaction price in a balance assignment will cause the calculated + amount to have that price attached: + + 2019/1/1 + (a) = $1 @ EUR2 + + $ hledger print --explicit + 2019-01-01 + (a) $1 @ EUR2 = $1 @ EUR2 + Directives - A directive is a line in the journal beginning with a special keyword, + A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. hledger's directives are based on a subset of Ledger's, but there are many differences (and also some differences between hledger versions). Directives' behaviour and interactions can get a little bit complex, so - here is a table summarising the directives and their effects, with + here is a table summarising the directives and their effects, with links to more detailed docs. - direc- end di- subdi- purpose can affect (as of + direc- end di- subdi- purpose can affect (as of tive rective rec- 2018/06) tives ------------------------------------------------------------------------------------ - account any document account names, de- all entries in all - text clare account types & dis- files, before or + account any document account names, de- all entries in all + text clare account types & dis- files, before or play order after alias end rewrite account names following in- aliases line/included en- - tries until end of + tries until end of current file or end directive - apply end apply prepend a common parent to following in- + + + + + + apply end apply prepend a common parent to following in- account account account names line/included en- - tries until end of + tries until end of current file or end directive comment end com- ignore part of journal following in- ment line/included en- - tries until end of + tries until end of current file or end directive - commod- format declare a commodity and its number notation: + commod- format declare a commodity and its number notation: ity number notation & display following entries style in that commodity - in all files; dis- + in all files; dis- play style: amounts of that commodity in reports - D declare a commodity to be default commodity: + D declare a commodity to be default commodity: used for commodityless following commod- - amounts, and its number no- ityless entries un- - tation & display style til end of current - file; number nota- + amounts, and its number no- ityless entries un- + tation & display style til end of current + file; number nota- tion: following en- - tries in that com- + tries in that com- modity until end of - current file; dis- + current file; dis- play style: amounts of that commodity in reports include include entries/directives what the included from another file directives affect P declare a market price for a amounts of that - commodity commodity in re- - ports, when -V is + commodity commodity in re- + ports, when -V is used - Y declare a year for yearless following in- + Y declare a year for yearless following in- dates line/included en- - tries until end of + tries until end of current file And some definitions: subdirec- optional indented directive line immediately following a par- tive ent directive - number how to interpret numbers when parsing journal entries (the - notation identity of the decimal separator character). (Currently - each commodity can have its own notation, even in the same + number how to interpret numbers when parsing journal entries (the + notation identity of the decimal separator character). (Currently + each commodity can have its own notation, even in the same file.) display how to display amounts of a commodity in reports (symbol side style and spacing, digit groups, decimal separator, decimal places) @@ -740,34 +734,34 @@ FILE FORMAT affect, and whether they are focussed on input (parsing) or output (re- ports). Some directives have multiple effects. - If you have a journal made up of multiple files, or pass multiple -f - options on the command line, note that directives which affect input - typically last only until the end of their defining file. This pro- + If you have a journal made up of multiple files, or pass multiple -f + options on the command line, note that directives which affect input + typically last only until the end of their defining file. This pro- vides more simplicity and predictability, eg reports are not changed by - writing file options in a different order. It can be surprising at + writing file options in a different order. It can be surprising at times though. Comment blocks - A line containing just comment starts a commented region of the file, + A line containing just comment starts a commented region of the file, and a line containing just end comment (or the end of the current file) ends it. See also comments. Including other files - You can pull in the content of additional files by writing an include + You can pull in the content of additional files by writing an include directive, like this: include path/to/file.journal - If the path does not begin with a slash, it is relative to the current - file. The include file path may contain common glob patterns (e.g. + If the path does not begin with a slash, it is relative to the current + file. The include file path may contain common glob patterns (e.g. *). - The include directive can only be used in journal files. It can in- + The include directive can only be used in journal files. It can in- clude journal, timeclock or timedot files, but not CSV files. Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. Eg: Y2009 ; set default year to 2009 @@ -789,18 +783,18 @@ FILE FORMAT Declaring commodities The commodity directive has several functions: - 1. It declares commodities which may be used in the journal. This is + 1. It declares commodities which may be used in the journal. This is currently not enforced, but can serve as documentation. 2. It declares what decimal mark character to expect when parsing input - - useful to disambiguate international number formats in your data. + - useful to disambiguate international number formats in your data. (Without this, hledger will parse both 1,000 and 1.000 as 1). 3. It declares the amount display format to use in output - decimal and digit group marks, number of decimal places, symbol placement etc. - You are likely to run into one of the problems solved by commodity di- - rectives, sooner or later, so it's a good idea to just always use them + You are likely to run into one of the problems solved by commodity di- + rectives, sooner or later, so it's a good idea to just always use them to declare your commodities. A commodity directive is just the word commodity followed by an amount. @@ -813,8 +807,8 @@ FILE FORMAT ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. (In this case - the commodity symbol appears twice and should be the same in both + or on multiple lines, using the "format" subdirective. (In this case + the commodity symbol appears twice and should be the same in both places.): ; commodity SYMBOL @@ -827,14 +821,14 @@ FILE FORMAT format INR 1,00,00,000.00 The quantity of the amount does not matter; only the format is signifi- - cant. The number must include a decimal mark: either a period or a + cant. The number must include a decimal mark: either a period or a comma, followed by 0 or more decimal digits. Default commodity - The D directive sets a default commodity (and display format), to be + The D directive sets a default commodity (and display format), to be used for amounts without a commodity symbol (ie, plain numbers). (Note - this differs from Ledger's default commodity directive.) The commodity - and display format will be applied to all subsequent commodity-less + this differs from Ledger's default commodity directive.) The commodity + and display format will be applied to all subsequent commodity-less amounts, or until the next D directive. ; commodity-less amounts should be treated as dollars @@ -849,9 +843,9 @@ FILE FORMAT a decimal point. Market prices - The P directive declares a market price, which is an exchange rate be- - tween two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, + The P directive declares a market price, which is an exchange rate be- + tween two commodities on a certain date. (In Ledger, they are called + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. Here is the format: @@ -862,16 +856,16 @@ FILE FORMAT o COMMODITYA is the symbol of the commodity being priced - o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- + o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- modity, giving the price in commodity B of one unit of commodity A. - These two market price directives say that one euro was worth 1.35 US + These two market price directives say that one euro was worth 1.35 US dollars during 2009, and $1.40 from 2010 onward: P 2009/1/1 EUR $1.35 P 2010/1/1 EUR $1.40 - The -V/--value flag can be used to convert reported amounts to another + The -V/--value flag can be used to convert reported amounts to another commodity using these prices. Declaring accounts @@ -881,20 +875,20 @@ FILE FORMAT o They can document your intended chart of accounts, providing a refer- ence. - o They can store extra information about accounts (account numbers, + o They can store extra information about accounts (account numbers, notes, etc.) - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), useful for reports like balancesheet and + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and incomestatement. - o They control account display order in reports, allowing non-alpha- + o They control account display order in reports, allowing non-alpha- betic sorting (eg Revenues to appear above Expenses). - o They help with account name completion in the add command, hledger- + o They help with account name completion in the add command, hledger- iadd, hledger-web, ledger-mode etc. - The simplest form is just the word account followed by a hledger-style + The simplest form is just the word account followed by a hledger-style account name, eg: account assets:bank:checking @@ -902,7 +896,7 @@ FILE FORMAT Account comments Comments, beginning with a semicolon, can be added: - o on the same line, after two or more spaces (because ; is allowed in + o on the same line, after two or more spaces (because ; is allowed in account names) o on the next lines, indented @@ -916,7 +910,7 @@ FILE FORMAT Same-line comments are not supported by Ledger, or hledger <1.13. Account subdirectives - We also allow (and ignore) Ledger-style indented subdirectives, just + We also allow (and ignore) Ledger-style indented subdirectives, just for compatibility.: account assets:bank:checking @@ -929,18 +923,18 @@ FILE FORMAT [LEDGER-STYLE SUBDIRECTIVES, IGNORED] Account types - hledger recognises five types (or classes) of account: Asset, Liabil- - ity, Equity, Revenue, Expense. This is used by a few accounting-aware + hledger recognises five types (or classes) of account: Asset, Liabil- + ity, Equity, Revenue, Expense. This is used by a few accounting-aware reports such as balancesheet, incomestatement and cashflow. Auto-detected account types If you name your top-level accounts with some variation of assets, lia- - bilities/debts, equity, revenues/income, or expenses, their types are + bilities/debts, equity, revenues/income, or expenses, their types are detected automatically. Account types declared with tags - More generally, you can declare an account's type with an account di- - rective, by writing a type: tag in a comment, followed by one of the + More generally, you can declare an account's type with an account di- + rective, by writing a type: tag in a comment, followed by one of the words Asset, Liability, Equity, Revenue, Expense, or one of the letters ALERX (case insensitive): @@ -951,8 +945,8 @@ FILE FORMAT account expenses ; type:Expenses Account types declared with account type codes - Or, you can write one of those letters separated from the account name - by two or more spaces, but this should probably be considered depre- + Or, you can write one of those letters separated from the account name + by two or more spaces, but this should probably be considered depre- cated as of hledger 1.13: account assets A @@ -962,7 +956,7 @@ FILE FORMAT account expenses X Overriding auto-detected types - If you ever override the types of those auto-detected english account + If you ever override the types of those auto-detected english account names mentioned above, you might need to help the reports a bit. Eg: ; make "liabilities" not have the liability type - who knows why @@ -973,8 +967,8 @@ FILE FORMAT account - ; type:L Account display order - Account directives also set the order in which accounts are displayed, - eg in reports, the hledger-ui accounts screen, and the hledger-web + Account directives also set the order in which accounts are displayed, + eg in reports, the hledger-ui accounts screen, and the hledger-web sidebar. By default accounts are listed in alphabetical order. But if you have these account directives in the journal: @@ -996,18 +990,21 @@ FILE FORMAT Undeclared accounts, if any, are displayed last, in alphabetical order. - Note that sorting is done at each level of the account tree (within - each group of sibling accounts under the same parent). And currently, + Note that sorting is done at each level of the account tree (within + each group of sibling accounts under the same parent). And currently, this directive: account other:zoo - would influence the position of zoo among other's subaccounts, but not - the position of other among the top-level accounts. This means: - 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). + would influence the position of zoo among other's subaccounts, but not + the position of other among the top-level accounts. This means: + + o you will sometimes declare parent accounts (eg account other above) + that you don't intend to post to, just to customize their display or- + der + + o sibling accounts stay together (you couldn't display x:y in between + a:b and a:c). Rewriting accounts You can define account alias rules which rewrite your account names, or @@ -1383,15 +1380,6 @@ FILE FORMAT o _modified: - a hidden tag not appearing in the comment; this transac- tion was modified "just now". -EDITOR SUPPORT - Helper modes exist for popular text editors, which make working with - journal files easier. They add colour, formatting, tab completion, and - helpful commands, and are quite recommended if you edit your journal - with a text editor. They include ledger-mode or hledger-mode for - Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and - others. See the Editor configuration at hledger.org for the latest in- - formation. - REPORTING BUGS