diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index 18a57897d..434aca4ba 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -1066,13 +1066,21 @@ As you can see, directives vary in which journal entries and files they affect, and whether they are focussed on input (parsing) or output (reports). Some directives have multiple effects. +.SS Directives and multiple files .PP -If you 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 provides more simplicity and predictability, eg reports are not -changed by writing file options in a different order. -It can be surprising at times though. +If you use multiple \f[C]-f\f[R]/\f[C]--file\f[R] options, or the +\f[C]include\f[R] directive, hledger will process multiple input files. +But note that directives which affect input (see above) typically last +only until the end of the file in which they occur. +.PP +This may seem inconvenient, but it\[aq]s intentional; it makes reports +stable and deterministic, independent of the order of input. +Otherwise you could see different numbers if you happened to write -f +options in a different order, or if you moved includes around while +cleaning up your files. +.PP +It can be surprising though; for example, it means that \f[C]alias\f[R] +directives do not affect parent or sibling files (see below). .SS Comment blocks .PP A line containing just \f[C]comment\f[R] starts a commented region of @@ -1543,6 +1551,46 @@ independent of which files are being read and in which order. .PP In case of trouble, adding \f[C]--debug=6\f[R] to the command line will show which aliases are being applied when. +.SS Aliases and multiple files +.PP +As explained at Directives and multiple files, \f[C]alias\f[R] +directives do not affect parent or sibling files. +Eg in this command, +.IP +.nf +\f[C] +hledger -f a.aliases -f b.journal +\f[R] +.fi +.PP +account aliases defined in a.aliases will not affect b.journal. +Including the aliases doesn\[aq]t work either: +.IP +.nf +\f[C] +include a.aliases + +2020-01-01 ; not affected by a.aliases + foo 1 + bar +\f[R] +.fi +.PP +This means that account aliases should usually be declared at the start +of your top-most file, like this: +.IP +.nf +\f[C] +alias foo=Foo +alias bar=Bar + +2020-01-01 ; affected by aliases above + foo 1 + bar + +include c.journal ; also affected +\f[R] +.fi .SS \f[C]end aliases\f[R] .PP You can clear (forget) all currently defined aliases with the diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index c4165dddb..65c23ce30 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -929,15 +929,9 @@ scope are affected by a directive they 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 provides -more simplicity and predictability, eg reports are not changed by -writing file options in a different order. It can be surprising at -times though. - * Menu: +* Directives and multiple files:: * Comment blocks:: * Including other files:: * Default year:: @@ -949,9 +943,29 @@ times though. * Default parent account::  -File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Up: Directives +File: hledger_journal.info, Node: Directives and multiple files, Next: Comment blocks, Up: Directives -1.12.1 Comment blocks +1.12.1 Directives and multiple files +------------------------------------ + +If you use multiple '-f'/'--file' options, or the 'include' directive, +hledger will process multiple input files. But note that directives +which affect input (see above) typically last only until the end of the +file in which they occur. + + This may seem inconvenient, but it's intentional; it makes reports +stable and deterministic, independent of the order of input. Otherwise +you could see different numbers if you happened to write -f options in a +different order, or if you moved includes around while cleaning up your +files. + + It can be surprising though; for example, it means that 'alias' +directives do not affect parent or sibling files (see below). + + +File: hledger_journal.info, Node: Comment blocks, Next: Including other files, Prev: Directives and multiple files, Up: Directives + +1.12.2 Comment blocks --------------------- A line containing just 'comment' starts a commented region of the file, @@ -961,7 +975,7 @@ file) ends it. See also comments.  File: hledger_journal.info, Node: Including other files, Next: Default year, Prev: Comment blocks, Up: Directives -1.12.2 Including other files +1.12.3 Including other files ---------------------------- You can pull in the content of additional files by writing an include @@ -979,7 +993,7 @@ include journal, timeclock or timedot files, but not CSV files.  File: hledger_journal.info, Node: Default year, Next: Declaring commodities, Prev: Including other files, Up: Directives -1.12.3 Default year +1.12.4 Default year ------------------- You can set a default year to be used for subsequent dates which don't @@ -1005,7 +1019,7 @@ Y2010 ; change default year to 2010  File: hledger_journal.info, Node: Declaring commodities, Next: Default commodity, Prev: Default year, Up: Directives -1.12.4 Declaring commodities +1.12.5 Declaring commodities ---------------------------- The 'commodity' directive has several functions: @@ -1055,7 +1069,7 @@ a comma, followed by 0 or more decimal digits.  File: hledger_journal.info, Node: Default commodity, Next: Market prices, Prev: Declaring commodities, Up: Directives -1.12.5 Default commodity +1.12.6 Default commodity ------------------------ The 'D' directive sets a default commodity, to be used for amounts @@ -1082,7 +1096,7 @@ D $1,000.00  File: hledger_journal.info, Node: Market prices, Next: Declaring accounts, Prev: Default commodity, Up: Directives -1.12.6 Market prices +1.12.7 Market prices -------------------- The 'P' directive declares a market price, which is an exchange rate @@ -1112,7 +1126,7 @@ another commodity using these prices.  File: hledger_journal.info, Node: Declaring accounts, Next: Rewriting accounts, Prev: Market prices, Up: Directives -1.12.7 Declaring accounts +1.12.8 Declaring accounts ------------------------- 'account' directives can be used to pre-declare accounts. Though not @@ -1145,7 +1159,7 @@ account assets:bank:checking  File: hledger_journal.info, Node: Account comments, Next: Account subdirectives, Up: Declaring accounts -1.12.7.1 Account comments +1.12.8.1 Account comments ......................... Comments, beginning with a semicolon, can be added: @@ -1165,7 +1179,7 @@ account assets:bank:checking ; same-line comment, note 2+ spaces before ;  File: hledger_journal.info, Node: Account subdirectives, Next: Account types, Prev: Account comments, Up: Declaring accounts -1.12.7.2 Account subdirectives +1.12.8.2 Account subdirectives .............................. We also allow (and ignore) Ledger-style indented subdirectives, just for @@ -1183,7 +1197,7 @@ account ACCTNAME [ACCTTYPE] [;COMMENT]  File: hledger_journal.info, Node: Account types, Next: Account display order, Prev: Account subdirectives, Up: Declaring accounts -1.12.7.3 Account types +1.12.8.3 Account types ...................... hledger recognises five types (or classes) of account: Asset, Liability, @@ -1228,7 +1242,7 @@ account - ; type:L  File: hledger_journal.info, Node: Account display order, Prev: Account types, Up: Declaring accounts -1.12.7.4 Account display order +1.12.8.4 Account display order .............................. Account directives also set the order in which accounts are displayed, @@ -1274,7 +1288,7 @@ means:  File: hledger_journal.info, Node: Rewriting accounts, Next: Default parent account, Prev: Declaring accounts, Up: Directives -1.12.8 Rewriting accounts +1.12.9 Rewriting accounts ------------------------- You can define account alias rules which rewrite your account names, or @@ -1298,12 +1312,13 @@ hledger-web. * Basic aliases:: * Regex aliases:: * Combining aliases:: +* Aliases and multiple files:: * end aliases::  File: hledger_journal.info, Node: Basic aliases, Next: Regex aliases, Up: Rewriting accounts -1.12.8.1 Basic aliases +1.12.9.1 Basic aliases ...................... To set an account alias, use the 'alias' directive in your journal file. @@ -1326,7 +1341,7 @@ alias checking = assets:bank:wells fargo:checking  File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts -1.12.8.2 Regex aliases +1.12.9.2 Regex aliases ...................... There is also a more powerful variant that uses a regular expression, @@ -1349,9 +1364,9 @@ command line, to end of option argument), so it can contain trailing whitespace.  -File: hledger_journal.info, Node: Combining aliases, Next: end aliases, Prev: Regex aliases, Up: Rewriting accounts +File: hledger_journal.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: Rewriting accounts -1.12.8.3 Combining aliases +1.12.9.3 Combining aliases .......................... You can define as many aliases as you like, using journal directives @@ -1386,9 +1401,41 @@ independent of which files are being read and in which order. which aliases are being applied when.  -File: hledger_journal.info, Node: end aliases, Prev: Combining aliases, Up: Rewriting accounts +File: hledger_journal.info, Node: Aliases and multiple files, Next: end aliases, Prev: Combining aliases, Up: Rewriting accounts -1.12.8.4 'end aliases' +1.12.9.4 Aliases and multiple files +................................... + +As explained at Directives and multiple files, 'alias' directives do not +affect parent or sibling files. Eg in this command, + +hledger -f a.aliases -f b.journal + + account aliases defined in a.aliases will not affect b.journal. +Including the aliases doesn't work either: + +include a.aliases + +2020-01-01 ; not affected by a.aliases + foo 1 + bar + + This means that account aliases should usually be declared at the +start of your top-most file, like this: + +alias foo=Foo +alias bar=Bar + +2020-01-01 ; affected by aliases above + foo 1 + bar + +include c.journal ; also affected + + +File: hledger_journal.info, Node: end aliases, Prev: Aliases and multiple files, Up: Rewriting accounts + +1.12.9.5 'end aliases' ...................... You can clear (forget) all currently defined aliases with the 'end @@ -1399,8 +1446,8 @@ end aliases  File: hledger_journal.info, Node: Default parent account, Prev: Rewriting accounts, Up: Directives -1.12.9 Default parent account ------------------------------ +1.12.10 Default parent account +------------------------------ You can specify a parent account which will be prepended to all accounts within a section of the journal. Use the 'apply account' and 'end apply @@ -1793,58 +1840,62 @@ Node: Balance assignments and prices29457 Ref: #balance-assignments-and-prices29629 Node: Directives29853 Ref: #directives30012 -Node: Comment blocks35660 -Ref: #comment-blocks35805 -Node: Including other files35981 -Ref: #including-other-files36161 -Node: Default year36569 -Ref: #default-year36738 -Node: Declaring commodities37145 -Ref: #declaring-commodities37328 -Node: Default commodity39001 -Ref: #default-commodity39177 -Node: Market prices40066 -Ref: #market-prices40231 -Node: Declaring accounts41072 -Ref: #declaring-accounts41248 -Node: Account comments42173 -Ref: #account-comments42336 -Node: Account subdirectives42760 -Ref: #account-subdirectives42955 -Node: Account types43268 -Ref: #account-types43452 -Node: Account display order45091 -Ref: #account-display-order45261 -Node: Rewriting accounts46412 -Ref: #rewriting-accounts46597 -Node: Basic aliases47323 -Ref: #basic-aliases47469 -Node: Regex aliases48173 -Ref: #regex-aliases48345 -Node: Combining aliases49063 -Ref: #combining-aliases49241 -Node: end aliases50517 -Ref: #end-aliases50665 -Node: Default parent account50766 -Ref: #default-parent-account50932 -Node: Periodic transactions51816 -Ref: #periodic-transactions52015 -Node: Periodic rule syntax53887 -Ref: #periodic-rule-syntax54093 -Node: Two spaces between period expression and description!54797 -Ref: #two-spaces-between-period-expression-and-description55116 -Node: Forecasting with periodic transactions55800 -Ref: #forecasting-with-periodic-transactions56105 -Node: Budgeting with periodic transactions58131 -Ref: #budgeting-with-periodic-transactions58370 -Node: Auto postings / transaction modifiers58819 -Ref: #auto-postings-transaction-modifiers59031 -Node: Auto postings and dates61527 -Ref: #auto-postings-and-dates61784 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions61959 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions62334 -Node: Auto posting tags62712 -Ref: #auto-posting-tags62951 +Node: Directives and multiple files35331 +Ref: #directives-and-multiple-files35514 +Node: Comment blocks36178 +Ref: #comment-blocks36361 +Node: Including other files36537 +Ref: #including-other-files36717 +Node: Default year37125 +Ref: #default-year37294 +Node: Declaring commodities37701 +Ref: #declaring-commodities37884 +Node: Default commodity39557 +Ref: #default-commodity39733 +Node: Market prices40622 +Ref: #market-prices40787 +Node: Declaring accounts41628 +Ref: #declaring-accounts41804 +Node: Account comments42729 +Ref: #account-comments42892 +Node: Account subdirectives43316 +Ref: #account-subdirectives43511 +Node: Account types43824 +Ref: #account-types44008 +Node: Account display order45647 +Ref: #account-display-order45817 +Node: Rewriting accounts46968 +Ref: #rewriting-accounts47153 +Node: Basic aliases47910 +Ref: #basic-aliases48056 +Node: Regex aliases48760 +Ref: #regex-aliases48932 +Node: Combining aliases49650 +Ref: #combining-aliases49843 +Node: Aliases and multiple files51119 +Ref: #aliases-and-multiple-files51328 +Node: end aliases51907 +Ref: #end-aliases52064 +Node: Default parent account52165 +Ref: #default-parent-account52333 +Node: Periodic transactions53217 +Ref: #periodic-transactions53416 +Node: Periodic rule syntax55288 +Ref: #periodic-rule-syntax55494 +Node: Two spaces between period expression and description!56198 +Ref: #two-spaces-between-period-expression-and-description56517 +Node: Forecasting with periodic transactions57201 +Ref: #forecasting-with-periodic-transactions57506 +Node: Budgeting with periodic transactions59532 +Ref: #budgeting-with-periodic-transactions59771 +Node: Auto postings / transaction modifiers60220 +Ref: #auto-postings-transaction-modifiers60432 +Node: Auto postings and dates62928 +Ref: #auto-postings-and-dates63185 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions63360 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions63735 +Node: Auto posting tags64113 +Ref: #auto-posting-tags64352  End Tag Table diff --git a/hledger-lib/hledger_journal.m4.md b/hledger-lib/hledger_journal.m4.md index c8f5e6d08..988a1e75a 100644 --- a/hledger-lib/hledger_journal.m4.md +++ b/hledger-lib/hledger_journal.m4.md @@ -819,18 +819,22 @@ As you can see, directives vary in which journal entries and files they affect, and whether they are focussed on input (parsing) or output (reports). Some directives have multiple effects. -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 provides more simplicity and predictability, eg reports are not changed by writing file options in a different order. -It can be surprising at times though. - +This may seem inconvenient, but it's intentional; it makes reports +stable and deterministic, independent of the order of input. Otherwise +you could see different numbers if you happened to write -f options in +a different order, or if you moved includes around while cleaning up +your files. + +It can be surprising though; for example, it means that +[`alias` directives do not affect parent or sibling files](#aliases-and-multiple-files) +(see below). ### Comment blocks @@ -1215,9 +1219,39 @@ independent of which files are being read and in which order. In case of trouble, adding `--debug=6` to the command line will show which aliases are being applied when. +#### Aliases and multiple files + +As explained at [Directives and multiple files](#directives-and-multiple-files), +`alias` directives do not affect parent or sibling files. Eg in this command, +```shell +hledger -f a.aliases -f b.journal +``` +account aliases defined in a.aliases will not affect b.journal. +Including the aliases doesn't work either: +```journal +include a.aliases + +2020-01-01 ; not affected by a.aliases + foo 1 + bar +``` +This means that account aliases should usually be declared at the +start of your top-most file, like this: +```journal +alias foo=Foo +alias bar=Bar + +2020-01-01 ; affected by aliases above + foo 1 + bar + +include c.journal ; also affected +``` + #### `end aliases` -You can clear (forget) all currently defined aliases with the `end aliases` directive: +You can clear (forget) all currently defined aliases with the `end +aliases` directive: ```journal end aliases diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 118de1297..c076424a2 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -732,34 +732,42 @@ FILE FORMAT affect, and whether they are focussed on input (parsing) or output (re- ports). 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- - vides more simplicity and predictability, eg reports are not changed by - writing file options in a different order. It can be surprising at - times though. + Directives and multiple files + If you use multiple -f/--file options, or the include directive, + hledger will process multiple input files. But note that directives + which affect input (see above) typically last only until the end of the + file in which they occur. + + This may seem inconvenient, but it's intentional; it makes reports sta- + ble and deterministic, independent of the order of input. Otherwise + you could see different numbers if you happened to write -f options in + a different order, or if you moved includes around while cleaning up + your files. + + It can be surprising though; for example, it means that alias direc- + tives do not affect parent or sibling files (see below). Comment blocks - A line containing just comment starts a commented region of the file, + 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 in- + The include directive can only be used in journal files. It can in- clude 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 @@ -781,19 +789,19 @@ FILE FORMAT Declaring commodities The commodity directive has several functions: - 1. It declares commodities which may be used in the journal. This is + 1. It declares commodities which may be used in the journal. This is currently not enforced, but can serve as documentation. - 2. It declares what decimal mark character (period or comma) to expect - when parsing input - useful to disambiguate international number - formats in your data. (Without this, hledger will parse both 1,000 + 2. It declares what decimal mark character (period or comma) to expect + when parsing input - useful to disambiguate international number + formats in your data. (Without this, hledger will parse both 1,000 and 1.000 as 1). - 3. It declares the amount display style to use in output - decimal and + 3. It declares the amount display style to use in output - decimal and digit group marks, number of decimal places, symbol placement etc. - You are likely to run into one of the problems solved by commodity di- - rectives, sooner or later, so it's a good idea to just always use them + You are likely to run into one of the problems solved by commodity di- + rectives, sooner or later, so it's a good idea to just always use them to declare your commodities. A commodity directive is just the word commodity followed by an amount. @@ -806,8 +814,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 @@ -820,19 +828,19 @@ FILE FORMAT format INR 1,00,00,000.00 The quantity of the amount does not matter; only the format is signifi- - cant. The number must include a decimal mark: either a period or a + cant. The number must include a decimal mark: either a period or a comma, followed by 0 or more decimal digits. Default commodity - The D directive sets a default commodity, to be used for amounts with- + The D directive sets a default commodity, to be used for amounts with- out a commodity symbol (ie, plain numbers). This commodity will be ap- plied to all subsequent commodity-less amounts, or until the next D di- rective. (Note, this is different from Ledger's D.) - For compatibility/historical reasons, D also acts like a commodity di- + For compatibility/historical reasons, D also acts like a commodity di- rective, setting the commodity's display style (for output) and decimal mark (for parsing input). As with commodity, the amount must always be - written with a decimal mark (period or comma). If both directives are + written with a decimal mark (period or comma). If both directives are used, commodity's style takes precedence. The syntax is D AMOUNT. Eg: @@ -846,9 +854,9 @@ FILE FORMAT b Market prices - The P directive declares a market price, which is an exchange rate be- - tween two commodities on a certain date. (In Ledger, they are called - "historical prices".) These are often obtained from a stock exchange, + The P directive declares a market price, which is an exchange rate be- + tween two commodities on a certain date. (In Ledger, they are called + "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. Here is the format: @@ -859,16 +867,16 @@ 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 EUR $1.35 P 2010/1/1 EUR $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 @@ -878,20 +886,20 @@ FILE FORMAT 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, hledger- + 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 @@ -899,7 +907,7 @@ FILE FORMAT Account comments Comments, beginning with a semicolon, can be added: - o on the same line, after two or more spaces (because ; is allowed in + o on the same line, after two or more spaces (because ; is allowed in account names) o on the next lines, indented @@ -913,7 +921,7 @@ FILE FORMAT Same-line comments are not supported by Ledger, or hledger <1.13. 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 @@ -926,18 +934,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 di- - rective, 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 di- + rective, 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): @@ -948,8 +956,8 @@ FILE FORMAT account expenses ; type:Expense 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 @@ -959,7 +967,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 @@ -970,8 +978,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: @@ -993,20 +1001,20 @@ 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 + would influence the position of zoo among other's subaccounts, but not the position of other among the top-level accounts. This means: - o you will sometimes declare parent accounts (eg account other above) + o you will sometimes declare parent accounts (eg account other above) that you don't intend to post to, just to customize their display or- der - o sibling accounts stay together (you couldn't display x:y in between + o sibling accounts stay together (you couldn't display x:y in between a:b and a:c). Rewriting accounts @@ -1024,14 +1032,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 hledger- + do not affect account names being entered via hledger add or hledger- web. See also Rewrite account names. Basic aliases - To set an account alias, use the alias directive in your journal file. - This affects all subsequent journal entries in the current file or its + 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 @@ -1039,49 +1047,49 @@ 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 re- - place any occurrence of the old account name with the new one. Subac- + OLD and NEW are case sensitive full account names. hledger will re- + place any occurrence of the old account name with the new one. Subac- counts 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. Combining aliases - You can define as many aliases as you like, using journal directives + You can define as many aliases as you like, using journal directives and/or command line options. - Recursive aliases - where an account name is rewritten by one alias, - then by another alias, and so on - are allowed. Each alias sees the + Recursive aliases - where an account name is rewritten by one alias, + then by another alias, and so on - are allowed. Each alias sees the effect of previously applied aliases. - In such cases it can be important to understand which aliases will be - applied and in which order. For (each account name in) each journal + In such cases it can be important to understand which aliases will be + applied and in which order. For (each account name in) each journal entry, we apply: - 1. alias directives preceding the journal entry, most recently parsed + 1. alias directives preceding the journal entry, most recently parsed first (ie, reading upward from the journal entry, bottom to top) - 2. --alias options, in the order they appeared on the command line + 2. --alias options, in the order they appeared on the command line (left to right). In other words, for (an account name in) a given journal entry: @@ -1092,13 +1100,40 @@ FILE FORMAT o aliases defined after/below the entry do not affect it. - This gives nearby aliases precedence over distant ones, and helps pro- - vide semantic stability - aliases will keep working the same way inde- + This gives nearby aliases precedence over distant ones, and helps pro- + vide semantic stability - aliases will keep working the same way inde- pendent of which files are being read and in which order. - In case of trouble, adding --debug=6 to the command line will show + In case of trouble, adding --debug=6 to the command line will show which aliases are being applied when. + Aliases and multiple files + As explained at Directives and multiple files, alias directives do not + affect parent or sibling files. Eg in this command, + + hledger -f a.aliases -f b.journal + + account aliases defined in a.aliases will not affect b.journal. In- + cluding the aliases doesn't work either: + + include a.aliases + + 2020-01-01 ; not affected by a.aliases + foo 1 + bar + + This means that account aliases should usually be declared at the start + of your top-most file, like this: + + alias foo=Foo + alias bar=Bar + + 2020-01-01 ; affected by aliases above + foo 1 + bar + + include c.journal ; also affected + end aliases You can clear (forget) all currently defined aliases with the end aliases directive: