From 12853b1fdaaf324f3af35734ff82e3a79d5e9e2a Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 16 Mar 2023 21:53:37 -1000 Subject: [PATCH] ;doc: update manuals --- hledger/hledger.1 | 28 +++ hledger/hledger.info | 455 ++++++++++++++++++---------------- hledger/hledger.txt | 568 ++++++++++++++++++++++--------------------- 3 files changed, 565 insertions(+), 486 deletions(-) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 25b590376..1955b1709 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -8062,6 +8062,8 @@ test - run self tests .SS HELP .IP \[bu] 2 help - show the hledger manual with info/man/pager +.IP \[bu] 2 +demo - show small hledger demos in the terminal .PP .SS ADD-ONS .PP @@ -10201,6 +10203,32 @@ $ hledger codes -E .SS commodities .PP List all commodity/currency symbols used or declared in the journal. +.SS demo +.PP +Play small demos of hledger usage in the terminal. +.PP +Run this command with no argument to list the demos. +To play a demo, write its number or name or a substring. +asciinema must be installed. +.PP +During playback, several keys are available: - SPACE pause/unpause - . +step forward (while paused) - CTRL-c quit early +.PP +asciinema options can be added following a double-dash; list them with +\f[V]asciinema -h\f[R]. +\f[V]-s\f[R] (speed) and \f[V]-i\f[R] (max idle time) are particularly +useful. +.PP +Examples: +.IP +.nf +\f[C] +$ hledger demo # list available demos +$ hledger demo 1 # play the first demo +$ hledger demo install -s5 -i.5 # play the demo named or containing \[dq]install\[dq], + # at 5x speed, limiting idle time to 0.5s. +\f[R] +.fi .SS descriptions .PP List the unique descriptions that appear in transactions. diff --git a/hledger/hledger.info b/hledger/hledger.info index 3d16a6df3..e875f8c25 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -6881,6 +6881,7 @@ File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: V * close:: * codes:: * commodities:: +* demo:: * descriptions:: * diff:: * files:: @@ -6998,6 +6999,7 @@ File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Comm ----------- • help - show the hledger manual with info/man/pager + • demo - show small hledger demos in the terminal  File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview @@ -8894,7 +8896,7 @@ $ hledger codes -E 126  -File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: PART 4 COMMANDS +File: hledger.info, Node: commodities, Next: demo, Prev: codes, Up: PART 4 COMMANDS 24.13 commodities ================= @@ -8902,9 +8904,34 @@ File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: List all commodity/currency symbols used or declared in the journal.  -File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: PART 4 COMMANDS +File: hledger.info, Node: demo, Next: descriptions, Prev: commodities, Up: PART 4 COMMANDS -24.14 descriptions +24.14 demo +========== + +Play small demos of hledger usage in the terminal. + + Run this command with no argument to list the demos. To play a demo, +write its number or name or a substring. asciinema must be installed. + + During playback, several keys are available: - SPACE pause/unpause - +. step forward (while paused) - CTRL-c quit early + + asciinema options can be added following a double-dash; list them +with ‘asciinema -h’. ‘-s’ (speed) and ‘-i’ (max idle time) are +particularly useful. + + Examples: + +$ hledger demo # list available demos +$ hledger demo 1 # play the first demo +$ hledger demo install -s5 -i.5 # play the demo named or containing "install", + # at 5x speed, limiting idle time to 0.5s. + + +File: hledger.info, Node: descriptions, Next: diff, Prev: demo, Up: PART 4 COMMANDS + +24.15 descriptions ================== List the unique descriptions that appear in transactions. @@ -8923,7 +8950,7 @@ Person A  File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS -24.15 diff +24.16 diff ========== Compares a particular account’s transactions in two input files. It @@ -8957,7 +8984,7 @@ These transactions are in the second file only:  File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS -24.16 files +24.17 files =========== List all files included in the journal. With a REGEX argument, only @@ -8966,7 +8993,7 @@ file names matching the regular expression (case sensitive) are shown.  File: hledger.info, Node: help, Next: import, Prev: files, Up: PART 4 COMMANDS -24.17 help +24.18 help ========== Show the hledger user manual in the terminal, with ‘info’, ‘man’, or a @@ -8993,7 +9020,7 @@ $ hledger help journal # show the journal topic in the hledger manual  File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS -24.18 import +24.19 import ============ Read new transactions added to each FILE since last run, and add them to @@ -9025,7 +9052,7 @@ most common import source, and these docs focus on that case.  File: hledger.info, Node: Deduplication, Next: Import testing, Up: import -24.18.1 Deduplication +24.19.1 Deduplication --------------------- As a convenience ‘import’ does _deduplication_ while reading @@ -9069,7 +9096,7 @@ certain date.  File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import -24.18.2 Import testing +24.19.2 Import testing ---------------------- With ‘--dry-run’, the transactions that will be imported are printed to @@ -9094,7 +9121,7 @@ import.  File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import -24.18.3 Importing balance assignments +24.19.3 Importing balance assignments ------------------------------------- Entries added by import will have their posting amounts made explicit @@ -9113,7 +9140,7 @@ please test it and send a pull request.)  File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import -24.18.4 Commodity display styles +24.19.4 Commodity display styles -------------------------------- Imported amounts will be formatted according to the canonical commodity @@ -9122,7 +9149,7 @@ styles (declared or inferred) in the main journal file.  File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS -24.19 incomestatement +24.20 incomestatement ===================== (is) @@ -9172,7 +9199,7 @@ options The output formats supported are ‘txt’, ‘csv’, ‘html’, and  File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS -24.20 notes +24.21 notes =========== List the unique notes that appear in transactions. @@ -9191,7 +9218,7 @@ Snacks  File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS -24.21 payees +24.22 payees ============ List the unique payee/payer names that appear in transactions. @@ -9216,7 +9243,7 @@ Person A  File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS -24.22 prices +24.23 prices ============ Print market price directives from the journal. With @@ -9228,7 +9255,7 @@ displayed with their full precision.  File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS -24.23 print +24.24 print =========== Show transaction journal entries, sorted by date. @@ -9352,7 +9379,7 @@ $ hledger print -Ocsv  File: hledger.info, Node: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS -24.24 register +24.25 register ============== (reg) @@ -9462,7 +9489,7 @@ no posting will be shown and the program exit code will be non-zero.  File: hledger.info, Node: Custom register output, Up: register -24.24.1 Custom register output +24.25.1 Custom register output ------------------------------ register uses the full terminal width by default, except on windows. @@ -9494,7 +9521,7 @@ options The output formats supported are ‘txt’, ‘csv’, and  File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS -24.25 rewrite +24.26 rewrite ============= Print all transactions, rewriting the postings of matched transactions. @@ -9547,7 +9574,7 @@ commodity.  File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite -24.25.1 Re-write rules in a file +24.26.1 Re-write rules in a file -------------------------------- During the run this tool will execute so called "Automated Transactions" @@ -9585,7 +9612,7 @@ postings.  File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite -24.25.2 Diff output format +24.26.2 Diff output format -------------------------- To use this tool for batch modification of your journal files you may @@ -9626,7 +9653,7 @@ output from ‘hledger print’.  File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite -24.25.3 rewrite vs. print –auto +24.26.3 rewrite vs. print –auto ------------------------------- This command predates print –auto, and currently does much the same @@ -9646,7 +9673,7 @@ thing, but with these differences:  File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: PART 4 COMMANDS -24.26 roi +24.27 roi ========= Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on @@ -9694,7 +9721,7 @@ display, regardless of the length of reporting interval.  File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi -24.26.1 Spaces and special characters in ‘--inv’ and +24.27.1 Spaces and special characters in ‘--inv’ and ---------------------------------------------------- ‘--pnl’ Note that ‘--inv’ and ‘--pnl’’s argument is a query, and queries @@ -9713,7 +9740,7 @@ $ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'  File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi -24.26.2 Semantics of ‘--inv’ and ‘--pnl’ +24.27.2 Semantics of ‘--inv’ and ‘--pnl’ ---------------------------------------- Query supplied to ‘--inv’ has to match all transactions that are related @@ -9767,7 +9794,7 @@ postings in the example below would be classifed as:  File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi -24.26.3 IRR and TWR explained +24.27.3 IRR and TWR explained ----------------------------- "ROI" stands for "return on investment". Traditionally this was @@ -9834,7 +9861,7 @@ your investment.  File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS -24.27 stats +24.28 stats =========== Show journal and performance statistics. @@ -9874,7 +9901,7 @@ Throughput : 8342 txns/s  File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS -24.28 tags +24.29 tags ========== List the tags used in the journal, or their values. @@ -9904,7 +9931,7 @@ transactions also acquire tags from their postings.  File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS -24.29 test +24.30 test ========== Run built-in unit tests. @@ -10776,190 +10803,192 @@ Node: Effect of valuation on reports239415 Ref: #effect-of-valuation-on-reports239612 Node: PART 4 COMMANDS247371 Ref: #part-4-commands247514 -Node: Commands overview247884 -Ref: #commands-overview248018 -Node: DATA ENTRY248197 -Ref: #data-entry248321 -Node: DATA CREATION248524 -Ref: #data-creation248678 -Node: DATA MANAGEMENT248802 -Ref: #data-management248967 -Node: REPORTS FINANCIAL249092 -Ref: #reports-financial249267 -Node: REPORTS VERSATILE249582 -Ref: #reports-versatile249755 -Node: REPORTS BASIC250016 -Ref: #reports-basic250168 -Node: HELP250701 -Ref: #help250823 -Node: ADD-ONS250882 -Ref: #add-ons250988 -Node: accounts251585 -Ref: #accounts251718 -Node: activity253693 -Ref: #activity253812 -Node: add254186 -Ref: #add254296 -Node: aregister257157 -Ref: #aregister257278 -Node: aregister and custom posting dates260254 -Ref: #aregister-and-custom-posting-dates260420 -Node: balance260988 -Ref: #balance261114 -Node: balance features262119 -Ref: #balance-features262259 -Node: Simple balance report264389 -Ref: #simple-balance-report264574 -Node: Balance report line format266219 -Ref: #balance-report-line-format266421 -Node: Filtered balance report268671 -Ref: #filtered-balance-report268863 -Node: List or tree mode269190 -Ref: #list-or-tree-mode269358 -Node: Depth limiting270733 -Ref: #depth-limiting270899 -Node: Dropping top-level accounts271516 -Ref: #dropping-top-level-accounts271716 -Node: Showing declared accounts272030 -Ref: #showing-declared-accounts272229 -Node: Sorting by amount272770 -Ref: #sorting-by-amount272937 -Node: Percentages273627 -Ref: #percentages273786 -Node: Multi-period balance report274356 -Ref: #multi-period-balance-report274556 -Node: Balance change end balance276949 -Ref: #balance-change-end-balance277158 -Node: Balance report types278606 -Ref: #balance-report-types278787 -Node: Calculation type279303 -Ref: #calculation-type279458 -Node: Accumulation type279989 -Ref: #accumulation-type280169 -Node: Valuation type281097 -Ref: #valuation-type281285 -Node: Combining balance report types282352 -Ref: #combining-balance-report-types282546 -Node: Budget report284450 -Ref: #budget-report284602 -Node: Budget report start date290336 -Ref: #budget-report-start-date290514 -Node: Budgets and subaccounts291876 -Ref: #budgets-and-subaccounts292083 -Node: Selecting budget goals295569 -Ref: #selecting-budget-goals295768 -Node: Budget vs forecast296815 -Ref: #budget-vs-forecast296974 -Node: Data layout298674 -Ref: #data-layout298824 -Node: Useful balance reports306765 -Ref: #useful-balance-reports306915 -Node: balancesheet308068 -Ref: #balancesheet308213 -Node: balancesheetequity309579 -Ref: #balancesheetequity309737 -Node: cashflow311180 -Ref: #cashflow311311 -Node: check312797 -Ref: #check312911 -Node: Basic checks313717 -Ref: #basic-checks313837 -Node: Strict checks314375 -Ref: #strict-checks314518 -Node: Other checks314959 -Ref: #other-checks315101 -Node: Custom checks315678 -Ref: #custom-checks315835 -Node: More about specific checks316256 -Ref: #more-about-specific-checks316418 -Node: close317150 -Ref: #close317261 -Node: close and costs319647 -Ref: #close-and-costs319791 -Node: close and balance assertions320080 -Ref: #close-and-balance-assertions320282 -Node: Example retain earnings321453 -Ref: #example-retain-earnings321670 -Node: Example migrate balances to a new file322028 -Ref: #example-migrate-balances-to-a-new-file322293 -Node: Example excluding closing/opening transactions322846 -Ref: #example-excluding-closingopening-transactions323095 -Node: codes324273 -Ref: #codes324390 -Node: commodities325266 -Ref: #commodities325402 -Node: descriptions325472 -Ref: #descriptions325609 -Node: diff325900 -Ref: #diff326015 -Node: files327061 -Ref: #files327170 -Node: help327311 -Ref: #help-1327420 -Node: import328410 -Ref: #import328533 -Node: Deduplication329641 -Ref: #deduplication329766 -Node: Import testing331688 -Ref: #import-testing331853 -Node: Importing balance assignments332704 -Ref: #importing-balance-assignments332910 -Node: Commodity display styles333567 -Ref: #commodity-display-styles333740 -Node: incomestatement333869 -Ref: #incomestatement334011 -Node: notes335378 -Ref: #notes335500 -Node: payees335862 -Ref: #payees335977 -Node: prices336502 -Ref: #prices336617 -Node: print336919 -Ref: #print337034 -Node: register342480 -Ref: #register342602 -Node: Custom register output347711 -Ref: #custom-register-output347842 -Node: rewrite349217 -Ref: #rewrite349335 -Node: Re-write rules in a file351247 -Ref: #re-write-rules-in-a-file351410 -Node: Diff output format352563 -Ref: #diff-output-format352746 -Node: rewrite vs print --auto353858 -Ref: #rewrite-vs.-print---auto354020 -Node: roi354594 -Ref: #roi354701 -Node: Spaces and special characters in --inv and --pnl356462 -Ref: #spaces-and-special-characters-in---inv-and---pnl356710 -Node: Semantics of --inv and --pnl357208 -Ref: #semantics-of---inv-and---pnl357455 -Node: IRR and TWR explained359333 -Ref: #irr-and-twr-explained359493 -Node: stats362605 -Ref: #stats362713 -Node: tags364110 -Ref: #tags-1364217 -Node: test365234 -Ref: #test365327 -Node: PART 5 COMMON TASKS366077 -Ref: #part-5-common-tasks366210 -Node: Getting help366484 -Ref: #getting-help366625 -Node: Constructing command lines367389 -Ref: #constructing-command-lines367590 -Node: Starting a journal file368271 -Ref: #starting-a-journal-file368478 -Node: Setting opening balances369676 -Ref: #setting-opening-balances369881 -Node: Recording transactions373034 -Ref: #recording-transactions373223 -Node: Reconciling373779 -Ref: #reconciling373931 -Node: Reporting376244 -Ref: #reporting376393 -Node: Migrating to a new file380382 -Ref: #migrating-to-a-new-file380539 +Node: Commands overview247893 +Ref: #commands-overview248027 +Node: DATA ENTRY248206 +Ref: #data-entry248330 +Node: DATA CREATION248533 +Ref: #data-creation248687 +Node: DATA MANAGEMENT248811 +Ref: #data-management248976 +Node: REPORTS FINANCIAL249101 +Ref: #reports-financial249276 +Node: REPORTS VERSATILE249591 +Ref: #reports-versatile249764 +Node: REPORTS BASIC250025 +Ref: #reports-basic250177 +Node: HELP250710 +Ref: #help250832 +Node: ADD-ONS250946 +Ref: #add-ons251052 +Node: accounts251649 +Ref: #accounts251782 +Node: activity253757 +Ref: #activity253876 +Node: add254250 +Ref: #add254360 +Node: aregister257221 +Ref: #aregister257342 +Node: aregister and custom posting dates260318 +Ref: #aregister-and-custom-posting-dates260484 +Node: balance261052 +Ref: #balance261178 +Node: balance features262183 +Ref: #balance-features262323 +Node: Simple balance report264453 +Ref: #simple-balance-report264638 +Node: Balance report line format266283 +Ref: #balance-report-line-format266485 +Node: Filtered balance report268735 +Ref: #filtered-balance-report268927 +Node: List or tree mode269254 +Ref: #list-or-tree-mode269422 +Node: Depth limiting270797 +Ref: #depth-limiting270963 +Node: Dropping top-level accounts271580 +Ref: #dropping-top-level-accounts271780 +Node: Showing declared accounts272094 +Ref: #showing-declared-accounts272293 +Node: Sorting by amount272834 +Ref: #sorting-by-amount273001 +Node: Percentages273691 +Ref: #percentages273850 +Node: Multi-period balance report274420 +Ref: #multi-period-balance-report274620 +Node: Balance change end balance277013 +Ref: #balance-change-end-balance277222 +Node: Balance report types278670 +Ref: #balance-report-types278851 +Node: Calculation type279367 +Ref: #calculation-type279522 +Node: Accumulation type280053 +Ref: #accumulation-type280233 +Node: Valuation type281161 +Ref: #valuation-type281349 +Node: Combining balance report types282416 +Ref: #combining-balance-report-types282610 +Node: Budget report284514 +Ref: #budget-report284666 +Node: Budget report start date290400 +Ref: #budget-report-start-date290578 +Node: Budgets and subaccounts291940 +Ref: #budgets-and-subaccounts292147 +Node: Selecting budget goals295633 +Ref: #selecting-budget-goals295832 +Node: Budget vs forecast296879 +Ref: #budget-vs-forecast297038 +Node: Data layout298738 +Ref: #data-layout298888 +Node: Useful balance reports306829 +Ref: #useful-balance-reports306979 +Node: balancesheet308132 +Ref: #balancesheet308277 +Node: balancesheetequity309643 +Ref: #balancesheetequity309801 +Node: cashflow311244 +Ref: #cashflow311375 +Node: check312861 +Ref: #check312975 +Node: Basic checks313781 +Ref: #basic-checks313901 +Node: Strict checks314439 +Ref: #strict-checks314582 +Node: Other checks315023 +Ref: #other-checks315165 +Node: Custom checks315742 +Ref: #custom-checks315899 +Node: More about specific checks316320 +Ref: #more-about-specific-checks316482 +Node: close317214 +Ref: #close317325 +Node: close and costs319711 +Ref: #close-and-costs319855 +Node: close and balance assertions320144 +Ref: #close-and-balance-assertions320346 +Node: Example retain earnings321517 +Ref: #example-retain-earnings321734 +Node: Example migrate balances to a new file322092 +Ref: #example-migrate-balances-to-a-new-file322357 +Node: Example excluding closing/opening transactions322910 +Ref: #example-excluding-closingopening-transactions323159 +Node: codes324337 +Ref: #codes324454 +Node: commodities325330 +Ref: #commodities325458 +Node: demo325528 +Ref: #demo325649 +Node: descriptions326419 +Ref: #descriptions326549 +Node: diff326840 +Ref: #diff326955 +Node: files328001 +Ref: #files328110 +Node: help328251 +Ref: #help-1328360 +Node: import329350 +Ref: #import329473 +Node: Deduplication330581 +Ref: #deduplication330706 +Node: Import testing332628 +Ref: #import-testing332793 +Node: Importing balance assignments333644 +Ref: #importing-balance-assignments333850 +Node: Commodity display styles334507 +Ref: #commodity-display-styles334680 +Node: incomestatement334809 +Ref: #incomestatement334951 +Node: notes336318 +Ref: #notes336440 +Node: payees336802 +Ref: #payees336917 +Node: prices337442 +Ref: #prices337557 +Node: print337859 +Ref: #print337974 +Node: register343420 +Ref: #register343542 +Node: Custom register output348651 +Ref: #custom-register-output348782 +Node: rewrite350157 +Ref: #rewrite350275 +Node: Re-write rules in a file352187 +Ref: #re-write-rules-in-a-file352350 +Node: Diff output format353503 +Ref: #diff-output-format353686 +Node: rewrite vs print --auto354798 +Ref: #rewrite-vs.-print---auto354960 +Node: roi355534 +Ref: #roi355641 +Node: Spaces and special characters in --inv and --pnl357402 +Ref: #spaces-and-special-characters-in---inv-and---pnl357650 +Node: Semantics of --inv and --pnl358148 +Ref: #semantics-of---inv-and---pnl358395 +Node: IRR and TWR explained360273 +Ref: #irr-and-twr-explained360433 +Node: stats363545 +Ref: #stats363653 +Node: tags365050 +Ref: #tags-1365157 +Node: test366174 +Ref: #test366267 +Node: PART 5 COMMON TASKS367017 +Ref: #part-5-common-tasks367150 +Node: Getting help367424 +Ref: #getting-help367565 +Node: Constructing command lines368329 +Ref: #constructing-command-lines368530 +Node: Starting a journal file369211 +Ref: #starting-a-journal-file369418 +Node: Setting opening balances370616 +Ref: #setting-opening-balances370821 +Node: Recording transactions373974 +Ref: #recording-transactions374163 +Node: Reconciling374719 +Ref: #reconciling374871 +Node: Reporting377184 +Ref: #reporting377333 +Node: Migrating to a new file381322 +Ref: #migrating-to-a-new-file381479  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 46d321d9e..264a264b1 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -5709,6 +5709,8 @@ PART 4: COMMANDS HELP o help - show the hledger manual with info/man/pager + o demo - show small hledger demos in the terminal + ADD-ONS And here are some typical add-on commands. Some of these are installed @@ -7381,11 +7383,31 @@ PART 4: COMMANDS commodities List all commodity/currency symbols used or declared in the journal. + demo + Play small demos of hledger usage in the terminal. + + Run this command with no argument to list the demos. To play a demo, + write its number or name or a substring. asciinema must be installed. + + During playback, several keys are available: - SPACE pause/unpause - . + step forward (while paused) - CTRL-c quit early + + asciinema options can be added following a double-dash; list them with + asciinema -h. -s (speed) and -i (max idle time) are particularly use- + ful. + + Examples: + + $ hledger demo # list available demos + $ hledger demo 1 # play the first demo + $ hledger demo install -s5 -i.5 # play the demo named or containing "install", + # at 5x speed, limiting idle time to 0.5s. + descriptions List the unique descriptions that appear in transactions. This command lists the unique descriptions that appear in transactions, - in alphabetic order. You can add a query to select a subset of trans- + in alphabetic order. You can add a query to select a subset of trans- actions. Example: @@ -7396,18 +7418,18 @@ PART 4: COMMANDS Person A diff - Compares a particular account's transactions in two input files. It + Compares a particular account's transactions in two input files. It shows any transactions to this account which are in one file but not in the other. More precisely, for each posting affecting this account in either file, - it looks for a corresponding posting in the other file which posts the - same amount to the same account (ignoring date, description, etc.) + it looks for a corresponding posting in the other file which posts the + same amount to the same account (ignoring date, description, etc.) Since postings not transactions are compared, this also works when mul- tiple bank transactions have been combined into a single journal entry. This is useful eg if you have downloaded an account's transactions from - your bank (eg as CSV data). When hledger and your bank disagree about + 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. @@ -7424,22 +7446,22 @@ PART 4: COMMANDS These transactions are in the second file only: files - List all files included in the journal. With a REGEX argument, only - file names matching the regular expression (case sensitive) are shown. + List all files included in the journal. With a REGEX argument, only + file names matching the regular expression (case sensitive) are shown. help - Show the hledger user manual in the terminal, with info, man, or a - pager. With a TOPIC argument, open it at that topic if possible. - TOPIC can be any heading in the manual, or a heading prefix, case - insensitive. Eg: commands, print, forecast, journal, amount, "auto + Show the hledger user manual in the terminal, with info, man, or a + pager. With a TOPIC argument, open it at that topic if possible. + TOPIC can be any heading in the manual, or a heading prefix, case + insensitive. Eg: commands, print, forecast, journal, amount, "auto postings". This command shows the hledger manual built in to your hledger version. It can be useful when offline, or when you prefer the terminal to a web - browser, or when the appropriate hledger manual or viewing tools are + browser, or when the appropriate hledger manual or viewing tools are not installed on your system. - By default it chooses the best viewer found in $PATH (preferring info + By default it chooses the best viewer found in $PATH (preferring info since the hledger manual is large). You can select a particular viewer with the -i, -m, or -p flags. @@ -7450,71 +7472,71 @@ PART 4: COMMANDS $ hledger help journal # show the journal topic in the hledger manual import - Read new transactions added to each FILE since last run, and add them - to the journal. Or with --dry-run, just print the transactions that - would be added. Or with --catchup, just mark all of the FILEs' trans- + Read new transactions added to each FILE since last run, and add them + to the journal. Or with --dry-run, just print the transactions that + would be added. Or with --catchup, just mark all of the FILEs' trans- actions as imported, without actually importing any. - This command may append new transactions to the main journal file - (which should be in journal format). Existing transactions are not - changed. This is one of the few hledger commands that writes to the + This command may append new transactions to the main journal file + (which should be in journal format). Existing transactions are not + changed. This is one of the few hledger commands that writes to the journal file (see also add). - Unlike other hledger commands, with import the journal file is an out- + Unlike other hledger commands, with import the journal file is an out- put file, and will be modified, though only by appending (existing data - will not be changed). The input files are specified as arguments, so - to import one or more CSV files to your main journal, you will run + will not be changed). The input files are specified as arguments, so + to import one or more CSV files to your main journal, you will run hledger import bank.csv or perhaps hledger import *.csv. Note you can import from any file format, though CSV files are the most common import source, and these docs focus on that case. Deduplication - As a convenience import does deduplication while reading transactions. + As a convenience import does deduplication while reading transactions. This does not mean "ignore transactions that look the same", but rather "ignore transactions that have been seen before". This is intended for - when you are periodically importing foreign data which may contain - already-imported transactions. So eg, if every day you download bank - CSV files containing redundant data, you can safely run hledger import - bank.csv and only new transactions will be imported. (import is idem- + when you are periodically importing foreign data which may contain + already-imported transactions. So eg, if every day you download bank + CSV files containing redundant data, you can safely run hledger import + bank.csv and only new transactions will be imported. (import is idem- potent.) - Since the items being read (CSV records, eg) often do not come with - unique identifiers, hledger detects new transactions by date, assuming + Since the items being read (CSV records, eg) often do not come with + unique identifiers, hledger detects new transactions by date, assuming that: 1. new items always have the newest dates 2. item dates do not change across reads - 3. and items with the same date remain in the same relative order + 3. and items with the same date remain in the same relative order across reads. - These are often true of CSV files representing transactions, or true - enough so that it works pretty well in practice. 1 is important, but + These are often true of CSV files representing transactions, or true + enough so that it works pretty well in practice. 1 is important, but violations of 2 and 3 amongst the old transactions won't matter (and if - you import often, the new transactions will be few, so less likely to + you import often, the new transactions will be few, so less likely to be the ones affected). - hledger remembers the latest date processed in each input file by sav- + hledger remembers the latest date processed in each input file by sav- ing a hidden ".latest" state file in the same directory. Eg when read- - ing finance/bank.csv, it will look for and update the finance/.lat- - est.bank.csv state file. The format is simple: one or more lines con- - taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro- - cessed transactions up to this date, and this many of them on that + ing finance/bank.csv, it will look for and update the finance/.lat- + est.bank.csv state file. The format is simple: one or more lines con- + taining the same ISO-format date (YYYY-MM-DD), meaning "I have pro- + cessed transactions up to this date, and this many of them on that date." Normally you won't see or manipulate these state files yourself. - But if needed, you can delete them to reset the state (making all - transactions "new"), or you can construct them to "catch up" to a cer- + But if needed, you can delete them to reset the state (making all + transactions "new"), or you can construct them to "catch up" to a cer- tain date. - Note deduplication (and updating of state files) can also be done by + Note deduplication (and updating of state files) can also be done by print --new, but this is less often used. Import testing - With --dry-run, the transactions that will be imported are printed to + With --dry-run, the transactions that will be imported are printed to the terminal, without updating your journal or state files. The output - is valid journal format, like the print command, so you can re-parse - it. Eg, to see any importable transactions which CSV rules have not + is valid journal format, like the print command, so you can re-parse + it. Eg, to see any importable transactions which CSV rules have not categorised: $ hledger import --dry bank.csv | hledger -f- -I print unknown @@ -7530,17 +7552,17 @@ PART 4: COMMANDS do a --dry-run first and fix any problems before the real import. Importing balance assignments - Entries added by import will have their posting amounts made explicit - (like hledger print -x). This means that any balance assignments in - imported files must be evaluated; but, imported files don't get to see - the main file's account balances. As a result, importing entries with + Entries added by import will have their posting amounts made explicit + (like hledger print -x). This means that any balance assignments in + imported files must be evaluated; but, imported files don't get to see + the main file's account balances. As a result, importing entries with balance assignments (eg from an institution that provides only balances - and not posting amounts) will probably generate incorrect posting + and not posting amounts) will probably generate incorrect posting amounts. To avoid this problem, use print instead of import: $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE - (If you think import should leave amounts implicit like print does, + (If you think import should leave amounts implicit like print does, please test it and send a pull request.) Commodity display styles @@ -7551,12 +7573,12 @@ PART 4: COMMANDS (is) This command displays an income statement, showing revenues and - expenses during one or more periods. Amounts are shown with normal + expenses during one or more periods. Amounts are shown with normal positive sign, as in conventional financial statements. - This report shows accounts declared with the Revenue or Expense type - (see account types). Or if no such accounts are declared, it shows - top-level accounts named revenue or income or expense (case insensi- + This report shows accounts declared with the Revenue or Expense type + (see account types). Or if no such accounts are declared, it shows + top-level accounts named revenue or income or expense (case insensi- tive, plurals allowed) and their subaccounts. Example: @@ -7583,21 +7605,21 @@ PART 4: COMMANDS 0 This command is a higher-level variant of the balance command, and sup- - ports many of that command's features, such as multi-period reports. + ports many of that command's features, such as multi-period reports. It is similar to hledger balance '(revenues|income)' expenses, but with - smarter account detection, and revenues/income displayed with their + smarter account detection, and revenues/income displayed with their sign flipped. - This command also supports the output destination and output format - options The output formats supported are txt, csv, html, and (experi- + This command also supports the output destination and output format + options The output formats supported are txt, csv, html, and (experi- mental) json. notes List the unique notes that appear in transactions. - This command lists the unique notes that appear in transactions, in - alphabetic order. You can add a query to select a subset of transac- - tions. The note is the part of the transaction description after a | + This command lists the unique notes that appear in transactions, in + alphabetic order. You can add a query to select a subset of transac- + tions. The note is the part of the transaction description after a | character (or if there is no |, the whole description). Example: @@ -7609,14 +7631,14 @@ PART 4: COMMANDS payees List the unique payee/payer names that appear in transactions. - This command lists unique payee/payer names which have been declared - with payee directives (--declared), used in transaction descriptions + This command lists unique payee/payer names which have been declared + with payee directives (--declared), used in transaction descriptions (--used), or both (the default). - The payee/payer is the part of the transaction description before a | + The payee/payer is the part of the transaction description before a | character (or if there is no |, the whole description). - You can add query arguments to select a subset of transactions. This + You can add query arguments to select a subset of transactions. This implies --used. Example: @@ -7627,10 +7649,10 @@ PART 4: COMMANDS Person A prices - Print market price directives from the journal. With --infer-market- - prices, generate additional market prices from costs. With --infer- - reverse-prices, also generate market prices by inverting known prices. - Prices can be filtered by a query. Price amounts are displayed with + Print market price directives from the journal. With --infer-market- + prices, generate additional market prices from costs. With --infer- + reverse-prices, also generate market prices by inverting known prices. + Prices can be filtered by a query. Price amounts are displayed with their full precision. print @@ -7639,17 +7661,17 @@ PART 4: COMMANDS The print command displays full journal entries (transactions) from the journal file, sorted by date (or with --date2, by secondary date). - Amounts are shown mostly normalised to commodity display style, eg the - placement of commodity symbols will be consistent. All of their deci- + Amounts are shown mostly normalised to commodity display style, eg the + placement of commodity symbols will be consistent. All of their deci- mal places are shown, as in the original journal entry (with one alter- ation: in some cases trailing zeroes are added.) Amounts are shown right-aligned within each transaction (but not across all transactions). - Directives and inter-transaction comments are not shown, currently. + Directives and inter-transaction comments are not shown, currently. This means the print command is somewhat lossy, and if you are using it - to reformat your journal you should take care to also copy over the + to reformat your journal you should take care to also copy over the directives and file-level comments. Eg: @@ -7676,7 +7698,7 @@ PART 4: COMMANDS liabilities:debts $1 assets:bank:checking $-1 - print's output is usually a valid hledger journal, and you can process + print's output is usually a valid hledger journal, and you can process it again with a second hledger command. This can be useful for certain kinds of search, eg: @@ -7686,7 +7708,7 @@ PART 4: COMMANDS There are some situations where print's output can become unparseable: - o Valuation affects posting amounts but not balance assertion or bal- + o Valuation affects posting amounts but not balance assertion or bal- ance assignment amounts, potentially causing those to fail. o Auto postings can generate postings with too many missing amounts. @@ -7695,33 +7717,33 @@ PART 4: COMMANDS Normally, the journal entry's explicit or implicit amount style is pre- served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, when a cost is implied but not - written, it will not appear in the output. You can use the + not appear in the output. Similarly, when a cost is implied but not + written, it will not appear in the output. You can use the -x/--explicit flag to make all amounts and costs explicit, which can be useful for troubleshooting or for making your journal more readable and - robust against data entry errors. -x is also implied by using any of + robust against data entry errors. -x is also implied by using any of -B,-V,-X,--value. - Note, -x/--explicit will cause postings with a multi-commodity amount - (these can arise when a multi-commodity transaction has an implicit - amount) to be split into multiple single-commodity postings, keeping + Note, -x/--explicit will cause postings with a multi-commodity amount + (these can arise when a multi-commodity transaction has an implicit + amount) to be split into multiple single-commodity postings, keeping the output parseable. - With -B/--cost, amounts with costs are converted to cost using that + With -B/--cost, amounts with costs are converted to cost using that price. This can be used for troubleshooting. - With -m DESC/--match=DESC, print does a fuzzy search for one recent - transaction whose description is most similar to DESC. DESC should - contain at least two characters. If there is no similar-enough match, - no transaction will be shown and the program exit code will be non- + With -m DESC/--match=DESC, print does a fuzzy search for one recent + transaction whose description is most similar to DESC. DESC should + contain at least two characters. If there is no similar-enough match, + no transaction will be shown and the program exit code will be non- zero. - With --new, hledger prints only transactions it has not seen on a pre- - vious run. This uses the same deduplication system as the import com- + With --new, hledger prints only transactions it has not seen on a pre- + vious run. This uses the same deduplication system as the import com- mand. (See import's docs for details.) - This command also supports the output destination and output format - options The output formats supported are txt, csv, and (experimental) + This command also supports the output destination and output format + options The output formats supported are txt, csv, and (experimental) json and sql. Here's an example of print's CSV output: @@ -7740,20 +7762,20 @@ PART 4: COMMANDS "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) register @@ -7762,14 +7784,14 @@ PART 4: COMMANDS Show postings and their running total. The register command displays matched postings, across all accounts, in - date order, with their running total or running historical balance. - (See also the aregister command, which shows matched transactions in a + date order, with their running total or running historical balance. + (See also the aregister command, which shows matched transactions in a specific account.) register normally shows line per posting, but note that multi-commodity amounts will occupy multiple lines (one line per commodity). - It is typically used with a query selecting a particular account, to + It is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -7780,14 +7802,14 @@ PART 4: COMMANDS With --date2, it shows and sorts by secondary date instead. - For performance reasons, column widths are chosen based on the first - 1000 lines; this means unusually wide values in later lines can cause - visual discontinuities as column widths are adjusted. If you want to - ensure perfect alignment, at the cost of more time and memory, use the + For performance reasons, column widths are chosen based on the first + 1000 lines; this means unusually wide values in later lines can cause + visual discontinuities as column widths are adjusted. If you want to + ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -7797,30 +7819,30 @@ PART 4: COMMANDS The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one account and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account + bers. It's also useful to show postings on the checking account together with the related account: $ hledger register --related --invert assets:checking - With a reporting interval, register shows summary postings, one per + With a reporting interval, register shows summary postings, one per interval, aggregating the postings to each account: $ hledger register --monthly income 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -7837,7 +7859,7 @@ PART 4: COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth + Often, you'll want to see just one line per interval. The --depth option helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h @@ -7845,24 +7867,24 @@ PART 4: COMMANDS 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of - intervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of + intervals. This ensures that the first and last intervals are full length and comparable to the others in the report. - With -m DESC/--match=DESC, register does a fuzzy search for one recent + With -m DESC/--match=DESC, register does a fuzzy search for one recent posting whose description is most similar to DESC. DESC should contain at least two characters. If there is no similar-enough match, no post- ing will be shown and the program exit code will be non-zero. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a - description width as part of --width's argument, comma-separated: + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a + description width as part of --width's argument, comma-separated: --width W,D . Here's a diagram (won't display correctly in --help): <--------------------------------- width (W) ----------------------------------> @@ -7878,19 +7900,19 @@ PART 4: COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 - This command also supports the output destination and output format - options The output formats supported are txt, csv, and (experimental) + This command also supports the output destination and output format + options The output formats supported are txt, csv, and (experimental) json. rewrite Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print + For now the only rewrite available is adding new postings, like print --auto. This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds + the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- + posting amounts can be fixed, or a multiplier of the existing transac- tion's first posting amount. Examples: @@ -7906,7 +7928,7 @@ PART 4: COMMANDS (reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery - Note the single quotes to protect the dollar sign from bash, and the + Note the single quotes to protect the dollar sign from bash, and the two spaces between account and amount. More: @@ -7916,16 +7938,16 @@ PART 4: COMMANDS $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' $ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' - Argument for --add-posting option is a usual posting of transaction - with an exception for amount specification. More precisely, you can + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount - includes a commodity name, the new posting amount will be in the new - commodity; otherwise, it will be in the matched posting amount's com- + factor for an amount of original matched posting. If the amount + includes a commodity name, the new posting amount will be in the new + commodity; otherwise, it will be in the matched posting amount's com- modity. Re-write rules in a file - During the run this tool will execute so called "Automated Transac- + During the run this tool will execute so called "Automated Transac- tions" found in any journal it process. I.e instead of specifying this operations in command line you can put them in a journal file. @@ -7940,7 +7962,7 @@ PART 4: COMMANDS budget:gifts *-1 assets:budget *1 - Note that '=' (equality symbol) that is used instead of date in trans- + Note that '=' (equality symbol) that is used instead of date in trans- actions you usually write. It indicates the query by which you want to match the posting to add new ones. @@ -7953,12 +7975,12 @@ PART 4: COMMANDS --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- ings. Diff output format - To use this tool for batch modification of your journal files you may + To use this tool for batch modification of your journal files you may find useful output in form of unified diff. $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' @@ -7982,10 +8004,10 @@ PART 4: COMMANDS If you'll pass this through patch tool you'll get transactions contain- ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via + files might be update according to list of input files specified via --file options and include directives inside of these files. - Be careful. Whole transaction being re-formatted in a style of output + Be careful. Whole transaction being re-formatted in a style of output from hledger print. See also: @@ -7993,53 +8015,53 @@ PART 4: COMMANDS https://github.com/simonmichael/hledger/issues/99 rewrite vs. print --auto - This command predates print --auto, and currently does much the same + This command predates print --auto, and currently does much the same thing, but with these differences: - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect only child files. - o rewrite's query limits which transactions can be rewritten; all are + o rewrite's query limits which transactions can be rewritten; all are printed. print --auto's query limits which transactions are printed. - o rewrite applies rules specified on command line or in the journal. + o rewrite applies rules specified on command line or in the journal. print --auto applies rules specified in the journal. roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. - At a minimum, you need to supply a query (which could be just an - account name) to select your investment(s) with --inv, and another + At a minimum, you need to supply a query (which could be just an + account name) to select your investment(s) with --inv, and another query to identify your profit and loss transactions with --pnl. - If you do not record changes in the value of your investment manually, - or do not require computation of time-weighted return (TWR), --pnl + If you do not record changes in the value of your investment manually, + or do not require computation of time-weighted return (TWR), --pnl could be an empty query (--pnl "" or --pnl STR where STR does not match any of your accounts). - This command will compute and display the internalized rate of return - (IRR) and time-weighted rate of return (TWR) for your investments for - the time period requested. Both rates of return are annualized before + This command will compute and display the internalized rate of return + (IRR) and time-weighted rate of return (TWR) for your investments for + the time period requested. Both rates of return are annualized before display, regardless of the length of reporting interval. - Price directives will be taken into account if you supply appropriate + Price directives will be taken into account if you supply appropriate --cost or --value flags (see VALUATION). Note, in some cases this report can fail, for these reasons: - o Error (NotBracketed): No solution for Internal Rate of Return (IRR). - Possible causes: IRR is huge (>1000000%), balance of investment + o Error (NotBracketed): No solution for Internal Rate of Return (IRR). + Possible causes: IRR is huge (>1000000%), balance of investment becomes negative at some point in time. - o Error (SearchFailed): Failed to find solution for Internal Rate of + o Error (SearchFailed): Failed to find solution for Internal Rate of Return (IRR). Either search does not converge to a solution, or con- verges too slowly. Examples: - o Using roi to compute total return of investment in stocks: + o Using roi to compute total return of investment in stocks: https://github.com/simonmichael/hledger/blob/master/examples/invest- ing/roi-unrealised.ledger @@ -8049,27 +8071,27 @@ PART 4: COMMANDS Note that --inv and --pnl's argument is a query, and queries could have several space-separated terms (see QUERIES). - To indicate that all search terms form single command-line argument, + To indicate that all search terms form single command-line argument, you will need to put them in quotes (see Special characters): $ hledger roi --inv 'term1 term2 term3 ...' - If any query terms contain spaces themselves, you will need an extra + If any query terms contain spaces themselves, you will need an extra level of nested quoting, eg: $ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'" Semantics of --inv and --pnl - Query supplied to --inv has to match all transactions that are related + Query supplied to --inv has to match all transactions that are related to your investment. Transactions not matching --inv will be ignored. In these transactions, ROI will conside postings that match --inv to be - "investment postings" and other postings (not matching --inv) will be - sorted into two categories: "cash flow" and "profit and loss", as ROI - needs to know which part of the investment value is your contributions + "investment postings" and other postings (not matching --inv) will be + sorted into two categories: "cash flow" and "profit and loss", as ROI + needs to know which part of the investment value is your contributions and which is due to the return on investment. - o "Cash flow" is depositing or withdrawing money, buying or selling + o "Cash flow" is depositing or withdrawing money, buying or selling assets, or otherwise converting between your investment commodity and any other commodity. Example: @@ -8087,12 +8109,12 @@ PART 4: COMMANDS investment:snake oil = $57 equity:unrealized profit or loss - All non-investment postings are assumed to be "cash flow", unless they - match --pnl query. Changes in value of your investment due to "profit - and loss" postings will be considered as part of your investment + All non-investment postings are assumed to be "cash flow", unless they + match --pnl query. Changes in value of your investment due to "profit + and loss" postings will be considered as part of your investment return. - Example: if you use --inv snake --pnl equity:unrealized, then postings + Example: if you use --inv snake --pnl equity:unrealized, then postings in the example below would be classifed as: 2019-01-01 Snake Oil #1 @@ -8109,57 +8131,57 @@ PART 4: COMMANDS snake oil $50 ; investment posting IRR and TWR explained - "ROI" stands for "return on investment". Traditionally this was com- - puted as a difference between current value of investment and its ini- + "ROI" stands for "return on investment". Traditionally this was com- + puted as a difference between current value of investment and its ini- tial value, expressed in percentage of the initial value. However, this approach is only practical in simple cases, where invest- - ments receives no in-flows or out-flows of money, and where rate of + ments receives no in-flows or out-flows of money, and where rate of growth is fixed over time. For more complex scenarios you need differ- - ent ways to compute rate of return, and this command implements two of + ent ways to compute rate of return, and this command implements two of them: IRR and TWR. - Internal rate of return, or "IRR" (also called "money-weighted rate of - return") takes into account effects of in-flows and out-flows. + Internal rate of return, or "IRR" (also called "money-weighted rate of + return") takes into account effects of in-flows and out-flows. Naively, if you are withdrawing from your investment, your future gains - would be smaller (in absolute numbers), and will be a smaller percent- - age of your initial investment, and if you are adding to your invest- - ment, you will receive bigger absolute gains (but probably at the same - rate of return). IRR is a way to compute rate of return for each + would be smaller (in absolute numbers), and will be a smaller percent- + age of your initial investment, and if you are adding to your invest- + ment, you will receive bigger absolute gains (but probably at the same + rate of return). IRR is a way to compute rate of return for each period between in-flow or out-flow of money, and then combine them in a - way that gives you a compound annual rate of return that investment is + way that gives you a compound annual rate of return that investment is expected to generate. - As mentioned before, in-flows and out-flows would be any cash that you + As mentioned before, in-flows and out-flows would be any cash that you personally put in or withdraw, and for the "roi" command, these are the - postings that match the query in the--inv argument and NOT match the + postings that match the query in the--inv argument and NOT match the query in the--pnl argument. - If you manually record changes in the value of your investment as - transactions that balance them against "profit and loss" (or "unreal- - ized gains") account or use price directives, then in order for IRR to - compute the precise effect of your in-flows and out-flows on the rate - of return, you will need to record the value of your investement on or + If you manually record changes in the value of your investment as + transactions that balance them against "profit and loss" (or "unreal- + ized gains") account or use price directives, then in order for IRR to + compute the precise effect of your in-flows and out-flows on the rate + of return, you will need to record the value of your investement on or close to the days when in- or out-flows occur. - In technical terms, IRR uses the same approach as computation of net + In technical terms, IRR uses the same approach as computation of net present value, and tries to find a discount rate that makes net present value of all the cash flows of your investment to add up to zero. This - could be hard to wrap your head around, especially if you haven't done + could be hard to wrap your head around, especially if you haven't done discounted cash flow analysis before. Implementation of IRR in hledger should produce results that match the XIRR formula in Excel. - Second way to compute rate of return that roi command implements is + Second way to compute rate of return that roi command implements is called "time-weighted rate of return" or "TWR". Like IRR, it will also - break the history of your investment into periods between in-flows, - out-flows and value changes, to compute rate of return per each period - and then a compound rate of return. However, internal workings of TWR + break the history of your investment into periods between in-flows, + out-flows and value changes, to compute rate of return per each period + and then a compound rate of return. However, internal workings of TWR are quite different. - TWR represents your investment as an imaginary "unit fund" where in- - flows/ out-flows lead to buying or selling "units" of your investment + TWR represents your investment as an imaginary "unit fund" where in- + flows/ out-flows lead to buying or selling "units" of your investment and changes in its value change the value of "investment unit". Change - in "unit price" over the reporting period gives you rate of return of + in "unit price" over the reporting period gives you rate of return of your investment. References: @@ -8170,21 +8192,21 @@ PART 4: COMMANDS o Explanation of TWR - o Examples of computing IRR and TWR and discussion of the limitations + o Examples of computing IRR and TWR and discussion of the limitations of both metrics stats Show journal and performance statistics. - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. - At the end, it shows (in the terminal) the overall run time and number - of transactions processed per second. Note these are approximate and - will vary based on machine, current load, data size, hledger version, - haskell lib versions, GHC version.. but they may be of interest. The - stats command's run time is similar to that of a single-column balance + At the end, it shows (in the terminal) the overall run time and number + of transactions processed per second. Note these are approximate and + will vary based on machine, current load, data size, hledger version, + haskell lib versions, GHC version.. but they may be of interest. The + stats command's run time is similar to that of a single-column balance report. Example: @@ -8214,35 +8236,35 @@ PART 4: COMMANDS This command lists the tag names used in the journal, whether on trans- actions, postings, or account declarations. - With a TAGREGEX argument, only tag names matching this regular expres- + With a TAGREGEX argument, only tag names matching this regular expres- sion (case insensitive, infix matched) are shown. - With QUERY arguments, only transactions and accounts matching this + With QUERY arguments, only transactions and accounts matching this query are considered. If the query involves transaction fields (date:, desc:, amt:, ...), the search is restricted to the matched transactions and their accounts. - With the --values flag, the tags' unique non-empty values are listed + With the --values flag, the tags' unique non-empty values are listed instead. With -E/--empty, blank/empty values are also shown. - With --parsed, tags or values are shown in the order they were parsed, - with duplicates included. (Except, tags from account declarations are + With --parsed, tags or values are shown in the order they were parsed, + with duplicates included. (Except, tags from account declarations are always shown first.) - Tip: remember, accounts also acquire tags from their parents, postings + Tip: remember, accounts also acquire tags from their parents, postings also acquire tags from their account and transaction, transactions also acquire tags from their postings. test Run built-in unit tests. - 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 + 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. - This is mainly used by hledger developers, but you can also use it to - sanity-check the installed hledger executable on your platform. All - tests are expected to pass - if you ever see a failure, please report + This is mainly used by hledger developers, but you can also use it to + sanity-check the installed hledger executable on your platform. All + tests are expected to pass - if you ever see a failure, please report as a bug! This command also accepts tasty test runner options, written after a -- @@ -8251,12 +8273,12 @@ PART 4: COMMANDS $ hledger test -- -pData.Amount --color=never - For help on these, see https://github.com/feuerbach/tasty#options (-- + For help on these, see https://github.com/feuerbach/tasty#options (-- --help currently doesn't show them). PART 5: COMMON TASKS - Here are some quick examples of how to do some basic tasks with + Here are some quick examples of how to do some basic tasks with hledger. Getting help @@ -8266,37 +8288,37 @@ PART 5: COMMON TASKS $ hledger --help # show common options $ hledger CMD --help # show CMD's options, common options and CMD's documentation - You can also view your hledger version's manual in several formats by + You can also view your hledger version's manual in several formats by using the help command. Eg: $ hledger help # show the hledger manual with info, man or $PAGER (best available) $ hledger help journal # show the journal topic in the hledger manual $ hledger help --help # find out more about the help command - To view manuals and introductory docs on the web, visit - https://hledger.org. Chat and mail list support and discussion ar- + To view manuals and introductory docs on the web, visit + https://hledger.org. Chat and mail list support and discussion ar- chives can be found at https://hledger.org/support. Constructing command lines - hledger has a flexible command line interface. We strive to keep it - simple and ergonomic, but if you run into one of the sharp edges + hledger has a flexible command line interface. We strive to keep it + simple and ergonomic, but if you run into one of the sharp edges described in OPTIONS, here are some tips that might help: - o command-specific options must go after the command (it's fine to put + o command-specific options must go after the command (it's fine to put common options there too: hledger CMD OPTS ARGS) - o running add-on executables directly simplifies command line parsing + o running add-on executables directly simplifies command line parsing (hledger-ui OPTS ARGS) o enclose "problematic" args in single quotes - o if needed, also add a backslash to hide regular expression metachar- + o if needed, also add a backslash to hide regular expression metachar- acters from the shell o to see how a misbehaving command line is being parsed, add --debug=2. Starting a journal file - hledger looks for your accounting data in a journal file, + hledger looks for your accounting data in a journal file, $HOME/.hledger.journal by default: $ hledger stats @@ -8304,9 +8326,9 @@ PART 5: COMMON TASKS Please create it first, eg with "hledger add" or a text editor. Or, specify an existing journal file with -f or LEDGER_FILE. - You can override this by setting the LEDGER_FILE environment variable. + You can override this by setting the LEDGER_FILE environment variable. It's a good practice to keep this important file under version control, - and to start a new file each year. So you could do something like + and to start a new file each year. So you could do something like this: $ mkdir ~/finance @@ -8330,20 +8352,20 @@ PART 5: COMMON TASKS Market prices : 0 () Setting opening balances - Pick a starting date for which you can look up the balances of some - real-world assets (bank accounts, wallet..) and liabilities (credit + Pick a starting date for which you can look up the balances of some + real-world assets (bank accounts, wallet..) and liabilities (credit cards..). - To avoid a lot of data entry, you may want to start with just one or - two accounts, like your checking account or cash wallet; and pick a - recent starting date, like today or the start of the week. You can + To avoid a lot of data entry, you may want to start with just one or + two accounts, like your checking account or cash wallet; and pick a + recent starting date, like today or the start of the week. You can always come back later and add more accounts and older transactions, eg going back to january 1st. - Add an opening balances transaction to the journal, declaring the bal- + Add an opening balances transaction to the journal, declaring the bal- ances on this date. Here are two ways to do it: - o The first way: open the journal in any text editor and save an entry + o The first way: open the journal in any text editor and save an entry like this: 2020-01-01 * opening balances @@ -8353,19 +8375,19 @@ PART 5: COMMON TASKS liabilities:creditcard $-50 = $-50 equity:opening/closing balances - These are start-of-day balances, ie whatever was in the account at + These are start-of-day balances, ie whatever was in the account at the end of the previous day. - The * after the date is an optional status flag. Here it means + The * after the date is an optional status flag. Here it means "cleared & confirmed". - The currency symbols are optional, but usually a good idea as you'll + The currency symbols are optional, but usually a good idea as you'll be dealing with multiple currencies sooner or later. - The = amounts are optional balance assertions, providing extra error + The = amounts are optional balance assertions, providing extra error checking. - o The second way: run hledger add and follow the prompts to record a + o The second way: run hledger add and follow the prompts to record a similar transaction: $ hledger add @@ -8402,18 +8424,18 @@ PART 5: COMMON TASKS Starting the next transaction (. or ctrl-D/ctrl-C to quit) Date [2020-01-01]: . - If you're using version control, this could be a good time to commit + If you're using version control, this could be a good time to commit the journal. Eg: $ git commit -m 'initial balances' 2020.journal Recording transactions - As you spend or receive money, you can record these transactions using - one of the methods above (text editor, hledger add) or by using the - hledger-iadd or hledger-web add-ons, or by using the import command to + As you spend or receive money, you can record these transactions using + one of the methods above (text editor, hledger add) or by using the + hledger-iadd or hledger-web add-ons, or by using the import command to convert CSV data downloaded from your bank. - Here are some simple transactions, see the hledger_journal(5) manual + Here are some simple transactions, see the hledger_journal(5) manual and hledger.org for more ideas: 2020/1/10 * gift received @@ -8429,22 +8451,22 @@ PART 5: COMMON TASKS assets:bank:checking $1000 Reconciling - Periodically you should reconcile - compare your hledger-reported bal- - ances against external sources of truth, like bank statements or your - bank's website - to be sure that your ledger accurately represents the - real-world balances (and, that the real-world institutions have not - made a mistake!). This gets easy and fast with (1) practice and (2) - frequency. If you do it daily, it can take 2-10 minutes. If you let - it pile up, expect it to take longer as you hunt down errors and dis- + Periodically you should reconcile - compare your hledger-reported bal- + ances against external sources of truth, like bank statements or your + bank's website - to be sure that your ledger accurately represents the + real-world balances (and, that the real-world institutions have not + made a mistake!). This gets easy and fast with (1) practice and (2) + frequency. If you do it daily, it can take 2-10 minutes. If you let + it pile up, expect it to take longer as you hunt down errors and dis- crepancies. A typical workflow: - 1. Reconcile cash. Count what's in your wallet. Compare with what - hledger reports (hledger bal cash). If they are different, try to - remember the missing transaction, or look for the error in the - already-recorded transactions. A register report can be helpful - (hledger reg cash). If you can't find the error, add an adjustment + 1. Reconcile cash. Count what's in your wallet. Compare with what + hledger reports (hledger bal cash). If they are different, try to + remember the missing transaction, or look for the error in the + already-recorded transactions. A register report can be helpful + (hledger reg cash). If you can't find the error, add an adjustment transaction. Eg if you have $105 after the above, and can't explain the missing $2, it could be: @@ -8454,26 +8476,26 @@ PART 5: COMMON TASKS 2. Reconcile checking. Log in to your bank's website. Compare today's (cleared) balance with hledger's cleared balance (hledger bal check- - ing -C). If they are different, track down the error or record the - missing transaction(s) or add an adjustment transaction, similar to + ing -C). If they are different, track down the error or record the + missing transaction(s) or add an adjustment transaction, similar to the above. Unlike the cash case, you can usually compare the trans- - action history and running balance from your bank with the one - reported by hledger reg checking -C. This will be easier if you - generally record transaction dates quite similar to your bank's + action history and running balance from your bank with the one + reported by hledger reg checking -C. This will be easier if you + generally record transaction dates quite similar to your bank's clearing dates. 3. Repeat for other asset/liability accounts. - Tip: instead of the register command, use hledger-ui to see a live- + Tip: instead of the register command, use hledger-ui to see a live- updating register while you edit the journal: hledger-ui --watch --reg- ister checking -C - After reconciling, it could be a good time to mark the reconciled - transactions' status as "cleared and confirmed", if you want to track - that, by adding the * marker. Eg in the paycheck transaction above, + After reconciling, it could be a good time to mark the reconciled + transactions' status as "cleared and confirmed", if you want to track + that, by adding the * marker. Eg in the paycheck transaction above, insert * between 2020-01-15 and paycheck - If you're using version control, this can be another good time to com- + If you're using version control, this can be another good time to com- mit: $ git commit -m 'txns' 2020.journal @@ -8545,7 +8567,7 @@ PART 5: COMMON TASKS -------------------- 0 - Show only asset and liability balances, as a flat list, limited to + Show only asset and liability balances, as a flat list, limited to depth 2: $ hledger bal assets liabilities -2 @@ -8555,7 +8577,7 @@ PART 5: COMMON TASKS -------------------- $4055 - Show the same thing without negative numbers, formatted as a simple + Show the same thing without negative numbers, formatted as a simple balance sheet: $ hledger bs -2 @@ -8622,9 +8644,9 @@ PART 5: COMMON TASKS 2020-01-13 **** Migrating to a new file - At the end of the year, you may want to continue your journal in a new + At the end of the year, you may want to continue your journal in a new file, so that old transactions don't slow down or clutter your reports, - and to help ensure the integrity of your accounting history. See the + and to help ensure the integrity of your accounting history. See the close command. If using version control, don't forget to git add the new file. @@ -8632,7 +8654,7 @@ PART 5: COMMON TASKS REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger chat or + Report bugs at http://bugs.hledger.org (or on the #hledger chat or hledger mail list)