From f91076cc6a9afd93a2c8d41eebf3733883ffb433 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 5 Jan 2020 07:04:00 -0800 Subject: [PATCH] ;doc: regen manuals I think all the non-content changes are due to newer doc tools and harmless, including this one hopefully: -.B \f[C]--watch\f[R] +\f[B]\f[CB]--watch\f[B]\f[R] [ci skip] --- hledger-lib/hledger_csv.5 | 69 +++- hledger-lib/hledger_csv.info | 179 ++++++---- hledger-lib/hledger_csv.txt | 74 +++- hledger-lib/hledger_journal.5 | 1 + hledger-lib/hledger_journal.info | 174 +++++----- hledger-lib/hledger_journal.txt | 445 ++++++++++++------------ hledger-lib/hledger_timeclock.5 | 2 +- hledger-lib/hledger_timeclock.info | 7 +- hledger-lib/hledger_timeclock.txt | 6 +- hledger-lib/hledger_timedot.info | 7 +- hledger-ui/hledger-ui.1 | 75 ++-- hledger-ui/hledger-ui.info | 34 +- hledger-ui/hledger-ui.txt | 217 ++++++------ hledger-web/hledger-web.1 | 77 +++-- hledger-web/hledger-web.info | 26 +- hledger-web/hledger-web.txt | 111 +++--- hledger/hledger.1 | 184 ++++++---- hledger/hledger.info | 437 ++++++++++++----------- hledger/hledger.txt | 534 ++++++++++++++++------------- 19 files changed, 1486 insertions(+), 1173 deletions(-) diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index c7d25bc31..4c1fe63e4 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -472,6 +472,9 @@ Fields you don\[aq]t care about can be left unnamed. Currently there must be least two items (there must be at least one comma). .PP +Note, always use comma in the fields list, even if your CSV uses another +separator character. +.PP Here are the standard hledger field/pseudo-field names. For more about the transaction parts they refer to, see the manual for hledger\[aq]s journal format. @@ -508,6 +511,7 @@ If the CSV has the currency symbol in a separate field, you can use .PP \f[C]balanceN\f[R] sets a balance assertion amount (or if the posting amount is left empty, a balance assignment). +You may need to adjust this with the \f[C]balance-type\f[R] rule. .PP Finally, \f[C]commentN\f[R] sets a comment on the Nth posting. Comments can also contain tags, as usual. @@ -733,7 +737,52 @@ account2 expenses:misc include categorisation.rules \f[R] .fi +.SS \f[C]balance-type\f[R] +.PP +Balance assertions generated by assigning to balanceN are of the simple +\f[C]=\f[R] type by default, which is a single-commodity, +subaccount-excluding assertion. +You may find the subaccount-including variants more useful, eg if you +have created some virtual subaccounts of checking to help with +budgeting. +You can select a different type of assertion with the +\f[C]balance-type\f[R] rule: +.IP +.nf +\f[C] +# balance assertions will consider all commodities and all subaccounts +balance-type ==* +\f[R] +.fi +.PP +Here are the balance assertion types for quick reference: +.IP +.nf +\f[C] += single commodity, exclude subaccounts +=* single commodity, include subaccounts +== multi commodity, exclude subaccounts +==* multi commodity, include subaccounts +\f[R] +.fi .SH TIPS +.SS Rapid feedback +.PP +It\[aq]s a good idea to get rapid feedback while +creating/troubleshooting CSV rules. +Here\[aq]s a good way, using entr from http://eradman.com/entrproject : +.IP +.nf +\f[C] +$ ls foo.csv* | entr bash -c \[aq]echo ----; hledger -f foo.csv print desc:SOMEDESC\[aq] +\f[R] +.fi +.PP +A desc: query (eg) is used to select just one, or a few, transactions of +interest. +\[dq]bash -c\[dq] is used to run multiple commands, so we can echo a +separator each time the command re-runs, making it easier to read the +output. .SS Valid CSV .PP hledger accepts CSV conforming to RFC 4180. @@ -744,17 +793,27 @@ they must be double quotes (not single quotes) spaces outside the quotes are not allowed .SS Other separator characters .PP -With the \f[C]--separator \[aq]CHAR\[aq]\f[R] option (experimental), -hledger will expect the separator to be CHAR instead of a comma. -Ie it will read other \[dq]Character Separated Values\[dq] formats, such -as TSV (Tab Separated Values). -Note: on the command line, use a real tab character in quotes, not Eg: +You can use the \f[C]--separator \[aq]CHAR\[aq]\f[R] command line option +(experimental) to read other kinds of character-separated data. +Eg to read SSV (Semicolon Separated Values), use: +.IP +.nf +\f[C] +$ hledger -f foo.tsv --separator \[aq];\[aq] print +\f[R] +.fi +.PP +Note the semicolon is quoted because it\[aq]s a special shell character. +.PP +To read TSV (Tab Separated Values), use: .IP .nf \f[C] $ hledger -f foo.tsv --separator \[aq] \[aq] print \f[R] .fi +.PP +Note, that\[aq]s a real tab character in quotes, not \f[C]\[rs]t\f[R]. .SS Reading multiple CSV files .PP If you use multiple \f[C]-f\f[R] options to read multiple CSV files at diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index 5ef4e7429..ce7ea41f1 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -1,4 +1,4 @@ -This is hledger_csv.info, produced by makeinfo version 6.5 from stdin. +This is hledger_csv.info, produced by makeinfo version 6.7 from stdin.  File: hledger_csv.info, Node: Top, Next: EXAMPLES, Up: (dir) @@ -376,6 +376,7 @@ Blank lines and lines beginning with '#' or ';' are ignored. * date-format:: * newest-first:: * include:: +* balance-type::  File: hledger_csv.info, Node: skip, Next: fields, Up: CSV RULES @@ -421,6 +422,9 @@ fields date, description, , amount, , , somefield, anotherfield can be left unnamed. Currently there must be least two items (there must be at least one comma). + Note, always use comma in the fields list, even if your CSV uses +another separator character. + Here are the standard hledger field/pseudo-field names. For more about the transaction parts they refer to, see the manual for hledger's journal format. @@ -466,7 +470,8 @@ indicating an unbalanced posting.) affects ALL postings. 'balanceN' sets a balance assertion amount (or if the posting amount -is left empty, a balance assignment). +is left empty, a balance assignment). You may need to adjust this with +the 'balance-type' rule. Finally, 'commentN' sets a comment on the Nth posting. Comments can also contain tags, as usual. @@ -625,7 +630,7 @@ oldest first or newest first. But if all of the following are true: newest-first  -File: hledger_csv.info, Node: include, Prev: newest-first, Up: CSV RULES +File: hledger_csv.info, Node: include, Next: balance-type, Prev: newest-first, Up: CSV RULES 2.8 'include' ============= @@ -647,6 +652,29 @@ account2 expenses:misc ## common rules include categorisation.rules + +File: hledger_csv.info, Node: balance-type, Prev: include, Up: CSV RULES + +2.9 'balance-type' +================== + +Balance assertions generated by assigning to balanceN are of the simple +'=' type by default, which is a single-commodity, subaccount-excluding +assertion. You may find the subaccount-including variants more useful, +eg if you have created some virtual subaccounts of checking to help with +budgeting. You can select a different type of assertion with the +'balance-type' rule: + +# balance assertions will consider all commodities and all subaccounts +balance-type ==* + + Here are the balance assertion types for quick reference: + += single commodity, exclude subaccounts +=* single commodity, include subaccounts +== multi commodity, exclude subaccounts +==* multi commodity, include subaccounts +  File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top @@ -655,6 +683,7 @@ File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top * Menu: +* Rapid feedback:: * Valid CSV:: * Other separator characters:: * Reading multiple CSV files:: @@ -666,9 +695,26 @@ File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top * How CSV rules are evaluated::  -File: hledger_csv.info, Node: Valid CSV, Next: Other separator characters, Up: TIPS +File: hledger_csv.info, Node: Rapid feedback, Next: Valid CSV, Up: TIPS -3.1 Valid CSV +3.1 Rapid feedback +================== + +It's a good idea to get rapid feedback while creating/troubleshooting +CSV rules. Here's a good way, using entr from +http://eradman.com/entrproject : + +$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' + + A desc: query (eg) is used to select just one, or a few, transactions +of interest. "bash -c" is used to run multiple commands, so we can echo +a separator each time the command re-runs, making it easier to read the +output. + + +File: hledger_csv.info, Node: Valid CSV, Next: Other separator characters, Prev: Rapid feedback, Up: TIPS + +3.2 Valid CSV ============= hledger accepts CSV conforming to RFC 4180. When CSV values are @@ -680,21 +726,27 @@ enclosed in quotes, note:  File: hledger_csv.info, Node: Other separator characters, Next: Reading multiple CSV files, Prev: Valid CSV, Up: TIPS -3.2 Other separator characters +3.3 Other separator characters ============================== -With the '--separator 'CHAR'' option (experimental), hledger will expect -the separator to be CHAR instead of a comma. Ie it will read other -"Character Separated Values" formats, such as TSV (Tab Separated -Values). Note: on the command line, use a real tab character in quotes, -not +You can use the '--separator 'CHAR'' command line option (experimental) +to read other kinds of character-separated data. Eg to read SSV +(Semicolon Separated Values), use: + +$ hledger -f foo.tsv --separator ';' print + + Note the semicolon is quoted because it's a special shell character. + + To read TSV (Tab Separated Values), use: $ hledger -f foo.tsv --separator ' ' print + Note, that's a real tab character in quotes, not '\t'. +  File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Other separator characters, Up: TIPS -3.3 Reading multiple CSV files +3.4 Reading multiple CSV files ============================== If you use multiple '-f' options to read multiple CSV files at once, @@ -705,7 +757,7 @@ used for all the CSV files.  File: hledger_csv.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: TIPS -3.4 Valid transactions +3.5 Valid transactions ====================== After reading a CSV file, hledger post-processes and validates the @@ -724,7 +776,7 @@ $ hledger -f file.csv print | hledger -f- print  File: hledger_csv.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: TIPS -3.5 Deduplicating, importing +3.6 Deduplicating, importing ============================ When you download a CSV file periodically, eg to get your latest bank @@ -754,7 +806,7 @@ CSV data. See:  File: hledger_csv.info, Node: Setting amounts, Next: Setting currency/commodity, Prev: Deduplicating importing, Up: TIPS -3.6 Setting amounts +3.7 Setting amounts =================== A posting amount can be set in one of these ways: @@ -783,7 +835,7 @@ A posting amount can be set in one of these ways:  File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing other fields, Prev: Setting amounts, Up: TIPS -3.7 Setting currency/commodity +3.8 Setting currency/commodity ============================== If the currency/commodity symbol is included in the CSV's amount @@ -810,7 +862,7 @@ field(s), you don't have to do anything special.  File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: TIPS -3.8 Referencing other fields +3.9 Referencing other fields ============================ In field assignments, you can interpolate only CSV fields, not hledger @@ -847,8 +899,8 @@ if something  File: hledger_csv.info, Node: How CSV rules are evaluated, Prev: Referencing other fields, Up: TIPS -3.9 How CSV rules are evaluated -=============================== +3.10 How CSV rules are evaluated +================================ Here's how to think of CSV rules being evaluated (if you really need to). First, @@ -900,45 +952,54 @@ Node: Paypal6438 Ref: #paypal6532 Node: CSV RULES14415 Ref: #csv-rules14524 -Node: skip14769 -Ref: #skip14862 -Node: fields15237 -Ref: #fields15359 -Node: Transaction field names16426 -Ref: #transaction-field-names16586 -Node: Posting field names16697 -Ref: #posting-field-names16849 -Node: field assignment18081 -Ref: #field-assignment18217 -Node: if19035 -Ref: #if19144 -Node: end20860 -Ref: #end20966 -Node: date-format21190 -Ref: #date-format21322 -Node: newest-first22071 -Ref: #newest-first22209 -Node: include22892 -Ref: #include23000 -Node: TIPS23444 -Ref: #tips23526 -Node: Valid CSV23775 -Ref: #valid-csv23894 -Node: Other separator characters24086 -Ref: #other-separator-characters24274 -Node: Reading multiple CSV files24603 -Ref: #reading-multiple-csv-files24800 -Node: Valid transactions25041 -Ref: #valid-transactions25219 -Node: Deduplicating importing25847 -Ref: #deduplicating-importing26026 -Node: Setting amounts27059 -Ref: #setting-amounts27228 -Node: Setting currency/commodity28214 -Ref: #setting-currencycommodity28406 -Node: Referencing other fields29209 -Ref: #referencing-other-fields29409 -Node: How CSV rules are evaluated30306 -Ref: #how-csv-rules-are-evaluated30477 +Node: skip14786 +Ref: #skip14879 +Node: fields15254 +Ref: #fields15376 +Node: Transaction field names16541 +Ref: #transaction-field-names16701 +Node: Posting field names16812 +Ref: #posting-field-names16964 +Node: field assignment18255 +Ref: #field-assignment18391 +Node: if19209 +Ref: #if19318 +Node: end21034 +Ref: #end21140 +Node: date-format21364 +Ref: #date-format21496 +Node: newest-first22245 +Ref: #newest-first22383 +Node: include23066 +Ref: #include23195 +Node: balance-type23639 +Ref: #balance-type23757 +Node: TIPS24457 +Ref: #tips24539 +Node: Rapid feedback24807 +Ref: #rapid-feedback24924 +Node: Valid CSV25384 +Ref: #valid-csv25526 +Node: Other separator characters25718 +Ref: #other-separator-characters25906 +Node: Reading multiple CSV files26345 +Ref: #reading-multiple-csv-files26542 +Node: Valid transactions26783 +Ref: #valid-transactions26961 +Node: Deduplicating importing27589 +Ref: #deduplicating-importing27768 +Node: Setting amounts28801 +Ref: #setting-amounts28970 +Node: Setting currency/commodity29956 +Ref: #setting-currencycommodity30148 +Node: Referencing other fields30951 +Ref: #referencing-other-fields31151 +Node: How CSV rules are evaluated32048 +Ref: #how-csv-rules-are-evaluated32221  End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 38e090b02..4840b8373 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -366,6 +366,9 @@ CSV RULES can be left unnamed. Currently there must be least two items (there must be at least one comma). + Note, always use comma in the fields list, even if your CSV uses an- + other separator character. + Here are the standard hledger field/pseudo-field names. For more about the transaction parts they refer to, see the manual for hledger's jour- nal format. @@ -375,28 +378,29 @@ CSV RULES transaction's first line. Posting field names - accountN, where N is 1 to 9, generates a posting, with that account - name. Most often there are two postings, so you'll want to set ac- + accountN, where N is 1 to 9, generates a posting, with that account + name. Most often there are two postings, so you'll want to set ac- count1 and account2. If a posting's account name is left unset but its amount is set, a default account name will be chosen (like expenses:un- known or income:unknown). - amountN sets posting N's amount. Or, amount with no N sets posting - 1's. If the CSV has debits and credits in separate fields, use - amountN-in and amountN-out instead. Or amount-in and amount-out with + amountN sets posting N's amount. Or, amount with no N sets posting + 1's. If the CSV has debits and credits in separate fields, use + amountN-in and amountN-out instead. Or amount-in and amount-out with no N for posting 1. - For convenience and backwards compatibility, if you set the amount of - posting 1 only, a second posting with the negative amount will be gen- - erated automatically. (Unless the account name is parenthesised indi- + For convenience and backwards compatibility, if you set the amount of + posting 1 only, a second posting with the negative amount will be gen- + erated automatically. (Unless the account name is parenthesised indi- cating an unbalanced posting.) - If the CSV has the currency symbol in a separate field, you can use - currencyN to prepend it to posting N's amount. currency with no N af- + If the CSV has the currency symbol in a separate field, you can use + currencyN to prepend it to posting N's amount. currency with no N af- fects ALL postings. - balanceN sets a balance assertion amount (or if the posting amount is - left empty, a balance assignment). + balanceN sets a balance assertion amount (or if the posting amount is + left empty, a balance assignment). You may need to adjust this with + the balance-type rule. Finally, commentN sets a comment on the Nth posting. Comments can also contain tags, as usual. @@ -551,7 +555,37 @@ CSV RULES ## common rules include categorisation.rules + balance-type + Balance assertions generated by assigning to balanceN are of the simple + = type by default, which is a single-commodity, subaccount-excluding + assertion. You may find the subaccount-including variants more useful, + eg if you have created some virtual subaccounts of checking to help + with budgeting. You can select a different type of assertion with the + balance-type rule: + + # balance assertions will consider all commodities and all subaccounts + balance-type ==* + + Here are the balance assertion types for quick reference: + + = single commodity, exclude subaccounts + =* single commodity, include subaccounts + == multi commodity, exclude subaccounts + ==* multi commodity, include subaccounts + TIPS + Rapid feedback + It's a good idea to get rapid feedback while creating/troubleshooting + CSV rules. Here's a good way, using entr from http://eradman.com/entr- + project : + + $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' + + A desc: query (eg) is used to select just one, or a few, transactions + of interest. "bash -c" is used to run multiple commands, so we can + echo a separator each time the command re-runs, making it easier to + read the output. + Valid CSV hledger accepts CSV conforming to RFC 4180. When CSV values are en- closed in quotes, note: @@ -561,14 +595,20 @@ TIPS o spaces outside the quotes are not allowed Other separator characters - With the --separator 'CHAR' option (experimental), hledger will expect - the separator to be CHAR instead of a comma. Ie it will read other - "Character Separated Values" formats, such as TSV (Tab Separated Val- - ues). Note: on the command line, use a real tab character in quotes, - not Eg: + You can use the --separator 'CHAR' command line option (experimental) + to read other kinds of character-separated data. Eg to read SSV (Semi- + colon Separated Values), use: + + $ hledger -f foo.tsv --separator ';' print + + Note the semicolon is quoted because it's a special shell character. + + To read TSV (Tab Separated Values), use: $ hledger -f foo.tsv --separator ' ' print + Note, that's a real tab character in quotes, not \t. + Reading multiple CSV files If you use multiple -f options to read multiple CSV files at once, hledger will look for a correspondingly-named rules file for each CSV diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index d5617149b..d8e1234ba 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -533,6 +533,7 @@ reconciled balances while cleaning up old entries. You can disable them temporarily with the \f[C]-I/--ignore-assertions\f[R] flag, which can be useful for troubleshooting or for reading Ledger files. +(Note: this flag currently does not disable balance assignments, below). .SS Assertions and ordering .PP hledger sorts an account\[aq]s postings and assertions first by date and diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index 7e7a0dddf..ac13bf1f7 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -1,4 +1,4 @@ -This is hledger_journal.info, produced by makeinfo version 6.5 from +This is hledger_journal.info, produced by makeinfo version 6.7 from stdin.  @@ -500,7 +500,8 @@ assertions and report an error if any of them fail. Balance assertions can protect you from, eg, inadvertently disrupting reconciled balances while cleaning up old entries. You can disable them temporarily with the '-I/--ignore-assertions' flag, which can be useful for -troubleshooting or for reading Ledger files. +troubleshooting or for reading Ledger files. (Note: this flag currently +does not disable balance assignments, below). * Menu: @@ -1779,87 +1780,92 @@ Node: Virtual Postings15303 Ref: #virtual-postings15462 Node: Balance Assertions16682 Ref: #balance-assertions16857 -Node: Assertions and ordering17816 -Ref: #assertions-and-ordering18002 -Node: Assertions and included files18702 -Ref: #assertions-and-included-files18943 -Node: Assertions and multiple -f options19276 -Ref: #assertions-and-multiple--f-options19530 -Node: Assertions and commodities19662 -Ref: #assertions-and-commodities19892 -Node: Assertions and prices21048 -Ref: #assertions-and-prices21260 -Node: Assertions and subaccounts21700 -Ref: #assertions-and-subaccounts21927 -Node: Assertions and virtual postings22251 -Ref: #assertions-and-virtual-postings22491 -Node: Assertions and precision22633 -Ref: #assertions-and-precision22824 -Node: Balance Assignments23091 -Ref: #balance-assignments23272 -Node: Balance assignments and prices24437 -Ref: #balance-assignments-and-prices24609 -Node: Transaction prices24833 -Ref: #transaction-prices25002 -Node: Comments27268 -Ref: #comments27402 -Node: Tags28572 -Ref: #tags28690 -Node: Directives30083 -Ref: #directives30226 -Node: Comment blocks35834 -Ref: #comment-blocks35979 -Node: Including other files36155 -Ref: #including-other-files36335 -Node: Default year36743 -Ref: #default-year36912 -Node: Declaring commodities37319 -Ref: #declaring-commodities37502 -Node: Default commodity39163 -Ref: #default-commodity39339 -Node: Market prices39973 -Ref: #market-prices40138 -Node: Declaring accounts40979 -Ref: #declaring-accounts41155 -Node: Account comments42080 -Ref: #account-comments42243 -Node: Account subdirectives42638 -Ref: #account-subdirectives42833 -Node: Account types43146 -Ref: #account-types43330 -Node: Account display order44972 -Ref: #account-display-order45142 -Node: Rewriting accounts46271 -Ref: #rewriting-accounts46456 -Node: Basic aliases47182 -Ref: #basic-aliases47328 -Node: Regex aliases48032 -Ref: #regex-aliases48204 -Node: Combining aliases48922 -Ref: #combining-aliases49100 -Node: end aliases50376 -Ref: #end-aliases50524 -Node: Default parent account50625 -Ref: #default-parent-account50791 -Node: Periodic transactions51675 -Ref: #periodic-transactions51873 -Node: Periodic rule syntax53745 -Ref: #periodic-rule-syntax53951 -Node: Two spaces between period expression and description!54655 -Ref: #two-spaces-between-period-expression-and-description54974 -Node: Forecasting with periodic transactions55658 -Ref: #forecasting-with-periodic-transactions55963 -Node: Budgeting with periodic transactions57989 -Ref: #budgeting-with-periodic-transactions58228 -Node: Auto postings / transaction modifiers58677 -Ref: #auto-postings-transaction-modifiers58888 -Node: Auto postings and dates61117 -Ref: #auto-postings-and-dates61374 -Node: Auto postings and transaction balancing / inferred amounts / balance assertions61549 -Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61924 -Node: Auto posting tags62302 -Ref: #auto-posting-tags62541 -Node: EDITOR SUPPORT63206 -Ref: #editor-support63324 +Node: Assertions and ordering17890 +Ref: #assertions-and-ordering18076 +Node: Assertions and included files18776 +Ref: #assertions-and-included-files19017 +Node: Assertions and multiple -f options19350 +Ref: #assertions-and-multiple--f-options19604 +Node: Assertions and commodities19736 +Ref: #assertions-and-commodities19966 +Node: Assertions and prices21122 +Ref: #assertions-and-prices21334 +Node: Assertions and subaccounts21774 +Ref: #assertions-and-subaccounts22001 +Node: Assertions and virtual postings22325 +Ref: #assertions-and-virtual-postings22565 +Node: Assertions and precision22707 +Ref: #assertions-and-precision22898 +Node: Balance Assignments23165 +Ref: #balance-assignments23346 +Node: Balance assignments and prices24511 +Ref: #balance-assignments-and-prices24683 +Node: Transaction prices24907 +Ref: #transaction-prices25076 +Node: Comments27342 +Ref: #comments27476 +Node: Tags28646 +Ref: #tags28764 +Node: Directives30157 +Ref: #directives30300 +Node: Comment blocks35908 +Ref: #comment-blocks36053 +Node: Including other files36229 +Ref: #including-other-files36409 +Node: Default year36817 +Ref: #default-year36986 +Node: Declaring commodities37393 +Ref: #declaring-commodities37576 +Node: Default commodity39237 +Ref: #default-commodity39413 +Node: Market prices40047 +Ref: #market-prices40212 +Node: Declaring accounts41053 +Ref: #declaring-accounts41229 +Node: Account comments42154 +Ref: #account-comments42317 +Node: Account subdirectives42712 +Ref: #account-subdirectives42907 +Node: Account types43220 +Ref: #account-types43404 +Node: Account display order45046 +Ref: #account-display-order45216 +Node: Rewriting accounts46345 +Ref: #rewriting-accounts46530 +Node: Basic aliases47256 +Ref: #basic-aliases47402 +Node: Regex aliases48106 +Ref: #regex-aliases48278 +Node: Combining aliases48996 +Ref: #combining-aliases49174 +Node: end aliases50450 +Ref: #end-aliases50598 +Node: Default parent account50699 +Ref: #default-parent-account50865 +Node: Periodic transactions51749 +Ref: #periodic-transactions51947 +Node: Periodic rule syntax53819 +Ref: #periodic-rule-syntax54025 +Node: Two spaces between period expression and description!54729 +Ref: #two-spaces-between-period-expression-and-description55048 +Node: Forecasting with periodic transactions55732 +Ref: #forecasting-with-periodic-transactions56037 +Node: Budgeting with periodic transactions58063 +Ref: #budgeting-with-periodic-transactions58302 +Node: Auto postings / transaction modifiers58751 +Ref: #auto-postings-transaction-modifiers58962 +Node: Auto postings and dates61191 +Ref: #auto-postings-and-dates61448 +Node: Auto postings and transaction balancing / inferred amounts / balance assertions61623 +Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions61998 +Node: Auto posting tags62376 +Ref: #auto-posting-tags62615 +Node: EDITOR SUPPORT63280 +Ref: #editor-support63398  End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index 28decb5a5..4f2035f93 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -384,27 +384,28 @@ FILE FORMAT tect you from, eg, inadvertently disrupting reconciled balances while cleaning up old entries. You can disable them temporarily with the -I/--ignore-assertions flag, which can be useful for troubleshooting or - for reading Ledger files. + for reading Ledger files. (Note: this flag currently does not disable + balance assignments, below). Assertions and ordering - hledger sorts an account's postings and assertions first by date and - then (for postings on the same day) by parse order. Note this is dif- + hledger sorts an account's postings and assertions first by date and + then (for postings on the same day) by parse order. Note this is dif- ferent from Ledger, which sorts assertions only by parse order. (Also, - Ledger assertions do not see the accumulated effect of repeated post- + Ledger assertions do not see the accumulated effect of repeated post- ings to the same account within a transaction.) So, hledger balance assertions keep working if you reorder differently- - dated transactions within the journal. But if you reorder same-dated - transactions or postings, assertions might break and require updating. + dated transactions within the journal. But if you reorder same-dated + transactions or postings, assertions might break and require updating. This order dependence does bring an advantage: precise control over the order of postings and assertions within a day, so you can assert intra- day balances. Assertions and included files - With included files, things are a little more complicated. Including - preserves the ordering of postings and assertions. If you have multi- - ple postings to an account on the same day, split across different - files, and you also want to assert the account's balance on the same + With included files, things are a little more complicated. Including + preserves the ordering of postings and assertions. If you have multi- + ple postings to an account on the same day, split across different + files, and you also want to assert the account's balance on the same day, you'll have to put the assertion in the right file. Assertions and multiple -f options @@ -412,8 +413,8 @@ FILE FORMAT -f options. Use include or concatenate the files instead. Assertions and commodities - The asserted balance must be a simple single-commodity amount, and in - fact the assertion checks only this commodity's balance within the + The asserted balance must be a simple single-commodity amount, and in + fact the assertion checks only this commodity's balance within the (possibly multi-commodity) account balance. This is how assertions work in Ledger also. We could call this a "par- tial" balance assertion. @@ -421,7 +422,7 @@ FILE FORMAT To assert the balance of more than one commodity in an account, you can write multiple postings, each asserting one commodity's balance. - You can make a stronger "total" balance assertion by writing a double + You can make a stronger "total" balance assertion by writing a double equals sign (== EXPECTEDBALANCE). This asserts that there are no other unasserted commodities in the account (or, that their balance is 0). @@ -441,7 +442,7 @@ FILE FORMAT a 0 == $1 It's not yet possible to make a complete assertion about a balance that - has multiple commodities. One workaround is to isolate each commodity + has multiple commodities. One workaround is to isolate each commodity into its own subaccount: 2013/1/1 @@ -455,21 +456,21 @@ FILE FORMAT a:euro 0 == 1EUR Assertions and prices - Balance assertions ignore transaction prices, and should normally be + Balance assertions ignore transaction prices, and should normally be written without one: 2019/1/1 (a) $1 @ EUR1 = $1 - We do allow prices to be written there, however, and print shows them, - even though they don't affect whether the assertion passes or fails. - This is for backward compatibility (hledger's close command used to - generate balance assertions with prices), and because balance assign- + We do allow prices to be written there, however, and print shows them, + even though they don't affect whether the assertion passes or fails. + This is for backward compatibility (hledger's close command used to + generate balance assertions with prices), and because balance assign- ments do use them (see below). Assertions and subaccounts - The balance assertions above (= and ==) do not count the balance from - subaccounts; they check the account's exclusive balance only. You can + The balance assertions above (= and ==) do not count the balance from + subaccounts; they check the account's exclusive balance only. You can assert the balance including subaccounts by writing =* or ==*, eg: 2019/1/1 @@ -483,16 +484,16 @@ FILE FORMAT tual. They are not affected by the --real/-R flag or real: query. Assertions and precision - Balance assertions compare the exactly calculated amounts, which are - not always what is shown by reports. Eg a commodity directive may - limit the display precision, but this will not affect balance asser- + Balance assertions compare the exactly calculated amounts, which are + not always what is shown by reports. Eg a commodity directive may + limit the display precision, but this will not affect balance asser- tions. Balance assertion failure messages show exact amounts. Balance Assignments - Ledger-style balance assignments are also supported. These are like - balance assertions, but with no posting amount on the left side of the - equals sign; instead it is calculated automatically so as to satisfy - the assertion. This can be a convenience during data entry, eg when + Ledger-style balance assignments are also supported. These are like + balance assertions, but with no posting amount on the left side of the + equals sign; instead it is calculated automatically so as to satisfy + the assertion. This can be a convenience during data entry, eg when setting opening balances: ; starting a new journal, set asset account balances @@ -510,14 +511,14 @@ FILE FORMAT expenses:misc The calculated amount depends on the account's balance in the commodity - at that point (which depends on the previously-dated postings of the - commodity to that account since the last balance assertion or assign- + at that point (which depends on the previously-dated postings of the + commodity to that account since the last balance assertion or assign- ment). Note that using balance assignments makes your journal a little less explicit; to know the exact amount posted, you have to run hledger or do the calculations yourself, instead of just reading it. Balance assignments and prices - A transaction price in a balance assignment will cause the calculated + A transaction price in a balance assignment will cause the calculated amount to have that price attached: 2019/1/1 @@ -529,9 +530,9 @@ FILE FORMAT 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. @@ -560,7 +561,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: @@ -571,8 +572,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: @@ -586,13 +587,13 @@ 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 de- + You can attach comments to a transaction by writing them after the de- scription and/or indented on the following lines (before the postings). - Similarly, you can attach comments to an individual posting by writing + Similarly, you can attach comments to an individual posting by writing them after the amount and/or indented on the following lines. Transac- tion and posting comments must begin with a semicolon (;). @@ -617,24 +618,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 end + 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: @@ -648,65 +649,65 @@ 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, third- + 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 di- subdi- purpose can affect (as of + direc- end di- subdi- purpose can affect (as of tive rective rec- 2018/06) tives ------------------------------------------------------------------------------------ - account any document account names, de- all entries in all - text clare account types & dis- files, before or + account any document account names, de- all entries in all + text clare account types & dis- files, before or play order after alias end rewrite account names following in- aliases line/included en- - tries until end of + tries until end of current file or end directive - apply end apply prepend a common parent to following in- + apply end apply prepend a common parent to following in- account account account names line/included en- - tries until end of + tries until end of current file or end directive comment end com- ignore part of journal following in- ment line/included en- - tries until end of + tries until end of current file or end directive - commod- format declare a commodity and its number notation: + commod- format declare a commodity and its number notation: ity 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 @@ -714,26 +715,24 @@ FILE FORMAT include include entries/directives what the included from another file directives affect P declare a market price for a amounts of that - commodity commodity in re- - ports, when -V is + commodity commodity in re- + ports, when -V is used - Y declare a year for yearless following in- + Y declare a year for yearless following in- dates line/included en- - tries until end of + tries until end of current file And some definitions: 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) - - directive which entries and (when there are multiple files) which files scope are affected by a directive @@ -741,34 +740,34 @@ 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- + 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 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 @@ -790,18 +789,18 @@ 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 to expect when parsing input - - useful to disambiguate international number formats in your data. + - 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 format 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. @@ -814,8 +813,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 @@ -828,14 +827,14 @@ 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 (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 @@ -850,9 +849,9 @@ FILE FORMAT a decimal point. 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: @@ -863,16 +862,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 @@ -882,20 +881,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 @@ -913,7 +912,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 @@ -926,18 +925,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 +947,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 @@ -959,7 +958,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 +969,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,16 +992,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). @@ -1021,14 +1020,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 @@ -1036,49 +1035,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: @@ -1089,22 +1088,22 @@ 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. end aliases - You can clear (forget) all currently defined aliases with the end + 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 ac- - counts within a section of the journal. Use the apply account and end + You can specify a parent account which will be prepended to all ac- + counts within a section of the journal. Use the apply account and end apply account directives like so: apply account home @@ -1121,7 +1120,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 @@ -1130,50 +1129,50 @@ 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 al- - low hledger to generate temporary future transactions to help with - forecasting, so you don't have to write out each one in the journal, - and it's easy to try out different forecasts. Secondly, they are also + Periodic transaction rules describe transactions that recur. They al- + low hledger to generate temporary future transactions to help with + forecasting, so you don't have to write out each one in the journal, + and it's easy to try out different forecasts. Secondly, they are also used to define the budgets shown in budget reports. - Periodic transactions can be a little tricky, so before you use them, + Periodic transactions can be a little tricky, so before you use them, read this whole section - or at least these tips: - 1. Two spaces accidentally added or omitted will cause you trouble - + 1. Two spaces accidentally added or omitted will cause you trouble - read about this below. - 2. For troubleshooting, show the generated transactions with hledger - print --forecast tag:generated or hledger register --forecast + 2. For troubleshooting, show the generated transactions with hledger + print --forecast tag:generated or hledger register --forecast tag:generated. - 3. Forecasted transactions will begin only after the last non-fore- + 3. Forecasted transactions will begin only after the last non-fore- casted transaction's date. - 4. Forecasted transactions will end 6 months from today, by default. + 4. Forecasted transactions will end 6 months from today, by default. See below for the exact start/end rules. - 5. period expressions can be tricky. Their documentation needs im- + 5. period expressions can be tricky. Their documentation needs im- provement, but is worth studying. - 6. Some period expressions with a repeating interval must begin on a - natural boundary of that interval. Eg in weekly from DATE, DATE - must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an + 6. Some period expressions with a repeating interval must begin on a + natural boundary of that interval. Eg in weekly from DATE, DATE + must be a monday. ~ weekly from 2019/10/1 (a tuesday) will give an error. 7. Other period expressions with an interval are automatically expanded - to cover a whole number of that interval. (This is done to improve + to cover a whole number of that interval. (This is done to improve reports, but it also affects periodic transactions. Yes, it's a bit - inconsistent with the above.) Eg: ~ every 10th day of month from - 2020/01, which is equivalent to ~ every 10th day of month from + inconsistent with the above.) Eg: ~ every 10th day of month from + 2020/01, which is equivalent to ~ every 10th day of month from 2020/01/01, will be adjusted to start on 2019/12/10. Periodic rule syntax @@ -1185,17 +1184,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 monthly from + 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 between period expression and description! - 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: @@ -1209,82 +1208,82 @@ FILE FORMAT So, - o Do write two spaces between your period expression and your transac- + o Do write two spaces between your period expression and your transac- tion description, if any. - o Don't accidentally write two spaces in the middle of your period ex- + o Don't accidentally write two spaces in the middle of your period ex- pression. Forecasting with periodic transactions - With the --forecast flag, each periodic transaction rule generates fu- - ture transactions recurring at the specified interval. These are not - saved in the journal, but appear in all reports. They will look like + With the --forecast flag, each periodic transaction rule generates fu- + ture 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: - o generated-transaction:~ PERIODICEXPR - shows that this was generated + o generated-transaction:~ PERIODICEXPR - shows that this was generated by a periodic transaction rule, and the period - There is also a hidden tag, with an underscore prefix, which does not + There is also a hidden tag, with an underscore prefix, which does not appear in hledger's output: o _generated-transaction:~ PERIODICEXPR - This can be used to match transactions generated "just now", rather + This can be used to match transactions generated "just now", rather than generated in the past and saved to the journal. - 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 Budgeting and Fore- + For more details, see: balance: Budget report and Budgeting and Fore- casting. Auto postings / transaction modifiers Transaction modifier rules, AKA auto posting rules, describe changes to - be applied automatically to certain matched transactions. Currently - just one kind of change is possible - adding extra postings, which we - call "automated postings" or just "auto postings". These rules become + be applied automatically to certain matched transactions. Currently + just one kind of change is possible - adding extra postings, which we + call "automated postings" or just "auto postings". These rules become active when you use the --auto flag. A transaction modifier rule looks much like a normal transaction except - the first line is an equals sign followed by a query that matches cer- - tain postings (mnemonic: = suggests matching). And each "posting" is + the first line is an equals sign followed by a query that matches cer- + tain postings (mnemonic: = suggests matching). And each "posting" is actually a posting-generating rule: = QUERY @@ -1292,20 +1291,20 @@ FILE FORMAT ACCT [AMT] ... - These posting-generating rules look like normal postings, except the + These posting-generating rules look 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. @@ -1345,20 +1344,20 @@ FILE FORMAT assets:checking $20 Auto postings and dates - A posting date (or secondary date) in the matched posting, or (taking - precedence) a posting date in the auto posting rule itself, will also + A posting date (or secondary date) in the matched posting, or (taking + precedence) a posting date in the auto posting rule itself, will also be used in the generated posting. Auto postings and transaction balancing / inferred amounts / balance asser- tions Currently, transaction modifiers are applied / auto postings are added: - o after missing amounts are inferred, and transactions are checked for + o after missing amounts are inferred, and transactions are checked for balancedness, o but before balance assertions are checked. - Note this means that journal entries must be balanced both before and + Note this means that journal entries must be balanced both before and after auto postings are added. This changed in hledger 1.12+; see #893 for background. @@ -1368,11 +1367,11 @@ FILE FORMAT o generated-posting:= QUERY - shows this was generated by an auto post- ing rule, and the query - o _generated-posting:= QUERY - a hidden tag, which does not appear in + o _generated-posting:= QUERY - a hidden tag, which does not appear in hledger's output. This can be used to match postings generated "just now", rather than generated in the past and saved to the journal. - Also, any transaction that has been changed by transaction modifier + Also, any transaction that has been changed by transaction modifier rules will have these tags added: o modified: - this transaction was modified @@ -1381,18 +1380,18 @@ FILE FORMAT tion was modified "just now". EDITOR SUPPORT - Helper modes exist for popular text editors, which make working with + Helper modes exist for popular text editors, which make working with journal files easier. They add colour, formatting, tab completion, and - helpful commands, and are quite recommended if you edit your journal - with a text editor. They include ledger-mode or hledger-mode for - Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and + helpful commands, and are quite recommended if you edit your journal + with a text editor. They include ledger-mode or hledger-mode for + Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and others. See the Editor configuration at hledger.org for the latest in- formation. 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) @@ -1406,7 +1405,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-lib/hledger_timeclock.5 b/hledger-lib/hledger_timeclock.5 index 33f16b986..a68fe419a 100644 --- a/hledger-lib/hledger_timeclock.5 +++ b/hledger-lib/hledger_timeclock.5 @@ -63,7 +63,7 @@ use emacs and the built-in timeclock.el, or the extended timeclock-x.el and perhaps the extras in ledgerutils.el .IP \[bu] 2 at the command line, use these bash aliases: -\f[C]shell alias ti=\[dq]echo i \[ga]date \[aq]+%Y-%m-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq] alias to=\[dq]echo o \[ga]date \[aq]+%Y-%m-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R] +\f[C]shell alias ti=\[dq]echo i \[ga]date \[aq]+%Y-%m-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq] alias to=\[dq]echo o \[ga]date \[aq]+%Y-%m-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R] .IP \[bu] 2 or use the old \f[C]ti\f[R] and \f[C]to\f[R] scripts in the ledger 2.x repository. diff --git a/hledger-lib/hledger_timeclock.info b/hledger-lib/hledger_timeclock.info index 7b78658a4..c6e6a33b0 100644 --- a/hledger-lib/hledger_timeclock.info +++ b/hledger-lib/hledger_timeclock.info @@ -1,4 +1,4 @@ -This is hledger_timeclock.info, produced by makeinfo version 6.5 from +This is hledger_timeclock.info, produced by makeinfo version 6.7 from stdin.  @@ -59,3 +59,8 @@ Tag Table: Node: Top78  End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/hledger-lib/hledger_timeclock.txt b/hledger-lib/hledger_timeclock.txt index 905bae5c8..3747caf62 100644 --- a/hledger-lib/hledger_timeclock.txt +++ b/hledger-lib/hledger_timeclock.txt @@ -45,9 +45,9 @@ DESCRIPTION o use emacs and the built-in timeclock.el, or the extended timeclock- x.el and perhaps the extras in ledgerutils.el - o at the command line, use these bash aliases: shell alias ti="echo i - `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date - '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" + o at the command line, use these bash aliases: shell alias ti="echo + i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o + `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" o or use the old ti and to scripts in the ledger 2.x repository. These rely on a "timeclock" executable which I think is just the ledger 2 diff --git a/hledger-lib/hledger_timedot.info b/hledger-lib/hledger_timedot.info index 573dfae73..f0219dc02 100644 --- a/hledger-lib/hledger_timedot.info +++ b/hledger-lib/hledger_timedot.info @@ -1,4 +1,4 @@ -This is hledger_timedot.info, produced by makeinfo version 6.5 from +This is hledger_timedot.info, produced by makeinfo version 6.7 from stdin.  @@ -115,3 +115,8 @@ Node: FILE FORMAT812 Ref: #file-format913  End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 index 30eac9f06..4ec9c4b3a 100644 --- a/hledger-ui/hledger-ui.1 +++ b/hledger-ui/hledger-ui.1 @@ -47,113 +47,114 @@ before options as shown above. Any QUERYARGS are interpreted as a hledger search query which filters the data. .TP -.B \f[C]--watch\f[R] +\f[B]\f[CB]--watch\f[B]\f[R] watch for data and date changes and reload automatically .TP -.B \f[C]--theme=default|terminal|greenterm\f[R] +\f[B]\f[CB]--theme=default|terminal|greenterm\f[B]\f[R] use this custom display theme .TP -.B \f[C]--register=ACCTREGEX\f[R] +\f[B]\f[CB]--register=ACCTREGEX\f[B]\f[R] start in the (first) matched account\[aq]s register screen .TP -.B \f[C]--change\f[R] +\f[B]\f[CB]--change\f[B]\f[R] show period balances (changes) at startup instead of historical balances .TP -.B \f[C]-F --flat\f[R] +\f[B]\f[CB]-F --flat\f[B]\f[R] show accounts as a list (default) .TP -.B \f[C]-T --tree\f[R] +\f[B]\f[CB]-T --tree\f[B]\f[R] show accounts as a tree .TP -.B \f[C]--future\f[R] +\f[B]\f[CB]--future\f[B]\f[R] show transactions dated later than today (normally hidden) .PP hledger input options: .TP -.B \f[C]-f FILE --file=FILE\f[R] +\f[B]\f[CB]-f FILE --file=FILE\f[B]\f[R] use a different input file. For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or \f[C]$HOME/.hledger.journal\f[R]) .TP -.B \f[C]--rules-file=RULESFILE\f[R] +\f[B]\f[CB]--rules-file=RULESFILE\f[B]\f[R] Conversion rules file to use when reading CSV (default: FILE.rules) .TP -.B \f[C]--separator=CHAR\f[R] +\f[B]\f[CB]--separator=CHAR\f[B]\f[R] Field separator to expect when reading CSV (default: \[aq],\[aq]) .TP -.B \f[C]--alias=OLD=NEW\f[R] +\f[B]\f[CB]--alias=OLD=NEW\f[B]\f[R] rename accounts named OLD to NEW .TP -.B \f[C]--anon\f[R] +\f[B]\f[CB]--anon\f[B]\f[R] anonymize accounts and payees .TP -.B \f[C]--pivot FIELDNAME\f[R] +\f[B]\f[CB]--pivot FIELDNAME\f[B]\f[R] use some other field or tag for the account name .TP -.B \f[C]-I --ignore-assertions\f[R] -ignore any failing balance assertions +\f[B]\f[CB]-I --ignore-assertions\f[B]\f[R] +disable balance assertion checks (note: does not disable balance +assignments) .PP hledger reporting options: .TP -.B \f[C]-b --begin=DATE\f[R] +\f[B]\f[CB]-b --begin=DATE\f[B]\f[R] include postings/txns on or after this date .TP -.B \f[C]-e --end=DATE\f[R] +\f[B]\f[CB]-e --end=DATE\f[B]\f[R] include postings/txns before this date .TP -.B \f[C]-D --daily\f[R] +\f[B]\f[CB]-D --daily\f[B]\f[R] multiperiod/multicolumn report by day .TP -.B \f[C]-W --weekly\f[R] +\f[B]\f[CB]-W --weekly\f[B]\f[R] multiperiod/multicolumn report by week .TP -.B \f[C]-M --monthly\f[R] +\f[B]\f[CB]-M --monthly\f[B]\f[R] multiperiod/multicolumn report by month .TP -.B \f[C]-Q --quarterly\f[R] +\f[B]\f[CB]-Q --quarterly\f[B]\f[R] multiperiod/multicolumn report by quarter .TP -.B \f[C]-Y --yearly\f[R] +\f[B]\f[CB]-Y --yearly\f[B]\f[R] multiperiod/multicolumn report by year .TP -.B \f[C]-p --period=PERIODEXP\f[R] +\f[B]\f[CB]-p --period=PERIODEXP\f[B]\f[R] set start date, end date, and/or reporting interval all at once using period expressions syntax .TP -.B \f[C]--date2\f[R] +\f[B]\f[CB]--date2\f[B]\f[R] match the secondary date instead (see command help for other effects) .TP -.B \f[C]-U --unmarked\f[R] +\f[B]\f[CB]-U --unmarked\f[B]\f[R] include only unmarked postings/txns (can combine with -P or -C) .TP -.B \f[C]-P --pending\f[R] +\f[B]\f[CB]-P --pending\f[B]\f[R] include only pending postings/txns .TP -.B \f[C]-C --cleared\f[R] +\f[B]\f[CB]-C --cleared\f[B]\f[R] include only cleared postings/txns .TP -.B \f[C]-R --real\f[R] +\f[B]\f[CB]-R --real\f[B]\f[R] include only non-virtual postings .TP -.B \f[C]-NUM --depth=NUM\f[R] +\f[B]\f[CB]-NUM --depth=NUM\f[B]\f[R] hide/aggregate accounts or postings more than NUM levels deep .TP -.B \f[C]-E --empty\f[R] +\f[B]\f[CB]-E --empty\f[B]\f[R] show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) .TP -.B \f[C]-B --cost\f[R] +\f[B]\f[CB]-B --cost\f[B]\f[R] convert amounts to their cost at transaction time (using the transaction price, if any) .TP -.B \f[C]-V --value\f[R] +\f[B]\f[CB]-V --value\f[B]\f[R] convert amounts to their market value on the report end date (using the most recent applicable market price, if any) .TP -.B \f[C]--auto\f[R] +\f[B]\f[CB]--auto\f[B]\f[R] apply automated posting rules to modify transactions. .TP -.B \f[C]--forecast\f[R] +\f[B]\f[CB]--forecast\f[B]\f[R] apply periodic transaction rules to generate future transactions, to 6 months from now or report end date. .PP @@ -164,13 +165,13 @@ Some reporting options can also be written as query arguments. .PP hledger help options: .TP -.B \f[C]-h --help\f[R] +\f[B]\f[CB]-h --help\f[B]\f[R] show general usage (or after COMMAND, command usage) .TP -.B \f[C]--version\f[R] +\f[B]\f[CB]--version\f[B]\f[R] show version .TP -.B \f[C]--debug[=N]\f[R] +\f[B]\f[CB]--debug[=N]\f[B]\f[R] show debug output (levels 1-9, default: 1) .PP A \[at]FILE argument will be expanded to the contents of FILE, which diff --git a/hledger-ui/hledger-ui.info b/hledger-ui/hledger-ui.info index 99da17aca..ef177782c 100644 --- a/hledger-ui/hledger-ui.info +++ b/hledger-ui/hledger-ui.info @@ -1,4 +1,4 @@ -This is hledger-ui.info, produced by makeinfo version 6.5 from stdin. +This is hledger-ui.info, produced by makeinfo version 6.7 from stdin.  File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir) @@ -89,7 +89,8 @@ the data. use some other field or tag for the account name '-I --ignore-assertions' - ignore any failing balance assertions + disable balance assertion checks (note: does not disable balance + assignments) hledger reporting options: @@ -425,17 +426,22 @@ Tag Table: Node: Top71 Node: OPTIONS1101 Ref: #options1198 -Node: KEYS4589 -Ref: #keys4684 -Node: SCREENS8991 -Ref: #screens9076 -Node: Accounts screen9166 -Ref: #accounts-screen9294 -Node: Register screen11510 -Ref: #register-screen11665 -Node: Transaction screen13661 -Ref: #transaction-screen13819 -Node: Error screen14689 -Ref: #error-screen14811 +Node: KEYS4634 +Ref: #keys4729 +Node: SCREENS9036 +Ref: #screens9121 +Node: Accounts screen9211 +Ref: #accounts-screen9339 +Node: Register screen11555 +Ref: #register-screen11710 +Node: Transaction screen13706 +Ref: #transaction-screen13864 +Node: Error screen14734 +Ref: #error-screen14856  End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/hledger-ui/hledger-ui.txt b/hledger-ui/hledger-ui.txt index 3cb237d08..8050a8e2a 100644 --- a/hledger-ui/hledger-ui.txt +++ b/hledger-ui/hledger-ui.txt @@ -87,7 +87,8 @@ OPTIONS use some other field or tag for the account name -I --ignore-assertions - ignore any failing balance assertions + disable balance assertion checks (note: does not disable balance + assignments) hledger reporting options: @@ -113,7 +114,7 @@ OPTIONS multiperiod/multicolumn report by year -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once + set start date, end date, and/or reporting interval all at once using period expressions syntax --date2 @@ -136,21 +137,21 @@ OPTIONS hide/aggregate accounts or postings more than NUM levels deep -E --empty - show items with zero amount, normally hidden (and vice-versa in + show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) -B --cost - convert amounts to their cost at transaction time (using the + convert amounts to their cost at transaction time (using the transaction price, if any) -V --value - convert amounts to their market value on the report end date + convert amounts to their market value on the report end date (using the most recent applicable market price, if any) --auto apply automated posting rules to modify transactions. --forecast - apply periodic transaction rules to generate future transac- + apply periodic transaction rules to generate future transac- tions, to 6 months from now or report end date. When a reporting option appears more than once in the command line, the @@ -170,138 +171,138 @@ OPTIONS show debug output (levels 1-9, default: 1) A @FILE argument will be expanded to the contents of FILE, which should - contain one command line option/argument per line. (To prevent this, + contain one command line option/argument per line. (To prevent this, insert a -- argument before.) KEYS - ? shows a help dialog listing all keys. (Some of these also appear in + ? shows a help dialog listing all keys. (Some of these also appear in the quick help at the bottom of each screen.) Press ? again (or ESCAPE, or LEFT) to close it. The following keys work on most screens: The cursor keys navigate: right (or enter) goes deeper, left returns to - the previous screen, up/down/page up/page down/home/end move up and - down through lists. Vi-style (h/j/k/l) and Emacs-style (CTRL-p/CTRL- - n/CTRL-f/CTRL-b) movement keys are also supported. A tip: movement - speed is limited by your keyboard repeat rate, to move faster you may - want to adjust it. (If you're on a mac, the Karabiner app is one way + the previous screen, up/down/page up/page down/home/end move up and + down through lists. Vi-style (h/j/k/l) and Emacs-style (CTRL-p/CTRL- + n/CTRL-f/CTRL-b) movement keys are also supported. A tip: movement + speed is limited by your keyboard repeat rate, to move faster you may + want to adjust it. (If you're on a mac, the Karabiner app is one way to do that.) - With shift pressed, the cursor keys adjust the report period, limiting - the transactions to be shown (by default, all are shown). shift- - down/up steps downward and upward through these standard report period - durations: year, quarter, month, week, day. Then, shift-left/right - moves to the previous/next period. t sets the report period to today. - With the --watch option, when viewing a "current" period (the current + With shift pressed, the cursor keys adjust the report period, limiting + the transactions to be shown (by default, all are shown). shift- + down/up steps downward and upward through these standard report period + durations: year, quarter, month, week, day. Then, shift-left/right + moves to the previous/next period. t sets the report period to today. + With the --watch option, when viewing a "current" period (the current day, week, month, quarter, or year), the period will move automatically to track the current date. To set a non-standard period, you can use / and a date: query. - / lets you set a general filter query limiting the data shown, using - the same query terms as in hledger and hledger-web. While editing the - query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set + / lets you set a general filter query limiting the data shown, using + the same query terms as in hledger and hledger-web. While editing the + query, you can use CTRL-a/e/d/k, BS, cursor keys; press ENTER to set it, or ESCAPEto cancel. There are also keys for quickly adjusting some - common filters like account depth and transaction status (see below). + common filters like account depth and transaction status (see below). BACKSPACE or DELETE removes all filters, showing all transactions. - As mentioned above, hledger-ui shows auto-generated periodic transac- - tions, and hides future transactions (auto-generated or not) by de- - fault. F toggles showing and hiding these future transactions. This - is similar to using a query like date:-tomorrow, but more convenient. + As mentioned above, hledger-ui shows auto-generated periodic transac- + tions, and hides future transactions (auto-generated or not) by de- + fault. F toggles showing and hiding these future transactions. This + is similar to using a query like date:-tomorrow, but more convenient. (experimental) - ESCAPE removes all filters and jumps back to the top screen. Or, it + ESCAPE removes all filters and jumps back to the top screen. Or, it cancels a minibuffer edit or help dialog in progress. CTRL-l redraws the screen and centers the selection if possible (selec- - tions near the top won't be centered, since we don't scroll above the + tions near the top won't be centered, since we don't scroll above the top). - g reloads from the data file(s) and updates the current screen and any - previous screens. (With large files, this could cause a noticeable + g reloads from the data file(s) and updates the current screen and any + previous screens. (With large files, this could cause a noticeable pause.) - I toggles balance assertion checking. Disabling balance assertions + I toggles balance assertion checking. Disabling balance assertions temporarily can be useful for troubleshooting. - a runs command-line hledger's add command, and reloads the updated + a runs command-line hledger's add command, and reloads the updated file. This allows some basic data entry. - A is like a, but runs the hledger-iadd tool, which provides a terminal - interface. This key will be available if hledger-iadd is installed in + A is like a, but runs the hledger-iadd tool, which provides a terminal + interface. This key will be available if hledger-iadd is installed in $PATH. - E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a "" - -nw) on the journal file. With some editors (emacs, vi), the cursor - will be positioned at the current transaction when invoked from the - register and transaction screens, and at the error location (if possi- + E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a "" + -nw) on the journal file. With some editors (emacs, vi), the cursor + will be positioned at the current transaction when invoked from the + register and transaction screens, and at the error location (if possi- ble) when invoked from the error screen. q quits the application. Experimental: - B toggles cost mode, showing amounts in their transaction price's com- + B toggles cost mode, showing amounts in their transaction price's com- modity (like toggling the -B/--cost flag). - V toggles value mode, showing amounts' current market value in their - default valuation commodity (like toggling the -V/--market flag). - Note, "current market value" means the value on the report end date if - specified, otherwise today. To see the value on another date, you can - temporarily set that as the report end date. Eg: to see a transaction - as it was valued on july 30, go to the accounts or register screen, + V toggles value mode, showing amounts' current market value in their + default valuation commodity (like toggling the -V/--market flag). + Note, "current market value" means the value on the report end date if + specified, otherwise today. To see the value on another date, you can + temporarily set that as the report end date. Eg: to see a transaction + as it was valued on july 30, go to the accounts or register screen, press /, and add date:-7/30 to the query. At most one of cost or value mode can be active at once. - There's not yet any visual reminder when cost or value mode is active; + There's not yet any visual reminder when cost or value mode is active; for now pressing B B V should reliably reset to normal mode. - With --watch active, if you save an edit to the journal file while + With --watch active, if you save an edit to the journal file while viewing the transaction screen in cost or value mode, the B/V keys will - stop working. To work around, press g to force a manual reload, or + stop working. To work around, press g to force a manual reload, or exit the transaction screen. Additional screen-specific keys are described below. SCREENS Accounts screen - This is normally the first screen displayed. It lists accounts and - their balances, like hledger's balance command. By default, it shows - all accounts and their latest ending balances (including the balances - of subaccounts). if you specify a query on the command line, it shows + This is normally the first screen displayed. It lists accounts and + their balances, like hledger's balance command. By default, it shows + all accounts and their latest ending balances (including the balances + of subaccounts). if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. - Account names are shown as a flat list by default. Press T to toggle - tree mode. In flat mode, account balances are exclusive of subac- - counts, except where subaccounts are hidden by a depth limit (see be- + Account names are shown as a flat list by default. Press T to toggle + tree mode. In flat mode, account balances are exclusive of subac- + counts, except where subaccounts are hidden by a depth limit (see be- low). In tree mode, all account balances are inclusive of subaccounts. - To see less detail, press a number key, 1 to 9, to set a depth limit. + To see less detail, press a number key, 1 to 9, to set a depth limit. Or use - to decrease and +/= to increase the depth limit. 0 shows even - less detail, collapsing all accounts to a single total. To remove the + less detail, collapsing all accounts to a single total. To remove the depth limit, set it higher than the maximum account depth, or press ES- CAPE. H toggles between showing historical balances or period balances. His- - torical balances (the default) are ending balances at the end of the - report period, taking into account all transactions before that date - (filtered by the filter query if any), including transactions before - the start of the report period. In other words, historical balances - are what you would see on a bank statement for that account (unless - disturbed by a filter query). Period balances ignore transactions be- - fore the report start date, so they show the change in balance during + torical balances (the default) are ending balances at the end of the + report period, taking into account all transactions before that date + (filtered by the filter query if any), including transactions before + the start of the report period. In other words, historical balances + are what you would see on a bank statement for that account (unless + disturbed by a filter query). Period balances ignore transactions be- + fore the report start date, so they show the change in balance during the report period. They are more useful eg when viewing a time log. U toggles filtering by unmarked status, including or excluding unmarked postings in the balances. Similarly, P toggles pending postings, and C - toggles cleared postings. (By default, balances include all postings; - if you activate one or two status filters, only those postings are in- + toggles cleared postings. (By default, balances include all postings; + if you activate one or two status filters, only those postings are in- cluded; and if you activate all three, the filter is removed.) R toggles real mode, in which virtual postings are ignored. - Z toggles nonzero mode, in which only accounts with nonzero balances - are shown (hledger-ui shows zero items by default, unlike command-line + Z toggles nonzero mode, in which only accounts with nonzero balances + are shown (hledger-ui shows zero items by default, unlike command-line hledger). Press right or enter to view an account's transactions register. @@ -310,63 +311,63 @@ SCREENS This screen shows the transactions affecting a particular account, like a check register. Each line represents one transaction and shows: - o the other account(s) involved, in abbreviated form. (If there are - both real and virtual postings, it shows only the accounts affected + o the other account(s) involved, in abbreviated form. (If there are + both real and virtual postings, it shows only the accounts affected by real postings.) - o the overall change to the current account's balance; positive for an + o the overall change to the current account's balance; positive for an inflow to this account, negative for an outflow. o the running historical total or period total for the current account, - after the transaction. This can be toggled with H. Similar to the - accounts screen, the historical total is affected by transactions - (filtered by the filter query) before the report start date, while + after the transaction. This can be toggled with H. Similar to the + accounts screen, the historical total is affected by transactions + (filtered by the filter query) before the report start date, while the period total is not. If the historical total is not disturbed by - a filter query, it will be the running historical balance you would + a filter query, it will be the running historical balance you would see on a bank register for the current account. - Transactions affecting this account's subaccounts will be included in + Transactions affecting this account's subaccounts will be included in the register if the accounts screen is in tree mode, or if it's in flat - mode but this account has subaccounts which are not shown due to a - depth limit. In other words, the register always shows the transac- + mode but this account has subaccounts which are not shown due to a + depth limit. In other words, the register always shows the transac- tions contributing to the balance shown on the accounts screen. Tree mode/flat mode can be toggled with T here also. - U toggles filtering by unmarked status, showing or hiding unmarked + U toggles filtering by unmarked status, showing or hiding unmarked 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- + 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.) R toggles real mode, in which virtual postings are ignored. - Z toggles nonzero mode, in which only transactions posting a nonzero - change are shown (hledger-ui shows zero items by default, unlike com- + Z toggles nonzero mode, in which only transactions posting a nonzero + change are shown (hledger-ui shows zero items by default, unlike com- mand-line hledger). Press right (or enter) to view the selected transaction in detail. Transaction screen - This screen shows a single transaction, as a general journal entry, - similar to hledger's print command and journal format (hledger_jour- + This screen shows a single transaction, as a general journal entry, + similar to hledger's print command and journal format (hledger_jour- nal(5)). - The transaction's date(s) and any cleared flag, transaction code, de- - scription, comments, along with all of its account postings are shown. - Simple transactions have two postings, but there can be more (or in + The transaction's date(s) and any cleared flag, transaction code, de- + scription, comments, along with all of its account postings are shown. + Simple transactions have two postings, but there can be more (or in certain cases, fewer). - up and down will step through all transactions listed in the previous - account register screen. In the title bar, the numbers in parentheses - show your position within that account register. They will vary de- + up and down will step through all transactions listed in the previous + account register screen. In the title bar, the numbers in parentheses + show your position within that account register. They will vary de- pending on which account register you came from (remember most transac- - tions appear in multiple account registers). The #N number preceding + tions appear in multiple account registers). The #N number preceding them is the transaction's position within the complete unfiltered jour- nal, which is a more stable id (at least until the next reload). Error screen - This screen will appear if there is a problem, such as a parse error, - when you press g to reload. Once you have fixed the problem, press g + This screen will appear if there is a problem, such as a parse error, + when you press g to reload. Once you have fixed the problem, press g again to reload and resume normal operation. (Or, you can press escape to cancel the reload attempt.) @@ -374,17 +375,17 @@ ENVIRONMENT COLUMNS The screen width to use. 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 options with -- when invoked from hledger is awk- + The need to precede options with -- when invoked from hledger is awk- ward. -f- doesn't work (hledger-ui can't read from stdin). @@ -392,24 +393,24 @@ BUGS -V affects only the accounts screen. When you press g, the current and all previous screens are regenerated, - which may cause a noticeable pause with large files. Also there is no + which may cause a noticeable pause with large files. Also there is no visual indication that this is in progress. - --watch is not yet fully robust. It works well for normal usage, but - many file changes in a short time (eg saving the file thousands of - times with an editor macro) can cause problems at least on OSX. Symp- - toms include: unresponsive UI, periodic resetting of the cursor posi- + --watch is not yet fully robust. It works well for normal usage, but + many file changes in a short time (eg saving the file thousands of + times with an editor macro) can cause problems at least on OSX. Symp- + toms include: unresponsive UI, periodic resetting of the cursor posi- tion, momentary display of parse errors, high CPU usage eventually sub- siding, and possibly a small but persistent build-up of CPU usage until the program is restarted. - Also, if you are viewing files mounted from another machine, --watch + Also, if you are viewing files mounted from another machine, --watch requires that both machine clocks are roughly in step. 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) @@ -423,7 +424,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-web/hledger-web.1 b/hledger-web/hledger-web.1 index ac6bde19b..b63f50edd 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -51,123 +51,124 @@ in addition to any search query entered there. Note: if invoking hledger-web as a hledger subcommand, write \f[C]--\f[R] before options, as shown in the synopsis above. .TP -.B \f[C]--serve\f[R] +\f[B]\f[CB]--serve\f[B]\f[R] serve and log requests, don\[aq]t browse or auto-exit .TP -.B \f[C]--serve-api\f[R] +\f[B]\f[CB]--serve-api\f[B]\f[R] like --serve, but serve only the JSON web API, without the server-side web UI .TP -.B \f[C]--host=IPADDR\f[R] +\f[B]\f[CB]--host=IPADDR\f[B]\f[R] listen on this IP address (default: 127.0.0.1) .TP -.B \f[C]--port=PORT\f[R] +\f[B]\f[CB]--port=PORT\f[B]\f[R] listen on this TCP port (default: 5000) .TP -.B \f[C]--base-url=URL\f[R] +\f[B]\f[CB]--base-url=URL\f[B]\f[R] set the base url (default: http://IPADDR:PORT). You would change this when sharing over the network, or integrating within a larger website. .TP -.B \f[C]--file-url=URL\f[R] +\f[B]\f[CB]--file-url=URL\f[B]\f[R] set the static files url (default: BASEURL/static). hledger-web normally serves static files itself, but if you wanted to serve them from another server for efficiency, you would set the url with this. .TP -.B \f[C]--capabilities=CAP[,CAP..]\f[R] +\f[B]\f[CB]--capabilities=CAP[,CAP..]\f[B]\f[R] enable the view, add, and/or manage capabilities (default: view,add) .TP -.B \f[C]--capabilities-header=HTTPHEADER\f[R] +\f[B]\f[CB]--capabilities-header=HTTPHEADER\f[B]\f[R] read capabilities to enable from a HTTP header, like X-Sandstorm-Permissions (default: disabled) .PP hledger input options: .TP -.B \f[C]-f FILE --file=FILE\f[R] +\f[B]\f[CB]-f FILE --file=FILE\f[B]\f[R] use a different input file. For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or \f[C]$HOME/.hledger.journal\f[R]) .TP -.B \f[C]--rules-file=RULESFILE\f[R] +\f[B]\f[CB]--rules-file=RULESFILE\f[B]\f[R] Conversion rules file to use when reading CSV (default: FILE.rules) .TP -.B \f[C]--separator=CHAR\f[R] +\f[B]\f[CB]--separator=CHAR\f[B]\f[R] Field separator to expect when reading CSV (default: \[aq],\[aq]) .TP -.B \f[C]--alias=OLD=NEW\f[R] +\f[B]\f[CB]--alias=OLD=NEW\f[B]\f[R] rename accounts named OLD to NEW .TP -.B \f[C]--anon\f[R] +\f[B]\f[CB]--anon\f[B]\f[R] anonymize accounts and payees .TP -.B \f[C]--pivot FIELDNAME\f[R] +\f[B]\f[CB]--pivot FIELDNAME\f[B]\f[R] use some other field or tag for the account name .TP -.B \f[C]-I --ignore-assertions\f[R] -ignore any failing balance assertions +\f[B]\f[CB]-I --ignore-assertions\f[B]\f[R] +disable balance assertion checks (note: does not disable balance +assignments) .PP hledger reporting options: .TP -.B \f[C]-b --begin=DATE\f[R] +\f[B]\f[CB]-b --begin=DATE\f[B]\f[R] include postings/txns on or after this date .TP -.B \f[C]-e --end=DATE\f[R] +\f[B]\f[CB]-e --end=DATE\f[B]\f[R] include postings/txns before this date .TP -.B \f[C]-D --daily\f[R] +\f[B]\f[CB]-D --daily\f[B]\f[R] multiperiod/multicolumn report by day .TP -.B \f[C]-W --weekly\f[R] +\f[B]\f[CB]-W --weekly\f[B]\f[R] multiperiod/multicolumn report by week .TP -.B \f[C]-M --monthly\f[R] +\f[B]\f[CB]-M --monthly\f[B]\f[R] multiperiod/multicolumn report by month .TP -.B \f[C]-Q --quarterly\f[R] +\f[B]\f[CB]-Q --quarterly\f[B]\f[R] multiperiod/multicolumn report by quarter .TP -.B \f[C]-Y --yearly\f[R] +\f[B]\f[CB]-Y --yearly\f[B]\f[R] multiperiod/multicolumn report by year .TP -.B \f[C]-p --period=PERIODEXP\f[R] +\f[B]\f[CB]-p --period=PERIODEXP\f[B]\f[R] set start date, end date, and/or reporting interval all at once using period expressions syntax .TP -.B \f[C]--date2\f[R] +\f[B]\f[CB]--date2\f[B]\f[R] match the secondary date instead (see command help for other effects) .TP -.B \f[C]-U --unmarked\f[R] +\f[B]\f[CB]-U --unmarked\f[B]\f[R] include only unmarked postings/txns (can combine with -P or -C) .TP -.B \f[C]-P --pending\f[R] +\f[B]\f[CB]-P --pending\f[B]\f[R] include only pending postings/txns .TP -.B \f[C]-C --cleared\f[R] +\f[B]\f[CB]-C --cleared\f[B]\f[R] include only cleared postings/txns .TP -.B \f[C]-R --real\f[R] +\f[B]\f[CB]-R --real\f[B]\f[R] include only non-virtual postings .TP -.B \f[C]-NUM --depth=NUM\f[R] +\f[B]\f[CB]-NUM --depth=NUM\f[B]\f[R] hide/aggregate accounts or postings more than NUM levels deep .TP -.B \f[C]-E --empty\f[R] +\f[B]\f[CB]-E --empty\f[B]\f[R] show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) .TP -.B \f[C]-B --cost\f[R] +\f[B]\f[CB]-B --cost\f[B]\f[R] convert amounts to their cost at transaction time (using the transaction price, if any) .TP -.B \f[C]-V --value\f[R] +\f[B]\f[CB]-V --value\f[B]\f[R] convert amounts to their market value on the report end date (using the most recent applicable market price, if any) .TP -.B \f[C]--auto\f[R] +\f[B]\f[CB]--auto\f[B]\f[R] apply automated posting rules to modify transactions. .TP -.B \f[C]--forecast\f[R] +\f[B]\f[CB]--forecast\f[B]\f[R] apply periodic transaction rules to generate future transactions, to 6 months from now or report end date. .PP @@ -178,13 +179,13 @@ Some reporting options can also be written as query arguments. .PP hledger help options: .TP -.B \f[C]-h --help\f[R] +\f[B]\f[CB]-h --help\f[B]\f[R] show general usage (or after COMMAND, command usage) .TP -.B \f[C]--version\f[R] +\f[B]\f[CB]--version\f[B]\f[R] show version .TP -.B \f[C]--debug[=N]\f[R] +\f[B]\f[CB]--debug[=N]\f[B]\f[R] show debug output (levels 1-9, default: 1) .PP A \[at]FILE argument will be expanded to the contents of FILE, which diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index c16b99bcc..c2512af84 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -1,4 +1,4 @@ -This is hledger-web.info, produced by makeinfo version 6.5 from stdin. +This is hledger-web.info, produced by makeinfo version 6.7 from stdin.  File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir) @@ -103,7 +103,8 @@ before options, as shown in the synopsis above. use some other field or tag for the account name '-I --ignore-assertions' - ignore any failing balance assertions + disable balance assertion checks (note: does not disable balance + assignments) hledger reporting options: @@ -342,13 +343,18 @@ Tag Table: Node: Top72 Node: OPTIONS1359 Ref: #options1464 -Node: PERMISSIONS6743 -Ref: #permissions6882 -Node: EDITING UPLOADING DOWNLOADING8094 -Ref: #editing-uploading-downloading8275 -Node: RELOADING9109 -Ref: #reloading9243 -Node: JSON API9676 -Ref: #json-api9770 +Node: PERMISSIONS6788 +Ref: #permissions6927 +Node: EDITING UPLOADING DOWNLOADING8139 +Ref: #editing-uploading-downloading8320 +Node: RELOADING9154 +Ref: #reloading9288 +Node: JSON API9721 +Ref: #json-api9815  End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 25e487326..a239d0795 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -97,7 +97,8 @@ OPTIONS use some other field or tag for the account name -I --ignore-assertions - ignore any failing balance assertions + disable balance assertion checks (note: does not disable balance + assignments) hledger reporting options: @@ -123,7 +124,7 @@ OPTIONS multiperiod/multicolumn report by year -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once + set start date, end date, and/or reporting interval all at once using period expressions syntax --date2 @@ -146,21 +147,21 @@ OPTIONS hide/aggregate accounts or postings more than NUM levels deep -E --empty - show items with zero amount, normally hidden (and vice-versa in + show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) -B --cost - convert amounts to their cost at transaction time (using the + convert amounts to their cost at transaction time (using the transaction price, if any) -V --value - convert amounts to their market value on the report end date + convert amounts to their market value on the report end date (using the most recent applicable market price, if any) --auto apply automated posting rules to modify transactions. --forecast - apply periodic transaction rules to generate future transac- + apply periodic transaction rules to generate future transac- tions, to 6 months from now or report end date. When a reporting option appears more than once in the command line, the @@ -180,41 +181,41 @@ OPTIONS show debug output (levels 1-9, default: 1) A @FILE argument will be expanded to the contents of FILE, which should - contain one command line option/argument per line. (To prevent this, + contain one command line option/argument per line. (To prevent this, insert a -- argument before.) By default, hledger-web starts the web app in "transient mode" and also opens it in your default web browser if possible. In this mode the web app will keep running for as long as you have it open in a browser win- - dow, and will exit after two minutes of inactivity (no requests and no - browser windows viewing it). With --serve, it just runs the web app - without exiting, and logs requests to the console. With --serve-api, - only the JSON web api (see below) is served, with the usual HTML + dow, and will exit after two minutes of inactivity (no requests and no + browser windows viewing it). With --serve, it just runs the web app + without exiting, and logs requests to the console. With --serve-api, + only the JSON web api (see below) is served, with the usual HTML server-side web UI disabled. - By default the server listens on IP address 127.0.0.1, accessible only - to local requests. You can use --host to change this, eg --host + By default the server listens on IP address 127.0.0.1, accessible only + to local requests. You can use --host to change this, eg --host 0.0.0.0 to listen on all configured addresses. - Similarly, use --port to set a TCP port other than 5000, eg if you are + Similarly, use --port to set a TCP port other than 5000, eg if you are running multiple hledger-web instances. - You can use --base-url to change the protocol, hostname, port and path + You can use --base-url to change the protocol, hostname, port and path that appear in hyperlinks, useful eg for integrating hledger-web within - a larger website. The default is http://HOST:PORT/ using the server's + a larger website. The default is http://HOST:PORT/ using the server's configured host address and TCP port (or http://HOST if PORT is 80). - With --file-url you can set a different base url for static files, eg + With --file-url you can set a different base url for static files, eg for better caching or cookie-less serving on high performance websites. PERMISSIONS - By default, hledger-web allows anyone who can reach it to view the + By default, hledger-web allows anyone who can reach it to view the journal and to add new transactions, but not to change existing data. You can restrict who can reach it by - o setting the IP address it listens on (see --host above). By default - it listens on 127.0.0.1, accessible to all users on the local ma- + o setting the IP address it listens on (see --host above). By default + it listens on 127.0.0.1, accessible to all users on the local ma- chine. o putting it behind an authenticating proxy, using eg apache or nginx @@ -224,44 +225,44 @@ PERMISSIONS You can restrict what the users who reach it can do, by o using the --capabilities=CAP[,CAP..] flag when you start it, enabling - one or more of the following capabilities. The default value is + one or more of the following capabilities. The default value is view,add: o view - allows viewing the journal file and all included files o add - allows adding new transactions to the main journal file - o manage - allows editing, uploading or downloading the main or in- + o manage - allows editing, uploading or downloading the main or in- cluded files - o using the --capabilities-header=HTTPHEADER flag to specify a HTTP - header from which it will read capabilities to enable. hledger-web - on Sandstorm uses the X-Sandstorm-Permissions header to integrate + o using the --capabilities-header=HTTPHEADER flag to specify a HTTP + header from which it will read capabilities to enable. hledger-web + on Sandstorm uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions. This is disabled by default. EDITING, UPLOADING, DOWNLOADING - If you enable the manage capability mentioned above, you'll see a new - "spanner" button to the right of the search form. Clicking this will - let you edit, upload, or download the journal file or any files it in- + If you enable the manage capability mentioned above, you'll see a new + "spanner" button to the right of the search form. Clicking this will + let you edit, upload, or download the journal file or any files it in- cludes. - Note, unlike any other hledger command, in this mode you (or any visi- + Note, unlike any other hledger command, in this mode you (or any visi- tor) can alter or wipe the data files. - Normally whenever a file is changed in this way, hledger-web saves a - numbered backup (assuming file permissions allow it, the disk is not - full, etc.) hledger-web is not aware of version control systems, cur- - rently; if you use one, you'll have to arrange to commit the changes + Normally whenever a file is changed in this way, hledger-web saves a + numbered backup (assuming file permissions allow it, the disk is not + full, etc.) hledger-web is not aware of version control systems, cur- + rently; if you use one, you'll have to arrange to commit the changes yourself (eg with a cron job or a file watcher like entr). - Changes which would leave the journal file(s) unparseable or non-valid - (eg with failing balance assertions) are prevented. (Probably. This + Changes which would leave the journal file(s) unparseable or non-valid + (eg with failing balance assertions) are prevented. (Probably. This needs re-testing.) RELOADING hledger-web detects changes made to the files by other means (eg if you - edit it directly, outside of hledger-web), and it will show the new - data when you reload the page or navigate to a new page. If a change + edit it directly, outside of hledger-web), and it will show the new + data when you reload the page or navigate to a new page. If a change makes a file unparseable, hledger-web will display an error message un- til the file has been fixed. @@ -269,8 +270,8 @@ RELOADING that both machine clocks are roughly in step.) JSON API - In addition to the web UI, hledger-web provides some API routes that - serve JSON in response to GET requests. (And when started with + In addition to the web UI, hledger-web provides some API routes that + serve JSON in response to GET requests. (And when started with --serve-api, it provides only these routes.): /accountnames @@ -280,17 +281,17 @@ JSON API /accounts /accounttransactions/#AccountName - Also, you can append a new transaction to the journal by sending a PUT - request to /add (hledger-web only). As with the web UI's add form, - hledger-web must be started with the add capability for this (enabled + Also, you can append a new transaction to the journal by sending a PUT + request to /add (hledger-web only). As with the web UI's add form, + hledger-web must be started with the add capability for this (enabled by default). - The payload should be a valid hledger transaction as JSON, similar to + The payload should be a valid hledger transaction as JSON, similar to what you get from /transactions or /accounttransactions. - Another way to generate test data is with the readJsonFile/writeJson- - File helpers in Hledger.Web.Json, which read or write any of hledger's - JSON-capable types from or to a file. Eg here we write the first + Another way to generate test data is with the readJsonFile/writeJson- + File helpers in Hledger.Web.Json, which read or write any of hledger's + JSON-capable types from or to a file. Eg here we write the first transaction of a sample journal: $ make ghci-web @@ -305,23 +306,23 @@ JSON API $ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo - By default, both the server-side HTML UI and the JSON API are served. - Running with --serve-api disables the former, useful if you only want + By default, both the server-side HTML UI and the JSON API are served. + Running with --serve-api disables the former, useful if you only want to serve the API. ENVIRONMENT 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 options with -- when invoked from hledger is awk- + The need to precede options with -- when invoked from hledger is awk- ward. -f- doesn't work (hledger-web can't read from stdin). @@ -335,7 +336,7 @@ BUGS 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) @@ -349,7 +350,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/hledger.1 b/hledger/hledger.1 index e82a3c8c9..3ae0034fa 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -159,101 +159,102 @@ by most hledger commands, run \f[C]hledger -h\f[R]. .PP General help options: .TP -.B \f[C]-h --help\f[R] +\f[B]\f[CB]-h --help\f[B]\f[R] show general usage (or after COMMAND, command usage) .TP -.B \f[C]--version\f[R] +\f[B]\f[CB]--version\f[B]\f[R] show version .TP -.B \f[C]--debug[=N]\f[R] +\f[B]\f[CB]--debug[=N]\f[B]\f[R] show debug output (levels 1-9, default: 1) .PP General input options: .TP -.B \f[C]-f FILE --file=FILE\f[R] +\f[B]\f[CB]-f FILE --file=FILE\f[B]\f[R] use a different input file. For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or \f[C]$HOME/.hledger.journal\f[R]) .TP -.B \f[C]--rules-file=RULESFILE\f[R] +\f[B]\f[CB]--rules-file=RULESFILE\f[B]\f[R] Conversion rules file to use when reading CSV (default: FILE.rules) .TP -.B \f[C]--separator=CHAR\f[R] +\f[B]\f[CB]--separator=CHAR\f[B]\f[R] Field separator to expect when reading CSV (default: \[aq],\[aq]) .TP -.B \f[C]--alias=OLD=NEW\f[R] +\f[B]\f[CB]--alias=OLD=NEW\f[B]\f[R] rename accounts named OLD to NEW .TP -.B \f[C]--anon\f[R] +\f[B]\f[CB]--anon\f[B]\f[R] anonymize accounts and payees .TP -.B \f[C]--pivot FIELDNAME\f[R] +\f[B]\f[CB]--pivot FIELDNAME\f[B]\f[R] use some other field or tag for the account name .TP -.B \f[C]-I --ignore-assertions\f[R] -ignore any failing balance assertions +\f[B]\f[CB]-I --ignore-assertions\f[B]\f[R] +disable balance assertion checks (note: does not disable balance +assignments) .PP General reporting options: .TP -.B \f[C]-b --begin=DATE\f[R] +\f[B]\f[CB]-b --begin=DATE\f[B]\f[R] include postings/txns on or after this date .TP -.B \f[C]-e --end=DATE\f[R] +\f[B]\f[CB]-e --end=DATE\f[B]\f[R] include postings/txns before this date .TP -.B \f[C]-D --daily\f[R] +\f[B]\f[CB]-D --daily\f[B]\f[R] multiperiod/multicolumn report by day .TP -.B \f[C]-W --weekly\f[R] +\f[B]\f[CB]-W --weekly\f[B]\f[R] multiperiod/multicolumn report by week .TP -.B \f[C]-M --monthly\f[R] +\f[B]\f[CB]-M --monthly\f[B]\f[R] multiperiod/multicolumn report by month .TP -.B \f[C]-Q --quarterly\f[R] +\f[B]\f[CB]-Q --quarterly\f[B]\f[R] multiperiod/multicolumn report by quarter .TP -.B \f[C]-Y --yearly\f[R] +\f[B]\f[CB]-Y --yearly\f[B]\f[R] multiperiod/multicolumn report by year .TP -.B \f[C]-p --period=PERIODEXP\f[R] +\f[B]\f[CB]-p --period=PERIODEXP\f[B]\f[R] set start date, end date, and/or reporting interval all at once using period expressions syntax .TP -.B \f[C]--date2\f[R] +\f[B]\f[CB]--date2\f[B]\f[R] match the secondary date instead (see command help for other effects) .TP -.B \f[C]-U --unmarked\f[R] +\f[B]\f[CB]-U --unmarked\f[B]\f[R] include only unmarked postings/txns (can combine with -P or -C) .TP -.B \f[C]-P --pending\f[R] +\f[B]\f[CB]-P --pending\f[B]\f[R] include only pending postings/txns .TP -.B \f[C]-C --cleared\f[R] +\f[B]\f[CB]-C --cleared\f[B]\f[R] include only cleared postings/txns .TP -.B \f[C]-R --real\f[R] +\f[B]\f[CB]-R --real\f[B]\f[R] include only non-virtual postings .TP -.B \f[C]-NUM --depth=NUM\f[R] +\f[B]\f[CB]-NUM --depth=NUM\f[B]\f[R] hide/aggregate accounts or postings more than NUM levels deep .TP -.B \f[C]-E --empty\f[R] +\f[B]\f[CB]-E --empty\f[B]\f[R] show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) .TP -.B \f[C]-B --cost\f[R] +\f[B]\f[CB]-B --cost\f[B]\f[R] convert amounts to their cost at transaction time (using the transaction price, if any) .TP -.B \f[C]-V --value\f[R] +\f[B]\f[CB]-V --value\f[B]\f[R] convert amounts to their market value on the report end date (using the most recent applicable market price, if any) .TP -.B \f[C]--auto\f[R] +\f[B]\f[CB]--auto\f[B]\f[R] apply automated posting rules to modify transactions. .TP -.B \f[C]--forecast\f[R] +\f[B]\f[CB]--forecast\f[B]\f[R] apply periodic transaction rules to generate future transactions, to 6 months from now or report end date. .PP @@ -773,7 +774,7 @@ start and end date like so: .PP .TS tab(@); -l l. +l r. T{ \f[C]-p \[dq]2009\[dq]\f[R] T}@T{ @@ -1101,20 +1102,20 @@ more general \f[C]--value\f[R] option: The TYPE part basically selects either \[dq]cost\[dq], or \[dq]market value\[dq] plus a valuation date: .TP -.B \f[C]--value=cost\f[R] +\f[B]\f[CB]--value=cost\f[B]\f[R] Convert amounts to cost, using the prices recorded in transactions. .TP -.B \f[C]--value=end\f[R] +\f[B]\f[CB]--value=end\f[B]\f[R] Convert amounts to their value in a default valuation commodity, using market prices on the last day of the report period (or if unspecified, the journal\[aq]s end date); or in multiperiod reports, market prices on the last day of each subperiod. .TP -.B \f[C]--value=now\f[R] +\f[B]\f[CB]--value=now\f[B]\f[R] Convert amounts to their value in default valuation commodity using current market prices (as of when report is generated). .TP -.B \f[C]--value=YYYY-MM-DD\f[R] +\f[B]\f[CB]--value=YYYY-MM-DD\f[B]\f[R] Convert amounts to their value in default valuation commodity using market prices on this date. .PP @@ -1509,30 +1510,30 @@ T} .PP \f[B]Additional notes\f[R] .TP -.B \f[I]cost\f[R] +\f[I]cost\f[R] calculated using price(s) recorded in the transaction(s). .TP -.B \f[I]value\f[R] +\f[I]value\f[R] market value using available market price declarations, or the unchanged amount if no conversion rate can be found. .TP -.B \f[I]report start\f[R] +\f[I]report start\f[R] the first day of the report period specified with -b or -p or date:, otherwise today. .TP -.B \f[I]report or journal start\f[R] +\f[I]report or journal start\f[R] the first day of the report period specified with -b or -p or date:, otherwise the earliest transaction date in the journal, otherwise today. .TP -.B \f[I]report end\f[R] +\f[I]report end\f[R] the last day of the report period specified with -e or -p or date:, otherwise today. .TP -.B \f[I]report or journal end\f[R] +\f[I]report or journal end\f[R] the last day of the report period specified with -e or -p or date:, otherwise the latest transaction date in the journal, otherwise today. .TP -.B \f[I]report interval\f[R] +\f[I]report interval\f[R] a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report\[aq]s multi-period mode (whether showing one or many subperiods). .SS Combining -B, -V, -X, --value @@ -1646,12 +1647,12 @@ The following kinds of search terms can be used. Remember these can also be prefixed with \f[B]\f[CB]not:\f[B]\f[R], eg to exclude a particular subaccount. .TP -.B \f[B]\f[CB]REGEX\f[B], \f[CB]acct:REGEX\f[B]\f[R] +\f[B]\f[R]\f[C]REGEX\f[R]\f[B], \f[R]\f[C]acct:REGEX\f[R]\f[B]\f[R] match account names by this regular expression. (With no prefix, \f[C]acct:\f[R] is assumed.) same as above .TP -.B \f[B]\f[CB]amt:N, amt:N, amt:>=N\f[B]\f[R] +\f[B]\f[R]\f[C]amt:N, amt:N, amt:>=N\f[R]\f[B]\f[R] match postings with a single-commodity amount that is equal to, less than, or greater than N. (Multi-commodity amounts are not tested, and will always match.) The @@ -1659,10 +1660,10 @@ comparison has two modes: if N is preceded by a + or - sign (or is 0), the two signed numbers are compared. Otherwise, the absolute magnitudes are compared, ignoring sign. .TP -.B \f[B]\f[CB]code:REGEX\f[B]\f[R] +\f[B]\f[R]\f[C]code:REGEX\f[R]\f[B]\f[R] match by transaction code (eg check number) .TP -.B \f[B]\f[CB]cur:REGEX\f[B]\f[R] +\f[B]\f[R]\f[C]cur:REGEX\f[R]\f[B]\f[R] match postings or transactions including any amounts whose currency/commodity symbol is fully matched by REGEX. (For a partial match, use \f[C].*REGEX.*\f[R]). @@ -1673,10 +1674,10 @@ quoting to hide it from the shell, so eg do: \f[C]hledger print cur:\[aq]\[rs]$\[aq]\f[R] or \f[C]hledger print cur:\[rs]\[rs]$\f[R]. .TP -.B \f[B]\f[CB]desc:REGEX\f[B]\f[R] +\f[B]\f[R]\f[C]desc:REGEX\f[R]\f[B]\f[R] match transaction descriptions. .TP -.B \f[B]\f[CB]date:PERIODEXPR\f[B]\f[R] +\f[B]\f[R]\f[C]date:PERIODEXPR\f[R]\f[B]\f[R] match dates within the specified period. PERIODEXPR is a period expression (with no report interval). Examples: \f[C]date:2016\f[R], \f[C]date:thismonth\f[R], @@ -1684,27 +1685,27 @@ Examples: \f[C]date:2016\f[R], \f[C]date:thismonth\f[R], If the \f[C]--date2\f[R] command line flag is present, this matches secondary dates instead. .TP -.B \f[B]\f[CB]date2:PERIODEXPR\f[B]\f[R] +\f[B]\f[R]\f[C]date2:PERIODEXPR\f[R]\f[B]\f[R] match secondary dates within the specified period. .TP -.B \f[B]\f[CB]depth:N\f[B]\f[R] +\f[B]\f[R]\f[C]depth:N\f[R]\f[B]\f[R] match (or display, depending on command) accounts at or above this depth .TP -.B \f[B]\f[CB]note:REGEX\f[B]\f[R] +\f[B]\f[R]\f[C]note:REGEX\f[R]\f[B]\f[R] match transaction notes (part of description right of \f[C]|\f[R], or whole description when there\[aq]s no \f[C]|\f[R]) .TP -.B \f[B]\f[CB]payee:REGEX\f[B]\f[R] +\f[B]\f[R]\f[C]payee:REGEX\f[R]\f[B]\f[R] match transaction payee/payer names (part of description left of \f[C]|\f[R], or whole description when there\[aq]s no \f[C]|\f[R]) .TP -.B \f[B]\f[CB]real:, real:0\f[B]\f[R] +\f[B]\f[R]\f[C]real:, real:0\f[R]\f[B]\f[R] match real or virtual postings respectively .TP -.B \f[B]\f[CB]status:, status:!, status:*\f[B]\f[R] +\f[B]\f[R]\f[C]status:, status:!, status:*\f[R]\f[B]\f[R] match unmarked, pending, or cleared transactions respectively .TP -.B \f[B]\f[CB]tag:REGEX[=REGEX]\f[B]\f[R] +\f[B]\f[R]\f[C]tag:REGEX[=REGEX]\f[R]\f[B]\f[R] match by tag name, and optionally also by tag value. Note a tag: query is considered to match a transaction if it matches any of the postings. @@ -1714,7 +1715,7 @@ transaction. The following special search term is used automatically in hledger-web, only: .TP -.B \f[B]\f[CB]inacct:ACCTNAME\f[B]\f[R] +\f[B]\f[R]\f[C]inacct:ACCTNAME\f[R]\f[B]\f[R] tells hledger-web to show the transaction register for this account. Can be filtered further with \f[C]acct\f[R] etc. .PP @@ -1749,6 +1750,8 @@ accounts, a .PD Show account names. .PP +$FLAGS$ +.PP This command lists account names, either declared with account directives (--declared), posted to (--used), or both (the default). With query arguments, only matched account names and account names @@ -1784,6 +1787,8 @@ activity .PD Show an ascii barchart of posting counts per interval. .PP +$FLAGS$ +.PP The activity command displays an ascii histogram showing transaction counts by day, week, month or other reporting interval (by day is the default). @@ -1808,6 +1813,8 @@ add .PD Prompt for transactions and add them to the journal. .PP +$FLAGS$ +.PP Many hledger users edit their journals directly with a text editor, or generate them from CSV. For more interactive data entry, there is the \f[C]add\f[R] command, @@ -1891,6 +1898,8 @@ balance, bal, b .PD Show accounts and their balances. .PP +$FLAGS$ +.PP The balance command is hledger\[aq]s most versatile command. Note, despite the name, it is not always used for showing real-world account balances; the more accounting-aware balancesheet and @@ -2512,6 +2521,8 @@ Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). .PP +$FLAGS$ +.PP Example: .IP .nf @@ -2559,6 +2570,8 @@ balancesheetequity, bse Just like balancesheet, but also reports Equity (which it assumes is under a top-level \f[C]equity\f[R] account). .PP +$FLAGS$ +.PP Example: .IP .nf @@ -2603,6 +2616,8 @@ Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). .PP +$FLAGS$ +.PP Example: .IP .nf @@ -2644,6 +2659,8 @@ With --date2, checks secondary dates instead. With --strict, dates must also be unique. With a query, only matched transactions\[aq] dates are checked. Reads the default journal file, or another specified with -f. +.PP +$FLAGS$ .SS check-dupes .PP check-dupes @@ -2654,6 +2671,8 @@ Reports account names having the same leaf but different prefixes. In other words, two or more leaves that are categorized differently. Reads the default journal file, or another specified as an argument. .PP +$FLAGS$ +.PP An example: http://stefanorodighiero.net/software/hledger-dupes.html .SS close .PP @@ -2668,6 +2687,8 @@ 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. .PP +$FLAGS$ +.PP The closing transaction transfers balances to \[dq]equity:closing balances\[dq], and the opening transaction transfers balances from \[dq]equity:opening balances\[dq], or you can customise these with the @@ -2773,10 +2794,14 @@ commodities .P .PD List all commodity/currency symbols used or declared in the journal. +.PP +$FLAGS$ .SS descriptions .PP descriptions Show descriptions. .PP +$FLAGS$ +.PP This command lists all descriptions that appear in transactions. .PP Examples: @@ -2810,6 +2835,8 @@ from your bank (eg as CSV data). When hledger and your bank disagree about the account balance, you can compare the bank data with your journal to find out the cause. .PP +$FLAGS$ +.PP Examples: .IP .nf @@ -2834,6 +2861,8 @@ files List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. +.PP +$FLAGS$ .SS help .PP help @@ -2842,6 +2871,8 @@ help .PD Show any of the hledger manuals. .PP +$FLAGS$ +.PP The \f[C]help\f[R] 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 @@ -2894,6 +2925,8 @@ Or with --dry-run, just print the transactions that would be added. Or with --catchup, just mark all of the FILEs\[aq] transactions as imported, without actually importing any. .PP +$FLAGS$ +.PP The input files are specified as arguments - no need to write -f before each one. So eg to add new transactions from all CSV files to the main journal, @@ -2946,6 +2979,8 @@ Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). .PP +$FLAGS$ +.PP This command displays a simple income statement. It currently assumes that you have top-level accounts named \f[C]income\f[R] (or \f[C]revenue\f[R]) and \f[C]expense\f[R] (plural @@ -2990,6 +3025,8 @@ selection. .PP notes Show notes. .PP +$FLAGS$ +.PP This command lists all notes that appear in transactions. .PP Examples: @@ -3005,6 +3042,8 @@ Snacks .PP payees Show payee names. .PP +$FLAGS$ +.PP This command lists all payee names that appear in transactions. .PP Examples: @@ -3030,6 +3069,8 @@ With --inverted-costs, also print inverse prices based on transaction prices. Prices (and postings providing prices) can be filtered by a query. Price amounts are always displayed with their full precision. +.PP +$FLAGS$ .SS print .PP print, txns, p @@ -3038,6 +3079,8 @@ print, txns, p .PD Show transaction journal entries, sorted by date. .PP +$FLAGS$ +.PP The print command displays full journal entries (transactions) from the journal file in date order, tidily formatted. With --date2, transactions are sorted by secondary date instead. @@ -3164,6 +3207,8 @@ print-unique .PD Print transactions which do not reuse an already-seen description. .PP +$FLAGS$ +.PP Example: .IP .nf @@ -3187,6 +3232,8 @@ register, reg, r .PD Show postings and their running total. .PP +$FLAGS$ +.PP The register command displays postings in date order, one per line, and their running total. This is typically used with a query selecting a particular account, to @@ -3343,6 +3390,8 @@ If there are multiple equally good matches, it shows the most recent. Query options (options, not arguments) can be used to restrict the search space. Helps ledger-autosync detect already-seen transactions when importing. +.PP +$FLAGS$ .SS rewrite .PP rewrite @@ -3353,6 +3402,8 @@ Print all transactions, rewriting the postings of matched transactions. For now the only rewrite available is adding new postings, like print --auto. .PP +$FLAGS$ +.PP This is a start at a generic rewriter of transaction entries. It reads the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching @@ -3524,6 +3575,8 @@ roi Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. .PP +$FLAGS$ +.PP This command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) that, @@ -3550,6 +3603,8 @@ stats .PD Show some journal statistics. .PP +$FLAGS$ +.PP 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. @@ -3587,6 +3642,8 @@ With a TAGREGEX argument, only tag names matching the regular expression With QUERY arguments, only transactions matching the query are considered. With --values flag, the tags\[aq] unique values are listed instead. +.PP +$FLAGS$ .SS test .PP test @@ -3595,6 +3652,8 @@ test .PD Run built-in unit tests. .PP +$FLAGS$ +.PP This command runs the unit tests built in to hledger and hledger-lib, printing the results on stdout. If any test fails, the exit code will be non-zero. @@ -3662,10 +3721,6 @@ hledger-web provides a simple web interface. .PP These are maintained separately, and usually updated shortly after a hledger release. -.SS diff -.PP -hledger-diff shows differences in an account\[aq]s transactions between -one journal file and another. .SS iadd .PP hledger-iadd is a more interactive, terminal UI replacement for the add @@ -3674,10 +3729,6 @@ command. .PP hledger-interest generates interest transactions for an account according to various schemes. -.SS irr -.PP -hledger-irr calculates the internal rate of return of an investment -account, but it\[aq]s superseded now by the built-in roi command. .SS Experimental add-ons .PP These are available in source form in the hledger repo\[aq]s bin/ @@ -3693,10 +3744,7 @@ formats, and can also download the data if your bank offers OFX Direct Connect. .SS chart .PP -hledger-chart.hs is an old pie chart generator, in need of some love. -.SS check -.PP -hledger-check.hs checks more powerful account balance assertions. +hledger-chart.hs is an old very basic pie chart generator. .SH ENVIRONMENT .PP \f[B]COLUMNS\f[R] The screen width used by the register command. diff --git a/hledger/hledger.info b/hledger/hledger.info index 9e8f29b6e..344c95561 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1,4 +1,4 @@ -This is hledger.info, produced by makeinfo version 6.5 from stdin. +This is hledger.info, produced by makeinfo version 6.7 from stdin.  File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir) @@ -179,7 +179,8 @@ by most hledger commands, run 'hledger -h'. use some other field or tag for the account name '-I --ignore-assertions' - ignore any failing balance assertions + disable balance assertion checks (note: does not disable balance + assignments) General reporting options: @@ -1347,6 +1348,8 @@ File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS accounts, a Show account names. + $FLAGS$ + This command lists account names, either declared with account directives (-declared), posted to (-used), or both (the default). With query arguments, only matched account names and account names referenced @@ -1377,6 +1380,8 @@ File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS activity Show an ascii barchart of posting counts per interval. + $FLAGS$ + The activity command displays an ascii histogram showing transaction counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. @@ -1398,6 +1403,8 @@ File: hledger.info, Node: add, Next: balance, Prev: activity, Up: COMMANDS add Prompt for transactions and add them to the journal. + $FLAGS$ + Many hledger users edit their journals directly with a text editor, or generate them from CSV. For more interactive data entry, there is the 'add' command, which prompts interactively on the console for new @@ -1469,6 +1476,8 @@ File: hledger.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMAN balance, bal, b Show accounts and their balances. + $FLAGS$ + The balance command is hledger's most versatile command. Note, despite the name, it is not always used for showing real-world account balances; the more accounting-aware balancesheet and incomestatement may @@ -2040,6 +2049,8 @@ date). It assumes that these accounts are under a top-level 'asset' or (like conventional financial statements, unlike balance/print/register) (experimental). + $FLAGS$ + Example: $ hledger balancesheet @@ -2083,6 +2094,8 @@ balancesheetequity, bse Just like balancesheet, but also reports Equity (which it assumes is under a top-level 'equity' account). + $FLAGS$ + Example: $ hledger balancesheetequity @@ -2123,6 +2136,8 @@ 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). + $FLAGS$ + Example: $ hledger cashflow @@ -2160,6 +2175,8 @@ checks secondary dates instead. With -strict, dates must also be unique. With a query, only matched transactions' dates are checked. Reads the default journal file, or another specified with -f. + $FLAGS$ +  File: hledger.info, Node: check-dupes, Next: close, Prev: check-dates, Up: COMMANDS @@ -2171,6 +2188,8 @@ Reports account names having the same leaf but different prefixes. In other words, two or more leaves that are categorized differently. Reads the default journal file, or another specified as an argument. + $FLAGS$ + An example: http://stefanorodighiero.net/software/hledger-dupes.html  @@ -2186,6 +2205,8 @@ 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. + $FLAGS$ + The closing transaction transfers balances to "equity:closing balances", and the opening transaction transfers balances from "equity:opening balances", or you can customise these with the @@ -2272,6 +2293,8 @@ File: hledger.info, Node: commodities, Next: descriptions, Prev: close, Up: commodities List all commodity/currency symbols used or declared in the journal. + $FLAGS$ +  File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS @@ -2280,6 +2303,8 @@ File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: C descriptions Show descriptions. + $FLAGS$ + This command lists all descriptions that appear in transactions. Examples: @@ -2312,6 +2337,8 @@ from your bank (eg as CSV data). When hledger and your bank disagree about the account balance, you can compare the bank data with your journal to find out the cause. + $FLAGS$ + Examples: $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro @@ -2334,6 +2361,8 @@ files List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. + $FLAGS$ +  File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS @@ -2343,6 +2372,8 @@ File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS help Show any of the hledger manuals. + $FLAGS$ + 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. @@ -2386,6 +2417,8 @@ the main journal file. Or with -dry-run, just print the transactions that would be added. Or with -catchup, just mark all of the FILEs' transactions as imported, without actually importing any. + $FLAGS$ + The input files are specified as arguments - no need to write -f before each one. So eg to add new transactions from all CSV files to the main journal, it's just: 'hledger import *.csv' @@ -2436,6 +2469,8 @@ plural forms also allowed). Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). + $FLAGS$ + 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.) @@ -2478,6 +2513,8 @@ File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: CO notes Show notes. + $FLAGS$ + This command lists all notes that appear in transactions. Examples: @@ -2494,6 +2531,8 @@ File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: COMMANDS payees Show payee names. + $FLAGS$ + This command lists all payee names that appear in transactions. Examples: @@ -2516,6 +2555,8 @@ synthetic market prices based on transaction prices. With Prices (and postings providing prices) can be filtered by a query. Price amounts are always displayed with their full precision. + $FLAGS$ +  File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS @@ -2525,6 +2566,8 @@ File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMA print, txns, p Show transaction journal entries, sorted by date. + $FLAGS$ + The print command displays full journal entries (transactions) from the journal file in date order, tidily formatted. With -date2, transactions are sorted by secondary date instead. @@ -2626,6 +2669,8 @@ File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COM print-unique Print transactions which do not reuse an already-seen description. + $FLAGS$ + Example: $ cat unique.journal @@ -2647,6 +2692,8 @@ File: hledger.info, Node: register, Next: register-match, Prev: print-unique, register, reg, r Show postings and their running total. + $FLAGS$ + The register command displays postings in date order, one per line, and their running total. This is typically used with a query selecting a particular account, to see that account's activity: @@ -2772,6 +2819,8 @@ good matches, it shows the most recent. Query options (options, not arguments) can be used to restrict the search space. Helps ledger-autosync detect already-seen transactions when importing. + $FLAGS$ +  File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS @@ -2783,6 +2832,8 @@ Print all transactions, rewriting the postings of matched transactions. For now the only rewrite available is adding new postings, like print -auto. + $FLAGS$ + This is a start at a generic rewriter of transaction entries. It reads the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. @@ -2938,6 +2989,8 @@ roi Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. + $FLAGS$ + This command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) @@ -2965,6 +3018,8 @@ File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS stats Show some journal statistics. + $FLAGS$ + 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. @@ -3000,6 +3055,8 @@ shown. With QUERY arguments, only transactions matching the query are considered. With -values flag, the tags' unique values are listed instead. + $FLAGS$ +  File: hledger.info, Node: test, Prev: tags, Up: COMMANDS @@ -3009,6 +3066,8 @@ File: hledger.info, Node: test, Prev: tags, Up: COMMANDS test Run built-in unit tests. + $FLAGS$ + This command runs the unit tests built in to hledger and hledger-lib, printing the results on stdout. If any test fails, the exit code will be non-zero. @@ -3106,44 +3165,27 @@ hledger release. * Menu: -* diff:: * iadd:: * interest:: -* irr:: - -5.2.1 diff ----------- - -hledger-diff shows differences in an account's transactions between one -journal file and another.  -File: hledger.info, Node: iadd, Next: interest, Prev: , Up: Third party add-ons +File: hledger.info, Node: iadd, Next: interest, Up: Third party add-ons -5.2.2 iadd +5.2.1 iadd ---------- hledger-iadd is a more interactive, terminal UI replacement for the add command.  -File: hledger.info, Node: interest, Next: irr, Prev: iadd, Up: Third party add-ons +File: hledger.info, Node: interest, Prev: iadd, Up: Third party add-ons -5.2.3 interest +5.2.2 interest -------------- hledger-interest generates interest transactions for an account according to various schemes. - -File: hledger.info, Node: irr, Prev: interest, Up: Third party add-ons - -5.2.4 irr ---------- - -hledger-irr calculates the internal rate of return of an investment -account, but it's superseded now by the built-in roi command. -  File: hledger.info, Node: Experimental add-ons, Prev: Third party add-ons, Up: ADD-ON COMMANDS @@ -3158,7 +3200,6 @@ and tweaking these is a good way to start making your own! * autosync:: * chart:: -* check::  File: hledger.info, Node: autosync, Next: chart, Up: Experimental add-ons @@ -3172,20 +3213,12 @@ and some CSV formats, and can also download the data if your bank offers OFX Direct Connect.  -File: hledger.info, Node: chart, Next: check, Prev: autosync, Up: Experimental add-ons +File: hledger.info, Node: chart, Prev: autosync, Up: Experimental add-ons 5.3.2 chart ----------- -hledger-chart.hs is an old pie chart generator, in need of some love. - - -File: hledger.info, Node: check, Prev: chart, Up: Experimental add-ons - -5.3.3 check ------------ - -hledger-check.hs checks more powerful account balance assertions. +hledger-chart.hs is an old very basic pie chart generator.  Tag Table: @@ -3196,173 +3229,173 @@ Node: OPTIONS3637 Ref: #options3739 Node: General options4138 Ref: #general-options4263 -Node: Command options6917 -Ref: #command-options7068 -Node: Command arguments7466 -Ref: #command-arguments7620 -Node: Argument files7741 -Ref: #argument-files7917 -Node: Special characters in arguments and queries8183 -Ref: #special-characters-in-arguments-and-queries8417 -Node: More escaping8868 -Ref: #more-escaping9030 -Node: Even more escaping9326 -Ref: #even-more-escaping9520 -Node: Less escaping10191 -Ref: #less-escaping10353 -Node: Command line tips10598 -Ref: #command-line-tips10784 -Node: Unicode characters11161 -Ref: #unicode-characters11317 -Node: Input files12729 -Ref: #input-files12865 -Node: Smart dates14794 -Ref: #smart-dates14935 -Node: Report start & end date16341 -Ref: #report-start-end-date16513 -Node: Report intervals17937 -Ref: #report-intervals18102 -Node: Period expressions18492 -Ref: #period-expressions18652 -Node: Depth limiting22607 -Ref: #depth-limiting22751 -Node: Pivoting23093 -Ref: #pivoting23216 -Node: Valuation24892 -Ref: #valuation25021 -Node: -B Cost25201 -Ref: #b-cost25312 -Node: -V Market value25510 -Ref: #v-market-value25684 -Node: -X Market value in specified commodity27116 -Ref: #x-market-value-in-specified-commodity27355 -Node: --value Flexible valuation27531 -Ref: #value-flexible-valuation27757 -Node: Effect of --value on reports31947 -Ref: #effect-of---value-on-reports32163 -Node: Combining -B -V -X --value37094 -Ref: #combining--b--v--x---value37277 -Node: Output destination37313 -Ref: #output-destination37465 -Node: Output format37748 -Ref: #output-format37900 -Node: Regular expressions38285 -Ref: #regular-expressions38422 -Node: QUERIES39783 -Ref: #queries39885 -Node: COMMANDS43847 -Ref: #commands43959 -Node: accounts45023 -Ref: #accounts45121 -Node: activity45820 -Ref: #activity45930 -Node: add46313 -Ref: #add46412 -Node: balance49157 -Ref: #balance49268 -Node: Classic balance report50726 -Ref: #classic-balance-report50899 -Node: Customising the classic balance report52268 -Ref: #customising-the-classic-balance-report52496 -Node: Colour support54572 -Ref: #colour-support54739 -Node: Flat mode54912 -Ref: #flat-mode55060 -Node: Depth limited balance reports55473 -Ref: #depth-limited-balance-reports55658 -Node: Percentages56114 -Ref: #percentages56280 -Node: Multicolumn balance report57417 -Ref: #multicolumn-balance-report57597 -Node: Budget report62911 -Ref: #budget-report63054 -Node: Nested budgets68256 -Ref: #nested-budgets68368 -Ref: #output-format-171848 -Node: balancesheet71926 -Ref: #balancesheet72062 -Node: balancesheetequity73445 -Ref: #balancesheetequity73594 -Node: cashflow74155 -Ref: #cashflow74283 -Node: check-dates75379 -Ref: #check-dates75506 -Node: check-dupes75785 -Ref: #check-dupes75909 -Node: close76202 -Ref: #close76316 -Node: commodities79982 -Ref: #commodities80109 -Node: descriptions80191 -Ref: #descriptions80319 -Node: diff80500 -Ref: #diff80606 -Node: files81653 -Ref: #files81753 -Node: help81900 -Ref: #help82000 -Node: import83081 -Ref: #import83195 -Node: Importing balance assignments84088 -Ref: #importing-balance-assignments84236 -Node: incomestatement84885 -Ref: #incomestatement85018 -Node: notes86422 -Ref: #notes86535 -Node: payees86661 -Ref: #payees86767 -Node: prices86925 -Ref: #prices87031 -Node: print87372 -Ref: #print87482 -Node: print-unique91975 -Ref: #print-unique92101 -Node: register92386 -Ref: #register92513 -Node: Custom register output96685 -Ref: #custom-register-output96814 -Node: register-match98076 -Ref: #register-match98210 -Node: rewrite98561 -Ref: #rewrite98676 -Node: Re-write rules in a file100531 -Ref: #re-write-rules-in-a-file100665 -Node: Diff output format101875 -Ref: #diff-output-format102044 -Node: rewrite vs print --auto103136 -Ref: #rewrite-vs.-print---auto103315 -Node: roi103871 -Ref: #roi103969 -Node: stats104981 -Ref: #stats105080 -Node: tags105868 -Ref: #tags105966 -Node: test106260 -Ref: #test106344 -Node: ADD-ON COMMANDS107091 -Ref: #add-on-commands107201 -Node: Official add-ons108489 -Ref: #official-add-ons108629 -Node: ui108709 -Ref: #ui108796 -Node: web108850 -Ref: #web108939 -Node: Third party add-ons108985 -Ref: #third-party-add-ons109160 -Ref: #diff-1109319 -Node: iadd109418 -Ref: #iadd109528 -Node: interest109610 -Ref: #interest109731 -Node: irr109826 -Ref: #irr109924 -Node: Experimental add-ons110055 -Ref: #experimental-add-ons110207 -Node: autosync110455 -Ref: #autosync110566 -Node: chart110805 -Ref: #chart110924 -Node: check110995 -Ref: #check111097 +Node: Command options6962 +Ref: #command-options7113 +Node: Command arguments7511 +Ref: #command-arguments7665 +Node: Argument files7786 +Ref: #argument-files7962 +Node: Special characters in arguments and queries8228 +Ref: #special-characters-in-arguments-and-queries8462 +Node: More escaping8913 +Ref: #more-escaping9075 +Node: Even more escaping9371 +Ref: #even-more-escaping9565 +Node: Less escaping10236 +Ref: #less-escaping10398 +Node: Command line tips10643 +Ref: #command-line-tips10829 +Node: Unicode characters11206 +Ref: #unicode-characters11362 +Node: Input files12774 +Ref: #input-files12910 +Node: Smart dates14839 +Ref: #smart-dates14980 +Node: Report start & end date16386 +Ref: #report-start-end-date16558 +Node: Report intervals17982 +Ref: #report-intervals18147 +Node: Period expressions18537 +Ref: #period-expressions18697 +Node: Depth limiting22652 +Ref: #depth-limiting22796 +Node: Pivoting23138 +Ref: #pivoting23261 +Node: Valuation24937 +Ref: #valuation25066 +Node: -B Cost25246 +Ref: #b-cost25357 +Node: -V Market value25555 +Ref: #v-market-value25729 +Node: -X Market value in specified commodity27161 +Ref: #x-market-value-in-specified-commodity27400 +Node: --value Flexible valuation27576 +Ref: #value-flexible-valuation27802 +Node: Effect of --value on reports31992 +Ref: #effect-of---value-on-reports32208 +Node: Combining -B -V -X --value37139 +Ref: #combining--b--v--x---value37322 +Node: Output destination37358 +Ref: #output-destination37510 +Node: Output format37793 +Ref: #output-format37945 +Node: Regular expressions38330 +Ref: #regular-expressions38467 +Node: QUERIES39828 +Ref: #queries39930 +Node: COMMANDS43892 +Ref: #commands44004 +Node: accounts45068 +Ref: #accounts45166 +Node: activity45877 +Ref: #activity45987 +Node: add46382 +Ref: #add46481 +Node: balance49232 +Ref: #balance49343 +Node: Classic balance report50813 +Ref: #classic-balance-report50986 +Node: Customising the classic balance report52355 +Ref: #customising-the-classic-balance-report52583 +Node: Colour support54659 +Ref: #colour-support54826 +Node: Flat mode54999 +Ref: #flat-mode55147 +Node: Depth limited balance reports55560 +Ref: #depth-limited-balance-reports55745 +Node: Percentages56201 +Ref: #percentages56367 +Node: Multicolumn balance report57504 +Ref: #multicolumn-balance-report57684 +Node: Budget report62998 +Ref: #budget-report63141 +Node: Nested budgets68343 +Ref: #nested-budgets68455 +Ref: #output-format-171936 +Node: balancesheet72014 +Ref: #balancesheet72150 +Node: balancesheetequity73545 +Ref: #balancesheetequity73694 +Node: cashflow74267 +Ref: #cashflow74395 +Node: check-dates75503 +Ref: #check-dates75630 +Node: check-dupes75921 +Ref: #check-dupes76045 +Node: close76350 +Ref: #close76464 +Node: commodities80142 +Ref: #commodities80269 +Node: descriptions80363 +Ref: #descriptions80491 +Node: diff80684 +Ref: #diff80790 +Node: files81849 +Ref: #files81949 +Node: help82108 +Ref: #help82208 +Node: import83301 +Ref: #import83415 +Node: Importing balance assignments84320 +Ref: #importing-balance-assignments84468 +Node: incomestatement85117 +Ref: #incomestatement85250 +Node: notes86666 +Ref: #notes86779 +Node: payees86917 +Ref: #payees87023 +Node: prices87193 +Ref: #prices87299 +Node: print87652 +Ref: #print87762 +Node: print-unique92267 +Ref: #print-unique92393 +Node: register92690 +Ref: #register92817 +Node: Custom register output97001 +Ref: #custom-register-output97130 +Node: register-match98392 +Ref: #register-match98526 +Node: rewrite98889 +Ref: #rewrite99004 +Node: Re-write rules in a file100871 +Ref: #re-write-rules-in-a-file101005 +Node: Diff output format102215 +Ref: #diff-output-format102384 +Node: rewrite vs print --auto103476 +Ref: #rewrite-vs.-print---auto103655 +Node: roi104211 +Ref: #roi104309 +Node: stats105333 +Ref: #stats105432 +Node: tags106232 +Ref: #tags106330 +Node: test106636 +Ref: #test106720 +Node: ADD-ON COMMANDS107479 +Ref: #add-on-commands107589 +Node: Official add-ons108877 +Ref: #official-add-ons109017 +Node: ui109097 +Ref: #ui109184 +Node: web109238 +Ref: #web109327 +Node: Third party add-ons109373 +Ref: #third-party-add-ons109548 +Node: iadd109667 +Ref: #iadd109768 +Node: interest109850 +Ref: #interest109959 +Node: Experimental add-ons110054 +Ref: #experimental-add-ons110206 +Node: autosync110444 +Ref: #autosync110555 +Node: chart110794 +Ref: #chart110899  End Tag Table + + +Local Variables: +coding: utf-8 +End: diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 6ff18453d..c1af48220 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -146,7 +146,8 @@ OPTIONS use some other field or tag for the account name -I --ignore-assertions - ignore any failing balance assertions + disable balance assertion checks (note: does not disable balance + assignments) General reporting options: @@ -172,7 +173,7 @@ OPTIONS multiperiod/multicolumn report by year -p --period=PERIODEXP - set start date, end date, and/or reporting interval all at once + set start date, end date, and/or reporting interval all at once using period expressions syntax --date2 @@ -195,21 +196,21 @@ OPTIONS hide/aggregate accounts or postings more than NUM levels deep -E --empty - show items with zero amount, normally hidden (and vice-versa in + show items with zero amount, normally hidden (and vice-versa in hledger-ui/hledger-web) -B --cost - convert amounts to their cost at transaction time (using the + convert amounts to their cost at transaction time (using the transaction price, if any) -V --value - convert amounts to their market value on the report end date + convert amounts to their market value on the report end date (using the most recent applicable market price, if any) --auto apply automated posting rules to modify transactions. --forecast - apply periodic transaction rules to generate future transac- + apply periodic transaction rules to generate future transac- tions, to 6 months from now or report end date. When a reporting option appears more than once in the command line, the @@ -221,35 +222,35 @@ OPTIONS To see options for a particular command, including command-specific op- tions, run: hledger COMMAND -h. - Command-specific options must be written after the command name, eg: + Command-specific options must be written after the command name, eg: hledger print -x. - Additionally, if the command is an addon, you may need to put its op- - tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can + Additionally, if the command is an addon, you may need to put its op- + tions after a double-hyphen, eg: hledger ui -- --watch. Or, you can run the addon executable directly: hledger-ui --watch. Command arguments - Most hledger commands accept arguments after the command name, which + Most hledger commands accept arguments after the command name, which are often a query, filtering the data in some way. Argument files You can save a set of command line options/arguments in a file, one per - line, and then reuse them by writing @FILENAME in a command line. To + line, and then reuse them by writing @FILENAME in a command line. To prevent this expansion of @-arguments, precede them with a -- argument. For more, see Save frequently used options. Special characters in arguments and queries In shell command lines, option and argument values which contain "prob- lematic" characters, ie spaces, and also characters significant to your - shell such as <, >, (, ), | and $, should be escaped by enclosing them + shell such as <, >, (, ), | and $, should be escaped by enclosing them in quotes or by writing backslashes before the characters. Eg: - hledger register -p 'last year' "accounts receivable (receiv- + hledger register -p 'last year' "accounts receivable (receiv- able|payable)" amt:\>100. More escaping Characters significant both to the shell and in regular expressions may - need one extra level of escaping. These include parentheses, the pipe + need one extra level of escaping. These include parentheses, the pipe symbol and the dollar sign. Eg, to match the dollar symbol, bash users should do: @@ -260,9 +261,9 @@ OPTIONS hledger balance cur:\\$ Even more escaping - When hledger runs an addon executable (eg you type hledger ui, hledger - runs hledger-ui), it de-escapes command-line options and arguments - once, so you might need to triple-escape. Eg in bash, running the ui + When hledger runs an addon executable (eg you type hledger ui, hledger + runs hledger-ui), it de-escapes command-line options and arguments + once, so you might need to triple-escape. Eg in bash, running the ui command and matching the dollar sign, it's: hledger ui cur:'\\$' @@ -287,8 +288,8 @@ OPTIONS hledger-ui cur:\\$ Less escaping - Inside an argument file, or in the search field of hledger-ui or - hledger-web, or at a GHCI prompt, you need one less level of escaping + Inside an argument file, or in the search field of hledger-ui or + hledger-web, or at a GHCI prompt, you need one less level of escaping than at the command line. And backslashes may work better than quotes. Eg: @@ -305,47 +306,47 @@ OPTIONS o if needed, also add a backslash to escape regexp metacharacters - To find out exactly how a command line is being parsed, add --debug=2 + To find out exactly how a command line is being parsed, add --debug=2 to troubleshoot. Unicode characters hledger is expected to handle non-ascii characters correctly: - o they should be parsed correctly in input files and on the command - line, by all hledger tools (add, iadd, hledger-web's search/add/edit + o they should be parsed correctly in input files and on the command + line, by all hledger tools (add, iadd, hledger-web's search/add/edit forms, etc.) - o they should be displayed correctly by all hledger tools, and on- + o they should be displayed correctly by all hledger tools, and on- screen alignment should be preserved. This requires a well-configured environment. Here are some tips: - o A system locale must be configured, and it must be one that can de- - code the characters being used. In bash, you can set a locale like - this: export LANG=en_US.UTF-8. There are some more details in Trou- - bleshooting. This step is essential - without it, hledger will quit - on encountering a non-ascii character (as with all GHC-compiled pro- + o A system locale must be configured, and it must be one that can de- + code the characters being used. In bash, you can set a locale like + this: export LANG=en_US.UTF-8. There are some more details in Trou- + bleshooting. This step is essential - without it, hledger will quit + on encountering a non-ascii character (as with all GHC-compiled pro- grams). - o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) + o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..) must support unicode o the terminal must be using a font which includes the required unicode glyphs - o the terminal should be configured to display wide characters as dou- + o the terminal should be configured to display wide characters as dou- ble width (for report alignment) - o on Windows, for best results you should run hledger in the same kind - of environment in which it was built. Eg hledger built in the stan- - dard CMD.EXE environment (like the binaries on our download page) - might show display problems when run in a cygwin or msys terminal, + o on Windows, for best results you should run hledger in the same kind + of environment in which it was built. Eg hledger built in the stan- + dard CMD.EXE environment (like the binaries on our download page) + might show display problems when run in a cygwin or msys terminal, and vice versa. (See eg #961). Input files hledger reads transactions from a data file (and the add command writes to it). By default this file is $HOME/.hledger.journal (or on Windows, - something like C:/Users/USER/.hledger.journal). You can override this + something like C:/Users/USER/.hledger.journal). You can override this with the $LEDGER_FILE environment variable: $ setenv LEDGER_FILE ~/finance/2016.journal @@ -359,24 +360,24 @@ OPTIONS $ cat some.journal | hledger -f- - Usually the data file is in hledger's journal format, but it can also - be one of several other formats, listed below. hledger detects the - format automatically based on the file extension, or if that is not + Usually the data file is in hledger's journal format, but it can also + be one of several other formats, listed below. hledger detects the + format automatically based on the file extension, or if that is not recognised, by trying each built-in "reader" in turn: Reader: Reads: Used for file extensions: ----------------------------------------------------------------------------- - journal hledger's journal format, also .journal .j .hledger .ledger + journal hledger's journal format, also .journal .j .hledger .ledger some Ledger journals - time- timeclock files (precise time .timeclock + time- timeclock files (precise time .timeclock clock logging) timedot timedot files (approximate time .timedot logging) - csv comma-separated values (data .csv + csv comma-separated values (data .csv interchange) - If needed (eg to ensure correct error messages when a file has the - "wrong" extension), you can force a specific reader/format by prepend- + If needed (eg to ensure correct error messages when a file has the + "wrong" extension), you can force a specific reader/format by prepend- ing it to the file path with a colon. Examples: $ hledger -f csv:/some/csv-file.dat stats @@ -387,7 +388,7 @@ OPTIONS o directives in one file will not affect the other files - o balance assertions will not see any account balances from previous + o balance assertions will not see any account balances from previous files If you need those, either use the include directive, or concatenate the @@ -395,83 +396,80 @@ OPTIONS Smart dates hledger's user interfaces accept a flexible "smart date" syntax (unlike - dates in the journal file). Smart dates allow some english words, can - be relative to today's date, and can have less-significant date parts + dates in the journal file). Smart dates allow some english words, can + be relative to today's date, and can have less-significant date parts omitted (defaulting to 1). Examples: - 2004/10/1, 2004-01-01, exact date, several sepa- - 2004.9.1 rators allowed. Year is - 4+ digits, month is 1-12, + 2004/10/1, 2004-01-01, exact date, several sepa- + 2004.9.1 rators allowed. Year is + 4+ digits, month is 1-12, day is 1-31 2004 start of year 2004/10 start of month - 10/1 month and day in current + 10/1 month and day in current year 21 day in current month - october, oct start of month in current + october, oct start of month in current year yesterday, today, tomorrow -1, 0, 1 days from today - last/this/next -1, 0, 1 periods from the + last/this/next -1, 0, 1 periods from the day/week/month/quar- current period ter/year - 20181201 8 digit YYYYMMDD with + 20181201 8 digit YYYYMMDD with valid year month and day - 201812 6 digit YYYYMM with valid + 201812 6 digit YYYYMM with valid year and month - Counterexamples - malformed digit sequences might give surprising re- + Counterexamples - malformed digit sequences might give surprising re- sults: - 201813 6 digits with an invalid - month is parsed as start + 201813 6 digits with an invalid + month is parsed as start of 6-digit year - 20181301 8 digits with an invalid - month is parsed as start + 20181301 8 digits with an invalid + month is parsed as start of 8-digit year - 20181232 8 digits with an invalid + 20181232 8 digits with an invalid day gives an error 201801012 9+ digits beginning with a valid YYYYMMDD gives an error Report start & end date - Most hledger reports show the full span of time represented by the + Most hledger reports show the full span of time represented by the journal data, by default. So, the effective report start and end dates - will be the earliest and latest transaction or posting dates found in + will be the earliest and latest transaction or posting dates found in the journal. - Often you will want to see a shorter time span, such as the current - month. You can specify a start and/or end date using -b/--begin, + Often you will want to see a shorter time span, such as the current + month. You can specify a start and/or end date using -b/--begin, -e/--end, -p/--period or a date: query (described below). All of these accept the smart date syntax. Some notes: - o As in Ledger, end dates are exclusive, so you need to write the date + o As in Ledger, end dates are exclusive, so you need to write the date after the last day you want to include. - o As noted in reporting options: among start/end dates specified with + o As noted in reporting options: among start/end dates specified with options, the last (i.e. right-most) option takes precedence. - o The effective report start and end dates are the intersection of the - start/end dates from options and that from date: queries. That is, - date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the + o The effective report start and end dates are the intersection of the + start/end dates from options and that from date: queries. That is, + date:2019-01 date:2019 -p'2000 to 2030' yields January 2019, the smallest common time span. Examples: -b 2016/3/17 begin on St. Patrick's day 2016 - - - - -e 12/1 end at the start of decem- ber 1st of the current - year (11/30 will be the + year (11/30 will be the last date included) + -b thismonth all transactions on or af- ter the 1st of the current month @@ -485,31 +483,31 @@ OPTIONS Report intervals A report interval can be specified so that commands like register, bal- - ance and activity will divide their reports into multiple subperiods. - The basic intervals can be selected with one of -D/--daily, - -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- - plex intervals may be specified with a period expression. Report in- + ance and activity will divide their reports into multiple subperiods. + The basic intervals can be selected with one of -D/--daily, + -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- + plex intervals may be specified with a period expression. Report in- tervals can not be specified with a query. Period expressions - The -p/--period option accepts period expressions, a shorthand way of + The -p/--period option accepts period expressions, a shorthand way of expressing a start date, end date, and/or report interval all at once. - Here's a basic period expression specifying the first quarter of 2009. - Note, hledger always treats start dates as inclusive and end dates as + Here's a basic period expression specifying the first quarter of 2009. + Note, hledger always treats start dates as inclusive and end dates as exclusive: -p "from 2009/1/1 to 2009/4/1" - Keywords like "from" and "to" are optional, and so are the spaces, as - long as you don't run two dates together. "to" can also be written as + Keywords like "from" and "to" are optional, and so are the spaces, as + long as you don't run two dates together. "to" can also be written as "-". These are equivalent to the above: -p "2009/1/1 2009/4/1" -p2009/1/1to2009/4/1 -p2009/1/1-2009/4/1 - Dates are smart dates, so if the current year is 2009, the above can + Dates are smart dates, so if the current year is 2009, the above can also be written as: -p "1/1 4/1" @@ -523,70 +521,68 @@ OPTIONS 1, 2009 -p "from 2009/1" the same -p "from 2009" the same - -p "to 2009" everything before january + -p "to 2009" everything before january 1, 2009 - A single date with no "from" or "to" defines both the start and end + A single date with no "from" or "to" defines both the start and end date like so: - -p "2009" the year 2009; equivalent + -p "2009" the year 2009; equivalent to "2009/1/1 to 2010/1/1" - -p "2009/1" the month of jan; equiva- + -p "2009/1" the month of jan; equiva- lent to "2009/1/1 to 2009/2/1" - - - -p "2009/1/1" just that day; equivalent + -p "2009/1/1" just that day; equivalent to "2009/1/1 to 2009/1/2" - The argument of -p can also begin with, or be, a report interval ex- + The argument of -p can also begin with, or be, a report interval ex- pression. The basic report intervals are daily, weekly, monthly, quar- - terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y - flags. Between report interval and start/end dates (if any), the word + terly, or yearly, which have the same effect as the -D,-W,-M,-Q, or -Y + flags. Between report interval and start/end dates (if any), the word in is optional. Examples: -p "weekly from 2009/1/1 to 2009/4/1" -p "monthly in 2008" -p "quarterly" - Note that weekly, monthly, quarterly and yearly intervals will always + Note that weekly, monthly, quarterly and yearly intervals will always start on the first day on week, month, quarter or year accordingly, and - will end on the last day of same period, even if associated period ex- + will end on the last day of same period, even if associated period ex- pression specifies different explicit start and end date. For example: - -p "weekly from 2009/1/1 to 2009/4/1" - -- starts on 2008/12/29, closest pre- + -p "weekly from 2009/1/1 to 2009/4/1" + -- starts on 2008/12/29, closest pre- ceding Monday -p "monthly in 2008/11/25" -- starts on 2018/11/01 - -p "quarterly from 2009-05-05 to + -p "quarterly from 2009-05-05 to 2009-06-01" - starts on 2009/04/01, ends on 2009/06/30, which are first and last days of Q2 2009 -p "yearly from 2009-12-29" - starts on 2009/01/01, first day of 2009 - The following more complex report intervals are also supported: bi- + The following more complex report intervals are also supported: bi- weekly, bimonthly, every day|week|month|quarter|year, every N days|weeks|months|quarters|years. - All of these will start on the first day of the requested period and + All of these will start on the first day of the requested period and end on the last one, as described above. Examples: - -p "bimonthly from 2008" -- periods + -p "bimonthly from 2008" -- periods will have boundaries on 2008/01/01, 2008/03/01, ... -p "every 2 weeks" -- starts on closest preceding Monday - -p "every 5 month from 2009/03" -- pe- - riods will have boundaries on + -p "every 5 month from 2009/03" -- pe- + riods will have boundaries on 2009/03/01, 2009/08/01, ... - If you want intervals that start on arbitrary day of your choosing and + If you want intervals that start on arbitrary day of your choosing and span a week, month or year, you need to use any of the following: every Nth day of week, every , every Nth day [of month], every @@ -595,48 +591,47 @@ OPTIONS Examples: - -p "every 2nd day of week" -- periods + -p "every 2nd day of week" -- periods will go from Tue to Tue -p "every Tue" -- same - -p "every 15th day" -- period bound- + -p "every 15th day" -- period bound- aries will be on 15th of each month - -p "every 2nd Monday" -- period bound- - aries will be on second Monday of each + -p "every 2nd Monday" -- period bound- + aries will be on second Monday of each month - -p "every 11/05" -- yearly periods with boundaries on 5th of Nov -p "every 5th Nov" -- same -p "every Nov 5th" -- same - Show historical balances at end of 15th each month (N is exclusive end + Show historical balances at end of 15th each month (N is exclusive end date): hledger balance -H -p "every 16th day" - Group postings from start of wednesday to end of next tuesday (N is + Group postings from start of wednesday to end of next tuesday (N is start date and exclusive end date): hledger register checking -p "every 3rd day of week" Depth limiting With the --depth N option (short form: -N), commands like account, bal- - ance and register will show only the uppermost accounts in the account - tree, down to level N. Use this when you want a summary with less de- + ance and register will show only the uppermost accounts in the account + tree, down to level N. Use this when you want a summary with less de- tail. This flag has the same effect as a depth: query argument (so -2, --depth=2 or depth:2 are basically equivalent). Pivoting Normally hledger sums amounts, and organizes them in a hierarchy, based - on account name. The --pivot FIELD option causes it to sum and orga- - nize hierarchy based on the value of some other field instead. FIELD + on account name. The --pivot FIELD option causes it to sum and orga- + nize hierarchy based on the value of some other field instead. FIELD can be: code, description, payee, note, or the full name (case insensi- tive) of any tag. As with account names, values containing colon:sepa- rated:parts will be displayed hierarchically in reports. - --pivot is a general option affecting all reports; you can think of + --pivot is a general option affecting all reports; you can think of hledger transforming the journal before any other processing, replacing - every posting's account name with the value of the specified field on + every posting's account name with the value of the specified field on that posting, inheriting it from the transaction or using a blank value if it's not present. @@ -662,7 +657,7 @@ OPTIONS -------------------- 0 - One way to show only amounts with a member: value (using a query, de- + One way to show only amounts with a member: value (using a query, de- scribed below): $ hledger balance --pivot member tag:member=. @@ -670,7 +665,7 @@ OPTIONS -------------------- -2 EUR - Another way (the acct: query matches against the pivoted "account + Another way (the acct: query matches against the pivoted "account name"): $ hledger balance --pivot member acct:. @@ -681,23 +676,23 @@ OPTIONS Valuation -B: Cost The -B/--cost flag converts amounts to their cost (or selling price) at - transaction time, if they have a transaction price specified. This + transaction time, if they have a transaction price specified. This flag is equivalent to --value=cost, described below. -V: Market value The -V/--market flag converts reported amounts to their market value in - a default valuation commodity, using the market prices in effect on a - default valuation date. For single period reports, the valuation date - is today (equivalent to --value=now); for multiperiod reports, it is + a default valuation commodity, using the market prices in effect on a + default valuation date. For single period reports, the valuation date + is today (equivalent to --value=now); for multiperiod reports, it is the last day of each subperiod (equivalent to --value=end). The default valuation commodity is the one referenced in the latest ap- - plicable market price dated on or before the valuation date. If most - of your P declarations lead to a single home currency, this will usu- + plicable market price dated on or before the valuation date. If most + of your P declarations lead to a single home currency, this will usu- ally be what you want. (To specify the commodity, see -X below.) Note that in hledger, market prices are always declared explicitly with - P directives; we do not infer them from transaction prices as Ledger + P directives; we do not infer them from transaction prices as Ledger does. Here's a quick example of -V: @@ -723,15 +718,15 @@ OPTIONS $ hledger -f t.j bal -N euros -V -e 2016/11/4 $110.00 assets:euros - What are they worth after 2016/12/21 ? (no report end date specified, + What are they worth after 2016/12/21 ? (no report end date specified, defaults to today) $ hledger -f t.j bal -N euros -V $103.00 assets:euros -X: Market value in specified commodity - The -X/--exchange option is like -V, except it specifies the target - commodity you would like to convert to. It is equivalent to + The -X/--exchange option is like -V, except it specifies the target + commodity you would like to convert to. It is equivalent to --value=now,COMM or --value=end,COMM. --value: Flexible valuation @@ -751,43 +746,43 @@ OPTIONS valuation date: --value=cost - Convert amounts to cost, using the prices recorded in transac- + Convert amounts to cost, using the prices recorded in transac- tions. --value=end Convert amounts to their value in a default valuation commodity, - using market prices on the last day of the report period (or if + using market prices on the last day of the report period (or if unspecified, the journal's end date); or in multiperiod reports, market prices on the last day of each subperiod. --value=now - Convert amounts to their value in default valuation commodity + Convert amounts to their value in default valuation commodity using current market prices (as of when report is generated). --value=YYYY-MM-DD - Convert amounts to their value in default valuation commodity + Convert amounts to their value in default valuation commodity using market prices on this date. - The default valuation commodity is the commodity mentioned in the most + The default valuation commodity is the commodity mentioned in the most recent applicable market price declaration. When all your price decla- - rations lead to a single home currency, this will usually do what you + rations lead to a single home currency, this will usually do what you want. To select a different valuation commodity, add the optional ,COMM part: - a comma, then the target commodity's symbol. Eg: --value=now,EUR. + a comma, then the target commodity's symbol. Eg: --value=now,EUR. hledger will do its best to convert amounts to this commodity, using: o declared prices (from source commodity to valuation commodity) - o reverse prices (declared prices from valuation to source commodity, + o reverse prices (declared prices from valuation to source commodity, inverted) - o indirect prices (prices calculated from the shortest chain of de- + o indirect prices (prices calculated from the shortest chain of de- clared or reverse prices from source to valuation commodity) in that order. - Here are some examples showing the effect of --value as seen with + Here are some examples showing the effect of --value as seen with print: P 2000-01-01 A 1 B @@ -825,7 +820,7 @@ OPTIONS 2000-02-01 (a) 2 B - With no report period specified, that shows the value as of the last + With no report period specified, that shows the value as of the last day of the journal (2000-03-01): $ hledger -f- print --value=end @@ -862,7 +857,7 @@ OPTIONS 2000/03/01 (a) 1 B - You may need to explicitly set a commodity's display style, when re- + You may need to explicitly set a commodity's display style, when re- verse prices are used. Eg this output might be surprising: P 2000-01-01 A 2B @@ -876,10 +871,10 @@ OPTIONS a 0 b 0 - Explanation: because there's no amount or commodity directive specify- - ing a display style for A, 0.5A gets the default style, which shows no + Explanation: because there's no amount or commodity directive specify- + ing a display style for A, 0.5A gets the default style, which shows no decimal digits. Because the displayed amount looks like zero, the com- - modity symbol and minus sign are not displayed either. Adding a com- + modity symbol and minus sign are not displayed either. Adding a com- modity directive sets a more useful display style for A: P 2000-01-01 A 2B @@ -895,10 +890,10 @@ OPTIONS b -0.50A Effect of --value on reports - Here is a reference for how --value currently affects each part of - hledger's reports. It's work in progress, but may be useful for trou- - bleshooting or reporting bugs. See also the definitions and notes be- - low. If you find problems, please report them, ideally with a repro- + Here is a reference for how --value currently affects each part of + hledger's reports. It's work in progress, but may be useful for trou- + bleshooting or reporting bugs. See also the definitions and notes be- + low. If you find problems, please report them, ideally with a repro- ducible example. Related: #329, #1083. Report type -B, -V, -X --value=end --value=DATE, @@ -908,11 +903,11 @@ OPTIONS posting cost value at report value at report value at amounts end or today or journal end DATE/today balance asser- unchanged unchanged unchanged unchanged - tions / as- + tions / as- signments register - starting bal- cost value at day value at day value at + starting bal- cost value at day value at day value at ance (with -H) before report before report DATE/today or journal or journal start start @@ -931,28 +926,27 @@ OPTIONS balance (bs, bse, cf, is..) balances (no sums of costs value at report value at report value at - report inter- end or today of or journal end DATE/today of - val) sums of post- of sums of sums of post- + report inter- end or today of or journal end DATE/today of + val) sums of post- of sums of sums of post- ings postings ings balances (with sums of costs value at period value at period value at report inter- ends of sums of ends of sums of DATE/today of val) postings postings sums of post- ings - starting bal- sums of costs sums of post- sums of post- sums of post- + starting bal- sums of costs sums of post- sums of post- sums of post- ances (with of postings ings before re- ings before re- ings before report inter- before report port start port start report start val and -H) start budget amounts like balances like balances like balances like balances with --budget - grand total sum of dis- sum of dis- sum of dis- sum of dis- + grand total sum of dis- sum of dis- sum of dis- sum of dis- (no report in- played values played values played values played values terval) - row totals/av- sums/averages sums/averages sums/averages sums/averages erages (with of displayed of displayed of displayed of displayed report inter- values values values values val) - column totals sums of dis- sums of dis- sums of dis- sums of dis- + column totals sums of dis- sums of dis- sums of dis- sums of dis- played values played values played values played values grand to- sum/average of sum/average of sum/average of sum/average tal/average column totals column totals column totals of column to- @@ -963,29 +957,29 @@ OPTIONS cost calculated using price(s) recorded in the transaction(s). - value market value using available market price declarations, or the + value market value using available market price declarations, or the unchanged amount if no conversion rate can be found. report start - the first day of the report period specified with -b or -p or + the first day of the report period specified with -b or -p or date:, otherwise today. report or journal start - the first day of the report period specified with -b or -p or - date:, otherwise the earliest transaction date in the journal, + the first day of the report period specified with -b or -p or + date:, otherwise the earliest transaction date in the journal, otherwise today. report end - the last day of the report period specified with -e or -p or + the last day of the report period specified with -e or -p or date:, otherwise today. report or journal end - the last day of the report period specified with -e or -p or - date:, otherwise the latest transaction date in the journal, + the last day of the report period specified with -e or -p or + date:, otherwise the latest transaction date in the journal, otherwise today. report interval - a flag (-D/-W/-M/-Q/-Y) or period expression that activates the + a flag (-D/-W/-M/-Q/-Y) or period expression that activates the report's multi-period mode (whether showing one or many subperi- ods). @@ -993,16 +987,16 @@ OPTIONS The rightmost of these flags wins. Output destination - Some commands (print, register, stats, the balance commands) can write - their output to a destination other than the console. This is con- + Some commands (print, register, stats, the balance commands) can write + their output to a destination other than the console. This is con- trolled by the -o/--output-file option. $ hledger balance -o - # write to stdout (the default) $ hledger balance -o FILE # write to FILE Output format - Some commands can write their output in other formats. Eg print and - register can output CSV, and the balance commands can output CSV or + Some commands can write their output in other formats. Eg print and + register can output CSV, and the balance commands can output CSV or HTML. This is controlled by the -O/--output-format option, or by spec- ifying a .csv or .html file extension with -o/--output-file. @@ -1012,56 +1006,56 @@ OPTIONS Regular expressions hledger uses regular expressions in a number of places: - o query terms, on the command line and in the hledger-web search form: + o query terms, on the command line and in the hledger-web search form: REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX o CSV rules conditional blocks: if REGEX ... - o account alias directives and options: alias /REGEX/ = REPLACEMENT, + o account alias directives and options: alias /REGEX/ = REPLACEMENT, --alias /REGEX/=REPLACEMENT - hledger's regular expressions come from the regex-tdfa library. In + hledger's regular expressions come from the regex-tdfa library. In general they: o are case insensitive - o are infix matching (do not need to match the entire thing being + o are infix matching (do not need to match the entire thing being matched) o are POSIX extended regular expressions o also support GNU word boundaries (\<, \>, \b, \B) - o and parenthesised capturing groups and numeric backreferences in re- + o and parenthesised capturing groups and numeric backreferences in re- placement strings o do not support mode modifiers like (?s) Some things to note: - o In the alias directive and --alias option, regular expressions must - be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, + o In the alias directive and --alias option, regular expressions must + be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required. - o In queries, to match a regular expression metacharacter like $ as a - literal character, prepend a backslash. Eg to search for amounts + o In queries, to match a regular expression metacharacter like $ as a + literal character, prepend a backslash. Eg to search for amounts with the dollar sign in hledger-web, write cur:\$. - o On the command line, some metacharacters like $ have a special mean- + o On the command line, some metacharacters like $ have a special mean- ing to the shell and so must be escaped at least once more. See Spe- cial characters. QUERIES - One of hledger's strengths is being able to quickly report on precise - subsets of your data. Most commands accept an optional query expres- - sion, written as arguments after the command name, to filter the data - by date, account name or other criteria. The syntax is similar to a + One of hledger's strengths is being able to quickly report on precise + subsets of your data. Most commands accept an optional query expres- + sion, written as arguments after the command name, to filter the data + by date, account name or other criteria. The syntax is similar to a web search: one or more space-separated search terms, quotes to enclose - whitespace, prefixes to match specific fields, a not: prefix to negate + whitespace, prefixes to match specific fields, a not: prefix to negate the match. - We do not yet support arbitrary boolean combinations of search terms; - instead most commands show transactions/postings/accounts which match + We do not yet support arbitrary boolean combinations of search terms; + instead most commands show transactions/postings/accounts which match (or negatively match): o any of the description terms AND @@ -1082,31 +1076,31 @@ QUERIES o match all the other terms. - The following kinds of search terms can be used. Remember these can + The following kinds of search terms can be used. Remember these can also be prefixed with not:, eg to exclude a particular subaccount. REGEX, acct:REGEX - match account names by this regular expression. (With no pre- + match account names by this regular expression. (With no pre- fix, acct: is assumed.) same as above amt:N, amt:N, amt:>=N - match postings with a single-commodity amount that is equal to, - less than, or greater than N. (Multi-commodity amounts are not + match postings with a single-commodity amount that is equal to, + less than, or greater than N. (Multi-commodity amounts are not tested, and will always match.) The comparison has two modes: if N is preceded by a + or - sign (or is 0), the two signed numbers - are compared. Otherwise, the absolute magnitudes are compared, + are compared. Otherwise, the absolute magnitudes are compared, ignoring sign. code:REGEX match by transaction code (eg check number) cur:REGEX - match postings or transactions including any amounts whose cur- - rency/commodity symbol is fully matched by REGEX. (For a par- + match postings or transactions including any amounts whose cur- + rency/commodity symbol is fully matched by REGEX. (For a par- tial match, use .*REGEX.*). Note, to match characters which are regex-significant, like the dollar sign ($), you need to prepend - \. And when using the command line you need to add one more - level of quoting to hide it from the shell, so eg do: hledger + \. And when using the command line you need to add one more + level of quoting to hide it from the shell, so eg do: hledger print cur:'\$' or hledger print cur:\\$. desc:REGEX @@ -1114,20 +1108,20 @@ QUERIES date:PERIODEXPR match dates within the specified period. PERIODEXPR is a period - expression (with no report interval). Examples: date:2016, - date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the - --date2 command line flag is present, this matches secondary + expression (with no report interval). Examples: date:2016, + date:thismonth, date:2000/2/1-2/15, date:lastweek-. If the + --date2 command line flag is present, this matches secondary dates instead. date2:PERIODEXPR match secondary dates within the specified period. depth:N - match (or display, depending on command) accounts at or above + match (or display, depending on command) accounts at or above this depth note:REGEX - match transaction notes (part of description right of |, or + match transaction notes (part of description right of |, or whole description when there's no |) payee:REGEX @@ -1141,51 +1135,53 @@ QUERIES match unmarked, pending, or cleared transactions respectively tag:REGEX[=REGEX] - match by tag name, and optionally also by tag value. Note a - tag: query is considered to match a transaction if it matches - any of the postings. Also remember that postings inherit the + match by tag name, and optionally also by tag value. Note a + tag: query is considered to match a transaction if it matches + any of the postings. Also remember that postings inherit the tags of their parent transaction. The following special search term is used automatically in hledger-web, only: inacct:ACCTNAME - tells hledger-web to show the transaction register for this ac- + tells hledger-web to show the transaction register for this ac- count. Can be filtered further with acct etc. Some of these can also be expressed as command-line options (eg depth:2 - is equivalent to --depth 2). Generally you can mix options and query - arguments, and the resulting query will be their intersection (perhaps + is equivalent to --depth 2). Generally you can mix options and query + arguments, and the resulting query will be their intersection (perhaps excluding the -p/--period option). COMMANDS - hledger provides a number of subcommands; hledger with no arguments + hledger provides a number of subcommands; hledger with no arguments shows a list. If you install additional hledger-* packages, or if you put programs or - scripts named hledger-NAME in your PATH, these will also be listed as + scripts named hledger-NAME in your PATH, these will also be listed as subcommands. - Run a subcommand by writing its name as first argument (eg hledger in- - comestatement). You can also write one of the standard short aliases - displayed in parentheses in the command list (hledger b), or any any + Run a subcommand by writing its name as first argument (eg hledger in- + comestatement). You can also write one of the standard short aliases + displayed in parentheses in the command list (hledger b), or any any unambiguous prefix of a command name (hledger inc). - Here are all the builtin commands in alphabetical order. See also - hledger for a more organised command list, and hledger CMD -h for de- + Here are all the builtin commands in alphabetical order. See also + hledger for a more organised command list, and hledger CMD -h for de- tailed command help. accounts accounts, a Show account names. - This command lists account names, either declared with account direc- - tives (--declared), posted to (--used), or both (the default). With - query arguments, only matched account names and account names refer- - enced by matched postings are shown. It shows a flat list by default. - With --tree, it uses indentation to show the account hierarchy. In - flat mode you can add --drop N to omit the first few account name com- - ponents. Account names can be depth-clipped with depth:N or --depth N + $FLAGS$ + + This command lists account names, either declared with account direc- + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N or -N. Examples: @@ -1204,8 +1200,10 @@ COMMANDS activity Show an ascii barchart of posting counts per interval. - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the + $FLAGS$ + + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. Examples: @@ -1220,22 +1218,24 @@ COMMANDS add Prompt for transactions and add them to the journal. - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- + $FLAGS$ + + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- actions, and appends them to the journal file (if there are multiple -f - FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal + FILE options, the first file is used.) Existing transactions are not + changed. This is the only hledger command that writes to the journal file. To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar (by de- - scription) recent transaction (filtered by the query, if any) as a + o add tries to provide useful defaults, using the most similar (by de- + scription) recent transaction (filtered by the query, if any) as a template. o You can also set the initial defaults with command line arguments. @@ -1243,18 +1243,17 @@ COMMANDS o Readline-style edit keys can be used during data entry. o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is + tions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any + o If the journal defines a default commodity, it will be added to any bare numbers entered. o A parenthesised transaction code may be entered following a date. o Comments and tags may be entered following a description or amount. - o If you make a mistake, enter < at any prompt to go one step - backward. + o If you make a mistake, enter < at any prompt to go one step backward. o Input prompts are displayed in a different colour when the terminal supports it. @@ -1294,6 +1293,8 @@ COMMANDS balance, bal, b Show accounts and their balances. + $FLAGS$ + 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 @@ -1723,7 +1724,7 @@ COMMANDS liabilities With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which implicity + budget for personal expenses is an additional $1000, which implicitly means that budget for both expenses:personal and expenses is $1100. Transactions in expenses:personal:electronics will be counted both to- @@ -1804,6 +1805,8 @@ COMMANDS (like conventional financial statements, unlike balance/print/register) (experimental). + $FLAGS$ + Example: $ hledger balancesheet @@ -1842,6 +1845,8 @@ COMMANDS Just like balancesheet, but also reports Equity (which it assumes is under a top-level equity account). + $FLAGS$ + Example: $ hledger balancesheetequity @@ -1877,6 +1882,8 @@ COMMANDS account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). + $FLAGS$ + Example: $ hledger cashflow @@ -1909,12 +1916,16 @@ COMMANDS unique. With a query, only matched transactions' dates are checked. Reads the default journal file, or another specified with -f. + $FLAGS$ + check-dupes check-dupes Reports account names having the same leaf but different prefixes. In other words, two or more leaves that are categorized differently. Reads the default journal file, or another specified as an argument. + $FLAGS$ + An example: http://stefanorodighiero.net/software/hledger-dupes.html close @@ -1925,6 +1936,8 @@ COMMANDS file, or for closing out revenues/expenses to retained earnings at the end of a period. + $FLAGS$ + The closing transaction transfers balances to "equity:closing bal- ances", and the opening transaction transfers balances from "eq- uity:opening balances", or you can customise these with the --close-to @@ -2005,9 +2018,13 @@ COMMANDS commodities List all commodity/currency symbols used or declared in the journal. + $FLAGS$ + descriptions descriptions Show descriptions. + $FLAGS$ + This command lists all descriptions that appear in transactions. Examples: @@ -2034,6 +2051,8 @@ COMMANDS the account balance, you can compare the bank data with your journal to find out the cause. + $FLAGS$ + Examples: $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro @@ -2051,10 +2070,14 @@ COMMANDS List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. + $FLAGS$ + help help Show any of the hledger manuals. + $FLAGS$ + 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. @@ -2093,6 +2116,8 @@ COMMANDS tions that would be added. Or with --catchup, just mark all of the FILEs' transactions as imported, without actually importing any. + $FLAGS$ + The input files are specified as arguments - no need to write -f before each one. So eg to add new transactions from all CSV files to the main journal, it's just: hledger import *.csv @@ -2129,6 +2154,8 @@ COMMANDS with normal positive sign (like conventional financial statements, un- like balance/print/register) (experimental). + $FLAGS$ + 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.) @@ -2166,6 +2193,8 @@ COMMANDS notes notes Show notes. + $FLAGS$ + This command lists all notes that appear in transactions. Examples: @@ -2177,6 +2206,8 @@ COMMANDS payees payees Show payee names. + $FLAGS$ + This command lists all payee names that appear in transactions. Examples: @@ -2194,10 +2225,14 @@ COMMANDS Prices (and postings providing prices) can be filtered by a query. Price amounts are always displayed with their full precision. + $FLAGS$ + print print, txns, p Show transaction journal entries, sorted by date. + $FLAGS$ + The print command displays full journal entries (transactions) from the journal file in date order, tidily formatted. With --date2, transac- tions are sorted by secondary date instead. @@ -2298,6 +2333,8 @@ COMMANDS print-unique Print transactions which do not reuse an already-seen description. + $FLAGS$ + Example: $ cat unique.journal @@ -2314,6 +2351,8 @@ COMMANDS register, reg, r Show postings and their running total. + $FLAGS$ + The register command displays postings in date order, one per line, and their running total. This is typically used with a query selecting a particular account, to see that account's activity: @@ -2424,12 +2463,16 @@ COMMANDS arguments) can be used to restrict the search space. Helps ledger-au- tosync detect already-seen transactions when importing. + $FLAGS$ + rewrite rewrite Print all transactions, rewriting the postings of matched transactions. For now the only rewrite available is adding new postings, like print --auto. + $FLAGS$ + This is a start at a generic rewriter of transaction entries. It reads the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The @@ -2554,6 +2597,8 @@ COMMANDS Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. + $FLAGS$ + This command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) @@ -2576,6 +2621,8 @@ COMMANDS stats Show some journal statistics. + $FLAGS$ + 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. @@ -2606,10 +2653,14 @@ COMMANDS considered. With --values flag, the tags' unique values are listed in- stead. + $FLAGS$ + test test Run built-in unit tests. + $FLAGS$ + This command runs the unit tests built in to hledger and hledger-lib, printing the results on stdout. If any test fails, the exit code will be non-zero. @@ -2668,10 +2719,6 @@ ADD-ON COMMANDS These are maintained separately, and usually updated shortly after a hledger release. - diff - hledger-diff shows differences in an account's transactions between one - journal file and another. - iadd hledger-iadd is a more interactive, terminal UI replacement for the add command. @@ -2680,10 +2727,6 @@ ADD-ON COMMANDS hledger-interest generates interest transactions for an account accord- ing to various schemes. - irr - hledger-irr calculates the internal rate of return of an investment ac- - count, 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- tory. They may be less mature and documented than built-in commands. @@ -2696,10 +2739,7 @@ ADD-ON COMMANDS offers OFX Direct Connect. chart - hledger-chart.hs is an old pie chart generator, in need of some love. - - check - hledger-check.hs checks more powerful account balance assertions. + hledger-chart.hs is an old very basic pie chart generator. ENVIRONMENT COLUMNS The screen width used by the register command. Default: the