README.md (4660B)
1 # conf - a personal configuration manager 2 ## Installation 3 1. Perl is required, but should be installed by default on most UNIX systems. 4 2. On Mac, you can `brew install thezeroalpha/formulae/conf`. 5 Alternatively, or on Linux, you can `make install`. 6 The third option is to download the `conf` script, make it executable, and put it in your `$PATH`. 7 3. Set the value of the `DOTFILES` variable to the location of your dotfiles, either in the environment (recommended), or in the `conf` script itself. 8 4. Set up your dotfiles hierarchy in any way you want, see the FAQ below for an example. 9 5. Create a map file; this file defines how your dotfiles/folders map to other locations in your filesystem. 10 You have three options, in ascending order of customization: 11 * Run `conf edit` to open the default file at the default location (named `dot.map` at the root of the directory in the `DOTFILES` variable). 12 * Or manually put a map file in the root of the directory defined in the `DOTFILES` variable. 13 By default, the file is named "dot.map", but this can be changed by manually editing the definition of `$MAPFILE` in the `conf` script. 14 * Or put the file wherever you want on your filesystem, and change the definition of `$MAPFILE` in the `conf` script accordingly. 15 6. Use `conf`, and profit, maybe. Run `conf -h` or `conf -man` to get help. 16 17 ## FAQ 18 ### How do you write a map file? 19 This is easier by example. 20 21 If you have a dotfile directory hierarchy that looks like this: 22 23 ``` 24 ~/dotfiles 25 ├── dot.map 26 ├── shell 27 │ ├── zprofile 28 │ └── zshrc 29 └── vim 30 │ ├── after 31 │ │ └── ftplugin 32 │ ├── autoload 33 │ └── vimrc 34 └── tools 35 ├── lfrc 36 └── polybar 37 └── config 38 39 ``` 40 41 Then the `dot.map` file listed in the `dotfiles` directory might look like this: 42 43 ```map 44 shell: 45 - zprofile: ~/.zprofile 46 - zshrc: ~/.zshrc 47 48 vim: 49 - after/ftplugin: ~/.vim/after/ftplugin 50 - autoload: ~/.vim/autoload 51 - vimrc: ~/.vimrc 52 53 tools/lfrc: ~/.config/lf/lfrc 54 tools: 55 - polybar: 56 -- config: ~/.config/polybar/config 57 ``` 58 59 Lines starting with '#' are comments, all other lines are interpreted. All file/directory names are relative to the value of the `DOTFILES` variable, which is set in the environment or explicitly inside the `conf` script itself. 60 61 As long as the `DOTFILES` variable is set to `~/dotfiles`, running `conf link` would result in the following symbolic links: 62 63 * `~/.zprofile` pointing to `~/dotfiles/shell/zprofile` 64 * `~/.zshrc` pointing to `~/dotfiles/shell/zshrc` 65 * `~/.vim/after/ftplugin` pointing to `~/dotfiles/vim/after/ftplugin` 66 * `~/.vim/autoload` pointing to `~/dotfiles/vim/autoload` 67 * `~/.vimrc` pointing to `~/dotfiles/vimrc` 68 * `~/.config/lf/lfrc` pointing to `~/dotfiles/tools/lfrc` 69 * `~/.config/polybar/config` pointing to `~/dotfiles/tools/polybar/config` 70 71 ### Why would you make _another_ dotfiles manager? 72 Valid question, there's so many dotfile managers already available. 73 Why do I think I'm so special that none of the existing ones are good enough? 74 75 Well, a few points about this manager: 76 77 * It manages your dotfiles, and does nothing else. 78 It doesn't have git integration, it doesn't do any smart tracking, it doesn't replace your toilet paper -- it just manages symbolic links between your configuration and the various configuration directories around your filesystem. 79 You want git actions? Use git. 80 * It reads its configuration from a single, plain-text file that can be named whatever you want. 81 * It uses a configuration syntax that's intuitive _for me_. 82 * It leverages the filesystem structure and environment variables for a simpler configuration. 83 * It essentially runs anywhere out of the box, as its only dependency is on Perl 5, which is generally available on almost any (modern) UNIX system. 84 85 All this to make a dotfiles manager that works exactly the way I want it to work. 86 87 ### Why Perl? 88 Because: 89 90 * It's basically ubiquitous. 91 * It's a step up from shell script in data structures, readability, maintainability, abstractions, etc. 92 * It's still low level enough to work with the shell and filesystem, unlike e.g. Python. 93 If I want to test for a file's existence, I can use `-e`, like in Bash. 94 Symlink functions are available without having to import anything. 95 * It's powerful for text manipulation, because it has regex built straight into the language, among other things. 96 * It's still quite fast. 97 In fact, it's super fast, compared to my previous version written in Bash. 98 On my computer, the "list all" operation is at least five times faster, and "check all" is at least seven times faster.