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

doc: move most non-manual docs to the wiki

Browse Source
This commit is contained in:
Simon Michael 2018-03-07 23:34:23 -08:00
parent 669e6f0e18
commit 7ffdcc509d
15 changed files with 8 additions and 2106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
Shake.hs
View File

@ -60,7 +60,6 @@ usage = unlines
-- ,"./Shake infomanpages # generate info files for info" -- ,"./Shake infomanpages # generate info files for info"
-- ,"./Shake webmanpages # generate individual web man pages for hakyll" -- ,"./Shake webmanpages # generate individual web man pages for hakyll"
-- ,"./Shake webmanall # generate all-in-one web manual for hakyll" -- ,"./Shake webmanall # generate all-in-one web manual for hakyll"
-- ,"./Shake guideall # generate all-in-one web user guide for hakyll"
,"./Shake site/doc/VER/.snapshot # generate and save a versioned web site snapshot" ,"./Shake site/doc/VER/.snapshot # generate and save a versioned web site snapshot"
,"./Shake all # generate everything" ,"./Shake all # generate everything"
,"./Shake clean # clean generated files" ,"./Shake clean # clean generated files"
@ -155,28 +154,6 @@ main = do
-- manuals rendered to markdown and combined, ready for web output by hakyll -- manuals rendered to markdown and combined, ready for web output by hakyll
webmanall = "site/manual.md" webmanall = "site/manual.md"
-- user guide pages in markdown, ready for web output by hakyll (site/csv-import.md).
-- Keeping these in the main site directory allows hakyll-std to see them (and simpler urls).
-- These should be kept ordered like the links on the docs page, so that the
-- combined guide follows the same order.
-- XXX This, as well as keeping page link, heading, and filename synced, will be a bit tricky.
-- Current policy:
-- filenames are simple and stable as possible, beginning with TOPIC- prefix when appropriate
-- titles are succinct and practical/action/verb-oriented
guidepages = [
"site/start-journal.md"
,"site/version-control.md"
,"site/entries.md"
,"site/csv-import.md"
,"site/account-aliases.md"
,"site/account-separator.md"
,"site/investments.md"
,"site/argfiles.md"
]
-- guide pages combined, ready for web output by hakyll
guideall = "site/guide.md"
-- hledger.1 -> hledger/doc, hledger_journal.5 -> hledger-lib/doc -- hledger.1 -> hledger/doc, hledger_journal.5 -> hledger-lib/doc
manpageDir m manpageDir m
| '_' `elem` m = "hledger-lib" | '_' `elem` m = "hledger-lib"
@ -266,7 +243,6 @@ main = do
need $ need $
webmanpages ++ webmanpages ++
[webmanall [webmanall
,guideall
,hakyllstd ,hakyllstd
] ]
cmd Shell (Cwd "site") "hakyll-std/hakyll-std" "build" cmd Shell (Cwd "site") "hakyll-std/hakyll-std" "build"
@ -316,20 +292,6 @@ main = do
">>" webmanall :: Action ExitCode ">>" webmanall :: Action ExitCode
-- adjust and combine recipe mds for single-page web output, using pandoc -- adjust and combine recipe mds for single-page web output, using pandoc
phony "guideall" $ need [ guideall ]
guideall %> \out -> do
need $ guidepages ++ pandocFilters -- XXX seems not to work, not rebuilt when a recipe changes
liftIO $ writeFile guideall "* toc\n\n" -- # User Guide\n\n -- TOC style is better without main heading,
forM_ guidepages $ \f -> do -- site/csv-import.md, site/account-aliases.md, ...
cmd Shell ("printf '\\n\\n' >>") guideall :: Action ExitCode
cmd Shell "pandoc" f "-t markdown-fenced_divs --atx-headers"
-- "--filter tools/pandoc-drop-man-blocks"
"--filter tools/pandoc-drop-toc"
-- "--filter tools/pandoc-capitalize-headers"
"--filter tools/pandoc-demote-headers"
">>" guideall :: Action ExitCode
-- build the currently checked out web docs and save as a named snapshot -- build the currently checked out web docs and save as a named snapshot
"site/doc/*/.snapshot" %> \out -> do "site/doc/*/.snapshot" %> \out -> do
need [ webmanall ] need [ webmanall ]
@ -359,7 +321,7 @@ main = do
phony "clean" $ do phony "clean" $ do
putNormal "Cleaning generated files" putNormal "Cleaning generated files"
removeFilesAfter "." webmanpages removeFilesAfter "." webmanpages
removeFilesAfter "." [webmanall, guideall] removeFilesAfter "." [webmanall]
phony "Clean" $ do phony "Clean" $ do
need ["clean"] need ["clean"]

51
site/account-aliases.md
View File

@ -1,51 +0,0 @@
# Rewrite account names
Here's an example of using [account aliases](manual.html#account-aliases).
Say a sole proprietor has a `personal.journal`:
```journal
2014/1/2
expenses:food $1
assets:cash
```
and a `business.journal`:
```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,
```journal
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:
```shell
$ 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:
```shell
$ hledger --alias 'my earning=income:business' ...
```
See also [How to use another account separator character](how-to-use-another-account-separator-character.html).

48
site/account-separator.md
View File

@ -1,48 +0,0 @@
# Use another account separator character
[Timedot format](manual.html#timedot) makes me want to use dots (`.`) for separating account components, instead of colon (`:`).
For example, instead of `fos:hledger:timedot` I'd like to write `fos.hledger.timedot`.
We can use the powerful [account aliases](manual.html#account-aliases) feature
to rewrite account names before hledger's account name parser sees them.
In journal files, we can use an alias directive.
Note the backslash which tells the regular expression engine it's a literal `.` not a wildcard:
```journal
# alias /REGEX/=REPLACEMENT
alias /\./=:
2008/01/01 income
assets.bank.checking $1
income.salary
```
Check that subaccounts are recognised:
```shell
$ hledger -f t.journal bal --no-elide
$1 assets
$1 bank
$1 checking
$-1 income
$-1 salary
--------------------
0
```
Alias directives aren't supported in the timedot format,
```timedot
2016/2/4
fos.hledger.timedot 2
fos.ledger 1
```
so we would use the `--alias` command line option instead.
The second backslash tells the shell that's a literal backslash, not a shell escape sequence:
```shell
$ hledger --alias /\\./=: -f t.timedot bal --no-elide
3.00 fos
2.00 hledger
2.00 timedot
1.00 ledger
--------------------
3.00
```

80
site/argfiles.md
View File

@ -1,80 +0,0 @@
# Save frequently used options
You can save frequently used options and arguments in an
[argument file](manual#argument-files), one per
line, then reuse them via a @FILE argument on the command line.
(hledger 1.4+)
Here's an example.
I keep frequently-used options for quick daily reports in a file
called `simple.args`. The name can be anything; I use a `.args` suffix
so I can find these easily. Here's the content of `simple.args`:
```
--alias=/:(business|personal):/=:
--alias=/:(bank|cash|online):/=:
--alias=/:bofi:/=:b
--alias=/:unify:/=:u
--alias=/:wf:/=:w
-2
cur:.
```
The format is one command-line flag or command-line argument per line.
Now if I write `@simple.args` in a hledger command line, it will be replaced
by all of the above options/flags.
The options above are just an example, but in case you're wondering:
- the [aliases](manual.html#account-aliases) simplify the chart of accounts, hiding some distinctions (eg business vs. personal) and flattening some bank account names
- the `-2` [depth flag](manual.html#depth-limiting) limits account depth to 2, hiding deeper subaccounts
- the `cur:.` [query argument](manual.html#queries) shows only single-character currencies, hiding a bunch of cluttersome commodities I don't want to see
Ie they remove some detail, giving simplified reports which are easier for me to read at a glance.
## Usage
Generate a balance report showing the simplified accounts:
```shell
$ hledger bal @simple.args
```
Start a live-updating hledger-ui showing the simplified asset accounts only:
```shell
$ hledger-ui --watch @simple.args assets
```
Options in the arguments file can be overridden by similar options later on
the command line, in the [usual way](manual.html#options).
Eg, to show just a little more account detail:
```shell
$ hledger bal @simple.args -3
```
## Quoting
[Special characters](manual.html#special-characters) in the arguments file
may need to be quoted, depending on your shell (bash, fish etc.)
They'll need one less level of quoting than on the command line.
I think
```shell
$ hledger bal @simple.args
```
is equivalent to writing:
```shell
$ hledger bal "--alias=/:(business|personal):/=:" "--alias=/:(bank|cash|online):/=:" "--alias=/:bofi:/=:b" "--alias=/:unify:/=:u" "--alias=/:wf:/=:w" "-2" "cur:."
```
So in this example, using the bash shell, the `|` pipe character did
not need to be quoted in the arguments file (and should not be).
## Suppressing this feature
If you actually need to write an argument beginning with @,
eg let's say you have an account pattern beginning with that character,
you'll want a way to disable this feature. On unix systems at least,
you can do that by inserting a `--` (double hyphen) argument first. Eg:
```
$ hledger bal @somewhere.com # looks for additional arguments in the ./somewhere.com file
$ hledger bal -- @somewhere.com # matches account names containing "@somewhere.com"
```
On windows, this double hyphen trick [might](https://ghc.haskell.org/trac/ghc/ticket/13287) require a hledger built with GHC 8.2+.
(Let us know.)

323
site/budgeting-and-forecasting.md
View File

@ -1,323 +0,0 @@
# Budgeting and forecasting
Budgeting and forecasting allows you to keep better track of your expenses and future financial situation.
If you write down your expectations of what your income/expenses/investment yields/etc should be, you can use them to:
- check how far off are your expectations from reality (budgeting)
- project your future account activity or balances (forecasting)
(This section uses examples/bcexample.hledger from hledger source repository).
## Periodic budget
To start budgeting, you need to know what your average yearly or weekly expenditures are. Hledger could help you with that.
Usually the interval for which you compute budget figures will be the same as the interval between
your paychecks -- monthly or weekly.
Lets create monthly (-M) report for years 2013-2014 (-b 2013) of all
top-level expense categories (--depth 2 Expenses), looking for average
figures (-A) in the cost at the time of transaction (-B), limiting
ourselves to USD transactions only, to save screen space:
```shell
$ hledger balance -f bcexample.hledger -MBA -b 2013 --depth 2 Expenses cur:USD
Balance changes in 2013/01/01-2014/10/31:
|| 2013/01 2013/02 2013/03 ... 2014/07 2014/08 2014/09 2014/10 Average
====================++========================================...==================================================================
Expenses:Financial || 4.00 USD 12.95 USD 39.80 USD ... 30.85 USD 21.90 USD 12.95 USD 4.00 USD 17.83 USD
Expenses:Food || 396.46 USD 481.48 USD 603.32 USD ... 871.20 USD 768.23 USD 466.72 USD 83.00 USD 562.10 USD
Expenses:Health || 290.70 USD 193.80 USD 193.80 USD ... 290.70 USD 193.80 USD 193.80 USD 96.90 USD 207.01 USD
Expenses:Home || 2544.98 USD 2545.02 USD 2544.97 USD ... 2545.12 USD 2545.01 USD 2545.10 USD 0 2429.33 USD
Expenses:Taxes || 5976.60 USD 3984.40 USD 4901.83 USD ... 5976.60 USD 3984.40 USD 3984.40 USD 1992.20 USD 4322.27 USD
Expenses:Transport || 120.00 USD 120.00 USD 120.00 USD ... 0 120.00 USD 120.00 USD 120.00 USD 109.09 USD
--------------------++----------------------------------------...------------------------------------------------------------------
|| 9332.74 USD 7337.65 USD 8403.72 USD ... 9714.47 USD 7633.34 USD 7322.97 USD 2296.10 USD 7647.64 USD
```
This report is rather wide and portion of it had been cut out for
brevity. Most interesting column is the last one, it shows average
monthly expenses for each category. Expenses in Food, Health, Home and
Transport categories seem to roughly similar month to month, so lets
create a budget for them.
Budgets are described with periodic transactions. Periodic transaction
has `~` instead of date and period expression instead of description. In this case
we want to create a monthly budget that will come into effect starting from January 2013,
which will include income of 10000 USD that is partically spent on Food, Health, Home and Transport
and the rest becomes our Assets:
```journal
~ monthly from 2013/01
Expenses:Food 500 USD
Expenses:Health 200 USD
Expenses:Home 2545 USD
Expenses:Transport 120 USD
Income:US -10700 USD ;; Taken as monthy average of Income account group
Assets:US
```
This transaction could be put into separate file (budget.journal) or
could be kept in the main journal. Normally hledger will ignore it and
will not include it in any computations or reports.
To put it into action, you need to add `--budget` switch to your balance invocation. If you do that,
you would be able to see how your past expenses aligned with the budget that you just created. This
time, lets not limit accounts in any way:
```shell
$ hledger balance -f bcexample.hledger -f budget.journal -MB -b 2013 --budget cur:USD
Balance changes in 2013/01/01-2014/10/31:
|| 2013/01 2013/02 2013/03
==========================++===========================================================================================================
<unbudgeted>:Expenses || 5980.60 USD 3997.35 USD 4941.63 USD
<unbudgeted>:Liabilities || 293.09 USD -147.51 USD -66.01 USD
Assets:US || 1893.32 USD [26% of 7335 USD] 2929.77 USD [40% of 7335 USD] -3898.89 USD [-53% of 7335 USD]
Expenses:Food || 396.46 USD [79% of 500 USD] 481.48 USD [96% of 500 USD] 603.32 USD [121% of 500 USD]
Expenses:Health || 290.70 USD [145% of 200 USD] 193.80 USD [97% of 200 USD] 193.80 USD [97% of 200 USD]
Expenses:Home || 2544.98 USD [100% of 2545 USD] 2545.02 USD [100% of 2545 USD] 2544.97 USD [100% of 2545 USD]
Expenses:Transport || 120.00 USD [100% of 120 USD] 120.00 USD [100% of 120 USD] 120.00 USD [100% of 120 USD]
Income:US || -15119.10 USD [141% of -10700 USD] -10331.21 USD [97% of -10700 USD] -11079.40 USD [104% of -10700 USD]
--------------------------++-----------------------------------------------------------------------------------------------------------
|| -3599.95 USD -211.30 USD -6640.58 USD
```
Numbers in square brackets give you your budget estimate and percentage of it used by your real expenses. Numbers below 100% mean
that you have some of your budget left, numbers over 100% mean that you went over your budget.
You can notice that actual numbers for Assets:US seem to be well below computed budget of 7335 USD. Why? Answer to this is in the first
row of the report: we have quite a lot of unbudgeted Expenses!
Notice that even though we have not limited accounts in any way, report includes just those mentioned in the budget. This is on purpose,
assumption is that when you are checking your budgets you probably do not want unbudgeted accounts getting in your way. Another thing to
note is that budget numbers have been allocated to top-level expense subcategories (like Expenses:Food). Journal has subaccounts under
Food, but to compute budget report they have all been rolled up into a nearest parent with budget number associated with it. Accounts that
do not have such parent went into `<unbudgeted>` row.
Allright, it seems that for Jan 2013 we have ~3000 USD of budgeted expenses and almost twice as much unbudgeted. Lets figure out what they are.
We can see more details if we add `--show-unbudgeted` switch:
```shell
$ hledger balance -f bcexample.hledger -f budget.journal -M -b 2013-01 -e 2013-02 --budget cur:USD --show-unbudgeted
Balance changes in 2013/01:
|| 2013/01
==================================++====================================
Assets:US || 1893.32 USD [26% of 7335 USD]
Expenses:Financial:Fees || 4.00 USD
Expenses:Food || 396.46 USD [79% of 500 USD]
Expenses:Health || 290.70 USD [145% of 200 USD]
Expenses:Home || 2544.98 USD [100% of 2545 USD]
Expenses:Taxes:Y2013:US:CityNYC || 524.76 USD
Expenses:Taxes:Y2013:US:Federal || 3188.76 USD
Expenses:Taxes:Y2013:US:Medicare || 319.86 USD
Expenses:Taxes:Y2013:US:SDI || 3.36 USD
Expenses:Taxes:Y2013:US:SocSec || 844.62 USD
Expenses:Taxes:Y2013:US:State || 1095.24 USD
Expenses:Transport || 120.00 USD [100% of 120 USD]
Income:US || -15119.10 USD [141% of -10700 USD]
Liabilities:US:Chase:Slate || 293.09 USD
----------------------------------++------------------------------------
|| -3599.95 USD
```
All the accounts that were rolled up into `<unbudgeted>` category are now shown with their original name, but budgeted accounts are still rolled up. It
is easy to see now that we forgot taxes. Lets add them to our budget:
```journal
~ monthly from 2013/01
Expenses:Food 500 USD
Expenses:Health 200 USD
Expenses:Home 2545 USD
Expenses:Transport 120 USD
Expenses:Taxes 4300 USD ;; Taken from monthly average report
Income:US -10700 USD
Assets:US
```
Lets try again for a couple of month with this updated budget:
```shell
$ hledger balance -f bcexample.hledger -f budget.journal -M -b 2013-01 -e 2013-04 --budget cur:USD
Balance changes in 2013q1:
|| 2013/01 2013/02 2013/03
==========================++===========================================================================================================
<unbudgeted>:Expenses || 4.00 USD 12.95 USD 39.80 USD
<unbudgeted>:Liabilities || 293.09 USD -147.51 USD -66.01 USD
Assets:US || 1893.32 USD [62% of 3035 USD] 2929.77 USD [97% of 3035 USD] -3898.89 USD [-128% of 3035 USD]
Expenses:Food || 396.46 USD [79% of 500 USD] 481.48 USD [96% of 500 USD] 603.32 USD [121% of 500 USD]
Expenses:Health || 290.70 USD [145% of 200 USD] 193.80 USD [97% of 200 USD] 193.80 USD [97% of 200 USD]
Expenses:Home || 2544.98 USD [100% of 2545 USD] 2545.02 USD [100% of 2545 USD] 2544.97 USD [100% of 2545 USD]
Expenses:Taxes || 5976.60 USD [139% of 4300 USD] 3984.40 USD [93% of 4300 USD] 4901.83 USD [114% of 4300 USD]
Expenses:Transport || 120.00 USD [100% of 120 USD] 120.00 USD [100% of 120 USD] 120.00 USD [100% of 120 USD]
Income:US || -15119.10 USD [141% of -10700 USD] -10331.21 USD [97% of -10700 USD] -11079.40 USD [104% of -10700 USD]
--------------------------++-----------------------------------------------------------------------------------------------------------
|| -3599.95 USD -211.30 USD -6640.58 USD
```
Now unbudgeted amounts are much smaller and some of them could be dismissed as noise, and we can see that budget created is actually
close enough to the real numbers, meaning that they are usually close to average that we put in our budget.
## Envelope budget
Budget report that we have used so far assumes that any unused budget amount for a given (monthly) period will not contribute to the
budget of the next period. Alternative popular "envelope budget" strategy assumes that you put a certain amount of money into an envelope
each month, and any unused amount stays there for future expenses. This is easy to simulate by adding --cumulative switch. Lets redo
the last report with it:
```shell
$ hledger balance -f bcexample.hledger -f budget.journal -M -b 2013-01 -e 2013-04 --cumulative --budget cur:USD
Ending balances (cumulative) in 2013q1:
|| 2013/01/31 2013/02/28 2013/03/31
==========================++============================================================================================================
<unbudgeted>:Expenses || 4.00 USD 16.95 USD 56.75 USD
<unbudgeted>:Liabilities || 293.09 USD 145.58 USD 79.57 USD
Assets:US || 1893.32 USD [62% of 3035 USD] 4823.09 USD [79% of 6070 USD] 924.20 USD [10% of 9105 USD]
Expenses:Food || 396.46 USD [79% of 500 USD] 877.94 USD [88% of 1000 USD] 1481.26 USD [99% of 1500 USD]
Expenses:Health || 290.70 USD [145% of 200 USD] 484.50 USD [121% of 400 USD] 678.30 USD [113% of 600 USD]
Expenses:Home || 2544.98 USD [100% of 2545 USD] 5090.00 USD [100% of 5090 USD] 7634.97 USD [100% of 7635 USD]
Expenses:Taxes || 5976.60 USD [139% of 4300 USD] 9961.00 USD [116% of 8600 USD] 14862.83 USD [115% of 12900 USD]
Expenses:Transport || 120.00 USD [100% of 120 USD] 240.00 USD [100% of 240 USD] 360.00 USD [100% of 360 USD]
Income:US || -15119.10 USD [141% of -10700 USD] -25450.31 USD [119% of -21400 USD] -36529.71 USD [114% of -32100 USD]
--------------------------++------------------------------------------------------------------------------------------------------------
|| -3599.95 USD -3811.25 USD -10451.83 USD
```
If you look at Expenses:Food category, you will see that every month budget is increased by 500 USD, and by March total amount budgeted
is 1500 USD, of which 1481.26 USD is spent. If you look back at the previous non-cumulative monthly budget report, you will see that in March food expenses
were 121% of the budgeted amount, but cumulative report shows that taking into account budget carry-over from Jan and Feb we are well withing planned numbers.
# Forecasting
Budget transaction that was created could be used to predict what would be our financial situation in the future. If you add `--forecast` switch, you will
see how budgeted income and expense affects you past the last transaction in the journal. Since journal ends in Oct 2014, lets see next two month:
```shell
$ hledger balance -f bcexample.hledger -f budget.journal -M -b 2014-10 -e 2015 --forecast cur:USD
Balance changes in 2014q4:
|| 2014/10 2014/11 2014/12
====================================++======================================
Assets:US || 0 3035 USD 3035 USD
Assets:US:BofA:Checking || -2453.40 USD 0 0
Assets:US:ETrade:Cash || 5000.00 USD 0 0
Expenses:Financial:Fees || 4.00 USD 0 0
Expenses:Food || 0 500 USD 500 USD
Expenses:Food:Restaurant || 83.00 USD 0 0
Expenses:Health || 0 200 USD 200 USD
Expenses:Health:Dental:Insurance || 2.90 USD 0 0
Expenses:Health:Life:GroupTermLife || 24.32 USD 0 0
Expenses:Health:Medical:Insurance || 27.38 USD 0 0
Expenses:Health:Vision:Insurance || 42.30 USD 0 0
Expenses:Home || 0 2545 USD 2545 USD
Expenses:Taxes || 0 4300 USD 4300 USD
Expenses:Taxes:Y2014:US:CityNYC || 174.92 USD 0 0
Expenses:Taxes:Y2014:US:Federal || 1062.92 USD 0 0
Expenses:Taxes:Y2014:US:Medicare || 106.62 USD 0 0
Expenses:Taxes:Y2014:US:SDI || 1.12 USD 0 0
Expenses:Taxes:Y2014:US:SocSec || 281.54 USD 0 0
Expenses:Taxes:Y2014:US:State || 365.08 USD 0 0
Expenses:Transport || 0 120 USD 120 USD
Expenses:Transport:Tram || 120.00 USD 0 0
Income:US || 0 -10700 USD -10700 USD
Income:US:Hoogle:GroupTermLife || -24.32 USD 0 0
Income:US:Hoogle:Salary || -4615.38 USD 0 0
Liabilities:US:Chase:Slate || -203.00 USD 0 0
------------------------------------++--------------------------------------
|| 0 0 0
```
Note that this time there is no roll-up of accounts. Unlike `--budget`, which could be used with `balance` command only, `--forecast`
could be used with any report. Forecast transactions would be added to your real journal and would appear in the report you requested as
if you have entered them on the scheduled dates.
Since quite a lot of accounts do not have any budgeted transactions, lets limit the depth of the report to avoid seeing lots of zeroes:
```shell
$ hledger balance -f bcexample.hledger -f budget.journal -M -b 2014-10 -e 2015 --forecast cur:USD --depth 2
Balance changes in 2014q4:
|| 2014/10 2014/11 2014/12
====================++======================================
Assets:US || 2546.60 USD 3035 USD 3035 USD
Expenses:Financial || 4.00 USD 0 0
Expenses:Food || 83.00 USD 500 USD 500 USD
Expenses:Health || 96.90 USD 200 USD 200 USD
Expenses:Home || 0 2545 USD 2545 USD
Expenses:Taxes || 1992.20 USD 4300 USD 4300 USD
Expenses:Transport || 120.00 USD 120 USD 120 USD
Income:US || -4639.70 USD -10700 USD -10700 USD
Liabilities:US || -203.00 USD 0 0
--------------------++--------------------------------------
|| 0 0 0
```
As you can see, we should expect 3035 USD to be added into Assets:US each month. It is quite easy to see how overal amount of Assets will change with time if you use
`--cumulative` switch:
```shell
$ hledger balance -f bcexample.hledger -f budget.journal -M -b 2014-10 -e 2015 --forecast cur:USD --depth 2 --cumulative
Ending balances (cumulative) in 2014q4:
|| 2014/10/31 2014/11/30 2014/12/31
====================++============================================
Assets:US || 2546.60 USD 5581.60 USD 8616.60 USD
Expenses:Financial || 4.00 USD 4.00 USD 4.00 USD
Expenses:Food || 83.00 USD 583.00 USD 1083.00 USD
Expenses:Health || 96.90 USD 296.90 USD 496.90 USD
Expenses:Home || 0 2545 USD 5090 USD
Expenses:Taxes || 1992.20 USD 6292.20 USD 10592.20 USD
Expenses:Transport || 120.00 USD 240.00 USD 360.00 USD
Income:US || -4639.70 USD -15339.70 USD -26039.70 USD
Liabilities:US || -203.00 USD -203.00 USD -203.00 USD
--------------------++--------------------------------------------
|| 0 0 0
```
According to forecast, assets are expected to grow to 8600+ USD by the end of 2014. However, our forecast does not include a couple
of big one-off year end expenses. First, we plan to buy prize turkey for the Christmas table every year from 2014, spending up to 500 USD on it.
And on 17th Nov 2014 we would celebrate birthday of significant other, spending up to 6000 USD in a fancy restaurant:
```journal
~ every 20th Dec from 2014
Expenses:Food 500 USD ; Prize turkey, the biggest of the big
Assets:US
~ 2014/11/17
Assets:US
Expenses:Food 6000 USD ; Birthday, lots of guests
```
Note that turkey transaction is not entered as "yearly from 2014/12/20", since yearly/quarterly/monthy/weekly periodic expressions always generate
entries at the first day of the calendar year/quarter/month/week. Thus "monthly from 2014/12" will occur on 2014/12/01, 2015/01/01, ..., whereas
"every 20th of month from 2014/12" will happen on 2014/12/20, 2015/12/20, etc.
With latest additions forecast now looks like this:
```shell
hledger balance -f bcexample.hledger -f budget.journal -M -b 2014-10 -e 2015 --forecast cur:USD --depth 2 --cumulative
Ending balances (cumulative) in 2014q4:
|| 2014/10/31 2014/11/30 2014/12/31
====================++============================================
Assets:US || 2546.60 USD -418.40 USD 2116.60 USD
Expenses:Financial || 4.00 USD 4.00 USD 4.00 USD
Expenses:Food || 83.00 USD 6583.00 USD 7583.00 USD
Expenses:Health || 96.90 USD 296.90 USD 496.90 USD
Expenses:Home || 0 2545 USD 5090 USD
Expenses:Taxes || 1992.20 USD 6292.20 USD 10592.20 USD
Expenses:Transport || 120.00 USD 240.00 USD 360.00 USD
Income:US || -4639.70 USD -15339.70 USD -26039.70 USD
Liabilities:US || -203.00 USD -203.00 USD -203.00 USD
--------------------++--------------------------------------------
|| 0 0 0
```
It is easy to see that in Nov 2014 we will run out of Assets. Using `register` we can figure out when or why it would happen:
```shell
$ hledger register -f bcexample.hledger -f budget.journal -b 2014-10 -e 2014-12 --forecast cur:USD Assets
2014/10/04 "BANK FEES" | "Monthly bank fee" Assets:US:BofA:Checking -4.00 USD -4.00 USD
2014/10/09 "Hoogle" | "Payroll" Assets:US:BofA:Checking 2550.60 USD 2546.60 USD
2014/10/10 "Transfering accumulated savings to o.. Assets:US:BofA:Checking -5000.00 USD -2453.40 USD
Assets:US:ETrade:Cash 5000.00 USD 2546.60 USD
2014/11/01 Forecast transaction Assets:US 3035 USD 5581.60 USD
2014/11/17 Forecast transaction Assets:US -6000 USD -418.40 USD
```
It is 6000 USD planned for birthday! Something will have to be done about the birthday plans.

59
site/csv-import.md
View File

@ -1,59 +0,0 @@
# Convert CSV files
Here's a quick example of reading CSV data with hledger.
Say we have downloaded `checking.csv` from a bank for the first time:
```csv
"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 [CSV rules syntax](manual.html#csv-format). Eg:
```rules
# 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:
```shell
$ 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:
```shell
$ 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
```
Here are more [CSV rules examples](https://github.com/simonmichael/hledger/tree/master/examples/csv).

94
site/docs.md
View File

@ -33,7 +33,6 @@ For more docs relevant to all ledger-likes, see [plaintextaccounting.org](http:/
### What is hledger? ### What is hledger?
An enhanced, well-documented rewrite of the original plain text accounting tool.\ An enhanced, well-documented rewrite of the original plain text accounting tool.\
[hledger intro](http://hledger.org)\ [hledger intro](http://hledger.org)\
[Frequently Asked Questions](faq.html)\
[Download](download.html)\ [Download](download.html)\
[Release notes](release-notes.html)\ [Release notes](release-notes.html)\
@ -45,67 +44,10 @@ Using plain text data formats and modular free software tools for robust, effici
### What is Accounting? ### What is Accounting?
Tracking your use of valuable commodities, such as money or time, for increased awareness and effectiveness.\ Tracking your use of valuable commodities, such as money or time, for increased awareness and effectiveness.\
[Selected accounting links](more-docs.html#accounting)\ [Selected accounting links](http://github.com/simonmichael/hledger/wiki/more-docs)\
</div> </div>
<div class="col-sm-3">
## [Guide](guide.html){title="all on one page"}
A growing collection of tutorials, how-tos and discussion of general topics.
### Getting started
[hledger Step by Step](step-by-step.html) tutorial\
### Journal management
[Start a journal](start-journal.html)\
[Track changes with version control](version-control.html)\
### Account names
[PTA: choosing accounts](http://plaintextaccounting.org/#choosing-accounts)\
[Rewrite account names](account-aliases.html)\
[Use another account separator character](account-separator.html)\
### Journal entries
[Basic journal entries](entries.html)\
[Project accounting](project-accounting.html)\
### Data entry/import
[Convert CSV files](csv-import.html)\
### Budgeting/forecasting
[Budgeting and forecasting](budgeting-and-forecasting.html)\
### Investing
[Track investments](investments.html)\
### More..
[Save frequently used options](argfiles.html)\
[PTA: Common tasks](http://plaintextaccounting.org/#common-tasks)\
</div>
<div class="col-sm-3"> <div class="col-sm-3">
## [Reference](manual.html){title="all on one page"} ## [Reference](manual.html){title="all on one page"}
@ -140,39 +82,17 @@ is for precise time logging with clock-in/clock-out
[timedot format](timedot.html) [timedot format](timedot.html)
is for human-friendly approximate time logging is for human-friendly approximate time logging
### Addon tools </div>
[hledger-diff](http://hackage.haskell.org/package/hledger-diff) <div class="col-sm-3">
shows differences in an account's transactions between one journal file and another.
[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) ## Wiki / Cookbook
is a curses-style replacement for hledger's add command.
[hledger-interest](http://hackage.haskell.org/package/hledger-interest) Tutorials, how-tos and discussion of general topics.
generates interest transactions for an account according to various schemes.
[hledger-irr](http://hackage.haskell.org/package/hledger-irr) https://github.com/simonmichael/hledger/wiki
calculates the internal rate of return of an investment account.
Some experimental tools: </div>
[hledger-budget.hs](https://github.com/simonmichael/hledger/blob/master/bin/hledger-budget.hs#L10)
adds Ledger-style periodic transactions and budget reports.
[hledger-check.hs](https://github.com/simonmichael/hledger/blob/master/bin/hledger-check.hs)
checks more powerful account balance assertions.
Also:
[ledger-autosync](https://pypi.python.org/pypi/ledger-autosync),
can download, deduplicate and/or convert OFX data (includes hledger support,
rename/symlink it to hledger-autosync to see it in commands list)
[PTA: related tools](http://plaintextaccounting.org/#related-tools)
lists all known plain text accounting helper tools
</div> <!-- col -->
</div> <!-- row --> </div> <!-- row -->
</div> <!-- container --> </div> <!-- container -->

12
site/entries.md
View File

@ -1,12 +0,0 @@
# Example journal entries
Example hledger journal entries for various kinds of transaction.
A purchase:
```journal
2017/1/26 market
expenses:food $10
assets:cash
```

286
site/faq.md
View File

@ -1,286 +0,0 @@
<style>
#toc > ol > li > a { display:none; }
#toc > ol > li > ol > li { padding-left:0; }
</style>
* toc
# Frequently asked questions
## hledger & Ledger
### History
I discovered John Wiegley's [Ledger](http://ledger-cli.org) in 2006,
and was very happy to find this efficient command-line reporting tool with a transparent data format.
Initially, I used it to generate time reports for my job.
Before long I wanted that to work differently - splitting sessions at day boundaries, reporting in hours, etc.
John had got busy elsewhere and the Ledger project now stalled, with unfixed bugs, wrong documentation and a confusing release situation persisting for a long time.
I did what I could to help build momentum, reporting bugs, supporting newcomers, and contributing a new domain and website.
But, I didn't want to spend time learning C++.
I was learning Haskell, which I did want to spend time in.
I felt Ledger could be implemented well and, in the long run, more efficiently in that language,
which has some compelling advantages such as lower maintenance costs.
<!-- ([eg](http://neilmitchell.blogspot.com/2016/02/selling-haskell-in-pub.html)). -->
<!-- (It encourages the coding style known as pure functional programming, -->
<!-- allowing more bug-free, concise and maintainable software. It provides -->
<!-- a more abstracted, portable platform making installation easier. It is -->
<!-- attractive for contributors to work on.) -->
I urgently needed a reliable accounting tool that I enjoyed using.
I also wanted to see what I could do to reduce roadbumps and confusion for newcomers.
I couldn't expect John to start over - at that time he was not the Haskell fan he is now!
So in 2007 I began experimenting.
I built a toy parser in a few different languages, and it was easiest in Haskell.
I kept tinkering.
Goals included:
- to get better at Haskell by building something useful to me,
- to learn how well Haskell could work for real-world applications,
- and eventually: to provide a new implementation focussing more on
ease of use, absence of user-visible bugs, and high-quality documentation and web presence.
Also to experiment with new user interfaces, APIs, etc.
Before too long I had a tool that was useful to me. With Ledger still installed,
and by maintaining high compatibility, I now had two tools with different strengths,
each providing a comparison for the other in case of confusion or suspected bugs,
which was itself quite valuable.
Happily, the Ledger project later revived and has attracted new active contributors.
I have remained active in that community, sharing discoveries and
design discussions, and we have seen many ideas travelling in both directions.
hledger shared #ledger's IRC channel until 2014, when I added
[#hledger](irc://irc.freenode.net/#hledger) to allow us more space.
I think having independent but compatible implementations has been
quite helpful for troubleshooting, exploring the design space, and
growing the "Ledger-likes" community.
My other projects in that direction include
the [ledger-cli.org](http://ledger-cli.org) site,
[LedgerTips](http://twitter.com/LedgerTips),
IRC support on #ledger,
and now [plaintextaccounting.org](http://plaintextaccounting.org).
### Features
Compared to Ledger, hledger builds quickly and has a complete and
accurate manual, an easier report query syntax, multi-column balance
reports, better depth limiting, an interactive data entry assistant,
and optional web and curses interfaces.
Compared to hledger, Ledger has additional power-user features such as
periodic and modifier transactions, budget reports, and the built in
value expressions language, and it remains faster and more memory
efficient (for now).
We currently support:
- Ledger's journal format, mostly
- csv format
- timeclock format
- regular journal transactions
- multiple commodities
- fixed transaction prices
- varying market prices
- virtual postings
- some basic output formatting
- the print, register & balance commands
- report filtering, using a different query syntax
We do not support:
- automated transactions
- value expressions
- budget reports
And we add these commands:
- add
- balancesheet
- cashflow
- chart
- incomestatement
- irr
- interest
- ui
- web
### File formats
hledger's journal 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 and hledger's more specialised syntax
(or keep it in separate files which you include only when appropriate).
Some Ledger syntax is parsed but ignored (such as
[automated transactions](http://ledger-cli.org/3.0/doc/ledger3.html#Automated-Transactions)
and [periodic transactions](http://ledger-cli.org/3.0/doc/ledger3.html#Periodic-Transactions)).
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, such as with
[hledger comments](manual.html#comments) vs [Ledger comments](http://ledger-cli.org/3.0/doc/ledger3.html#Commenting-on-your-Journal),
or [balance assertions](manual.html#assertions-and-ordering).
### Functional 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 time balances (from the timeclock/timedot formats) in hours, with two decimal places
- hledger splits multi-day time sessions at midnight by default (Ledger does this with an option)
- 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's [include directive](manual.html#including-other-files) does not support
shell glob patterns (eg `include *.journal` ), as Ledger's 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 checks assertions
in parse order, ignoring dates.
- Ledger allows amounts to have a fixed lot price (the {} syntax ?)
and a regular price in any order (and uses whichever appears
first). hledger requires the fixed lot price to come last (and
ignores it).
- hledger uses --ignore-assertions/-I to disable balance assertions.
Ledger uses --permissive, and -I means something else (--prices).
- hledger's -p option doesn't combine nicely with -b/-e/-D/-W/-M/-Q/-Y.
Basically if there's a -p, all those others are ignored.
There's an open issue.
With hledger you can also specify start and/or end dates with a query argument,
date:START-END, which probably doesn't combine perfectly with the options.
- in hledger version 1.3 onward,
the "uncleared" status has been renamed to "unmarked",
it is matched by the -U/--unmarked flag.
Also, the --unmarked/--pending/--cleared flags can be combined,
so eg -UP matches unmarked and pending, similar to Ledger's --uncleared flag.
(#564)
- hledger's -P flag is short for --pending. Ledger uses it for grouping by payee.
- hledger's journal and timeclock formats are separate; you can't use
[both syntaxes in the same file](https://www.reddit.com/r/plaintextaccounting/comments/7buf8q/how_to_balance_working_hours/dpligsd/)
unlike Ledger. ([Include](journal.html#including-other-files) a separate timeclock file instead.)
### Future ?
There is a [ledger4](https://github.com/ledger/ledger4) repo on
github; this is John's 2012/2013 rewrite of some parts of Ledger 3,
including the parser, in Haskell. We have a plan to add this parser to
hledger in 2015/2016, increasing its ability to read Ledger's files.
## UI surprises
### Why does it complain about missing amounts even though I wrote one ?
This is an easy mistake at first. This journal entry:
```journal
1/1
a 1
b
```
will give a parse error (`...can't have more than one real posting with no amount...`).
There must always be at least two spaces between the account name and amount. So instead, it should be:
```journal
1/1
a 1
b
```
### Why do some amounts appear on their own line with no account name ?
When hledger needs to show a multi-commodity amount, each commodity is displayed on its own line, one above the other (like Ledger).
Here are some examples. With this journal, the implicit balancing amount drawn from the `b` account will be a multicommodity amount (a euro and a dollar):
```journal
2015/1/1
a EUR 1
a USD 1
b
```
the `print` command shows the `b` posting's amount on two lines, bottom-aligned:
```shell
$ hledger -f t.j print
2015/01/01
a USD 1
a EUR 1
EUR -1 ; <-
b USD -1 ; <- a euro and a dollar is drawn from b
```
the `balance` command shows that both `a` and `b` have a multi-commodity balance (again, bottom-aligned):
```shell
$ hledger -f t.j balance
EUR 1 ; <-
USD 1 a ; <- a's balance is a euro and a dollar
EUR -1 ; <-
USD -1 b ; <- b's balance is a negative euro and dollar
--------------------
0
```
while the `register` command shows (top-aligned, this time!) a multi-commodity running total after the second posting,
and a multi-commodity amount in the third posting:
```shell
$ hledger -f t.j register --width 50
2015/01/01 a EUR 1 EUR 1
a USD 1 EUR 1 ; <- the running total is now a euro and a dollar
USD 1 ;
b EUR -1 ; <- the amount posted to b is a negative euro and dollar
USD -1 0 ;
```
Newer reports like [multi-column balance reports](manual.html#multicolumn-balance-reports) show multi-commodity amounts on one line instead, comma-separated.
Although wider, this seems clearer and we should probably use it more:
```shell
$ hledger -f t.j balance --yearly
Balance changes in 2015:
|| 2015
===++================
a || EUR 1, USD 1
b || EUR -1, USD -1
---++----------------
|| 0
```
You will also see amounts without a corresponding account name if you remove too many account name segments with [`--drop`](manual.html#balance):
```shell
$ hledger -f t.j balance --drop 1
EUR 1
USD 1
EUR -1
USD -1
--------------------
0
```

145
site/investments.md
View File

@ -1,145 +0,0 @@
# Track investments
You can use hledger to track stock investments.
In fact, the double-entry accounting is flexible enough to support most constellations you will come across.
However, you may find that some transactions could be better supported.
Caveats are:
- hledger does not validate the cost basis during a sale.
- historical mark-to-market performance is not supported
(but the market value at one instant, like today, can be calculated)
## Example
### Buying a stock
Let's go over a simple example using [prices](/journal.html#prices):
```journal
2017/1/1 opening balance
(assets:depot) $3000
2017/1/2 buy shares at $200
; let's assume no fees
assets:shares 10 TSLA @ $200 ; transaction/purchase price
assets:depot
```
Some reports.
We start with $3000.
After the 1/2 purchase, we have $1000 remaining and 10 TSLA shares:
```shell
$ hledger -f t.j bal --flat -HD
Ending balances (historical) in 2017/01/01-2017/01/02:
|| 2017/01/01 2017/01/02
===============++============================
assets:depot || $3000 $1000
assets:shares || 0 10 TSLA
---------------++----------------------------
|| $3000 $1000, 10 TSLA
```
Show the shares' value at cost, with [`-B/--cost`](/hledger.html#reporting-options):
```shell
$ hledger -f t.j bal --flat -HD -B
Ending balances (historical) in 2017/01/01-2017/01/02:
|| 2017/01/01 2017/01/02
===============++=========================
assets:depot || $3000 $1000
assets:shares || 0 $2000
---------------++-------------------------
|| $3000 $3000
```
## Value reporting
Add the following to the journal file.
```journal
; market price, has jumped since yesterday's purchase!
P 2017/1/3 TSLA $250
```
Show the shares's value using the latest applicable market price,
with [`-V/--value`](/hledger.html#market-value).
A $500 capital gain is apparent in the totals:
```shell
$ hledger -f t.j bal --flat -HD -V
Ending balances (historical) in 2017/01/01-2017/01/02:
|| 2017/01/01 2017/01/02
===============++=========================
assets:depot || $3000 $1000
assets:shares || 0 $2500
---------------++-------------------------
|| $3000 $3500
```
There are still limitations in the value reporting that hledger can currently do.
More information can be found in [Github issue #131](https://github.com/simonmichael/hledger/issues/131) and [Github issue #329](https://github.com/simonmichael/hledger/issues/329).
You may want to investigate the output after adding more prices to the journal file.
```journal
P 2017/1/1 TSLA $210
P 2017/1/4 TSLA $250
P 2017/1/8 TSLA $270
```
### Selling a stock and tracking capital gains
At some point you will probably sell shares.
It may seem intuitive to model such a sale as follows.
```journal
2017/1/4 sell shares at $250 ; NOTE: You probably want to model capital gains too; see below
assets:shares -10 TSLA @ $250 ; sell price
assets:depot
```
This leads to the following evolution
```shell
hledger -f t.j balance --flat -HD
Ending balances (historical) in 2017/01/01-2017/01/04:
|| 2017/01/01 2017/01/02 2017/01/03 2017/01/04
===============++=======================================================
assets:depot || $3000 $1000 $1000 $3500
assets:shares || 0 10 TSLA 10 TSLA 0
---------------++-------------------------------------------------------
|| $3000 $1000, 10 TSLA $1000, 10 TSLA $3500
```
You end up with the correct amount in your depot.
At some point, however, you will have to report the capital gain that you realized with your sale.
This gain is currently invisible.
In fact, we have violated the double-entry principle and created money out of nowhere.
Let's report our sale in a different way.
```journal
2017/1/4 sell shares at $250
assets:shares -10 TSLA @ $200 ; cost basis (must be tracked by user!)
assets:depot $2500 ; cash proceeds
revenue:capital_gains ; deduce profit
```
Now, the new $500 are correctly balanced with the capital gains account.
```shell
hledger -f t.j balance --flat -HD
Ending balances (historical) in 2017/01/01-2017/01/04:
|| 2017/01/01 2017/01/02 2017/01/03 2017/01/04
=======================++=======================================================
assets:depot || $3000 $1000 $1000 $3500
assets:shares || 0 10 TSLA 10 TSLA 0
revenue:capital_gains || 0 0 0 $-500
-----------------------++-------------------------------------------------------
|| $3000 $1000, 10 TSLA $1000, 10 TSLA $3000
```
## Further reading
- Beancount guides (general double-entry accounting advice from another tool)
- [Cookbook][beancount_cookbook]: Account naming, basic trading transactions
- [Trading guide][beancount_trading]: More complicated trading transactions, discussion on tricky cost basis adjustments
- [Github #624 on investment tracking](https://github.com/simonmichael/hledger/issues/624)
- [Discussion on investment modeling from the mailing list](https://groups.google.com/forum/#!topic/hledger/e8Ss7ZL4ADI)
[beancount_cookbook]: http://furius.ca/beancount/doc/cookbook
[beancount_trading]: http://furius.ca/beancount/doc/trading

124
site/more-docs.md
View File

@ -1,124 +0,0 @@
<style>
#toc > ol > li > a { display:none; }
#toc > ol > li > ol > li { padding-left:0; }
</style>
* toc
# More docs...
Most of this has been contributed to the new **[plaintextaccounting.org](http://plaintextaccounting.org)** site,
but not yet eg the [accounting](#accounting) links.
## Blog posts & articles
- Simon Michael:
[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
- Hacker News mentions:\
[Hledger – Double-entry accounting from the Unix tools perspective (2012)](https://news.ycombinator.com/item?id=8806056) 2014\
[Ledger, a powerful CLI accounting tool](https://news.ycombinator.com/item?id=7707262) 2014\
[Command Line Accounting With Ledger and Reckon](https://news.ycombinator.com/item?id=5233255) 2013\
[Ledger: Command-line double-entry accounting](https://news.ycombinator.com/item?id=872244) 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
Martin Blais' [beancount](http://furius.ca/beancount/) is another Ledger-inspired tool, written in Python.
It has good [documentation](http://furius.ca/beancount/doc/index), some of which may be useful to hledger users:
- Command-line Accounting in Context
- The Double-Entry Counting Method
- [Command-line Accounting Cookbook](http://furius.ca/beancount/doc/cookbook) example real-world journal entries
- A Comparison of Beancount and Ledger & HLedger
See also the two Twitter feeds:
- <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
-
[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
[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)
- [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 [bin/](https://github.com/simonmichael/hledger/tree/master/bin/)
## Scripting examples
- <https://gist.github.com/4172604> printing average expenses by month
- <https://gist.github.com/4210558> calculating historical account balances
- More in [bin/](https://github.com/simonmichael/hledger/tree/master/bin/)
## Similar projects
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)
- 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 [npo-acct](http://npoacct.sfconservancy.org) project

68
site/project-accounting.md
View File

@ -1,68 +0,0 @@
# Project accounting
Some ways to track small business/freelancer activity - orders, budgets, invoices, payments..
## Accrual method
Revenue is declared when work is performed:
```journal
; budget:* - virtual accounts tracking what customers have committed
; to pay for various things. Should not go below 0.
2017/10/30 Order from CUSTOMER (order id)
(budget:CUSTOMER:PROJECT_ID:pos1) 1000
(budget:CUSTOMER:PROJECT_ID:pos2) 3000
; some work was done on pos1 and pos2, invoice for it.
; Using accrual accounting method
; (revenue is declared when work is done, ~= when invoiced)
2017/10/31 Invoice (invoice id) - (PROJECT_ID)
(budget:CUSTOMER:PROJECT_ID:pos1) -500 ; update project budget
(budget:CUSTOMER:PROJECT_ID:pos2) -1000
assets:receivable:CUSTOMER:PROJECT_ID:pos1 500
assets:receivable:CUSTOMER:PROJECT_ID:pos2 1000
revenues:CUSTOMER
(liabilities:tax:federal) -150 ; note tax due, eg 15% of revenue
; a customer payment is received
2017/11/15 Payment for INVOICE_ID
assets:receivable:CUSTOMER:PROJECT_ID:pos1 -500
assets:receivable:CUSTOMER:PROJECT_ID:pos2 -1000
assets:bank:checking
; make a tax payment
2018/4/15 Pay taxes due from 2017
liabilities:tax:federal 5000
assets:bank:checking
```
## Cash method
Revenue is declared when payment is received:
```journal
2017/10/30 Order from CUSTOMER (order id)
(budget:CUSTOMER:PROJECT_ID:pos1) 1000
(budget:CUSTOMER:PROJECT_ID:pos2) 3000
; record an invoice sent. Not a real transaction in cash accounting,
; but we can balance it with the project budget as shown:
2017/10/31 Invoice (invoice id) - (PROJECT_ID)
budget:CUSTOMER:PROJECT_ID:pos1 -500
assets:receivable:CUSTOMER:PROJECT_ID:pos1 500
budget:CUSTOMER:PROJECT_ID:pos2 -1000
assets:receivable:CUSTOMER:PROJECT_ID:pos2 1000
; receive payment. Cash basis, so revenue declared here.
2017/11/15 Payment for INVOICE_ID
(assets:receivable:CUSTOMER:PROJECT_ID:pos1) -500
(assets:receivable:CUSTOMER:PROJECT_ID:pos2) -1000
revenues:CUSTOMER -1500
(liabilities:tax:federal) -150 ; note tax due, eg 15% of revenue
assets:bank:checking
; make a tax payment
2018/4/15 Pay taxes due from 2017
liabilities:tax:federal 5000
assets:bank:checking
```

61
site/start-journal.md
View File

@ -1,61 +0,0 @@
# Start a journal
## by hand
(power users)
The simplest possible journal is just an empty file:\
`echo >2017.journal`
The name doesn't matter much and can be changed later.
One file per year is common,
and so is a `.journal` or `.hledger` extension.
Record a transaction, using [journal format](/journal.html):
```shell
$ cat >>2017.journal
2017/1/26
expenses:food $10
assets:cash
<CTRL-D>
```
[Account names](/journal.html#account-names) can be anything
and you can change them later by search and replace.
If you don't know what to [choose](http://plaintextaccounting.org/#choosing-accounts),
start with these five:\
`expenses`, `income`, `assets`, `liabilities`, and `equity`,\
perhaps with one extra subcategory as above.
## by text editor
Write transactions in a [text editor](/journal.html#editor-support) and save the file.
## by add
Use the [add](/hledger.html#add) command:\
`hledger add -f 2017.journal`\
enter one or more transactions
## set `LEDGER_FILE`
To avoid typing `-f FILE` every time, set the
[`LEDGER_FILE` environment variable](/hledger.html#input-files). Eg:\
`echo "export LEDGER_FILE=~/finance/2017.journal" >> ~/.bash_profile && source ~/.bash_profile`
Most examples here assume you have done this.
## by hledger-iadd
ensure $LEDGER_FILE exists\
`hledger iadd`\
enter one or more transactions
## by hledger-web
ensure $LEDGER_FILE exists\
`hledger web`\
wait for web browser to open\
click "add transaction" or press "a"\
enter a transaction, click ok or press enter

697
site/step-by-step.md
View File

@ -1,697 +0,0 @@
<style>
#toc > ol > li > a { display:none; }
#toc > ol > li > ol > li { padding-left:0; }
</style>
* toc
# hledger Step by Step
Here you can learn hledger (and a little double-entry bookkeeping)
by practicing, one hands-on exercise at a time. You'll need:
1. A little familiarity with
the [command](http://tutorial.djangogirls.org/en/intro_to_command_line/index.html)
[line](https://en.flossmanuals.net/command-line/).
Or, the ability to ask for help on the IRC channel.
2. hledger. [Download](download.html) and install it if you haven't already.
You'll learn the most if you master each small step, in order. Most
steps give you a task with a clear goal; if not, your task is to run
the examples and understand them.
If you get stuck, find a problem, or have feedback, please report it on the
[IRC channel or mail list](contributing.html#quick-links),
or send a pull request for this page.
Let's get started!
<div class="clearfix"></div>
## SETUP
### Check your hledger installation
Get a command prompt, and run hledger to check the version. It should be reasonably [up to date](release-notes.html). These exercises were last tested with this version:
```shell
$ hledger --version
hledger 0.26
```
## 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 [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:
```shell
$ 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 [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.
```shell
$ hledger add
Creating hledger journal file "/home/YOU/.hledger.journal".
Adding transactions to journal file /home/YOU/.hledger.journal
Any command line arguments will be used as defaults.
Use tab key to complete, readline keys to edit, enter to accept defaults.
An optional (CODE) may follow transaction dates.
An optional ; COMMENT may follow descriptions or amounts.
If you make a mistake, enter < at any prompt to restart the transaction.
To end a transaction, enter . when prompted.
To quit, enter . at a date prompt or press control-d or control-c.
Date [2015/05/25]:
```
`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.
```{.shell .continued}
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.
```{.shell .continued}
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.
```{.shell .continued}
Amount 1: $10
```
The amount being "moved" to `expenses`. In this case 10 US dollars.
```{.shell .continued}
Account 2: assets
```
Next, specify which account the money comes from. Just say `assets`.
```{.shell .continued}
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 the 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.
```{.shell .continued}
Account 3 (or . to finish this transaction): .
```
Type `.` (period) and press enter.
```{.shell .continued}
2015/05/25 trip to the supermarket
expenses $10
assets $-10.0
Save this transaction to the journal ? [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.
```{.shell .continued}
Saved.
Starting the next transaction (. or ctrl-D/ctrl-C to quit)
Date [2015/05/25]: <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:
```shell
$ hledger stats
Main journal file : /home/YOU/.hledger.journal
Included journal files :
Transactions span : 2015-05-25 to 2015-05-26 (1 days)
Last transaction : 2015-05-25 (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 [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:
```shell
$ hledger print
2015/05/25 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`):
```shell
$ ls -l ~/.hledger.journal
-rw-r--r-- 1 YOU YOU 114 May 25 16:55 /home/YOU/.hledger.journal
$ cat ~/.hledger.journal
; journal created 2015-05-25 by hledger
2015/05/25 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).
Only one missing amount is allowed in each transaction.
`add` uses the same convention when it writes an entry.
(To see all such inferred amounts in full, you can use `hledger print -x`.)
### 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:
```shell
$ emacs ~/.hledger.journal
```
Remove the expenses amount and save the file. It now looks like this:
```journal
2015/05/25 trip to the supermarket
expenses
assets
```
Running `print` again, you should see:
```shell
hledger: could not balance this transaction (can't have more than one missing amount; remember to put 2 or more spaces before amounts)
2015/05/25 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:
```journal
2015/05/25 trip to the supermarket
expenses $10 ; <- problem: only one space between expenses and $10
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:
```journal
2015/05/25 trip to the supermarket
expenses $10
assets $10 ; <- deliberate problem: both amounts are positive
```
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:
```shell
$ hledger print
hledger: could not balance this transaction (real postings are off by $20)
2015/05/25 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:
```shell
$ hledger print
2015/05/25 trip to the supermarket
expenses $10
assets $-10
```
### 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:
```journal
2015/05/25 trip to the supermarket
expenses $10
assets $-10
2015/05/26 forgot the bread
expenses $5
assets
```
The blank line between transactions is customary, though not required.
Test your work with `print`. You should see:
```shell
$ hledger print
2015/05/25 trip to the supermarket
expenses $10
assets $-10
2015/05/26 forgot the bread
expenses $5
assets $-5
```
### Show postings and a running total with "hledger register"
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:
```shell
$ hledger register
2015/05/25 trip to the supermarket expenses $10 $10
assets $-10 0
2015/05/26 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 something like the below.
(On POSIX platforms, this command uses the terminal width so the output may look slightly different.
You can force it to look like the below by running `export COLUMNS=80` first:
```shell
$ hledger register expenses
2015/05/25 trip to the super.. expenses $10 $10
2015/05/26 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:
```shell
$ hledger register assets
2015/05/25 trip to the super.. assets $-10 $-10
2015/05/26 forgot the bread assets $-5 $-15
```
### Query expressions
The account name argument above is an example of a
[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.
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$`".
(In a regular expression `^` means "match at the beginning" and `$` means "match at the end".)
If this doesn't make sense, read a little about [regular expressions](manual.html#regular-expressions).
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 ends with "bread":
```shell
$ hledger print desc:bread$
2015/05/26 forgot the bread
expenses $5
assets $-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 only postings on or after a certain date to an account whose name contains "exp":
```shell
$ hledger register date:2015/5/26- exp
2015/05/26 forgot the bread expenses $5 $5
```
### Show accounts and their balances with "hledger 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:
```{.shell .nobold}
$ hledger balance
$-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:
```shell
$ 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 2015/5/26:
```shell
$ hledger balance date:2015/5/26
$-5 assets
$5 expenses
--------------------
0
```
As you can see from this, `balance` does not necessarily report
real-world account balances; 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:
```shell
$ hledger register date:2015/5/26
2015/05/26 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.
-->
## 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 [accounting equation](http://en.wikipedia.org/wiki/accounting_equation), which says
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 do 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:
```shell
$ hledger register desc:supermarket expenses
2015/05/25 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:
```shell
$ cat ~/.hledger.journal
2015/05/25 trip to the supermarket
expenses:supplies $10
assets:checking $-10
2015/05/26 forgot the bread
expenses:food $5
assets:cash
```
hledger will infer the chart of accounts from these names.
The `accounts` command will list all accounts posted to:
```shell
$ hledger accounts
assets:cash
assets:checking
expenses:food
expenses:supplies
```
and `accounts --tree` will show the tree structure, indenting subaccounts below their parents (and eliding the common part of their names):
```shell
assets
cash
checking
expenses
food
supplies
```
Conversely, the `balance` command shows the tree structure by default:
```shell
$ hledger balance
$-15 assets
$-5 cash
$-10 checking
$15 expenses
$5 food
$10 supplies
--------------------
0
```
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.)
To see full account names in a flat list, use `--flat`:
```shell
$ hledger balance --flat
$-5 assets:cash
$-10 assets:checking
$5 expenses:food
$10 expenses:supplies
--------------------
0
```
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 limit the amount of detail in a balance report by hiding accounts below a certain depth:
```shell
$ 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.
-->
<!-- TODO make date-independent -->

26
site/version-control.md
View File

@ -1,26 +0,0 @@
# Track changes with version control
You don't need to do this, but it's a nice way to keep track of changes to your data.
## git
Start tracking changes:\
`git init && git add 2017.journal && git commit 2017.journal -m "first commit"`
View uncommitted changes: `git status`, `git diff`
Commit changes: `git commit 2017.journal -m "updates"`
View past commits: `git log`
## darcs
`darcs init && darcs add 2017.journal && darcs record 2017.journal -m "first commit"`
`darcs whatsnew`, `darcs diff`
`darcs record 2017.journal -m "updates"`
`darcs log`
## etc.