From cf607adfcfbe9b1d2b2b2b0362740f1102820845 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 14 Dec 2022 07:53:03 -1000 Subject: [PATCH] ;doc: update CLI usage texts --- hledger/Hledger/Cli/Commands/Balance.txt | 581 ++++++++++++----------- hledger/Hledger/Cli/Commands/Check.txt | 5 +- hledger/Hledger/Cli/Commands/Close.txt | 32 +- hledger/Hledger/Cli/Commands/Codes.txt | 21 +- hledger/Hledger/Cli/Commands/Prices.txt | 7 +- hledger/Hledger/Cli/Commands/Print.txt | 16 +- 6 files changed, 341 insertions(+), 321 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 5a06aa35f..b9f323a99 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -73,9 +73,12 @@ 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). +during the entire period of the journal. ("Simple" here means just one +column of numbers, covering a single period. You can also have +multi-period reports, described later.) + +For real-world accounts, these numbers will normally be 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): @@ -91,8 +94,8 @@ $ hledger -f examples/sample.journal bal -------------------- 0 -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 +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): $ hledger -f examples/sample.journal bal -E @@ -110,6 +113,65 @@ $ hledger -f examples/sample.journal bal -E The total of the amounts displayed is shown as the last line, unless -N/--no-total is used. +Balance report line format + +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 -f examples/sample.journal 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 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 + Filtered balance report You can show fewer accounts, a different time period, totals from @@ -190,6 +252,53 @@ $ hledger -f examples/sample.journal bal expenses --drop 1 -------------------- $2 +Showing declared accounts + +With --declared, accounts which have been declared with an account +directive will be included in the balance report, even if they have no +transactions. (Since they will have a zero balance, you will also need +-E/--empty to see them.) + +More precisely, leaf declared accounts (with no subaccounts) will be +included, since those are usually the more useful in reports. + +The idea of this is to be able to see a useful "complete" balance +report, even when you don't have transactions in all of your declared +accounts yet. + +Sorting by amount + +With -S/--sort-amount, accounts with the largest (most positive) +balances are shown first. Eg: hledger bal expenses -MAS shows your +biggest averaged monthly expenses first. When more than one commodity is +present, they will be sorted by the alphabetically earliest commodity +first, and then by subsequent commodities (if an amount is missing a +commodity, it is treated as 0). + +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 higher-level reports, which flip +the sign automatically. Eg: hledger incomestatement -MAS). + +Percentages + +With -%/--percent, balance reports show each account's value expressed +as a percentage of the (column) total. + +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: + +$ hledger bal -% amt:`>0` +$ hledger bal -% amt:`<0` + +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: + +$ hledger bal -% cur:\\$ +$ hledger bal -% cur:€ + Multi-period balance report With a report interval (set by the -D/--daily, -W/--weekly, @@ -242,193 +351,6 @@ in the terminal. Here are some ways to handle that: - Output as HTML and view with a browser: hledger bal -D -o a.html && open a.html -Showing declared accounts - -With --declared, accounts which have been declared with an account -directive will be included in the balance report, even if they have no -transactions. (Since they will have a zero balance, you will also need --E/--empty to see them.) - -More precisely, leaf declared accounts (with no subaccounts) will be -included, since those are usually the more useful in reports. - -The idea of this is to be able to see a useful "complete" balance -report, even when you don't have transactions in all of your declared -accounts yet. - -Data layout - -The --layout option affects how multi-commodity amounts are displayed, -and some other things, influencing the overall layout of the report -data: - -- --layout=wide[,WIDTH]: commodities are shown on a single line, - possibly elided to the specified width -- --layout=tall: each commodity is shown on a separate line -- --layout=bare: amounts are shown as bare numbers, with commodity - symbols in a separate column -- --layout=tidy: data is normalised to tidy form, with one row per - data value. We currently support this with CSV output only. In tidy - mode, totals and row averages are disabled (-N/--no-total is implied - and -T/--row-total and -A/--average will be ignored). - -These --layout modes are supported with some but not all of the output -formats: - - - txt csv html json sql - ------ ----- ----- ------ ------ ----- - wide Y Y Y - tall Y Y Y - bare Y Y Y - tidy Y - -Examples: - -- Wide layout. With many commodities, reports can be very wide: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++==================================================================================================================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - -- Limited wide layout. A width limit reduces the width, but some - commodities will be hidden: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++=========================================================================================================================== - Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++--------------------------------------------------------------------------------------------------------------------------- - || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - -- Tall layout. Each commodity gets a new line (may be different in - each column), and account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall - Balance changes in 2012-01-01..2014-12-31: - - || 2012 2013 2014 Total - ==================++================================================== - Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++-------------------------------------------------- - || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT - -- Bare layout. Commodity symbols are kept in one column, each - commodity gets its own report row, account names are repeated: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare - Balance changes in 2012-01-01..2014-12-31: - - || Commodity 2012 2013 2014 Total - ==================++============================================= - Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++--------------------------------------------- - || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 - -- Bare layout also affects CSV output, which is useful for producing - data that is easier to consume, eg when making charts: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare - "account","commodity","balance" - "Assets:US:ETrade","GLD","70.00" - "Assets:US:ETrade","ITOT","17.00" - "Assets:US:ETrade","USD","5120.50" - "Assets:US:ETrade","VEA","36.00" - "Assets:US:ETrade","VHT","294.00" - "total","GLD","70.00" - "total","ITOT","17.00" - "total","USD","5120.50" - "total","VEA","36.00" - "total","VHT","294.00" - -- Tidy layout produces normalised "tidy data", where every variable is - a column and each row represents a single data point (see - https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html). - This kind of data is the easiest to process with other software: - - $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy - "account","period","start_date","end_date","commodity","value" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" - "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" - "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" - "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" - -Sorting by amount - -With -S/--sort-amount, accounts with the largest (most positive) -balances are shown first. Eg: hledger bal expenses -MAS shows your -biggest averaged monthly expenses first. When more than one commodity is -present, they will be sorted by the alphabetically earliest commodity -first, and then by subsequent commodities (if an amount is missing a -commodity, it is treated as 0). - -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 higher-level reports, which flip -the sign automatically. Eg: hledger incomestatement -MAS). - -Percentages - -With -%/--percent, balance reports show each account's value expressed -as a percentage of the (column) total: - -$ hledger -f examples/sample.journal bal expenses -Q -% -Balance changes in 2008: - - || 2008Q1 2008Q2 2008Q3 2008Q4 -===================++================================= - expenses:food || 0 50.0 % 0 0 - expenses:supplies || 0 50.0 % 0 0 --------------------++--------------------------------- - || 0 100.0 % 0 0 - -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: - -$ hledger bal -% amt:`>0` -$ hledger bal -% amt:`<0` - -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: - -$ hledger bal -% cur:\\$ -$ hledger bal -% cur:€ - Balance change, end balance It's important to be clear on the meaning of the numbers shown in @@ -464,18 +386,26 @@ balances: Balance report types -For more flexible reporting, there are three important option groups: +The balance command is quite flexible; here is the full detail on how to +control what it reports. There are three important option groups: 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. +The first two are the most important: + +- calculation type selects the basic calculation to perform for each + table cell +- 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. Then + +- a valuation type can be added if you want to convert the basic + report to value or cost + +Calculation type -Calculation type: The basic calculation to perform for each table cell. It is one of: - --sum : sum the posting amounts (default) @@ -486,7 +416,8 @@ The basic calculation to perform for each table cell. It is one of: - --gain : show the unrealised capital gain/loss, (the current valued balance minus each amount's original cost) -Accumulation type: +Accumulation type + Which postings should be included in each cell's calculation. It is one of: @@ -503,7 +434,8 @@ of: assets/liabilities/equity. (default for balancesheet, balancesheetequity, cashflow) -Valuation type: +Valuation type + Which kind of valuation, valuation date(s) and optionally a target valuation commodity to use. It is one of: @@ -517,6 +449,8 @@ valuation commodity to use. It is one of: or one of their aliases: --cost/-B, --market/-V or --exchange/-X. +Combining balance report types + 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: @@ -530,8 +464,8 @@ 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 + 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 @@ -552,41 +486,6 @@ valuation show: 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 The --budget report type activates extra columns showing any budget @@ -848,61 +747,175 @@ regular expression or query). This means you can give your periodic rules descriptions (remember that two spaces are needed), and then select from multiple budgets defined in your journal. -Customising single-period balance reports +Data layout -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: +The --layout option affects how balance reports show commodity symbols +and multi-commodity amounts, which can improve readability. It can also +normalise the data for easy consumption by other programs. It has four +possible values: -$ hledger -f examples/sample.journal 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 +- --layout=wide[,WIDTH]: commodities are shown on a single line, + possibly elided to the specified width +- --layout=tall: each commodity is shown on a separate line +- --layout=bare: amounts are shown as bare numbers, with commodity + symbols in a separate column +- --layout=tidy: data is normalised to easily-consumed "tidy" form, + with one row per data value (works only with CSV output) -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: +These --layout modes are supported with some but not all of the output +formats: -%[MIN][.MAX](FIELDNAME) + - txt csv html json sql + ------ ----- ----- ------ ------ ----- + wide Y Y Y + tall Y Y Y + bare Y Y Y + tidy Y -- MIN pads with spaces to at least this width (optional) +Examples: -- MAX truncates at this width (optional) +- Wide layout. With many commodities, reports can be very wide: -- FIELDNAME must be enclosed in parentheses, and can be one of: + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide + Balance changes in 2012-01-01..2014-12-31: - - 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 + || 2012 2013 2014 Total + ==================++==================================================================================================================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + ------------------++-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT -Also, FMT can begin with an optional prefix to control how -multi-commodity amounts are rendered: +- Limited wide layout. A width limit reduces the width, but some + commodities will be hidden: -- %_ - render on multiple lines, bottom-aligned (the default) -- %^ - render on multiple lines, top-aligned -- %, - render on one line, comma-separated + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32 + Balance changes in 2012-01-01..2014-12-31: -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. + || 2012 2013 2014 Total + ==================++=========================================================================================================================== + Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + ------------------++--------------------------------------------------------------------------------------------------------------------------- + || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. -Some example formats: +- Tall layout. Each commodity gets a new line (may be different in + each column), and account names are repeated: -- %(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 -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall + Balance changes in 2012-01-01..2014-12-31: + + || 2012 2013 2014 Total + ==================++================================================== + Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT + ------------------++-------------------------------------------------- + || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT + +- Bare layout. Commodity symbols are kept in one column, each + commodity gets its own report row, account names are repeated: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare + Balance changes in 2012-01-01..2014-12-31: + + || Commodity 2012 2013 2014 Total + ==================++============================================= + Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 + ------------------++--------------------------------------------- + || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 + +- Bare layout also affects CSV output, which is useful for producing + data that is easier to consume, eg when making charts: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare + "account","commodity","balance" + "Assets:US:ETrade","GLD","70.00" + "Assets:US:ETrade","ITOT","17.00" + "Assets:US:ETrade","USD","5120.50" + "Assets:US:ETrade","VEA","36.00" + "Assets:US:ETrade","VHT","294.00" + "total","GLD","70.00" + "total","ITOT","17.00" + "total","USD","5120.50" + "total","VEA","36.00" + "total","VHT","294.00" + +- Tidy layout produces normalised "tidy data", where every variable + has its own column and each row represents a single data point. See + https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html + for more. + + This kind of output is the easiest to process with other software. + Here's how it looks: + + $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy + "account","period","start_date","end_date","commodity","value" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00" + "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00" + "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00" + "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00" + + Currently tidy layout is supported only with CSV output. + + In tidy mode, row totals, row averages and column totals are not + shown (-T/--row-total and -A/--average flags are disabled and + -N/--no-total is enabled). + +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 diff --git a/hledger/Hledger/Cli/Commands/Check.txt b/hledger/Hledger/Cli/Commands/Check.txt index 0a1439eb0..e18b576f1 100644 --- a/hledger/Hledger/Cli/Commands/Check.txt +++ b/hledger/Hledger/Cli/Commands/Check.txt @@ -30,8 +30,7 @@ commands, including check: - balancedwithautoconversion - all transactions are balanced, inferring missing amounts where necessary, and possibly converting - commodities using transaction prices or automatically-inferred - transaction prices + commodities using costs or automatically-inferred costs - assertions - all balance assertions in the journal are passing. (This check can be disabled with -I/--ignore-assertions.) @@ -47,7 +46,7 @@ check: - commodities - all commodity symbols used have been declared - balancednoautoconversion - transactions are balanced, possibly using - explicit transaction prices but not inferred ones + explicit costs but not inferred ones Other checks diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index 1026be860..b3b3aaec6 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -38,14 +38,14 @@ separate equity posting for each commodity (as in the print command). With --interleaved, each equity posting is shown next to the posting it balances (good for troubleshooting). -close and prices +close and costs -Transaction prices are ignored (and discarded) by closing/opening -transactions, by default. With --show-costs, they are preserved; there -will be a separate equity posting for each cost in each commodity. This -means balance -B reports will look the same after the transition. Note -if you have many foreign currency or investment transactions, this will -generate very large journal entries. +Costs are ignored (and discarded) by closing/opening transactions, by +default. With --show-costs, they are preserved; there will be a separate +equity posting for each cost in each commodity. This means balance -B +reports will look the same after the transition. Note if you have many +foreign currency or investment transactions, this will generate very +large journal entries. close date @@ -59,12 +59,18 @@ closing date. The opening date is always the following day. So to close on (end of) 2020-12-31 and open on (start of) 2021-01-01, any of these will work: - end date argument explanation - ------------------- ------------------------------------------------ - -e 2021-01-01 end dates are exclusive - -e 2021 equivalent, per smart dates - -p 2020 equivalent, the period's begin date is ignored - date:2020 equivalent query + ----------------------------------------------------------------------- + end date explanation + argument + --------------- ------------------------------------------------------- + -e 2021-01-01 end dates are exclusive + + -e 2021 equivalent, per smart dates + + -p 2020 equivalent, the period's begin date is ignored + + date:2020 equivalent query + ----------------------------------------------------------------------- Example: close asset/liability accounts for file transition diff --git a/hledger/Hledger/Cli/Commands/Codes.txt b/hledger/Hledger/Cli/Commands/Codes.txt index ddc698414..8c6937548 100644 --- a/hledger/Hledger/Cli/Commands/Codes.txt +++ b/hledger/Hledger/Cli/Commands/Codes.txt @@ -16,17 +16,21 @@ You can add a query to select a subset of transactions. Examples: -1/1 (123) - (a) 1 +2022/1/1 (123) Supermarket + Food $5.00 + Checking -1/1 () - (a) 1 +2022/1/2 (124) Post Office + Postage $8.32 + Checking -1/1 - (a) 1 +2022/1/3 Supermarket + Food $11.23 + Checking -1/1 (126) - (a) 1 +2022/1/4 (126) Post Office + Postage $3.21 + Checking $ hledger codes 123 @@ -37,5 +41,4 @@ $ hledger codes -E 123 124 - 126 diff --git a/hledger/Hledger/Cli/Commands/Prices.txt b/hledger/Hledger/Cli/Commands/Prices.txt index d66950ad0..8c0cf3290 100644 --- a/hledger/Hledger/Cli/Commands/Prices.txt +++ b/hledger/Hledger/Cli/Commands/Prices.txt @@ -1,9 +1,8 @@ prices Print market price directives from the journal. With ---infer-market-prices, generate additional market prices from -transaction prices. With --infer-reverse-prices, also generate market -prices by inverting transaction prices. Prices (and postings providing -transaction prices) can be filtered by a query. Price amounts are +--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. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index bfb434ed2..1202af9d7 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -60,20 +60,20 @@ There are some situations where print's output can become unparseable: Normally, the journal entry's explicit or implicit amount style is preserved. For example, when an amount is omitted in the journal, it -will not appear in the output. Similarly, when a transaction price is -implied but not written, it will not appear in the output. You can use -the -x/--explicit flag to make all amounts and transaction prices -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 -B,-V,-X,--value. +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 -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 +-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 the output parseable. -With -B/--cost, amounts with transaction prices are converted to cost -using that price. This can be used for troubleshooting. +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 the one transaction whose description is most similar to DESC, also preferring