summaryrefslogtreecommitdiff
path: root/hledger_journal.info
diff options
context:
space:
mode:
Diffstat (limited to 'hledger_journal.info')
-rw-r--r--hledger_journal.info2217
1 files changed, 0 insertions, 2217 deletions
diff --git a/hledger_journal.info b/hledger_journal.info
deleted file mode 100644
index a94b728..0000000
--- a/hledger_journal.info
+++ /dev/null
@@ -1,2217 +0,0 @@
-This is hledger-lib/hledger_journal.info, produced by makeinfo version
-4.8 from stdin.
-
-
-File: hledger_journal.info, Node: Top, Up: (dir)
-
-hledger_journal(5)
-******************
-
-hledger's default file format, representing a General Journal.
-
- hledger's usual data source is a plain text file containing journal
-entries in hledger journal format. This file represents a standard
-accounting general journal. I use file names ending in `.journal', but
-that's not required. The journal file contains a number of transaction
-entries, each describing a transfer of money (or any commodity) between
-two or more named accounts, in a simple format readable by both hledger
-and humans.
-
- hledger's journal format is a compatible subset, mostly, of ledger's
-journal format, so hledger can work with compatible ledger journal files
-as well. It's safe, and encouraged, to run both hledger and ledger on
-the same journal file, eg to validate the results you're getting.
-
- You can use hledger without learning any more about this file; just
-use the add or web or import commands to create and update it.
-
- Many users, though, edit the journal file with a text editor, and
-track changes with a version control system such as git. Editor addons
-such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
-hledger-vscode for Visual Studio Code, make this easier, adding colour,
-formatting, tab completion, and useful commands. See Editor
-configuration at hledger.org for the full list.
-
- Here's a description of each part of the file format (and hledger's
-data model). These are mostly in the order you'll use them, but in some
-cases related concepts have been grouped together for easy reference, or
-linked before they are introduced, so feel free to skip over anything
-that looks unnecessary right now.
-
-* Menu:
-
-* TRANSACTIONS::
-* DATES::
-* STATUS::
-* DESCRIPTION::
-* COMMENTS::
-* TAGS::
-* POSTINGS::
-* ACCOUNT NAMES::
-* AMOUNTS::
-* TRANSACTION PRICES::
-* LOT PRICES LOT DATES::
-* BALANCE ASSERTIONS::
-* BALANCE ASSIGNMENTS::
-* DIRECTIVES::
-* PERIODIC TRANSACTIONS::
-* AUTO POSTINGS::
-
-
-File: hledger_journal.info, Node: TRANSACTIONS, Next: DATES, Prev: Top, 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 (indented comment lines are also
- allowed, but not blank lines or non-indented lines).
-
- Here's a simple journal file containing one transaction:
-
-
-2008/01/01 income
- assets:bank:checking $1
- income:salary $-1
-
-
-File: hledger_journal.info, Node: DATES, Next: STATUS, Prev: TRANSACTIONS, Up: Top
-
-2 DATES
-*******
-
-* Menu:
-
-* Simple dates::
-* Secondary dates::
-* Posting dates::
-
-
-File: hledger_journal.info, Node: Simple dates, Next: Secondary dates, Up: DATES
-
-2.1 Simple dates
-================
-
-Dates in the journal file use _simple dates_ format: `YYYY-MM-DD' or
-`YYYY/MM/DD' or `YYYY.MM.DD', with leading zeros optional. The year may
-be omitted, in which case it will be inferred from the context: the
-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
-
-2.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, for more accurate daily balances, you can specify
-individual posting dates.
-
- Or, you can use the older _secondary date_ 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.
-
- A secondary date is written after the primary date, following an
-equals sign. If the year is omitted, the primary date's year is
-assumed. When running reports, the primary (left) date is used by
-default, but with the `--date2' flag (or `--aux-date' or `--effective'),
-the secondary (right) date will be used instead.
-
- The meaning of secondary dates is up to you, but it's best to follow
-a consistent rule. Eg "primary = the bank's clearing date, secondary =
-date the transaction was initiated, if different", as shown here:
-
-
-2010/2/23=2/19 movie ticket
- expenses:cinema $10
- assets:checking
-
-
-$ hledger register checking
-2010-02-23 movie ticket assets:checking $-10 $-10
-
-
-$ hledger register checking --date2
-2010-02-19 movie ticket assets:checking $-10 $-10
-
-
-File: hledger_journal.info, Node: Posting dates, Prev: Secondary dates, Up: DATES
-
-2.3 Posting dates
-=================
-
-You can give individual postings a different date from their parent
-transaction, by adding a posting comment containing a tag (see below)
-like `date:DATE'. This is probably the best way to control posting
-dates precisely. Eg in this example the expense should appear in May
-reports, and the deduction from checking should be reported on 6/1 for
-easy bank reconciliation:
-
-
-2015/5/30
- expenses:food $10 ; food purchased on saturday 5/30
- assets:checking ; bank cleared it on monday, date:6/1
-
-
-$ hledger -f t.j register food
-2015-05-30 expenses:food $10 $10
-
-
-$ hledger -f t.j register checking
-2015-06-01 assets:checking $-10 $-10
-
- DATE should be a simple date; if the year is not specified it will
-use the year of the transaction's date. You can set the secondary date
-similarly, with `date2:DATE2'. The `date:' or `date2:' tags must have a
-valid simple date value if they are present, eg a `date:' tag with no
-value is not allowed.
-
- Ledger's earlier, more compact bracketed date syntax is also
-supported: `[DATE]', `[DATE=DATE2]' or `[=DATE2]'. hledger will attempt
-to parse any square-bracketed sequence of the `0123456789/-.='
-characters in this way. With this syntax, DATE infers its year from the
-transaction and DATE2 infers its year from DATE.
-
-
-File: hledger_journal.info, Node: STATUS, Next: DESCRIPTION, Prev: DATES, Up: Top
-
-3 STATUS
-********
-
-Transactions, or individual postings within a transaction, can have a
-status mark, which is a single character before the transaction
-description or posting account name, separated from it by a space,
-indicating one of three statuses:
-
-mark status
------------------
- unmarked
-`!' pending
-`*' cleared
-
- When reporting, you can filter by status with the `-U/--unmarked',
-`-P/--pending', and `-C/--cleared' flags; or the `status:', `status:!',
-and `status:*' queries; or the U, P, C keys in hledger-ui.
-
- Note, in Ledger and in older versions of hledger, the "unmarked"
-state is called "uncleared". As of hledger 1.3 we have renamed it to
-unmarked for clarity.
-
- To replicate Ledger and old hledger's behaviour of also matching
-pending, combine -U and -P.
-
- Status marks are optional, but can be helpful eg for reconciling with
-real-world accounts. Some editor modes provide highlighting and
-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.
-
- What "uncleared", "pending", and "cleared" actually mean is up to
-you. Here's one suggestion:
-
-status meaning
---------------------------------------------------------------------------
-uncleared recorded but not yet reconciled; needs review
-pending tentatively reconciled (if needed, eg during a big
- reconciliation)
-cleared complete, reconciled as far as possible, and considered
- correct
-
- With this scheme, you would use `-PC' to see the current balance at
-your bank, `-U' to see things which will probably hit your bank soon
-(like uncashed checks), and no flags to see the most up-to-date state
-of your finances.
-
-
-File: hledger_journal.info, Node: DESCRIPTION, Next: COMMENTS, Prev: STATUS, Up: Top
-
-4 DESCRIPTION
-*************
-
-A transaction's description is the rest of the line following the date
-and status mark (or until a comment begins). Sometimes called the
-"narration" in traditional bookkeeping, it can be used for whatever you
-wish, or left blank. Transaction descriptions can be queried, unlike
-comments.
-
-* Menu:
-
-* Payee and note::
-
-
-File: hledger_journal.info, Node: Payee and note, Up: DESCRIPTION
-
-4.1 Payee and note
-==================
-
-You can optionally include a `|' (pipe) character in descriptions to
-subdivide the description into separate fields for payee/payer name on
-the left (up to the first `|') and an additional note field on the
-right (after the first `|'). This may be worthwhile if you need to do
-more precise querying and pivoting by payee or by note.
-
-
-File: hledger_journal.info, Node: COMMENTS, Next: TAGS, Prev: DESCRIPTION, Up: Top
-
-5 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
-; another file comment
-* also a file comment, useful in org/orgstruct mode
-
-comment
-A multiline file comment, which continues
-until a line containing just "end comment"
-(or end of file).
-end comment
-
-2012/5/14 something ; a transaction comment
- ; the transaction comment, continued
- posting1 1 ; a comment for posting 1
- posting2
- ; a comment for posting 2
- ; another comment line for posting 2
-; a file comment (because not indented)
-
- You can also comment larger regions of a file using `comment' and
-`end comment' directives.
-
-
-File: hledger_journal.info, Node: TAGS, Next: POSTINGS, Prev: COMMENTS, Up: Top
-
-6 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: Top
-
-7 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
-
-7.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: Top
-
-8 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
-receivable'. Because of this, they must always be followed by *two or
-more spaces* (or newline).
-
- Account names can be aliased.
-
-
-File: hledger_journal.info, Node: AMOUNTS, Next: TRANSACTION PRICES, Prev: ACCOUNT NAMES, Up: Top
-
-9 AMOUNTS
-*********
-
-After the account name, there is usually an amount. (Important: between
-account name and amount, there must be *two or more spaces*.)
-
- hledger's amount format is flexible, supporting several international
-formats. Here are some examples. Amounts have a number (the "quantity"):
-
-
-1
-
- ..and usually a currency or commodity name (the "commodity"). This
-is a symbol, word, or phrase, to the left or right of the quantity,
-with or without a separating space:
-
-
-$1
-4000 AAPL
-
- If the commodity name contains spaces, numbers, or punctuation, it
-must be enclosed in double quotes:
-
-
-3 "no. 42 green apples"
-
- Amounts can be preceded by a minus sign (or a plus sign, though plus
-is the default), The sign can be written before or after a left-side
-commodity symbol:
-
-
--$1
-$-1
-
- One or more spaces between the sign and the number are acceptable
-when parsing (but they won't be displayed in output):
-
-
-+ $1
-$- 1
-
- Scientific E notation is allowed:
-
-
-1E-6
-EUR 1E3
-
- A decimal mark can be written as a period or a comma:
-
-
-1.23
-1,23456780000009
-
-* Menu:
-
-* Digit group marks::
-* Commodity display style::
-* Rounding::
-
-
-File: hledger_journal.info, Node: Digit group marks, Next: Commodity display style, Up: AMOUNTS
-
-9.1 Digit group marks
-=====================
-
-In the integer part of the quantity (left of the decimal mark), groups
-of digits can optionally be separated by a "digit group mark" - a space,
-comma, or period (different from the decimal mark):
-
-
- $1,000,000.00
- EUR 2.000.000,00
-INR 9,99,99,999.00
- 1 000 000.9455
-
- Note, a number containing a single group mark and no decimal mark is
-ambiguous. Are these group marks or decimal marks ?
-
-
-1,000
-1.000
-
- hledger will treat them both as decimal marks by default (cf #793).
-If you use digit group marks, to prevent confusion and undetected typos
-we recommend you write commodity directives at the top of the file to
-explicitly declare the decimal mark (and optionally a digit group mark).
-Note, these formats ("amount styles") are specific to each 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
-
-
-File: hledger_journal.info, Node: Commodity display style, Next: Rounding, Prev: Digit group marks, Up: AMOUNTS
-
-9.2 Commodity display style
-===========================
-
-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:
-
- * If there is a commodity directive (or default commodity directive)
- for the commodity, its style is used (see examples above).
-
- * Otherwise the style is inferred from the amounts in that commodity
- seen in the journal.
-
- * Or if there are no such amounts in the journal, a default style is
- used (like `$1000.00').
-
-
- A style is inferred from the journal amounts in a commodity as
-follows:
-
- * Use the general style (decimal mark, symbol placement) of the first
- amount
-
- * Use the first-seen digit group style (digit group mark, digit group
- sizes), if any
-
- * Use the maximum number of decimal places of all.
-
- Transaction price amounts don't affect the commodity display style
-directly, but occasionally they can do so indirectly (eg when a
-posting's amount is inferred using a transaction price). If you find
-this causing problems, use a commodity directive to fix the display
-style.
-
- In summary, each commodity's amounts will be normalised to
-
- * the style declared by a `commodity' directive
-
- * or, the style of the first posting amount in the journal, with the
- first-seen digit group style and the maximum-seen number of decimal
- places.
-
- If reports are showing amounts in a way you don't like (eg, with too
-many decimal places), use a commodity directive to set your preferred
-style.
-
-
-File: hledger_journal.info, Node: Rounding, Prev: Commodity display style, Up: AMOUNTS
-
-9.3 Rounding
-============
-
-Amounts are stored internally as decimal numbers with up to 255 decimal
-places, and displayed with the number of decimal places specified by the
-commodity display style. Note, hledger uses banker's rounding: it rounds
-to the nearest even number, eg 0.5 displayed with zero decimal places is
-"0"). (Guaranteed since hledger 1.17.1; in older versions this could
-vary if hledger was built with Decimal < 0.5.1.)
-
-
-File: hledger_journal.info, Node: TRANSACTION PRICES, Next: LOT PRICES LOT DATES, Prev: AMOUNTS, Up: Top
-
-10 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 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.
-
- 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 €100 @ $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 €100 @@ $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 €100 ; one hundred euros purchased
- assets:dollars $-135 ; for $135
-
- 4. Like 1, but the `@' is parenthesised, i.e. `(@)'; this is for
- compatibility with Ledger journals (Virtual posting costs), and is
- equivalent to 1 in hledger.
-
- 5. Like 2, but as in 4 the `@@' is parenthesised, i.e. `(@@)'; in
- hledger, this is equivalent to 2.
-
-
- Use the `-B/--cost' flag to convert amounts to their transaction
-price's commodity, if any. (mnemonic: "B" is from "cost Basis", as in
-Ledger). Eg here is how -B affects the balance report for the example
-above:
-
-
-$ hledger bal -N --flat
- $-135 assets:dollars
- €100 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 €100 ; for 100 euros
-
-
-$ hledger bal -N --flat -B
- €-100 assets:dollars # <- the dollars' selling price
- €100 assets:euros
-
-
-File: hledger_journal.info, Node: LOT PRICES LOT DATES, Next: BALANCE ASSERTIONS, Prev: TRANSACTION PRICES, Up: Top
-
-11 LOT PRICES, LOT DATES
-************************
-
-Ledger allows another kind of price, lot price (four variants:
-`{UNITPRICE}', `{{TOTALPRICE}}', `{=FIXEDUNITPRICE}',
-`{{=FIXEDTOTALPRICE}}'), and/or a lot date (`[DATE]') to be specified.
-These are normally used to select a lot when selling investments.
-hledger will parse these, for compatibility with Ledger journals, but
-currently ignores them. A transaction price, lot price and/or lot date
-may appear in any order, after the posting amount and before the
-balance assertion if any.
-
-
-File: hledger_journal.info, Node: BALANCE ASSERTIONS, Next: BALANCE ASSIGNMENTS, Prev: LOT PRICES LOT DATES, Up: Top
-
-12 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 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
-
-12.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
-
-12.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
-
-12.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
-
-12.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
-
-12.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
-
-12.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
-
-12.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
-
-12.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: Top
-
-13 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
-
-13.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: Top
-
-14 DIRECTIVES
-*************
-
-A directive is a line in the journal beginning with a special keyword,
-that influences how the journal is processed. hledger's directives are
-based on a subset of Ledger's, but there are many differences (and also
-some differences between hledger versions).
-
- Directives' behaviour and interactions can get a little bit complex,
-so here is a table summarising the directives and their effects, with
-links to more detailed docs. Note part of this table is hidden when
-viewed in a web browser - scroll it sideways to see more.
-
-directiveend subdirectivespurpose can affect (as of
- directive 2018/06)
------------------------------------------------------------------------------
-`account' any document account names, all entries in all
- text declare account types & files, before or
- display order after
-`alias' `end rewrite account names following entries
- aliases' until end of
- current file or
- end directive
-`apply `end prepend a common parent to following entries
-account' apply account names until end of
- account' current file or
- end directive
-`comment'`end ignore part of journal following entries
- comment' until end of
- current file or
- end directive
-`commodity' `format'declare a commodity and its number notation:
- number notation & display following entries
- style in that commodity
- in all files ;
- display style:
- amounts of that
- commodity in
- reports
-`D' declare a commodity to be default commodity:
- used for commodityless following
- amounts, and its number commodityless
- notation & display style 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
-`include' include entries/directives what the included
- from another file directives affect
-`P' declare a market price for a amounts of that
- commodity commodity in
- reports, when -V
- is used
-`Y' declare a year for yearless following entries
- dates until end of
- current file
-`=' declare an auto posting all entries in
- rule, adding postings to parent/current/child
- other transactions files (but not
- sibling files, see
- #1212)
-
- And some definitions:
-
-subdirectiveoptional indented directive line immediately following a parent
- directive
-number how to interpret numbers when parsing journal entries (the
-notationidentity of the decimal separator character). (Currently each
- commodity can have its own notation, even in the same file.)
-displayhow to display amounts of a commodity in reports (symbol side and
-style spacing, digit groups, decimal separator, decimal places)
-directivewhich entries and (when there are multiple files) which files are
-scope affected by a directive
-
- 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.
-
-* Menu:
-
-* Directives and multiple files::
-* Comment blocks::
-* Including other files::
-* Default year::
-* Declaring commodities::
-* Default commodity::
-* Declaring market prices::
-* Declaring accounts::
-* Rewriting accounts::
-* Default parent account::
-
-
-File: hledger_journal.info, Node: Directives and multiple files, Next: Comment blocks, Up: DIRECTIVES
-
-14.1 Directives and multiple files
-==================================
-
-If you use multiple `-f'/`--file' options, or the `include' directive,
-hledger will process multiple input files. But note that directives
-which affect input (see above) typically last only until the end of the
-file in which they occur.
-
- This may seem inconvenient, but it's intentional; it makes reports
-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.
-
- It can be surprising though; for example, it means that `alias'
-directives do not affect parent or sibling files (see below).
-
-
-File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: DIRECTIVES
-
-14.2 Comment blocks
-===================
-
-A line containing just `comment' starts a commented region of the file,
-and a line containing just `end comment' (or the end of the current
-file) ends it. See also comments.
-
-
-File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: DIRECTIVES
-
-14.3 Including other files
-==========================
-
-You can pull in the content of additional files by writing an include
-directive, like this:
-
-
-include FILEPATH
-
- Only journal files can include, and only journal, timeclock or
-timedot files can be included (not CSV files, currently).
-
- If the file path does not begin with a slash, it is relative to the
-current file's folder.
-
- A tilde means home directory, eg: `include ~/main.journal'.
-
- The path may contain glob patterns to match multiple files, eg:
-`include *.journal'.
-
- There is limited support for recursive wildcards: `**/' (the slash
-is required) matches 0 or more subdirectories. It's not super convenient
-since you have to avoid include cycles and including directories, but
-this can be done, eg: `include */**/*.journal'.
-
- The path may also be prefixed to force a specific file format,
-overriding the file extension (as described in hledger.1 -> Input
-files): `include timedot:~/notes/2020*.md'.
-
-
-File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: DIRECTIVES
-
-14.4 Default year
-=================
-
-You can set a default year to be used for subsequent dates which don't
-specify a year. This is a line beginning with `Y' followed by the year.
-Eg:
-
-
-Y2009 ; set default year to 2009
-
-12/15 ; equivalent to 2009/12/15
- expenses 1
- assets
-
-Y2010 ; change default year to 2010
-
-2009/1/30 ; specifies the year, not affected
- expenses 1
- assets
-
-1/31 ; equivalent to 2010/1/31
- expenses 1
- assets
-
-
-File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: DIRECTIVES
-
-14.5 Declaring commodities
-==========================
-
-The `commodity' directive has several functions:
-
- 1. It declares commodities which may be used in the journal. This is
- currently not enforced, but can serve as documentation.
-
- 2. It declares what decimal mark character (period or comma) to
- expect when parsing input - useful to disambiguate international
- number formats in your data. (Without this, hledger will parse
- both `1,000' and `1.000' as 1).
-
- 3. It declares a commodity's display style in output - decimal and
- digit group marks, number of decimal places, symbol placement etc.
-
-
- You are likely to run into one of the problems solved by commodity
-directives, sooner or later, so it's a good idea to just always use them
-to declare your commodities.
-
- A commodity directive is just the word `commodity' followed by an
-amount. It may be written on a single line, like this:
-
-
-; commodity EXAMPLEAMOUNT
-
-; display AAAA amounts with the symbol on the right, space-separated,
-; using period as decimal point, with four decimal places, and
-; separating thousands with comma.
-commodity 1,000.0000 AAAA
-
- or on multiple lines, using the "format" subdirective. (In this case
-the commodity symbol appears twice and should be the same in both
-places.):
-
-
-; commodity SYMBOL
-; format EXAMPLEAMOUNT
-
-; display indian rupees with currency name on the left,
-; thousands, lakhs and crores comma-separated,
-; period as decimal point, and two decimal places.
-commodity INR
- format INR 1,00,00,000.00
-
- The quantity of the amount does not matter; only the format is
-significant. The number must include a decimal mark: either a period or
-a comma, followed by 0 or more decimal digits.
-
- Note hledger normally uses banker's rounding, so 0.5 displayed with
-zero decimal digits is "0". (More at Commodity display style.)
-
-* Menu:
-
-* Commodity error checking::
-
-
-File: hledger_journal.info, Node: Commodity error checking, Up: Declaring commodities
-
-14.5.1 Commodity error checking
--------------------------------
-
-In strict mode, enabled with the `-s'/`--strict' flag, hledger will
-report an error if a commodity symbol is used that has not been
-declared by a `commodity' directive. This works similarly to account
-error checking, see the notes there for more details.
-
-
-File: hledger_journal.info, Node: Default commodity, Next: Declaring market prices, Prev: Declaring commodities, Up: DIRECTIVES
-
-14.6 Default commodity
-======================
-
-The `D' 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 `D'
-directive. (Note, this is different from Ledger's `D'.)
-
- For compatibility/historical reasons, `D' also acts like a
-`commodity' directive, setting the commodity's display style (for
-output) and decimal mark (for parsing input). As with `commodity', the
-amount must always be written with a decimal mark (period or comma).
-If both directives are used, `commodity''s style takes precedence.
-
- The syntax is `D AMOUNT'. Eg:
-
-
-; commodity-less amounts should be treated as dollars
-; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
-D $1,000.00
-
-1/1
- a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
- b
-
-
-File: hledger_journal.info, Node: Declaring market prices, Next: Declaring accounts, Prev: Default commodity, Up: DIRECTIVES
-
-14.7 Declaring market prices
-============================
-
-The `P' directive declares a market price, which is an exchange rate
-between two commodities on a certain date. (In Ledger, they are called
-"historical prices".) These are often obtained from a stock exchange,
-cryptocurrency exchange, or the foreign exchange market.
-
- Here is the format:
-
-
-P DATE COMMODITYA COMMODITYBAMOUNT
-
- * DATE is a simple date
-
- * COMMODITYA is the symbol of the commodity being priced
-
- * COMMODITYBAMOUNT is an amount (symbol and quantity) in a second
- commodity, giving the price in commodity B of one unit of
- commodity A.
-
- These two market price directives say that one euro was worth 1.35 US
-dollars during 2009, and $1.40 from 2010 onward:
-
-
-P 2009/1/1 € $1.35
-P 2010/1/1 € $1.40
-
- The `-V', `-X' and `--value' flags use these market prices to show
-amount values in another commodity. See Valuation.
-
-
-File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Declaring market prices, Up: DIRECTIVES
-
-14.8 Declaring accounts
-=======================
-
-`account' 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:
-
- * They can document your intended chart of accounts, providing a
- reference.
-
- * They can help hledger know your accounts' types (asset, liability,
- equity, revenue, expense), useful for reports like balancesheet and
- incomestatement.
-
- * They control account display order in reports, allowing
- non-alphabetic sorting (eg Revenues to appear above Expenses).
-
- * They can store extra information about accounts (account numbers,
- notes, etc.)
-
- * They help with account name completion in the add command,
- hledger-iadd, hledger-web, ledger-mode etc.
-
- * In strict mode, they restrict which accounts may be posted to by
- transactions, which helps detect typos.
-
- The simplest form is just the word `account' followed by a
-hledger-style account name, eg this account directive declares the
-`assets:bank:checking' account:
-
-
-account assets:bank:checking
-
-* Menu:
-
-* Account error checking::
-* Account comments::
-* Account subdirectives::
-* Account types::
-* Account display order::
-
-
-File: hledger_journal.info, Node: Account error checking, Next: Account comments, Up: Declaring accounts
-
-14.8.1 Account error checking
------------------------------
-
-By default, accounts come into existence when a transaction references
-them by name. This is convenient, but it means hledger can't warn you
-when you mis-spell an account name in the journal. Usually you'll find
-the error later, as an extra account in balance reports, or an incorrect
-balance when reconciling.
-
- In strict mode, enabled with the `-s'/`--strict' flag, hledger will
-report an error if any transaction uses an account name that has not
-been declared by an account directive. Some notes:
-
- * The declaration is case-sensitive; transactions must use the
- correct account name capitalisation.
-
- * The account directive's scope is "whole file and below" (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's
- usual to put them at the top.
-
- * Accounts can only be declared in `journal' files (but will affect
- included files in other formats).
-
- * It's currently not possible to declare "all possible subaccounts"
- with a wildcard; every account posted to must be declared.
-
-
-File: hledger_journal.info, Node: Account comments, Next: Account subdirectives, Prev: Account error checking, Up: Declaring accounts
-
-14.8.2 Account comments
------------------------
-
-Comments, beginning with a semicolon, can be added:
-
- * on the same line, *after two or more spaces* (because ; is allowed
- in account names)
-
- * on the next lines, indented
-
- An example of both:
-
-
-account assets:bank:checking ; same-line comment, note 2+ spaces before ;
- ; next-line comment
- ; another with tag, acctno:12345 (not used yet)
-
- Same-line comments are not supported by Ledger, or hledger <1.13.
-
-
-File: hledger_journal.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts
-
-14.8.3 Account subdirectives
-----------------------------
-
-We also allow (and ignore) Ledger-style indented subdirectives, just for
-compatibility.:
-
-
-account assets:bank:checking
- format blah blah ; <- subdirective, ignored
-
- Here is the full syntax of account directives:
-
-
-account ACCTNAME [ACCTTYPE] [;COMMENT]
- [;COMMENTS]
- [LEDGER-STYLE SUBDIRECTIVES, IGNORED]
-
-
-File: hledger_journal.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts
-
-14.8.4 Account types
---------------------
-
-hledger recognises five main types of account, corresponding to the
-account classes in the accounting equation:
-
- `Asset', `Liability', `Equity', `Revenue', `Expense'.
-
- These account types are important for controlling which accounts
-appear in the balancesheet, balancesheetequity, incomestatement reports
-(and probably for other things in future).
-
- Additionally, we recognise the `Cash' type, which is also an
-`Asset', and which causes accounts to appear in the cashflow report.
-("Cash" here means liquid assets, eg bank balances but typically not
-investments or receivables.)
-
-* Menu:
-
-* Declaring account types::
-* Auto-detected account types::
-* Interference from auto-detected account types::
-* Old account type syntax::
-
-
-File: hledger_journal.info, Node: Declaring account types, Next: Auto-detected account types, Up: Account types
-
-14.8.4.1 Declaring account types
-................................
-
-Generally, to make these reports work you should declare your top-level
-accounts and their types, using account directives with `type:' tags.
-
- The tag's value should be one of: `Asset', `Liability', `Equity',
-`Revenue', `Expense', `Cash', `A', `L', `E', `R', `X', `C' (all case
-insensitive). The type is inherited by all subaccounts except where
-they override it. Here's a complete example:
-
-
-account assets ; type: Asset
-account assets:bank ; type: Cash
-account assets:cash ; type: Cash
-account liabilities ; type: Liability
-account equity ; type: Equity
-account revenues ; type: Revenue
-account expenses ; type: Expense
-
-
-File: hledger_journal.info, Node: Auto-detected account types, Next: Interference from auto-detected account types, Prev: Declaring account types, Up: Account types
-
-14.8.4.2 Auto-detected account types
-....................................
-
-If you happen to use common english top-level account names, you may not
-need to declare account types, as they will be detected automatically
-using the following rules:
-
-If name matches regular account type
-expression: is:
--------------------------------------------------
-`^assets?(:|$)' `Asset'
-`^(debts?|liabilit(y|ies))(:|$)' `Liability'
-`^equity(:|$)' `Equity'
-`^(income|revenue)s?(:|$)' `Revenue'
-`^expenses?(:|$)' `Expense'
-
-If account type is `Asset' and name does not contain account type
-regular expression: is:
---------------------------------------------------------------------------
-`(investment|receivable|:A/R|:fixed)' `Cash'
-
- Even so, explicit declarations may be a good idea, for clarity and
-predictability.
-
-
-File: hledger_journal.info, Node: Interference from auto-detected account types, Next: Old account type syntax, Prev: Auto-detected account types, Up: Account types
-
-14.8.4.3 Interference from auto-detected account types
-......................................................
-
-If you assign any account type, it's a good idea to assign all of them,
-to prevent any confusion from mixing declared and auto-detected types.
-Although it's unlikely to happen in real life, here's an example: with
-the following journal, `balancesheetequity' shows "liabilities" in both
-Liabilities and Equity sections. Declaring another account as
-`type:Liability' would fix it:
-
-
-account liabilities ; type:Equity
-
-2020-01-01
- assets 1
- liabilities 1
- equity -2
-
-
-File: hledger_journal.info, Node: Old account type syntax, Prev: Interference from auto-detected account types, Up: Account types
-
-14.8.4.4 Old account type syntax
-................................
-
-In some hledger journals you might instead see this old syntax (the
-letters ALERX, separated from the account name by two or more spaces);
-this is deprecated and may be removed soon:
-
-
-account assets A
-account liabilities L
-account equity E
-account revenues R
-account expenses X
-
-
-File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts
-
-14.8.5 Account display order
-----------------------------
-
-Account directives also set the order in which accounts are displayed,
-eg in reports, the hledger-ui accounts screen, and the hledger-web
-sidebar. By default accounts are listed in alphabetical order. But if
-you have these account directives in the journal:
-
-
-account assets
-account liabilities
-account equity
-account revenues
-account expenses
-
- you'll see those accounts displayed in declaration order, not
-alphabetically:
-
-
-$ hledger accounts -1
-assets
-liabilities
-equity
-revenues
-expenses
-
- Undeclared accounts, if any, are displayed last, in alphabetical
-order.
-
- Note that sorting is done at each level of the account tree (within
-each group of sibling accounts under the same parent). And currently,
-this directive:
-
-
-account other:zoo
-
- would influence the position of `zoo' among `other''s subaccounts,
-but not the position of `other' among the top-level accounts. This
-means:
-
- * 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
-
-14.9 Rewriting accounts
-=======================
-
-You can define account alias rules which rewrite your account names, or
-parts of them, before generating reports. This can be useful for:
-
- * expanding shorthand account names to their full form, allowing
- easier data entry and a less verbose journal
-
- * adapting old journals to your current chart of accounts
-
- * experimenting with new account organisations, like a new hierarchy
- or combining two accounts into one
-
- * customising reports
-
- Account aliases also rewrite account names in account directives.
-They do not affect account names being entered via hledger add or
-hledger-web.
-
- See also Rewrite account names.
-
-* Menu:
-
-* Basic aliases::
-* Regex aliases::
-* Combining aliases::
-* Aliases and multiple files::
-* end aliases::
-
-
-File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts
-
-14.9.1 Basic aliases
---------------------
-
-To set an account alias, use the `alias' directive in your journal
-file. This affects all subsequent journal entries in the current file or
-its included files. The spaces around the = are optional:
-
-
-alias OLD = NEW
-
- Or, you can use the `--alias 'OLD=NEW'' option on the command line.
-This affects all entries. It's useful for trying out aliases
-interactively.
-
- OLD and NEW are case sensitive full account names. hledger will
-replace any occurrence of the old account name with the new one.
-Subaccounts are also affected. Eg:
-
-
-alias checking = assets:bank:wells fargo:checking
-; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
-
-
-File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts
-
-14.9.2 Regex aliases
---------------------
-
-There is also a more powerful variant that uses a regular expression,
-indicated by the forward slashes:
-
-
-alias /REGEX/ = REPLACEMENT
-
- or `--alias '/REGEX/=REPLACEMENT''.
-
- REGEX is a case-insensitive regular expression. Anywhere it matches
-inside an account name, the matched part will be replaced by
-REPLACEMENT. If REGEX contains parenthesised match groups, these can be
-referenced by the usual numeric backreferences in REPLACEMENT. Eg:
-
-
-alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
-; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
-
- Also note that REPLACEMENT continues to the end of line (or on
-command line, to end of option argument), so it can contain trailing
-whitespace.
-
-
-File: hledger_journal.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: Rewriting accounts
-
-14.9.3 Combining aliases
-------------------------
-
-You can define as many aliases as you like, using journal directives
-and/or command line options.
-
- Recursive aliases - where an account name is rewritten by one alias,
-then by another alias, and so on - are allowed. Each alias sees the
-effect of previously applied aliases.
-
- In such cases it can be important to understand which aliases will be
-applied and in which order. For (each account name in) each journal
-entry, we apply:
-
- 1. `alias' directives preceding the journal entry, most recently
- parsed first (ie, reading upward from the journal entry, bottom to
- top)
-
- 2. `--alias' options, in the order they appeared on the command line
- (left to right).
-
- In other words, for (an account name in) a given journal entry:
-
- * the nearest alias declaration before/above the entry is applied
- first
-
- * the next alias before/above that will be be applied next, and so on
-
- * aliases defined after/below the entry do not affect it.
-
- 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.
-
- In case of trouble, adding `--debug=6' to the command line will show
-which aliases are being applied when.
-
-
-File: hledger_journal.info, Node: Aliases and multiple files, Next: end aliases, Prev: Combining aliases, Up: Rewriting accounts
-
-14.9.4 Aliases and multiple files
----------------------------------
-
-As explained at Directives and multiple files, `alias' directives do
-not affect parent or sibling files. Eg in this command,
-
-
-hledger -f a.aliases -f b.journal
-
- account aliases defined in a.aliases will not affect b.journal.
-Including the aliases doesn't work either:
-
-
-include a.aliases
-
-2020-01-01 ; not affected by a.aliases
- foo 1
- bar
-
- This means that account aliases should usually be declared at the
-start of your top-most file, like this:
-
-
-alias foo=Foo
-alias bar=Bar
-
-2020-01-01 ; affected by aliases above
- foo 1
- bar
-
-include c.journal ; also affected
-
-
-File: hledger_journal.info, Node: end aliases, Prev: Aliases and multiple files, Up: Rewriting accounts
-
-14.9.5 `end aliases'
---------------------
-
-You can clear (forget) all currently defined aliases with the `end
-aliases' directive:
-
-
-end aliases
-
-
-File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: DIRECTIVES
-
-14.10 Default parent account
-============================
-
-You can specify a parent account which will be prepended to all accounts
-within a section of the journal. Use the `apply account' and `end apply
-account' directives like so:
-
-
-apply account home
-
-2010/1/1
- food $10
- cash
-
-end apply account
-
- which is equivalent to:
-
-
-2010/01/01
- home:food $10
- home:cash $-10
-
- If `end apply account' is omitted, the effect lasts to the end of
-the file. Included files are also affected, eg:
-
-
-apply account business
-include biz.journal
-end apply account
-apply account personal
-include personal.journal
-
- Prior to hledger 1.0, legacy `account' and `end' spellings were also
-supported.
-
- 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.
-
-
-File: hledger_journal.info, Node: PERIODIC TRANSACTIONS, Next: AUTO POSTINGS, Prev: DIRECTIVES, Up: Top
-
-15 PERIODIC TRANSACTIONS
-************************
-
-Periodic transaction rules describe transactions that recur. They allow
-hledger to generate temporary future transactions to help with
-forecasting, so you don't have to write out each one in the journal, and
-it's easy to try out different forecasts.
-
- Periodic transactions can be a little tricky, so before you use them,
-read this whole section - or at least these tips:
-
- 1. Two spaces accidentally added or omitted will cause you trouble -
- read about this below.
-
- 2. For troubleshooting, show the generated transactions with `hledger
- print --forecast tag:generated' or `hledger register --forecast
- tag:generated'.
-
- 3. Forecasted transactions will begin only after the last
- non-forecasted transaction's date.
-
- 4. Forecasted transactions will end 6 months from today, by default.
- See below for the exact start/end rules.
-
- 5. period expressions can be tricky. Their documentation needs
- improvement, but is worth studying.
-
- 6. Some period expressions with a repeating interval must begin on a
- natural boundary of that interval. Eg in `weekly from DATE', DATE
- must be a monday. `~ weekly from 2019/10/1' (a tuesday) will give
- an error.
-
- 7. Other period expressions with an interval are automatically
- expanded to cover a whole number of that interval. (This is done
- to improve reports, but it also affects periodic transactions.
- Yes, it's a bit inconsistent with the above.) Eg: `~ every 10th
- day of month from 2020/01', which is equivalent to `~ every 10th
- day of month from 2020/01/01', will be adjusted to start on
- 2019/12/10.
-
- Periodic transaction rules also have a second meaning: they are used
-to define budget goals, shown in budget reports.
-
-* Menu:
-
-* Periodic rule syntax::
-* Two spaces between period expression and description!::
-* Forecasting with periodic transactions::
-* Budgeting with periodic transactions::
-
-
-File: hledger_journal.info, Node: Periodic rule syntax, Next: Two spaces between period expression and description!, Up: PERIODIC TRANSACTIONS
-
-15.1 Periodic rule syntax
-=========================
-
-A periodic transaction rule looks like a normal journal entry, with the
-date replaced by a tilde (`~') followed by a period expression
-(mnemonic: `~' looks like a recurring sine wave.):
-
-
-~ monthly
- expenses:rent $2000
- assets:bank:checking
-
- There is an additional constraint on the period expression: the start
-date must fall on a natural boundary of the interval. Eg `monthly from
-2018/1/1' is valid, but `monthly from 2018/1/15' is not.
-
- Partial or relative dates (M/D, D, tomorrow, last week) in the period
-expression can work (useful or not). They will be relative to today's
-date, unless a Y default year directive is in effect, in which case they
-will be relative to Y/1/1.
-
-
-File: hledger_journal.info, Node: Two spaces between period expression and description!, Next: Forecasting with periodic transactions, Prev: Periodic rule syntax, Up: PERIODIC TRANSACTIONS
-
-15.2 Two spaces between period expression and description!
-==========================================================
-
-If the period expression is followed by a transaction description, these
-must be separated by *two or more spaces*. This helps hledger know
-where the period expression ends, so that descriptions can not
-accidentally alter their meaning, as in this example:
-
-
-; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"
-; ||
-; vv
-~ every 2 months in 2020, we will review
- assets:bank:checking $1500
- income:acme inc
-
- So,
-
- * Do write two spaces between your period expression and your
- transaction description, if any.
-
- * Don't accidentally write two spaces in the middle of your period
- expression.
-
-
-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
-
-15.3 Forecasting with periodic transactions
-===========================================
-
-The `--forecast' flag activates any periodic transaction rules in the
-journal. They will generate temporary recurring transactions, which are
-not saved in the journal, but will appear in all reports (eg print).
-This can be useful for estimating balances into the future, or
-experimenting with different scenarios. Or, it can be used as a data
-entry aid: describe recurring transactions, and every so often copy the
-output of `print --forecast' into the journal.
-
- These transactions will have an extra tag indicating which periodic
-rule generated them: `generated-transaction:~ PERIODICEXPR'. And a
-similar, hidden tag (beginning with an underscore) which, because it's
-never displayed by print, can be used to match transactions generated
-"just now": `_generated-transaction:~ PERIODICEXPR'.
-
- Periodic transactions are generated within some forecast period. By
-default, this
-
- * begins on the later of
- * the report start date if specified with -b/-p/date:
-
- * the day after the latest normal (non-periodic) transaction in
- the journal, or today if there are no normal transactions.
-
- * ends on the report end date if specified with -e/-p/date:, or 6
- months (180 days) from today.
-
- This means that periodic transactions will begin only after the
-latest recorded transaction. And a recorded transaction dated in the
-future can prevent generation of periodic transactions. (You can avoid
-that by writing the future transaction as a one-time periodic rule
-instead - put tilde before the date, eg `~ YYYY-MM-DD ...').
-
- Or, you can set your own arbitrary "forecast period", which can
-overlap recorded transactions, and need not be in the future, by
-providing an option argument, like `--forecast=PERIODEXPR'. Note the
-equals sign is required, a space won't work. PERIODEXPR is a period
-expression, which can specify the start date, end date, or both, like
-in a `date:' query. (See also hledger.1 -> Report start & end date).
-Some examples: `--forecast=202001-202004', `--forecast=jan-',
-`--forecast=2020'.
-
-
-File: hledger_journal.info, Node: Budgeting with periodic transactions, Prev: Forecasting with periodic transactions, Up: PERIODIC TRANSACTIONS
-
-15.4 Budgeting with periodic transactions
-=========================================
-
-With the `--budget' flag, currently supported by the balance command,
-each periodic transaction rule declares recurring budget goals for the
-specified accounts. Eg the first example above declares a goal of
-spending $2000 on rent (and also, a goal of depositing $2000 into
-checking) every month. Goals and actual performance can then be compared
-in budget reports.
-
- See also: Budgeting and Forecasting.
-
-
-File: hledger_journal.info, Node: AUTO POSTINGS, Prev: PERIODIC TRANSACTIONS, Up: Top
-
-16 AUTO POSTINGS
-****************
-
-"Automated postings" or "auto postings" are extra postings which get
-added automatically to transactions which match certain queries, defined
-by "auto posting rules", when you use the `--auto' flag.
-
- An auto posting rule looks a bit like a transaction:
-
-
-= QUERY
- ACCOUNT AMOUNT
- ...
- ACCOUNT [AMOUNT]
-
- except the first line is an equals sign (mnemonic: `=' suggests
-matching), followed by a query (which matches existing postings), and
-each "posting" line describes a posting to be generated, and the posting
-amounts can be:
-
- * a normal amount with a commodity symbol, eg `$2'. This will be used
- as-is.
-
- * a number, eg `2'. The commodity symbol (if any) from the matched
- posting will be added to this.
-
- * a numeric multiplier, eg `*2' (a star followed by a number N). The
- matched posting's amount (and total price, if any) will be
- multiplied by N.
-
- * a multiplier with a commodity symbol, eg `*$2' (a star, number N,
- and symbol S). The matched posting's amount will be multiplied by
- N, and its commodity symbol will be replaced with S.
-
- Any query term containing spaces must be enclosed in single or double
-quotes, as on the command line. Eg, note the quotes around the second
-query term below:
-
-
-= expenses:groceries 'expenses:dining out'
- (budget:funds:dining out) *-1
-
- Some examples:
-
-
-; every time I buy food, schedule a dollar donation
-= expenses:food
- (liabilities:charity) $-1
-
-; when I buy a gift, also deduct that amount from a budget envelope subaccount
-= expenses:gifts
- assets:checking:gifts *-1
- assets:checking *1
-
-2017/12/1
- expenses:food $10
- assets:checking
-
-2017/12/14
- expenses:gifts $20
- assets:checking
-
-
-$ hledger print --auto
-2017-12-01
- expenses:food $10
- assets:checking
- (liabilities:charity) $-1
-
-2017-12-14
- expenses:gifts $20
- assets:checking
- assets:checking:gifts -$20
- assets:checking $20
-
-* Menu:
-
-* Auto postings and multiple files::
-* Auto postings and dates::
-* Auto postings and transaction balancing / inferred amounts / balance assertions::
-* Auto posting tags::
-
-
-File: hledger_journal.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: AUTO POSTINGS
-
-16.1 Auto postings and multiple files
-=====================================
-
-An auto posting rule can affect any transaction in the current file, or
-in any parent file or child file. Note, currently it will not affect
-sibling files (when multiple `-f'/`--file' are used - see #1212).
-
-
-File: hledger_journal.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: AUTO POSTINGS
-
-16.2 Auto postings and dates
-============================
-
-A posting date (or secondary date) in the matched posting, or (taking
-precedence) a posting date in the auto posting rule itself, will also be
-used in the generated posting.
-
-
-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
-
-16.3 Auto postings and transaction balancing / inferred amounts /
-=================================================================
-
-balance assertions
-
- Currently, auto postings are added:
-
- * after missing amounts are inferred, and transactions are checked
- for balancedness,
-
- * but before balance assertions are checked.
-
- Note this means that journal entries must be balanced both before and
-after auto postings are added. This changed in hledger 1.12+; see #893
-for background.
-
-
-File: hledger_journal.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: AUTO POSTINGS
-
-16.4 Auto posting tags
-======================
-
-Automated postings will have some extra tags:
-
- * `generated-posting:= QUERY' - shows this was generated by an auto
- posting rule, and the query
-
- * `_generated-posting:= QUERY' - a hidden tag, which does not appear
- in hledger's output. This can be used to match postings generated
- "just now", rather than generated in the past and saved to the
- journal.
-
- Also, any transaction that has been changed by auto posting rules
-will have these tags added:
-
- * `modified:' - this transaction was modified
-
- * `_modified:' - a hidden tag not appearing in the comment; this
- transaction was modified "just now".
-
-
-
-Tag Table:
-Node: Top88
-Node: TRANSACTIONS2095
-Ref: #transactions2213
-Node: DATES3230
-Ref: #dates3337
-Node: Simple dates3402
-Ref: #simple-dates3524
-Node: Secondary dates4031
-Ref: #secondary-dates4181
-Node: Posting dates5515
-Ref: #posting-dates5640
-Node: STATUS7009
-Ref: #status7117
-Node: DESCRIPTION8822
-Ref: #description8943
-Node: Payee and note9261
-Ref: #payee-and-note9371
-Node: COMMENTS9705
-Ref: #comments9818
-Node: TAGS11011
-Ref: #tags11113
-Node: POSTINGS12511
-Ref: #postings12626
-Node: Virtual postings13650
-Ref: #virtual-postings13763
-Node: ACCOUNT NAMES15065
-Ref: #account-names15193
-Node: AMOUNTS15678
-Ref: #amounts15804
-Node: Digit group marks16931
-Ref: #digit-group-marks17078
-Node: Commodity display style18018
-Ref: #commodity-display-style18194
-Node: Rounding19738
-Ref: #rounding19858
-Node: TRANSACTION PRICES20268
-Ref: #transaction-prices20425
-Node: LOT PRICES LOT DATES22855
-Ref: #lot-prices-lot-dates23029
-Node: BALANCE ASSERTIONS23516
-Ref: #balance-assertions23685
-Node: Assertions and ordering24715
-Ref: #assertions-and-ordering24899
-Node: Assertions and included files25596
-Ref: #assertions-and-included-files25835
-Node: Assertions and multiple -f options26166
-Ref: #assertions-and-multiple--f-options26418
-Node: Assertions and commodities26549
-Ref: #assertions-and-commodities26777
-Node: Assertions and prices27932
-Ref: #assertions-and-prices28142
-Node: Assertions and subaccounts28583
-Ref: #assertions-and-subaccounts28808
-Node: Assertions and virtual postings29132
-Ref: #assertions-and-virtual-postings29370
-Node: Assertions and precision29511
-Ref: #assertions-and-precision29700
-Node: BALANCE ASSIGNMENTS29965
-Ref: #balance-assignments30126
-Node: Balance assignments and prices31289
-Ref: #balance-assignments-and-prices31457
-Node: DIRECTIVES31683
-Ref: #directives31829
-Node: Directives and multiple files37274
-Ref: #directives-and-multiple-files37453
-Node: Comment blocks38115
-Ref: #comment-blocks38294
-Node: Including other files38469
-Ref: #including-other-files38645
-Node: Default year39569
-Ref: #default-year39734
-Node: Declaring commodities40141
-Ref: #declaring-commodities40320
-Node: Commodity error checking42161
-Ref: #commodity-error-checking42317
-Node: Default commodity42573
-Ref: #default-commodity42755
-Node: Declaring market prices43640
-Ref: #declaring-market-prices43831
-Node: Declaring accounts44689
-Ref: #declaring-accounts44871
-Node: Account error checking46078
-Ref: #account-error-checking46250
-Node: Account comments47427
-Ref: #account-comments47617
-Node: Account subdirectives48043
-Ref: #account-subdirectives48234
-Node: Account types48549
-Ref: #account-types48729
-Node: Declaring account types49464
-Ref: #declaring-account-types49649
-Node: Auto-detected account types50300
-Ref: #auto-detected-account-types50547
-Node: Interference from auto-detected account types51446
-Ref: #interference-from-auto-detected-account-types51729
-Node: Old account type syntax52212
-Ref: #old-account-type-syntax52415
-Node: Account display order52716
-Ref: #account-display-order52882
-Node: Rewriting accounts54033
-Ref: #rewriting-accounts54214
-Node: Basic aliases54973
-Ref: #basic-aliases55115
-Node: Regex aliases55817
-Ref: #regex-aliases55985
-Node: Combining aliases56705
-Ref: #combining-aliases56894
-Node: Aliases and multiple files58171
-Ref: #aliases-and-multiple-files58376
-Node: end aliases58957
-Ref: #end-aliases59110
-Node: Default parent account59212
-Ref: #default-parent-account59376
-Node: PERIODIC TRANSACTIONS60260
-Ref: #periodic-transactions60422
-Node: Periodic rule syntax62339
-Ref: #periodic-rule-syntax62541
-Node: Two spaces between period expression and description!63244
-Ref: #two-spaces-between-period-expression-and-description63559
-Node: Forecasting with periodic transactions64244
-Ref: #forecasting-with-periodic-transactions64545
-Node: Budgeting with periodic transactions66591
-Ref: #budgeting-with-periodic-transactions66826
-Node: AUTO POSTINGS67233
-Ref: #auto-postings67360
-Node: Auto postings and multiple files69543
-Ref: #auto-postings-and-multiple-files69743
-Node: Auto postings and dates69951
-Ref: #auto-postings-and-dates70221
-Node: Auto postings and transaction balancing / inferred amounts / balance assertions70396
-Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions70744
-Node: Auto posting tags71089
-Ref: #auto-posting-tags71300
-
-End Tag Table