This package provides automatic synchronization of assorted dotfiles,
simplifying the maintenance of a uniform configuration across several
hosts.

The `original implementation`_ was by Steve Kemp.

.. _original implementation: http://dotfiles.repository.steve.org.uk

This package only contains the ``dotfiles.sh`` script which manages the
dotfiles framework.  The files that are being managed live in separate
repositories.  A stand-alone framework has two goals:

1. Allow others to reuse the framework with their own dotfile
   repositories.
2. Allow several concurrent repositories (e.g. public and private).

Installation
------------

To install the distribution framework, just drop ``dotfiles.sh`` into
your ``PATH``.  Also check that you have already installed the utilities
listed in the ``External utilities`` section of ``dotfiles.sh``.

Setting up managed repositories will look something like this::

  $ mkdir ~/src/dotfiles
  $ cd ~/src/dotfiles
  $ dotfiles.sh clone public wget http://example.com/public-dotfiles.tar.gz
  $ dotfiles.sh patch public
  $ dotfiles.sh link --force-file --dry-run public
  $ dotfiles.sh link --force-file public

Maintenance
-----------

Once you've got your repository installed, just run::

  $ dotfiles.sh --dotfiles-dir ~/src/dotfiles update

to fetch any new developments from the central source, apply local
patches, and link to any new files from your target directory.  In
order to automate this, you may want to add this line to your
``.bashrc``, which will update your dotfiles every time you start a new
Bash shell.  Since dotfiles are not expected to change rapidly, the
``update`` command remembers the last time it ran and only actually
performs the update if it has been at least a week since the last
update.

If you're using Git, you may have a choice of transport protocols for
accessing the central repository.  Some protocols (e.g. SSH) often
require you to authenticate before you are allowed access.  Because
dotfiles will try and update your local repository as you log in, make
sure you set up your authentication mechanism (e.g. SSH agent) before
running ``dotfiles.sh``.  If you don't want to bother authenticating,
use a protocol that does not require authentication (e.g. HTTP) in
your default pull URL.

Local differences
-----------------

After syncing with the central server, any local patches
(``${DOTFILES_DIR}/${REPO}/local-patch/*.patch``) are applied and
filenames ``${DOTFILES_DIR}/${REPO}/local-patch/*.remove`` are removed
to adapt to the local system.  As with installation, symlinks are
automatically created for any dotfile
(``${DOTFILES_DIR}/${REPO}/patched-src/XXX``) that does not already
have a locally installed version (``${TARGET}/XXX``).

If you followed the installation instructions above, you may have
received warnings about files that you already have that dotfiles
wants to control.  You have two options for dealing with these
collisions:

1. Control the file yourself.  In this case, you should add the
   filename to a ``local-patch/*.remove`` file, so that dotfiles knows
   you've assumed control.
2. Delegate control to dotfiles.  In this case, you should remove your
   local version of the file.  Dotfiles will symlink in its version
   the next time you run ``dotfiles.sh``.  If you have many such files,
   ``dotfiles.sh link --force`` will overwrite all of them at once.

You can use the ``diff`` command in ``dotfiles.sh`` to browse the
differences between your checked out source and installed targets.
The ``--local-patch`` option will record all such differences in the
``local-patch`` directory for editing.

Additional repositories
-----------------------

Some dotfiles contain passwords, hostnames, or other personal
information.  You may want to synchronize these files, but placing
them in a globally readable repository would not be a good idea.  A
simple solution would be to distribute *all* your dotfiles through
secure channels (e.g. Git over SSH), but then nobody would benefit
from the cool tricks you've used in your non-sensitive dotfiles.  A
better solution is to run two (or more) dotfiles repositories
concurrently, one for sensitive files and the other for public files.
Of course, you might also want to run concurrent repositories reason
besides privacy.  Whatever your motivation, installing another
repository is the same as installing the first::

  $ cd ~/src/dotfiles
  $ dotfiles.sh clone private git ssh://example.com/~/private-dotfiles.git
  $ dotfiles.sh patch private
  $ dotfiles.sh link --force-file private

Future calls to ``dotfiles.sh update`` will update all of your
repositories in turn.

Dependencies
------------

``dotfiles.sh`` is a script, so there are no compilation dependencies.
However, you will need sufficiently modern versions of the external
utilities it uses.  They are listed at the beginning of
``dotfiles.sh``, which should make it easy to select alternative
implementations if the version installed in your ``PATH`` is not up to
standard.  For example, I just set things up on my university's archaic
SunOS 5.10 server (circa 2005), and I needed to install current
versions of ``bash``, ``ln`` (in the coreutils_ package), and ``tar``
to succesfully run a ``wget``-based dotfile repository.

.. _coreutils: http://www.gnu.org/software/coreutils/

Help
----

This ``README`` is designed to get you started with this dotfiles
framework and give you a feel for the overall structure.  For more
details, browse through the ``dotfiles.sh`` documentation, starting
with::

  $ dotfiles.sh --help

Homepage
--------

http://blog.tremily.us/posts/dotfiles/