diff --git a/hledger/doc/hledger.1 b/hledger/doc/hledger.1 index 0600af6da..02933e5d4 100644 --- a/hledger/doc/hledger.1 +++ b/hledger/doc/hledger.1 @@ -1998,6 +1998,15 @@ it\[aq]s just: \f[C]hledger\ import\ *.csv\f[] New transactions are detected in the same way as print \-\-new: by assuming transactions are always added to the input files in increasing date order, and by saving \f[C]\&.latest.FILE\f[] state files. +.PP +The \-\-dry\-run output is in journal format, so you can filter it, eg +to see only uncategorised transactions: +.IP +.nf +\f[C] +$\ hledger\ import\ \-\-dry\ ...\ |\ hledger\ \-f\-\ print\ unknown\ \-\-ignore\-assertions +\f[] +.fi .SS incomestatement .PP Show an income statement. @@ -2470,7 +2479,11 @@ The stats command also supports \f[C]\-o/\-\-output\-file\f[] for controlling output destination. .SS tags .PP -List all the tag names in use. +List all the tag names used in the journal. +With a TAGREGEX argument, only tag names matching the regular expression +(case insensitive) are shown. +With additional QUERY arguments, only transactions matching the query +are considered. .SS test .PP Run built\-in unit tests. diff --git a/hledger/doc/hledger.1.info b/hledger/doc/hledger.1.info index f2d09a482..0c1ba1093 100644 --- a/hledger/doc/hledger.1.info +++ b/hledger/doc/hledger.1.info @@ -1606,6 +1606,11 @@ the main journal, it's just: 'hledger import *.csv' assuming transactions are always added to the input files in increasing date order, and by saving '.latest.FILE' state files. + The -dry-run output is in journal format, so you can filter it, eg to +see only uncategorised transactions: + +$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions +  File: hledger.1.info, Node: incomestatement, Next: prices, Prev: import, Up: COMMANDS @@ -2011,7 +2016,10 @@ File: hledger.1.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS 4.21 tags ========= -List all the tag names in use. +List all the tag names used in the journal. With a TAGREGEX argument, +only tag names matching the regular expression (case insensitive) are +shown. With additional QUERY arguments, only transactions matching the +query are considered.  File: hledger.1.info, Node: test, Prev: tags, Up: COMMANDS @@ -2286,57 +2294,57 @@ Node: help50477 Ref: #help50580 Node: import51654 Ref: #import51770 -Node: incomestatement52313 -Ref: #incomestatement52449 -Node: prices54402 -Ref: #prices54519 -Node: print54562 -Ref: #print54674 -Node: print-unique59520 -Ref: #print-unique59648 -Node: register59716 -Ref: #register59845 -Node: Custom register output64346 -Ref: #custom-register-output64477 -Node: register-match65774 -Ref: #register-match65910 -Node: rewrite66093 -Ref: #rewrite66212 -Node: stats66281 -Ref: #stats66386 -Node: tags67267 -Ref: #tags67367 -Node: test67399 -Ref: #test67485 -Node: ADD-ON COMMANDS67853 -Ref: #add-on-commands67965 -Node: Official add-ons69252 -Ref: #official-add-ons69394 -Node: api69481 -Ref: #api69572 -Node: ui69624 -Ref: #ui69725 -Node: web69783 -Ref: #web69874 -Node: Third party add-ons69920 -Ref: #third-party-add-ons70097 -Node: diff70232 -Ref: #diff70331 -Node: iadd70430 -Ref: #iadd70546 -Node: interest70629 -Ref: #interest70752 -Node: irr70847 -Ref: #irr70947 -Node: Experimental add-ons71025 -Ref: #experimental-add-ons71179 -Node: autosync71470 -Ref: #autosync71584 -Node: budget71823 -Ref: #budget71947 -Node: chart72013 -Ref: #chart72132 -Node: check72203 -Ref: #check72307 +Node: incomestatement52500 +Ref: #incomestatement52636 +Node: prices54589 +Ref: #prices54706 +Node: print54749 +Ref: #print54861 +Node: print-unique59707 +Ref: #print-unique59835 +Node: register59903 +Ref: #register60032 +Node: Custom register output64533 +Ref: #custom-register-output64664 +Node: register-match65961 +Ref: #register-match66097 +Node: rewrite66280 +Ref: #rewrite66399 +Node: stats66468 +Ref: #stats66573 +Node: tags67454 +Ref: #tags67554 +Node: test67790 +Ref: #test67876 +Node: ADD-ON COMMANDS68244 +Ref: #add-on-commands68356 +Node: Official add-ons69643 +Ref: #official-add-ons69785 +Node: api69872 +Ref: #api69963 +Node: ui70015 +Ref: #ui70116 +Node: web70174 +Ref: #web70265 +Node: Third party add-ons70311 +Ref: #third-party-add-ons70488 +Node: diff70623 +Ref: #diff70722 +Node: iadd70821 +Ref: #iadd70937 +Node: interest71020 +Ref: #interest71143 +Node: irr71238 +Ref: #irr71338 +Node: Experimental add-ons71416 +Ref: #experimental-add-ons71570 +Node: autosync71861 +Ref: #autosync71975 +Node: budget72214 +Ref: #budget72338 +Node: chart72404 +Ref: #chart72523 +Node: check72594 +Ref: #check72698  End Tag Table diff --git a/hledger/doc/hledger.1.txt b/hledger/doc/hledger.1.txt index 4642e2b2b..188aa4f96 100644 --- a/hledger/doc/hledger.1.txt +++ b/hledger/doc/hledger.1.txt @@ -1412,6 +1412,11 @@ COMMANDS ing transactions are always added to the input files in increasing date order, and by saving .latest.FILE state files. + The --dry-run output is in journal format, so you can filter it, eg to + see only uncategorised transactions: + + $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions + incomestatement Show an income statement. Alias: is. @@ -1419,7 +1424,7 @@ COMMANDS show balance change in each period (default) --cumulative - show balance change accumulated across periods (in multicolumn + show balance change accumulated across periods (in multicolumn reports), instead of changes during periods -H --historical @@ -1453,8 +1458,8 @@ COMMANDS --sort-amount sort by amount instead of account name - This command displays a simple income statement. It currently assumes - that you have top-level accounts named income (or revenue) and expense + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense (plural forms also allowed.) $ hledger incomestatement @@ -1479,8 +1484,8 @@ COMMANDS 0 With a reporting interval, multiple columns will be shown, one for each - report period. Normally incomestatement shows revenues/expenses per - period, though as with multicolumn balance reports you can alter the + report period. Normally incomestatement shows revenues/expenses per + period, though as with multicolumn balance reports you can alter the report mode with --change/--cumulative/--historical. prices @@ -1490,7 +1495,7 @@ COMMANDS Show transactions from the journal. Aliases: p, txns. -m STR --match=STR - show the transaction whose description is most similar to STR, + show the transaction whose description is most similar to STR, and is most recent --new show only newer-dated transactions added in each file since last @@ -1503,7 +1508,7 @@ COMMANDS select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger print @@ -1534,39 +1539,39 @@ COMMANDS it does not preserve directives or inter-transaction comments Normally, the journal entry's explicit or implicit amount style is pre- - served. Ie when an amount is omitted in the journal, it will be omit- - ted in the output. You can use the -x/--explicit flag to make all + served. Ie when an amount is omitted in the journal, it will be omit- + ted in the output. You can use the -x/--explicit flag to make all amounts explicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. Note, - -x will cause postings with a multi-commodity amount (these can arise - when a multi-commodity transaction has an implicit amount) will be - split into multiple single-commodity postings, for valid journal out- + -x will cause postings with a multi-commodity amount (these can arise + when a multi-commodity transaction has an implicit amount) will be + split into multiple single-commodity postings, for valid journal out- put. - With -B/--cost, amounts with transaction prices are converted to cost + With -B/--cost, amounts with transaction prices are converted to cost using that price. - With -m/--match and a STR argument, print will show at most one trans- - action: the one one whose description is most similar to STR, and is - most recent. STR should contain at least two characters. If there is + With -m/--match and a STR argument, print will show at most one trans- + action: the one one whose description is most similar to STR, and is + most recent. STR should contain at least two characters. If there is no similar-enough match, no transaction will be shown. With --new, for each FILE being read, hledger reads (and writes) a spe- - cial state file (.latest.FILE in the same directory), containing the - latest transaction date(s) that were seen last time FILE was read. - When this file is found, only transactions with newer dates (and new - transactions on the latest date) are printed. This is useful for - ignoring already-seen entries in import data, such as downloaded CSV + cial state file (.latest.FILE in the same directory), containing the + latest transaction date(s) that were seen last time FILE was read. + When this file is found, only transactions with newer dates (and new + transactions on the latest date) are printed. This is useful for + ignoring already-seen entries in import data, such as downloaded CSV files. Eg: $ hledger -f bank1.csv print --new # shows transactions added since last print --new on this file - This assumes that transactions added to FILE always have same or - increasing dates, and that transactions on the same day do not get + This assumes that transactions added to FILE always have same or + increasing dates, and that transactions on the same day do not get reordered. See also the import command. - The print command also supports output destination and CSV output. + The print command also supports output destination and CSV output. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -1583,20 +1588,20 @@ COMMANDS "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","","" "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","","" - o There is one CSV record per posting, with the parent transaction's + o There is one CSV record per posting, with the parent transaction's fields repeated. o The "txnidx" (transaction index) field shows which postings belong to - the same transaction. (This number might change if transactions are - reordered within the file, files are parsed/included in a different + the same transaction. (This number might change if transactions are + reordered within the file, files are parsed/included in a different order, etc.) - o The amount is separated into "commodity" (the symbol) and "amount" + o The amount is separated into "commodity" (the symbol) and "amount" (numeric quantity) fields. o The numeric amount is repeated in either the "credit" or "debit" col- - umn, for convenience. (Those names are not accurate in the account- - ing sense; it just puts negative amounts under credit and zero or + umn, for convenience. (Those names are not accurate in the account- + ing sense; it just puts negative amounts under credit and zero or greater amounts under debit.) print-unique @@ -1609,7 +1614,7 @@ COMMANDS show running total from report start date (default) -H --historical - show historical running total/balance (includes postings before + show historical running total/balance (includes postings before report start date) -A --average @@ -1620,18 +1625,18 @@ COMMANDS show postings' siblings instead -w N --width=N - set output width (default: terminal width or COLUMNS. -wN,M + set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. The register command displays postings, one per line, and their running - total. This is typically used with a query selecting a particular + total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -1640,8 +1645,8 @@ COMMANDS 2008/06/02 save assets:bank:checking $-1 $1 2008/12/31 pay off assets:bank:checking $-1 0 - The --historical/-H flag adds the balance from any undisplayed prior - postings to the running total. This is useful when you want to see + The --historical/-H flag adds the balance from any undisplayed prior + postings to the running total. This is useful when you want to see only recent activity, with a historically accurate running balance: $ hledger register checking -b 2008/6 --historical @@ -1651,23 +1656,23 @@ COMMANDS The --depth option limits the amount of sub-account detail displayed. - The --average/-A flag shows the running average posting amount instead + The --average/-A flag shows the running average posting amount instead of the running total (so, the final number displayed is the average for - the whole report period). This flag implies --empty (see below). It - is affected by --historical. It works best when showing just one + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one account and one commodity. - The --related/-r flag shows the other postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. - With a reporting interval, register shows summary postings, one per + With a reporting interval, register shows summary postings, one per interval, aggregating the postings to each account: $ hledger register --monthly income 2008/01 income:salary $-1 $-1 2008/06 income:gifts $-1 $-2 - Periods with no activity, and summary postings with a zero amount, are + Periods with no activity, and summary postings with a zero amount, are not shown by default; use the --empty/-E flag to see them: $ hledger register --monthly income -E @@ -1684,7 +1689,7 @@ COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth + 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 @@ -1692,19 +1697,19 @@ COMMANDS 2008/06 assets $-1 0 2008/12 assets $-1 $-1 - Note when using report intervals, if you specify start/end dates these - will be adjusted outward if necessary to contain a whole number of - intervals. This ensures that the first and last intervals are full + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of + intervals. This ensures that the first and last intervals are full length and comparable to the others in the report. Custom register output - register uses the full terminal width by default, except on windows. - You can override this by setting the COLUMNS environment variable (not + register uses the full terminal width by default, except on windows. + You can override this by setting the COLUMNS environment variable (not a bash shell variable) or by using the --width/-w option. - The description and account columns normally share the space equally - (about half of (width - 40) each). You can adjust this by adding a - description width as part of --width's argument, comma-separated: + The description and account columns normally share the space equally + (about half of (width - 40) each). You can adjust this by adding a + description width as part of --width's argument, comma-separated: --width W,D . Here's a diagram: <--------------------------------- width (W) ----------------------------------> @@ -1720,12 +1725,12 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width - The register command also supports the -o/--output-file and -O/--out- + The register command also supports the -o/--output-file and -O/--out- put-format options for controlling output destination and CSV output. register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. Helps ledger-autosync detect + in the style of the register command. Helps ledger-autosync detect already-seen transactions when importing. rewrite @@ -1735,7 +1740,7 @@ COMMANDS Show some journal statistics. -o FILE --output-file=FILE - write output to FILE. A file extension matching one of the + write output to FILE. A file extension matching one of the above formats selects that format. $ hledger stats @@ -1750,15 +1755,18 @@ COMMANDS Accounts : 8 (depth 3) Commodities : 1 ($) - The stats command displays summary information for the whole journal, - or a matched part of it. With a reporting interval, it shows a report + The stats command displays summary information for the whole journal, + or a matched part of it. With a reporting interval, it shows a report for each report period. The stats command also supports -o/--output-file for controlling output destination. tags - List all the tag names in use. + List all the tag names used in the journal. With a TAGREGEX argument, + only tag names matching the regular expression (case insensitive) are + shown. With additional QUERY arguments, only transactions matching the + query are considered. test Run built-in unit tests.