Update some documentation with example

README.md

@@ -1,2 +1,29 @@
 # git-cache
-simple git cache management script
+A simple script to cache git repositories and packages locally. If git-cache
+has not been initialized, it will fall back to do checkouts from the remote
+repository. Otherwise it will transparently cache repositories in it's cache
+folder, ideally not touching the network if a requested commit / tag can be
+cloned from the cache.
+
+## Use Case
+This is particularly useful when many copies of a git repository are needed,
+such as when running a CI that requires a clean directory to build with.
+
+## Example Setup
+
+Either add the `git-cache` binary to the `PATH` or directly execute it.
+
+Initialize the git repository (by default it creates a `${HOME}/.gitcache`).
+```
+git-cache init
+```
+
+Use git-cache to clone the repository as needed.
+```
+git-cache clone https://github.com/MaxMusterman/ExampleRepo HEAD test1
+git-cache clone https://github.com/MaxMusterman/ExampleRepo HEAD test2
+```
+
+_The first clone may take a while since it needs to fetch the repo and add it
+to the cache. The second clone should be able to fetch the repo from the
+cache._

git-cache

@@ -232,17 +232,18 @@ usage() {
     echo ""
     echo "usage:"
     echo ""
-    echo "    git cache init                initialize git cache"
-    echo "    git cache add <url>           add repository <url>"
-    echo "    git cache list                list cached repositories"
-    echo "    git cache drop <url>          drop repo from cache"
-    echo "    git cache update [<url>]      fetch repo <url> (or all)"
-    echo "    git cache clone <url> <SHA1>  clone repository <url> from cache"
-    echo "    git cache show-path           print's the path that can be used as "
-    echo "                                  '--reference' parameter"
-    echo "    git cache cleanup             cleanup dangling temporary tags"
-    echo "                                  (appear if git-cache gets inter-"
-    echo "                                   rupted, but are harmless)"
+    echo "    git-cache init                    initialize git cache"
+    echo "    git-cache add <url>               add repository <url>"
+    echo "    git-cache list                    list cached repositories"
+    echo "    git-cache drop <url>              drop repo from cache"
+    echo "    git-cache update [<url>]          fetch repo <url> (or all)"
+    echo "    git-cache clone <url> [SHA1] [TARGET_PATH]"
+    echo "                                      clone repository <url> from cache"
+    echo "    git-cache show-path               print's the path that can be used as"
+    echo "                                      '--reference' parameter"
+    echo "    git-cache cleanup                 cleanup dangling temporary tags"
+    echo "                                      (appear if git-cache gets inter-"
+    echo "                                      rupted, but are harmless)"
     echo ""
     echo "To retrieve objects from cache (will use remote repository if needed):"
     echo '    git clone --reference $(git cache show-path) <repo>'