README

   1 This package provides automatic synchronization of assorted dotfiles,
   2 simplifying the maintenance of a uniform configuration across several
   3 hosts.
   4
   5 The `original implentation`_ was by Steve Kemp.
   6
   7 _original implementation: http://dotfiles.repository.steve.org.uk
   8
   9 Installation
  10 ------------
  11
  12 To install dotfiles, you'll need to check out a copy of the source,
  13 either by using `git`:
  14
  15   $ git clone http://physics.drexel.edu/~wking/code/git/dotfiles.git
  16
  17 or by downloading and unpacking a tarball:
  18
  19   $ wget http://physics.drexel.edu/~wking/code/tar/dotfiles.tgz
  20   $ tar -xvf dotfiles.tgz
  21
  22 It's up to you where you keep the unpacked source.  Popular choices
  23 are `~/src/dotfiles` and `~/.dotfiles`.  Once you've unpacked the
  24 source, set the `DOTFILES_DIR` environment variable to the source
  25 directory:
  26
  27   $ export DOTFILES_DIR=~/src/dotfiles/
  28
  29 If you're using Git, you may have a choice of transport protocols for
  30 accessing the central repository.  Some protocols (e.g. SSH) often
  31 require you to authenticate before you are allowed access.  Because
  32 dotfiles will try and update your local repository as you log in, make
  33 sure you set up your authentication mechanism (e.g. SSH agent) before
  34 running `dotfiles.sh`.  If you don't want to bother authenticating,
  35 use a protocol that does not require authentication (e.g. HTTP) in
  36 your default pull URL.
  37
  38 If you aren't using Git, you'll need to set the `DOTFILES_TGZ`
  39 environment variable so dotfiles knows where to look for updated
  40 versions of your central source:
  41
  42   $ export DOTFILES_TGZ="http://physics.drexel.edu/~wking/code/tar/dotfiles.tgz"
  43
  44 Once you've setup the environment variables, you can run
  45 `bin/dotfiles.sh` to install dotfiles-controlled versions of any
  46 dotfiles that you don't already have.
  47
  48 Maintenance
  49 -----------
  50
  51 In order to stay abreast of changes to the central repository, you
  52 should run `dotfiles.sh` periodically.  An easy way to accomplish this
  53 is to source `${DOTFILES_DIR}/src/.bashrc.d/dotfiles` in your
  54 `~/.bashrc` (as I do at the end of my central `.bashrc`).  This will
  55 call `dotfiles.sh` whenever you open a Bash shell, ensuring you're
  56 always up-to-date at the start of your session.
  57
  58 After syncing with the central server, any local patches
  59 (`${DOTFILES_DIR}/local-patch/*.patch`) are applied and filenames
  60 `${DOTFILES_DIR}/local-patch/*.remove` are removed to adapt to the local
  61 system.  As with installation, symlinks are automatically created for
  62 any dotfile (`${DOTFILES_DIR}/XXX`) that does not already have a
  63 locally installed version (`~/XXX`).
  64
  65 If you followed the installation instructions above, you may have
  66 received warnings about files that you already have that dotfiles
  67 wants to control.  You have two options for dealing with these
  68 collisions:
  69
  70 1. Control the file yourself.  In this case, you should add the
  71    filename to a `local-patch/*.remove` file, so that dotfiles knows
  72    you've assumed control.
  73 2. Delegate control to dotfiles.  In this case, you should remove your
  74    local version of the file.  Dotfiles will symlink in its version
  75    the next time you run `dotfiles.sh`.  If you have many such files,
  76    `link.sh --force` will overwrite all of them at once.
  77
  78 Local differences
  79 -----------------
  80
  81 As we hinted at above, you can tailor how closely your local dotfiles
  82 installation tracks the central repository.  Using
  83 `local-patch/*.remove` allows you to select purely-local control for
  84 files.  When you only need a small tweak to central version, use
  85 `local-patch/*.patch`, giving some degree of shared control.  You run
  86
  87   $ cd "${DOTFILES_DIR}"
  88   $ ./bin/diff.sh --local-patch
  89
  90 To create `.patch` and `.remove` files that recreate your currently
  91 installed state from the current source state.  Edit (and optionally
  92 rename) these files to get the exact set of local adjustments you
  93 need.