From 7ffdcc509dd3841107d63bbeee871b05fecdae5e Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 7 Mar 2018 23:34:23 -0800 Subject: [PATCH] doc: move most non-manual docs to the wiki --- Shake.hs | 40 +- site/account-aliases.md | 51 --- site/account-separator.md | 48 -- site/argfiles.md | 80 ---- site/budgeting-and-forecasting.md | 323 -------------- site/csv-import.md | 59 --- site/docs.md | 94 +--- site/entries.md | 12 - site/faq.md | 286 ------------ site/investments.md | 145 ------- site/more-docs.md | 124 ------ site/project-accounting.md | 68 --- site/start-journal.md | 61 --- site/step-by-step.md | 697 ------------------------------ site/version-control.md | 26 -- 15 files changed, 8 insertions(+), 2106 deletions(-) delete mode 100644 site/account-aliases.md delete mode 100644 site/account-separator.md delete mode 100644 site/argfiles.md delete mode 100644 site/budgeting-and-forecasting.md delete mode 100644 site/csv-import.md delete mode 100644 site/entries.md delete mode 100644 site/faq.md delete mode 100644 site/investments.md delete mode 100644 site/more-docs.md delete mode 100644 site/project-accounting.md delete mode 100644 site/start-journal.md delete mode 100644 site/step-by-step.md delete mode 100644 site/version-control.md diff --git a/Shake.hs b/Shake.hs index 4c745554b..564dded2d 100755 --- a/Shake.hs +++ b/Shake.hs @@ -60,7 +60,6 @@ usage = unlines -- ,"./Shake infomanpages # generate info files for info" -- ,"./Shake webmanpages # generate individual web man pages 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 all # generate everything" ,"./Shake clean # clean generated files" @@ -155,28 +154,6 @@ main = do -- manuals rendered to markdown and combined, ready for web output by hakyll 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 manpageDir m | '_' `elem` m = "hledger-lib" @@ -266,7 +243,6 @@ main = do need $ webmanpages ++ [webmanall - ,guideall ,hakyllstd ] cmd Shell (Cwd "site") "hakyll-std/hakyll-std" "build" @@ -316,20 +292,6 @@ main = do ">>" webmanall :: Action ExitCode -- 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 "site/doc/*/.snapshot" %> \out -> do need [ webmanall ] @@ -359,7 +321,7 @@ main = do phony "clean" $ do putNormal "Cleaning generated files" removeFilesAfter "." webmanpages - removeFilesAfter "." [webmanall, guideall] + removeFilesAfter "." [webmanall] phony "Clean" $ do need ["clean"] diff --git a/site/account-aliases.md b/site/account-aliases.md deleted file mode 100644 index a2df9fbd9..000000000 --- a/site/account-aliases.md +++ /dev/null @@ -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). diff --git a/site/account-separator.md b/site/account-separator.md deleted file mode 100644 index 4b0966c8d..000000000 --- a/site/account-separator.md +++ /dev/null @@ -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 -``` diff --git a/site/argfiles.md b/site/argfiles.md deleted file mode 100644 index c6e77c5e4..000000000 --- a/site/argfiles.md +++ /dev/null @@ -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.) diff --git a/site/budgeting-and-forecasting.md b/site/budgeting-and-forecasting.md deleted file mode 100644 index f1d964abd..000000000 --- a/site/budgeting-and-forecasting.md +++ /dev/null @@ -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 -==========================++=========================================================================================================== - :Expenses || 5980.60 USD 3997.35 USD 4941.63 USD - :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 `` 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 `` 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 -==========================++=========================================================================================================== - :Expenses || 4.00 USD 12.95 USD 39.80 USD - :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 -==========================++============================================================================================================ - :Expenses || 4.00 USD 16.95 USD 56.75 USD - :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. diff --git a/site/csv-import.md b/site/csv-import.md deleted file mode 100644 index ec48119cb..000000000 --- a/site/csv-import.md +++ /dev/null @@ -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). diff --git a/site/docs.md b/site/docs.md index cbb319da7..f23e537b3 100644 --- a/site/docs.md +++ b/site/docs.md @@ -33,7 +33,6 @@ For more docs relevant to all ledger-likes, see [plaintextaccounting.org](http:/ ### What is hledger? An enhanced, well-documented rewrite of the original plain text accounting tool.\ [hledger intro](http://hledger.org)\ -[Frequently Asked Questions](faq.html)\ [Download](download.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? 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)\ - - -
- -## [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)\ - -
- - -
## [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) is for human-friendly approximate time logging -### Addon tools +
-[hledger-diff](http://hackage.haskell.org/package/hledger-diff) -shows differences in an account's transactions between one journal file and another. +
-[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) -is a curses-style replacement for hledger's add command. +## Wiki / Cookbook -[hledger-interest](http://hackage.haskell.org/package/hledger-interest) -generates interest transactions for an account according to various schemes. +Tutorials, how-tos and discussion of general topics. -[hledger-irr](http://hackage.haskell.org/package/hledger-irr) -calculates the internal rate of return of an investment account. +https://github.com/simonmichael/hledger/wiki -Some experimental tools: - -[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 - - -
+ diff --git a/site/entries.md b/site/entries.md deleted file mode 100644 index 51b9ef018..000000000 --- a/site/entries.md +++ /dev/null @@ -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 -``` - diff --git a/site/faq.md b/site/faq.md deleted file mode 100644 index 3543d66b6..000000000 --- a/site/faq.md +++ /dev/null @@ -1,286 +0,0 @@ - -* 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. - - - - - -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 -``` diff --git a/site/investments.md b/site/investments.md deleted file mode 100644 index 00f2b9b46..000000000 --- a/site/investments.md +++ /dev/null @@ -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 diff --git a/site/more-docs.md b/site/more-docs.md deleted file mode 100644 index f13d95846..000000000 --- a/site/more-docs.md +++ /dev/null @@ -1,124 +0,0 @@ - -* 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: - -- @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 - -- - [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 - -- printing average expenses by month -- 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 - diff --git a/site/project-accounting.md b/site/project-accounting.md deleted file mode 100644 index 80410d54b..000000000 --- a/site/project-accounting.md +++ /dev/null @@ -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 -``` diff --git a/site/start-journal.md b/site/start-journal.md deleted file mode 100644 index 870d72892..000000000 --- a/site/start-journal.md +++ /dev/null @@ -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 - -``` - -[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 - diff --git a/site/step-by-step.md b/site/step-by-step.md deleted file mode 100644 index 960e9cee3..000000000 --- a/site/step-by-step.md +++ /dev/null @@ -1,697 +0,0 @@ - -* 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! - -
-## 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]: -``` - -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 - -``` - - - - -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` - - - - -## 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 -``` - - - - - - - - diff --git a/site/version-control.md b/site/version-control.md deleted file mode 100644 index 07b822438..000000000 --- a/site/version-control.md +++ /dev/null @@ -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. \ No newline at end of file