From 3d968fb98eb4a227462bb9a778812cf874f0a3c8 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 16 Mar 2023 15:44:35 -1000 Subject: [PATCH] ;doc: update manuals --- hledger/hledger.1 | 6 - hledger/hledger.info | 177 ++++++------- hledger/hledger.txt | 609 +++++++++++++++++++++---------------------- 3 files changed, 388 insertions(+), 404 deletions(-) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 5ef43bb98..25b590376 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -9971,12 +9971,6 @@ generated for each commodity. With \f[V]--interleaved\f[R], each equity posting is shown next to the corresponding source/destination posting. .PP -The default closing date is yesterday or the journal\[aq]s end date, -whichever is later. -You can change this by specifying a report end date; the last day of the -report period will be the closing date. -Eg \f[V]-e 2022\f[R] means \[dq]close on 2022-12-31\[dq]. -.PP The default closing date is yesterday, or the journal\[aq]s end date, whichever is later. You can change this by specifying a report end date; (The report start diff --git a/hledger/hledger.info b/hledger/hledger.info index b370f668d..3d16a6df3 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -8699,11 +8699,6 @@ each commodity. With ‘--interleaved’, each equity posting is shown next to the corresponding source/destination posting. - The default closing date is yesterday or the journal’s end date, -whichever is later. You can change this by specifying a report end -date; the last day of the report period will be the closing date. Eg -‘-e 2022’ means "close on 2022-12-31". - The default closing date is yesterday, or the journal’s end date, whichever is later. You can change this by specifying a report end date; (The report start date does not matter.) The last day of the @@ -10879,92 +10874,92 @@ Node: More about specific checks316256 Ref: #more-about-specific-checks316418 Node: close317150 Ref: #close317261 -Node: close and costs319899 -Ref: #close-and-costs320043 -Node: close and balance assertions320332 -Ref: #close-and-balance-assertions320534 -Node: Example retain earnings321705 -Ref: #example-retain-earnings321922 -Node: Example migrate balances to a new file322280 -Ref: #example-migrate-balances-to-a-new-file322545 -Node: Example excluding closing/opening transactions323098 -Ref: #example-excluding-closingopening-transactions323347 -Node: codes324525 -Ref: #codes324642 -Node: commodities325518 -Ref: #commodities325654 -Node: descriptions325724 -Ref: #descriptions325861 -Node: diff326152 -Ref: #diff326267 -Node: files327313 -Ref: #files327422 -Node: help327563 -Ref: #help-1327672 -Node: import328662 -Ref: #import328785 -Node: Deduplication329893 -Ref: #deduplication330018 -Node: Import testing331940 -Ref: #import-testing332105 -Node: Importing balance assignments332956 -Ref: #importing-balance-assignments333162 -Node: Commodity display styles333819 -Ref: #commodity-display-styles333992 -Node: incomestatement334121 -Ref: #incomestatement334263 -Node: notes335630 -Ref: #notes335752 -Node: payees336114 -Ref: #payees336229 -Node: prices336754 -Ref: #prices336869 -Node: print337171 -Ref: #print337286 -Node: register342732 -Ref: #register342854 -Node: Custom register output347963 -Ref: #custom-register-output348094 -Node: rewrite349469 -Ref: #rewrite349587 -Node: Re-write rules in a file351499 -Ref: #re-write-rules-in-a-file351662 -Node: Diff output format352815 -Ref: #diff-output-format352998 -Node: rewrite vs print --auto354110 -Ref: #rewrite-vs.-print---auto354272 -Node: roi354846 -Ref: #roi354953 -Node: Spaces and special characters in --inv and --pnl356714 -Ref: #spaces-and-special-characters-in---inv-and---pnl356962 -Node: Semantics of --inv and --pnl357460 -Ref: #semantics-of---inv-and---pnl357707 -Node: IRR and TWR explained359585 -Ref: #irr-and-twr-explained359745 -Node: stats362857 -Ref: #stats362965 -Node: tags364362 -Ref: #tags-1364469 -Node: test365486 -Ref: #test365579 -Node: PART 5 COMMON TASKS366329 -Ref: #part-5-common-tasks366462 -Node: Getting help366736 -Ref: #getting-help366877 -Node: Constructing command lines367641 -Ref: #constructing-command-lines367842 -Node: Starting a journal file368523 -Ref: #starting-a-journal-file368730 -Node: Setting opening balances369928 -Ref: #setting-opening-balances370133 -Node: Recording transactions373286 -Ref: #recording-transactions373475 -Node: Reconciling374031 -Ref: #reconciling374183 -Node: Reporting376496 -Ref: #reporting376645 -Node: Migrating to a new file380634 -Ref: #migrating-to-a-new-file380791 +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  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index cfd7e3110..46d321d9e 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -7221,44 +7221,39 @@ PART 4: COMMANDS With --interleaved, each equity posting is shown next to the corre- sponding source/destination posting. - The default closing date is yesterday or the journal's end date, which- - ever is later. You can change this by specifying a report end date; - the last day of the report period will be the closing date. Eg -e 2022 - means "close on 2022-12-31". - - The default closing date is yesterday, or the journal's end date, - whichever is later. You can change this by specifying a report end - date; (The report start date does not matter.) The last day of the - report period will be the closing date; eg -e 2022 means "close on - 2022-12-31". The opening date is always the day after the closing + The default closing date is yesterday, or the journal's end date, + whichever is later. You can change this by specifying a report end + date; (The report start date does not matter.) The last day of the + report period will be the closing date; eg -e 2022 means "close on + 2022-12-31". The opening date is always the day after the closing date. close and costs - With --show-costs, any amount costs are shown, with separate postings + With --show-costs, any amount costs are shown, with separate postings for each cost. (This currently the best way to view investment assets, - showing lots and cost bases.) If you have many currency conversion or + showing lots and cost bases.) If you have many currency conversion or investment transactions, it can generate very large journal entries. close and balance assertions - Balance assertions will be generated, verifying that the accounts have - been reset to zero (and then restored to their previous balances, if + Balance assertions will be generated, verifying that the accounts have + been reset to zero (and then restored to their previous balances, if there is an opening transaction). - These provide useful error checking, but you can ignore them temporar- + These provide useful error checking, but you can ignore them temporar- ily with -I, or remove them if you prefer. - You probably should avoid filtering transactions by status or realness - (-C, -R, status:), or generating postings (--auto), with this command, + You probably should avoid filtering transactions by status or realness + (-C, -R, status:), or generating postings (--auto), with this command, since the balance assertions would depend on these. - Note custom posting dates spanning the file boundary will disrupt the + Note custom posting dates spanning the file boundary will disrupt the balance assertions: 2023-12-30 a purchase made in december, cleared in january expenses:food 5 assets:bank:checking -5 ; date: 2023-01-02 - To solve that you can transfer the money to and from a temporary + To solve that you can transfer the money to and from a temporary account, in effect splitting the multi-day transaction into two single- day transactions: @@ -7273,38 +7268,38 @@ PART 4: COMMANDS assets:bank:checking -5 Example: retain earnings - Record 2022's revenues/expenses as retained earnings on 2022-12-31, + Record 2022's revenues/expenses as retained earnings on 2022-12-31, appending the generated transaction to the journal: $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal - Now 2022's income statement will show only zeroes. To see it again, + Now 2022's income statement will show only zeroes. To see it again, exclude the retain transaction. Eg: $ hledger -f 2022.journal is not:desc:'retain earnings' Example: migrate balances to a new file - Close assets/liabilities/equity on 2022-12-31 and re-open them on + Close assets/liabilities/equity on 2022-12-31 and re-open them on 2023-01-01: $ hledger close --migrate -f 2022.journal -p 2022 # copy/paste the closing transaction to the end of 2022.journal # copy/paste the opening transaction to the start of 2023.journal - Now 2022's balance sheet will show only zeroes, indicating a balanced - accounting equation. (Unless you are using @/@@ notation - in that + Now 2022's balance sheet will show only zeroes, indicating a balanced + accounting equation. (Unless you are using @/@@ notation - in that case, try adding --infer-equity.) To see it again, exclude the closing transaction. Eg: $ hledger -f 2022.journal bs not:desc:'closing balances' Example: excluding closing/opening transactions - When combining many files for multi-year reports, the closing/opening - transactions cause some noise in reports like print and register. You + When combining many files for multi-year reports, the closing/opening + transactions cause some noise in reports like print and register. You can exclude them as shown above, but not:desc:... could be fragile, and - also you will need to avoid excluding the very first opening transac- - tion, which can be awkward. Here is a way to do it, using tags: add - clopen: tags to all opening/closing balances transactions except the + also you will need to avoid excluding the very first opening transac- + tion, which can be awkward. Here is a way to do it, using tags: add + clopen: tags to all opening/closing balances transactions except the first, like this: ; 2021.journal @@ -7330,7 +7325,7 @@ PART 4: COMMANDS include 2022.journal include 2023.journal - The clopen: tag can exclude all but the first opening transaction. To + The clopen: tag can exclude all but the first opening transaction. To show a clean multi-year checking register: $ hledger -f all.journal areg checking not:tag:clopen @@ -7343,13 +7338,13 @@ PART 4: COMMANDS codes List the codes seen in transactions, in the order parsed. - This command prints the value of each transaction's code field, in the - order transactions were parsed. The transaction code is an optional - value written in parentheses between the date and description, often + This command prints the value of each transaction's code field, in the + order transactions were parsed. The transaction code is an optional + value written in parentheses between the date and description, often used to store a cheque number, order number or similar. Transactions aren't required to have a code, and missing or empty codes - will not be shown by default. With the -E/--empty flag, they will be + will not be shown by default. With the -E/--empty flag, they will be printed as blank lines. You can add a query to select a subset of transactions. @@ -7390,7 +7385,7 @@ PART 4: COMMANDS 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: @@ -7401,18 +7396,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. @@ -7429,22 +7424,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. @@ -7455,71 +7450,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 @@ -7535,17 +7530,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 @@ -7556,12 +7551,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: @@ -7588,21 +7583,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: @@ -7614,14 +7609,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: @@ -7632,10 +7627,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 @@ -7644,17 +7639,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: @@ -7681,7 +7676,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: @@ -7691,7 +7686,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. @@ -7700,33 +7695,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: @@ -7745,20 +7740,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 @@ -7767,14 +7762,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 @@ -7785,14 +7780,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 @@ -7802,30 +7797,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 @@ -7842,7 +7837,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 @@ -7850,24 +7845,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) ----------------------------------> @@ -7883,19 +7878,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: @@ -7911,7 +7906,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: @@ -7921,16 +7916,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. @@ -7945,7 +7940,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. @@ -7958,12 +7953,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' @@ -7987,10 +7982,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: @@ -7998,53 +7993,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 @@ -8054,27 +8049,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: @@ -8092,12 +8087,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 @@ -8114,57 +8109,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: @@ -8175,21 +8170,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: @@ -8219,35 +8214,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 -- @@ -8256,12 +8251,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 @@ -8271,37 +8266,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 @@ -8309,9 +8304,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 @@ -8335,20 +8330,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 @@ -8358,19 +8353,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 @@ -8407,18 +8402,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 @@ -8434,22 +8429,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: @@ -8459,26 +8454,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 @@ -8550,7 +8545,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 @@ -8560,7 +8555,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 @@ -8627,9 +8622,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. @@ -8637,7 +8632,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)