INSTALLATION
============


To install, you need to perform following steps:

1.  Clone repository to a stable place on your box

    For now, I'm going to assume it's local/mydots

        $ cd local/mydots

2.  Move (and merge if needed) your existing configs to dotfiles folder.
    Remove the dot from name, e.g.:

        $ mv ~/.gnucash dotfiles/gnucash

    If your configs live under `~/.config` folder, put them under a similar
    folder under dotfiles:

        $ mv ~/.config/dunst dotfiles/config/dunst

    Since unlike the "classic" scheme where dotfiles live right under $HOME,
    with ".config", you don't want to share *whole* config, so you need to
    tell dottum to look for link targets on *deeper* level.  This is done
    by adding entry to file "dotfiles/dotvault/subvaults":

        $ mkdir dotfiles/dotvault
        $ echo "config" >> dotfiles/dotvault/subvaults

    This will caulse dottum to look **inside** the `config` sub-folder
    rather than treat it as whole and create link at `~/.config`.  Note that
    you can do this at any depth, for example, in vault that keeps only host
    specific files, you can do

        $ echo "config/myapp/hosts" >> dotfiles/dotvault/subvaults

    and have dottum look for items *under* `config/myapp/hosts` and link them
    *under* `~/.config/myapp/hosts`, eg. `~/.config/myapp/hosts/foo ->
    ~/local/mydots/dotfiles/config/myapp/foo`

3.  Run dottum script with single argument: path to dotfiles folder (or how
    you named it), e.g.:

        $ dottum ~/local/mydots/dotfiles

    The script will create links back in your `$HOME`, uless they (or real
    files) did already exist, in which case it will only warn you.  This
    makes it easy to exclude some of your applications from some of your
    machines: just skip step 2 for them.

    Pro tip: Notice how the dottum script discovers your `.config/`-bound
    files such as dunst.

     1. The path you pointed to is "path/to/dotfiles", so this will be
        regarded as "base path" of your config pool.

     2. Any members of the *base* directory will be prefixed with single
        dot and symlinked *directly* to your home--just as the ancient
        tradition dictates.

     3. If the "base path" has neighbor called the same but with suffix
        `.config`, i.e. `path/to/dotfiles.config`, it will symlink all
        present members to `~/.config` path--just as XDG convention
        uses in its most common version.

     4. The case is similar for `.local/share` files; here you'll just need
        to go one step deeper: files that should be linked to `~/.local/share`
        should be in `dotfiles.local/share`.


Instructions for bash
---------------------

Although similar technique could be used for bash, I prefer to have defaults
specified by distro.  Therefore I use other technique:

Instead of step 2 above, move/merge your specific ~/.bashrc changes to either
one of these, or preferably, split them as needed:

    dotfiles/bash/main.bashrc
    dotfiles/bash/user/<your-username>.bashrc
    dotfiles/bash/host/<your-hostname>.bashrc
    dotfiles/bash/post.bashrc

Then, replace your ~/.bashrc with your default distro's one, commonly found
in /etc/skel/.bashrc, and use `dotfiles/bash/setup` to patch it:

    $ cp /etc/skel/.bashrc ~/
    $ local/mydots/dotfiles/bash/setup

From that point on, `.bashrc` will source appropriate fies for you, so do not
make any changes to your local `.bashrc`, unless you really want them to be
local, i.e. private only.


Instructions for Vim
--------------------

If you want to keep default vim-ish behavior and have all local config in
~/.vimrc, you can use above generic steps.  However, if you want to have
rather more sophisticated model, and for example use my vim configuration
as a starting point, do this instead of step 2:

1.  Merge your local ~/.vimrc into dotfiles/vim/vimrc

2.  Create a symlink to ~/.vim/vimrc:

        $ cd
        $ ln -s local/mydots/dotfiles/vim/vimrc .vimrc

You could actually have your .vimrc symlink point right to local/mydots/...
I find this more flexible, though.

### perlcritic_vim ###

Additionally, if you want to use perlcritic.vim, you need to:

*   install Perl::Critic (from CPAN)

*   put bin/perlcritic\_vim to your PATH


Instructions for git
--------------------

**Note**: For most of config I have shared, you will need at least git 1.8.
Without it, things will not work, and you might even end up with broken git!

However, if you only want to use the sharing/splitting mechanism, 1.7 *should*
be OK.  **No warranties**, though.

The pricnicple is the same as in bash section above: a new folder is created,
local config is split into parts per user/host or global one, and original
file becomes just a crossroads into these.

Except that since git does not support expansion in config paths, the file
must be created by a script.  So what you want to do is the same as for bash
above, except that instead of applying patch to your .gitconfig, you simply
delete it and run dotfiles/git/setup.

If you have a local changes that you don't want to share, you can either put
them into the re-created ~.gitconfig, or (as I prefer) in
dotfiles/git/private/gitconfig