diff --git a/hledger/Hledger/Cli/Commands/Add.txt b/hledger/Hledger/Cli/Commands/Add.txt index 9fb9a68a0..71584d4ce 100644 --- a/hledger/Hledger/Cli/Commands/Add.txt +++ b/hledger/Hledger/Cli/Commands/Add.txt @@ -1,6 +1,6 @@ add -Record new transactions with interactive prompting in the console. +Add new transactions to a journal file, with interactive prompting. Flags: --no-new-accounts don't allow creating new accounts @@ -40,6 +40,8 @@ Notes: 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. +- add creates entries in journal format; it won't work with timeclock or + timedot files. Examples: diff --git a/hledger/Hledger/Cli/Commands/Aregister.txt b/hledger/Hledger/Cli/Commands/Aregister.txt index e6482caac..53c609dba 100644 --- a/hledger/Hledger/Cli/Commands/Aregister.txt +++ b/hledger/Hledger/Cli/Commands/Aregister.txt @@ -50,7 +50,7 @@ matches uniquely. Transactions involving subaccounts of this account will also be shown. aregister ignores depth limits, so its final total will always match a -balance report with similar arguments. +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 diff --git a/hledger/Hledger/Cli/Commands/Demo.txt b/hledger/Hledger/Cli/Commands/Demo.txt index 406c9b927..bc8e32a5c 100644 --- a/hledger/Hledger/Cli/Commands/Demo.txt +++ b/hledger/Hledger/Cli/Commands/Demo.txt @@ -15,9 +15,6 @@ Use the -s/--speed SPEED option to set your preferred playback speed, eg -s4 to play at 4x original speed or -s.5 to play at half speed. The default speed is 2x. -Other asciinema options can be added following a double dash, eg -- -i.1 -to limit pauses or -- -h to list asciinema's other options. - During playback, several keys are available: SPACE to pause/unpause, . to step forward (while paused), CTRL-c quit. diff --git a/hledger/Hledger/Cli/Commands/Import.txt b/hledger/Hledger/Cli/Commands/Import.txt index 7dac436ed..e384b88e1 100644 --- a/hledger/Hledger/Cli/Commands/Import.txt +++ b/hledger/Hledger/Cli/Commands/Import.txt @@ -23,7 +23,7 @@ $ hledger import bank1-checking.csv bank1-savings.csv $ hledger import *.csv -Import preview +Import dry run It's useful to preview the import by running first with --dry-run, to sanity check the range of dates being imported, and to check the effect @@ -40,7 +40,7 @@ $ hledger import --dry-run bank.csv | hledger -f- -I print unknown You could also run this repeatedly to see the effect of edits to your conversion rules: -$ watchexec -- 'hledger import --dry-run bank.csv | hledger -f- -I print unknown' +$ watchexec -- "hledger import --dry-run bank.csv | hledger -f- -I print unknown" Once the conversion and dates look good enough to import to your journal, perhaps with some manual fixups to follow, you would do the @@ -164,30 +164,53 @@ directives or inferred from the journal's amounts. Related: CSV > Amount decimal places. +Import archiving + +When importing from a CSV rules file (hledger import bank.rules), you +can use the archive rule to enable automatic archiving of the data file. +After a successful import, the data file (specified by source) will be +moved to an archive folder (data/, next to the rules file, +auto-created), and renamed similar to the rules file, with a date. This +can be useful for troubleshooting, detecting variations in your banks' +CSV data, regenerating entries with improved rules, etc. + +The archive rule also causes import to handle source glob patterns +differently: when there are multiple matched files, it will pick the +oldest, not the newest. + Import special cases -If you have a download whose file name varies, you could rename it to a -fixed name after each download. Or you could use a CSV source rule with -a suitable glob pattern, and import from the .rules file instead of the -data file. - -Here's a situation where you would need to run import with care: say you -download bank.csv, but forget to import it or delete it. And next month -you download it again. This time your web browser may save it as -bank (2).csv. So now each of these may have data not included in the -other. And a source rule with a glob pattern would match only the most -recent file. So in this case you should import from each one in turn, in -the correct order, taking care to use the same filename each time: - -$ hledger import bank.csv -$ mv 'bank (2).csv' bank.csv -$ hledger import bank.csv +Deduplication Here are two kinds of "deduplication" which import does not handle (and -generally should not, since these can happen legitimately in financial -data): +should not, because these can happen legitimately in financial data): - Two or more of the new CSV records are identical, and generate identical new journal entries. - A new CSV record generates a journal entry identical to one(s) already in the journal. + +Varying file name + +If you have a download whose file name varies, you could rename it to a +fixed name after each download. Or you could use a CSV source rule with +a suitable glob pattern, and import from the .rules file. + +Multiple versions + +Say you download bank.csv, import it, but forget to delete it from your +downloads folder. The next time you download it, your web browser will +save it as (eg) bank (2).csv. The source rule's glob patterns are for +just this situation: instead of specifying source bank.csv, specify +source bank*.csv. Then hledger -f bank.rules CMD or +hledger import bank.rules will automatically pick the newest matched +file (bank (2).csv). + +Alternately, what if you download, but forget to import or delete, then +download again ? Now each of bank.csv and bank (2).csv might contain +data that's not in the other, and not in your journal. In this case, +it's best to import each of them in turn, oldest first (otherwise, +overlap detection could cause new records to be skipped). Enabling +import archiving ensures this. Then +hledger import bank.rules; hledger import bank.rules will import and +archive first bank.csv, then bank (2).csv. diff --git a/hledger/Hledger/Cli/Commands/Rewrite.txt b/hledger/Hledger/Cli/Commands/Rewrite.txt index ac7e8a88f..68902d29b 100644 --- a/hledger/Hledger/Cli/Commands/Rewrite.txt +++ b/hledger/Hledger/Cli/Commands/Rewrite.txt @@ -38,10 +38,10 @@ spaces between account and amount. More: -$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... -$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' -$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' -$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' +$ hledger rewrite [QUERY] --add-posting "ACCT AMTEXPR" ... +$ hledger rewrite ^income --add-posting '(liabilities:tax) *.33' +$ hledger rewrite expenses:gifts --add-posting '(budget:gifts) *-1"' +$ hledger rewrite ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify' Argument for --add-posting option is a usual posting of transaction with an exception for amount specification. More precisely, you can use '*' @@ -71,12 +71,12 @@ Note that '=' (equality symbol) that is used instead of date in transactions you usually write. It indicates the query by which you want to match the posting to add new ones. -$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal +$ hledger rewrite -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal This is something similar to the commands pipeline: -$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ - | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \ +$ hledger rewrite -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \ + | hledger rewrite -f - expenses:gifts --add-posting 'budget:gifts *-1' \ --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal @@ -89,7 +89,7 @@ Diff output format To use this tool for batch modification of your journal files you may find useful output in form of unified diff. -$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' +$ hledger rewrite --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33' Output might look like: