diff options
Diffstat (limited to 'hledger_journal.5')
| -rw-r--r-- | hledger_journal.5 | 2153 |
1 files changed, 0 insertions, 2153 deletions
diff --git a/hledger_journal.5 b/hledger_journal.5 deleted file mode 100644 index c1b6c53..0000000 --- a/hledger_journal.5 +++ /dev/null @@ -1,2153 +0,0 @@ -.\"t - -.TH "HLEDGER_JOURNAL" "5" "December 2020" "hledger-lib-1.20.4 " "hledger User Manuals" - - - -.SH NAME -.PP -hledger\[aq]s default file format, representing a General Journal. -.SH DESCRIPTION -.PP -hledger\[aq]s usual data source is a plain text file containing journal -entries in hledger journal format. -This file represents a standard accounting general journal. -I use file names ending in \f[C].journal\f[R], but that\[aq]s not -required. -The journal file contains a number of transaction entries, each -describing a transfer of money (or any commodity) between two or more -named accounts, in a simple format readable by both hledger and humans. -.PP -hledger\[aq]s journal format is a compatible subset, mostly, of -ledger\[aq]s journal format, so hledger can work with compatible ledger -journal files as well. -It\[aq]s safe, and encouraged, to run both hledger and ledger on the -same journal file, eg to validate the results you\[aq]re getting. -.PP -You can use hledger without learning any more about this file; just use -the add or web or import commands to create and update it. -.PP -Many users, though, edit the journal file with a text editor, and track -changes with a version control system such as git. -Editor addons such as ledger-mode or hledger-mode for Emacs, vim-ledger -for Vim, and hledger-vscode for Visual Studio Code, make this easier, -adding colour, formatting, tab completion, and useful commands. -See Editor configuration at hledger.org for the full list. -.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. -.SH 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 (indented comment lines are also -allowed, but not blank lines or non-indented lines). -.PP -Here\[aq]s a simple journal file containing one transaction: -.IP -.nf -\f[C] -2008/01/01 income - assets:bank:checking $1 - income:salary $-1 -\f[R] -.fi -.SH DATES -.SS Simple dates -.PP -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 -year directive, or the current date when the command is run. -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, for more accurate daily balances, you can -specify individual posting dates. -.PP -Or, you can use the older \f[I]secondary date\f[R] feature (Ledger calls -it auxiliary date or effective date). -Note: we support this for compatibility, but I usually recommend -avoiding this feature; posting dates are almost always clearer and -simpler. -.PP -A secondary date is written after the primary date, following an equals -sign. -If the year is omitted, the primary date\[aq]s year is assumed. -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 \[dq]primary = the bank\[aq]s clearing date, secondary = date the -transaction was initiated, if different\[dq], as shown here: -.IP -.nf -\f[C] -2010/2/23=2/19 movie ticket - expenses:cinema $10 - assets:checking -\f[R] -.fi -.IP -.nf -\f[C] -$ hledger register checking -2010-02-23 movie ticket assets:checking $-10 $-10 -\f[R] -.fi -.IP -.nf -\f[C] -$ hledger register checking --date2 -2010-02-19 movie ticket assets:checking $-10 $-10 -\f[R] -.fi -.SS Posting dates -.PP -You can give individual postings a different date from their parent -transaction, by adding a posting comment containing a tag (see below) -like \f[C]date:DATE\f[R]. -This is probably the best way to control posting dates precisely. -Eg in this example the expense should appear in May reports, and the -deduction from checking should be reported on 6/1 for easy bank -reconciliation: -.IP -.nf -\f[C] -2015/5/30 - expenses:food $10 ; food purchased on saturday 5/30 - assets:checking ; bank cleared it on monday, date:6/1 -\f[R] -.fi -.IP -.nf -\f[C] -$ hledger -f t.j register food -2015-05-30 expenses:food $10 $10 -\f[R] -.fi -.IP -.nf -\f[C] -$ hledger -f t.j register checking -2015-06-01 assets:checking $-10 $-10 -\f[R] -.fi -.PP -DATE should be a simple date; if the year is not specified it will use -the year of the transaction\[aq]s date. -You can set the secondary date similarly, with \f[C]date2:DATE2\f[R]. -The \f[C]date:\f[R] or \f[C]date2:\f[R] tags must have a valid simple -date value if they are present, eg a \f[C]date:\f[R] tag with no value -is not allowed. -.PP -Ledger\[aq]s earlier, more compact bracketed date syntax is also -supported: \f[C][DATE]\f[R], \f[C][DATE=DATE2]\f[R] or -\f[C][=DATE2]\f[R]. -hledger will attempt to parse any square-bracketed sequence of the -\f[C]0123456789/-.=\f[R] characters in this way. -With this syntax, DATE infers its year from the transaction and DATE2 -infers its year from DATE. -.SH STATUS -.PP -Transactions, or individual postings within a transaction, can have a -status mark, which is a single character before the transaction -description or posting account name, separated from it by a space, -indicating one of three statuses: -.PP -.TS -tab(@); -l l. -T{ -mark \ -T}@T{ -status -T} -_ -T{ -\ -T}@T{ -unmarked -T} -T{ -\f[C]!\f[R] -T}@T{ -pending -T} -T{ -\f[C]*\f[R] -T}@T{ -cleared -T} -.TE -.PP -When reporting, you can filter by status with the -\f[C]-U/--unmarked\f[R], \f[C]-P/--pending\f[R], and -\f[C]-C/--cleared\f[R] flags; or the \f[C]status:\f[R], -\f[C]status:!\f[R], and \f[C]status:*\f[R] queries; or the U, P, C keys -in hledger-ui. -.PP -Note, in Ledger and in older versions of hledger, the \[dq]unmarked\[dq] -state is called \[dq]uncleared\[dq]. -As of hledger 1.3 we have renamed it to unmarked for clarity. -.PP -To replicate Ledger and old hledger\[aq]s behaviour of also matching -pending, combine -U and -P. -.PP -Status marks are optional, but can be helpful eg for reconciling with -real-world accounts. -Some editor modes provide highlighting and shortcuts for working with -status. -Eg in Emacs ledger-mode, you can toggle transaction status with C-c C-e, -or posting status with C-c C-c. -.PP -What \[dq]uncleared\[dq], \[dq]pending\[dq], and \[dq]cleared\[dq] -actually mean is up to you. -Here\[aq]s one suggestion: -.PP -.TS -tab(@); -lw(9.7n) lw(60.3n). -T{ -status -T}@T{ -meaning -T} -_ -T{ -uncleared -T}@T{ -recorded but not yet reconciled; needs review -T} -T{ -pending -T}@T{ -tentatively reconciled (if needed, eg during a big reconciliation) -T} -T{ -cleared -T}@T{ -complete, reconciled as far as possible, and considered correct -T} -.TE -.PP -With this scheme, you would use \f[C]-PC\f[R] to see the current balance -at your bank, \f[C]-U\f[R] to see things which will probably hit your -bank soon (like uncashed checks), and no flags to see the most -up-to-date state of your finances. -.SH DESCRIPTION -.PP -A transaction\[aq]s description is the rest of the line following the -date and status mark (or until a comment begins). -Sometimes called the \[dq]narration\[dq] in traditional bookkeeping, it -can be used for whatever you wish, or left blank. -Transaction descriptions can be queried, unlike comments. -.SS Payee and note -.PP -You can optionally include a \f[C]|\f[R] (pipe) character in -descriptions to subdivide the description into separate fields for -payee/payer name on the left (up to the first \f[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. -.SH 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 -; another file comment -* also a file comment, useful in org/orgstruct mode - -comment -A multiline file comment, which continues -until a line containing just \[dq]end comment\[dq] -(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. -.SH 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. -.SH 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. -.SH ACCOUNT NAMES -.PP -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: \f[C]assets\f[R], \f[C]liabilities\f[R], -\f[C]income\f[R], \f[C]expenses\f[R], and \f[C]equity\f[R]. -.PP -Account names may contain single spaces, eg: -\f[C]assets:accounts receivable\f[R]. -Because of this, they must always be followed by \f[B]two or more -spaces\f[R] (or newline). -.PP -Account names can be aliased. -.SH AMOUNTS -.PP -After the account name, there is usually an amount. -(Important: between account name and amount, there must be \f[B]two or -more spaces\f[R].) -.PP -hledger\[aq]s amount format is flexible, supporting several -international formats. -Here are some examples. -Amounts have a number (the \[dq]quantity\[dq]): -.IP -.nf -\f[C] -1 -\f[R] -.fi -.PP -\&..and usually a currency or commodity name (the \[dq]commodity\[dq]). -This is a symbol, word, or phrase, to the left or right of the quantity, -with or without a separating space: -.IP -.nf -\f[C] -$1 -4000 AAPL -\f[R] -.fi -.PP -If the commodity name contains spaces, numbers, or punctuation, it must -be enclosed in double quotes: -.IP -.nf -\f[C] -3 \[dq]no. 42 green apples\[dq] -\f[R] -.fi -.PP -Amounts can be preceded by a minus sign (or a plus sign, though plus is -the default), The sign can be written before or after a left-side -commodity symbol: -.IP -.nf -\f[C] --$1 -$-1 -\f[R] -.fi -.PP -One or more spaces between the sign and the number are acceptable when -parsing (but they won\[aq]t be displayed in output): -.IP -.nf -\f[C] -+ $1 -$- 1 -\f[R] -.fi -.PP -Scientific E notation is allowed: -.IP -.nf -\f[C] -1E-6 -EUR 1E3 -\f[R] -.fi -.PP -A decimal mark can be written as a period or a comma: -.IP -.nf -\f[C] -1.23 -1,23456780000009 -\f[R] -.fi -.SS Digit group marks -.PP -In the integer part of the quantity (left of the decimal mark), groups -of digits can optionally be separated by a \[dq]digit group mark\[dq] - -a space, comma, or period (different from the decimal mark): -.IP -.nf -\f[C] - $1,000,000.00 - EUR 2.000.000,00 -INR 9,99,99,999.00 - 1 000 000.9455 -\f[R] -.fi -.PP -Note, a number containing a single group mark and no decimal mark is -ambiguous. -Are these group marks or decimal marks ? -.IP -.nf -\f[C] -1,000 -1.000 -\f[R] -.fi -.PP -hledger will treat them both as decimal marks by default (cf #793). -If you use digit group marks, to prevent confusion and undetected typos -we recommend you write commodity directives at the top of the file to -explicitly declare the decimal mark (and optionally a digit group mark). -Note, these formats (\[dq]amount styles\[dq]) are specific to each -commodity, so if your data uses multiple formats, hledger can handle it: -.IP -.nf -\f[C] -commodity $1,000.00 -commodity EUR 1.000,00 -commodity INR 9,99,99,999.00 -commodity 1 000 000.9455 -\f[R] -.fi -.PP -.SS Commodity display style -.PP -For each commodity, hledger chooses a consistent style to use when -displaying amounts. -(Except price amounts, which are always displayed as written). -The display style is chosen as follows: -.IP \[bu] 2 -If there is a commodity directive (or default commodity directive) for -the commodity, its style is used (see examples above). -.IP \[bu] 2 -Otherwise the style is inferred from the amounts in that commodity seen -in the journal. -.IP \[bu] 2 -Or if there are no such amounts in the journal, a default style is used -(like \f[C]$1000.00\f[R]). -.PP -A style is inferred from the journal amounts in a commodity as follows: -.IP \[bu] 2 -Use the general style (decimal mark, symbol placement) of the first -amount -.IP \[bu] 2 -Use the first-seen digit group style (digit group mark, digit group -sizes), if any -.IP \[bu] 2 -Use the maximum number of decimal places of all. -.PP -Transaction price amounts don\[aq]t affect the commodity display style -directly, but occasionally they can do so indirectly (eg when a -posting\[aq]s amount is inferred using a transaction price). -If you find this causing problems, use a commodity directive to fix the -display style. -.PP -In summary, each commodity\[aq]s amounts will be normalised to -.IP \[bu] 2 -the style declared by a \f[C]commodity\f[R] directive -.IP \[bu] 2 -or, the style of the first posting amount in the journal, with the -first-seen digit group style and the maximum-seen number of decimal -places. -.PP -If reports are showing amounts in a way you don\[aq]t like (eg, with too -many decimal places), use a commodity directive to set your preferred -style. -.SS Rounding -.PP -Amounts are stored internally as decimal numbers with up to 255 decimal -places, and displayed with the number of decimal places specified by the -commodity display style. -Note, hledger uses banker\[aq]s rounding: it rounds to the nearest even -number, eg 0.5 displayed with zero decimal places is \[dq]0\[dq]). -(Guaranteed since hledger 1.17.1; in older versions this could vary if -hledger was built with Decimal < 0.5.1.) -.SH 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 -.IP "4." 3 -Like 1, but the \f[C]\[at]\f[R] is parenthesised, i.e. -\f[C](\[at])\f[R]; this is for compatibility with Ledger journals -(Virtual posting costs), and is equivalent to 1 in hledger. -.IP "5." 3 -Like 2, but as in 4 the \f[C]\[at]\[at]\f[R] is parenthesised, i.e. -\f[C](\[at]\[at])\f[R]; in hledger, this is equivalent to 2. -.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 -.SH LOT PRICES, LOT DATES -.PP -Ledger allows another kind of price, lot price (four variants: -\f[C]{UNITPRICE}\f[R], \f[C]{{TOTALPRICE}}\f[R], -\f[C]{=FIXEDUNITPRICE}\f[R], \f[C]{{=FIXEDTOTALPRICE}}\f[R]), and/or a -lot date (\f[C][DATE]\f[R]) to be specified. -These are normally used to select a lot when selling investments. -hledger will parse these, for compatibility with Ledger journals, but -currently ignores them. -A transaction price, lot price and/or lot date may appear in any order, -after the posting amount and before the balance assertion if any. -.SH BALANCE ASSERTIONS -.PP -hledger supports Ledger-style balance assertions in journal files. -These look like, for example, \f[C]= EXPECTEDBALANCE\f[R] following a -posting\[aq]s amount. -Eg here we assert the expected dollar balance in accounts a and b after -each posting: -.IP -.nf -\f[C] -2013/1/1 - a $1 =$1 - b =$-1 - -2013/1/2 - a $1 =$2 - b $-1 =$-2 -\f[R] -.fi -.PP -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 -\f[C]-I/--ignore-assertions\f[R] flag, which can be useful for -troubleshooting or for reading Ledger files. -(Note: this flag currently does not disable balance assignments, below). -.SS Assertions and ordering -.PP -hledger sorts an account\[aq]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.) -.PP -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. -.SS Assertions and included files -.PP -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\[aq]s -balance on the same day, you\[aq]ll have to put the assertion in the -right file. -.SS Assertions and multiple -f options -.PP -Balance assertions don\[aq]t work well across files specified with -multiple -f options. -Use include or concatenate the files instead. -.SS Assertions and commodities -.PP -The asserted balance must be a simple single-commodity amount, and in -fact the assertion checks only this commodity\[aq]s balance within the -(possibly multi-commodity) account balance. -This is how assertions work in Ledger also. -We could call this a \[dq]partial\[dq] balance assertion. -.PP -To assert the balance of more than one commodity in an account, you can -write multiple postings, each asserting one commodity\[aq]s balance. -.PP -You can make a stronger \[dq]total\[dq] balance assertion by writing a -double equals sign (\f[C]== EXPECTEDBALANCE\f[R]). -This asserts that there are no other unasserted commodities in the -account (or, that their balance is 0). -.IP -.nf -\f[C] -2013/1/1 - a $1 - a 1\[Eu] - b $-1 - c -1\[Eu] - -2013/1/2 ; These assertions succeed - a 0 = $1 - a 0 = 1\[Eu] - b 0 == $-1 - c 0 == -1\[Eu] - -2013/1/3 ; This assertion fails as \[aq]a\[aq] also contains 1\[Eu] - a 0 == $1 -\f[R] -.fi -.PP -It\[aq]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: -.IP -.nf -\f[C] -2013/1/1 - a:usd $1 - a:euro 1\[Eu] - b - -2013/1/2 - a 0 == 0 - a:usd 0 == $1 - a:euro 0 == 1\[Eu] -\f[R] -.fi -.SS Assertions and prices -.PP -Balance assertions ignore transaction prices, and should normally be -written without one: -.IP -.nf -\f[C] -2019/1/1 - (a) $1 \[at] \[Eu]1 = $1 -\f[R] -.fi -.PP -We do allow prices to be written there, however, and print shows them, -even though they don\[aq]t affect whether the assertion passes or fails. -This is for backward compatibility (hledger\[aq]s close command used to -generate balance assertions with prices), and because balance -\f[I]assignments\f[R] do use them (see below). -.SS Assertions and subaccounts -.PP -The balance assertions above (\f[C]=\f[R] and \f[C]==\f[R]) do not count -the balance from subaccounts; they check the account\[aq]s exclusive -balance only. -You can assert the balance including subaccounts by writing \f[C]=*\f[R] -or \f[C]==*\f[R], eg: -.IP -.nf -\f[C] -2019/1/1 - equity:opening balances - checking:a 5 - checking:b 5 - checking 1 ==* 11 -\f[R] -.fi -.SS Assertions and virtual postings -.PP -Balance assertions are checked against all postings, both real and -virtual. -They are not affected by the \f[C]--real/-R\f[R] flag or \f[C]real:\f[R] -query. -.SS Assertions and precision -.PP -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. -.SH BALANCE ASSIGNMENTS -.PP -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: -.IP -.nf -\f[C] -; 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 -\f[R] -.fi -.PP -or when adjusting a balance to reality: -.IP -.nf -\f[C] -; no cash left; update balance, record any untracked spending as a generic expense -2016/1/15 - assets:cash = $0 - expenses:misc -\f[R] -.fi -.PP -The calculated amount depends on the account\[aq]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. -.SS Balance assignments and prices -.PP -A transaction price in a balance assignment will cause the calculated -amount to have that price attached: -.IP -.nf -\f[C] -2019/1/1 - (a) = $1 \[at] \[Eu]2 -\f[R] -.fi -.IP -.nf -\f[C] -$ hledger print --explicit -2019-01-01 - (a) $1 \[at] \[Eu]2 = $1 \[at] \[Eu]2 -\f[R] -.fi -.SH DIRECTIVES -.PP -A directive is a line in the journal beginning with a special keyword, -that influences how the journal is processed. -hledger\[aq]s directives are based on a subset of Ledger\[aq]s, but -there are many differences (and also some differences between hledger -versions). -.PP -Directives\[aq] behaviour and interactions can get a little bit complex, -so here is a table summarising the directives and their effects, with -links to more detailed docs. -Note part of this table is hidden when viewed in a web browser - scroll -it sideways to see more. -.PP -.TS -tab(@); -lw(7.8n) lw(8.6n) lw(7.0n) lw(27.8n) lw(18.8n). -T{ -directive -T}@T{ -end directive -T}@T{ -subdirectives -T}@T{ -purpose -T}@T{ -can affect (as of 2018/06) -T} -_ -T{ -\f[C]account\f[R] -T}@T{ -T}@T{ -any text -T}@T{ -document account names, declare account types & display order -T}@T{ -all entries in all files, before or after -T} -T{ -\f[C]alias\f[R] -T}@T{ -\f[C]end aliases\f[R] -T}@T{ -T}@T{ -rewrite account names -T}@T{ -following entries until end of current file or end directive -T} -T{ -\f[C]apply account\f[R] -T}@T{ -\f[C]end apply account\f[R] -T}@T{ -T}@T{ -prepend a common parent to account names -T}@T{ -following entries until end of current file or end directive -T} -T{ -\f[C]comment\f[R] -T}@T{ -\f[C]end comment\f[R] -T}@T{ -T}@T{ -ignore part of journal -T}@T{ -following entries until end of current file or end directive -T} -T{ -\f[C]commodity\f[R] -T}@T{ -T}@T{ -\f[C]format\f[R] -T}@T{ -declare a commodity and its number notation & display style -T}@T{ -number notation: following entries in that commodity in all files ; -display style: amounts of that commodity in reports -T} -T{ -\f[C]D\f[R] -T}@T{ -T}@T{ -T}@T{ -declare a commodity to be used for commodityless amounts, and its number -notation & display style -T}@T{ -default commodity: following commodityless entries until end of current -file; number notation: following entries in that commodity until end of -current file; display style: amounts of that commodity in reports -T} -T{ -\f[C]include\f[R] -T}@T{ -T}@T{ -T}@T{ -include entries/directives from another file -T}@T{ -what the included directives affect -T} -T{ -\f[C]P\f[R] -T}@T{ -T}@T{ -T}@T{ -declare a market price for a commodity -T}@T{ -amounts of that commodity in reports, when -V is used -T} -T{ -\f[C]Y\f[R] -T}@T{ -T}@T{ -T}@T{ -declare a year for yearless dates -T}@T{ -following entries until end of current file -T} -T{ -\f[C]=\f[R] -T}@T{ -T}@T{ -T}@T{ -declare an auto posting rule, adding postings to other transactions -T}@T{ -all entries in parent/current/child files (but not sibling files, see -#1212) -T} -.TE -.PP -And some definitions: -.PP -.TS -tab(@); -lw(6.0n) lw(64.0n). -T{ -subdirective -T}@T{ -optional indented directive line immediately following a parent -directive -T} -T{ -number notation -T}@T{ -how to interpret numbers when parsing journal entries (the identity of -the decimal separator character). -(Currently each commodity can have its own notation, even in the same -file.) -T} -T{ -display style -T}@T{ -how to display amounts of a commodity in reports (symbol side and -spacing, digit groups, decimal separator, decimal places) -T} -T{ -directive scope -T}@T{ -which entries and (when there are multiple files) which files are -affected by a directive -T} -.TE -.PP -As you can see, directives vary in which journal entries and files they -affect, and whether they are focussed on input (parsing) or output -(reports). -Some directives have multiple effects. -.SS Directives and multiple files -.PP -If you use multiple \f[C]-f\f[R]/\f[C]--file\f[R] options, or the -\f[C]include\f[R] directive, hledger will process multiple input files. -But note that directives which affect input (see above) typically last -only until the end of the file in which they occur. -.PP -This may seem inconvenient, but it\[aq]s intentional; it makes reports -stable and deterministic, independent of the order of input. -Otherwise you could see different numbers if you happened to write -f -options in a different order, or if you moved includes around while -cleaning up your files. -.PP -It can be surprising though; for example, it means that \f[C]alias\f[R] -directives do not affect parent or sibling files (see below). -.SS Comment blocks -.PP -A line containing just \f[C]comment\f[R] starts a commented region of -the file, and a line containing just \f[C]end comment\f[R] (or the end -of the current file) ends it. -See also comments. -.SS Including other files -.PP -You can pull in the content of additional files by writing an include -directive, like this: -.IP -.nf -\f[C] -include FILEPATH -\f[R] -.fi -.PP -Only journal files can include, and only journal, timeclock or timedot -files can be included (not CSV files, currently). -.PP -If the file path does not begin with a slash, it is relative to the -current file\[aq]s folder. -.PP -A tilde means home directory, eg: \f[C]include \[ti]/main.journal\f[R]. -.PP -The path may contain glob patterns to match multiple files, eg: -\f[C]include *.journal\f[R]. -.PP -There is limited support for recursive wildcards: \f[C]**/\f[R] (the -slash is required) matches 0 or more subdirectories. -It\[aq]s not super convenient since you have to avoid include cycles and -including directories, but this can be done, eg: -\f[C]include */**/*.journal\f[R]. -.PP -The path may also be prefixed to force a specific file format, -overriding the file extension (as described in hledger.1 -> Input -files): \f[C]include timedot:\[ti]/notes/2020*.md\f[R]. -.SS Default year -.PP -You can set a default year to be used for subsequent dates which -don\[aq]t specify a year. -This is a line beginning with \f[C]Y\f[R] followed by the year. -Eg: -.IP -.nf -\f[C] -Y2009 ; set default year to 2009 - -12/15 ; equivalent to 2009/12/15 - expenses 1 - assets - -Y2010 ; change default year to 2010 - -2009/1/30 ; specifies the year, not affected - expenses 1 - assets - -1/31 ; equivalent to 2010/1/31 - expenses 1 - assets -\f[R] -.fi -.SS Declaring commodities -.PP -The \f[C]commodity\f[R] directive has several functions: -.IP "1." 3 -It declares commodities which may be used in the journal. -This is currently not enforced, but can serve as documentation. -.IP "2." 3 -It declares what decimal mark character (period or comma) to expect when -parsing input - useful to disambiguate international number formats in -your data. -(Without this, hledger will parse both \f[C]1,000\f[R] and -\f[C]1.000\f[R] as 1). -.IP "3." 3 -It declares a commodity\[aq]s display style in output - decimal and -digit group marks, number of decimal places, symbol placement etc. -.PP -You are likely to run into one of the problems solved by commodity -directives, sooner or later, so it\[aq]s a good idea to just always use -them to declare your commodities. -.PP -A commodity directive is just the word \f[C]commodity\f[R] followed by -an amount. -It may be written on a single line, like this: -.IP -.nf -\f[C] -; commodity EXAMPLEAMOUNT - -; display AAAA amounts with the symbol on the right, space-separated, -; using period as decimal point, with four decimal places, and -; separating thousands with comma. -commodity 1,000.0000 AAAA -\f[R] -.fi -.PP -or on multiple lines, using the \[dq]format\[dq] subdirective. -(In this case the commodity symbol appears twice and should be the same -in both places.): -.IP -.nf -\f[C] -; commodity SYMBOL -; format EXAMPLEAMOUNT - -; display indian rupees with currency name on the left, -; thousands, lakhs and crores comma-separated, -; period as decimal point, and two decimal places. -commodity INR - format INR 1,00,00,000.00 -\f[R] -.fi -.PP -The quantity of the amount does not matter; only the format is -significant. -The number must include a decimal mark: either a period or a comma, -followed by 0 or more decimal digits. -.PP -Note hledger normally uses banker\[aq]s rounding, so 0.5 displayed with -zero decimal digits is \[dq]0\[dq]. -(More at Commodity display style.) -.SS Commodity error checking -.PP -In strict mode, enabled with the \f[C]-s\f[R]/\f[C]--strict\f[R] flag, -hledger will report an error if a commodity symbol is used that has not -been declared by a \f[C]commodity\f[R] directive. -This works similarly to account error checking, see the notes there for -more details. -.SS Default commodity -.PP -The \f[C]D\f[R] directive sets a default commodity, to be used for -amounts without a commodity symbol (ie, plain numbers). -This commodity will be applied to all subsequent commodity-less amounts, -or until the next \f[C]D\f[R] directive. -(Note, this is different from Ledger\[aq]s \f[C]D\f[R].) -.PP -For compatibility/historical reasons, \f[C]D\f[R] also acts like a -\f[C]commodity\f[R] directive, setting the commodity\[aq]s display style -(for output) and decimal mark (for parsing input). -As with \f[C]commodity\f[R], the amount must always be written with a -decimal mark (period or comma). -If both directives are used, \f[C]commodity\f[R]\[aq]s style takes -precedence. -.PP -The syntax is \f[C]D AMOUNT\f[R]. -Eg: -.IP -.nf -\f[C] -; commodity-less amounts should be treated as dollars -; (and displayed with the dollar sign on the left, thousands separators and two decimal places) -D $1,000.00 - -1/1 - a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00 - b -\f[R] -.fi -.SS Declaring market prices -.PP -The \f[C]P\f[R] directive declares a market price, which is an exchange -rate between two commodities on a certain date. -(In Ledger, they are called \[dq]historical prices\[dq].) These are -often obtained from a stock exchange, cryptocurrency exchange, or the -foreign exchange market. -.PP -Here is the format: -.IP -.nf -\f[C] -P DATE COMMODITYA COMMODITYBAMOUNT -\f[R] -.fi -.IP \[bu] 2 -DATE is a simple date -.IP \[bu] 2 -COMMODITYA is the symbol of the commodity being priced -.IP \[bu] 2 -COMMODITYBAMOUNT is an amount (symbol and quantity) in a second -commodity, giving the price in commodity B of one unit of commodity A. -.PP -These two market price directives say that one euro was worth 1.35 US -dollars during 2009, and $1.40 from 2010 onward: -.IP -.nf -\f[C] -P 2009/1/1 \[Eu] $1.35 -P 2010/1/1 \[Eu] $1.40 -\f[R] -.fi -.PP -The \f[C]-V\f[R], \f[C]-X\f[R] and \f[C]--value\f[R] flags use these -market prices to show amount values in another commodity. -See Valuation. -.SS Declaring accounts -.PP -\f[C]account\f[R] directives can be used to declare accounts (ie, the -places that amounts are transferred from and to). -Though not required, these declarations can provide several benefits: -.IP \[bu] 2 -They can document your intended chart of accounts, providing a -reference. -.IP \[bu] 2 -They can help hledger know your accounts\[aq] types (asset, liability, -equity, revenue, expense), useful for reports like balancesheet and -incomestatement. -.IP \[bu] 2 -They control account display order in reports, allowing non-alphabetic -sorting (eg Revenues to appear above Expenses). -.IP \[bu] 2 -They can store extra information about accounts (account numbers, notes, -etc.) -.IP \[bu] 2 -They help with account name completion in the add command, hledger-iadd, -hledger-web, ledger-mode etc. -.IP \[bu] 2 -In strict mode, they restrict which accounts may be posted to by -transactions, which helps detect typos. -.PP -The simplest form is just the word \f[C]account\f[R] followed by a -hledger-style account name, eg this account directive declares the -\f[C]assets:bank:checking\f[R] account: -.IP -.nf -\f[C] -account assets:bank:checking -\f[R] -.fi -.SS Account error checking -.PP -By default, accounts come into existence when a transaction references -them by name. -This is convenient, but it means hledger can\[aq]t warn you when you -mis-spell an account name in the journal. -Usually you\[aq]ll find the error later, as an extra account in balance -reports, or an incorrect balance when reconciling. -.PP -In strict mode, enabled with the \f[C]-s\f[R]/\f[C]--strict\f[R] flag, -hledger will report an error if any transaction uses an account name -that has not been declared by an account directive. -Some notes: -.IP \[bu] 2 -The declaration is case-sensitive; transactions must use the correct -account name capitalisation. -.IP \[bu] 2 -The account directive\[aq]s scope is \[dq]whole file and below\[dq] (see -directives). -This means it affects all of the current file, and any files it -includes, but not parent or sibling files. -The position of account directives within the file does not matter, -though it\[aq]s usual to put them at the top. -.IP \[bu] 2 -Accounts can only be declared in \f[C]journal\f[R] files (but will -affect included files in other formats). -.IP \[bu] 2 -It\[aq]s currently not possible to declare \[dq]all possible -subaccounts\[dq] with a wildcard; every account posted to must be -declared. -.SS Account comments -.PP -Comments, beginning with a semicolon, can be added: -.IP \[bu] 2 -on the same line, \f[B]after two or more spaces\f[R] (because ; is -allowed in account names) -.IP \[bu] 2 -on the next lines, indented -.PP -An example of both: -.IP -.nf -\f[C] -account assets:bank:checking ; same-line comment, note 2+ spaces before ; - ; next-line comment - ; another with tag, acctno:12345 (not used yet) -\f[R] -.fi -.PP -Same-line comments are not supported by Ledger, or hledger <1.13. -.SS Account subdirectives -.PP -We also allow (and ignore) Ledger-style indented subdirectives, just for -compatibility.: -.IP -.nf -\f[C] -account assets:bank:checking - format blah blah ; <- subdirective, ignored -\f[R] -.fi -.PP -Here is the full syntax of account directives: -.IP -.nf -\f[C] -account ACCTNAME [ACCTTYPE] [;COMMENT] - [;COMMENTS] - [LEDGER-STYLE SUBDIRECTIVES, IGNORED] -\f[R] -.fi -.SS Account types -.PP -hledger recognises five main types of account, corresponding to the -account classes in the accounting equation: -.PP -\f[C]Asset\f[R], \f[C]Liability\f[R], \f[C]Equity\f[R], -\f[C]Revenue\f[R], \f[C]Expense\f[R]. -.PP -These account types are important for controlling which accounts appear -in the balancesheet, balancesheetequity, incomestatement reports (and -probably for other things in future). -.PP -Additionally, we recognise the \f[C]Cash\f[R] type, which is also an -\f[C]Asset\f[R], and which causes accounts to appear in the cashflow -report. -(\[dq]Cash\[dq] here means liquid assets, eg bank balances but typically -not investments or receivables.) -.SS Declaring account types -.PP -Generally, to make these reports work you should declare your top-level -accounts and their types, using account directives with \f[C]type:\f[R] -tags. -.PP -The tag\[aq]s value should be one of: \f[C]Asset\f[R], -\f[C]Liability\f[R], \f[C]Equity\f[R], \f[C]Revenue\f[R], -\f[C]Expense\f[R], \f[C]Cash\f[R], \f[C]A\f[R], \f[C]L\f[R], -\f[C]E\f[R], \f[C]R\f[R], \f[C]X\f[R], \f[C]C\f[R] (all case -insensitive). -The type is inherited by all subaccounts except where they override it. -Here\[aq]s a complete example: -.IP -.nf -\f[C] -account assets ; type: Asset -account assets:bank ; type: Cash -account assets:cash ; type: Cash -account liabilities ; type: Liability -account equity ; type: Equity -account revenues ; type: Revenue -account expenses ; type: Expense -\f[R] -.fi -.SS Auto-detected account types -.PP -If you happen to use common english top-level account names, you may not -need to declare account types, as they will be detected automatically -using the following rules: -.PP -.TS -tab(@); -l l. -T{ -If name matches regular expression: -T}@T{ -account type is: -T} -_ -T{ -\f[C]\[ha]assets?(:|$)\f[R] -T}@T{ -\f[C]Asset\f[R] -T} -T{ -\f[C]\[ha](debts?|liabilit(y|ies))(:|$)\f[R] -T}@T{ -\f[C]Liability\f[R] -T} -T{ -\f[C]\[ha]equity(:|$)\f[R] -T}@T{ -\f[C]Equity\f[R] -T} -T{ -\f[C]\[ha](income|revenue)s?(:|$)\f[R] -T}@T{ -\f[C]Revenue\f[R] -T} -T{ -\f[C]\[ha]expenses?(:|$)\f[R] -T}@T{ -\f[C]Expense\f[R] -T} -.TE -.PP -.TS -tab(@); -lw(56.9n) lw(13.1n). -T{ -If account type is \f[C]Asset\f[R] and name does not contain regular -expression: -T}@T{ -account type is: -T} -_ -T{ -\f[C](investment|receivable|:A/R|:fixed)\f[R] -T}@T{ -\f[C]Cash\f[R] -T} -.TE -.PP -Even so, explicit declarations may be a good idea, for clarity and -predictability. -.SS Interference from auto-detected account types -.PP -If you assign any account type, it\[aq]s a good idea to assign all of -them, to prevent any confusion from mixing declared and auto-detected -types. -Although it\[aq]s unlikely to happen in real life, here\[aq]s an -example: with the following journal, \f[C]balancesheetequity\f[R] shows -\[dq]liabilities\[dq] in both Liabilities and Equity sections. -Declaring another account as \f[C]type:Liability\f[R] would fix it: -.IP -.nf -\f[C] -account liabilities ; type:Equity - -2020-01-01 - assets 1 - liabilities 1 - equity -2 -\f[R] -.fi -.SS Old account type syntax -.PP -In some hledger journals you might instead see this old syntax (the -letters ALERX, separated from the account name by two or more spaces); -this is deprecated and may be removed soon: -.IP -.nf -\f[C] -account assets A -account liabilities L -account equity E -account revenues R -account expenses X -\f[R] -.fi -.SS Account display order -.PP -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: -.IP -.nf -\f[C] -account assets -account liabilities -account equity -account revenues -account expenses -\f[R] -.fi -.PP -you\[aq]ll see those accounts displayed in declaration order, not -alphabetically: -.IP -.nf -\f[C] -$ hledger accounts -1 -assets -liabilities -equity -revenues -expenses -\f[R] -.fi -.PP -Undeclared accounts, if any, are displayed last, in alphabetical order. -.PP -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: -.IP -.nf -\f[C] -account other:zoo -\f[R] -.fi -.PP -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: -.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 -parts of them, before generating reports. -This can be useful for: -.IP \[bu] 2 -expanding shorthand account names to their full form, allowing easier -data entry and a less verbose journal -.IP \[bu] 2 -adapting old journals to your current chart of accounts -.IP \[bu] 2 -experimenting with new account organisations, like a new hierarchy or -combining two accounts into one -.IP \[bu] 2 -customising reports -.PP -Account aliases also rewrite account names in account directives. -They do not affect account names being entered via hledger add or -hledger-web. -.PP -See also Rewrite account names. -.SS Basic aliases -.PP -To set an account alias, use the \f[C]alias\f[R] directive in your -journal file. -This affects all subsequent journal entries in the current file or its -included files. -The spaces around the = are optional: -.IP -.nf -\f[C] -alias OLD = NEW -\f[R] -.fi -.PP -Or, you can use the \f[C]--alias \[aq]OLD=NEW\[aq]\f[R] option on the -command line. -This affects all entries. -It\[aq]s useful for trying out aliases interactively. -.PP -OLD and NEW are case sensitive full account names. -hledger will replace any occurrence of the old account name with the new -one. -Subaccounts are also affected. -Eg: -.IP -.nf -\f[C] -alias checking = assets:bank:wells fargo:checking -; rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq] -\f[R] -.fi -.SS Regex aliases -.PP -There is also a more powerful variant that uses a regular expression, -indicated by the forward slashes: -.IP -.nf -\f[C] -alias /REGEX/ = REPLACEMENT -\f[R] -.fi -.PP -or \f[C]--alias \[aq]/REGEX/=REPLACEMENT\[aq]\f[R]. -.PP -REGEX is a case-insensitive regular expression. -Anywhere it matches inside an account name, the matched part will be -replaced by REPLACEMENT. -If REGEX contains parenthesised match groups, these can be referenced by -the usual numeric backreferences in REPLACEMENT. -Eg: -.IP -.nf -\f[C] -alias /\[ha](.+):bank:([\[ha]:]+):(.*)/ = \[rs]1:\[rs]2 \[rs]3 -; rewrites \[dq]assets:bank:wells fargo:checking\[dq] to \[dq]assets:wells fargo checking\[dq] -\f[R] -.fi -.PP -Also note that REPLACEMENT continues to the end of line (or on command -line, to end of option argument), so it can contain trailing whitespace. -.SS Combining aliases -.PP -You can define as many aliases as you like, using journal directives -and/or command line options. -.PP -Recursive aliases - where an account name is rewritten by one alias, -then by another alias, and so on - are allowed. -Each alias sees the effect of previously applied aliases. -.PP -In such cases it can be important to understand which aliases will be -applied and in which order. -For (each account name in) each journal entry, we apply: -.IP "1." 3 -\f[C]alias\f[R] directives preceding the journal entry, most recently -parsed first (ie, reading upward from the journal entry, bottom to top) -.IP "2." 3 -\f[C]--alias\f[R] options, in the order they appeared on the command -line (left to right). -.PP -In other words, for (an account name in) a given journal entry: -.IP \[bu] 2 -the nearest alias declaration before/above the entry is applied first -.IP \[bu] 2 -the next alias before/above that will be be applied next, and so on -.IP \[bu] 2 -aliases defined after/below the entry do not affect it. -.PP -This gives nearby aliases precedence over distant ones, and helps -provide semantic stability - aliases will keep working the same way -independent of which files are being read and in which order. -.PP -In case of trouble, adding \f[C]--debug=6\f[R] to the command line will -show which aliases are being applied when. -.SS Aliases and multiple files -.PP -As explained at Directives and multiple files, \f[C]alias\f[R] -directives do not affect parent or sibling files. -Eg in this command, -.IP -.nf -\f[C] -hledger -f a.aliases -f b.journal -\f[R] -.fi -.PP -account aliases defined in a.aliases will not affect b.journal. -Including the aliases doesn\[aq]t work either: -.IP -.nf -\f[C] -include a.aliases - -2020-01-01 ; not affected by a.aliases - foo 1 - bar -\f[R] -.fi -.PP -This means that account aliases should usually be declared at the start -of your top-most file, like this: -.IP -.nf -\f[C] -alias foo=Foo -alias bar=Bar - -2020-01-01 ; affected by aliases above - foo 1 - bar - -include c.journal ; also affected -\f[R] -.fi -.SS \f[C]end aliases\f[R] -.PP -You can clear (forget) all currently defined aliases with the -\f[C]end aliases\f[R] directive: -.IP -.nf -\f[C] -end aliases -\f[R] -.fi -.SS Default parent account -.PP -You can specify a parent account which will be prepended to all accounts -within a section of the journal. -Use the \f[C]apply account\f[R] and \f[C]end apply account\f[R] -directives like so: -.IP -.nf -\f[C] -apply account home - -2010/1/1 - food $10 - cash - -end apply account -\f[R] -.fi -.PP -which is equivalent to: -.IP -.nf -\f[C] -2010/01/01 - home:food $10 - home:cash $-10 -\f[R] -.fi -.PP -If \f[C]end apply account\f[R] is omitted, the effect lasts to the end -of the file. -Included files are also affected, eg: -.IP -.nf -\f[C] -apply account business -include biz.journal -end apply account -apply account personal -include personal.journal -\f[R] -.fi -.PP -Prior to hledger 1.0, legacy \f[C]account\f[R] and \f[C]end\f[R] -spellings were also supported. -.PP -A default parent account also affects account directives. -It does not affect account names being entered via hledger add or -hledger-web. -If account aliases are present, they are applied after the default -parent account. -.SH PERIODIC TRANSACTIONS -.PP -Periodic transaction rules describe transactions that recur. -They allow hledger to generate temporary future transactions to help -with forecasting, so you don\[aq]t have to write out each one in the -journal, and it\[aq]s easy to try out different forecasts. -.PP -Periodic transactions can be a little tricky, so before you use them, -read this whole section - or at least these tips: -.IP "1." 3 -Two spaces accidentally added or omitted will cause you trouble - read -about this below. -.IP "2." 3 -For troubleshooting, show the generated transactions with -\f[C]hledger print --forecast tag:generated\f[R] or -\f[C]hledger register --forecast tag:generated\f[R]. -.IP "3." 3 -Forecasted transactions will begin only after the last non-forecasted -transaction\[aq]s date. -.IP "4." 3 -Forecasted transactions will end 6 months from today, by default. -See below for the exact start/end rules. -.IP "5." 3 -period expressions can be tricky. -Their documentation needs improvement, but is worth studying. -.IP "6." 3 -Some period expressions with a repeating interval must begin on a -natural boundary of that interval. -Eg in \f[C]weekly from DATE\f[R], DATE must be a monday. -\f[C]\[ti] weekly from 2019/10/1\f[R] (a tuesday) will give an error. -.IP "7." 3 -Other period expressions with an interval are automatically expanded to -cover a whole number of that interval. -(This is done to improve reports, but it also affects periodic -transactions. -Yes, it\[aq]s a bit inconsistent with the above.) Eg: -\f[C]\[ti] every 10th day of month from 2020/01\f[R], which is -equivalent to \f[C]\[ti] every 10th day of month from 2020/01/01\f[R], -will be adjusted to start on 2019/12/10. -.PP -Periodic transaction rules also have a second meaning: they are used to -define budget goals, shown in budget reports. -.SS Periodic rule syntax -.PP -A periodic transaction rule looks like a normal journal entry, with the -date replaced by a tilde (\f[C]\[ti]\f[R]) followed by a period -expression (mnemonic: \f[C]\[ti]\f[R] looks like a recurring sine -wave.): -.IP -.nf -\f[C] -\[ti] monthly - expenses:rent $2000 - assets:bank:checking -\f[R] -.fi -.PP -There is an additional constraint on the period expression: the start -date must fall on a natural boundary of the interval. -Eg \f[C]monthly from 2018/1/1\f[R] is valid, but -\f[C]monthly from 2018/1/15\f[R] is not. -.PP -Partial or relative dates (M/D, D, tomorrow, last week) in the period -expression can work (useful or not). -They will be relative to today\[aq]s date, unless a Y default year -directive is in effect, in which case they will be relative to Y/1/1. -.SS Two spaces between period expression and description! -.PP -If the period expression is followed by a transaction description, these -must be separated by \f[B]two or more spaces\f[R]. -This helps hledger know where the period expression ends, so that -descriptions can not accidentally alter their meaning, as in this -example: -.IP -.nf -\f[C] -; 2 or more spaces needed here, so the period is not understood as \[dq]every 2 months in 2020\[dq] -; || -; vv -\[ti] every 2 months in 2020, we will review - assets:bank:checking $1500 - income:acme inc -\f[R] -.fi -.PP -So, -.IP \[bu] 2 -Do write two spaces between your period expression and your transaction -description, if any. -.IP \[bu] 2 -Don\[aq]t accidentally write two spaces in the middle of your period -expression. -.SS Forecasting with periodic transactions -.PP -The \f[C]--forecast\f[R] flag activates any periodic transaction rules -in the journal. -They will generate temporary recurring transactions, which are not saved -in the journal, but will appear in all reports (eg print). -This can be useful for estimating balances into the future, or -experimenting with different scenarios. -Or, it can be used as a data entry aid: describe recurring transactions, -and every so often copy the output of \f[C]print --forecast\f[R] into -the journal. -.PP -These transactions will have an extra tag indicating which periodic rule -generated them: \f[C]generated-transaction:\[ti] PERIODICEXPR\f[R]. -And a similar, hidden tag (beginning with an underscore) which, because -it\[aq]s never displayed by print, can be used to match transactions -generated \[dq]just now\[dq]: -\f[C]_generated-transaction:\[ti] PERIODICEXPR\f[R]. -.PP -Periodic transactions are generated within some forecast period. -By default, this -.IP \[bu] 2 -begins on the later of -.RS 2 -.IP \[bu] 2 -the report start date if specified with -b/-p/date: -.IP \[bu] 2 -the day after the latest normal (non-periodic) transaction in the -journal, or today if there are no normal transactions. -.RE -.IP \[bu] 2 -ends on the report end date if specified with -e/-p/date:, or 6 months -(180 days) from today. -.PP -This means that periodic transactions will begin only after the latest -recorded transaction. -And a recorded transaction dated in the future can prevent generation of -periodic transactions. -(You can avoid that by writing the future transaction as a one-time -periodic rule instead - put tilde before the date, eg -\f[C]\[ti] YYYY-MM-DD ...\f[R]). -.PP -Or, you can set your own arbitrary \[dq]forecast period\[dq], which can -overlap recorded transactions, and need not be in the future, by -providing an option argument, like \f[C]--forecast=PERIODEXPR\f[R]. -Note the equals sign is required, a space won\[aq]t work. -PERIODEXPR is a period expression, which can specify the start date, end -date, or both, like in a \f[C]date:\f[R] query. -(See also hledger.1 -> Report start & end date). -Some examples: \f[C]--forecast=202001-202004\f[R], -\f[C]--forecast=jan-\f[R], \f[C]--forecast=2020\f[R]. -.SS Budgeting with periodic transactions -.PP -With the \f[C]--budget\f[R] flag, currently supported by the balance -command, each periodic transaction rule declares recurring budget goals -for the specified accounts. -Eg the first example above declares a goal of spending $2000 on rent -(and also, a goal of depositing $2000 into checking) every month. -Goals and actual performance can then be compared in budget reports. -.PP -See also: Budgeting and Forecasting. -.PP -.SH AUTO POSTINGS -.PP -\[dq]Automated postings\[dq] or \[dq]auto postings\[dq] are extra -postings which get added automatically to transactions which match -certain queries, defined by \[dq]auto posting rules\[dq], when you use -the \f[C]--auto\f[R] flag. -.PP -An auto posting rule looks a bit like a transaction: -.IP -.nf -\f[C] -= QUERY - ACCOUNT AMOUNT - ... - ACCOUNT [AMOUNT] -\f[R] -.fi -.PP -except the first line is an equals sign (mnemonic: \f[C]=\f[R] suggests -matching), followed by a query (which matches existing postings), and -each \[dq]posting\[dq] line describes a posting to be generated, and the -posting amounts can be: -.IP \[bu] 2 -a normal amount with a commodity symbol, eg \f[C]$2\f[R]. -This will be used as-is. -.IP \[bu] 2 -a number, eg \f[C]2\f[R]. -The commodity symbol (if any) from the matched posting will be added to -this. -.IP \[bu] 2 -a numeric multiplier, eg \f[C]*2\f[R] (a star followed by a number N). -The matched posting\[aq]s amount (and total price, if any) will be -multiplied by N. -.IP \[bu] 2 -a multiplier with a commodity symbol, eg \f[C]*$2\f[R] (a star, number -N, and symbol S). -The matched posting\[aq]s amount will be multiplied by N, and its -commodity symbol will be replaced with S. -.PP -Any query term containing spaces must be enclosed in single or double -quotes, as on the command line. -Eg, note the quotes around the second query term below: -.IP -.nf -\f[C] -= expenses:groceries \[aq]expenses:dining out\[aq] - (budget:funds:dining out) *-1 -\f[R] -.fi -.PP -Some examples: -.IP -.nf -\f[C] -; every time I buy food, schedule a dollar donation -= expenses:food - (liabilities:charity) $-1 - -; when I buy a gift, also deduct that amount from a budget envelope subaccount -= expenses:gifts - assets:checking:gifts *-1 - assets:checking *1 - -2017/12/1 - expenses:food $10 - assets:checking - -2017/12/14 - expenses:gifts $20 - assets:checking -\f[R] -.fi -.IP -.nf -\f[C] -$ hledger print --auto -2017-12-01 - expenses:food $10 - assets:checking - (liabilities:charity) $-1 - -2017-12-14 - expenses:gifts $20 - assets:checking - assets:checking:gifts -$20 - assets:checking $20 -\f[R] -.fi -.SS Auto postings and multiple files -.PP -An auto posting rule can affect any transaction in the current file, or -in any parent file or child file. -Note, currently it will not affect sibling files (when multiple -\f[C]-f\f[R]/\f[C]--file\f[R] are used - see #1212). -.SS Auto postings and dates -.PP -A posting date (or secondary date) in the matched posting, or (taking -precedence) a posting date in the auto posting rule itself, will also be -used in the generated posting. -.SS Auto postings and transaction balancing / inferred amounts / balance assertions -.PP -Currently, auto postings are added: -.IP \[bu] 2 -after missing amounts are inferred, and transactions are checked for -balancedness, -.IP \[bu] 2 -but before balance assertions are checked. -.PP -Note this means that journal entries must be balanced both before and -after auto postings are added. -This changed in hledger 1.12+; see #893 for background. -.SS Auto posting tags -.PP -Automated postings will have some extra tags: -.IP \[bu] 2 -\f[C]generated-posting:= QUERY\f[R] - shows this was generated by an -auto posting rule, and the query -.IP \[bu] 2 -\f[C]_generated-posting:= QUERY\f[R] - a hidden tag, which does not -appear in hledger\[aq]s output. -This can be used to match postings generated \[dq]just now\[dq], rather -than generated in the past and saved to the journal. -.PP -Also, any transaction that has been changed by auto posting rules will -have these tags added: -.IP \[bu] 2 -\f[C]modified:\f[R] - this transaction was modified -.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 "REPORTING BUGS" -Report bugs at http://bugs.hledger.org -(or on the #hledger IRC channel or hledger mail list) - -.SH AUTHORS -Simon Michael <simon@joyful.com> and contributors - -.SH COPYRIGHT - -Copyright (C) 2007-2020 Simon Michael. -.br -Released under GNU GPL v3 or later. - -.SH SEE ALSO -hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) - -hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_timedot(5) |