;doc: update manuals
This commit is contained in:
Simon Michael
parent
2d9b6b91b5
commit
423f3bd155
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{July 2022}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{August 2022}})m4_dnl
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{July 2022}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{August 2022}})m4_dnl
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER-UI" "1" "July 2022" "hledger-ui-1.26.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER-UI" "1" "August 2022" "hledger-ui-1.26.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
|
||||
@ -549,4 +549,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-ui-1.26.99 July 2022 HLEDGER-UI(1)
|
||||
hledger-ui-1.26.99 August 2022 HLEDGER-UI(1)
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{July 2022}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{August 2022}})m4_dnl
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
|
||||
.TH "HLEDGER-WEB" "1" "July 2022" "hledger-web-1.26.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER-WEB" "1" "August 2022" "hledger-web-1.26.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
|
||||
@ -586,4 +586,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-web-1.26.99 July 2022 HLEDGER-WEB(1)
|
||||
hledger-web-1.26.99 August 2022 HLEDGER-WEB(1)
|
||||
|
||||
@ -1,2 +1,2 @@
|
||||
m4_dnl Date to show in man pages. Updated by "Shake manuals"
|
||||
m4_define({{_monthyear_}}, {{July 2022}})m4_dnl
|
||||
m4_define({{_monthyear_}}, {{August 2022}})m4_dnl
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
.\"t
|
||||
|
||||
.TH "HLEDGER" "1" "July 2022" "hledger-1.26.99 " "hledger User Manuals"
|
||||
.TH "HLEDGER" "1" "August 2022" "hledger-1.26.99 " "hledger User Manuals"
|
||||
|
||||
|
||||
|
||||
@ -2984,6 +2984,7 @@ This command lists account names, either declared with account
|
||||
directives (--declared), posted to (--used), or both (the default).
|
||||
With query arguments, only matched account names and account names
|
||||
referenced by matched postings are shown.
|
||||
.PP
|
||||
It shows a flat list by default.
|
||||
With \f[C]--tree\f[R], it uses indentation to show the account
|
||||
hierarchy.
|
||||
@ -2996,6 +2997,15 @@ With \f[C]--types\f[R], it also shows each account\[aq]s type, if
|
||||
it\[aq]s known.
|
||||
(See Declaring accounts > Account types.)
|
||||
.PP
|
||||
With \f[C]--positions\f[R], it also shows the file and line number of
|
||||
each account\[aq]s declaration, if any, and the account\[aq]s overall
|
||||
declaration order; these may be useful when troubleshooting account
|
||||
display order.
|
||||
.PP
|
||||
With \f[C]--directives\f[R], it adds the \f[C]account\f[R] keyword,
|
||||
showing valid account directives which can be pasted into a journal
|
||||
file.
|
||||
.PP
|
||||
Examples:
|
||||
.IP
|
||||
.nf
|
||||
@ -4644,6 +4654,9 @@ hledger check ordereddates payees # basic + two other checks
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
If you are an Emacs user, you can also configure flycheck-hledger to run
|
||||
these checks, providing instant feedback as you edit the journal.
|
||||
.PP
|
||||
Here are the checks currently available:
|
||||
.SS Basic checks
|
||||
.PP
|
||||
@ -4688,6 +4701,9 @@ file
|
||||
.IP \[bu] 2
|
||||
\f[B]payees\f[R] - all payees used by transactions have been declared
|
||||
.IP \[bu] 2
|
||||
\f[B]recentassertions\f[R] - all accounts with balance assertions have a
|
||||
balance assertion no more than 7 days before their latest posting
|
||||
.IP \[bu] 2
|
||||
\f[B]uniqueleafnames\f[R] - all account leaf names are unique
|
||||
.SS Custom checks
|
||||
.PP
|
||||
@ -4702,6 +4718,20 @@ assertions are passing
|
||||
.PP
|
||||
You could make similar scripts to perform your own custom checks.
|
||||
See: Cookbook -> Scripting.
|
||||
.SS More about specific checks
|
||||
.PP
|
||||
\f[C]hledger check recentassertions\f[R] 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.
|
||||
.SS close
|
||||
.PP
|
||||
close, equity
|
||||
@ -5134,12 +5164,10 @@ help
|
||||
Show the hledger user manual in one of several formats, optionally
|
||||
positioned at a given TOPIC (if possible).
|
||||
.PP
|
||||
TOPIC is any heading in the manual, or the start of any heading (but not
|
||||
the middle).
|
||||
It is case insensitive.
|
||||
.PP
|
||||
Some examples: \f[C]commands\f[R], \f[C]print\f[R], \f[C]forecast\f[R],
|
||||
\f[C]\[dq]auto postings\[dq]\f[R], \f[C]\[dq]commodity column\[dq]\f[R].
|
||||
TOPIC is any heading in the manual, or a heading prefix, case
|
||||
insensitive.
|
||||
Eg: \f[C]commands\f[R], \f[C]print\f[R], \f[C]forecast\f[R],
|
||||
\f[C]\[dq]auto postings\[dq]\f[R], \f[C]journal\f[R], \f[C]amount\f[R].
|
||||
.PP
|
||||
This command shows the user manual built in to this hledger version.
|
||||
It can be useful if the correct version of the hledger manual, or the
|
||||
@ -5151,6 +5179,16 @@ By default it uses the best viewer it can find in $PATH, in this order:
|
||||
When run non-interactively, it always uses stdout.
|
||||
Or you can select a particular viewer with the \f[C]-i\f[R] (info),
|
||||
\f[C]-m\f[R] (man), or \f[C]-p\f[R] (pager) flags.
|
||||
.PP
|
||||
Examples
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger help --help # show how the help command works
|
||||
$ hledger help # show the hledger manual with info, man or $PAGER
|
||||
$ hledger help journal # show the journal topic in the hledger manual
|
||||
\f[R]
|
||||
.fi
|
||||
.SS import
|
||||
.PP
|
||||
import
|
||||
@ -6595,63 +6633,53 @@ You can also comment larger regions of a file using \f[C]comment\f[R]
|
||||
and \f[C]end comment\f[R] directives.
|
||||
.SS Tags
|
||||
.PP
|
||||
Tags are a way to add extra labels or labelled data to postings and
|
||||
transactions, which you can then search or pivot on.
|
||||
Tags are a way to add extra labels or labelled data to transactions,
|
||||
postings, or accounts, which you can then search or pivot on.
|
||||
.PP
|
||||
A simple tag is a word (which may contain hyphens) followed by a full
|
||||
colon, written inside a transaction or posting comment line:
|
||||
They are written as a (optionally hyphenated) word immediately followed
|
||||
by a full colon within a transaction or posting or account
|
||||
directive\[aq]s comment:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
2017/1/16 bought groceries ; sometag:
|
||||
account assets:checking ; accounttag:
|
||||
|
||||
2017/1/16 bought groceries ; transaction-tag:
|
||||
; another-transaction-tag:
|
||||
assets:checking $-1
|
||||
expenses:food $1 ; posting-tag:
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Tags can have a value, which is the text after the colon, up to the next
|
||||
comma or end of line, with leading/trailing whitespace removed:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
expenses:food $10 ; a-posting-tag: the tag value
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Note this means hledger\[aq]s tag values can not contain commas or
|
||||
newlines.
|
||||
Ending at commas means you can write multiple short tags on one line,
|
||||
comma separated:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
assets:checking ; a comment containing tag1:, tag2: some value ...
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Here,
|
||||
Tags are inherited, as follows:
|
||||
.IP \[bu] 2
|
||||
\[dq]\f[C]a comment containing\f[R]\[dq] is just comment text, not a tag
|
||||
Tags on a transaction affect the transaction and all of its postings
|
||||
.IP \[bu] 2
|
||||
\[dq]\f[C]tag1\f[R]\[dq] is a tag with no value
|
||||
.IP \[bu] 2
|
||||
\[dq]\f[C]tag2\f[R]\[dq] is another tag, whose value is
|
||||
\[dq]\f[C]some value ...\f[R]\[dq]
|
||||
Tags on an account affect all postings to that account.
|
||||
.PP
|
||||
Tags in a transaction comment affect the transaction and all of its
|
||||
postings, while tags in a posting comment affect only that posting.
|
||||
For example, the following transaction has three tags (\f[C]A\f[R],
|
||||
\f[C]TAG2\f[R], \f[C]third-tag\f[R]) and the posting has four (those
|
||||
plus \f[C]posting-tag\f[R]):
|
||||
So in the example above, - the \f[C]assets:checking\f[R] account has one
|
||||
tag (\f[C]accounttag\f[R]) - the transaction has two tags
|
||||
(\f[C]transaction-tag\f[R], \f[C]another-transaction-tag\f[R]) - the
|
||||
\f[C]assets:checking\f[R] posting has three tags
|
||||
(\f[C]transaction-tag\f[R], \f[C]another-transaction-tag\f[R],
|
||||
\f[C]accounttag\f[R]) - the \f[C]expenses:food\f[R] posting has three
|
||||
tags (\f[C]transaction-tag\f[R], \f[C]another-transaction-tag\f[R],
|
||||
\f[C]posting-tag\f[R]).
|
||||
.PP
|
||||
Tags can have a value, which is the text after the colon, until the next
|
||||
comma or end of line, with surrounding whitespace stripped.
|
||||
So here \f[C]a-posting-tag\f[R]\[aq]s value is \[dq]the tag value\[dq],
|
||||
\f[C]tag2\f[R]\[aq]s value is \[dq]foo\[dq], and \f[C]tag3\f[R]\[aq]s
|
||||
value is \[dq]\[dq] (the empty string):
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
1/1 a transaction ; A:, TAG2:
|
||||
; third-tag: a third transaction tag, <- with a value
|
||||
(a) $1 ; posting-tag:
|
||||
expenses:food $10
|
||||
; some text, a-posting-tag:the tag value, tag2: foo , tag3: , other text
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag
|
||||
values are simple strings.
|
||||
A hledger tag value may not contain a comma.
|
||||
.SS Postings
|
||||
.PP
|
||||
A posting is an addition of some amount to, or removal of some amount
|
||||
@ -7914,38 +7942,68 @@ Though not required, these declarations can provide several benefits:
|
||||
They can document your intended chart of accounts, providing a
|
||||
reference.
|
||||
.IP \[bu] 2
|
||||
In strict mode, they restrict which accounts may be posted to by
|
||||
transactions, which helps detect typos.
|
||||
.IP \[bu] 2
|
||||
They control account display order in reports, allowing non-alphabetic
|
||||
sorting (eg Revenues to appear above Expenses).
|
||||
.IP \[bu] 2
|
||||
They can help hledger know your accounts\[aq] types (asset, liability,
|
||||
equity, revenue, expense), useful for reports like balancesheet and
|
||||
incomestatement.
|
||||
.IP \[bu] 2
|
||||
They can store other account information, as comments or as tags which
|
||||
can be used to filter reports.
|
||||
.IP \[bu] 2
|
||||
They help with account name completion (in hledger add, hledger-web,
|
||||
hledger-iadd, ledger-mode, etc.)
|
||||
.IP \[bu] 2
|
||||
In strict mode, they restrict which accounts may be posted to by
|
||||
transactions, which helps detect typos.
|
||||
They can store additional account information as comments, or as tags
|
||||
which can be used to filter or pivot reports.
|
||||
.IP \[bu] 2
|
||||
They can help hledger know your accounts\[aq] types (asset, liability,
|
||||
equity, revenue, expense), affecting reports like balancesheet and
|
||||
incomestatement.
|
||||
.PP
|
||||
The simplest form is just the word \f[C]account\f[R] followed by a
|
||||
hledger-style account name, eg this account directive declares the
|
||||
\f[C]assets:bank:checking\f[R] account:
|
||||
They are written as the word \f[C]account\f[R] followed by a
|
||||
hledger-style account name, eg:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
account assets:bank:checking
|
||||
\f[R]
|
||||
.fi
|
||||
.SS Account comments
|
||||
.PP
|
||||
Comments, beginning with a semicolon:
|
||||
.IP \[bu] 2
|
||||
can be written on the same line, but only after \f[B]two or more
|
||||
spaces\f[R] (because \f[C];\f[R] is allowed in account names)
|
||||
.IP \[bu] 2
|
||||
and/or on the next lines, indented
|
||||
.IP \[bu] 2
|
||||
and may contain tags, such as the \f[C]type:\f[R] tag.
|
||||
.PP
|
||||
For example:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon
|
||||
; next-line comment
|
||||
; some tags - type:A, acctnum:12345
|
||||
\f[R]
|
||||
.fi
|
||||
.SS Account subdirectives
|
||||
.PP
|
||||
Ledger-style indented subdirectives are also accepted, but currently
|
||||
ignored:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
account assets:bank:checking
|
||||
format subdirective is ignored
|
||||
\f[R]
|
||||
.fi
|
||||
.SS Account error checking
|
||||
.PP
|
||||
By default, accounts come into existence when a transaction references
|
||||
them by name.
|
||||
By default, accounts need not be declared; they come into existence when
|
||||
a posting references them.
|
||||
This is convenient, but it means hledger can\[aq]t warn you when you
|
||||
mis-spell an account name in the journal.
|
||||
Usually you\[aq]ll find the error later, as an extra account in balance
|
||||
Usually you\[aq]ll find that error later, as an extra account in balance
|
||||
reports, or an incorrect balance when reconciling.
|
||||
.PP
|
||||
In strict mode, enabled with the \f[C]-s\f[R]/\f[C]--strict\f[R] flag,
|
||||
@ -7963,54 +8021,65 @@ includes, but not parent or sibling files.
|
||||
The position of account directives within the file does not matter,
|
||||
though it\[aq]s usual to put them at the top.
|
||||
.IP \[bu] 2
|
||||
Accounts can only be declared in \f[C]journal\f[R] files (but will
|
||||
affect included files in other formats).
|
||||
Accounts can only be declared in \f[C]journal\f[R] files, but will
|
||||
affect included files of all types.
|
||||
.IP \[bu] 2
|
||||
It\[aq]s currently not possible to declare \[dq]all possible
|
||||
subaccounts\[dq] with a wildcard; every account posted to must be
|
||||
declared.
|
||||
.SS Account comments
|
||||
.SS Account display order
|
||||
.PP
|
||||
Comments, beginning with a semicolon, can be added:
|
||||
The order in which account directives are written influences the order
|
||||
in which accounts appear in reports, hledger-ui, hledger-web etc.
|
||||
By default accounts appear in alphabetical order, but if you add these
|
||||
account directives to the journal file:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
account assets
|
||||
account liabilities
|
||||
account equity
|
||||
account revenues
|
||||
account expenses
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
those accounts will be displayed in declaration order:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger accounts -1
|
||||
assets
|
||||
liabilities
|
||||
equity
|
||||
revenues
|
||||
expenses
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Any undeclared accounts are displayed last, in alphabetical order.
|
||||
.PP
|
||||
Sorting is done at each level of the account tree, within each group of
|
||||
sibling accounts under the same parent.
|
||||
And currently, this directive:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
account other:zoo
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
would influence the position of \f[C]zoo\f[R] among
|
||||
\f[C]other\f[R]\[aq]s subaccounts, but not the position of
|
||||
\f[C]other\f[R] among the top-level accounts.
|
||||
This means:
|
||||
.IP \[bu] 2
|
||||
on the same line, \f[B]after two or more spaces\f[R] (because ; is
|
||||
allowed in account names)
|
||||
you will sometimes declare parent accounts (eg \f[C]account other\f[R]
|
||||
above) that you don\[aq]t intend to post to, just to customize their
|
||||
display order
|
||||
.IP \[bu] 2
|
||||
on the next lines, indented
|
||||
.PP
|
||||
An example of both:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
account assets:bank:checking ; same-line comment, note 2+ spaces required before ;
|
||||
; next-line comment
|
||||
; some tags, type:A, acctnum:12345
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Compatibility note: same-line comments are not supported by Ledger or
|
||||
hledger <1.13.
|
||||
.SS Account subdirectives
|
||||
.PP
|
||||
We also allow (and ignore) Ledger-style indented subdirectives, just for
|
||||
compatibility.:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
account assets:bank:checking
|
||||
format blah blah ; <- subdirective, ignored
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Here is the full syntax of account directives:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
account ACCTNAME [;type:ACCTTYPE] [COMMENT]
|
||||
[;COMMENTS]
|
||||
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]
|
||||
\f[R]
|
||||
.fi
|
||||
sibling accounts stay together (you couldn\[aq]t display \f[C]x:y\f[R]
|
||||
in between \f[C]a:b\f[R] and \f[C]a:c\f[R]).
|
||||
.SS Account types
|
||||
.PP
|
||||
hledger knows that accounts come in several types: assets, liabilities,
|
||||
@ -8124,61 +8193,6 @@ $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]
|
||||
\f[R]
|
||||
.fi
|
||||
.RE
|
||||
.SS Account display order
|
||||
.PP
|
||||
Account directives also set the order in which accounts are displayed,
|
||||
eg in reports, the hledger-ui accounts screen, and the hledger-web
|
||||
sidebar.
|
||||
By default accounts are listed in alphabetical order.
|
||||
But if you have these account directives in the journal:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
account assets
|
||||
account liabilities
|
||||
account equity
|
||||
account revenues
|
||||
account expenses
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
you\[aq]ll see those accounts displayed in declaration order, not
|
||||
alphabetically:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger accounts -1
|
||||
assets
|
||||
liabilities
|
||||
equity
|
||||
revenues
|
||||
expenses
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Undeclared accounts, if any, are displayed last, in alphabetical order.
|
||||
.PP
|
||||
Note that sorting is done at each level of the account tree (within each
|
||||
group of sibling accounts under the same parent).
|
||||
And currently, this directive:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
account other:zoo
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
would influence the position of \f[C]zoo\f[R] among
|
||||
\f[C]other\f[R]\[aq]s subaccounts, but not the position of
|
||||
\f[C]other\f[R] among the top-level accounts.
|
||||
This means:
|
||||
.IP \[bu] 2
|
||||
you will sometimes declare parent accounts (eg \f[C]account other\f[R]
|
||||
above) that you don\[aq]t intend to post to, just to customize their
|
||||
display order
|
||||
.IP \[bu] 2
|
||||
sibling accounts stay together (you couldn\[aq]t display \f[C]x:y\f[R]
|
||||
in between \f[C]a:b\f[R] and \f[C]a:c\f[R]).
|
||||
.SS Rewriting accounts
|
||||
.PP
|
||||
You can define account alias rules which rewrite your account names, or
|
||||
@ -8910,7 +8924,7 @@ Note, for best error messages when reading CSV files, use a
|
||||
\f[C].csv\f[R], \f[C].tsv\f[R] or \f[C].ssv\f[R] file extension or file
|
||||
prefix - see File Extension below.
|
||||
.PP
|
||||
There\[aq]s an introductory Convert CSV files tutorial on hledger.org.
|
||||
There\[aq]s an introductory Importing CSV data tutorial on hledger.org.
|
||||
.SS Examples
|
||||
.PP
|
||||
Here are some sample hledger CSV rules files.
|
||||
@ -10557,25 +10571,34 @@ A sample.timedot file.
|
||||
.SH COMMON TASKS
|
||||
.PP
|
||||
Here are some quick examples of how to do some basic tasks with hledger.
|
||||
For more details, see the reference section below, the
|
||||
hledger_journal(5) manual, or the more extensive docs at
|
||||
https://hledger.org.
|
||||
.SS Getting help
|
||||
.PP
|
||||
Here\[aq]s how to list commands and view options and command docs:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger # show available commands
|
||||
$ hledger --help # show common options
|
||||
$ hledger CMD --help # show common and command options, and command help
|
||||
$ hledger help # show available manuals/topics
|
||||
$ hledger help hledger # show hledger manual, as info/man/text (auto-chosen)
|
||||
$ hledger help journal -m # show the journal topic, as a man page scrolled to that section
|
||||
$ hledger help --help # show more detailed help for the help command
|
||||
$ hledger CMD --help # show common options and CMD\[aq]s options and documentation
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
Find more docs, chat, mail list, reddit, issue tracker:
|
||||
https://hledger.org/support.html
|
||||
You can also view your hledger version\[aq]s manual in several formats
|
||||
by using the help command.
|
||||
Eg:
|
||||
.IP
|
||||
.nf
|
||||
\f[C]
|
||||
$ hledger help # show the hledger manual with info, man or $PAGER (best available)
|
||||
$ hledger help journal # show the journal topic in the hledger manual
|
||||
$ hledger help --help # show how the help command works
|
||||
\f[R]
|
||||
.fi
|
||||
.PP
|
||||
To view manuals and introductory docs on the web, visit
|
||||
https://hledger.org.
|
||||
Chat and mail list support and discussion archives can be found at
|
||||
https://hledger.org/support.
|
||||
.SS Constructing command lines
|
||||
.PP
|
||||
hledger has an extensive and powerful command line interface.
|
||||
|
||||
1149
hledger/hledger.info
1149
hledger/hledger.info
File diff suppressed because it is too large
Load Diff
@ -1991,15 +1991,23 @@ COMMANDS
|
||||
This command lists account names, either declared with account direc-
|
||||
tives (--declared), posted to (--used), or both (the default). With
|
||||
query arguments, only matched account names and account names refer-
|
||||
enced by matched postings are shown. 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 com-
|
||||
ponents. Account names can be depth-clipped with depth:N or --depth N
|
||||
or -N.
|
||||
enced by matched postings are shown.
|
||||
|
||||
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 adds the account keyword, showing valid account
|
||||
directives which can be pasted into a journal file.
|
||||
|
||||
Examples:
|
||||
|
||||
$ hledger accounts
|
||||
@ -3264,6 +3272,9 @@ COMMANDS
|
||||
hledger check -s # basic + strict checks
|
||||
hledger check ordereddates payees # basic + two other checks
|
||||
|
||||
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:
|
||||
|
||||
Basic checks
|
||||
@ -3300,6 +3311,9 @@ COMMANDS
|
||||
|
||||
o payees - all payees used by transactions have been declared
|
||||
|
||||
o recentassertions - all accounts with balance assertions have a bal-
|
||||
ance assertion no more than 7 days before their latest posting
|
||||
|
||||
o uniqueleafnames - all account leaf names are unique
|
||||
|
||||
Custom checks
|
||||
@ -3315,6 +3329,19 @@ COMMANDS
|
||||
You could make similar scripts to perform your own custom checks. See:
|
||||
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 lat-
|
||||
est posting. This aims to prevent the situation where you are regu-
|
||||
larly 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 man-
|
||||
ual-review-and-mark-cleared phase as a reminder to check the latest
|
||||
assertions against real-world balances.
|
||||
|
||||
close
|
||||
close, equity
|
||||
Prints a sample "closing" transaction bringing specified account bal-
|
||||
@ -3609,11 +3636,8 @@ COMMANDS
|
||||
Show the hledger user manual in one of several formats, optionally
|
||||
positioned at a given TOPIC (if possible).
|
||||
|
||||
TOPIC is any heading in the manual, or the start of any heading (but
|
||||
not the middle). It is case insensitive.
|
||||
|
||||
Some examples: commands, print, forecast, "auto postings", "commodity
|
||||
column".
|
||||
TOPIC is any heading in the manual, or a heading prefix, case insensi-
|
||||
tive. Eg: commands, print, forecast, "auto postings", journal, amount.
|
||||
|
||||
This command shows the user manual built in to this hledger version.
|
||||
It can be useful if the correct version of the hledger manual, or the
|
||||
@ -3624,6 +3648,12 @@ COMMANDS
|
||||
run non-interactively, it always uses stdout. Or you can select a par-
|
||||
ticular viewer with the -i (info), -m (man), or -p (pager) flags.
|
||||
|
||||
Examples
|
||||
|
||||
$ hledger help --help # show how the help command works
|
||||
$ hledger help # show the hledger manual with info, man or $PAGER
|
||||
$ hledger help journal # show the journal topic in the hledger manual
|
||||
|
||||
import
|
||||
import
|
||||
Read new transactions added to each FILE since last run, and add them
|
||||
@ -4626,8 +4656,6 @@ JOURNAL FORMAT
|
||||
indicating one of three statuses:
|
||||
|
||||
|
||||
|
||||
|
||||
mark status
|
||||
------------------
|
||||
unmarked
|
||||
@ -4723,44 +4751,42 @@ JOURNAL FORMAT
|
||||
comment directives.
|
||||
|
||||
Tags
|
||||
Tags are a way to add extra labels or labelled data to postings and
|
||||
transactions, which you can then search or pivot on.
|
||||
Tags are a way to add extra labels or labelled data to transactions,
|
||||
postings, or accounts, which you can then search or pivot on.
|
||||
|
||||
A simple tag is a word (which may contain hyphens) followed by a full
|
||||
colon, written inside a transaction or posting comment line:
|
||||
They are written as a (optionally hyphenated) word immediately followed
|
||||
by a full colon within a transaction or posting or account directive's
|
||||
comment:
|
||||
|
||||
2017/1/16 bought groceries ; sometag:
|
||||
account assets:checking ; accounttag:
|
||||
|
||||
Tags can have a value, which is the text after the colon, up to the
|
||||
next comma or end of line, with leading/trailing whitespace removed:
|
||||
2017/1/16 bought groceries ; transaction-tag:
|
||||
; another-transaction-tag:
|
||||
assets:checking $-1
|
||||
expenses:food $1 ; posting-tag:
|
||||
|
||||
expenses:food $10 ; a-posting-tag: the tag value
|
||||
Tags are inherited, as follows:
|
||||
|
||||
Note this means hledger's tag values can not contain commas or new-
|
||||
lines. Ending at commas means you can write multiple short tags on one
|
||||
line, comma separated:
|
||||
o Tags on a transaction affect the transaction and all of its postings
|
||||
|
||||
assets:checking ; a comment containing tag1:, tag2: some value ...
|
||||
o Tags on an account affect all postings to that account.
|
||||
|
||||
Here,
|
||||
So in the example above, - the assets:checking account has one tag
|
||||
(accounttag) - the transaction has two tags (transaction-tag, another-
|
||||
transaction-tag) - the assets:checking posting has three tags (transac-
|
||||
tion-tag, another-transaction-tag, accounttag) - the expenses:food
|
||||
posting has three tags (transaction-tag, another-transaction-tag, post-
|
||||
ing-tag).
|
||||
|
||||
o "a comment containing" is just comment text, not a tag
|
||||
Tags can have a value, which is the text after the colon, until the
|
||||
next comma or end of line, with surrounding whitespace stripped. So
|
||||
here a-posting-tag's value is "the tag value", tag2's value is "foo",
|
||||
and tag3's value is "" (the empty string):
|
||||
|
||||
o "tag1" is a tag with no value
|
||||
expenses:food $10
|
||||
; some text, a-posting-tag:the tag value, tag2: foo , tag3: , other text
|
||||
|
||||
o "tag2" is another tag, whose value is "some value ..."
|
||||
|
||||
Tags in a transaction comment affect the transaction and all of its
|
||||
postings, while tags in a posting comment affect only that posting.
|
||||
For example, the following transaction has three tags (A, TAG2, third-
|
||||
tag) and the posting has four (those plus posting-tag):
|
||||
|
||||
1/1 a transaction ; A:, TAG2:
|
||||
; third-tag: a third transaction tag, <- with a value
|
||||
(a) $1 ; posting-tag:
|
||||
|
||||
Tags are like Ledger's metadata feature, except hledger's tag values
|
||||
are simple strings.
|
||||
A hledger tag value may not contain a comma.
|
||||
|
||||
Postings
|
||||
A posting is an addition of some amount to, or removal of some amount
|
||||
@ -5376,6 +5402,9 @@ JOURNAL FORMAT
|
||||
any text, ignored.
|
||||
alias Rewrites account names, in following entries until end of Y
|
||||
current file or end aliases.
|
||||
|
||||
|
||||
|
||||
apply Prepends a common parent account to all account names, in Y
|
||||
account following entries until end of current file or end apply
|
||||
account.
|
||||
@ -5636,34 +5665,56 @@ JOURNAL FORMAT
|
||||
o They can document your intended chart of accounts, providing a refer-
|
||||
ence.
|
||||
|
||||
o In strict mode, they restrict which accounts may be posted to by
|
||||
transactions, which helps detect typos.
|
||||
|
||||
o They control account display order in reports, allowing non-alpha-
|
||||
betic sorting (eg Revenues to appear above Expenses).
|
||||
|
||||
o They can help hledger know your accounts' types (asset, liability,
|
||||
equity, revenue, expense), useful for reports like balancesheet and
|
||||
incomestatement.
|
||||
|
||||
o They can store other account information, as comments or as tags
|
||||
which can be used to filter reports.
|
||||
|
||||
o They help with account name completion (in hledger add, hledger-web,
|
||||
hledger-iadd, ledger-mode, etc.)
|
||||
|
||||
o In strict mode, they restrict which accounts may be posted to by
|
||||
transactions, which helps detect typos.
|
||||
o They can store additional account information as comments, or as tags
|
||||
which can be used to filter or pivot reports.
|
||||
|
||||
The simplest form is just the word account followed by a hledger-style
|
||||
account name, eg this account directive declares the assets:bank:check-
|
||||
ing account:
|
||||
o They can help hledger know your accounts' types (asset, liability,
|
||||
equity, revenue, expense), affecting reports like balancesheet and
|
||||
incomestatement.
|
||||
|
||||
They are written as the word account followed by a hledger-style
|
||||
account name, eg:
|
||||
|
||||
account assets:bank:checking
|
||||
|
||||
Account comments
|
||||
Comments, beginning with a semicolon:
|
||||
|
||||
o can be written on the same line, but only after two or more spaces
|
||||
(because ; is allowed in account names)
|
||||
|
||||
o and/or on the next lines, indented
|
||||
|
||||
o and may contain tags, such as the type: tag.
|
||||
|
||||
For example:
|
||||
|
||||
account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon
|
||||
; next-line comment
|
||||
; some tags - type:A, acctnum:12345
|
||||
|
||||
Account subdirectives
|
||||
Ledger-style indented subdirectives are also accepted, but currently
|
||||
ignored:
|
||||
|
||||
account assets:bank:checking
|
||||
format subdirective is ignored
|
||||
|
||||
Account error checking
|
||||
By default, accounts come into existence when a transaction references
|
||||
them by name. This is convenient, but it means hledger can't warn you
|
||||
when you mis-spell an account name in the journal. Usually you'll find
|
||||
the error later, as an extra account in balance reports, or an incor-
|
||||
rect balance when reconciling.
|
||||
By default, accounts need not be declared; they come into existence
|
||||
when a posting references them. This is convenient, but it means
|
||||
hledger can't warn you when you mis-spell an account name in the jour-
|
||||
nal. Usually you'll find that error later, as an extra account in bal-
|
||||
ance reports, or an incorrect balance when reconciling.
|
||||
|
||||
In strict mode, enabled with the -s/--strict flag, hledger will report
|
||||
an error if any transaction uses an account name that has not been
|
||||
@ -5678,41 +5729,49 @@ JOURNAL FORMAT
|
||||
account directives within the file does not matter, though it's usual
|
||||
to put them at the top.
|
||||
|
||||
o Accounts can only be declared in journal files (but will affect
|
||||
included files in other formats).
|
||||
o Accounts can only be declared in journal files, but will affect
|
||||
included files of all types.
|
||||
|
||||
o It's currently not possible to declare "all possible subaccounts"
|
||||
with a wildcard; every account posted to must be declared.
|
||||
|
||||
Account comments
|
||||
Comments, beginning with a semicolon, can be added:
|
||||
Account display order
|
||||
The order in which account directives are written influences the order
|
||||
in which accounts appear in reports, hledger-ui, hledger-web etc. By
|
||||
default accounts appear in alphabetical order, but if you add these
|
||||
account directives to the journal file:
|
||||
|
||||
o on the same line, after two or more spaces (because ; is allowed in
|
||||
account names)
|
||||
account assets
|
||||
account liabilities
|
||||
account equity
|
||||
account revenues
|
||||
account expenses
|
||||
|
||||
o on the next lines, indented
|
||||
those accounts will be displayed in declaration order:
|
||||
|
||||
An example of both:
|
||||
$ hledger accounts -1
|
||||
assets
|
||||
liabilities
|
||||
equity
|
||||
revenues
|
||||
expenses
|
||||
|
||||
account assets:bank:checking ; same-line comment, note 2+ spaces required before ;
|
||||
; next-line comment
|
||||
; some tags, type:A, acctnum:12345
|
||||
Any undeclared accounts are displayed last, in alphabetical order.
|
||||
|
||||
Compatibility note: same-line comments are not supported by Ledger or
|
||||
hledger <1.13.
|
||||
Sorting is done at each level of the account tree, within each group of
|
||||
sibling accounts under the same parent. And currently, this directive:
|
||||
|
||||
Account subdirectives
|
||||
We also allow (and ignore) Ledger-style indented subdirectives, just
|
||||
for compatibility.:
|
||||
account other:zoo
|
||||
|
||||
account assets:bank:checking
|
||||
format blah blah ; <- subdirective, ignored
|
||||
would influence the position of zoo among other's subaccounts, but not
|
||||
the position of other among the top-level accounts. This means:
|
||||
|
||||
Here is the full syntax of account directives:
|
||||
o you will sometimes declare parent accounts (eg account other above)
|
||||
that you don't intend to post to, just to customize their display
|
||||
order
|
||||
|
||||
account ACCTNAME [;type:ACCTTYPE] [COMMENT]
|
||||
[;COMMENTS]
|
||||
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]
|
||||
o sibling accounts stay together (you couldn't display x:y in between
|
||||
a:b and a:c).
|
||||
|
||||
Account types
|
||||
hledger knows that accounts come in several types: assets, liabilities,
|
||||
@ -5804,46 +5863,6 @@ JOURNAL FORMAT
|
||||
|
||||
$ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]
|
||||
|
||||
Account display order
|
||||
Account directives also set the order in which accounts are displayed,
|
||||
eg in reports, the hledger-ui accounts screen, and the hledger-web
|
||||
sidebar. By default accounts are listed in alphabetical order. But if
|
||||
you have these account directives in the journal:
|
||||
|
||||
account assets
|
||||
account liabilities
|
||||
account equity
|
||||
account revenues
|
||||
account expenses
|
||||
|
||||
you'll see those accounts displayed in declaration order, not alphabet-
|
||||
ically:
|
||||
|
||||
$ hledger accounts -1
|
||||
assets
|
||||
liabilities
|
||||
equity
|
||||
revenues
|
||||
expenses
|
||||
|
||||
Undeclared accounts, if any, are displayed last, in alphabetical order.
|
||||
|
||||
Note that sorting is done at each level of the account tree (within
|
||||
each group of sibling accounts under the same parent). And currently,
|
||||
this directive:
|
||||
|
||||
account other:zoo
|
||||
|
||||
would influence the position of zoo among other's subaccounts, but not
|
||||
the position of other among the top-level accounts. This means:
|
||||
|
||||
o you will sometimes declare parent accounts (eg account other above)
|
||||
that you don't intend to post to, just to customize their display
|
||||
order
|
||||
|
||||
o sibling accounts stay together (you couldn't display x:y in between
|
||||
a:b and a:c).
|
||||
|
||||
Rewriting accounts
|
||||
You can define account alias rules which rewrite your account names, or
|
||||
parts of them, before generating reports. This can be useful for:
|
||||
@ -6369,6 +6388,8 @@ CSV FORMAT
|
||||
below, after the examples:
|
||||
|
||||
|
||||
|
||||
|
||||
skip skip one or more header lines or matched CSV
|
||||
records
|
||||
fields list name CSV fields, assign them to hledger
|
||||
@ -6395,7 +6416,7 @@ CSV FORMAT
|
||||
Note, for best error messages when reading CSV files, use a .csv, .tsv
|
||||
or .ssv file extension or file prefix - see File Extension below.
|
||||
|
||||
There's an introductory Convert CSV files tutorial on hledger.org.
|
||||
There's an introductory Importing CSV data tutorial on hledger.org.
|
||||
|
||||
Examples
|
||||
Here are some sample hledger CSV rules files. See also the full col-
|
||||
@ -7609,21 +7630,25 @@ TIMEDOT FORMAT
|
||||
|
||||
COMMON TASKS
|
||||
Here are some quick examples of how to do some basic tasks with
|
||||
hledger. For more details, see the reference section below, the
|
||||
hledger_journal(5) manual, or the more extensive docs at
|
||||
https://hledger.org.
|
||||
hledger.
|
||||
|
||||
Getting help
|
||||
Here's how to list commands and view options and command docs:
|
||||
|
||||
$ hledger # show available commands
|
||||
$ hledger --help # show common options
|
||||
$ hledger CMD --help # show common and command options, and command help
|
||||
$ hledger help # show available manuals/topics
|
||||
$ hledger help hledger # show hledger manual, as info/man/text (auto-chosen)
|
||||
$ hledger help journal -m # show the journal topic, as a man page scrolled to that section
|
||||
$ hledger help --help # show more detailed help for the help command
|
||||
$ hledger CMD --help # show common options and CMD's options and documentation
|
||||
|
||||
Find more docs, chat, mail list, reddit, issue tracker:
|
||||
https://hledger.org/support.html
|
||||
You can also view your hledger version's manual in several formats by
|
||||
using the help command. Eg:
|
||||
|
||||
$ hledger help # show the hledger manual with info, man or $PAGER (best available)
|
||||
$ hledger help journal # show the journal topic in the hledger manual
|
||||
$ hledger help --help # show how the help command works
|
||||
|
||||
To view manuals and introductory docs on the web, visit
|
||||
https://hledger.org. Chat and mail list support and discussion ar-
|
||||
chives can be found at https://hledger.org/support.
|
||||
|
||||
Constructing command lines
|
||||
hledger has an extensive and powerful command line interface. We
|
||||
@ -8089,4 +8114,4 @@ SEE ALSO
|
||||
|
||||
|
||||
|
||||
hledger-1.26.99 July 2022 HLEDGER(1)
|
||||
hledger-1.26.99 August 2022 HLEDGER(1)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user