site: content updates for the hakyll/pandoc site
This commit is contained in:
Simon Michael
parent
05474d9a9f
commit
7ca806c5b0
@ -1,17 +1,32 @@
|
||||
<!-- hledger repo and http://hledger.org versions of this document are periodically bidirectionally synced -->
|
||||
|
||||
* toc
|
||||
|
||||
# Developer guide
|
||||
|
||||
## Quick links
|
||||
|
||||
^ hledger.org: ^ [[release notes|combined release notes]], [[download|pre-compiled binaries]] ^
|
||||
^ Github: ^ [code](http://github.com/simonmichael/hledger), [commits](http://github.com/simonmichael/hledger/commits), [COMMITS](http://starlogs.net/#simonmichael/hledger) (turn up your volume) \\ [commits only in master](https://github.com/simonmichael/hledger/compare/0.23...master), [commits only in release branch](https://github.com/simonmichael/hledger/compare/master...0.23) \\ [build status (hydra)](http://hydra.cryp.to/jobset/hledger/master#tabs-jobs) \\ [open bugs](https://github.com/simonmichael/hledger/issues?direction=desc&labels=BUG&page=1&sort=created&state=open), [all bugs](https://github.com/simonmichael/hledger/issues?direction=desc&labels=BUG&page=1&sort=created), [open issues](https://github.com/simonmichael/hledger/issues?direction=desc&labels=&page=1&sort=created&state=open), [all issues](https://github.com/simonmichael/hledger/issues?direction=desc&labels=&page=1&sort=created) ^
|
||||
^ Hackage: ^ [hledger-lib](http://hackage.haskell.org/package/hledger-lib), [hledger](http://hackage.haskell.org/package/hledger), [hledger-web](http://hackage.haskell.org/package/hledger-web), [hledger-interest](http://hackage.haskell.org/package/hledger-interest), [hledger-irr](http://hackage.haskell.org/package/hledger-irr), [hledger-vty](http://hackage.haskell.org/package/hledger-vty), [hledger-chart](http://hackage.haskell.org/package/hledger-chart), [*hledger*](http://hackage.haskell.org/packages/search?terms=hledger) \\ reverse dependencies: [hledger-lib](http://packdeps.haskellers.com/reverse/hledger-lib), [hledger](http://packdeps.haskellers.com/reverse/hledger), [outdated dependencies](http://packdeps.haskellers.com/feed/?needle=hledger) \\ [download activity](http://best-haskell.herokuapp.com/#/category/Finance) ^
|
||||
^ Stackage: ^ [hledger entry](https://github.com/fpco/stackage/blob/master/Stackage/Config.hs#L449-450), [issues](https://github.com/fpco/stackage/search?q=hledger&ref=cmdform&type=Issues) \\ [build status (jenkins)](http://jenkins.stackage.org/job/Stackage/), last build output: [7.4](http://jenkins.stackage.org/job/Stackage/ghcversion=7.4.2/lastBuild/console), [7.6](http://jenkins.stackage.org/job/Stackage/ghcversion=7.6.3/lastBuild/console), [7.8](http://jenkins.stackage.org/job/Stackage/ghcversion=7.8.2/lastBuild/console) ^
|
||||
^ Debian: ^ source packages \\ [haskell-hledger-lib](http://packages.qa.debian.org/h/haskell-hledger-lib.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger-lib), [haskell-hledger](http://packages.qa.debian.org/h/haskell-hledger.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger), [haskell-hledger-web](http://packages.qa.debian.org/h/haskell-hledger-web.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger-web) \\ binary packages \\ testing: [hledger](https://packages.debian.org/testing/hledger), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger;dist=testing), [hledger-web](https://packages.debian.org/testing/hledger-web), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger-web;dist=testing) \\ unstable: [hledger](https://packages.debian.org/unstable/hledger), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger;dist=unstable), [hledger-web](https://packages.debian.org/unstable/hledger-web), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger-web;dist=unstable) \\ all: [*hledger*](https://packages.debian.org/search?searchon=names&keywords=hledger) \\ popularity stats: [hledger](https://qa.debian.org/popcon.php?package=haskell-hledger), [hledger-web](https://qa.debian.org/popcon.php?package=haskell-hledger-web) \\ [PTS help](https://www.debian.org/doc/manuals/developers-reference/resources.html#pkg-tracking-system) ^
|
||||
^ Ubuntu: ^ source packages \\ [haskell-hledger-lib](https://launchpad.net/ubuntu/+source/haskell-hledger-lib), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger-lib), [haskell-hledger](https://launchpad.net/ubuntu/+source/haskell-hledger), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger), [haskell-hledger-web](https://launchpad.net/ubuntu/+source/haskell-hledger-web), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger-web) \\ binary packages \\ [*hledger*](http://packages.ubuntu.com/search?suite=all&searchon=names&keywords=hledger) ^
|
||||
^ Gentoo: ^ [hledger](http://gpo.zugaina.org/dev-haskell/hledger), [hledger-web](http://gpo.zugaina.org/dev-haskell/hledger-web), [*hledger*](http://gpo.zugaina.org/Search?search=hledger) ^
|
||||
^ Fedora: ^ [hledger](https://apps.fedoraproject.org/packages/hledger), [*hledger*](https://apps.fedoraproject.org/packages/s/hledger) ^
|
||||
<style>
|
||||
tr {
|
||||
/*vertical-align:top;*/
|
||||
border-top:thin solid #bbb;
|
||||
}
|
||||
</style>
|
||||
<!-- | hledger.org | [combined release notes](release notes), [pre-compiled binaries](download) | -->
|
||||
<!-- [web ui demo](http://demo.hledger.org/register?q=inacct%3Aassets%3Abank%3Achecking+sym%3A\%24) -->
|
||||
|-------------------------|----------------------------------------------------------------------------|
|
||||
| IRC | Join [#hledger](http://hledger.org/irc) (see also [#ledger](http://webchat.freenode.net?channels=ledger&randomnick=1)) |
|
||||
| Mail list | <http://hledger.org/list> |
|
||||
| Twitter | [#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime), <a href="https://twitter.com/ledgertips">@LedgerTips</a> |
|
||||
| hledger-web demo | [demo.hledger.org](http://demo.hledger.org) |
|
||||
| Trello | [planning board](http://hledger.org/trello) |
|
||||
| Github | [code](http://github.com/simonmichael/hledger), [commits](http://github.com/simonmichael/hledger/commits), [COMMITS](http://starlogs.net/#simonmichael/hledger) (turn up your volume) <br> [commits only in master](https://github.com/simonmichael/hledger/compare/0.23...master), [commits only in release branch](https://github.com/simonmichael/hledger/compare/master...0.23) <br> [build status (hydra)](http://hydra.cryp.to/jobset/hledger/master#tabs-jobs) <br> [open bugs](https://github.com/simonmichael/hledger/issues?direction=desc&labels=BUG&page=1&sort=created&state=open), [all bugs](https://github.com/simonmichael/hledger/issues?direction=desc&labels=BUG&page=1&sort=created), [open issues](https://github.com/simonmichael/hledger/issues?direction=desc&labels=&page=1&sort=created&state=open), [all issues](https://github.com/simonmichael/hledger/issues?direction=desc&labels=&page=1&sort=created) |
|
||||
| Hackage | [hledger-lib](http://hackage.haskell.org/package/hledger-lib), [hledger](http://hackage.haskell.org/package/hledger), [hledger-web](http://hackage.haskell.org/package/hledger-web), [hledger-interest](http://hackage.haskell.org/package/hledger-interest), [hledger-irr](http://hackage.haskell.org/package/hledger-irr), [hledger-vty](http://hackage.haskell.org/package/hledger-vty), [hledger-chart](http://hackage.haskell.org/package/hledger-chart), [*hledger*](http://hackage.haskell.org/packages/search?terms=hledger) <br> reverse dependencies: [hledger-lib](http://packdeps.haskellers.com/reverse/hledger-lib), [hledger](http://packdeps.haskellers.com/reverse/hledger), [outdated dependencies](http://packdeps.haskellers.com/feed/?needle=hledger) <br> [download activity](http://best-haskell.herokuapp.com/#/category/Finance) |
|
||||
| Stackage | [hledger entry](https://github.com/fpco/stackage/blob/master/Stackage/Config.hs#L449-450), [issues](https://github.com/fpco/stackage/search?q=hledger&ref=cmdform&type=Issues) <br> [build status (jenkins)](http://jenkins.stackage.org/job/Stackage/), last build output: [7.4](http://jenkins.stackage.org/job/Stackage/ghcversion=7.4.2/lastBuild/console), [7.6](http://jenkins.stackage.org/job/Stackage/ghcversion=7.6.3/lastBuild/console), [7.8](http://jenkins.stackage.org/job/Stackage/ghcversion=7.8.2/lastBuild/console) |
|
||||
| Debian | source packages <br> [haskell-hledger-lib](http://packages.qa.debian.org/h/haskell-hledger-lib.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger-lib), [haskell-hledger](http://packages.qa.debian.org/h/haskell-hledger.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger), [haskell-hledger-web](http://packages.qa.debian.org/h/haskell-hledger-web.html), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=haskell-hledger-web) <br> binary packages <br> testing: [hledger](https://packages.debian.org/testing/hledger), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger;dist=testing), [hledger-web](https://packages.debian.org/testing/hledger-web), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger-web;dist=testing) <br> unstable: [hledger](https://packages.debian.org/unstable/hledger), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger;dist=unstable), [hledger-web](https://packages.debian.org/unstable/hledger-web), [bugs](https://bugs.debian.org/cgi-bin/pkgreport.cgi?package=hledger-web;dist=unstable) <br> all: [*hledger*](https://packages.debian.org/search?searchon=names&keywords=hledger) <br> popularity stats: [hledger](https://qa.debian.org/popcon.php?package=haskell-hledger), [hledger-web](https://qa.debian.org/popcon.php?package=haskell-hledger-web) <br> [PTS help](https://www.debian.org/doc/manuals/developers-reference/resources.html#pkg-tracking-system) |
|
||||
| Ubuntu | source packages <br> [haskell-hledger-lib](https://launchpad.net/ubuntu/+source/haskell-hledger-lib), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger-lib), [haskell-hledger](https://launchpad.net/ubuntu/+source/haskell-hledger), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger), [haskell-hledger-web](https://launchpad.net/ubuntu/+source/haskell-hledger-web), [bugs](https://bugs.launchpad.net/ubuntu/+source/haskell-hledger-web) <br> binary packages <br> [*hledger*](http://packages.ubuntu.com/search?suite=all&searchon=names&keywords=hledger) |
|
||||
| Gentoo | [hledger](http://gpo.zugaina.org/dev-haskell/hledger), [hledger-web](http://gpo.zugaina.org/dev-haskell/hledger-web), [*hledger*](http://gpo.zugaina.org/Search?search=hledger) |
|
||||
| Fedora | [hledger](https://apps.fedoraproject.org/packages/hledger), [*hledger*](https://apps.fedoraproject.org/packages/s/hledger) |
|
||||
|
||||
<!-- list the debian packages for clarity:
|
||||
3 source:
|
||||
@ -37,7 +52,7 @@ libghc-hledger-lib-prof
|
||||
<!-- [heap](http://hledger.org/profs/latest.ps) -->
|
||||
<!-- [developer notes](http://github.com/simonmichael/hledger/NOTES.org)\ -->
|
||||
<!-- [browse dev API docs](http://hledger.org/api/frames.html) -->
|
||||
<!-- [[developer-guide#set-up-for-development|How to clone it]] -->
|
||||
<!-- [How to clone it](developer-guide#set-up-for-development) -->
|
||||
<!-- [hledger-web dev demo](http://demo.hledger.org:5001) -->
|
||||
|
||||
<!-- hoogle search form
|
||||
@ -247,7 +262,7 @@ It is a single-executable web application using the
|
||||
[yesod](http://yesodweb.com) framework. It runs a built-in web server
|
||||
serving some views of the journal file, reading it at startup and
|
||||
again whenever it changes. It can also append new transactions to the journal file.
|
||||
There are two main views, which can be filtered with [[manual#query-arguments|query arguments]]:
|
||||
There are two main views, which can be filtered with [query arguments](manual#query-arguments):
|
||||
|
||||
- [/journal](http://demo.hledger.org/journal), showing general journal entries (like `hledger print`)
|
||||
|
||||
|
||||
@ -1,25 +1,18 @@
|
||||
<!-- hledger.org and hledger repo versions last synced: 2014/5/1 -->
|
||||
|
||||
* toc
|
||||
|
||||
# hledger User Manual
|
||||
|
||||
This reference manual is for
|
||||
hledger 0.23.98 (the latest pre-0.24 HEAD).
|
||||
<!-- [hledger 0.23](http://hackage.haskell.org/package/hledger-0.23) -->
|
||||
and [hledger-web 0.23](http://hackage.haskell.org/package/hledger-web-0.23).
|
||||
<!-- Other versions: [[0.22/manual|0.22 Manual]]. -->
|
||||
|
||||
- [[#Introduction]]
|
||||
- [[#Usage]]
|
||||
- [[#Data format]]
|
||||
- [[#Options]]
|
||||
- [[#Query arguments]]
|
||||
- [[#Commands]]
|
||||
- [[#Known limitations]]
|
||||
- [[#Troubleshooting]]
|
||||
<!-- Other versions: [0.22 Manual](0.22/manual). -->
|
||||
|
||||
## Introduction
|
||||
|
||||
[[home|hledger]] is a program for tracking money, time,
|
||||
[hledger](/) is a program for tracking money, time,
|
||||
or any other commodity, using a simple, editable file format and
|
||||
double-entry accounting, inspired by and largely compatible with
|
||||
[ledger](http://ledger-cli.org). hledger is Free Software released
|
||||
@ -38,16 +31,8 @@ You can use it to, eg:
|
||||
- track time and report by day/week/month/project
|
||||
- get accurate numbers for client billing and tax filing
|
||||
|
||||
hledger works on linux, mac and windows. People most often build the
|
||||
latest release with cabal-install, like so:
|
||||
|
||||
$ cabal update
|
||||
$ cabal install hledger [hledger-web]
|
||||
...
|
||||
$ hledger --version
|
||||
hledger 0.22.1
|
||||
|
||||
For more help with this, and other install options, see the [[installing|Installation Guide]].
|
||||
hledger works on unix, mac and windows.
|
||||
See [Download](download.html) for installation help.
|
||||
|
||||
## Usage
|
||||
|
||||
@ -56,7 +41,7 @@ Basic usage is:
|
||||
$ hledger COMMAND [OPTIONS] [ARGS]
|
||||
|
||||
Most [commands](#commands) query or operate on a
|
||||
[journal file](#the-journal-file), which by default is `.hledger.journal`
|
||||
[journal file](#journal-files), which by default is `.hledger.journal`
|
||||
in your home directory. You can specify a different file with the `-f`
|
||||
option or `LEDGER_FILE` environment variable, or standard input with `-f-`.
|
||||
|
||||
@ -97,9 +82,9 @@ 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](http://hledger.org/faq#file-format-differences),
|
||||
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#what-are-the-file-format-differences) ledger journal files as well.
|
||||
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.
|
||||
|
||||
@ -294,7 +279,7 @@ 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 [[#including-other-files|included files]], things are a little
|
||||
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
|
||||
@ -386,7 +371,7 @@ starts a transaction comment.
|
||||
|
||||
- With the `comment` and `end comment` keywords it is possible to have multiline comments.
|
||||
|
||||
Transaction and posting comments are displayed by [[#print]], can contain [[#tags]] and can be [[#queries|queried]].
|
||||
Transaction and posting comments are displayed by [print](#print), can contain [tags](#tags) and can be [queried](#queries).
|
||||
|
||||
Some examples:
|
||||
|
||||
@ -413,7 +398,7 @@ Some examples:
|
||||
#### Tags
|
||||
|
||||
You can include *tags* (labels), optionally with values,
|
||||
in transaction and posting comments, and then [[manual#query-arguments|query by tag]].
|
||||
in transaction and posting comments, and then [query by tag](manual#queries).
|
||||
This is like Ledger's [metadata](http://ledger-cli.org/3.0/doc/ledger3.html#Metadata)
|
||||
feature, except hledger's tag values are simple strings.
|
||||
|
||||
@ -433,7 +418,7 @@ one, and all tags have values except TAG1:
|
||||
|
||||
In the journal file, a hledger tag value can contain: text, internal whitespace, or punctuation, but not: commas, newlines, or leading/trailing whitespace (putting quotes around it doesn't work, but probably should).
|
||||
|
||||
In [[manual#query-arguments|tag queries]], remember the tag name must match exactly, while the value part is the usual case-insensitive infix regular expression match.
|
||||
In [tag queries](manual#queries), remember the tag name must match exactly, while the value part is the usual case-insensitive infix regular expression match.
|
||||
#### Directives
|
||||
|
||||
##### Account aliases
|
||||
@ -456,7 +441,7 @@ You can also specify aliases on the command line:
|
||||
Journal directive aliases are applied first, then command-line aliases,
|
||||
and at most one of each will be applied to each account name.
|
||||
|
||||
See also [[How to use account aliases]].
|
||||
See also [How to use account aliases](how-to-use-account-aliases.html).
|
||||
|
||||
##### Default commodity
|
||||
|
||||
@ -466,7 +451,7 @@ The commodity (and the sample amount's display style) will be applied to all sub
|
||||
(Note this is different from Ledger's default commodity directive.)
|
||||
|
||||
Also note the directive itself does not influence the commodity's default
|
||||
[[#amount-display-styles|display style]], but the amount it is
|
||||
[display style](#amount-display-styles), but the amount it is
|
||||
applied to might. Here's an example:
|
||||
|
||||
; set £ as the default commodity
|
||||
@ -749,7 +734,7 @@ Examples:
|
||||
### Reporting interval
|
||||
|
||||
A reporting interval can be specified so that commands like
|
||||
[[#register]], [[#balance]] and [[#activity]] will divide their
|
||||
[register](#register), [balance](#balance) and [activity](#activity) will divide their
|
||||
reports into multiple report periods. The basic intervals can be
|
||||
selected with one of `-D/--daily`, `-W/--weekly`, `-M/--monthly`,
|
||||
`-Q/--quarterly`, or `-Y/--yearly`. More complex intervals may be
|
||||
@ -813,16 +798,16 @@ Examples:
|
||||
|
||||
### Depth limiting
|
||||
|
||||
With the `--depth N` option, commands like [[#account]], [[#balance]]
|
||||
and [[#register]] will show only the uppermost accounts in the account
|
||||
With the `--depth N` option, commands like [account](#account), [balance](#balance)
|
||||
and [register](#register) will show only the uppermost accounts in the account
|
||||
tree, down to level N. Use this when you want a summary with less detail.
|
||||
|
||||
## Query arguments
|
||||
## Queries
|
||||
|
||||
Part of hledger's usefulness is being able to report on just a precise subset of your data.
|
||||
Most commands accept an optional query expression, written as arguments after the command name,
|
||||
to filter the data by date, account name or other criteria. Query expressions are also used
|
||||
in the [[#web|web ui]]'s search form.
|
||||
in the [web ui](#web)'s search form.
|
||||
|
||||
The query syntax is similar to a Google search expression: one or
|
||||
more space-separated search terms, optional prefixes to match specific
|
||||
@ -833,10 +818,10 @@ A query term can be any of the following:
|
||||
- `acct:REGEX` - same as above
|
||||
- `code:REGEX` - match by transaction code (eg check number)
|
||||
- `desc:REGEX` - match transaction descriptions
|
||||
- `date:PERIODEXPR` - match dates within the specified [[#period-expressions|period]]. *Actually, full period syntax is [[https://github.com/simonmichael/hledger/issues/141|not yet supported]].*
|
||||
- `date:PERIODEXPR` - match dates within the specified [period](#period-expressions). *Actually, full period syntax is [not yet supported](https://github.com/simonmichael/hledger/issues/141).*
|
||||
- `date2:PERIODEXPR` - as above, but match secondary dates
|
||||
- `tag:NAME[=REGEX]` - match by (exact, case sensitive) [[#tags|tag]] name, and optionally match the tag value by regular expression. Note `tag:` will match a transaction if it or any its postings have the tag, and will match posting if it or its parent transaction has the tag.
|
||||
- `depth:N` - match (or display, depending on command) accounts at or above this [[#depth-limiting|depth]]
|
||||
- `tag:NAME[=REGEX]` - match by (exact, case sensitive) [tag](#tags) name, and optionally match the tag value by regular expression. Note `tag:` will match a transaction if it or any its postings have the tag, and will match posting if it or its parent transaction has the tag.
|
||||
- `depth:N` - match (or display, depending on command) accounts at or above this [depth](#depth-limiting)
|
||||
- `status:1` or `status:0` - match cleared/uncleared transactions
|
||||
- `real:1` or `real:0` - match real/virtual-ness
|
||||
- `empty:1` or `empty:0` - match if amount is/is not zero
|
||||
@ -860,7 +845,7 @@ A query term can be any of the following:
|
||||
hledger query expressions don't support full boolean logic. Instead, multiple query terms
|
||||
are combined as follows:
|
||||
|
||||
- The [[#print]] command selects transactions which:
|
||||
- The [print](#print) command selects 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
|
||||
@ -868,7 +853,7 @@ are combined as follows:
|
||||
|
||||
<!-- -->
|
||||
|
||||
- Other reporting commands (eg [[#register]] and [[#balance]]) select transactions/postings/accounts which match (or negatively match):
|
||||
- Other reporting commands (eg [register](#register) and [balance](#balance)) select transactions/postings/accounts which match (or negatively match):
|
||||
- any of the description terms AND
|
||||
- any of the account terms AND
|
||||
- all the other terms.
|
||||
@ -877,7 +862,7 @@ are combined as follows:
|
||||
|
||||
On the command line, some of the query terms above can also be expressed as command-line flags.
|
||||
Generally you can mix and match query arguments and flags, and the resulting query will be their intersection.
|
||||
Remember that a `-p` [[#period-expressions|period]] flag will cause any other `-b`, `-e` or `-p` flags on the command line to be ignored.
|
||||
Remember that a `-p` [period](#period-expressions) flag will cause any other `-b`, `-e` or `-p` flags on the command line to be ignored.
|
||||
|
||||
|
||||
## Commands
|
||||
@ -917,18 +902,18 @@ Additional convenience features:
|
||||
descriptions, dates (`yesterday`, `today`, `tomorrow`). If the input
|
||||
area is empty, it will insert the default value.
|
||||
|
||||
- If the journal defines a [[#default-commodity|default commodity]],
|
||||
- If the journal defines a [default commodity](#default-commodity),
|
||||
it will be added to any bare numbers entered.
|
||||
|
||||
- A parenthesised transaction [[#entries|code]] may be entered following a date.
|
||||
- A parenthesised transaction [code](#entries) may be entered following a date.
|
||||
|
||||
- [[#comments|Comments]] and tags may be entered following a description or amount.
|
||||
- [Comments](#comments) and tags may be entered following a description or amount.
|
||||
|
||||
- If you make a mistake, enter `<` at any prompt to restart the transaction.
|
||||
|
||||
- Input prompts are displayed in a different colour when the terminal supports it.
|
||||
|
||||
Here's [[step-by-step#record-a-transaction-with-hledger-add|an example]].
|
||||
Here's [an example](step-by-step#record-a-transaction-with-hledger-add).
|
||||
<!--
|
||||
$ hledger add
|
||||
(...)
|
||||
@ -1037,7 +1022,7 @@ The balance command displays accounts and their balances.
|
||||
|
||||
##### Simple balance reports
|
||||
|
||||
Simple balance reports have no [[#reporting-interval|reporting interval]].
|
||||
Simple balance reports have no [reporting interval](#reporting-interval).
|
||||
They show the sum of matched postings in each account.
|
||||
(If postings are not date-restricted, this is usually the same as the ending balance).
|
||||
|
||||
@ -1075,7 +1060,7 @@ This is very useful to summarise complex charts of accounts.
|
||||
|
||||
##### Multi balance reports
|
||||
|
||||
With a [[#reporting-interval|reporting interval]], multiple balance
|
||||
With a [reporting interval](#reporting-interval), multiple balance
|
||||
columns will be shown, one for each report period.
|
||||
There are three types of multi-column balance report, showing different information:
|
||||
|
||||
@ -1261,7 +1246,7 @@ There are some tricks when specifying options:
|
||||
|
||||
Add-ons which are written in haskell can take advantage of hledger's library API
|
||||
for journal parsing, reports, consistent command-line options etc.
|
||||
One notable add-on is [[#web|hledger-web]], which is maintained along with
|
||||
One notable add-on is [hledger-web](#web), which is maintained along with
|
||||
hledger and supported on the same major platforms. Other add-ons may
|
||||
have different release schedules and platform support.
|
||||
|
||||
@ -1478,13 +1463,13 @@ preceding them. Eg hledger-web's `--server` flag must be used like so:
|
||||
|
||||
### -w/--width and --debug options must be written without whitespace
|
||||
|
||||
Up to hledger 0.23, these optional-value flags [[https://github.com/simonmichael/hledger/issues/149|did not work]] with whitespace between the flag and value.
|
||||
Up to hledger 0.23, these optional-value flags [did not work](https://github.com/simonmichael/hledger/issues/149) with whitespace between the flag and value.
|
||||
IE these worked: `--debug`, `-w`, `--debug=2`, `-w100`, but these did not: `--debug 2`, `-w 100`.
|
||||
From 0.24, a value is required and the whitespace does not matter.
|
||||
|
||||
### Not all of Ledger's journal file syntax is supported
|
||||
|
||||
See [[faq#file-format-differences|file format differences]].
|
||||
See [file format differences](faq#file-format-differences).
|
||||
|
||||
### balance is less speedy than Ledger's on large data files
|
||||
|
||||
|
||||
@ -1,31 +1,75 @@
|
||||
# Download
|
||||
|
||||
\\
|
||||
**I want to download and get started quickly !**\\
|
||||
<!-- <sub>(If the download is out of date or doesn't run on my system, I might troubleshoot or donate to fund improvements)</sub> -->
|
||||
| **I'm on Debian or Ubuntu**\\ `apt-get install hledger[-web]` \\ \\ **I'm on Gentoo**\\ `emerge hledger[-web]` <!-- \\ --> <!-- \\ --> <!-- **I'm on another GNU/Linux\\<small>(or can run Linux binaries)</small>**\\ --> <!-- <\\!-- [hledger.linux-32.zip]()\\ -\\-> --> <!-- <\\!-- [hledger-web.linux-32.zip]()\\ -\\-> --> <!-- <\\!-- [hledger.linux-64.zip]()\\ -\\-> --> <!-- <\\!-- [hledger-web.linux-64.zip]()\\ -\\-> --> <!-- Use cabal --> <!-- </td> --> \\ \\ **I'm on Red Hat/Fedora/CentOS**\\ `yum install hledger` \\ \\ **I'm on NixOS**\\ `nix-env -iA nixpkgs.haskellPackages.hledger` | **I'm on Windows**\\ <!-- [windows install guide](windows-install.html)\\ --> Download, unzip, and run:\\ [hledger-0.23.3.win32.zip](http://hledger.org/downloads/hledger-0.23.3-windows-intel32.exe.zip)\\ [hledger-web-0.23.3.win32.zip](http://hledger.org/downloads/hledger-web-0.23.3-windows-intel32.exe.zip)\\ | **I'm on Mac**\\ <!-- **I'm on Mac OSX 10.9+**\\ --> <!-- [mac install guide](mac-install.html)\\ --> <!-- [hledger.mac.zip]()\\ --> <!-- [hledger-web.mac.zip]()\\ --> Use cabal |
|
||||
|
||||
**I want to build the
|
||||
[latest release](http://hackage.haskell.org/package/hledger-web) with
|
||||
[GHC](http://haskell.org/haskell) and
|
||||
[cabal](http://haskell.org/cabal/download.html)...**
|
||||
| `cabal sandbox init; cabal update; cabal install hledger[-web]`\\ |
|
||||
<!-- [cabal install guide](cabal-install.html) -->
|
||||
|
||||
**I want to build the [latest development code](http://hledger.org/code)...**
|
||||
| `git clone https://github.com/simonmichael/hledger; cd hledger; make sandbox install`\\ |
|
||||
|
||||
**I want more info...**
|
||||
|
||||
The [[installing|Installation Guide]] describes how to install using cabal in more detail.
|
||||
|
||||
hledger is shipped as two executables: `hledger` (the command-line
|
||||
tool) and `hledger-web` (the web interface). If you install
|
||||
`hledger-web`, `hledger` will also be installed automatically (except on Windows).
|
||||
`hledger-web`, `hledger` is also installed automatically (except on Windows).
|
||||
|
||||
Building, testing and supporting cross-platform binaries is costly, so
|
||||
## I want to download and run
|
||||
<!-- <sub>(If the download is out of date or doesn't run on my system, I might troubleshoot or donate to fund improvements)</sub> -->
|
||||
|
||||
<table>
|
||||
<tr valign="top">
|
||||
<td width="33%">
|
||||
**I'm on Debian or Ubuntu**\
|
||||
`apt-get install hledger[-web]`
|
||||
|
||||
**I'm on Gentoo**\
|
||||
`emerge hledger[-web]`
|
||||
|
||||
**I'm on Red Hat/Fedora/CentOS**\
|
||||
`yum install hledger`
|
||||
|
||||
**I'm on NixOS**\
|
||||
`nix-env -iA nixpkgs.haskellPackages.hledger`
|
||||
|
||||
<!--
|
||||
**I'm on another GNU/Linux\<small>(or can run Linux binaries)</small>**
|
||||
[hledger.linux-32.zip]()
|
||||
[hledger-web.linux-32.zip]()
|
||||
[hledger.linux-64.zip]()
|
||||
[hledger-web.linux-64.zip]()
|
||||
Use cabal
|
||||
-->
|
||||
|
||||
</td>
|
||||
<td width="33%">
|
||||
|
||||
**I'm on Windows**\
|
||||
<!-- [windows install guide](windows-install.html)\ -->
|
||||
Download, unzip, and run:\
|
||||
[hledger-0.23.3.win32.zip](http://hledger.org/downloads/hledger-0.23.3-windows-intel32.exe.zip)\
|
||||
[hledger-web-0.23.3.win32.zip](http://hledger.org/downloads/hledger-web-0.23.3-windows-intel32.exe.zip)
|
||||
|
||||
</td>
|
||||
<td width="33%">
|
||||
|
||||
**I'm on Mac**\
|
||||
<!-- [mac install guide](mac-install.html)\ -->
|
||||
<!-- [hledger.mac.zip]()\ -->
|
||||
<!-- [hledger-web.mac.zip]()\ -->
|
||||
Use cabal
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<div style="margin-left:1em; float:right;">
|
||||
**[Gittip](https://www.gittip.com/simonmichael/)**,
|
||||
<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5J33NLXYXCYAY"><img border=0 src="https://www.paypal.com/en_US/i/btn/x-click-but04.gif" alt="paypal"></a>
|
||||
</div>
|
||||
Building, testing and supporting Windows and Mac binaries is costly, so
|
||||
it's demand-driven - you can indicate demand by making a project
|
||||
donation of any size. Binaries funded in this way will be linked here.
|
||||
This is a quick way to help the project and your fellow users!
|
||||
|
||||
[[https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5J33NLXYXCYAY|{{https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif }}]]
|
||||
## I want to build the [latest release](http://hackage.haskell.org/package/hledger-web) with [GHC](http://haskell.org/haskell) and [cabal](http://haskell.org/cabal/download.html)
|
||||
|
||||
`cabal sandbox init; cabal update; cabal install hledger[-web]`\
|
||||
<!-- [cabal install guide](cabal-install.html) -->
|
||||
|
||||
The [Installation Guide](installing.html) describes how to install using cabal in more detail.
|
||||
|
||||
## I want to build the [latest development code](http://hledger.org/code)
|
||||
|
||||
`git clone https://github.com/simonmichael/hledger; cd hledger; make sandbox install`
|
||||
|
||||
|
||||
@ -1,3 +1,5 @@
|
||||
* toc
|
||||
|
||||
# Frequently asked questions
|
||||
|
||||
## hledger and ledger
|
||||
@ -35,11 +37,11 @@ can often use both tools on the same data file.
|
||||
Summary: hledger is a friendly, co-evolving, compatible rewrite of Ledger
|
||||
in Haskell, lacking some of ledger's power features and raw performance,
|
||||
and focussing on robustness, usability, ease of development, and
|
||||
experimental add-ons such as the [web interface](MANUAL.html#web).
|
||||
experimental add-ons such as the [web interface](manual.html#web).
|
||||
|
||||
### And ledger 4 ?
|
||||
|
||||
There is also a [[https://github.com/ledger/ledger4|ledger4]] on github; this is
|
||||
There is also a [ledger4](https://github.com/ledger/ledger4) on github; this is
|
||||
John's own rewrite of the core of
|
||||
ledger 3 in haskell. It's an early library prototype, not a usable tool.
|
||||
Perhaps some day hledger or something like it would use this as its foundation.
|
||||
@ -51,10 +53,10 @@ Generally, it's easy to keep a journal file that works with both hledger
|
||||
and ledger if you avoid ledger's most specialised syntax.
|
||||
Some ledger syntax is parsed but ignored (such as
|
||||
[automated transactions](http://ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions), [periodic transactions](http://ledger-cli.org/3.0/doc/ledger3.html#Periodic-Transactions), and
|
||||
[[manual#historical-prices|historical prices]]).
|
||||
[historical prices](manual.html#historical-prices)).
|
||||
Some features are not currently parsed and will cause an error, eg
|
||||
ledger's more recent top-level directives. There can also be subtle
|
||||
differences in parser behaviour, eg [[manual#comments|hledger comments]] vs [[http://ledger-cli.org/3.0/doc/ledger3.html#Commenting-on-your-Journal|ledger comments]].
|
||||
differences in parser behaviour, eg [hledger comments](manual.html#comments) vs [ledger comments](http://ledger-cli.org/3.0/doc/ledger3.html#Commenting-on-your-Journal).
|
||||
|
||||
### Feature differences ?
|
||||
|
||||
@ -191,16 +193,16 @@ entry DATE PAYEE AMT output a derived entry, based on the arguments
|
||||
- hledger generates a description for timelog sessions, instead of
|
||||
taking it from the clock-out entry
|
||||
|
||||
- hledger's [include directive](MANUAL.html#including-other-files) does not support
|
||||
- hledger's [include directive](manual.html#including-other-files) does not support
|
||||
shell glob patterns (eg `include *.journal` ), which ledger does.
|
||||
|
||||
- when checking [balance assertions](MANUAL.html#balance-assertions)
|
||||
- when checking [balance assertions](manual.html#balance-assertions)
|
||||
hledger sorts the account's postings first by date and then (for
|
||||
postings with the same date) by parse order. ledger goes strictly by
|
||||
parse order.
|
||||
|
||||
- ledger allows amounts to have a
|
||||
[fixed lot price](MANUAL.html#prices) and a regular price in any
|
||||
[fixed lot price](manual.html#fixed-lot-prices) and a regular price in any
|
||||
order (and uses whichever appears first). hledger requires the fixed
|
||||
lot price to come last (and ignores it).
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# How to read CSV files
|
||||
|
||||
Here's a quick example of [[manual#csv-files|converting a CSV file]].
|
||||
Here's a quick example of [converting a CSV file](manual.html#csv-files).
|
||||
|
||||
Say we have downloaded `checking.csv` from a bank for the first time:
|
||||
|
||||
@ -8,7 +8,7 @@ Say we have downloaded `checking.csv` from a bank for the first time:
|
||||
"2012/3/22","DEPOSIT","50.00"
|
||||
"2012/3/23","TRANSFER TO SAVINGS","-10.00"
|
||||
|
||||
We tell hledger how to intepret this with a file named `checking.csv.rules`, using the [[manual#csv-files|CSV rules syntax]]. Eg:
|
||||
We tell hledger how to intepret this with a file named `checking.csv.rules`, using the [CSV rules syntax](manual.html#csv-files). Eg:
|
||||
|
||||
# skip the first CSV line (headings)
|
||||
skip 1
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# How to use account aliases
|
||||
|
||||
Here's an example of using [[manual#account-aliases|account aliases]].
|
||||
Here's an example of using [account aliases](manual.html#account-aliases).
|
||||
|
||||
Say a sole proprietor has a `personal.journal`:
|
||||
|
||||
|
||||
@ -4,30 +4,49 @@
|
||||
|
||||
hledger is a computer program for easily tracking money, time, or other commodities,
|
||||
on unix, mac and windows.
|
||||
|
||||
It is first a command-line tool, but there is also a [web interface](manual.html#web)
|
||||
It was inspired by and maintains substantial compatibility with [Ledger](faq.html#hledger-and-ledger).
|
||||
hledger is first a command-line tool, but there is also a [web interface](manual.html#web),
|
||||
and a [Haskell library](http://hackage.haskell.org/package/hledger-lib) for
|
||||
building your own programs and [scripts](more-docs.html#scripting-examples)
|
||||
(hledger is written in Haskell).
|
||||
hledger was inspired by and is largely compatible with [Ledger](faq.html#hledger-and-ledger).
|
||||
hledger is free software available under the GNU General Public License v3+.
|
||||
|
||||
hledger aims to help both computer experts and regular folks
|
||||
to gain clarity and control in their finances and time management,
|
||||
but currently it is a bit more suited to techies.
|
||||
I use it every day to:
|
||||
|
||||
- track spending and income
|
||||
- see time reports by day/week/month/project
|
||||
- get accurate numbers for client billing and tax filing
|
||||
- track invoices
|
||||
hledger is free software, available under the GNU GPLv3+,
|
||||
created by [Simon Michael](http://joyful.com) and [contributors](CONTRIBUTORS.html).
|
||||
|
||||
Though limited in features, hledger is lightweight, usable and reliable.
|
||||
For some, it is a simpler, less distracting, more future-proof alternative to Quicken or GnuCash.
|
||||
To get started, see the navigation links.
|
||||
For some, it is a simple, flexible, future-proof alternative to Quicken or GnuCash.
|
||||
It aims to help both computer experts and regular folks
|
||||
to gain clarity and control in their finances and time management,
|
||||
but currently it is a bit more suited to techies.
|
||||
I've been using (and improving) it since 2007 to:
|
||||
|
||||
- track spending and income
|
||||
- see time reports by day/week/month/project
|
||||
- get accurate numbers for client billing and tax filing
|
||||
- track invoices
|
||||
|
||||
To get started, you could
|
||||
**[download](download.html)**,
|
||||
read the **[tutorial](step-by-step.html)**,
|
||||
or **[join the IRC channel](http://hledger.org/irc)** and ask questions.
|
||||
|
||||
<!-- <style> -->
|
||||
<!-- tr { -->
|
||||
<!-- /*vertical-align:top;*/ -->
|
||||
<!-- border-top:thin solid #bbb; -->
|
||||
<!-- } -->
|
||||
<!-- </style> -->
|
||||
|-------------------------|----------------------------------------------------------------------------|
|
||||
| IRC | [#hledger](http://hledger.org/irc) (see also [#ledger](http://webchat.freenode.net?channels=ledger&randomnick=1)) |
|
||||
| Mail list | [hledger.org/list](http://hledger.org/list) |
|
||||
| Twitter | [#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime), <a href="https://twitter.com/ledgertips">@LedgerTips</a> |
|
||||
|
||||
<!-- | web UI demo | [demo.hledger.org](http://demo.hledger.org) | -->
|
||||
<!-- [web ui demo](http://demo.hledger.org/register?q=inacct%3Aassets%3Abank%3Achecking+sym%3A\%24) -->
|
||||
|
||||
<div style="margin-top:2em; text-align:right; float:right;">
|
||||
<!-- Has hledger saved you or your employer money, time or peace of mind ? -->
|
||||
<!-- Donations: -->
|
||||
<!-- **[Gittip](https://www.gittip.com/simonmichael/)**, -->
|
||||
<!-- [https://www.paypal.com/en_US/i/btn/x-click-but04.gif](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5J33NLXYXCYAY) -->
|
||||
**[Gittip](https://www.gittip.com/simonmichael/)**,
|
||||
<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5J33NLXYXCYAY"><img border=0 src="https://www.paypal.com/en_US/i/btn/x-click-but04.gif" alt="paypal"></a>
|
||||
<!-- Also testimonials, examples, blogging, packaging, and patches. -->
|
||||
</div>
|
||||
|
||||
@ -1,3 +1,5 @@
|
||||
* toc
|
||||
|
||||
# Installation Guide
|
||||
|
||||
- [[#How to install]]
|
||||
|
||||
@ -1,11 +1,13 @@
|
||||
* toc
|
||||
|
||||
# More docs...
|
||||
|
||||
[[old screenshots|Screenshots]] (old)
|
||||
[Screenshots](old-screenshots.html) (old)
|
||||
|
||||
## How-tos
|
||||
|
||||
- [[How to read CSV files]]
|
||||
- [[How to use account aliases]]
|
||||
- [How to read CSV files](how-to-read-csv-files.html)
|
||||
- [How to use account aliases](how-to-use-account-aliases.html)
|
||||
|
||||
## Blog posts & articles
|
||||
|
||||
@ -41,16 +43,16 @@ Here are some good intros, which also serve as a good orientation for hledger:
|
||||
|
||||
See also the two Twitter feeds:
|
||||
|
||||
- [@LedgerTips](https://twitter.com/LedgerTips) Tips and tricks for Ledger, hledger, beancount, etc.
|
||||
- <a href="https://twitter.com/LedgerTips">@LedgerTips</a> Tips and tricks for Ledger, hledger, beancount, etc.
|
||||
- [#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime) Search for latest mentions of the `#ledgercli` hash tag
|
||||
|
||||
## Accounting
|
||||
|
||||
-
|
||||
[[wp>Accountancy]],
|
||||
[[wp>Bookkeeping]],
|
||||
[[wp>Double-entry bookkeeping system]],
|
||||
[[wp>General journal]]
|
||||
[Accounting](http://en.wikipedia.org/wiki/Accounting),
|
||||
[Bookkeeping](http://en.wikipedia.org/wiki/Bookkeeping),
|
||||
[Double-entry bookkeeping system](http://en.wikipedia.org/wiki/Double_entry_bookkeeping_system),
|
||||
[General journal](http://en.wikipedia.org/wiki/General_journal)
|
||||
etc. at Wikipedia
|
||||
- [Accounting For Dragons](http://podcastle.org/2009/10/09/pc-miniature-38-accounting-for-dragons) why you should know accounting
|
||||
- [Bean Counter](http://www.dwmbeancounter.com/) - tutorials, such as
|
||||
@ -77,20 +79,20 @@ See also the two Twitter feeds:
|
||||
|
||||
- [hledger-interest](http://hackage.haskell.org/package/hledger-interest) generates various kinds of interest transaction
|
||||
- [hledger-irr](http://hackage.haskell.org/package/hledger-irr) reports internal rate of return (effective interest rate)
|
||||
- [[h]ledger-autosync](https://bitbucket.org/egh/ledger-autosync) downloads/converts/deduplicates OFX data
|
||||
- [ledger-autosync](https://bitbucket.org/egh/ledger-autosync) downloads/converts/deduplicates OFX data
|
||||
- [hledger-chart](http://hackage.haskell.org/package/hledger-chart) generates simple pie charts (unmaintained)
|
||||
- [hledger-vty](http://hackage.haskell.org/package/hledger-vty) a simple curses-style UI (unmaintained)
|
||||
- More in [[code>extra/]]
|
||||
- More in [extra/](https://github.com/simonmichael/hledger/tree/master/extra/)
|
||||
|
||||
## Scripting examples
|
||||
|
||||
- https://gist.github.com/4172604 printing average expenses by month
|
||||
- https://gist.github.com/4210558 calculating historical account balances
|
||||
- More in [[code>extra/]]
|
||||
- <https://gist.github.com/4172604> printing average expenses by month
|
||||
- <https://gist.github.com/4210558> calculating historical account balances
|
||||
- More in [extra/](https://github.com/simonmichael/hledger/tree/master/extra/)
|
||||
|
||||
## Similar projects
|
||||
|
||||
In addition to hledger and Ledger, there are other [[ledgerwiki>Ports|Ledger ports]] and Ledger-likes, incompatible but similar in concept:
|
||||
In addition to hledger and Ledger, there are other [Ledger ports](ledgerwiki>Ports) and Ledger-likes, incompatible but similar in concept:
|
||||
|
||||
- Martin Blais' [beancount](https://furius.ca/beancount/) (python)
|
||||
- Harshad RJ's [Abandon](https://github.com/hrj/abandon) (scala)
|
||||
@ -104,5 +106,5 @@ Other things of interest:
|
||||
- [debts](http://darcsden.com/ozamosi/debts) - small debt tracking web app
|
||||
- [housetab-multi](http://darcsden.com/dbp/housetab-multi), [housetab.org](http://housetab.org) - a web app to manage expenses between a group of friends
|
||||
- [You Need A Budget](http://www.youneedabudget.com/)
|
||||
- Software Freedom Conservancy's [[http://npoacct.sfconservancy.org|npo-acct]] project
|
||||
- Software Freedom Conservancy's [npo-acct](http://npoacct.sfconservancy.org) project
|
||||
|
||||
|
||||
@ -6,32 +6,32 @@
|
||||
|
||||
Showing the journal format, a register report, and a balance report:
|
||||
|
||||
{{http://hledger.org/images/hledger-screen-1.png|Basic command-line reports, like ledger}}
|
||||
|
||||
|
||||
## Time dashboard in emacs
|
||||
|
||||
The upper window displays today's time report every minute (using ansi-term, watch, a helper script, and hledger invoked via 'hours' symlink.) The lower window is viewing the timelog file, to tweak clock-ins/clock-outs made with C-x t i and C-x t o.
|
||||
|
||||
{{http://hledger.org/images/watchhours.png|The upper window displays today's time report every minute (using ansi-term, watch, a helper script, and hledger invoked via 'hours' symlink.) The lower window is viewing the timelog file, to tweak clock-ins/clock-outs made with C-x t i and C-x t o.}}
|
||||
|
||||
|
||||
## Pie charts (hledger-chart)
|
||||
|
||||
Viewing a year of monthly expense charts in emacs. These were generated by hledger 0.10 with -fchart, which became [[http://hackage.haskell.org/package/hledger-chart|hledger-chart]], presently unmaintained.
|
||||
Viewing a year of monthly expense charts in emacs. These were generated by hledger 0.10 with -fchart, which became [hledger-chart](http://hackage.haskell.org/package/hledger-chart), presently unmaintained.
|
||||
|
||||
{{http://hledger.org/images/hledger-charts-2.png|Viewing a year of monthly expense charts in emacs (hledger 0.10 with -fchart).}}
|
||||
|
||||
|
||||
## Curses-style interface (hledger-vty)
|
||||
|
||||
[[http://hackage.haskell.org/package/hledger-vty|hledger-vty]], currently unmaintained.
|
||||
[hledger-vty](http://hackage.haskell.org/package/hledger-vty), currently unmaintained.
|
||||
|
||||
{{http://hledger.org/images/sshot.png|The vty (curses-style) interface}}
|
||||
|
||||
|
||||
## Web interface (hledger-web)
|
||||
|
||||
This minimal web interface was hledger 0.11pre with -fwebyesod, which became [[http://hackage.haskell.org/package/hledger-web|hledger-web]].
|
||||
Here's the [[http://demo.hledger.org|latest interface]].
|
||||
This minimal web interface was hledger 0.11pre with -fwebyesod, which became [hledger-web](http://hackage.haskell.org/package/hledger-web).
|
||||
Here's the [latest interface](http://demo.hledger.org).
|
||||
|
||||
{{http://hledger.org/images/hledger-web-journal.png|The web interface (hledger 0.11pre with -fwebyesod).}}
|
||||
|
||||
|
||||
|
||||
<!--
|
||||
|
||||
@ -1,3 +1,5 @@
|
||||
* toc
|
||||
|
||||
# Release notes
|
||||
|
||||
Based on the
|
||||
@ -189,7 +191,7 @@ Improved:
|
||||
**New:**
|
||||
|
||||
- balance: with a reporting interval (monthly, yearly etc.), the
|
||||
[balance command](MANUAL.html#balance) will now show a multi-column report, showing either
|
||||
[balance command](manual.html#balance) will now show a multi-column report, showing either
|
||||
the per-period changes in balance (by default),
|
||||
the period ending balances starting from zero (`--cumulative`),
|
||||
or the actual period ending balances (`--historical`).
|
||||
@ -314,7 +316,7 @@ Marko Kocić, Max Bolingbroke, and a big welcome to first-time committer John Wi
|
||||
|
||||
**CSV reading:**
|
||||
|
||||
- CSV conversion rules have a simpler, more flexible [syntax](MANUAL.html#csv-files).
|
||||
- CSV conversion rules have a simpler, more flexible [syntax](manual.html#csv-files).
|
||||
Existing rules files will need to be updated manually:
|
||||
- the filename is now `FILE.csv.rules` instead of `FILE.rules`
|
||||
- `FIELD-field N` is now `FIELD %N+1` (or set them all at once with a `fields` rule)
|
||||
@ -452,11 +454,11 @@ Marko Kocić, Max Bolingbroke, and a big welcome to first-time committer John Wi
|
||||
## 2012/5/29 hledger 0.18
|
||||
|
||||
* web: hledger-web is now based on yesod 1.0
|
||||
* web: fix js error breaking second use of add form ([#72](http://code.google.com/p/hledger/issues/detail?id=72))
|
||||
* web: fix js error breaking second use of add form ([#72](http://bugs.hledger.org/72))
|
||||
* web: make `yesod devel` work
|
||||
* the command-line now supports a more powerful [query language](MANUAL.html#queries), consistent with the web UI
|
||||
* hledger now fully supports [tags](MANUAL.html#tags) (aka metadata) on both transactions and postings, and querying by tag or tag value
|
||||
* new commands `incomestatement`, `balancesheet`, and `cashflow` provide basic financial statements under certain [conditions](http://hledger.org/MANUAL.html#incomestatement)
|
||||
* the command-line now supports a more powerful [query language](manual.html#queries), consistent with the web UI
|
||||
* hledger now fully supports [tags](manual.html#tags) (aka metadata) on both transactions and postings, and querying by tag or tag value
|
||||
* new [commands](manual.html#incomestatement) `incomestatement`, `balancesheet`, and `cashflow` provide basic financial statements under certain conditions
|
||||
* format conversion is now done on demand, and the convert command has been dropped. So instead of
|
||||
`hledger convert FILE.csv` just do `hledger -f FILE.csv print` or any other command.
|
||||
You can also pipe any supported format into `hledger -f- CMD` and hledger will try to do the right thing.
|
||||
|
||||
@ -1,51 +1,41 @@
|
||||
# hledger Step by Step (draft)
|
||||
* toc
|
||||
|
||||
*(c) Simon Michael, 2014*
|
||||
# hledger step by step
|
||||
|
||||
Welcome! Here you can learn hledger (and a little double-entry
|
||||
accounting) by practicing, one hands-on exercise at a time, in the
|
||||
style of the "Learn X the Hard Way" books. Exercises are grouped into
|
||||
these chapters:
|
||||
|
||||
- [[#0. SETUP]]
|
||||
- [[#1. BASIC DATA ENTRY & REPORTING]]
|
||||
- [[#2. USEFUL ACCOUNTING CONCEPTS]]
|
||||
Here you can learn hledger (and a little double-entry accounting) by
|
||||
practicing, one hands-on exercise at a time (similar to the
|
||||
"Learn X the Hard Way" books.)
|
||||
|
||||
You'll learn the most if you work through each small step in order.
|
||||
If a step specifies no particular task, your task is to run the examples and understand it.
|
||||
|
||||
If you get stuck, or have any other feedback, report it on IRC or the mail list (see the sidebar),
|
||||
or right on this page (click the pencil on the right).
|
||||
If you get stuck, or have any other feedback, report it on IRC or the mail list, or send a pull request for this page.
|
||||
|
||||
You'll need:
|
||||
|
||||
1. hledger, installed using the [[installing|Installation Guide]]. These exercises were last tested with: hledger 0.23dev-20140212.
|
||||
1. A basic understanding of the command line, text file editing, and regular expressions. Or, the ability to ask for help on the IRC channel.
|
||||
|
||||
2. A basic understanding of the command line, text file editing, and regular expressions. Or, the ability to ask for help on the IRC channel.
|
||||
2. hledger (see [Download](download.html)). These exercises were last tested with: hledger 0.23dev-20140212.
|
||||
|
||||
|
||||
|
||||
---
|
||||
## 0. SETUP
|
||||
## SETUP
|
||||
|
||||
---
|
||||
### Check your hledger
|
||||
|
||||
Get a command prompt, and run hledger to check the version. It should be reasonably [[release-notes|up to date]].:
|
||||
Get a command prompt, and run hledger to check the version. It should be reasonably [up to date](release-notes.html):
|
||||
|
||||
```
|
||||
$ hledger --version
|
||||
hledger 0.23
|
||||
```
|
||||
|
||||
---
|
||||
## 1. BASIC DATA ENTRY & REPORTING
|
||||
## BASIC DATA ENTRY & REPORTING
|
||||
|
||||
---
|
||||
### Locate your journal file with "hledger stats"
|
||||
|
||||
hledger reads financial transactions from a "journal file" (so named because it represents a [[wp>General Journal]]).
|
||||
The default journal file is in your home directory; check its path using the [[manual#stats|stats]] command.
|
||||
hledger reads financial transactions from a "journal file" (so named because it represents a [General Journal](http://en.wikipedia.org/wiki/General_Journal)).
|
||||
The default journal file is in your home directory; check its path using the [stats](manual.html#stats) command.
|
||||
You should see something like:
|
||||
```
|
||||
$ hledger stats
|
||||
@ -58,10 +48,9 @@ Most hledger commands read this file but can not change it; the `add` and `web`
|
||||
|
||||
(If `stats` reports that the file exists, eg because you previously created it, move it out of the way temporarily for these exercises.)
|
||||
|
||||
---
|
||||
### Record a transaction with "hledger add"
|
||||
|
||||
Follow the help and use the [[manual#add|add]] command to record your first transaction,
|
||||
Follow the help and use the [add](manual.html#add) command to record your first transaction,
|
||||
an imaginary purchase at the supermarket.
|
||||
We'll go through this in detail. Later you'll learn other ways to enter data.
|
||||
|
||||
@ -176,10 +165,9 @@ Accounts : 2 (depth 1)
|
||||
Commodities : 1 ($)
|
||||
```
|
||||
|
||||
---
|
||||
### Show transactions with "hledger print"
|
||||
|
||||
The [[manual#print|print]] command shows a tidied-up view of the transaction entries in your journal.
|
||||
The [print](manual.html#print) command shows a tidied-up view of the transaction entries in your journal.
|
||||
Since there's just one so far, you should see:
|
||||
|
||||
```
|
||||
@ -189,7 +177,6 @@ $ hledger print
|
||||
assets $-10
|
||||
```
|
||||
|
||||
---
|
||||
### Examine your journal file
|
||||
|
||||
List and print the journal file (on Windows, use `dir` and `type` and the file path from `hledger stats`):
|
||||
@ -204,7 +191,6 @@ $ cat ~/.hledger.journal
|
||||
assets
|
||||
```
|
||||
|
||||
---
|
||||
### A convenience: inferred amounts
|
||||
|
||||
Why is the amount missing from the assets posting above ?
|
||||
@ -214,7 +200,6 @@ For consistency, `add` uses the same convention when it writes an entry.
|
||||
(But `print` shows the inferred amount, for clarity.)
|
||||
Only one missing amount is allowed in each transaction.
|
||||
|
||||
---
|
||||
### Edit the journal file
|
||||
|
||||
Since the journal file is plain text, you can edit it directly with any text editor.
|
||||
@ -245,7 +230,6 @@ hledger: could not balance this transaction (can't have more than one missing am
|
||||
|
||||
All hledger commands expect the journal to be well-formed, and will report an error and exit otherwise.
|
||||
|
||||
---
|
||||
### Two spaces
|
||||
|
||||
Notice the last part of that error message: "`... remember to put 2 or more spaces before amounts)`".
|
||||
@ -262,7 +246,6 @@ Since account names may contain spaces, hledger thinks the first
|
||||
posting is to an account named "`expenses $10`", with a missing
|
||||
amount. So remember: two or more spaces.
|
||||
|
||||
---
|
||||
### Unbalanced transactions
|
||||
|
||||
Edit the file to look like this:
|
||||
@ -289,7 +272,6 @@ That makes sense. (It calls them "real" postings because there are some other ki
|
||||
Correct the mistake by adding the minus sign, or just removing the assets amount entirely, and verify
|
||||
that `print` works again.
|
||||
|
||||
---
|
||||
### Record a transaction by editing
|
||||
|
||||
Edit the file again and manually add a second purchase transaction.
|
||||
@ -321,10 +303,9 @@ $ hledger print
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
### Show postings and a running total with "hledger register"
|
||||
|
||||
The [[manual#register|register]] command shows transactions in a different format. More precisely, it shows postings.
|
||||
The [register](manual.html#register) command shows transactions in a different format. More precisely, it shows postings.
|
||||
Remember, a posting is an increase or decrease of some account by some amount, and a transaction contains two or more of them.
|
||||
Run `register` and compare with the output of `print` above. You should see:
|
||||
|
||||
@ -341,7 +322,6 @@ The transaction's date and description is displayed only for the first posting i
|
||||
Next we see the posted account's name and the amount posted.
|
||||
The final column is a running total of the posted amounts.
|
||||
|
||||
---
|
||||
### Show a per-account register report
|
||||
|
||||
Notice how the running total above keeps resetting to 0.
|
||||
@ -368,11 +348,10 @@ $ hledger register assets
|
||||
2014/02/13 forgot the bread assets $-5 $-15
|
||||
```
|
||||
|
||||
---
|
||||
### Query expressions
|
||||
|
||||
The account name argument above is an example of a
|
||||
[[manual#queries|query expression]], a search pattern which restricts a report to a subset of the data.
|
||||
[query expression](manual.html#queries), a search pattern which restricts a report to a subset of the data.
|
||||
In this way you can make very precise queries.
|
||||
|
||||
Note that it is a case-insensitive regular expression which matches anywhere inside the account name.
|
||||
@ -406,10 +385,9 @@ $ hledger register date:2014/2/13- 'es$'
|
||||
Note how the account-matching pattern `es$` needs to be quoted here,
|
||||
because it contains the regular expression metacharacter `$` which would otherwise be interpreted by the unix shell.
|
||||
|
||||
---
|
||||
### Show accounts and their balances with "hledger balance"
|
||||
|
||||
The third of hledger's three core reporting commands is [[manual#balance|balance]].
|
||||
The third of hledger's three core reporting commands is [balance](manual.html#balance).
|
||||
Use it to list all the accounts posted to, and their ending balance.
|
||||
You should see account balances agreeing with the final running total in the register reports above:
|
||||
|
||||
@ -430,7 +408,6 @@ $ hledger balance assets
|
||||
$-15
|
||||
```
|
||||
|
||||
---
|
||||
### balance shows the sum of matched posting amounts
|
||||
|
||||
Here's a balance report based only on the postings dated 2013/2/13:
|
||||
@ -453,8 +430,6 @@ $ hledger register date:2014/2/13
|
||||
assets $-5 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Review
|
||||
|
||||
You have learned:
|
||||
@ -479,8 +454,6 @@ You have learned:
|
||||
|
||||
- how to list accounts and their current balance, or the sum of their postings in some period, with `hledger balance`
|
||||
|
||||
---
|
||||
|
||||
<!--
|
||||
|
||||
### Test yourself
|
||||
@ -502,14 +475,11 @@ You don't need to categorise, you don't need to track anything other than the am
|
||||
Can you complete this challenge ? Keep at it! :)
|
||||
I couldn't do this when I started using hledger, but I can now. Build that muscle.
|
||||
|
||||
---
|
||||
|
||||
-->
|
||||
|
||||
|
||||
## 2. USEFUL ACCOUNTING CONCEPTS
|
||||
## USEFUL ACCOUNTING CONCEPTS
|
||||
|
||||
---
|
||||
### Assets, Liabilities and Equity
|
||||
|
||||
Accounting describes the status of a business, person or other entity at any point in time in terms of three amounts:
|
||||
@ -518,7 +488,7 @@ Accounting describes the status of a business, person or other entity at any poi
|
||||
- **Liabilities** - Things owed
|
||||
- **Equity** - The amount invested by owners/shareholders
|
||||
|
||||
The foundation of double-entry accounting is the [[wp>accounting equation]], which says
|
||||
The foundation of double-entry accounting is the [accounting equation](http://en.wikipedia.org/wiki/accounting_equation), which says
|
||||
that Equity is always equal to Assets minus Liabilities (or, Net Assets).
|
||||
|
||||
This is also written as: Assets = Liabilities + Equity.
|
||||
@ -526,7 +496,6 @@ Another way to say it: what the entity owns is funded either by debt or by the c
|
||||
|
||||
These three are called the Balance Sheet accounts. Their balances summarise the overall financial status at some point in time.
|
||||
|
||||
---
|
||||
|
||||
### Revenue and Expenses
|
||||
|
||||
@ -544,7 +513,6 @@ accumulate during some period of time indicate the inflows and
|
||||
outflows during that period (which will affect the Assets and
|
||||
Liabilities balances).
|
||||
|
||||
---
|
||||
|
||||
### Chart of Accounts
|
||||
|
||||
@ -584,14 +552,17 @@ In some organisations and accounting systems (eg, QuickBooks), the
|
||||
tree structure is de-emphasised, so the above is represented more
|
||||
like:
|
||||
|
||||
^ Account name ^ Account type ^
|
||||
| checking | ASSET |
|
||||
| cash | ASSET |
|
||||
| business income | REVENUE |
|
||||
| gifts received | REVENUE |
|
||||
| food | EXPENSE |
|
||||
| rent | EXPENSE |
|
||||
| supplies | EXPENSE |
|
||||
```
|
||||
Account name Account type
|
||||
-------------------------------
|
||||
checking ASSET
|
||||
cash ASSET
|
||||
business income REVENUE
|
||||
gifts received REVENUE
|
||||
food EXPENSE
|
||||
rent EXPENSE
|
||||
supplies EXPENSE
|
||||
```
|
||||
|
||||
In others, the tree structure is encoded as decimal account numbers, something like this:
|
||||
|
||||
@ -610,7 +581,6 @@ In others, the tree structure is encoded as decimal account numbers, something l
|
||||
5300 supplies
|
||||
```
|
||||
|
||||
---
|
||||
### Subaccounts in hledger
|
||||
|
||||
With hledger, tree structure is implied by writing account names like `ACCOUNT:SUBACCOUNT`.
|
||||
@ -679,7 +649,6 @@ $ hledger balance --depth 1
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user