commit 12028bba143ea800e9014d88e9ddf142b3983e28
parent cdb8b96bc6050573c3da1eb02b371f567537fb8e
Author: Alex Balgavy <a.balgavy@gmail.com>
Date: Tue, 11 Feb 2020 12:35:21 +0100
Updated documentation
Diffstat:
| M | README.md | | | 35 | ++++++++++++++++++++--------------- |
| M | conf | | | 6 | ++++-- |
| M | conf.1 | | | 9 | ++++++--- |
| A | example-dot.map | | | 99 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
4 files changed, 129 insertions(+), 20 deletions(-)
diff --git a/README.md b/README.md
@@ -1,12 +1,17 @@
# conf - a personal configuration manager
## Installation
-1. Download the `conf` script, make it executable, and put it in your `$PATH`.
-2. Set value of `$DOTFILES` to the location of your dotfiles, either in the environment, or in the `conf` script itself.
-3. Set up your dotfiles hierarchy in any way you want.
-3. Put a map file in the root of $DOTFILES.
- This file defines how your dotfiles/folders map to other locations in your filesystem.
- By default, the file is named "dot.map", but this can be changed by manually editing the script.
-4. Use `conf`, and profit, maybe. Run `conf -h` or `conf -man` to get help.
+1. Download the `conf` script, make it executable, and put it in your `$PATH`. Perl is required, but should be installed by default on most UNIX systems. On Mac, you can `brew install thezeroalpha/formulae/conf`.
+2. Set the value of the `DOTFILES` variable to the location of your dotfiles, either in the environment (recommended), or in the `conf` script itself.
+3. Set up your dotfiles hierarchy in any way you want, see the FAQ below for an example.
+4. Create a map file; this file defines how your dotfiles/folders map to other locations in your filesystem.
+ You have three options, in ascending order of customization:
+ * 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).
+ * Or manually put a map file in the root of the directory defined in the `DOTFILES` variable.
+ By default, the file is named "dot.map", but this can be changed by manually editing the definition of `$MAPFILE` in the `conf` script.
+ * Or put the file wherever you want on your filesystem, and change the definition of `$MAPFILE` in the `conf` script accordingly.
+
+
+5. Use `conf`, and profit, maybe. Run `conf -h` or `conf -man` to get help.
## FAQ
### How do you write a map file?
@@ -35,8 +40,6 @@ If you have a dotfile directory hierarchy that looks like this:
Then the `dot.map` file listed in the `dotfiles` directory might look like this:
```map
-# 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.
shell:
- zprofile: ~/.zprofile
- zshrc: ~/.zshrc
@@ -52,7 +55,9 @@ tools:
-- config: ~/.config/polybar/config
```
-And would result in the following symbolic links:
+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.
+
+As long as the `DOTFILES` variable is set to `~/dotfiles`, running `conf link` would result in the following symbolic links:
* `~/.zprofile` pointing to `~/dotfiles/shell/zprofile`
* `~/.zshrc` pointing to `~/dotfiles/shell/zshrc`
@@ -69,24 +74,24 @@ Why do I think I'm so special that none of the existing ones are good enough?
Well, a few points about this manager:
* It manages your dotfiles, and does nothing else.
- It doesn't have git integration, it doesn't do any smart tracking, it doesn't replace your toilet paper - it just manages links between your configuration and the various configuration directories around your system.
+ 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.
You want git actions? Use git.
* It reads its configuration from a single, plain-text file that can be named whatever you want.
* It uses a configuration syntax that's intuitive _for me_.
-* It leverages the filesystem structure for simpler configuration.
-* It essentially runs anywhere out of the box.
+* It leverages the filesystem structure and environment variables for a simpler configuration.
+* 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.
All this to make a dotfiles manager that works exactly the way I want it to work.
### Why Perl?
Because:
-* It's ubiquitous.
+* It's basically ubiquitous.
* It's a step up from shell script in data structures, readability, maintainability, abstractions, etc.
* It's still low level enough to work with the shell and filesystem, unlike e.g. Python.
If I want to test for a file's existence, I can use `-e`, like in Bash.
Symlink functions are available without having to import anything.
-* It's powerful for text manipulation, because it has regex built straight into the language.
+* It's powerful for text manipulation, because it has regex built straight into the language, among other things.
* It's still quite fast.
In fact, it's super fast, compared to my previous version written in Bash.
On my computer, the "list all" operation is at least five times faster, and "check all" is at least seven times faster.
diff --git a/conf b/conf
@@ -379,8 +379,10 @@ This is a script to manage filesystem-wide symbolic links to your dotfiles (conf
The location of the map file is set in the script itself, using the $MAPFILE variable.
The default name of the mapfile is "dot.map", and it is located in the root of your dotfiles folder.
The location of your dotfiles is set either using the $DOTFILES environment variable, or inside the script itself.
-
-=head1 ARGUMENTS
+Every existing file will be backed up by appending the extension '.bak', before being overwritten.
+If a directory in the destination path doesn't exist, it is automatically created.
+`conf` doesn't remove empty directories after unlinking.
+When linking/unlinking you either provide the name of the top directory, or the full name of the mapped path (see examples below for more information).
=over 4
diff --git a/conf.1 b/conf.1
@@ -133,7 +133,7 @@
.\" ========================================================================
.\"
.IX Title "CONF 1"
-.TH CONF 1 "2020-01-31" "perl v5.30.1" "User Contributed Perl Documentation"
+.TH CONF 1 "2020-02-11" "perl v5.30.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@@ -170,8 +170,11 @@ This is a script to manage filesystem-wide symbolic links to your dotfiles (conf
The location of the map file is set in the script itself, using the \f(CW$MAPFILE\fR variable.
The default name of the mapfile is \*(L"dot.map\*(R", and it is located in the root of your dotfiles folder.
The location of your dotfiles is set either using the \f(CW$DOTFILES\fR environment variable, or inside the script itself.
-.SH "ARGUMENTS"
-.IX Header "ARGUMENTS"
+.PP
+Every existing file will be backed up by appending the extension '.bak', before being overwritten.
+If a directory in the destination path doesn't exist, it is automatically created.
+`conf` doesn't remove empty directories after unlinking.
+When linking/unlinking you either provide the name of the top directory, or the full name of the mapped path (see examples below for more information).
.IP "\(bu" 4
\&\fBlink [entry1 [entry2...]]\fR
.Sp
diff --git a/example-dot.map b/example-dot.map
@@ -0,0 +1,99 @@
+# Mappings for your dotfiles
+#
+# The format of this file is:
+# - comments:
+# - lines starting with '#' are comments
+# - a comment must be on its own line
+# - there are no multi-line comments
+# - whitespace:
+# - whitespace is ignored, except inside a mapping definition
+# (i.e. you can indent lines however you like, and insert blank lines)
+# - mappings:
+# - a mapping definition is: "source: destination"
+# - source paths are relative to $DOTFILES (set in scripts/conf, or from an environment variable)
+# - lines that don't start with a '-' (dash) are top-level directories or files inside $DOTFILES
+# - lines starting with n number of '-' (dashes) are files/directories n levels deep
+# (i.e. '- bin' is one level deep, '-- bin' is two levels deep, etc.)
+# - every file/directory that is not at the root level must be under some top directory
+# (i.e. you can't have a line starting with '-' as the first line of the mapfile)
+# - every mapping source must exist (conf will complain if it doesn't)
+#
+# For example, the map definitions:
+# vim:
+# - vimrc: ~/.vimrc
+# - autoload:
+# -- script1.vim: ~/.vim/autoload/script1.vim
+# -- script2.vim: ~/.vim/autoload/script2.vim
+# tmux/tmux.conf: ~/.tmux.conf
+# ghci: ~/.ghci
+#
+# Get parsed as:
+# vim/vimrc => ~/.vimrc
+# vim/autoload/script1.vim => ~/.vim/autoload/script1.vim
+# vim/autoload/script2.vim => ~/.vim/autoload/script2.vim
+# tmux/tmux.conf => ~/.tmux.conf
+# ghci => ~/.ghci
+#
+# And executed as the commands:
+# ln -svf "$DOTFILES/vim/vimrc" "~/.vimrc"
+# ln -svf "$DOTFILES/vim/autoload/script1.vim" "~/.vim/autoload/script1.vim"
+# ln -svf "$DOTFILES/vim/autoload/script2.vim" "~/.vim/autoload/script2.vim"
+# ln -svf "$DOTFILES/tmux/tmux.conf" "~/.tmux.conf"
+# ln -svf "$DOTFILES/ghci" "~/.ghci"
+#
+# Every existing file will be backed up by appending the extension '.bak', before being overwritten.
+# If a directory in the destination path doesn't exist, it is automatically created.
+# `conf` doesn't remove empty directories after unlinking.
+#
+# The arrows "x => y" mean:
+# - "source => name_of_symlink"
+# - "the symbolic link to x is y"
+# - "y points to x"
+#
+# When linking/unlinking you either provide the name of the top directory,
+# or the full name of the mapped path.
+
+# Custom scripts
+bin: ~/.bin
+scripts: ~/.scripts
+
+# Utilities
+ctags.d: ~/.ctags.d
+git:
+- gitconfig: ~/.gitconfig
+tmux:
+- tmux.conf: ~/.tmux.conf
+mpv: ~/.config/mpv
+joplin/keymap.json: ~/.config/joplin/keymap.json
+
+# X server
+Xresources: ~/.Xresources
+
+# Emacs config
+emacs:
+- emacs.d/themes: ~/.emacs.d/themes
+- emacs: ~/.emacs
+
+# All shell configs
+shell:
+- aliases: ~/.aliases
+- functions: ~/.functions
+- zprofile: ~/.zprofile
+- zshrc: ~/.zshrc
+- bash_profile: ~/.bash_profile
+- bashrc: ~/.bashrc
+- profile: ~/.profile
+- inputrc: ~/.inputrc
+
+# Vim config
+vim:
+- after: ~/.vim/after
+- autoload: ~/.vim/autoload
+- colors: ~/.vim/colors
+- compiler: ~/.vim/compiler
+- ftdetect: ~/.vim/ftdetect
+- plugin: ~/.vim/plugin
+- syntax: ~/.vim/syntax
+- ultisnips: ~/.vim/ultisnips
+- vimrc: ~/.vimrc
+
