From 95b67ef86b1e2a8b77b9be21f161ea80f507a360 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Tue, 22 Aug 2023 08:40:46 +0100 Subject: [PATCH] ;doc: update command help --- hledger/Hledger/Cli/Commands/Balance.txt | 9 +++++-- hledger/Hledger/Cli/Commands/Check.txt | 33 ++++++++++++------------ hledger/Hledger/Cli/Commands/Import.txt | 2 ++ hledger/Hledger/Cli/Commands/Print.txt | 2 +- 4 files changed, 27 insertions(+), 19 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 3c25059b3..a9b6bfe94 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -457,7 +457,7 @@ or one of the equivalent simpler flags: - -V/--market : like --value=end - -X COMM/--exchange COMM : like --value=end,COMM -See Cost reporting and Valuation for more about these. +See Cost reporting and Value reporting for more about these. Combining balance report types @@ -808,7 +808,7 @@ Period of generated transactions: - possibly restricted by a period specified in the periodic transaction rule. -Data layout +Balance report layout The --layout option affects how balance reports show multi-commodity amounts and commodity symbols, which can improve readability. It can @@ -914,6 +914,11 @@ Examples: "total","VEA","36.00" "total","VHT","294.00" +- Note: bare layout will sometimes display an extra row for the + no-symbol commodity, because of zero amounts (hledger treats zeroes + as commodity-less, usually). This can break hledger-bar confusingly + (workaround: add a cur: query to exclude the no-symbol row). + - Tidy layout produces normalised "tidy data", where every variable has its own column and each row represents a single data point. See https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html diff --git a/hledger/Hledger/Cli/Commands/Check.txt b/hledger/Hledger/Cli/Commands/Check.txt index 007f2c2c1..317faf4f5 100644 --- a/hledger/Hledger/Cli/Commands/Check.txt +++ b/hledger/Hledger/Cli/Commands/Check.txt @@ -29,9 +29,9 @@ commands, including check: - parseable - data files are well-formed and can be successfully parsed -- balancedwithautoconversion - all transactions are balanced, - inferring missing amounts where necessary, and possibly converting - commodities using costs or automatically-inferred costs +- autobalanced - all transactions are balanced, after converting to + cost. Missing amounts and missing costs are inferred automatically + where possible. - assertions - all balance assertions in the journal are passing. (This check can be disabled with -I/--ignore-assertions.) @@ -46,8 +46,9 @@ check: - commodities - all commodity symbols used have been declared -- balancednoautoconversion - transactions are balanced, possibly using - explicit costs but not inferred ones +- balanced - all transactions are balanced after converting to cost, + without inferring missing costs. If conversion costs are required, + they must be explicit. Other checks @@ -60,7 +61,7 @@ therefore optional: - payees - all payees used by transactions have been declared - recentassertions - all accounts with balance assertions have a - balance assertion no more than 7 days before their latest posting + balance assertion within 7 days of their latest posting - tags - all tags used by transactions have been declared @@ -83,13 +84,13 @@ Cookbook -> Scripting. More about specific checks hledger check recentassertions will complain if any balance-asserted -account does not have a balance assertion within 7 days before its -latest posting. This aims to prevent the situation where you are -regularly updating your journal, but forgetting to check your balances -against the real world, then one day must dig back through months of -data to find an error. It assumes that adding a balance assertion -requires/reminds you to check the real-world balance. That may not be -true if you auto-generate balance assertions from bank data; in that -case, I recommend to import transactions uncleared, then use the -manual-review-and-mark-cleared phase as a reminder to check the latest -assertions against real-world balances. +account has postings more than 7 days after its latest balance +assertion. This aims to prevent the situation where you are regularly +updating your journal, but forgetting to check your balances against the +real world, then one day must dig back through months of data to find an +error. It assumes that adding a balance assertion requires/reminds you +to check the real-world balance. (That may not be true if you +auto-generate balance assertions from bank data; in that case, I +recommend to import transactions uncleared, and when you manually review +and clear them, also check the latest assertion against the real-world +balance.) diff --git a/hledger/Hledger/Cli/Commands/Import.txt b/hledger/Hledger/Cli/Commands/Import.txt index 7662d76d4..c3ff42286 100644 --- a/hledger/Hledger/Cli/Commands/Import.txt +++ b/hledger/Hledger/Cli/Commands/Import.txt @@ -61,6 +61,8 @@ certain date. Note deduplication (and updating of state files) can also be done by print --new, but this is less often used. +Related: CSV > Working with CSV > Deduplicating, importing. + Import testing With --dry-run, the transactions that will be imported are printed to diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index 433ab457f..0a0b5d121 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -54,7 +54,7 @@ $ hledger print assets:cash | hledger -f- -I reg expenses:food There are some situations where print's output can become unparseable: -- Valuation affects posting amounts but not balance assertion or +- 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.