slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

;doc: update command docs

Browse Source
This commit is contained in:
Simon Michael 2025-10-13 11:28:36 -10:00
parent 9af95105b4
commit d066c62dd0
8 changed files with 87 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
hledger/Hledger/Cli/Commands/Accounts.txt
View File

@ -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:

24
hledger/Hledger/Cli/Commands/Aregister.txt
View File

@ -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":

5
hledger/Hledger/Cli/Commands/Commodities.txt
View File

@ -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.

5
hledger/Hledger/Cli/Commands/Payees.txt
View File

@ -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).

4
hledger/Hledger/Cli/Commands/Print.md
View File

@ -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,

83
hledger/Hledger/Cli/Commands/Print.txt
View File

@ -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

2
hledger/Hledger/Cli/Commands/Register.txt
View File

@ -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

16
hledger/Hledger/Cli/Commands/Tags.txt
View File

@ -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.