From f68309b1069a1a1bd16a40b9dfffd9d4c1bb4471 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 26 Jan 2019 17:00:46 -0800 Subject: [PATCH] acc: integrate CLI help & manual --- hledger/Hledger/Cli/Commands/Accounts.hs | 37 +- hledger/Hledger/Cli/Commands/Accounts.md | 27 ++ hledger/Hledger/Cli/Commands/README | 1 + hledger/hledger.1 | 69 +-- hledger/hledger.info | 239 ++++------ hledger/hledger.txt | 569 +++++++++++------------ hledger/hledger_commands.m4.md | 70 +-- 7 files changed, 414 insertions(+), 598 deletions(-) create mode 100644 hledger/Hledger/Cli/Commands/Accounts.md diff --git a/hledger/Hledger/Cli/Commands/Accounts.hs b/hledger/Hledger/Cli/Commands/Accounts.hs index 2ff78eebc..d497bff15 100644 --- a/hledger/Hledger/Cli/Commands/Accounts.hs +++ b/hledger/Hledger/Cli/Commands/Accounts.hs @@ -13,6 +13,7 @@ The @accounts@ command lists account names: {-# LANGUAGE MultiWayIf #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE ScopedTypeVariables #-} +{-# LANGUAGE TemplateHaskell #-} {-# LANGUAGE CPP #-} module Hledger.Cli.Commands.Accounts ( @@ -33,31 +34,17 @@ import Hledger.Cli.CliOptions -- | Command line options for this command. -accountsmode = (defCommandMode $ ["accounts"] ++ aliases) { - modeHelp = "show account names" `withAliases` aliases - ,modeHelpSuffix = [ - "This command lists account names, either declared with account directives" - ,"(--declared), posted to (--used), or both (default)." - ,"With query arguments, only matched account names and account names" - ,"referenced by matched postings are shown." - ,"It shows a flat list by default. With `--tree`, it uses indentation to" - ,"show the account hierarchy." - ,"In flat mode you can add `--drop N` to omit the first few account name components." - ,"Account names can be depth-clipped with `--depth N` or depth:N." - ] - ,modeGroupFlags = C.Group { - groupUnnamed = [ - flagNone ["declared"] (\opts -> setboolopt "declared" opts) "show account names declared with account directives" - ,flagNone ["used"] (\opts -> setboolopt "used" opts) "show account names referenced by transactions" - ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show short account names, as a tree" - ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, as a list (default)" - ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" - ] - ,groupHidden = [] - ,groupNamed = [generalflagsgroup1] - } - } - where aliases = ["a"] +accountsmode = hledgerCommandMode + $(hereFileRelative "Hledger/Cli/Commands/Accounts.md") + [flagNone ["declared"] (\opts -> setboolopt "declared" opts) "show account names declared with account directives" + ,flagNone ["used"] (\opts -> setboolopt "used" opts) "show account names referenced by transactions" + ,flagNone ["tree"] (\opts -> setboolopt "tree" opts) "show short account names, as a tree" + ,flagNone ["flat"] (\opts -> setboolopt "flat" opts) "show full account names, as a list (default)" + ,flagReq ["drop"] (\s opts -> Right $ setopt "drop" s opts) "N" "flat mode: omit N leading account name parts" + ] + [generalflagsgroup1] + [] + ([], Just $ argsFlag "[QUERY]") -- | The accounts command. accounts :: CliOpts -> Journal -> IO () diff --git a/hledger/Hledger/Cli/Commands/Accounts.md b/hledger/Hledger/Cli/Commands/Accounts.md new file mode 100644 index 000000000..8abb95296 --- /dev/null +++ b/hledger/Hledger/Cli/Commands/Accounts.md @@ -0,0 +1,27 @@ +accounts, a\ +Show account names. + +_FLAGS_ + +This command lists account names, either declared with account directives +(--declared), posted to (--used), or both (the default). +With query arguments, only matched account names and account names +referenced by matched postings are shown. +It shows a flat list by default. With `--tree`, it uses indentation to +show the account hierarchy. +In flat mode you can add `--drop N` to omit the first few account name components. +Account names can be depth-clipped with `depth:N` or `--depth N` or `-N`. + +Examples: + +```shell +$ hledger accounts +assets:bank:checking +assets:bank:saving +assets:cash +expenses:food +expenses:supplies +income:gifts +income:salary +liabilities:debts +``` diff --git a/hledger/Hledger/Cli/Commands/README b/hledger/Hledger/Cli/Commands/README index ebce1a849..778884f25 100644 --- a/hledger/Hledger/Cli/Commands/README +++ b/hledger/Hledger/Cli/Commands/README @@ -23,6 +23,7 @@ It has some special features: - Markdown can be used to influence the appearance of the manuals, especially the html version. But the markup will also appear uninterpreted in the --help output, so use sparingly. + m4 macros can not be used. - Use only one newline on the first line (or cmdargs will display the short help with two newlines after each line). This also means diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 1b412481f..8c8b884ae 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -1350,36 +1350,14 @@ See also \f[C]hledger\f[] for a more organised command list, and \f[C]hledger\ CMD\ \-h\f[] for detailed command help. .SS accounts .PP +accounts, a +.PD 0 +.P +.PD Show account names. -Alias: a. -.TP -.B \f[C]\-\-declared\f[] -show account names declared with account directives -.RS -.RE -.TP -.B \f[C]\-\-used\f[] -show account names posted to by transactions -.RS -.RE -.TP -.B \f[C]\-\-tree\f[] -show short account names and their parents, as a tree -.RS -.RE -.TP -.B \f[C]\-\-flat\f[] -show full account names, as a list (default) -.RS -.RE -.TP -.B \f[C]\-\-drop=N\f[] -in flat mode: omit N leading account name parts -.RS -.RE .PP This command lists account names, either declared with account -directives (\-\-declared), posted to (\-\-used), or both (default). +directives (\-\-declared), posted to (\-\-used), or both (the default). With query arguments, only matched account names and account names referenced by matched postings are shown. It shows a flat list by default. @@ -1387,46 +1365,13 @@ With \f[C]\-\-tree\f[], it uses indentation to show the account hierarchy. In flat mode you can add \f[C]\-\-drop\ N\f[] to omit the first few account name components. -Account names can be depth\-clipped with \f[C]\-\-depth\ N\f[] or -depth:N. +Account names can be depth\-clipped with \f[C]depth:N\f[] or +\f[C]\-\-depth\ N\f[] or \f[C]\-N\f[]. .PP Examples: .IP .nf \f[C] -$\ hledger\ accounts\ \-\-tree -assets -\ \ bank -\ \ \ \ checking -\ \ \ \ saving -\ \ cash -expenses -\ \ food -\ \ supplies -income -\ \ gifts -\ \ salary -liabilities -\ \ debts -\f[] -.fi -.IP -.nf -\f[C] -$\ hledger\ accounts\ \-\-drop\ 1 -bank:checking -bank:saving -cash -food -supplies -gifts -salary -debts -\f[] -.fi -.IP -.nf -\f[C] $\ hledger\ accounts assets:bank:checking assets:bank:saving diff --git a/hledger/hledger.info b/hledger/hledger.info index 4791fddca..dc32616b9 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1020,60 +1020,20 @@ File: hledger.info, Node: accounts, Next: activity, Up: COMMANDS 4.1 accounts ============ -Show account names. Alias: a. - -'--declared' - - show account names declared with account directives -'--used' - - show account names posted to by transactions -'--tree' - - show short account names and their parents, as a tree -'--flat' - - show full account names, as a list (default) -'--drop=N' - - in flat mode: omit N leading account name parts +accounts, a +Show account names. This command lists account names, either declared with account -directives (-declared), posted to (-used), or both (default). With +directives (-declared), posted to (-used), or both (the default). With query arguments, only matched account names and account names referenced by matched postings are shown. It shows a flat list by default. With '--tree', it uses indentation to show the account hierarchy. In flat mode you can add '--drop N' to omit the first few account name -components. Account names can be depth-clipped with '--depth N' or -depth:N. +components. Account names can be depth-clipped with 'depth:N' or +'--depth N' or '-N'. Examples: -$ hledger accounts --tree -assets - bank - checking - saving - cash -expenses - food - supplies -income - gifts - salary -liabilities - debts - -$ hledger accounts --drop 1 -bank:checking -bank:saving -cash -food -supplies -gifts -salary -debts - $ hledger accounts assets:bank:checking assets:bank:saving @@ -1970,8 +1930,7 @@ File: hledger.info, Node: close, Next: files, Prev: check-dupes, Up: COMMAND ========== close, equity - - Prints a "closing balances" transaction and an "opening balances" +Prints a "closing balances" transaction and an "opening balances" transaction that bring account balances to and from zero, respectively. Useful for bringing asset/liability balances forward into a new journal file, or for closing out revenues/expenses to retained earnings at the @@ -2802,98 +2761,98 @@ Node: COMMANDS32539 Ref: #commands32651 Node: accounts33651 Ref: #accounts33749 -Node: activity34995 -Ref: #activity35105 -Node: add35465 -Ref: #add35564 -Node: balance38225 -Ref: #balance38336 -Node: Classic balance report41456 -Ref: #classic-balance-report41629 -Node: Customising the classic balance report42998 -Ref: #customising-the-classic-balance-report43226 -Node: Colour support45300 -Ref: #colour-support45467 -Node: Flat mode45640 -Ref: #flat-mode45788 -Node: Depth limited balance reports46201 -Ref: #depth-limited-balance-reports46401 -Node: Multicolumn balance report46857 -Ref: #multicolumn-balance-report47055 -Node: Budget report52295 -Ref: #budget-report52438 -Node: Nested budgets57122 -Ref: #nested-budgets57234 -Ref: #output-format-160714 -Node: balancesheet60792 -Ref: #balancesheet60928 -Node: balancesheetequity63239 -Ref: #balancesheetequity63388 -Node: cashflow63925 -Ref: #cashflow64053 -Node: check-dates66176 -Ref: #check-dates66303 -Node: check-dupes66420 -Ref: #check-dupes66544 -Node: close66681 -Ref: #close66789 -Node: files70206 -Ref: #files70307 -Node: help70448 -Ref: #help70548 -Node: import71622 -Ref: #import71736 -Node: incomestatement72466 -Ref: #incomestatement72600 -Node: prices75004 -Ref: #prices75119 -Node: print75391 -Ref: #print75501 -Node: print-unique80395 -Ref: #print-unique80521 -Node: register80589 -Ref: #register80716 -Node: Custom register output85217 -Ref: #custom-register-output85346 -Node: register-match86576 -Ref: #register-match86710 -Node: rewrite86893 -Ref: #rewrite87008 -Node: roi87077 -Ref: #roi87175 -Node: stats87291 -Ref: #stats87390 -Node: tags88260 -Ref: #tags88358 -Node: test88594 -Ref: #test88678 -Node: ADD-ON COMMANDS89386 -Ref: #add-on-commands89496 -Node: Official add-ons90783 -Ref: #official-add-ons90923 -Node: api91010 -Ref: #api91099 -Node: ui91151 -Ref: #ui91250 -Node: web91308 -Ref: #web91397 -Node: Third party add-ons91443 -Ref: #third-party-add-ons91618 -Node: diff91753 -Ref: #diff91850 -Node: iadd91949 -Ref: #iadd92063 -Node: interest92146 -Ref: #interest92267 -Node: irr92362 -Ref: #irr92460 -Node: Experimental add-ons92591 -Ref: #experimental-add-ons92743 -Node: autosync93023 -Ref: #autosync93134 -Node: chart93373 -Ref: #chart93492 -Node: check93563 -Ref: #check93665 +Node: activity34448 +Ref: #activity34558 +Node: add34918 +Ref: #add35017 +Node: balance37678 +Ref: #balance37789 +Node: Classic balance report40909 +Ref: #classic-balance-report41082 +Node: Customising the classic balance report42451 +Ref: #customising-the-classic-balance-report42679 +Node: Colour support44753 +Ref: #colour-support44920 +Node: Flat mode45093 +Ref: #flat-mode45241 +Node: Depth limited balance reports45654 +Ref: #depth-limited-balance-reports45854 +Node: Multicolumn balance report46310 +Ref: #multicolumn-balance-report46508 +Node: Budget report51748 +Ref: #budget-report51891 +Node: Nested budgets56575 +Ref: #nested-budgets56687 +Ref: #output-format-160167 +Node: balancesheet60245 +Ref: #balancesheet60381 +Node: balancesheetequity62692 +Ref: #balancesheetequity62841 +Node: cashflow63378 +Ref: #cashflow63506 +Node: check-dates65629 +Ref: #check-dates65756 +Node: check-dupes65873 +Ref: #check-dupes65997 +Node: close66134 +Ref: #close66242 +Node: files69655 +Ref: #files69756 +Node: help69897 +Ref: #help69997 +Node: import71071 +Ref: #import71185 +Node: incomestatement71915 +Ref: #incomestatement72049 +Node: prices74453 +Ref: #prices74568 +Node: print74840 +Ref: #print74950 +Node: print-unique79844 +Ref: #print-unique79970 +Node: register80038 +Ref: #register80165 +Node: Custom register output84666 +Ref: #custom-register-output84795 +Node: register-match86025 +Ref: #register-match86159 +Node: rewrite86342 +Ref: #rewrite86457 +Node: roi86526 +Ref: #roi86624 +Node: stats86740 +Ref: #stats86839 +Node: tags87709 +Ref: #tags87807 +Node: test88043 +Ref: #test88127 +Node: ADD-ON COMMANDS88835 +Ref: #add-on-commands88945 +Node: Official add-ons90232 +Ref: #official-add-ons90372 +Node: api90459 +Ref: #api90548 +Node: ui90600 +Ref: #ui90699 +Node: web90757 +Ref: #web90846 +Node: Third party add-ons90892 +Ref: #third-party-add-ons91067 +Node: diff91202 +Ref: #diff91299 +Node: iadd91398 +Ref: #iadd91512 +Node: interest91595 +Ref: #interest91716 +Node: irr91811 +Ref: #irr91909 +Node: Experimental add-ons92040 +Ref: #experimental-add-ons92192 +Node: autosync92472 +Ref: #autosync92583 +Node: chart92822 +Ref: #chart92941 +Node: check93012 +Ref: #check93114  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 819c8621d..0d9edc67b 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -903,55 +903,20 @@ COMMANDS detailed command help. accounts - Show account names. Alias: a. - - --declared - show account names declared with account directives - - --used show account names posted to by transactions - - --tree show short account names and their parents, as a tree - - --flat show full account names, as a list (default) - - --drop=N - in flat mode: omit N leading account name parts + accounts, a + Show account names. This command lists account names, either declared with account direc- - tives (--declared), posted to (--used), or both (default). With query - arguments, only matched account names and account names referenced by - matched postings are shown. It shows a flat list by default. With - --tree, it uses indentation to show the account hierarchy. In flat - mode you can add --drop N to omit the first few account name compo- - nents. Account names can be depth-clipped with --depth N or depth:N. + tives (--declared), posted to (--used), or both (the default). With + query arguments, only matched account names and account names refer- + enced by matched postings are shown. It shows a flat list by default. + With --tree, it uses indentation to show the account hierarchy. In + flat mode you can add --drop N to omit the first few account name com- + ponents. Account names can be depth-clipped with depth:N or --depth N + or -N. Examples: - $ hledger accounts --tree - assets - bank - checking - saving - cash - expenses - food - supplies - income - gifts - salary - liabilities - debts - - $ hledger accounts --drop 1 - bank:checking - bank:saving - cash - food - supplies - gifts - salary - debts - $ hledger accounts assets:bank:checking assets:bank:saving @@ -965,8 +930,8 @@ COMMANDS activity Show an ascii barchart of posting counts per interval. - The activity command displays an ascii histogram showing transaction - counts by day, week, month or other reporting interval (by day is the + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the default). With query arguments, it counts only matched transactions. $ hledger activity --quarterly @@ -979,24 +944,24 @@ COMMANDS Prompt for transactions and add them to the journal. --no-new-accounts - don't allow creating new accounts; helps prevent typos when + don't allow creating new accounts; helps prevent typos when entering account names - Many hledger users edit their journals directly with a text editor, or - generate them from CSV. For more interactive data entry, there is the - add command, which prompts interactively on the console for new trans- - actions, and appends them to the journal file (if there are multiple + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- + actions, and appends them to the journal file (if there are multiple -f FILE options, the first file is used.) Existing transactions are not - changed. This is the only hledger command that writes to the journal + changed. This is the only hledger command that writes to the journal file. To use it, just run hledger add and follow the prompts. You can add as - many transactions as you like; when you are finished, enter . or press + many transactions as you like; when you are finished, enter . or press control-d or control-c to exit. Features: - o add tries to provide useful defaults, using the most similar recent + o add tries to provide useful defaults, using the most similar recent transaction (by description) as a template. o You can also set the initial defaults with command line arguments. @@ -1004,20 +969,20 @@ COMMANDS o Readline-style edit keys can be used during data entry. o The tab key will auto-complete whenever possible - accounts, descrip- - tions, dates (yesterday, today, tomorrow). If the input area is + tions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - o If the journal defines a default commodity, it will be added to any + o If the journal defines a default commodity, it will be added to any bare numbers entered. o A parenthesised transaction code may be entered following a date. o Comments and tags may be entered following a description or amount. - o If you make a mistake, enter < at any prompt to restart the transac- + o If you make a mistake, enter < at any prompt to restart the transac- tion. - o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Example (see the tutorial for a detailed explanation): @@ -1054,7 +1019,7 @@ COMMANDS show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports) -H --historical @@ -1089,18 +1054,18 @@ COMMANDS select the output format. Supported formats: txt, csv, html. --transpose - transposes rows and columns in multi-column reports. Supported + transposes rows and columns in multi-column reports. Supported formats: txt, csv -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. --pretty-tables use unicode to display prettier tables. --sort-amount - sort by amount instead of account code/name (in flat mode). + sort by amount instead of account code/name (in flat mode). With multiple columns, sorts by the row total, or by row average if that is displayed. @@ -1108,33 +1073,33 @@ COMMANDS display all amounts with reversed sign --budget - show performance compared to budget goals defined by periodic + show performance compared to budget goals defined by periodic transactions The balance command is hledger's most versatile command. Note, despite - the name, it is not always used for showing real-world account bal- - ances; the more accounting-aware balancesheet and incomestatement may + the name, it is not always used for showing real-world account bal- + ances; the more accounting-aware balancesheet and incomestatement may be more convenient for that. By default, it displays all accounts, and each account's change in bal- ance during the entire period of the journal. Balance changes are cal- - culated by adding up the postings in each account. You can limit the - postings matched, by a query, to see fewer accounts, changes over a + culated 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. If you include an account's complete history of postings in the report, - the balance change is equivalent to the account's current ending bal- - ance. For a real-world account, typically you won't have all transac- + the balance change is equivalent to the account's current ending bal- + ance. For a real-world account, typically you won't have all transac- tions in the journal; instead you'll have all transactions after a cer- - tain date, and an "opening balances" transaction setting the correct - starting balance on that date. Then the balance command will show + tain 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). The balance command can produce several styles of report: Classic balance report - This is the original balance report, as found in Ledger. It usually + This is the original balance report, as found in Ledger. It usually looks like this: $ hledger balance @@ -1151,23 +1116,23 @@ COMMANDS -------------------- 0 - By default, accounts are displayed hierarchically, with subaccounts - indented below their parent. At each level of the tree, accounts are - sorted by account code if any, then by account name. Or with + By default, accounts are displayed hierarchically, with subaccounts + indented below their parent. At each level of the tree, accounts are + sorted by account code if any, then by account name. Or with -S/--sort-amount, by their balance amount. "Boring" accounts, which contain a single interesting subaccount and no - balance of their own, are elided into the following line for more com- - pact output. (Eg above, the "liabilities" account.) Use --no-elide to + balance of their own, are elided into the following line for more com- + pact output. (Eg above, the "liabilities" account.) Use --no-elide to prevent this. - Account balances are "inclusive" - they include the balances of any + Account balances are "inclusive" - they include the balances of any subaccounts. - Accounts which have zero balance (and no non-zero subaccounts) are + Accounts which have zero balance (and no non-zero subaccounts) are omitted. Use -E/--empty to show them. - A final total is displayed by default; use -N/--no-total to suppress + A final total is displayed by default; use -N/--no-total to suppress it, eg: $ hledger balance -p 2008/6 expenses --no-total @@ -1176,7 +1141,7 @@ COMMANDS $1 supplies Customising the classic balance report - You can customise the layout of classic balance reports with --for- + You can customise the layout of classic balance reports with --for- mat FMT: $ hledger balance --format "%20(account) %12(total)" @@ -1194,7 +1159,7 @@ COMMANDS 0 The FMT format string (plus a newline) specifies the formatting applied - to each account/balance pair. It may contain any suitable text, with + to each account/balance pair. It may contain any suitable text, with data fields interpolated like so: %[MIN][.MAX](FIELDNAME) @@ -1205,14 +1170,14 @@ COMMANDS o FIELDNAME must be enclosed in parentheses, and can be one of: - o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. o account - the account's name o total - the account's balance/posted total, right justified - Also, FMT can begin with an optional prefix to control how multi-com- + Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: o %_ - render on multiple lines, bottom-aligned (the default) @@ -1221,7 +1186,7 @@ COMMANDS o %, - render on one line, comma-separated - There are some quirks. Eg in one-line mode, %(depth_spacer) has no + 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. @@ -1229,14 +1194,14 @@ COMMANDS o %(total) - the account's total - o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - o %,%-50(account) %25(total) - account name padded to 50 characters, - total padded to 20 characters, with multiple commodities rendered on + o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on one line - o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report Colour support @@ -1247,9 +1212,9 @@ COMMANDS o the output is not being redirected or piped anywhere Flat mode - To see a flat list instead of the default hierarchical display, use - --flat. In this mode, accounts (unless depth-clipped) show their full - names and "exclusive" balance, excluding any subaccount balances. In + To see a flat list instead of the default hierarchical display, use + --flat. In this mode, accounts (unless depth-clipped) show their full + names and "exclusive" balance, excluding any subaccount balances. In this mode, you can also use --drop N to omit the first few account name components. @@ -1258,8 +1223,8 @@ COMMANDS $1 supplies Depth limited balance reports - With --depth N or depth:N or just -N, balance reports show accounts - only to the specified numeric depth. This is very useful to summarise + With --depth N or depth:N or just -N, balance reports show accounts + only to the specified numeric depth. This is very useful to summarise a complex set of accounts and get an overview. $ hledger balance -N -1 @@ -1272,17 +1237,17 @@ COMMANDS inclusive balances at the depth limit. Multicolumn balance report - Multicolumn or tabular balance reports are a very useful hledger fea- - ture, and usually the preferred style. They share many of the above - features, but they show the report as a table, with columns represent- - ing time periods. This mode is activated by providing a reporting + Multicolumn or tabular balance reports are a very useful hledger fea- + ture, and usually the preferred style. They share many of the above + features, but they show the report as a table, with columns represent- + ing time periods. This mode is activated by providing a reporting interval. - There are three types of multicolumn balance report, showing different + There are three types of multicolumn balance report, showing different information: 1. 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 + the account's change of balance in that period. This is useful eg for a monthly income statement: $ hledger balance --quarterly income expenses -E @@ -1297,8 +1262,8 @@ COMMANDS -------------------++--------------------------------- || $-1 $1 0 0 - 2. With --cumulative: each column shows the ending balance for that - period, accumulating the changes across periods, starting from 0 at + 2. With --cumulative: each column shows the ending balance for that + period, accumulating the changes across periods, starting from 0 at the report start date: $ hledger balance --quarterly income expenses -E --cumulative @@ -1314,8 +1279,8 @@ COMMANDS || $-1 0 0 0 3. With --historical/-H: each column shows the actual historical ending - balance for that period, accumulating the changes across periods, - starting from the actual balance at the report start date. This is + balance for that period, accumulating the changes across periods, + starting from the actual balance at the report start date. This is useful eg for a multi-period balance sheet, and when you are showing only the data after a certain start date: @@ -1331,19 +1296,19 @@ COMMANDS ----------------------++------------------------------------- || 0 0 0 - Multicolumn balance reports display accounts in flat mode by default; + Multicolumn balance reports display accounts in flat mode by default; to see the hierarchy, use --tree. - With a reporting interval (like --quarterly above), the report - start/end dates will be adjusted if necessary so that they encompass + 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 peri- ods 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 + 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 oth- erwise would be omitted). With --budget, --empty also shows unbudgeted accounts. @@ -1351,7 +1316,7 @@ COMMANDS 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 + The -A/--average flag adds a column showing the average value in each row. Here's an example of all three: @@ -1375,20 +1340,20 @@ COMMANDS Limitations: In multicolumn reports the -V/--value flag uses the market price on the - report end date, for all columns (not the price on each column's end + report end date, for all columns (not the price on each column's end date). - Eliding of boring parent accounts in tree mode, as in the classic bal- + Eliding of boring parent accounts in tree mode, as in the classic bal- ance report, is not yet supported in multicolumn reports. Budget report - With --budget, extra columns are displayed showing budget goals for - each account and period, if any. Budget goals are defined by periodic - transactions. This is very useful for comparing planned and actual - income, expenses, time usage, etc. --budget is most often combined + With --budget, extra columns are displayed showing budget goals for + each account and period, if any. Budget goals are defined by periodic + transactions. This is very useful for comparing planned and actual + income, expenses, time usage, etc. --budget is most often combined with a report interval. - For example, you can take average monthly expenses in the common + For example, you can take average monthly expenses in the common expense categories to construct a minimal monthly budget: ;; Budget @@ -1433,10 +1398,10 @@ COMMANDS ----------------------++---------------------------------------------------- || 0 [ 0] 0 [ 0] - By default, only accounts with budget goals during the report period - are shown. In the example above, transactions in expenses:gifts and - expenses:supplies are counted towards expenses budget, but accounts - expenses:gifts and expenses:supplies are not shown, as they don't have + By default, only accounts with budget goals during the report period + are shown. In the example above, transactions in expenses:gifts and + expenses:supplies are counted towards expenses budget, but accounts + expenses:gifts and expenses:supplies are not shown, as they don't have any budgets. You can use --empty shows unbudgeted accounts as well: @@ -1477,18 +1442,18 @@ COMMANDS ----------------------++---------------------------------------------------- || 0 [ 0] 0 [ 0] - Note, the -S/--sort-amount flag is not yet fully supported with --bud- + Note, the -S/--sort-amount flag is not yet fully supported with --bud- get. For more examples, see Budgeting and Forecasting. Nested budgets - You can add budgets to any account in your account hierarchy. If you + You can add budgets to any account in your account hierarchy. If you have budgets on both parent account and some of its children, then bud- - get(s) of the child account(s) would be added to the budget of their + get(s) of the child account(s) would be added to the budget of their parent, much like account balances behave. - In the most simple case this means that once you add a budget to any + In the most simple case this means that once you add a budget to any account, all its parents would have budget as well. To illustrate this, consider the following budget: @@ -1498,13 +1463,13 @@ COMMANDS expenses:personal:electronics $100.00 liabilities - With this, monthly budget for electronics is defined to be $100 and - budget for personal expenses is an additional $1000, which implicity + With this, monthly budget for electronics is defined to be $100 and + budget for personal expenses is an additional $1000, which implicity means that budget for both expenses:personal and expenses is $1100. - Transactions in expenses:personal:electronics will be counted both - towards its $100 budget and $1100 of expenses:personal , and transac- - tions in any other subaccount of expenses:personal would be counted + Transactions in expenses:personal:electronics will be counted both + towards its $100 budget and $1100 of expenses:personal , and transac- + tions in any other subaccount of expenses:personal would be counted towards only towards the budget of expenses:personal. For example, let's consider these transactions: @@ -1530,9 +1495,9 @@ COMMANDS expenses:personal $30.00 liabilities - As you can see, we have transactions in expenses:personal:electron- - ics:upgrades and expenses:personal:train tickets, and since both of - these accounts are without explicitly defined budget, these transac- + As you can see, we have transactions in expenses:personal:electron- + ics:upgrades and expenses:personal:train tickets, and since both of + these accounts are without explicitly defined budget, these transac- tions would be counted towards budgets of expenses:personal:electronics and expenses:personal accordingly: @@ -1548,7 +1513,7 @@ COMMANDS -------------------------------++------------------------------- || 0 [ 0] - And with --empty, we can get a better picture of budget allocation and + And with --empty, we can get a better picture of budget allocation and consumption: $ hledger balance --budget -M --empty @@ -1566,16 +1531,16 @@ COMMANDS || 0 [ 0] Output format - The balance command supports output destination and output format + The balance command supports output destination and output format selection. balancesheet This command displays a simple balance sheet, showing historical ending - balances of asset and liability accounts (ignoring any report begin - date). It assumes that these accounts are under a top-level asset or - liability account (case insensitive, plural forms also allowed). Note - this report shows all account balances with normal positive sign (like - conventional financial statements, unlike balance/print/register) + balances of asset and liability accounts (ignoring any report begin + date). It assumes that these accounts are under a top-level asset or + liability account (case insensitive, plural forms also allowed). Note + this report shows all account balances with normal positive sign (like + conventional financial statements, unlike balance/print/register) (experimental). (bs) --change @@ -1583,7 +1548,7 @@ COMMANDS balances --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of historical ending balances -H --historical @@ -1639,16 +1604,16 @@ COMMANDS 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 bal- - ancesheet shows historical ending balances, which is what you need for + report period. As with multicolumn balance reports, you can alter the + report mode with --change/--cumulative/--historical. Normally bal- + ancesheet shows historical ending balances, which is what you need for a balance sheet; note this means it ignores report begin dates. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. balancesheetequity - Just like balancesheet, but also reports Equity (which it assumes is + Just like balancesheet, but also reports Equity (which it assumes is under a top-level equity account). Example: @@ -1678,10 +1643,10 @@ COMMANDS 0 cashflow - This command displays a simple cashflow statement, showing changes in - "cash" accounts. It assumes that these accounts are under a top-level - asset account (case insensitive, plural forms also allowed) and do not - contain receivable or A/R in their name. Note this report shows all + This command displays a simple cashflow statement, showing changes in + "cash" accounts. It assumes that these accounts are under a top-level + asset account (case insensitive, plural forms also allowed) and do not + contain receivable or A/R in their name. Note this report shows all account balances with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). (cf) @@ -1689,7 +1654,7 @@ COMMANDS show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1740,70 +1705,70 @@ COMMANDS $-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 + 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. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. check-dates - Check that transactions are sorted by increasing date. With a query, + Check that transactions are sorted by increasing date. With a query, only matched transactions' dates are checked. check-dupes - Report account names having the same leaf but different prefixes. An + Report account names having the same leaf but different prefixes. An example: http://stefanorodighiero.net/software/hledger-dupes.html close close, equity - Prints a "closing balances" transaction and an "opening balances" + Prints a "closing balances" transaction and an "opening balances" transaction that bring account balances to and from zero, respectively. Useful for bringing asset/liability balances forward into a new journal - file, or for closing out revenues/expenses to retained earnings at the + file, or for closing out revenues/expenses to retained earnings at the end of a period. - The closing transaction transfers balances to "equity:closing bal- - ances". The opening transaction transfers balances from "equity:open- - ing balances". You can chose to print just one of the transactions by + The closing transaction transfers balances to "equity:closing bal- + ances". The opening transaction transfers balances from "equity:open- + ing balances". You can chose to print just one of the transactions by using the --opening or --closing flag. If you split your journal files by time (eg yearly), you will typically - run this command at the end of the year, and save the closing transac- - tion as last entry of the old file, and the opening transaction as the - first entry of the new file. This makes the files self contained, so - that correct balances are reported no matter which of them are loaded. - Ie, if you load just one file, the balances are initialised correctly; - or if you load several files, the redundant closing/opening transac- - tions cancel each other out. (They will show up in print or register - reports; you can exclude them with a query like not:desc:'(open- + run this command at the end of the year, and save the closing transac- + tion as last entry of the old file, and the opening transaction as the + first entry of the new file. This makes the files self contained, so + that correct balances are reported no matter which of them are loaded. + Ie, if you load just one file, the balances are initialised correctly; + or if you load several files, the redundant closing/opening transac- + tions cancel each other out. (They will show up in print or register + reports; you can exclude them with a query like not:desc:'(open- ing|closing) balances'.) If you're running a business, you might also use this command to "close - the books" at the end of an accounting period, transferring income - statement account balances to retained earnings. (You may want to + the books" at the end of an accounting period, transferring income + statement account balances to retained earnings. (You may want to change the equity account name to something like "equity:retained earn- ings".) - By default, the closing transaction is dated yesterday, the balances - are calculated as of end of yesterday, and the opening transaction is - dated today. To close on some other date, use: hledger close -e OPEN- - INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. + By default, the closing transaction is dated yesterday, the balances + are calculated as of end of yesterday, and the opening transaction is + dated today. To close on some other date, use: hledger close -e OPEN- + INGDATE. Eg, to close/open on the 2018/2019 boundary, use -e 2019. You can also use -p or date:PERIOD (any starting date is ignored). Both transactions will include balance assertions for the - closed/reopened accounts. You probably shouldn't use status or real- - ness filters (like -C or -R or status:) with this command, or the gen- + closed/reopened accounts. You probably shouldn't use status or real- + ness filters (like -C or -R or status:) with this command, or the gen- erated balance assertions will depend on these flags. Likewise, if you - run this command with --auto, the balance assertions will probably + run this command with --auto, the balance assertions will probably always require --auto. Examples: - Carrying asset/liability balances into a new file for 2019, all from + Carrying asset/liability balances into a new file for 2019, all from command line: - Warning: we use >> here to append; be careful not to type a single > + Warning: we use >> here to append; be careful not to type a single > which would wipe your journal! $ hledger close -f 2018.journal -e 2019 assets liabilities --opening >>2019.journal @@ -1835,19 +1800,19 @@ COMMANDS assets:checking 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 any of the hledger manuals. - The help command displays any of the main hledger manuals, in one of - several ways. Run it with no argument to list the manuals, or provide + The help command displays any of the main hledger manuals, in one of + several ways. Run it with no argument to list the manuals, or provide a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can + hledger manuals are available in several formats. hledger help will + use the first of these display methods that it finds: info, man, + $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. $ hledger help @@ -1871,7 +1836,7 @@ COMMANDS ... import - Read new transactions added to each FILE since last run, and add them + Read new transactions added to each FILE since last run, and add them to the main journal file. --dry-run @@ -1885,24 +1850,24 @@ COMMANDS ing transactions are always added to the input files in increasing date order, and by saving .latest.FILE state files. - The --dry-run output is in journal format, so you can filter it, eg to + The --dry-run output is in journal format, so you can filter it, eg to see only uncategorised transactions: $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions incomestatement - This command displays a simple income statement, showing revenues and - expenses during a period. It assumes that these accounts are under a - top-level revenue or income or expense account (case insensitive, plu- - ral forms also allowed). Note this report shows all account balances - with normal positive sign (like conventional financial statements, + This command displays a simple income statement, showing revenues and + expenses during a period. It assumes that these accounts are under a + top-level revenue or income or expense account (case insensitive, plu- + ral forms also allowed). Note this report shows all account balances + with normal positive sign (like conventional financial statements, unlike balance/print/register) (experimental). (is) --change show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1936,8 +1901,8 @@ COMMANDS --sort-amount sort by amount instead of account code/name - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense (plural forms also allowed.) $ hledger incomestatement @@ -1962,25 +1927,25 @@ COMMANDS 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 period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. prices - Print market price directives from the journal. With --costs, also - print synthetic market prices based on transaction prices. With + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With --inverted-costs, also print inverse prices based on transaction - prices. Prices (and postings providing prices) can be filtered by a + prices. Prices (and postings providing prices) can be filtered by a query. print Show transactions from the journal. Aliases: p, txns. -m STR --match=STR - show the transaction whose description is most similar to STR, + show the transaction whose description is most similar to STR, and is most recent --new show only newer-dated transactions added in each file since last @@ -1993,7 +1958,7 @@ COMMANDS select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger print @@ -2024,39 +1989,39 @@ COMMANDS it does not preserve directives or inter-transaction comments Normally, the journal entry's explicit or implicit amount style is pre- - served. Ie when an amount is omitted in the journal, it will be omit- - ted in the output. You can use the -x/--explicit flag to make all + served. Ie when an amount is omitted in the journal, it will be omit- + ted in the output. You can use the -x/--explicit flag to make all amounts explicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. Note, - -x will cause postings with a multi-commodity amount (these can arise - when a multi-commodity transaction has an implicit amount) will be - split into multiple single-commodity postings, for valid journal out- + -x will cause postings with a multi-commodity amount (these can arise + when a multi-commodity transaction has an implicit amount) will be + split into multiple single-commodity postings, for valid journal out- put. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. This can be used for troubleshooting. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: 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 spe- - cial 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 + cial 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 + 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. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -2073,20 +2038,20 @@ 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.) print-unique @@ -2099,7 +2064,7 @@ COMMANDS show running total from report start date (default) -H --historical - show historical running total/balance (includes postings before + show historical running total/balance (includes postings before report start date) -A --average @@ -2110,18 +2075,18 @@ COMMANDS show postings' siblings instead -w N --width=N - set output width (default: terminal width or COLUMNS. -wN,M + set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. The register command displays postings, one per line, and their running - total. This is typically used with a query selecting a particular + total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -2130,8 +2095,8 @@ COMMANDS 2008/06/02 save assets:bank:checking $-1 $1 2008/12/31 pay off assets:bank:checking $-1 0 - 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 @@ -2141,23 +2106,23 @@ 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. - 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 @@ -2174,7 +2139,7 @@ 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 @@ -2182,19 +2147,19 @@ 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. 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: <--------------------------------- width (W) ----------------------------------> @@ -2210,26 +2175,26 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. Helps ledger-autosync detect + in the style of the register command. Helps ledger-autosync detect already-seen transactions when importing. rewrite Print all transactions, adding custom postings to the matched ones. roi - Shows time-weighted (TWR) and money-weighted (IRR) rate of return on + Shows time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. See roi --help for more. stats Show some journal statistics. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger stats @@ -2244,61 +2209,61 @@ COMMANDS Accounts : 8 (depth 3) Commodities : 1 ($) - 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. - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags - List all the tag names used in the journal. With a TAGREGEX argument, - only tag names matching the regular expression (case insensitive) are + List all the tag names used in the journal. With a TAGREGEX argument, + only tag names matching the regular expression (case insensitive) are shown. With additional QUERY arguments, only transactions matching the query are considered. test Run built-in unit tests. - Prints test names and their results on stdout. If any test fails or + Prints test names and their results on stdout. If any test fails or gives an error, the exit code will be non-zero. - Test names include a group prefix. If a (exact, case sensitive) group - prefix, or a full test name is provided as the first argument, only + Test names include a group prefix. If a (exact, case sensitive) group + prefix, or a full test name is provided as the first argument, only that group or test is run. - If a numeric second argument is provided, it will set the randomness - seed, for repeatable results from tests using randomness (currently + If a numeric second argument is provided, it will set the randomness + seed, for repeatable results from tests using randomness (currently none of them). - This is mainly used by developers, but it's nice to be able to san- + This is mainly used by developers, but it's nice to be able to san- ity-check your installed hledger executable at any time. All tests are expected to pass - if you ever see otherwise, something has gone wrong, please report a bug! ADD-ON COMMANDS - hledger also searches for external add-on commands, and will include + hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- + whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few + Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them - from hledger. So hledger web --serve --port 9000 will be rejected; + o Flags specific to the add-on must have a preceding -- to hide them + from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. - o You can always run add-ons directly if preferred: + o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger (and - haskell) library functions that built-in commands do, for command-line + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. Here are some hledger add-ons available: @@ -2316,7 +2281,7 @@ ADD-ON COMMANDS hledger-web provides a simple web interface. Third party add-ons - These are maintained separately, and usually updated shortly after a + These are maintained separately, and usually updated shortly after a hledger release. diff @@ -2324,7 +2289,7 @@ ADD-ON COMMANDS journal file and another. iadd - hledger-iadd is a curses-style, more interactive replacement for the + hledger-iadd is a curses-style, more interactive replacement for the add command. interest @@ -2332,19 +2297,19 @@ ADD-ON COMMANDS ing to various schemes. irr - hledger-irr calculates the internal rate of return of an investment + hledger-irr calculates the internal rate of return of an investment account, but it's superseded now by the built-in roi command. Experimental add-ons - These are available in source form in the hledger repo's bin/ direc- + These are available in source form in the hledger repo's bin/ direc- tory; installing them is pretty easy. They may be less mature and doc- - umented than built-in commands. Reading and tweaking these is a good + umented than built-in commands. Reading and tweaking these is a good way to start making your own! autosync hledger-autosync is a symbolic link for easily running ledger-autosync, - if installed. ledger-autosync does deduplicating conversion of OFX - data and some CSV formats, and can also download the data if your bank + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank offers OFX Direct Connect. chart @@ -2354,21 +2319,21 @@ ADD-ON COMMANDS hledger-check.hs checks more powerful account balance assertions. ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). BUGS - The need to precede addon command options with -- when invoked from + The need to precede addon command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -2381,33 +2346,33 @@ BUGS In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and - remember you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and + remember you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu @@ -2426,7 +2391,7 @@ TROUBLESHOOTING $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ bash --login - If we preferred to use eg fr_FR.utf8, we might have to install that + If we preferred to use eg fr_FR.utf8, we might have to install that first: $ apt-get install language-pack-fr @@ -2447,7 +2412,7 @@ TROUBLESHOOTING REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -2461,7 +2426,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/hledger/hledger_commands.m4.md b/hledger/hledger_commands.m4.md index 32dbffab8..d6f816c05 100644 --- a/hledger/hledger_commands.m4.md +++ b/hledger/hledger_commands.m4.md @@ -24,76 +24,8 @@ for each command: name, synopsis, description, examples. --> ## accounts -Show account names. Alias: a. -`--declared` -: show account names declared with account directives - -`--used` -: show account names posted to by transactions - -`--tree` -: show short account names and their parents, as a tree - -`--flat` -: show full account names, as a list (default) - -`--drop=N` -: in flat mode: omit N leading account name parts - -This command lists account names, either declared with account directives -(--declared), posted to (--used), or both (default). -With query arguments, only matched account names and account names -referenced by matched postings are shown. -It shows a flat list by default. With `--tree`, it uses indentation to -show the account hierarchy. -In flat mode you can add `--drop N` to omit the first few account name components. -Account names can be depth-clipped with `--depth N` or depth:N. - -Examples: - -_col3_({{ -_shell_({{ -$ hledger accounts --tree -assets - bank - checking - saving - cash -expenses - food - supplies -income - gifts - salary -liabilities - debts -}}) -}},{{ -_shell_({{ -$ hledger accounts --drop 1 -bank:checking -bank:saving -cash -food -supplies -gifts -salary -debts -}}) -}},{{ -_shell_({{ -$ hledger accounts -assets:bank:checking -assets:bank:saving -assets:cash -expenses:food -expenses:supplies -income:gifts -income:salary -liabilities:debts -}}) -}}) +_include_(Hledger/Cli/Commands/Accounts.md) ## activity Show an ascii barchart of posting counts per interval.