From 7c5b97816e7d39859b1c6915049d7f0f650fffae Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Thu, 26 Jan 2017 14:19:59 -0800
Subject: [PATCH] doc: cookbook: journal starting and version control recipes

---
 Shake.hs                |  4 ++-
 site/docs.md            |  4 +++
 site/start-journal.md   | 57 +++++++++++++++++++++++++++++++++++++++++
 site/version-control.md | 26 +++++++++++++++++++
 4 files changed, 90 insertions(+), 1 deletion(-)
 create mode 100644 site/start-journal.md
 create mode 100644 site/version-control.md

diff --git a/Shake.hs b/Shake.hs
index 5962d7406..94e869aa9 100755
--- a/Shake.hs
+++ b/Shake.hs
@@ -140,7 +140,9 @@ main = do
       -- filenames are simple and stable as possible, beginning with TOPIC- prefix when appropriate
       -- titles are succinct and practical/action-oriented 
       cookbookpages = [
-         "site/entries.md"
+         "site/start-journal.md"
+        ,"site/version-control.md"
+        ,"site/entries.md"
         ,"site/csv-import.md"
         ,"site/account-aliases.md"
         ,"site/account-separator.md"
diff --git a/site/docs.md b/site/docs.md
index b170facf5..5b8623d3c 100644
--- a/site/docs.md
+++ b/site/docs.md
@@ -1,3 +1,5 @@
+<span style="float:right; font-size:small;">[improve this page](http://code.hledger.org/blob/master/site/docs.md)</span>
+
 # Documentation
 
 <style>
@@ -89,6 +91,8 @@ Practical recipes on one page, including:
 
 <div style="padding-left:0em;">
 
+[Start a journal](start-journal.html)\
+[Track changes with version control](version-control.html)\
 [Common journal entries](entries.html)\
 [Convert CSV files](csv-import.html)\
 [Rewrite account names](account-aliases.html)\
diff --git a/site/start-journal.md b/site/start-journal.md
new file mode 100644
index 000000000..325a24ae5
--- /dev/null
+++ b/site/start-journal.md
@@ -0,0 +1,57 @@
+# Start a journal
+
+## by hand
+
+(power users)
+
+The simplest possible journal is just an empty file:\
+`echo >2017.journal`
+
+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
+
+Use a [text editor](/journal.html#editor-support) to add transactions 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/version-control.md b/site/version-control.md
new file mode 100644
index 000000000..3e30ae1e6
--- /dev/null
+++ b/site/version-control.md
@@ -0,0 +1,26 @@
+# 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 "initial 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 "initial commit"`
+
+`darcs whatsnew`, `darcs diff`
+
+`darcs record 2017.journal -m "updates"`
+
+`darcs log`
+
+## etc.
\ No newline at end of file