From 5dc644d28089a974e0b36d6dd588897455195018 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sun, 7 Mar 2021 10:25:08 -0800 Subject: [PATCH] ;update CLI usage texts --- hledger/Hledger/Cli/Commands/Balance.txt | 648 +++++++++++------- hledger/Hledger/Cli/Commands/Balancesheet.txt | 14 +- .../Cli/Commands/Balancesheetequity.txt | 9 +- hledger/Hledger/Cli/Commands/Cashflow.txt | 13 +- hledger/Hledger/Cli/Commands/Check.txt | 6 +- hledger/Hledger/Cli/Commands/Import.txt | 68 +- .../Hledger/Cli/Commands/Incomestatement.txt | 13 +- hledger/Hledger/Cli/Commands/Print.txt | 17 +- hledger/Hledger/Cli/Commands/Roi.txt | 269 +++----- 9 files changed, 569 insertions(+), 488 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index f17212b58..84ab5d767 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -3,40 +3,77 @@ Show accounts and their balances. _FLAGS -The balance command is hledger's most versatile command. Note, despite -the name, it is not always used for showing real-world account balances; -the more accounting-aware balancesheet and incomestatement may be more -convenient for that. +balance is one of hledger's oldest and most versatile commands, for +listing account balances, balance changes, values, value changes and +more, during one time period or many. Generally it shows a table, with +rows representing accounts, and columns representing periods. -By default, it displays all accounts, and each account's change in -balance during the entire period of the journal. Balance changes are -calculated by adding up the postings in each account. You can limit the -postings matched, by a query, to see fewer accounts, changes over a -different time period, changes from only cleared transactions, etc. +Note there are some higher-level variants of the balance command with +convenient defaults, which can be simpler to use: balancesheet, +balancesheetequity, cashflow and incomestatement. When you need more +control, then use balance. -If you include an account's complete history of postings in the report, -the balance change is equivalent to the account's current ending -balance. For a real-world account, typically you won't have all -transactions in the journal; instead you'll have all transactions after -a certain date, and an "opening balances" transaction setting the -correct starting balance on that date. Then the balance command will -show real-world account balances. In some cases the -H/--historical flag -is used to ensure this (more below). +balance features -This command also supports the output destination and output format -options The output formats supported are (in most modes): txt, csv, -html, and json. +Here's a quick overview of the balance command's features, followed by +more detailed descriptions and examples. Many of these work with the +higher-level commands as well. -The balance command can produce several styles of report: +balance can show.. -Single-period flat balance report +- accounts as a list (-l) or a tree (-t) +- optionally depth-limited (-[1-9]) +- sorted by declaration order and name, or by amount -This is the default for hledger's balance command: a flat list of all -(or with a query, matched) accounts, showing full account names. -Accounts are sorted by declaration order if any, and then by account -name. Accounts which have zero balance are not shown unless -E/--empty -is used. The reported balances' total is shown as the last line, unless -disabled by -N/--no-total. +..and their.. + +- balance changes (the default) +- or actual and planned balance changes (--budget) +- or value of balance changes (-V) +- or change of balance values (--valuechange) + +..in.. + +- one time period (the whole journal period by default) +- or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL) + +..either.. + +- per period (the default) +- or accumulated since report start date (--cumulative) +- or accumulated since account creation (--historical/-H) + +..possibly converted to.. + +- cost (--value=cost[,COMM]/--cost/-B) +- or market value, as of transaction dates (--value=then[,COMM]) +- or at period ends (--value=end[,COMM]) +- or now (--value=now) +- or at some other date (--value=YYYY-MM-DD) + +..with.. + +- totals (-T), averages (-A), percentages (-%), inverted sign + (--invert) +- rows and columns swapped (--transpose) +- another field used as account name (--pivot) +- custom-formatted line items (single-period reports only) (--format) + +This command supports the output destination and output format options, +with output formats txt, csv, json, and (multi-period reports only:) +html. In txt output in a colour-supporting terminal, negative amounts +are shown in red. + +Simple balance report + +With no arguments, balance shows a list of all accounts and their change +of balance - ie, the sum of posting amounts, both inflows and outflows - +during the entire period of the journal. For real-world accounts, this +should also match their end balance at the end of the journal period +(more on this below). + +Accounts are sorted by declaration order if any, and then alphabetically +by account name. For instance, using examples/sample.journal: $ hledger bal $1 assets:bank:saving @@ -49,11 +86,43 @@ $ hledger bal -------------------- 0 -Single-period tree-mode balance report +Accounts with a zero balance (and no non-zero subaccounts, in tree mode +- see below) are hidden by default. Use -E/--empty to show them +(revealing assets:bank:checking here): -With the -t/--tree flag, accounts are displayed hierarchically, showing -subaccounts as short names indented below their parent. (This is the -default style in Ledger and in older hledger versions.) +$ hledger -f examples/sample.journal bal -E + 0 assets:bank:checking + $1 assets:bank:saving + $-2 assets:cash + $1 expenses:food + $1 expenses:supplies + $-1 income:gifts + $-1 income:salary + $1 liabilities:debts +-------------------- + 0 + +The total of the amounts displayed is shown as the last line, unless +-N/--no-total is used. + +Filtered balance report + +You can show fewer accounts, a different time period, totals from +cleared transactions only, etc. by using query arguments or options to +limit the postings being matched. Eg: + +$ hledger bal --cleared assets date:200806 + $-2 assets:cash +-------------------- + $-2 + +List or tree mode + +By default, or with -l/--flat, accounts are shown as a flat list with +their full names visible, as in the examples above. + +With -t/--tree, the account hierarchy is shown, with subaccounts' "leaf" +names indented below their parent: $ hledger balance $-1 assets @@ -69,37 +138,52 @@ $ hledger balance -------------------- 0 -For more compact output, "boring" accounts containing a single -interesting subaccount and no balance of their own (assets:bank and -liabilities here) are elided into the following line, unless --no-elide -is used. And accounts which have zero balance and no non-zero -subaccounts are omitted, unless -E/--empty is used. +Notes: -Account balances in tree mode are "inclusive" - they include the -balances of any subaccounts. Eg, the assets $-1 balance here includes -the $1 from assets:bank:saving and the $-2 from assets:cash. (And it -would include balance posted to the assets account itself, if there was -any). Note this causes some repetition, and the final total (0) is the -sum of the top-level balances, not of all the balances shown. +- "Boring" accounts are combined with their subaccount for more + compact output, unless --no-elide is used. Boring accounts have no + balance of their own and just one subaccount (eg assets:bank and + liabilities above). -Each group of sibling accounts is sorted separately, by declaration -order and then by account name. +- All balances shown are "inclusive", ie including the balances from + all subaccounts. Note this means some repetition in the output, + which requires explanation when sharing reports with + non-plaintextaccounting-users. A tree mode report's final total is + the sum of the top-level balances shown, not of all the balances + shown. + +- Each group of sibling accounts (ie, under a common parent) is sorted + separately. + +Depth limiting + +With a depth:N query, or --depth N option, or just -N, balance reports +will show accounts only to the specified depth, hiding the deeper +subaccounts. Account balances at the depth limit always include the +balances from any hidden subaccounts (even in list mode). This can be +useful for getting an overview. Eg, limiting to depth 1: + +$ hledger balance -N -1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + +You can also hide top-level account name parts, using --drop N. This can +be useful for hiding repetitive top-level account names: + +$ hledger bal expenses --drop 1 + $1 food + $1 supplies +-------------------- + $2 Multi-period balance report -Multi-period balance reports are a very useful hledger feature, -activated if you provide one of the reporting interval flags, such as --M/--monthly. They are similar to single-period balance reports, but -they show the report as a table, with columns representing one or more -successive time periods. This is the usually the preferred style of -balance report in hledger (even for a single period). - -Multi-period balance reports come in several types, showing different -information: - -1. A balance change report: by default, each column shows the sum of - postings in that period, ie the account's change of balance in that - period. This is useful eg for a monthly income statement: +With a report interval (set by the -D/--daily, -W/--weekly, +-M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period flag), balance +shows a tabular report, with columns representing successive time +periods (and a title): $ hledger balance --quarterly income expenses -E Balance changes in 2008: @@ -113,225 +197,240 @@ Balance changes in 2008: -------------------++--------------------------------- || $-1 $1 0 0 -2. A cumulative end balance report: with --cumulative, each column - shows the end balance for that period, accumulating the changes - across periods, starting from 0 at the report start date: +Notes: - $ hledger balance --quarterly income expenses -E --cumulative - Ending balances (cumulative) in 2008: +- The report's start/end dates will be expanded, if necessary, to + fully encompass the displayed subperiods (so that the first and last + subperiods have the same duration as the others). +- Leading and trailing periods (columns) containing all zeroes are not + shown, unless -E/--empty is used. +- Accounts (rows) containing all zeroes are not shown, unless + -E/--empty is used. +- Amounts with many commodities are shown in abbreviated form, unless + --no-elide is used. (experimental) +- Average and/or total columns can be added with the -A/--average and + -T/--row-total flags. +- The --transpose flag can be used to exchange rows and columns. +- The --pivot FIELD option causes a different transaction field to be + used as "account name". See PIVOTING. - || 2008/03/31 2008/06/30 2008/09/30 2008/12/31 - ===================++================================================= - expenses:food || 0 $1 $1 $1 - expenses:supplies || 0 $1 $1 $1 - income:gifts || 0 $-1 $-1 $-1 - income:salary || $-1 $-1 $-1 $-1 - -------------------++------------------------------------------------- - || $-1 0 0 0 +Multi-period reports with many periods can be too wide for easy viewing +in the terminal. Here are some ways to handle that: -3. A historical end balance report: with --historical/-H, each column - shows the actual historical end balance for that period, - accumulating the changes across periods, and including the balance - from any postings before the report start date. This is useful eg - for a multi-period balance sheet, and when you want to see balances - only after a certain date: - - $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 - Ending balances (historical) in 2008/04/01-2008/12/31: - - || 2008/06/30 2008/09/30 2008/12/31 - ======================++===================================== - assets:bank:checking || $1 $1 0 - assets:bank:saving || $1 $1 $1 - assets:cash || $-2 $-2 $-2 - liabilities:debts || 0 0 $1 - ----------------------++------------------------------------- - || 0 0 0 - -Note that --cumulative or --historical/-H disable --row-total/-T, since -summing end balances generally does not make sense. - -With a reporting interval (like --quarterly above), the report start/end -dates will be adjusted if necessary so that they encompass the displayed -report periods. This is so that the first and last periods will be -"full" and comparable to the others. - -The -E/--empty flag does two things in multicolumn balance reports: -first, the report will show all columns within the specified report -period (without -E, leading and trailing columns with all zeroes are not -shown). Second, all accounts which existed at the report start date will -be considered, not just the ones with activity during the report period -(use -E to include low-activity accounts which would otherwise would be -omitted). - -The -T/--row-total flag adds an additional column showing the total for -each row. - -The -A/--average flag adds a column showing the average value in each -row. - -Here's an example of all three: - -$ hledger balance -Q income expenses --tree -ETA -Balance changes in 2008: - - || 2008q1 2008q2 2008q3 2008q4 Total Average -============++=================================================== - expenses || 0 $2 0 0 $2 $1 - food || 0 $1 0 0 $1 0 - supplies || 0 $1 0 0 $1 0 - income || $-1 $-1 0 0 $-2 $-1 - gifts || 0 $-1 0 0 $-1 0 - salary || $-1 0 0 0 $-1 0 -------------++--------------------------------------------------- - || $-1 $1 0 0 0 0 - -(Average is rounded to the dollar here since all journal amounts are) - -The --transpose flag can be used to exchange the rows and columns of a -multicolumn report. - -When showing multicommodity amounts, multicolumn balance reports will -elide any amounts which have more than two commodities, since otherwise -columns could get very wide. The --no-elide flag disables this. Hiding -totals with the -N/--no-total flag can also help reduce the width of -multicommodity reports. - -When the report is still too wide, a good workaround is to pipe it into -less -RS (-R for colour, -S to chop long lines). Eg: -hledger bal -D --color=yes | less -RS. - -Depth limiting - -With a depth:N query, or --depth N option, or just -N, balance reports -will show accounts only to the specified depth. This is very useful to -hide low-level accounts and get an overview. Eg, limiting to depth 1 -shows the top-level accounts: - -$ hledger balance -N -1 - $-1 assets - $2 expenses - $-2 income - $1 liabilities - -Accounts at the depth limit will include the balances of any hidden -subaccounts (even in flat mode, which normally shows exclusive -balances). - -You can also drop account name components from the start of account -names, using --drop N. This can be useful to hide unwanted top-level -detail. - -Colour support - -In terminal output, when colour is enabled, the balance command shows -negative amounts in red. +- Hide the totals row with -N/--no-total +- Convert to a single currency with -V +- Maximize the terminal window +- Reduce the terminal's font size +- View with a pager like less, eg: + hledger bal -D --color=yes | less -RS +- Output as CSV and use a CSV viewer like visidata + (hledger bal -D -O csv | vd -f csv), Emacs' csv-mode + (M-x csv-mode, C-c C-a), or a spreadsheet + (hledger bal -D -o a.csv && open a.csv) +- Output as HTML and view with a browser: + hledger bal -D -o a.html && open a.html Sorting by amount With -S/--sort-amount, accounts with the largest (most positive) -balances are shown first. For example, hledger bal expenses -MAS shows -your biggest averaged monthly expenses first. +balances are shown first. Eg: hledger bal expenses -MAS shows your +biggest averaged monthly expenses first. Revenues and liability balances are typically negative, however, so -S shows these in reverse order. To work around this, you can add --invert -to flip the signs. Or, use one of the sign-flipping reports like -balancesheet or incomestatement, which also support -S. Eg: -hledger is -MAS. +to flip the signs. (Or, use one of the higher-level reports, which flip +the sign automatically. Eg: hledger incomestatement -MAS). Percentages -With -% or --percent, balance reports show each account's value -expressed as a percentage of the column's total. This is useful to get -an overview of the relative sizes of account balances. For example to -obtain an overview of expenses: +With -%/--percent, balance reports show each account's value expressed +as a percentage of the (column) total: -$ hledger balance expenses -% - 100.0 % expenses - 50.0 % food - 50.0 % supplies --------------------- - 100.0 % +$ hledger bal expenses -Q -% +Balance changes in 2008: -Note that --tree does not have an effect on -%. The percentages are -always relative to the total sum of each column, they are never relative -to the parent account. + || 2008Q1 2008Q2 2008Q3 2008Q4 +===================++================================= + expenses:food || 0 50.0 % 0 0 + expenses:supplies || 0 50.0 % 0 0 +-------------------++--------------------------------- + || 0 100.0 % 0 0 -Since the percentages are relative to the columns sum, it is usually not -useful to calculate percentages if the signs of the amounts are mixed. -Although the results are technically correct, they are most likely -useless. Especially in a balance report that sums up to zero (eg -hledger balance -B) all percentage values will be zero. +Note it is not useful to calculate percentages if the amounts in a +column have mixed signs. In this case, make a separate report for each +sign, eg: -This flag does not work if the report contains any mixed commodity -accounts. If there are mixed commodity accounts in the report be sure to -use -V or -B to coerce the report into using a single commodity. +$ hledger bal -% amt:`>0` +$ hledger bal -% amt:`<0` -Customising single-period balance reports +Similarly, if the amounts in a column have mixed commodities, convert +them to one commodity with -B, -V, -X or --value, or make a separate +report for each commodity: -You can customise the layout of single-period balance reports with ---format FMT, which sets the format of each line. Eg: +$ hledger bal -% cur:\\$ +$ hledger bal -% cur:€ -$ hledger balance --format "%20(account) %12(total)" - assets $-1 - bank:saving $1 - cash $-2 - expenses $2 - food $1 - supplies $1 - income $-2 - gifts $-1 - salary $-1 - liabilities:debts $1 ---------------------------------- - 0 +Balance change, end balance -The FMT format string (plus a newline) specifies the formatting applied -to each account/balance pair. It may contain any suitable text, with -data fields interpolated like so: +It's important to be clear on the meaning of the numbers shown in +balance reports. Here is some terminology we use: -%[MIN][.MAX](FIELDNAME) +A balance change is the net amount added to, or removed from, an account +during some period. -- MIN pads with spaces to at least this width (optional) +An end balance is the amount accumulated in an account as of some date +(and some time, but hledger doesn't store that; assume end of day in +your timezone). It is the sum of previous balance changes. -- MAX truncates at this width (optional) +We call it a historical end balance if it includes all balance changes +since the account was created. For a real world account, this means it +will match the "historical record", eg the balances reported in your +bank statements or bank web UI. (If they are correct!) -- FIELDNAME must be enclosed in parentheses, and can be one of: +In general, balance changes are what you want to see when reviewing +revenues and expenses, and historical end balances are what you want to +see when reviewing or reconciling asset, liability and equity accounts. - - depth_spacer - a number of spaces equal to the account's depth, - or if MIN is specified, MIN * depth spaces. - - account - the account's name - - total - the account's balance/posted total, right justified +balance shows balance changes by default. To see accurate historical end +balances: -Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: +1. Initialise account starting balances with an "opening balances" + transaction (a transfer from equity to the account), unless the + journal covers the account's full lifetime. -- %_ - render on multiple lines, bottom-aligned (the default) -- %^ - render on multiple lines, top-aligned -- %, - render on one line, comma-separated +2. Include all of of the account's prior postings in the report, by not + specifying a report start date, or by using the -H/--historical + flag. (-H causes report start date to be ignored when summing + postings.) -There are some quirks. Eg in one-line mode, %(depth_spacer) has no -effect, instead %(account) has indentation built in. Experimentation may -be needed to get pleasing results. +Balance report types -Some example formats: +For more flexible reporting, there are three important option groups: -- %(total) - the account's total -- %-20.20(account) - the account's name, left justified, padded to 20 - characters and clipped at 20 characters -- %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on - one line -- %20(total) %2(depth_spacer)%-(account) - the default format for the - single-column balance report +hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE] ... + +The first two are the most important: calculation type selects the basic +calculation to perform for each table cell, while accumulation type says +which postings should be included in each cell's calculation. Typically +one or both of these are selected by default, so you don't need to write +them explicitly. A valuation type can be added if you want to convert +the basic report to value or cost. + +Calculation type: +The basic calculation to perform for each table cell. It is one of: + +- --sum : sum the posting amounts (default) +- --budget : like --sum but also show a goal amount +- --valuechange : show the change in period-end historical balance + values + +Accumulation type: +Which postings should be included in each cell's calculation. It is one +of: + +- --change : postings from column start to column end, ie within the + cell's period. Typically used to see revenues/expenses. (default for + balance, incomestatement) + +- --cumulative : postings from report start to column end, eg to show + changes accumulated since the report's start date. Rarely used. + +- --historical/-H : postings from journal start to column end, ie all + postings from account creation to the end of the cell's period. + Typically used to see historical end balances of + assets/liabilities/equity. (default for balancesheet, + balancesheetequity, cashflow) + +Valuation type: +Which kind of valuation, valuation date(s) and optionally a target +valuation commodity to use. It is one of: + +- no valuation, show amounts in their original commodities (default) +- --value=cost[,COMM] : no valuation, show amounts converted to cost +- --value=then[,COMM] : show value at transaction dates +- --value=end[,COMM] : show value at period end date(s) (default with + --valuechange) +- --value=now[,COMM] : show value at today's date +- --value=YYYY-MM-DD[,COMM] : show value at another date + +or one of their aliases: --cost/-B, --market/-V or --exchange/-X. + +Most combinations of these options should produce reasonable reports, +but if you find any that seem wrong or misleading, let us know. The +following restrictions are applied: + +- --valuechange implies --value=end +- --valuechange makes --change the default when used with the + balancesheet/balancesheetequity commands +- --cumulative or --historical disables --row-total/-T + +For reference, here is what the combinations of accumulation and +valuation show: + + ------------------------------------------------------------------------------------------------ + Valuation: no valuation --value= then --value= end --value= YYYY-MM-DD /now + >Accumulation: v + ------------------ ---------------- ----------------- --------------- -------------------------- + --change change in period sum of period-end DATE-value of change in + posting-date value of change period + market values in in period + period + + --cumulative change from sum of period-end DATE-value of change from + report start to posting-date value of change report start to period end + period end market values from report + from report start start to period + to period end end + + --historical /-H change from sum of period-end DATE-value of change from + journal start to posting-date value of change journal start to period + period end market values from journal end + (historical end from journal start to period + balance) start to period end + end + ------------------------------------------------------------------------------------------------ + +Useful balance reports + +Some frequently used balance options/reports are: + +- bal -M revenues expenses + Show revenues/expenses in each month. Also available as the + incomestatement command. + +- bal -M -H assets liabilities + Show historical asset/liability balances at each month end. Also + available as the balancesheet command. + +- bal -M -H assets liabilities equity + Show historical asset/liability/equity balances at each month end. + Also available as the balancesheetequity command. + +- bal -M assets not:receivable + Show changes to liquid assets in each month. Also available as the + cashflow command. + +Also: + +- bal -M expenses -2 -SA + Show monthly expenses summarised to depth 2 and sorted by average + amount. + +- bal -M --budget expenses + Show monthly expenses and budget goals. + +- bal -M --valuechange investments + Show monthly change in market value of investment assets. + +- bal investments --valuechange -D date:lastweek amt:'>1000' -STA [--invert] + Show top gainers [or losers] last week Budget report -There is also a special balance report mode for showing budget -performance. The --budget flag activates extra columns showing the -budget goals for each account and period, if any. For this report, -budget goals are defined by periodic transactions. This is very useful -for comparing planned and actual income, expenses, time usage, etc. +The --budget report type activates extra columns showing any budget +goals for each account and period. The budget goals are defined by +periodic transactions. This is very useful for comparing planned and +actual income, expenses, time usage, etc. For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: @@ -387,11 +486,11 @@ This is different from a normal balance report in several ways: goal amounts are shown, and the actual/goal percentage. (Note: budget goals should be in the same commodity as the actual amount.) -- All parent accounts are always shown, even in flat mode. Eg assets, +- All parent accounts are always shown, even in list mode. Eg assets, assets:bank, and expenses above. - Amounts always include all subaccounts, budgeted or unbudgeted, even - in flat mode. + in list mode. This means that the numbers displayed will not always add up! Eg above, the expenses actual amount includes the gifts and supplies transactions, @@ -564,3 +663,62 @@ Budget performance in 2019/01: liabilities || $-283.00 [ 26% of $-1100.00] ----------------------------------------++------------------------------- || 0 [ 0] + +Customising single-period balance reports + +For single-period balance reports displayed in the terminal (only), you +can use --format FMT to customise the format and content of each line. +Eg: + +$ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 +--------------------------------- + 0 + +The FMT format string (plus a newline) specifies the formatting applied +to each account/balance pair. It may contain any suitable text, with +data fields interpolated like so: + +%[MIN][.MAX](FIELDNAME) + +- MIN pads with spaces to at least this width (optional) + +- MAX truncates at this width (optional) + +- FIELDNAME must be enclosed in parentheses, and can be one of: + + - depth_spacer - a number of spaces equal to the account's depth, + or if MIN is specified, MIN * depth spaces. + - account - the account's name + - total - the account's balance/posted total, right justified + +Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + +- %_ - render on multiple lines, bottom-aligned (the default) +- %^ - render on multiple lines, top-aligned +- %, - render on one line, comma-separated + +There are some quirks. Eg in one-line mode, %(depth_spacer) has no +effect, instead %(account) has indentation built in. Experimentation may +be needed to get pleasing results. + +Some example formats: + +- %(total) - the account's total +- %-20.20(account) - the account's name, left justified, padded to 20 + characters and clipped at 20 characters +- %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on + one line +- %20(total) %2(depth_spacer)%-(account) - the default format for the + single-column balance report diff --git a/hledger/Hledger/Cli/Commands/Balancesheet.txt b/hledger/Hledger/Cli/Commands/Balancesheet.txt index 7114c7b56..2a1a05364 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheet.txt +++ b/hledger/Hledger/Cli/Commands/Balancesheet.txt @@ -11,9 +11,6 @@ the Asset or Cash or Liability type, or otherwise all accounts under a top-level asset or liability account (case insensitive, plurals allowed). -(This report is essentially similar to "hledger balance --historical -assets liabilities", with liabilities sign-flipped.) - Example: $ hledger balancesheet @@ -35,13 +32,10 @@ Total: -------------------- 0 -With a reporting interval, multiple columns will be shown, one for each -report period. As with multicolumn balance reports, you can alter the -report mode with --change/--cumulative/--historical. Normally -balancesheet shows historical ending balances, which is what you need -for a balance sheet; note this means it ignores report begin dates (and --T/--row-total, since summing end balances generally does not make -sense). Instead of absolute values percentages can be displayed with -%. +This command is a higher-level variant of the balance command, and +supports many of that command's features, such as multi-period reports. +It is similar to hledger balance -H assets liabilities, but with smarter +account detection, and liabilities 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 diff --git a/hledger/Hledger/Cli/Commands/Balancesheetequity.txt b/hledger/Hledger/Cli/Commands/Balancesheetequity.txt index 1a4e5e798..4d0efa554 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheetequity.txt +++ b/hledger/Hledger/Cli/Commands/Balancesheetequity.txt @@ -10,9 +10,6 @@ declared with the Asset, Cash, Liability or Equity type, or otherwise all accounts under a top-level asset, liability or equity account (case insensitive, plurals allowed). -(This report is essentially similar to "hledger balance --historical -assets liabilities equity", with liabilities and equity sign-flipped.) - Example: $ hledger balancesheetequity @@ -39,6 +36,12 @@ Total: -------------------- 0 +This command is a higher-level variant of the balance command, and +supports many of that command's features, such as multi-period reports. +It is similar to hledger balance -H assets liabilities equity, but with +smarter account detection, and liabilities/equity 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 (experimental) json. diff --git a/hledger/Hledger/Cli/Commands/Cashflow.txt b/hledger/Hledger/Cli/Commands/Cashflow.txt index 76af943d0..0d9e6c604 100644 --- a/hledger/Hledger/Cli/Commands/Cashflow.txt +++ b/hledger/Hledger/Cli/Commands/Cashflow.txt @@ -10,9 +10,6 @@ type, or otherwise all accounts under a top-level asset account (case insensitive, plural allowed) which do not have fixed, investment, receivable or A/R in their name. -(This report is essentially similar to "hledger balance --change assets -not:fixed not:investment not:receivable".) - Example: $ hledger cashflow @@ -29,11 +26,11 @@ Total: -------------------- $-1 -With a reporting interval, multiple columns will be shown, one for each -report period. Normally cashflow shows changes in assets per period, -though as with multicolumn balance reports you can alter the report mode -with --change/--cumulative/--historical. Instead of absolute values -percentages can be displayed with -%. +This command is a higher-level variant of the balance command, and +supports many of that command's features, such as multi-period reports. +It is similar to +hledger balance assets not:fixed not:investment not:receivable, but with +smarter account detection. This command also supports the output destination and output format options The output formats supported are txt, csv, html, and diff --git a/hledger/Hledger/Cli/Commands/Check.txt b/hledger/Hledger/Cli/Commands/Check.txt index 2436ceceb..84754f5a9 100644 --- a/hledger/Hledger/Cli/Commands/Check.txt +++ b/hledger/Hledger/Cli/Commands/Check.txt @@ -48,13 +48,11 @@ These checks can be run only by giving their names as arguments to check. They are more specialised and not desirable for everyone, therefore optional: -- ordereddates - transactions are ordered by date (similar to the old - check-dates command) +- ordereddates - transactions are ordered by date in each file - payees - all payees used by transactions have been declared -- uniqueleafnames - all account leaf names are unique (similar to the - old check-dupes command). +- uniqueleafnames - all account leaf names are unique Custom checks diff --git a/hledger/Hledger/Cli/Commands/Import.txt b/hledger/Hledger/Cli/Commands/Import.txt index 22154a843..37795300d 100644 --- a/hledger/Hledger/Cli/Commands/Import.txt +++ b/hledger/Hledger/Cli/Commands/Import.txt @@ -6,18 +6,68 @@ transactions as imported, without actually importing any. _FLAGS -The input files are specified as arguments - no need to write -f before -each one. So eg to add new transactions from all CSV files to the main -journal, it's just: hledger import *.csv +Unlike other hledger commands, with import the journal file is an output +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 +hledger import bank.csv or perhaps hledger import *.csv. -New transactions are detected in the same way as print --new: by -assuming transactions are always added to the input files in increasing -date order, and by saving .latest.FILE state files. +Note you can import from any file format, though CSV files are the most +common import source, and these docs focus on that case. -The --dry-run output is in journal format, so you can filter it, eg to -see only uncategorised transactions: +Deduplication -$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions +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 idempotent.) + +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 + 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 +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 be +the ones affected). + +hledger remembers the latest date processed in each input file by saving +a hidden ".latest" state file in the same directory. Eg when reading +finance/bank.csv, it will look for and update the +finance/.latest.bank.csv state file. The format is simple: one or more +lines containing the same ISO-format date (YYYY-MM-DD), meaning "I have +processed 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 +certain date. + +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 +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 +categorised: + +$ hledger import --dry bank.csv | hledger -f- -I print unknown + +or (live updating): + +$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown' Importing balance assignments diff --git a/hledger/Hledger/Cli/Commands/Incomestatement.txt b/hledger/Hledger/Cli/Commands/Incomestatement.txt index 8cd669d73..a6667e1a2 100644 --- a/hledger/Hledger/Cli/Commands/Incomestatement.txt +++ b/hledger/Hledger/Cli/Commands/Incomestatement.txt @@ -11,9 +11,6 @@ the Revenue or Expense type, or otherwise all accounts under a top-level revenue or income or expense account (case insensitive, plurals allowed). -(This report is essentially similar to "hledger balance --change -revenues expenses", with revenues sign-flipped.) - Example: $ hledger incomestatement @@ -37,11 +34,11 @@ Total: -------------------- 0 -With a reporting interval, multiple columns will be shown, one for each -report period. Normally incomestatement shows revenues/expenses per -period, though as with multicolumn balance reports you can alter the -report mode with --change/--cumulative/--historical. Instead of absolute -values percentages can be displayed with -%. +This command is a higher-level variant of the balance command, and +supports 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 sign +flipped. This command also supports the output destination and output format options The output formats supported are txt, csv, html, and diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index 0298fb441..9c18cbd48 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -79,20 +79,9 @@ transaction: the one one whose description is most similar to STR, and is most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. -With --new, for each FILE being read, hledger reads (and writes) a -special state file (.latest.FILE in the same directory), containing the -latest transaction date(s) that were seen last time FILE was read. When -this file is found, only transactions with newer dates (and new -transactions on the latest date) are printed. This is useful for -ignoring already-seen entries in import data, such as downloaded CSV -files. Eg: - -$ hledger -f bank1.csv print --new -(shows transactions added since last print --new on this file) - -This assumes that transactions added to FILE always have same or -increasing dates, and that transactions on the same day do not get -reordered. See also the import command. +With --new, hledger prints only transactions it has not seen on a +previous run. This uses the same deduplication system as the import +command. (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) diff --git a/hledger/Hledger/Cli/Commands/Roi.txt b/hledger/Hledger/Cli/Commands/Roi.txt index 6c406effe..15e86dad1 100644 --- a/hledger/Hledger/Cli/Commands/Roi.txt +++ b/hledger/Hledger/Cli/Commands/Roi.txt @@ -4,24 +4,23 @@ your investments. _FLAGS -This command assumes that you have account(s) that hold nothing but your -investments and whenever you record current appraisal/valuation of these -investments you offset unrealized profit and loss into account(s) that, -again, hold nothing but unrealized profit and loss. - -Any transactions affecting balance of investment account(s) and not -originating from unrealized profit and loss account(s) are assumed to be -your investments or withdrawals. - At a minimum, you need to supply a query (which could be just an account -name) to select your investments with --inv, and another query to +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 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 display, regardless of the length of reporting interval. +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: - Error (NotBracketed): No solution for Internal Rate of Return (IRR). @@ -33,10 +32,61 @@ Note, in some cases this report can fail, for these reasons: Examples: -- Using roi to report unrealised gains: +- Using roi to compute total return of investment in stocks: https://github.com/simonmichael/hledger/blob/master/examples/roi-unrealised.ledger -More background: +- Cookbook -> Return on Investment + +Semantics of --inv and --pnl + +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 +and which is due to the return on investment. + +- "Cash flow" is depositing or withdrawing money, buying or selling + assets, or otherwise converting between your investment commodity + and any other commodity. Example: + + 2019-01-01 Investing in Snake Oil + assets:cash -$100 + investment:snake oil + + 2020-01-01 Selling my Snake Oil + assets:cash $10 + investment:snake oil = 0 + +- "Profit and loss" is change in the value of your investment: + + 2019-06-01 Snake Oil falls in value + 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 return. + +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 + assets:cash -$100 ; cash flow posting + investment:snake oil ; investment posting + +2019-03-01 Snake Oil #2 + equity:unrealized pnl -$100 ; profit and loss posting + snake oil ; investment posting + +2019-07-01 Snake Oil #3 + equity:unrealized pnl ; profit and loss posting + cash -$100 ; cash flow posting + snake oil $50 ; investment posting + +IRR and TWR explained "ROI" stands for "return on investment". Traditionally this was computed as a difference between current value of investment and its initial @@ -55,34 +105,34 @@ smaller (in absolute numbers), and will be a smaller percentage of your initial investment, and if you are adding to your investment, 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 an -annual rate of return that investment is expected to generate. +or out-flow of money, and then combine them in a 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 -personally put in or withdraw, and for the "roi" command, these are -transactions that involve account(s) matching --inv argument and NOT -involve account(s) matching --pnl argument. +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 +query in the--pnl argument. -Presumably, you will also record changes in the value of your -investment, and balance them against "profit and loss" (or "unrealized -gains") account. Note that 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. - -Implementation of IRR in hledger should match the XIRR formula in Excel. - -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 and -out-flows to compute rate of return per each period and then a compound -rate of return. However, internal workings of TWR are quite different. +If you manually record changes in the value of your investment as +transactions that balance them against "profit and loss" (or "unrealized +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 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 -discounted cash flow analysis before. +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 +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 +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 @@ -93,158 +143,3 @@ your investment. References: * Explanation of rate of return * Explanation of IRR * Explanation of TWR * Examples of computing IRR and TWR and discussion of the limitations of both metrics - -More examples: - -Lets say that we found an investment in Snake Oil that is proising to -give us 10% annually: - -2019-01-01 Investing in Snake Oil - assets:cash -$100 - investment:snake oil - -2019-12-24 Recording the growth of Snake Oil - investment:snake oil = $110 - equity:unrealized gains - -For now, basic computation of the rate of return, as well as IRR and -TWR, gives us the expected 10%: - -$ hledger roi -Y --inv investment --pnl "unrealized" -+---++------------+------------++---------------+----------+-------------+-----++--------+--------+ -| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR | -+===++============+============++===============+==========+=============+=====++========+========+ -| 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 110 | 10 || 10.00% | 10.00% | -+---++------------+------------++---------------+----------+-------------+-----++--------+--------+ - -However, lets say that shorty after investing in the Snake Oil we -started to have second thoughs, so we prompty withdrew $90, leaving only -$10 in. Before Christmas, though, we started to get the "fear of mission -out", so we put the $90 back in. So for most of the year, our investment -was just $10 dollars, and it gave us just $1 in growth: - -2019-01-01 Investing in Snake Oil - assets:cash -$100 - investment:snake oil - -2019-01-02 Buyers remorse - assets:cash $90 - investment:snake oil - -2019-12-30 Fear of missing out - assets:cash -$90 - investment:snake oil - -2019-12-31 Recording the growth of Snake Oil - investment:snake oil = $101 - equity:unrealized gains - -Now IRR and TWR are drastically different: - -$ hledger roi -Y --inv investment --pnl "unrealized" -+---++------------+------------++---------------+----------+-------------+-----++-------+-------+ -| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR | -+===++============+============++===============+==========+=============+=====++=======+=======+ -| 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 101 | 1 || 9.32% | 1.00% | -+---++------------+------------++---------------+----------+-------------+-----++-------+-------+ - -Here, IRR tells us that we made close to 10% on the $10 dollars that we -had in the account most of the time. And TWR is ... just 1%? Why? - -Based on the transactions in our journal, TWR "think" that we are buying -back $90 worst of Snake Oil at the same price that it had at the -beginning of they year, and then after that our $100 investment gets $1 -increase in value, or 1% of $100. Let's take a closer look at what is -happening here by asking for quarterly reports instead of annual: - -$ hledger roi -Q --inv investment --pnl "unrealized" -+---++------------+------------++---------------+----------+-------------+-----++--------+-------+ -| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR | -+===++============+============++===============+==========+=============+=====++========+=======+ -| 1 || 2019-01-01 | 2019-03-31 || 0 | 10 | 10 | 0 || 0.00% | 0.00% | -| 2 || 2019-04-01 | 2019-06-30 || 10 | 0 | 10 | 0 || 0.00% | 0.00% | -| 3 || 2019-07-01 | 2019-09-30 || 10 | 0 | 10 | 0 || 0.00% | 0.00% | -| 4 || 2019-10-01 | 2019-12-31 || 10 | 90 | 101 | 1 || 37.80% | 4.03% | -+---++------------+------------++---------------+----------+-------------+-----++--------+-------+ - -Now both IRR and TWR are thrown off by the fact that all of the growth -for our investment happens in Q4 2019. This happes because IRR -computation is still yielding 9.32% and TWR is still 1%, but this time -these are rates for three month period instead of twelve, so in order to -get an annual rate they should be multiplied by four! - -Let's try to keep a better record of how Snake Oil grew in value: - -2019-01-01 Investing in Snake Oil - assets:cash -$100 - investment:snake oil - -2019-01-02 Buyers remorse - assets:cash $90 - investment:snake oil - -2019-02-28 Recording the growth of Snake Oil - investment:snake oil - equity:unrealized gains -$0.25 - -2019-06-30 Recording the growth of Snake Oil - investment:snake oil - equity:unrealized gains -$0.25 - -2019-09-30 Recording the growth of Snake Oil - investment:snake oil - equity:unrealized gains -$0.25 - -2019-12-30 Fear of missing out - assets:cash -$90 - investment:snake oil - -2019-12-31 Recording the growth of Snake Oil - investment:snake oil - equity:unrealized gains -$0.25 - -Would our quartery report look better now? Almost: - -$ hledger roi -Q --inv investment --pnl "unrealized" -+---++------------+------------++---------------+----------+-------------+------++--------+--------+ -| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR | -+===++============+============++===============+==========+=============+======++========+========+ -| 1 || 2019-01-01 | 2019-03-31 || 0 | 10 | 10.25 | 0.25 || 9.53% | 10.53% | -| 2 || 2019-04-01 | 2019-06-30 || 10.25 | 0 | 10.50 | 0.25 || 10.15% | 10.15% | -| 3 || 2019-07-01 | 2019-09-30 || 10.50 | 0 | 10.75 | 0.25 || 9.79% | 9.78% | -| 4 || 2019-10-01 | 2019-12-31 || 10.75 | 90 | 101.00 | 0.25 || 8.05% | 1.00% | -+---++------------+------------++---------------+----------+-------------+------++--------+--------+ - -Something is still wrong with TWR computation for Q4, and if you have -been paying attention you know what it is already: big $90 buy-back is -recorded prior to the only transaction that captures the change of value -of Snake Oil that happened in this time period. Lets combine -transactions from 30th and 31st of Dec into one: - -2019-12-30 Fear of missing out and growth of Snake Oil - assets:cash -$90 - investment:snake oil - equity:unrealized gains -$0.25 - -Now growth of investment properly affects its price at the time of -buy-back: - -$ hledger roi -Q --inv investment --pnl "unrealized" -+---++------------+------------++---------------+----------+-------------+------++--------+--------+ -| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR | -+===++============+============++===============+==========+=============+======++========+========+ -| 1 || 2019-01-01 | 2019-03-31 || 0 | 10 | 10.25 | 0.25 || 9.53% | 10.53% | -| 2 || 2019-04-01 | 2019-06-30 || 10.25 | 0 | 10.50 | 0.25 || 10.15% | 10.15% | -| 3 || 2019-07-01 | 2019-09-30 || 10.50 | 0 | 10.75 | 0.25 || 9.79% | 9.78% | -| 4 || 2019-10-01 | 2019-12-31 || 10.75 | 90 | 101.00 | 0.25 || 8.05% | 9.57% | -+---++------------+------------++---------------+----------+-------------+------++--------+--------+ - -And for annual report, TWR now reports the exact profitability of our -investment: - -$ hledger roi -Y --inv investment --pnl "unrealized" -+---++------------+------------++---------------+----------+-------------+------++-------+--------+ -| || Begin | End || Value (begin) | Cashflow | Value (end) | PnL || IRR | TWR | -+===++============+============++===============+==========+=============+======++=======+========+ -| 1 || 2019-01-01 | 2019-12-31 || 0 | 100 | 101.00 | 1.00 || 9.32% | 10.00% | -+---++------------+------------++---------------+----------+-------------+------++-------+--------+