This is hledger_csv.5.info, produced by makeinfo version 6.0 from stdin.  File: hledger_csv.5.info, Node: Top, Next: CSV RULES, Up: (dir) hledger_csv(5) hledger 1.4 ************************** hledger can read CSV files, converting each CSV record into a journal entry (transaction), if you provide some conversion hints in a "rules file". This file should be named like the CSV file with an additional '.rules' suffix (eg: 'mybank.csv.rules'); or, you can specify the file with '--rules-file PATH'. hledger will create it if necessary, with some default rules which you'll need to adjust. At minimum, the rules file must specify the 'date' and 'amount' fields. For an example, see Cookbook: convert CSV files. To learn about _exporting_ CSV, see CSV output. * Menu: * CSV RULES:: * CSV TIPS::  File: hledger_csv.5.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top 1 CSV RULES *********** The following seven kinds of rule can appear in the rules file, in any order. Blank lines and lines beginning with '#' or ';' are ignored. * Menu: * skip:: * date-format:: * field list:: * field assignment:: * conditional block:: * include:: * newest-first::  File: hledger_csv.5.info, Node: skip, Next: date-format, Up: CSV RULES 1.1 skip ======== 'skip'_'N'_ Skip this number of CSV records at the beginning. You'll need this whenever your CSV data contains header lines. Eg: # ignore the first CSV line skip 1  File: hledger_csv.5.info, Node: date-format, Next: field list, Prev: skip, Up: CSV RULES 1.2 date-format =============== 'date-format'_'DATEFMT'_ When your CSV date fields are not formatted like 'YYYY/MM/DD' (or 'YYYY-MM-DD' or 'YYYY.MM.DD'), you'll need to specify the format. DATEFMT is a strptime-like date parsing pattern, which must parse the date field values completely. Examples: # for dates like "6/11/2013": date-format %-d/%-m/%Y # for dates like "11/06/2013": date-format %m/%d/%Y # for dates like "2013-Nov-06": date-format %Y-%h-%d # for dates like "11/6/2013 11:32 PM": date-format %-m/%-d/%Y %l:%M %p  File: hledger_csv.5.info, Node: field list, Next: field assignment, Prev: date-format, Up: CSV RULES 1.3 field list ============== 'fields'_'FIELDNAME1'_, _'FIELDNAME2'_... This (a) names the CSV fields, in order (names may not contain whitespace; uninteresting names may be left blank), and (b) assigns them to journal entry fields if you use any of these standard field names: 'date', 'date2', 'status', 'code', 'description', 'comment', 'account1', 'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance'. Eg: # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, # and give the 7th and 8th fields meaningful names for later reference: # # CSV field: # 1 2 3 4 5 6 7 8 # entry field: fields date, description, , amount, , , somefield, anotherfield  File: hledger_csv.5.info, Node: field assignment, Next: conditional block, Prev: field list, Up: CSV RULES 1.4 field assignment ==================== _'ENTRYFIELDNAME'_ _'FIELDVALUE'_ This sets a journal entry field (one of the standard names above) to the given text value, which can include CSV field values interpolated by name ('%CSVFIELDNAME') or 1-based position ('%N'). Eg: # set the amount to the 4th CSV field with "USD " prepended amount USD %4 # combine three fields to make a comment (containing two tags) comment note: %somefield - %anotherfield, date: %1 Field assignments can be used instead of or in addition to a field list.  File: hledger_csv.5.info, Node: conditional block, Next: include, Prev: field assignment, Up: CSV RULES 1.5 conditional block ===================== 'if' _'PATTERN'_ _'FIELDASSIGNMENTS'_... 'if' _'PATTERN'_ _'PATTERN'_... _'FIELDASSIGNMENTS'_... This applies one or more field assignments, only to those CSV records matched by one of the PATTERNs. The patterns are case-insensitive regular expressions which match anywhere within the whole CSV record (it's not yet possible to match within a specific field). When there are multiple patterns they can be written on separate lines, unindented. The field assignments are on separate lines indented by at least one space. Examples: # if the CSV record contains "groceries", set account2 to "expenses:groceries" if groceries account2 expenses:groceries # if the CSV record contains any of these patterns, set account2 and comment as shown if monthly service fee atm transaction fee banking thru software account2 expenses:business:banking comment XXX deductible ? check it  File: hledger_csv.5.info, Node: include, Next: newest-first, Prev: conditional block, Up: CSV RULES 1.6 include =========== 'include'_'RULESFILE'_ Include another rules file at this point. 'RULESFILE' is either an absolute file path or a path relative to the current file's directory. Eg: # rules reused with several CSV files include common.rules  File: hledger_csv.5.info, Node: newest-first, Prev: include, Up: CSV RULES 1.7 newest-first ================ 'newest-first' Consider adding this rule if all of the following are true: you might be processing just one day of data, your CSV records are in reverse chronological order (newest first), and you care about preserving the order of same-day transactions. It usually isn't needed, because hledger autodetects the CSV order, but when all CSV records have the same date it will assume they are oldest first.  File: hledger_csv.5.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top 2 CSV TIPS ********** * Menu: * CSV ordering:: * CSV accounts:: * CSV amounts:: * CSV balance assertions:: * Reading multiple CSV files::  File: hledger_csv.5.info, Node: CSV ordering, Next: CSV accounts, Up: CSV TIPS 2.1 CSV ordering ================ The generated journal entries will be sorted by date. The order of same-day entries will be preserved (except in the special case where you might need 'newest-first', see above).  File: hledger_csv.5.info, Node: CSV accounts, Next: CSV amounts, Prev: CSV ordering, Up: CSV TIPS 2.2 CSV accounts ================ Each journal entry will have two postings, to 'account1' and 'account2' respectively. It's not yet possible to generate entries with more than two postings. It's conventional and recommended to use 'account1' for the account whose CSV we are reading.  File: hledger_csv.5.info, Node: CSV amounts, Next: CSV balance assertions, Prev: CSV accounts, Up: CSV TIPS 2.3 CSV amounts =============== The 'amount' field sets the amount of the 'account1' posting. If the CSV has debit/credit amounts in separate fields, assign to the 'amount-in' and 'amount-out' pseudo fields instead. (Whichever one has a value will be used, with appropriate sign. If both contain a value, it may not work so well.) If an amount value is parenthesised, it will be de-parenthesised and sign-flipped. If an amount value begins with a double minus sign, those will cancel out and be removed. If the CSV has the currency symbol in a separate field, assign that to the 'currency' pseudo field to have it prepended to the amount. Or, you can use a field assignment to 'amount' that interpolates both CSV fields (giving more control, eg to put the currency symbol on the right).  File: hledger_csv.5.info, Node: CSV balance assertions, Next: Reading multiple CSV files, Prev: CSV amounts, Up: CSV TIPS 2.4 CSV balance assertions ========================== If the CSV includes a running balance, you can assign that to the 'balance' pseudo field; whenever the running balance value is non-empty, it will be asserted as the balance after the 'account1' posting.  File: hledger_csv.5.info, Node: Reading multiple CSV files, Prev: CSV balance assertions, Up: CSV TIPS 2.5 Reading multiple CSV files ============================== You can read multiple CSV files at once using multiple '-f' arguments on the command line, and hledger will look for a correspondingly-named rules file for each. Note if you use the '--rules-file' option, this one rules file will be used for all the CSV files being read.  Tag Table: Node: Top74 Node: CSV RULES810 Ref: #csv-rules920 Node: skip1182 Ref: #skip1278 Node: date-format1450 Ref: #date-format1579 Node: field list2085 Ref: #field-list2224 Node: field assignment2929 Ref: #field-assignment3086 Node: conditional block3590 Ref: #conditional-block3746 Node: include4642 Ref: #include4774 Node: newest-first5005 Ref: #newest-first5121 Node: CSV TIPS5532 Ref: #csv-tips5628 Node: CSV ordering5746 Ref: #csv-ordering5866 Node: CSV accounts6047 Ref: #csv-accounts6187 Node: CSV amounts6441 Ref: #csv-amounts6589 Node: CSV balance assertions7364 Ref: #csv-balance-assertions7548 Node: Reading multiple CSV files7753 Ref: #reading-multiple-csv-files7925  End Tag Table