diff --git a/hledger/Hledger/Cli/Commands/Add.txt b/hledger/Hledger/Cli/Commands/Add.txt index ef1e20a90..b4e778c3e 100644 --- a/hledger/Hledger/Cli/Commands/Add.txt +++ b/hledger/Hledger/Cli/Commands/Add.txt @@ -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]: $ +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. diff --git a/hledger/Hledger/Cli/Commands/Balance.txt b/hledger/Hledger/Cli/Commands/Balance.txt index 2a16f9593..3cc454c11 100644 --- a/hledger/Hledger/Cli/Commands/Balance.txt +++ b/hledger/Hledger/Cli/Commands/Balance.txt @@ -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: diff --git a/hledger/Hledger/Cli/Commands/Check.txt b/hledger/Hledger/Cli/Commands/Check.txt index 7a0266ae0..04c38203b 100644 --- a/hledger/Hledger/Cli/Commands/Check.txt +++ b/hledger/Hledger/Cli/Commands/Check.txt @@ -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.) diff --git a/hledger/Hledger/Cli/Commands/Help.txt b/hledger/Hledger/Cli/Commands/Help.txt index fb94fdcd8..4d2b24c4d 100644 --- a/hledger/Hledger/Cli/Commands/Help.txt +++ b/hledger/Hledger/Cli/Commands/Help.txt @@ -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 diff --git a/hledger/Hledger/Cli/Commands/Import.txt b/hledger/Hledger/Cli/Commands/Import.txt index d9e32d62c..7636c2014 100644 --- a/hledger/Hledger/Cli/Commands/Import.txt +++ b/hledger/Hledger/Cli/Commands/Import.txt @@ -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.