slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: static site uses hakyll(-std) again, import wiki content

Browse Source
This commit is contained in:
Simon Michael 2014-11-04 21:18:13 -08:00
parent b045d6b530
commit c92b6520ea
15 changed files with 2700 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/site/developer-guide.md Symbolic link
View File

@ -0,0 +1 @@
../developer-guide.md

31
doc/site/download.md Normal file
View File

@ -0,0 +1,31 @@
# 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).
Building, testing and supporting cross-platform 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 }}]]

215
doc/site/faq.md Normal file
View File

@ -0,0 +1,215 @@
# Frequently asked questions
## hledger and ledger
### How does hledger relate to ledger ?
hledger was inspired by and is partly a clone of John Wiegley's [ledger](http://ledger-cli.org),
specifically Ledger 3.
I was a happy ledger user and contributor for some time; I still use it
occasionally. I wrote hledger because I wanted to develop financial tools
in the Haskell programming language and ecosystem, whose advantages I
believe are compelling. I have also tried to make hledger a little more
simple, usable, installable, documented, appealing to collaborators, and
to provide alternate user interfaces to make it more widely useful.
ledger has more advanced power-user features on the command-line
(periodic and modifier transactions, budgets, capital gains tracking,
value expressions, custom output formats, etc.) and it remains faster
and more memory efficient (for now!)...
hledger builds faster and has an up-to-date manual and an optional web
interface (which often works on ledger files too)...
The two projects collaborate freely. We share the
[#ledger](irc://irc.freenode.net/#ledger) IRC channel but have
separate mail lists
([hledger list](http://groups.google.com/group/hledger/),
[ledger-cli list](http://groups.google.com/group/ledger-cli/)). I try
to give back by providing infrastructure
([ledger-cli.org](http://ledger-cli.org)) and IRC support.
hledger stays compatible with ledger wherever possible, so that you
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).
### And ledger 4 ?
There is also a [[https://github.com/ledger/ledger4|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.
### File format differences ?
hledger's file format is mostly identical with ledger's, by design.
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]]).
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]].
### Feature differences ?
hledger mimics a subset of [ledger 3.x](http://ledger-cli.org), and adds some features of its own.
We currently support:
- ledger's journal format, mostly
- csv format
- timelog format
- regular journal transactions
- multiple commodities
- fixed prices
- virtual postings
- print, register & balance commands
- filtering by many criteria, with different query syntax
- display expressions containing just a simple date predicate
- some basic output formatting
We do not support:
- automated transactions
- value expressions
- fluctuating prices and historical price records
- display formats other than `d>[DATE]` or similar
- budget reports
And we add these commands:
- add
- balancesheet
- cashflow
- chart
- incomestatement
- irr
- interest
- vty
- web
### Option/command differences ?
ledger options and commands not supported include:
```
Basic options:
-o, --output FILE write output to FILE
-i, --init-file FILE initialize ledger using FILE (default: ~/.ledgerrc)
-a, --account NAME use NAME for the default account (useful with QIF)
Report filtering:
-c, --current show only current and past entries (not future)
--period-sort EXPR sort each report period's entries by EXPR
-L, --actual consider only actual (non-automated) transactions
--budget generate budget entries based on periodic entries
--add-budget show all transactions plus the budget
--unbudgeted show only unbudgeted transactions
--forecast EXPR generate forecast entries while EXPR is true
-l, --limit EXPR calculate only transactions matching EXPR
-t, --amount EXPR use EXPR to calculate the displayed amount
-T, --total EXPR use EXPR to calculate the displayed total
Output customization:
-n, --collapse Only show totals in the top-most accounts.
-P, --by-payee show summarized totals by payee
-x, --comm-as-payee set commodity name as the payee, for reporting
--dow show a days-of-the-week report
-S, --sort EXPR sort report according to the value expression EXPR
--head COUNT show only the first COUNT entries (negative inverts)
--tail COUNT show only the last COUNT entries (negative inverts)
--pager PAGER send all output through the given PAGER program
-A, --average report average transaction amount
-D, --deviation report deviation from the average
-%, --percentage report balance totals as a percentile of the parent
--totals in the "xml" report, include running total
-j, --amount-data print only raw amount data (useful for scripting)
-J, --total-data print only raw total data
-y, --date-format STR use STR as the date format (default: %Y/%m/%d)
--balance-format --register-format --print-format
--plot-amount-format --plot-total-format --equity-format
--prices-format --wide-register-format
Commodity reporting:
--price-db FILE sets the price database to FILE (def: ~/.pricedb)
-L, --price-exp MINS download quotes only if newer than MINS (def: 1440)
-Q, --download download price information when needed
-O, --quantity report commodity totals (this is the default)
-V, --market report last known market value
-g, --performance report gain/loss for each displayed transaction
-G, --gain report net gain/loss
Commands:
xml [REGEXP]... print matching entries in XML format
equity [REGEXP]... output equity entries for matching accounts
prices [REGEXP]... display price history for matching commodities
entry DATE PAYEE AMT output a derived entry, based on the arguments
```
### Other functionality differences ?
- hledger recognises description and negative patterns by "desc:"
and "not:" prefixes, unlike ledger 3's free-form parser
- hledger does not require a space between command-line flags and their values,
eg `-fFILE` works as well as `-f FILE`
- hledger's weekly reporting intervals always start on mondays
- hledger shows start and end dates of the intervals requested,
not just the span containing data
- hledger always shows timelog balances in hours
- hledger splits multi-day timelog sessions at midnight by default (Ledger does this with an option)
- hledger doesn't track the value of commodities with varying
price; prices are fixed as of the transaction date
- hledger's output follows the decimal point character, digit grouping,
and digit group separator character used in the journal.
- hledger print shows amounts for all postings, and shows unit prices for
amounts which have them. (This means that it does not currently print
multi-commodity transactions in valid journal format.)
- hledger print ignores the --date2 flag, always showing both dates.
ledger print shows only the secondary date with --aux-date, but not
vice versa.
- hledger's default commodity directive (D) sets the commodity to be
used for subsequent commodityless amounts, and also sets that
commodity's display settings if such an amount is the first
seen. ledger uses D only for commodity display settings and for the
entry command.
- 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
shell glob patterns (eg `include *.journal` ), which ledger does.
- 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
order (and uses whichever appears first). hledger requires the fixed
lot price to come last (and ignores it).
### Implementation differences ?
ledger is written in C++, whereas hledger is written in [Haskell](http://haskell.org).
Haskell is a highly regarded up-and-coming programming language that enables
a coding style known as pure functional programming, offering the
promise of more bug-free and maintainable software built in fewer
lines of code. Haskell also provides a more abstracted, portable
platform which can make deployment and installation easier in some
cases.

53
doc/site/how-to-read-csv-files.md Normal file
View File

@ -0,0 +1,53 @@
# How to read CSV files
Here's a quick example of [[manual#csv-files|converting a CSV file]].
Say we have downloaded `checking.csv` from a bank for the first time:
"Date","Note","Amount"
"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:
# skip the first CSV line (headings)
skip 1
# use the first three fields in each CSV record as transaction date, description and amount respectively
fields date, description, amount
# prepend $ to CSV amounts
currency $
# always set the first account to assets:bank:checking
account1 assets:bank:checking
# if the CSV record contains ‘SAVINGS’, set the second account to assets:bank:savings
# (if not set, it will be expenses:unknown or income:unknown)
if ~ SAVINGS
account2 assets:bank:savings
Now hledger can read this CSV file as journal data:
$ hledger -f checking.csv print
using conversion rules file checking.csv.rules
2012/03/22 DEPOSIT
income:unknown $-50.00
assets:bank:checking $50.00
2012/03/23 TRANSFER TO SAVINGS
assets:bank:savings $10.00
assets:bank:checking $-10.00
We might save this output as `checking.journal`, and/or merge it (manually) into the main journal file.
We could also run other commands:
$ hledger -f checking.csv balance
using conversion rules file checking.csv.rules
$50.00 assets:bank
$40.00 checking
$10.00 savings
$-50.00 income:unknown
--------------------
0

48
doc/site/how-to-use-account-aliases.md Normal file
View File

@ -0,0 +1,48 @@
# How to use account aliases
Here's an example of using [[manual#account-aliases|account aliases]].
Say a sole proprietor has a `personal.journal`:
2014/1/2
expenses:food $1
assets:cash
and a `business.journal`:
2014/1/1
expenses:office supplies $1
assets:business checking
So each entity (the business owner, and the business) has their own file with its own simple chart of accounts.
However, at tax reporting time we need to view these as a single entity (at least in the US).
In `unified.journal`, we include both files, and rewrite the personal
account names to fit into the business chart of accounts,
alias expenses = equity:draw:personal
alias assets:cash = assets:personal cash
include personal.journal
end aliases
include business.journal
Now we can see the data from both files at once, and the personal account names have changed:
$ hledger -f unified.journal print
2014/01/01 # from business.journal - no aliases applied
expenses:office supplies $1
assets:business checking $-1
2014/01/02 # from personal.journal
equity:draw:personal:food $1 # <- was expenses:food
assets:personal cash $-1 # <- was assets:cash
You can also specify aliases on the command line. This could be useful to
quickly rewrite account names when sharing a report with someone else, such as
your accountant:
$ hledger --alias 'my earning=income:business' ...
Note that
journal directive aliases are applied first, then command-line aliases,
and at most one of each will be applied to each account name.

33
doc/site/index.md Normal file
View File

@ -0,0 +1,33 @@
# hledger
## lightweight, portable, dependable accounting tools
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)
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
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.
<!-- 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) -->
<!-- Also testimonials, examples, blogging, packaging, and patches. -->

263
doc/site/installing.md Normal file
View File

@ -0,0 +1,263 @@
# Installation Guide
- [[#How to install]]
- [[#Troubleshooting]]
## How to install
hledger works on GNU/linux, mac and windows.
Here are several ways to install it:
### a. With your system package manager
If you have a system package manager that includes hledger,
this will be the quickest and easiest way to install,
if you don't need the very latest version.
^ On distro/packaging system: ^ Run: ^
| Debian & Ubuntu: | `apt-get install hledger [hledger-web]` |
| Red Hat, Fedora & CentOS (?): | `yum install hledger` |
| NixOS: | `nix-env -iA nixpkgs.haskellPackages.hledger` |
### b. Download binaries from hledger.org
Ready-to-run [[download|downloads]] for GNU/Linux, Mac OSX, and
Microsoft Windows are provided on a donation basis. These have not
been updated recently, but you can fix that by making a donation of
any size (see the page for more).
These are simple compressed executables (not installers), so after downloading
you may need to decompress, adjust permissions, and rename the file. Eg:
$ gunzip hledger-web-0.18.2-mac-x86_64.gz
$ chmod +x hledger-web-0.18.2-mac-x86_64
$ mv hledger-web-0.18.2-mac-x86_64 /usr/local/bin/hledger-web
$ /usr/local/bin/hledger-web --version
### c. Build released source from Hackage
You can download and build the latest release yourself using [cabal](http://www.haskell.org/cabal/users-guide/),
the standard installer for Haskell software.
This is the most common way to install hledger, but not always the easiest;
use the troubleshooting tips below if needed.
Ensure you have [GHC](http://haskell.org/ghc) or
the [Haskell Platform](http://haskell.org/platform) installed.
hledger requires GHC 7.2 or greater, and hledger-web requires GHC 7.4 or greater.
Also note that some Haskell packages depend on C packages, and cabal
currently isn't able to install or identify those for you. A common
issue is not having all the ncurses C libraries installed. A quick way
to ensure you have all required C libs is to
[install hledger once with your system package manager](#install-with-your-system-package-manager)
before installing the latest version with cabal.
Then install the hledger command-line tool:
$ cabal update
$ cabal install hledger [--dry-run]
$ hledger --version
You should see the proper version reported.
If you get "could not resolve dependencies", "hledger not found",
or any other problem, see [troubleshooting](#troubleshooting).
Also note, to use non-ascii characters like £ in your data, you might need to [configure a suitable locale](MANUAL.html#locale).
#### Installing hledger-web
To also install the web interface, in theory just do:
$ cabal install hledger-web
In practice, this is a real beast to keep working, so as of 2014/4/17 it's best to do it this way:
$ cabal sandbox init # start with a clean cabal package db, requires cabal 1.18
$ cabal update
$ cabal install -j alex happy # update to alex 3.1 and happy 1.19
$ cabal install -j hledger-web # don't cabal install hledger first
This installs hledger and hledger-web. hledger-web will appear as the `web` command in hledger's commands list.
There are other [[start#add-on-commands|add-on packages]], hopefully compatible with the current hledger release and your platform.
### d. Build latest source from git
To download and build the latest development version of hledger, ensure you have
[git](http://git-scm.com) installed, then:
$ git clone http://github.com/simonmichael/hledger.git
$ cd hledger
$ cabal update
$ [optional: cabal sandbox init]
$ cabal install ./hledger-lib ./hledger [./hledger-web]
The same [notes above](#install-from-hackage-with-cabal) about requirements and checking your installation apply. Note this time we mention `cabal sandbox`, a feature of cabal 1.18+ which can be used to reduce package dependency problems; it can be used when installing from Hackage as well.
## Troubleshooting
There are a lot of ways things can go wrong, especially if you are building from source.
Here are some known issues and things to try. Please also seek
[support](DEVELOPMENT.html#support) from the
[IRC channel](irc://irc.freenode.net/#ledger),
[mail list](http://hledger.org/list) or
[bug tracker](http://hledger.org/bugs).
Starting from the top, consider whether each of these might apply to
you. Tip: blindly reinstalling/upgrading everything in sight probably
won't work, it's better to go in small steps and understand the problem,
or get help.
### hledger not found ?
If cabal install succeeded but you get a message like "hledger not found" when you run hledger,
you should add cabal's bin directory to your PATH environment variable.
Eg on unix-like systems, something like:
```
$ echo 'export PATH=$PATH:~/cabal/bin' >> ~/.bash_profile
$ source ~/.bash_profile
```
On Ubuntu 14.04:
```
$ echo 'export PATH=~/.cabal/bin:$PATH' >> ~/.bashrc
$ source ~/.bashrc
```
Test your PATH-variable with:
```
$ $PATH
```
### hledger --version shows wrong version ?
Perhaps you have multiple versions of hledger in your PATH. Eg you installed with the system package manager
(to get C libs) and then with cabal (to get the latest version), but cabal's bin directory appears too late
in the PATH. Move it closer to the front.
### Did you cabal update ?
If not, `cabal update` and try again.
### Do you have a new enough version of GHC ?
Run `ghc --version`. hledger requires GHC 7.0 or greater
(and on [some platforms](#5551), 7.2.1+ can be helpful).
### Do you have a new enough version of cabal ?
Avoid ancient versions, which are less capable and more confusing.
`cabal --version` should ideally report at least 1.16 (or if you want to
do sandboxed installs, 1.18). You may be able to upgrade it with:
```
$ cabal update
$ cabal install cabal-install
```
### haskeline fails to install, requires Cabal >=1.16
Related to the above. haskeline, one of hledger's dependencies, claims
to require cabal-install version 1.16+, which is a problem if, say,
you are on Debian Wheezy and only have cabal-install version 0.14.
You can relax haskeline's version constraint like so:
```
cabal unpack haskeline
cd haskeline-X.Y
(edit haskeline.cabal, comment out the `Cabal-Version: >=1.16` line)
cabal install
(resume installing hledger)
```
### Are your installed GHC/cabal packages in good repair ?
Run `ghc-pkg check`. If it reports problems, some of your packages have
become inconsistent, and you should fix these first.
[ghc-pkg-clean](https://gist.github.com/1185421) is an easy way.
### cabal says "rejecting: system-fileio-0.3.11, 0.3.10 (conflict: blah blah blah.."
system-fileio does not yet allow text 1.x, making cabal sweat.
If your cabal is modern enough, adding `--max-backjumps=10000` should help.
([more](https://groups.google.com/d/topic/hledger/FdWGTSAVzYU/discussion)).
### cabal can't satisfy the new dependencies due to old installed packages
Cabal dependency failures become more likely as you install more
packages over time. If `cabal install hledger-web --dry` says it can't
satisfy dependencies, you have this problem. You can:
- (a) try to understand which packages to remove (with `ghc-pkg unregister`)
or which constraints to add (with `--constraint 'PKG == ...'`) to help cabal
find a solution
- (b) install into a fresh cabal sandbox, created with `cabal sandbox init`.
([virthualenv](http://hackage.haskell.org/package/virthualenv) or
[cabal-dev](http://hackage.haskell.org/package/cabal-dev) also work).
- or (c<!-- -->) (easiest) erase your installed packages with
[ghc-pkg-reset](https://gist.github.com/1185421) and try again.
For more detail, see [How to cabal install](https://www.fpcomplete.com/user/simonmichael/how-to-cabal-install).
### Dependency or compilation error in one of the new packages ?
If cabal starts downloading and building packages and then terminates
with an error, look at the output carefully and identify the problem
package(s). If necessary, add `-v2` or `-v3` for more verbose
output. You can install the new packages one at a time to troubleshoot,
but remember cabal is smarter when installing all packages at once.
Often the problem is that you need to install a particular C library
using your platform's package management system. Or the dependencies
specified on a package may need updating. Or there may be a compilation
error. If you find an error in a hledger package, check the
[recent commits](http://github.com/simonmichael/hledger/commits) to
see if the [latest development version](#installing) might have a fix.
### ExitFailure 11
See
[http://hackage.haskell.org/trac/hackage/ticket/777](http://hackage.haskell.org/trac/hackage/ticket/777).
This means that a build process has been killed, usually because it grew
too large. This is common on memory-limited VPS's and with GHC 7.4.1.
Look for some memory-hogging processes you can kill, increase your RAM,
or limit GHC's heap size by doing `cabal install ... --ghc-options='+RTS
-M400m'` (400 megabytes works well on my 1G VPS, adjust up or down..)
### Can't load .so/.DLL for: ncursesw (/usr/lib/libncursesw.so: file too short)
(or similar): cf [GHC bug #5551](http://hackage.haskell.org/trac/ghc/ticket/5551).
Upgrade GHC to 7.2.1, or try your luck with [this workaround](http://eclipsefp.github.com/faq.html).
### Undefined iconv symbols on OS X
This kind of error:
Linking dist/build/hledger/hledger ...
Undefined symbols:
"_iconv_close", referenced from:
_hs_iconv_close in libHSbase-4.2.0.2.a(iconv.o)
"_iconv", referenced from:
_hs_iconv in libHSbase-4.2.0.2.a(iconv.o)
"_iconv_open", referenced from:
_hs_iconv_open in libHSbase-4.2.0.2.a(iconv.o)
probably means you are on a mac with macports libraries installed, cf
[http://hackage.haskell.org/trac/ghc/ticket/4068](http://hackage.haskell.org/trac/ghc/ticket/4068).
To work around temporarily, add this --extra-lib-dirs flag:
$ cabal install hledger --extra-lib-dirs=/usr/lib
or permanently, add this to ~/.cabal/config:
extra-lib-dirs: /usr/lib
### "invalid preprocessing directive" on OS X
> "I'm trying to cabal install hledger-web on OS X, GHC 7.6, and getting error: invalid preprocessing directive #{mixedAmountAsHtml amt}".
[Example](https://gist.github.com/miikka/8886233)
Certain OS X and GHC versions do not work well together ([cabal #1496](https://github.com/haskell/cabal/issues/1496), [ghc #7678](https://ghc.haskell.org/trac/ghc/ticket/7678)).
There's a fix for this in hledger HEAD as of 2014/2/8 (it's not in 0.22.1).
If you find more cases, please report it.
### Many warnings about "missing terminating ' character" on OS X
Related to the above problem, can be ignored.
### hledger-vty requires curses-related libraries
On Ubuntu, eg, you'll need the `libncurses5-dev` package. On Windows,
these are not available (unless perhaps via Cygwin.)
### hledger-chart requires GTK-related libraries
On Ubuntu, eg, install the `libghc6-gtk-dev` package. See also [Gtk2Hs installation notes](http://code.haskell.org/gtk2hs/INSTALL).
### error based on missing ncurses C libs on Ubuntu 14.04 trusty
The following solved my dependency-problem with ncurses (this was required even when I had installed hledger 0.22 via apt-get)
sudo apt-get install libghc-hscurses-dev libghc-ncurses-dev

5
doc/site/ledgertips.md Normal file
View File

@ -0,0 +1,5 @@
{{https://pbs.twimg.com/profile_images/455396161352781824/efsKSkXH_bigger.png |}}
[[https://twitter.com/LedgerTips|@LedgerTips]] on twitter.com posts tips and tricks for all the [[https://github.com/ledger/ledger/wiki/Ports|Ledger ports and work-alikes]], in the spirit of [[https://twitter.com/HaskellTips|HaskellTips]].
All *ledger users are invited to post tips! Contact Simon (sm) on #ledger with suggestions, or to get login details to become a guest host.
Posts should include the `#ledgercli` hash tag. Links to longer tips are also welcome.

1
doc/site/manual.md Symbolic link
View File

@ -0,0 +1 @@
../manual.md

108
doc/site/more-docs.md Normal file
View File

@ -0,0 +1,108 @@
# More docs...
[[old screenshots|Screenshots]] (old)
## How-tos
- [[How to read CSV files]]
- [[How to use account aliases]]
## Blog posts & articles
- Simon's hledger-tagged blog posts:
[Introducing hledger!](http://joyful.com/blog/2013-10-18-introducing-hledger.html),
[More on ledger](http://joyful.com/blog/2013-10-19-more-on-ledger.html),
[What is hledger ?](http://joyful.com/blog/2013-10-20-what-is-hledger.html),
[more...](http://joyful.com/tags/hledger.html) 2013-
- [Joey Hess: hledger](http://joeyh.name/blog/entry/hledger) 2012
- [Magnus Henoch: monspuraj programoj](http://חנוך.se/diary/monspuraj_programoj/index.eo.html) ([english](http://translate.google.com/translate?hl=en&sl=eo&u=http://xn--9dbdkw.se/diary/monspuraj_programoj/index.eo.html)) 2012
- [Sascha Welter: Doing my own accounting](http://betabug.ch/blogs/ch-athens/1221) 2011
- [Clint Adams: Accounting at SFLC](http://www.softwarefreedom.org/blog/2011/sep/07/accounting-at-sflc/) 2011
- [Christine Spang: [h]ledger rocks my world](http://blog.spang.cc/posts/hledger_rocks_my_world/) 2010
- [Roman Cheplyaka: hledger](http://ro-che.blogspot.com/2010/02/hledger.html) 2010
- [Fabrice Niessen on Ledger, hledger, beancount, CSV2Ledger](http://www.mygooglest.com/fni/ledger.html) 2010
- [советы: Ledger — бухучёт в командной строке](http://s.arboreus.com/2009/05/personal-accounting-in-command-line.html) ([english](http://translate.google.com/translate?hl=en&sl=ru&u=http://s.arboreus.com/2009/05/personal-accounting-in-command-line.html)) 2009
## Related info
John Wiegley's [Ledger](http://www.ledger-cli.org/) inspired hledger.
Here are some good intros, which also serve as a good orientation for hledger:
- [Ledger CLI Accounting for Geeks](http://blog.loadingdata.nl/accounting-for-geeks/#/) slides by Daniël Bos, 2014
(press space to advance)
- [ledger basics and habits](http://matthewturland.com/2014/03/29/ledger-basics-and-habits/) blog post by Matthew Turland, 2014
- [Hacking Your Finances for Fun and Profit](http://matthewturland.com/slides/ledger-stats/) slides by Matthew Turland, 2013
- [The accounting quest: Ledger](http://lwn.net/Articles/501681/) LWN.net, 2012
- [Ledger: Command-line double-entry accounting](https://news.ycombinator.com/item?id=872244) Hacker News discussion, 2009
- [Ledger's informative manual](http://ledger-cli.org/3.0/doc/ledger3.html),
and the [Ledger wiki](http://wiki.ledger-cli.org)
- [Non-Profit Accounting With Ledger CLI, A Tutorial](https://gitorious.org/ledger/npo-ledger-cli/source/npo-ledger-cli-tutorial.md)
describes Software Freedom Conservancy's setup, 2013
See also the two Twitter feeds:
- [@LedgerTips](https://twitter.com/LedgerTips) 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]]
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
[So, you want to learn Bookkeeping!](http://www.dwmbeancounter.com/tutorial/Tutorial.html).
This has been recommended on the ledger list.
- [Accounting Basics](http://www.accountingverse.com/accounting-basics/)
- [Guru 99 Accounting Tutorials](http://www.guru99.com/accounting.html)
- [principlesofaccounting.com](http://www.principlesofaccounting.com)
- [Double Entry Bookkeeping](http://c2.com/cgi/wiki?DoubleEntryBookkeeping) discussion by software developers at the WikiWikiWeb
- [The Vanished Grandeur of Accounting](http://www.bostonglobe.com/ideas/2014/06/07/the-vanished-grandeur-accounting/3zcbRBoPDNIryWyNYNMvbO/story.html) (Boston Globe) & [discussion](https://news.ycombinator.com/item?id=7933746)
- [Winning Financially is Simple](http://directory.libsyn.com/episode/index/show/youneedabudget/id/2657122) and other good episodes from the [YNAB Podcast](http://directory.libsyn.com/shows/view/id/youneedabudget)
- [Back to the Stone Age: Low-Tech Expense Tracking](http://www.getrichslowly.org/blog/2011/02/28/back-to-the-stone-age-low-tech-expense-tracking/) Get Rich Slowly
- [Track Every Penny You Spend](http://www.getrichslowly.org/blog/2006/09/22/track-every-penny-you-spend/) Get Rich Slowly
- [I’ve Tracked My Expenses — Now What?](http://www.getrichslowly.org/blog/2011/04/08/ask-the-readers-ive-tracked-my-expenses-now-what/) Get Rich Slowly
- [A Slow-Tech Approach to Tracking Spending](http://mobile.nytimes.com/2014/05/12/your-money/household-budgeting/a-slow-tech-approach-to-tracking-spending.html)
- [Your Financial Network Map](http://www.bargaineering.com/articles/financial-network-map.html)
- [The Accountancy Model and The Accountancy Model Examples](http://timriley.net/appahost/accountancy_model.html) - two free books by Tim Riley
- [Gnucash and double entry accounting](http://www.austintek.com/gnucash/ncsa-gnucash-talk.html) - double entry accounting introduction with examples
- [Accounting for Computer Scientists](http://martin.kleppmann.com/2011/03/07/accounting-for-computer-scientists.html)
- [Closing Entries](http://www.cliffsnotes.com/more-subjects/accounting/accounting-principles-i/completion-of-the-accounting-cycle/closing-entries)
- [Tutorial on multiple currency accounting](http://www.mscs.dal.ca/~selinger/accounting/tutorial.html) by Peter Selinger
## hledger add-ons
- [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
- [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/]]
## 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/]]
## Similar projects
In addition to hledger and Ledger, there are other [[ledgerwiki>Ports|Ledger 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)
- dimonf's [ledger.pl](https://github.com/dimonf/ledger.pl) (perl)
- Omari Norman's [penny](https://github.com/massysett/penny) (haskell)
- Uwe Hollerbach's [umm](http://hackage.haskell.org/package/UMM) (haskell)
Other things of interest:
- [bill](http://darcsden.com/alex/bill), [bill-atomo](http://darcsden.com/alex/bill-atomo) - small time-tracking and billing app
- [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

50
doc/site/old-screenshots.md Normal file
View File

@ -0,0 +1,50 @@
# Old screenshots
---
## Basic command-line reports
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.
{{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.
{{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]].
{{http://hledger.org/images/hledger-web-journal.png|The web interface (hledger 0.11pre with -fwebyesod).}}
<!--
```
zooming version (requires HTML)
Click to enlarge, or mouse over for captions..
<style>
.highslide img {height:90px;}
.highslide-caption {color:white; background-color:black;}
</style>
<a name="hledger-screen-1" href="images/hledger-screen-1.png" class="highslide" onclick="return hs.expand(this)">
<img src="images/hledger-screen-1.png" title="Basic command-line reports, like ledger" /></a>
```
-->

1129
doc/site/release-notes.md Normal file
View File

File diff suppressed because it is too large Load Diff

36
doc/site/sidebar.md Normal file
View File

@ -0,0 +1,36 @@
~~NOCACHE~~
[[Home]]
[[Download]]
[[Release Notes]]
[[step-by-step|Tutorial]]
[[Manual]]
[[Developer Guide]]
[[FAQ]]
[[More docs]]
---
[Code](http://hledger.org/code)
[Bug tracker](http://hledger.org/bugs) &
[trello](http://hledger.org/trello)
[Mail list](http://hledger.org/list)
[#hledger IRC](http://hledger.org/irc)
(also [#ledger](http://webchat.freenode.net?channels=ledger&randomnick=1))
[[https://twitter.com/LedgerTips|@LedgerTips]],
[#ledgercli](https://twitter.com/search?q=%23ledgercli&src=typd&f=realtime)
(Twitter)
<!-- [web ui demo](http://demo.hledger.org/) -->
<!-- [web ui demo](http://demo.hledger.org/register?q=inacct%3Aassets%3Abank%3Achecking+sym%3A\%24) -->

32
doc/site/site.tmpl Normal file
View File

@ -0,0 +1,32 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>$title$</title>
<link href="/css/site.css" rel="stylesheet">
<style>
body { max-width:50em; margin:auto; color:black; background-color:#eee; }
ul.nav { padding-left:0; text-align:right; }
.nav li { display:inline; margin-right:1em; }
</style>
</head>
<body>
<ul class="nav">
<li><a href="index.html">Home</a>
<li><a href="download.html">Download</a>
<li><a href="release-notes.html">Release Notes</a>
<li><a href="step-by-step.html">Tutorial</a>
<li><a href="manual.html">Manual</a>
<li><a href="developer-guide.html">Developer Guide</a>
<li><a href="faq.html">FAQ</a>
<li><a href="more-docs.html">More docs</a>
</ul>
$body$
<em>2014/11/4: The site is going through some changes, for now please enjoy the old-school styling.</em>
</body>
</html>

695
doc/site/step-by-step.md Normal file
View File

@ -0,0 +1,695 @@
# hledger Step by Step (draft)
*(c) Simon Michael, 2014*
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]]
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).
You'll need:
1. hledger, installed using the [[installing|Installation Guide]]. These exercises were last tested with: hledger 0.23dev-20140212.
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.
---
## 0. SETUP
---
### Check your hledger
Get a command prompt, and run hledger to check the version. It should be reasonably [[release-notes|up to date]].:
```
$ hledger --version
hledger 0.23
```
---
## 1. 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.
You should see something like:
```
$ hledger stats
The hledger journal file "/home/YOU/.hledger.journal" was not found.
Please create it first, eg with "hledger add" or a text editor.
Or, specify an existing journal file with -f or LEDGER_FILE.
```
Most hledger commands read this file but can not change it; the `add` and `web` commands can also write it.
(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,
an imaginary purchase at the supermarket.
We'll go through this in detail. Later you'll learn other ways to enter data.
```
$ hledger add
Adding transactions to journal file /home/YOU/.hledger.journal
Provide field values at the prompts, or press enter to accept defaults.
Use readline keys to edit, use tab key to complete account names.
A code (in parentheses) may be entered following transaction dates.
A comment may be entered following descriptions or amounts.
If you make a mistake, enter < at any prompt to restart the transaction.
To complete a transaction, enter . when prompted.
To quit, press control-d or control-c.
Starting a new transaction.
date ? [2014/02/12]:
```
`add` prompts for each transaction field. The first is the date.
The value in square brackets is the suggested default (today's date). Press enter to accept it.
```
description ? : trip to the supermarket
```
Transactions have an optional description (a single line of text) to help you understand them.
You can describe the transaction here, or put a payee name, or leave it blank.
Type `trip to the supermarket` and press enter.
```
account 1 ? : expenses
```
Transactions have two or more accounts. Keep it simple; just enter `expenses` for the first one.
If you're thinking "expenses sounds more like a category": it is, but double entry accounting calls those "accounts", too.
A purchase is a transfer of money from an asset account to an expense account.
An asset is something you own, like some money in a bank account or in your pocket.
Once the money has been "moved" to an expense, you no longer own it, but the increasing balance in the expense account reminds you where it went.
```
amount 1 ? : $10
```
The amount being "moved" to `expenses`. In this case 10 US dollars.
```
account 2 ? : assets
```
Next, specify which account the money comes from. Just say `assets`.
```
amount 2 ? [$-10.0]:
```
Now you're asked for the amount to "move" to or from the `assets` account.
As the default, hledger offers the amount required to "balance" the postings entered so far.
The minus sign indicates the money is moving from this account.
(hledger uses positive and negative sign instead of accounting's traditional "debit" and "credit" terminology.)
In a balanced transaction, the sum of posted amounts is zero, in other words no money disappears into thin air.
hledger does not allow unbalanced transactions.
Press enter to accept the default. It has an extra decimal place, but never mind.
```
account 3 (or . to complete this transaction) ? : .
```
Type `.` (period) and press enter.
```
Transaction entered:
2014/02/12 trip to the supermarket
expenses $10
assets $-10.0
Accept this transaction ? [y]:
```
You are given a chance to review the transaction just entered.
Here you see hledger's plain text data format for journal entries:
a non-indented YYYY/MM/DD date, space, and description,
followed by two or more indented posting lines, each containing an account name,
two or more spaces, and an amount.
(Account names can contain spaces, so at least two spaces are needed to separate them from the amount.)
Press enter.
```
Added to the journal.
Starting a new transaction.
date ? [2014/02/12]: <CTRL-D>
$
```
hledger has saved it to the journal file and is ready for the next
entry. Press control-d (on Windows, control-c) once to exit.
`stats` should now report that your journal exists and contains one transaction:
```
$ hledger stats
Main journal file : /home/YOU/.hledger.journal
Included journal files :
Transactions span : 2014-02-12 to 2014-02-13 (1 days)
Last transaction : 2014-02-12 (0 days ago)
Transactions : 1 (1.0 per day)
Transactions last 30 days: 1 (0.0 per day)
Transactions last 7 days : 1 (0.1 per day)
Payees/descriptions : 1
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.
Since there's just one so far, you should see:
```
$ hledger print
2014/02/12 trip to the supermarket
expenses $10
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`):
```
$ ls -l ~/.hledger.journal
-rw-rw-r-- 1 YOU YOU 74 Feb 12 08:10 /home/YOU/.hledger.journal
$ cat ~/.hledger.journal
2014/02/12 trip to the supermarket
expenses $10
assets
```
---
### A convenience: inferred amounts
Why is the amount missing from the assets posting above ?
As a convenience to make manual data entry easier, if one amount is missing
hledger infers it so as to balance the transaction ($-10 in this case).
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.
Edit the file and change it to test whether two missing amounts is reported as an error. Eg:
```
$ emacs ~/.hledger.journal
```
Remove the expenses amount and save the file. It now looks like this:
```
2014/02/12 trip to the supermarket
expenses
assets
```
Running `print` again, you should see:
```
$ hledger print
hledger: could not balance this transaction (can't have more than one missing amount; remember to put 2 or more spaces before amounts)
2014/02/12 trip to the supermarket
expenses
assets
```
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)`".
Another cause of this error is forgetting to put two spaces before the
amount, like this:
```
2014/02/12 trip to the supermarket
expenses $10 ; <- only one space between expenses and $10 - need at least two
assets
```
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:
```
2014/02/12 trip to the supermarket
expenses $10
assets $10
```
Here, we wrote both posting amounts but got the sign wrong on one of them, so they don't add up to zero.
hledger should detect this mistake. Verify it by running some command, eg `print`. You should see:
```
$ hledger print
hledger: could not balance this transaction (real postings are off by $20)
2014/02/12 trip to the supermarket
expenses $10
assets $10
```
That makes sense. (It calls them "real" postings because there are some other kinds of posting you haven't learned about yet; they aren't important.)
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.
It's often quickest to copy & paste a similar entry, then change it.
Make the file look like this:
```
2014/02/12 trip to the supermarket
expenses $10
assets
2014/02/13 forgot the bread
expenses $5
assets
```
The blank line between transactions is customary, though not required.
Test your work with `print`. You should see:
```
$ hledger print
2014/02/12 trip to the supermarket
expenses $10
assets $-10
2014/02/13 forgot the bread
expenses $5
assets $-5
```
---
### 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.
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:
```
$ hledger register
2014/02/12 trip to the super.. expenses $10 $10
assets $-10 0
2014/02/13 forgot the bread expenses $5 $5
assets $-5 0
```
Postings are displayed one per line.
The transaction's date and description is displayed only for the first posting in each transaction.
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.
This makes sense (since we know each transaction's postings add up to zero) but isn't very useful.
The register report is more useful when we restrict it to a subset of postings -
say, only the postings within a single account.
You can do this by specifying the account name as a command line argument.
Run a register report for the `expenses` account. You should see:
```
$ hledger register expenses
2014/02/12 trip to the super.. expenses $10 $10
2014/02/13 forgot the bread expenses $5 $15
```
Now it's clear that your `expenses` balance - ie, the total amount spent - has increased to $15.
Your `assets` balance should have dropped accordingly. Check it:
```
$ hledger register assets
2014/02/12 trip to the super.. assets $-10 $-10
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.
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.
So "`e`" would match both `expenses` and `assets`.
And if you had an account named `other assets`, "`assets`" would also match that, so to match only the `assets`
account you'd need a more precise pattern like "`^assets$`".
If this doesn't make sense, read a little about regular expressions.
In a regular expression `^` means "match at the beginning" and `$` means "match at the end".
Multiple query arguments are ANDed and ORed together in a fixed way - follow the link for details.
Basically queries on the same field are ORed, and queries on different fields are ANDed.
Run the following examples and make sure they make sense, consulting the manual as needed.
Show only transactions whose description contains the regular expression "`bread`":
```
$ hledger print desc:bread
2014/02/13 forgot the bread
expenses $5
assets $-5
```
Show only postings on or after a certain date to an account whose name ends with "es":
```
$ hledger register date:2014/2/13- 'es$'
2014/02/13 forgot the bread expenses $5 $5
```
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]].
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:
```
$-15 assets
$15 expenses
--------------------
0
```
The overall total of these balances is also shown. As with other reports, you can use a query expression to select a subset of the data to report on.
Eg:
```
$ hledger balance assets
$-15 assets
--------------------
$-15
```
---
### balance shows the sum of matched posting amounts
Here's a balance report based only on the postings dated 2013/2/13:
```
$ hledger balance date:2014/2/13
$-5 assets
$5 expenses
--------------------
0
```
As you can see from this, `balance` does not always report the current
real-world account balance, rather it shows the sum of the postings
you have selected.
If you're not sure what those are, run a `register` report with the same arguments to see them:
```
$ hledger register date:2014/2/13
2014/02/13 forgot the bread expenses $5 $5
assets $-5 0
```
---
### Review
You have learned:
- a simple plain text notation for recording financial transactions, used by hledger, Ledger and others
- what is the journal file, where it is, and how to get statistics on it with `hledger stats`
- how to record new transactions using `hledger add`
- how to record transactions by editing the journal file
- what the journal entry for a purchase looks like
- how to detect some common errors, by eye or with hledger
- how hledger selects data to report on, and how to select by account, description, or date
- how to list transactions with `hledger print`
- how to list postings and see an account's balance over time with `hledger register`
- how to list accounts and their current balance, or the sum of their postings in some period, with `hledger balance`
---
<!--
### Test yourself
Start a journal tracking the cash in your pocket or wallet. Every day for one week,
1. record each and every outflow and inflow of this cash, to the penny
2. run reports showing the transactions, per-account running balance, and current account balances
After seven days, do an audit:
- Count the cash. Does it exactly match the final balance in your hledger reports ?
If not, try to identify how and when things went wrong.
If you're confident you found the mistake, have corrected the journal and it now agrees with reality, that counts as a pass.
- Can you easily recall and understand the purpose of each transaction, with the help of your descriptions ?
You don't need to categorise, you don't need to track anything other than the amount of cash in your pocket, and it's only for seven days.
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
---
### 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:
- **Assets** - Things owned
- **Liabilities** - Things owed
- **Equity** - The amount invested by owners/shareholders
The foundation of double-entry accounting is the [[wp>accounting equation]], which says
that Equity is always equal to Assets minus Liabilities (or, Net Assets).
This is also written as: Assets = Liabilities + Equity.
Another way to say it: what the entity owns is funded either by debt or by the capital provided by its owners.
These three are called the Balance Sheet accounts. Their balances summarise the overall financial status at some point in time.
---
### Revenue and Expenses
Two more amounts are used to describe changes in the above during a given period:
- **Revenue** - Money flowing in
- **Expenses** - Money flowing out
You may be accustomed to using the word Income instead Revenue.
That's fine, just remember that Income is sometimes used to mean Net
Income, which is Revenue - Expenses.
These two are called the Income Statement accounts. The balances they
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
Five numbers does not give a lot of detail. If you want to know what
portion of expenses went to buy food, you could add up just the
transactions with (say) "supermarket" in their description. You know how to do this with hledger:
```
$ hledger register desc:supermarket expenses
2014/02/12 trip to the super.. expenses $10 $10
```
But descriptions are irregular, and as you can see we missed the $5 purchase on the following day.
Instead, the major "top-level" accounts above are subdivided into subaccounts which can be used
in transactions, thereby categorising them in a more structured way.
If needed, these subaccounts can be subdivided further.
This tree of accounts is called the Chart of Accounts. Here's a simple example
where `assets`, `revenue` and `expenses` each have a few subaccounts:
```
assets
checking
cash
liabilities
equity
revenue
business income
gifts received
expenses
food
rent
supplies
```
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 |
In others, the tree structure is encoded as decimal account numbers, something like this:
```
1000 assets
1100 checking
1200 cash
2000 liabilities
3000 equity
4000 revenue
4100 business income
4200 gifts received
5000 expenses
5100 food
5200 rent
5300 supplies
```
---
### Subaccounts in hledger
With hledger, tree structure is implied by writing account names like `ACCOUNT:SUBACCOUNT`.
Try it: edit your journal file and change the account names like so:
```
$ cat ~/.hledger.journal
2014/02/12 trip to the supermarket
expenses:supplies $10
assets:checking
2014/02/13 forgot the bread
expenses:food $5
assets:cash
```
hledger will infer the chart of accounts from these names, and `balance` will indent subaccounts to show the tree structure:
```
$ hledger balance
$-15 assets
$-5 cash
$-10 checking
$15 expenses
$5 food
$10 supplies
--------------------
0
```
For clarity, the common part of the subaccount names is not displayed.
You can see the full account names used internally like this:
```
$ hledger balance --flat --empty
$-15 assets
$-5 assets:cash
$-10 assets:checking
$15 expenses
$5 expenses:food
$10 expenses:supplies
--------------------
0
```
With `--flat`, the balance command shows full account names without indentation.
The `--empty` flag here requests that the accounts with no direct postings of their own be displayed.
Normally the balance report omits or elides such "uninteresting" accounts when they don't add much information.
(In the default indented view, they are included to clarify the structure.)
As you can see, the balance reported for parent accounts includes the
balances of any subaccounts (it would also include any postings to the
parent account itself.)
hledger accepts whatever account names you choose, so you can use as much or as little account hierarchy as you need.
Most users have at least two levels of accounts.
You can always limit the amount of detail in a balance report with `--depth`:
```
$ hledger balance --depth 1
$-15 assets
$15 expenses
--------------------
0
```
---
<!--
### Transactions
A transaction is a movement of money from some account(s) to some
other account(s). There are many common types of transaction. A
purchase is where money moves from an asset account to an expense
account. Eg, buying food.
-->