diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 4ac42c16a..9a749d078 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -406,14 +406,6 @@ until the next reload). On this screen (and the register screen), the \f[CR]E\f[R] key will open your text editor with the cursor positioned at the current transaction if possible. -.PP -This screen has a limitation with showing file updates: it will not show -them until you exit and re\-enter it. -So eg to see the effect of using the \f[CR]E\f[R] key, currently you -must: \- press \f[CR]E\f[R], edit and save the file, then exit the -editor, returning to hledger\-ui \- press \f[CR]g\f[R] to reload the -file (or use \f[CR]\-w/\-\-watch\f[R] mode) \- press \f[CR]LEFT\f[R] -then \f[CR]RIGHT\f[R] to exit and re\-enter the transaction screen. .SS Error screen This screen will appear if there is a problem, such as a parse error, when you press g to reload. @@ -495,10 +487,6 @@ stdin). \f[CR]\-\-watch\f[R] is not robust, especially with large files (see WATCH MODE above). .PP -The Transaction screen does not update after file changes, even if you -press \f[CR]g\f[R], until you exit and re\-enter it. -(#2288) -.PP If you press \f[CR]g\f[R] with large files, there could be a noticeable pause with the UI unresponsive. diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index e769d9593..104964cf1 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -453,13 +453,6 @@ reload). text editor with the cursor positioned at the current transaction if possible. - This screen has a limitation with showing file updates: it will not -show them until you exit and re-enter it. So eg to see the effect of -using the 'E' key, currently you must: - press 'E', edit and save the -file, then exit the editor, returning to hledger-ui - press 'g' to -reload the file (or use '-w/--watch' mode) - press 'LEFT' then 'RIGHT' -to exit and re-enter the transaction screen. -  File: hledger-ui.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS @@ -556,9 +549,6 @@ We welcome bug reports in the hledger issue tracker '--watch' is not robust, especially with large files (see WATCH MODE above). - The Transaction screen does not update after file changes, even if -you press 'g', until you exit and re-enter it. (#2288) - If you press 'g' with large files, there could be a noticeable pause with the UI unresponsive. @@ -576,11 +566,11 @@ Node: Income statement accounts screen15844 Node: All accounts screen16229 Node: Register screen16592 Node: Transaction screen19035 -Node: Error screen20610 -Node: WATCH MODE20976 -Node: --watch problems21874 -Node: ENVIRONMENT23227 -Node: BUGS23460 +Node: Error screen20215 +Node: WATCH MODE20581 +Node: --watch problems21479 +Node: ENVIRONMENT22832 +Node: BUGS23065  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index eec278da8..1b4e28012 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -366,13 +366,6 @@ SCREENS editor with the cursor positioned at the current transaction if possi- ble. - This screen has a limitation with showing file updates: it will not - show them until you exit and re-enter it. So eg to see the effect of - using the E key, currently you must: - press E, edit and save the file, - then exit the editor, returning to hledger-ui - press g to reload the - file (or use -w/--watch mode) - press LEFT then RIGHT to exit and - re-enter the transaction screen. - Error screen This screen will appear if there is a problem, such as a parse error, when you press g to reload. Once you have fixed the problem, press g @@ -447,9 +440,6 @@ BUGS --watch is not robust, especially with large files (see WATCH MODE above). - The Transaction screen does not update after file changes, even if you - press g, until you exit and re-enter it. (#2288) - If you press g with large files, there could be a noticeable pause with the UI unresponsive. diff --git a/hledger/hledger.1 b/hledger/hledger.1 index ef151da4c..33e4003c0 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -829,7 +829,7 @@ Here\[aq]s a small example: \f[I]# Options following a \[ga][COMMAND]\[ga] heading are used with that hledger command only.\f[R] \f[B][print]\f[R] -\-\-explicit \-\-show\-costs +\-\-explicit \-\-infer\-costs .EE .PP To use a config file, specify it with the \f[CR]\-\-conf\f[R] option. @@ -1413,7 +1413,7 @@ Editor add\-ons 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. +See Editors at hledger.org for the full list. .PP A hledger journal file can contain three kinds of thing: comment lines, transactions, and/or directives (including periodic transaction rules @@ -1630,7 +1630,10 @@ dates documented in the hledger manual.) .SS 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 \f[CR]date:DATE\f[R]. +like \f[CR]; date:DATE\f[R]. +(There\[aq]s also a Ledger\-compatible syntax, \f[CR]; [DATE]\f[R], +which can be convenient.) +.PP 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 @@ -1807,10 +1810,15 @@ is common), followed by: (optional) a status character (empty, \f[CR]!\f[R], or \f[CR]*\f[R]), followed by a space .IP \[bu] 2 -(required) an account name (any text, optionally containing \f[B]single -spaces\f[R], until end of line or a double space) +(required) an account name (any text, optionally including single +spaces. +If anything follows the account name on the same line, the account name +must be ended by \f[B]two or more spaces\f[R].) .IP \[bu] 2 -(optional) \f[B]two or more spaces\f[R] (or tabs) followed by an amount. +(optional) an amount +.IP \[bu] 2 +(optional) a same\-line posting comment, beginning with a semicolon +(\f[CR];\f[R]). .PP If the amount is positive, it is being added to the account; if negative, it is being removed from the account. @@ -1818,14 +1826,15 @@ negative, it is being removed from the account. The posting amounts in a transaction must sum up to zero, indicating that the inflows and outflows are equal. We call this a balanced transaction. -(You can read more about the nitty\-gritty details of \[dq]sum up to -zero\[dq] in Transaction balancing below.) +(You can read more about the details of transaction balancing below.) .PP -As a convenience, you can optionally leave one amount blank; hledger -will infer what it should be so as to balance the transaction. +If no amount is written, it will be calculated automatically from the +other postings in the transaction, so as to balance the transaction. +In other words, in any transaction you can leave one posting amountless +to save typing. .SS Debits and credits The traditional accounting concepts of debit and credit of course exist -in hledger, but we represent them with numeric sign, as described above. +in hledger, but we represent them with numeric sign. Positive and negative posting amounts represent debits and credits respectively. .PP @@ -1838,33 +1847,66 @@ handy mnemonic: .P .PD \f[I]\f[CI]credit / minus / right / longer words\f[I]\f[R] -.SS The two space delimiter -Be sure to notice the unusual separator between the account name and the -following amount. -Because hledger allows account names with spaces in them, you must -separate the account name and amount (if any) by \f[B]two or more -spaces\f[R] (or tabs). -It\[aq]s easy to forget at first. -If you ever see the amount being treated as part of the account name, -you\[aq]ll know you probably need to add another space between them. .SS Account names Accounts are the main way of categorising things in hledger. As in Double Entry Bookkeeping, they can represent real world accounts (such as a bank account), or more abstract categories such as \[dq]money -borrowed from Frank\[dq] or \[dq]money spent on electricity\[dq]. +spent on food\[dq] or \[dq]money borrowed from Frank\[dq]. +.PP +Account names are flexible. +They may be capitalised or not; they may contain letters, numbers, +punctuation, symbols, or single spaces; they may be in any language. +.PP +Typically we use the five traditional accounting categories as the +starting point for account names. +In english they are: .PP -You can use any account names you like, but we usually start with the -traditional accounting categories, which in english are \f[CR]assets\f[R], \f[CR]liabilities\f[R], \f[CR]equity\f[R], -\f[CR]revenues\f[R], \f[CR]expenses\f[R]. -(You might see these referred to as A, L, E, R, X for short.) +\f[CR]revenues\f[R], \f[CR]expenses\f[R] .PP -For more precise reporting, we usually divide the top level accounts -into more detailed subaccounts, by writing a full colon between account -name parts. -For example, from the account names \f[CR]assets:bank:checking\f[R] and -\f[CR]expenses:food\f[R], hledger will infer this hierarchy of five -accounts: +These will be discussed more in Account types below. +In hledger docs you may see them referred to as A, L, E, R, X for short. +.SS The two space delimiter +Note the \f[B]two or more spaces\f[R] delimiter that\[aq]s sometimes +required after account names. +\ hledger\[aq]s account names, inherited from Ledger, are very +permissive; they may contain pretty much any kind of text, including +single spaces and semicolons. +Because of this, they must be terminated by \f[B]two or more spaces\f[R] +if there is anything following them on the same line. +For example, if an amount, balance assignment, or same\-line comment +follows an account name, they must be preceded by two or more spaces, +else they would be considered part of the account name: +.IP +.EX +bad: assets:accounts receivable $10 ; <\- too close! +good: assets:accounts receivable $10 +.EE +.IP +.EX +bad: assets:accounts receivable =$1000 ; <\- too close! +good: assets:accounts receivable =$1000 +.EE +.IP +.EX +bad: assets:accounts receivable ; comment. <\- too close! +good: assets:accounts receivable ; comment +.EE +.PP +This two\-space delimiter appears in a few places in hledger, such as +after account names in postings or account directives; also after the +period expression in periodic transaction rules. +When you are starting out, expect it to catch you out at least once. +It\[aq]s annoying sometimes, but it lets us use expressive account names +while still keeping the syntax light. +.SS Account hierarchy +For more precise reporting, we usually divide accounts into more +detailed subaccounts, subsubaccounts, and so on, by writing a full colon +between account name parts. +For example, instead of writing \f[CR]assets\f[R] and +\f[CR]expenses\f[R], we might write \f[CR]assets:bank:checking\f[R] and +\f[CR]expenses:food\f[R]. +From these names hledger will infer this hierarchy of five accounts: .IP .EX assets @@ -1874,7 +1916,7 @@ expenses expenses:food .EE .PP -Shown as an outline, the hierarchical tree structure is more clear: +Or as an outline: .IP .EX assets @@ -1885,21 +1927,16 @@ expenses .EE .PP hledger reports can summarise the account tree to any depth, so you can -go as deep as you like with subcategories, but keeping your account -names relatively simple may be best when starting out. +make your subcategories as detailed as you like. +But don\[aq]t go overboard, especially when getting started; simpler +categories can be less work. +.SS Other account name features +Enclosing the account name in parentheses or brackets, like +\f[CR](expenses:food)\f[R], enables a non\-standard bookkeeping feature: +virtual postings. .PP -Account names may be capitalised or not; they may contain letters, -numbers, symbols, or single spaces. -Note, when an account name and an amount are written on the same line, -they must be separated by \f[B]two or more spaces\f[R] (or tabs). -.PP -Parentheses or brackets enclosing the full account name indicate virtual -postings, described below. -Parentheses or brackets internal to the account name have no special -meaning. -.PP -Account names can be altered temporarily or permanently by account -aliases. +Account names can be rewritten and restructured, temporarily or +permanently, by account aliases. .SS Amounts After the account name, there is usually an amount. (Remember: between account name and amount, there must be two or more @@ -6694,46 +6731,37 @@ With the \f[CR]\-\-depth NUM\f[R] option (short form: \f[CR]\-NUM\f[R]), reports will show accounts only to the specified depth, hiding deeper subaccounts. Use this when you want a summary with less detail. -This flag has the same effect as a \f[CR]depth:\f[R] query argument: -\f[CR]depth:2\f[R], \f[CR]\-\-depth=2\f[R] or \f[CR]\-2\f[R] are -equivalent. +This flag has the same effect as a \f[CR]depth:\f[R] query argument. +So all of these are equivalent: \f[CR]depth:2\f[R], +\f[CR]\-\-depth=2\f[R], \f[CR]\-2\f[R]. .PP In place of a single number which limits the depth for all accounts, you -can also provide separate depth limits for different accounts using -regular expressions \f[I](since 1.41)\f[R]. -.PP -For example, \f[CR]\-\-depth assets=2\f[R] (or, equivalently: +can also provide depth limits for specific accounts, by providing a +\f[CR]REGEX=DEPTH\f[R] argument instead of just a \f[CR]DEPTH\f[R] +\f[I](since 1.41)\f[R]. +For example, \f[CR]\-\-depth assets=2\f[R] (or \f[CR]depth:assets=2\f[R]) will collapse accounts matching the regular -expression \f[CR]assets\f[R] to depth 2. +expression \[dq]assets\[dq] to depth 2. So \f[CR]assets:bank:savings\f[R] would be collapsed to -\f[CR]assets:bank\f[R], while \f[CR]liabilities:bank:credit card\f[R] +\f[CR]assets:bank\f[R], but \f[CR]liabilities:bank:credit card\f[R] would not be affected. -This can be combined with a flat depth to collapse other accounts not -matching the regular expression, so -\f[CR]\-\-depth assets=2 \-\-depth 1\f[R] would collapse -\f[CR]assets:bank:savings\f[R] to \f[CR]assets:bank\f[R] and -\f[CR]liabilities:bank:credit card\f[R] to \f[CR]liabilities\f[R]. .PP -You can supply multiple depth arguments and they will all be applied, so -\f[CR]\-\-depth assets=2 \-\-depth liabilities=3 \-\-depth 1\f[R] would -collapse: -.IP \[bu] 2 -accounts matching \f[CR]assets\f[R] to depth 2, -.IP \[bu] 2 -accounts matching \f[CR]liabilities\f[R] to depth 3, -.IP \[bu] 2 -all other accounts to depth 1. +(If REGEX contains spaces or other special characters, enclose it in +quotes in the usual way. +Eg: \f[CR]\-\-depth \[aq]credit card=2\[aq]\f[R]) +.PP +Specific depth options and a general depth option can be combined. +Eg \f[CR]\-\-depth assets=3 \-\-depth expenses=2 \-\-depth 1\f[R] would +collapse accounts containing \[dq]assets\[dq] to depth 3, accounts +containing \[dq]expenses\[dq] to depth 2, and all other accounts to +depth 1. .PP If an account is matched by more than one regular expression depth -argument then the more specific one will be used. -For example, if -\f[CR]\-\-depth assets=1 \-\-depth assets:bank:savings=2\f[R] is -provided, then \f[CR]assets:bank:savings\f[R] will be collapsed to depth -2 rather than depth 1. -This is because \f[CR]assets:bank:savings\f[R] matches at level 3 in the -account name, while \f[CR]assets\f[R] matches at level 1. -The same would be true with the argument -\f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R]. +argument, the most specific (deepest) match will be used. +For example, with \f[CR]\-\-depth assets=1 \-\-depth savings=2\f[R], +\f[CR]assets:bank:savings\f[R] will be collapsed to depth 2, not depth 1 +(because \[dq]savings\[dq] matches a deeper part of it than +\[dq]assets\[dq] does). .SH Queries Many hledger commands accept query arguments, which restrict their scope and let you report on a precise subset of your data. @@ -8265,7 +8293,6 @@ Related: #1625 .SS Effect of valuation on reports Here is a reference for how valuation is supposed to affect each part of hledger\[aq]s reports. -(It\[aq]s wide, you may need to scroll sideways.) It may be useful when troubleshooting. If you find problems, please report them, ideally with a reproducible example. @@ -9709,8 +9736,16 @@ Show full journal entries, representing transactions. .EX Flags: \-x \-\-explicit show all amounts explicitly - \-\-show\-costs show transaction prices even with conversion - postings + \-\-invert display all amounts with reversed sign + \-\-location add tags showing file paths and line numbers + \-m \-\-match=DESC fuzzy search for one recent transaction with + description closest to DESC + \-\-new show only newer\-dated transactions added in each + file since last run + \-\-no\-lots remove lot subaccounts and their balance + assertions + \-\-no\-lots2 remove lot subaccounts and their costs and + balance assertions (can produce unbalanced entries) \-\-round=TYPE how much rounding or padding should be done when displaying amounts ? none \- show original decimal digits, @@ -9721,15 +9756,9 @@ Flags: (can unbalance transactions) all \- also round cost amounts to precision (can unbalance transactions) - \-\-invert display all amounts with reversed sign - \-\-new show only newer\-dated transactions added in each - file since last run - \-m \-\-match=DESC fuzzy search for one recent transaction with - description closest to DESC \-\-base\-url=URLPREFIX in html output, generate links to hledger\-web, with this prefix. (Usually the base url shown by hledger\-web; can also be relative.) - \-\-location add tags showing file paths and line numbers \-O \-\-output\-format=FMT select the output format. Supported formats: txt, beancount, csv, tsv, html, fods, json, sql. \-o \-\-output\-file=FILE write output to FILE. A file extension matching @@ -10191,7 +10220,7 @@ The \f[CR]\-\-depth\f[R] option helps with this, causing subaccounts to be aggregated: .IP .EX -$ hledger register \-\-monthly assets \-\-depth 1h +$ hledger register \-\-monthly assets \-\-depth 1 2008/01 assets $1 $1 2008/06 assets $\-1 0 2008/12 assets $\-1 $\-1 @@ -13214,13 +13243,16 @@ We welcome bug reports in the hledger issue tracker .PP Some known issues and limitations: .PP -A system locale with a suitable text encoding must be configured to work -with non\-ascii data. +hledger uses the system\[aq]s text encoding when reading non\-ascii +text. +If no system encoding is configured, or if the data\[aq]s encoding is +different, hledger will give an error. (See Text encoding, Troubleshooting.) .PP On Microsoft Windows, depending what kind of terminal window you use, non\-ascii characters, ANSI text formatting, and/or the add -command\[aq]s TAB key for completion, may not be supported. +command\[aq]s TAB key, may not be fully supported. +(For best results, try a powershell window.) .PP When processing large data files, hledger uses more memory than Ledger. .SS Troubleshooting diff --git a/hledger/hledger.info b/hledger/hledger.info index 918805a28..a79eeb357 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -840,7 +840,7 @@ example: # Options following a `[COMMAND]` heading are used with that hledger command only. [print] ---explicit --show-costs +--explicit --infer-costs To use a config file, specify it with the '--conf' option. Its options will be inserted near the start of your command line, so you can @@ -1390,8 +1390,8 @@ use the add or web or import commands to create and update it. track changes with a version control system such as git. Editor add-ons 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. +formatting, tab completion, and useful commands. See Editors at +hledger.org for the full list. A hledger journal file can contain three kinds of thing: comment lines, transactions, and/or directives (including periodic transaction @@ -1659,10 +1659,13 @@ File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: 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: +like '; date:DATE'. (There's also a Ledger-compatible syntax, '; +[DATE]', which can be convenient.) + + 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 @@ -1814,36 +1817,39 @@ 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. + * (required) an account name (any text, optionally including single + spaces. If anything follows the account name on the same line, the + account name must be ended by *two or more spaces*.) + * (optional) an amount + * (optional) a same-line posting comment, beginning with a semicolon + (';'). If the amount is positive, it is being added to the account; if negative, it is being removed from the account. The posting amounts in a transaction must sum up to zero, indicating that the inflows and outflows are equal. We call this a balanced -transaction. (You can read more about the nitty-gritty details of "sum -up to zero" in Transaction balancing below.) +transaction. (You can read more about the details of transaction +balancing below.) - As a convenience, you can optionally leave one amount blank; hledger -will infer what it should be so as to balance the transaction. + If no amount is written, it will be calculated automatically from the +other postings in the transaction, so as to balance the transaction. In +other words, in any transaction you can leave one posting amountless to +save typing. * Menu: * Debits and credits:: -* The two space delimiter::  -File: hledger.info, Node: Debits and credits, Next: The two space delimiter, Up: Postings +File: hledger.info, Node: Debits and credits, Up: Postings 8.9.1 Debits and credits ------------------------ The traditional accounting concepts of debit and credit of course exist -in hledger, but we represent them with numeric sign, as described above. -Positive and negative posting amounts represent debits and credits -respectively. +in hledger, but we represent them with numeric sign. Positive and +negative posting amounts represent debits and credits respectively. You don't need to remember that, but if you would like to - eg for helping newcomers or for talking with your accountant - here's a handy @@ -1852,19 +1858,6 @@ mnemonic: _'debit / plus / left / short words'_ _'credit / minus / right / longer words'_ - -File: hledger.info, Node: The two space delimiter, Prev: Debits and credits, Up: Postings - -8.9.2 The two space delimiter ------------------------------ - -Be sure to notice the unusual separator between the account name and the -following amount. Because hledger allows account names with spaces in -them, you must separate the account name and amount (if any) by *two or -more spaces* (or tabs). It's easy to forget at first. If you ever see -the amount being treated as part of the account name, you'll know you -probably need to add another space between them. -  File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal @@ -1873,18 +1866,70 @@ File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Accounts are the main way of categorising things in hledger. As in Double Entry Bookkeeping, they can represent real world accounts (such -as a bank account), or more abstract categories such as "money borrowed -from Frank" or "money spent on electricity". +as a bank account), or more abstract categories such as "money spent on +food" or "money borrowed from Frank". - You can use any account names you like, but we usually start with the -traditional accounting categories, which in english are 'assets', -'liabilities', 'equity', 'revenues', 'expenses'. (You might see these -referred to as A, L, E, R, X for short.) + Account names are flexible. They may be capitalised or not; they may +contain letters, numbers, punctuation, symbols, or single spaces; they +may be in any language. - For more precise reporting, we usually divide the top level accounts -into more detailed subaccounts, by writing a full colon between account -name parts. For example, from the account names 'assets:bank:checking' -and 'expenses:food', hledger will infer this hierarchy of five accounts: + Typically we use the five traditional accounting categories as the +starting point for account names. In english they are: + + 'assets', 'liabilities', 'equity', 'revenues', 'expenses' + + These will be discussed more in Account types below. In hledger docs +you may see them referred to as A, L, E, R, X for short. + +* Menu: + +* The two space delimiter:: +* Account hierarchy:: +* Other account name features:: + + +File: hledger.info, Node: The two space delimiter, Next: Account hierarchy, Up: Account names + +8.10.1 The two space delimiter +------------------------------ + +Note the *two or more spaces* delimiter that's sometimes required after +account names. hledger's account names, inherited from Ledger, are very +permissive; they may contain pretty much any kind of text, including +single spaces and semicolons. Because of this, they must be terminated +by *two or more spaces* if there is anything following them on the same +line. For example, if an amount, balance assignment, or same-line +comment follows an account name, they must be preceded by two or more +spaces, else they would be considered part of the account name: + +bad: assets:accounts receivable $10 ; <- too close! +good: assets:accounts receivable $10 + +bad: assets:accounts receivable =$1000 ; <- too close! +good: assets:accounts receivable =$1000 + +bad: assets:accounts receivable ; comment. <- too close! +good: assets:accounts receivable ; comment + + This two-space delimiter appears in a few places in hledger, such as +after account names in postings or account directives; also after the +period expression in periodic transaction rules. When you are starting +out, expect it to catch you out at least once. It's annoying sometimes, +but it lets us use expressive account names while still keeping the +syntax light. + + +File: hledger.info, Node: Account hierarchy, Next: Other account name features, Prev: The two space delimiter, Up: Account names + +8.10.2 Account hierarchy +------------------------ + +For more precise reporting, we usually divide accounts into more +detailed subaccounts, subsubaccounts, and so on, by writing a full colon +between account name parts. For example, instead of writing 'assets' +and 'expenses', we might write 'assets:bank:checking' and +'expenses:food'. From these names hledger will infer this hierarchy of +five accounts: assets assets:bank @@ -1892,7 +1937,7 @@ assets:bank:checking expenses expenses:food - Shown as an outline, the hierarchical tree structure is more clear: + Or as an outline: assets bank @@ -1901,20 +1946,22 @@ expenses food hledger reports can summarise the account tree to any depth, so you -can go as deep as you like with subcategories, but keeping your account -names relatively simple may be best when starting out. +can make your subcategories as detailed as you like. But don't go +overboard, especially when getting started; simpler categories can be +less work. - Account names may be capitalised or not; they may contain letters, -numbers, symbols, or single spaces. Note, when an account name and an -amount are written on the same line, they must be separated by *two or -more spaces* (or tabs). + +File: hledger.info, Node: Other account name features, Prev: Account hierarchy, Up: Account names - Parentheses or brackets enclosing the full account name indicate -virtual postings, described below. Parentheses or brackets internal to -the account name have no special meaning. +8.10.3 Other account name features +---------------------------------- - Account names can be altered temporarily or permanently by account -aliases. +Enclosing the account name in parentheses or brackets, like +'(expenses:food)', enables a non-standard bookkeeping feature: virtual +postings. + + Account names can be rewritten and restructured, temporarily or +permanently, by account aliases.  File: hledger.info, Node: Amounts, Next: Balance assertions, Prev: Account names, Up: Journal @@ -6528,36 +6575,30 @@ File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top With the '--depth NUM' option (short form: '-NUM'), reports will show accounts only to the specified depth, hiding deeper subaccounts. Use this when you want a summary with less detail. This flag has the same -effect as a 'depth:' query argument: 'depth:2', '--depth=2' or '-2' are -equivalent. +effect as a 'depth:' query argument. So all of these are equivalent: +'depth:2', '--depth=2', '-2'. In place of a single number which limits the depth for all accounts, -you can also provide separate depth limits for different accounts using -regular expressions _(since 1.41)_. +you can also provide depth limits for specific accounts, by providing a +'REGEX=DEPTH' argument instead of just a 'DEPTH' _(since 1.41)_. For +example, '--depth assets=2' (or 'depth:assets=2') will collapse accounts +matching the regular expression "assets" to depth 2. So +'assets:bank:savings' would be collapsed to 'assets:bank', but +'liabilities:bank:credit card' would not be affected. - For example, '--depth assets=2' (or, equivalently: 'depth:assets=2') -will collapse accounts matching the regular expression 'assets' to depth -2. So 'assets:bank:savings' would be collapsed to 'assets:bank', while -'liabilities:bank:credit card' would not be affected. This can be -combined with a flat depth to collapse other accounts not matching the -regular expression, so '--depth assets=2 --depth 1' would collapse -'assets:bank:savings' to 'assets:bank' and 'liabilities:bank:credit -card' to 'liabilities'. + (If REGEX contains spaces or other special characters, enclose it in +quotes in the usual way. Eg: '--depth 'credit card=2'') - You can supply multiple depth arguments and they will all be applied, -so '--depth assets=2 --depth liabilities=3 --depth 1' would collapse: - - * accounts matching 'assets' to depth 2, - * accounts matching 'liabilities' to depth 3, - * all other accounts to depth 1. + Specific depth options and a general depth option can be combined. +Eg '--depth assets=3 --depth expenses=2 --depth 1' would collapse +accounts containing "assets" to depth 3, accounts containing "expenses" +to depth 2, and all other accounts to depth 1. If an account is matched by more than one regular expression depth -argument then the more specific one will be used. For example, if -'--depth assets=1 --depth assets:bank:savings=2' is provided, then -'assets:bank:savings' will be collapsed to depth 2 rather than depth 1. -This is because 'assets:bank:savings' matches at level 3 in the account -name, while 'assets' matches at level 1. The same would be true with -the argument '--depth assets=1 --depth savings=2'. +argument, the most specific (deepest) match will be used. For example, +with '--depth assets=1 --depth savings=2', 'assets:bank:savings' will be +collapsed to depth 2, not depth 1 (because "savings" matches a deeper +part of it than "assets" does).  File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top @@ -8128,9 +8169,9 @@ File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of ==================================== Here is a reference for how valuation is supposed to affect each part of -hledger's reports. (It's wide, you may need to scroll sideways.) It -may be useful when troubleshooting. If you find problems, please report -them, ideally with a reproducible example. Related: #329, #1083. +hledger's reports. It may be useful when troubleshooting. If you find +problems, please report them, ideally with a reproducible example. +Related: #329, #1083. First, a quick glossary: @@ -9459,8 +9500,16 @@ Show full journal entries, representing transactions. Flags: -x --explicit show all amounts explicitly - --show-costs show transaction prices even with conversion - postings + --invert display all amounts with reversed sign + --location add tags showing file paths and line numbers + -m --match=DESC fuzzy search for one recent transaction with + description closest to DESC + --new show only newer-dated transactions added in each + file since last run + --no-lots remove lot subaccounts and their balance + assertions + --no-lots2 remove lot subaccounts and their costs and + balance assertions (can produce unbalanced entries) --round=TYPE how much rounding or padding should be done when displaying amounts ? none - show original decimal digits, @@ -9471,15 +9520,9 @@ Flags: (can unbalance transactions) all - also round cost amounts to precision (can unbalance transactions) - --invert display all amounts with reversed sign - --new show only newer-dated transactions added in each - file since last run - -m --match=DESC fuzzy search for one recent transaction with - description closest to DESC --base-url=URLPREFIX in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by hledger-web; can also be relative.) - --location add tags showing file paths and line numbers -O --output-format=FMT select the output format. Supported formats: txt, beancount, csv, tsv, html, fods, json, sql. -o --output-file=FILE write output to FILE. A file extension matching @@ -9928,7 +9971,7 @@ $ hledger register --monthly income -E Often, you'll want to see just one line per interval. The '--depth' option helps with this, causing subaccounts to be aggregated: -$ hledger register --monthly assets --depth 1h +$ hledger register --monthly assets --depth 1 2008/01 assets $1 $1 2008/06 assets $-1 0 2008/12 assets $-1 $-1 @@ -12991,12 +13034,15 @@ We welcome bug reports in the hledger issue tracker Some known issues and limitations: - A system locale with a suitable text encoding must be configured to -work with non-ascii data. (See Text encoding, Troubleshooting.) + hledger uses the system's text encoding when reading non-ascii text. +If no system encoding is configured, or if the data's encoding is +different, hledger will give an error. (See Text encoding, +Troubleshooting.) On Microsoft Windows, depending what kind of terminal window you use, non-ascii characters, ANSI text formatting, and/or the add command's TAB -key for completion, may not be supported. +key, may not be fully supported. (For best results, try a powershell +window.) When processing large data files, hledger uses more memory than Ledger. @@ -13068,378 +13114,380 @@ Node: Regular expressions27166 Node: hledger's regular expressions30425 Node: Argument files32066 Node: Config files32769 -Node: Shell completions36037 -Node: Output36526 -Node: Output destination36717 -Node: Output format37275 -Node: Text output39061 -Node: Box-drawing characters40040 -Node: Colour40540 -Node: Paging41126 -Node: HTML output42645 -Node: CSV / TSV output43063 -Node: FODS output43317 -Node: Beancount output44121 -Node: Beancount account names45622 -Node: Beancount commodity names46163 -Node: Beancount virtual postings46810 -Node: Beancount metadata47126 -Node: Beancount costs47906 -Node: Beancount operating currency48322 -Node: SQL output48772 -Node: JSON output49563 -Node: Commodity styles50380 -Node: Debug output51267 -Node: Environment52099 -Node: PART 2 DATA FORMATS52756 -Node: Journal52899 -Node: Journal cheatsheet55377 -Node: Comments61628 -Node: Transactions62572 -Node: Dates63709 -Node: Simple dates63861 -Node: Posting dates64477 -Node: Status65564 -Node: Code67330 -Node: Description67665 -Node: Payee and note68352 -Node: Transaction comments69443 -Node: Postings69959 -Node: Debits and credits71122 -Node: The two space delimiter71732 -Node: Account names72297 -Node: Amounts74101 -Node: Decimal marks75130 -Node: Digit group marks76234 -Node: Commodity76869 -Node: Costs77986 -Node: Balance assertions80238 -Node: Assertions and ordering81486 -Node: Assertions and multiple files82205 -Node: Assertions and costs83373 -Node: Assertions and commodities84020 -Node: Assertions and subaccounts85679 -Node: Assertions and status86339 -Node: Assertions and virtual postings86759 -Node: Assertions and auto postings87124 -Node: Assertions and precision87999 -Node: Assertions and hledger add88483 -Node: Posting comments89231 -Node: Transaction balancing89771 -Node: Tags91979 -Node: Querying with tags93273 -Node: Displaying tags94072 -Node: When to use tags ?94468 -Node: Tag names95132 -Node: Special tags95685 -Node: Directives97250 -Node: Directives and multiple files98707 -Node: Directive effects99652 -Node: account directive102808 -Node: Account comments104258 -Node: Account error checking104917 -Node: Account display order106454 -Node: Account types107652 -Node: alias directive110927 -Node: Basic aliases112138 -Node: Regex aliases113013 -Node: Combining aliases114060 -Node: Aliases and multiple files115514 -Node: end aliases directive116297 -Node: Aliases can generate bad account names116665 -Node: Aliases and account types117498 -Node: commodity directive118390 -Node: Commodity directive syntax119977 -Node: Commodity error checking121626 -Node: decimal-mark directive122101 -Node: include directive122680 -Node: P directive124898 -Node: payee directive125932 -Node: tag directive126554 -Node: Periodic transactions127166 -Node: Periodic rule syntax129320 -Node: Periodic rules and relative dates130143 -Node: Two spaces between period expression and description!130920 -Node: Auto postings131881 -Node: Auto postings and multiple files135167 -Node: Auto postings and dates135572 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions136013 -Node: Auto posting tags136859 -Node: Auto postings on forecast transactions only137754 -Node: Other syntax138224 -Node: Balance assignments138996 -Node: Balance assignments and costs140524 -Node: Balance assignments and multiple files140946 -Node: Bracketed posting dates141369 -Node: D directive142067 -Node: apply account directive143840 -Node: Y directive144707 -Node: Secondary dates145695 -Node: Star comments147180 -Node: Valuation expressions147872 -Node: Virtual postings148171 -Node: Other Ledger directives149795 -Node: Other cost/lot notations150557 -Node: CSV153398 -Node: CSV rules cheatsheet155564 -Node: source157663 -Node: Data cleaning / generating commands159062 -Node: archive160924 -Node: encoding161852 -Node: separator162895 -Node: skip163548 -Node: date-format164198 -Node: timezone165143 -Node: newest-first166269 -Node: intra-day-reversed166982 -Node: decimal-mark167584 -Node: fields list168064 -Node: Field assignment169872 -Node: Field names171091 -Node: date field172423 -Node: date2 field172587 -Node: status field172782 -Node: code field172972 -Node: description field173160 -Node: comment field173377 -Node: account field173934 -Node: amount field174652 -Node: currency field177491 -Node: balance field177899 -Node: if block178422 -Node: Matchers179949 -Node: Multiple matchers181939 -Node: Match groups182747 -Node: if table183640 -Node: balance-type185703 -Node: include186530 -Node: Working with CSV187099 -Node: Rapid feedback187651 -Node: Valid CSV188234 -Node: File Extension189110 -Node: Reading CSV from standard input189845 -Node: Reading multiple CSV files190231 -Node: Reading files specified by rule190707 -Node: Valid transactions192104 -Node: Deduplicating importing192929 -Node: Setting amounts194158 -Node: Amount signs196685 -Node: Setting currency/commodity197750 -Node: Amount decimal places199126 -Node: Referencing other fields200383 -Node: How CSV rules are evaluated201491 -Node: Well factored rules204208 -Node: CSV rules examples204698 -Node: Bank of Ireland204896 -Node: Coinbase206493 -Node: Amazon207676 -Node: Paypal209518 -Node: Timeclock217268 -Node: Timedot221321 -Node: Timedot examples224798 -Node: PART 3 REPORTING CONCEPTS227075 -Node: Time periods227239 -Node: Report start & end date227512 -Node: Smart dates228988 -Node: Report intervals231111 -Node: Date adjustments231685 -Node: Start date adjustment231905 -Node: End date adjustment232808 -Node: Period headings233589 -Node: Period expressions234522 -Node: Period expressions with a report interval236427 -Node: More complex report intervals236875 -Node: Multiple weekday intervals238991 -Node: Depth240002 -Node: Queries241840 -Node: Query types244512 -Node: acct query244887 -Node: amt query245198 -Node: code query245895 -Node: cur query246090 -Node: desc query246696 -Node: date query246879 -Node: date2 query247275 -Node: depth query247566 -Node: note query247902 -Node: payee query248168 -Node: real query248449 -Node: status query248654 -Node: type query248894 -Node: tag query249427 -Node: Negative queries250056 -Node: not query250238 -Node: Space-separated queries250525 -Node: Boolean queries251213 -Node: expr query252531 -Node: any query253211 -Node: all query253664 -Node: Queries and command options254246 -Node: Queries and account aliases254694 -Node: Queries and valuation255019 -Node: Pivoting255381 -Node: Generating data257657 -Node: Forecasting259457 -Node: --forecast260113 -Node: Inspecting forecast transactions261214 -Node: Forecast reports262547 -Node: Forecast tags263656 -Node: Forecast period in detail264276 -Node: Forecast troubleshooting265364 -Node: Budgeting266435 -Node: Amount formatting266995 -Node: Commodity display style267239 -Node: Rounding269080 -Node: Trailing decimal marks269685 -Node: Amount parseability270618 -Node: Cost reporting272227 -Node: Recording costs273058 -Node: Reporting at cost274785 -Node: Equity conversion postings275550 -Node: Inferring equity conversion postings278195 -Node: Combining costs and equity conversion postings279337 -Node: Requirements for detecting equity conversion postings280562 -Node: Infer cost and equity by default ?282084 -Node: Value reporting282521 -Node: -V Value283457 -Node: -X Value in specified commodity283784 -Node: Valuation date284134 -Node: Finding market price284967 -Node: --infer-market-prices market prices from transactions286347 -Node: Valuation commodity289391 -Node: --value Flexible valuation290824 -Node: Valuation examples292667 -Node: Interaction of valuation and queries294811 -Node: Effect of valuation on reports295528 -Node: PART 4 COMMANDS303426 -Node: Help commands306215 -Node: commands306401 -Node: demo306609 -Node: help307702 -Node: User interface commands309407 -Node: repl309618 -Node: Examples311882 -Node: run312440 -Node: Examples 2314855 -Node: ui315879 -Node: web316016 -Node: Data entry commands316144 -Node: add316405 -Node: add and balance assertions318979 -Node: add and balance assignments319703 -Node: import320264 -Node: Import dry run321343 -Node: Overlap detection322291 -Node: First import325177 -Node: Importing balance assignments326372 -Node: Import and commodity styles327427 -Node: Import archiving327861 -Node: Import special cases328686 -Node: Deduplication328904 -Node: Varying file name329395 -Node: Multiple versions329779 -Node: Basic report commands330886 -Node: accounts331187 -Node: codes333833 -Node: commodities334855 -Node: descriptions335612 -Node: files336072 -Node: notes336369 -Node: payees336881 -Node: prices337793 -Node: stats338685 -Node: tags340426 -Node: Standard report commands341963 -Node: print342268 -Node: print explicitness345082 -Node: print amount style346002 -Node: print parseability347240 -Node: print other features348159 -Node: print output format349120 -Node: aregister352405 -Node: aregister and posting dates356969 -Node: register357870 -Node: Custom register output365111 -Node: balancesheet366296 -Node: balancesheetequity371261 -Node: cashflow376596 -Node: incomestatement381409 -Node: Advanced report commands386258 -Node: balance386466 -Node: balance features391887 -Node: Simple balance report393990 -Node: Balance report line format395800 -Node: Filtered balance report398160 -Node: List or tree mode398679 -Node: Depth limiting400192 -Node: Dropping top-level accounts400959 -Node: Showing declared accounts401469 -Node: Sorting by amount402199 -Node: Percentages403053 -Node: Multi-period balance report403760 -Node: Balance change end balance406512 -Node: Balance report modes408149 -Node: Calculation mode408828 -Node: Accumulation mode409532 -Node: Valuation mode410633 -Node: Combining balance report modes411977 -Node: Budget report414007 -Node: Using the budget report416307 -Node: Budget date surprises418583 -Node: Selecting budget goals419947 -Node: Budgeting vs forecasting420895 -Node: Balance report layout422572 -Node: Wide layout423777 -Node: Tall layout426182 -Node: Bare layout427488 -Node: Tidy layout429552 -Node: Balance report output431096 -Node: Some useful balance reports431870 -Node: roi433130 -Node: Spaces and special characters in --inv and --pnl435377 -Node: Semantics of --inv and --pnl436103 -Node: IRR and TWR explained438190 -Node: Chart commands441601 -Node: activity441782 -Node: Data generation commands442279 -Node: close442485 -Node: close --clopen445048 -Node: close --close447222 -Node: close --open447746 -Node: close --assert447996 -Node: close --assign448323 -Node: close --retain449002 -Node: close customisation449859 -Node: close and balance assertions451503 -Node: close examples453025 -Node: Retain earnings453262 -Node: Migrate balances to a new file453765 -Node: More detailed close examples455127 -Node: rewrite455349 -Node: Re-write rules in a file457909 -Node: Diff output format459210 -Node: rewrite vs print --auto460480 -Node: Maintenance commands461194 -Node: check461413 -Node: Basic checks462495 -Node: Strict checks463516 -Node: Other checks464453 -Node: Custom checks466205 -Node: diff466660 -Node: setup467868 -Node: test470735 -Node: PART 5 COMMON TASKS471638 -Node: Getting help471871 -Node: Constructing command lines472780 -Node: Starting a journal file473625 -Node: Setting LEDGER_FILE475009 -Node: Setting opening balances476267 -Node: Recording transactions479589 -Node: Reconciling480314 -Node: Reporting482703 -Node: Migrating to a new file486817 -Node: BUGS487266 -Node: Troubleshooting487979 +Node: Shell completions36038 +Node: Output36527 +Node: Output destination36718 +Node: Output format37276 +Node: Text output39062 +Node: Box-drawing characters40041 +Node: Colour40541 +Node: Paging41127 +Node: HTML output42646 +Node: CSV / TSV output43064 +Node: FODS output43318 +Node: Beancount output44122 +Node: Beancount account names45623 +Node: Beancount commodity names46164 +Node: Beancount virtual postings46811 +Node: Beancount metadata47127 +Node: Beancount costs47907 +Node: Beancount operating currency48323 +Node: SQL output48773 +Node: JSON output49564 +Node: Commodity styles50381 +Node: Debug output51268 +Node: Environment52100 +Node: PART 2 DATA FORMATS52757 +Node: Journal52900 +Node: Journal cheatsheet55365 +Node: Comments61616 +Node: Transactions62560 +Node: Dates63697 +Node: Simple dates63849 +Node: Posting dates64465 +Node: Status65638 +Node: Code67404 +Node: Description67739 +Node: Payee and note68426 +Node: Transaction comments69517 +Node: Postings70033 +Node: Debits and credits71349 +Node: Account names71908 +Node: The two space delimiter72869 +Node: Account hierarchy74286 +Node: Other account name features75173 +Node: Amounts75591 +Node: Decimal marks76620 +Node: Digit group marks77724 +Node: Commodity78359 +Node: Costs79476 +Node: Balance assertions81728 +Node: Assertions and ordering82976 +Node: Assertions and multiple files83695 +Node: Assertions and costs84863 +Node: Assertions and commodities85510 +Node: Assertions and subaccounts87169 +Node: Assertions and status87829 +Node: Assertions and virtual postings88249 +Node: Assertions and auto postings88614 +Node: Assertions and precision89489 +Node: Assertions and hledger add89973 +Node: Posting comments90721 +Node: Transaction balancing91261 +Node: Tags93469 +Node: Querying with tags94763 +Node: Displaying tags95562 +Node: When to use tags ?95958 +Node: Tag names96622 +Node: Special tags97175 +Node: Directives98740 +Node: Directives and multiple files100197 +Node: Directive effects101142 +Node: account directive104298 +Node: Account comments105748 +Node: Account error checking106407 +Node: Account display order107944 +Node: Account types109142 +Node: alias directive112417 +Node: Basic aliases113628 +Node: Regex aliases114503 +Node: Combining aliases115550 +Node: Aliases and multiple files117004 +Node: end aliases directive117787 +Node: Aliases can generate bad account names118155 +Node: Aliases and account types118988 +Node: commodity directive119880 +Node: Commodity directive syntax121467 +Node: Commodity error checking123116 +Node: decimal-mark directive123591 +Node: include directive124170 +Node: P directive126388 +Node: payee directive127422 +Node: tag directive128044 +Node: Periodic transactions128656 +Node: Periodic rule syntax130810 +Node: Periodic rules and relative dates131633 +Node: Two spaces between period expression and description!132410 +Node: Auto postings133371 +Node: Auto postings and multiple files136657 +Node: Auto postings and dates137062 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions137503 +Node: Auto posting tags138349 +Node: Auto postings on forecast transactions only139244 +Node: Other syntax139714 +Node: Balance assignments140486 +Node: Balance assignments and costs142014 +Node: Balance assignments and multiple files142436 +Node: Bracketed posting dates142859 +Node: D directive143557 +Node: apply account directive145330 +Node: Y directive146197 +Node: Secondary dates147185 +Node: Star comments148670 +Node: Valuation expressions149362 +Node: Virtual postings149661 +Node: Other Ledger directives151285 +Node: Other cost/lot notations152047 +Node: CSV154888 +Node: CSV rules cheatsheet157054 +Node: source159153 +Node: Data cleaning / generating commands160552 +Node: archive162414 +Node: encoding163342 +Node: separator164385 +Node: skip165038 +Node: date-format165688 +Node: timezone166633 +Node: newest-first167759 +Node: intra-day-reversed168472 +Node: decimal-mark169074 +Node: fields list169554 +Node: Field assignment171362 +Node: Field names172581 +Node: date field173913 +Node: date2 field174077 +Node: status field174272 +Node: code field174462 +Node: description field174650 +Node: comment field174867 +Node: account field175424 +Node: amount field176142 +Node: currency field178981 +Node: balance field179389 +Node: if block179912 +Node: Matchers181439 +Node: Multiple matchers183429 +Node: Match groups184237 +Node: if table185130 +Node: balance-type187193 +Node: include188020 +Node: Working with CSV188589 +Node: Rapid feedback189141 +Node: Valid CSV189724 +Node: File Extension190600 +Node: Reading CSV from standard input191335 +Node: Reading multiple CSV files191721 +Node: Reading files specified by rule192197 +Node: Valid transactions193594 +Node: Deduplicating importing194419 +Node: Setting amounts195648 +Node: Amount signs198175 +Node: Setting currency/commodity199240 +Node: Amount decimal places200616 +Node: Referencing other fields201873 +Node: How CSV rules are evaluated202981 +Node: Well factored rules205698 +Node: CSV rules examples206188 +Node: Bank of Ireland206386 +Node: Coinbase207983 +Node: Amazon209166 +Node: Paypal211008 +Node: Timeclock218758 +Node: Timedot222811 +Node: Timedot examples226288 +Node: PART 3 REPORTING CONCEPTS228565 +Node: Time periods228729 +Node: Report start & end date229002 +Node: Smart dates230478 +Node: Report intervals232601 +Node: Date adjustments233175 +Node: Start date adjustment233395 +Node: End date adjustment234298 +Node: Period headings235079 +Node: Period expressions236012 +Node: Period expressions with a report interval237917 +Node: More complex report intervals238365 +Node: Multiple weekday intervals240481 +Node: Depth241492 +Node: Queries243072 +Node: Query types245744 +Node: acct query246119 +Node: amt query246430 +Node: code query247127 +Node: cur query247322 +Node: desc query247928 +Node: date query248111 +Node: date2 query248507 +Node: depth query248798 +Node: note query249134 +Node: payee query249400 +Node: real query249681 +Node: status query249886 +Node: type query250126 +Node: tag query250659 +Node: Negative queries251288 +Node: not query251470 +Node: Space-separated queries251757 +Node: Boolean queries252445 +Node: expr query253763 +Node: any query254443 +Node: all query254896 +Node: Queries and command options255478 +Node: Queries and account aliases255926 +Node: Queries and valuation256251 +Node: Pivoting256613 +Node: Generating data258889 +Node: Forecasting260689 +Node: --forecast261345 +Node: Inspecting forecast transactions262446 +Node: Forecast reports263779 +Node: Forecast tags264888 +Node: Forecast period in detail265508 +Node: Forecast troubleshooting266596 +Node: Budgeting267667 +Node: Amount formatting268227 +Node: Commodity display style268471 +Node: Rounding270312 +Node: Trailing decimal marks270917 +Node: Amount parseability271850 +Node: Cost reporting273459 +Node: Recording costs274290 +Node: Reporting at cost276017 +Node: Equity conversion postings276782 +Node: Inferring equity conversion postings279427 +Node: Combining costs and equity conversion postings280569 +Node: Requirements for detecting equity conversion postings281794 +Node: Infer cost and equity by default ?283316 +Node: Value reporting283753 +Node: -V Value284689 +Node: -X Value in specified commodity285016 +Node: Valuation date285366 +Node: Finding market price286199 +Node: --infer-market-prices market prices from transactions287579 +Node: Valuation commodity290623 +Node: --value Flexible valuation292056 +Node: Valuation examples293899 +Node: Interaction of valuation and queries296043 +Node: Effect of valuation on reports296760 +Node: PART 4 COMMANDS304610 +Node: Help commands307399 +Node: commands307585 +Node: demo307793 +Node: help308886 +Node: User interface commands310591 +Node: repl310802 +Node: Examples313066 +Node: run313624 +Node: Examples 2316039 +Node: ui317063 +Node: web317200 +Node: Data entry commands317328 +Node: add317589 +Node: add and balance assertions320163 +Node: add and balance assignments320887 +Node: import321448 +Node: Import dry run322527 +Node: Overlap detection323475 +Node: First import326361 +Node: Importing balance assignments327556 +Node: Import and commodity styles328611 +Node: Import archiving329045 +Node: Import special cases329870 +Node: Deduplication330088 +Node: Varying file name330579 +Node: Multiple versions330963 +Node: Basic report commands332070 +Node: accounts332371 +Node: codes335017 +Node: commodities336039 +Node: descriptions336796 +Node: files337256 +Node: notes337553 +Node: payees338065 +Node: prices338977 +Node: stats339869 +Node: tags341610 +Node: Standard report commands343147 +Node: print343452 +Node: print explicitness346415 +Node: print amount style347335 +Node: print parseability348573 +Node: print other features349492 +Node: print output format350453 +Node: aregister353738 +Node: aregister and posting dates358302 +Node: register359203 +Node: Custom register output366443 +Node: balancesheet367628 +Node: balancesheetequity372593 +Node: cashflow377928 +Node: incomestatement382741 +Node: Advanced report commands387590 +Node: balance387798 +Node: balance features393219 +Node: Simple balance report395322 +Node: Balance report line format397132 +Node: Filtered balance report399492 +Node: List or tree mode400011 +Node: Depth limiting401524 +Node: Dropping top-level accounts402291 +Node: Showing declared accounts402801 +Node: Sorting by amount403531 +Node: Percentages404385 +Node: Multi-period balance report405092 +Node: Balance change end balance407844 +Node: Balance report modes409481 +Node: Calculation mode410160 +Node: Accumulation mode410864 +Node: Valuation mode411965 +Node: Combining balance report modes413309 +Node: Budget report415339 +Node: Using the budget report417639 +Node: Budget date surprises419915 +Node: Selecting budget goals421279 +Node: Budgeting vs forecasting422227 +Node: Balance report layout423904 +Node: Wide layout425109 +Node: Tall layout427514 +Node: Bare layout428820 +Node: Tidy layout430884 +Node: Balance report output432428 +Node: Some useful balance reports433202 +Node: roi434462 +Node: Spaces and special characters in --inv and --pnl436709 +Node: Semantics of --inv and --pnl437435 +Node: IRR and TWR explained439522 +Node: Chart commands442933 +Node: activity443114 +Node: Data generation commands443611 +Node: close443817 +Node: close --clopen446380 +Node: close --close448554 +Node: close --open449078 +Node: close --assert449328 +Node: close --assign449655 +Node: close --retain450334 +Node: close customisation451191 +Node: close and balance assertions452835 +Node: close examples454357 +Node: Retain earnings454594 +Node: Migrate balances to a new file455097 +Node: More detailed close examples456459 +Node: rewrite456681 +Node: Re-write rules in a file459241 +Node: Diff output format460542 +Node: rewrite vs print --auto461812 +Node: Maintenance commands462526 +Node: check462745 +Node: Basic checks463827 +Node: Strict checks464848 +Node: Other checks465785 +Node: Custom checks467537 +Node: diff467992 +Node: setup469200 +Node: test472067 +Node: PART 5 COMMON TASKS472970 +Node: Getting help473203 +Node: Constructing command lines474112 +Node: Starting a journal file474957 +Node: Setting LEDGER_FILE476341 +Node: Setting opening balances477599 +Node: Recording transactions480921 +Node: Reconciling481646 +Node: Reporting484035 +Node: Migrating to a new file488149 +Node: BUGS488598 +Node: Troubleshooting489428  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 5ec161b5c..80db7e03c 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -646,7 +646,7 @@ Options # Options following a `[COMMAND]` heading are used with that hledger command only. [print] - --explicit --show-costs + --explicit --infer-costs To use a config file, specify it with the --conf option. Its options will be inserted near the start of your command line, so you can over- @@ -1046,14 +1046,14 @@ Journal changes with a version control system such as git. Editor add-ons 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. + formatting, tab completion, and useful commands. See Editors at + hledger.org for the full list. A hledger journal file can contain three kinds of thing: comment lines, - transactions, and/or directives (including periodic transaction rules - and auto posting rules). Understanding the journal file format will - also give you a good understanding of hledger's data model. Here's a - quick cheatsheet/overview, followed by detailed descriptions of each + transactions, and/or directives (including periodic transaction rules + and auto posting rules). Understanding the journal file format will + also give you a good understanding of hledger's data model. Here's a + quick cheatsheet/overview, followed by detailed descriptions of each part. Journal cheatsheet @@ -1188,7 +1188,7 @@ Journal Comments Lines in the journal will be ignored if they begin with a hash (#) or a - semicolon (;). (See also Other syntax.) hledger will also ignore re- + semicolon (;). (See also Other syntax.) hledger will also ignore re- gions beginning with a comment line and ending with an end comment line (or file end). Here's a suggestion for choosing between them: @@ -1210,15 +1210,15 @@ Journal end comment Some hledger entries can have same-line comments attached to them, from - ; (semicolon) to end of line. See Transaction comments, Posting com- + ; (semicolon) to end of line. See Transaction comments, Posting com- ments, and Account comments below. Transactions - Transactions are the main unit of information in a journal file. They - represent events, typically a movement of some quantity of commodities + 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- + Each transaction is recorded as a journal entry, beginning with a sim- ple date in column 0. This can be followed by any of the following op- tional fields, separated by spaces: @@ -1228,11 +1228,11 @@ Journal 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 + 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 + 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: @@ -1243,23 +1243,26 @@ Journal Dates Simple dates - Dates in the journal file use simple dates format: YYYY-MM-DD or + 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 Y directive, or the cur- + omitted, in which case it will be inferred from the context: the cur- + rent transaction, the default year set with a Y directive, or the cur- rent 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 + (The UI also accepts simple dates, as well as the more flexible smart dates documented in the hledger manual.) 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 re- - ports, and the deduction from checking should be reported on 6/1 for - easy bank reconciliation: + 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. (There's also a Ledger-compatible syntax, ; [DATE], + which can be convenient.) + + This is probably the best way to control posting dates precisely. Eg + in this example the expense should appear in May reports, and the de- + duction from checking should be reported on 6/1 for easy bank reconcil- + iation: 2015/5/30 expenses:food $10 ; food purchased on saturday 5/30 @@ -1375,27 +1378,32 @@ Journal 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 (required) an account name (any text, optionally including single + spaces. If anything follows the account name on the same line, the + account name must be ended by two or more spaces.) - o (optional) two or more spaces (or tabs) followed by an amount. + o (optional) an amount + + o (optional) a same-line posting comment, beginning with a semicolon + (;). If the amount is positive, it is being added to the account; if nega- tive, it is being removed from the account. The posting amounts in a transaction must sum up to zero, indicating that the inflows and outflows are equal. We call this a balanced - transaction. (You can read more about the nitty-gritty details of "sum - up to zero" in Transaction balancing below.) + transaction. (You can read more about the details of transaction bal- + ancing below.) - As a convenience, you can optionally leave one amount blank; hledger - will infer what it should be so as to balance the transaction. + If no amount is written, it will be calculated automatically from the + other postings in the transaction, so as to balance the transaction. + In other words, in any transaction you can leave one posting amountless + to save typing. Debits and credits The traditional accounting concepts of debit and credit of course exist - in hledger, but we represent them with numeric sign, as described - above. Positive and negative posting amounts represent debits and - credits respectively. + in hledger, but we represent them with numeric sign. Positive and neg- + ative posting amounts represent debits and credits respectively. You don't need to remember that, but if you would like to - eg for helping newcomers or for talking with your accountant - here's a handy @@ -1404,29 +1412,56 @@ Journal debit / plus / left / short words credit / minus / right / longer words - The two space delimiter - Be sure to notice the unusual separator between the account name and - the following amount. Because hledger allows account names with spaces - in them, you must separate the account name and amount (if any) by two - or more spaces (or tabs). It's easy to forget at first. If you ever - see the amount being treated as part of the account name, you'll know - you probably need to add another space between them. - Account names Accounts are the main way of categorising things in hledger. As in Double Entry Bookkeeping, they can represent real world accounts (such - as a bank account), or more abstract categories such as "money borrowed - from Frank" or "money spent on electricity". + as a bank account), or more abstract categories such as "money spent on + food" or "money borrowed from Frank". - You can use any account names you like, but we usually start with the - traditional accounting categories, which in english are assets, liabil- - ities, equity, revenues, expenses. (You might see these referred to as - A, L, E, R, X for short.) + Account names are flexible. They may be capitalised or not; they may + contain letters, numbers, punctuation, symbols, or single spaces; they + may be in any language. - For more precise reporting, we usually divide the top level accounts - into more detailed subaccounts, by writing a full colon between account - name parts. For example, from the account names assets:bank:checking - and expenses:food, hledger will infer this hierarchy of five accounts: + Typically we use the five traditional accounting categories as the + starting point for account names. In english they are: + + assets, liabilities, equity, revenues, expenses + + These will be discussed more in Account types below. In hledger docs + you may see them referred to as A, L, E, R, X for short. + + The two space delimiter + Note the two or more spaces delimiter that's sometimes required after + account names. hledger's account names, inherited from Ledger, are + very permissive; they may contain pretty much any kind of text, includ- + ing single spaces and semicolons. Because of this, they must be termi- + nated by two or more spaces if there is anything following them on the + same line. For example, if an amount, balance assignment, or same-line + comment follows an account name, they must be preceded by two or more + spaces, else they would be considered part of the account name: + + bad: assets:accounts receivable $10 ; <- too close! + good: assets:accounts receivable $10 + + bad: assets:accounts receivable =$1000 ; <- too close! + good: assets:accounts receivable =$1000 + + bad: assets:accounts receivable ; comment. <- too close! + good: assets:accounts receivable ; comment + + This two-space delimiter appears in a few places in hledger, such as + after account names in postings or account directives; also after the + period expression in periodic transaction rules. When you are starting + out, expect it to catch you out at least once. It's annoying some- + times, but it lets us use expressive account names while still keeping + the syntax light. + + Account hierarchy + For more precise reporting, we usually divide accounts into more de- + tailed subaccounts, subsubaccounts, and so on, by writing a full colon + between account name parts. For example, instead of writing assets and + expenses, we might write assets:bank:checking and expenses:food. From + these names hledger will infer this hierarchy of five accounts: assets assets:bank @@ -1434,7 +1469,7 @@ Journal expenses expenses:food - Shown as an outline, the hierarchical tree structure is more clear: + Or as an outline: assets bank @@ -1443,20 +1478,17 @@ Journal food hledger reports can summarise the account tree to any depth, so you can - go as deep as you like with subcategories, but keeping your account - names relatively simple may be best when starting out. + make your subcategories as detailed as you like. But don't go over- + board, especially when getting started; simpler categories can be less + work. - Account names may be capitalised or not; they may contain letters, num- - bers, symbols, or single spaces. Note, when an account name and an - amount are written on the same line, they must be separated by two or - more spaces (or tabs). + Other account name features + Enclosing the account name in parentheses or brackets, like (ex- + penses:food), enables a non-standard bookkeeping feature: virtual post- + ings. - Parentheses or brackets enclosing the full account name indicate vir- - tual postings, described below. Parentheses or brackets internal to - the account name have no special meaning. - - Account names can be altered temporarily or permanently by account - aliases. + Account names can be rewritten and restructured, temporarily or perma- + nently, by account aliases. Amounts After the account name, there is usually an amount. (Remember: between @@ -5225,38 +5257,30 @@ Depth With the --depth NUM option (short form: -NUM), reports will show ac- counts only to the specified depth, hiding deeper subaccounts. Use this when you want a summary with less detail. This flag has the same - effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva- - lent. + effect as a depth: query argument. So all of these are equivalent: + depth:2, --depth=2, -2. - In place of a single number which limits the depth for all accounts, - you can also provide separate depth limits for different accounts using - regular expressions (since 1.41). + In place of a single number which limits the depth for all accounts, + you can also provide depth limits for specific accounts, by providing a + REGEX=DEPTH argument instead of just a DEPTH (since 1.41). For exam- + ple, --depth assets=2 (or depth:assets=2) will collapse accounts match- + ing the regular expression "assets" to depth 2. So assets:bank:savings + would be collapsed to assets:bank, but liabilities:bank:credit card + would not be affected. - For example, --depth assets=2 (or, equivalently: depth:assets=2) will - collapse accounts matching the regular expression assets to depth 2. - So assets:bank:savings would be collapsed to assets:bank, while liabil- - ities:bank:credit card would not be affected. This can be combined - with a flat depth to collapse other accounts not matching the regular - expression, so --depth assets=2 --depth 1 would collapse as- - sets:bank:savings to assets:bank and liabilities:bank:credit card to - liabilities. + (If REGEX contains spaces or other special characters, enclose it in + quotes in the usual way. Eg: --depth 'credit card=2') - You can supply multiple depth arguments and they will all be applied, - so --depth assets=2 --depth liabilities=3 --depth 1 would collapse: + Specific depth options and a general depth option can be combined. Eg + --depth assets=3 --depth expenses=2 --depth 1 would collapse accounts + containing "assets" to depth 3, accounts containing "expenses" to depth + 2, and all other accounts to depth 1. - o accounts matching assets to depth 2, - - o accounts matching liabilities to depth 3, - - o all other accounts to depth 1. - - If an account is matched by more than one regular expression depth ar- - gument then the more specific one will be used. For example, if - --depth assets=1 --depth assets:bank:savings=2 is provided, then as- - sets:bank:savings will be collapsed to depth 2 rather than depth 1. - This is because assets:bank:savings matches at level 3 in the account - name, while assets matches at level 1. The same would be true with the - argument --depth assets=1 --depth savings=2. + If an account is matched by more than one regular expression depth ar- + gument, the most specific (deepest) match will be used. For example, + with --depth assets=1 --depth savings=2, assets:bank:savings will be + collapsed to depth 2, not depth 1 (because "savings" matches a deeper + part of it than "assets" does). Queries Many hledger commands accept query arguments, which restrict their @@ -6489,10 +6513,9 @@ Value reporting Effect of valuation on reports Here is a reference for how valuation is supposed to affect each part - of hledger's reports. (It's wide, you may need to scroll sideways.) - It may be useful when troubleshooting. If you find problems, please - report them, ideally with a reproducible example. Related: #329, - #1083. + of hledger's reports. It may be useful when troubleshooting. If you + find problems, please report them, ideally with a reproducible example. + Related: #329, #1083. First, a quick glossary: @@ -7590,8 +7613,16 @@ Standard report commands Flags: -x --explicit show all amounts explicitly - --show-costs show transaction prices even with conversion - postings + --invert display all amounts with reversed sign + --location add tags showing file paths and line numbers + -m --match=DESC fuzzy search for one recent transaction with + description closest to DESC + --new show only newer-dated transactions added in each + file since last run + --no-lots remove lot subaccounts and their balance + assertions + --no-lots2 remove lot subaccounts and their costs and + balance assertions (can produce unbalanced entries) --round=TYPE how much rounding or padding should be done when displaying amounts ? none - show original decimal digits, @@ -7602,15 +7633,9 @@ Standard report commands (can unbalance transactions) all - also round cost amounts to precision (can unbalance transactions) - --invert display all amounts with reversed sign - --new show only newer-dated transactions added in each - file since last run - -m --match=DESC fuzzy search for one recent transaction with - description closest to DESC --base-url=URLPREFIX in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by hledger-web; can also be relative.) - --location add tags showing file paths and line numbers -O --output-format=FMT select the output format. Supported formats: txt, beancount, csv, tsv, html, fods, json, sql. -o --output-file=FILE write output to FILE. A file extension matching @@ -8018,7 +8043,7 @@ Standard report commands Often, you'll want to see just one line per interval. The --depth op- tion helps with this, causing subaccounts to be aggregated: - $ hledger register --monthly assets --depth 1h + $ hledger register --monthly assets --depth 1 2008/01 assets $1 $1 2008/06 assets $-1 0 2008/12 assets $-1 $-1 @@ -10626,45 +10651,48 @@ BUGS Some known issues and limitations: - A system locale with a suitable text encoding must be configured to - work with non-ascii data. (See Text encoding, Troubleshooting.) + hledger uses the system's text encoding when reading non-ascii text. + If no system encoding is configured, or if the data's encoding is dif- + ferent, hledger will give an error. (See Text encoding, Troubleshoot- + ing.) On Microsoft Windows, depending what kind of terminal window you use, non-ascii characters, ANSI text formatting, and/or the add command's - TAB key for completion, may not be supported. + TAB key, may not be fully supported. (For best results, try a power- + shell window.) When processing large data files, hledger uses more memory than Ledger. Troubleshooting - Here are some common issues you might encounter when you run hledger, - and how to resolve them (and remember also you can usually get quick + Here are some common issues you might encounter when you run hledger, + and how to resolve them (and remember also you can usually get quick Support): PATH issues: I get an error like "No command 'hledger' found" Depending how you installed hledger, the executables may not be in your - shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- + shell's PATH. Eg on unix systems, stack installs hledger in ~/.lo- cal/bin and cabal installs it in ~/.cabal/bin. You may need to add one - of these directories to your shell's PATH, and/or open a new terminal + of these directories to your shell's PATH, and/or open a new terminal window. - LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using + LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not using it - o LEDGER_FILE should be a real environment variable, not just a shell + o LEDGER_FILE should be a real environment variable, not just a shell variable. Eg on unix, the command env | grep LEDGER_FILE should show - it. You may need to use export (see https://stackover- + it. You may need to use export (see https://stackover- flow.com/a/7411509). On Windows, $env:LEDGER_FILE should show it. - o You may need to force your shell to see the new configuration. A + o You may need to force your shell to see the new configuration. A simple way is to close your terminal window and open a new one. Text decoding issues: I get errors like "Illegal byte sequence" or "In- - valid or incomplete multibyte or wide character" or "commitAndRelease- + valid or incomplete multibyte or wide character" or "commitAndRelease- Buffer: invalid argument (invalid character)" - hledger usually needs its input to be decodable with the system lo- + hledger usually needs its input to be decodable with the system lo- cale's text encoding. See Text encoding and Install: Text encoding. COMPATIBILITY ISSUES: hledger gives an error with my Ledger file - Not all of Ledger's journal file syntax or feature set is supported. + Not all of Ledger's journal file syntax or feature set is supported. See hledger and Ledger for full details.