From 053efeb23a16c63028e25d42eb942d8f84ef5534 Mon Sep 17 00:00:00 2001
From: Jonathan Lebon <jonathan@jlebon.com>
Date: Mon, 7 May 2018 09:41:27 -0400
Subject: [PATCH] docs: Add "Hello World" example

Let's get practical faster in the manual and have a simple "Hello World"
example right off the bat to hopefully make it easier to grok how OSTree
works.

Also some minor tweaks on wording around comparisons to git.

Closes: #1581
Approved by: cgwalters
---
 README.md                   |  6 ++--
 docs/manual/introduction.md | 71 ++++++++++++++++++++++++++++++++++---
 2 files changed, 70 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index c54151d1..36bcfc24 100644
--- a/README.md
+++ b/README.md
@@ -20,9 +20,9 @@ bootloader configuration.
 
 The core OSTree model is like git in that it checksums individual files and has
 a content-addressed-object store. It's unlike git in that it "checks out" the
-files via hardlinks, and they should thus be immutable. Therefore, another way
-to think of OSTree is that it's just a more polished version
-of
+files via hardlinks, and they thus need to be immutable to prevent corruption.
+Therefore, another way to think of OSTree is that it's just a more polished
+version of
 [Linux VServer hardlinks](http://linux-vserver.org/index.php?title=util-vserver:Vhashify&oldid=2285).
 
 **Features:**
diff --git a/docs/manual/introduction.md b/docs/manual/introduction.md
index 92fc45f2..c0113f5d 100644
--- a/docs/manual/introduction.md
+++ b/docs/manual/introduction.md
@@ -11,15 +11,78 @@ replicating them to clients.
 The underlying architecture might be summarized as "git for
 operating system binaries".  It operates in userspace, and will
 work on top of any Linux filesystem.  At its core is a git-like
-content-addressed object store, and layered on top of that is
-bootloader configuration, management of
-`/etc`, and other functions to perform an
-upgrade beyond just replicating files.
+content-addressed object store with branches (or "refs") to track
+meaningful filesystem trees within the store. Similarly, one can
+check out or commit to these branches.
+
+Layered on top of that is bootloader configuration, management of
+`/etc`, and other functions to perform an upgrade beyond just
+replicating files.
 
 You can use OSTree standalone in the pure replication model,
 but another approach is to add a package manager on top,
 thus creating a hybrid tree/package system.
 
+## Hello World example
+
+OSTree is mostly used as a library, but a quick tour of using its
+CLI tools can give a general idea of how it works at its most
+basic level.
+
+You can create a new OSTree repository using `init`:
+
+```
+$ ostree --repo=repo init
+```
+
+This will create a new `repo` directory containing your
+repository. Feel free to inspect it.
+
+Now, let's prepare some data to add to the repo:
+
+```
+$ mkdir tree
+$ echo "Hello world!" > tree/hello.txt
+```
+
+We can now import our `tree/` directory using the `commit`
+command:
+
+```
+$ ostree --repo=repo commit --branch=foo tree/
+```
+
+This will create a new branch `foo` pointing to the full tree
+imported from `tree/`. In fact, we could now delete `tree/` if we
+wanted to.
+
+To check that we indeed now have a `foo` branch, you can use the
+`refs` command:
+
+```
+$ ostree --repo=repo refs
+foo
+```
+
+We can also inspect the filesystem tree using the `ls` and `cat`
+commands:
+
+```
+$ ostree --repo=repo ls foo
+d00775 1000 1000      0 /
+-00664 1000 1000     13 /hello.txt
+$ ostree --repo=repo cat foo /hello.txt
+Hello world!
+```
+
+And finally, we can check out our tree from the repository:
+
+```
+$ ostree --repo=repo checkout foo tree-checkout/
+$ cat tree-checkout/hello.txt
+Hello world!
+```
+
 ## Comparison with "package managers"
 
 Because OSTree is designed for deploying core operating