summaryrefslogtreecommitdiff
path: root/hledger_journal.txt
diff options
context:
space:
mode:
Diffstat (limited to 'hledger_journal.txt')
-rw-r--r--hledger_journal.txt1597
1 files changed, 0 insertions, 1597 deletions
diff --git a/hledger_journal.txt b/hledger_journal.txt
deleted file mode 100644
index 210741d..0000000
--- a/hledger_journal.txt
+++ /dev/null
@@ -1,1597 +0,0 @@
-
-HLEDGER_JOURNAL(5) hledger User Manuals HLEDGER_JOURNAL(5)
-
-
-
-NAME
- hledger's default file format, representing a General Journal.
-
-DESCRIPTION
- hledger's usual data source is a plain text file containing journal
- entries in hledger journal format. This file represents a standard
- accounting general journal. I use file names ending in .journal, but
- that's not required. The journal file contains a number of transaction
- entries, each describing a transfer of money (or any commodity) between
- two or more named accounts, in a simple format readable by both hledger
- and humans.
-
- hledger's journal format is a compatible subset, mostly, of ledger's
- journal format, so hledger can work with compatible ledger journal
- files as well. It's safe, and encouraged, to run both hledger and
- ledger on the same journal file, eg to validate the results you're get-
- ting.
-
- You can use hledger without learning any more about this file; just use
- the add or web or import commands to create and update it.
-
- Many users, though, edit the journal file with a text editor, and track
- changes with a version control system such as git. Editor addons such
- as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
- hledger-vscode for Visual Studio Code, make this easier, adding colour,
- formatting, tab completion, and useful commands. See Editor configura-
- tion at hledger.org for the full list.
-
- Here's a description of each part of the file format (and hledger's
- data model). These are mostly in the order you'll use them, but in
- some cases related concepts have been grouped together for easy refer-
- ence, or linked before they are introduced, so feel free to skip over
- anything that looks unnecessary right now.
-
-TRANSACTIONS
- Transactions are the main unit of information in a journal file. They
- represent events, typically a movement of some quantity of commodities
- between two or more named accounts.
-
- Each transaction is recorded as a journal entry, beginning with a sim-
- ple date in column 0. This can be followed by any of the following
- optional fields, separated by spaces:
-
- o a status character (empty, !, or *)
-
- o a code (any short number or text, enclosed in parentheses)
-
- o a description (any remaining text until end of line or a semicolon)
-
- o a comment (any remaining text following a semicolon until end of
- line, and any following indented lines beginning with a semicolon)
-
- o 0 or more indented posting lines, describing what was transferred and
- the accounts involved (indented comment lines are also allowed, but
- not blank lines or non-indented lines).
-
- Here's a simple journal file containing one transaction:
-
- 2008/01/01 income
- assets:bank:checking $1
- income:salary $-1
-
-DATES
- Simple dates
- Dates in the journal file use simple dates format: YYYY-MM-DD or
- YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional. The year may be
- omitted, in which case it will be inferred from the context: the cur-
- rent transaction, the default year set with a default year directive,
- or the current date when the command is run. Some examples:
- 2010-01-31, 2010/01/31, 2010.1.31, 1/31.
-
- (The UI also accepts simple dates, as well as the more flexible smart
- dates documented in the hledger manual.)
-
- Secondary dates
- Real-life transactions sometimes involve more than one date - eg the
- date you write a cheque, and the date it clears in your bank. When you
- want to model this, for more accurate daily balances, you can specify
- individual posting dates.
-
- Or, you can use the older secondary date feature (Ledger calls it aux-
- iliary date or effective date). Note: we support this for compatibil-
- ity, but I usually recommend avoiding this feature; posting dates are
- almost always clearer and simpler.
-
- A secondary date is written after the primary date, following an equals
- sign. If the year is omitted, the primary date's year is assumed.
- When running reports, the primary (left) date is used by default, but
- with the --date2 flag (or --aux-date or --effective), the secondary
- (right) date will be used instead.
-
- The meaning of secondary dates is up to you, but it's best to follow a
- consistent rule. Eg "primary = the bank's clearing date, secondary =
- date the transaction was initiated, if different", as shown here:
-
- 2010/2/23=2/19 movie ticket
- expenses:cinema $10
- assets:checking
-
- $ hledger register checking
- 2010-02-23 movie ticket assets:checking $-10 $-10
-
- $ hledger register checking --date2
- 2010-02-19 movie ticket assets:checking $-10 $-10
-
- Posting dates
- You can give individual postings a different date from their parent
- transaction, by adding a posting comment containing a tag (see below)
- like date:DATE. This is probably the best way to control posting dates
- precisely. Eg in this example the expense should appear in May
- reports, and the deduction from checking should be reported on 6/1 for
- easy bank reconciliation:
-
- 2015/5/30
- expenses:food $10 ; food purchased on saturday 5/30
- assets:checking ; bank cleared it on monday, date:6/1
-
- $ hledger -f t.j register food
- 2015-05-30 expenses:food $10 $10
-
- $ hledger -f t.j register checking
- 2015-06-01 assets:checking $-10 $-10
-
- DATE should be a simple date; if the year is not specified it will use
- the year of the transaction's date. You can set the secondary date
- similarly, with date2:DATE2. The date: or date2: tags must have a
- valid simple date value if they are present, eg a date: tag with no
- value is not allowed.
-
- Ledger's earlier, more compact bracketed date syntax is also supported:
- [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any
- square-bracketed sequence of the 0123456789/-.= characters in this way.
- With this syntax, DATE infers its year from the transaction and DATE2
- infers its year from DATE.
-
-STATUS
- Transactions, or individual postings within a transaction, can have a
- status mark, which is a single character before the transaction
- description or posting account name, separated from it by a space,
- indicating one of three statuses:
-
-
- mark status
- ------------------
- unmarked
- ! pending
- * cleared
-
- When reporting, you can filter by status with the -U/--unmarked,
- -P/--pending, and -C/--cleared flags; or the status:, status:!, and
- status:* queries; or the U, P, C keys in hledger-ui.
-
- Note, in Ledger and in older versions of hledger, the "unmarked" state
- is called "uncleared". As of hledger 1.3 we have renamed it to
- unmarked for clarity.
-
- To replicate Ledger and old hledger's behaviour of also matching pend-
- ing, combine -U and -P.
-
- Status marks are optional, but can be helpful eg for reconciling with
- real-world accounts. Some editor modes provide highlighting and short-
- cuts for working with status. Eg in Emacs ledger-mode, you can toggle
- transaction status with C-c C-e, or posting status with C-c C-c.
-
- What "uncleared", "pending", and "cleared" actually mean is up to you.
- Here's one suggestion:
-
-
- status meaning
- --------------------------------------------------------------------------
- uncleared recorded but not yet reconciled; needs review
- pending tentatively reconciled (if needed, eg during a big reconcil-
- iation)
- cleared complete, reconciled as far as possible, and considered cor-
- rect
-
- With this scheme, you would use -PC to see the current balance at your
- bank, -U to see things which will probably hit your bank soon (like
- uncashed checks), and no flags to see the most up-to-date state of your
- finances.
-
-DESCRIPTION
- A transaction's description is the rest of the line following the date
- and status mark (or until a comment begins). Sometimes called the
- "narration" in traditional bookkeeping, it can be used for whatever you
- wish, or left blank. Transaction descriptions can be queried, unlike
- comments.
-
- Payee and note
- You can optionally include a | (pipe) character in descriptions to sub-
- divide the description into separate fields for payee/payer name on the
- left (up to the first |) and an additional note field on the right
- (after the first |). This may be worthwhile if you need to do more
- precise querying and pivoting by payee or by note.
-
-COMMENTS
- Lines in the journal beginning with a semicolon (;) or hash (#) or star
- (*) are comments, and will be ignored. (Star comments cause org-mode
- nodes to be ignored, allowing emacs users to fold and navigate their
- journals with org-mode or orgstruct-mode.)
-
- You can attach comments to a transaction by writing them after the
- description and/or indented on the following lines (before the post-
- ings). Similarly, you can attach comments to an individual posting by
- writing them after the amount and/or indented on the following lines.
- Transaction and posting comments must begin with a semicolon (;).
-
- Some examples:
-
- # a file comment
- ; another file comment
- * also a file comment, useful in org/orgstruct mode
-
- comment
- A multiline file comment, which continues
- until a line containing just "end comment"
- (or end of file).
- end comment
-
- 2012/5/14 something ; a transaction comment
- ; the transaction comment, continued
- posting1 1 ; a comment for posting 1
- posting2
- ; a comment for posting 2
- ; another comment line for posting 2
- ; a file comment (because not indented)
-
- You can also comment larger regions of a file using comment and end
- comment directives.
-
-TAGS
- Tags are a way to add extra labels or labelled data to postings and
- transactions, which you can then search or pivot on.
-
- A simple tag is a word (which may contain hyphens) followed by a full
- colon, written inside a transaction or posting comment line:
-
- 2017/1/16 bought groceries ; sometag:
-
- Tags can have a value, which is the text after the colon, up to the
- next comma or end of line, with leading/trailing whitespace removed:
-
- expenses:food $10 ; a-posting-tag: the tag value
-
- Note this means hledger's tag values can not contain commas or new-
- lines. Ending at commas means you can write multiple short tags on one
- line, comma separated:
-
- assets:checking ; a comment containing tag1:, tag2: some value ...
-
- Here,
-
- o "a comment containing" is just comment text, not a tag
-
- o "tag1" is a tag with no value
-
- o "tag2" is another tag, whose value is "some value ..."
-
- Tags in a transaction comment affect the transaction and all of its
- postings, while tags in a posting comment affect only that posting.
- For example, the following transaction has three tags (A, TAG2, third-
- tag) and the posting has four (those plus posting-tag):
-
- 1/1 a transaction ; A:, TAG2:
- ; third-tag: a third transaction tag, <- with a value
- (a) $1 ; posting-tag:
-
- Tags are like Ledger's metadata feature, except hledger's tag values
- are simple strings.
-
-POSTINGS
- A posting is an addition of some amount to, or removal of some amount
- from, an account. Each posting line begins with at least one space or
- tab (2 or 4 spaces is common), followed by:
-
- o (optional) a status character (empty, !, or *), followed by a space
-
- o (required) an account name (any text, optionally containing single
- spaces, until end of line or a double space)
-
- o (optional) two or more spaces or tabs followed by an amount.
-
- Positive amounts are being added to the account, negative amounts are
- being removed.
-
- The amounts within a transaction must always sum up to zero. As a con-
- venience, one amount may be left blank; it will be inferred so as to
- balance the transaction.
-
- Be sure to note the unusual two-space delimiter between account name
- and amount. This makes it easy to write account names containing spa-
- ces. But if you accidentally leave only one space (or tab) before the
- amount, the amount will be considered part of the account name.
-
- Virtual postings
- A posting with a parenthesised account name is called a virtual posting
- or unbalanced posting, which means it is exempt from the usual rule
- that a transaction's postings must balance add up to zero.
-
- This is not part of double entry accounting, so you might choose to
- avoid this feature. Or you can use it sparingly for certain special
- cases where it can be convenient. Eg, you could set opening balances
- without using a balancing equity account:
-
- 1/1 opening balances
- (assets:checking) $1000
- (assets:savings) $2000
-
- A posting with a bracketed account name is called a balanced virtual
- posting. The balanced virtual postings in a transaction must add up to
- zero (separately from other postings). Eg:
-
- 1/1 buy food with cash, update budget envelope subaccounts, & something else
- assets:cash $-10 ; <- these balance
- expenses:food $7 ; <-
- expenses:food $3 ; <-
- [assets:checking:budget:food] $-10 ; <- and these balance
- [assets:checking:available] $10 ; <-
- (something:else) $5 ; <- not required to balance
-
- Ordinary non-parenthesised, non-bracketed postings are called real
- postings. You can exclude virtual postings from reports with the
- -R/--real flag or real:1 query.
-
-ACCOUNT NAMES
- Account names typically have several parts separated by a full colon,
- from which hledger derives a hierarchical chart of accounts. They can
- be anything you like, but in finance there are traditionally five top-
- level accounts: assets, liabilities, income, expenses, and equity.
-
- Account names may contain single spaces, eg: assets:accounts receiv-
- able. Because of this, they must always be followed by two or more
- spaces (or newline).
-
- Account names can be aliased.
-
-AMOUNTS
- After the account name, there is usually an amount. (Important:
- between account name and amount, there must be two or more spaces.)
-
- hledger's amount format is flexible, supporting several international
- formats. Here are some examples. Amounts have a number (the "quan-
- tity"):
-
- 1
-
- ..and usually a currency or commodity name (the "commodity"). This is
- a symbol, word, or phrase, to the left or right of the quantity, with
- or without a separating space:
-
- $1
- 4000 AAPL
-
- If the commodity name contains spaces, numbers, or punctuation, it must
- be enclosed in double quotes:
-
- 3 "no. 42 green apples"
-
- Amounts can be preceded by a minus sign (or a plus sign, though plus is
- the default), The sign can be written before or after a left-side com-
- modity symbol:
-
- -$1
- $-1
-
- One or more spaces between the sign and the number are acceptable when
- parsing (but they won't be displayed in output):
-
- + $1
- $- 1
-
- Scientific E notation is allowed:
-
- 1E-6
- EUR 1E3
-
- A decimal mark can be written as a period or a comma:
-
- 1.23
- 1,23456780000009
-
- Digit group marks
- In the integer part of the quantity (left of the decimal mark), groups
- of digits can optionally be separated by a "digit group mark" - a
- space, comma, or period (different from the decimal mark):
-
- $1,000,000.00
- EUR 2.000.000,00
- INR 9,99,99,999.00
- 1 000 000.9455
-
- Note, a number containing a single group mark and no decimal mark is
- ambiguous. Are these group marks or decimal marks ?
-
- 1,000
- 1.000
-
- hledger will treat them both as decimal marks by default (cf #793). If
- you use digit group marks, to prevent confusion and undetected typos we
- recommend you write commodity directives at the top of the file to
- explicitly declare the decimal mark (and optionally a digit group
- mark). Note, these formats ("amount styles") are specific to each com-
- modity, so if your data uses multiple formats, hledger can handle it:
-
- commodity $1,000.00
- commodity EUR 1.000,00
- commodity INR 9,99,99,999.00
- commodity 1 000 000.9455
-
-
- Commodity display style
- For each commodity, hledger chooses a consistent style to use when dis-
- playing amounts. (Except price amounts, which are always displayed as
- written). The display style is chosen as follows:
-
- o If there is a commodity directive (or default commodity directive)
- for the commodity, its style is used (see examples above).
-
- o Otherwise the style is inferred from the amounts in that commodity
- seen in the journal.
-
- o Or if there are no such amounts in the journal, a default style is
- used (like $1000.00).
-
- A style is inferred from the journal amounts in a commodity as follows:
-
- o Use the general style (decimal mark, symbol placement) of the first
- amount
-
- o Use the first-seen digit group style (digit group mark, digit group
- sizes), if any
-
- o Use the maximum number of decimal places of all.
-
- Transaction price amounts don't affect the commodity display style
- directly, but occasionally they can do so indirectly (eg when a post-
- ing's amount is inferred using a transaction price). If you find this
- causing problems, use a commodity directive to fix the display style.
-
- In summary, each commodity's amounts will be normalised to
-
- o the style declared by a commodity directive
-
- o or, the style of the first posting amount in the journal, with the
- first-seen digit group style and the maximum-seen number of decimal
- places.
-
- If reports are showing amounts in a way you don't like (eg, with too
- many decimal places), use a commodity directive to set your preferred
- style.
-
- Rounding
- Amounts are stored internally as decimal numbers with up to 255 decimal
- places, and displayed with the number of decimal places specified by
- the commodity display style. Note, hledger uses banker's rounding: it
- rounds to the nearest even number, eg 0.5 displayed with zero decimal
- places is "0"). (Guaranteed since hledger 1.17.1; in older versions
- this could vary if hledger was built with Decimal < 0.5.1.)
-
-TRANSACTION PRICES
- Within a transaction, you can note an amount's price in another commod-
- ity. This can be used to document the cost (in a purchase) or selling
- price (in a sale). For example, transaction prices are useful to
- record purchases of a foreign currency. Note transaction prices are
- fixed at the time of the transaction, and do not change over time. See
- also market prices, which represent prevailing exchange rates on a cer-
- tain date.
-
- There are several ways to record a transaction price:
-
- 1. Write the price per unit, as @ UNITPRICE after the amount:
-
- 2009/1/1
- assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each
- assets:dollars ; balancing amount is -$135.00
-
- 2. Write the total price, as @@ TOTALPRICE after the amount:
-
- 2009/1/1
- assets:euros EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot
- assets:dollars
-
- 3. Specify amounts for all postings, using exactly two commodities, and
- let hledger infer the price that balances the transaction:
-
- 2009/1/1
- assets:euros EUR100 ; one hundred euros purchased
- assets:dollars $-135 ; for $135
-
- 4. Like 1, but the @ is parenthesised, i.e. (@); this is for compati-
- bility with Ledger journals (Virtual posting costs), and is equiva-
- lent to 1 in hledger.
-
- 5. Like 2, but as in 4 the @@ is parenthesised, i.e. (@@); in hledger,
- this is equivalent to 2.
-
- Use the -B/--cost flag to convert amounts to their transaction price's
- commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger).
- Eg here is how -B affects the balance report for the example above:
-
- $ hledger bal -N --flat
- $-135 assets:dollars
- EUR100 assets:euros
- $ hledger bal -N --flat -B
- $-135 assets:dollars
- $135 assets:euros # <- the euros' cost
-
- Note -B is sensitive to the order of postings when a transaction price
- is inferred: the inferred price will be in the commodity of the last
- amount. So if example 3's postings are reversed, while the transaction
- is equivalent, -B shows something different:
-
- 2009/1/1
- assets:dollars $-135 ; 135 dollars sold
- assets:euros EUR100 ; for 100 euros
-
- $ hledger bal -N --flat -B
- EUR-100 assets:dollars # <- the dollars' selling price
- EUR100 assets:euros
-
-LOT PRICES, LOT DATES
- Ledger allows another kind of price, lot price (four variants: {UNIT-
- PRICE}, {{TOTALPRICE}}, {=FIXEDUNITPRICE}, {{=FIXEDTOTALPRICE}}),
- and/or a lot date ([DATE]) to be specified. These are normally used to
- select a lot when selling investments. hledger will parse these, for
- compatibility with Ledger journals, but currently ignores them. A
- transaction price, lot price and/or lot date may appear in any order,
- after the posting amount and before the balance assertion if any.
-
-BALANCE ASSERTIONS
- hledger supports Ledger-style balance assertions in journal files.
- These look like, for example, = EXPECTEDBALANCE following a posting's
- amount. Eg here we assert the expected dollar balance in accounts a
- and b after each posting:
-
- 2013/1/1
- a $1 =$1
- b =$-1
-
- 2013/1/2
- a $1 =$2
- b $-1 =$-2
-
- After reading a journal file, hledger will check all balance assertions
- and report an error if any of them fail. Balance assertions can pro-
- tect you from, eg, inadvertently disrupting reconciled balances while
- cleaning up old entries. You can disable them temporarily with the
- -I/--ignore-assertions flag, which can be useful for troubleshooting or
- for reading Ledger files. (Note: this flag currently does not disable
- balance assignments, below).
-
- Assertions and ordering
- hledger sorts an account's postings and assertions first by date and
- then (for postings on the same day) by parse order. Note this is dif-
- ferent from Ledger, which sorts assertions only by parse order. (Also,
- Ledger assertions do not see the accumulated effect of repeated post-
- ings to the same account within a transaction.)
-
- So, hledger balance assertions keep working if you reorder differently-
- dated transactions within the journal. But if you reorder same-dated
- transactions or postings, assertions might break and require updating.
- This order dependence does bring an advantage: precise control over the
- order of postings and assertions within a day, so you can assert intra-
- day balances.
-
- Assertions and included files
- With included files, things are a little more complicated. Including
- preserves the ordering of postings and assertions. If you have multi-
- ple postings to an account on the same day, split across different
- files, and you also want to assert the account's balance on the same
- day, you'll have to put the assertion in the right file.
-
- Assertions and multiple -f options
- Balance assertions don't work well across files specified with multiple
- -f options. Use include or concatenate the files instead.
-
- Assertions and commodities
- The asserted balance must be a simple single-commodity amount, and in
- fact the assertion checks only this commodity's balance within the
- (possibly multi-commodity) account balance. This is how assertions
- work in Ledger also. We could call this a "partial" balance assertion.
-
- To assert the balance of more than one commodity in an account, you can
- write multiple postings, each asserting one commodity's balance.
-
- You can make a stronger "total" balance assertion by writing a double
- equals sign (== EXPECTEDBALANCE). This asserts that there are no other
- unasserted commodities in the account (or, that their balance is 0).
-
- 2013/1/1
- a $1
- a 1EUR
- b $-1
- c -1EUR
-
- 2013/1/2 ; These assertions succeed
- a 0 = $1
- a 0 = 1EUR
- b 0 == $-1
- c 0 == -1EUR
-
- 2013/1/3 ; This assertion fails as 'a' also contains 1EUR
- a 0 == $1
-
- It's not yet possible to make a complete assertion about a balance that
- has multiple commodities. One workaround is to isolate each commodity
- into its own subaccount:
-
- 2013/1/1
- a:usd $1
- a:euro 1EUR
- b
-
- 2013/1/2
- a 0 == 0
- a:usd 0 == $1
- a:euro 0 == 1EUR
-
- Assertions and prices
- Balance assertions ignore transaction prices, and should normally be
- written without one:
-
- 2019/1/1
- (a) $1 @ EUR1 = $1
-
- We do allow prices to be written there, however, and print shows them,
- even though they don't affect whether the assertion passes or fails.
- This is for backward compatibility (hledger's close command used to
- generate balance assertions with prices), and because balance assign-
- ments do use them (see below).
-
- Assertions and subaccounts
- The balance assertions above (= and ==) do not count the balance from
- subaccounts; they check the account's exclusive balance only. You can
- assert the balance including subaccounts by writing =* or ==*, eg:
-
- 2019/1/1
- equity:opening balances
- checking:a 5
- checking:b 5
- checking 1 ==* 11
-
- Assertions and virtual postings
- Balance assertions are checked against all postings, both real and vir-
- tual. They are not affected by the --real/-R flag or real: query.
-
- Assertions and precision
- Balance assertions compare the exactly calculated amounts, which are
- not always what is shown by reports. Eg a commodity directive may
- limit the display precision, but this will not affect balance asser-
- tions. Balance assertion failure messages show exact amounts.
-
-BALANCE ASSIGNMENTS
- Ledger-style balance assignments are also supported. These are like
- balance assertions, but with no posting amount on the left side of the
- equals sign; instead it is calculated automatically so as to satisfy
- the assertion. This can be a convenience during data entry, eg when
- setting opening balances:
-
- ; starting a new journal, set asset account balances
- 2016/1/1 opening balances
- assets:checking = $409.32
- assets:savings = $735.24
- assets:cash = $42
- equity:opening balances
-
- or when adjusting a balance to reality:
-
- ; no cash left; update balance, record any untracked spending as a generic expense
- 2016/1/15
- assets:cash = $0
- expenses:misc
-
- The calculated amount depends on the account's balance in the commodity
- at that point (which depends on the previously-dated postings of the
- commodity to that account since the last balance assertion or assign-
- ment). Note that using balance assignments makes your journal a little
- less explicit; to know the exact amount posted, you have to run hledger
- or do the calculations yourself, instead of just reading it.
-
- Balance assignments and prices
- A transaction price in a balance assignment will cause the calculated
- amount to have that price attached:
-
- 2019/1/1
- (a) = $1 @ EUR2
-
- $ hledger print --explicit
- 2019-01-01
- (a) $1 @ EUR2 = $1 @ EUR2
-
-DIRECTIVES
- A directive is a line in the journal beginning with a special keyword,
- that influences how the journal is processed. hledger's directives are
- based on a subset of Ledger's, but there are many differences (and also
- some differences between hledger versions).
-
- Directives' behaviour and interactions can get a little bit complex, so
- here is a table summarising the directives and their effects, with
- links to more detailed docs. Note part of this table is hidden when
- viewed in a web browser - scroll it sideways to see more.
-
-
- direc- end subdi- purpose can affect (as of
- tive directive rec- 2018/06)
- tives
- ------------------------------------------------------------------------------------
- account any document account names, all entries in all
- text declare account types & dis- files, before or
- play order after
- alias end rewrite account names following entries
- aliases until end of cur-
- rent file or end
- directive
- apply end apply prepend a common parent to following entries
- account account account names until end of cur-
- rent file or end
- directive
- comment end com- ignore part of journal following entries
- ment until end of cur-
- rent file or end
- directive
- commod- format declare a commodity and its number notation:
- ity number notation & display following entries
- style in that commodity
- in all files ; dis-
- play style: amounts
- of that commodity
- in reports
-
-
-
-
-
-
-
-
-
-
-
-
- D declare a commodity to be default commodity:
- used for commodityless following commod-
- amounts, and its number ityless entries
- notation & display style until end of cur-
- rent file; number
- notation: following
- entries in that
- commodity until end
- of current file;
- display style:
- amounts of that
- commodity in
- reports
- include include entries/directives what the included
- from another file directives affect
- P declare a market price for a amounts of that
- commodity commodity in
- reports, when -V is
- used
- Y declare a year for yearless following entries
- dates until end of cur-
- rent file
- = declare an auto posting all entries in par-
- rule, adding postings to ent/current/child
- other transactions files (but not sib-
- ling files, see
- #1212)
-
- And some definitions:
-
-
- subdi- optional indented directive line immediately following a parent
- rec- directive
- tive
- number how to interpret numbers when parsing journal entries (the iden-
- nota- tity of the decimal separator character). (Currently each com-
- tion modity can have its own notation, even in the same file.)
- dis- how to display amounts of a commodity in reports (symbol side
- play and spacing, digit groups, decimal separator, decimal places)
- style
- direc- which entries and (when there are multiple files) which files
- tive are affected by a directive
- scope
-
- As you can see, directives vary in which journal entries and files they
- affect, and whether they are focussed on input (parsing) or output
- (reports). Some directives have multiple effects.
-
- Directives and multiple files
- If you use multiple -f/--file options, or the include directive,
- hledger will process multiple input files. But note that directives
- which affect input (see above) typically last only until the end of the
- file in which they occur.
-
- This may seem inconvenient, but it's intentional; it makes reports sta-
- ble and deterministic, independent of the order of input. Otherwise
- you could see different numbers if you happened to write -f options in
- a different order, or if you moved includes around while cleaning up
- your files.
-
- It can be surprising though; for example, it means that alias direc-
- tives do not affect parent or sibling files (see below).
-
- Comment blocks
- A line containing just comment starts a commented region of the file,
- and a line containing just end comment (or the end of the current file)
- ends it. See also comments.
-
- Including other files
- You can pull in the content of additional files by writing an include
- directive, like this:
-
- include FILEPATH
-
- Only journal files can include, and only journal, timeclock or timedot
- files can be included (not CSV files, currently).
-
- If the file path does not begin with a slash, it is relative to the
- current file's folder.
-
- A tilde means home directory, eg: include ~/main.journal.
-
- The path may contain glob patterns to match multiple files, eg: include
- *.journal.
-
- There is limited support for recursive wildcards: **/ (the slash is
- required) matches 0 or more subdirectories. It's not super convenient
- since you have to avoid include cycles and including directories, but
- this can be done, eg: include */**/*.journal.
-
- The path may also be prefixed to force a specific file format, overrid-
- ing the file extension (as described in hledger.1 -> Input files):
- include timedot:~/notes/2020*.md.
-
- Default year
- You can set a default year to be used for subsequent dates which don't
- specify a year. This is a line beginning with Y followed by the year.
- Eg:
-
- Y2009 ; set default year to 2009
-
- 12/15 ; equivalent to 2009/12/15
- expenses 1
- assets
-
- Y2010 ; change default year to 2010
-
- 2009/1/30 ; specifies the year, not affected
- expenses 1
- assets
-
- 1/31 ; equivalent to 2010/1/31
- expenses 1
- assets
-
- Declaring commodities
- The commodity directive has several functions:
-
- 1. It declares commodities which may be used in the journal. This is
- currently not enforced, but can serve as documentation.
-
- 2. It declares what decimal mark character (period or comma) to expect
- when parsing input - useful to disambiguate international number
- formats in your data. (Without this, hledger will parse both 1,000
- and 1.000 as 1).
-
- 3. It declares a commodity's display style in output - decimal and
- digit group marks, number of decimal places, symbol placement etc.
-
- You are likely to run into one of the problems solved by commodity
- directives, sooner or later, so it's a good idea to just always use
- them to declare your commodities.
-
- A commodity directive is just the word commodity followed by an amount.
- It may be written on a single line, like this:
-
- ; commodity EXAMPLEAMOUNT
-
- ; display AAAA amounts with the symbol on the right, space-separated,
- ; using period as decimal point, with four decimal places, and
- ; separating thousands with comma.
- commodity 1,000.0000 AAAA
-
- or on multiple lines, using the "format" subdirective. (In this case
- the commodity symbol appears twice and should be the same in both
- places.):
-
- ; commodity SYMBOL
- ; format EXAMPLEAMOUNT
-
- ; display indian rupees with currency name on the left,
- ; thousands, lakhs and crores comma-separated,
- ; period as decimal point, and two decimal places.
- commodity INR
- format INR 1,00,00,000.00
-
- The quantity of the amount does not matter; only the format is signifi-
- cant. The number must include a decimal mark: either a period or a
- comma, followed by 0 or more decimal digits.
-
- Note hledger normally uses banker's rounding, so 0.5 displayed with
- zero decimal digits is "0". (More at Commodity display style.)
-
- Commodity error checking
- In strict mode, enabled with the -s/--strict flag, hledger will report
- an error if a commodity symbol is used that has not been declared by a
- commodity directive. This works similarly to account error checking,
- see the notes there for more details.
-
- Default commodity
- The D directive sets a default commodity, to be used for amounts with-
- out a commodity symbol (ie, plain numbers). This commodity will be
- applied to all subsequent commodity-less amounts, or until the next D
- directive. (Note, this is different from Ledger's D.)
-
- For compatibility/historical reasons, D also acts like a commodity
- directive, setting the commodity's display style (for output) and deci-
- mal mark (for parsing input). As with commodity, the amount must
- always be written with a decimal mark (period or comma). If both
- directives are used, commodity's style takes precedence.
-
- The syntax is D AMOUNT. Eg:
-
- ; commodity-less amounts should be treated as dollars
- ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
- D $1,000.00
-
- 1/1
- a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00
- b
-
- Declaring market prices
- The P directive declares a market price, which is an exchange rate
- between two commodities on a certain date. (In Ledger, they are called
- "historical prices".) These are often obtained from a stock exchange,
- cryptocurrency exchange, or the foreign exchange market.
-
- Here is the format:
-
- P DATE COMMODITYA COMMODITYBAMOUNT
-
- o DATE is a simple date
-
- o COMMODITYA is the symbol of the commodity being priced
-
- o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
- modity, giving the price in commodity B of one unit of commodity A.
-
- These two market price directives say that one euro was worth 1.35 US
- dollars during 2009, and $1.40 from 2010 onward:
-
- P 2009/1/1 EUR $1.35
- P 2010/1/1 EUR $1.40
-
- The -V, -X and --value flags use these market prices to show amount
- values in another commodity. See Valuation.
-
- Declaring accounts
- account directives can be used to declare accounts (ie, the places that
- amounts are transferred from and to). Though not required, these dec-
- larations can provide several benefits:
-
- o They can document your intended chart of accounts, providing a refer-
- ence.
-
- o They can help hledger know your accounts' types (asset, liability,
- equity, revenue, expense), useful for reports like balancesheet and
- incomestatement.
-
- o They control account display order in reports, allowing non-alpha-
- betic sorting (eg Revenues to appear above Expenses).
-
- o They can store extra information about accounts (account numbers,
- notes, etc.)
-
- o They help with account name completion in the add command, hledger-
- iadd, hledger-web, ledger-mode etc.
-
- o In strict mode, they restrict which accounts may be posted to by
- transactions, which helps detect typos.
-
- The simplest form is just the word account followed by a hledger-style
- account name, eg this account directive declares the assets:bank:check-
- ing account:
-
- account assets:bank:checking
-
- Account error checking
- By default, accounts come into existence when a transaction references
- them by name. This is convenient, but it means hledger can't warn you
- when you mis-spell an account name in the journal. Usually you'll find
- the error later, as an extra account in balance reports, or an incor-
- rect balance when reconciling.
-
- In strict mode, enabled with the -s/--strict flag, hledger will report
- an error if any transaction uses an account name that has not been
- declared by an account directive. Some notes:
-
- o The declaration is case-sensitive; transactions must use the correct
- account name capitalisation.
-
- o The account directive's scope is "whole file and below" (see direc-
- tives). This means it affects all of the current file, and any files
- it includes, but not parent or sibling files. The position of
- account directives within the file does not matter, though it's usual
- to put them at the top.
-
- o Accounts can only be declared in journal files (but will affect
- included files in other formats).
-
- o It's currently not possible to declare "all possible subaccounts"
- with a wildcard; every account posted to must be declared.
-
- Account comments
- Comments, beginning with a semicolon, can be added:
-
- o on the same line, after two or more spaces (because ; is allowed in
- account names)
-
- o on the next lines, indented
-
- An example of both:
-
- account assets:bank:checking ; same-line comment, note 2+ spaces before ;
- ; next-line comment
- ; another with tag, acctno:12345 (not used yet)
-
- Same-line comments are not supported by Ledger, or hledger <1.13.
-
- Account subdirectives
- We also allow (and ignore) Ledger-style indented subdirectives, just
- for compatibility.:
-
- account assets:bank:checking
- format blah blah ; <- subdirective, ignored
-
- Here is the full syntax of account directives:
-
- account ACCTNAME [ACCTTYPE] [;COMMENT]
- [;COMMENTS]
- [LEDGER-STYLE SUBDIRECTIVES, IGNORED]
-
- Account types
- hledger recognises five main types of account, corresponding to the
- account classes in the accounting equation:
-
- Asset, Liability, Equity, Revenue, Expense.
-
- These account types are important for controlling which accounts appear
- in the balancesheet, balancesheetequity, incomestatement reports (and
- probably for other things in future).
-
- Additionally, we recognise the Cash type, which is also an Asset, and
- which causes accounts to appear in the cashflow report. ("Cash" here
- means liquid assets, eg bank balances but typically not investments or
- receivables.)
-
- Declaring account types
- Generally, to make these reports work you should declare your top-level
- accounts and their types, using account directives with type: tags.
-
- The tag's value should be one of: Asset, Liability, Equity, Revenue,
- Expense, Cash, A, L, E, R, X, C (all case insensitive). The type is
- inherited by all subaccounts except where they override it. Here's a
- complete example:
-
- account assets ; type: Asset
- account assets:bank ; type: Cash
- account assets:cash ; type: Cash
- account liabilities ; type: Liability
- account equity ; type: Equity
- account revenues ; type: Revenue
- account expenses ; type: Expense
-
- Auto-detected account types
- If you happen to use common english top-level account names, you may
- not need to declare account types, as they will be detected automati-
- cally using the following rules:
-
-
- If name matches regular account type is:
- expression:
- ----------------------------------------------
- ^assets?(:|$) Asset
- ^(debts?|lia- Liability
- bilit(y|ies))(:|$)
- ^equity(:|$) Equity
- ^(income|revenue)s?(:|$) Revenue
- ^expenses?(:|$) Expense
-
-
- If account type is Asset and name does not contain regu- account type
- lar expression: is:
- --------------------------------------------------------------------------
- (investment|receivable|:A/R|:fixed) Cash
-
- Even so, explicit declarations may be a good idea, for clarity and pre-
- dictability.
-
- Interference from auto-detected account types
- If you assign any account type, it's a good idea to assign all of them,
- to prevent any confusion from mixing declared and auto-detected types.
- Although it's unlikely to happen in real life, here's an example: with
- the following journal, balancesheetequity shows "liabilities" in both
- Liabilities and Equity sections. Declaring another account as
- type:Liability would fix it:
-
- account liabilities ; type:Equity
-
- 2020-01-01
- assets 1
- liabilities 1
- equity -2
-
- Old account type syntax
- In some hledger journals you might instead see this old syntax (the
- letters ALERX, separated from the account name by two or more spaces);
- this is deprecated and may be removed soon:
-
- account assets A
- account liabilities L
- account equity E
- account revenues R
- account expenses X
-
- Account display order
- Account directives also set the order in which accounts are displayed,
- eg in reports, the hledger-ui accounts screen, and the hledger-web
- sidebar. By default accounts are listed in alphabetical order. But if
- you have these account directives in the journal:
-
- account assets
- account liabilities
- account equity
- account revenues
- account expenses
-
- you'll see those accounts displayed in declaration order, not alphabet-
- ically:
-
- $ hledger accounts -1
- assets
- liabilities
- equity
- revenues
- expenses
-
- Undeclared accounts, if any, are displayed last, in alphabetical order.
-
- Note that sorting is done at each level of the account tree (within
- each group of sibling accounts under the same parent). And currently,
- this directive:
-
- account other:zoo
-
- would influence the position of zoo among other's subaccounts, but not
- the position of other among the top-level accounts. This means:
-
- o you will sometimes declare parent accounts (eg account other above)
- that you don't intend to post to, just to customize their display
- order
-
- o sibling accounts stay together (you couldn't display x:y in between
- a:b and a:c).
-
- Rewriting accounts
- You can define account alias rules which rewrite your account names, or
- parts of them, before generating reports. This can be useful for:
-
- o expanding shorthand account names to their full form, allowing easier
- data entry and a less verbose journal
-
- o adapting old journals to your current chart of accounts
-
- o experimenting with new account organisations, like a new hierarchy or
- combining two accounts into one
-
- o customising reports
-
- Account aliases also rewrite account names in account directives. They
- do not affect account names being entered via hledger add or hledger-
- web.
-
- See also Rewrite account names.
-
- Basic aliases
- To set an account alias, use the alias directive in your journal file.
- This affects all subsequent journal entries in the current file or its
- included files. The spaces around the = are optional:
-
- alias OLD = NEW
-
- Or, you can use the --alias 'OLD=NEW' option on the command line. This
- affects all entries. It's useful for trying out aliases interactively.
-
- OLD and NEW are case sensitive full account names. hledger will
- replace any occurrence of the old account name with the new one. Sub-
- accounts are also affected. Eg:
-
- alias checking = assets:bank:wells fargo:checking
- ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
-
- Regex aliases
- There is also a more powerful variant that uses a regular expression,
- indicated by the forward slashes:
-
- alias /REGEX/ = REPLACEMENT
-
- or --alias '/REGEX/=REPLACEMENT'.
-
- REGEX is a case-insensitive regular expression. Anywhere it matches
- inside an account name, the matched part will be replaced by REPLACE-
- MENT. If REGEX contains parenthesised match groups, these can be ref-
- erenced by the usual numeric backreferences in REPLACEMENT. Eg:
-
- alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
- ; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
-
- Also note that REPLACEMENT continues to the end of line (or on command
- line, to end of option argument), so it can contain trailing white-
- space.
-
- Combining aliases
- You can define as many aliases as you like, using journal directives
- and/or command line options.
-
- Recursive aliases - where an account name is rewritten by one alias,
- then by another alias, and so on - are allowed. Each alias sees the
- effect of previously applied aliases.
-
- In such cases it can be important to understand which aliases will be
- applied and in which order. For (each account name in) each journal
- entry, we apply:
-
- 1. alias directives preceding the journal entry, most recently parsed
- first (ie, reading upward from the journal entry, bottom to top)
-
- 2. --alias options, in the order they appeared on the command line
- (left to right).
-
- In other words, for (an account name in) a given journal entry:
-
- o the nearest alias declaration before/above the entry is applied first
-
- o the next alias before/above that will be be applied next, and so on
-
- o aliases defined after/below the entry do not affect it.
-
- This gives nearby aliases precedence over distant ones, and helps pro-
- vide semantic stability - aliases will keep working the same way inde-
- pendent of which files are being read and in which order.
-
- In case of trouble, adding --debug=6 to the command line will show
- which aliases are being applied when.
-
- Aliases and multiple files
- As explained at Directives and multiple files, alias directives do not
- affect parent or sibling files. Eg in this command,
-
- hledger -f a.aliases -f b.journal
-
- account aliases defined in a.aliases will not affect b.journal.
- Including the aliases doesn't work either:
-
- include a.aliases
-
- 2020-01-01 ; not affected by a.aliases
- foo 1
- bar
-
- This means that account aliases should usually be declared at the start
- of your top-most file, like this:
-
- alias foo=Foo
- alias bar=Bar
-
- 2020-01-01 ; affected by aliases above
- foo 1
- bar
-
- include c.journal ; also affected
-
- end aliases
- You can clear (forget) all currently defined aliases with the end
- aliases directive:
-
- end aliases
-
- Default parent account
- You can specify a parent account which will be prepended to all
- accounts within a section of the journal. Use the apply account and
- end apply account directives like so:
-
- apply account home
-
- 2010/1/1
- food $10
- cash
-
- end apply account
-
- which is equivalent to:
-
- 2010/01/01
- home:food $10
- home:cash $-10
-
- If end apply account is omitted, the effect lasts to the end of the
- file. Included files are also affected, eg:
-
- apply account business
- include biz.journal
- end apply account
- apply account personal
- include personal.journal
-
- Prior to hledger 1.0, legacy account and end spellings were also sup-
- ported.
-
- A default parent account also affects account directives. It does not
- affect account names being entered via hledger add or hledger-web. If
- account aliases are present, they are applied after the default parent
- account.
-
-PERIODIC TRANSACTIONS
- Periodic transaction rules describe transactions that recur. They
- allow hledger to generate temporary future transactions to help with
- forecasting, so you don't have to write out each one in the journal,
- and it's easy to try out different forecasts.
-
- Periodic transactions can be a little tricky, so before you use them,
- read this whole section - or at least these tips:
-
- 1. Two spaces accidentally added or omitted will cause you trouble -
- read about this below.
-
- 2. For troubleshooting, show the generated transactions with hledger
- print --forecast tag:generated or hledger register --forecast
- tag:generated.
-
- 3. Forecasted transactions will begin only after the last non-fore-
- casted transaction's date.
-
- 4. Forecasted transactions will end 6 months from today, by default.
- See below for the exact start/end rules.
-
- 5. period expressions can be tricky. Their documentation needs
- improvement, but is worth studying.
-
- 6. Some period expressions with a repeating interval must begin on a
- natural boundary of that interval. Eg in weekly from DATE, DATE
- must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an
- error.
-
- 7. Other period expressions with an interval are automatically expanded
- to cover a whole number of that interval. (This is done to improve
- reports, but it also affects periodic transactions. Yes, it's a bit
- inconsistent with the above.) Eg: ~ every 10th day of month from
- 2020/01, which is equivalent to ~ every 10th day of month from
- 2020/01/01, will be adjusted to start on 2019/12/10.
-
- Periodic transaction rules also have a second meaning: they are used to
- define budget goals, shown in budget reports.
-
- Periodic rule syntax
- A periodic transaction rule looks like a normal journal entry, with the
- date replaced by a tilde (~) followed by a period expression (mnemonic:
- ~ looks like a recurring sine wave.):
-
- ~ monthly
- expenses:rent $2000
- assets:bank:checking
-
- There is an additional constraint on the period expression: the start
- date must fall on a natural boundary of the interval. Eg monthly from
- 2018/1/1 is valid, but monthly from 2018/1/15 is not.
-
- Partial or relative dates (M/D, D, tomorrow, last week) in the period
- expression can work (useful or not). They will be relative to today's
- date, unless a Y default year directive is in effect, in which case
- they will be relative to Y/1/1.
-
- Two spaces between period expression and description!
- If the period expression is followed by a transaction description,
- these must be separated by two or more spaces. This helps hledger know
- where the period expression ends, so that descriptions can not acciden-
- tally alter their meaning, as in this example:
-
- ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"
- ; ||
- ; vv
- ~ every 2 months in 2020, we will review
- assets:bank:checking $1500
- income:acme inc
-
- So,
-
- o Do write two spaces between your period expression and your transac-
- tion description, if any.
-
- o Don't accidentally write two spaces in the middle of your period
- expression.
-
- Forecasting with periodic transactions
- The --forecast flag activates any periodic transaction rules in the
- journal. They will generate temporary recurring transactions, which
- are not saved in the journal, but will appear in all reports (eg
- print). This can be useful for estimating balances into the future, or
- experimenting with different scenarios. Or, it can be used as a data
- entry aid: describe recurring transactions, and every so often copy the
- output of print --forecast into the journal.
-
- These transactions will have an extra tag indicating which periodic
- rule generated them: generated-transaction:~ PERIODICEXPR. And a simi-
- lar, hidden tag (beginning with an underscore) which, because it's
- never displayed by print, can be used to match transactions generated
- "just now": _generated-transaction:~ PERIODICEXPR.
-
- Periodic transactions are generated within some forecast period. By
- default, this
-
- o begins on the later of
-
- o the report start date if specified with -b/-p/date:
-
- o the day after the latest normal (non-periodic) transaction in the
- journal, or today if there are no normal transactions.
-
- o ends on the report end date if specified with -e/-p/date:, or 6
- months (180 days) from today.
-
- This means that periodic transactions will begin only after the latest
- recorded transaction. And a recorded transaction dated in the future
- can prevent generation of periodic transactions. (You can avoid that
- by writing the future transaction as a one-time periodic rule instead -
- put tilde before the date, eg ~ YYYY-MM-DD ...).
-
- Or, you can set your own arbitrary "forecast period", which can overlap
- recorded transactions, and need not be in the future, by providing an
- option argument, like --forecast=PERIODEXPR. Note the equals sign is
- required, a space won't work. PERIODEXPR is a period expression, which
- can specify the start date, end date, or both, like in a date: query.
- (See also hledger.1 -> Report start & end date). Some examples:
- --forecast=202001-202004, --forecast=jan-, --forecast=2020.
-
- Budgeting with periodic transactions
- With the --budget flag, currently supported by the balance command,
- each periodic transaction rule declares recurring budget goals for the
- specified accounts. Eg the first example above declares a goal of
- spending $2000 on rent (and also, a goal of depositing $2000 into
- checking) every month. Goals and actual performance can then be com-
- pared in budget reports.
-
- See also: Budgeting and Forecasting.
-
-
-AUTO POSTINGS
- "Automated postings" or "auto postings" are extra postings which get
- added automatically to transactions which match certain queries,
- defined by "auto posting rules", when you use the --auto flag.
-
- An auto posting rule looks a bit like a transaction:
-
- = QUERY
- ACCOUNT AMOUNT
- ...
- ACCOUNT [AMOUNT]
-
- except the first line is an equals sign (mnemonic: = suggests match-
- ing), followed by a query (which matches existing postings), and each
- "posting" line describes a posting to be generated, and the posting
- amounts can be:
-
- o a normal amount with a commodity symbol, eg $2. This will be used
- as-is.
-
- o a number, eg 2. The commodity symbol (if any) from the matched post-
- ing will be added to this.
-
- o a numeric multiplier, eg *2 (a star followed by a number N). The
- matched posting's amount (and total price, if any) will be multiplied
- by N.
-
- o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
- symbol S). The matched posting's amount will be multiplied by N, and
- its commodity symbol will be replaced with S.
-
- Any query term containing spaces must be enclosed in single or double
- quotes, as on the command line. Eg, note the quotes around the second
- query term below:
-
- = expenses:groceries 'expenses:dining out'
- (budget:funds:dining out) *-1
-
- Some examples:
-
- ; every time I buy food, schedule a dollar donation
- = expenses:food
- (liabilities:charity) $-1
-
- ; when I buy a gift, also deduct that amount from a budget envelope subaccount
- = expenses:gifts
- assets:checking:gifts *-1
- assets:checking *1
-
- 2017/12/1
- expenses:food $10
- assets:checking
-
- 2017/12/14
- expenses:gifts $20
- assets:checking
-
- $ hledger print --auto
- 2017-12-01
- expenses:food $10
- assets:checking
- (liabilities:charity) $-1
-
- 2017-12-14
- expenses:gifts $20
- assets:checking
- assets:checking:gifts -$20
- assets:checking $20
-
- Auto postings and multiple files
- An auto posting rule can affect any transaction in the current file, or
- in any parent file or child file. Note, currently it will not affect
- sibling files (when multiple -f/--file are used - see #1212).
-
- Auto postings and dates
- A posting date (or secondary date) in the matched posting, or (taking
- precedence) a posting date in the auto posting rule itself, will also
- be used in the generated posting.
-
- Auto postings and transaction balancing / inferred amounts / balance asser-
- tions
- Currently, auto postings are added:
-
- o after missing amounts are inferred, and transactions are checked for
- balancedness,
-
- o but before balance assertions are checked.
-
- Note this means that journal entries must be balanced both before and
- after auto postings are added. This changed in hledger 1.12+; see #893
- for background.
-
- Auto posting tags
- Automated postings will have some extra tags:
-
- o generated-posting:= QUERY - shows this was generated by an auto post-
- ing rule, and the query
-
- o _generated-posting:= QUERY - a hidden tag, which does not appear in
- hledger's output. This can be used to match postings generated "just
- now", rather than generated in the past and saved to the journal.
-
- Also, any transaction that has been changed by auto posting rules will
- have these tags added:
-
- o modified: - this transaction was modified
-
- o _modified: - a hidden tag not appearing in the comment; this transac-
- tion was modified "just now".
-
-
-
-REPORTING BUGS
- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
- or hledger mail list)
-
-
-AUTHORS
- Simon Michael <simon@joyful.com> and contributors
-
-
-COPYRIGHT
- Copyright (C) 2007-2020 Simon Michael.
- Released under GNU GPL v3 or later.
-
-
-SEE ALSO
- hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
-
- hledger_journal(5), hledger_csv(5), hledger_timeclock(5), hledger_time-
- dot(5)
-
-
-
-hledger-lib-1.20.4 December 2020 HLEDGER_JOURNAL(5)