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.

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.

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/