diff --git a/Makefile b/Makefile index 9bd946b03..82537d15a 100644 --- a/Makefile +++ b/Makefile @@ -1033,6 +1033,34 @@ haddock: \ # # cd site/api && \ # # hoogle --convert=main.txt --output=default.hoo +# in subsequent rules, allow automatic variables to be used in prerequisites (use $$) +.SECONDEXPANSION: + +MANPAGES=\ + hledger-lib/hledger_csv.5 \ + hledger-lib/hledger_journal.5 \ + hledger-lib/hledger_timelog.5 \ + hledger/hledger.1 \ + hledger-ui/hledger-ui.1 \ + hledger-web/hledger-web.1 \ + +manpages: $(MANPAGES) \ + $(call def-help,manpages, generate man pages from markdown ) + +%.1 %.5: $$@.md doc/manpage.template + pandoc $< -t man -s --template doc/manpage.template -o $@ \ + --filter tools/pandocCapitalizeHeaders.hs \ + --filter tools/pandocRemoveNotes.hs \ + --filter tools/pandocRemoveLinks.hs +# --filter tools/pandocCapitalizeHeaders \ +# --filter tools/pandocRemoveNotes \ +# --filter tools/pandocRemoveLinks +# faster when compiled + + +clean-manpages: + rm -f $(MANPAGES) + ############################################################################### $(call def-help-subsection,RELEASING:) #$(call def-help-subsection,see also developer guide -> how to -> do a release) @@ -1321,9 +1349,6 @@ tagrelease: \ ############################################################################### $(call def-help-subsection,MISCELLANEOUS:) -# allow automatic variables (using $$) in the prerequisites of subsequent rules -.SECONDEXPANSION: - # XXX enable for all cabal files when hpack is a little better # gencabalfiles: $$(CABALFILES) gencabalfiles: doc/site/hakyll-std.cabal \ @@ -1386,7 +1411,7 @@ cleanghc: cleanghco \ clean: cleanghco \ $(call def-help,clean, default cleanup (ghc build leftovers) ) -Clean: stackclean cabalclean cleanghc cleantags \ +Clean: stackclean cabalclean cleanghc cleantags clean-manpages \ $(call def-help,Clean, thorough cleanup (stack/cabal/ghc builds and tags) ) # reverse = $(if $(wordlist 2,2,$(1)),$(call reverse,$(wordlist 2,$(words $(1)),$(1))) $(firstword $(1)),$(1)) diff --git a/doc/manpage.template b/doc/manpage.template new file mode 100644 index 000000000..8f66051df --- /dev/null +++ b/doc/manpage.template @@ -0,0 +1,42 @@ +$if(has-tables)$ +.\"t +$endif$ + +.TH "$title$" "$section$" "$date$" "$footer$" "hledger User Manuals" + +$for(header-includes)$ +$header-includes$ +$endfor$ + +$for(include-before)$ +$include-before$ +$endfor$ + +$body$ + +$for(include-after)$ +$include-after$ +$endfor$ + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org. + +.SH AUTHORS +$if(author)$ +$for(author)$$author$$sep$; $endfor$. +$else$ +Simon Michael +$endif$ + +.SH COPYRIGHT + +Copyright (C) 2007-2015 Simon Michael. +.br +Released under GNU GPLv3+. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) +.br +hledger_csv(5), hledger_journal(5), hledger_timelog(5) + +For more information, see http://hledger.org. diff --git a/hledger-lib/hledger_csv.5 b/hledger-lib/hledger_csv.5 new file mode 100644 index 000000000..6ab08e634 --- /dev/null +++ b/hledger-lib/hledger_csv.5 @@ -0,0 +1,258 @@ + +.TH "hledger_csv" "5" "October 2015" "" "hledger User Manuals" + + + +.SH NAME +.PP +hledger_csv \- reading CSV files with hledger, and the CSV rules file +format +.SH DESCRIPTION +.PP +hledger can read CSV files, converting each CSV record into a journal +entry (transaction), if you provide some conversion hints in a "rules +file". +This file should be named like the CSV file with an additional +\f[C]\&.rules\f[] suffix (eg: \f[C]mybank.csv.rules\f[]); or, you can +specify the file with \f[C]\-\-rules\-file\ PATH\f[]. +hledger will create it if necessary, with some default rules which +you\[aq]ll need to adjust. +At minimum, the rules file must specify the \f[C]date\f[] and +\f[C]amount\f[] fields. +For an example, see How to read CSV files. +.PP +(For CSV output, see CSV output.) +.SH CSV RULES +.PP +The following six kinds of rule can appear in the rules file, in any +order. +Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are +ignored. +.PP +\f[B]\f[C]skip\f[] \f[I]N\f[]\f[] +.PD 0 +.P +.PD +Skip this number of CSV records at the beginning. +You\[aq]ll need this when your CSV contains header lines. +Eg: +.IP +.nf +\f[C] +#\ ignore\ the\ first\ CSV\ line +skip\ 1 +\f[] +.fi +.PP +\f[B]\f[C]date\-format\f[] \f[I]DATEFMT\f[]\f[] +.PD 0 +.P +.PD +When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or +\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to +specify the format. +DATEFMT is a strptime\-like date parsing pattern, which must parse the +date field values completely. +Examples: +.IP +.nf +\f[C] +#\ parses\ "6/11/2013": +date\-format\ %\-d/%\-m/%Y +\f[] +.fi +.IP +.nf +\f[C] +#\ parses\ "11/06/2013": +date\-format\ %m/%d/%Y +\f[] +.fi +.IP +.nf +\f[C] +#\ parses\ "2013\-Nov\-06": +date\-format\ %Y\-%h\-%d +\f[] +.fi +.IP +.nf +\f[C] +#\ parses\ "11/6/2013\ 11:32\ PM": +date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p +\f[] +.fi +.PP +\f[B]\f[C]fields\f[] \f[I]CSVFIELDNAME1\f[], +\f[I]CSVFIELDNAME2\f[]...\f[] +.PD 0 +.P +.PD +(Field list) +.PD 0 +.P +.PD +This (a) names the CSV fields (names may not contain whitespace), and +(b) assigns them to journal entry fields if you use any of these +standard field names: \f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], +\f[C]code\f[], \f[C]description\f[], \f[C]comment\f[], +\f[C]account1\f[], \f[C]account2\f[], \f[C]amount\f[], +\f[C]amount\-in\f[], \f[C]amount\-out\f[], \f[C]currency\f[]. +Eg: +.IP +.nf +\f[C] +#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\ date,\ description\ and\ amount +#\ give\ the\ 7th\ and\ 8th\ fields\ custom\ names\ for\ later\ reference +fields\ date,\ description,\ ,\ amount,\ ,\ ,\ somefield,\ anotherfield +\f[] +.fi +.PP +\f[B]\f[I]ENTRYFIELDNAME\f[] \f[I]FIELDVALUE\f[]\f[] +.PD 0 +.P +.PD +(Field assignment) +.PD 0 +.P +.PD +This sets a journal entry field (one of the standard names above) to the +given text value, which can include CSV field values interpolated by +name (\f[C]%CSVFIELDNAME\f[]) or 1\-based position (\f[C]%N\f[]). + Field assignments can be used instead of or in addition to a field +list. +Eg: +.IP +.nf +\f[C] +#\ set\ the\ amount\ to\ the\ 4th\ CSV\ field\ with\ "USD\ "\ prepended +amount\ USD\ %4 +\f[] +.fi +.IP +.nf +\f[C] +#\ combine\ three\ fields\ to\ make\ a\ comment\ (containing\ two\ tags) +comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1 +\f[] +.fi +.PP +\f[B]\f[C]if\f[] \f[I]PATTERN\f[] +.PD 0 +.P +.PD +\ \ \ \ \f[I]FIELDASSIGNMENTS\f[]...\f[] +.PD 0 +.P +.PD +or +.PD 0 +.P +.PD +\f[B]\f[C]if\f[] +.PD 0 +.P +.PD +\f[I]PATTERN\f[] +.PD 0 +.P +.PD +\f[I]PATTERN\f[]... +.PD 0 +.P +.PD +\ \ \ \ \f[I]FIELDASSIGNMENTS\f[]...\f[] +.PD 0 +.P +.PD +(Conditional block) +.PD 0 +.P +.PD +This applies one or more field assignments, only to those CSV records +matched by one of the PATTERNs. +The patterns are case\-insensitive regular expressions which match +anywhere within the whole CSV record (it\[aq]s not yet possible to match +within a specific field). +When there are multiple patterns they should be written on separate +lines, unindented. +The field assignments are on separate lines indented by at least one +space. +Examples: +.IP +.nf +\f[C] +#\ if\ the\ CSV\ record\ contains\ "groceries",\ set\ account2\ to\ "expenses:groceries" +if\ groceries +\ account2\ expenses:groceries +\f[] +.fi +.IP +.nf +\f[C] +#\ if\ the\ CSV\ record\ contains\ any\ of\ these\ patterns,\ set\ account2\ and\ comment\ as\ shown +if +monthly\ service\ fee +atm\ transaction\ fee +banking\ thru\ software +\ account2\ expenses:business:banking +\ comment\ \ XXX\ deductible\ ?\ check +\f[] +.fi +.PP +\f[B]\f[C]include\f[] \f[I]RULESFILE\f[]\f[] +.PD 0 +.P +.PD +Include another rules file at this point. +\f[C]RULESFILE\f[] is either an absolute file path or a path relative to +the current file\[aq]s directory. +Eg: +.IP +.nf +\f[C] +#\ rules\ reused\ with\ several\ CSV\ files +include\ common.rules +\f[] +.fi +.SS Other CSV tips +.PP +Each generated journal entry will have two postings, to +\f[C]account1\f[] and \f[C]account2\f[] respectively. +Currently it\[aq]s not possible to generate entries with more than two +postings. +.PP +If the CSV has debit/credit amounts in separate fields, assign to the +\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead of +\f[C]amount\f[]. +.PP +If the CSV has the currency in a separate field, assign that to the +\f[C]currency\f[] pseudo field which will be automatically prepended to +the amount. +(Or you can do the same thing with a field assignment.) +.PP +If an amount value is parenthesised, it will be de\-parenthesised and +sign\-flipped automatically. +.PP +The generated journal entries will be sorted by date. +The original order of same\-day entries will be preserved, usually. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org. + +.SH AUTHORS +Simon Michael + +.SH COPYRIGHT + +Copyright (C) 2007-2015 Simon Michael. +.br +Released under GNU GPLv3+. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) +.br +hledger_csv(5), hledger_journal(5), hledger_timelog(5) + +For more information, see http://hledger.org. diff --git a/hledger-lib/hledger_csv.5.md b/hledger-lib/hledger_csv.5.md new file mode 100644 index 000000000..cba962178 --- /dev/null +++ b/hledger-lib/hledger_csv.5.md @@ -0,0 +1,147 @@ +% hledger_csv(5) +% +% October 2015 + +# NAME + +hledger_csv - reading CSV files with hledger, and the CSV rules file format + +# DESCRIPTION + +hledger can read +[CSV](http://en.wikipedia.org/wiki/Comma-separated_values) 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](how-to-read-csv-files.html). + +(For CSV output, see [CSV output](#csv-output).) + + +# 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. + +**`skip` *N***\ +Skip this number of CSV records at the beginning. +You'll need this when your CSV contains header lines. Eg: + + + + +```rules +# ignore the first CSV line +skip 1 +``` + +**`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](http://hackage.haskell.org/packages/archive/time/latest/doc/html/Data-Time-Format.html#v:formatTime), +which must parse the date field values completely. Examples: + +``` {.rules .display-table} +# parses "6/11/2013": +date-format %-d/%-m/%Y +``` + +``` {.rules .display-table} +# parses "11/06/2013": +date-format %m/%d/%Y +``` + +``` {.rules .display-table} +# parses "2013-Nov-06": +date-format %Y-%h-%d +``` + +``` {.rules .display-table} +# parses "11/6/2013 11:32 PM": +date-format %-m/%-d/%Y %l:%M %p +``` + +**`fields` *CSVFIELDNAME1*, *CSVFIELDNAME2*...**\ +(Field list)\ +This (a) names the CSV fields (names may not contain whitespace), +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: +```rules +# use the 1st, 2nd and 4th CSV fields as the entry date, description and amount +# give the 7th and 8th fields custom names for later reference +fields date, description, , amount, , , somefield, anotherfield +``` + +***ENTRYFIELDNAME* *FIELDVALUE***\ +(Field assignment)\ +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`). + +Field assignments can be used instead of or in addition to a field list. +Eg: +```{.rules .display-table} +# set the amount to the 4th CSV field with "USD " prepended +amount USD %4 +``` +```{.rules .display-table} +# combine three fields to make a comment (containing two tags) +comment note: %somefield - %anotherfield, date: %1 +``` + +**`if` *PATTERN*\ +    *FIELDASSIGNMENTS*...**\ +or\ +**`if`\ +*PATTERN*\ +*PATTERN*...\ +    *FIELDASSIGNMENTS*...**\ +(Conditional block)\ +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: +```{.rules .display-table} +# if the CSV record contains "groceries", set account2 to "expenses:groceries" +if groceries + account2 expenses:groceries +``` +```{.rules .display-table} +# 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 +``` + +**`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 +# rules reused with several CSV files +include common.rules +``` + +## Other CSV 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. + diff --git a/hledger-lib/hledger_journal.5 b/hledger-lib/hledger_journal.5 new file mode 100644 index 000000000..66fa9a6e0 --- /dev/null +++ b/hledger-lib/hledger_journal.5 @@ -0,0 +1,800 @@ + +.TH "hledger_journal" "5" "October 2015" "" "hledger User Manuals" + + + +.SH NAME +.PP +hledger_journal \- reference for hledger\[aq]s journal file format +.SH DESCRIPTION +.PP +hledger\[aq]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 \f[C]\&.journal\f[], but that\[aq]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. +.PP +hledger\[aq]s journal format is a compatible subset, mostly, of +ledger\[aq]s journal format, so hledger can work with compatible ledger +journal files as well. +It\[aq]s safe, and encouraged, to run both hledger and ledger on the +same journal file, eg to validate the results you\[aq]re getting. +.PP +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. +.PP +Here\[aq]s an example: +.IP +.nf +\f[C] +;\ A\ sample\ journal\ file.\ This\ is\ a\ comment. + +2008/01/01\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ ;\ <\-\ transaction\[aq]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 +\f[] +.fi +.PP +Now let\[aq]s explore the available journal file syntax in detail. +.SH TRANSACTIONS +.PP +Transactions are represented by journal entries. +Each begins with a simple date in column 0, followed by three optional +fields with spaces between them: +.IP \[bu] 2 +a status flag, which can be empty or \f[C]!\f[] or \f[C]*\f[] (meaning +"uncleared", "pending" and "cleared", or whatever you want) +.IP \[bu] 2 +a transaction code (eg a check number), +.IP \[bu] 2 +and/or a description +.PP +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. +.PP +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. +.SH DATES +.SS Simple dates +.PP +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. +.PP +Some examples: \f[C]2010/01/31\f[], \f[C]1/31\f[], +\f[C]2010\-01\-31\f[], \f[C]2010.1.31\f[]. +.SS Secondary dates +.PP +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 \f[I]primary date\f[], on the left, is used by default; the +\f[I]secondary date\f[], on the right, is used when the +\f[C]\-\-date2\f[] flag is specified (For Ledger compatibility, +\f[C]\-\-aux\-date\f[] or \f[C]\-\-effective\f[] also work.) +.PP +Their meaning is up to you, but it\[aq]s best to follow a consistent +rule. +Eg write the bank\[aq]s clearing date as primary, and when needed, the +date the transaction was initiated as secondary. +.PP +Here\[aq]s an example. +Note that a secondary date will use the year of the primary date if +unspecified. +.IP +.nf +\f[C] +2010/2/23=2/19\ movie\ ticket +\ \ expenses:cinema\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10 +\ \ assets:checking +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ register\ checking +2010/02/23\ movie\ ticket\ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ $\-10 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ register\ checking\ \-\-date2 +2010/02/19\ movie\ ticket\ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ $\-10 +\f[] +.fi +.PP +Secondary dates require some effort: you must use them consistently in +your journal entries and remember whether to use or not use the +\f[C]\-\-date2\f[] flag for your reports. +Arguably they are now obsolete, superseded by... +.SS Posting dates +.PP +You can give individual postings a different date from their parent +transaction, by adding a posting tag (see below) like +\f[C]date:DATE\f[], 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: +.IP +.nf +\f[C] +2015/5/30 +\ \ \ \ expenses:food\ \ \ \ \ $10\ \ \ ;\ food\ purchased\ on\ saturday\ 5/30 +\ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ ;\ bank\ cleared\ it\ on\ monday,\ date:6/1 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ \-f\ tt.j\ register\ food +2015/05/30\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ \ \ \ \ \ \ \ \ \ $10 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ \-f\ tt.j\ register\ checking +2015/06/01\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ assets:checking\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ $\-10 +\f[] +.fi +.PP +A posting date will use the year of the transaction date if unspecified. +.PP +You can also set the secondary date, with \f[C]date2:DATE2\f[]. +For compatibility, Ledger\[aq]s older posting date syntax is also +supported: \f[C][DATE]\f[], \f[C][DATE=DATE2]\f[] or \f[C][=DATE2]\f[] +in a posting comment. +.PP +When using any of these forms, be sure to provide a valid simple date or +you\[aq]ll get a parse error. +Eg a \f[C]date:\f[] tag with no value is not allowed. +.SH ACCOUNT NAMES +.PP +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: \f[C]assets\f[], \f[C]liabilities\f[], +\f[C]income\f[], \f[C]expenses\f[], and \f[C]equity\f[]. +.PP +Account names may contain single spaces, eg: +\f[C]assets:accounts\ receivable\f[]. +Because of this, they must always be followed by at least two spaces (or +newline). +.PP +Account names can be aliased. +.SH AMOUNTS +.PP +After the account name, there is usually an amount. +Important: between account name and amount, there must be \f[B]two or +more\f[] spaces. +.PP +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 (\f[C]\-$1\f[] or \f[C]$\-1\f[]). +Commodity names which contain more than just letters should be enclosed +in double quotes (\f[C]1\ "person\ hours"\f[]). +.SS Decimal points and digit groups +.PP +hledger supports flexible decimal point and digit group separator +styles, to support international variations. +Numbers can use either a period (\f[C]\&.\f[]) or a comma (\f[C],\f[]) +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 \f[C]$1,000.00\f[] or \f[C]$1.000,00\f[]. +.SS Amount display styles +.PP +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: +.IP \[bu] 2 +the position (left or right) and spacing (space or no separator) of the +commodity symbol +.IP \[bu] 2 +the digit group separator character (comma or period) and digit group +sizes, if any +.IP \[bu] 2 +the decimal point character (period or comma) +.IP \[bu] 2 +the display precision (number of decimal places displayed) +.PP +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. +.PP +The precisions used in a price amount, or a D directive, don\[aq]t +affect the canonical display precision directly, but they can affect it +indirectly, eg when D\[aq]s default commodity is applied to a +commodity\-less amount or when an amountless posting is balanced using a +price\[aq]s commodity (actually this last case does not influence the +canonical display precision but probably should). +.SH VIRTUAL POSTINGS +.PP +When you parenthesise the account name in a posting, that posting is +considered \f[I]virtual\f[], which means: +.IP \[bu] 2 +it is ignored when checking that the transaction is balanced +.IP \[bu] 2 +it is excluded from reports when the \f[C]\-\-real/\-R\f[] flag is used, +or the \f[C]real:1\f[] query. +.PP +You could use this, eg, to set an account\[aq]s opening balance without +needing to use the \f[C]equity:opening\ balances\f[] account: +.IP +.nf +\f[C] +1/1\ special\ unbalanced\ posting\ to\ set\ initial\ balance +\ \ (assets:checking)\ \ \ $1000 +\f[] +.fi +.SS Balanced Virtual Postings +.PP +When the account name is bracketed, the posting is \f[I]balanced +virtual\f[], 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 \f[C]\-\-real/\-R\f[] or +\f[C]real:1\f[]. +.PP +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. +.SH BALANCE ASSERTIONS +.PP +hledger supports ledger\-style balance assertions in journal files. +These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s +amount. +Eg in this example we assert the expected dollar balance in accounts a +and b after each posting: +.IP +.nf +\f[C] +2013/1/1 +\ \ a\ \ \ $1\ \ =$1 +\ \ b\ \ \ \ \ \ \ =$\-1 + +2013/1/2 +\ \ a\ \ \ $1\ \ =$2 +\ \ b\ \ $\-1\ \ =$\-2 +\f[] +.fi +.PP +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 +\f[C]\-\-ignore\-assertions\f[] flag, which can be useful for +troubleshooting or for reading Ledger files. +.SS Assertions and ordering +.PP +hledger sorts an account\[aq]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.) +.PP +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. +.PP +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\[aq]s +balance on the same day, you\[aq]ll have to put the assertion in the +right file. +.SS Assertions and commodities +.PP +The asserted balance must be a simple single\-commodity amount, and in +fact the assertion checks only this commodity\[aq]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. +.PP +To assert each commodity\[aq]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\[aq]t be +sure the account does not contain some unexpected commodity. +(We\[aq]ll add support for this kind of total balance assertion if +there\[aq]s demand.) +.SS Assertions and subaccounts +.PP +Balance assertions do not count the balance from subaccounts; they check +the posted account\[aq]s exclusive balance. +For example: +.IP +.nf +\f[C] +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 +\f[] +.fi +.PP +The balance report\[aq]s flat mode shows these exclusive balances more +clearly: +.IP +.nf +\f[C] +$\ hledger\ bal\ checking\ \-\-flat +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking:fund +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2 +\f[] +.fi +.SS Assertions and virtual postings +.PP +Balance assertions are checked against all postings, both real and +virtual. +They are not affected by the \f[C]\-\-real/\-R\f[] flag or +\f[C]real:\f[] query. +.SH PRICES +.SS Transaction prices +.PP +When recording a transaction, you can also record an amount\[aq]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. +.PP +Such priced amounts can be displayed in their transaction price\[aq]s +commodity, by using the \f[C]\-\-cost/\-B\f[] flag (B for "cost Basis"), +supported by most hledger commands. +.PP +There are three ways to specify a transaction price: +.IP "1." 3 +Write the unit price (aka exchange rate), as \f[C]\@\ UNITPRICE\f[] +after the amount: +.RS 4 +.IP +.nf +\f[C] +2009/1/1 +\ \ assets:foreign\ currency\ \ \ €100\ \@\ $1.35\ \ ;\ one\ hundred\ euros\ at\ $1.35\ each +\ \ assets:cash +\f[] +.fi +.RE +.IP "2." 3 +Or write the total price, as \f[C]\@\@\ TOTALPRICE\f[] after the amount: +.RS 4 +.IP +.nf +\f[C] +2009/1/1 +\ \ assets:foreign\ currency\ \ \ €100\ \@\@\ $135\ \ ;\ one\ hundred\ euros\ at\ $135\ for\ the\ lot +\ \ assets:cash +\f[] +.fi +.RE +.IP "3." 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: +.RS 4 +.IP +.nf +\f[C] +2009/1/1 +\ \ assets:foreign\ currency\ \ \ €100\ \ \ \ \ \ \ \ \ \ ;\ one\ hundred\ euros +\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135\ \ \ \ \ \ \ \ \ \ ;\ exchanged\ for\ $135 +\f[] +.fi +.RE +.PP +With any of the above examples we get: +.IP +.nf +\f[C] +$\ hledger\ print\ \-B +2009/01/01 +\ \ \ \ assets:foreign\ currency\ \ \ \ \ \ \ $135.00 +\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-135.00 +\f[] +.fi +.PP +Example use for transaction prices: recording the effective conversion +rate of purchases made in a foreign currency. +.SS Market prices +.PP +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. +.PP +When market prices are known, the \f[C]\-V/\-\-value\f[] 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. +.PP +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: +.IP +.nf +\f[C] +P\ DATE\ COMMODITYSYMBOL\ UNITPRICE +\f[] +.fi +.PP +For example, the following directives say that the euro\[aq]s exchange +rate was 1.35 US dollars during 2009, and $1.40 from 2010 onward (and +unknown before 2009). +.IP +.nf +\f[C] +P\ 2009/1/1\ €\ $1.35 +P\ 2010/1/1\ €\ $1.40 +\f[] +.fi +.PP +Example use for market prices: tracking the value of stocks. +.SH COMMENTS +.PP +Lines in the journal beginning with a semicolon (\f[C];\f[]) or hash +(\f[C]#\f[]) or asterisk (\f[C]*\f[]) are comments, and will be ignored. +(Asterisk comments make it easy to treat your journal like an org\-mode +outline in emacs.) +.PP +Also, anything between \f[C]comment\f[] and \f[C]end\ comment\f[] +directives is a (multi\-line) comment. +If there is no \f[C]end\ comment\f[], the comment extends to the end of +the file. +.PP +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. +.PP +Some examples: +.IP +.nf +\f[C] +#\ 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) +\f[] +.fi +.SH TAGS +.PP +A \f[I]tag\f[] is a word followed by a full colon inside a transaction +or posting comment. +You can write multiple tags, comma separated. +Eg: \f[C];\ a\ comment\ containing\ sometag:,\ anothertag:\f[]. +You can search for tags with the \f[C]tag:\f[] query. +.PP +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). +.PP +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): +.IP +.nf +\f[C] +1/1\ a\ transaction\ \ ;\ A:,\ TAG2: +\ \ \ \ ;\ third\-tag:\ a\ third\ transaction\ tag,\ this\ time\ with\ a\ value +\ \ \ \ (a)\ \ $1\ \ ;\ posting\-tag: +\f[] +.fi +.PP +Tags are like Ledger\[aq]s metadata feature, except hledger\[aq]s tag +values are always simple strings. +.SH DIRECTIVES +.SS Account aliases +.PP +You can define aliases which rewrite your account names (after reading +the journal, before generating reports). +hledger\[aq]s account aliases can be useful for: +.IP \[bu] 2 +expanding shorthand account names to their full form, allowing easier +data entry and a less verbose journal +.IP \[bu] 2 +adapting old journals to your current chart of accounts +.IP \[bu] 2 +experimenting with new account organisations, like a new hierarchy or +combining two accounts into one +.IP \[bu] 2 +customising reports +.PP +See also How to use account aliases. +.SS Basic aliases +.PP +To set an account alias, use the \f[C]alias\f[] 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: +.IP +.nf +\f[C] +alias\ OLD\ =\ NEW +\f[] +.fi +.PP +Or, you can use the \f[C]\-\-alias\ \[aq]OLD=NEW\[aq]\f[] option on the +command line. +This affects all entries. +It\[aq]s useful for trying out aliases interactively. +.PP +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: +.IP +.nf +\f[C] +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" +\f[] +.fi +.SS Regex aliases +.PP +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): +.IP +.nf +\f[C] +alias\ /REGEX/\ =\ REPLACEMENT +\f[] +.fi +.PP +or \f[C]\-\-alias\ \[aq]/REGEX/=REPLACEMENT\[aq]\f[]. +.PP +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: +.IP +.nf +\f[C] +alias\ /^(.+):bank:([^:]+)(.*)/\ =\ \\1:\\2\ \\3 +#\ rewrites\ "assets:bank:wells\ fargo:checking"\ to\ \ "assets:wells\ fargo\ checking" +\f[] +.fi +.SS Multiple aliases +.PP +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: +.IP "1." 3 +alias directives, most recently seen first (recent directives take +precedence over earlier ones; directives not yet seen are ignored) +.IP "2." 3 +alias options, in the order they appear on the command line +.SS end aliases +.PP +You can clear (forget) all currently defined aliases with the +\f[C]end\ aliases\f[] directive: +.IP +.nf +\f[C] +end\ aliases +\f[] +.fi +.SS Multi\-line comments +.PP +A line containing just \f[C]comment\f[] starts a multi\-line comment, +and a line containing just \f[C]end\ comment\f[] ends it. +See comments. +.SS Default commodity +.PP +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\[aq]s display style) will be +applied to all subsequent commodity\-less amounts, up to the next D +directive. +(Note this is different from Ledger\[aq]s default commodity directive.) +.PP +Also note the directive itself does not influence the commodity\[aq]s +default display style, but the amount it is applied to might. +Here\[aq]s an example: +.IP +.nf +\f[C] +;\ set\ £\ as\ the\ default\ commodity +D\ £1,000.00 + +2010/1/1 +\ \ a\ \ 2340 +\ \ b + +2014/1/1 +\ \ c\ \ £1000 +\ \ d +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ print +2010/01/01 +\ \ \ \ a\ \ \ \ \ £2,340.00 +\ \ \ \ b\ \ \ \ £\-2,340.00 + +2014/01/01 +\ \ \ \ c\ \ \ \ \ £1,000.00 +\ \ \ \ d\ \ \ \ £\-1,000.00 +\f[] +.fi +.SS Default parent account +.PP +You can specify a parent account which will be prepended to all accounts +within a section of the journal. +Use the \f[C]account\f[] directive like so: +.IP +.nf +\f[C] +account\ home + +2010/1/1 +\ \ \ \ food\ \ \ \ $10 +\ \ \ \ cash + +end +\f[] +.fi +.PP +If \f[C]end\f[] is omitted, the effect lasts to the end of the file. +The above is equivalent to: +.IP +.nf +\f[C] +2010/01/01 +\ \ \ \ home:food\ \ \ \ \ \ \ \ \ \ \ $10 +\ \ \ \ home:cash\ \ \ \ \ \ \ \ \ \ $\-10 +\f[] +.fi +.PP +Included files are also affected, eg: +.IP +.nf +\f[C] +account\ business +include\ biz.journal +end +account\ personal +include\ personal.journal +end +\f[] +.fi +.SS Default year +.PP +You can set a default year to be used for subsequent dates which +don\[aq]t specify a year. +This is a line beginning with \f[C]Y\f[] followed by the year. +Eg: +.IP +.nf +\f[C] +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 +\f[] +.fi +.SS Including other files +.PP +You can pull in the content of additional journal files by writing an +include directive, like this: +.IP +.nf +\f[C] +include\ path/to/file.journal +\f[] +.fi +.PP +If the path does not begin with a slash, it is relative to the current +file. +.PP +The \f[C]include\f[] directive may only be used in journal files, and +currently it may only include other journal files (eg, not CSV or +timelog files.) + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org. + +.SH AUTHORS +Simon Michael + +.SH COPYRIGHT + +Copyright (C) 2007-2015 Simon Michael. +.br +Released under GNU GPLv3+. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) +.br +hledger_csv(5), hledger_journal(5), hledger_timelog(5) + +For more information, see http://hledger.org. diff --git a/hledger-lib/hledger_journal.5.md b/hledger-lib/hledger_journal.5.md new file mode 100644 index 000000000..2f00c5270 --- /dev/null +++ b/hledger-lib/hledger_journal.5.md @@ -0,0 +1,666 @@ +% hledger_journal(5) +% +% October 2015 + +# NAME + +hledger_journal - reference for hledger's journal file format + +# DESCRIPTION + +hledger's usual data source is a plain text file containing journal entries in hledger journal format. +This file represents a standard accounting [general journal](http://en.wikipedia.org/wiki/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](faq.html#file-format-differences), +of [ledger's journal format](http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), +so hledger can work with [compatible](faq.html#file-format-differences) 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](#add) or [web](#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: + +```journal +; 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 +``` + +Now let's explore the available journal file syntax in detail. + +# Transactions + +Transactions are represented by journal entries. Each begins with a +[simple date](#simple-dates) 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](#virtual-postings)) 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. + +# Dates + +## 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](#default-year). + +Some examples: `2010/01/31`, `1/31`, `2010-01-31`, `2010.1.31`. + +## 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. + +```journal +2010/2/23=2/19 movie ticket + expenses:cinema $10 + assets:checking +``` + +
+```{.shell} +$ hledger register checking +2010/02/23 movie ticket assets:checking $-10 $-10 +``` + +
+```{.shell} +$ 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... + +## Posting dates + +You can give individual postings a different date from their parent +transaction, by adding a [posting tag](#tags) (see below) like +`date:DATE`, where DATE is a [simple date](#simple-dates). 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: + +``` {.journal} +2015/5/30 + expenses:food $10 ; food purchased on saturday 5/30 + assets:checking ; bank cleared it on monday, date:6/1 +``` + +
+```{.shell} +$ hledger -f tt.j register food +2015/05/30 expenses:food $10 $10 +``` + +
+```{.shell} +$ 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. + +# 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](#account-aliases). + +# 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"`). + +## 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`. + +## 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). + + +# 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: + +```journal +1/1 special unbalanced posting to set initial balance + (assets:checking) $1000 +``` +## 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. + +# Balance Assertions + +hledger supports ledger-style +[balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#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: + +``` {.journal} +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. + +## 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](#including-other-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. + + +## 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.) + +## Assertions and subaccounts + +Balance assertions do not count the balance from subaccounts; they check +the posted account's exclusive balance. For example: +``` {.journal} +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: +```shell +$ hledger bal checking --flat + 1 checking + 1 checking:fund +-------------------- + 2 +``` + +### Assertions and virtual postings + +Balance assertions are checked against all postings, both real and +[virtual](#virtual-postings). They are not affected by the `--real/-R` +flag or `real:` query. + + +# Prices + +## Transaction prices + +When recording a transaction, you can also record an amount's price in another commodity. +This documents the exchange rate, cost (of a 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: + + ```journal + 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: + + ```journal + 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: + + ```journal + 2009/1/1 + assets:foreign currency €100 ; one hundred euros + assets:cash $-135 ; exchanged for $135 + ``` + +With any of the above examples we get: + +```shell +$ 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. + +## 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](#balance) command. + +You record market prices (Ledger calls them historical prices) with a +P directive, in the journal or perhaps in a separate +[included](#including-other-files) file. Market price directives have +the format: +```journal +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). +```journal +P 2009/1/1 € $1.35 +P 2010/1/1 € $1.40 +``` + +Example use for market prices: tracking the value of stocks. + + + + +# 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](#multi-line-comments) 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: + +```journal +# 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) +``` + +# Tags + +A *tag* is a word followed by a full colon inside a transaction or +posting [comment](#comments). You can write multiple tags, comma +separated. Eg: `; a comment containing sometag:, anothertag:`. You can search for tags +with the [`tag:` query](manual#queries). + +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): + +``` {.journal} +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](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata) +feature, except hledger's tag values are always simple strings. + +# Directives + +## Account aliases + +You can define aliases which rewrite your account names (after reading the journal, +before generating reports). hledger's account aliases can be useful for: + +- 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](how-to-use-account-aliases.html). + +### 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](#including-other-files). +The spaces around the = are optional: + +``` {.journal} +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: + +``` {.journal} +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" +``` + +### 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): + +``` {.journal} +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: + +``` {.journal} +alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3 +# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" +``` + +### 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 + +### end aliases + +You can clear (forget) all currently defined aliases with the `end aliases` directive: + +``` {.journal} +end aliases +``` + +## Multi-line comments + +A line containing just `comment` starts a multi-line comment, and a +line containing just `end comment` ends it. See [comments](#comments). + +## 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](#amount-display-styles), but the amount it is +applied to might. Here's an example: + +```journal +; set £ as the default commodity +D £1,000.00 + +2010/1/1 + a 2340 + b + +2014/1/1 + c £1000 + d +``` +```{.shell} +$ hledger print +2010/01/01 + a £2,340.00 + b £-2,340.00 + +2014/01/01 + c £1,000.00 + d £-1,000.00 +``` + +## Default parent account + +You can specify a parent account which will be prepended to all accounts +within a section of the journal. Use the `account` directive like so: + +``` {.journal} +account home + +2010/1/1 + food $10 + cash + +end +``` + +If `end` is omitted, the effect lasts to the end of the file. +The above is equivalent to: + +``` {.journal} +2010/01/01 + home:food $10 + home:cash $-10 +``` + +Included files are also affected, eg: + +``` {.journal} +account business +include biz.journal +end +account personal +include personal.journal +end +``` + +## 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: + +``` {.journal} +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 +``` + +## Including other files + +You can pull in the content of additional journal files by writing an +include directive, like this: + +``` {.journal} +include path/to/file.journal +``` + +If the path does not begin with a slash, it is relative to the current file. + +The `include` directive may only be used in journal files, and currently +it may only include other journal files (eg, not CSV or timelog files.) diff --git a/hledger-lib/hledger_timelog.5 b/hledger-lib/hledger_timelog.5 new file mode 100644 index 000000000..29cd18a95 --- /dev/null +++ b/hledger-lib/hledger_timelog.5 @@ -0,0 +1,99 @@ + +.TH "hledger_timelog" "5" "October 2015" "" "hledger User Manuals" + + + +.SH NAME +.PP +hledger_timelog \- hledger\[aq]s timelog file format +.SH DESCRIPTION +.PP +hledger can read timelog files. +As with Ledger, these are (a subset of) timeclock.el\[aq]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). +.IP +.nf +\f[C] +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 +\f[] +.fi +.PP +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, \f[C]hledger\ print\f[] generates these journal +entries: +.IP +.nf +\f[C] +$\ hledger\ \-f\ t.timelog\ 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 +\f[] +.fi +.PP +Here is a sample.timelog to download and some queries to try: +.IP +.nf +\f[C] +$\ hledger\ \-f\ sample.timelog\ balance\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ current\ time\ balances +$\ hledger\ \-f\ sample.timelog\ register\ \-p\ 2009/3\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ sessions\ in\ march\ 2009 +$\ hledger\ \-f\ sample.timelog\ register\ \-p\ weekly\ \-\-depth\ 1\ \-\-empty\ \ #\ time\ summary\ by\ week +\f[] +.fi +.PP +To generate time logs, ie to clock in and clock out, you could: +.IP \[bu] 2 +use emacs and the built\-in timeclock.el, or the extended +timeclock\-x.el and perhaps the extras in ledgerutils.el +.IP \[bu] 2 +at the command line, use these bash aliases: +.RS 2 +.IP +.nf +\f[C] +alias\ ti="echo\ i\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ \\$*\ >>$TIMELOG" +alias\ to="echo\ o\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ >>$TIMELOG" +\f[] +.fi +.RE +.IP \[bu] 2 +or use the old \f[C]ti\f[] and \f[C]to\f[] scripts in the ledger 2.x +repository. +These rely on a "timeclock" executable which I think is just the ledger +2 executable renamed. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org. + +.SH AUTHORS +Simon Michael + +.SH COPYRIGHT + +Copyright (C) 2007-2015 Simon Michael. +.br +Released under GNU GPLv3+. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) +.br +hledger_csv(5), hledger_journal(5), hledger_timelog(5) + +For more information, see http://hledger.org. diff --git a/hledger-lib/hledger_timelog.5.md b/hledger-lib/hledger_timelog.5.md new file mode 100644 index 000000000..ce0903e83 --- /dev/null +++ b/hledger-lib/hledger_timelog.5.md @@ -0,0 +1,68 @@ +% hledger_timelog(5) +% +% October 2015 + +# NAME + +hledger_timelog - hledger's timelog file format + +# DESCRIPTION + +hledger can read timelog files. +[As with Ledger](http://ledger-cli.org/3.0/doc/ledger3.html#Time-Keeping), +these are (a subset of) +[timeclock.el](http://www.emacswiki.org/emacs/TimeClock)'s format, +containing clock-in and clock-out entries as in the example below. +The date is a [simple date](#simple-dates) (also, [default year directives](#default-year) 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). + +```timelog +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: + +``` {.shell} +$ hledger -f t.timelog 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.timelog](https://raw.github.com/simonmichael/hledger/master/data/sample.timelog) to +download and some queries to try: + +```shell +$ hledger -f sample.timelog balance # current time balances +$ hledger -f sample.timelog register -p 2009/3 # sessions in march 2009 +$ hledger -f sample.timelog 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](http://www.emacswiki.org/emacs/timeclock-x.el) + and perhaps the extras in [ledgerutils.el](http://hub.darcs.net/simon/ledgertools/ledgerutils.el) + +- at the command line, use these bash aliases: + ```shell + 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](https://github.com/ledger/ledger/tree/maint/scripts). + These rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. diff --git a/hledger-ui/hledger-ui.1 b/hledger-ui/hledger-ui.1 new file mode 100644 index 000000000..33a230da0 --- /dev/null +++ b/hledger-ui/hledger-ui.1 @@ -0,0 +1,204 @@ + +.TH "hledger\-ui" "1" "October 2015" "" "hledger User Manuals" + + + +.SH NAME +.PP +hledger\-ui \- curses\-style interface for the hledger accounting tool +.SH SYNOPSIS +.PP +\f[C]hledger\-ui\ [OPTIONS]\ [QUERYARGS]\f[] +.PD 0 +.P +.PD +\f[C]hledger\ ui\ \-\-\ [OPTIONS]\ [QUERYARGS]\f[] +.SH DESCRIPTION +.PP +hledger is a cross\-platform program for tracking money, time, or any +other commodity, using double\-entry accounting and a simple, editable +file format. +hledger is inspired by and largely compatible with ledger(1). +.PP +hledger\-ui is hledger\[aq]s curses\-style interface. +It reads a hledger journal file (~/.hledger.journal, $LEDGER_FILE, or +\-f FILE) and provides a simple full\-screen console interface for +viewing account balances and transactions. +It is simpler and more efficient for browsing than the hledger CLI, but +lighter and faster than hledger\-web. +.PP +The journal file is \f[C]~/.hledger.journal\f[], \f[C]$LEDGER_FILE\f[], +or another file specified with \-f. +For more about the format, see hledger(1) or hledger_journal(5). +.SH OPTIONS +.PP +Note: if invoking hledger\-ui as a hledger subcommand, write +\f[C]\-\-\f[] before options as shown above. +.PP +Any QUERYARGS are interpreted as a hledger search query which filters +the data. +.TP +.B \f[C]\-\-flat\f[] +show full account names, unindented +.RS +.RE +.TP +.B \f[C]\-\-no\-elide\f[] +don\[aq]t compress empty parent accounts on one line +.RS +.RE +.TP +.B \f[C]\-\-register=ACCTREGEX\f[] +start in the (first) matched account\[aq]s register screen +.RS +.RE +.TP +.B \f[C]\-\-theme=default|terminal|greenterm\f[] +use this custom display theme +.RS +.RE +.TP +.B \f[C]\-V\ \-\-value\f[] +show amounts as their current market value in their default valuation +commodity (accounts screen only) +.RS +.RE +.TP +.B \f[C]\-h\ \-\-help\f[] +show help +.RS +.RE +.TP +.B \f[C]\-\-version\f[] +show version information +.RS +.RE +.SS hledger options: +.PP +The following common hledger options should also work: +.TP +.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] +use a different input file. +For stdin, use \- +.RS +.RE +.TP +.B \f[C]\-\-rules\-file=RULESFILE\f[] +Conversion rules file to use when reading CSV (default: FILE.rules) +.RS +.RE +.TP +.B \f[C]\-\-alias=OLD=NEW\f[] +display accounts named OLD as NEW +.RS +.RE +.TP +.B \f[C]\-\-ignore\-assertions\f[] +ignore any failing balance assertions in the journal +.RS +.RE +.TP +.B \f[C]\-\-debug=N\f[] +show debug output if N is 1\-9 (default: 0) +.RS +.RE +.TP +.B \f[C]\-b\ \-\-begin=DATE\f[] +include postings/txns on or after this date +.RS +.RE +.TP +.B \f[C]\-e\ \-\-end=DATE\f[] +include postings/txns before this date +.RS +.RE +.TP +.B \f[C]\-p\ \-\-period=PERIODEXP\f[] +set start date, end date, and/or reporting interval all at once +(overrides the flags above) +.RS +.RE +.TP +.B \f[C]\-\-date2\ \-\-aux\-date\f[] +use postings/txns\[aq] secondary dates instead +.RS +.RE +.TP +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns +.RS +.RE +.TP +.B \f[C]\-\-pending\f[] +include only pending postings/txns +.RS +.RE +.TP +.B \f[C]\-U\ \-\-uncleared\f[] +include only uncleared (and pending) postings/txns +.RS +.RE +.TP +.B \f[C]\-R\ \-\-real\f[] +include only non\-virtual postings +.RS +.RE +.TP +.B \f[C]\-\-depth=N\f[] +hide accounts/postings deeper than N +.RS +.RE +.TP +.B \f[C]\-E\ \-\-empty\f[] +show empty/zero things which are normally omitted +.RS +.RE +.TP +.B \f[C]\-B\ \-\-cost\f[] +show amounts in their cost price\[aq]s commodity +.RS +.RE +.SH ENVIRONMENT +.PP +\f[B]LEDGER_FILE\f[] sets the default journal file path. +If not set, it is \f[C]~/.hledger.journal\f[]. +.PP +\f[B]COLUMNS\f[] sets the screen width to use (normally the full +terminal width). +.SH FILES +.PP +Reads data from a hledger journal file (\f[C]$LEDGER_FILE\f[] or +\f[C]~/.hledger.journal\f[] by default), or a CSV file plus associated +CSV rules file. +.SH BUGS +.PP +The need to precede options with \f[C]\-\-\f[] when invoked from hledger +is awkward. +.PP +\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-ui can\[aq]t read from stdin). +.PP +\f[C]\-V\f[] doesn\[aq]t affect the register screen. +.PP +If you reload while in the register screen, when you return to the +accounts screen it will be showing old data, and pressing g again will +not reload it; you must adjust depth to force it (eg press 0). + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org. + +.SH AUTHORS +Simon Michael + +.SH COPYRIGHT + +Copyright (C) 2007-2015 Simon Michael. +.br +Released under GNU GPLv3+. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) +.br +hledger_csv(5), hledger_journal(5), hledger_timelog(5) + +For more information, see http://hledger.org. diff --git a/hledger-ui/hledger-ui.1.md b/hledger-ui/hledger-ui.1.md new file mode 100644 index 000000000..a87445950 --- /dev/null +++ b/hledger-ui/hledger-ui.1.md @@ -0,0 +1,134 @@ +% hledger-ui(1) +% +% October 2015 + +# NAME + +hledger-ui - curses-style interface for the hledger accounting tool + +# SYNOPSIS + +`hledger-ui [OPTIONS] [QUERYARGS]`\ +`hledger ui -- [OPTIONS] [QUERYARGS]` + +# DESCRIPTION + +hledger is a cross-platform program for tracking money, time, or any other commodity, +using double-entry accounting and a simple, editable file format. +hledger is inspired by and largely compatible with ledger(1). + +hledger-ui is hledger's curses-style interface. +It reads a hledger journal file (~/.hledger.journal, $LEDGER_FILE, or -f FILE) and +provides a simple full-screen console interface for viewing account +balances and transactions. It is simpler and more efficient for +browsing than the hledger CLI, 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). + +# 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 --help` +: show help + +`--version` +: show version information + +## 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 + +# ENVIRONMENT + +**LEDGER_FILE** +sets the default journal file path. If not set, it is `~/.hledger.journal`. + +**COLUMNS** +sets the screen width to use (normally the full terminal width). + +# FILES + +Reads data from a hledger journal file (`$LEDGER_FILE` or +`~/.hledger.journal` by default), or a CSV file plus associated CSV +rules file. + +# BUGS + +The need to precede options with `--` when invoked from hledger is awkward. + +`-f-` doesn't work (hledger-ui can't read from stdin). + +`-V` doesn't affect the register screen. + +If you reload while in the register screen, when you return to the +accounts screen it will be showing old data, and pressing g again will +not reload it; you must adjust depth to force it (eg press 0). diff --git a/hledger-web/hledger-web.1 b/hledger-web/hledger-web.1 new file mode 100644 index 000000000..10a95c196 --- /dev/null +++ b/hledger-web/hledger-web.1 @@ -0,0 +1,219 @@ + +.TH "hledger\-web" "1" "October 2015" "" "hledger User Manuals" + + + +.SH NAME +.PP +hledger\-web \- web interface for the hledger accounting tool +.SH SYNOPSIS +.PP +\f[C]hledger\-web\ [OPTIONS]\f[] +.PD 0 +.P +.PD +\f[C]hledger\ web\ \-\-\ [OPTIONS]\f[] +.SH DESCRIPTION +.PP +hledger is a cross\-platform program for tracking money, time, or any +other commodity, using double\-entry accounting and a simple, editable +file format. +hledger is inspired by and largely compatible with ledger(1). +.PP +hledger\-web is hledger\[aq]s web interface. +It starts a simple web application for browsing and adding transactions +in a hledger journal file, and also (unless started with \-\-server) +opens the app in a new web browser window if possible, and exits after +two minutes of inactivity. +.PP +hledger\-web 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. +.PP +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. +.PP +The journal file is \f[C]~/.hledger.journal\f[], \f[C]$LEDGER_FILE\f[], +or another file specified with \-f. +For more about the format, see hledger(1) or hledger_journal(5). +.SH OPTIONS +.PP +Note: if invoking hledger\-web as a hledger subcommand, write +\f[C]\-\-\f[] before options as shown above. +.TP +.B \f[C]\-\-server\f[] +disable browser\-opening and auto\-exit\-on\-idle, and log all requests +to stdout +.RS +.RE +.TP +.B \f[C]\-\-port=PORT\f[] +set the TCP port to listen on (default: 5000) +.RS +.RE +.TP +.B \f[C]\-\-base\-url=URL\f[] +set the base url (default: http://localhost:PORT). +You would change this when sharing over the network, or integrating +within a larger website. +.RS +.RE +.TP +.B \f[C]\-\-file\-url=URL\f[] +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. +.RS +.RE +.TP +.B \f[C]\-h\ \-\-help\f[] +show help +.RS +.RE +.TP +.B \f[C]\-\-version\f[] +show version information +.RS +.RE +.SS hledger options: +.PP +The following common hledger options should also work: +.TP +.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] +use a different input file. +For stdin, use \- +.RS +.RE +.TP +.B \f[C]\-\-rules\-file=RULESFILE\f[] +Conversion rules file to use when reading CSV (default: FILE.rules) +.RS +.RE +.TP +.B \f[C]\-\-alias=OLD=NEW\f[] +display accounts named OLD as NEW +.RS +.RE +.TP +.B \f[C]\-\-ignore\-assertions\f[] +ignore any failing balance assertions in the journal +.RS +.RE +.TP +.B \f[C]\-\-debug=N\f[] +show debug output if N is 1\-9 (default: 0) +.RS +.RE +.TP +.B \f[C]\-b\ \-\-begin=DATE\f[] +include postings/txns on or after this date +.RS +.RE +.TP +.B \f[C]\-e\ \-\-end=DATE\f[] +include postings/txns before this date +.RS +.RE +.TP +.B \f[C]\-p\ \-\-period=PERIODEXP\f[] +set start date, end date, and/or reporting interval all at once +(overrides the flags above) +.RS +.RE +.TP +.B \f[C]\-\-date2\ \-\-aux\-date\f[] +use postings/txns\[aq] secondary dates instead +.RS +.RE +.TP +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns +.RS +.RE +.TP +.B \f[C]\-\-pending\f[] +include only pending postings/txns +.RS +.RE +.TP +.B \f[C]\-U\ \-\-uncleared\f[] +include only uncleared (and pending) postings/txns +.RS +.RE +.TP +.B \f[C]\-R\ \-\-real\f[] +include only non\-virtual postings +.RS +.RE +.TP +.B \f[C]\-\-depth=N\f[] +hide accounts/postings deeper than N +.RS +.RE +.TP +.B \f[C]\-E\ \-\-empty\f[] +show empty/zero things which are normally omitted +.RS +.RE +.TP +.B \f[C]\-B\ \-\-cost\f[] +show amounts in their cost price\[aq]s commodity +.RS +.RE +.SH ENVIRONMENT +.PP +\f[B]LEDGER_FILE\f[] sets the default journal file path. +If not set, it is \f[C]~/.hledger.journal\f[]. +.SH FILES +.PP +Reads data from a hledger journal file (\f[C]$LEDGER_FILE\f[] or +\f[C]~/.hledger.journal\f[] by default), or a CSV file plus associated +CSV rules file. +.SH BUGS +.PP +The need to precede options with \f[C]\-\-\f[] when invoked from hledger +is awkward. +.PP +\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-web can\[aq]t read from +stdin). +.PP +Query arguments and some applicable hledger options probably aren\[aq]t +supported. +.PP +Does not work in text\-mode browsers. +.PP +Does not work well on small screens. +.PP +The auto\-exit feature was added to avoid leaving stray processes, eg on +Windows. +It is not well tested. +.PP +If you start two instances on the same port, the second one will appear +to run normally, but you will be seeing pages served from the first one. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org. + +.SH AUTHORS +Simon Michael + +.SH COPYRIGHT + +Copyright (C) 2007-2015 Simon Michael. +.br +Released under GNU GPLv3+. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) +.br +hledger_csv(5), hledger_journal(5), hledger_timelog(5) + +For more information, see http://hledger.org. diff --git a/hledger-web/hledger-web.1.md b/hledger-web/hledger-web.1.md new file mode 100644 index 000000000..1e0755548 --- /dev/null +++ b/hledger-web/hledger-web.1.md @@ -0,0 +1,146 @@ +% hledger-web(1) +% +% October 2015 + +# NAME + +hledger-web - web interface for the hledger accounting tool + +# SYNOPSIS + +`hledger-web [OPTIONS]`\ +`hledger web -- [OPTIONS]` + +# DESCRIPTION + +hledger is a cross-platform program for tracking money, time, or any other commodity, +using double-entry accounting and a simple, editable file format. +hledger is inspired by and largely compatible with ledger(1). + +hledger-web is hledger's web interface. It starts a simple web +application for browsing and adding transactions in a hledger journal +file, and also (unless started with --server) opens the app in a new +web browser window if possible, and exits after two minutes of +inactivity. + +hledger-web 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). + +# 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 --help` +: show help + +`--version` +: show version information + +## 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 + +# ENVIRONMENT + +**LEDGER_FILE** +sets the default journal file path. If not set, it is `~/.hledger.journal`. + +# FILES + +Reads data from a hledger journal file (`$LEDGER_FILE` or +`~/.hledger.journal` by default), or a CSV file plus associated CSV +rules file. + +# BUGS + +The need to precede options with `--` when invoked from hledger is awkward. + +`-f-` doesn't work (hledger-web can't read from stdin). + +Query arguments and some applicable hledger options probably aren't supported. + +Does not work in text-mode browsers. + +Does not work well on small screens. + +The auto-exit feature was added to avoid leaving stray processes, eg on Windows. +It is not well tested. + +If you start two instances on the same port, the second one will +appear to run normally, but you will be seeing pages served from the +first one. + diff --git a/hledger/hledger.1 b/hledger/hledger.1 new file mode 100644 index 000000000..3a938fb9a --- /dev/null +++ b/hledger/hledger.1 @@ -0,0 +1,699 @@ + +.TH "hledger" "1" "October 2015" "hledger 0.26.98" "hledger User Manuals" + + + +.SH NAME +.PP +hledger \- a command\-line accounting tool +.SH SYNOPSIS +.PP +\f[C]hledger\ [\-f\ FILE]\ COMMAND\ [OPTIONS]\ [CMDARGS]\f[] +.PD 0 +.P +.PD +\f[C]hledger\ [\-f\ FILE]\ ADDONCMD\ \-\-\ [OPTIONS]\ [CMDARGS]\f[] +.SH DESCRIPTION +.PP +hledger is a cross\-platform program for tracking money, time, or any +other commodity, using double\-entry accounting and a simple, editable +file format. +It is inspired by and largely compatible with ledger(1). +hledger aims to be a reliable, practical tool for daily use. +This man page is a quick reference and introduction; for more complete +docs, see http://hledger.org/manual. +.PP +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. +.PP +The journal file is \f[C]~/.hledger.journal\f[] by default, or another +file path specified by \f[C]$LEDGER_FILE\f[]. +You can also specify a file with \f[C]\-f\ FILE\f[], or standard input +with \f[C]\-f\-\f[]. +.PP +Transactions are dated movements of money between two (or more) named +accounts, and are recorded with journal entries like this: +.IP +.nf +\f[C] +2015/10/16\ bought\ food +\ expenses:food\ \ \ \ \ \ \ \ \ \ $10 +\ assets:cash +\f[] +.fi +.PP +For more about the format, see hledger_journal(5). +.PP +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. +.PP +To get started, you can either save some entries like the above in +\f[C]~/.hledger.journal\f[], or run \f[C]hledger\ add\f[] and follow the +prompts. +Then try some commands like \f[C]hledger\ print\f[] or +\f[C]hledger\ balance\f[]. +See COMMANDS and EXAMPLES below. +.SH OPTIONS +.PP +To see general help and the command list: \f[C]hledger\ \-\-help\f[] or +\f[C]hledger\f[] +.PP +To see all options available with a command: +\f[C]hledger\ COMMAND\ \-\-help\f[] +.PP +Except for the General options below, options must be written after +COMMAND, not before it. +.PP +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: +.IP +.nf +\f[C] +$\ hledger\ ui\ \-\-\ \-\-register\ cash +$\ hledger\-ui\ \-\-register\ cash +\f[] +.fi +.PP +Options and command arguments can be intermixed. +Arguments are usually interpreted as a search query which filters the +data, see QUERIES. +.SS General flags: +.PP +These can appear anywhere in the command line. +.TP +.B \f[C]\-h\ \-\-help\f[] +show general help or (after command) command help +.RS +.RE +.TP +.B \f[C]\-\-version\f[] +show version information +.RS +.RE +.TP +.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] +use a different input file. +For stdin, use \- +.RS +.RE +.TP +.B \f[C]\-\-rules\-file=RULESFILE\f[] +Conversion rules file to use when reading CSV (default: FILE.rules) +.RS +.RE +.TP +.B \f[C]\-\-alias=OLD=NEW\f[] +display accounts named OLD as NEW +.RS +.RE +.TP +.B \f[C]\-\-ignore\-assertions\f[] +ignore any failing balance assertions in the journal +.RS +.RE +.TP +.B \f[C]\-\-debug=N\f[] +: show debug output if N is 1\-9 (default: 0) +.RS +.RE +.SS Common reporting flags: +.PP +These are supported by most commands, where applicable. +They must be written after the command name. +Additional command\-specific flags are described in COMMANDS below. +.TP +.B \f[C]\-b\ \-\-begin=DATE\f[] +include postings/txns on or after this date +.RS +.RE +.TP +.B \f[C]\-e\ \-\-end=DATE\f[] +include postings/txns before this date +.RS +.RE +.TP +.B \f[C]\-D\ \-\-daily\f[] +multiperiod/multicolumn report by day +.RS +.RE +.TP +.B \f[C]\-W\ \-\-weekly\f[] +multiperiod/multicolumn report by week +.RS +.RE +.TP +.B \f[C]\-M\ \-\-monthly\f[] +multiperiod/multicolumn report by month +.RS +.RE +.TP +.B \f[C]\-Q\ \-\-quarterly\f[] +multiperiod/multicolumn report by quarter +.RS +.RE +.TP +.B \f[C]\-Y\ \-\-yearly\f[] +multiperiod/multicolumn report by year +.RS +.RE +.TP +.B \f[C]\-p\ \-\-period=PERIODEXP\f[] +set start date, end date, and/or reporting interval all at once +(overrides the flags above) +.RS +.RE +.TP +.B \f[C]\-\-date2\ \-\-aux\-date\f[] +use postings/txns\[aq] secondary dates instead +.RS +.RE +.TP +.B \f[C]\-C\ \-\-cleared\f[] +include only cleared postings/txns +.RS +.RE +.TP +.B \f[C]\-\-pending\f[] +include only pending postings/txns +.RS +.RE +.TP +.B \f[C]\-U\ \-\-uncleared\f[] +include only uncleared (and pending) postings/txns +.RS +.RE +.TP +.B \f[C]\-R\ \-\-real\f[] +include only non\-virtual postings +.RS +.RE +.TP +.B \f[C]\-\-depth=N\f[] +hide accounts/postings deeper than N +.RS +.RE +.TP +.B \f[C]\-E\ \-\-empty\f[] +show empty/zero things which are normally omitted +.RS +.RE +.TP +.B \f[C]\-B\ \-\-cost\f[] +show amounts in their cost price\[aq]s commodity +.RS +.RE +.PP +If a reporting option is repeated, the last one takes precedence. +Eg \-p jan \-p feb is equivalent to \-p feb. +.SH COMMANDS +.PP +COMMAND selects one of hledger\[aq]s subcommands; omit it to list +available commands. +To save typing, some commands have a short form; any unique prefix also +works. +.PP +Here is a summary (see http://hledger.org/manual#commands for the full +command help): +.SS Data entry: +.SS add +.PP +prompt for transactions and add them to the journal. +.PP +This is the only hledger command that writes to the journal file. +It appends only, existing transactions are not changed. +.TP +.B \f[C]\-\-no\-new\-accounts\f[] +don\[aq]t allow creating new accounts; helps prevent typos when entering +account names +.RS +.RE +.SS Reporting: +.SS accounts +.PP +show account names +.TP +.B \f[C]\-\-tree\f[] +show short account names, as a tree +.RS +.RE +.TP +.B \f[C]\-\-flat\f[] +show full account names, as a list (default) +.RS +.RE +.TP +.B \f[C]\-\-drop=N\f[] +in flat mode: omit N leading account name parts +.RS +.RE +.SS activity +.PP +show an ascii barchart of posting counts per interval (default: daily) +.SS balance, bal +.PP +show accounts and balances +.TP +.B \f[C]\-\-tree\f[] +show short account names, as a tree +.RS +.RE +.TP +.B \f[C]\-\-flat\f[] +show full account names, as a list (default) +.RS +.RE +.TP +.B \f[C]\-\-drop=N\f[] +in flat mode: omit N leading account name parts +.RS +.RE +.TP +.B \f[C]\-\-format=LINEFORMAT\f[] +in single\-column balance reports: use this custom line format +.RS +.RE +.TP +.B \f[C]\-\-no\-elide\f[] +in tree mode: don\[aq]t squash boring parent accounts +.RS +.RE +.TP +.B \f[C]\-H\ \-\-historical\f[] +in multicolumn mode: show historical ending balances +.RS +.RE +.TP +.B \f[C]\-\-cumulative\f[] +in multicolumn mode: show accumulated ending balances +.RS +.RE +.TP +.B \f[C]\-A\ \-\-average\f[] +in multicolumn mode: show a row average column +.RS +.RE +.TP +.B \f[C]\-T\ \-\-row\-total\f[] +in multicolumn mode: show a row total column +.RS +.RE +.TP +.B \f[C]\-N\ \-\-no\-total\f[] +don\[aq]t show the final total row +.RS +.RE +.TP +.B \f[C]\-V\ \-\-value\f[] +show amounts as their current market value in their default valuation +commodity +.RS +.RE +.TP +.B \f[C]\-o\ FILE[.FMT]\ \-\-output\-file=FILE[.FMT]\f[] +write output to FILE instead of stdout. +A recognised FMT suffix influences the format. +.RS +.RE +.TP +.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] +select the output format. +Supported formats: txt, csv. +.RS +.RE +.SS balancesheet, bs +.PP +show a balance sheet +.TP +.B \f[C]\-\-flat\f[] +show full account names, as a list (default) +.RS +.RE +.TP +.B \f[C]\-\-drop=N\f[] +in flat mode: omit N leading account name parts +.RS +.RE +.SS cashflow, cf +.PP +show a cashflow statement +.TP +.B \f[C]\-\-flat\f[] +show full account names, as a list (default) +.RS +.RE +.TP +.B \f[C]\-\-drop=N\f[] +in flat mode: omit N leading account name parts +.RS +.RE +.SS incomestatement, is +.PP +show an income statement +.TP +.B \f[C]\-\-flat\f[] +show full account names, as a list (default) +.RS +.RE +.TP +.B \f[C]\-\-drop=N\f[] +in flat mode: omit N leading account name parts +.RS +.RE +.SS print +.PP +show transactions from the journal +.TP +.B \f[C]\-m\ STR\ \-\-match=STR\f[] +show the transaction whose description is most similar to STR, and is +most recent +.RS +.RE +.TP +.B \f[C]\-o\ FILE[.FMT]\ \-\-output\-file=FILE[.FMT]\f[] +write output to FILE instead of stdout. +A recognised FMT suffix influences the format. +.RS +.RE +.TP +.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] +select the output format. +Supported formats: txt, csv. +.RS +.RE +.SS register, reg +.PP +show postings and running total +.TP +.B \f[C]\-H\ \-\-historical\f[] +include prior postings in the running total +.RS +.RE +.TP +.B \f[C]\-A\ \-\-average\f[] +show a running average instead of the running total (implies \-\-empty) +.RS +.RE +.TP +.B \f[C]\-r\ \-\-related\f[] +show postings\[aq] siblings instead +.RS +.RE +.TP +.B \f[C]\-w\ N\ \-\-width=N\f[] +set output width (default: terminal width or COLUMNS. +\-wN,M sets description width as well) +.RS +.RE +.TP +.B \f[C]\-o\ FILE[.FMT]\ \-\-output\-file=FILE[.FMT]\f[] +write output to FILE instead of stdout. +A recognised FMT suffix influences the format. +.RS +.RE +.TP +.B \f[C]\-O\ FMT\ \-\-output\-format=FMT\f[] +select the output format. +Supported formats: txt, csv. +.RS +.RE +.SS stats +.PP +show some journal statistics +.TP +.B \f[C]\-o\ FILE[.FMT]\ \-\-output\-file=FILE[.FMT]\f[] +write output to FILE instead of stdout. +A recognised FMT suffix influences the format. +.RS +.RE +.SS Add\-on commands: +.PP +Additional commands will be available when executables or scripts named +"\f[C]hledger\-\f[]CMD" are installed in the PATH. +These are often provided by a package of the same name, or you can make +your own custom scripts (haskell scripts can use hledger\-lib allowing +tight integration). +Some available add\-ons are: +.SS autosync +.PP +download OFX bank data and/or convert OFX to hledger journal format +.SS diff +.PP +show transactions present in one journal file but not another +.SS interest +.PP +generate interest transactions +.SS irr +.PP +calculate internal rate of return +.SS ui +.PP +curses\-style interface, see hledger\-ui(1) +.SS web +.PP +web interface, see hledger\-web(1) +.SH QUERIES +.PP +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: +.PP +All commands except print: show transactions/postings/accounts which +match (or negatively match) +.IP \[bu] 2 +any of the description terms AND +.IP \[bu] 2 +any of the account terms AND +.IP \[bu] 2 +all the other terms. +.PP +The print command: show transactions which +.IP \[bu] 2 +match any of the description terms AND +.IP \[bu] 2 +have any postings matching any of the positive account terms AND +.IP \[bu] 2 +have no postings matching any of the negative account terms AND +.IP \[bu] 2 +match all the other terms. +.PP +The following kinds of search terms can be used: +.TP +.B \f[B]\f[C]REGEX\f[]\f[] +match account names by this regular expression +.RS +.RE +.TP +.B \f[B]\f[C]acct:REGEX\f[]\f[] +same as above +.RS +.RE +.TP +.B \f[B]\f[C]amt:N,\ amt:N,\ amt:>=N\f[]\f[] +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. +.RS +.RE +.TP +.B \f[B]\f[C]code:REGEX\f[]\f[] +match by transaction code (eg check number) +.RS +.RE +.TP +.B \f[B]\f[C]cur:REGEX\f[]\f[] +match postings or transactions including any amounts whose +currency/commodity symbol is fully matched by REGEX. +(For a partial match, use \f[C]\&.*REGEX.*\f[]). +Note, to match characters which are regex\-significant, like the dollar +sign (\f[C]$\f[]), you need to prepend \f[C]\\\f[]. +And when using the command line you need to add one more level of +quoting to hide it from the shell, so eg do: +\f[C]hledger\ print\ cur:\[aq]\\$\[aq]\f[] or +\f[C]hledger\ print\ cur:\\\\$\f[]. +.RS +.RE +.TP +.B \f[B]\f[C]desc:REGEX\f[]\f[] +match transaction descriptions +.RS +.RE +.TP +.B \f[B]\f[C]date:PERIODEXPR\f[]\f[] +match dates within the specified period (which should not include a +reporting interval +.RS +.RE +.TP +.B \f[B]\f[C]date2:PERIODEXPR\f[]\f[] +as above, but match secondary dates +.RS +.RE +.TP +.B \f[B]\f[C]depth:N\f[]\f[] +match (or display, depending on command) accounts at or above this depth +.RS +.RE +.TP +.B \f[B]\f[C]real:,\ real:0\f[]\f[] +match real or virtual postings respectively +.RS +.RE +.TP +.B \f[B]\f[C]status:*,\ status:!,\ status:\f[]\f[] +match cleared, pending, or uncleared/pending transactions respectively +.RS +.RE +.TP +.B \f[B]\f[C]tag:REGEX[=REGEX]\f[]\f[] +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. +.RS +.RE +.TP +.B \f[B]\f[C]not:\f[]\f[] +before any of the above negates the match. +.RS +.RE +.SH EXAMPLES +.PP +Two simple transactions in hledger journal format: +.IP +.nf +\f[C] +2015/9/30\ gift\ received +\ \ assets:cash\ \ \ $20 +\ \ income:gifts + +2015/10/16\ farmers\ market +\ \ expenses:food\ \ \ \ $10 +\ \ assets:cash +\f[] +.fi +.PP +Some basic reports: +.IP +.nf +\f[C] +$\ hledger\ print +2015/09/30\ gift\ received +\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ $20 +\ \ \ \ income:gifts\ \ \ \ \ \ \ \ \ \ $\-20 + +2015/10/16\ farmers\ market +\ \ \ \ expenses:food\ \ \ \ \ \ \ \ \ \ \ $10 +\ \ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ $\-10 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ accounts\ \-\-tree +assets +\ \ cash +expenses +\ \ food +income +\ \ gifts +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ balance +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ assets:cash +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $10\ \ expenses:food +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-20\ \ income:gifts +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- +\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ register\ cash +2015/09/30\ gift\ received\ \ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ $20\ \ \ \ \ \ \ \ \ \ \ $20 +2015/10/16\ farmers\ market\ \ assets:cash\ \ \ \ \ \ \ \ \ \ \ \ \ \ $\-10\ \ \ \ \ \ \ \ \ \ \ $10 +\f[] +.fi +.IP +.nf +\f[C] +$\ hledger\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ available\ commands +$\ hledger\ add\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ add\ more\ transactions\ to\ the\ journal\ file +$\ hledger\ balance\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ all\ accounts\ with\ aggregated\ balances +$\ hledger\ balance\ \-\-help\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ help\ for\ balance\ command +$\ hledger\ balance\ \-\-depth\ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ only\ top\-level\ accounts +$\ hledger\ register\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ account\ postings,\ with\ running\ total +$\ hledger\ reg\ income\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ show\ postings\ to/from\ income\ accounts +$\ hledger\ reg\ \[aq]assets:some\ bank:checking\[aq]\ #\ 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 +\f[] +.fi +.SH ENVIRONMENT +.PP +\f[B]LEDGER_FILE\f[] sets the default journal file path. +If not set, it is \f[C]~/.hledger.journal\f[]. +.PP +\f[B]COLUMNS\f[] sets the default width used by the register command +(normally the full terminal width). +.SH FILES +.PP +Reads data from a hledger journal file (\f[C]$LEDGER_FILE\f[] or +\f[C]~/.hledger.journal\f[] by default), or a CSV file plus associated +CSV rules file. +.SH BUGS +.PP +The need to precede options with \f[C]\-\-\f[] when invoked from hledger +is awkward. +.PP +hledger can\[aq]t render non\-ascii characters when run from a Windows +command prompt (up to Windows 7 at least). +.PP +When input data contains non\-ascii characters, a suitable system locale +must be configured (or there will be an unhelpful error). +Eg on POSIX, set LANG to something other than C. +.SH REPORTING BUGS +.PP +Report bugs at http://bugs.hledger.org. + + +.SH "REPORTING BUGS" +Report bugs at http://bugs.hledger.org. + +.SH AUTHORS +Simon Michael + +.SH COPYRIGHT + +Copyright (C) 2007-2015 Simon Michael. +.br +Released under GNU GPLv3+. + +.SH SEE ALSO +hledger(1), hledger\-ui(1), hledger\-web(1), ledger(1) +.br +hledger_csv(5), hledger_journal(5), hledger_timelog(5) + +For more information, see http://hledger.org. diff --git a/hledger/hledger.1.md b/hledger/hledger.1.md new file mode 100644 index 000000000..1b0815b96 --- /dev/null +++ b/hledger/hledger.1.md @@ -0,0 +1,510 @@ +% hledger(1) hledger 0.26.98 +% +% October 2015 + +# NAME + +hledger - a command-line accounting tool + +# SYNOPSIS + +`hledger [-f FILE] COMMAND [OPTIONS] [CMDARGS]`\ +`hledger [-f FILE] ADDONCMD -- [OPTIONS] [CMDARGS]` + +# DESCRIPTION + +hledger is a cross-platform program for tracking money, time, or any +other commodity, using double-entry accounting and a simple, editable +file format. It is inspired by and largely compatible with ledger(1). +hledger aims to be a reliable, practical tool for daily use. This man +page is a quick reference and introduction; for more complete docs, see +http://hledger.org/manual. + +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`. 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: + +```journal +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. + +# OPTIONS + +To see general help and the command list: `hledger --help` or `hledger` + +To see all options available with a command: `hledger COMMAND --help` + +Except for the General options below, options must be written after +COMMAND, not before it. + +Also, when invoking external add-on commands, their options must be +written after a double hyphen. (Or, you can invoke the external command +directly.) Eg: +```{.shell .bold} +$ 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. + +## General flags: + +These can appear anywhere in the command line. + +`-h --help` +: show general help or (after command) command help + +`--version` +: show version information + +`-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 flags: + +These are supported by most commands, where applicable. +They must be written after the command name. +Additional command-specific flags are described in COMMANDS below. + +`-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 + +If a reporting option is repeated, the last one takes precedence. Eg -p jan -p +feb is equivalent to -p feb. + +# COMMANDS + +COMMAND selects one of hledger's subcommands; omit it to list available commands. +To save typing, some commands have a short form; any unique prefix also works. + +Here is a summary (see http://hledger.org/manual#commands for the full command help): + +## Data entry: + +### add +prompt for transactions and add them to the journal. + +This is the only hledger command that writes to the journal file. +It appends only, existing transactions are not changed. + +`--no-new-accounts` +: don't allow creating new accounts; helps prevent typos when entering account names + +## Reporting: + +### 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 + +### activity +show an ascii barchart of posting counts per interval +(default: daily) + +### balance, bal +show accounts and balances + +`--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. + +### balancesheet, bs +show a balance sheet + +`--flat` +: show full account names, as a list (default) + +`--drop=N` +: in flat mode: omit N leading account name parts + +### cashflow, cf +show a cashflow statement + +`--flat` +: show full account names, as a list (default) + +`--drop=N` +: in flat mode: omit N leading account name parts + +### incomestatement, is +show an income statement + +`--flat` +: show full account names, as a list (default) + +`--drop=N` +: in flat mode: omit N leading account name parts + +### 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. + +### register, reg +show postings and running total + +`-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. + +### 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. + +## Add-on commands: + +Additional commands will be available when executables or scripts +named "`hledger-`CMD" are installed in the PATH. These are often +provided by a package of the same name, or you can make your own custom scripts +(haskell scripts can use hledger-lib allowing tight integration). +Some available add-ons are: + +### autosync +download OFX bank data and/or convert OFX to hledger journal format + +### diff +show transactions present in one journal file but not another + +### interest +generate interest transactions + +### irr +calculate internal rate of return + +### ui +curses-style interface, see hledger-ui(1) + +### web +web interface, see hledger-web(1) + +# QUERIES + +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. + +# EXAMPLES + +Two simple transactions in hledger journal format: + +```journal +2015/9/30 gift received + assets:cash $20 + income:gifts + +2015/10/16 farmers market + expenses:food $10 + assets:cash +``` + +Some basic reports: + +```shell +$ hledger print +2015/09/30 gift received + assets:cash $20 + income:gifts $-20 + +2015/10/16 farmers market + expenses:food $10 + assets:cash $-10 +``` +```shell +$ hledger accounts --tree +assets + cash +expenses + food +income + gifts +``` +```shell +$ hledger balance + $10 assets:cash + $10 expenses:food + $-20 income:gifts +-------------------- + 0 +``` +```shell +$ hledger register cash +2015/09/30 gift received assets:cash $20 $20 +2015/10/16 farmers market assets:cash $-10 $10 +``` + +```{.shell .bold} +$ hledger # show available commands +$ hledger add # add more transactions to the journal file +$ hledger balance # all accounts with aggregated balances +$ hledger balance --help # show help for balance command +$ hledger balance --depth 1 # only top-level accounts +$ hledger register # show account postings, with running total +$ hledger reg income # show postings to/from income accounts +$ hledger reg 'assets:some bank:checking' # show postings to/from this checking account +$ hledger print desc:shop # show transactions with shop in the description +$ hledger activity -W # show transaction counts per week as a bar chart +``` + +# ENVIRONMENT + +**LEDGER_FILE** +sets the default journal file path. If not set, it is `~/.hledger.journal`. + +**COLUMNS** +sets the default width used by the register command (normally the full terminal width). + +# FILES + +Reads data from a hledger journal file (`$LEDGER_FILE` or +`~/.hledger.journal` by default), or a CSV file plus associated CSV +rules file. + +# BUGS + +The need to precede options with `--` when invoked from hledger is awkward. + +hledger can't render non-ascii characters when run from a Windows command prompt (up to Windows 7 at least). + +When input data contains non-ascii characters, a suitable system locale must be configured (or there will be an unhelpful error). +Eg on POSIX, set LANG to something other than C. + +# REPORTING BUGS + +Report bugs at http://bugs.hledger.org.