Add usage examples to README.md

README.md

@@ -2,7 +2,8 @@
 
 > NOTE: This project is *alpha* stage. Flags, configuration, behavior and design may change significantly in following releases.
 
-The jsonnet-bundler is a package manager for [jsonnet](http://jsonnet.org/).
+The jsonnet-bundler is a package manager for [Jsonnet](http://jsonnet.org/).
+
 
 ## Install
 
@@ -10,9 +11,67 @@ The jsonnet-bundler is a package manager for [jsonnet](http://jsonnet.org/).
 go get github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb
 ```
 
-## Usage
 
-All command line flags:
+## Features
+
+- Fetches transitive dependencies
+- Can vendor subtrees, as opposed to whole repositories
+
+
+## Current Limitations
+
+- Always clones entire dependent repositories, even when updating
+- If two dependencies depend on the same package (diamond problem), they must require the same version
+
+
+## Example Usage
+
+Initialize your project:
+
+```sh
+mkdir myproject
+cd myproject
+jb init
+```
+
+The existence of the `jsonnetfile.json` file means your directory is now a
+jsonnet-bundler package.
+
+To depend on another package (another Github repository):
+
+```sh
+jb install https://github.com/anguslees/kustomize-libsonnet
+```
+
+Now write `myconfig.jsonnet`, which can import a file from that package.
+
+```jsonnet
+local kustomize = import 'vendor/kustomize-libsonnet/kustomize.libsonnet';
+
+local my_resource = {
+  metadata: {
+    name: 'my-resource',
+  },
+};
+
+kustomize.namePrefix('staging-')(my_resource)
+```
+
+Depend on a package that is in a subtree of a Github repo (this package also
+happens to bring in a transitive dependency):
+
+```sh
+jb install https://github.com/coreos/prometheus-operator/jsonnet/prometheus-operator
+```
+
+Note that if you are copy pasting from the Github website's address bar,
+remove the `tree/master` from the path.
+
+If pushed to Github, your project can now be referenced from other packages in
+the same way.
+
+
+## All command line flags
 
 [embedmd]:# (_output/help.txt)
 ```txt
@@ -39,5 +98,5 @@ Commands:
   update
     Update all dependencies.
 
-
 ```
+