document rtree

1 files changed, 53 insertions, 3 deletions

diff --git a/README.md b/README.md
index 057d0ba..4fbee32 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,12 @@ house for protection.
 Alternatively, the name can also be read as
 "[Go](https://golang.org)-[fu](http://www.retrologic.com/jargon/F/suffix-fu.html)".
 
+# Installation
+
+```bash
+$ make && make install
+```
+
 # List of applets
 
 ## `prettyprompt`
@@ -27,10 +33,54 @@ possible, e.g. if the cwd starts with `$GOPATH/src/`, that is shortened to
 
 ## `rtree`
 
-TODO: document
+This manages my Git repositories. Borrowing from the convention established by
+Go's `GOPATH`, the location of each local repository is defined by its remote
+URL. For example, this repo here will always be checked out at
 
-# Installation
+```
+$GOPATH/src/github.com/majewsky/gofu
+```
+
+The most common operation with `rtree` is to get a repository path:
 
 ```bash
-$ make && make install
+$ rtree get https://github.com/majewsky/gofu
+/x/src/github.com/majewsky/gofu
 ```
+
+This will automatically clone the repo if it has not been cloned yet. Git URL aliases [like
+these](https://github.com/majewsky/devenv/blob/2642c2e2040e029b4334d55f0714bb86fc24d4a9/toplevel/gitconfig#L55-L56) are
+supported. I use a [shell function called
+`cg`](https://github.com/majewsky/devenv/blob/2642c2e2040e029b4334d55f0714bb86fc24d4a9/toplevel/profile#L47-L50) that
+means `cd to git repository` and is based on `rtree get`:
+
+```bash
+$ pwd
+/home/stefan
+$ cg gh:majewsky/gofu
+$ pwd
+/x/src/github.com/majewsky/gofu
+```
+
+There are a few other subcommands in `rtree`:
+
+* `rtree drop <URL>` deletes the local repo identified by the given remote URL (after asking for confirmation).
+* `rtree repos` lists the paths (below `$GOPATH/src`) of all local repos.
+* `rtree remotes` lists the remote URLs of all local repos.
+* `rtree each <COMMAND>` executes the given command in each repository.
+* `rtree import <PATH>` takes a path to a local Git repo, and moves it to the correct place below `$GOPATH/src`.
+
+Finally, `rtree index` rebuilds the index file (`~/.rtree/index.yaml`) that all of these operations use to find repos
+and remotes. If a repo is checked out, but not yet indexed, the index entry will be added. If the repo for an index
+entry is missing, the user will be prompted about what to do:
+
+```
+$ rtree index
+repository /x/src/github.com/Masterminds/sprig has been deleted
+ [r] (r)estore from https://github.com/Masterminds/sprig
+ [d] delete from index
+ [s] skip
+```
+
+One of the intended usecases is that stuff below `$GOPATH/src` does not need to be backed up. As long as the index file
+`~/.rtree/index.yaml` is backed up, all repos can be restored in one step with `yes r | rtree index`.