From bfa5e14373a6c451d4a7971f329e80f1ae2fd6b3 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 13 Apr 2016 22:29:16 -0700 Subject: [PATCH] doc: generate (and commit) text-rendred man pages Intended for embedding in executables. Quick implementation, hopefully these are fixed-width and compatible with all terminals. --- Shake.hs | 12 +- hledger-api/doc/hledger-api.1.txt | 71 + hledger-lib/doc/hledger_csv.5.txt | 169 +++ hledger-lib/doc/hledger_journal.5.txt | 668 ++++++++++ hledger-lib/doc/hledger_timeclock.5.txt | 83 ++ hledger-lib/doc/hledger_timedot.5.txt | 125 ++ hledger-ui/doc/hledger-ui.1.txt | 258 ++++ hledger-web/doc/hledger-web.1.txt | 204 +++ hledger/doc/hledger.1.txt | 1628 +++++++++++++++++++++++ 9 files changed, 3217 insertions(+), 1 deletion(-) create mode 100644 hledger-api/doc/hledger-api.1.txt create mode 100644 hledger-lib/doc/hledger_csv.5.txt create mode 100644 hledger-lib/doc/hledger_journal.5.txt create mode 100644 hledger-lib/doc/hledger_timeclock.5.txt create mode 100644 hledger-lib/doc/hledger_timedot.5.txt create mode 100644 hledger-ui/doc/hledger-ui.1.txt create mode 100644 hledger-web/doc/hledger-web.1.txt create mode 100644 hledger/doc/hledger.1.txt diff --git a/Shake.hs b/Shake.hs index 913d267a4..2eb9842d9 100755 --- a/Shake.hs +++ b/Shake.hs @@ -44,6 +44,7 @@ usage = [i|Usage: ./Shake # show commands ./Shake site # generate things needed for the website ./Shake manpages # generate nroff files for man + ./Shake txtmanpages # generate text man pages for embedding ./Shake webmanpages # generate web man pages for hakyll ./Shake webmanual # generate combined web man page for hakyll |] @@ -52,6 +53,7 @@ pandoc = -- "stack exec -- pandoc" -- use the pandoc required above "pandoc" -- use pandoc in PATH (faster) hakyllstd = "site/hakyll-std/hakyll-std" +nroff = "nroff" main = do @@ -79,7 +81,8 @@ main = do phony "docs" $ do need [ - "manpages" + "manpages" + ,"txtmanpages" ] let webmanual = "site/manual.md" @@ -157,6 +160,13 @@ main = do "--filter doc/pandoc-drop-notes" "-o" out + -- render man page nroffs as fixed-width text, for embedding + let txtmanpages = [m <.> "txt" | m <- manpages] -- hledger/doc/hledger.1.txt, hledger-lib/doc/journal.5.txt + phony "txtmanpages" $ need txtmanpages + txtmanpages |%> \out -> do + let nroffsrc = dropExtension out -- hledger/doc/hledger.1 + cmd Shell nroff "-man" nroffsrc ">" out + -- adjust man page mds for (hakyll) web output, with pandoc let webmanpages = ["site" manpageNameToUri m <.>".md" | m <- manpageNames] -- site/hledger.md, site/journal.md phony "webmanpages" $ need webmanpages diff --git a/hledger-api/doc/hledger-api.1.txt b/hledger-api/doc/hledger-api.1.txt new file mode 100644 index 000000000..bca63fe06 --- /dev/null +++ b/hledger-api/doc/hledger-api.1.txt @@ -0,0 +1,71 @@ + +hledger-api(1) hledger User Manuals hledger-api(1) + + + +NNAAMMEE + hledger-api - web API server for the hledger accounting tool + +SSYYNNOOPPSSIISS + hledger-api [OPTIONS] + hledger api -- [OPTIONS] + +DDEESSCCRRIIPPTTIIOONN + 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 + ledger(1). + + hledger-api is a simple web API server, intended to support client-side + web apps operating on hledger data. It comes with a series of simple + client-side app examples, which drive it's evolution. + + Data is served from the usual hledger journal file: ~/.hledger.journal, + $LEDGER_FILE, or another file specified with -f. For more about the + format, see hledger(1) or hledger_journal(5). + + The server listens for requests on port ... + + Note there is no built-in access control, so you will need to hide + hledger-api behind an authenticating proxy if you want to restrict + access. + +EENNVVIIRROONNMMEENNTT + LLEEDDGGEERR__FFIILLEE sets the default journal file path. If not set, it is + ~/.hledger.journal. + +FFIILLEESS + Reads data from a hledger journal file ($LEDGER_FILE or + ~/.hledger.journal by default), or a CSV file plus associated CSV rules + file. + +BBUUGGSS + The need to precede options with -- when invoked from hledger is awk- + ward. + + + +RREEPPOORRTTIINNGG BBUUGGSS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AAUUTTHHOORRSS + Simon Michael and contributors + + +CCOOPPYYRRIIGGHHTT + 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), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + + January 2016 hledger-api(1) diff --git a/hledger-lib/doc/hledger_csv.5.txt b/hledger-lib/doc/hledger_csv.5.txt new file mode 100644 index 000000000..0d28efb5e --- /dev/null +++ b/hledger-lib/doc/hledger_csv.5.txt @@ -0,0 +1,169 @@ + +hledger_csv(5) hledger User Manuals hledger_csv(5) + + + +NNAAMMEE + CSV - how hledger reads CSV data, and the CSV rules file format + +DDEESSCCRRIIPPTTIIOONN + hledger can read CSV files, converting each CSV record into a journal + entry (transaction), if you provide some conversion hints in a "rules + file". This file should be named like the CSV file with an additional + .rules suffix (eg: mybank.csv.rules); or, you can specify the file with + --rules-file PATH. hledger will create it if necessary, with some + default rules which you'll need to adjust. At minimum, the rules file + must specify the date and amount fields. For an example, see How to + read CSV files. + + To learn about _e_x_p_o_r_t_i_n_g CSV, see CSV output. + +CCSSVV RRUULLEESS + 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 this number of CSV records at the beginning. You'll need this + whenever your CSV data contains header lines. Eg: + + # ignore the first CSV line + skip 1 + + ddaattee--ffoorrmmaatt + date-format_D_A_T_E_F_M_T + + When your CSV date fields are not formatted like YYYY/MM/DD (or + YYYY-MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT + is a strptime-like date parsing pattern, which must parse the date + field values completely. Examples: + + # for dates like "6/11/2013": + date-format %-d/%-m/%Y + + # for dates like "11/06/2013": + date-format %m/%d/%Y + + # for dates like "2013-Nov-06": + date-format %Y-%h-%d + + # for dates like "11/6/2013 11:32 PM": + date-format %-m/%-d/%Y %l:%M %p + + ffiieelldd lliisstt + fields_F_I_E_L_D_N_A_M_E_1_, _F_I_E_L_D_N_A_M_E_2_._._. + + 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 + fields if you use any of these standard field names: date, date2, sta- + tus, code, description, comment, account1, account2, amount, amount-in, + amount-out, currency. Eg: + + # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, + # and give the 7th and 8th fields meaningful names for later reference: + # + # CSV field: + # 1 2 3 4 5 6 7 8 + # entry field: + fields date, description, , amount, , , somefield, anotherfield + + 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 + + This sets a journal entry field (one of the standard names above) to + the given text value, which can include CSV field values interpolated + by name (%CSVFIELDNAME) or 1-based position (%N). + Eg: + + # set the amount to the 4th CSV field with "USD " prepended + amount USD %4 + + # combine three fields to make a comment (containing two tags) + comment note: %somefield - %anotherfield, date: %1 + + Field assignments can be used instead of or in addition to a field + list. + + 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_._._. + + 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_._._. + + This applies one or more field assignments, only to those CSV records + matched by one of the PATTERNs. The patterns are case-insensitive reg- + ular expressions which match anywhere within the whole CSV record (it's + not yet possible to match within a specific field). When there are + multiple patterns they should be written on separate lines, unindented. + The field assignments are on separate lines indented by at least one + space. Examples: + + # if the CSV record contains "groceries", set account2 to "expenses:groceries" + if groceries + account2 expenses:groceries + + # if the CSV record contains any of these patterns, set account2 and comment as shown + if + monthly service fee + atm transaction fee + banking thru software + account2 expenses:business:banking + comment XXX deductible ? check it + + iinncclluuddee + include_R_U_L_E_S_F_I_L_E + + 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: + + # rules reused with several CSV files + include common.rules + +TTIIPPSS + 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. + + If the CSV has debit/credit amounts in separate fields, assign to the + amount-in and amount-out pseudo fields instead of amount. + + If the CSV has the currency in a separate field, assign that to the + currency pseudo field which will be automatically prepended to the + amount. (Or you can do the same thing with a field assignment.) + + If an amount value is parenthesised, it will be de-parenthesised and + sign-flipped automatically. + + The generated journal entries will be sorted by date. The original + order of same-day entries will be preserved, usually. + + + +RREEPPOORRTTIINNGG BBUUGGSS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AAUUTTHHOORRSS + Simon Michael and contributors + + +CCOOPPYYRRIIGGHHTT + 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), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + + April 2016 hledger_csv(5) diff --git a/hledger-lib/doc/hledger_journal.5.txt b/hledger-lib/doc/hledger_journal.5.txt new file mode 100644 index 000000000..fea8d231f --- /dev/null +++ b/hledger-lib/doc/hledger_journal.5.txt @@ -0,0 +1,668 @@ + +hledger_journal(5) hledger User Manuals hledger_journal(5) + + + +NNAAMMEE + Journal - hledger's default file format, representing a General Journal + +DDEESSCCRRIIPPTTIIOONN + 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 + that's not required. The journal file contains a number of transaction + entries, each describing a transfer of money (or any commodity) between + two or more named accounts, in a simple format readable by both hledger + and humans. + + hledger's journal format is a compatible subset, mostly, of ledger's + journal format, so hledger can work with compatible ledger journal + files as well. It's safe, and encouraged, to run both hledger and + ledger on the same journal file, eg to validate the results you're get- + ting. + + You can use hledger without learning any more about this file; just use + the add or web commands to create and update it. Many users, though, + also edit the journal file directly with a text editor, perhaps + assisted by the helper modes for emacs or vim. + + Here's an example: + + ; A sample journal file. This is a comment. + + 2008/01/01 income ; <- transaction's first line starts in column 0, contains date and description + assets:bank:checking $1 ; <- posting lines start with whitespace, each contains an account name + income:salary $-1 ; followed by at least two spaces and an amount + + 2008/06/01 gift + assets:bank:checking $1 ; <- at least two postings in a transaction + income:gifts $-1 ; <- their amounts must balance to 0 + + 2008/06/02 save + assets:bank:saving $1 + assets:bank:checking ; <- one amount may be omitted; here $-1 is inferred + + 2008/06/03 eat & shop ; <- description can be anything + expenses:food $1 + expenses:supplies $1 ; <- this transaction debits two expense accounts + assets:cash ; <- $-2 inferred + + 2008/12/31 * pay off ; <- an optional * or ! after the date means "cleared" (or anything you want) + liabilities:debts $1 + assets:bank:checking + +FFIILLEE FFOORRMMAATT + TTrraannssaaccttiioonnss + 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", + "pending" and "cleared", or whatever you want) + + +o a transaction code (eg a check number), + + +o and/or a description + + then some number of postings, of some amount to some account, each on + its own line. Usually there are at least two postings, though one or + even none is possible. + + The (real) 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 + Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D) + Leading zeroes are optional. The year may be omitted, in which case it + defaults to the current year, or you can set the default year with a + default year directive. + + Some examples: 2010/01/31, 1/31, 2010-01-31, 2010.1.31. + + SSeeccoonnddaarryy ddaatteess + 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, write both dates + separated by an equals sign. The _p_r_i_m_a_r_y _d_a_t_e, on the left, is used by + default; the _s_e_c_o_n_d_a_r_y _d_a_t_e, on the right, is used when the --date2 + flag is specified (For Ledger compatibility, --aux-date or --effective + also work.) + + Their meaning is up to you, but it's best to follow a consistent rule. + Eg write the bank's clearing date as primary, and when needed, the date + the transaction was initiated as secondary. + + Here's an example. Note that a secondary date will use the year of the + primary date if unspecified. + + 2010/2/23=2/19 movie ticket + expenses:cinema $10 + assets:checking + + $ hledger register checking + 2010/02/23 movie ticket assets:checking $-10 $-10 + + $ hledger register checking --date2 + 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 + flag for your reports. Arguably they are now obsolete, superseded + by... + + PPoossttiinngg ddaatteess + You can give individual postings a different date from their parent + transaction, by adding a posting tag (see below) like date:DATE, where + DATE is a simple date. This is probably the best way to control post- + ing dates precisely. Eg in this example the expense should appear in + May reports, and the deduction from checking should be reported on 6/1 + for easy bank reconciliation: + + 2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 + + $ hledger -f tt.j register food + 2015/05/30 expenses:food $10 $10 + + $ hledger -f tt.j register checking + 2015/06/01 assets:checking $-10 $-10 + + A posting date will use the year of the transaction date if unspeci- + fied. + + You can also set the secondary date, with date2:DATE2. For compatibil- + ity, Ledger's older posting date syntax is also supported: [DATE], + [DATE=DATE2] or [=DATE2] in a posting comment. + + When using any of these forms, be sure to provide a valid simple date + or you'll get a parse error. Eg a date: tag with no value is not + allowed. + + AAccccoouunntt nnaammeess + 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 at least two + spaces (or newline). + + Account names can be aliased. + + AAmmoouunnttss + After the account name, there is usually an amount. Important: between + account name and amount, there must be ttwwoo oorr mmoorree spaces. + + The amount is a number, optionally with a currency symbol or commodity + name on either the left or right. Negative amounts may have the minus + sign either before or after the currency symbol (-$1 or $-1). Commod- + ity names which contain more than just letters should be enclosed in + double quotes (1 "person hours"). + + DDeecciimmaall ppooiinnttss aanndd ddiiggiitt ggrroouuppss + hledger supports flexible decimal point and digit group separator + styles, to support international variations. Numbers can use either a + period (.) or a comma (,) as decimal point. They can also have digit + group separators at any position (eg thousands separators) which can be + comma or period - whichever one you did not use as a decimal point. If + you use digit group separators, you must also include a decimal point + in at least one number in the same commodity, so that hledger knows + which character is which. Eg, write $1,000.00 or $1.000,00. + + AAmmoouunntt ddiissppllaayy ssttyylleess + Based on how you format amounts, hledger will infer canonical display + styles for each commodity, and use these when displaying amounts in + that commodity. Amount styles include: + + +o the position (left or right) and spacing (space or no separator) of + the commodity symbol + + +o the digit group separator character (comma or period) and digit group + sizes, if any + + +o the decimal point character (period or comma) + + +o the display precision (number of decimal places displayed) + + The canonical style is generally the style of the first posting amount + seen in a commodity. However the display precision will be the highest + precision seen in all posting amounts in that commmodity. + + The precisions used in a price amount, or a D directive, don't affect + the canonical display precision directly, but they can affect it indi- + rectly, eg when D's default commodity is applied to a commodity-less + amount or when an amountless posting is balanced using a price's com- + modity (actually this last case does not influence the canonical dis- + play precision but probably should). + + VViirrttuuaall PPoossttiinnggss + When you parenthesise the account name in a posting, that posting is + considered _v_i_r_t_u_a_l, which means: + + +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 + real:1 query. + + You could use this, eg, to set an account's opening balance without + needing to use the equity:opening balances account: + + 1/1 special unbalanced posting to set initial balance + (assets:checking) $1000 + + BBaallaanncceedd VViirrttuuaall PPoossttiinnggss + When the account name is bracketed, the posting is _b_a_l_a_n_c_e_d _v_i_r_t_u_a_l, + which is just like a virtual posting except the balanced virtual post- + ings in a transaction must balance to 0, like the real postings (but + separately from them). Balanced virtual postings are also excluded by + --real/-R or real:1. + + Virtual postings are a feature inherited from Ledger can can occasion- + ally be useful, but they can be a crutch and you should think twice or + three times before using them. You can almost always find an equiva- + lent journal entry using two or more real postings that will be more + correct and more error-proof. + + BBaallaannccee AAsssseerrttiioonnss + 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 + after each posting: + + 2013/1/1 + a $1 =$1 + b =$-1 + + 2013/1/2 + a $1 =$2 + b $-1 =$-2 + + After reading a journal file, hledger will check all balance assertions + and report an error if any of them fail. Balance assertions can pro- + tect you from, eg, inadvertently disrupting reconciled balances while + cleaning up old entries. You can disable them temporarily with the + --ignore-assertions flag, which can be useful for troubleshooting or + for reading Ledger files. + + AAsssseerrttiioonnss aanndd oorrddeerriinngg + 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, + Ledger assertions do not see the accumulated effect of repeated post- + ings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder differ- + ently-dated transactions within the journal. But if you reorder + same-dated transactions or postings, assertions might break and require + updating. This order dependence does bring an advantage: precise con- + trol over the order of postings and assertions within a day, so you can + assert intra-day balances. + + With included files, things are a little more complicated. Including + preserves the ordering of postings and assertions. If you have multi- + ple postings to an account on the same day, split across different + 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 + 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- + tial balance assertion. This is compatible with Ledger, and makes it + possible to make assertions about accounts containing multiple commodi- + ties. + + To assert each commodity's balance in such a multi-commodity account, + you can add multiple postings (with amount 0 if necessary). But note + that no matter how many assertions you add, you can't be sure the + 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 + Balance assertions do not count the balance from subaccounts; they + check the posted account's exclusive balance. For example: + + 1/1 + checking:fund 1 = 1 ; post to this subaccount, its balance is now 1 + checking 1 = 1 ; post to the parent account, its exclusive balance is now 1 + equity + + The balance report's flat mode shows these exclusive balances more + clearly: + + $ hledger bal checking --flat + 1 checking + 1 checking:fund + -------------------- + 2 + + AAsssseerrttiioonnss aanndd vviirrttuuaall ppoossttiinnggss + 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 + 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 + particular transaction (or more precisely, within the particular post- + ing). These transaction prices are fixed, and do not change. + + Such priced amounts can be displayed in their transaction price's com- + modity, by using the --cost/-B flag (B for "cost Basis"), supported by + most hledger commands. + + There are three ways to specify a transaction price: + + 1. Write the unit price (aka exchange rate), as @ UNITPRICE after the + amount: + + 2009/1/1 + assets:foreign currency ^a~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:cash + + 3. Or let hledger infer the price so as to balance the transaction. To + permit this, you must fully specify all posting amounts, and their + sum must have a non-zero amount in exactly two commodities: + + 2009/1/1 + assets:foreign currency ^a~100 ; one hundred euros + assets:cash $-135 ; exchanged for $135 + + With any of the above examples we get: + + $ hledger print -B + 2009/01/01 + assets:foreign currency $135.00 + assets:cash $-135.00 + + Example use for transaction prices: recording the effective conversion + rate of purchases made in a foreign currency. + + MMaarrkkeett pprriicceess + 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. + + When market prices are known, the -V/--value option will use them to + convert reported amounts to their market value as of the report end + date. This option is currently available only with the balance com- + mand. + + You record market prices (Ledger calls them historical prices) with a P + directive, in the journal or perhaps in a separate included file. Mar- + ket price directives have the format: + + P DATE COMMODITYSYMBOL UNITPRICE + + For example, the following directives say that the euro's exchange rate + 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 + + Example use for market prices: tracking the value of stocks. + + CCoommmmeennttss + 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.) + + Also, anything between comment and end comment directives is a + (multi-line) comment. If there is no end comment, the comment extends + to the end of the file. + + You can attach comments to a transaction by writing them after the + description and/or indented on the following lines (before the post- + ings). Similarly, you can attach comments to an individual posting by + writing them after the amount and/or indented on the following lines. + + Some examples: + + # a journal comment + + ; also a journal comment + + comment + This is a multiline comment, + which continues until a line + where the "end comment" string + appears on its own. + end comment + + 2012/5/14 something ; a transaction comment + ; the transaction comment, continued + posting1 1 ; a comment for posting 1 + posting2 + ; a comment for posting 2 + ; 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- + ing comment. You can write multiple tags, comma separated. Eg: + ; a comment containing sometag:, anothertag:. You can search for tags + with the tag: query. + + A tag can also have a value, which is any text between the colon and + the next comma or newline, excluding leading/trailing whitespace. (So + hledger tag values can not contain commas or newlines). + + Tags in a transaction comment affect the transaction and all of its + postings, while tags in a posting comment affect only that posting. + For example, the following transaction has three tags (A, TAG2, + third-tag) and the posting has four (A, TAG2, third-tag, posting-tag): + + 1/1 a transaction ; A:, TAG2: + ; third-tag: a third transaction tag, this time with a value + (a) $1 ; posting-tag: + + Tags are like Ledger's metadata feature, except hledger's tag values + are always simple strings. + + DDiirreeccttiivveess + AAccccoouunntt aalliiaasseess + 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 + data entry and a less verbose journal + + +o adapting old journals to your current chart of accounts + + +o experimenting with new account organisations, like a new hierarchy or + combining two accounts into one + + +o customising reports + + See also How to use account aliases. + + BBaassiicc aalliiaasseess + 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: + + alias OLD = NEW + + Or, you can use the --alias 'OLD=NEW' option on the command line. This + affects all entries. It's useful for trying out aliases interactively. + + OLD and NEW are full account names. hledger will replace any occur- + rence of the old account name with the new one. Subaccounts are also + affected. Eg: + + 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 + 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): + + alias /REGEX/ = REPLACEMENT + + or --alias '/REGEX/=REPLACEMENT'. + + REGEX is a case-insensitive regular expression. Anywhere it matches + inside an account name, the matched part will be replaced by REPLACE- + MENT. If REGEX contains parenthesised match groups, these can be ref- + erenced by the usual numeric backreferences in REPLACEMENT. Note, cur- + rently regular expression aliases may cause noticeable slow-downs. + (And if you use Ledger on your hledger file, they will be ignored.) Eg: + + alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 + # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" + + MMuullttiippllee aalliiaasseess + 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 + aliases are non-recursive by default). Aliases are applied in the fol- + lowing order: + + 1. alias directives, most recently seen first (recent directives take + precedence over earlier ones; directives not yet seen are ignored) + + 2. alias options, in the order they appear on the command line + + eenndd aalliiaasseess + You can clear (forget) all currently defined aliases with the + end aliases directive: + + end aliases + + aaccccoouunntt ddiirreeccttiivvee + 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. + + ; account ACCT + ; OPTIONAL COMMENTS/TAGS... + + account assets:bank:checking + a comment + acct-no:12345 + + account expenses:food + + ; etc. + + aappppllyy aaccccoouunntt ddiirreeccttiivvee + 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: + + apply account home + + 2010/1/1 + food $10 + cash + + end apply account + + which is equivalent to: + + 2010/01/01 + home:food $10 + home:cash $-10 + + If end apply account is omitted, the effect lasts to the end of the + file. Included files are also affected, eg: + + apply account business + include biz.journal + end apply account + apply account personal + include personal.journal + + Prior to hledger 0.28, legacy account and end spellings were also sup- + ported. + + MMuullttii--lliinnee ccoommmmeennttss + A line containing just comment starts a multi-line comment, and a line + containing just end comment ends it. See comments. + + DDeeffaauulltt ccoommmmooddiittyy + 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 style) 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.) + + Also note the directive itself does not influence the commodity's + default display style, but the amount it is applied to might. Here's + an example: + + ; set ^A-L as the default commodity + D ^A-L1,000.00 + + 2010/1/1 + a 2340 + b + + 2014/1/1 + c ^A-L1000 + d + + $ hledger print + 2010/01/01 + a ^A-L2,340.00 + b ^A-L-2,340.00 + + 2014/01/01 + c ^A-L1,000.00 + d ^A-L-1,000.00 + + DDeeffaauulltt yyeeaarr + 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: + + Y2009 ; set default year to 2009 + + 12/15 ; equivalent to 2009/12/15 + expenses 1 + assets + + Y2010 ; change default year to 2010 + + 2009/1/30 ; specifies the year, not affected + expenses 1 + assets + + 1/31 ; equivalent to 2010/1/31 + expenses 1 + assets + + IInncclluuddiinngg ootthheerr ffiilleess + You can pull in the content of additional journal files by writing an + include directive, like this: + + include path/to/file.journal + + If the path does not begin with a slash, it is relative to the current + file. + + Glob patterns (*) are not currently supported. + + The include directive may only be used in journal files, and currently + it may only include other journal files (eg, not CSV or timeclock + files.) + +EEDDIITTOORR SSUUPPPPOORRTT + 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 + majority), using one of these modes is quite recommended. + + These were written with Ledger in mind, but also work with hledger + 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} + + + +RREEPPOORRTTIINNGG BBUUGGSS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AAUUTTHHOORRSS + Simon Michael and contributors + + +CCOOPPYYRRIIGGHHTT + 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), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + + April 2016 hledger_journal(5) diff --git a/hledger-lib/doc/hledger_timeclock.5.txt b/hledger-lib/doc/hledger_timeclock.5.txt new file mode 100644 index 000000000..b305050f0 --- /dev/null +++ b/hledger-lib/doc/hledger_timeclock.5.txt @@ -0,0 +1,83 @@ + +hledger_timeclock(5) hledger User Manuals hledger_timeclock(5) + + + +NNAAMMEE + Timeclock - the time logging format of timeclock.el, as read by hledger + +DDEESSCCRRIIPPTTIIOONN + 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 (also, default year + directives work). The time format is HH:MM[:SS][+-ZZZZ]. Seconds and + timezone are optional. The timezone, if present, must be four digits + and is ignored (currently the time is always interpreted as a local + time). + + i 2015/03/30 09:00:00 some:account name optional description after two spaces + o 2015/03/30 09:20:00 + i 2015/03/31 22:21:45 another account + o 2015/04/01 02:00:34 + + hledger treats each clock-in/clock-out pair as a transaction posting + some number of hours to an account. Or if the session spans more than + 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 + (some:account name) 0.33h + + 2015/03/31 * 22:21-23:59 + (another account) 1.64h + + 2015/04/01 * 00:00-02:00 + (another account) 2.01h + + Here is a sample.timeclock to download and some queries to try: + + $ hledger -f sample.timeclock balance # current time balances + $ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009 + $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week + + 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- + clock-x.el and perhaps the extras in ledgerutils.el + + +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 + rely on a "timeclock" executable which I think is just the ledger 2 + executable renamed. + + + +RREEPPOORRTTIINNGG BBUUGGSS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AAUUTTHHOORRSS + Simon Michael and contributors + + +CCOOPPYYRRIIGGHHTT + 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), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + + April 2016 hledger_timeclock(5) diff --git a/hledger-lib/doc/hledger_timedot.5.txt b/hledger-lib/doc/hledger_timedot.5.txt new file mode 100644 index 000000000..dcdc24d03 --- /dev/null +++ b/hledger-lib/doc/hledger_timedot.5.txt @@ -0,0 +1,125 @@ + +hledger_timedot(5) hledger User Manuals hledger_timedot(5) + + + +NNAAMMEE + Timedot - hledger's human-friendly time logging format + +DDEESSCCRRIIPPTTIIOONN + 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 + required with a timeclock file is too precise or too interruptive. It + can be formatted like a bar chart, making clear at a glance where time + was spent. + + Though called "timedot", the format does not specify the commodity + being logged, so could represent other dated, quantifiable things. Eg + you could record a single-entry journal of financial transactions, per- + haps slightly more conveniently than with hledger_journal(5) format. + +FFIILLEE FFOORRMMAATT + 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- + gories are hledger-style account names, optionally indented. There + must be at least two spaces between the category and the quantity. + Quantities can be written in two ways: + + 1. a series of dots (period characters). Each dot represents "a quar- + ter" - eg, a quarter hour. Spaces can be used to group dots into + hours, for easier counting. + + 2. a number (integer or decimal), representing "units" - eg, hours. A + good alternative when dots are cumbersome. (A number also can + record negative quantities.) + + Blank lines and lines beginning with #, ; or * are ignored. An exam- + ple: + + # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. + 2016/2/1 + inc:client1 .... .... .... .... .... .... + fos:haskell .... .. + biz:research . + + 2016/2/2 + inc:client1 .... .... + biz:research . + + Or with numbers: + + 2016/2/3 + inc:client1 4 + fos:hledger 3 + biz:research 1 + + Reporting: + + $ hledger -f t.timedot print date:2016/2/2 + 2016/02/02 * + (inc:client1) 2.00 + + 2016/02/02 * + (biz:research) 0.25 + + $ hledger -f t.timedot bal --daily --tree + Balance changes in 2016/02/01-2016/02/03: + + || 2016/02/01d 2016/02/02d 2016/02/03d + ============++======================================== + biz || 0.25 0.25 1.00 + research || 0.25 0.25 1.00 + fos || 1.50 0 3.00 + haskell || 1.50 0 0 + hledger || 0 0 3.00 + inc || 6.00 2.00 4.00 + client1 || 6.00 2.00 4.00 + ------------++---------------------------------------- + || 7.75 2.25 8.00 + + I prefer to use period for separating account components. We can make + this work with an account alias: + + 2016/2/4 + fos.hledger.timedot 4 + fos.ledger .. + + $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4 + 4.50 fos + 4.00 hledger:timedot + 0.50 ledger + -------------------- + 4.50 + + default year directives may be used. + + Here is a sample.timedot. + + + +RREEPPOORRTTIINNGG BBUUGGSS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AAUUTTHHOORRSS + Simon Michael and contributors + + +CCOOPPYYRRIIGGHHTT + 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), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + + April 2016 hledger_timedot(5) diff --git a/hledger-ui/doc/hledger-ui.1.txt b/hledger-ui/doc/hledger-ui.1.txt new file mode 100644 index 000000000..33d198bc0 --- /dev/null +++ b/hledger-ui/doc/hledger-ui.1.txt @@ -0,0 +1,258 @@ + +hledger-ui(1) hledger User Manuals hledger-ui(1) + + + +NNAAMMEE + hledger-ui - curses-style interface for the hledger accounting tool + +SSYYNNOOPPSSIISS + hledger-ui [OPTIONS] [QUERYARGS] + hledger ui -- [OPTIONS] [QUERYARGS] + +DDEESSCCRRIIPPTTIIOONN + 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 + ledger(1). hledger-ui is hledger's curses-style interface. It reads a + hledger journal file + + (~/.hledger.journal, $LEDGER_FILE, or -f FILE; see hledger(1) or + hledger_journal(5)) + + and provides a simple full-screen console interface for viewing account + balances and transactions. + + It is simpler and more convenient for browsing than the command-line + interface, but lighter and faster than hledger-web. + + The journal file is ~/.hledger.journal, $LEDGER_FILE, or another file + specified with -f. For more about the format, see hledger(1) or + hledger_journal(5). + +OOPPTTIIOONNSS + 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 + + ----nnoo--eelliiddee + don't compress empty parent accounts on one line + + ----rreeggiisstteerr==AACCCCTTRREEGGEEXX + start in the (first) matched account's register screen + + ----tthheemmee==ddeeffaauulltt||tteerrmmiinnaall||ggrreeeenntteerrmm + use this custom display theme + + --VV ----vvaalluuee + show amounts as their current market value in their default val- + uation commodity (accounts screen only) + + --hh ----hheellpp + show help + + ----vveerrssiioonn + show version information + + hhlleeddggeerr ooppttiioonnss + The following common hledger options should also work: + + --ff FFIILLEE ----ffiillee==FFIILLEE + use a different input file. For stdin, use - + + ----rruulleess--ffiillee==RRUULLEESSFFIILLEE + Conversion rules file to use when reading CSV (default: + FILE.rules) + + ----aalliiaass==OOLLDD==NNEEWW + display accounts named OLD as NEW + + ----iiggnnoorree--aasssseerrttiioonnss + ignore any failing balance assertions in the journal + + ----ddeebbuugg==NN + show debug output if N is 1-9 (default: 0) + + --bb ----bbeeggiinn==DDAATTEE + include postings/txns on or after this date + + --ee ----eenndd==DDAATTEE + include postings/txns before this date + + --pp ----ppeerriioodd==PPEERRIIOODDEEXXPP + set start date, end date, and/or reporting interval all at once + (overrides the flags above) + + ----ddaattee22 ----aauuxx--ddaattee + use postings/txns' secondary dates instead + + --CC ----cclleeaarreedd + include only cleared postings/txns + + ----ppeennddiinngg + include only pending postings/txns + + --UU ----uunncclleeaarreedd + include only uncleared (and pending) postings/txns + + --RR ----rreeaall + include only non-virtual postings + + ----ddeepptthh==NN + hide accounts/postings deeper than N + + --EE ----eemmppttyy + show empty/zero things which are normally omitted + + --BB ----ccoosstt + show amounts in their cost price's commodity + +KKEEYYSS + Generally the cursor keys navigate; right (or enter) goes deeper, left + returns to the previous screen, up/down/page up/page down/home/end move + up and down through lists. + + g gets the latest data and reloads the screen (and any previous + screens). There may be a noticeable pause. + + q quits the application. + + Some screens have additional key bindings, described below. + +SSCCRREEEENNSS + AAccccoouunnttss ssccrreeeenn + 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 + on the command line, it shows just the matched accounts and the bal- + ances from matched transactions. + + When not in flat mode, indentation indicates the account hierarchy. F + toggles flat mode on and off. + + By default, all subaccounts are displayed. To see less detail, set a + depth limit by pressing a number key, 1 to 9. Or, adjust the depth + limit by pressing - or + (= also works). 0 removes the depth limit. + + C toggles cleared mode. In cleared mode, the accounts and balances are + derived only from transactions which are marked cleared (*). + + Press right or enter to view an account's transactions register. + + RReeggiisstteerr ssccrreeeenn + This screen lists all transactions affecting a particular account (like + a check register). In cleared mode (press C) it lists only transac- + tions which are marked cleared. It does not otherwise filter by query. + + Note this screen shows transactions, not postings (unlike hledger's + register command). This means: + + +o Each line represents a whole transaction. + + +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 + 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- + 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: + + $ hledger-ui + $ hledger-ui --begin 'this month' + $ hledger-ui --register checking date:2015/10 + + while these will show a running total, since the queries are not just + date limits: + + $ hledger-ui checking + $ hledger-ui --begin 'this month' desc:market + $ hledger-ui --register checking --cleared + + Press right or enter to view the selected transaction in full detail. + + TTrraannssaaccttiioonn ssccrreeeenn + This screen shows a single transaction, as a general journal entry, + similar to hledger's print command and journal format (hledger_jour- + nal(5)). + + The transaction's date(s) and any cleared flag, transaction code, + description, comments, along with all of its account postings are + shown. Simple transactions have two postings, but there can be more + (or in certain cases, fewer). + + up and down will step through all transactions listed in the previous + account register screen. In the title bar, the numbers in parentheses + show your position within that account register. They will vary + depending on which account register you came from (remember most trans- + actions appear in multiple account registers). The #N number preceding + 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 + 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 described, + press g again to reload and restore normal operation. + +EENNVVIIRROONNMMEENNTT + LLEEDDGGEERR__FFIILLEE sets the default journal file path. If not set, it is + ~/.hledger.journal. + + CCOOLLUUMMNNSS sets the screen width to use (normally the full terminal + width). + +FFIILLEESS + Reads data from a hledger journal file ($LEDGER_FILE or + ~/.hledger.journal by default), or a CSV file plus associated CSV rules + file. + +BBUUGGSS + The need to precede options with -- when invoked from hledger is awk- + ward. + + -f- doesn't work (hledger-ui can't read from stdin). + + -V affects only the accounts screen. + + When you press g, the current and all previous screens are regenerated, + which may cause a noticeable pause. Also there is no visual indication + that this is in progress. + + The register screen's switching between historic balance and running + total based on query arguments may be confusing, and there is no column + heading to indicate which is being displayed. + + + +RREEPPOORRTTIINNGG BBUUGGSS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AAUUTTHHOORRSS + Simon Michael and contributors + + +CCOOPPYYRRIIGGHHTT + 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), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + + October 2015 hledger-ui(1) diff --git a/hledger-web/doc/hledger-web.1.txt b/hledger-web/doc/hledger-web.1.txt new file mode 100644 index 000000000..9efd875c0 --- /dev/null +++ b/hledger-web/doc/hledger-web.1.txt @@ -0,0 +1,204 @@ + +hledger-web(1) hledger User Manuals hledger-web(1) + + + +NNAAMMEE + hledger-web - web interface for the hledger accounting tool + +SSYYNNOOPPSSIISS + hledger-web [OPTIONS] + hledger web -- [OPTIONS] + + + +DDEESSCCRRIIPPTTIIOONN + 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 + ledger(1). + + hledger-web is hledger's web interface. It starts a simple web appli- + cation for browsing and adding transactions, and optionally opens it in + a web browser window if possible. It provides a more user-friendly UI + than the hledger CLI or hledger-ui interface, showing more at once + (accounts, the current account register, balance charts) and allowing + history-aware data entry, interactive searching, and bookmarking. + + hledger-web also lets you share a ledger with multiple users, or even + the public web. There is no access control, so if you need that you + should put it behind a suitable web proxy. As a small protection + against data loss when running an unprotected instance, it writes a + numbered backup of the main journal file (only ?) on every edit. + + The journal file is ~/.hledger.journal, $LEDGER_FILE, or another file + specified with -f. For more about the format, see hledger(1) or + hledger_journal(5). + + By default, hledger-web starts the web app in "transient mode" and also + opens it in your default web browser if possible. In this mode the web + app will keep running for as long as you have it open in a browser win- + dow, and will exit after two minutes of inactivity (no requests and no + browser windows viewing it). + + $ hledger web + Starting web app on port 5000 with base url http://localhost:5000 + Starting web browser if possible + Web app will auto-exit after a few minutes with no browsers (or press ctrl-c) + + With --server, it starts the web app in non-transient mode and logs + requests to the console. Typically when running hledger web as part of + a website you'll want to use --base-url to set the protocol/host- + name/port/path to be used in hyperlinks. The --file-url option allows + static files to be served from a different url, eg for better caching + or cookie-less serving. + + You can use --port to listen on a different TCP port, eg if you are + running multiple hledger-web instances. This need not be the same as + the PORT in the base url. + + Note there is no built-in access control, so you will need to hide + hledger-web behind an authenticating proxy (such as apache or nginx) if + you want to restrict who can see and add entries to your journal. + + With journal and timeclock files (but not CSV files, currently) the web + app detects changes and will show the new data on the next request. If + a change makes the file unparseable, hledger-web will show an error + until the file has been fixed. + +OOPPTTIIOONNSS + Note: if invoking hledger-web as a hledger subcommand, write -- before + options as shown above. + + ----sseerrvveerr + disable browser-opening and auto-exit-on-idle, and log all + requests to stdout + + ----ppoorrtt==PPOORRTT + set the TCP port to listen on (default: 5000) + + ----bbaassee--uurrll==UURRLL + 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 + 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 + with this. + + --hh ----hheellpp + show help + + ----vveerrssiioonn + show version information + + hhlleeddggeerr ooppttiioonnss + The following common hledger options should also work: + + --ff FFIILLEE ----ffiillee==FFIILLEE + use a different input file. For stdin, use - + + ----rruulleess--ffiillee==RRUULLEESSFFIILLEE + Conversion rules file to use when reading CSV (default: + FILE.rules) + + ----aalliiaass==OOLLDD==NNEEWW + display accounts named OLD as NEW + + ----iiggnnoorree--aasssseerrttiioonnss + ignore any failing balance assertions in the journal + + ----ddeebbuugg==NN + show debug output if N is 1-9 (default: 0) + + --bb ----bbeeggiinn==DDAATTEE + include postings/txns on or after this date + + --ee ----eenndd==DDAATTEE + include postings/txns before this date + + --pp ----ppeerriioodd==PPEERRIIOODDEEXXPP + set start date, end date, and/or reporting interval all at once + (overrides the flags above) + + ----ddaattee22 ----aauuxx--ddaattee + use postings/txns' secondary dates instead + + --CC ----cclleeaarreedd + include only cleared postings/txns + + ----ppeennddiinngg + include only pending postings/txns + + --UU ----uunncclleeaarreedd + include only uncleared (and pending) postings/txns + + --RR ----rreeaall + include only non-virtual postings + + ----ddeepptthh==NN + hide accounts/postings deeper than N + + --EE ----eemmppttyy + show empty/zero things which are normally omitted + + --BB ----ccoosstt + show amounts in their cost price's commodity + +EENNVVIIRROONNMMEENNTT + LLEEDDGGEERR__FFIILLEE sets the default journal file path. If not set, it is + ~/.hledger.journal. + +FFIILLEESS + Reads data from a hledger journal file ($LEDGER_FILE or + ~/.hledger.journal by default), or a CSV file plus associated CSV rules + file. + +BBUUGGSS + The need to precede options with -- when invoked from hledger is awk- + ward. + + -f- doesn't work (hledger-web can't read from stdin). + + Query arguments and some applicable hledger options probably aren't + supported. + + Does not work in text-mode browsers. + + Does not work well on small screens. + + The auto-exit feature was added to avoid leaving stray processes, eg on + Windows. It is not well tested. + + If you start two instances on the same port, the second one will appear + to run normally, but you will be seeing pages served from the first + one. + + + +RREEPPOORRTTIINNGG BBUUGGSS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AAUUTTHHOORRSS + Simon Michael and contributors + + +CCOOPPYYRRIIGGHHTT + 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), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + + October 2015 hledger-web(1) diff --git a/hledger/doc/hledger.1.txt b/hledger/doc/hledger.1.txt new file mode 100644 index 000000000..25107cbb0 --- /dev/null +++ b/hledger/doc/hledger.1.txt @@ -0,0 +1,1628 @@ + +hledger(1) hledger User Manuals hledger(1) + + + +NNAAMMEE + hledger - a command-line accounting tool + +SSYYNNOOPPSSIISS + hledger [-f FILE] COMMAND [OPTIONS] [CMDARGS] + hledger [-f FILE] ADDONCMD -- [OPTIONS] [CMDARGS] + +DDEESSCCRRIIPPTTIIOONN + hledger is a cross-platform program for tracking money, time, or any + other commodity, using double-entry accounting and a simple, editable + file format. It is inspired by and largely compatible with ledger(1). + Tested on unix, mac, windows, hledger aims to be a reliable, practical + tool for daily use. + + This is hledger's command-line interface (there are also curses and web + interfaces). Its basic function is to read a plain text file describ- + ing financial transactions (in accounting terms, a general journal) and + print useful reports on standard output, or export them as CSV. + hledger can also read CSV files, converting them semi-automatically to + journal format. Additionally, hledger lists other hledger-* executa- + bles found in the user's $PATH and can invoke them as subcommands. + + The journal file is ~/.hledger.journal by default, or another file path + specified by $LEDGER_FILE. (This should be a real environment vari- + able, not a shell variable.) You can also specify a file with -f FILE, + or standard input with -f-. + + Transactions are dated movements of money between two (or more) named + accounts, and are recorded with journal entries like this: + + 2015/10/16 bought food + expenses:food $10 + assets:cash + + For more about the format, see hledger_journal(5). + + Most users use a text editor to edit the journal, usually with an edi- + tor mode such as ledger-mode for added convenience. hledger's interac- + tive add command is another way to record new transactions. hledger + never changes existing transactions. + + To get started, you can either save some entries like the above in + ~/.hledger.journal, or run hledger add and follow the prompts. Then + try some commands like hledger print or hledger balance. See COMMANDS + and EXAMPLES below. + +EEXXAAMMPPLLEESS + Two simple transactions in hledger journal format: + + 2015/9/30 gift received + assets:cash $20 + income:gifts + + 2015/10/16 farmers market + expenses:food $10 + assets:cash + + Some basic reports: + + $ hledger print + 2015/09/30 gift received + assets:cash $20 + income:gifts $-20 + + 2015/10/16 farmers market + expenses:food $10 + assets:cash $-10 + + $ hledger accounts --tree + assets + cash + expenses + food + income + gifts + + $ hledger balance + $10 assets:cash + $10 expenses:food + $-20 income:gifts + -------------------- + 0 + + $ hledger register cash + 2015/09/30 gift received assets:cash $20 $20 + 2015/10/16 farmers market assets:cash $-10 $10 + + $ hledger # show available commands + $ hledger add # add more transactions to the journal file + $ hledger balance # all accounts with aggregated balances + $ hledger balance --help # show help for balance command + $ hledger balance --depth 1 # only top-level accounts + $ hledger register # show account postings, with running total + $ hledger reg income # show postings to/from income accounts + $ hledger reg 'assets:some bank:checking' # show postings to/from this checking account + $ hledger print desc:shop # show transactions with shop in the description + $ hledger activity -W # show transaction counts per week as a bar chart + +OOPPTTIIOONNSS + To see general help and the command list: hledger --help or hledger + + To see all options available with a command: hledger COMMAND --help + + Except for the General options below, options must be written after + COMMAND, not before it. + + 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: + + $ hledger ui -- --register cash + $ hledger-ui --register cash + + Options and command arguments can be intermixed. Arguments are usually + interpreted as a search query which filters the data, see QUERIES. + + There are three kinds of options. General options are always available + and can appear anywhere in the command line: + + --hh ----hheellpp + show general help or (after command) command help + + ----vveerrssiioonn + show version information + + --ff FFIILLEE ----ffiillee==FFIILLEE + use a different input file. For stdin, use - + + ----rruulleess--ffiillee==RRUULLEESSFFIILLEE + Conversion rules file to use when reading CSV (default: + FILE.rules) + + ----aalliiaass==OOLLDD==NNEEWW + display accounts named OLD as NEW + + ----iiggnnoorree--aasssseerrttiioonnss + ignore any failing balance assertions in the journal + + ----ddeebbuugg==NN + : show debug output if N is 1-9 (default: 0) + + 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. + + --bb ----bbeeggiinn==DDAATTEE + include postings/txns on or after this date + + --ee ----eenndd==DDAATTEE + include postings/txns before this date + + --DD ----ddaaiillyy + multiperiod/multicolumn report by day + + --WW ----wweeeekkllyy + multiperiod/multicolumn report by week + + --MM ----mmoonntthhllyy + multiperiod/multicolumn report by month + + --QQ ----qquuaarrtteerrllyy + multiperiod/multicolumn report by quarter + + --YY ----yyeeaarrllyy + multiperiod/multicolumn report by year + + --pp ----ppeerriioodd==PPEERRIIOODDEEXXPP + set start date, end date, and/or reporting interval all at once + (overrides the flags above) + + ----ddaattee22 ----aauuxx--ddaattee + use postings/txns' secondary dates instead + + --CC ----cclleeaarreedd + include only cleared postings/txns + + ----ppeennddiinngg + include only pending postings/txns + + --UU ----uunncclleeaarreedd + include only uncleared (and pending) postings/txns + + --RR ----rreeaall + include only non-virtual postings + + ----ddeepptthh==NN + hide accounts/postings deeper than N + + --EE ----eemmppttyy + show empty/zero things which are normally omitted + + --BB ----ccoosstt + show amounts in their cost price's commodity + + MMuullttiippllee ffiilleess + One may specify the --file FILE option multiple times. This is equiva- + lent to concatenating the files to standard input and passing --file -, + except that the add command functions normally and adds entries to the + first specified file. + + RReeppeeaatteedd ooppttiioonnss + 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 + 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 + 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 + omitted (defaulting to 1). + + Examples: + + + tab(@); lw(33.7n) lw(36.3n). 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, yester- + day, tomorrow T}@T{ T} + + RReeppoorrttiinngg iinntteerrvvaall + 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 + 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 + other date flags (-b/-e/-D/-W/-M/-Q/-Y) to be ignored. + + hledger's period expressions are similar to Ledger's, though not iden- + tical. Here's a basic period expression specifying the first quarter + of 2009. Note hledger always treats start dates as inclusive and end + dates as exclusive: + + -p "from 2009/1/1 to 2009/4/1" + + Keywords like "from" and "to" are optional, and so are the spaces. + Just don't run two dates together: + + -p2009/1/1to2009/4/1 + -p"2009/1/1 2009/4/1" + + Dates are smart dates, so if the current year is 2009, the above can + also be written as: + + -p "1/1 to 4/1" + -p "january to 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: + + -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: + + -p "2009" (the year 2009; equivalent to "2009/1/1 to 2010/1/1") + -p "2009/1" (the month of jan; equivalent 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 + reporting interval and the start/end dates. Examples: + + -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 + hledger uses regular expressions in a number of places: + + +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 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 infix matching (do not need to match the entire thing being + matched) + + +o are POSIX extended regular expressions + + +o also support GNU word boundaries (\<, \>, \b, \B) + + +o and parenthesised capturing groups and numeric backreferences in + replacement strings + + +o do not support mode modifiers like (?s) + + Some things to note: + + +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- + 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- + 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 + 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 + by date, account name or other criteria. The syntax is similar to a + web search: one or more space-separated search terms, quotes to enclose + whitespace, optional prefixes to match specific fields. Multiple + search terms are combined as follows: + + All commands except print: show transactions/postings/accounts which + match (or negatively match) + + +o any of the description terms AND + + +o any of the account terms AND + + +o all the other terms. + + The print command: show transactions which + + +o match any of the description 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 match all the other terms. + + The following kinds of search terms can be used: + + RREEGGEEXX match account names by this regular expression + + aacccctt::RREEGGEEXX + same as above + + aammtt::NN,, aammtt::<>NN,, aammtt::>>==NN + 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 + N is preceded by a + or - sign (or is 0), the two signed numbers + are compared. Otherwise, the absolute magnitudes are compared, + ignoring sign. + + ccooddee::RREEGGEEXX + match by transaction code (eg check number) + + ccuurr::RREEGGEEXX + 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 + regex-significant, like the dollar sign ($), you need to prepend + \. And when using the command line you need to add one more + level of quoting to hide it from the shell, so eg do: + hledger print cur:'\$' or hledger print cur:\\$. + + ddeesscc::RREEGGEEXX + match transaction descriptions + + ddaattee::PPEERRIIOODDEEXXPPRR + match dates within the specified period (which should not + include a reporting interval + + ddaattee22::PPEERRIIOODDEEXXPPRR + as above, but match secondary dates + + ddeepptthh::NN + match (or display, depending on command) accounts at or above + this depth + + rreeaall::,, rreeaall::00 + match real or virtual postings respectively + + ssttaattuuss::**,, ssttaattuuss::!!,, ssttaattuuss:: + match cleared, pending, or uncleared/pending transactions + respectively + + ttaagg::RREEGGEEXX[[==RREEGGEEXX]] + 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. + + * * * * * + + 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 + hledger provides a number of subcommands; hledger with no arguments + shows a list. + + If you install additional hledger-* packages, or if you put programs or + scripts named hledger-NAME in your PATH, these will also be listed as + subcommands. + + Run a subcommand by writing its name as first argument (eg + hledger incomestatement). You can also write any unambiguous prefix of + a command name (hledger inc), or one of the standard short aliases dis- + played in the command list (hledger is). + + aaccccoouunnttss + Show account names. + + ----ttrreeee show short account names, as a tree + + ----ffllaatt show full account names, as a list (default) + + ----ddrroopp==NN + in flat mode: omit N leading account name parts + + This command lists all account names that are in use (ie, all the + accounts which have at least one transaction posting to them). With + query arguments, only matched account names are shown. + + It shows a flat list by default. With --tree, it uses indentation to + show the account hierarchy. + + In flat mode you can add --drop N to omit the first few account name + components. + + Examples: + + $ hledger accounts --tree + assets + bank + checking + saving + cash + expenses + food + supplies + income + gifts + salary + liabilities + debts + + $ hledger accounts --drop 1 + bank:checking + bank:saving + cash + food + supplies + gifts + salary + debts + + $ hledger accounts + assets:bank:checking + assets:bank:saving + assets:cash + expenses:food + expenses:supplies + income:gifts + income:salary + liabilities:debts + + aaccttiivviittyy + Show an ascii barchart of posting counts per interval. + + The activity command displays an ascii histogram showing transaction + counts by day, week, month or other reporting interval (by day is the + default). With query arguments, it counts only matched transactions. + + $ hledger activity --quarterly + 2008-01-01 ** + 2008-04-01 ******* + 2008-07-01 + 2008-10-01 ** + + aadddd + Prompt for transactions and add them to the journal. + + ----nnoo--nneeww--aaccccoouunnttss + don't allow creating new accounts; helps prevent typos when + entering account names + + Many hledger users edit their journals directly with a text editor, or + generate them from CSV. For more interactive data entry, there is the + add command, which prompts interactively on the console for new trans- + actions, and appends them to the journal file (existing transactions + are not changed). This is the only hledger command that writes to the + journal file. + + To use it, just run hledger add and follow the prompts. You can add as + many transactions as you like; when you are finished, enter . or press + control-d or control-c to exit. + + Features: + + +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 Readline-style edit keys can be used during data entry. + + +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 + bare numbers entered. + + +o A parenthesised transaction code may be entered following a date. + + +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- + tion. + + +o Input prompts are displayed in a different colour when the terminal + supports it. + + Example (see the tutorial for a detailed explanation): + + $ hledger add + Adding transactions to journal file /src/hledger/data/sample.journal + Any command line arguments will be used as defaults. + Use tab key to complete, readline keys to edit, enter to accept defaults. + An optional (CODE) may follow transaction dates. + An optional ; COMMENT may follow descriptions or amounts. + If you make a mistake, enter < at any prompt to restart the transaction. + To end a transaction, enter . when prompted. + To quit, enter . at a date prompt or press control-d or control-c. + Date [2015/05/22]: + Description: supermarket + Account 1: expenses:food + Amount 1: $10 + Account 2: assets:checking + Amount 2 [$-10.0]: + Account 3 (or . or enter to finish this transaction): . + 2015/05/22 supermarket + expenses:food $10 + assets:checking $-10.0 + + Save this transaction to the journal ? [y]: + Saved. + Starting the next transaction (. or ctrl-D/ctrl-C to quit) + Date [2015/05/22]: $ + + bbaallaannccee + Show accounts and their balances. Alias: bal. + + ----ttrreeee show short account names, as a tree + + ----ffllaatt show full account names, as a list (default) + + ----ddrroopp==NN + in flat mode: omit N leading account name parts + + ----ffoorrmmaatt==LLIINNEEFFOORRMMAATT + in single-column balance reports: use this custom line format + + ----nnoo--eelliiddee + in tree mode: don't squash boring parent accounts + + --HH ----hhiissttoorriiccaall + in multicolumn mode: show historical ending balances + + ----ccuummuullaattiivvee + in multicolumn mode: show accumulated ending balances + + --AA ----aavveerraaggee + in multicolumn mode: show a row average column + + --TT ----rrooww--ttoottaall + in multicolumn mode: show a row total column + + --NN ----nnoo--ttoottaall + don't show the final total row + + --VV ----vvaalluuee + show amounts as their current market value in their default val- + uation commodity + + --oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]] + write output to FILE instead of stdout. A recognised FMT suffix + influences the format. + + --OO FFMMTT ----oouuttppuutt--ffoorrmmaatt==FFMMTT + select the output format. Supported formats: txt, csv. + + The balance command displays accounts and balances. It is hledger's + most featureful and most useful command. + + $ hledger balance + $-1 assets + $1 bank:saving + $-2 cash + $2 expenses + $1 food + $1 supplies + $-2 income + $-1 gifts + $-1 salary + $1 liabilities:debts + -------------------- + 0 + + More precisely, the balance command shows the _c_h_a_n_g_e 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. + + By default, accounts are displayed hierarchically, with subaccounts + indented below their parent. "Boring" accounts, which contain a single + interesting subaccount and no balance of their own, are elided into the + following line for more compact output. (Use --no-elide to prevent + this.) + + Each account's balance is the "inclusive" balance - it includes the + balances of any subaccounts. + + Accounts which have zero balance (and no non-zero subaccounts) are + omitted. Use -E/--empty to show them. + + $ hledger balance -p 2008/6 expenses --no-total + $2 expenses + $1 food + $1 supplies + + A final total is displayed by default; use -N/--no-total to suppress + it. + + FFllaatt mmooddee + $ hledger balance -p 2008/6 expenses -N --flat --drop 1 + $1 food + $1 supplies + + 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 + balances. In this mode, you can also use --drop N to omit the first + few account name components. + + DDeepptthh lliimmiittiinngg + $ hledger balance -N --depth 1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + + 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 + will be shown as part of a parent account at the depth limit. + + MMuullttiiccoolluummnn bbaallaannccee rreeppoorrttss + 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: + + $ hledger balance --quarterly income expenses -E + Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 + ===================++================================= + expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 + -------------------++--------------------------------- + || $-1 $1 0 0 + + 1. By default: each column shows the sum of postings in that period, ie + the account's change of balance in that period. This is useful eg + for a monthly income statement. + + $ hledger balance --quarterly income expenses -E --cumulative + Ending balances (cumulative) in 2008: + + || 2008/03/31 2008/06/30 2008/09/30 2008/12/31 + ===================++================================================= + expenses:food || 0 $1 $1 $1 + expenses:supplies || 0 $1 $1 $1 + income:gifts || 0 $-1 $-1 $-1 + income:salary || $-1 $-1 $-1 $-1 + -------------------++------------------------------------------------- + || $-1 0 0 0 + + 2. With --cumulative: each column shows the ending balance for that + period, accumulating the changes across periods, starting from 0 at + the report start date. This mode is not often used. + + $ hledger balance ^assets ^liabilities -Q + Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 + ======================++================================= + assets:bank:checking || $1 0 0 $-1 + assets:bank:saving || 0 $1 0 0 + assets:cash || 0 $-2 0 0 + liabilities:debts || 0 0 0 $1 + ----------------------++--------------------------------- + || $1 $-1 0 0 + + $ hledger balance ^assets ^liabilities --quarterly --historical --begin 2008/4/1 + Ending balances (historical) in 2008/04/01-2008/12/31: + + || 2008/06/30 2008/09/30 2008/12/31 + ======================++===================================== + assets:bank:checking || $1 $1 0 + assets:bank:saving || $1 $1 $1 + assets:cash || $-2 $-2 $-2 + liabilities:debts || 0 0 $1 + ----------------------++------------------------------------- + || 0 0 0 + + 3. With --historical/-H: each column shows the actual historical ending + balance for that period, accumulating the changes across periods, + starting from the actual balance at the report start date. This is + useful eg for a multi-period balance sheet, and when you are showing + only the data after a certain start date. + + $ hledger balance -Q income expenses --tree -E -TA + Balance changes in 2008: + + || 2008q1 2008q2 2008q3 2008q4 Total Average + ============++=================================================== + expenses || 0 $2 0 0 $2 $1 + food || 0 $1 0 0 $1 0 + supplies || 0 $1 0 0 $1 0 + income || $-1 $-1 0 0 $-2 $-1 + gifts || 0 $-1 0 0 $-1 0 + salary || $-1 0 0 0 $-1 0 + ------------++--------------------------------------------------- + || $-1 $1 0 0 0 0 + + # Average is rounded to the dollar here since all journal amounts are + + Multi-column balance reports display accounts in flat mode by default; + to see the hierarchy, use --tree. + + Note that with a reporting interval, the report start/end dates will be + "enlarged" if necessary so that they encompass the displayed report + periods. This is so that the first and last periods will be "full" and + comparable to the others. + + The -E/--empty flag does two things here: first, the report will show + all columns within the specified report period (without -E, leading and + trailing columns with all zeroes are not shown). Second, all accounts + which existed at the report start date will be considered, not just the + ones with activity during the report period (use -E to include + low-activity accounts which would otherwise would be omitted). + + The -T/--row-total flag adds an additional column showing the total for + each row. The -A/--average flag adds a column showing the average + value in each row. Note in --H/--historical mode only the average is + useful, and in --cumulative mode neither is useful. + + MMaarrkkeett vvaalluuee + 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), + for the amount's commodity, dated on or before the report end date. + + Unlike Ledger, hledger's -V only uses the market prices recorded with P + directives, ignoring transaction prices recorded as part of posting + amounts (which -B/--cost uses). Using -B and -V together is allowed. + + CCuussttoomm bbaallaannccee oouuttppuutt + $ hledger balance --format "%20(account) %12(total)" + assets $-1 + bank:saving $1 + cash $-2 + expenses $2 + food $1 + supplies $1 + income $-2 + gifts $-1 + salary $-1 + liabilities:debts $1 + --------------------------------- + 0 + + In simple (non-multi-column) balance reports, you can customise the + output with --format FMT. FMT (plus a newline) will be displayed for + each account/balance pair. It is a format string with data fields + interpolated by + + %[MIN][.MAX](FIELDNAME) + + where MIN means pad with spaces to at least this width, and MAX means + truncate at this width. The field name must be enclosed in parenthe- + ses. Three fields are available: + + +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 total - the account's balance/posted total, right justified + + When the total has multiple commodities, by default each commodity is + displayed on a separate line, and the report item will be bottom + aligned. You can change how such multi-line values are rendered by + beginning the format with a special prefix: + + +o %_ - render on multiple lines, bottom-aligned (the default) + + +o %^ - render on multiple lines, top-aligned + + +o %, - render on one line, with multi-line values comma-separated + + There are some quirks, and experimentation may be needed to get pleas- + ing output. In one-line mode, %(depth_spacer) has no effect, instead + %(account) has indentation built in. + + Examples: + + +o %(total) - the account's total + + +o %-20.20(account) - the account's name, left justified, padded to 20 + characters and clipped at 20 characters + + +o %20(total) %2(depth_spacer)%-(account) - default format for the sin- + gle-column balance report + + +o %,%-50(account) %25(total) - account name padded to 50 characters, + total padded to 20 characters, with multiple commodities rendered on + one line + + OOuuttppuutt ddeessttiinnaattiioonn + $ hledger balance -o - # write to stdout (the default) + $ hledger balance -o FILE # write to FILE + + 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. + + CCSSVV oouuttppuutt + $ hledger balance -O csv # write CSV to stdout + $ hledger balance -o FILE.csv # write CSV to FILE.csv + + 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 + option, or by specifying a .csv file extension with -o/--output-file. + + bbaallaanncceesshheeeett + Show a balance sheet. Alias: bs. + + ----ffllaatt show full account names, as a list (default) + + ----ddrroopp==NN + in flat mode: omit N leading account name parts + + This command displays a simple balance sheet. It currently assumes + that you have top-level accounts named asset and liability (plural + forms also allowed.) + + $ hledger balancesheet + Balance Sheet + + Assets: + $-1 assets + $1 bank:saving + $-2 cash + -------------------- + $-1 + + Liabilities: + $1 liabilities:debts + -------------------- + $1 + + Total: + -------------------- + 0 + + ccaasshhffllooww + Show a cashflow statement. Alias: cf. + + ----ffllaatt show full account names, as a list (default) + + ----ddrroopp==NN + in flat mode: omit N leading account name parts + + This command displays a simple cashflow statement It shows the change + in all "cash" (ie, liquid assets) accounts for the period. It cur- + rently assumes that cash accounts are under a top-level account named + asset and do not contain receivable or A/R (plural forms also allowed.) + + $ hledger cashflow + Cashflow Statement + + Cash flows: + $-1 assets + $1 bank:saving + $-2 cash + -------------------- + $-1 + + Total: + -------------------- + $-1 + + iinnccoommeessttaatteemmeenntt + Show an income statement. Alias: is. + + ----ffllaatt show full account names, as a list (default) + + ----ddrroopp==NN + in flat mode: omit N leading account name parts + + This command displays a simple income statement. It currently assumes + that you have top-level accounts named income (or revenue) and expense + (plural forms also allowed.) + + $ hledger incomestatement + Income Statement + + Revenues: + $-2 income + $-1 gifts + $-1 salary + -------------------- + $-2 + + Expenses: + $2 expenses + $1 food + $1 supplies + -------------------- + $2 + + Total: + -------------------- + 0 + + pprriinntt + Show transactions from the journal. + + --mm SSTTRR ----mmaattcchh==SSTTRR + show the transaction whose description is most similar to STR, + and is most recent + + --oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]] + write output to FILE instead of stdout. A recognised FMT suffix + influences the format. + + --OO FFMMTT ----oouuttppuutt--ffoorrmmaatt==FFMMTT + select the output format. Supported formats: txt, csv. + + The print command displays full transactions from the journal file, + tidily formatted and showing all amounts explicitly. The output of + print is always a valid hledger journal, but it does always not pre- + serve all original content exactly (eg directives). + + hledger's print command also shows all unit prices in effect, or (with + -B/--cost) shows cost amounts. + + The print command also supports output destination and CSV output. + + $ hledger print + 2008/01/01 income + assets:bank:checking $1 + income:salary $-1 + + 2008/06/01 gift + assets:bank:checking $1 + income:gifts $-1 + + 2008/06/02 save + assets:bank:saving $1 + assets:bank:checking $-1 + + 2008/06/03 * eat & shop + expenses:food $1 + expenses:supplies $1 + assets:cash $-2 + + 2008/12/31 * pay off + liabilities:debts $1 + assets:bank:checking $-1 + + rreeggiisstteerr + Show postings and their running total. Alias: reg. + + --HH ----hhiissttoorriiccaall + include prior postings in the running total + + --AA ----aavveerraaggee + show a running average instead of the running total (implies + --empty) + + --rr ----rreellaatteedd + show postings' siblings instead + + --ww NN ----wwiiddtthh==NN + set output width (default: terminal width or COLUMNS. -wN,M + sets description width as well) + + --oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]] + write output to FILE instead of stdout. A recognised FMT suffix + influences the format. + + --OO FFMMTT ----oouuttppuutt--ffoorrmmaatt==FFMMTT + select the output format. Supported formats: txt, csv. + + $ hledger register checking + 2008/01/01 income assets:bank:checking $1 $1 + 2008/06/01 gift assets:bank:checking $1 $2 + 2008/06/02 save assets:bank:checking $-1 $1 + 2008/12/31 pay off assets:bank:checking $-1 0 + + The register command displays postings, one per line, and their running + total. This is typically used with a query selecting a particular + account, to see that account's activity. + + $ hledger register checking -b 2008/6 --historical + 2008/06/01 gift assets:bank:checking $1 $2 + 2008/06/02 save assets:bank:checking $-1 $1 + 2008/12/31 pay off assets:bank:checking $-1 0 + + The --historical/-H flag adds the balance from any prior postings to + the running total, to show the actual historical running balance. This + is useful when you want to see just the recent activity. + + The --depth option limits the amount of sub-account detail displayed. + + 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 + 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 postings which would normally be shown. + + $ hledger register --monthly income + 2008/01 income:salary $-1 $-1 + 2008/06 income:gifts $-1 $-2 + + $ hledger register --monthly income -E + 2008/01 income:salary $-1 $-1 + 2008/02 0 $-1 + 2008/03 0 $-1 + 2008/04 0 $-1 + 2008/05 0 $-1 + 2008/06 income:gifts $-1 $-2 + 2008/07 0 $-2 + 2008/08 0 $-2 + 2008/09 0 $-2 + 2008/10 0 $-2 + 2008/11 0 $-2 + 2008/12 0 $-2 + + $ hledger register --monthly assets --depth 1 # cashflow (changes to assets) by month + 2008/01 assets $1 $1 + 2008/06 assets $-1 0 + 2008/12 assets $-1 $-1 + + With a reporting interval, register shows summary postings, one per + interval, aggregating the postings to each account. + + Periods with no activity, and summary postings with a zero amount, are + not shown by default; use the --empty/-E flag to see them. + + Often, you'll want to see just one line per interval. The --depth + option helps with this, causing subaccounts to be aggregated. + + Note when using report intervals, if you specify start/end dates these + will be adjusted outward if necessary to contain a whole number of + intervals. This ensures that the first and last intervals are full + length and comparable to the others in the report. + + CCuussttoomm rreeggiisstteerr oouuttppuutt + 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 + (about half of (width - 40) each). You can adjust this by adding a + description width as part of --width's argument, comma-separated: + --width W,D . Here's a diagram: + + <--------------------------------- width (W) ----------------------------------> + date (10) description (D) account (W-41-D) amount (12) balance (12) + DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA + + and some examples: + + $ hledger reg # use terminal width (or 80 on windows) + $ hledger reg -w 100 # use width 100 + $ COLUMNS=100 hledger reg # set with one-time environment variable + $ export COLUMNS=100; hledger reg # set till session end (or window resize) + $ hledger reg -w 100,40 # set overall width 100, description width 40 + $ hledger reg -w $COLUMNS,40 # use terminal width, and set description width + + The register command also supports the -o/--output-file and -O/--out- + put-format options for controlling output destination and CSV output. + + ssttaattss + Show some journal statistics. + + --oo FFIILLEE[[..FFMMTT]] ----oouuttppuutt--ffiillee==FFIILLEE[[..FFMMTT]] + write output to FILE instead of stdout. A recognised FMT suffix + influences the format. + + $ hledger stats + Main journal file : /src/hledger/data/sample.journal + Included journal files : + Transactions span : 2008-01-01 to 2009-01-01 (366 days) + Last transaction : 2008-12-31 (2333 days ago) + Transactions : 5 (0.0 per day) + Transactions last 30 days: 0 (0.0 per day) + Transactions last 7 days : 0 (0.0 per day) + Payees/descriptions : 5 + Accounts : 8 (depth 3) + Commodities : 1 ($) + + 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. + + The stats command also supports -o/--output-file for controlling output + destination. + + tteesstt + Run built-in unit tests. + + $ hledger test + Cases: 74 Tried: 74 Errors: 0 Failures: 0 + + This command runs hledger's built-in unit tests and displays a quick + report. With a regular expression argument, it selects only tests with + 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 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 + may not be the same as any built-in command or alias. + + hledger will detect these and include them in the command list and let + you invoke them with hledger ADDONCMD. However there are some limita- + tions: + + +o Options appearing before ADDONCMD will be visible only to hledger and + will not be passed to the add-on. Eg: hledger --help web shows + hledger's help, hledger web --help shows hledger-web's help. + + +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. + + Sometimes it may be more convenient to just run the add-on directly, + eg: hledger-web --server. + + Add-ons which are written in haskell can take advantage of the + hledger-lib library for journal parsing, reporting, command-line + options, etc. + + Here are some hledger add-ons available from Hackage, the extra direc- + tory in the hledger source, or elsewhere: + + aappii + Web API server, see hledger-api. + + aauuttoossyynncc + Download OFX bank data and/or convert OFX to hledger journal format. + + $ hledger autosync --help + usage: hledger-autosync [-h] [-m MAX] [-r] [-a ACCOUNT] [-l LEDGER] [-i INDENT] + [--initial] [--fid FID] [--assertions] [-d] [--hledger] + [--slow] [--which] + [PATH] + + Synchronize ledger. + + positional arguments: + PATH do not sync; import from OFX file + + optional arguments: + -h, --help show this help message and exit + -m MAX, --max MAX maximum number of days to process + -r, --resync do not stop until max days reached + -a ACCOUNT, --account ACCOUNT + set account name for import + -l LEDGER, --ledger LEDGER + specify ledger file to READ for syncing + -i INDENT, --indent INDENT + number of spaces to use for indentation + --initial create initial balance entries + --fid FID pass in fid value for OFX files that do not supply it + --assertions create balance assertion entries + -d, --debug enable debug logging + --hledger force use of hledger (on by default if invoked as hledger- + autosync) + --slow use slow, but possibly more robust, method of calling ledger + (no subprocess) + --which display which version of ledger/hledger/ledger-python will + be used by ledger-autosync to check for previous + transactions + $ head acct1.ofx + OFXHEADER:100 + DATA:OFXSGML + VERSION:102 + SECURITY:NONE + ENCODING:USASCII + CHARSET:1252 + COMPRESSION:NONE + OLDFILEUID:NONE + NEWFILEUIDe:8509488b59d1bb45 + + $ hledger autosync acct1.ofx + 2013/08/30 MONTHLY SERVICE FEE + ; ofxid: 3000.4303001832.201308301 + WF:4303001832 -$6.00 + [assets:business:bank:wf:bchecking:banking] $6.00 + + ledger-autosync, which includes a hledger-autosync alias, downloads + transactions from your bank(s) via OFX, and prints just the new ones as + journal entries which you can add to your journal. It can also operate + on .OFX files which you've downloaded manually. It can be a nice + alternative to hledger's built-in CSV reader, especially if your bank + supports OFX download. + + ddiiffff + Show transactions present in one journal file but not another + + $ hledger diff --help + Usage: hledger-diff account:name left.journal right.journal + $ cat a.journal + 1/1 + (acct:one) 1 + + $ cat b.journal + 1/1 + (acct:one) 1 + 2/2 + (acct:two) 2 + + $ hledger diff acct:two a.journal b.journal + Unmatched transactions in the first journal: + + Unmatched transactions in the second journal: + + 2015/02/02 + (acct:two) $2 + + hledger-diff compares two journal files. Given an account name, it + prints out the transactions affecting that account which are in one + journal file but not in the other. This can be useful for reconciling + existing journals with bank statements. + + eeqquuiittyy + Print a journal entry that resets account balances to zero. + + $ hledger balance --flat -E assets liabilities + 0 assets:bank:checking + $1 assets:bank:saving + $-2 assets:cash + $1 liabilities:debts + -------------------- + 0 + $ hledger equity assets liabilities + 2015/05/23 + assets:bank:saving $-1 + assets:cash $2 + liabilities:debts $-1 + equity:closing balances 0 + + 2015/05/23 + assets:bank:saving $1 + assets:cash $-2 + liabilities:debts $1 + equity:opening balances 0 + + This prints a journal entry which zeroes out the specified accounts (or + all accounts) with a transfer to/from "equity:closing balances" (like + Ledger's equity command). Also, it prints an similar entry with oppo- + site sign for restoring the balances from "equity:opening balances". + + These can be useful for ending one journal file and starting a new one, + respectively. By zeroing your asset and liability accounts at the end + of a file and restoring them at the start of the next one, you will see + correct asset/liability balances whether you run hledger on just one + file, or on several files concatenated with include. + + iinntteerreesstt + Generate interest transactions. + + $ hledger interest --help + Usage: hledger-interest [OPTION...] ACCOUNT + -h --help print this message and exit + -V --version show version number and exit + -v --verbose echo input ledger to stdout (default) + -q --quiet don't echo input ledger to stdout + --today compute interest up until today + -f FILE --file=FILE input ledger file (pass '-' for stdin) + -s ACCOUNT --source=ACCOUNT interest source account + -t ACCOUNT --target=ACCOUNT interest target account + --act use 'act' day counting convention + --30-360 use '30/360' day counting convention + --30E-360 use '30E/360' day counting convention + --30E-360isda use '30E/360isda' day counting convention + --constant=RATE constant interest rate + --annual=RATE annual interest rate + --bgb288 compute interest according to German BGB288 + --ing-diba compute interest according for Ing-Diba Tagesgeld account + + $ cat interest.journal + 2008/09/26 Loan + Assets:Bank EUR 10000.00 + Liabilities:Bank + + 2008/11/27 Payment + Assets:Bank EUR -3771.12 + Liabilities:Bank + + 2009/05/03 Payment + Assets:Bank EUR -1200.00 + Liabilities:Bank + + 2010/12/10 Payment + Assets:Bank EUR -3700.00 + Liabilities:Bank + + $ hledger interest -- -f interest.journal --source=Expenses:Interest \ + --target=Liabilities:Bank --30-360 --annual=0.05 Liabilities:Bank + 2008/09/26 Loan + Assets:Bank EUR 10000.00 + Liabilities:Bank EUR -10000.00 + + 2008/11/27 0.05% interest for EUR -10000.00 over 61 days + Liabilities:Bank EUR -84.72 + Expenses:Interest EUR 84.72 + + 2008/11/27 Payment + Assets:Bank EUR -3771.12 + Liabilities:Bank EUR 3771.12 + + 2008/12/31 0.05% interest for EUR -6313.60 over 34 days + Liabilities:Bank EUR -29.81 + Expenses:Interest EUR 29.81 + + 2009/05/03 0.05% interest for EUR -6343.42 over 123 days + Liabilities:Bank EUR -108.37 + Expenses:Interest EUR 108.37 + + 2009/05/03 Payment + Assets:Bank EUR -1200.00 + Liabilities:Bank EUR 1200.00 + + 2009/12/31 0.05% interest for EUR -5251.78 over 238 days + Liabilities:Bank EUR -173.60 + Expenses:Interest EUR 173.60 + + 2010/12/10 0.05% interest for EUR -5425.38 over 340 days + Liabilities:Bank EUR -256.20 + Expenses:Interest EUR 256.20 + + 2010/12/10 Payment + Assets:Bank EUR -3700.00 + Liabilities:Bank EUR 3700.00 + + hledger-interest computes interests for a given account. Using command + line flags, the program can be configured to use various schemes for + 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. + + iirrrr + Calculate internal rate of return. + + $ hledger irr --help + Usage: hledger-irr [OPTION...] + -h --help print this message and exit + -V --version show version number and exit + -c --cashflow also show all revant transactions + -f FILE --file=FILE input ledger file (pass '-' for stdin) + -i ACCOUNT --investment-account=ACCOUNT investment account + -t ACCOUNT --interest-account=ACCOUNT interest/gain/fees/losses account + -b DATE --begin=DATE calculate interest from this date + -e DATE --end=DATE calculate interest until this date + -D --daily calculate interest for each day + -W --weekly calculate interest for each week + -M --monthly calculate interest for each month + -Y --yearly calculate interest for each year + + $ cat irr.journal + 2011-01-01 Some wild speculation - I wonder if it pays off + Speculation ^a~100.00 + Cash + + 2011-02-01 More speculation (and adjustment of value) + Cash -^a~10.00 + Rate Gain -^a~1.00 + Speculation + + 2011-03-01 Lets pull out some money (and adjustment of value) + Cash ^a~30.00 + Rate Gain -^a~3.00 + Speculation + + 2011-04-01 More speculation (and it lost some money!) + Cash -^a~50.00 + Rate Gain ^a~ 5.00 + Speculation + + 2011-05-01 Getting some money out (and adjustment of value) + Speculation -^a~44.00 + Rate Gain -^a~ 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 + + $ hledger-irr -f irr.journal -t "Rate Gain" -i Speculation --monthly + 2011/01/01 - 2011/02/01: 12.49% + 2011/02/01 - 2011/03/01: 41.55% + 2011/03/01 - 2011/04/01: -51.44% + 2011/04/01 - 2011/05/01: 32.24% + 2011/05/01 - 2011/06/01: 95.92% + + hledger-irr computes the internal rate of return, also known as the + effective interest rate, of a given investment. After specifying what + account holds the investment, and what account stores the gains (or + losses, or fees, or cost), it calculates the hypothetical annual rate + of fixed rate investment that would have provided the exact same cash + flow. See the package page for more. + + pprriinntt--uunniiqquuee + Print only only journal entries which have a unique description. + + $ cat unique.journal + 1/1 test + (acct:one) 1 + 2/2 test + (acct:two) 2 + $ LEDGER_FILE=unique.journal hledger print-unique + (-f option not supported) + 2015/01/01 test + (acct:one) 1 + + rreewwrriittee + Prints all journal entries, adding specified custom postings to matched + entries. + + $ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ... + $ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33' + $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"' + + uuii + Curses-style interface, see hledger-ui. + + wweebb + Web interface, see hledger-web. + +TTRROOUUBBLLEESSHHOOOOTTIINNGG + RRuunn--ttiimmee pprroobblleemmss + 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"" + 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 + 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). + + Here's an example of setting the locale temporarily, on ubuntu + gnu/linux: + + $ file my.journal + my.journal: UTF-8 Unicode text # <- the file is UTF8-encoded + $ locale -a + C + en_US.utf8 # <- a UTF8-aware locale is available + POSIX + $ LANG=en_US.utf8 hledger -f my.journal print # <- use it for this command + + Here's one way to set it permanently, there are probably better ways: + + $ 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 + first: + + $ apt-get install language-pack-fr + $ locale -a + C + en_US.utf8 + fr_BE.utf8 + fr_CA.utf8 + fr_CH.utf8 + fr_FR.utf8 + fr_LU.utf8 + POSIX + $ LANG=fr_FR.utf8 hledger -f my.journal print + + 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 + + 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 + + Not all of Ledger's journal file syntax is supported. See file format + differences. + + hledger is slower than Ledger, and uses more memory, on large data + files. + + WWiinnddoowwss lliimmiittaattiioonnss + + In a windows CMD window, non-ascii characters and colours are not sup- + ported. + + In a windows Cygwin/MSYS/Mintty window, the tab key is not supported in + hledger add. + +EENNVVIIRROONNMMEENNTT + LLEEDDGGEERR__FFIILLEE sets the default journal file path. If not set, it is + ~/.hledger.journal. + + CCOOLLUUMMNNSS sets the default width used by the register command (normally + the full terminal width). + +FFIILLEESS + Reads data from a hledger journal file ($LEDGER_FILE or + ~/.hledger.journal by default), or a CSV file plus associated CSV rules + file. + +BBUUGGSS + The need to precede options with -- when invoked from hledger is awk- + ward. + + hledger can't render non-ascii characters when run from a Windows com- + mand prompt (up to Windows 7 at least). + + When input data contains non-ascii characters, a suitable system locale + must be configured (or there will be an unhelpful error). Eg on POSIX, + set LANG to something other than C. + + + +RREEPPOORRTTIINNGG BBUUGGSS + Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel + or hledger mail list) + + +AAUUTTHHOORRSS + Simon Michael and contributors + + +CCOOPPYYRRIIGGHHTT + 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), + hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- + dot(5), ledger(1) + + http://hledger.org + + + +hledger 0.27.98 April 2016 hledger(1)