From 80948d1db70c1aa24805b576912adb82b670e778 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 20 Apr 2016 12:44:04 -0700 Subject: [PATCH] doc: also commit info files, should fix travis --- hledger-api/doc/hledger-api.1.info | 74 + hledger-lib/doc/hledger_csv.5.info | 230 +++ hledger-lib/doc/hledger_journal.5.info | 983 ++++++++++ hledger-lib/doc/hledger_timeclock.5.info | 67 + hledger-lib/doc/hledger_timedot.5.info | 123 ++ hledger-ui/doc/hledger-ui.1.info | 289 +++ hledger-web/doc/hledger-web.1.info | 175 ++ hledger/doc/hledger.1.info | 2105 ++++++++++++++++++++++ 8 files changed, 4046 insertions(+) create mode 100644 hledger-api/doc/hledger-api.1.info create mode 100644 hledger-lib/doc/hledger_csv.5.info create mode 100644 hledger-lib/doc/hledger_journal.5.info create mode 100644 hledger-lib/doc/hledger_timeclock.5.info create mode 100644 hledger-lib/doc/hledger_timedot.5.info create mode 100644 hledger-ui/doc/hledger-ui.1.info create mode 100644 hledger-web/doc/hledger-web.1.info create mode 100644 hledger/doc/hledger.1.info diff --git a/hledger-api/doc/hledger-api.1.info b/hledger-api/doc/hledger-api.1.info new file mode 100644 index 000000000..bdc40de60 --- /dev/null +++ b/hledger-api/doc/hledger-api.1.info @@ -0,0 +1,74 @@ +This is hledger-api/doc/hledger-api.1.info, produced by makeinfo +version 4.8 from stdin. + + +File: hledger-api.1.info, Node: Top, Up: (dir) + +hledger-api(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 on port 8001, or another specified with `-p +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. + + If invoked as `hledger-api --swagger', instead of starting a server +the API docs will be printed in Swagger 2.0 format. + +* Menu: + +* OPTIONS:: + + +File: hledger-api.1.info, Node: OPTIONS, Prev: Top, Up: Top + +1 OPTIONS +********* + +Note: if invoking hledger-api as a hledger subcommand, write `--' +before options as shown above. + +`-f --file FILE' + use a different input file (default: `$LEDGER_FILE' or + `~/.hledger.journal') + +`-d --static-dir=DIR' + serve files from a different directory (default: `.') + +`-p --port=PORT' + use a different TCP port (default: 8001) + +`--swagger' + print API docs in Swagger 2.0 format, and exit + +`-h' + show usage + +`--help' + show manual + +`--man' + show manual with man + +`--info' + show manual with info + +`--version' + show version + + + +Tag Table: +Node: Top90 +Node: OPTIONS925 +Ref: #options1012 + +End Tag Table diff --git a/hledger-lib/doc/hledger_csv.5.info b/hledger-lib/doc/hledger_csv.5.info new file mode 100644 index 000000000..832ba1a27 --- /dev/null +++ b/hledger-lib/doc/hledger_csv.5.info @@ -0,0 +1,230 @@ +This is hledger-lib/doc/hledger_csv.5.info, produced by makeinfo +version 4.8 from stdin. + + +File: hledger_csv.5.info, Node: Top, Up: (dir) + +hledger_csv(5) +************** + +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 _exporting_ CSV, see CSV output. + +* Menu: + +* CSV RULES:: +* TIPS:: + + +File: hledger_csv.5.info, Node: CSV RULES, Next: TIPS, Prev: Top, Up: Top + +1 CSV RULES +*********** + +The following six kinds of rule can appear in the rules file, in any +order. Blank lines and lines beginning with `#' or `;' are ignored. + +* Menu: + +* skip:: +* date-format:: +* field list:: +* field assignment:: +* conditional block:: +* include:: + + +File: hledger_csv.5.info, Node: skip, Next: date-format, Up: CSV RULES + +1.1 skip +======== + +`skip'_`N'_ + + Skip this number of CSV records at the beginning. You'll need this +whenever your CSV data contains header lines. Eg: + + +# ignore the first CSV line +skip 1 + + +File: hledger_csv.5.info, Node: date-format, Next: field list, Prev: skip, Up: CSV RULES + +1.2 date-format +=============== + +`date-format'_`DATEFMT'_ + + When your CSV date fields are not formatted like `YYYY/MM/DD' (or +`YYYY-MM-DD' or `YYYY.MM.DD'), you'll need to specify the format. +DATEFMT is a strptime-like date parsing pattern, which must parse the +date field values completely. Examples: + + +# for dates like "6/11/2013": +date-format %-d/%-m/%Y + + +# for dates like "11/06/2013": +date-format %m/%d/%Y + + +# for dates like "2013-Nov-06": +date-format %Y-%h-%d + + +# for dates like "11/6/2013 11:32 PM": +date-format %-m/%-d/%Y %l:%M %p + + +File: hledger_csv.5.info, Node: field list, Next: field assignment, Prev: date-format, Up: CSV RULES + +1.3 field list +============== + +`fields'_`FIELDNAME1'_, _`FIELDNAME2'_... + + This (a) names the CSV fields, in order (names may not contain +whitespace, but may be omitted), and (b) assigns them to journal entry +fields if you use any of these standard field names: `date', `date2', +`status', `code', `description', `comment', `account1', `account2', +`amount', `amount-in', `amount-out', `currency'. Eg: + + +# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, +# and give the 7th and 8th fields meaningful names for later reference: +# +# CSV field: +# 1 2 3 4 5 6 7 8 +# entry field: +fields date, description, , amount, , , somefield, anotherfield + + +File: hledger_csv.5.info, Node: field assignment, Next: conditional block, Prev: field list, Up: CSV RULES + +1.4 field assignment +==================== + +_`ENTRYFIELDNAME'_ _`FIELDVALUE'_ + + This sets a journal entry field (one of the standard names above) to +the given text value, which can include CSV field values interpolated by +name (`%CSVFIELDNAME') or 1-based position (`%N'). Eg: + + +# set the amount to the 4th CSV field with "USD " prepended +amount USD %4 + + +# combine three fields to make a comment (containing two tags) +comment note: %somefield - %anotherfield, date: %1 + + Field assignments can be used instead of or in addition to a field +list. + + +File: hledger_csv.5.info, Node: conditional block, Next: include, Prev: field assignment, Up: CSV RULES + +1.5 conditional block +===================== + +`if' _`PATTERN'_ +_`FIELDASSIGNMENTS'_... + + `if' +_`PATTERN'_ +_`PATTERN'_... +_`FIELDASSIGNMENTS'_... + + This applies one or more field assignments, only to those CSV records +matched by one of the PATTERNs. The patterns are case-insensitive +regular expressions which match anywhere within the whole CSV record +(it's not yet possible to match within a specific field). When there are +multiple patterns they 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 + + +File: hledger_csv.5.info, Node: include, Prev: conditional block, Up: CSV RULES + +1.6 include +=========== + +`include'_`RULESFILE'_ + + Include another rules file at this point. `RULESFILE' is either an +absolute file path or a path relative to the current file's directory. +Eg: + + +# rules reused with several CSV files +include common.rules + + +File: hledger_csv.5.info, Node: TIPS, Prev: CSV RULES, Up: Top + +2 TIPS +****** + +Each generated journal entry will have two postings, to `account1' and +`account2' respectively. Currently it's not possible to generate +entries with more than two postings. + + 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. + + + +Tag Table: +Node: Top90 +Node: CSV RULES771 +Ref: #csv-rules877 +Node: skip1120 +Ref: #skip1216 +Node: date-format1387 +Ref: #date-format1516 +Node: field list2025 +Ref: #field-list2164 +Node: field assignment2840 +Ref: #field-assignment2997 +Node: conditional block3502 +Ref: #conditional-block3658 +Node: include4548 +Ref: #include4659 +Node: TIPS4890 +Ref: #tips4974 + +End Tag Table diff --git a/hledger-lib/doc/hledger_journal.5.info b/hledger-lib/doc/hledger_journal.5.info new file mode 100644 index 000000000..58ef58079 --- /dev/null +++ b/hledger-lib/doc/hledger_journal.5.info @@ -0,0 +1,983 @@ +This is hledger-lib/doc/hledger_journal.5.info, produced by makeinfo +version 4.8 from stdin. + + +File: hledger_journal.5.info, Node: Top, Up: (dir) + +hledger_journal(5) +****************** + +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 getting. + + 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 + +* Menu: + +* FILE FORMAT:: +* EDITOR SUPPORT:: + + +File: hledger_journal.5.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: Top, Up: Top + +1 FILE FORMAT +************* + +* Menu: + +* Transactions:: +* Dates:: +* Account names:: +* Amounts:: +* Virtual Postings:: +* Balance Assertions:: +* Prices:: +* Comments:: +* Tags:: +* Directives:: + + +File: hledger_journal.5.info, Node: Transactions, Next: Dates, Up: FILE FORMAT + +1.1 Transactions +================ + +Transactions are represented by journal entries. Each begins with a +simple date in column 0, followed by three optional fields with spaces +between them: + + * a status flag, which can be empty or `!' or `*' (meaning + "uncleared", "pending" and "cleared", or whatever you want) + + * a transaction code (eg a check number), + + * 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. + + +File: hledger_journal.5.info, Node: Dates, Next: Account names, Prev: Transactions, Up: FILE FORMAT + +1.2 Dates +========= + +* Menu: + +* Simple dates:: +* Secondary dates:: +* Posting dates:: + + +File: hledger_journal.5.info, Node: Simple dates, Next: Secondary dates, Up: Dates + +1.2.1 Simple dates +------------------ + +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'. + + +File: hledger_journal.5.info, Node: Secondary dates, Next: Posting dates, Prev: Simple dates, Up: Dates + +1.2.2 Secondary dates +--------------------- + +Real-life transactions sometimes involve more than one date - eg the +date you write a cheque, and the date it clears in your bank. When you +want to model this, eg for more accurate balances, write both dates +separated by an equals sign. The _primary date_, on the left, is used +by default; the _secondary date_, 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... + + +File: hledger_journal.5.info, Node: Posting dates, Prev: Secondary dates, Up: Dates + +1.2.3 Posting dates +------------------- + +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 +posting 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 +unspecified. + + You can also set the secondary date, with `date2:DATE2'. For +compatibility, 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. + + +File: hledger_journal.5.info, Node: Account names, Next: Amounts, Prev: Dates, Up: FILE FORMAT + +1.3 Account names +================= + +Account names typically have several parts separated by a full colon, +from which hledger derives a hierarchical chart of accounts. They can be +anything you like, but in finance there are traditionally five top-level +accounts: `assets', `liabilities', `income', `expenses', and `equity'. + + Account names may contain single spaces, eg: `assets:accounts +receivable'. Because of this, they must always be followed by at least +two spaces (or newline). + + Account names can be aliased. + + +File: hledger_journal.5.info, Node: Amounts, Next: Virtual Postings, Prev: Account names, Up: FILE FORMAT + +1.4 Amounts +=========== + +After the account name, there is usually an amount. Important: between +account name and amount, there must be *two or more* 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'). Commodity names which contain more than just letters should be +enclosed in double quotes (`1 "person hours"'). + +* Menu: + +* Decimal points and digit groups:: +* Amount display styles:: + + +File: hledger_journal.5.info, Node: Decimal points and digit groups, Next: Amount display styles, Up: Amounts + +1.4.1 Decimal points and digit groups +------------------------------------- + +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'. + + +File: hledger_journal.5.info, Node: Amount display styles, Prev: Decimal points and digit groups, Up: Amounts + +1.4.2 Amount display styles +--------------------------- + +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: + + * the position (left or right) and spacing (space or no separator) + of the commodity symbol + + * the digit group separator character (comma or period) and digit + group sizes, if any + + * the decimal point character (period or comma) + + * 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 +indirectly, eg when D's default commodity is applied to a commodity-less +amount or when an amountless posting is balanced using a price's +commodity (actually this last case does not influence the canonical +display precision but probably should). + + +File: hledger_journal.5.info, Node: Virtual Postings, Next: Balance Assertions, Prev: Amounts, Up: FILE FORMAT + +1.5 Virtual Postings +==================== + +When you parenthesise the account name in a posting, that posting is +considered _virtual_, which means: + + * it is ignored when checking that the transaction is balanced + + * 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 + +* Menu: + +* Balanced Virtual Postings:: + + +File: hledger_journal.5.info, Node: Balanced Virtual Postings, Up: Virtual Postings + +1.5.1 Balanced Virtual Postings +------------------------------- + +When the account name is bracketed, the posting is _balanced virtual_, +which is just like a virtual posting except the balanced virtual +postings 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 +occasionally 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 +equivalent journal entry using two or more real postings that will be +more correct and more error-proof. + + +File: hledger_journal.5.info, Node: Balance Assertions, Next: Prices, Prev: Virtual Postings, Up: FILE FORMAT + +1.6 Balance Assertions +====================== + +hledger supports ledger-style balance assertions in journal files. These +look like `=EXPECTEDBALANCE' following a posting's amount. Eg in this +example we assert the expected dollar balance in accounts a and b 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 protect 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. + +* Menu: + +* Assertions and ordering:: +* Assertions and commodities:: +* Assertions and subaccounts:: +* Assertions and virtual postings:: + + +File: hledger_journal.5.info, Node: Assertions and ordering, Next: Assertions and commodities, Up: Balance Assertions + +1.6.1 Assertions and ordering +----------------------------- + +hledger sorts an account's postings and assertions first by date and +then (for postings on the same day) by parse order. Note this is +different from Ledger, which sorts assertions only by parse order. +(Also, Ledger assertions do not see the accumulated effect of repeated +postings to the same account within a transaction.) + + So, hledger balance assertions keep working if you reorder +differently-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 control +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 multiple +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. + + +File: hledger_journal.5.info, Node: Assertions and commodities, Next: Assertions and subaccounts, Prev: Assertions and ordering, Up: Balance Assertions + +1.6.2 Assertions and commodities +-------------------------------- + +The asserted balance must be a simple single-commodity amount, and in +fact the assertion checks only this commodity's balance within the +(possibly multi-commodity) account balance. We could call this a partial +balance assertion. This is compatible with Ledger, and makes it possible +to make assertions about accounts containing multiple commodities. + + 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.) + + +File: hledger_journal.5.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and commodities, Up: Balance Assertions + +1.6.3 Assertions and subaccounts +-------------------------------- + +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 + + +File: hledger_journal.5.info, Node: Assertions and virtual postings, Prev: Assertions and subaccounts, Up: Balance Assertions + +1.6.4 Assertions and virtual postings +------------------------------------- + +Balance assertions are checked against all postings, both real and +virtual. They are not affected by the `--real/-R' flag or `real:' query. + + +File: hledger_journal.5.info, Node: Prices, Next: Comments, Prev: Balance Assertions, Up: FILE FORMAT + +1.7 Prices +========== + +* Menu: + +* Transaction prices:: +* Market prices:: + + +File: hledger_journal.5.info, Node: Transaction prices, Next: Market prices, Up: Prices + +1.7.1 Transaction prices +------------------------ + +When recording a transaction, you can also record an amount's price in +another commodity. This documents the exchange rate, cost (of a +purchase), or selling price (of a sale) that was in effect within this +particular transaction (or more precisely, within the particular +posting). These transaction prices are fixed, and do not change. + + Such priced amounts can be displayed in their transaction price's +commodity, 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 €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 €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 €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. + + +File: hledger_journal.5.info, Node: Market prices, Prev: Transaction prices, Up: Prices + +1.7.2 Market prices +------------------- + +Market prices are not tied to a particular transaction; they represent +historical exchange rates between two commodities, usually from some +public market which publishes such rates. + + 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 command. + + You record market prices (Ledger calls them historical prices) with +a P directive, in the journal or perhaps in a separate included file. +Market 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 € $1.35 +P 2010/1/1 € $1.40 + + Example use for market prices: tracking the value of stocks. + + +File: hledger_journal.5.info, Node: Comments, Next: Tags, Prev: Prices, Up: FILE FORMAT + +1.8 Comments +============ + +Lines in the journal beginning with a semicolon (`;') or hash (`#') or +asterisk (`*') are comments, and will be ignored. (Asterisk comments +make it easy to treat your journal like an org-mode outline in emacs.) + + 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 +postings). 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) + + +File: hledger_journal.5.info, Node: Tags, Next: Directives, Prev: Comments, Up: FILE FORMAT + +1.9 Tags +======== + +A _tag_ is a word followed by a full colon inside a transaction or +posting 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. + + +File: hledger_journal.5.info, Node: Directives, Prev: Tags, Up: FILE FORMAT + +1.10 Directives +=============== + +* Menu: + +* Account aliases:: +* account directive:: +* apply account directive:: +* Multi-line comments:: +* Default commodity:: +* Default year:: +* Including other files:: + + +File: hledger_journal.5.info, Node: Account aliases, Next: account directive, Up: Directives + +1.10.1 Account aliases +---------------------- + +You can define aliases which rewrite your account names (after reading +the journal, before generating reports). hledger's account aliases can +be useful for: + + * expanding shorthand account names to their full form, allowing + easier data entry and a less verbose journal + + * adapting old journals to your current chart of accounts + + * experimenting with new account organisations, like a new hierarchy + or combining two accounts into one + + * customising reports + + See also How to use account aliases. + +* Menu: + +* Basic aliases:: +* Regex aliases:: +* Multiple aliases:: +* end aliases:: + + +File: hledger_journal.5.info, Node: Basic aliases, Next: Regex aliases, Up: Account aliases + +1.10.1.1 Basic aliases +...................... + +To set an account alias, use the `alias' directive in your journal +file. This affects all subsequent journal entries in the current file or +its included files. The spaces around the = are optional: + + +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 +occurrence 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" + + +File: hledger_journal.5.info, Node: Regex aliases, Next: Multiple aliases, Prev: Basic aliases, Up: Account aliases + +1.10.1.2 Regex aliases +...................... + +There is also a more powerful variant that uses a regular expression, +indicated by the forward slashes. (This was the default behaviour in +hledger 0.24-0.25): + + +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 +REPLACEMENT. If REGEX contains parenthesised match groups, these can be +referenced by the usual numeric backreferences in REPLACEMENT. Note, +currently 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" + + +File: hledger_journal.5.info, Node: Multiple aliases, Next: end aliases, Prev: Regex aliases, Up: Account aliases + +1.10.1.3 Multiple aliases +......................... + +You can define as many aliases as you like using directives or +command-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 following +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 + + +File: hledger_journal.5.info, Node: end aliases, Prev: Multiple aliases, Up: Account aliases + +1.10.1.4 end aliases +.................... + +You can clear (forget) all currently defined aliases with the `end +aliases' directive: + + +end aliases + + +File: hledger_journal.5.info, Node: account directive, Next: apply account directive, Prev: Account aliases, Up: Directives + +1.10.2 account directive +------------------------ + +The `account' directive predefines account names, as in Ledger and +Beancount. 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. + + +File: hledger_journal.5.info, Node: apply account directive, Next: Multi-line comments, Prev: account directive, Up: Directives + +1.10.3 apply account directive +------------------------------ + +You can specify a parent account which will be prepended to all accounts +within a section of the journal. Use the `apply account' and `end apply +account' directives like so: + + +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 supported. + + +File: hledger_journal.5.info, Node: Multi-line comments, Next: Default commodity, Prev: apply account directive, Up: Directives + +1.10.4 Multi-line comments +-------------------------- + +A line containing just `comment' starts a multi-line comment, and a +line containing just `end comment' ends it. See comments. + + +File: hledger_journal.5.info, Node: Default commodity, Next: Default year, Prev: Multi-line comments, Up: Directives + +1.10.5 Default commodity +------------------------ + +You can set a default commodity, to be used for amounts without one. Use +the D directive with a sample amount. The commodity (and the sample +amount's display style) will be applied to all subsequent commodity-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 £ as the default commodity +D £1,000.00 + +2010/1/1 + a 2340 + b + +2014/1/1 + c £1000 + d + + +$ hledger print +2010/01/01 + a £2,340.00 + b £-2,340.00 + +2014/01/01 + c £1,000.00 + d £-1,000.00 + + +File: hledger_journal.5.info, Node: Default year, Next: Including other files, Prev: Default commodity, Up: Directives + +1.10.6 Default year +------------------- + +You can set a default year to be used for subsequent dates which don't +specify a year. This is a line beginning with `Y' followed by the year. +Eg: + + +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 + + +File: hledger_journal.5.info, Node: Including other files, Prev: Default year, Up: Directives + +1.10.7 Including other files +---------------------------- + +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.) + + +File: hledger_journal.5.info, Node: EDITOR SUPPORT, Prev: FILE FORMAT, Up: Top + +2 EDITOR SUPPORT +**************** + +Add-on modes exist for various text editors, to make working with +journal files easier. They add colour, navigation aids and helpful +commands. 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: + +Emacs http://www.ledger-cli.org/3.0/doc/ledger-mode.html +Vim https://github.com/ledger/ledger/wiki/Getting-started +Sublime Text https://github.com/ledger/ledger/wiki/Using-Sublime-Text +Textmate https://github.com/ledger/ledger/wiki/Using-TextMate-2 +Text Wrangler https://github.com/ledger/ledger/wiki/Editing-Ledger-files-with-TextWrangler + + + +Tag Table: +Node: Top94 +Node: FILE FORMAT2260 +Ref: #file-format2386 +Node: Transactions2545 +Ref: #transactions2665 +Node: Dates3351 +Ref: #dates3479 +Node: Simple dates3544 +Ref: #simple-dates3672 +Node: Secondary dates3976 +Ref: #secondary-dates4132 +Node: Posting dates5408 +Ref: #posting-dates5539 +Node: Account names6715 +Ref: #account-names6854 +Node: Amounts7338 +Ref: #amounts7476 +Node: Decimal points and digit groups8003 +Ref: #decimal-points-and-digit-groups8196 +Node: Amount display styles8751 +Ref: #amount-display-styles8924 +Node: Virtual Postings10003 +Ref: #virtual-postings10164 +Node: Balanced Virtual Postings10683 +Ref: #balanced-virtual-postings10837 +Node: Balance Assertions11452 +Ref: #balance-assertions11616 +Node: Assertions and ordering12438 +Ref: #assertions-and-ordering12623 +Node: Assertions and commodities13654 +Ref: #assertions-and-commodities13880 +Node: Assertions and subaccounts14572 +Ref: #assertions-and-subaccounts14806 +Node: Assertions and virtual postings15328 +Ref: #assertions-and-virtual-postings15537 +Node: Prices15678 +Ref: #prices15810 +Node: Transaction prices15861 +Ref: #transaction-prices16006 +Node: Market prices17613 +Ref: #market-prices17748 +Node: Comments18636 +Ref: #comments18758 +Node: Tags19870 +Ref: #tags19988 +Node: Directives20918 +Ref: #directives21033 +Node: Account aliases21202 +Ref: #account-aliases21348 +Node: Basic aliases21950 +Ref: #basic-aliases22095 +Node: Regex aliases22783 +Ref: #regex-aliases22953 +Node: Multiple aliases23723 +Ref: #multiple-aliases23897 +Node: end aliases24393 +Ref: #end-aliases24535 +Node: account directive24637 +Ref: #account-directive24819 +Node: apply account directive25115 +Ref: #apply-account-directive25313 +Node: Multi-line comments25974 +Ref: #multi-line-comments26164 +Node: Default commodity26291 +Ref: #default-commodity26466 +Node: Default year27161 +Ref: #default-year27328 +Node: Including other files27751 +Ref: #including-other-files27910 +Node: EDITOR SUPPORT28327 +Ref: #editor-support28447 + +End Tag Table diff --git a/hledger-lib/doc/hledger_timeclock.5.info b/hledger-lib/doc/hledger_timeclock.5.info new file mode 100644 index 000000000..6c92acd2a --- /dev/null +++ b/hledger-lib/doc/hledger_timeclock.5.info @@ -0,0 +1,67 @@ +This is hledger-lib/doc/hledger_timeclock.5.info, produced by makeinfo +version 4.8 from stdin. + + +File: hledger_timeclock.5.info, Node: Top, Up: (dir) + +hledger_timeclock(5) +******************** + +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: + + * use emacs and the built-in timeclock.el, or the extended + timeclock-x.el and perhaps the extras in ledgerutils.el + + * 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" + + * 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. + + + + +Tag Table: +Node: Top96 + +End Tag Table diff --git a/hledger-lib/doc/hledger_timedot.5.info b/hledger-lib/doc/hledger_timedot.5.info new file mode 100644 index 000000000..07291450c --- /dev/null +++ b/hledger-lib/doc/hledger_timedot.5.info @@ -0,0 +1,123 @@ +This is hledger-lib/doc/hledger_timedot.5.info, produced by makeinfo +version 4.8 from stdin. + + +File: hledger_timedot.5.info, Node: Top, Up: (dir) + +hledger_timedot(5) +****************** + +Timedot is a plain text format for logging dated, categorised quantities +(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, +perhaps slightly more conveniently than with hledger_journal(5) format. + +* Menu: + +* FILE FORMAT:: + + +File: hledger_timedot.5.info, Node: FILE FORMAT, Prev: Top, Up: Top + +1 FILE FORMAT +************* + +A timedot file contains a series of day entries. A day entry begins with +a date, and is followed by category/quantity pairs, one per line. Dates +are hledger-style simple dates (see hledger_journal(5)). Categories 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 + quarter" - 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 +example: + + +# 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. + + + +Tag Table: +Node: Top94 +Node: FILE FORMAT852 +Ref: #file-format955 + +End Tag Table diff --git a/hledger-ui/doc/hledger-ui.1.info b/hledger-ui/doc/hledger-ui.1.info new file mode 100644 index 000000000..7f5ef81e0 --- /dev/null +++ b/hledger-ui/doc/hledger-ui.1.info @@ -0,0 +1,289 @@ +This is hledger-ui/doc/hledger-ui.1.info, produced by makeinfo version +4.8 from stdin. + + +File: hledger-ui.1.info, Node: Top, Up: (dir) + +hledger-ui(1) +************* + +hledger-ui is hledger's curses-style interface. It reads a hledger +journal file + + 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). + +* Menu: + +* OPTIONS:: +* KEYS:: +* SCREENS:: + + +File: hledger-ui.1.info, Node: OPTIONS, Next: KEYS, Prev: Top, Up: Top + +1 OPTIONS +********* + +Note: if invoking hledger-ui as a hledger subcommand, write `--' before +options as shown above. + + Any QUERYARGS are interpreted as a hledger search query which filters +the data. + +`--flat' + show full account names, unindented + +`--no-elide' + don't compress empty parent accounts on one line + +`--register=ACCTREGEX' + start in the (first) matched account's register screen + +`--theme=default|terminal|greenterm' + use this custom display theme + +`-V --value' + show amounts as their current market value in their default + valuation commodity (accounts screen only) + +`-h' + show usage + +`--help' + show manual + +`--man' + show manual with man + +`--info' + show manual with info + +`--version' + show version + +* Menu: + +* hledger options:: + + +File: hledger-ui.1.info, Node: hledger options, Up: OPTIONS + +1.1 hledger options +=================== + +The following common hledger options should also work: + +`-f FILE --file=FILE' + use a different input file. For stdin, use - + +`--rules-file=RULESFILE' + Conversion rules file to use when reading CSV (default: FILE.rules) + +`--alias=OLD=NEW' + display accounts named OLD as NEW + +`--ignore-assertions' + ignore any failing balance assertions in the journal + +`--debug=N' + show debug output if N is 1-9 (default: 0) + +`-b --begin=DATE' + include postings/txns on or after this date + +`-e --end=DATE' + include postings/txns before this date + +`-p --period=PERIODEXP' + set start date, end date, and/or reporting interval all at once + (overrides the flags above) + +`--date2 --aux-date' + use postings/txns' secondary dates instead + +`-C --cleared' + include only cleared postings/txns + +`--pending' + include only pending postings/txns + +`-U --uncleared' + include only uncleared (and pending) postings/txns + +`-R --real' + include only non-virtual postings + +`--depth=N' + hide accounts/postings deeper than N + +`-E --empty' + show empty/zero things which are normally omitted + +`-B --cost' + show amounts in their cost price's commodity + + +File: hledger-ui.1.info, Node: KEYS, Next: SCREENS, Prev: OPTIONS, Up: Top + +2 KEYS +****** + +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. + + +File: hledger-ui.1.info, Node: SCREENS, Prev: KEYS, Up: Top + +3 SCREENS +********* + +* Menu: + +* Accounts screen:: +* Register screen:: +* Transaction screen:: +* Error screen:: + + +File: hledger-ui.1.info, Node: Accounts screen, Next: Register screen, Up: SCREENS + +3.1 Accounts screen +=================== + +This is normally the first screen displayed. It lists accounts and their +balances, like hledger's balance command. By default, it shows all +accounts and their latest ending balances. if you specify a query on the +command line, it shows just the matched accounts and the balances 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. + + +File: hledger-ui.1.info, Node: Register screen, Next: Transaction screen, Prev: Accounts screen, Up: SCREENS + +3.2 Register screen +=================== + +This screen lists all transactions affecting a particular account (like +a check register). In cleared mode (press `C') it lists only +transactions 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: + + * Each line represents a whole transaction. + + * 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.) + + * 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. + + * When no query other than a date limit is in effect, it shows the + current account's historic balance as of the transaction date. + Otherwise 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. + + +File: hledger-ui.1.info, Node: Transaction screen, Next: Error screen, Prev: Register screen, Up: SCREENS + +3.3 Transaction screen +====================== + +This screen shows a single transaction, as a general journal entry, +similar to hledger's print command and journal format +(hledger_journal(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 +transactions appear in multiple account registers). The #N number +preceding them is the transaction's position within the complete +unfiltered journal, which is a more stable id (at least until the next +reload). + + +File: hledger-ui.1.info, Node: Error screen, Prev: Transaction screen, Up: SCREENS + +3.4 Error screen +================ + +This screen will appear if there is a problem, such as a parse error, +when you press g to reload. Once you have fixed the problem described, +press g again to reload and restore normal operation. + + + +Tag Table: +Node: Top88 +Node: OPTIONS682 +Ref: #options781 +Node: hledger options1547 +Ref: #hledger-options1653 +Node: KEYS2829 +Ref: #keys2926 +Node: SCREENS3323 +Ref: #screens3410 +Node: Accounts screen3500 +Ref: #accounts-screen3630 +Node: Register screen4475 +Ref: #register-screen4632 +Node: Transaction screen6014 +Ref: #transaction-screen6174 +Node: Error screen7041 +Ref: #error-screen7165 + +End Tag Table diff --git a/hledger-web/doc/hledger-web.1.info b/hledger-web/doc/hledger-web.1.info new file mode 100644 index 000000000..5d3929ef9 --- /dev/null +++ b/hledger-web/doc/hledger-web.1.info @@ -0,0 +1,175 @@ +This is hledger-web/doc/hledger-web.1.info, produced by makeinfo +version 4.8 from stdin. + + +File: hledger-web.1.info, Node: Top, Up: (dir) + +hledger-web(1) +************** + +hledger-web is hledger's web interface. It starts a simple web +application 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 +window, 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/hostname/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. + +* Menu: + +* OPTIONS:: + + +File: hledger-web.1.info, Node: OPTIONS, Prev: Top, Up: Top + +1 OPTIONS +********* + +Note: if invoking hledger-web as a hledger subcommand, write `--' +before options as shown above. + +`--server' + disable browser-opening and auto-exit-on-idle, and log all + requests to stdout + +`--port=PORT' + set the TCP port to listen on (default: 5000) + +`--base-url=URL' + set the base url (default: http://localhost:PORT). You would + change this when sharing over the network, or integrating within a + larger website. + +`--file-url=URL' + set the static files url (default: BASEURL/static). hledger-web + normally serves static files itself, but if you wanted to serve + them from another server for efficiency, you would set the url + with this. + +`-h' + show usage + +`--help' + show manual + +`--man' + show manual with man + +`--info' + show manual with info + +`--version' + show version + +* Menu: + +* hledger options:: + + +File: hledger-web.1.info, Node: hledger options, Up: OPTIONS + +1.1 hledger options +=================== + +The following common hledger options should also work: + +`-f FILE --file=FILE' + use a different input file. For stdin, use - + +`--rules-file=RULESFILE' + Conversion rules file to use when reading CSV (default: FILE.rules) + +`--alias=OLD=NEW' + display accounts named OLD as NEW + +`--ignore-assertions' + ignore any failing balance assertions in the journal + +`--debug=N' + show debug output if N is 1-9 (default: 0) + +`-b --begin=DATE' + include postings/txns on or after this date + +`-e --end=DATE' + include postings/txns before this date + +`-p --period=PERIODEXP' + set start date, end date, and/or reporting interval all at once + (overrides the flags above) + +`--date2 --aux-date' + use postings/txns' secondary dates instead + +`-C --cleared' + include only cleared postings/txns + +`--pending' + include only pending postings/txns + +`-U --uncleared' + include only uncleared (and pending) postings/txns + +`-R --real' + include only non-virtual postings + +`--depth=N' + hide accounts/postings deeper than N + +`-E --empty' + show empty/zero things which are normally omitted + +`-B --cost' + show amounts in their cost price's commodity + + + +Tag Table: +Node: Top90 +Node: OPTIONS2622 +Ref: #options2709 +Node: hledger options3572 +Ref: #hledger-options3679 + +End Tag Table diff --git a/hledger/doc/hledger.1.info b/hledger/doc/hledger.1.info new file mode 100644 index 000000000..76f5bb0c7 --- /dev/null +++ b/hledger/doc/hledger.1.info @@ -0,0 +1,2105 @@ +This is hledger/doc/hledger.1.info, produced by makeinfo version 4.8 +from stdin. + + +File: hledger.1.info, Node: Top, Up: (dir) + +hledger(1) hledger 0.27.98 +************************** + +This is hledger's command-line interface (there are also curses and web +interfaces). Its basic function is to read a plain text file describing +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-* executables 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 +variable, 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 +editor mode such as ledger-mode for added convenience. hledger's +interactive 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. + +* Menu: + +* EXAMPLES:: +* OPTIONS:: +* QUERIES:: +* COMMANDS:: +* ADD-ON COMMANDS:: +* TROUBLESHOOTING:: + + +File: hledger.1.info, Node: EXAMPLES, Next: OPTIONS, Prev: Top, Up: Top + +1 EXAMPLES +********** + +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 + + More commands: + + +$ hledger # show available commands +$ hledger add # add more transactions to the journal file +$ hledger balance # all accounts with aggregated balances +$ hledger balance --help # show detailed 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 + + +File: hledger.1.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top + +2 OPTIONS +********* + +To see general usage and the command list: `hledger -h' or just +`hledger' + + To see usage for a specific command: `hledger COMMAND -h' + + 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 command +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: + +`-h' + show general usage (or if after COMMAND, the command's usage) + +`--help' + show hledger manual (or if after an add-on COMMAND, show the + add-on's manual) + +`--man' + show manual with man + +`--info' + show manual with info + +`--version' + show version + +`-f FILE --file=FILE' + use a different input file. For stdin, use - + +`--rules-file=RULESFILE' + Conversion rules file to use when reading CSV (default: FILE.rules) + +`--alias=OLD=NEW' + display accounts named OLD as NEW + +`--ignore-assertions' + ignore any failing balance assertions in the journal + +`--debug=N' + : show debug output if N is 1-9 (default: 0) + + Common reporting options are supported by most commands where +applicable, and individual commands may provide additional +command-specific options. Both of these must be written after the +command name. + +`-b --begin=DATE' + include postings/txns on or after this date + +`-e --end=DATE' + include postings/txns before this date + +`-D --daily' + multiperiod/multicolumn report by day + +`-W --weekly' + multiperiod/multicolumn report by week + +`-M --monthly' + multiperiod/multicolumn report by month + +`-Q --quarterly' + multiperiod/multicolumn report by quarter + +`-Y --yearly' + multiperiod/multicolumn report by year + +`-p --period=PERIODEXP' + set start date, end date, and/or reporting interval all at once + (overrides the flags above) + +`--date2 --aux-date' + use postings/txns' secondary dates instead + +`-C --cleared' + include only cleared postings/txns + +`--pending' + include only pending postings/txns + +`-U --uncleared' + include only uncleared (and pending) postings/txns + +`-R --real' + include only non-virtual postings + +`--depth=N' + hide accounts/postings deeper than N + +`-E --empty' + show empty/zero things which are normally omitted + +`-B --cost' + show amounts in their cost price's commodity + +* Menu: + +* Multiple files:: +* Repeated options:: +* Depth limiting:: +* Smart dates:: +* Reporting interval:: +* Period expressions:: +* Regular Expressions:: + + +File: hledger.1.info, Node: Multiple files, Next: Repeated options, Up: OPTIONS + +2.1 Multiple files +================== + +One may specify the `--file FILE' option multiple times. This is +equivalent 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. + + +File: hledger.1.info, Node: Repeated options, Next: Depth limiting, Prev: Multiple files, Up: OPTIONS + +2.2 Repeated options +==================== + +Otherwise, if a reporting option is repeated, the last one takes +precedence. Eg -p jan -p feb is equivalent to -p feb. + + +File: hledger.1.info, Node: Depth limiting, Next: Smart dates, Prev: Repeated options, Up: OPTIONS + +2.3 Depth limiting +================== + +With the `--depth N' option, commands like account, balance and +register will show only the uppermost accounts in the account tree, down +to level N. Use this when you want a summary with less detail. + + +File: hledger.1.info, Node: Smart dates, Next: Reporting interval, Prev: Depth limiting, Up: OPTIONS + +2.4 Smart dates +=============== + +hledger's user interfaces accept a flexible "smart date" syntax (unlike +dates in the journal file). Smart dates allow some english words, can be +relative to today's date, and can have less-significant date parts +omitted (defaulting to 1). + + Examples: + +`2009/1/1', `2009/01/01', `2009-1-1', `2009.1.1' simple dates, several separators allowed +`2009/1', `2009' same as above - a missing day or month defaults to 1 +`1/1', `january', `jan', `this year' relative dates, meaning january 1 of the current year +`next year' january 1 of next year +`this month' the 1st of the current month +`this week' the most recent monday +`last week' the monday of the week before this one +`lastweek' spaces are optional +`today', `yesterday', `tomorrow' + + +File: hledger.1.info, Node: Reporting interval, Next: Period expressions, Prev: Smart dates, Up: OPTIONS + +2.5 Reporting interval +====================== + +A reporting interval can be specified so that commands like register, +balance and activity will divide their reports into multiple report +periods. The basic intervals can be selected with one of `-D/--daily', +`-W/--weekly', `-M/--monthly', `-Q/--quarterly', or `-Y/--yearly'. More +complex intervals may be specified with a period expression. + + +File: hledger.1.info, Node: Period expressions, Next: Regular Expressions, Prev: Reporting interval, Up: OPTIONS + +2.6 Period expressions +====================== + +The `-p/--period' option accepts period expressions, a shorthand way of +expressing a start date, end date, and or reporting interval all at +once. Note a period expression on the command line will cause any other +date flags (`-b'/`-e'/`-D'/`-W'/`-M'/`-Q'/`-Y') to be ignored. + + hledger's period expressions are similar to Ledger's, though not +identical. 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, as +long as you don't run two dates together. "to" can also be written as +"-". These are equivalent to the above: + +`-p "2009/1/1 2009/4/1"' +`-p2009/1/1to2009/4/1' +`-p2009/1/1-2009/4/1' + + Dates are smart dates, so if the current year is 2009, the above can +also be written as: + +`-p "1/1 4/1"' +`-p "january-apr"' +`-p "this year to 4/1"' + + If you specify only one date, the missing start or end date will be +the earliest or latest transaction in your journal: + +`-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"' + + +File: hledger.1.info, Node: Regular Expressions, Prev: Period expressions, Up: OPTIONS + +2.7 Regular Expressions +======================= + +hledger uses regular expressions in a number of places: + + * query terms, on the command line and in the hledger-web search + form: `REGEX', `desc:REGEX', `cur:REGEX', `tag:...=REGEX' + + * CSV rules conditional blocks: `if REGEX ...' + + * account alias directives and options: `alias /REGEX/ = + REPLACEMENT', `--alias /REGEX/=REPLACEMENT' + + hledger's regular expressions come from the regex-tdfa library. In +general they: + + * are case insensitive + + * are infix matching (do not need to match the entire thing being + matched) + + * are POSIX extended regular expressions + + * also support GNU word boundaries (\<, \>, \b, \B) + + * and parenthesised capturing groups and numeric backreferences in + replacement strings + + * do not support mode modifiers like (?s) + + Some things to note: + + * In the `alias' directive and `--alias' option, regular expressions + must be enclosed in forward slashes (`/REGEX/'). Elsewhere in + hledger, these are not required. + + * To match a regular expression metacharacter like `$' as a literal + character, prepend a backslash. Eg to search for amounts with the + dollar sign in hledger-web, write `cur:\$'. + + * On the command line, some metacharacters like `$' have a special + meaning 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:\\$'. + + + +File: hledger.1.info, Node: QUERIES, Next: COMMANDS, Prev: OPTIONS, Up: Top + +3 QUERIES +********* + +One of hledger's strengths is being able to quickly report on precise +subsets of your data. Most commands accept an optional query expression, +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) + + * any of the description terms AND + + * any of the account terms AND + + * all the other terms. + + The print command: show transactions which + + * match any of the description terms AND + + * have any postings matching any of the positive account terms AND + + * have no postings matching any of the negative account terms AND + + * match all the other terms. + + The following kinds of search terms can be used: + +*`REGEX'* + match account names by this regular expression + +*`acct:REGEX'* + same as above + +*`amt:N, amt:N, amt:>=N'* + match postings with a single-commodity amount that is equal to, + less than, or greater than N. (Multi-commodity amounts are not + tested, and will always match.) The comparison has two modes: if N + is preceded by a + or - sign (or is 0), the two signed numbers are + compared. Otherwise, the absolute magnitudes are compared, + ignoring sign. + +*`code:REGEX'* + match by transaction code (eg check number) + +*`cur:REGEX'* + match postings or transactions including any amounts whose + currency/commodity symbol is fully matched by REGEX. (For a partial + 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:\\$'. + +*`desc:REGEX'* + match transaction descriptions + +*`date:PERIODEXPR'* + match dates within the specified period (which should not include a + reporting interval + +*`date2:PERIODEXPR'* + as above, but match secondary dates + +*`depth:N'* + match (or display, depending on command) accounts at or above this + depth + +*`real:, real:0'* + match real or virtual postings respectively + +*`status:*, status:!, status:'* + match cleared, pending, or uncleared/pending transactions + respectively + +*`tag:REGEX[=REGEX]'* + match by tag name, and optionally also by tag value. Note a tag: + query is considered to match a transaction if it matches any of + the postings. Also remember that postings inherit the tags of + their parent transaction. + +*`not:'* + before any of the above negates the match. + +----------------------------------------------------------------------- +Some of these can also be expressed as command-line options (eg +`depth:2' is equivalent to `--depth 2'). Generally you can mix options +and query arguments, and the resulting query will be their intersection +(perhaps excluding the `-p/--period' option). + + +File: hledger.1.info, Node: COMMANDS, Next: ADD-ON COMMANDS, Prev: QUERIES, Up: Top + +4 COMMANDS +********** + +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 +displayed in the command list (`hledger is'). + +* Menu: + +* accounts:: +* activity:: +* add:: +* balance:: +* balancesheet:: +* cashflow:: +* help:: +* incomestatement:: +* info:: +* man:: +* print:: +* register:: +* stats:: +* test:: + + +File: hledger.1.info, Node: accounts, Next: activity, Up: COMMANDS + +4.1 accounts +============ + +Show account names. + +`--tree' + show short account names, as a tree + +`--flat' + show full account names, as a list (default) + +`--drop=N' + 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 + + +File: hledger.1.info, Node: activity, Next: add, Prev: accounts, Up: COMMANDS + +4.2 activity +============ + +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 ** + + +File: hledger.1.info, Node: add, Next: balance, Prev: activity, Up: COMMANDS + +4.3 add +======= + +Prompt for transactions and add them to the journal. + +`--no-new-accounts' + 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 +transactions, 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: + + * add tries to provide useful defaults, using the most similar recent + transaction (by description) as a template. + + * You can also set the initial defaults with command line arguments. + + * Readline-style edit keys can be used during data entry. + + * The tab key will auto-complete whenever possible - accounts, + descriptions, dates (`yesterday', `today', `tomorrow'). If the + input area is empty, it will insert the default value. + + * If the journal defines a default commodity, it will be added to + any bare numbers entered. + + * A parenthesised transaction code may be entered following a date. + + * Comments and tags may be entered following a description or amount. + + * If you make a mistake, enter `<' at any prompt to restart the + transaction. + + * 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]: $ + + +File: hledger.1.info, Node: balance, Next: balancesheet, Prev: add, Up: COMMANDS + +4.4 balance +=========== + +Show accounts and their balances. Alias: bal. + +`--tree' + show short account names, as a tree + +`--flat' + show full account names, as a list (default) + +`--drop=N' + in flat mode: omit N leading account name parts + +`--format=LINEFORMAT' + in single-column balance reports: use this custom line format + +`--no-elide' + in tree mode: don't squash boring parent accounts + +`-H --historical' + in multicolumn mode: show historical ending balances + +`--cumulative' + in multicolumn mode: show accumulated ending balances + +`-A --average' + in multicolumn mode: show a row average column + +`-T --row-total' + in multicolumn mode: show a row total column + +`-N --no-total' + don't show the final total row + +`-V --value' + show amounts as their current market value in their default + valuation commodity + +`-o FILE[.FMT] --output-file=FILE[.FMT]' + write output to FILE instead of stdout. A recognised FMT suffix + influences the format. + +`-O FMT --output-format=FMT' + 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 _change_ to each +account's balance caused by all (matched) postings. In the common case +where you do not filter by date and your journal sets the correct +opening balances, 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. + + A final total is displayed by default; use `-N/--no-total' to +suppress it: + + +$ hledger balance -p 2008/6 expenses --no-total + $2 expenses + $1 food + $1 supplies + +* Menu: + +* Flat mode:: +* Depth limited balance reports:: +* Multicolumn balance reports:: +* Market value:: +* Custom balance output:: +* Output destination:: +* CSV output:: + + +File: hledger.1.info, Node: Flat mode, Next: Depth limited balance reports, Up: balance + +4.4.1 Flat mode +--------------- + +To see a flat list of full account names instead of the default +hierarchical 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. + + +$ hledger balance -p 2008/6 expenses -N --flat --drop 1 + $1 food + $1 supplies + + +File: hledger.1.info, Node: Depth limited balance reports, Next: Multicolumn balance reports, Prev: Flat mode, Up: balance + +4.4.2 Depth limited balance reports +----------------------------------- + +With `--depth N', balance shows accounts only to the specified depth. +This is very useful to show a complex charts of accounts in less +detail. In flat mode, balances from accounts below the depth limit will +be shown as part of a parent account at the depth limit. + + +$ hledger balance -N --depth 1 + $-1 assets + $2 expenses + $-2 income + $1 liabilities + + +File: hledger.1.info, Node: Multicolumn balance reports, Next: Market value, Prev: Depth limited balance reports, Up: balance + +4.4.3 Multicolumn balance reports +--------------------------------- + +With a reporting interval, multiple balance columns will be shown, one +for each report period. There are three types of multi-column balance +report, showing different information: + + 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 + 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 + + 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: + + + $ 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 + + 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 ^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 + + + Multi-column balance reports display accounts in flat mode by +default; to see the hierarchy, use `--tree'. + + With a reporting interval (like `--quarterly' above), the report +start/end dates will be adjusted 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 in multicolumn balance +reports: 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. + + Here's an example of all three: + + +$ hledger balance -Q income expenses --tree -ETA +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 + + +File: hledger.1.info, Node: Market value, Next: Custom balance output, Prev: Multicolumn balance reports, Up: balance + +4.4.4 Market value +------------------ + +The `-V/--value' flag converts all the reported amounts to their +"current market value" using their default market price. That is the +latest market price (P directive) found in the journal (or an included +file), 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. + + +File: hledger.1.info, Node: Custom balance output, Next: Output destination, Prev: Market value, Up: balance + +4.4.5 Custom balance output +--------------------------- + +In simple (non-multi-column) balance reports, you can customise the +output with `--format FMT': + + +$ 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 + + The FMT format string (plus a newline) specifies the formatting +applied to each account/balance pair. It may contain any suitable text, +with data fields interpolated like so: + + `%[MIN][.MAX](FIELDNAME)' + + * MIN pads with spaces to at least this width (optional) + + * MAX truncates at this width (optional) + + * FIELDNAME must be enclosed in parentheses, and can be one of: + + * `depth_spacer' - a number of spaces equal to the account's + depth, or if MIN is specified, MIN * depth spaces. + + * `account' - the account's name + + * `total' - the account's balance/posted total, right justified + + + Also, FMT can begin with an optional prefix to control how +multi-commodity amounts are rendered: + + * `%_' - render on multiple lines, bottom-aligned (the default) + + * `%^' - render on multiple lines, top-aligned + + * `%,' - render on one line, comma-separated + + There are some quirks. Eg in one-line mode, `%(depth_spacer)' has no +effect, instead `%(account)' has indentation built in. Experimentation +may be needed to get pleasing results. + + Some example formats: + + * `%(total)' - the account's total + + * `%-20.20(account)' - the account's name, left justified, padded to + 20 characters and clipped at 20 characters + + * `%,%-50(account) %25(total)' - account name padded to 50 + characters, total padded to 20 characters, with multiple + commodities rendered on one line + + * `%20(total) %2(depth_spacer)%-(account)' - the default format for + the single-column balance report + + +File: hledger.1.info, Node: Output destination, Next: CSV output, Prev: Custom balance output, Up: balance + +4.4.6 Output destination +------------------------ + +The balance, print, register and stats commands can write their output +to a destination other than the console. This is controlled by the +`-o/--output-file' option. + + +$ hledger balance -o - # write to stdout (the default) +$ hledger balance -o FILE # write to FILE + + +File: hledger.1.info, Node: CSV output, Prev: Output destination, Up: balance + +4.4.7 CSV output +---------------- + +The balance, print and register commands can write their output as CSV. +This is useful for exporting data to other applications, eg to make +charts in a spreadsheet. This is controlled by the `-O/--output-format' +option, or by specifying a `.csv' file extension with +`-o/--output-file'. + + +$ hledger balance -O csv # write CSV to stdout +$ hledger balance -o FILE.csv # write CSV to FILE.csv + + +File: hledger.1.info, Node: balancesheet, Next: cashflow, Prev: balance, Up: COMMANDS + +4.5 balancesheet +================ + +Show a balance sheet. Alias: bs. + +`--flat' + show full account names, as a list (default) + +`--drop=N' + 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 + + +File: hledger.1.info, Node: cashflow, Next: help, Prev: balancesheet, Up: COMMANDS + +4.6 cashflow +============ + +Show a cashflow statement. Alias: cf. + +`--flat' + show full account names, as a list (default) + +`--drop=N' + 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 +currently 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 + + +File: hledger.1.info, Node: help, Next: incomestatement, Prev: cashflow, Up: COMMANDS + +4.7 help +======== + +Show one of the hledger manuals. + + The `help' command displays any of the main hledger man pages. +(Unlike `hledger --help', which displays only the hledger man page.) +Run it with no arguments to list available topics (their names are +shortened for easier typing), and run `hledger help TOPIC' to select +one. The output is similar to a man page, but fixed width. It may be +long, so you may wish to pipe it into a pager. See also info and man. + + +$ hledger help +Choose a topic, eg: hledger help cli +cli, ui, web, api, journal, csv, timeclock, timedot + + +$ hledger help cli | less + +hledger(1) hledger User Manuals hledger(1) + + + +NAME + hledger - a command-line accounting tool + +SYNOPSIS + hledger [-f FILE] COMMAND [OPTIONS] [CMDARGS] + hledger [-f FILE] ADDONCMD -- [OPTIONS] [CMDARGS] +: + + +File: hledger.1.info, Node: incomestatement, Next: info, Prev: help, Up: COMMANDS + +4.8 incomestatement +=================== + +Show an income statement. Alias: is. + +`--flat' + show full account names, as a list (default) + +`--drop=N' + 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 + + +File: hledger.1.info, Node: info, Next: man, Prev: incomestatement, Up: COMMANDS + +4.9 info +======== + +Show one of the hledger manuals using info. + + The `info' command displays any of the hledger reference manuals +using the info hypertextual documentation viewer. This can be a very +efficient way to browse large manuals. It requires the "info" program to +be available in your PATH. + + As with help, run it with no arguments to list available topics +(manuals). + + +File: hledger.1.info, Node: man, Next: print, Prev: info, Up: COMMANDS + +4.10 man +======== + +Show one of the hledger manuals using man. + + The `man' command displays any of the hledger reference manuals +using man, the standard documentation viewer on unix systems. This will +fit the text to your terminal width, and probably invoke a pager +automatically. It requires the "man" program to be available in your +PATH. + + As with help, run it with no arguments to list available topics +(manuals). + + +File: hledger.1.info, Node: print, Next: register, Prev: man, Up: COMMANDS + +4.11 print +========== + +Show transactions from the journal. + +`-m STR --match=STR' + show the transaction whose description is most similar to STR, and + is most recent + +`-o FILE[.FMT] --output-file=FILE[.FMT]' + write output to FILE instead of stdout. A recognised FMT suffix + influences the format. + +`-O FMT --output-format=FMT' + select the output format. Supported formats: txt, csv. + + +$ 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 + + 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 preserve 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. + + +File: hledger.1.info, Node: register, Next: stats, Prev: print, Up: COMMANDS + +4.12 register +============= + +Show postings and their running total. Alias: reg. + +`-H --historical' + include prior postings in the running total + +`-A --average' + show a running average instead of the running total (implies + -empty) + +`-r --related' + show postings' siblings instead + +`-w N --width=N' + set output width (default: terminal width or COLUMNS. -wN,M sets + description width as well) + +`-o FILE[.FMT] --output-file=FILE[.FMT]' + write output to FILE instead of stdout. A recognised FMT suffix + influences the format. + +`-O FMT --output-format=FMT' + select the output format. Supported formats: txt, csv. + + 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 +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 `--historical'/`-H' flag adds the balance from any undisplayed +prior postings to the running total. This is useful when you want to +see only recent activity, with a historically accurate running balance: + + +$ hledger register checking -b 2008/6 --historical +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 `--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 _other_ postings in the +transactions of the postings which would normally be shown. + + With a reporting interval, register shows summary postings, one per +interval, aggregating the postings to each account: + + +$ hledger register --monthly income +2008/01 income:salary $-1 $-1 +2008/06 income:gifts $-1 $-2 + + Periods with no activity, and summary postings with a zero amount, +are not shown by default; use the `--empty'/`-E' flag to see them: + + +$ hledger register --monthly income -E +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 + + Often, you'll want to see just one line per interval. The `--depth' +option helps with this, causing subaccounts to be aggregated: + + +$ hledger register --monthly assets --depth 1h +2008/01 assets $1 $1 +2008/06 assets $-1 0 +2008/12 assets $-1 $-1 + + Note when using report intervals, if you specify start/end dates +these will be adjusted outward if necessary to contain a whole number of +intervals. This ensures that the first and last intervals are full +length and comparable to the others in the report. + +* Menu: + +* Custom register output:: + + +File: hledger.1.info, Node: Custom register output, Up: register + +4.12.1 Custom register output +----------------------------- + +register uses the full terminal width by default, except on windows. You +can override this by setting the `COLUMNS' environment variable (not a +bash shell variable) or by using the `--width'/`-w' option. + + 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/--output-format' options for controlling output destination and CSV +output. + + +File: hledger.1.info, Node: stats, Next: test, Prev: register, Up: COMMANDS + +4.13 stats +========== + +Show some journal statistics. + +`-o FILE[.FMT] --output-file=FILE[.FMT]' + 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. + + +File: hledger.1.info, Node: test, Prev: stats, Up: COMMANDS + +4.14 test +========= + +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. + + +File: hledger.1.info, Node: ADD-ON COMMANDS, Next: TROUBLESHOOTING, Prev: COMMANDS, Up: Top + +5 ADD-ON COMMANDS +***************** + +Add-on commands are executables in your PATH whose name starts with +`hledger-' and ends with any of these file extensions: none, +`.hs',`.lhs',`.pl',`.py',`.rb',`.rkt',`.sh',`.bat',`.com',`.exe'. +Also, an add-on's name 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 +limitations: + + * Options appearing before ADDONCMD will be visible only to hledger + and will not be passed to the add-on. Eg: `hledger -h web' shows + hledger's usage, `hledger web -h' shows hledger-web's usage. + + * 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 +directory in the hledger source, or elsewhere: + +* Menu: + +* api:: +* autosync:: +* diff:: +* equity:: +* interest:: +* irr:: +* print-unique:: +* rewrite:: +* ui:: +* web:: + + +File: hledger.1.info, Node: api, Next: autosync, Up: ADD-ON COMMANDS + +5.1 api +======= + +Web API server, see hledger-api. + + +File: hledger.1.info, Node: autosync, Next: diff, Prev: api, Up: ADD-ON COMMANDS + +5.2 autosync +============ + +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. + + +File: hledger.1.info, Node: diff, Next: equity, Prev: autosync, Up: ADD-ON COMMANDS + +5.3 diff +======== + +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. + + +File: hledger.1.info, Node: equity, Next: interest, Prev: diff, Up: ADD-ON COMMANDS + +5.4 equity +========== + +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 +opposite 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. + + +File: hledger.1.info, Node: interest, Next: irr, Prev: equity, Up: ADD-ON COMMANDS + +5.5 interest +============ + +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. Furthermore, 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ür Verbrauchergeschäfte). +See the package page for more. + + +File: hledger.1.info, Node: irr, Next: print-unique, Prev: interest, Up: ADD-ON COMMANDS + +5.6 irr +======= + +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 €100.00 + Cash + +2011-02-01 More speculation (and adjustment of value) + Cash -€10.00 + Rate Gain -€1.00 + Speculation + +2011-03-01 Lets pull out some money (and adjustment of value) + Cash €30.00 + Rate Gain -€3.00 + Speculation + +2011-04-01 More speculation (and it lost some money!) + Cash -€50.00 + Rate Gain € 5.00 + Speculation + +2011-05-01 Getting some money out (and adjustment of value) + Speculation -€44.00 + Rate Gain -€ 3.00 + Cash + +2011-06-01 Emptying the account (after adjusting the value) + Speculation -€85.00 + Cash €90.00 + Rate Gain -€ 5.00 + + +$ hledger-irr -f irr.journal -t "Rate Gain" -i Speculation --monthly +2011/01/01 - 2011/02/01: 12.49% +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. + + +File: hledger.1.info, Node: print-unique, Next: rewrite, Prev: irr, Up: ADD-ON COMMANDS + +5.7 print-unique +================ + +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 + + +File: hledger.1.info, Node: rewrite, Next: ui, Prev: print-unique, Up: ADD-ON COMMANDS + +5.8 rewrite +=========== + +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"' + + +File: hledger.1.info, Node: ui, Next: web, Prev: rewrite, Up: ADD-ON COMMANDS + +5.9 ui +====== + +Curses-style interface, see hledger-ui. + + +File: hledger.1.info, Node: web, Prev: ui, Up: ADD-ON COMMANDS + +5.10 web +======== + +Web interface, see hledger-web. + + +File: hledger.1.info, Node: TROUBLESHOOTING, Prev: ADD-ON COMMANDS, Up: Top + +6 TROUBLESHOOTING +***************** + +* Menu: + +* Run-time problems:: +* Known limitations:: + + +File: hledger.1.info, Node: Run-time problems, Next: Known limitations, Up: TROUBLESHOOTING + +6.1 Run-time problems +===================== + +Here are some issues you might encounter when you run hledger (and +remember you can also seek help from the IRC channel, mail list or bug +tracker): + + *Successfully installed, but "No command 'hledger' found"* +stack and cabal install binaries into a special directory, which should +be added to your PATH environment variable. Eg on unix-like systems, +that is ~/.local/bin and ~/.cabal/bin respectively. + + *I set a custom LEDGER_FILE, but hledger is still using the default +file* +`LEDGER_FILE' should be a real environment variable, not just a shell +variable. The command `env | grep LEDGER_FILE' should show it. You may +need to use `export'. Here's an explanation. + + *"Illegal byte sequence" or "Invalid or incomplete multibyte or wide +character" errors* +In order to handle non-ascii letters and symbols (like £), hledger +needs an appropriate locale. This is usually configured system-wide; +you can also configure it temporarily. The locale may need to be one +that 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'). + + +File: hledger.1.info, Node: Known limitations, Prev: Run-time problems, Up: TROUBLESHOOTING + +6.2 Known limitations +===================== + +*Command line interface* + + Add-on command options, unless they are also understood by the main +hledger executable, must be written after `--', like this: `hledger web +-- --server' + + *Differences from Ledger* + + 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. + + *Windows limitations* + + In a windows CMD window, non-ascii characters and colours are not +supported. + + In a windows Cygwin/MSYS/Mintty window, the tab key is not supported +in hledger add. + + + +Tag Table: +Node: Top82 +Node: EXAMPLES1754 +Ref: #examples1856 +Node: OPTIONS3508 +Ref: #options3612 +Node: Multiple files6386 +Ref: #multiple-files6511 +Node: Repeated options6750 +Ref: #repeated-options6902 +Node: Depth limiting7022 +Ref: #depth-limiting7167 +Node: Smart dates7368 +Ref: #smart-dates7509 +Node: Reporting interval8506 +Ref: #reporting-interval8665 +Node: Period expressions9008 +Ref: #period-expressions9175 +Node: Regular Expressions11221 +Ref: #regular-expressions11363 +Node: QUERIES12846 +Ref: #queries12950 +Node: COMMANDS16125 +Ref: #commands16239 +Node: accounts16912 +Ref: #accounts17012 +Node: activity17994 +Ref: #activity18106 +Node: add18465 +Ref: #add18566 +Node: balance21160 +Ref: #balance21273 +Node: Flat mode23989 +Ref: #flat-mode24116 +Node: Depth limited balance reports24535 +Ref: #depth-limited-balance-reports24738 +Node: Multicolumn balance reports25159 +Ref: #multicolumn-balance-reports25361 +Node: Market value30010 +Ref: #market-value30174 +Node: Custom balance output30667 +Ref: #custom-balance-output30840 +Node: Output destination32944 +Ref: #output-destination33109 +Node: CSV output33379 +Ref: #csv-output33498 +Node: balancesheet33895 +Ref: #balancesheet34023 +Node: cashflow34675 +Ref: #cashflow34792 +Node: help35482 +Ref: #help35594 +Node: incomestatement36431 +Ref: #incomestatement36561 +Node: info37288 +Ref: #info37395 +Node: man37757 +Ref: #man37854 +Node: print38257 +Ref: #print38362 +Node: register39713 +Ref: #register39826 +Node: Custom register output44167 +Ref: #custom-register-output44298 +Node: stats45595 +Ref: #stats45701 +Node: test46582 +Ref: #test46669 +Node: ADD-ON COMMANDS47036 +Ref: #add-on-commands47172 +Node: api48460 +Ref: #api48552 +Node: autosync48586 +Ref: #autosync48701 +Node: diff51016 +Ref: #diff51126 +Node: equity51790 +Ref: #equity51904 +Node: interest53232 +Ref: #interest53349 +Node: irr56433 +Ref: #irr56546 +Node: print-unique58921 +Ref: #print-unique59051 +Node: rewrite59309 +Ref: #rewrite59428 +Node: ui59731 +Ref: #ui59831 +Node: web59872 +Ref: #web59960 +Node: TROUBLESHOOTING59993 +Ref: #troubleshooting60112 +Node: Run-time problems60166 +Ref: #run-time-problems60309 +Node: Known limitations62253 +Ref: #known-limitations62396 + +End Tag Table