From 2df8a6c4debdaac6dd60afff554f1611757995a2 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 26 Jan 2019 15:56:43 -0800 Subject: [PATCH] doc: regen manuals --- hledger-lib/hledger_journal.5 | 36 ++- hledger-lib/hledger_journal.info | 158 +++++++----- hledger-lib/hledger_journal.txt | 347 ++++++++++++++------------- hledger-ui/hledger-ui.1 | 2 +- hledger-ui/hledger-ui.info | 10 +- hledger-ui/hledger-ui.txt | 3 +- hledger/hledger.1 | 18 +- hledger/hledger.info | 190 ++++++++------- hledger/hledger.txt | 398 +++++++++++++++---------------- 9 files changed, 618 insertions(+), 544 deletions(-) diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 07f573fc9..2b9c4a013 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -602,8 +602,21 @@ One workaround is to isolate each commodity into its own subaccount: .fi .SS Assertions and prices .PP -Balance assertion (or assignment) amounts should not have a price, as -the meaning of that would be unclear. +Balance assertions ignore transaction prices, and should normally be +written without one: +.IP +.nf +\f[C] +2019/1/1 +\ \ (a)\ \ \ \ \ $1\ \@\ €1\ =\ $1 +\f[] +.fi +.PP +We do allow prices to be written there, however, and print shows them, +even though they don\[aq]t affect whether the assertion passes or fails. +This is for backward compatibility (hledger\[aq]s close command used to +generate balance assertions with prices), and because balance +\f[I]assignments\f[] do use them (see below). .SS Assertions and subaccounts .PP Balance assertions do not count the balance from subaccounts; they check @@ -682,6 +695,25 @@ assignment). Note that using balance assignments makes your journal a little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. +.SS Balance assignments and prices +.PP +A transaction price in a balance assignment will cause the calculated +amount to have that price attached: +.IP +.nf +\f[C] +2019/1/1 +\ \ (a)\ \ \ \ \ \ \ \ \ \ \ \ \ =\ $1\ \@\ €2 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ print\ \-\-explicit +2019/01/01 +\ \ \ \ (a)\ \ \ \ \ \ \ \ \ $1\ \@\ €2\ =\ $1\ \@\ €2 +\f[] +.fi .SS Transaction prices .PP Within a transaction, you can note an amount\[aq]s price in another diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 69470b6f4..0c95914d1 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -573,8 +573,17 @@ File: hledger_journal.info, Node: Assertions and prices, Next: Assertions and 1.9.5 Assertions and prices --------------------------- -Balance assertion (or assignment) amounts should not have a price, as -the meaning of that would be unclear. +Balance assertions ignore transaction prices, and should normally be +written without one: + +2019/1/1 + (a) $1 @ €1 = $1 + + We do allow prices to be written there, however, and print shows +them, even though they don't affect whether the assertion passes or +fails. This is for backward compatibility (hledger's close command used +to generate balance assertions with prices), and because balance +_assignments_ do use them (see below).  File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance Assertions @@ -652,6 +661,25 @@ of the commodity to that account since the last balance assertion or assignment). Note that using balance assignments makes your journal a little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. +* Menu: + +* Balance assignments and prices:: + + +File: hledger_journal.info, Node: Balance assignments and prices, Up: Balance Assignments + +1.10.1 Balance assignments and prices +------------------------------------- + +A transaction price in a balance assignment will cause the calculated +amount to have that price attached: + +2019/1/1 + (a) = $1 @ €2 + +$ hledger print --explicit +2019/01/01 + (a) $1 @ €2 = $1 @ €2  File: hledger_journal.info, Node: Transaction prices, Next: Comments, Prev: Balance Assignments, Up: FILE FORMAT @@ -1597,67 +1625,69 @@ Node: Assertions and commodities19383 Ref: #assertions-and-commodities19613 Node: Assertions and prices20801 Ref: #assertions-and-prices21013 -Node: Assertions and subaccounts21122 -Ref: #assertions-and-subaccounts21349 -Node: Assertions and virtual postings21870 -Ref: #assertions-and-virtual-postings22110 -Node: Assertions and precision22252 -Ref: #assertions-and-precision22443 -Node: Balance Assignments22710 -Ref: #balance-assignments22891 -Node: Transaction prices24011 -Ref: #transaction-prices24180 -Node: Comments26448 -Ref: #comments26582 -Node: Tags27752 -Ref: #tags27870 -Node: Directives29272 -Ref: #directives29415 -Node: Comment blocks35022 -Ref: #comment-blocks35167 -Node: Including other files35343 -Ref: #including-other-files35523 -Node: Default year35931 -Ref: #default-year36100 -Node: Declaring commodities36523 -Ref: #declaring-commodities36706 -Node: Default commodity37933 -Ref: #default-commodity38109 -Node: Market prices38745 -Ref: #market-prices38910 -Node: Declaring accounts39751 -Ref: #declaring-accounts39927 -Node: Account comments40852 -Ref: #account-comments41015 -Node: Account subdirectives41410 -Ref: #account-subdirectives41605 -Node: Account types41918 -Ref: #account-types42102 -Node: Account display order43746 -Ref: #account-display-order43916 -Node: Rewriting accounts45045 -Ref: #rewriting-accounts45230 -Node: Basic aliases45964 -Ref: #basic-aliases46110 -Node: Regex aliases46814 -Ref: #regex-aliases46985 -Node: Multiple aliases47703 -Ref: #multiple-aliases47878 -Node: end aliases48376 -Ref: #end-aliases48523 -Node: Default parent account48624 -Ref: #default-parent-account48790 -Node: Periodic transactions49674 -Ref: #periodic-transactions49856 -Node: Two spaces after the period expression50981 -Ref: #two-spaces-after-the-period-expression51226 -Node: Forecasting with periodic transactions51711 -Ref: #forecasting-with-periodic-transactions52001 -Node: Budgeting with periodic transactions53688 -Ref: #budgeting-with-periodic-transactions53927 -Node: Transaction Modifiers54386 -Ref: #transaction-modifiers54549 -Node: EDITOR SUPPORT56530 -Ref: #editor-support56648 +Node: Assertions and subaccounts21453 +Ref: #assertions-and-subaccounts21680 +Node: Assertions and virtual postings22201 +Ref: #assertions-and-virtual-postings22441 +Node: Assertions and precision22583 +Ref: #assertions-and-precision22774 +Node: Balance Assignments23041 +Ref: #balance-assignments23222 +Node: Balance assignments and prices24386 +Ref: #balance-assignments-and-prices24558 +Node: Transaction prices24782 +Ref: #transaction-prices24951 +Node: Comments27219 +Ref: #comments27353 +Node: Tags28523 +Ref: #tags28641 +Node: Directives30043 +Ref: #directives30186 +Node: Comment blocks35793 +Ref: #comment-blocks35938 +Node: Including other files36114 +Ref: #including-other-files36294 +Node: Default year36702 +Ref: #default-year36871 +Node: Declaring commodities37294 +Ref: #declaring-commodities37477 +Node: Default commodity38704 +Ref: #default-commodity38880 +Node: Market prices39516 +Ref: #market-prices39681 +Node: Declaring accounts40522 +Ref: #declaring-accounts40698 +Node: Account comments41623 +Ref: #account-comments41786 +Node: Account subdirectives42181 +Ref: #account-subdirectives42376 +Node: Account types42689 +Ref: #account-types42873 +Node: Account display order44517 +Ref: #account-display-order44687 +Node: Rewriting accounts45816 +Ref: #rewriting-accounts46001 +Node: Basic aliases46735 +Ref: #basic-aliases46881 +Node: Regex aliases47585 +Ref: #regex-aliases47756 +Node: Multiple aliases48474 +Ref: #multiple-aliases48649 +Node: end aliases49147 +Ref: #end-aliases49294 +Node: Default parent account49395 +Ref: #default-parent-account49561 +Node: Periodic transactions50445 +Ref: #periodic-transactions50627 +Node: Two spaces after the period expression51752 +Ref: #two-spaces-after-the-period-expression51997 +Node: Forecasting with periodic transactions52482 +Ref: #forecasting-with-periodic-transactions52772 +Node: Budgeting with periodic transactions54459 +Ref: #budgeting-with-periodic-transactions54698 +Node: Transaction Modifiers55157 +Ref: #transaction-modifiers55320 +Node: EDITOR SUPPORT57301 +Ref: #editor-support57419  End Tag Table diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 1b1cf1d51..0f013a851 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -447,8 +447,17 @@ FILE FORMAT a:euro 0 == 1 Assertions and prices - Balance assertion (or assignment) amounts should not have a price, as - the meaning of that would be unclear. + Balance assertions ignore transaction prices, and should normally be + written without one: + + 2019/1/1 + (a) $1 @ 1 = $1 + + We do allow prices to be written there, however, and print shows them, + even though they don't affect whether the assertion passes or fails. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance assign- + ments do use them (see below). Assertions and subaccounts Balance assertions do not count the balance from subaccounts; they @@ -506,11 +515,22 @@ FILE FORMAT 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 @ 2 + + $ hledger print --explicit + 2019/01/01 + (a) $1 @ 2 = $1 @ 2 + 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 + 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. @@ -539,7 +559,7 @@ FILE FORMAT (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- PRICE}, which hledger currently ignores). - Use the -B/--cost flag to convert amounts to their transaction price's + 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: @@ -550,8 +570,8 @@ FILE FORMAT $-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 + 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: @@ -565,14 +585,14 @@ FILE FORMAT 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 + (*) 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. + 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: @@ -596,24 +616,24 @@ FILE FORMAT ; another comment line for posting 2 ; a file comment (because not indented) - You can also comment larger regions of a file using comment and + 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 + 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 + 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 + 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- + 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: @@ -627,68 +647,69 @@ FILE FORMAT 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, + 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 + Tags are like Ledger's metadata feature, except hledger's tag values are simple strings. Directives - A directive is a line in the journal beginning with a special keyword, + A directive is a line in the journal beginning with a special keyword, that influences how the journal is processed. hledger's directives are based on a subset of Ledger's, but there are many differences (and also some differences between hledger versions). Directives' behaviour and interactions can get a little bit complex, so - here is a table summarising the directives and their effects, with + here is a table summarising the directives and their effects, with links to more detailed docs. - direc- end subdi- purpose can affect (as of + + + + 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 + account any document account names, all entries in all + text declare account types & dis- files, before or play order after alias end aliases rewrite account names following inline/included entries until end - of current file or + of current file or end directive - apply account end apply account prepend a common parent to following + apply account end apply account prepend a common parent to following account names inline/included entries until end - of current file or + of current file or end directive comment end comment ignore part of journal following inline/included entries until end - of current file or + of current file or end directive - commodity format declare a commodity and its number notation: + commodity format declare a commodity and its number notation: number notation & display following entries style in that commodity - in all files; dis- + in all files; dis- play style: amounts of that commodity in reports - - - D declare a commodity, number commodity: all com- + D declare a commodity, number commodity: all com- notation & display style for modityless entries - commodityless amounts in all files; num- - ber notation: fol- + commodityless amounts in all files; num- + ber notation: fol- lowing commodity- - less entries and + less entries and entries in that - commodity in all + commodity in all files; display style: amounts of that commodity in @@ -699,7 +720,7 @@ FILE FORMAT commodity commodity in reports, when -V is used - Y declare a year for yearless following + Y declare a year for yearless following dates inline/included entries until end of current file @@ -709,9 +730,9 @@ FILE FORMAT subdirec- optional indented directive line immediately following a par- tive ent directive - number how to interpret numbers when parsing journal entries (the - notation identity of the decimal separator character). (Currently - each commodity can have its own notation, even in the same + number how to interpret numbers when parsing journal entries (the + notation identity of the decimal separator character). (Currently + each commodity can have its own notation, even in the same file.) display how to display amounts of a commodity in reports (symbol side style and spacing, digit groups, decimal separator, decimal places) @@ -719,37 +740,37 @@ FILE FORMAT scope are affected by a directive As you can see, directives vary in which journal entries and files they - affect, and whether they are focussed on input (parsing) or output + affect, and whether they are focussed on input (parsing) or output (reports). Some directives have multiple effects. - If you have a journal made up of multiple files, or pass multiple -f - options on the command line, note that directives which affect input - typically last only until the end of their defining file. This pro- + If you have a journal made up of multiple files, or pass multiple -f + options on the command line, note that directives which affect input + typically last only until the end of their defining file. This pro- vides more simplicity and predictability, eg reports are not changed by - writing file options in a different order. It can be surprising at + writing file options in a different order. It can be surprising at times though. Comment blocks - A line containing just comment starts a commented region of the file, + A line containing just comment starts a commented region of the file, and a line containing just end comment (or the end of the current file) ends it. See also comments. Including other files - You can pull in the content of additional files by writing an include + You can pull in the content of additional files by writing an include directive, like this: include path/to/file.journal - If the path does not begin with a slash, it is relative to the current - file. The include file path may contain common glob patterns (e.g. + If the path does not begin with a slash, it is relative to the current + file. The include file path may contain common glob patterns (e.g. *). - The include directive can only be used in journal files. It can + The include directive can only be used in journal files. It can include journal, timeclock or timedot files, but not CSV files. Default year - You can set a default year to be used for subsequent dates which don't - specify a year. This is a line beginning with Y followed by the year. + You can set a default year to be used for subsequent dates which don't + specify a year. This is a line beginning with Y followed by the year. Eg: Y2009 ; set default year to 2009 @@ -769,8 +790,8 @@ FILE FORMAT assets Declaring commodities - The commodity directive declares commodities which may be used in the - journal (though currently we do not enforce this). It may be written + The commodity directive declares commodities which may be used in the + journal (though currently we do not enforce this). It may be written on a single line, like this: ; commodity EXAMPLEAMOUNT @@ -780,8 +801,8 @@ FILE FORMAT ; separating thousands with comma. commodity 1,000.0000 AAAA - or on multiple lines, using the "format" subdirective. In this case - the commodity symbol appears twice and should be the same in both + or on multiple lines, using the "format" subdirective. In this case + the commodity symbol appears twice and should be the same in both places: ; commodity SYMBOL @@ -793,19 +814,19 @@ FILE FORMAT commodity INR format INR 9,99,99,999.00 - Commodity directives have a second purpose: they define the standard + Commodity directives have a second purpose: they define the standard display format for amounts in the commodity. Normally the display for- - mat is inferred from journal entries, but this can be unpredictable; - declaring it with a commodity directive overrides this and removes - ambiguity. Towards this end, amounts in commodity directives must - always be written with a decimal point (a period or comma, followed by + mat is inferred from journal entries, but this can be unpredictable; + declaring it with a commodity directive overrides this and removes + ambiguity. Towards this end, amounts in commodity directives must + always be written with a decimal point (a period or comma, followed by 0 or more decimal digits). Default commodity - The D directive sets a default commodity (and display format), to be + The D directive sets a default commodity (and display format), to be used for amounts without a commodity symbol (ie, plain numbers). (Note - this differs from Ledger's default commodity directive.) The commodity - and display format will be applied to all subsequent commodity-less + this differs from Ledger's default commodity directive.) The commodity + and display format will be applied to all subsequent commodity-less amounts, or until the next D directive. # commodity-less amounts should be treated as dollars @@ -820,9 +841,9 @@ FILE FORMAT a decimal point. Market prices - The P directive declares a market price, which is an exchange rate + 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, + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. Here is the format: @@ -833,39 +854,39 @@ FILE FORMAT o COMMODITYA is the symbol of the commodity being priced - o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- + o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com- modity, giving the price in commodity B of one unit of commodity A. - These two market price directives say that one euro was worth 1.35 US + These two market price directives say that one euro was worth 1.35 US dollars during 2009, and $1.40 from 2010 onward: P 2009/1/1 $1.35 P 2010/1/1 $1.40 - The -V/--value flag can be used to convert reported amounts to another + The -V/--value flag can be used to convert reported amounts to another commodity using these prices. Declaring accounts - account directives can be used to pre-declare accounts. Though not + account directives can be used to pre-declare accounts. Though not required, they can provide several benefits: o They can document your intended chart of accounts, providing a refer- ence. - o They can store extra information about accounts (account numbers, + o They can store extra information about accounts (account numbers, notes, etc.) - o They can help hledger know your accounts' types (asset, liability, - equity, revenue, expense), useful for reports like balancesheet and + o They can help hledger know your accounts' types (asset, liability, + equity, revenue, expense), useful for reports like balancesheet and incomestatement. - o They control account display order in reports, allowing non-alpha- + o They control account display order in reports, allowing non-alpha- betic sorting (eg Revenues to appear above Expenses). - o They help with account name completion in the add command, + o They help with account name completion in the add command, hledger-iadd, hledger-web, ledger-mode etc. - The simplest form is just the word account followed by a hledger-style + The simplest form is just the word account followed by a hledger-style account name, eg: account assets:bank:checking @@ -883,7 +904,7 @@ FILE FORMAT the next line instead. Account subdirectives - We also allow (and ignore) Ledger-style indented subdirectives, just + We also allow (and ignore) Ledger-style indented subdirectives, just for compatibility.: account assets:bank:checking @@ -896,18 +917,18 @@ FILE FORMAT [LEDGER-STYLE SUBDIRECTIVES, IGNORED] Account types - hledger recognises five types (or classes) of account: Asset, Liabil- - ity, Equity, Revenue, Expense. This is used by a few accounting-aware + hledger recognises five types (or classes) of account: Asset, Liabil- + ity, Equity, Revenue, Expense. This is used by a few accounting-aware reports such as balancesheet, incomestatement and cashflow. Auto-detected account types If you name your top-level accounts with some variation of assets, lia- - bilities/debts, equity, revenues/income, or expenses, their types are + bilities/debts, equity, revenues/income, or expenses, their types are detected automatically. Account types declared with tags - More generally, you can declare an account's type with an account - directive, by writing a type: tag in a comment, followed by one of the + More generally, you can declare an account's type with an account + directive, by writing a type: tag in a comment, followed by one of the words Asset, Liability, Equity, Revenue, Expense, or one of the letters ALERX (case insensitive): @@ -918,8 +939,8 @@ FILE FORMAT account expenses ; type:Expenses Account types declared with account type codes - Or, you can write one of those letters separated from the account name - by two or more spaces, but this should probably be considered depre- + Or, you can write one of those letters separated from the account name + by two or more spaces, but this should probably be considered depre- cated as of hledger 1.13: account assets A @@ -929,7 +950,7 @@ FILE FORMAT account expenses X Overriding auto-detected types - If you ever override the types of those auto-detected english account + If you ever override the types of those auto-detected english account names mentioned above, you might need to help the reports a bit. Eg: ; make "liabilities" not have the liability type - who knows why @@ -940,8 +961,8 @@ FILE FORMAT account - ; type:L Account display order - Account directives also set the order in which accounts are displayed, - eg in reports, the hledger-ui accounts screen, and the hledger-web + Account directives also set the order in which accounts are displayed, + eg in reports, the hledger-ui accounts screen, and the hledger-web sidebar. By default accounts are listed in alphabetical order. But if you have these account directives in the journal: @@ -963,16 +984,16 @@ FILE FORMAT Undeclared accounts, if any, are displayed last, in alphabetical order. - Note that sorting is done at each level of the account tree (within - each group of sibling accounts under the same parent). And currently, + Note that sorting is done at each level of the account tree (within + each group of sibling accounts under the same parent). And currently, this directive: account other:zoo - would influence the position of zoo among other's subaccounts, but not - the position of other among the top-level accounts. This means: - you - will sometimes declare parent accounts (eg account other above) that - you don't intend to post to, just to customize their display order - + would influence the position of zoo among other's subaccounts, but not + the position of other among the top-level accounts. This means: - you + will sometimes declare parent accounts (eg account other above) that + you don't intend to post to, just to customize their display order - sibling accounts stay together (you couldn't display x:y in between a:b and a:c). @@ -991,14 +1012,14 @@ FILE FORMAT o customising reports Account aliases also rewrite account names in account directives. They - do not affect account names being entered via hledger add or + do not affect account names being entered via hledger add or hledger-web. See also Cookbook: 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 + 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 @@ -1006,54 +1027,54 @@ FILE FORMAT 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- + 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, + 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- + 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- + 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. Multiple aliases - You can define as many aliases as you like using directives or com- - mand-line options. Aliases are recursive - each alias sees the result - of applying previous ones. (This is different from Ledger, where + You can define as many aliases as you like using directives or com- + mand-line options. Aliases are recursive - each alias sees the result + of applying previous ones. (This is different from Ledger, where aliases are non-recursive by default). Aliases are applied in the fol- lowing order: - 1. alias directives, most recently seen first (recent directives take + 1. alias directives, most recently seen first (recent directives take precedence over earlier ones; directives not yet seen are ignored) 2. alias options, in the order they appear on the command line end aliases - You can clear (forget) all currently defined aliases with the + 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 + 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 @@ -1070,7 +1091,7 @@ FILE FORMAT home:food $10 home:cash $-10 - If end apply account is omitted, the effect lasts to the end of the + If end apply account is omitted, the effect lasts to the end of the file. Included files are also affected, eg: apply account business @@ -1079,18 +1100,18 @@ FILE FORMAT apply account personal include personal.journal - Prior to hledger 1.0, legacy account and end spellings were also sup- + 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 + 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 + Periodic transaction rules describe transactions that recur. They allow you to generate future transactions for forecasting, without hav- - ing to write them out explicitly in the journal (with --forecast). + ing to write them out explicitly in the journal (with --forecast). Secondly, they also can be used to define budget goals (with --budget). A periodic transaction rule looks like a normal journal entry, with the @@ -1101,17 +1122,17 @@ FILE FORMAT 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 + 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 + 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 after the period expression - If the period expression is followed by a transaction 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: @@ -1124,65 +1145,65 @@ FILE FORMAT income:acme inc Forecasting with periodic transactions - With the --forecast flag, each periodic transaction rule generates + With the --forecast flag, each periodic transaction rule generates future transactions recurring at the specified interval. These are not - saved in the journal, but appear in all reports. They will look like - normal transactions, but with an extra tag named recur, whose value is + saved in the journal, but appear in all reports. They will look like + normal transactions, but with an extra tag named recur, whose value is the generating period expression. - Forecast transactions start on the first occurrence, and end on the - last occurrence, of their interval within the forecast period. The + Forecast transactions start on the first occurrence, and end on the + last occurrence, of their interval within the forecast period. The forecast period: 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 + 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 180 + o ends on the report end date if specified with -e/-p/date:, or 180 days from today. - where "today" means the current date at report time. The "later of" - rule ensures that forecast transactions do not overlap normal transac- + where "today" means the current date at report time. The "later of" + rule ensures that forecast transactions do not overlap normal transac- tions in time; they will begin only after normal transactions end. - Forecasting can be useful for estimating balances into the future, and - experimenting with different scenarios. Note the start date logic + Forecasting can be useful for estimating balances into the future, and + experimenting with different scenarios. Note the start date logic means that forecasted transactions are automatically replaced by normal transactions as you add those. Forecasting can also help with data entry: describe most of your trans- - actions with periodic rules, and every so often copy the output of + actions with periodic rules, and every so often copy the output of print --forecast to the journal. You can generate one-time transactions too: just write a period expres- - sion specifying a date with no report interval. (You could also write - a normal transaction with a future date, but remember this disables + sion specifying a date with no report interval. (You could also write + a normal transaction with a future date, but remember this disables forecast transactions on previous dates.) 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- + 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. - For more details, see: balance: Budget report and Cookbook: Budgeting + For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. Transaction Modifiers - Transaction modifier rules describe changes that should be applied - automatically to certain transactions. Currently, this means adding + Transaction modifier rules describe changes that should be applied + automatically to certain transactions. Currently, this means adding extra postings (also known as "automated postings"). Transaction modi- fiers are enabled by the --auto flag. - A transaction modifier rule looks quite like a normal transaction, - except the first line is an equals sign followed by a query that - matches certain postings (mnemonic: = suggests matching). And each + A transaction modifier rule looks quite like a normal transaction, + except the first line is an equals sign followed by a query that + matches certain postings (mnemonic: = suggests matching). And each "posting" is actually a posting-generating rule: = QUERY @@ -1193,17 +1214,17 @@ FILE FORMAT The posting rules look just like normal postings, except the amount can be: - o a normal amount with a commodity symbol, eg $2. This will be used + 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 + 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 + 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. @@ -1239,16 +1260,16 @@ FILE FORMAT assets:checking $20 Postings added by transaction modifiers participate in transaction bal- - ancing, missing amount inference and balance assertions, like regular + ancing, missing amount inference and balance assertions, like regular postings. EDITOR SUPPORT Add-on modes exist for various text editors, to make working with jour- - nal files easier. They add colour, navigation aids and helpful com- - mands. For hledger users who edit the journal file directly (the + nal files easier. They add colour, navigation aids and helpful com- + mands. For hledger users who edit the journal file directly (the majority), using one of these modes is quite recommended. - These were written with Ledger in mind, but also work with hledger + These were written with Ledger in mind, but also work with hledger files: @@ -1267,7 +1288,7 @@ EDITOR SUPPORT REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -1281,7 +1302,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 838bdb48f..2d6ed4df2 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -424,7 +424,7 @@ Similarly, \f[C]P\f[] toggles pending transactions, and \f[C]C\f[] toggles cleared transactions. (By default, transactions with all statuses are shown; if you activate one or two status filters, only those transactions are shown; and if you -activate all three, the filter is removed.)q +activate all three, the filter is removed.) .PP \f[C]R\f[] toggles real mode, in which virtual postings are ignored. .PP diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index e1edd0d4a..1b05ccc6e 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -349,7 +349,7 @@ transactions. Similarly, 'P' toggles pending transactions, and 'C' toggles cleared transactions. (By default, transactions with all statuses are shown; if you activate one or two status filters, only those transactions are shown; and if you activate all three, the filter -is removed.)q +is removed.) 'R' toggles real mode, in which virtual postings are ignored. @@ -408,9 +408,9 @@ Node: Accounts screen8148 Ref: #accounts-screen8276 Node: Register screen10492 Ref: #register-screen10647 -Node: Transaction screen12644 -Ref: #transaction-screen12802 -Node: Error screen13672 -Ref: #error-screen13794 +Node: Transaction screen12643 +Ref: #transaction-screen12801 +Node: Error screen13671 +Ref: #error-screen13793  End Tag Table diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 2853ccaf1..d4f67fe35 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -314,8 +314,7 @@ SCREENS transactions. Similarly, P toggles pending transactions, and C toggles cleared transactions. (By default, transactions with all statuses are shown; if you activate one or two status filters, only those transac- - tions are shown; and if you activate all three, the filter is - removed.)q + tions are shown; and if you activate all three, the filter is removed.) R toggles real mode, in which virtual postings are ignored. diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 350d4e842..14870ffe9 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1639,11 +1639,6 @@ show performance compared to budget goals defined by periodic transactions .RS .RE -.TP -.B \f[C]\-\-show\-unbudgeted\f[] -with \-\-budget, show unbudgeted accounts also -.RS -.RE .PP The balance command is hledger\[aq]s most versatile command. Note, despite the name, it is not always used for showing real\-world @@ -1934,6 +1929,8 @@ Second, all accounts which existed at the report start date will be considered, not just the ones with activity during the report period (use \-E to include low\-activity accounts which would otherwise would be omitted). +With \f[C]\-\-budget\f[], \f[C]\-\-empty\f[] also shows unbudgeted +accounts. .PP The \f[C]\-T/\-\-row\-total\f[] flag adds an additional column showing the total for each row. @@ -2040,12 +2037,11 @@ In the example above, transactions in \f[C]expenses:gifts\f[] and but accounts \f[C]expenses:gifts\f[] and \f[C]expenses:supplies\f[] are not shown, as they don\[aq]t have any budgets. .PP -You can use \f[C]\-\-show\-unbudgeted\f[] shows unbudgeted accounts as -well: +You can use \f[C]\-\-empty\f[] shows unbudgeted accounts as well: .IP .nf \f[C] -$\ hledger\ balance\ \-M\ \-\-budget\ \-\-show\-unbudgeted +$\ hledger\ balance\ \-M\ \-\-budget\ \-\-empty Budget\ performance\ in\ 2017/11/01\-2017/12/31: \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Nov\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Dec\ @@ -2174,12 +2170,12 @@ Budget\ performance\ in\ 2019/01: \f[] .fi .PP -And with \f[C]\-\-show\-unbudgeted\f[], we can get a better picture of -budget allocation and consumption: +And with \f[C]\-\-empty\f[], we can get a better picture of budget +allocation and consumption: .IP .nf \f[C] -$\ hledger\ balance\ \-\-budget\ \-M\ \-\-show\-unbudgeted +$\ hledger\ balance\ \-\-budget\ \-M\ \-\-empty Budget\ performance\ in\ 2019/01: \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Jan\ diff --git a/hledger/hledger.info b/hledger/hledger.info index 977ff6157..3b43f8b8e 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1243,9 +1243,6 @@ Show accounts and their balances. Aliases: b, bal. show performance compared to budget goals defined by periodic transactions -'--show-unbudgeted' - - with -budget, show unbudgeted accounts also The balance command is hledger's most versatile command. Note, despite the name, it is not always used for showing real-world account @@ -1510,7 +1507,8 @@ period (without -E, leading and trailing columns with all zeroes are not shown). Second, all accounts which existed at the report start date will be considered, not just the ones with activity during the report period (use -E to include low-activity accounts which would otherwise -would be omitted). +would be omitted). With '--budget', '--empty' also shows unbudgeted +accounts. The '-T/--row-total' flag adds an additional column showing the total for each row. @@ -1608,9 +1606,9 @@ are shown. In the example above, transactions in 'expenses:gifts' and 'expenses:gifts' and 'expenses:supplies' are not shown, as they don't have any budgets. - You can use '--show-unbudgeted' shows unbudgeted accounts as well: + You can use '--empty' shows unbudgeted accounts as well: -$ hledger balance -M --budget --show-unbudgeted +$ hledger balance -M --budget --empty Budget performance in 2017/11/01-2017/12/31: || Nov Dec @@ -1725,10 +1723,10 @@ Budget performance in 2019/01: -------------------------------++------------------------------- || 0 [ 0] - And with '--show-unbudgeted', we can get a better picture of budget -allocation and consumption: + And with '--empty', we can get a better picture of budget allocation +and consumption: -$ hledger balance --budget -M --show-unbudgeted +$ hledger balance --budget -M --empty Budget performance in 2019/01: || Jan @@ -2808,92 +2806,92 @@ Node: add35465 Ref: #add35564 Node: balance38225 Ref: #balance38336 -Node: Classic balance report41526 -Ref: #classic-balance-report41699 -Node: Customising the classic balance report43068 -Ref: #customising-the-classic-balance-report43296 -Node: Colour support45370 -Ref: #colour-support45537 -Node: Flat mode45710 -Ref: #flat-mode45858 -Node: Depth limited balance reports46271 -Ref: #depth-limited-balance-reports46471 -Node: Multicolumn balance report46927 -Ref: #multicolumn-balance-report47125 -Node: Budget report52305 -Ref: #budget-report52448 -Node: Nested budgets57152 -Ref: #nested-budgets57264 -Ref: #output-format-160764 -Node: balancesheet60842 -Ref: #balancesheet60978 -Node: balancesheetequity63289 -Ref: #balancesheetequity63438 -Node: cashflow63975 -Ref: #cashflow64103 -Node: check-dates66226 -Ref: #check-dates66353 -Node: check-dupes66470 -Ref: #check-dupes66594 -Node: close66731 -Ref: #close66839 -Node: files70253 -Ref: #files70354 -Node: help70495 -Ref: #help70595 -Node: import71669 -Ref: #import71783 -Node: incomestatement72513 -Ref: #incomestatement72647 -Node: prices75051 -Ref: #prices75166 -Node: print75438 -Ref: #print75548 -Node: print-unique80442 -Ref: #print-unique80568 -Node: register80636 -Ref: #register80763 -Node: Custom register output85264 -Ref: #custom-register-output85393 -Node: register-match86623 -Ref: #register-match86757 -Node: rewrite86940 -Ref: #rewrite87055 -Node: roi87124 -Ref: #roi87222 -Node: stats87338 -Ref: #stats87437 -Node: tags88307 -Ref: #tags88405 -Node: test88641 -Ref: #test88725 -Node: ADD-ON COMMANDS89433 -Ref: #add-on-commands89543 -Node: Official add-ons90830 -Ref: #official-add-ons90970 -Node: api91057 -Ref: #api91146 -Node: ui91198 -Ref: #ui91297 -Node: web91355 -Ref: #web91444 -Node: Third party add-ons91490 -Ref: #third-party-add-ons91665 -Node: diff91800 -Ref: #diff91897 -Node: iadd91996 -Ref: #iadd92110 -Node: interest92193 -Ref: #interest92314 -Node: irr92409 -Ref: #irr92507 -Node: Experimental add-ons92638 -Ref: #experimental-add-ons92790 -Node: autosync93070 -Ref: #autosync93181 -Node: chart93420 -Ref: #chart93539 -Node: check93610 -Ref: #check93712 +Node: Classic balance report41456 +Ref: #classic-balance-report41629 +Node: Customising the classic balance report42998 +Ref: #customising-the-classic-balance-report43226 +Node: Colour support45300 +Ref: #colour-support45467 +Node: Flat mode45640 +Ref: #flat-mode45788 +Node: Depth limited balance reports46201 +Ref: #depth-limited-balance-reports46401 +Node: Multicolumn balance report46857 +Ref: #multicolumn-balance-report47055 +Node: Budget report52295 +Ref: #budget-report52438 +Node: Nested budgets57122 +Ref: #nested-budgets57234 +Ref: #output-format-160714 +Node: balancesheet60792 +Ref: #balancesheet60928 +Node: balancesheetequity63239 +Ref: #balancesheetequity63388 +Node: cashflow63925 +Ref: #cashflow64053 +Node: check-dates66176 +Ref: #check-dates66303 +Node: check-dupes66420 +Ref: #check-dupes66544 +Node: close66681 +Ref: #close66789 +Node: files70203 +Ref: #files70304 +Node: help70445 +Ref: #help70545 +Node: import71619 +Ref: #import71733 +Node: incomestatement72463 +Ref: #incomestatement72597 +Node: prices75001 +Ref: #prices75116 +Node: print75388 +Ref: #print75498 +Node: print-unique80392 +Ref: #print-unique80518 +Node: register80586 +Ref: #register80713 +Node: Custom register output85214 +Ref: #custom-register-output85343 +Node: register-match86573 +Ref: #register-match86707 +Node: rewrite86890 +Ref: #rewrite87005 +Node: roi87074 +Ref: #roi87172 +Node: stats87288 +Ref: #stats87387 +Node: tags88257 +Ref: #tags88355 +Node: test88591 +Ref: #test88675 +Node: ADD-ON COMMANDS89383 +Ref: #add-on-commands89493 +Node: Official add-ons90780 +Ref: #official-add-ons90920 +Node: api91007 +Ref: #api91096 +Node: ui91148 +Ref: #ui91247 +Node: web91305 +Ref: #web91394 +Node: Third party add-ons91440 +Ref: #third-party-add-ons91615 +Node: diff91750 +Ref: #diff91847 +Node: iadd91946 +Ref: #iadd92060 +Node: interest92143 +Ref: #interest92264 +Node: irr92359 +Ref: #irr92457 +Node: Experimental add-ons92588 +Ref: #experimental-add-ons92740 +Node: autosync93020 +Ref: #autosync93131 +Node: chart93370 +Ref: #chart93489 +Node: check93560 +Ref: #check93662  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index ada9547f8..1e55cd417 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -1111,9 +1111,6 @@ COMMANDS show performance compared to budget goals defined by periodic transactions - --show-unbudgeted - with --budget, show unbudgeted accounts also - The balance command is hledger's most versatile command. Note, despite the name, it is not always used for showing real-world account bal- ances; the more accounting-aware balancesheet and incomestatement may @@ -1348,12 +1345,13 @@ COMMANDS not shown). Second, all accounts which existed at the report start date will be considered, not just the ones with activity during the report period (use -E to include low-activity accounts which would oth- - erwise would be omitted). + erwise would be omitted). With --budget, --empty also shows unbudgeted + accounts. The -T/--row-total flag adds an additional column showing the total for each row. - The -A/--average flag adds a column showing the average value in each + The -A/--average flag adds a column showing the average value in each row. Here's an example of all three: @@ -1377,20 +1375,20 @@ COMMANDS Limitations: In multicolumn reports the -V/--value flag uses the market price on the - report end date, for all columns (not the price on each column's end + report end date, for all columns (not the price on each column's end date). - Eliding of boring parent accounts in tree mode, as in the classic bal- + Eliding of boring parent accounts in tree mode, as in the classic bal- ance report, is not yet supported in multicolumn reports. Budget report - With --budget, extra columns are displayed showing budget goals for - each account and period, if any. Budget goals are defined by periodic - transactions. This is very useful for comparing planned and actual - income, expenses, time usage, etc. --budget is most often combined + With --budget, extra columns are displayed showing budget goals for + each account and period, if any. Budget goals are defined by periodic + transactions. This is very useful for comparing planned and actual + income, expenses, time usage, etc. --budget is most often combined with a report interval. - For example, you can take average monthly expenses in the common + For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: ;; Budget @@ -1435,15 +1433,15 @@ COMMANDS ----------------------++---------------------------------------------------- || 0 [ 0] 0 [ 0] - By default, only accounts with budget goals during the report period - are shown. In the example above, transactions in expenses:gifts and - expenses:supplies are counted towards expenses budget, but accounts - expenses:gifts and expenses:supplies are not shown, as they don't have + By default, only accounts with budget goals during the report period + are shown. In the example above, transactions in expenses:gifts and + expenses:supplies are counted towards expenses budget, but accounts + expenses:gifts and expenses:supplies are not shown, as they don't have any budgets. - You can use --show-unbudgeted shows unbudgeted accounts as well: + You can use --empty shows unbudgeted accounts as well: - $ hledger balance -M --budget --show-unbudgeted + $ hledger balance -M --budget --empty Budget performance in 2017/11/01-2017/12/31: || Nov Dec @@ -1479,18 +1477,18 @@ COMMANDS ----------------------++---------------------------------------------------- || 0 [ 0] 0 [ 0] - Note, the -S/--sort-amount flag is not yet fully supported with --bud- + Note, the -S/--sort-amount flag is not yet fully supported with --bud- get. For more examples, see Budgeting and Forecasting. Nested budgets - You can add budgets to any account in your account hierarchy. If you + You can add budgets to any account in your account hierarchy. If you have budgets on both parent account and some of its children, then bud- - get(s) of the child account(s) would be added to the budget of their + get(s) of the child account(s) would be added to the budget of their parent, much like account balances behave. - In the most simple case this means that once you add a budget to any + In the most simple case this means that once you add a budget to any account, all its parents would have budget as well. To illustrate this, consider the following budget: @@ -1500,13 +1498,13 @@ COMMANDS expenses:personal:electronics $100.00 liabilities - With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which implicity + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicity means that budget for both expenses:personal and expenses is $1100. - Transactions in expenses:personal:electronics will be counted both - towards its $100 budget and $1100 of expenses:personal , and transac- - tions in any other subaccount of expenses:personal would be counted + Transactions in expenses:personal:electronics will be counted both + towards its $100 budget and $1100 of expenses:personal , and transac- + tions in any other subaccount of expenses:personal would be counted towards only towards the budget of expenses:personal. For example, let's consider these transactions: @@ -1532,9 +1530,9 @@ COMMANDS expenses:personal $30.00 liabilities - As you can see, we have transactions in expenses:personal:electron- - ics:upgrades and expenses:personal:train tickets, and since both of - these accounts are without explicitly defined budget, these transac- + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- tions would be counted towards budgets of expenses:personal:electronics and expenses:personal accordingly: @@ -1550,10 +1548,10 @@ COMMANDS -------------------------------++------------------------------- || 0 [ 0] - And with --show-unbudgeted, we can get a better picture of budget allo- - cation and consumption: + And with --empty, we can get a better picture of budget allocation and + consumption: - $ hledger balance --budget -M --show-unbudgeted + $ hledger balance --budget -M --empty Budget performance in 2019/01: || Jan @@ -1568,16 +1566,16 @@ COMMANDS || 0 [ 0] Output format - The balance command supports output destination and output format + The balance command supports output destination and output format selection. balancesheet This command displays a simple balance sheet, showing historical ending - balances of asset and liability accounts (ignoring any report begin - date). It assumes that these accounts are under a top-level asset or - liability account (case insensitive, plural forms also allowed). Note - this report shows all account balances with normal positive sign (like - conventional financial statements, unlike balance/print/register) + balances of asset and liability accounts (ignoring any report begin + date). It assumes that these accounts are under a top-level asset or + liability account (case insensitive, plural forms also allowed). Note + this report shows all account balances with normal positive sign (like + conventional financial statements, unlike balance/print/register) (experimental). (bs) --change @@ -1585,7 +1583,7 @@ COMMANDS balances --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of historical ending balances -H --historical @@ -1641,16 +1639,16 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. As with multicolumn balance reports, you can alter the - report mode with --change/--cumulative/--historical. Normally bal- - ancesheet shows historical ending balances, which is what you need for + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. balancesheetequity - Just like balancesheet, but also reports Equity (which it assumes is + Just like balancesheet, but also reports Equity (which it assumes is under a top-level equity account). Example: @@ -1680,10 +1678,10 @@ COMMANDS 0 cashflow - This command displays a simple cashflow statement, showing changes in - "cash" accounts. It assumes that these accounts are under a top-level - asset account (case insensitive, plural forms also allowed) and do not - contain receivable or A/R in their name. Note this report shows all + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). (cf) @@ -1691,7 +1689,7 @@ COMMANDS show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1742,69 +1740,69 @@ COMMANDS $-1 With a reporting interval, multiple columns will be shown, one for each - report period. Normally cashflow shows changes in assets per period, - though as with multicolumn balance reports you can alter the report + report period. Normally cashflow shows changes in assets per period, + though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. check-dates - Check that transactions are sorted by increasing date. With a query, + Check that transactions are sorted by increasing date. With a query, only matched transactions' dates are checked. check-dupes - Report account names having the same leaf but different prefixes. An + Report account names having the same leaf but different prefixes. An example: http://stefanorodighiero.net/software/hledger-dupes.html close - close, equity Prints a "closing balances" transaction and an "opening - balances" transaction that bring account balances to and from zero, - respectively. Useful for bringing asset/liability balances forward - into a new journal file, or for closing out revenues/expenses to + close, equity Prints a "closing balances" transaction and an "opening + balances" transaction that bring account balances to and from zero, + respectively. Useful for bringing asset/liability balances forward + into a new journal file, or for closing out revenues/expenses to retained earnings at the end of a period. - The closing transaction transfers balances to "equity:closing bal- - ances". The opening transaction transfers balances from "equity:open- - ing balances". You can chose to print just one of the transactions by + The closing transaction transfers balances to "equity:closing bal- + ances". The opening transaction transfers balances from "equity:open- + ing balances". You can chose to print just one of the transactions by using the --opening or --closing flag. If you split your journal files by time (eg yearly), you will typically - run this command at the end of the year, and save the closing transac- - tion as last entry of the old file, and the opening transaction as the - first entry of the new file. This makes the files self contained, so - that correct balances are reported no matter which of them are loaded. - Ie, if you load just one file, the balances are initialised correctly; - or if you load several files, the redundant closing/opening transac- - tions cancel each other out. (They will show up in print or register - reports; you can exclude them with a query like not:desc:'(open- + run this command at the end of the year, and save the closing transac- + tion as last entry of the old file, and the opening transaction as the + first entry of the new file. This makes the files self contained, so + that correct balances are reported no matter which of them are loaded. + Ie, if you load just one file, the balances are initialised correctly; + or if you load several files, the redundant closing/opening transac- + tions cancel each other out. (They will show up in print or register + reports; you can exclude them with a query like not:desc:'(open- ing|closing) balances'.) If you're running a business, you might also use this command to "close - the books" at the end of an accounting period, transferring income - statement account balances to retained earnings. (You may want to + the books" at the end of an accounting period, transferring income + statement account balances to retained earnings. (You may want to change the equity account name to something like "equity:retained earn- ings".) - By default, the closing transaction is dated yesterday, the balances - are calculated as of end of yesterday, and the opening transaction is - dated today. To close on some other date, use: hledger close -e OPEN- - INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. + By default, the closing transaction is dated yesterday, the balances + are calculated as of end of yesterday, and the opening transaction is + dated today. To close on some other date, use: hledger close -e OPEN- + INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also use -p or date:PERIOD (any starting date is ignored). Both transactions will include balance assertions for the - closed/reopened accounts. You probably shouldn't use status or real- - ness filters (like -C or -R or status:) with this command, or the gen- + closed/reopened accounts. You probably shouldn't use status or real- + ness filters (like -C or -R or status:) with this command, or the gen- erated balance assertions will depend on these flags. Likewise, if you - run this command with --auto, the balance assertions will probably + run this command with --auto, the balance assertions will probably always require --auto. Examples: - Carrying asset/liability balances into a new file for 2019, all from + Carrying asset/liability balances into a new file for 2019, all from command line: - Warning: we use >> here to append; be careful not to type a single > + Warning: we use >> here to append; be careful not to type a single > which would wipe your journal! $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal @@ -1836,19 +1834,19 @@ COMMANDS assets:checking files - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. help Show any of the hledger manuals. - The help command displays any of the main hledger manuals, in one of - several ways. Run it with no argument to list the manuals, or provide + The help command displays any of the main hledger manuals, in one of + several ways. Run it with no argument to list the manuals, or provide a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can + hledger manuals are available in several formats. hledger help will + use the first of these display methods that it finds: info, man, + $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. $ hledger help @@ -1872,7 +1870,7 @@ COMMANDS ... import - Read new transactions added to each FILE since last run, and add them + Read new transactions added to each FILE since last run, and add them to the main journal file. --dry-run @@ -1886,24 +1884,24 @@ COMMANDS ing transactions are always added to the input files in increasing date order, and by saving .latest.FILE state files. - The --dry-run output is in journal format, so you can filter it, eg to + The --dry-run output is in journal format, so you can filter it, eg to see only uncategorised transactions: $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions incomestatement - This command displays a simple income statement, showing revenues and - expenses during a period. It assumes that these accounts are under a - top-level revenue or income or expense account (case insensitive, plu- - ral forms also allowed). Note this report shows all account balances - with normal positive sign (like conventional financial statements, + This command displays a simple income statement, showing revenues and + expenses during a period. It assumes that these accounts are under a + top-level revenue or income or expense account (case insensitive, plu- + ral forms also allowed). Note this report shows all account balances + with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). (is) --change show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1937,8 +1935,8 @@ COMMANDS --sort-amount sort by amount instead of account code/name - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense (plural forms also allowed.) $ hledger incomestatement @@ -1963,25 +1961,25 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. prices - Print market price directives from the journal. With --costs, also - print synthetic market prices based on transaction prices. With + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With --inverted-costs, also print inverse prices based on transaction - prices. Prices (and postings providing prices) can be filtered by a + prices. Prices (and postings providing prices) can be filtered by a query. print Show transactions from the journal. Aliases: p, txns. -m STR --match=STR - show the transaction whose description is most similar to STR, + show the transaction whose description is most similar to STR, and is most recent --new show only newer-dated transactions added in each file since last @@ -1994,7 +1992,7 @@ COMMANDS select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger print @@ -2025,39 +2023,39 @@ COMMANDS it does not preserve directives or inter-transaction comments Normally, the journal entry's explicit or implicit amount style is pre- - served. Ie when an amount is omitted in the journal, it will be omit- - ted in the output. You can use the -x/--explicit flag to make all + served. Ie when an amount is omitted in the journal, it will be omit- + ted in the output. You can use the -x/--explicit flag to make all amounts explicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. Note, - -x will cause postings with a multi-commodity amount (these can arise - when a multi-commodity transaction has an implicit amount) will be - split into multiple single-commodity postings, for valid journal out- + -x will cause postings with a multi-commodity amount (these can arise + when a multi-commodity transaction has an implicit amount) will be + split into multiple single-commodity postings, for valid journal out- put. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. This can be used for troubleshooting. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for - ignoring already-seen entries in import data, such as downloaded CSV + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for + ignoring already-seen entries in import data, such as downloaded CSV files. Eg: $ hledger -f bank1.csv print --new # shows transactions added since last print --new on this file - This assumes that transactions added to FILE always have same or - increasing dates, and that transactions on the same day do not get + This assumes that transactions added to FILE always have same or + increasing dates, and that transactions on the same day do not get reordered. See also the import command. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -2074,20 +2072,20 @@ COMMANDS "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) print-unique @@ -2100,7 +2098,7 @@ COMMANDS show running total from report start date (default) -H --historical - show historical running total/balance (includes postings before + show historical running total/balance (includes postings before report start date) -A --average @@ -2111,18 +2109,18 @@ COMMANDS show postings' siblings instead -w N --width=N - set output width (default: terminal width or COLUMNS. -wN,M + set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. The register command displays postings, one per line, and their running - total. This is typically used with a query selecting a particular + total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -2131,8 +2129,8 @@ COMMANDS 2008/06/02 save assets:bank:checking $-1 $1 2008/12/31 pay off assets:bank:checking $-1 0 - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -2142,23 +2140,23 @@ COMMANDS The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one account and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - With a reporting interval, register shows summary postings, one per + With a reporting interval, register shows summary postings, one per interval, aggregating the postings to each account: $ hledger register --monthly income 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -2175,7 +2173,7 @@ COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth + 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 @@ -2183,19 +2181,19 @@ COMMANDS 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of - intervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of + intervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a - description width as part of --width's argument, comma-separated: + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a + description width as part of --width's argument, comma-separated: --width W,D . Here's a diagram: <--------------------------------- width (W) ----------------------------------> @@ -2211,26 +2209,26 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. Helps ledger-autosync detect + in the style of the register command. Helps ledger-autosync detect already-seen transactions when importing. rewrite Print all transactions, adding custom postings to the matched ones. roi - Shows time-weighted (TWR) and money-weighted (IRR) rate of return on + Shows time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. See roi --help for more. stats Show some journal statistics. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger stats @@ -2245,61 +2243,61 @@ COMMANDS Accounts : 8 (depth 3) Commodities : 1 ($) - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags - List all the tag names used in the journal. With a TAGREGEX argument, - only tag names matching the regular expression (case insensitive) are + List all the tag names used in the journal. With a TAGREGEX argument, + only tag names matching the regular expression (case insensitive) are shown. With additional QUERY arguments, only transactions matching the query are considered. test Run built-in unit tests. - Prints test names and their results on stdout. If any test fails or + Prints test names and their results on stdout. If any test fails or gives an error, the exit code will be non-zero. - Test names include a group prefix. If a (exact, case sensitive) group - prefix, or a full test name is provided as the first argument, only + Test names include a group prefix. If a (exact, case sensitive) group + prefix, or a full test name is provided as the first argument, only that group or test is run. - If a numeric second argument is provided, it will set the randomness - seed, for repeatable results from tests using randomness (currently + If a numeric second argument is provided, it will set the randomness + seed, for repeatable results from tests using randomness (currently none of them). - This is mainly used by developers, but it's nice to be able to san- + This is mainly used by developers, but it's nice to be able to san- ity-check your installed hledger executable at any time. All tests are expected to pass - if you ever see otherwise, something has gone wrong, please report a bug! ADD-ON COMMANDS - hledger also searches for external add-on commands, and will include + hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- + whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few + Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them - from hledger. So hledger web --serve --port 9000 will be rejected; + o Flags specific to the add-on must have a preceding -- to hide them + from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. - o You can always run add-ons directly if preferred: + o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger (and - haskell) library functions that built-in commands do, for command-line + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. Here are some hledger add-ons available: @@ -2317,7 +2315,7 @@ ADD-ON COMMANDS hledger-web provides a simple web interface. Third party add-ons - These are maintained separately, and usually updated shortly after a + These are maintained separately, and usually updated shortly after a hledger release. diff @@ -2325,7 +2323,7 @@ ADD-ON COMMANDS journal file and another. iadd - hledger-iadd is a curses-style, more interactive replacement for the + hledger-iadd is a curses-style, more interactive replacement for the add command. interest @@ -2333,19 +2331,19 @@ ADD-ON COMMANDS ing to various schemes. irr - hledger-irr calculates the internal rate of return of an investment + hledger-irr calculates the internal rate of return of an investment account, but it's superseded now by the built-in roi command. Experimental add-ons - These are available in source form in the hledger repo's bin/ direc- + These are available in source form in the hledger repo's bin/ direc- tory; installing them is pretty easy. They may be less mature and doc- - umented than built-in commands. Reading and tweaking these is a good + umented than built-in commands. Reading and tweaking these is a good way to start making your own! autosync hledger-autosync is a symbolic link for easily running ledger-autosync, - if installed. ledger-autosync does deduplicating conversion of OFX - data and some CSV formats, and can also download the data if your bank + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank offers OFX Direct Connect. chart @@ -2355,21 +2353,21 @@ ADD-ON COMMANDS hledger-check.hs checks more powerful account balance assertions. ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). BUGS - The need to precede addon command options with -- when invoked from + The need to precede addon command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -2382,33 +2380,33 @@ BUGS In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu @@ -2427,7 +2425,7 @@ TROUBLESHOOTING $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ bash --login - If we preferred to use eg fr_FR.utf8, we might have to install that + If we preferred to use eg fr_FR.utf8, we might have to install that first: $ apt-get install language-pack-fr @@ -2448,7 +2446,7 @@ TROUBLESHOOTING REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -2462,7 +2460,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1)