Add readme

1 files changed, 73 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c21d738
--- /dev/null
+++ b/README.md
@@ -0,0 +1,73 @@
+# conf - a simple dotfile management tool
+
+## Motivation
+
+I've used many tools to manage my dotfiles over the years. I've used a repo with
+an install script, GNU stow, and most recently, Ansible. Conf is an attempt to
+take the good parts of each approach and build a highly specific yet flexible
+tool for dotfile management.
+
+## Installation
+
+go get git.sr.ht/~benburwell/conf
+
+## Usage
+
+To start using conf, you'll need to specify source and destination directories.
+This is currently done through environment variables. For example, to target
+dotfiles in your home directory from a repository at ~/projects/dotfiles, use:
+
+* `CONF_SOURCE=~/projects/dotfiles`
+* `CONF_DEST=~`
+
+Now, you can start adopting dotfiles for conf to manage. Let's start with
+`.vimrc`:
+
+```
+$ conf adopt .vimrc
+```
+
+You can run this command from anywhere on your system, and conf will place a
+copy of your `$CONF_DEST/.vimrc` file into `$CONF_SOURCE/templates/.vimrc`.
+
+Open up `$CONF_SOURCE/templates/.vimrc`, make a change, and then run `conf apply
+.vimrc`. You'll see that conf has updated your vimrc file with your latest
+changes. Like `conf adopt`, this command can be run from anywhere on your
+system; `.vimrc` in this case is relative to `$CONF_SOURCE`, not to your current
+directory.
+
+If you typically use Vim, you may wish to add the following to your .vimrc:
+
+```vimscript
+au BufWritePost ~/dotfiles/templates/* call ConfApply(expand('%:p'))
+
+function! ConfApply(name)
+  let l:rel = substitute(a:name, "^".expand("~/dotfiles/templates/"), "", "")
+  silent execute "!conf apply " . l:rel
+endfunction
+```
+
+Any time you write changes to a file in your dotfiles, conf will automatically
+apply them.
+
+You may have noticed that your source dotfiles are in a directory named
+"templates". This is because you can use Go's templating engine to enhance your
+dotfiles. For example, you may want to include OS-dependent behavior:
+
+```
+{{ if eq OS "darwin" }}
+export OPENER=open
+{{ else }}
+export OPENER=xdg-open
+{{ end }}
+```
+
+The following variables are available for you:
+
+* `OS`
+* `Arch`
+* `Hostname`
+* `Home`
+
+If you want to define your own variables, you may do so in
+`$CONF_SOURCE/vars.toml` and they will be available under `.Vars`.