mirror of
https://github.com/simonmichael/hledger.git
synced 2024-12-24 02:44:25 +03:00
;doc: update command help
This commit is contained in:
parent
6007e4b417
commit
f3eba65726
@ -36,35 +36,27 @@ Features:
|
||||
- Input prompts are displayed in a different colour when the terminal
|
||||
supports it.
|
||||
|
||||
Example (see https://hledger.org/add.html for a detailed tutorial):
|
||||
Notes:
|
||||
|
||||
$ hledger add
|
||||
Adding transactions to journal file /src/hledger/examples/sample.journal
|
||||
Any command line arguments will be used as defaults.
|
||||
Use tab key to complete, readline keys to edit, enter to accept defaults.
|
||||
An optional (CODE) may follow transaction dates.
|
||||
An optional ; COMMENT may follow descriptions or amounts.
|
||||
If you make a mistake, enter < at any prompt to go one step backward.
|
||||
To end a transaction, enter . when prompted.
|
||||
To quit, enter . at a date prompt or press control-d or control-c.
|
||||
Date [2015/05/22]:
|
||||
Description: supermarket
|
||||
Account 1: expenses:food
|
||||
Amount 1: $10
|
||||
Account 2: assets:checking
|
||||
Amount 2 [$-10.0]:
|
||||
Account 3 (or . or enter to finish this transaction): .
|
||||
2015/05/22 supermarket
|
||||
expenses:food $10
|
||||
assets:checking $-10.0
|
||||
- If you enter a number with no commodity symbol, and you have
|
||||
declared a default commodity with a D directive, you might expect
|
||||
add to add this symbol for you. It does not do this; we assume that
|
||||
if you are using a D directive you prefer not to see the commodity
|
||||
symbol repeated on amounts in the journal.
|
||||
|
||||
Save this transaction to the journal ? [y]:
|
||||
Saved.
|
||||
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
|
||||
Date [2015/05/22]: <CTRL-D> $
|
||||
Examples:
|
||||
|
||||
If you enter a number with no commodity symbol, and you have declared a
|
||||
default commodity with a D directive, you might expect add to add this
|
||||
symbol for you. It does not do this; we assume that if you are using a D
|
||||
directive you prefer not to see the commodity symbol repeated on amounts
|
||||
in the journal.
|
||||
- Record new transactions, saving to the default journal file:
|
||||
|
||||
hledger add
|
||||
|
||||
- Add transactions to 2024.journal, but also load 2023.journal for
|
||||
completions:
|
||||
|
||||
hledger add --file 2024.journal --file 2023.journal
|
||||
|
||||
- Provide answers for the first four prompts:
|
||||
|
||||
hledger add today 'best buy' expenses:supplies '$20'
|
||||
|
||||
There is a detailed tutorial at https://hledger.org/add.html.
|
||||
|
@ -336,6 +336,9 @@ Notes:
|
||||
- The --transpose flag can be used to exchange rows and columns.
|
||||
- The --pivot FIELD option causes a different transaction field to be
|
||||
used as "account name". See PIVOTING.
|
||||
- The --summary-only flag (--summary also works) hides all but the
|
||||
Total and Average columns (those should be enabled with --row-total
|
||||
and -A/--average).
|
||||
|
||||
Multi-period reports with many periods can be too wide for easy viewing
|
||||
in the terminal. Here are some ways to handle that:
|
||||
|
@ -4,91 +4,102 @@ Check for various kinds of errors in your data.
|
||||
|
||||
_FLAGS
|
||||
|
||||
hledger provides a number of built-in error checks to help prevent
|
||||
problems in your data. Some of these are run automatically; or, you can
|
||||
use this check command to run them on demand, with no output and a zero
|
||||
exit code if all is well. Specify their names (or a prefix) as
|
||||
argument(s).
|
||||
hledger provides a number of built-in correctness checks to help
|
||||
validate your data and prevent errors. Some are run automatically, some
|
||||
when you enable --strict mode; or you can run any of them on demand by
|
||||
providing them as arguments to the check command. check produces no
|
||||
output and a zero exit code if all is well. Eg:
|
||||
|
||||
Some examples:
|
||||
|
||||
hledger check # basic checks
|
||||
hledger check -s # basic + strict checks
|
||||
hledger check ordereddates payees # basic + two other checks
|
||||
hledger check # run basic checks
|
||||
hledger check -s # run basic and strict checks
|
||||
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:
|
||||
Here are the checks currently available. Generally, they are performed
|
||||
in the order they are shown here (and only the first failure is
|
||||
reported).
|
||||
|
||||
Default checks
|
||||
Basic checks
|
||||
|
||||
These checks are run automatically by (almost) all hledger commands:
|
||||
These important checks are performed by default, by almost all hledger
|
||||
commands:
|
||||
|
||||
- parseable - data files are in a supported format, with no syntax
|
||||
errors and no invalid include directives.
|
||||
errors and no invalid include directives. This ensures that all
|
||||
files exist and are readable.
|
||||
|
||||
- autobalanced - all transactions are balanced, after converting to
|
||||
cost. Missing amounts and missing costs are inferred automatically
|
||||
where possible.
|
||||
- autobalanced - all transactions are balanced, after inferring
|
||||
missing amounts and conversion costs where possible, and then
|
||||
converting to cost. This ensures that each individual transaction is
|
||||
well formed.
|
||||
|
||||
- assertions - all balance assertions in the journal are passing.
|
||||
(This check can be disabled with -I/--ignore-assertions.)
|
||||
Balance assertions are like canaries in your journal, they catch
|
||||
many problems. They can get in the way sometimes; you can disable
|
||||
them temporarily with -I/--ignore-assertions (unless overridden with
|
||||
-s/--strict or hledger check assertions).
|
||||
|
||||
Strict checks
|
||||
|
||||
These additional checks are run when the -s/--strict (strict mode) flag
|
||||
is used. Or, they can be run by giving their names as arguments to
|
||||
check:
|
||||
These additional checks are performed by any command when the
|
||||
-s/--strict flag is used (strict mode). Strict mode always enables the
|
||||
balance assertions check, also. These provide extra error-catching power
|
||||
when you are serious about keeping your data clean and free of typos:
|
||||
|
||||
- balanced - all transactions are balanced after converting to cost,
|
||||
without inferring missing costs. If conversion costs are required,
|
||||
they must be explicit.
|
||||
- balanced - like autobalanced, but in conversion transactions, costs
|
||||
must be written explicitly. This ensures some redundancy in the
|
||||
entry, which helps prevent typos.
|
||||
|
||||
- accounts - all account names used by transactions have been declared
|
||||
- commodities - all commodity symbols used must be declared. This
|
||||
guards against mistyping or omitting commodity symbols.
|
||||
|
||||
- commodities - all commodity symbols used have been declared
|
||||
- accounts - all account names used must be declared. This prevents
|
||||
the use of mis-spelled or outdated account names.
|
||||
|
||||
Other checks
|
||||
|
||||
These checks can be run only by giving their names as arguments to
|
||||
check. They are more specialised and not desirable for everyone:
|
||||
These other checks are not wanted by everyone, but can be run using the
|
||||
check command:
|
||||
|
||||
- ordereddates - transactions are ordered by date within each file
|
||||
- ordereddates - within each file, transactions are ordered by date.
|
||||
This is a simple and effective error catcher, and you should use it.
|
||||
Alas! not everyone wants it. If you do, use
|
||||
hledger check -s ordereddates. When enabled, this check is performed
|
||||
early, before balance assertions (because copy-pasted dates are
|
||||
often the root cause of balance assertion failures).
|
||||
|
||||
- payees - all payees used by transactions have been declared
|
||||
- payees - all payees used by transactions must be declared. This will
|
||||
force you to always use known/declared payee names. For most people
|
||||
this is a bit too restrictive.
|
||||
|
||||
- recentassertions - all accounts with balance assertions have a
|
||||
balance assertion within 7 days of their latest posting
|
||||
- tags - all tags used by transactions must be declared. This prevents
|
||||
mistyped tag names.
|
||||
|
||||
- tags - all tags used by transactions have been declared
|
||||
- recentassertions - all accounts with balance assertions must have a
|
||||
balance assertion within the last 7 days before their latest
|
||||
posting. This encourages you to add balance assertions fairly
|
||||
regularly for your active asset/liability accounts, which in turn
|
||||
should encourage you to check and reconcile with their real world
|
||||
balances fairly regularly. close --assert can be helpful. (The older
|
||||
balance assertions become redundant; you can remove them
|
||||
periodically, or leave them in place, perhaps commented, as
|
||||
documentation.)
|
||||
|
||||
- uniqueleafnames - all account leaf names are unique
|
||||
- uniqueleafnames - no two accounts may have the same leaf name. The
|
||||
leaf name is the last colon-separated part of an account name, eg
|
||||
checking in assets:bank:checking. This encourages you to keep those
|
||||
unique, effectively giving each account a short name which is easier
|
||||
to remember and to type in reporting commands.
|
||||
|
||||
Custom checks
|
||||
|
||||
A few more checks are are available as separate add-on commands, in
|
||||
https://github.com/simonmichael/hledger/tree/master/bin:
|
||||
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-fancyassertions - more complex balance assertions are
|
||||
passing
|
||||
|
||||
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 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.)
|
||||
|
@ -1,31 +1,31 @@
|
||||
help
|
||||
|
||||
Show the hledger user manual in the terminal, with info, man, or a
|
||||
pager. With a TOPIC argument, open it at that topic if possible. TOPIC
|
||||
can be any heading in the manual, or a heading prefix, case insensitive.
|
||||
Eg: commands, print, forecast, journal, amount, "auto postings".
|
||||
Show the hledger user manual with info, man, or a pager. With a (case
|
||||
insensitive) TOPIC argument, try to open it at that section heading.
|
||||
|
||||
_FLAGS
|
||||
|
||||
This command shows the hledger manual built in to your hledger version.
|
||||
It can be useful when offline, or when you prefer the terminal to a web
|
||||
browser, or when the appropriate hledger manual or viewing tools are not
|
||||
installed on your system.
|
||||
This command shows the hledger manual built in to your hledger
|
||||
executable. It can be useful when offline, or when you prefer the
|
||||
terminal to a web browser, or when the appropriate hledger manual or
|
||||
viewers are not installed properly on your system.
|
||||
|
||||
By default it chooses the best viewer found in $PATH, trying (in this
|
||||
order): info, man, $PAGER, less, more. You can force the use of info,
|
||||
man, or a pager with the -i, -m, or -p flags, If no viewer can be found,
|
||||
or the command is run non-interactively, it just prints the manual to
|
||||
stdout.
|
||||
By default it chooses the best viewer found in $PATH, trying in this
|
||||
order: info, man, $PAGER, less, more, stdout. (If a TOPIC is specified,
|
||||
$PAGER and more are not tried.) You can force the use of info, man, or a
|
||||
pager with the -i, -m, or -p flags. If no viewer can be found, or if
|
||||
running non-interactively, it just prints the manual to stdout.
|
||||
|
||||
If using info, note that version 6 or greater is needed for TOPIC
|
||||
lookup. If you are on mac you will likely have info 4.8, and should
|
||||
consider installing a newer version, eg with brew install texinfo
|
||||
(#1770).
|
||||
When using info, TOPIC can match either the full heading or a prefix. If
|
||||
your info --version is < 6, you'll need to upgrade it, eg with
|
||||
'brew install texinfo' on mac.
|
||||
|
||||
When using man or less, TOPIC must match the full heading. For a prefix
|
||||
match, you can write 'TOPIC.*'.
|
||||
|
||||
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
|
||||
$ hledger help -m journal # show it with man, even if info is installed
|
||||
$ hledger help -h # show the help command's usage
|
||||
$ hledger help # show the manual with info, man or $PAGER
|
||||
$ hledger help 'time periods' # show the manual's "Time periods" topic
|
||||
$ hledger help 'time periods' -m # use man, even if info is installed
|
||||
|
@ -21,7 +21,7 @@ hledger import bank.csv or perhaps hledger import *.csv.
|
||||
Note you can import from any file format, though CSV files are the most
|
||||
common import source, and these docs focus on that case.
|
||||
|
||||
Deduplication
|
||||
Date skipping
|
||||
|
||||
import tries to import only the transactions which are new since the
|
||||
last import, ignoring any that it has seen in previous runs. So if your
|
||||
@ -29,53 +29,55 @@ bank's CSV includes the last three months of data, you can download and
|
||||
import it every month (or week, or day) and only the new transactions
|
||||
will be imported each time.
|
||||
|
||||
It works as follows. For each imported FILE (usually CSV, but they could
|
||||
be any of hledger's input formats):
|
||||
It works as follows: for each imported FILE,
|
||||
|
||||
- It tries to recall the latest date seen previously, reading it from
|
||||
a hidden .latest.FILE in the same directory.
|
||||
- Then it processes FILE, ignoring any transactions on or before the
|
||||
"latest seen" date.
|
||||
- It tries to read the latest date previously seen, from .latest.FILE
|
||||
in the same directory
|
||||
- Then it processes FILE, ignoring transactions on or before that date
|
||||
|
||||
And after a successful import, it updates the .latest.FILE(s) for next
|
||||
time (unless --dry-run was used).
|
||||
And after a successful import, unless --dry-run was used, it updates the
|
||||
.latest.FILE(s) for next time. This is a simple system that works for
|
||||
most real-world CSV files; it assumes the following are true, or true
|
||||
enough:
|
||||
|
||||
This is a limited kind of deduplication, let's call it "date skipping".
|
||||
Within each input file, it avoids reprocessing the same dates across
|
||||
successive runs. This is a simple system that works for most real-world
|
||||
CSV files; it assumes these are true, or true enough:
|
||||
1. the name of the input file is stable across successive downloads
|
||||
2. new items always have the newest dates
|
||||
3. item dates are stable across downloads
|
||||
4. the order of same-date items is stable across downloads.
|
||||
|
||||
1. new items always have the newest dates
|
||||
2. item dates are stable across successive downloads
|
||||
3. the order of same-date items is stable across downloads
|
||||
4. the name of the input file is stable across downloads
|
||||
Tips:
|
||||
|
||||
If you have a bank whose CSV dates or ordering occasionally change, you
|
||||
can reduce the chance of this happening in new transactions by importing
|
||||
more often, and in old transactions it doesn't matter. And remember you
|
||||
can use CSV rules files as input, which is one way to ensure a stable
|
||||
file name.
|
||||
- To help ensure a stable file name, remember you can use a CSV rules
|
||||
file as an input file.
|
||||
|
||||
import doesn't detect other kinds of duplication, such as duplicate
|
||||
transactions within a single run. (In part, because legitimate duplicate
|
||||
transactions can easily occur in real-world data.) So, say you
|
||||
downloaded but forgot to import bank.1.csv, and a week later you
|
||||
downloaded bank.2.csv with overlapping data. Now you should not import
|
||||
both of these at once (hledger import bank.1.csv bank.2.csv); the
|
||||
overlapping transactions which appear twice would not be deduplicated
|
||||
since this is considered a single import. Instead, import these files
|
||||
one at a time, and also use the same filename each time for a common
|
||||
"latest seen" state:
|
||||
- If you have a bank whose CSV dates or ordering occasionally change,
|
||||
you can reduce the chance of this happening in new transactions by
|
||||
importing more often. (If it happens in old transactions, that's
|
||||
harmless.)
|
||||
|
||||
Note this is just one kind of "deduplication": not reprocessing the same
|
||||
dates across successive runs. import doesn't detect other kinds of
|
||||
duplication, such as the same transaction appearing multiple times
|
||||
within a single run, or a new transaction that looks identical to a
|
||||
transaction already in the journal. (Because these can happen
|
||||
legitimately in real-world data.)
|
||||
|
||||
Here's a situation where you need to run import with care: say you
|
||||
download but forget to import bank.1.csv, and a week later you download
|
||||
bank.2.csv with some overlapping data. You should not process both of
|
||||
these as a single import (hledger import bank.1.csv bank.2.csv), because
|
||||
the overlapping transactions would not be deduplicated. Instead, import
|
||||
one file at a time, using the same filename each time:
|
||||
|
||||
$ mv bank.1.csv bank.csv; hledger import bank.csv
|
||||
$ mv bank.2.csv bank.csv; hledger import bank.csv
|
||||
|
||||
Normally you can ignore the .latest.* files, but if needed, you can
|
||||
delete them (to make all transactions unseen), or construct/modify them
|
||||
(to catch up to a certain date). The format is just a single ISO-format
|
||||
date (YYYY-MM-DD), possibly repeated on multiple lines. It means "I have
|
||||
seen transactions up to this date, and this many of them occurring on
|
||||
that date".
|
||||
Normally you don't need to think about .latest.* files, but you can
|
||||
create or modify them to catch up to a certain date, or delete them to
|
||||
mark all transactions as new. Their format is a single ISO-format
|
||||
YYYY-MM-DD date, optionally repeated on multiple lines, meaning "I have
|
||||
seen the transactions before this date, and this many of them on this
|
||||
date".
|
||||
|
||||
hledger print --new also uses and updates these .latest.* files, but it
|
||||
is less often used.
|
||||
@ -118,7 +120,10 @@ $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
|
||||
(If you think import should leave amounts implicit like print does,
|
||||
please test it and send a pull request.)
|
||||
|
||||
Commodity display styles
|
||||
Import and commodity styles
|
||||
|
||||
Imported amounts will be formatted according to the canonical commodity
|
||||
styles (declared or inferred) in the main journal file.
|
||||
Amounts in entries added by import will be formatted according to the
|
||||
journal's canonical commodity styles, as declared by commodity
|
||||
directives or inferred from the journal's amounts.
|
||||
|
||||
Related: CSV > Amount decimal places.
|
||||
|
Loading…
Reference in New Issue
Block a user