From e473fc9794bd2f3b6fbd71ee9c506980e74024b1 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Sat, 14 Jun 2025 18:10:07 -1000 Subject: [PATCH] ;doc: update command docs --- hledger/Hledger/Cli/Commands/Accounts.txt | 39 ++++++++----------- hledger/Hledger/Cli/Commands/Add.txt | 24 ++++++++++++ hledger/Hledger/Cli/Commands/Commodities.txt | 14 ++++++- hledger/Hledger/Cli/Commands/Descriptions.txt | 2 +- hledger/Hledger/Cli/Commands/Payees.txt | 23 ++++++----- hledger/Hledger/Cli/Commands/Print.txt | 2 +- hledger/Hledger/Cli/Commands/Tags.txt | 34 +++++++++------- 7 files changed, 87 insertions(+), 51 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Accounts.txt b/hledger/Hledger/Cli/Commands/Accounts.txt index 3f52d3613..96f02066a 100644 --- a/hledger/Hledger/Cli/Commands/Accounts.txt +++ b/hledger/Hledger/Cli/Commands/Accounts.txt @@ -1,34 +1,29 @@ accounts -List account names. +List the account names used or declared in the journal. Flags: - -u --used show only accounts used by transactions - -d --declared show only accounts declared by account directive - --unused show only accounts declared but not used - --undeclared show only accounts used but not declared + -u --used list accounts used + -d --declared list accounts declared + --undeclared list accounts used but not declared + --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 - --find find the first account matched by the first - argument (a case-insensitive infix regexp or - account name) -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. By default it shows all known -accounts, either used in transactions or declared with account -directives. +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. -With query arguments, only matched account names and account names -referenced by matched postings are shown. - -Or it can show just the used accounts (--used/-u), the declared accounts -(--declared/-d), the accounts declared but not used (--unused), the -accounts used but not declared (--undeclared), or the first account -matched by an account name pattern, if any (--find). +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 @@ -42,10 +37,10 @@ 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 adds the account keyword, showing valid account -directives which can be pasted into a journal file. This is useful -together with --undeclared when updating your account declarations to -satisfy hledger check accounts. +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 diff --git a/hledger/Hledger/Cli/Commands/Add.txt b/hledger/Hledger/Cli/Commands/Add.txt index bea908a36..9fb9a68a0 100644 --- a/hledger/Hledger/Cli/Commands/Add.txt +++ b/hledger/Hledger/Cli/Commands/Add.txt @@ -57,3 +57,27 @@ Examples: hledger add today 'best buy' expenses:supplies '$20' 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. + +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. + +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. diff --git a/hledger/Hledger/Cli/Commands/Commodities.txt b/hledger/Hledger/Cli/Commands/Commodities.txt index df27c394a..a312ea3d2 100644 --- a/hledger/Hledger/Cli/Commands/Commodities.txt +++ b/hledger/Hledger/Cli/Commands/Commodities.txt @@ -1,6 +1,16 @@ commodities -List all commodity/currency symbols used or declared in the journal. +List the commodity symbols used or declared in the journal. Flags: -no command-specific flags + --used list commodities used + --declared list commodities declared + --undeclared list commodities used but not declared + --unused list commodities declared but not used + +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. + +You can add cur: query arguments to further limit the commodities. diff --git a/hledger/Hledger/Cli/Commands/Descriptions.txt b/hledger/Hledger/Cli/Commands/Descriptions.txt index 915b54af6..f41a84a27 100644 --- a/hledger/Hledger/Cli/Commands/Descriptions.txt +++ b/hledger/Hledger/Cli/Commands/Descriptions.txt @@ -1,6 +1,6 @@ descriptions -List the unique descriptions that appear in transactions. +List the unique descriptions used in transactions. Flags: no command-specific flags diff --git a/hledger/Hledger/Cli/Commands/Payees.txt b/hledger/Hledger/Cli/Commands/Payees.txt index ffe2893c9..ec0e5249e 100644 --- a/hledger/Hledger/Cli/Commands/Payees.txt +++ b/hledger/Hledger/Cli/Commands/Payees.txt @@ -1,20 +1,23 @@ payees -List the unique payee/payer names that appear in transactions. +List the payee/payer names used or declared in the journal. Flags: - --declared show payees declared with payee directives - --used show payees referenced by transactions + --used list payees used + --declared list payees declared + --undeclared list payees used but not declared + --unused list payees declared but not used -This command lists unique payee/payer names which have been declared -with payee directives (--declared), used in transaction descriptions -(--used), or both (the default). +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. -The payee/payer is the part of the transaction description before a | -character (or if there is no |, the whole description). +The payee/payer name is the part of the transaction description before a +| character (or if there is no |, the whole description). -You can add query arguments to select a subset of transactions. This -implies --used. +You can add query arguments to select a subset of transactions or +payees. Example: diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index e5f9437d5..4d0a8cb04 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -24,7 +24,7 @@ Flags: --base-url=URLPREFIX in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by hledger-web; can also be relative.) - --location add file/line number tags to print output + --location add tags showing file paths and line numbers -O --output-format=FMT select the output format. Supported formats: txt, beancount, csv, tsv, html, fods, json, sql. -o --output-file=FILE write output to FILE. A file extension matching diff --git a/hledger/Hledger/Cli/Commands/Tags.txt b/hledger/Hledger/Cli/Commands/Tags.txt index 8f9e0bf11..b12540c98 100644 --- a/hledger/Hledger/Cli/Commands/Tags.txt +++ b/hledger/Hledger/Cli/Commands/Tags.txt @@ -1,30 +1,34 @@ tags -List the tags used in the journal, or their values. +List the tag names used or declared in the journal, or their values. Flags: + --used list tags used + --declared list tags declared + --undeclared list tags used but not declared + --unused list tags declared but not used --values list tag values instead of tag names - --parsed show tags/values in the order they were parsed, + --parsed show them in the order they were parsed (mostly), including duplicates -This command lists the tag names used in the journal, whether on -transactions, postings, or account declarations. +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. -With a TAGREGEX argument, only tag names matching this regular -expression (case insensitive, infix matched) are shown. +You can add one TAGREGEX argument, to show only tags whose name is +matched by this case-insensitive, infix-matching regular expression. -With QUERY arguments, only transactions and accounts matching this query -are considered. If the query involves transaction fields (date:, desc:, -amt:, ...), the search is restricted to the matched transactions and -their accounts. +After that, you can add query arguments to filter the transactions, +postings, or accounts providing tags. -With the --values flag, the tags' unique non-empty values are listed -instead. With -E/--empty, blank/empty values are also shown. +With --values, the tags' unique non-empty values are listed instead. + +With -E/--empty, blank/empty values are also shown. With --parsed, tags or values are shown in the order they were parsed, with duplicates included. (Except, tags from account declarations are always shown first.) -Tip: remember, accounts also acquire tags from their parents, postings -also acquire tags from their account and transaction, transactions also -acquire tags from their postings. +Remember that accounts also acquire tags from their parents; postings +also acquire tags from their account and transaction; and transactions +also acquire tags from their postings.