From fcfa7ed78a4363f700f5f64a9f9b39aa74a5c4e8 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 22 Nov 2023 22:56:08 -1000 Subject: [PATCH] ;doc: update command help --- hledger/Hledger/Cli/Commands/Aregister.txt | 24 ++-- hledger/Hledger/Cli/Commands/Balance.txt | 6 +- hledger/Hledger/Cli/Commands/Balancesheet.txt | 2 +- .../Cli/Commands/Balancesheetequity.txt | 2 +- hledger/Hledger/Cli/Commands/Cashflow.txt | 2 +- hledger/Hledger/Cli/Commands/Import.txt | 31 ++--- .../Hledger/Cli/Commands/Incomestatement.txt | 2 +- hledger/Hledger/Cli/Commands/Prices.txt | 19 ++- hledger/Hledger/Cli/Commands/Print.txt | 117 +++++++++++------- hledger/Hledger/Cli/Commands/Register.txt | 4 +- 10 files changed, 129 insertions(+), 80 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Aregister.txt b/hledger/Hledger/Cli/Commands/Aregister.txt index a6e92f347..c172e72f9 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.txt +++ b/hledger/Hledger/Cli/Commands/Aregister.txt @@ -61,16 +61,20 @@ ensure perfect alignment, at the cost of more time and memory, use the --align-all flag. This command also supports the output destination and output format -options. The output formats supported are txt, csv, and json. +options. The output formats supported are txt, csv, tsv, and json. -aregister and custom posting dates +aregister and posting dates -Transactions whose date is outside the report period can still be shown, -if they have a posting to this account dated inside the report period. -(And in this case it's the posting date that is shown.) This ensures -that aregister can show an accurate historical running balance, matching -the one shown by register -H with the same arguments. +aregister always shows one line (and date and amount) per transaction. +But sometimes transactions have postings with different dates. Also, not +all of a transaction's postings may be within the report period. To +resolve this, aregister shows the earliest of the transaction's date and +posting dates that is in-period, and the sum of the in-period postings. +In other words it will show a combined line item with just the earliest +date, and the running balance will (temporarily, until the transaction's +last posting) be inaccurate. Use register -H if you need to see the +individual postings. -To filter strictly by transaction date instead, add the --txn-dates -flag. If you use this flag and some of your postings have custom dates, -it's probably best to assume the running balance is wrong. +There is also a --txn-dates flag, which filters strictly by transaction +date, ignoring posting dates. This too can cause an inaccurate running +balance. diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index a9b6bfe94..0e663bec4 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -66,9 +66,9 @@ balance can show.. - commodities displayed on the same line or multiple lines (--layout) This command supports the output destination and output format options, -with output formats txt, csv, json, and (multi-period reports only:) -html. In txt output in a colour-supporting terminal, negative amounts -are shown in red. +with output formats txt, csv, tsv, json, and (multi-period reports +only:) html. In txt output in a colour-supporting terminal, negative +amounts are shown in red. The --related/-r flag shows the balance of the other postings in the transactions of the postings which would normally be shown. diff --git a/hledger/Hledger/Cli/Commands/Balancesheet.txt b/hledger/Hledger/Cli/Commands/Balancesheet.txt index 0341b0667..7d8196fa8 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheet.txt +++ b/hledger/Hledger/Cli/Commands/Balancesheet.txt @@ -41,5 +41,5 @@ It is similar to hledger balance -H assets liabilities, but with smarter account detection, and liabilities displayed with their sign flipped. This command also supports the output destination and output format -options The output formats supported are txt, csv, html, and +options The output formats supported are txt, csv, tsv, html, and (experimental) json. diff --git a/hledger/Hledger/Cli/Commands/Balancesheetequity.txt b/hledger/Hledger/Cli/Commands/Balancesheetequity.txt index b327a4f92..ce5a652db 100644 --- a/hledger/Hledger/Cli/Commands/Balancesheetequity.txt +++ b/hledger/Hledger/Cli/Commands/Balancesheetequity.txt @@ -46,5 +46,5 @@ smarter account detection, and liabilities/equity displayed with their sign flipped. This command also supports the output destination and output format -options The output formats supported are txt, csv, html, and +options The output formats supported are txt, csv, tsv, html, and (experimental) json. diff --git a/hledger/Hledger/Cli/Commands/Cashflow.txt b/hledger/Hledger/Cli/Commands/Cashflow.txt index f017159a4..598e85795 100644 --- a/hledger/Hledger/Cli/Commands/Cashflow.txt +++ b/hledger/Hledger/Cli/Commands/Cashflow.txt @@ -47,5 +47,5 @@ hledger balance assets not:fixed not:investment not:receivable, but with smarter account detection. This command also supports the output destination and output format -options The output formats supported are txt, csv, html, and +options The output formats supported are txt, csv, tsv, html, and (experimental) json. diff --git a/hledger/Hledger/Cli/Commands/Import.txt b/hledger/Hledger/Cli/Commands/Import.txt index c3ff42286..177766d4a 100644 --- a/hledger/Hledger/Cli/Commands/Import.txt +++ b/hledger/Hledger/Cli/Commands/Import.txt @@ -1,9 +1,9 @@ import -Read new transactions added to each FILE since last run, and add them to -the journal. Or with --dry-run, just print the transactions that would -be added. Or with --catchup, just mark all of the FILEs' transactions as -imported, without actually importing any. +Read new transactions added to each FILE provided as arguments since +last run, and add them to the journal. Or with --dry-run, just print the +transactions that would be added. Or with --catchup, just mark all of +the FILEs' current transactions as imported, without importing them. _FLAGS @@ -23,14 +23,15 @@ common import source, and these docs focus on that case. Deduplication -As a convenience import does deduplication while reading transactions. -This does not mean "ignore transactions that look the same", but rather -"ignore transactions that have been seen before". This is intended for -when you are periodically importing foreign data which may contain -already-imported transactions. So eg, if every day you download bank CSV -files containing redundant data, you can safely run -hledger import bank.csv and only new transactions will be imported. -(import is idempotent.) +import does time-based deduplication, to detect only the new +transactions since the last successful import. (This does not mean +"ignore transactions that look the same", but rather "ignore +transactions that have been seen before".) This is intended for when you +are periodically importing downloaded data, which may overlap with +previous downloads. Eg if every week (or every day) you download a +bank's last three months of CSV data, you can safely run +hledger import thebank.csv each time and only new transactions will be +imported. Since the items being read (CSV records, eg) often do not come with unique identifiers, hledger detects new transactions by date, assuming @@ -48,8 +49,10 @@ you import often, the new transactions will be few, so less likely to be the ones affected). hledger remembers the latest date processed in each input file by saving -a hidden ".latest" state file in the same directory. Eg when reading -finance/bank.csv, it will look for and update the +a hidden ".latest.FILE" file in FILE's directory (after a succesful +import). + +Eg when reading finance/bank.csv, it will look for and update the finance/.latest.bank.csv state file. The format is simple: one or more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I have processed transactions up to this date, and this many of them on that diff --git a/hledger/Hledger/Cli/Commands/Incomestatement.txt b/hledger/Hledger/Cli/Commands/Incomestatement.txt index 91f8f4534..e0cbf7cc2 100644 --- a/hledger/Hledger/Cli/Commands/Incomestatement.txt +++ b/hledger/Hledger/Cli/Commands/Incomestatement.txt @@ -43,5 +43,5 @@ smarter account detection, and revenues/income displayed with their sign flipped. This command also supports the output destination and output format -options The output formats supported are txt, csv, html, and +options The output formats supported are txt, csv, tsv, html, and (experimental) json. diff --git a/hledger/Hledger/Cli/Commands/Prices.txt b/hledger/Hledger/Cli/Commands/Prices.txt index bdb1a4cd4..fc6866833 100644 --- a/hledger/Hledger/Cli/Commands/Prices.txt +++ b/hledger/Hledger/Cli/Commands/Prices.txt @@ -1,9 +1,18 @@ prices -Print market price directives from the journal. With ---infer-market-prices, generate additional market prices from costs. -With --infer-reverse-prices, also generate market prices by inverting -known prices. Prices can be filtered by a query. Price amounts are -displayed with their full precision. +Print the market prices declared with P directives. With +--infer-market-prices, also show any additional prices inferred from +costs. With --show-reverse, also show additional prices inferred by +reversing known prices. + +Price amounts are always displayed with their full precision, except for +reverse prices which are limited to 8 decimal digits. + +Prices can be filtered by a date:, cur: or amt: query. + +Generally if you run this command with --infer-market-prices +--show-reverse, it will show the same prices used internally to +calculate value reports. But if in doubt, you can inspect those directly +by running the value report with --debug=2. _FLAGS diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index 0a0b5d121..c5fe5ba28 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -7,26 +7,14 @@ _FLAGS The print command displays full journal entries (transactions) from the journal file, sorted by date (or with --date2, by secondary date). -Amounts are shown mostly normalised to commodity display style, eg the -placement of commodity symbols will be consistent. All of their decimal -places are shown, as in the original journal entry (with one alteration: -in some cases trailing zeroes are added.) - -Amounts are shown right-aligned within each transaction (but not across -all transactions). - Directives and inter-transaction comments are not shown, currently. This means the print command is somewhat lossy, and if you are using it to -reformat your journal you should take care to also copy over the -directives and file-level comments. +reformat/regenerate your journal you should take care to also copy over +the directives and inter-transaction comments. Eg: -$ hledger print -2008/01/01 income - assets:bank:checking $1 - income:salary $-1 - +$ hledger print -f examples/sample.journal date:200806 2008/06/01 gift assets:bank:checking $1 income:gifts $-1 @@ -40,13 +28,55 @@ $ hledger print expenses:supplies $1 assets:cash $-2 -2008/12/31 * pay off - liabilities:debts $1 - assets:bank:checking $-1 +print explicitness + +Normally, whether posting amounts are implicit or explicit is preserved. +For example, when an amount is omitted in the journal, it will not +appear in the output. Similarly, if a conversion cost is implied but not +written, it will not appear in the output. + +You can use the -x/--explicit flag to force explicit display of all +amounts and costs. This 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. + +The -x/--explicit flag will cause any postings with a multi-commodity +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 + +Amounts are shown right-aligned within each transaction (but not aligned +across all transactions; you can do 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. + +With the --round option, print will try increasingly hard to display +decimal digits according to the commodity display styles: + +- --round=none show amounts with original precisions (default) +- --round=soft add/remove decimal zeros in amounts (except costs) +- --round=hard round amounts (except costs), possibly hiding + significant 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. + +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. + +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, eg: +kinds of search (though the same can be achieved with expr: queries +now): # Show running total of food expenses paid from cash. # -f- reads from stdin. -I/--ignore-assertions is sometimes needed. @@ -59,35 +89,38 @@ There are some situations where print's output can become unparseable: - Auto postings can generate postings with too many missing amounts. - Account aliases can generate bad account names. -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 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. +print, other features -Note, -x/--explicit will cause postings with a multi-commodity amount -(these can arise when a multi-commodity transaction has an implicit -amount) to be split into multiple single-commodity postings, keeping the -output parseable. +With -B/--cost, amounts with costs are shown converted to cost. -With -B/--cost, amounts with costs are converted to cost using that -price. This can be used for troubleshooting. +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 does a fuzzy search for one recent -transaction whose description is most similar to DESC. DESC should -contain at least two characters. If there is no similar-enough match, no -transaction will be shown and the program exit code will be non-zero. +With -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, hledger prints only transactions it has not seen on a -previous run. This uses the same deduplication system as the import -command. (See import's docs for details.) +print output format This command also supports the output destination and output format -options The output formats supported are txt, csv, and (experimental) -json and sql. +options The output formats supported are txt, beancount, csv, tsv, json +and sql. + +Experimental: The beancount format tries to produce Beancount-compatible +output. It is very basic and may require additional manual fixups: + +- Transaction and postings with unmarked status are converted to + cleared (`*``) status. +- Transactions' payee and or note are wrapped in double quotes. +- Transaction tags are copied to Beancount #tag format. +- Account name parts are capitalised, and if the first account name + part is not one of Assets, Liabilities, Equity, Income, or Expenses, + "Equity:" is prepended. +- The $ commodity symbol is converted to USD. +- An open directive is generated for each account used, on the + earliest transaction date. Here's an example of print's CSV output: diff --git a/hledger/Hledger/Cli/Commands/Register.txt b/hledger/Hledger/Cli/Commands/Register.txt index e70e8c6ce..7c66448cc 100644 --- a/hledger/Hledger/Cli/Commands/Register.txt +++ b/hledger/Hledger/Cli/Commands/Register.txt @@ -125,5 +125,5 @@ $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 This command also supports the output destination and output format -options The output formats supported are txt, csv, and (experimental) -json. +options The output formats supported are txt, csv, tsv, and +(experimental) json.