diff --git a/hledger/Hledger/Cli/Commands/Add.txt b/hledger/Hledger/Cli/Commands/Add.txt index 71584d4ce..1aabd5a4f 100644 --- a/hledger/Hledger/Cli/Commands/Add.txt +++ b/hledger/Hledger/Cli/Commands/Add.txt @@ -62,24 +62,22 @@ There is a detailed tutorial at https://hledger.org/add.html. add and balance assertions -Since hledger 1.43, whenever you enter a posting amount, add will -re-check all balance assertions in the journal, and if any of them fail, -it will report the problem and ask for the amount again. +Since hledger 1.43, you can add a balance assertion by writing +AMOUNT = BALANCE when asked for an amount. Eg 100 = 500. -You can also add a new balance assertion, following the amount as in -journal format. - -The new transaction's date, and the new posting's posting date if any -(entered in a comment following the amount), will influence assertion -checking. - -You can use -I/--ignore-assertions to disable assertion checking -temporarily. +Also, each time you enter a new amount, hledger re-checks all balance +assertions in the journal and rejects the new amount if it would make +any of them fail. You can run add with -I/--ignore-assertions to disable +balance assertion checking. add and balance assignments -Balance assignments are not recalculated during a hledger add session. -When add runs, it sees the journal with all balance assignments already -processed and converted to assertions. So if you add a new posting which -is dated earlier than a balance assignment, it will break the assertion -and be rejected. You can make it work by using hledger add -I. +Since hledger 1.51, you can add a balance assignment by writing += BALANCE (or ==, =* etc) when asked for an amount. The missing amount +will be calculated automatically. + +add normally won't let you add a new posting which is dated earlier than +an existing balance assignment. (Because when add runs, existing balance +assignments have already been calculated and converted to amounts and +balance assertions.) You can allow it by disabling balance assertion +checking with -I. diff --git a/hledger/Hledger/Cli/Commands/Aregister.txt b/hledger/Hledger/Cli/Commands/Aregister.txt index 12dce4c26..9ddab241f 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.txt +++ b/hledger/Hledger/Cli/Commands/Aregister.txt @@ -33,9 +33,10 @@ this behaviour using the --cumulative option. This is a more "real world", bank-like view than the register command (which shows individual postings, possibly from multiple accounts, not -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. +necessarily in historical mode). As a quick rule of thumb: + +- aregister is best when reconciling real-world asset/liability accounts +- register is best when reviewing individual revenues/expenses. Note this command's non-standard, and required, first argument; it specifies the account whose register will be shown. You can write the diff --git a/hledger/Hledger/Cli/Commands/Check.txt b/hledger/Hledger/Cli/Commands/Check.txt index d2df8ad26..0de53e333 100644 --- a/hledger/Hledger/Cli/Commands/Check.txt +++ b/hledger/Hledger/Cli/Commands/Check.txt @@ -18,9 +18,9 @@ hledger check ordereddates payees # run basic checks and two others If you are an Emacs user, you can also configure flycheck-hledger to run these checks, providing instant feedback as you edit the journal. -Here are the checks currently available. Generally, they are performed -in the order they are shown here (and only the first failure is -reported). +Here are the checks currently available. They are generally checked in +the order they are shown here, and only the first failure will be +reported. Basic checks @@ -33,30 +33,30 @@ commands: - autobalanced - all transactions are balanced, after automatically inferring missing amounts and conversion rates and then converting - amounts to cost. This ensures that each transaction's entry is well - formed. + amounts to cost. This ensures that each transaction's journal entry is + well formed. - assertions - all balance assertions in the journal are passing. - Balance assertions are a strong defense against errors; they help - catch many problems. If this check gets in your way, you can disable - it with -I/--ignore-assertions. Or you can add that to your config - file to disable it by default (and then use -s/--strict or - hledger check assertions to enable it). + Balance assertions are a strong defense against errors, catching many + problems. This check is on by default, but if it gets in your way, you + can disable it temporarily with -I/--ignore-assertions, or as a + default by adding that flag to your config file. (Then use -s/--strict + or hledger check assertions when you want to enable it). Strict checks -These additional checks are performed by all commands when the --s/--strict flag is used (strict mode). They provide extra -error-catching power to keep your data clean and correct. Strict mode -also always enables the assertions check. +When the -s/--strict flag is used (AKA strict mode), all commands will +perform the following additional checks (and assertions, above). These +provide extra error-catching power to help you keep your data clean and +correct: -- balanced - like autobalanced, but all conversions between commodities - must use explicit cost notation or equity postings. This prevents - wrong conversions caused by typos. +- balanced - like autobalanced, but implicit conversions between + commodities are not allowed; all conversion transactions must use cost + notation or equity postings. This prevents wrong conversions caused by + typos. - commodities - all commodity symbols used must be declared. This guards - against mistyping or omitting commodity symbols. Declaring commodities - also sets their precision for display and transaction balancing. + against mistyping or omitting commodity symbols. - accounts - all account names used must be declared. This prevents the use of mis-spelled or outdated account names. @@ -84,10 +84,9 @@ command: encourage adding balance assertions for your active asset/liability accounts, which in turn should encourage you to reconcile regularly with those real world balances - another strong defense against - errors. hledger close --assert can help generate assertion entries. - Over time the older assertions become somewhat redundant, and you can - remove them if you like (they don't affect performance much, but they - add some noise to the journal). + errors. (hledger close --assert >>$LEDGER_FILE is a convenient way to + add new balance assertions. Later these become quite redundant, and + you might choose to remove them to reduce clutter.) - uniqueleafnames - no two accounts may have the same last account name part (eg the checking in assets:bank:checking). This ensures each @@ -99,8 +98,8 @@ Custom checks You can build your own custom checks with add-on command scripts. See also Cookbook > Scripting. Here are some examples from hledger/bin/: -- hledger-check-tagfiles - all tag values containing / (a forward slash) - exist as file paths +- hledger-check-tagfiles - all tag values containing / exist as file + paths - hledger-check-fancyassertions - more complex balance assertions are passing diff --git a/hledger/Hledger/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index 1089939e8..d42b37776 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -36,9 +36,17 @@ Flags: all - also round cost amounts to precision (can unbalance transactions) -close has six modes, selected by choosing one of the mode flags (--close -is the default). They all do much the same operation, but with different -defaults, useful in different situations. +close has six modes, selected by choosing one of the mode flags: +--clopen, --close (default), --open, --assert, --assign, or --retain. +They are all doing the same kind of operation, but with different +defaults for different situations. + +The journal entries generated by close will have a clopen: tag, which is +helpful when you want to exclude them from reports. If the main journal +file name contains a number, the tag's value will be that base file name +with the number incremented. Eg if the journal file is 2025.journal, the +tag will be clopen:2026. Or you can set the tag value by providing an +argument to the mode flag. Eg --close=foo or --clopen=2025-main. close --clopen @@ -77,11 +85,6 @@ RX accounts (Revenue, Expense). Assertions will be added indicating and checking the new balances of the closed/opened accounts. -The generated transactions will have a clopen: tag. If the main -journal's base file name contains a number (eg a year number), the tag's -value will be that base file name with the number incremented. Or you -can choose the tag value yourself, by using --clopen=TAGVAL. - close --close This prints just the closing balances transaction of --clopen. It is the @@ -137,11 +140,12 @@ close customisation In all modes, the following things can be overridden: - the accounts to be closed/opened, with account query arguments +- the closing/opening dates, with -e OPENDATE - the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT - the transaction descriptions, with --close-desc=DESC and --open-desc=DESC -- the transaction's tag value, with a --MODE=NEW option argument -- the closing/opening dates, with -e OPENDATE +- the transactions' clopen tag value, with a TAGVAL argument for the + mode flag (see above). By default, the closing date is yesterday, or the journal's end date, whichever is later; and the opening date is always one day after the diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index 98ddea735..6b6d284be 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -121,6 +121,9 @@ unparseable: - Auto postings can generate too many amountless postings. - --infer-costs or --infer-equity can generate too-complex redundant costs. +- Because print always shows transactions in date order, balance + assertions involving non-date-ordered transactions (and same-day + postings) could be disrupted. print, other features