.TH "hledger_csv" "5" "July 2017" "hledger 1.3.99" "hledger User Manuals"



.SH NAME
.PP
CSV \- how hledger reads CSV data, and the CSV rules file format
.SH DESCRIPTION
.PP
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
\f[C]\&.rules\f[] suffix (eg: \f[C]mybank.csv.rules\f[]); or, you can
specify the file with \f[C]\-\-rules\-file\ PATH\f[].
hledger will create it if necessary, with some default rules which
you\[aq]ll need to adjust.
At minimum, the rules file must specify the \f[C]date\f[] and
\f[C]amount\f[] fields.
For an example, see Cookbook: convert CSV files.
.PP
To learn about \f[I]exporting\f[] CSV, see CSV output.
.SH CSV RULES
.PP
The following seven kinds of rule can appear in the rules file, in any
order.
Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are
ignored.
.SS skip
.PP
\f[C]skip\f[]\f[I]\f[C]N\f[]\f[]
.PP
Skip this number of CSV records at the beginning.
You\[aq]ll need this whenever your CSV data contains header lines.
Eg:
.IP
.nf
\f[C]
#\ ignore\ the\ first\ CSV\ line
skip\ 1
\f[]
.fi
.SS date\-format
.PP
\f[C]date\-format\f[]\f[I]\f[C]DATEFMT\f[]\f[]
.PP
When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or
\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to
specify the format.
DATEFMT is a strptime\-like date parsing pattern, which must parse the
date field values completely.
Examples:
.IP
.nf
\f[C]
#\ for\ dates\ like\ "6/11/2013":
date\-format\ %\-d/%\-m/%Y
\f[]
.fi
.IP
.nf
\f[C]
#\ for\ dates\ like\ "11/06/2013":
date\-format\ %m/%d/%Y
\f[]
.fi
.IP
.nf
\f[C]
#\ for\ dates\ like\ "2013\-Nov\-06":
date\-format\ %Y\-%h\-%d
\f[]
.fi
.IP
.nf
\f[C]
#\ for\ dates\ like\ "11/6/2013\ 11:32\ PM":
date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p
\f[]
.fi
.SS field list
.PP
\f[C]fields\f[]\f[I]\f[C]FIELDNAME1\f[]\f[],
\f[I]\f[C]FIELDNAME2\f[]\f[]...
.PP
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:
\f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], \f[C]code\f[],
\f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[],
\f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[],
\f[C]amount\-out\f[], \f[C]currency\f[], \f[C]balance\f[].
Eg:
.IP
.nf
\f[C]
#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\[aq]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
\f[]
.fi
.SS field assignment
.PP
\f[I]\f[C]ENTRYFIELDNAME\f[]\f[] \f[I]\f[C]FIELDVALUE\f[]\f[]
.PP
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 (\f[C]%CSVFIELDNAME\f[]) or 1\-based position (\f[C]%N\f[]).
 Eg:
.IP
.nf
\f[C]
#\ set\ the\ amount\ to\ the\ 4th\ CSV\ field\ with\ "USD\ "\ prepended
amount\ USD\ %4
\f[]
.fi
.IP
.nf
\f[C]
#\ combine\ three\ fields\ to\ make\ a\ comment\ (containing\ two\ tags)
comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1
\f[]
.fi
.PP
Field assignments can be used instead of or in addition to a field list.
.SS conditional block
.PP
\f[C]if\f[] \f[I]\f[C]PATTERN\f[]\f[]
.PD 0
.P
.PD
\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]...
.PP
\f[C]if\f[]
.PD 0
.P
.PD
\f[I]\f[C]PATTERN\f[]\f[]
.PD 0
.P
.PD
\f[I]\f[C]PATTERN\f[]\f[]...
.PD 0
.P
.PD
\ \ \ \ \f[I]\f[C]FIELDASSIGNMENTS\f[]\f[]...
.PP
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\[aq]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:
.IP
.nf
\f[C]
#\ if\ the\ CSV\ record\ contains\ "groceries",\ set\ account2\ to\ "expenses:groceries"
if\ groceries
\ account2\ expenses:groceries
\f[]
.fi
.IP
.nf
\f[C]
#\ 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
\f[]
.fi
.SS include
.PP
\f[C]include\f[]\f[I]\f[C]RULESFILE\f[]\f[]
.PP
Include another rules file at this point.
\f[C]RULESFILE\f[] is either an absolute file path or a path relative to
the current file\[aq]s directory.
Eg:
.IP
.nf
\f[C]
#\ rules\ reused\ with\ several\ CSV\ files
include\ common.rules
\f[]
.fi
.SS newest\-first
.PP
\f[C]newest\-first\f[]
.PP
Consider adding this rule if: your CSV records are in reverse
chronological order (newest first), and you care about preserving the
order of same\-day transactions, and you might be processing just one
day of data.
It usually isn\[aq]t needed, because hledger autodetects the CSV order,
but if all the CSV records have the same date it assumes they are oldest
first.
.SH CSV TIPS
.PP
Each generated journal entry will have two postings, to
\f[C]account1\f[] and \f[C]account2\f[] respectively.
Currently it\[aq]s not possible to generate entries with more than two
postings.
.PP
If the CSV has debit/credit amounts in separate fields, assign to the
\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead of
\f[C]amount\f[].
.PP
If the CSV has the currency in a separate field, assign that to the
\f[C]currency\f[] pseudo field which will be automatically prepended to
the amount.
(Or you can do the same thing with a field assignment.)
.PP
If the CSV includes a running balance, you can assign that to the
\f[C]balance\f[] pseudo field to generate a balance assertion on
\f[C]account1\f[] whenever the balance field is non\-empty.
(Eg to double\-check your bank\[aq]s balance calculation.)
.PP
If an amount value is parenthesised, it will be de\-parenthesised and
sign\-flipped automatically.
.PP
The generated journal entries will be sorted by date.
The original order of same\-day entries will be preserved, usually.


.SH "REPORTING BUGS"
Report bugs at http://bugs.hledger.org
(or on the #hledger IRC channel or hledger mail list)

.SH AUTHORS
Simon Michael <simon@joyful.com> and contributors

.SH COPYRIGHT

Copyright (C) 2007-2016 Simon Michael.
.br
Released under GNU GPL v3 or later.

.SH SEE ALSO
hledger(1), hledger\-ui(1), hledger\-web(1), hledger\-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_timedot(5),
ledger(1)

http://hledger.org