diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 index cf9b7c549..8c8d066d7 100644 --- a/hledger-lib/hledger_csv.5 +++ b/hledger-lib/hledger_csv.5 @@ -9,9 +9,9 @@ CSV - how hledger reads CSV data, and the CSV rules file format .SH DESCRIPTION .PP -hledger can read CSV (comma-separated value, or character-separated -value) files as if they were journal files, automatically converting -each CSV record into a transaction. +hledger can read CSV (Comma Separated Value/Character Separated Value) +files as if they were journal files, automatically converting each CSV +record into a transaction. (To learn about \f[I]writing\f[R] CSV, see CSV output.) .PP We describe each CSV file\[aq]s format with a corresponding \f[I]rules @@ -83,7 +83,11 @@ inline another CSV rules file T} .TE .PP -There\[aq]s also a Convert CSV files tutorial on hledger.org. +Note, for best error messages when reading CSV files, use a +\f[C].csv\f[R], \f[C].tsv\f[R] or \f[C].ssv\f[R] file extension or file +prefix - see File Extension below. +.PP +There\[aq]s an introductory Convert CSV files tutorial on hledger.org. .SH EXAMPLES .PP Here are some sample hledger CSV rules files. @@ -118,7 +122,7 @@ date-format %d/%m/%Y .nf \f[C] $ hledger print -f basic.csv -2019/11/12 Foo +2019-11-12 Foo expenses:unknown 10.23 income:unknown -10.23 \f[R] @@ -172,11 +176,11 @@ account1 assets:bank:boi:checking .nf \f[C] $ hledger -f bankofireland-checking.csv print -2012/12/07 LODGMENT 529898 +2012-12-07 LODGMENT 529898 assets:bank:boi:checking EUR10.0 = EUR131.2 income:unknown EUR-10.0 -2012/12/07 PAYMENT +2012-12-07 PAYMENT assets:bank:boi:checking EUR-5.0 = EUR126.0 expenses:unknown EUR5.0 \f[R] @@ -244,11 +248,11 @@ if ,\[rs]$[1-9][.0-9]+(,[\[ha],]*){1}$ .nf \f[C] $ hledger -f amazon-orders.csv print -2012/07/29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed +2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed assets:amazon expenses:misc $20.00 -2012/07/30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed +2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed assets:amazon expenses:misc $25.00 expenses:fees $1.00 @@ -391,32 +395,32 @@ if Google .nf \f[C] $ hledger -f paypal-custom.csv print -2019/10/01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon\[at]joyful.com, toemail:memberships\[at]calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed +2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon\[at]joyful.com, toemail:memberships\[at]calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed assets:online:paypal $-6.99 = $-6.99 expenses:online:apps $6.99 -2019/10/01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending +2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $6.99 = $0.00 assets:bank:wf:pchecking $-6.99 -2019/10/01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon\[at]joyful.com, toemail:support\[at]patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed +2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon\[at]joyful.com, toemail:support\[at]patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed assets:online:paypal $-7.00 = $-7.00 expenses:dues $7.00 -2019/10/01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending +2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $7.00 = $0.00 assets:bank:wf:pchecking $-7.00 -2019/10/19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon\[at]joyful.com, toemail:tle\[at]wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed +2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon\[at]joyful.com, toemail:tle\[at]wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed assets:online:paypal $-2.00 = $-2.00 expenses:dues $2.00 expenses:banking:paypal ; business: -2019/10/19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending +2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon\[at]joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $2.00 = $0.00 assets:bank:wf:pchecking $-2.00 -2019/10/22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble\[at]bene.fac.tor, toemail:simon\[at]joyful.com, time:05:07:06, type:Subscription Payment, status:Completed +2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble\[at]bene.fac.tor, toemail:simon\[at]joyful.com, time:05:07:06, type:Subscription Payment, status:Completed assets:online:paypal $9.41 = $9.41 revenues:foss donations:darcshub $-10.00 ; business: expenses:banking:paypal $0.59 ; business: @@ -575,6 +579,8 @@ Eg to read TSV (Tab Separated Values), use: separator TAB \f[R] .fi +.PP +See also: File Extension. .SS \f[C]if\f[R] .IP .nf @@ -819,6 +825,32 @@ When CSV values are enclosed in quotes, note: they must be double quotes (not single quotes) .IP \[bu] 2 spaces outside the quotes are not allowed +.SS File Extension +.PP +CSV (\[dq]Character Separated Values\[dq]) files should be named with +one of these filename extensions: \f[C].csv\f[R], \f[C].ssv\f[R], +\f[C].tsv\f[R]. +Or, the file path should be prefixed with one of \f[C]csv:\f[R], +\f[C]ssv:\f[R], \f[C]tsv:\f[R]. +This helps hledger identify the format and show the right error +messages. +For example: +.IP +.nf +\f[C] +$ hledger -f foo.ssv print +\f[R] +.fi +.PP +or: +.IP +.nf +\f[C] +$ cat foo | hledger -f ssv:- foo +\f[R] +.fi +.PP +More about this: Input files in the hledger manual. .SS Reading multiple CSV files .PP If you use multiple \f[C]-f\f[R] options to read multiple CSV files at diff --git a/hledger-lib/hledger_csv.info b/hledger-lib/hledger_csv.info index ffcb95990..6b6892301 100644 --- a/hledger-lib/hledger_csv.info +++ b/hledger-lib/hledger_csv.info @@ -6,10 +6,10 @@ File: hledger_csv.info, Node: Top, Next: EXAMPLES, Up: (dir) hledger_csv(5) hledger 1.16.99 ****************************** -hledger can read CSV (comma-separated value, or character-separated -value) files as if they were journal files, automatically converting -each CSV record into a transaction. (To learn about _writing_ CSV, see -CSV output.) +hledger can read CSV (Comma Separated Value/Character Separated Value) +files as if they were journal files, automatically converting each CSV +record into a transaction. (To learn about _writing_ CSV, see CSV +output.) We describe each CSV file's format with a corresponding _rules file_. By default this is named like the CSV file with a '.rules' extension @@ -37,7 +37,11 @@ assignment* *'newest-first'* disambiguate record order when there's only one date *'include'* inline another CSV rules file - There's also a Convert CSV files tutorial on hledger.org. + Note, for best error messages when reading CSV files, use a '.csv', +'.tsv' or '.ssv' file extension or file prefix - see File Extension +below. + + There's an introductory Convert CSV files tutorial on hledger.org. * Menu: @@ -81,7 +85,7 @@ fields date, description, _, amount date-format %d/%m/%Y $ hledger print -f basic.csv -2019/11/12 Foo +2019-11-12 Foo expenses:unknown 10.23 income:unknown -10.23 @@ -128,11 +132,11 @@ currency EUR account1 assets:bank:boi:checking $ hledger -f bankofireland-checking.csv print -2012/12/07 LODGMENT 529898 +2012-12-07 LODGMENT 529898 assets:bank:boi:checking EUR10.0 = EUR131.2 income:unknown EUR-10.0 -2012/12/07 PAYMENT +2012-12-07 PAYMENT assets:bank:boi:checking EUR-5.0 = EUR126.0 expenses:unknown EUR5.0 @@ -192,11 +196,11 @@ if ,\$[1-9][.0-9]+(,[^,]*){1}$ amount3 %fees $ hledger -f amazon-orders.csv print -2012/07/29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed +2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed assets:amazon expenses:misc $20.00 -2012/07/30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed +2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed assets:amazon expenses:misc $25.00 expenses:fees $1.00 @@ -328,32 +332,32 @@ if Google description google | music $ hledger -f paypal-custom.csv print -2019/10/01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed +2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed assets:online:paypal $-6.99 = $-6.99 expenses:online:apps $6.99 -2019/10/01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending +2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $6.99 = $0.00 assets:bank:wf:pchecking $-6.99 -2019/10/01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed +2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed assets:online:paypal $-7.00 = $-7.00 expenses:dues $7.00 -2019/10/01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending +2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $7.00 = $0.00 assets:bank:wf:pchecking $-7.00 -2019/10/19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed +2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed assets:online:paypal $-2.00 = $-2.00 expenses:dues $2.00 expenses:banking:paypal ; business: -2019/10/19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending +2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $2.00 = $0.00 assets:bank:wf:pchecking $-2.00 -2019/10/22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed +2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed assets:online:paypal $9.41 = $9.41 revenues:foss donations:darcshub $-10.00 ; business: expenses:banking:paypal $0.59 ; business: @@ -523,6 +527,8 @@ words 'TAB' or 'SPACE'. Eg to read TSV (Tab Separated Values), use: separator TAB + See also: File Extension. +  File: hledger_csv.info, Node: if, Next: end, Prev: separator, Up: CSV RULES @@ -705,6 +711,7 @@ File: hledger_csv.info, Node: TIPS, Prev: CSV RULES, Up: Top * Rapid feedback:: * Valid CSV:: +* File Extension:: * Reading multiple CSV files:: * Valid transactions:: * Deduplicating importing:: @@ -731,7 +738,7 @@ a separator each time the command re-runs, making it easier to read the output.  -File: hledger_csv.info, Node: Valid CSV, Next: Reading multiple CSV files, Prev: Rapid feedback, Up: TIPS +File: hledger_csv.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: TIPS 3.2 Valid CSV ============= @@ -743,9 +750,29 @@ enclosed in quotes, note: * spaces outside the quotes are not allowed  -File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Valid CSV, Up: TIPS +File: hledger_csv.info, Node: File Extension, Next: Reading multiple CSV files, Prev: Valid CSV, Up: TIPS -3.3 Reading multiple CSV files +3.3 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 the format and show the right error messages. For +example: + +$ hledger -f foo.ssv print + + or: + +$ cat foo | hledger -f ssv:- foo + + More about this: Input files in the hledger manual. + + +File: hledger_csv.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: File Extension, Up: TIPS + +3.4 Reading multiple CSV files ============================== If you use multiple '-f' options to read multiple CSV files at once, @@ -756,7 +783,7 @@ used for all the CSV files.  File: hledger_csv.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: TIPS -3.4 Valid transactions +3.5 Valid transactions ====================== After reading a CSV file, hledger post-processes and validates the @@ -775,7 +802,7 @@ $ hledger -f file.csv print | hledger -f- print  File: hledger_csv.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: TIPS -3.5 Deduplicating, importing +3.6 Deduplicating, importing ============================ When you download a CSV file periodically, eg to get your latest bank @@ -805,7 +832,7 @@ CSV data. See:  File: hledger_csv.info, Node: Setting amounts, Next: Setting currency/commodity, Prev: Deduplicating importing, Up: TIPS -3.6 Setting amounts +3.7 Setting amounts =================== A posting amount can be set in one of these ways: @@ -834,7 +861,7 @@ A posting amount can be set in one of these ways:  File: hledger_csv.info, Node: Setting currency/commodity, Next: Referencing other fields, Prev: Setting amounts, Up: TIPS -3.7 Setting currency/commodity +3.8 Setting currency/commodity ============================== If the currency/commodity symbol is included in the CSV's amount @@ -861,7 +888,7 @@ field(s), you don't have to do anything special.  File: hledger_csv.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Setting currency/commodity, Up: TIPS -3.8 Referencing other fields +3.9 Referencing other fields ============================ In field assignments, you can interpolate only CSV fields, not hledger @@ -898,8 +925,8 @@ if something  File: hledger_csv.info, Node: How CSV rules are evaluated, Prev: Referencing other fields, Up: TIPS -3.9 How CSV rules are evaluated -=============================== +3.10 How CSV rules are evaluated +================================ Here's how to think of CSV rules being evaluated (if you really need to). First, @@ -939,62 +966,64 @@ command the user specified.  Tag Table: Node: Top72 -Node: EXAMPLES1879 -Ref: #examples1985 -Node: Basic2193 -Ref: #basic2293 -Node: Bank of Ireland2835 -Ref: #bank-of-ireland2970 -Node: Amazon4433 -Ref: #amazon4551 -Node: Paypal6484 -Ref: #paypal6578 -Node: CSV RULES14461 -Ref: #csv-rules14570 -Node: skip14846 -Ref: #skip14939 -Node: fields15314 -Ref: #fields15436 -Node: Transaction field names16601 -Ref: #transaction-field-names16761 -Node: Posting field names16872 -Ref: #posting-field-names17024 -Node: field assignment18315 -Ref: #field-assignment18458 -Node: separator19276 -Ref: #separator19405 -Node: if19786 -Ref: #if19888 -Node: end21604 -Ref: #end21710 -Node: date-format21934 -Ref: #date-format22066 -Node: newest-first22815 -Ref: #newest-first22953 -Node: include23636 -Ref: #include23765 -Node: balance-type24209 -Ref: #balance-type24329 -Node: TIPS25029 -Ref: #tips25111 -Node: Rapid feedback25348 -Ref: #rapid-feedback25465 -Node: Valid CSV25925 -Ref: #valid-csv26067 -Node: Reading multiple CSV files26259 -Ref: #reading-multiple-csv-files26439 -Node: Valid transactions26680 -Ref: #valid-transactions26858 -Node: Deduplicating importing27486 -Ref: #deduplicating-importing27665 -Node: Setting amounts28698 -Ref: #setting-amounts28867 -Node: Setting currency/commodity29853 -Ref: #setting-currencycommodity30045 -Node: Referencing other fields30848 -Ref: #referencing-other-fields31048 -Node: How CSV rules are evaluated31945 -Ref: #how-csv-rules-are-evaluated32116 +Node: EXAMPLES2031 +Ref: #examples2137 +Node: Basic2345 +Ref: #basic2445 +Node: Bank of Ireland2987 +Ref: #bank-of-ireland3122 +Node: Amazon4585 +Ref: #amazon4703 +Node: Paypal6636 +Ref: #paypal6730 +Node: CSV RULES14613 +Ref: #csv-rules14722 +Node: skip14998 +Ref: #skip15091 +Node: fields15466 +Ref: #fields15588 +Node: Transaction field names16753 +Ref: #transaction-field-names16913 +Node: Posting field names17024 +Ref: #posting-field-names17176 +Node: field assignment18467 +Ref: #field-assignment18610 +Node: separator19428 +Ref: #separator19557 +Node: if19968 +Ref: #if20070 +Node: end21786 +Ref: #end21892 +Node: date-format22116 +Ref: #date-format22248 +Node: newest-first22997 +Ref: #newest-first23135 +Node: include23818 +Ref: #include23947 +Node: balance-type24391 +Ref: #balance-type24511 +Node: TIPS25211 +Ref: #tips25293 +Node: Rapid feedback25549 +Ref: #rapid-feedback25666 +Node: Valid CSV26126 +Ref: #valid-csv26256 +Node: File Extension26448 +Ref: #file-extension26600 +Node: Reading multiple CSV files27010 +Ref: #reading-multiple-csv-files27195 +Node: Valid transactions27436 +Ref: #valid-transactions27614 +Node: Deduplicating importing28242 +Ref: #deduplicating-importing28421 +Node: Setting amounts29454 +Ref: #setting-amounts29623 +Node: Setting currency/commodity30609 +Ref: #setting-currencycommodity30801 +Node: Referencing other fields31604 +Ref: #referencing-other-fields31804 +Node: How CSV rules are evaluated32701 +Ref: #how-csv-rules-are-evaluated32874  End Tag Table diff --git a/hledger-lib/hledger_csv.txt b/hledger-lib/hledger_csv.txt index 3d4e6b1d4..0f430c05a 100644 --- a/hledger-lib/hledger_csv.txt +++ b/hledger-lib/hledger_csv.txt @@ -7,10 +7,10 @@ NAME CSV - how hledger reads CSV data, and the CSV rules file format DESCRIPTION - hledger can read CSV (comma-separated value, or character-separated - value) files as if they were journal files, automatically converting - each CSV record into a transaction. (To learn about writing CSV, see - CSV output.) + hledger can read CSV (Comma Separated Value/Character Separated Value) + files as if they were journal files, automatically converting each CSV + record into a transaction. (To learn about writing CSV, see CSV out- + put.) We describe each CSV file's format with a corresponding rules file. By default this is named like the CSV file with a .rules extension added. @@ -46,16 +46,19 @@ DESCRIPTION include inline another CSV rules file - There's also a Convert CSV files tutorial on hledger.org. + Note, for best error messages when reading CSV files, use a .csv, .tsv + or .ssv file extension or file prefix - see File Extension below. + + There's an introductory Convert CSV files tutorial on hledger.org. EXAMPLES - Here are some sample hledger CSV rules files. See also the full col- + Here are some sample hledger CSV rules files. See also the full col- lection at: https://github.com/simonmichael/hledger/tree/master/examples/csv Basic - At minimum, the rules file must identify the date and amount fields, - and often it also specifies the date format and how many header lines + At minimum, the rules file must identify the date and amount fields, + and often it also specifies the date format and how many header lines there are. Here's a simple CSV file and a rules file for it: Date, Description, Id, Amount @@ -67,15 +70,15 @@ EXAMPLES date-format %d/%m/%Y $ hledger print -f basic.csv - 2019/11/12 Foo + 2019-11-12 Foo expenses:unknown 10.23 income:unknown -10.23 Default account names are chosen, since we didn't set them. Bank of Ireland - Here's a CSV with two amount fields (Debit and Credit), and a balance - field, which we can use to add balance assertions, which is not neces- + Here's a CSV with two amount fields (Debit and Credit), and a balance + field, which we can use to add balance assertions, which is not neces- sary but provides extra error checking: Date,Details,Debit,Credit,Balance @@ -109,21 +112,21 @@ EXAMPLES account1 assets:bank:boi:checking $ hledger -f bankofireland-checking.csv print - 2012/12/07 LODGMENT 529898 + 2012-12-07 LODGMENT 529898 assets:bank:boi:checking EUR10.0 = EUR131.2 income:unknown EUR-10.0 - 2012/12/07 PAYMENT + 2012-12-07 PAYMENT assets:bank:boi:checking EUR-5.0 = EUR126.0 expenses:unknown EUR5.0 - The balance assertions don't raise an error above, because we're read- - ing directly from CSV, but they will be checked if these entries are + The balance assertions don't raise an error above, because we're read- + ing directly from CSV, but they will be checked if these entries are imported into a journal file. Amazon Here we convert amazon.com order history, and use an if block to gener- - ate a third posting if there's a fee. (In practice you'd probably get + ate a third posting if there's a fee. (In practice you'd probably get this data from your bank instead, but it's an example.) "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID" @@ -168,17 +171,17 @@ EXAMPLES amount3 %fees $ hledger -f amazon-orders.csv print - 2012/07/29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed + 2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed assets:amazon expenses:misc $20.00 - 2012/07/30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed + 2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed assets:amazon expenses:misc $25.00 expenses:fees $1.00 Paypal - Here's a real-world rules file for (customised) Paypal CSV, with some + Here's a real-world rules file for (customised) Paypal CSV, with some Paypal-specific rules, and a second rules file included: "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note" @@ -299,32 +302,32 @@ EXAMPLES description google | music $ hledger -f paypal-custom.csv print - 2019/10/01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed + 2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed assets:online:paypal $-6.99 = $-6.99 expenses:online:apps $6.99 - 2019/10/01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending + 2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $6.99 = $0.00 assets:bank:wf:pchecking $-6.99 - 2019/10/01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed + 2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed assets:online:paypal $-7.00 = $-7.00 expenses:dues $7.00 - 2019/10/01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending + 2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $7.00 = $0.00 assets:bank:wf:pchecking $-7.00 - 2019/10/19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed + 2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed assets:online:paypal $-2.00 = $-2.00 expenses:dues $2.00 expenses:banking:paypal ; business: - 2019/10/19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending + 2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending assets:online:paypal $2.00 = $0.00 assets:bank:wf:pchecking $-2.00 - 2019/10/22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed + 2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed assets:online:paypal $9.41 = $9.41 revenues:foss donations:darcshub $-10.00 ; business: expenses:banking:paypal $0.59 ; business: @@ -336,9 +339,9 @@ CSV RULES skip skip N - The word "skip" followed by a number (or no number, meaning 1) tells - hledger to ignore this many non-empty lines preceding the CSV data. - (Empty/blank lines are skipped automatically.) You'll need this when- + The word "skip" followed by a number (or no number, meaning 1) tells + hledger to ignore this many non-empty lines preceding the CSV data. + (Empty/blank lines are skipped automatically.) You'll need this when- ever your CSV data contains header lines. It also has a second purpose: it can be used inside if blocks to ignore @@ -347,27 +350,27 @@ CSV RULES fields fields FIELDNAME1, FIELDNAME2, ... - A fields list (the word "fields" followed by comma-separated field - names) is the quick way to assign CSV field values to hledger fields. + A fields list (the word "fields" followed by comma-separated field + names) is the quick way to assign CSV field values to hledger fields. It does two things: - 1. it names the CSV fields. This is optional, but can be convenient + 1. it names the CSV fields. This is optional, but can be convenient later for interpolating them. 2. when you use a standard hledger field name, it assigns the CSV value to that part of the hledger transaction. - Here's an example that says "use the 1st, 2nd and 4th fields as the - transaction's date, description and amount; name the last two fields + Here's an example that says "use the 1st, 2nd and 4th fields as the + transaction's date, description and amount; name the last two fields for later reference; and ignore the others": fields date, description, , amount, , , somefield, anotherfield - Field names may not contain whitespace. Fields you don't care about - can be left unnamed. Currently there must be least two items (there + Field names may not contain whitespace. Fields you don't care about + can be left unnamed. Currently there must be least two items (there must be at least one comma). - Note, always use comma in the fields list, even if your CSV uses an- + Note, always use comma in the fields list, even if your CSV uses an- other separator character. Here are the standard hledger field/pseudo-field names. For more about @@ -379,28 +382,28 @@ CSV RULES transaction's first line. Posting field names - accountN, where N is 1 to 9, generates a posting, with that account - name. Most often there are two postings, so you'll want to set ac- + accountN, where N is 1 to 9, generates a posting, with that account + name. Most often there are two postings, so you'll want to set ac- count1 and account2. If a posting's account name is left unset but its amount is set, a default account name will be chosen (like expenses:un- known or income:unknown). - amountN sets posting N's amount. Or, amount with no N sets posting - 1's. If the CSV has debits and credits in separate fields, use - amountN-in and amountN-out instead. Or amount-in and amount-out with + amountN sets posting N's amount. Or, amount with no N sets posting + 1's. If the CSV has debits and credits in separate fields, use + amountN-in and amountN-out instead. Or amount-in and amount-out with no N for posting 1. - For convenience and backwards compatibility, if you set the amount of - posting 1 only, a second posting with the negative amount will be gen- - erated automatically. (Unless the account name is parenthesised indi- + For convenience and backwards compatibility, if you set the amount of + posting 1 only, a second posting with the negative amount will be gen- + erated automatically. (Unless the account name is parenthesised indi- cating an unbalanced posting.) - If the CSV has the currency symbol in a separate field, you can use - currencyN to prepend it to posting N's amount. currency with no N af- + If the CSV has the currency symbol in a separate field, you can use + currencyN to prepend it to posting N's amount. currency with no N af- fects ALL postings. - balanceN sets a balance assertion amount (or if the posting amount is - left empty, a balance assignment). You may need to adjust this with + balanceN sets a balance assertion amount (or if the posting amount is + left empty, a balance assignment). You may need to adjust this with the balance-type rule. Finally, commentN sets a comment on the Nth posting. Comments can also @@ -411,11 +414,11 @@ CSV RULES field assignment HLEDGERFIELDNAME FIELDVALUE - Instead of or in addition to a fields list, you can use a "field as- - signment" rule to set the value of a single hledger field, by writing - its name (any of the standard hledger field names above) followed by a - text value. The value may contain interpolated CSV fields, referenced - by their 1-based position in the CSV record (%N), or by the name they + Instead of or in addition to a fields list, you can use a "field as- + signment" rule to set the value of a single hledger field, by writing + its name (any of the standard hledger field names above) followed by a + text value. The value may contain interpolated CSV fields, referenced + by their 1-based position in the CSV record (%N), or by the name they were given in the fields list (%CSVFIELDNAME). Some examples: # set the amount to the 4th CSV field, with " USD" appended @@ -424,22 +427,24 @@ CSV RULES # combine three fields to make a comment, containing note: and date: tags comment note: %somefield - %anotherfield, date: %1 - Interpolation strips outer whitespace (so a CSV value like " 1 " be- + Interpolation strips outer whitespace (so a CSV value like " 1 " be- comes 1 when interpolated) (#1051). See TIPS below for more about ref- erencing other fields. separator - You can use the separator directive to read other kinds of character- + You can use the separator directive to read other kinds of character- separated data. Eg to read SSV (Semicolon Separated Values), use: separator ; - The separator directive accepts exactly one single byte character as a - separator. To specify whitespace characters, you may use the special + The separator directive accepts exactly one single byte character as a + separator. To specify whitespace characters, you may use the special words TAB or SPACE. Eg to read TSV (Tab Separated Values), use: separator TAB + See also: File Extension. + if if PATTERN RULE @@ -451,28 +456,28 @@ CSV RULES RULE RULE - Conditional blocks ("if blocks") are a block of rules that are applied - only to CSV records which match certain patterns. They are often used + Conditional blocks ("if blocks") are a block of rules that are applied + only to CSV records which match certain patterns. They are often used for customising account names based on transaction descriptions. A single pattern can be written on the same line as the "if"; or multi- ple patterns can be written on the following lines, non-indented. Mul- - tiple patterns are OR'd (any one of them can match). Patterns are + tiple patterns are OR'd (any one of them can match). Patterns are case-insensitive regular expressions which try to match anywhere within - the whole CSV record (POSIX extended regular expressions with some ad- + the whole CSV record (POSIX extended regular expressions with some ad- ditions, see https://hledger.org/hledger.html#regular-expressions). Note the CSV record they see is close to, but not identical to, the one in the CSV file; enclosing double quotes will be removed, and the sepa- rator character is always comma. - It's not yet easy to match within a specific field. If the data does + It's not yet easy to match within a specific field. If the data does not contain commas, you can hack it with a regular expression like: # match "foo" in the fourth field if ^([^,]*,){3}foo - 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- + 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) @@ -496,7 +501,7 @@ CSV RULES comment XXX deductible ? check it 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: @@ -507,10 +512,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 @@ -532,15 +537,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 @@ -553,9 +558,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 @@ -570,10 +575,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 @@ -588,25 +593,39 @@ 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) 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 + the format and show the right error messages. For example: + + $ hledger -f foo.ssv print + + or: + + $ cat foo | hledger -f ssv:- foo + + 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 diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 index ff246573f..b3a9da4ae 100644 --- a/hledger-lib/hledger_journal.5 +++ b/hledger-lib/hledger_journal.5 @@ -156,14 +156,14 @@ unspecified. .nf \f[C] $ hledger register checking -2010/02/23 movie ticket assets:checking $-10 $-10 +2010-02-23 movie ticket assets:checking $-10 $-10 \f[R] .fi .IP .nf \f[C] $ hledger register checking --date2 -2010/02/19 movie ticket assets:checking $-10 $-10 +2010-02-19 movie ticket assets:checking $-10 $-10 \f[R] .fi .PP @@ -193,14 +193,14 @@ reconciliation: .nf \f[C] $ hledger -f t.j register food -2015/05/30 expenses:food $10 $10 +2015-05-30 expenses:food $10 $10 \f[R] .fi .IP .nf \f[C] $ hledger -f t.j register checking -2015/06/01 assets:checking $-10 $-10 +2015-06-01 assets:checking $-10 $-10 \f[R] .fi .PP @@ -718,7 +718,7 @@ amount to have that price attached: .nf \f[C] $ hledger print --explicit -2019/01/01 +2019-01-01 (a) $1 \[at] \[Eu]2 = $1 \[at] \[Eu]2 \f[R] .fi @@ -1825,12 +1825,12 @@ Some examples: .nf \f[C] $ hledger print --auto -2017/12/01 +2017-12-01 expenses:food $10 assets:checking (liabilities:charity) $-1 -2017/12/14 +2017-12-14 expenses:gifts $20 assets:checking assets:checking:gifts -$20 diff --git a/hledger-lib/hledger_journal.info b/hledger-lib/hledger_journal.info index d4f8f865c..ea10a0a5c 100644 --- a/hledger-lib/hledger_journal.info +++ b/hledger-lib/hledger_journal.info @@ -189,10 +189,10 @@ the primary date if unspecified. assets:checking $ hledger register checking -2010/02/23 movie ticket assets:checking $-10 $-10 +2010-02-23 movie ticket assets:checking $-10 $-10 $ hledger register checking --date2 -2010/02/19 movie ticket assets:checking $-10 $-10 +2010-02-19 movie ticket assets:checking $-10 $-10 Secondary dates require some effort; you must use them consistently in your journal entries and remember whether to use or not use the @@ -218,10 +218,10 @@ easy bank reconciliation: assets:checking ; bank cleared it on monday, date:6/1 $ hledger -f t.j register food -2015/05/30 expenses:food $10 $10 +2015-05-30 expenses:food $10 $10 $ hledger -f t.j register checking -2015/06/01 assets:checking $-10 $-10 +2015-06-01 assets:checking $-10 $-10 DATE should be a simple date; if the year is not specified it will use the year of the transaction's date. You can set the secondary date @@ -709,7 +709,7 @@ amount to have that price attached: (a) = $1 @ €2 $ hledger print --explicit -2019/01/01 +2019-01-01 (a) $1 @ €2 = $1 @ €2  @@ -1667,12 +1667,12 @@ recorded above it or in another file. assets:checking $ hledger print --auto -2017/12/01 +2017-12-01 expenses:food $10 assets:checking (liabilities:charity) $-1 -2017/12/14 +2017-12-14 expenses:gifts $20 assets:checking assets:checking:gifts -$20 diff --git a/hledger-lib/hledger_journal.txt b/hledger-lib/hledger_journal.txt index e6c7d7b10..cc56e9cb2 100644 --- a/hledger-lib/hledger_journal.txt +++ b/hledger-lib/hledger_journal.txt @@ -134,10 +134,10 @@ FILE FORMAT assets:checking $ hledger register checking - 2010/02/23 movie ticket assets:checking $-10 $-10 + 2010-02-23 movie ticket assets:checking $-10 $-10 $ hledger register checking --date2 - 2010/02/19 movie ticket assets:checking $-10 $-10 + 2010-02-19 movie ticket assets:checking $-10 $-10 Secondary dates require some effort; you must use them consistently in your journal entries and remember whether to use or not use the --date2 @@ -158,10 +158,10 @@ FILE FORMAT assets:checking ; bank cleared it on monday, date:6/1 $ hledger -f t.j register food - 2015/05/30 expenses:food $10 $10 + 2015-05-30 expenses:food $10 $10 $ hledger -f t.j register checking - 2015/06/01 assets:checking $-10 $-10 + 2015-06-01 assets:checking $-10 $-10 DATE should be a simple date; if the year is not specified it will use the year of the transaction's date. You can set the secondary date @@ -525,7 +525,7 @@ FILE FORMAT (a) = $1 @ EUR2 $ hledger print --explicit - 2019/01/01 + 2019-01-01 (a) $1 @ EUR2 = $1 @ EUR2 Transaction prices @@ -1332,12 +1332,12 @@ FILE FORMAT assets:checking $ hledger print --auto - 2017/12/01 + 2017-12-01 expenses:food $10 assets:checking (liabilities:charity) $-1 - 2017/12/14 + 2017-12-14 expenses:gifts $20 assets:checking assets:checking:gifts -$20 diff --git a/hledger-lib/hledger_timeclock.5 b/hledger-lib/hledger_timeclock.5 index 604885fc8..12ed336e4 100644 --- a/hledger-lib/hledger_timeclock.5 +++ b/hledger-lib/hledger_timeclock.5 @@ -36,13 +36,13 @@ entries: .nf \f[C] $ hledger -f t.timeclock print -2015/03/30 * optional description after two spaces +2015-03-30 * optional description after two spaces (some:account name) 0.33h -2015/03/31 * 22:21-23:59 +2015-03-31 * 22:21-23:59 (another account) 1.64h -2015/04/01 * 00:00-02:00 +2015-04-01 * 00:00-02:00 (another account) 2.01h \f[R] .fi diff --git a/hledger-lib/hledger_timeclock.info b/hledger-lib/hledger_timeclock.info index 6d3071f4b..8872f4007 100644 --- a/hledger-lib/hledger_timeclock.info +++ b/hledger-lib/hledger_timeclock.info @@ -25,13 +25,13 @@ one day, it is split into several transactions, one for each day. For the above time log, 'hledger print' generates these journal entries: $ hledger -f t.timeclock print -2015/03/30 * optional description after two spaces +2015-03-30 * optional description after two spaces (some:account name) 0.33h -2015/03/31 * 22:21-23:59 +2015-03-31 * 22:21-23:59 (another account) 1.64h -2015/04/01 * 00:00-02:00 +2015-04-01 * 00:00-02:00 (another account) 2.01h Here is a sample.timeclock to download and some queries to try: diff --git a/hledger-lib/hledger_timeclock.txt b/hledger-lib/hledger_timeclock.txt index 1dde95b4e..4de57c30e 100644 --- a/hledger-lib/hledger_timeclock.txt +++ b/hledger-lib/hledger_timeclock.txt @@ -25,13 +25,13 @@ DESCRIPTION the above time log, hledger print generates these journal entries: $ hledger -f t.timeclock print - 2015/03/30 * optional description after two spaces + 2015-03-30 * optional description after two spaces (some:account name) 0.33h - 2015/03/31 * 22:21-23:59 + 2015-03-31 * 22:21-23:59 (another account) 1.64h - 2015/04/01 * 00:00-02:00 + 2015-04-01 * 00:00-02:00 (another account) 2.01h Here is a sample.timeclock to download and some queries to try: diff --git a/hledger-lib/hledger_timedot.5 b/hledger-lib/hledger_timedot.5 index 0e641fcab..36514800a 100644 --- a/hledger-lib/hledger_timedot.5 +++ b/hledger-lib/hledger_timedot.5 @@ -81,10 +81,10 @@ Reporting: .nf \f[C] $ hledger -f t.timedot print date:2016/2/2 -2016/02/02 * +2016-02-02 * (inc:client1) 2.00 -2016/02/02 * +2016-02-02 * (biz:research) 0.25 \f[R] .fi @@ -92,9 +92,9 @@ $ hledger -f t.timedot print date:2016/2/2 .nf \f[C] $ hledger -f t.timedot bal --daily --tree -Balance changes in 2016/02/01-2016/02/03: +Balance changes in 2016-02-01-2016-02-03: - || 2016/02/01d 2016/02/02d 2016/02/03d + || 2016-02-01d 2016-02-02d 2016-02-03d ============++======================================== biz || 0.25 0.25 1.00 research || 0.25 0.25 1.00 diff --git a/hledger-lib/hledger_timedot.info b/hledger-lib/hledger_timedot.info index 69f045295..39bf11804 100644 --- a/hledger-lib/hledger_timedot.info +++ b/hledger-lib/hledger_timedot.info @@ -71,16 +71,16 @@ biz:research 1 Reporting: $ hledger -f t.timedot print date:2016/2/2 -2016/02/02 * +2016-02-02 * (inc:client1) 2.00 -2016/02/02 * +2016-02-02 * (biz:research) 0.25 $ hledger -f t.timedot bal --daily --tree -Balance changes in 2016/02/01-2016/02/03: +Balance changes in 2016-02-01-2016-02-03: - || 2016/02/01d 2016/02/02d 2016/02/03d + || 2016-02-01d 2016-02-02d 2016-02-03d ============++======================================== biz || 0.25 0.25 1.00 research || 0.25 0.25 1.00 diff --git a/hledger-lib/hledger_timedot.txt b/hledger-lib/hledger_timedot.txt index ab375497b..ef9a4a14b 100644 --- a/hledger-lib/hledger_timedot.txt +++ b/hledger-lib/hledger_timedot.txt @@ -62,16 +62,16 @@ FILE FORMAT Reporting: $ hledger -f t.timedot print date:2016/2/2 - 2016/02/02 * + 2016-02-02 * (inc:client1) 2.00 - 2016/02/02 * + 2016-02-02 * (biz:research) 0.25 $ hledger -f t.timedot bal --daily --tree - Balance changes in 2016/02/01-2016/02/03: + Balance changes in 2016-02-01-2016-02-03: - || 2016/02/01d 2016/02/02d 2016/02/03d + || 2016-02-01d 2016-02-02d 2016-02-03d ============++======================================== biz || 0.25 0.25 1.00 research || 0.25 0.25 1.00 diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 index 319f027c4..d95a550b9 100644 --- a/hledger-web/hledger-web.1 +++ b/hledger-web/hledger-web.1 @@ -64,6 +64,13 @@ listen on this IP address (default: 127.0.0.1) \f[B]\f[CB]--port=PORT\f[B]\f[R] listen on this TCP port (default: 5000) .TP +\f[B]\f[CB]--socket=SOCKETFILE\f[B]\f[R] +use a unix domain socket file to listen for requests instead of a TCP +socket. +Implies \f[C]--serve\f[R]. +It can only be used if the operating system can provide this type of +socket. +.TP \f[B]\f[CB]--base-url=URL\f[B]\f[R] set the base url (default: http://IPADDR:PORT). You would change this when sharing over the network, or integrating @@ -210,6 +217,26 @@ to listen on all configured addresses. Similarly, use \f[C]--port\f[R] to set a TCP port other than 5000, eg if you are running multiple hledger-web instances. .PP +Both of these options are ignored when \f[C]--socket\f[R] is used. +In this case, it creates an \f[C]AF_UNIX\f[R] socket file at the +supplied path and uses that for communication. +This is an alternative way of running multiple hledger-web instances +behind a reverse proxy that handles authentication for different users. +The path can be derived in a predictable way, eg by using the username +within the path. +As an example, \f[C]nginx\f[R] as reverse proxy can use the variabel +\f[C]$remote_user\f[R] to derive a path from the username used in a HTTP +basic authentication. +The following \f[C]proxy_pass\f[R] directive allows access to all +\f[C]hledger-web\f[R] instances that created a socket in +\f[C]/tmp/hledger/\f[R]: +.IP +.nf +\f[C] + proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; +\f[R] +.fi +.PP You can use \f[C]--base-url\f[R] to change the protocol, hostname, port and path that appear in hyperlinks, useful eg for integrating hledger-web within a larger website. diff --git a/hledger-web/hledger-web.info b/hledger-web/hledger-web.info index 6ff865b4d..4841020a7 100644 --- a/hledger-web/hledger-web.info +++ b/hledger-web/hledger-web.info @@ -60,6 +60,11 @@ before options, as shown in the synopsis above. '--port=PORT' listen on this TCP port (default: 5000) +'--socket=SOCKETFILE' + + use a unix domain socket file to listen for requests instead of a + TCP socket. Implies '--serve'. It can only be used if the + operating system can provide this type of socket. '--base-url=URL' set the base url (default: http://IPADDR:PORT). You would change @@ -209,6 +214,19 @@ only to local requests. You can use '--host' to change this, eg '--host Similarly, use '--port' to set a TCP port other than 5000, eg if you are running multiple hledger-web instances. + Both of these options are ignored when '--socket' is used. In this +case, it creates an 'AF_UNIX' socket file at the supplied path and uses +that for communication. This is an alternative way of running multiple +hledger-web instances behind a reverse proxy that handles authentication +for different users. The path can be derived in a predictable way, eg +by using the username within the path. As an example, 'nginx' as +reverse proxy can use the variabel '$remote_user' to derive a path from +the username used in a HTTP basic authentication. The following +'proxy_pass' directive allows access to all 'hledger-web' instances that +created a socket in '/tmp/hledger/': + + proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; + You can use '--base-url' to change the protocol, hostname, port and path that appear in hyperlinks, useful eg for integrating hledger-web within a larger website. The default is 'http://HOST:PORT/' using the @@ -343,14 +361,14 @@ Tag Table: Node: Top72 Node: OPTIONS1361 Ref: #options1466 -Node: PERMISSIONS6790 -Ref: #permissions6929 -Node: EDITING UPLOADING DOWNLOADING8141 -Ref: #editing-uploading-downloading8322 -Node: RELOADING9156 -Ref: #reloading9290 -Node: JSON API9723 -Ref: #json-api9817 +Node: PERMISSIONS7739 +Ref: #permissions7878 +Node: EDITING UPLOADING DOWNLOADING9090 +Ref: #editing-uploading-downloading9271 +Node: RELOADING10105 +Ref: #reloading10239 +Node: JSON API10672 +Ref: #json-api10766  End Tag Table diff --git a/hledger-web/hledger-web.txt b/hledger-web/hledger-web.txt index 52690fb12..5897beec5 100644 --- a/hledger-web/hledger-web.txt +++ b/hledger-web/hledger-web.txt @@ -56,6 +56,11 @@ OPTIONS --port=PORT listen on this TCP port (default: 5000) + --socket=SOCKETFILE + use a unix domain socket file to listen for requests instead of + a TCP socket. Implies --serve. It can only be used if the op- + erating system can provide this type of socket. + --base-url=URL set the base url (default: http://IPADDR:PORT). You would change this when sharing over the network, or integrating within @@ -200,22 +205,35 @@ OPTIONS Similarly, use --port to set a TCP port other than 5000, eg if you are running multiple hledger-web instances. - You can use --base-url to change the protocol, hostname, port and path + Both of these options are ignored when --socket is used. In this case, + it creates an AF_UNIX socket file at the supplied path and uses that + for communication. This is an alternative way of running multiple + hledger-web instances behind a reverse proxy that handles authentica- + tion for different users. The path can be derived in a predictable + way, eg by using the username within the path. As an example, nginx as + reverse proxy can use the variabel $remote_user to derive a path from + the username used in a HTTP basic authentication. The following + proxy_pass directive allows access to all hledger-web instances that + created a socket in /tmp/hledger/: + + proxy_pass http://unix:/tmp/hledger/${remote_user}.socket; + + You can use --base-url to change the protocol, hostname, port and path that appear in hyperlinks, useful eg for integrating hledger-web within - a larger website. The default is http://HOST:PORT/ using the server's + a larger website. The default is http://HOST:PORT/ using the server's configured host address and TCP port (or http://HOST if PORT is 80). - With --file-url you can set a different base url for static files, eg + With --file-url you can set a different base url for static files, eg for better caching or cookie-less serving on high performance websites. PERMISSIONS - By default, hledger-web allows anyone who can reach it to view the + By default, hledger-web allows anyone who can reach it to view the journal and to add new transactions, but not to change existing data. You can restrict who can reach it by - o setting the IP address it listens on (see --host above). By default - it listens on 127.0.0.1, accessible to all users on the local ma- + o setting the IP address it listens on (see --host above). By default + it listens on 127.0.0.1, accessible to all users on the local ma- chine. o putting it behind an authenticating proxy, using eg apache or nginx @@ -225,44 +243,44 @@ PERMISSIONS You can restrict what the users who reach it can do, by o using the --capabilities=CAP[,CAP..] flag when you start it, enabling - one or more of the following capabilities. The default value is + one or more of the following capabilities. The default value is view,add: o view - allows viewing the journal file and all included files o add - allows adding new transactions to the main journal file - o manage - allows editing, uploading or downloading the main or in- + o manage - allows editing, uploading or downloading the main or in- cluded files - o using the --capabilities-header=HTTPHEADER flag to specify a HTTP - header from which it will read capabilities to enable. hledger-web - on Sandstorm uses the X-Sandstorm-Permissions header to integrate + o using the --capabilities-header=HTTPHEADER flag to specify a HTTP + header from which it will read capabilities to enable. hledger-web + on Sandstorm uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions. This is disabled by default. EDITING, UPLOADING, DOWNLOADING - If you enable the manage capability mentioned above, you'll see a new - "spanner" button to the right of the search form. Clicking this will - let you edit, upload, or download the journal file or any files it in- + If you enable the manage capability mentioned above, you'll see a new + "spanner" button to the right of the search form. Clicking this will + let you edit, upload, or download the journal file or any files it in- cludes. - Note, unlike any other hledger command, in this mode you (or any visi- + Note, unlike any other hledger command, in this mode you (or any visi- tor) can alter or wipe the data files. - Normally whenever a file is changed in this way, hledger-web saves a - numbered backup (assuming file permissions allow it, the disk is not - full, etc.) hledger-web is not aware of version control systems, cur- - rently; if you use one, you'll have to arrange to commit the changes + Normally whenever a file is changed in this way, hledger-web saves a + numbered backup (assuming file permissions allow it, the disk is not + full, etc.) hledger-web is not aware of version control systems, cur- + rently; if you use one, you'll have to arrange to commit the changes yourself (eg with a cron job or a file watcher like entr). - Changes which would leave the journal file(s) unparseable or non-valid - (eg with failing balance assertions) are prevented. (Probably. This + Changes which would leave the journal file(s) unparseable or non-valid + (eg with failing balance assertions) are prevented. (Probably. This needs re-testing.) RELOADING hledger-web detects changes made to the files by other means (eg if you - edit it directly, outside of hledger-web), and it will show the new - data when you reload the page or navigate to a new page. If a change + edit it directly, outside of hledger-web), and it will show the new + data when you reload the page or navigate to a new page. If a change makes a file unparseable, hledger-web will display an error message un- til the file has been fixed. @@ -270,8 +288,8 @@ RELOADING that both machine clocks are roughly in step.) JSON API - In addition to the web UI, hledger-web provides some API routes that - serve JSON in response to GET requests. (And when started with + In addition to the web UI, hledger-web provides some API routes that + serve JSON in response to GET requests. (And when started with --serve-api, it provides only these routes.): /accountnames @@ -281,17 +299,17 @@ JSON API /accounts /accounttransactions/#AccountName - Also, you can append a new transaction to the journal by sending a PUT - request to /add (hledger-web only). As with the web UI's add form, - hledger-web must be started with the add capability for this (enabled + Also, you can append a new transaction to the journal by sending a PUT + request to /add (hledger-web only). As with the web UI's add form, + hledger-web must be started with the add capability for this (enabled by default). - The payload should be a valid hledger transaction as JSON, similar to + The payload should be a valid hledger transaction as JSON, similar to what you get from /transactions or /accounttransactions. - Another way to generate test data is with the readJsonFile/writeJson- - File helpers in Hledger.Web.Json, which read or write any of hledger's - JSON-capable types from or to a file. Eg here we write the first + Another way to generate test data is with the readJsonFile/writeJson- + File helpers in Hledger.Web.Json, which read or write any of hledger's + JSON-capable types from or to a file. Eg here we write the first transaction of a sample journal: $ make ghci-web @@ -306,23 +324,23 @@ JSON API $ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo - By default, both the server-side HTML UI and the JSON API are served. - Running with --serve-api disables the former, useful if you only want + By default, both the server-side HTML UI and the JSON API are served. + Running with --serve-api disables the former, useful if you only want to serve the API. ENVIRONMENT 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). 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). BUGS - The need to precede options with -- when invoked from hledger is awk- + The need to precede options with -- when invoked from hledger is awk- ward. -f- doesn't work (hledger-web can't read from stdin). @@ -336,7 +354,7 @@ BUGS 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) @@ -350,7 +368,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/Cli/Commands/Close.txt b/hledger/Hledger/Cli/Commands/Close.txt index 229580d7a..d70f31834 100644 --- a/hledger/Hledger/Cli/Commands/Close.txt +++ b/hledger/Hledger/Cli/Commands/Close.txt @@ -13,6 +13,10 @@ balances", or you can customise these with the --close-to and --open-from options. You can choose to print just one of the transactions by using the --opening or --closing flag. +The equity postings appear at the end of the transaction by default; +with --interleaved, they appear beside their corresponding closing +postings. + If you split your journal files by time (eg yearly), you will typically run this command at the end of the year, and save the closing transaction as last entry of the old file, and the opening transaction diff --git a/hledger/Hledger/Cli/Commands/Print.txt b/hledger/Hledger/Cli/Commands/Print.txt index 879495c21..258031771 100644 --- a/hledger/Hledger/Cli/Commands/Print.txt +++ b/hledger/Hledger/Cli/Commands/Print.txt @@ -34,13 +34,17 @@ $ hledger print assets:bank:checking $-1 Normally, the journal entry's explicit or implicit amount style is -preserved. Ie when an amount is omitted in the journal, it will be -omitted 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 output. +preserved. For example, when an amount is omitted in the journal, it +will not appear in the output. Similarly, when a transaction price is +implied but not written, it will not appear in the output. You can use +the -x/--explicit flag to make all amounts and transaction prices +explicit, which can be useful for troubleshooting or for making your +journal more readable and robust against data entry errors. + +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 using that price. This can be used for troubleshooting. diff --git a/hledger/hledger.1 b/hledger/hledger.1 index a0e877a11..1e3328cd0 100644 --- a/hledger/hledger.1 +++ b/hledger/hledger.1 @@ -94,11 +94,11 @@ Some basic reports: .nf \f[C] $ hledger print -2015/09/30 gift received +2015-09-30 gift received assets:cash $20 income:gifts $-20 -2015/10/16 farmers market +2015-10-16 farmers market expenses:food $10 assets:cash $-10 \f[R] @@ -130,8 +130,8 @@ $ hledger balance .nf \f[C] $ hledger register cash -2015/09/30 gift received assets:cash $20 $20 -2015/10/16 farmers market assets:cash $-10 $10 +2015-09-30 gift received assets:cash $20 $20 +2015-10-16 farmers market assets:cash $-10 $10 \f[R] .fi .PP @@ -1210,13 +1210,13 @@ Show the cost of each posting: .nf \f[C] $ hledger -f- print --value=cost -2000/01/01 +2000-01-01 (a) 5 B -2000/02/01 +2000-02-01 (a) 6 B -2000/03/01 +2000-03-01 (a) 7 B \f[R] .fi @@ -1240,13 +1240,13 @@ of the journal (2000-03-01): .nf \f[C] $ hledger -f- print --value=end -2000/01/01 +2000-01-01 (a) 3 B -2000/02/01 +2000-02-01 (a) 3 B -2000/03/01 +2000-03-01 (a) 3 B \f[R] .fi @@ -1272,13 +1272,13 @@ Show the value on 2000/01/15: .nf \f[C] $ hledger -f- print --value=2000-01-15 -2000/01/01 +2000-01-01 (a) 1 B -2000/02/01 +2000-02-01 (a) 1 B -2000/03/01 +2000-03-01 (a) 1 B \f[R] .fi @@ -1300,7 +1300,7 @@ P 2000-01-01 A 2B .nf \f[C] $ hledger print -x -X A -2000/01/01 +2000-01-01 a 0 b 0 \f[R] @@ -1327,7 +1327,7 @@ commodity 0.00A .nf \f[C] $ hledger print -X A -2000/01/01 +2000-01-01 a 0.50A b -0.50A \f[R] @@ -2721,6 +2721,10 @@ balances\[dq], and the opening transaction transfers balances from You can choose to print just one of the transactions by using the \f[C]--opening\f[R] or \f[C]--closing\f[R] flag. .PP +The equity postings appear at the end of the transaction by default; +with \f[C]--interleaved\f[R], they appear beside their corresponding +closing postings. +.PP If you split your journal files by time (eg yearly), you will typically run this command at the end of the year, and save the closing transaction as last entry of the old file, and the opening transaction @@ -3123,15 +3127,19 @@ $ hledger print .PP Normally, the journal entry\[aq]s explicit or implicit amount style is preserved. -Ie when an amount is omitted in the journal, it will be omitted in the -output. +For example, when an amount is omitted in the journal, it will not +appear in the output. +Similarly, when a transaction price is implied but not written, it will +not appear in the output. You can use the \f[C]-x\f[R]/\f[C]--explicit\f[R] 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, \f[C]-x\f[R] 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 output. +amounts and transaction prices explicit, which can be useful for +troubleshooting or for making your journal more readable and robust +against data entry errors. +.PP +Note, \f[C]-x\f[R]/\f[C]--explicit\f[R] 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. .PP With \f[C]-B\f[R]/\f[C]--cost\f[R], amounts with transaction prices are converted to cost using that price. diff --git a/hledger/hledger.info b/hledger/hledger.info index b87ef4a42..0e9e5a8fa 100644 --- a/hledger/hledger.info +++ b/hledger/hledger.info @@ -68,11 +68,11 @@ Two simple transactions in hledger journal format: Some basic reports: $ hledger print -2015/09/30 gift received +2015-09-30 gift received assets:cash $20 income:gifts $-20 -2015/10/16 farmers market +2015-10-16 farmers market expenses:food $10 assets:cash $-10 @@ -92,8 +92,8 @@ $ hledger balance 0 $ hledger register cash -2015/09/30 gift received assets:cash $20 $20 -2015/10/16 farmers market assets:cash $-10 $10 +2015-09-30 gift received assets:cash $20 $20 +2015-10-16 farmers market assets:cash $-10 $10 More commands: @@ -932,13 +932,13 @@ P 2000-04-01 A 4 B Show the cost of each posting: $ hledger -f- print --value=cost -2000/01/01 +2000-01-01 (a) 5 B -2000/02/01 +2000-02-01 (a) 6 B -2000/03/01 +2000-03-01 (a) 7 B Show the value as of the last day of the report period (2000-02-29): @@ -954,13 +954,13 @@ $ hledger -f- print --value=end date:2000/01-2000/03 day of the journal (2000-03-01): $ hledger -f- print --value=end -2000/01/01 +2000-01-01 (a) 3 B -2000/02/01 +2000-02-01 (a) 3 B -2000/03/01 +2000-03-01 (a) 3 B Show the current value (the 2000-04-01 price is still in effect @@ -979,13 +979,13 @@ $ hledger -f- print --value=now Show the value on 2000/01/15: $ hledger -f- print --value=2000-01-15 -2000/01/01 +2000-01-01 (a) 1 B -2000/02/01 +2000-02-01 (a) 1 B -2000/03/01 +2000-03-01 (a) 1 B You may need to explicitly set a commodity's display style, when @@ -998,7 +998,7 @@ P 2000-01-01 A 2B b $ hledger print -x -X A -2000/01/01 +2000-01-01 a 0 b 0 @@ -1016,7 +1016,7 @@ commodity 0.00A b $ hledger print -X A -2000/01/01 +2000-01-01 a 0.50A b -0.50A @@ -2219,6 +2219,10 @@ balances", and the opening transaction transfers balances from '--close-to' and '--open-from' options. You can choose to print just one of the transactions by using the '--opening' or '--closing' flag. + The equity postings appear at the end of the transaction by default; +with '--interleaved', they appear beside their corresponding closing +postings. + If you split your journal files by time (eg yearly), you will typically run this command at the end of the year, and save the closing transaction as last entry of the old file, and the opening transaction @@ -2583,13 +2587,17 @@ $ hledger print assets:bank:checking $-1 Normally, the journal entry's explicit or implicit amount style is -preserved. Ie when an amount is omitted in the journal, it will be -omitted 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 output. +preserved. For example, when an amount is omitted in the journal, it +will not appear in the output. Similarly, when a transaction price is +implied but not written, it will not appear in the output. You can use +the '-x'/'--explicit' flag to make all amounts and transaction prices +explicit, which can be useful for troubleshooting or for making your +journal more readable and robust against data entry errors. + + 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 using that price. This can be used for troubleshooting. @@ -3292,74 +3300,74 @@ Node: check-dupes76317 Ref: #check-dupes76441 Node: close76734 Ref: #close76848 -Node: commodities80514 -Ref: #commodities80641 -Node: descriptions80723 -Ref: #descriptions80851 -Node: diff81032 -Ref: #diff81138 -Node: files82185 -Ref: #files82285 -Node: help82432 -Ref: #help82532 -Node: import83613 -Ref: #import83727 -Node: Importing balance assignments84620 -Ref: #importing-balance-assignments84768 -Node: incomestatement85417 -Ref: #incomestatement85550 -Node: notes86954 -Ref: #notes87067 -Node: payees87193 -Ref: #payees87299 -Node: prices87457 -Ref: #prices87563 -Node: print87904 -Ref: #print88014 -Node: print-unique92507 -Ref: #print-unique92633 -Node: register92918 -Ref: #register93045 -Node: Custom register output97217 -Ref: #custom-register-output97346 -Node: register-match98608 -Ref: #register-match98742 -Node: rewrite99093 -Ref: #rewrite99208 -Node: Re-write rules in a file101063 -Ref: #re-write-rules-in-a-file101197 -Node: Diff output format102407 -Ref: #diff-output-format102576 -Node: rewrite vs print --auto103668 -Ref: #rewrite-vs.-print---auto103847 -Node: roi104403 -Ref: #roi104501 -Node: stats105513 -Ref: #stats105612 -Node: tags106400 -Ref: #tags106498 -Node: test106792 -Ref: #test106876 -Node: ADD-ON COMMANDS107623 -Ref: #add-on-commands107733 -Node: Official add-ons109021 -Ref: #official-add-ons109161 -Node: ui109241 -Ref: #ui109328 -Node: web109382 -Ref: #web109471 -Node: Third party add-ons109517 -Ref: #third-party-add-ons109692 -Node: iadd109811 -Ref: #iadd109912 -Node: interest109994 -Ref: #interest110103 -Node: Experimental add-ons110198 -Ref: #experimental-add-ons110350 -Node: autosync110588 -Ref: #autosync110699 -Node: chart110938 -Ref: #chart111043 +Node: commodities80666 +Ref: #commodities80793 +Node: descriptions80875 +Ref: #descriptions81003 +Node: diff81184 +Ref: #diff81290 +Node: files82337 +Ref: #files82437 +Node: help82584 +Ref: #help82684 +Node: import83765 +Ref: #import83879 +Node: Importing balance assignments84772 +Ref: #importing-balance-assignments84920 +Node: incomestatement85569 +Ref: #incomestatement85702 +Node: notes87106 +Ref: #notes87219 +Node: payees87345 +Ref: #payees87451 +Node: prices87609 +Ref: #prices87715 +Node: print88056 +Ref: #print88166 +Node: print-unique92810 +Ref: #print-unique92936 +Node: register93221 +Ref: #register93348 +Node: Custom register output97520 +Ref: #custom-register-output97649 +Node: register-match98911 +Ref: #register-match99045 +Node: rewrite99396 +Ref: #rewrite99511 +Node: Re-write rules in a file101366 +Ref: #re-write-rules-in-a-file101500 +Node: Diff output format102710 +Ref: #diff-output-format102879 +Node: rewrite vs print --auto103971 +Ref: #rewrite-vs.-print---auto104150 +Node: roi104706 +Ref: #roi104804 +Node: stats105816 +Ref: #stats105915 +Node: tags106703 +Ref: #tags106801 +Node: test107095 +Ref: #test107179 +Node: ADD-ON COMMANDS107926 +Ref: #add-on-commands108036 +Node: Official add-ons109324 +Ref: #official-add-ons109464 +Node: ui109544 +Ref: #ui109631 +Node: web109685 +Ref: #web109774 +Node: Third party add-ons109820 +Ref: #third-party-add-ons109995 +Node: iadd110114 +Ref: #iadd110215 +Node: interest110297 +Ref: #interest110406 +Node: Experimental add-ons110501 +Ref: #experimental-add-ons110653 +Node: autosync110891 +Ref: #autosync111002 +Node: chart111241 +Ref: #chart111346  End Tag Table diff --git a/hledger/hledger.txt b/hledger/hledger.txt index 0b07bbb40..3eca860ee 100644 --- a/hledger/hledger.txt +++ b/hledger/hledger.txt @@ -68,11 +68,11 @@ EXAMPLES Some basic reports: $ hledger print - 2015/09/30 gift received + 2015-09-30 gift received assets:cash $20 income:gifts $-20 - 2015/10/16 farmers market + 2015-10-16 farmers market expenses:food $10 assets:cash $-10 @@ -92,8 +92,8 @@ EXAMPLES 0 $ hledger register cash - 2015/09/30 gift received assets:cash $20 $20 - 2015/10/16 farmers market assets:cash $-10 $10 + 2015-09-30 gift received assets:cash $20 $20 + 2015-10-16 farmers market assets:cash $-10 $10 More commands: @@ -829,13 +829,13 @@ OPTIONS Show the cost of each posting: $ hledger -f- print --value=cost - 2000/01/01 + 2000-01-01 (a) 5 B - 2000/02/01 + 2000-02-01 (a) 6 B - 2000/03/01 + 2000-03-01 (a) 7 B Show the value as of the last day of the report period (2000-02-29): @@ -851,13 +851,13 @@ OPTIONS day of the journal (2000-03-01): $ hledger -f- print --value=end - 2000/01/01 + 2000-01-01 (a) 3 B - 2000/02/01 + 2000-02-01 (a) 3 B - 2000/03/01 + 2000-03-01 (a) 3 B Show the current value (the 2000-04-01 price is still in effect today): @@ -875,13 +875,13 @@ OPTIONS Show the value on 2000/01/15: $ hledger -f- print --value=2000-01-15 - 2000/01/01 + 2000-01-01 (a) 1 B - 2000/02/01 + 2000-02-01 (a) 1 B - 2000/03/01 + 2000-03-01 (a) 1 B You may need to explicitly set a commodity's display style, when re- @@ -894,7 +894,7 @@ OPTIONS b $ hledger print -x -X A - 2000/01/01 + 2000-01-01 a 0 b 0 @@ -912,7 +912,7 @@ OPTIONS b $ hledger print -X A - 2000/01/01 + 2000-01-01 a 0.50A b -0.50A @@ -1955,6 +1955,10 @@ COMMANDS and --open-from options. You can choose to print just one of the transactions by using the --opening or --closing flag. + The equity postings appear at the end of the transaction by default; + with --interleaved, they appear beside their corresponding closing + postings. + If you split your journal files by time (eg yearly), you will typically run this command at the end of the year, and save the closing transac- tion as last entry of the old file, and the opening transaction as the @@ -2253,39 +2257,42 @@ COMMANDS assets:bank:checking $-1 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 - 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- - put. + 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 + journal more readable and robust against data entry errors. - With -B/--cost, amounts with transaction prices are converted to cost + 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 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 output destination and output format selec- + This command also supports output destination and output format selec- tion. Here's an example of print's CSV output: $ hledger print -Ocsv @@ -2302,20 +2309,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 @@ -2339,7 +2346,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 @@ -2350,8 +2357,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 @@ -2361,18 +2368,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 @@ -2384,7 +2391,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 @@ -2401,7 +2408,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 @@ -2409,17 +2416,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): @@ -2437,27 +2444,27 @@ COMMANDS $ hledger reg -w 100,40 # set overall width 100, description width 40 $ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40 - This command also supports output destination and output format selec- + This command also supports output destination and output format selec- tion. 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: @@ -2473,7 +2480,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: @@ -2483,16 +2490,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. @@ -2507,7 +2514,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. @@ -2520,12 +2527,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' @@ -2549,10 +2556,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: @@ -2560,48 +2567,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: @@ -2619,14 +2626,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. @@ -2634,13 +2641,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 -- @@ -2649,32 +2656,32 @@ 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. Here are some hledger add-ons available: @@ -2689,7 +2696,7 @@ ADD-ON COMMANDS hledger-web provides a simple web interface. Third party add-ons - These are maintained separately, and usually updated shortly after a + These are maintained separately, and usually updated shortly after a hledger release. iadd @@ -2701,35 +2708,35 @@ ADD-ON COMMANDS ing to various schemes. Experimental add-ons - These are available in source form in the hledger repo's bin/ direc- - tory. They may be less mature and documented than built-in commands. + These are available in source form in the hledger repo's bin/ direc- + tory. They may be less mature and documented than built-in commands. Reading and tweaking these is a good way to start making your own! autosync hledger-autosync is a symbolic link for easily running ledger-autosync, - if installed. ledger-autosync does deduplicating conversion of OFX - data and some CSV formats, and can also download the data if your bank + if installed. ledger-autosync does deduplicating conversion of OFX + data and some CSV formats, and can also download the data if your bank offers OFX Direct Connect. chart hledger-chart.hs is an old very basic pie chart generator. 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). 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 @@ -2745,33 +2752,33 @@ 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. - "Illegal byte sequence" or "Invalid or incomplete multibyte or wide + "Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors In order to handle non-ascii letters and symbols (like ), hledger needs an appropriate locale. This is usually configured system-wide; you can also configure it temporarily. The locale may need to be one that sup- - ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, + ports UTF-8, if you built hledger with GHC < 7.2 (or possibly always, I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu @@ -2790,7 +2797,7 @@ TROUBLESHOOTING $ echo "export LANG=en_US.UTF-8" >>~/.bash_profile $ bash --login - If we preferred to use eg fr_FR.utf8, we might have to install that + If we preferred to use eg fr_FR.utf8, we might have to install that first: $ apt-get install language-pack-fr @@ -2811,7 +2818,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) @@ -2825,7 +2832,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)