diff --git a/hledger/Hledger/Cli/Commands/Accounts.txt b/hledger/Hledger/Cli/Commands/Accounts.txt index 96f02066a..715a10497 100644 --- a/hledger/Hledger/Cli/Commands/Accounts.txt +++ b/hledger/Hledger/Cli/Commands/Accounts.txt @@ -9,43 +9,40 @@ Flags: --unused list accounts declared but not used --find list the first account matched by the first argument (a case-insensitive infix regexp) - --types also show account types when known - --positions also show where accounts were declared --directives show as account directives, for use in journals + --locations also show where accounts were declared + --types also show account types when known -l --flat list/tree mode: show accounts as a flat list (default) -t --tree list/tree mode: show accounts as a tree --drop=N flat mode: omit N leading account name parts -This command lists account names - all of them by default. or just the -ones which have been used in transactions, or declared with account -directives, or used but not declared, or declared but not used, or just -the first account name matched by a pattern. +This command lists account names - all of them by default, or just the +ones which have been used in transactions (-u/--used), or declared with +account directives (-d/--declared), or used but not declared +(--undeclared), or declared but not used (--unused), or just the first +one matched by a pattern (--find, returning a non-zero exit code if it +fails). You can add query arguments to select a subset of transactions or accounts. -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. - -With --types, it also shows each account's type, if it's known. (See -Declaring accounts > Account types.) - -With --positions, it also shows the file and line number of each -account's declaration, if any, and the account's overall declaration -order; these may be useful when troubleshooting account display order. - With --directives, it shows valid account directives which could be pasted into a journal file. This is useful together with --undeclared when updating your account declarations to satisfy hledger check accounts. -The --find flag can be used to look up a single account name, in the -same way that the aregister command does. It returns the -alphanumerically-first matched account name, or if none can be found, it -fails with a non-zero exit code. +With --locations, it also shows the file and line number of each +account's declaration, if any, and the account's overall declaration +order; these may be useful when troubleshooting account display order. + +With --types, it also shows each account's type, if it's known. (See +Declaring accounts > Account types.) + +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: diff --git a/hledger/Hledger/Cli/Commands/Aregister.txt b/hledger/Hledger/Cli/Commands/Aregister.txt index 53c609dba..12dce4c26 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.txt +++ b/hledger/Hledger/Cli/Commands/Aregister.txt @@ -37,24 +37,22 @@ necessarily in historical mode). As a quick rule of thumb: - use aregister for reviewing and reconciling real-world asset/liability accounts - use register for reviewing detailed revenues/expenses. -aregister requires one argument: the account to report on. You can write -either the full account name, or a case-insensitive regular expression -which will select the alphabetically first matched account. - -When there are multiple matches, the alphabetically-first choice can be -surprising; eg if you have assets:per:checking 1 and -assets:biz:checking 2 accounts, hledger areg checking would select -assets:biz:checking 2. It's just a convenience to save typing, so if in -doubt, write the full account name, or a distinctive substring that -matches uniquely. +Note this command's non-standard, and required, first argument; it +specifies the account whose register will be shown. You can write the +account's name, or (to save typing) a case-insensitive infix regular +expression matching the name, which selects the alphabetically first +matched account. (For example, if you have assets:personal checking and +assets:business checking, hledger areg checking would select +assets:business checking.) Transactions involving subaccounts of this account will also be shown. aregister ignores depth limits, so its final total will always match a historical balance report with similar arguments. -Any additional arguments form a query which will filter the transactions -shown. Note some queries will disturb the running balance, causing it to -be different from the account's real-world running balance. +Any additional arguments are standard query arguments, which will limit +the transactions shown. Note some queries will disturb the running +balance, causing it to be different from the account's real-world +running balance. An example: this shows the transactions and historical running balance during july, in the first account whose name contains "checking": diff --git a/hledger/Hledger/Cli/Commands/Commodities.txt b/hledger/Hledger/Cli/Commands/Commodities.txt index a312ea3d2..aadb7e206 100644 --- a/hledger/Hledger/Cli/Commands/Commodities.txt +++ b/hledger/Hledger/Cli/Commands/Commodities.txt @@ -7,10 +7,13 @@ Flags: --declared list commodities declared --undeclared list commodities used but not declared --unused list commodities declared but not used + --find list the first commodity matched by the first + argument (a case-insensitive infix regexp) This command lists commodity symbols/names - all of them by default, or just the ones which have been used in transactions or P directives, or declared with commodity directives, or used but not declared, or -declared but not used. +declared but not used, or just the first one matched by a pattern (with +--find, returning a non-zero exit code if it fails). You can add cur: query arguments to further limit the commodities. diff --git a/hledger/Hledger/Cli/Commands/Payees.txt b/hledger/Hledger/Cli/Commands/Payees.txt index ec0e5249e..4a37796df 100644 --- a/hledger/Hledger/Cli/Commands/Payees.txt +++ b/hledger/Hledger/Cli/Commands/Payees.txt @@ -7,11 +7,14 @@ Flags: --declared list payees declared --undeclared list payees used but not declared --unused list payees declared but not used + --find list the first payee matched by the first + argument (a case-insensitive infix regexp) This command lists unique payee/payer names - all of them by default, or just the ones which have been used in transaction descriptions, or declared with payee directives, or used but not declared, or declared -but not used. +but not used, or just the first one matched by a pattern (with --find, +returning a non-zero exit code if it fails). The payee/payer name is the part of the transaction description before a | character (or if there is no |, the whole description). diff --git a/hledger/Hledger/Cli/Commands/Print.md b/hledger/Hledger/Cli/Commands/Print.md index b764ed322..268d6ec1e 100644 --- a/hledger/Hledger/Cli/Commands/Print.md +++ b/hledger/Hledger/Cli/Commands/Print.md @@ -11,10 +11,6 @@ Flags: description closest to DESC --new show only newer-dated transactions added in each file since last run - --no-lots remove lot subaccounts and their balance - assertions - --no-lots2 remove lot subaccounts and their costs and - balance assertions (can produce unbalanced entries) --round=TYPE how much rounding or padding should be done when displaying amounts ? none - show original decimal digits, diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index 04af4e73f..98ddea735 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -5,15 +5,11 @@ Show full journal entries, representing transactions. Flags: -x --explicit show all amounts explicitly --invert display all amounts with reversed sign - --location add tags showing file paths and line numbers + --locations add tags showing file paths and line numbers -m --match=DESC fuzzy search for one recent transaction with description closest to DESC --new show only newer-dated transactions added in each file since last run - --no-lots remove lot subaccounts and their balance - assertions - --no-lots2 remove lot subaccounts and their costs and - balance assertions (can produce unbalanced entries) --round=TYPE how much rounding or padding should be done when displaying amounts ? none - show original decimal digits, @@ -56,7 +52,7 @@ $ hledger print -f examples/sample.journal date:200806 expenses:supplies $1 assets:cash $-2 -print explicitness +print amount explicitness Normally, whether posting amounts are implicit or explicit is preserved. For example, when an amount is omitted in the journal, it will not @@ -73,19 +69,22 @@ amount (which can arise when a multi-commodity transaction has an implicit amount) to be split into multiple single-commodity postings, keeping the output parseable. -print amount style +print alignment Amounts are shown right-aligned within each transaction (but not aligned -across all transactions; you can do that with ledger-mode in Emacs). +across all transactions; you can achieve that with ledger-mode in +Emacs). -Amounts will be (mostly) normalised to their commodity display style: -their symbol placement, decimal mark, and digit group marks will be made -consistent. By default, decimal digits are shown as they are written in -the journal. +print amount style -With the --round (Added in 1.32) option, print will try increasingly -hard to display decimal digits according to the commodity display -styles: +Amounts will be displayed mostly in their commodity's display style, +with standardised symbol placement, decimal mark, and digit group marks. +This does not apply to their decimal digits; print normally shows the +same decimal digits that are recorded in each journal entry. + +You can override the decimal precisions with print's special --round +option (since 1.32). --round tries to show amounts with their +commodities' standard decimal precisions, increasingly strongly: - --round=none show amounts with original precisions (default) - --round=soft add/remove decimal zeros in amounts (except costs) @@ -93,30 +92,35 @@ styles: digits - --round=all round all amounts and costs -soft is good for non-lossy cleanup, formatting amounts more consistently -where it's safe to do so. +soft is good for non-lossy cleanup, displaying more consistent decimals +where possible, without making entries unbalanced. -hard and all can cause print to show invalid unbalanced journal entries; -they may be useful eg for stronger cleanup, with manual fixups when -needed. +hard or all can be good for stronger cleanup, when decimal rounding is +wanted. Note rounding can produce unbalanced journal entries, perhaps +requiring manual fixup. print parseability -print's output is usually a valid hledger journal, and you can process -it again with a second hledger command. This can be useful for certain -kinds of search (though the same can be achieved with expr: queries -now): +Normally, print's output is a valid hledger journal, which you can +"pipe" to a second hledger command for further processing. This is +sometimes convenient for achieving certain kinds of query (though less +needed now that queries have become more powerful): # Show running total of food expenses paid from cash. # -f- reads from stdin. -I/--ignore-assertions is sometimes needed. $ hledger print assets:cash | hledger -f- -I reg expenses:food -There are some situations where print's output can become unparseable: +But here are some things which can cause print's output to become +unparseable: -- Value reporting affects posting amounts but not balance assertion or - balance assignment amounts, potentially causing those to fail. -- Auto postings can generate postings with too many missing amounts. -- Account aliases can generate bad account names. +- --round (see above) can disrupt transaction balancing. +- Account aliases or pivoting can disrupt account names, balance + assertions, or balance assignments. +- Value reporting also can disrupt balance assertions or balance + assignments. +- Auto postings can generate too many amountless postings. +- --infer-costs or --infer-equity can generate too-complex redundant + costs. print, other features @@ -126,28 +130,17 @@ With --invert, posting amounts are shown with their sign flipped. It could be useful if you have accidentally recorded some transactions with the wrong signs. -With --location, print adds the source file and line number to every -transaction, as a tag. +With --new, print shows only transactions it has not seen on a previous +run. This uses the same deduplication system as the import command. (See +import's docs for details.) With -m DESC/--match=DESC, print shows one recent transaction whose description is most similar to DESC. DESC should contain at least two characters. If there is no similar-enough match, no transaction will be shown and the program exit code will be non-zero. -With --new, print shows only transactions it has not seen on a previous -run, using the same deduplication system as the import command (see -import's docs). (Unlike import, there is no dry run - you'll see the new -transactions only once.) - -With --no-lots, print will hide lot subaccounts, and their balance -assertions. (Or with --no-lots2, their costs will also be removed, -possibly producing unbalanced entries.) Lot subaccounts are leaf -accounts whose last part begins with a date (YYYY-MM-DD or YYYYMMDD). -This can be useful for converting journal entries which use explicit lot -subaccounts, if you want to discard lot information. Note the -limitations: all postings in the same account with similar cost will be -consolidated, and all posting comments will be removed (including from -non-lot postings). +With --locations, print adds the source file and line number to every +transaction, as a tag. print output format diff --git a/hledger/Hledger/Cli/Commands/Register.txt b/hledger/Hledger/Cli/Commands/Register.txt index ae9ab1daf..0d76d7ee4 100644 --- a/hledger/Hledger/Cli/Commands/Register.txt +++ b/hledger/Hledger/Cli/Commands/Register.txt @@ -116,7 +116,7 @@ $ hledger register --monthly income -E 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 +$ hledger register --monthly assets --depth 1 2008/01 assets $1 $1 2008/06 assets $-1 0 2008/12 assets $-1 $-1 diff --git a/hledger/Hledger/Cli/Commands/Tags.txt b/hledger/Hledger/Cli/Commands/Tags.txt index b12540c98..4d5cf5d39 100644 --- a/hledger/Hledger/Cli/Commands/Tags.txt +++ b/hledger/Hledger/Cli/Commands/Tags.txt @@ -7,19 +7,23 @@ Flags: --declared list tags declared --undeclared list tags used but not declared --unused list tags declared but not used + --find list the first tag whose name is matched by the + first argument (a case-insensitive infix regexp) --values list tag values instead of tag names --parsed show them in the order they were parsed (mostly), including duplicates This command lists tag names - all of them by default, or just the ones which have been used on transactions/postings/accounts, or declared with -tag directives, or used but not declared, or declared but not used. +tag directives, or used but not declared, or declared but not used, or +just the first one matched by a pattern (with --find, returning a +non-zero exit code if it fails). -You can add one TAGREGEX argument, to show only tags whose name is -matched by this case-insensitive, infix-matching regular expression. - -After that, you can add query arguments to filter the transactions, -postings, or accounts providing tags. +Note this command's non-standard first argument: it is a +case-insensitive infix regular expression for matching tag names, which +limits the tags shown. Any additional arguments are standard query +arguments, which limit the transactions, postings, or accounts providing +tags. With --values, the tags' unique non-empty values are listed instead.