diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index d405506d9..b4fbdc663 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -674,7 +674,18 @@ number, like \f[C]%date\f[R] or \f[C]%1\f[R]. .PP A single matcher can be written on the same line as the \[dq]if\[dq]; or multiple matchers can be written on the following lines, non-indented. -Multiple matchers are OR\[aq]d (any one of them can match). +Multiple matchers are OR\[aq]d (any one of them can match), unless one +begins with an \f[C]&\f[R] symbol, in which case it is AND\[aq]ed with +the previous matcher. +.IP +.nf +\f[C] +if +MATCHER +& MATCHER + RULE +\f[R] +.fi .PP After the patterns there should be one or more rules to apply, all indented by at least one space. diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index 00f9d81e1..9a3e6605f 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -642,7 +642,14 @@ is a percent sign followed by the field's name or column number, like A single matcher can be written on the same line as the "if"; or multiple matchers can be written on the following lines, non-indented. -Multiple matchers are OR'd (any one of them can match). +Multiple matchers are OR'd (any one of them can match), unless one +begins with an '&' symbol, in which case it is AND'ed with the previous +matcher. + +if +MATCHER +& MATCHER + RULE After the patterns there should be one or more rules to apply, all indented by at least one space. Three kinds of rule are allowed in @@ -1141,40 +1148,40 @@ Node: separator21340 Ref: #separator21475 Node: if block21886 Ref: #if-block22011 -Node: if table24167 -Ref: #if-table24286 -Node: end26024 -Ref: #end26136 -Node: date-format26360 -Ref: #date-format26492 -Node: newest-first27241 -Ref: #newest-first27379 -Node: include28062 -Ref: #include28193 -Node: balance-type28637 -Ref: #balance-type28757 -Node: TIPS29457 -Ref: #tips29539 -Node: Rapid feedback29795 -Ref: #rapid-feedback29912 -Node: Valid CSV30372 -Ref: #valid-csv30502 -Node: File Extension30694 -Ref: #file-extension30846 -Node: Reading multiple CSV files31256 -Ref: #reading-multiple-csv-files31441 -Node: Valid transactions31682 -Ref: #valid-transactions31860 -Node: Deduplicating importing32488 -Ref: #deduplicating-importing32667 -Node: Setting amounts33700 -Ref: #setting-amounts33869 -Node: Setting currency/commodity34856 -Ref: #setting-currencycommodity35048 -Node: Referencing other fields35851 -Ref: #referencing-other-fields36051 -Node: How CSV rules are evaluated36948 -Ref: #how-csv-rules-are-evaluated37121 +Node: if table24287 +Ref: #if-table24406 +Node: end26144 +Ref: #end26256 +Node: date-format26480 +Ref: #date-format26612 +Node: newest-first27361 +Ref: #newest-first27499 +Node: include28182 +Ref: #include28313 +Node: balance-type28757 +Ref: #balance-type28877 +Node: TIPS29577 +Ref: #tips29659 +Node: Rapid feedback29915 +Ref: #rapid-feedback30032 +Node: Valid CSV30492 +Ref: #valid-csv30622 +Node: File Extension30814 +Ref: #file-extension30966 +Node: Reading multiple CSV files31376 +Ref: #reading-multiple-csv-files31561 +Node: Valid transactions31802 +Ref: #valid-transactions31980 +Node: Deduplicating importing32608 +Ref: #deduplicating-importing32787 +Node: Setting amounts33820 +Ref: #setting-amounts33989 +Node: Setting currency/commodity34976 +Ref: #setting-currencycommodity35168 +Node: Referencing other fields35971 +Ref: #referencing-other-fields36171 +Node: How CSV rules are evaluated37068 +Ref: #how-csv-rules-are-evaluated37241  End Tag Table diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 9d8db4c6e..06b663d05 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -506,10 +506,16 @@ CSV RULES A single matcher can be written on the same line as the "if"; or multi- ple matchers can be written on the following lines, non-indented. Mul- - tiple matchers are OR'd (any one of them can match). + tiple matchers are OR'd (any one of them can match), unless one begins + with an & symbol, in which case it is AND'ed with the previous matcher. - After the patterns there should be one or more rules to apply, all in- - dented by at least one space. Three kinds of rule are allowed in con- + if + MATCHER + & MATCHER + RULE + + After the patterns there should be one or more rules to apply, all in- + dented by at least one space. Three kinds of rule are allowed in con- ditional blocks: o field assignments (to set a hledger field) @@ -539,11 +545,11 @@ CSV RULES MATCHER3,VALUE31,VALUE32,...,VALUE3n - Conditional tables ("if tables") are a different syntax to specify - field assignments that will be applied only to CSV records which match + Conditional tables ("if tables") are a different syntax to specify + field assignments that will be applied only to CSV records which match certain patterns. - MATCHER could be either field or record matcher, as described above. + MATCHER could be either field or record matcher, as described above. When MATCHER matches, values from that row would be assigned to the CSV fields named on the if line, in the same order. @@ -567,17 +573,17 @@ CSV RULES ... CSVFIELDNAMEn VALUE3n - Each line starting with MATCHER should contain enough (possibly empty) + Each line starting with MATCHER should contain enough (possibly empty) values for all the listed fields. - Rules would be checked and applied in the order they are listed in the + Rules would be checked and applied in the order they are listed in the table and, like with if blocks, later rules (in the same or another ta- ble) or if blocks could override the effect of any rule. - Instead of ',' you can use a variety of other non-alphanumeric charac- + Instead of ',' you can use a variety of other non-alphanumeric charac- ters as a separator. First character after if is taken to be the sepa- - rator for the rest of the table. It is the responsibility of the user - to ensure that separator does not occur inside MATCHERs and values - + rator for the rest of the table. It is the responsibility of the user + to ensure that separator does not occur inside MATCHERs and values - there is no way to escape separator. Example: @@ -588,7 +594,7 @@ CSV RULES 2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out end - This rule can be used inside if blocks (only), to make hledger stop + This rule can be used inside if blocks (only), to make hledger stop reading this CSV file and move on to the next input file, or to command execution. Eg: @@ -599,10 +605,10 @@ CSV RULES date-format date-format DATEFMT - This is a helper for the date (and date2) fields. If your CSV dates - are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll - need to add a date-format rule describing them with a strptime date - parsing pattern, which must parse the CSV date value completely. Some + This is a helper for the date (and date2) fields. If your CSV dates + are not formatted like YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll + need to add a date-format rule describing them with a strptime date + parsing pattern, which must parse the CSV date value completely. Some examples: # MM/DD/YY @@ -624,15 +630,15 @@ CSV RULES mat.html#v:formatTime newest-first - hledger always sorts the generated transactions by date. Transactions - on the same date should appear in the same order as their CSV records, - as hledger can usually auto-detect whether the CSV's normal order is + hledger always sorts the generated transactions by date. Transactions + on the same date should appear in the same order as their CSV records, + as hledger can usually auto-detect whether the CSV's normal order is oldest first or newest first. But if all of the following are true: - o the CSV might sometimes contain just one day of data (all records + o the CSV might sometimes contain just one day of data (all records having the same date) - o the CSV records are normally in reverse chronological order (newest + o the CSV records are normally in reverse chronological order (newest at the top) o and you care about preserving the order of same-day transactions @@ -645,9 +651,9 @@ CSV RULES include include RULESFILE - This includes the contents of another CSV rules file at this point. - RULESFILE is an absolute file path or a path relative to the current - file's directory. This can be useful for sharing common rules between + This includes the contents of another CSV rules file at this point. + RULESFILE is an absolute file path or a path relative to the current + file's directory. This can be useful for sharing common rules between several rules files, eg: # someaccount.csv.rules @@ -662,10 +668,10 @@ CSV RULES balance-type Balance assertions generated by assigning to balanceN are of the simple - = type by default, which is a single-commodity, subaccount-excluding + = type by default, which is a single-commodity, subaccount-excluding assertion. You may find the subaccount-including variants more useful, - eg if you have created some virtual subaccounts of checking to help - with budgeting. You can select a different type of assertion with the + eg if you have created some virtual subaccounts of checking to help + with budgeting. You can select a different type of assertion with the balance-type rule: # balance assertions will consider all commodities and all subaccounts @@ -680,19 +686,19 @@ CSV RULES TIPS Rapid feedback - It's a good idea to get rapid feedback while creating/troubleshooting + It's a good idea to get rapid feedback while creating/troubleshooting CSV rules. Here's a good way, using entr from http://eradman.com/entr- project : $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC' - A desc: query (eg) is used to select just one, or a few, transactions - of interest. "bash -c" is used to run multiple commands, so we can - echo a separator each time the command re-runs, making it easier to + A desc: query (eg) is used to select just one, or a few, transactions + of interest. "bash -c" is used to run multiple commands, so we can + echo a separator each time the command re-runs, making it easier to read the output. Valid CSV - hledger accepts CSV conforming to RFC 4180. When CSV values are en- + hledger accepts CSV conforming to RFC 4180. When CSV values are en- closed in quotes, note: o they must be double quotes (not single quotes) @@ -700,9 +706,9 @@ TIPS o spaces outside the quotes are not allowed File Extension - CSV ("Character Separated Values") files should be named with one of - these filename extensions: .csv, .ssv, .tsv. Or, the file path should - be prefixed with one of csv:, ssv:, tsv:. This helps hledger identify + CSV ("Character Separated Values") files should be named with one of + these filename extensions: .csv, .ssv, .tsv. Or, the file path should + be prefixed with one of csv:, ssv:, tsv:. This helps hledger identify the format and show the right error messages. For example: $ hledger -f foo.ssv print @@ -714,44 +720,44 @@ TIPS More about this: Input files in the hledger manual. Reading multiple CSV files - If you use multiple -f options to read multiple CSV files at once, - hledger will look for a correspondingly-named rules file for each CSV - file. But if you use the --rules-file option, that rules file will be + If you use multiple -f options to read multiple CSV files at once, + hledger will look for a correspondingly-named rules file for each CSV + file. But if you use the --rules-file option, that rules file will be used for all the CSV files. Valid transactions After reading a CSV file, hledger post-processes and validates the gen- erated journal entries as it would for a journal file - balancing them, - applying balance assignments, and canonicalising amount styles. Any - errors at this stage will be reported in the usual way, displaying the + applying balance assignments, and canonicalising amount styles. Any + errors at this stage will be reported in the usual way, displaying the problem entry. There is one exception: balance assertions, if you have generated them, - will not be checked, since normally these will work only when the CSV - data is part of the main journal. If you do need to check balance as- + will not be checked, since normally these will work only when the CSV + data is part of the main journal. If you do need to check balance as- sertions generated from CSV right away, pipe into another hledger: $ hledger -f file.csv print | hledger -f- print Deduplicating, importing - When you download a CSV file periodically, eg to get your latest bank - transactions, the new file may overlap with the old one, containing + When you download a CSV file periodically, eg to get your latest bank + transactions, the new file may overlap with the old one, containing some of the same records. The import command will (a) detect the new transactions, and (b) append just those transactions to your main journal. It is idempotent, so you - don't have to remember how many times you ran it or with which version - of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This + don't have to remember how many times you ran it or with which version + of the CSV. (It keeps state in a hidden .latest.FILE.csv file.) This is the easiest way to import CSV data. Eg: # download the latest CSV files, then run this command. # Note, no -f flags needed here. $ hledger import *.csv [--dry] - This method works for most CSV files. (Where records have a stable + This method works for most CSV files. (Where records have a stable chronological order, and new records appear only at the new end.) - A number of other tools and workflows, hledger-specific and otherwise, + A number of other tools and workflows, hledger-specific and otherwise, exist for converting, deduplicating, classifying and managing CSV data. See: @@ -762,43 +768,43 @@ TIPS Setting amounts A posting amount can be set in one of these ways: - o by assigning (with a fields list or field assignment) to amountN + o by assigning (with a fields list or field assignment) to amountN (posting N's amount) or amount (posting 1's amount) - o by assigning to amountN-in and amountN-out (or amount-in and amount- - out). For each CSV record, whichever of these has a non-zero value - will be used, with appropriate sign. If both contain a non-zero + o by assigning to amountN-in and amountN-out (or amount-in and amount- + out). For each CSV record, whichever of these has a non-zero value + will be used, with appropriate sign. If both contain a non-zero value, this may not work. - o by assigning to balanceN (or balance) instead of the above, setting - the amount indirectly via a balance assignment. If you do this the + o by assigning to balanceN (or balance) instead of the above, setting + the amount indirectly via a balance assignment. If you do this the default account name may be wrong, so you should set that explicitly. There is some special handling for an amount's sign: - o If an amount value is parenthesised, it will be de-parenthesised and + o If an amount value is parenthesised, it will be de-parenthesised and sign-flipped. - o If an amount value begins with a double minus sign, those cancel out + o If an amount value begins with a double minus sign, those cancel out and are removed. o If an amount value begins with a plus sign, that will be removed Setting currency/commodity - If the currency/commodity symbol is included in the CSV's amount + If the currency/commodity symbol is included in the CSV's amount field(s), you don't have to do anything special. If the currency is provided as a separate CSV field, you can either: - o assign that to currency, which adds it to all posting amounts. The - symbol will prepended to the amount quantity (on the left side). If - you write a trailing space after the symbol, there will be a space - between symbol and amount (an exception to the usual whitespace + o assign that to currency, which adds it to all posting amounts. The + symbol will prepended to the amount quantity (on the left side). If + you write a trailing space after the symbol, there will be a space + between symbol and amount (an exception to the usual whitespace stripping). o or assign it to currencyN which adds it to posting N's amount only. - o or for more control, construct the amount from symbol and quantity + o or for more control, construct the amount from symbol and quantity using field assignment, eg: fields date,description,currency,quantity @@ -806,9 +812,9 @@ TIPS amount %quantity %currency Referencing other fields - In field assignments, you can interpolate only CSV fields, not hledger - fields. In the example below, there's both a CSV field and a hledger - field named amount1, but %amount1 always means the CSV field, not the + In field assignments, you can interpolate only CSV fields, not hledger + fields. In the example below, there's both a CSV field and a hledger + field named amount1, but %amount1 always means the CSV field, not the hledger field: # Name the third CSV field "amount1" @@ -820,7 +826,7 @@ TIPS # Set comment to the CSV amount1 (not the amount1 assigned above) comment %amount1 - Here, since there's no CSV amount1 field, %amount1 will produce a lit- + Here, since there's no CSV amount1 field, %amount1 will produce a lit- eral "amount1": fields date,description,csvamount @@ -828,7 +834,7 @@ TIPS # Can't interpolate amount1 here comment %amount1 - When there are multiple field assignments to the same hledger field, + When there are multiple field assignments to the same hledger field, only the last one takes effect. Here, comment's value will be be B, or C if "something" is matched, but never A: @@ -838,14 +844,14 @@ TIPS comment C How CSV rules are evaluated - Here's how to think of CSV rules being evaluated (if you really need + Here's how to think of CSV rules being evaluated (if you really need to). First, - o include - all includes are inlined, from top to bottom, depth first. - (At each include point the file is inlined and scanned for further + o include - all includes are inlined, from top to bottom, depth first. + (At each include point the file is inlined and scanned for further includes, recursively, before proceeding.) - Then "global" rules are evaluated, top to bottom. If a rule is re- + Then "global" rules are evaluated, top to bottom. If a rule is re- peated, the last one wins: o skip (at top level) @@ -859,30 +865,30 @@ TIPS Then for each CSV record in turn: - o test all if blocks. If any of them contain a end rule, skip all re- - maining CSV records. Otherwise if any of them contain a skip rule, - skip that many CSV records. If there are multiple matched skip + o test all if blocks. If any of them contain a end rule, skip all re- + maining CSV records. Otherwise if any of them contain a skip rule, + skip that many CSV records. If there are multiple matched skip rules, the first one wins. - o collect all field assignments at top level and in matched if blocks. - When there are multiple assignments for a field, keep only the last + o collect all field assignments at top level and in matched if blocks. + When there are multiple assignments for a field, keep only the last one. - o compute a value for each hledger field - either the one that was as- + o compute a value for each hledger field - either the one that was as- signed to it (and interpolate the %CSVFIELDNAME references), or a de- fault o generate a synthetic hledger transaction from these values. - This is all part of the CSV reader, one of several readers hledger can - use to parse input files. When all files have been read successfully, - the transactions are passed as input to whichever hledger command the + This is all part of the CSV reader, one of several readers hledger can + use to parse input files. When all files have been read successfully, + the transactions are passed as input to whichever hledger command the user specified. REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -896,7 +902,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1) diff --git a/hledger/hledger.1 b/hledger/hledger.1 index 1899bfc46..466cbff45 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -3429,6 +3429,64 @@ Here\[aq]s one way to resolve that: assets:checking \f[R] .fi +.SS codes +.PP +codes +.PD 0 +.P +.PD +List the codes seen in transactions, in the order parsed. +.PP +This command prints the value of each transaction\[aq]s code field, in +the order transactions were parsed. +The transaction code is an optional value written in parentheses between +the date and description, often used to store a cheque number, order +number or similar. +.PP +Transactions aren\[aq]t required to have a code, and missing or empty +codes will not be shown by default. +With the \f[C]-E\f[R]/\f[C]--empty\f[R] flag, they will be printed as +blank lines. +.PP +You can add a query to select a subset of transactions. +.PP +Examples: +.IP +.nf +\f[C] +1/1 (123) + (a) 1 + +1/1 () + (a) 1 + +1/1 + (a) 1 + +1/1 (126) + (a) 1 +\f[R] +.fi +.IP +.nf +\f[C] +$ hledger codes +123 +124 +126 +\f[R] +.fi +.IP +.nf +\f[C] +$ hledger codes -E +123 +124 + + +126 +\f[R] +.fi .SS commodities .PP commodities @@ -3438,11 +3496,17 @@ commodities List all commodity/currency symbols used or declared in the journal. .SS descriptions .PP -descriptions Show descriptions. +descriptions +.PD 0 +.P +.PD +List the unique descriptions that appear in transactions. .PP -This command lists all descriptions that appear in transactions. +This command lists the unique descriptions that appear in transactions, +in alphabetic order. +You can add a query to select a subset of transactions. .PP -Examples: +Example: .IP .nf \f[C] @@ -3652,11 +3716,19 @@ options The output formats supported are \f[C]txt\f[R], \f[C]csv\f[R], \f[C]html\f[R], and (experimental) \f[C]json\f[R]. .SS notes .PP -notes Show notes. +notes +.PD 0 +.P +.PD +List the unique notes that appear in transactions. .PP -This command lists all notes that appear in transactions. +This command lists the unique notes that appear in transactions, in +alphabetic order. +You can add a query to select a subset of transactions. +The note is the part of the transaction description after a | character +(or if there is no |, the whole description). .PP -Examples: +Example: .IP .nf \f[C] @@ -3667,11 +3739,19 @@ Snacks .fi .SS payees .PP -payees Show payee names. +payees +.PD 0 +.P +.PD +List the unique payee/payer names that appear in transactions. .PP -This command lists all payee names that appear in transactions. +This command lists the unique payee/payer names that appear in +transactions, in alphabetic order. +You can add a query to select a subset of transactions. +The payee/payer is the part of the transaction description before a | +character (or if there is no |, the whole description). .PP -Examples: +Example: .IP .nf \f[C] diff --git a/hledger/hledger.info b/hledger/hledger.info index 3a3c3fa86..3fcbb1d8a 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -1903,6 +1903,7 @@ detailed command help. * check-dates:: * check-dupes:: * close:: +* codes:: * commodities:: * descriptions:: * diff:: @@ -2776,7 +2777,7 @@ the default journal file, or another specified as an argument. An example: http://stefanorodighiero.net/software/hledger-dupes.html  -File: hledger.info, Node: close, Next: commodities, Prev: check-dupes, Up: COMMANDS +File: hledger.info, Node: close, Next: codes, Prev: check-dupes, Up: COMMANDS 3.10 close ========== @@ -2887,9 +2888,55 @@ breaking balance assertions: assets:checking  -File: hledger.info, Node: commodities, Next: descriptions, Prev: close, Up: COMMANDS +File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: COMMANDS -3.11 commodities +3.11 codes +========== + +codes +List the codes seen in transactions, in the order parsed. + + This command prints the value of each transaction's code field, in +the order transactions were parsed. The transaction code is an optional +value written in parentheses between the date and description, often +used to store a cheque number, order number or similar. + + Transactions aren't required to have a code, and missing or empty +codes will not be shown by default. With the '-E'/'--empty' flag, they +will be printed as blank lines. + + You can add a query to select a subset of transactions. + + Examples: + +1/1 (123) + (a) 1 + +1/1 () + (a) 1 + +1/1 + (a) 1 + +1/1 (126) + (a) 1 + +$ hledger codes +123 +124 +126 + +$ hledger codes -E +123 +124 + + +126 + + +File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: COMMANDS + +3.12 commodities ================ commodities @@ -2898,14 +2945,17 @@ List all commodity/currency symbols used or declared in the journal.  File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: COMMANDS -3.12 descriptions +3.13 descriptions ================= -descriptions Show descriptions. +descriptions +List the unique descriptions that appear in transactions. - This command lists all descriptions that appear in transactions. + This command lists the unique descriptions that appear in +transactions, in alphabetic order. You can add a query to select a +subset of transactions. - Examples: + Example: $ hledger descriptions Store Name @@ -2915,7 +2965,7 @@ Person A  File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: COMMANDS -3.13 diff +3.14 diff ========= diff @@ -2950,7 +3000,7 @@ These transactions are in the second file only:  File: hledger.info, Node: files, Next: help, Prev: diff, Up: COMMANDS -3.14 files +3.15 files ========== files @@ -2960,7 +3010,7 @@ file names matching the regular expression (case sensitive) are shown.  File: hledger.info, Node: help, Next: import, Prev: files, Up: COMMANDS -3.15 help +3.16 help ========= help @@ -3000,7 +3050,7 @@ DESCRIPTION  File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: COMMANDS -3.16 import +3.17 import =========== import @@ -3029,7 +3079,7 @@ $ hledger import --dry ... | hledger -f- print unknown --ignore-assertions  File: hledger.info, Node: Importing balance assignments, Up: import -3.16.1 Importing balance assignments +3.17.1 Importing balance assignments ------------------------------------ Entries added by import will have their posting amounts made explicit @@ -3048,7 +3098,7 @@ please test it and send a pull request.)  File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: COMMANDS -3.17 incomestatement +3.18 incomestatement ==================== incomestatement, is @@ -3097,14 +3147,18 @@ options The output formats supported are 'txt', 'csv', 'html', and  File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: COMMANDS -3.18 notes +3.19 notes ========== -notes Show notes. +notes +List the unique notes that appear in transactions. - This command lists all notes that appear in transactions. + This command lists the unique notes that appear in transactions, in +alphabetic order. You can add a query to select a subset of +transactions. The note is the part of the transaction description after +a | character (or if there is no |, the whole description). - Examples: + Example: $ hledger notes Petrol @@ -3113,14 +3167,19 @@ Snacks  File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: COMMANDS -3.19 payees +3.20 payees =========== -payees Show payee names. +payees +List the unique payee/payer names that appear in transactions. - This command lists all payee names that appear in transactions. + This command lists the unique payee/payer names that appear in +transactions, in alphabetic order. You can add a query to select a +subset of transactions. The payee/payer is the part of the transaction +description before a | character (or if there is no |, the whole +description). - Examples: + Example: $ hledger payees Store Name @@ -3130,7 +3189,7 @@ Person A  File: hledger.info, Node: prices, Next: print, Prev: payees, Up: COMMANDS -3.20 prices +3.21 prices =========== prices @@ -3143,7 +3202,7 @@ Price amounts are always displayed with their full precision.  File: hledger.info, Node: print, Next: print-unique, Prev: prices, Up: COMMANDS -3.21 print +3.22 print ========== print, txns, p @@ -3252,7 +3311,7 @@ $ hledger print -Ocsv  File: hledger.info, Node: print-unique, Next: register, Prev: print, Up: COMMANDS -3.22 print-unique +3.23 print-unique ================= print-unique @@ -3273,7 +3332,7 @@ $ LEDGER_FILE=unique.journal hledger print-unique  File: hledger.info, Node: register, Next: register-match, Prev: print-unique, Up: COMMANDS -3.23 register +3.24 register ============= register, reg, r @@ -3363,7 +3422,7 @@ length and comparable to the others in the report.  File: hledger.info, Node: Custom register output, Up: register -3.23.1 Custom register output +3.24.1 Custom register output ----------------------------- register uses the full terminal width by default, except on windows. @@ -3395,7 +3454,7 @@ options The output formats supported are 'txt', 'csv', and  File: hledger.info, Node: register-match, Next: rewrite, Prev: register, Up: COMMANDS -3.24 register-match +3.25 register-match =================== register-match @@ -3408,7 +3467,7 @@ ledger-autosync detect already-seen transactions when importing.  File: hledger.info, Node: rewrite, Next: roi, Prev: register-match, Up: COMMANDS -3.25 rewrite +3.26 rewrite ============ rewrite @@ -3460,7 +3519,7 @@ commodity.  File: hledger.info, Node: Re-write rules in a file, Up: rewrite -3.25.1 Re-write rules in a file +3.26.1 Re-write rules in a file ------------------------------- During the run this tool will execute so called "Automated Transactions" @@ -3503,7 +3562,7 @@ postings.  File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Up: Re-write rules in a file -3.25.1.1 Diff output format +3.26.1.1 Diff output format ........................... To use this tool for batch modification of your journal files you may @@ -3544,7 +3603,7 @@ output from 'hledger print'.  File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: Re-write rules in a file -3.25.1.2 rewrite vs. print -auto +3.26.1.2 rewrite vs. print -auto ................................ This command predates print -auto, and currently does much the same @@ -3564,7 +3623,7 @@ thing, but with these differences:  File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: COMMANDS -3.26 roi +3.27 roi ======== roi @@ -3592,7 +3651,7 @@ regardless of the length of reporting interval.  File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: COMMANDS -3.27 stats +3.28 stats ========== stats @@ -3623,7 +3682,7 @@ selection.  File: hledger.info, Node: tags, Next: test, Prev: stats, Up: COMMANDS -3.28 tags +3.29 tags ========= tags @@ -3636,7 +3695,7 @@ instead.  File: hledger.info, Node: test, Next: Add-on commands, Prev: tags, Up: COMMANDS -3.29 test +3.30 test ========= test @@ -3663,7 +3722,7 @@ $ hledger test -- -pData.Amount --color=never  File: hledger.info, Node: Add-on commands, Prev: test, Up: COMMANDS -3.30 Add-on commands +3.31 Add-on commands ==================== hledger also searches for external add-on commands, and will include @@ -3704,7 +3763,7 @@ interfaces. These are maintained and released along with hledger:  File: hledger.info, Node: ui, Next: web, Up: Add-on commands -3.30.1 ui +3.31.1 ui --------- hledger-ui provides an efficient terminal interface. @@ -3712,7 +3771,7 @@ hledger-ui provides an efficient terminal interface.  File: hledger.info, Node: web, Next: iadd, Prev: ui, Up: Add-on commands -3.30.2 web +3.31.2 web ---------- hledger-web provides a simple web interface. @@ -3722,7 +3781,7 @@ hledger-web provides a simple web interface.  File: hledger.info, Node: iadd, Next: interest, Prev: web, Up: Add-on commands -3.30.3 iadd +3.31.3 iadd ----------- hledger-iadd is a more interactive, terminal UI replacement for the add @@ -3731,7 +3790,7 @@ command.  File: hledger.info, Node: interest, Prev: iadd, Up: Add-on commands -3.30.4 interest +3.31.4 interest --------------- hledger-interest generates interest transactions for an account @@ -3968,113 +4027,115 @@ Node: Effect of valuation on reports58740 Ref: #effect-of-valuation-on-reports58928 Node: COMMANDS64449 Ref: #commands64557 -Node: accounts65641 -Ref: #accounts65739 -Node: activity66438 -Ref: #activity66548 -Node: add66931 -Ref: #add67030 -Node: balance69823 -Ref: #balance69934 -Node: Classic balance report71392 -Ref: #classic-balance-report71565 -Node: Customising the classic balance report72999 -Ref: #customising-the-classic-balance-report73227 -Node: Colour support75303 -Ref: #colour-support75470 -Node: Flat mode75643 -Ref: #flat-mode75791 -Node: Depth limited balance reports76204 -Ref: #depth-limited-balance-reports76389 -Node: Percentages76845 -Ref: #percentages77011 -Node: Multicolumn balance report78148 -Ref: #multicolumn-balance-report78328 -Node: Budget report84066 -Ref: #budget-report84209 -Node: Nested budgets89475 -Ref: #nested-budgets89587 -Ref: #output-format-193068 -Node: balancesheet93265 -Ref: #balancesheet93401 -Node: balancesheetequity94867 -Ref: #balancesheetequity95016 -Node: cashflow95739 -Ref: #cashflow95867 -Node: check-dates97046 -Ref: #check-dates97173 -Node: check-dupes97452 -Ref: #check-dupes97576 -Node: close97869 -Ref: #close97983 -Node: close usage99505 -Ref: #close-usage99598 -Node: commodities102411 -Ref: #commodities102538 -Node: descriptions102620 -Ref: #descriptions102748 -Node: diff102929 -Ref: #diff103035 -Node: files104082 -Ref: #files104182 -Node: help104329 -Ref: #help104429 -Node: import105510 -Ref: #import105624 -Node: Importing balance assignments106517 -Ref: #importing-balance-assignments106665 -Node: incomestatement107314 -Ref: #incomestatement107447 -Node: notes108934 -Ref: #notes109047 -Node: payees109173 -Ref: #payees109279 -Node: prices109437 -Ref: #prices109543 -Node: print109884 -Ref: #print109994 -Node: print-unique114790 -Ref: #print-unique114916 -Node: register115201 -Ref: #register115328 -Node: Custom register output119500 -Ref: #custom-register-output119629 -Node: register-match120966 -Ref: #register-match121100 -Node: rewrite121451 -Ref: #rewrite121566 -Node: Re-write rules in a file123421 -Ref: #re-write-rules-in-a-file123555 -Node: Diff output format124765 -Ref: #diff-output-format124934 -Node: rewrite vs print --auto126026 -Ref: #rewrite-vs.-print---auto126205 -Node: roi126761 -Ref: #roi126859 -Node: stats127871 -Ref: #stats127970 -Node: tags128758 -Ref: #tags128856 -Node: test129150 -Ref: #test129258 -Node: Add-on commands130005 -Ref: #add-on-commands130122 -Node: ui131465 -Ref: #ui131553 -Node: web131607 -Ref: #web131710 -Node: iadd131826 -Ref: #iadd131937 -Node: interest132019 -Ref: #interest132126 -Node: ENVIRONMENT132366 -Ref: #environment132478 -Node: FILES133307 -Ref: #files-1133410 -Node: LIMITATIONS133623 -Ref: #limitations133742 -Node: TROUBLESHOOTING134484 -Ref: #troubleshooting134597 +Node: accounts65651 +Ref: #accounts65749 +Node: activity66448 +Ref: #activity66558 +Node: add66941 +Ref: #add67040 +Node: balance69833 +Ref: #balance69944 +Node: Classic balance report71402 +Ref: #classic-balance-report71575 +Node: Customising the classic balance report73009 +Ref: #customising-the-classic-balance-report73237 +Node: Colour support75313 +Ref: #colour-support75480 +Node: Flat mode75653 +Ref: #flat-mode75801 +Node: Depth limited balance reports76214 +Ref: #depth-limited-balance-reports76399 +Node: Percentages76855 +Ref: #percentages77021 +Node: Multicolumn balance report78158 +Ref: #multicolumn-balance-report78338 +Node: Budget report84076 +Ref: #budget-report84219 +Node: Nested budgets89485 +Ref: #nested-budgets89597 +Ref: #output-format-193078 +Node: balancesheet93275 +Ref: #balancesheet93411 +Node: balancesheetequity94877 +Ref: #balancesheetequity95026 +Node: cashflow95749 +Ref: #cashflow95877 +Node: check-dates97056 +Ref: #check-dates97183 +Node: check-dupes97462 +Ref: #check-dupes97586 +Node: close97879 +Ref: #close97987 +Node: close usage99509 +Ref: #close-usage99602 +Node: codes102415 +Ref: #codes102523 +Node: commodities103235 +Ref: #commodities103362 +Node: descriptions103444 +Ref: #descriptions103572 +Node: diff103876 +Ref: #diff103982 +Node: files105029 +Ref: #files105129 +Node: help105276 +Ref: #help105376 +Node: import106457 +Ref: #import106571 +Node: Importing balance assignments107464 +Ref: #importing-balance-assignments107612 +Node: incomestatement108261 +Ref: #incomestatement108394 +Node: notes109881 +Ref: #notes109994 +Node: payees110362 +Ref: #payees110468 +Node: prices110888 +Ref: #prices110994 +Node: print111335 +Ref: #print111445 +Node: print-unique116241 +Ref: #print-unique116367 +Node: register116652 +Ref: #register116779 +Node: Custom register output120951 +Ref: #custom-register-output121080 +Node: register-match122417 +Ref: #register-match122551 +Node: rewrite122902 +Ref: #rewrite123017 +Node: Re-write rules in a file124872 +Ref: #re-write-rules-in-a-file125006 +Node: Diff output format126216 +Ref: #diff-output-format126385 +Node: rewrite vs print --auto127477 +Ref: #rewrite-vs.-print---auto127656 +Node: roi128212 +Ref: #roi128310 +Node: stats129322 +Ref: #stats129421 +Node: tags130209 +Ref: #tags130307 +Node: test130601 +Ref: #test130709 +Node: Add-on commands131456 +Ref: #add-on-commands131573 +Node: ui132916 +Ref: #ui133004 +Node: web133058 +Ref: #web133161 +Node: iadd133277 +Ref: #iadd133388 +Node: interest133470 +Ref: #interest133577 +Node: ENVIRONMENT133817 +Ref: #environment133929 +Node: FILES134758 +Ref: #files-1134861 +Node: LIMITATIONS135074 +Ref: #limitations135193 +Node: TROUBLESHOOTING135935 +Ref: #troubleshooting136048  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index b8c44e87d..7e6415f7d 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -2479,16 +2479,60 @@ COMMANDS liabilities:pending 5 = 0 assets:checking + codes + codes + List the codes seen in transactions, in the order parsed. + + This command prints the value of each transaction's code field, in the + order transactions were parsed. The transaction code is an optional + value written in parentheses between the date and description, often + used to store a cheque number, order number or similar. + + Transactions aren't required to have a code, and missing or empty codes + will not be shown by default. With the -E/--empty flag, they will be + printed as blank lines. + + You can add a query to select a subset of transactions. + + Examples: + + 1/1 (123) + (a) 1 + + 1/1 () + (a) 1 + + 1/1 + (a) 1 + + 1/1 (126) + (a) 1 + + $ hledger codes + 123 + 124 + 126 + + $ hledger codes -E + 123 + 124 + + + 126 + commodities commodities List all commodity/currency symbols used or declared in the journal. descriptions - descriptions Show descriptions. + descriptions + List the unique descriptions that appear in transactions. - This command lists all descriptions that appear in transactions. + This command lists the unique descriptions that appear in transactions, + in alphabetic order. You can add a query to select a subset of trans- + actions. - Examples: + Example: $ hledger descriptions Store Name @@ -2497,18 +2541,18 @@ COMMANDS diff diff - Compares a particular account's transactions in two input files. It + Compares a particular account's transactions in two input files. It shows any transactions to this account which are in one file but not in the other. More precisely, for each posting affecting this account in either file, - it looks for a corresponding posting in the other file which posts the - same amount to the same account (ignoring date, description, etc.) + it looks for a corresponding posting in the other file which posts the + same amount to the same account (ignoring date, description, etc.) Since postings not transactions are compared, this also works when mul- tiple bank transactions have been combined into a single journal entry. This is useful eg if you have downloaded an account's transactions from - your bank (eg as CSV data). When hledger and your bank disagree about + your bank (eg as CSV data). When hledger and your bank disagree about the account balance, you can compare the bank data with your journal to find out the cause. @@ -2526,20 +2570,20 @@ COMMANDS files files - List all files included in the journal. With a REGEX argument, only + List all files included in the journal. With a REGEX argument, only file names matching the regular expression (case sensitive) are shown. help help Show any of the hledger manuals. - The help command displays any of the main hledger manuals, in one of - several ways. Run it with no argument to list the manuals, or provide + The help command displays any of the main hledger manuals, in one of + several ways. Run it with no argument to list the manuals, or provide a full or partial manual name to select one. - hledger manuals are available in several formats. hledger help will - use the first of these display methods that it finds: info, man, - $PAGER, less, stdout (or when non-interactive, just stdout). You can + hledger manuals are available in several formats. hledger help will + use the first of these display methods that it finds: info, man, + $PAGER, less, stdout (or when non-interactive, just stdout). You can force a particular viewer with the --info, --man, --pager, --cat flags. Examples: @@ -2566,9 +2610,9 @@ COMMANDS import import - Read new transactions added to each FILE since last run, and add them - to the main journal file. Or with --dry-run, just print the transac- - tions that would be added. Or with --catchup, just mark all of the + Read new transactions added to each FILE since last run, and add them + to the main journal file. Or with --dry-run, just print the transac- + tions that would be added. Or with --catchup, just mark all of the FILEs' transactions as imported, without actually importing any. The input files are specified as arguments - no need to write -f before @@ -2579,36 +2623,36 @@ 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 + 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 Importing balance assignments - Entries added by import will have their posting amounts made explicit - (like hledger print -x). This means that any balance assignments in - imported files must be evaluated; but, imported files don't get to see - the main file's account balances. As a result, importing entries with + Entries added by import will have their posting amounts made explicit + (like hledger print -x). This means that any balance assignments in + imported files must be evaluated; but, imported files don't get to see + the main file's account balances. As a result, importing entries with balance assignments (eg from an institution that provides only balances - and not posting amounts) will probably generate incorrect posting + and not posting amounts) will probably generate incorrect posting amounts. To avoid this problem, use print instead of import: $ hledger print IMPORTFILE [--new] >> $LEDGER_FILE - (If you think import should leave amounts implicit like print does, + (If you think import should leave amounts implicit like print does, please test it and send a pull request.) incomestatement incomestatement, is - This command displays a simple income statement, showing revenues and - expenses during a period. It assumes that these accounts are under a - top-level revenue or income or expense account (case insensitive, plu- - ral forms also allowed). Note this report shows all account balances - with normal positive sign (like conventional financial statements, un- + This command displays a simple income statement, showing revenues and + expenses during a period. It assumes that these accounts are under a + top-level revenue or income or expense account (case insensitive, plu- + ral forms also allowed). Note this report shows all account balances + with normal positive sign (like conventional financial statements, un- like balance/print/register) (experimental). - 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 @@ -2633,32 +2677,40 @@ 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 mode with --change/--cumulative/--historical. Instead of abso- + 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. Instead of abso- lute values percentages can be displayed with -%. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, html, and (experimen- + tions The output formats supported are txt, csv, html, and (experimen- tal) json. notes - notes Show notes. + notes + List the unique notes that appear in transactions. - This command lists all notes that appear in transactions. + This command lists the unique notes that appear in transactions, in al- + phabetic order. You can add a query to select a subset of transac- + tions. The note is the part of the transaction description after a | + character (or if there is no |, the whole description). - Examples: + Example: $ hledger notes Petrol Snacks payees - payees Show payee names. + payees + List the unique payee/payer names that appear in transactions. - This command lists all payee names that appear in transactions. + This command lists the unique payee/payer names that appear in transac- + tions, in alphabetic order. You can add a query to select a subset of + transactions. The payee/payer is the part of the transaction descrip- + tion before a | character (or if there is no |, the whole description). - Examples: + Example: $ hledger payees Store Name @@ -2667,10 +2719,10 @@ COMMANDS prices prices - Print market price directives from the journal. With --costs, also - print synthetic market prices based on transaction prices. With --in- - verted-costs, also print inverse prices based on transaction prices. - Prices (and postings providing prices) can be filtered by a query. + Print market price directives from the journal. With --costs, also + print synthetic market prices based on transaction prices. With --in- + verted-costs, also print inverse prices based on transaction prices. + Prices (and postings providing prices) can be filtered by a query. Price amounts are always displayed with their full precision. print @@ -2678,11 +2730,11 @@ COMMANDS Show transaction journal entries, sorted by date. The print command displays full journal entries (transactions) from the - journal file in date order, tidily formatted. With --date2, transac- + journal file in date order, tidily formatted. With --date2, transac- tions are sorted by secondary date instead. print's output is always a valid hledger journal. - It preserves all transaction information, but it does not preserve di- + It preserves all transaction information, but it does not preserve di- rectives or inter-transaction comments $ hledger print @@ -2709,43 +2761,43 @@ COMMANDS Normally, the journal entry's explicit or implicit amount style is pre- served. For example, when an amount is omitted in the journal, it will - not appear in the output. Similarly, when a transaction price is im- - plied but not written, it will not appear in the output. You can use - the -x/--explicit flag to make all amounts and transaction prices ex- - plicit, which can be useful for troubleshooting or for making your + not appear in the output. Similarly, when a transaction price is im- + plied but not written, it will not appear in the output. You can use + the -x/--explicit flag to make all amounts and transaction prices ex- + plicit, which can be useful for troubleshooting or for making your journal more readable and robust against data entry errors. -x is also implied by using any of -B,-V,-X,--value. - Note, -x/--explicit will cause postings with a multi-commodity amount - (these can arise when a multi-commodity transaction has an implicit - amount) to be split into multiple single-commodity postings, keeping + Note, -x/--explicit will cause postings with a multi-commodity amount + (these can arise when a multi-commodity transaction has an implicit + amount) to be split into multiple single-commodity postings, keeping the output parseable. - 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. This can be used for troubleshooting. - 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 ig- - noring 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 ig- + noring 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 in- - creasing dates, and that transactions on the same day do not get re- + This assumes that transactions added to FILE always have same or in- + creasing dates, and that transactions on the same day do not get re- ordered. See also the import command. This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, and (experimental) + tions The output formats supported are txt, csv, and (experimental) json and sql. Here's an example of print's CSV output: @@ -2764,20 +2816,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 @@ -2801,7 +2853,7 @@ COMMANDS Show postings and their running total. The register command displays postings in date order, one per line, and - their running total. This is typically used with a query selecting a + their running total. This is typically used with a query selecting a particular account, to see that account's activity: $ hledger register checking @@ -2812,8 +2864,8 @@ COMMANDS With --date2, it shows and sorts by secondary date instead. - 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 @@ -2823,18 +2875,18 @@ 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 ac- + the whole report period). This flag implies --empty (see below). It + is affected by --historical. It works best when showing just one ac- count 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. - The --invert flag negates all amounts. For example, it can be used on + The --invert flag negates all amounts. For example, it can be used on an income account where amounts are normally displayed as negative num- - bers. It's also useful to show postings on the checking account to- + bers. It's also useful to show postings on the checking account to- gether with the related account: $ hledger register --related --invert assets:checking @@ -2846,7 +2898,7 @@ COMMANDS 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 @@ -2863,7 +2915,7 @@ COMMANDS 2008/11 0 $-2 2008/12 0 $-2 - Often, you'll want to see just one line per interval. The --depth op- + Often, you'll want to see just one line per interval. The --depth op- tion helps with this, causing subaccounts to be aggregated: $ hledger register --monthly assets --depth 1h @@ -2871,17 +2923,17 @@ 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 in- - tervals. 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 in- + tervals. 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 + The description and account columns normally share the space equally (about half of (width - 40) each). You can adjust this by adding a de- scription width as part of --width's argument, comma-separated: --width W,D . Here's a diagram (won't display correctly in --help): @@ -2900,27 +2952,27 @@ COMMANDS $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 This command also supports the output destination and output format op- - tions The output formats supported are txt, csv, and (experimental) + tions The output formats supported are txt, csv, and (experimental) json. register-match register-match Print the one posting whose transaction description is closest to DESC, - in the style of the register command. If there are multiple equally - good matches, it shows the most recent. Query options (options, not - arguments) can be used to restrict the search space. Helps ledger-au- + in the style of the register command. If there are multiple equally + good matches, it shows the most recent. Query options (options, not + arguments) can be used to restrict the search space. Helps ledger-au- tosync detect already-seen transactions when importing. rewrite rewrite Print all transactions, rewriting the postings of matched transactions. - For now the only rewrite available is adding new postings, like print + For now the only rewrite available is adding new postings, like print --auto. This is a start at a generic rewriter of transaction entries. It reads - the default journal and prints the transactions, like print, but adds + the default journal and prints the transactions, like print, but adds one or more specified postings to any transactions matching QUERY. The - posting amounts can be fixed, or a multiplier of the existing transac- + posting amounts can be fixed, or a multiplier of the existing transac- tion's first posting amount. Examples: @@ -2936,7 +2988,7 @@ COMMANDS (reserve:grocery) *0.25 ; reserve 25% for grocery (reserve:) *0.25 ; reserve 25% for grocery - Note the single quotes to protect the dollar sign from bash, and the + Note the single quotes to protect the dollar sign from bash, and the two spaces between account and amount. More: @@ -2946,16 +2998,16 @@ COMMANDS $ 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 + Argument for --add-posting option is a usual posting of transaction + with an exception for amount specification. More precisely, you can use '*' (star symbol) before the amount to indicate that that this is a - factor for an amount of original matched posting. If the amount in- + factor for an amount of original matched posting. If the amount in- cludes a commodity name, the new posting amount will be in the new com- - modity; otherwise, it will be in the matched posting amount's commod- + modity; otherwise, it will be in the matched posting amount's commod- ity. Re-write rules in a file - During the run this tool will execute so called "Automated Transac- + During the run this tool will execute so called "Automated Transac- tions" found in any journal it process. I.e instead of specifying this operations in command line you can put them in a journal file. @@ -2970,7 +3022,7 @@ COMMANDS budget:gifts *-1 assets:budget *1 - Note that '=' (equality symbol) that is used instead of date in trans- + Note that '=' (equality symbol) that is used instead of date in trans- actions you usually write. It indicates the query by which you want to match the posting to add new ones. @@ -2983,12 +3035,12 @@ COMMANDS --add-posting 'assets:budget *1' \ > rewritten-tidy-output.journal - It is important to understand that relative order of such entries in - journal is important. You can re-use result of previously added post- + It is important to understand that relative order of such entries in + journal is important. You can re-use result of previously added post- ings. Diff output format - To use this tool for batch modification of your journal files you may + 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' @@ -3012,10 +3064,10 @@ COMMANDS If you'll pass this through patch tool you'll get transactions contain- ing the posting that matches your query be updated. Note that multiple - files might be update according to list of input files specified via + files might be update according to list of input files specified via --file options and include directives inside of these files. - Be careful. Whole transaction being re-formatted in a style of output + Be careful. Whole transaction being re-formatted in a style of output from hledger print. See also: @@ -3023,48 +3075,48 @@ COMMANDS https://github.com/simonmichael/hledger/issues/99 rewrite vs. print --auto - This command predates print --auto, and currently does much the same + This command predates print --auto, and currently does much the same thing, but with these differences: - o with multiple files, rewrite lets rules in any file affect all other - files. print --auto uses standard directive scoping; rules affect + o with multiple files, rewrite lets rules in any file affect all other + files. print --auto uses standard directive scoping; rules affect only child files. - o rewrite's query limits which transactions can be rewritten; all are + o rewrite's query limits which transactions can be rewritten; all are printed. print --auto's query limits which transactions are printed. - o rewrite applies rules specified on command line or in the journal. + o rewrite applies rules specified on command line or in the journal. print --auto applies rules specified in the journal. roi roi - Shows the time-weighted (TWR) and money-weighted (IRR) rate of return + Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on your investments. - This command assumes that you have account(s) that hold nothing but + This command assumes that you have account(s) that hold nothing but your investments and whenever you record current appraisal/valuation of these investments you offset unrealized profit and loss into account(s) that, again, hold nothing but unrealized profit and loss. - Any transactions affecting balance of investment account(s) and not - originating from unrealized profit and loss account(s) are assumed to + Any transactions affecting balance of investment account(s) and not + originating from unrealized profit and loss account(s) are assumed to be your investments or withdrawals. - At a minimum, you need to supply a query (which could be just an ac- + At a minimum, you need to supply a query (which could be just an ac- count name) to select your investments with --inv, and another query to identify your profit and loss transactions with --pnl. - It will compute and display the internalized rate of return (IRR) and - time-weighted rate of return (TWR) for your investments for the time - period requested. Both rates of return are annualized before display, + It will compute and display the internalized rate of return (IRR) and + time-weighted rate of return (TWR) for your investments for the time + period requested. Both rates of return are annualized before display, regardless of the length of reporting interval. stats stats Show some journal statistics. - 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. Example: @@ -3082,14 +3134,14 @@ COMMANDS Commodities : 1 ($) Market prices : 12 ($) - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. tags tags - 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 QUERY arguments, only transactions matching the query are + 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 QUERY arguments, only transactions matching the query are considered. With --values flag, the tags' unique values are listed in- stead. @@ -3097,13 +3149,13 @@ COMMANDS test Run built-in unit tests. - This command runs the unit tests built in to hledger and hledger-lib, - printing the results on stdout. If any test fails, the exit code will + This command runs the unit tests built in to hledger and hledger-lib, + printing the results on stdout. If any test fails, the exit code will be non-zero. - This is mainly used by hledger developers, but you can also use it to - sanity-check the installed hledger executable on your platform. All - tests are expected to pass - if you ever see a failure, please report + This is mainly used by hledger developers, but you can also use it to + sanity-check the installed hledger executable on your platform. All + tests are expected to pass - if you ever see a failure, please report as a bug! This command also accepts tasty test runner options, written after a -- @@ -3112,35 +3164,35 @@ COMMANDS $ hledger test -- -pData.Amount --color=never - For help on these, see https://github.com/feuerbach/tasty#options (-- + For help on these, see https://github.com/feuerbach/tasty#options (-- --help currently doesn't show them). Add-on commands - hledger also searches for external add-on commands, and will include + hledger also searches for external add-on commands, and will include these in the commands list. These are programs or scripts in your PATH - whose name starts with hledger- and ends with a recognised file exten- + whose name starts with hledger- and ends with a recognised file exten- sion (currently: no extension, bat,com,exe, hs,lhs,pl,py,rb,rkt,sh). - Add-ons can be invoked like any hledger command, but there are a few + Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Eg if the hledger-web add-on is installed, - o hledger -h web shows hledger's help, while hledger web -h shows + o hledger -h web shows hledger's help, while hledger web -h shows hledger-web's help. - o Flags specific to the add-on must have a preceding -- to hide them - from hledger. So hledger web --serve --port 9000 will be rejected; + o Flags specific to the add-on must have a preceding -- to hide them + from hledger. So hledger web --serve --port 9000 will be rejected; you must use hledger web -- --serve --port 9000. o You can always run add-ons directly if preferred: hledger-web --serve --port 9000. - Add-ons are a relatively easy way to add local features or experiment - with new ideas. They can be written in any language, but haskell - scripts have a big advantage: they can use the same hledger (and - haskell) library functions that built-in commands do, for command-line + Add-ons are a relatively easy way to add local features or experiment + with new ideas. They can be written in any language, but haskell + scripts have a big advantage: they can use the same hledger (and + haskell) library functions that built-in commands do, for command-line options, journal parsing, reporting, etc. - Two important add-ons are the hledger-ui and hledger-web user inter- + Two important add-ons are the hledger-ui and hledger-web user inter- faces. These are maintained and released along with hledger: ui @@ -3159,23 +3211,23 @@ COMMANDS hledger-interest generates interest transactions for an account accord- ing to various schemes. - A few more experimental or old add-ons can be found in hledger's bin/ + A few more experimental or old add-ons can be found in hledger's bin/ directory. These are typically prototypes and not guaranteed to work. ENVIRONMENT - COLUMNS The screen width used by the register command. Default: the + COLUMNS The screen width used by the register command. Default: the full terminal width. LEDGER_FILE The journal file path when not specified with -f. Default: - ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- + ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). - A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- - trolled finance directory and YYYY is the current year. Or ~/DIR/cur- + A typical value is ~/DIR/YYYY.journal, where DIR is a version-con- + trolled finance directory and YYYY is the current year. Or ~/DIR/cur- rent.journal, where current.journal is a symbolic link to YYYY.journal. On Mac computers, you can set this and other environment variables in a - more thorough way that also affects applications started from the GUI + more thorough way that also affects applications started from the GUI (say, an Emacs dock icon). Eg on MacOS Catalina I have a ~/.MacOSX/en- vironment.plist file containing @@ -3186,13 +3238,13 @@ ENVIRONMENT To see the effect you may need to killall Dock, or reboot. FILES - Reads data from one or more files in hledger journal, timeclock, time- - dot, or CSV format specified with -f, or $LEDGER_FILE, or - $HOME/.hledger.journal (on windows, perhaps + Reads data from one or more files in hledger journal, timeclock, time- + dot, or CSV format specified with -f, or $LEDGER_FILE, or + $HOME/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.journal). LIMITATIONS - The need to precede addon command options with -- when invoked from + The need to precede addon command options with -- when invoked from hledger is awkward. When input data contains non-ascii characters, a suitable system locale @@ -3208,36 +3260,36 @@ LIMITATIONS In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. - Not all of Ledger's journal file syntax is supported. See file format + Not all of Ledger's journal file syntax is supported. See file format differences. - On large data files, hledger is slower and uses more memory than + On large data files, hledger is slower and uses more memory than Ledger. TROUBLESHOOTING - Here are some issues you might encounter when you run hledger (and re- - member you can also seek help from the IRC channel, mail list or bug + Here are some issues you might encounter when you run hledger (and re- + member you can also seek help from the IRC channel, mail list or bug tracker): Successfully installed, but "No command 'hledger' found" stack and cabal install binaries into a special directory, which should - be added to your PATH environment variable. Eg on unix-like systems, + be added to your PATH environment variable. Eg on unix-like systems, that is ~/.local/bin and ~/.cabal/bin respectively. I set a custom LEDGER_FILE, but hledger is still using the default file - LEDGER_FILE should be a real environment variable, not just a shell - variable. The command env | grep LEDGER_FILE should show it. You may + LEDGER_FILE should be a real environment variable, not just a shell + variable. The command env | grep LEDGER_FILE should show it. You may need to use export. Here's an explanation. - Getting errors like "Illegal byte sequence" or "Invalid or incomplete - multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- + Getting errors like "Illegal byte sequence" or "Invalid or incomplete + multibyte or wide character" or "commitAndReleaseBuffer: invalid argu- ment (invalid character)" Programs compiled with GHC (hledger, haskell build tools, etc.) need to have a UTF-8-aware locale configured in the environment, otherwise they - will fail with these kinds of errors when they encounter non-ascii + will fail with these kinds of errors when they encounter non-ascii characters. - To fix it, set the LANG environment variable to some locale which sup- + To fix it, set the LANG environment variable to some locale which sup- ports UTF-8. The locale you choose must be installed on your system. Here's an example of setting LANG temporarily, on Ubuntu GNU/Linux: @@ -3252,8 +3304,8 @@ TROUBLESHOOTING POSIX $ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command - If available, C.UTF-8 will also work. If your preferred locale isn't - listed by locale -a, you might need to install it. Eg on Ubuntu/De- + If available, C.UTF-8 will also work. If your preferred locale isn't + listed by locale -a, you might need to install it. Eg on Ubuntu/De- bian: $ apt-get install language-pack-fr @@ -3273,8 +3325,8 @@ TROUBLESHOOTING $ echo "export LANG=en_US.utf8" >>~/.bash_profile $ bash --login - Exact spelling and capitalisation may be important. Note the differ- - ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow + Exact spelling and capitalisation may be important. Note the differ- + ence on MacOS (UTF-8, not utf8). Some platforms (eg ubuntu) allow variant spellings, but others (eg macos) require it to be exact: $ locale -a | grep -iE en_us.*utf @@ -3284,7 +3336,7 @@ TROUBLESHOOTING REPORTING BUGS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -3298,7 +3350,7 @@ COPYRIGHT SEE ALSO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), + hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1)