aboutsummaryrefslogtreecommitdiff
path: root/README.md
blob: dbbc13afa59244641cf172c9fdf8317753447d4b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
# 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 a source directory.  This is
currently done through an environment variable. For example, to use a repository
at ~/projects/dotfiles, use:

* `CONF_SOURCE=~/projects/dotfiles`

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 `~/.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`.