diff --git a/Shake.hs b/Shake.hs index ca817c18f..f06d19227 100755 --- a/Shake.hs +++ b/Shake.hs @@ -56,7 +56,8 @@ pandoc = "pandoc" -- pandoc from PATH (faster) -- "stack exec -- pandoc" -- pandoc from project's stackage snapshot hakyllstd = "site/hakyll-std/hakyll-std" makeinfo = "makeinfo" -nroff = "nroff" +-- nroff = "nroff" +groff = "groff" main = do @@ -164,7 +165,7 @@ main = do txtmanpages |%> \out -> do -- hledger/doc/hledger.1.txt let src = dropExtension out need [src] - cmd Shell nroff "-man" src ">" out + cmd Shell groff "-t -e -mandoc -Tascii" src "| col -bx >" out -- http://www.tldp.org/HOWTO/Man-Page/q10.html -- use m4 and pandoc to process macros, filter content, and convert to info, suitable for info viewing phony "infomanpages" $ need infomanpages diff --git a/hledger-api/doc/hledger-api.1.txt b/hledger-api/doc/hledger-api.1.txt index b849eb180..f2eb1bff6 100644 --- a/hledger-api/doc/hledger-api.1.txt +++ b/hledger-api/doc/hledger-api.1.txt @@ -3,15 +3,15 @@ hledger-api(1) hledger User Manuals hledger-api(1) -NNAAMMEE +NAME hledger-api - web API server for the hledger accounting tool -SSYYNNOOPPSSIISS +SYNOPSIS hledger-api [OPTIONS] hledger-api --swagger hledger api -- [OPTIONS] -DDEESSCCRRIIPPTTIIOONN +DESCRIPTION hledger is a cross-platform program for tracking money, time, or any other commodity, using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with @@ -35,81 +35,81 @@ DDEESSCCRRIIPPTTIIOONN If invoked as hledger-api --swagger, instead of starting a server the API docs will be printed in Swagger 2.0 format. -OOPPTTIIOONNSS +OPTIONS Note: if invoking hledger-api as a hledger subcommand, write -- before options as shown above. - --dd ----ssttaattiicc--ddiirr==DDIIRR + -d --static-dir=DIR serve files from a different directory (default: .) - --pp ----ppoorrtt==PPOORRTT + -p --port=PORT use a different TCP port (default: 8001) - ----sswwaaggggeerr + --swagger print API docs in Swagger 2.0 format, and exit hledger general options: - --hh show general usage (or after COMMAND, the command's usage) + -h show general usage (or after COMMAND, the command's usage) - ----hheellpp show the current program's manual as plain text (or after an + --help show the current program's manual as plain text (or after an add-on COMMAND, the add-on's manual) - ----mmaann show the current program's manual with man + --man show the current program's manual with man - ----iinnffoo show the current program's manual with info + --info show the current program's manual with info - ----vveerrssiioonn + --version show version - ----ddeebbuugg==NN + --debug=N show debug output if N is 1-9 (default: 0) - --ff FFIILLEE ----ffiillee==FFIILLEE + -f FILE --file=FILE use a different input file. For stdin, use - - ----rruulleess--ffiillee==RRUULLEESSFFIILLEE + --rules-file=RULESFILE Conversion rules file to use when reading CSV (default: FILE.rules) - ----aalliiaass==OOLLDD==NNEEWW + --alias=OLD=NEW display accounts named OLD as NEW - ----iiggnnoorree--aasssseerrttiioonnss + --ignore-assertions ignore any failing balance assertions in the journal -EENNVVIIRROONNMMEENNTT - LLEEDDGGEERR__FFIILLEE The journal file path when not specified with -f. Default: +ENVIRONMENT + LEDGER_FILE The journal file path when not specified with -f. Default: ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). -FFIILLEESS +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 C:/Users/USER/.hledger.journal). -BBUUGGSS +BUGS The need to precede options with -- when invoked from hledger is awk- ward. -RREEPPOORRTTIINNGG BBUUGGSS +REPORTING BUGS Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) -AAUUTTHHOORRSS +AUTHORS Simon Michael and contributors -CCOOPPYYRRIIGGHHTT +COPYRIGHT Copyright (C) 2007-2016 Simon Michael. Released under GNU GPL v3 or later. -SSEEEE AALLSSOO +SEE ALSO 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-lib/doc/hledger_csv.5.txt b/hledger-lib/doc/hledger_csv.5.txt index cfd9eb950..55df6e7c8 100644 --- a/hledger-lib/doc/hledger_csv.5.txt +++ b/hledger-lib/doc/hledger_csv.5.txt @@ -3,10 +3,10 @@ hledger_csv(5) hledger User Manuals hledger_csv(5) -NNAAMMEE +NAME CSV - how hledger reads CSV data, and the CSV rules file format -DDEESSCCRRIIPPTTIIOONN +DESCRIPTION hledger can read CSV files, converting each CSV record into a journal entry (transaction), if you provide some conversion hints in a "rules file". This file should be named like the CSV file with an additional @@ -16,14 +16,14 @@ DDEESSCCRRIIPPTTIIOONN must specify the date and amount fields. For an example, see How to read CSV files. - To learn about _e_x_p_o_r_t_i_n_g CSV, see CSV output. + To learn about exporting CSV, see CSV output. -CCSSVV RRUULLEESS +CSV RULES The following six kinds of rule can appear in the rules file, in any order. Blank lines and lines beginning with # or ; are ignored. - sskkiipp - skip_N + skip + skipN Skip this number of CSV records at the beginning. You'll need this whenever your CSV data contains header lines. Eg: @@ -31,8 +31,8 @@ CCSSVV RRUULLEESS # ignore the first CSV line skip 1 - ddaattee--ffoorrmmaatt - date-format_D_A_T_E_F_M_T + date-format + date-formatDATEFMT When your CSV date fields are not formatted like YYYY/MM/DD (or YYYY-MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT @@ -51,8 +51,8 @@ CCSSVV RRUULLEESS # for dates like "11/6/2013 11:32 PM": date-format %-m/%-d/%Y %l:%M %p - ffiieelldd lliisstt - fields_F_I_E_L_D_N_A_M_E_1_, _F_I_E_L_D_N_A_M_E_2_._._. + field list + fieldsFIELDNAME1, FIELDNAME2... This (a) names the CSV fields, in order (names may not contain white- space, but may be omitted), and (b) assigns them to journal entry @@ -68,8 +68,8 @@ CCSSVV RRUULLEESS # entry field: fields date, description, , amount, , , somefield, anotherfield - ffiieelldd aassssiiggnnmmeenntt - _E_N_T_R_Y_F_I_E_L_D_N_A_M_E _F_I_E_L_D_V_A_L_U_E + field assignment + ENTRYFIELDNAME FIELDVALUE This sets a journal entry field (one of the standard names above) to the given text value, which can include CSV field values interpolated @@ -85,14 +85,14 @@ CCSSVV RRUULLEESS Field assignments can be used instead of or in addition to a field list. - ccoonnddiittiioonnaall bblloocckk - if _P_A_T_T_E_R_N - _F_I_E_L_D_A_S_S_I_G_N_M_E_N_T_S_._._. + conditional block + if PATTERN + FIELDASSIGNMENTS... if - _P_A_T_T_E_R_N - _P_A_T_T_E_R_N_._._. - _F_I_E_L_D_A_S_S_I_G_N_M_E_N_T_S_._._. + PATTERN + PATTERN... + FIELDASSIGNMENTS... This applies one or more field assignments, only to those CSV records matched by one of the PATTERNs. The patterns are case-insensitive reg- @@ -114,8 +114,8 @@ CCSSVV RRUULLEESS account2 expenses:business:banking comment XXX deductible ? check it - iinncclluuddee - include_R_U_L_E_S_F_I_L_E + include + includeRULESFILE Include another rules file at this point. RULESFILE is either an abso- lute file path or a path relative to the current file's directory. Eg: @@ -123,7 +123,7 @@ CCSSVV RRUULLEESS # rules reused with several CSV files include common.rules -TTIIPPSS +TIPS Each generated journal entry will have two postings, to account1 and account2 respectively. Currently it's not possible to generate entries with more than two postings. @@ -143,21 +143,21 @@ TTIIPPSS -RREEPPOORRTTIINNGG BBUUGGSS +REPORTING BUGS Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) -AAUUTTHHOORRSS +AUTHORS Simon Michael and contributors -CCOOPPYYRRIIGGHHTT +COPYRIGHT Copyright (C) 2007-2016 Simon Michael. Released under GNU GPL v3 or later. -SSEEEE AALLSSOO +SEE ALSO 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-lib/doc/hledger_journal.5.txt b/hledger-lib/doc/hledger_journal.5.txt index 8b4e35b55..213d7a19b 100644 --- a/hledger-lib/doc/hledger_journal.5.txt +++ b/hledger-lib/doc/hledger_journal.5.txt @@ -3,10 +3,10 @@ hledger_journal(5) hledger User Manuals hledger_journal(5) -NNAAMMEE +NAME Journal - hledger's default file format, representing a General Journal -DDEESSCCRRIIPPTTIIOONN +DESCRIPTION hledger's usual data source is a plain text file containing journal entries in hledger journal format. This file represents a standard accounting general journal. I use file names ending in .journal, but @@ -51,37 +51,37 @@ DDEESSCCRRIIPPTTIIOONN liabilities:debts $1 assets:bank:checking -FFIILLEE FFOORRMMAATT - TTrraannssaaccttiioonnss +FILE FORMAT + Transactions Transactions are represented by journal entries. Each begins with a simple date in column 0, followed by three optional fields with spaces between them: - +o a status flag, which can be empty or ! or * (meaning "uncleared", + o a status flag, which can be empty or ! or * (meaning "uncleared", "pending" and "cleared", or whatever you want) - +o a transaction code (eg a check number), + o a transaction code (eg a check number), - +o and/or a description + o and/or a description then some number of postings, of some amount to some account. Each posting is on its own line, consisting of: - +o indentation of one or more spaces (or tabs) + o indentation of one or more spaces (or tabs) - +o optionally, a ! or * status flag followed by a space + o optionally, a ! or * status flag followed by a space - +o an account name, optionally containing single spaces + o an account name, optionally containing single spaces - +o optionally, two or more spaces or tabs followed by an amount + o optionally, two or more spaces or tabs followed by an amount Usually there are two or more postings, though one or none is also pos- sible. The posting amounts within a transaction must always balance, ie add up to 0. Optionally one amount can be left blank, in which case it will be inferred. - DDaatteess - SSiimmppllee ddaatteess + Dates + Simple dates Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) Leading zeros are optional. The year may be omitted, in which case it will be inferred from the context - the current transaction, the @@ -89,7 +89,7 @@ FFIILLEE FFOORRMMAATT when the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31, 2010.1.31. - SSeeccoonnddaarryy ddaatteess + Secondary dates Real-life transactions sometimes involve more than one date - eg the date you write a cheque, and the date it clears in your bank. When you want to model this, eg for more accurate balances, you can specify @@ -125,7 +125,7 @@ FFIILLEE FFOORRMMAATT ibility, but posting dates are a more powerful and less confusing alternative. - PPoossttiinngg ddaatteess + Posting dates You can give individual postings a different date from their parent transaction, by adding a posting comment containing a tag (see below) like date:DATE. This is probably the best way to control posting dates @@ -155,21 +155,21 @@ FFIILLEE FFOORRMMAATT With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE. - AAccccoouunntt nnaammeess + Account names Account names typically have several parts separated by a full colon, from which hledger derives a hierarchical chart of accounts. They can be anything you like, but in finance there are traditionally five top-level accounts: assets, liabilities, income, expenses, and equity. Account names may contain single spaces, eg: assets:accounts receiv- - able. Because of this, they must always be followed by ttwwoo oorr mmoorree - ssppaacceess (or newline). + able. Because of this, they must always be followed by two or more + spaces (or newline). Account names can be aliased. - AAmmoouunnttss + Amounts After the account name, there is usually an amount. Important: between - account name and amount, there must be ttwwoo oorr mmoorree ssppaacceess. + account name and amount, there must be two or more spaces. Amounts consist of a number and (usually) a currency symbol or commod- ity name. Some examples: @@ -184,16 +184,16 @@ FFIILLEE FFOORRMMAATT As you can see, the amount format is somewhat flexible: - +o amounts are a number (the "quantity") and optionally a currency sym- + o amounts are a number (the "quantity") and optionally a currency sym- bol/commodity name (the "commodity"). - +o the commodity is a symbol, word, or double-quoted phrase, on the left + o the commodity is a symbol, word, or double-quoted phrase, on the left or right, with or without a separating space - +o negative amounts with a commodity on the left can have the minus sign + o negative amounts with a commodity on the left can have the minus sign before or after it - +o digit groups (thousands, or any other grouping) can be separated by + o digit groups (thousands, or any other grouping) can be separated by commas (in which case period is used for decimal point) or periods (in which case comma is used for decimal point) @@ -202,14 +202,14 @@ FFIILLEE FFOORRMMAATT commodity. (Except for price amounts, which are always formatted as written). The display format is chosen as follows: - +o if there is a commodity directive specifying the format, that is used + o if there is a commodity directive specifying the format, that is used - +o otherwise the format is inferred from the first posting amount in + o otherwise the format is inferred from the first posting amount in that commodity in the journal, and the precision (number of decimal places) will be the maximum from all posting amounts in that commmod- ity - +o or if there are no such amounts in the journal, a default format is + o or if there are no such amounts in the journal, a default format is used (like $1000.00). Price amounts and amounts in D directives usually don't affect amount @@ -219,13 +219,13 @@ FFIILLEE FFOORRMMAATT when -V is used.) If you find this causing problems, set the desired format with a commodity directive. - VViirrttuuaall PPoossttiinnggss + Virtual Postings When you parenthesise the account name in a posting, we call that a - _v_i_r_t_u_a_l _p_o_s_t_i_n_g, which means: + virtual posting, which means: - +o it is ignored when checking that the transaction is balanced + o it is ignored when checking that the transaction is balanced - +o it is excluded from reports when the --real/-R flag is used, or the + o it is excluded from reports when the --real/-R flag is used, or the real:1 query. You could use this, eg, to set an account's opening balance without @@ -234,8 +234,8 @@ FFIILLEE FFOORRMMAATT 1/1 special unbalanced posting to set initial balance (assets:checking) $1000 - When the account name is bracketed, we call it a _b_a_l_a_n_c_e_d _v_i_r_t_u_a_l _p_o_s_t_- - _i_n_g. This is like an ordinary virtual posting except the balanced vir- + When the account name is bracketed, we call it a balanced virtual post- + ing. This is like an ordinary virtual posting except the balanced vir- tual postings in a transaction must balance to 0, like the real post- ings (but separately from them). Balanced virtual postings are also excluded by --real/-R or real:1. @@ -250,7 +250,7 @@ FFIILLEE FFOORRMMAATT usually find an equivalent journal entry using real postings, which is more correct and provides better error checking. - BBaallaannccee AAsssseerrttiioonnss + Balance Assertions hledger supports ledger-style balance assertions in journal files. These look like =EXPECTEDBALANCE following a posting's amount. Eg in this example we assert the expected dollar balance in accounts a and b @@ -271,7 +271,7 @@ FFIILLEE FFOORRMMAATT --ignore-assertions flag, which can be useful for troubleshooting or for reading Ledger files. - AAsssseerrttiioonnss aanndd oorrddeerriinngg + Assertions and ordering hledger sorts an account's postings and assertions first by date and then (for postings on the same day) by parse order. Note this is dif- ferent from Ledger, which sorts assertions only by parse order. (Also, @@ -291,7 +291,7 @@ FFIILLEE FFOORRMMAATT files, and you also want to assert the account's balance on the same day, you'll have to put the assertion in the right file. - AAsssseerrttiioonnss aanndd ccoommmmooddiittiieess + Assertions and commodities The asserted balance must be a simple single-commodity amount, and in fact the assertion checks only this commodity's balance within the (possibly multi-commodity) account balance. We could call this a par- @@ -305,7 +305,7 @@ FFIILLEE FFOORRMMAATT account does not contain some unexpected commodity. (We'll add support for this kind of total balance assertion if there's demand.) - AAsssseerrttiioonnss aanndd ssuubbaaccccoouunnttss + Assertions and subaccounts Balance assertions do not count the balance from subaccounts; they check the posted account's exclusive balance. For example: @@ -323,12 +323,12 @@ FFIILLEE FFOORRMMAATT -------------------- 2 - AAsssseerrttiioonnss aanndd vviirrttuuaall ppoossttiinnggss + Assertions and virtual postings Balance assertions are checked against all postings, both real and vir- tual. They are not affected by the --real/-R flag or real: query. - PPrriicceess - TTrraannssaaccttiioonn pprriicceess + Prices + Transaction prices When recording a transaction, you can also record an amount's price in another commodity. This documents the exchange rate, cost (of a pur- chase), or selling price (of a sale) that was in effect within this @@ -345,13 +345,13 @@ FFIILLEE FFOORRMMAATT amount: 2009/1/1 - assets:foreign currency ^a~100 @ $1.35 ; one hundred euros at $1.35 each + assets:foreign currency 100 @ $1.35 ; one hundred euros at $1.35 each assets:cash 2. Or write the total price, as @@ TOTALPRICE after the amount: 2009/1/1 - assets:foreign currency ^a~100 @@ $135 ; one hundred euros at $135 for the lot + assets:foreign currency 100 @@ $135 ; one hundred euros at $135 for the lot assets:cash 3. Or let hledger infer the price so as to balance the transaction. To @@ -359,7 +359,7 @@ FFIILLEE FFOORRMMAATT sum must have a non-zero amount in exactly two commodities: 2009/1/1 - assets:foreign currency ^a~100 ; one hundred euros + assets:foreign currency 100 ; one hundred euros assets:cash $-135 ; exchanged for $135 With any of the above examples we get: @@ -372,7 +372,7 @@ FFIILLEE FFOORRMMAATT Example use for transaction prices: recording the effective conversion rate of purchases made in a foreign currency. - MMaarrkkeett pprriicceess + Market prices Market prices are not tied to a particular transaction; they represent historical exchange rates between two commodities, usually from some public market which publishes such rates. @@ -392,12 +392,12 @@ FFIILLEE FFOORRMMAATT was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and unknown before 2009). - P 2009/1/1 ^a~ $1.35 - P 2010/1/1 ^a~ $1.40 + P 2009/1/1 $1.35 + P 2010/1/1 $1.40 Example use for market prices: tracking the value of stocks. - CCoommmmeennttss + Comments Lines in the journal beginning with a semicolon (;) or hash (#) or asterisk (*) are comments, and will be ignored. (Asterisk comments make it easy to treat your journal like an org-mode outline in emacs.) @@ -432,8 +432,8 @@ FFIILLEE FFOORRMMAATT ; another comment line for posting 2 ; a journal comment (because not indented) - TTaaggss - A _t_a_g is a word followed by a full colon inside a transaction or post- + Tags + A tag is a word followed by a full colon inside a transaction or post- ing comment. You can write multiple tags, comma separated. Eg: ; a comment containing sometag:, anothertag:. You can search for tags with the tag: query. @@ -454,25 +454,25 @@ FFIILLEE FFOORRMMAATT Tags are like Ledger's metadata feature, except hledger's tag values are simple strings. - DDiirreeccttiivveess - AAccccoouunntt aalliiaasseess + Directives + Account aliases You can define aliases which rewrite your account names (after reading the journal, before generating reports). hledger's account aliases can be useful for: - +o expanding shorthand account names to their full form, allowing easier + o expanding shorthand account names to their full form, allowing easier data entry and a less verbose journal - +o adapting old journals to your current chart of accounts + o adapting old journals to your current chart of accounts - +o experimenting with new account organisations, like a new hierarchy or + o experimenting with new account organisations, like a new hierarchy or combining two accounts into one - +o customising reports + o customising reports See also How to use account aliases. - BBaassiicc aalliiaasseess + Basic aliases To set an account alias, use the alias directive in your journal file. This affects all subsequent journal entries in the current file or its included files. The spaces around the = are optional: @@ -489,7 +489,7 @@ FFIILLEE FFOORRMMAATT alias checking = assets:bank:wells fargo:checking # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" - RReeggeexx aalliiaasseess + Regex aliases There is also a more powerful variant that uses a regular expression, indicated by the forward slashes. (This was the default behaviour in hledger 0.24-0.25): @@ -508,7 +508,7 @@ FFIILLEE FFOORRMMAATT alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" - MMuullttiippllee aalliiaasseess + Multiple aliases You can define as many aliases as you like using directives or com- mand-line options. Aliases are recursive - each alias sees the result of applying previous ones. (This is different from Ledger, where @@ -520,13 +520,13 @@ FFIILLEE FFOORRMMAATT 2. alias options, in the order they appear on the command line - eenndd aalliiaasseess + end aliases You can clear (forget) all currently defined aliases with the end aliases directive: end aliases - aaccccoouunntt ddiirreeccttiivvee + account directive The account directive predefines account names, as in Ledger and Bean- count. This may be useful for your own documentation; hledger doesn't make use of it yet. @@ -542,7 +542,7 @@ FFIILLEE FFOORRMMAATT ; etc. - aappppllyy aaccccoouunntt ddiirreeccttiivvee + apply account directive You can specify a parent account which will be prepended to all accounts within a section of the journal. Use the apply account and end apply account directives like so: @@ -573,11 +573,11 @@ FFIILLEE FFOORRMMAATT Prior to hledger 0.28, legacy account and end spellings were also sup- ported. - MMuullttii--lliinnee ccoommmmeennttss + Multi-line comments A line containing just comment starts a multi-line comment, and a line containing just end comment ends it. See comments. - ccoommmmooddiittyy ddiirreeccttiivvee + commodity directive The commodity directive predefines commodities (currently this is just informational), and also it may define the display format for amounts in this commodity (overriding the automatically inferred format). @@ -604,14 +604,14 @@ FFIILLEE FFOORRMMAATT commodity INR format INR 9,99,99,999.00 - DDeeffaauulltt ccoommmmooddiittyy + Default commodity You can set a default commodity, to be used for amounts without one. Use the D directive with a sample amount. The commodity (and the sam- ple amount's display format) will be applied to all subsequent commod- ity-less amounts, up to the next D directive. (Note this is different from Ledger's default commodity directive.) - DDeeffaauulltt yyeeaarr + Default year You can set a default year to be used for subsequent dates which don't specify a year. This is a line beginning with Y followed by the year. Eg: @@ -632,7 +632,7 @@ FFIILLEE FFOORRMMAATT expenses 1 assets - IInncclluuddiinngg ootthheerr ffiilleess + Including other files You can pull in the content of additional journal files by writing an include directive, like this: @@ -644,7 +644,7 @@ FFIILLEE FFOORRMMAATT The include directive can only be used in journal files. It can include journal, timeclock or timedot files, but not CSV files. -EEDDIITTOORR SSUUPPPPOORRTT +EDITOR SUPPORT Add-on modes exist for various text editors, to make working with jour- nal files easier. They add colour, navigation aids and helpful com- mands. For hledger users who edit the journal file directly (the @@ -654,33 +654,34 @@ EEDDIITTOORR SSUUPPPPOORRTT files: - tab(@); lw(16.5n) lw(51.5n). T{ Emacs T}@T{ - http://www.ledger-cli.org/3.0/doc/ledger-mode.html T} T{ Vim T}@T{ - https://github.com/ledger/ledger/wiki/Getting-started T} T{ Sublime - Text T}@T{ https://github.com/ledger/ledger/wiki/Using-Sublime-Text T} - T{ Textmate T}@T{ https://github.com/ledger/ledger/wiki/Using-Text- - Mate-2 T} T{ Text Wrangler T}@T{ - https://github.com/ledger/ledger/wiki/Editing-Ledger-files-with-Tex- - tWrangler T} + Emacs http://www.ledger-cli.org/3.0/doc/ledger-mode.html + Vim https://github.com/ledger/ledger/wiki/Get- + ting-started + Sublime Text https://github.com/ledger/ledger/wiki/Using-Sub- + lime-Text + Textmate https://github.com/ledger/ledger/wiki/Using-Text- + Mate-2 + Text Wrangler https://github.com/ledger/ledger/wiki/Edit- + ing-Ledger-files-with-TextWrangler -RREEPPOORRTTIINNGG BBUUGGSS - Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel +REPORTING BUGS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) -AAUUTTHHOORRSS +AUTHORS Simon Michael and contributors -CCOOPPYYRRIIGGHHTT +COPYRIGHT Copyright (C) 2007-2016 Simon Michael. Released under GNU GPL v3 or later. -SSEEEE AALLSSOO - hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), +SEE ALSO + 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-lib/doc/hledger_timeclock.5.txt b/hledger-lib/doc/hledger_timeclock.5.txt index bbef91b64..6a08591f0 100644 --- a/hledger-lib/doc/hledger_timeclock.5.txt +++ b/hledger-lib/doc/hledger_timeclock.5.txt @@ -3,10 +3,10 @@ hledger_timeclock(5) hledger User Manuals hledger_timeclock(5) -NNAAMMEE +NAME Timeclock - the time logging format of timeclock.el, as read by hledger -DDEESSCCRRIIPPTTIIOONN +DESCRIPTION hledger can read timeclock files. As with Ledger, these are (a subset of) timeclock.el's format, containing clock-in and clock-out entries as in the example below. The date is a simple date. The time format is @@ -42,35 +42,35 @@ DDEESSCCRRIIPPTTIIOONN To generate time logs, ie to clock in and clock out, you could: - +o use emacs and the built-in timeclock.el, or the extended time- + o use emacs and the built-in timeclock.el, or the extended time- clock-x.el and perhaps the extras in ledgerutils.el - +o at the command line, use these bash aliases: + o at the command line, use these bash aliases: alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" - +o or use the old ti and to scripts in the ledger 2.x repository. These + o or use the old ti and to scripts in the ledger 2.x repository. These rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. -RREEPPOORRTTIINNGG BBUUGGSS +REPORTING BUGS Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) -AAUUTTHHOORRSS +AUTHORS Simon Michael and contributors -CCOOPPYYRRIIGGHHTT +COPYRIGHT Copyright (C) 2007-2016 Simon Michael. Released under GNU GPL v3 or later. -SSEEEE AALLSSOO +SEE ALSO 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-lib/doc/hledger_timedot.5.txt b/hledger-lib/doc/hledger_timedot.5.txt index 1d4f2984d..e87af8f56 100644 --- a/hledger-lib/doc/hledger_timedot.5.txt +++ b/hledger-lib/doc/hledger_timedot.5.txt @@ -3,10 +3,10 @@ hledger_timedot(5) hledger User Manuals hledger_timedot(5) -NNAAMMEE +NAME Timedot - hledger's human-friendly time logging format -DDEESSCCRRIIPPTTIIOONN +DESCRIPTION Timedot is a plain text format for logging dated, categorised quanti- ties (eg time), supported by hledger. It is convenient for approximate and retroactive time logging, eg when the real-time clock-in/out @@ -19,7 +19,7 @@ DDEESSCCRRIIPPTTIIOONN you could record a single-entry journal of financial transactions, per- haps slightly more conveniently than with hledger_journal(5) format. -FFIILLEE FFOORRMMAATT +FILE FORMAT A timedot file contains a series of day entries. A day entry begins with a date, and is followed by category/quantity pairs, one per line. Dates are hledger-style simple dates (see hledger_journal(5)). Cate- @@ -97,21 +97,21 @@ FFIILLEE FFOORRMMAATT -RREEPPOORRTTIINNGG BBUUGGSS +REPORTING BUGS Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) -AAUUTTHHOORRSS +AUTHORS Simon Michael and contributors -CCOOPPYYRRIIGGHHTT +COPYRIGHT Copyright (C) 2007-2016 Simon Michael. Released under GNU GPL v3 or later. -SSEEEE AALLSSOO +SEE ALSO 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-ui/doc/hledger-ui.1.txt b/hledger-ui/doc/hledger-ui.1.txt index 8eebebb1c..660bbb388 100644 --- a/hledger-ui/doc/hledger-ui.1.txt +++ b/hledger-ui/doc/hledger-ui.1.txt @@ -3,14 +3,14 @@ hledger-ui(1) hledger User Manuals hledger-ui(1) -NNAAMMEE +NAME hledger-ui - curses-style interface for the hledger accounting tool -SSYYNNOOPPSSIISS +SYNOPSIS hledger-ui [OPTIONS] [QUERYARGS] hledger ui -- [OPTIONS] [QUERYARGS] -DDEESSCCRRIIPPTTIIOONN +DESCRIPTION hledger is a cross-platform program for tracking money, time, or any other commodity, using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with @@ -28,110 +28,110 @@ DDEESSCCRRIIPPTTIIOONN C:/Users/USER/.hledger.journal). For more about this see hledger(1), hledger_journal(5) etc. -OOPPTTIIOONNSS +OPTIONS Note: if invoking hledger-ui as a hledger subcommand, write -- before options as shown above. Any QUERYARGS are interpreted as a hledger search query which filters the data. - ----ffllaatt show full account names, unindented + --flat show full account names, unindented - ----nnoo--eelliiddee + --no-elide don't compress empty parent accounts on one line - ----rreeggiisstteerr==AACCCCTTRREEGGEEXX + --register=ACCTREGEX start in the (first) matched account's register screen - ----tthheemmee==ddeeffaauulltt||tteerrmmiinnaall||ggrreeeenntteerrmm + --theme=default|terminal|greenterm use this custom display theme - --VV ----vvaalluuee + -V --value show amounts as their current market value in their default val- uation commodity (accounts screen only) hledger general options: - --hh show general usage (or after COMMAND, the command's usage) + -h show general usage (or after COMMAND, the command's usage) - ----hheellpp show the current program's manual as plain text (or after an + --help show the current program's manual as plain text (or after an add-on COMMAND, the add-on's manual) - ----mmaann show the current program's manual with man + --man show the current program's manual with man - ----iinnffoo show the current program's manual with info + --info show the current program's manual with info - ----vveerrssiioonn + --version show version - ----ddeebbuugg==NN + --debug=N show debug output if N is 1-9 (default: 0) - --ff FFIILLEE ----ffiillee==FFIILLEE + -f FILE --file=FILE use a different input file. For stdin, use - - ----rruulleess--ffiillee==RRUULLEESSFFIILLEE + --rules-file=RULESFILE Conversion rules file to use when reading CSV (default: FILE.rules) - ----aalliiaass==OOLLDD==NNEEWW + --alias=OLD=NEW display accounts named OLD as NEW - ----iiggnnoorree--aasssseerrttiioonnss + --ignore-assertions ignore any failing balance assertions in the journal hledger reporting options: - --bb ----bbeeggiinn==DDAATTEE + -b --begin=DATE include postings/txns on or after this date - --ee ----eenndd==DDAATTEE + -e --end=DATE include postings/txns before this date - --DD ----ddaaiillyy + -D --daily multiperiod/multicolumn report by day - --WW ----wweeeekkllyy + -W --weekly multiperiod/multicolumn report by week - --MM ----mmoonntthhllyy + -M --monthly multiperiod/multicolumn report by month - --QQ ----qquuaarrtteerrllyy + -Q --quarterly multiperiod/multicolumn report by quarter - --YY ----yyeeaarrllyy + -Y --yearly multiperiod/multicolumn report by year - --pp ----ppeerriioodd==PPEERRIIOODDEEXXPP + -p --period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) - ----ddaattee22 + --date2 show, and match with -b/-e/-p/date:, secondary dates instead - --CC ----cclleeaarreedd + -C --cleared include only cleared postings/txns - ----ppeennddiinngg + --pending include only pending postings/txns - --UU ----uunncclleeaarreedd + -U --uncleared include only uncleared (and pending) postings/txns - --RR ----rreeaall + -R --real include only non-virtual postings - ----ddeepptthh==NN + --depth=N hide accounts/postings deeper than N - --EE ----eemmppttyy + -E --empty show items with zero amount, normally hidden - --BB ----ccoosstt + -B --cost show amounts in their cost price's commodity - ----ppiivvoott TTAAGG + --pivot TAG will transform the journal before any other processing by replacing the account name of every posting having the tag TAG with content VALUE by the account name "TAG:VALUE". @@ -140,7 +140,7 @@ OOPPTTIIOONNSS tion. If the tag value is a multi:level:account:name the new account name will be "TAG:multi:level:account:name". -KKEEYYSS +KEYS h shows a help dialog listing all keys. (Some but not all of these also appear in the quick help at the bottom of each screen.) Press h again (or ESCAPE) to close it. @@ -171,8 +171,8 @@ KKEEYYSS Additional screen-specific keys are described below. -SSCCRREEEENNSS - AAccccoouunnttss ssccrreeeenn +SCREENS + Accounts screen This is normally the first screen displayed. It lists accounts and their balances, like hledger's balance command. By default, it shows all accounts and their latest ending balances. if you specify a query @@ -200,22 +200,22 @@ SSCCRREEEENNSS Press right or enter to view an account's transactions register. - RReeggiisstteerr ssccrreeeenn + Register screen This screen lists all transactions affecting a particular account, like a check register. Unlike hledger's register command (which lists indi- vidual postings), in hledger-ui's register: - +o Each line represents a whole transaction. + o Each line represents a whole transaction. - +o For each transaction, it shows the other account(s) involved, in + o For each transaction, it shows the other account(s) involved, in abbreviated form. (If there are both real and virtual postings, it shows only the accounts affected by real postings.) - +o It shows the overall change to the current account's balance from + o It shows the overall change to the current account's balance from each transaction; positive for an inflow to this account, negative for an outflow. - +o When no query other than a date limit is in effect, it shows the cur- + o When no query other than a date limit is in effect, it shows the cur- rent account's historic balance as of the transaction date. Other- wise it shows a running total starting from zero. Eg, these will show historic balances: @@ -231,6 +231,8 @@ SSCCRREEEENNSS $ hledger-ui --begin 'this month' desc:market $ hledger-ui --register checking --cleared + Filtering by account name is not very useful on this screen yet. + C toggles cleared mode, in which uncleared transactions and postings are not shown. U toggles uncleared mode, in which only uncleared transactions/postings are shown. @@ -241,12 +243,9 @@ SSCCRREEEENNSS change are shown (hledger-ui shows zero items by default, unlike com- mand-line hledger). - Press right (or enter) to view the selected transaction in full detail. + Press right (or enter) to view the selected transaction in detail. - Note, filter queries which filter by account name are not very useful - on this screen yet. - - TTrraannssaaccttiioonn ssccrreeeenn + Transaction screen This screen shows a single transaction, as a general journal entry, similar to hledger's print command and journal format (hledger_jour- nal(5)). @@ -264,26 +263,26 @@ SSCCRREEEENNSS them is the transaction's position within the complete unfiltered jour- nal, which is a more stable id (at least until the next reload). - EErrrroorr ssccrreeeenn + Error screen This screen will appear if there is a problem, such as a parse error, when you press g to reload. Once you have fixed the problem, press g again to reload and resume normal operation. (Or, you can press escape to cancel the reload attempt.) -EENNVVIIRROONNMMEENNTT - CCOOLLUUMMNNSS The screen width to use. Default: the full terminal width. +ENVIRONMENT + COLUMNS The screen width to use. Default: the full terminal width. - LLEEDDGGEERR__FFIILLEE The journal file path when not specified with -f. Default: + LEDGER_FILE The journal file path when not specified with -f. Default: ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). -FFIILLEESS +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 C:/Users/USER/.hledger.journal). -BBUUGGSS +BUGS The need to precede options with -- when invoked from hledger is awk- ward. @@ -301,21 +300,21 @@ BBUUGGSS -RREEPPOORRTTIINNGG BBUUGGSS +REPORTING BUGS Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) -AAUUTTHHOORRSS +AUTHORS Simon Michael and contributors -CCOOPPYYRRIIGGHHTT +COPYRIGHT Copyright (C) 2007-2016 Simon Michael. Released under GNU GPL v3 or later. -SSEEEE AALLSSOO +SEE ALSO 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-web/doc/hledger-web.1.txt b/hledger-web/doc/hledger-web.1.txt index e53225c2a..fbdd83983 100644 --- a/hledger-web/doc/hledger-web.1.txt +++ b/hledger-web/doc/hledger-web.1.txt @@ -3,16 +3,16 @@ hledger-web(1) hledger User Manuals hledger-web(1) -NNAAMMEE +NAME hledger-web - web interface for the hledger accounting tool -SSYYNNOOPPSSIISS +SYNOPSIS hledger-web [OPTIONS] hledger web -- [OPTIONS] -DDEESSCCRRIIPPTTIIOONN +DESCRIPTION hledger is a cross-platform program for tracking money, time, or any other commodity, using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with @@ -72,23 +72,23 @@ DDEESSCCRRIIPPTTIIOONN the next request. If a change makes the file unparseable, hledger-web will show an error until the file has been fixed. -OOPPTTIIOONNSS +OPTIONS Note: if invoking hledger-web as a hledger subcommand, write -- before options as shown above. - ----sseerrvveerr + --server disable browser-opening and auto-exit-on-idle, and log all requests to stdout - ----ppoorrtt==PPOORRTT + --port=PORT set the TCP port to listen on (default: 5000) - ----bbaassee--uurrll==UURRLL + --base-url=URL set the base url (default: http://localhost:PORT). You would change this when sharing over the network, or integrating within a larger website. - ----ffiillee--uurrll==UURRLL + --file-url=URL set the static files url (default: BASEURL/static). hledger-web normally serves static files itself, but if you wanted to serve them from another server for efficiency, you would set the url @@ -96,86 +96,86 @@ OOPPTTIIOONNSS hledger general options: - --hh show general usage (or after COMMAND, the command's usage) + -h show general usage (or after COMMAND, the command's usage) - ----hheellpp show the current program's manual as plain text (or after an + --help show the current program's manual as plain text (or after an add-on COMMAND, the add-on's manual) - ----mmaann show the current program's manual with man + --man show the current program's manual with man - ----iinnffoo show the current program's manual with info + --info show the current program's manual with info - ----vveerrssiioonn + --version show version - ----ddeebbuugg==NN + --debug=N show debug output if N is 1-9 (default: 0) - --ff FFIILLEE ----ffiillee==FFIILLEE + -f FILE --file=FILE use a different input file. For stdin, use - - ----rruulleess--ffiillee==RRUULLEESSFFIILLEE + --rules-file=RULESFILE Conversion rules file to use when reading CSV (default: FILE.rules) - ----aalliiaass==OOLLDD==NNEEWW + --alias=OLD=NEW display accounts named OLD as NEW - ----iiggnnoorree--aasssseerrttiioonnss + --ignore-assertions ignore any failing balance assertions in the journal hledger reporting options: - --bb ----bbeeggiinn==DDAATTEE + -b --begin=DATE include postings/txns on or after this date - --ee ----eenndd==DDAATTEE + -e --end=DATE include postings/txns before this date - --DD ----ddaaiillyy + -D --daily multiperiod/multicolumn report by day - --WW ----wweeeekkllyy + -W --weekly multiperiod/multicolumn report by week - --MM ----mmoonntthhllyy + -M --monthly multiperiod/multicolumn report by month - --QQ ----qquuaarrtteerrllyy + -Q --quarterly multiperiod/multicolumn report by quarter - --YY ----yyeeaarrllyy + -Y --yearly multiperiod/multicolumn report by year - --pp ----ppeerriioodd==PPEERRIIOODDEEXXPP + -p --period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) - ----ddaattee22 + --date2 show, and match with -b/-e/-p/date:, secondary dates instead - --CC ----cclleeaarreedd + -C --cleared include only cleared postings/txns - ----ppeennddiinngg + --pending include only pending postings/txns - --UU ----uunncclleeaarreedd + -U --uncleared include only uncleared (and pending) postings/txns - --RR ----rreeaall + -R --real include only non-virtual postings - ----ddeepptthh==NN + --depth=N hide accounts/postings deeper than N - --EE ----eemmppttyy + -E --empty show items with zero amount, normally hidden - --BB ----ccoosstt + -B --cost show amounts in their cost price's commodity - ----ppiivvoott TTAAGG + --pivot TAG will transform the journal before any other processing by replacing the account name of every posting having the tag TAG with content VALUE by the account name "TAG:VALUE". @@ -184,18 +184,18 @@ OOPPTTIIOONNSS tion. If the tag value is a multi:level:account:name the new account name will be "TAG:multi:level:account:name". -EENNVVIIRROONNMMEENNTT - LLEEDDGGEERR__FFIILLEE The journal file path when not specified with -f. Default: +ENVIRONMENT + LEDGER_FILE The journal file path when not specified with -f. Default: ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). -FFIILLEESS +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 C:/Users/USER/.hledger.journal). -BBUUGGSS +BUGS The need to precede options with -- when invoked from hledger is awk- ward. @@ -209,21 +209,21 @@ BBUUGGSS -RREEPPOORRTTIINNGG BBUUGGSS +REPORTING BUGS Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) -AAUUTTHHOORRSS +AUTHORS Simon Michael and contributors -CCOOPPYYRRIIGGHHTT +COPYRIGHT Copyright (C) 2007-2016 Simon Michael. Released under GNU GPL v3 or later. -SSEEEE AALLSSOO +SEE ALSO 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/doc/hledger.1.txt b/hledger/doc/hledger.1.txt index 22b4c54a9..cc4d152fb 100644 --- a/hledger/doc/hledger.1.txt +++ b/hledger/doc/hledger.1.txt @@ -3,14 +3,14 @@ hledger(1) hledger User Manuals hledger(1) -NNAAMMEE +NAME hledger - a command-line accounting tool -SSYYNNOOPPSSIISS +SYNOPSIS hledger [-f FILE] COMMAND [OPTIONS] [CMDARGS] hledger [-f FILE] ADDONCMD -- [OPTIONS] [CMDARGS] -DDEESSCCRRIIPPTTIIOONN +DESCRIPTION hledger is a cross-platform program for tracking money, time, or any other commodity, using double-entry accounting and a simple, editable file format. hledger is inspired by and largely compatible with @@ -53,7 +53,7 @@ DDEESSCCRRIIPPTTIIOONN try some commands like hledger print or hledger balance. See COMMANDS and EXAMPLES below. -EEXXAAMMPPLLEESS +EXAMPLES Two simple transactions in hledger journal format: 2015/9/30 gift received @@ -120,109 +120,145 @@ EEXXAAMMPPLLEESS 2 EUR assets:bank account -2 EUR member:John Doe -OOPPTTIIOONNSS - To see general usage and the command list: hledger -h or just hledger +OPTIONS + To see general usage and the command list: hledger -h or just hledger. + To see usage for a specific command: hledger COMMAND -h. - To see usage for a specific command: hledger COMMAND -h + hledger has several kinds of options: - Except for the General options below, options must be written after - COMMAND, not before it. + o General options are always available and can appear anywhere on the + command line. hledger -h shows these. Eg: hledger --version. - Also, when invoking external add-on commands, their options must be - written after a double hyphen. (Or, you can invoke the external com- - mand directly.) Eg: + o Common reporting options are available with most commands. These and + all other non-general options must be written after COMMAND. + hledger COMMAND -h shows these. Eg: hledger register --cleared. - $ hledger ui -- --register cash - $ hledger-ui --register cash + o Command-specific options are also provided by some commands. + hledger COMMAND -h shows these too. Eg: hledger register --average. - Options and command arguments can be intermixed. Arguments are usually - interpreted as a search query which filters the data, see QUERIES. + o Some hledger commands come from separate add-on executables, which + have their own options. hledger COMMAND -h shows these, as usual. + Such options, if not also supported by hledger, should be written + following a double hyphen argument (--) so that hledger's option + parser does not complain. Eg: hledger ui -- --register=checking. + Or, you can just run the add-on directly: hledger-ui --regis- + ter=checking. - There are three kinds of options. General options are always available - and can appear anywhere in the command line: + Command arguments may also follow the command name. In most cases + these specify a query which filters the data. Command options and + arguments can be intermixed. - --hh show general usage (or after COMMAND, the command's usage) + Option and argument values containing problematic characters should be + escaped with double quotes, backslashes, or (best) single quotes. This + means spaces, but also characters which are significant to your command + shell, such as less-than/greater-than. Eg: hledger regis- + ter -p 'last year' "accounts receivable (receiv- + able|payable)" amt:\>100. - ----hheellpp show the current program's manual as plain text (or after an + Characters which are significant to the shell and also in regular + expressions, like parentheses, the pipe symbol and the dollar sign, + must sometimes be double-escaped. Eg, to match the dollar symbol: + hledger balance cur:'\$' or hledger balance cur:\\$. + + There's more.. options and arguments being passed by hledger to an + add-on executable get de-escaped once in the process. In this case you + might need triple-escaping. Eg: hledger ui cur:'\\$' or + hledger ui cur:\\\\$. + + If in doubt, keep things simple: + + o write options after the command + + o enclose problematic args in single quotes + + o if needed, also add a backslash to escape regexp metacharacters + + o run add-on executables directly + + If you're really curious, add --debug 2 for troubleshooting. + + General options: + + -h show general usage (or after COMMAND, the command's usage) + + --help show the current program's manual as plain text (or after an add-on COMMAND, the add-on's manual) - ----mmaann show the current program's manual with man + --man show the current program's manual with man - ----iinnffoo show the current program's manual with info + --info show the current program's manual with info - ----vveerrssiioonn + --version show version - ----ddeebbuugg==NN + --debug=N show debug output if N is 1-9 (default: 0) - --ff FFIILLEE ----ffiillee==FFIILLEE + -f FILE --file=FILE use a different input file. For stdin, use - - ----rruulleess--ffiillee==RRUULLEESSFFIILLEE + --rules-file=RULESFILE Conversion rules file to use when reading CSV (default: FILE.rules) - ----aalliiaass==OOLLDD==NNEEWW + --alias=OLD=NEW display accounts named OLD as NEW - ----iiggnnoorree--aasssseerrttiioonnss + --ignore-assertions ignore any failing balance assertions in the journal - Common reporting options are supported by most commands where applica- - ble, and individual commands may provide additional command-specific - options. Both of these must be written after the command name. + Common reporting options: - --bb ----bbeeggiinn==DDAATTEE + -b --begin=DATE include postings/txns on or after this date - --ee ----eenndd==DDAATTEE + -e --end=DATE include postings/txns before this date - --DD ----ddaaiillyy + -D --daily multiperiod/multicolumn report by day - --WW ----wweeeekkllyy + -W --weekly multiperiod/multicolumn report by week - --MM ----mmoonntthhllyy + -M --monthly multiperiod/multicolumn report by month - --QQ ----qquuaarrtteerrllyy + -Q --quarterly multiperiod/multicolumn report by quarter - --YY ----yyeeaarrllyy + -Y --yearly multiperiod/multicolumn report by year - --pp ----ppeerriioodd==PPEERRIIOODDEEXXPP + -p --period=PERIODEXP set start date, end date, and/or reporting interval all at once (overrides the flags above) - ----ddaattee22 + --date2 show, and match with -b/-e/-p/date:, secondary dates instead - --CC ----cclleeaarreedd + -C --cleared include only cleared postings/txns - ----ppeennddiinngg + --pending include only pending postings/txns - --UU ----uunncclleeaarreedd + -U --uncleared include only uncleared (and pending) postings/txns - --RR ----rreeaall + -R --real include only non-virtual postings - ----ddeepptthh==NN + --depth=N hide accounts/postings deeper than N - --EE ----eemmppttyy + -E --empty show items with zero amount, normally hidden - --BB ----ccoosstt + -B --cost show amounts in their cost price's commodity - ----ppiivvoott TTAAGG + --pivot TAG will transform the journal before any other processing by replacing the account name of every posting having the tag TAG with content VALUE by the account name "TAG:VALUE". @@ -231,22 +267,22 @@ OOPPTTIIOONNSS tion. If the tag value is a multi:level:account:name the new account name will be "TAG:multi:level:account:name". - MMuullttiippllee ffiilleess + Multiple files You can specify multiple -f/--file FILE options. This is like combin- ing all the files into one, except they can have different formats. Also directives and aliases in one file do not affect subsequent files (if you need that, use the include directive instead). - RReeppeeaatteedd ooppttiioonnss + Repeated options Otherwise, if a reporting option is repeated, the last one takes prece- dence. Eg -p jan -p feb is equivalent to -p feb. - DDeepptthh lliimmiittiinngg + Depth limiting With the --depth N option, commands like account, balance and register will show only the uppermost accounts in the account tree, down to level N. Use this when you want a summary with less detail. - SSmmaarrtt ddaatteess + Smart dates hledger's user interfaces accept a flexible "smart date" syntax (unlike dates in the journal file). Smart dates allow some english words, can be relative to today's date, and can have less-significant date parts @@ -255,24 +291,30 @@ OOPPTTIIOONNSS Examples: - tab(@); l l. T{ 2009/1/1, 2009/01/01, 2009-1-1, 2009.1.1 T}@T{ simple - dates, several separators allowed T} T{ 2009/1, 2009 T}@T{ same as - above - a missing day or month defaults to 1 T} T{ 1/1, january, jan, - this year T}@T{ relative dates, meaning january 1 of the current year - T} T{ next year T}@T{ january 1 of next year T} T{ this month T}@T{ the - 1st of the current month T} T{ this week T}@T{ the most recent monday - T} T{ last week T}@T{ the monday of the week before this one T} T{ - lastweek T}@T{ spaces are optional T} T{ today, yesterday, tomorrow - T}@T{ T} + 2009/1/1, 2009/01/01, simple dates, several sep- + 2009-1-1, 2009.1.1 arators allowed + 2009/1, 2009 same as above - a missing + day or month defaults to 1 + 1/1, january, jan, relative dates, meaning + this year january 1 of the current + year + next year january 1 of next year + this month the 1st of the current + month + this week the most recent monday + last week the monday of the week + before this one + lastweek spaces are optional + today, yesterday, tomorrow - RReeppoorrttiinngg iinntteerrvvaall + Reporting interval A reporting interval can be specified so that commands like register, balance and activity will divide their reports into multiple report periods. The basic intervals can be selected with one of -D/--daily, -W/--weekly, -M/--monthly, -Q/--quarterly, or -Y/--yearly. More com- plex intervals may be specified with a period expression. - PPeerriioodd eexxpprreessssiioonnss + Period expressions The -p/--period option accepts period expressions, a shorthand way of expressing a start date, end date, and or reporting interval all at once. Note a period expression on the command line will cause any @@ -290,88 +332,100 @@ OOPPTTIIOONNSS "-". These are equivalent to the above: - tab(@); l. T{ -p "2009/1/1 2009/4/1" T} T{ -p2009/1/1to2009/4/1 T} T{ - -p2009/1/1-2009/4/1 T} + -p "2009/1/1 2009/4/1" + -p2009/1/1to2009/4/1 + -p2009/1/1-2009/4/1 - Dates are smart dates, so if the current year is 2009, the above can + Dates are smart dates, so if the current year is 2009, the above can also be written as: - tab(@); l. T{ -p "1/1 4/1" T} T{ -p "january-apr" T} T{ - -p "this year to 4/1" T} + -p "1/1 4/1" + -p "january-apr" + -p "this year to 4/1" If you specify only one date, the missing start or end date will be the earliest or latest transaction in your journal: - tab(@); l l. T{ -p "from 2009/1/1" T}@T{ everything after january 1, - 2009 T} T{ -p "from 2009/1" T}@T{ the same T} T{ -p "from 2009" T}@T{ - the same T} T{ -p "to 2009" T}@T{ everything before january 1, 2009 T} + -p "from 2009/1/1" everything after january + 1, 2009 + -p "from 2009/1" the same + -p "from 2009" the same + -p "to 2009" everything before january + 1, 2009 A single date with no "from" or "to" defines both the start and end date like so: - tab(@); l l. T{ -p "2009" T}@T{ the year 2009; equivalent to "2009/1/1 - to 2010/1/1" T} T{ -p "2009/1" T}@T{ the month of jan; equivalent to - "2009/1/1 to 2009/2/1" T} T{ -p "2009/1/1" T}@T{ just that day; equiva- - lent to "2009/1/1 to 2009/1/2" T} + -p "2009" the year 2009; equivalent + to "2009/1/1 to 2010/1/1" + -p "2009/1" the month of jan; equiva- + lent to "2009/1/1 to + 2009/2/1" + -p "2009/1/1" just that day; equivalent + to "2009/1/1 to 2009/1/2" - Period expressions can also start with (or be) a reporting interval: - daily, weekly, monthly, quarterly, yearly, or one of the every ... - expressions below. Optionally the word in may appear between the + Period expressions can also start with (or be) a reporting interval: + daily, weekly, monthly, quarterly, yearly, or one of the every ... + expressions below. Optionally the word in may appear between the reporting interval and the start/end dates. Examples: - tab(@); l. T{ -p "weekly from 2009/1/1 to 2009/4/1" T} T{ - -p "monthly in 2008" T} T{ -p "bimonthly from 2008" T} T{ -p "quar- - terly" T} T{ -p "every 2 weeks" T} T{ -p "every 5 days from 1/3" T} T{ - -p "every 15th day of month" T} T{ -p "every 4th day of week" T} + -p "weekly from 2009/1/1 to 2009/4/1" + -p "monthly in 2008" + -p "bimonthly from 2008" + -p "quarterly" + -p "every 2 weeks" + -p "every 5 days from 1/3" + -p "every 15th day of month" + -p "every 4th day of week" - RReegguullaarr EExxpprreessssiioonnss + Regular Expressions hledger uses regular expressions in a number of places: - +o query terms, on the command line and in the hledger-web search form: + o query terms, on the command line and in the hledger-web search form: REGEX, desc:REGEX, cur:REGEX, tag:...=REGEX - +o CSV rules conditional blocks: if REGEX ... + o CSV rules conditional blocks: if REGEX ... - +o account alias directives and options: alias /REGEX/ = REPLACEMENT, + o account alias directives and options: alias /REGEX/ = REPLACEMENT, --alias /REGEX/=REPLACEMENT hledger's regular expressions come from the regex-tdfa library. In general they: - +o are case insensitive + o are case insensitive - +o are infix matching (do not need to match the entire thing being + o are infix matching (do not need to match the entire thing being matched) - +o are POSIX extended regular expressions + o are POSIX extended regular expressions - +o also support GNU word boundaries (\<, \>, \b, \B) + o also support GNU word boundaries (\<, \>, \b, \B) - +o and parenthesised capturing groups and numeric backreferences in + o and parenthesised capturing groups and numeric backreferences in replacement strings - +o do not support mode modifiers like (?s) + o do not support mode modifiers like (?s) Some things to note: - +o In the alias directive and --alias option, regular expressions must + o In the alias directive and --alias option, regular expressions must be enclosed in forward slashes (/REGEX/). Elsewhere in hledger, these are not required. - +o To match a regular expression metacharacter like $ as a literal char- + o To match a regular expression metacharacter like $ as a literal char- acter, prepend a backslash. Eg to search for amounts with the dollar sign in hledger-web, write cur:\$. - +o On the command line, some metacharacters like $ have a special mean- + o On the command line, some metacharacters like $ have a special mean- ing to the shell and so must be escaped a second time, with single or double quotes or another backslash. Eg, to match amounts with the dollar sign from the command line, write cur:'\$' or cur:\\$. -QQUUEERRIIEESS +QUERIES One of hledger's strengths is being able to quickly report on precise subsets of your data. Most commands accept an optional query expres- sion, written as arguments after the command name, to filter the data @@ -383,30 +437,30 @@ QQUUEERRIIEESS All commands except print: show transactions/postings/accounts which match (or negatively match) - +o any of the description terms AND + o any of the description terms AND - +o any of the account terms AND + o any of the account terms AND - +o all the other terms. + o all the other terms. The print command: show transactions which - +o match any of the description terms AND + o match any of the description terms AND - +o have any postings matching any of the positive account terms AND + o have any postings matching any of the positive account terms AND - +o have no postings matching any of the negative account terms AND + o have no postings matching any of the negative account terms AND - +o match all the other terms. + o match all the other terms. The following kinds of search terms can be used: - RREEGGEEXX match account names by this regular expression + REGEX match account names by this regular expression - aacccctt::RREEGGEEXX + acct:REGEX same as above - aammtt::NN,, aammtt::<>NN,, aammtt::>>==NN + amt:N, amt:N, amt:>=N match postings with a single-commodity amount that is equal to, less than, or greater than N. (Multi-commodity amounts are not tested, and will always match.) The comparison has two modes: if @@ -414,10 +468,10 @@ QQUUEERRIIEESS are compared. Otherwise, the absolute magnitudes are compared, ignoring sign. - ccooddee::RREEGGEEXX + code:REGEX match by transaction code (eg check number) - ccuurr::RREEGGEEXX + cur:REGEX match postings or transactions including any amounts whose cur- rency/commodity symbol is fully matched by REGEX. (For a par- tial match, use .*REGEX.*). Note, to match characters which are @@ -426,44 +480,44 @@ QQUUEERRIIEESS level of quoting to hide it from the shell, so eg do: hledger print cur:'\$' or hledger print cur:\\$. - ddeesscc::RREEGGEEXX + desc:REGEX match transaction descriptions - ddaattee::PPEERRIIOODDEEXXPPRR + date:PERIODEXPR match dates within the specified period. PERIODEXPR should not include a reporting interval. The command-line --date2 flag makes this match secondary dates instead (like the -b/-e/-p options). - ddaattee22::PPEERRIIOODDEEXXPPRR + date2:PERIODEXPR match secondary dates within the specified period. PERIODEXPR should not include a reporting interval. - ddeepptthh::NN + depth:N match (or display, depending on command) accounts at or above this depth - rreeaall::,, rreeaall::00 + real:, real:0 match real or virtual postings respectively - ssttaattuuss::**,, ssttaattuuss::!!,, ssttaattuuss:: + status:*, status:!, status: match cleared, pending, or uncleared/pending transactions respectively - ttaagg::RREEGGEEXX[[==RREEGGEEXX]] + tag:REGEX[=REGEX] match by tag name, and optionally also by tag value. Note a tag: query is considered to match a transaction if it matches any of the postings. Also remember that postings inherit the tags of their parent transaction. - nnoott:: before any of the above negates the match. + not: before any of the above negates the match. Some of these can also be expressed as command-line options (eg depth:2 is equivalent to --depth 2). Generally you can mix options and query arguments, and the resulting query will be their intersection (perhaps excluding the -p/--period option). -CCOOMMMMAANNDDSS +COMMANDS hledger provides a number of subcommands; hledger with no arguments shows a list. @@ -476,14 +530,14 @@ CCOOMMMMAANNDDSS a command name (hledger inc), or one of the standard short aliases dis- played in the command list (hledger is). - aaccccoouunnttss + accounts Show account names. - ----ttrreeee show short account names, as a tree + --tree show short account names, as a tree - ----ffllaatt show full account names, as a list (default) + --flat show full account names, as a list (default) - ----ddrroopp==NN + --drop=N in flat mode: omit N leading account name parts This command lists all account names that are in use (ie, all the @@ -533,7 +587,7 @@ CCOOMMMMAANNDDSS income:salary liabilities:debts - aaccttiivviittyy + activity Show an ascii barchart of posting counts per interval. The activity command displays an ascii histogram showing transaction @@ -546,10 +600,10 @@ CCOOMMMMAANNDDSS 2008-07-01 2008-10-01 ** - aadddd + add Prompt for transactions and add them to the journal. - ----nnoo--nneeww--aaccccoouunnttss + --no-new-accounts don't allow creating new accounts; helps prevent typos when entering account names @@ -567,28 +621,28 @@ CCOOMMMMAANNDDSS Features: - +o add tries to provide useful defaults, using the most similar recent + o add tries to provide useful defaults, using the most similar recent transaction (by description) as a template. - +o You can also set the initial defaults with command line arguments. + o You can also set the initial defaults with command line arguments. - +o Readline-style edit keys can be used during data entry. + o Readline-style edit keys can be used during data entry. - +o The tab key will auto-complete whenever possible - accounts, descrip- + o The tab key will auto-complete whenever possible - accounts, descrip- tions, dates (yesterday, today, tomorrow). If the input area is empty, it will insert the default value. - +o If the journal defines a default commodity, it will be added to any + o If the journal defines a default commodity, it will be added to any bare numbers entered. - +o A parenthesised transaction code may be entered following a date. + o A parenthesised transaction code may be entered following a date. - +o Comments and tags may be entered following a description or amount. + o Comments and tags may be entered following a description or amount. - +o If you make a mistake, enter < at any prompt to restart the transac- + o If you make a mistake, enter < at any prompt to restart the transac- tion. - +o Input prompts are displayed in a different colour when the terminal + o Input prompts are displayed in a different colour when the terminal supports it. Example (see the tutorial for a detailed explanation): @@ -618,46 +672,46 @@ CCOOMMMMAANNDDSS Starting the next transaction (. or ctrl-D/ctrl-C to quit) Date [2015/05/22]: $ - bbaallaannccee + balance Show accounts and their balances. Alias: bal. - ----ttrreeee show short account names, as a tree + --tree show short account names, as a tree - ----ffllaatt show full account names, as a list (default) + --flat show full account names, as a list (default) - ----ddrroopp==NN + --drop=N in flat mode: omit N leading account name parts - ----ffoorrmmaatt==LLIINNEEFFOORRMMAATT + --format=LINEFORMAT in single-column balance reports: use this custom line format - ----nnoo--eelliiddee + --no-elide in tree mode: don't squash boring parent accounts - --HH ----hhiissttoorriiccaall + -H --historical in multicolumn mode: show historical ending balances - ----ccuummuullaattiivvee + --cumulative in multicolumn mode: show accumulated ending balances - --AA ----aavveerraaggee + -A --average in multicolumn mode: show a row average column - --TT ----rrooww--ttoottaall + -T --row-total in multicolumn mode: show a row total column - --NN ----nnoo--ttoottaall + -N --no-total don't show the final total row - --VV ----vvaalluuee + -V --value show amounts as their current market value in their default val- uation commodity - --oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]] + -o FILE[.FMT] --output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. - --OO FFMMTT ----oouuttppuutt--ffoorrmmaatt==FFMMTT + -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. The balance command displays accounts and balances. It is hledger's @@ -677,7 +731,7 @@ CCOOMMMMAANNDDSS -------------------- 0 - More precisely, the balance command shows the _c_h_a_n_g_e to each account's + More precisely, the balance command shows the change to each account's balance caused by all (matched) postings. In the common case where you do not filter by date and your journal sets the correct opening bal- ances, this is the same as the account's ending balance. @@ -702,7 +756,7 @@ CCOOMMMMAANNDDSS $1 food $1 supplies - FFllaatt mmooddee + Flat mode To see a flat list of full account names instead of the default hierar- chical display, use --flat. In this mode, accounts (unless depth-clipped) show their "exclusive" balance, excluding any subaccount @@ -713,7 +767,7 @@ CCOOMMMMAANNDDSS $1 food $1 supplies - DDeepptthh lliimmiitteedd bbaallaannccee rreeppoorrttss + Depth limited balance reports With --depth N, balance shows accounts only to the specified depth. This is very useful to show a complex charts of accounts in less detail. In flat mode, balances from accounts below the depth limit @@ -725,7 +779,7 @@ CCOOMMMMAANNDDSS $-2 income $1 liabilities - MMuullttiiccoolluummnn bbaallaannccee rreeppoorrttss + Multicolumn balance reports With a reporting interval, multiple balance columns will be shown, one for each report period. There are three types of multi-column balance report, showing different information: @@ -820,7 +874,7 @@ CCOOMMMMAANNDDSS # Average is rounded to the dollar here since all journal amounts are - MMaarrkkeett vvaalluuee + Market value The -V/--value flag converts all the reported amounts to their "current market value" using their default market price. That is the latest market price (P directive) found in the journal (or an included file), @@ -830,7 +884,7 @@ CCOOMMMMAANNDDSS directives, ignoring transaction prices recorded as part of posting amounts (which -B/--cost uses). Using -B and -V together is allowed. - CCuussttoomm bbaallaannccee oouuttppuutt + Custom balance output In simple (non-multi-column) balance reports, you can customise the output with --format FMT: @@ -854,27 +908,27 @@ CCOOMMMMAANNDDSS %[MIN][.MAX](FIELDNAME) - +o MIN pads with spaces to at least this width (optional) + o MIN pads with spaces to at least this width (optional) - +o MAX truncates at this width (optional) + o MAX truncates at this width (optional) - +o FIELDNAME must be enclosed in parentheses, and can be one of: + o FIELDNAME must be enclosed in parentheses, and can be one of: - +o depth_spacer - a number of spaces equal to the account's depth, or + o depth_spacer - a number of spaces equal to the account's depth, or if MIN is specified, MIN * depth spaces. - +o account - the account's name + o account - the account's name - +o total - the account's balance/posted total, right justified + o total - the account's balance/posted total, right justified Also, FMT can begin with an optional prefix to control how multi-com- modity amounts are rendered: - +o %_ - render on multiple lines, bottom-aligned (the default) + o %_ - render on multiple lines, bottom-aligned (the default) - +o %^ - render on multiple lines, top-aligned + o %^ - render on multiple lines, top-aligned - +o %, - render on one line, comma-separated + o %, - render on one line, comma-separated There are some quirks. Eg in one-line mode, %(depth_spacer) has no effect, instead %(account) has indentation built in. @@ -882,19 +936,19 @@ CCOOMMMMAANNDDSS Some example formats: - +o %(total) - the account's total + o %(total) - the account's total - +o %-20.20(account) - the account's name, left justified, padded to 20 + o %-20.20(account) - the account's name, left justified, padded to 20 characters and clipped at 20 characters - +o %,%-50(account) %25(total) - account name padded to 50 characters, + o %,%-50(account) %25(total) - account name padded to 50 characters, total padded to 20 characters, with multiple commodities rendered on one line - +o %20(total) %2(depth_spacer)%-(account) - the default format for the + o %20(total) %2(depth_spacer)%-(account) - the default format for the single-column balance report - OOuuttppuutt ddeessttiinnaattiioonn + Output destination The balance, print, register and stats commands can write their output to a destination other than the console. This is controlled by the -o/--output-file option. @@ -902,7 +956,7 @@ CCOOMMMMAANNDDSS $ hledger balance -o - # write to stdout (the default) $ hledger balance -o FILE # write to FILE - CCSSVV oouuttppuutt + CSV output The balance, print and register commands can write their output as CSV. This is useful for exporting data to other applications, eg to make charts in a spreadsheet. This is controlled by the -O/--output-format @@ -911,12 +965,12 @@ CCOOMMMMAANNDDSS $ hledger balance -O csv # write CSV to stdout $ hledger balance -o FILE.csv # write CSV to FILE.csv - bbaallaanncceesshheeeett + balancesheet Show a balance sheet. Alias: bs. - ----ffllaatt show full account names, as a list (default) + --flat show full account names, as a list (default) - ----ddrroopp==NN + --drop=N in flat mode: omit N leading account name parts This command displays a simple balance sheet. It currently assumes @@ -942,12 +996,12 @@ CCOOMMMMAANNDDSS -------------------- 0 - ccaasshhffllooww + cashflow Show a cashflow statement. Alias: cf. - ----ffllaatt show full account names, as a list (default) + --flat show full account names, as a list (default) - ----ddrroopp==NN + --drop=N in flat mode: omit N leading account name parts This command displays a simple cashflow statement It shows the change @@ -969,7 +1023,7 @@ CCOOMMMMAANNDDSS -------------------- $-1 - hheellpp + help Show any of the hledger manuals. The help command displays any of the main hledger man pages. (Unlike @@ -997,12 +1051,12 @@ CCOOMMMMAANNDDSS hledger [-f FILE] ADDONCMD -- [OPTIONS] [CMDARGS] : - iinnccoommeessttaatteemmeenntt + incomestatement Show an income statement. Alias: is. - ----ffllaatt show full account names, as a list (default) + --flat show full account names, as a list (default) - ----ddrroopp==NN + --drop=N in flat mode: omit N leading account name parts This command displays a simple income statement. It currently assumes @@ -1030,7 +1084,7 @@ CCOOMMMMAANNDDSS -------------------- 0 - iinnffoo + info Show any of the hledger manuals using info. The info command displays any of the hledger reference manuals using @@ -1041,7 +1095,7 @@ CCOOMMMMAANNDDSS As with help, run it with no arguments to list available topics (manu- als). - mmaann + man Show any of the hledger manuals using man. The man command displays any of the hledger reference manuals using @@ -1052,18 +1106,18 @@ CCOOMMMMAANNDDSS As with help, run it with no arguments to list available topics (manu- als). - pprriinntt + print Show transactions from the journal. - --mm SSTTRR ----mmaattcchh==SSTTRR + -m STR --match=STR show the transaction whose description is most similar to STR, and is most recent - --oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]] + -o FILE[.FMT] --output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. - --OO FFMMTT ----oouuttppuutt--ffoorrmmaatt==FFMMTT + -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. $ hledger print @@ -1098,28 +1152,28 @@ CCOOMMMMAANNDDSS The print command also supports output destination and CSV output. - rreeggiisstteerr + register Show postings and their running total. Alias: reg. - --HH ----hhiissttoorriiccaall + -H --historical include prior postings in the running total - --AA ----aavveerraaggee + -A --average show a running average instead of the running total (implies --empty) - --rr ----rreellaatteedd + -r --related show postings' siblings instead - --ww NN ----wwiiddtthh==NN + -w N --width=N set output width (default: terminal width or COLUMNS. -wN,M sets description width as well) - --oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]] + -o FILE[.FMT] --output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. - --OO FFMMTT ----oouuttppuutt--ffoorrmmaatt==FFMMTT + -O FMT --output-format=FMT select the output format. Supported formats: txt, csv. The register command displays postings, one per line, and their running @@ -1148,7 +1202,7 @@ CCOOMMMMAANNDDSS the whole report period). This flag implies --empty (see below). It works best when showing just one account and one commodity. - The --related/-r flag shows the _o_t_h_e_r postings in the transactions of + The --related/-r flag shows the other postings in the transactions of the postings which would normally be shown. With a reporting interval, register shows summary postings, one per @@ -1188,7 +1242,7 @@ CCOOMMMMAANNDDSS intervals. This ensures that the first and last intervals are full length and comparable to the others in the report. - CCuussttoomm rreeggiisstteerr oouuttppuutt + 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 a bash shell variable) or by using the --width/-w option. @@ -1214,10 +1268,10 @@ CCOOMMMMAANNDDSS The register command also supports the -o/--output-file and -O/--out- put-format options for controlling output destination and CSV output. - ssttaattss + stats Show some journal statistics. - --oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]] + -o FILE[.FMT] --output-file=FILE[.FMT] write output to FILE instead of stdout. A recognised FMT suffix influences the format. @@ -1240,7 +1294,7 @@ CCOOMMMMAANNDDSS The stats command also supports -o/--output-file for controlling output destination. - tteesstt + test Run built-in unit tests. $ hledger test @@ -1251,7 +1305,7 @@ CCOOMMMMAANNDDSS matching names. It's mainly used in development, but it's also nice to be able to check your hledger executable for smoke at any time. -AADDDD--OONN CCOOMMMMAANNDDSS +ADD-ON COMMANDS Add-on commands are executables in your PATH whose name starts with hledger- and ends with any of these file extensions: none, .hs,.lhs,.pl,.py,.rb,.rkt,.sh,.bat,.com,.exe. Also, an add-on's name @@ -1261,11 +1315,11 @@ AADDDD--OONN CCOOMMMMAANNDDSS you invoke them with hledger ADDONCMD. However there are some limita- tions: - +o Options appearing before ADDONCMD will be visible only to hledger and + o Options appearing before ADDONCMD will be visible only to hledger and will not be passed to the add-on. Eg: hledger -h web shows hledger's usage, hledger web -h shows hledger-web's usage. - +o Options understood only by the add-on must go after a -- argument to + o Options understood only by the add-on must go after a -- argument to hide them from hledger, which would otherwise reject them. Eg: hledger web -- --server. @@ -1279,10 +1333,10 @@ AADDDD--OONN CCOOMMMMAANNDDSS Here are some hledger add-ons available from Hackage, the extra direc- tory in the hledger source, or elsewhere: - aappii + api Web API server, see hledger-api. - aauuttoossyynncc + autosync Download OFX bank data and/or convert OFX to hledger journal format. $ hledger autosync --help @@ -1341,7 +1395,7 @@ AADDDD--OONN CCOOMMMMAANNDDSS alternative to hledger's built-in CSV reader, especially if your bank supports OFX download. - ddiiffff + diff Show transactions present in one journal file but not another $ hledger diff --help @@ -1369,7 +1423,7 @@ AADDDD--OONN CCOOMMMMAANNDDSS journal file but not in the other. This can be useful for reconciling existing journals with bank statements. - eeqquuiittyy + equity Print a journal entry that resets account balances to zero. $ hledger balance --flat -E assets liabilities @@ -1403,7 +1457,7 @@ AADDDD--OONN CCOOMMMMAANNDDSS correct asset/liability balances whether you run hledger on just one file, or on several files concatenated with include. - iinntteerreesstt + interest Generate interest transactions. $ hledger interest --help @@ -1485,10 +1539,10 @@ AADDDD--OONN CCOOMMMMAANNDDSS day-counting, such as act/act, 30/360, 30E/360, and 30/360isda. Fur- thermore, it supports a (small) number of interest schemes, i.e. annual interest with a fixed rate and the scheme mandated by the German - BGB288 (Basiszins f~A1/4r Verbrauchergesch~Aoxfte). See the package page - for more. + BGB288 (Basiszins fr Verbrauchergeschfte). See the package page for + more. - iirrrr + irr Calculate internal rate of return. $ hledger irr --help @@ -1508,33 +1562,33 @@ AADDDD--OONN CCOOMMMMAANNDDSS $ cat irr.journal 2011-01-01 Some wild speculation - I wonder if it pays off - Speculation ^a~100.00 + Speculation 100.00 Cash 2011-02-01 More speculation (and adjustment of value) - Cash -^a~10.00 - Rate Gain -^a~1.00 + Cash -10.00 + Rate Gain -1.00 Speculation 2011-03-01 Lets pull out some money (and adjustment of value) - Cash ^a~30.00 - Rate Gain -^a~3.00 + Cash 30.00 + Rate Gain -3.00 Speculation 2011-04-01 More speculation (and it lost some money!) - Cash -^a~50.00 - Rate Gain ^a~ 5.00 + Cash -50.00 + Rate Gain 5.00 Speculation 2011-05-01 Getting some money out (and adjustment of value) - Speculation -^a~44.00 - Rate Gain -^a~ 3.00 + Speculation -44.00 + Rate Gain - 3.00 Cash 2011-06-01 Emptying the account (after adjusting the value) - Speculation -^a~85.00 - Cash ^a~90.00 - Rate Gain -^a~ 5.00 + Speculation -85.00 + Cash 90.00 + Rate Gain - 5.00 $ hledger-irr -f irr.journal -t "Rate Gain" -i Speculation --monthly 2011/01/01 - 2011/02/01: 12.49% @@ -1550,7 +1604,7 @@ AADDDD--OONN CCOOMMMMAANNDDSS of fixed rate investment that would have provided the exact same cash flow. See the package page for more. - pprriinntt--uunniiqquuee + print-unique Print only only journal entries which have a unique description. $ cat unique.journal @@ -1563,7 +1617,7 @@ AADDDD--OONN CCOOMMMMAANNDDSS 2015/01/01 test (acct:one) 1 - rreewwrriittee + rewrite Prints all journal entries, adding specified custom postings to matched entries. @@ -1576,35 +1630,35 @@ AADDDD--OONN CCOOMMMMAANNDDSS $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' - uuii + ui Curses-style interface, see hledger-ui. - wweebb + web Web interface, see hledger-web. -TTRROOUUBBLLEESSHHOOOOTTIINNGG - RRuunn--ttiimmee pprroobblleemmss +TROUBLESHOOTING + Run-time problems Here are some issues you might encounter when you run hledger (and remember you can also seek help from the IRC channel, mail list or bug tracker): - SSuucccceessssffuullllyy iinnssttaalllleedd,, bbuutt ""NNoo ccoommmmaanndd ''hhlleeddggeerr'' ffoouunndd"" + 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, that is ~/.local/bin and ~/.cabal/bin respectively. - II sseett aa ccuussttoomm LLEEDDGGEERR__FFIILLEE,, bbuutt hhlleeddggeerr iiss ssttiillll uussiinngg tthhee ddeeffaauulltt ffiillee + 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 need to use export. Here's an explanation. - ""IIlllleeggaall bbyyttee sseeqquueennccee"" oorr ""IInnvvaalliidd oorr iinnccoommpplleettee mmuullttiibbyyttee oorr wwiiddee - cchhaarraacctteerr"" eerrrroorrss - In order to handle non-ascii letters and symbols (like ^A-L), 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 supports UTF-8, if you built hledger with GHC < 7.2 (or possibly - always, I'm not sure yet). + "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, + I'm not sure yet). Here's an example of setting the locale temporarily, on ubuntu gnu/linux: @@ -1640,14 +1694,14 @@ TTRROOUUBBLLEESSHHOOOOTTIINNGG Note some platforms allow variant locale spellings, but not all (ubuntu accepts fr_FR.UTF8, mac osx requires exactly fr_FR.UTF-8). - KKnnoowwnn lliimmiittaattiioonnss - CCoommmmaanndd lliinnee iinntteerrffaaccee + Known limitations + Command line interface Add-on command options, unless they are also understood by the main hledger executable, must be written after --, like this: hledger web -- --server - DDiiffffeerreenncceess ffrroomm LLeeddggeerr + Differences from Ledger Not all of Ledger's journal file syntax is supported. See file format differences. @@ -1655,7 +1709,7 @@ TTRROOUUBBLLEESSHHOOOOTTIINNGG hledger is slower than Ledger, and uses more memory, on large data files. - WWiinnddoowwss lliimmiittaattiioonnss + Windows limitations In a windows CMD window, non-ascii characters and colours are not sup- ported. @@ -1663,21 +1717,21 @@ TTRROOUUBBLLEESSHHOOOOTTIINNGG In a windows Cygwin/MSYS/Mintty window, the tab key is not supported in hledger add. -EENNVVIIRROONNMMEENNTT - CCOOLLUUMMNNSS The screen width used by the register command. Default: the +ENVIRONMENT + COLUMNS The screen width used by the register command. Default: the full terminal width. - LLEEDDGGEERR__FFIILLEE The journal file path when not specified with -f. Default: + LEDGER_FILE The journal file path when not specified with -f. Default: ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- nal). -FFIILLEESS +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 C:/Users/USER/.hledger.journal). -BBUUGGSS +BUGS The need to precede options with -- when invoked from hledger is awk- ward. @@ -1690,21 +1744,21 @@ BBUUGGSS -RREEPPOORRTTIINNGG BBUUGGSS +REPORTING BUGS Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) -AAUUTTHHOORRSS +AUTHORS Simon Michael and contributors -CCOOPPYYRRIIGGHHTT +COPYRIGHT Copyright (C) 2007-2016 Simon Michael. Released under GNU GPL v3 or later. -SSEEEE AALLSSOO +SEE ALSO 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)