1 This package provides automatic synchronization of assorted dotfiles,
2 simplifying the maintenance of a uniform configuration across several
5 The `original implementation`_ was by Steve Kemp.
7 .. _original implementation: http://dotfiles.repository.steve.org.uk
9 This package only contains the ``dotfiles.sh`` script which manages the
10 dotfiles framework. The files that are being managed live in separate
11 repositories. A stand-alone framework has two goals:
13 1. Allow others to reuse the framework with their own dotfile
15 2. Allow several concurrent repositories (e.g. public and private).
20 To install the distribution framework, just drop ``dotfiles.sh`` into
21 your ``PATH``. Also check that you have already installed the utilities
22 listed in the ``External utilities`` section of ``dotfiles.sh``.
24 Setting up managed repositories will look something like this::
26 $ mkdir ~/src/dotfiles
28 $ dotfiles.sh clone public wget http://example.com/public-dotfiles.tar.gz
29 $ dotfiles.sh patch public
30 $ dotfiles.sh link --force-file --dry-run public
31 $ dotfiles.sh link --force-file public
36 Once you've got your repository installed, just run::
38 $ dotfiles.sh --dotfiles-dir ~/src/dotfiles update
40 to fetch any new developments from the central source, apply local
41 patches, and link to any new files from your target directory. In
42 order to automate this, you may want to add this line to your
43 ``.bashrc``, which will update your dotfiles every time you start a new
44 Bash shell. Since dotfiles are not expected to change rapidly, the
45 ``update`` command remembers the last time it ran and only actually
46 performs the update if it has been at least a week since the last
49 If you're using Git, you may have a choice of transport protocols for
50 accessing the central repository. Some protocols (e.g. SSH) often
51 require you to authenticate before you are allowed access. Because
52 dotfiles will try and update your local repository as you log in, make
53 sure you set up your authentication mechanism (e.g. SSH agent) before
54 running ``dotfiles.sh``. If you don't want to bother authenticating,
55 use a protocol that does not require authentication (e.g. HTTP) in
56 your default pull URL.
61 After syncing with the central server, any local patches
62 (``${DOTFILES_DIR}/${REPO}/local-patch/*.patch``) are applied and
63 filenames ``${DOTFILES_DIR}/${REPO}/local-patch/*.remove`` are removed
64 to adapt to the local system. As with installation, symlinks are
65 automatically created for any dotfile
66 (``${DOTFILES_DIR}/${REPO}/patched-src/XXX``) that does not already
67 have a locally installed version (``${TARGET}/XXX``).
69 If you followed the installation instructions above, you may have
70 received warnings about files that you already have that dotfiles
71 wants to control. You have two options for dealing with these
74 1. Control the file yourself. In this case, you should add the
75 filename to a ``local-patch/*.remove`` file, so that dotfiles knows
76 you've assumed control.
77 2. Delegate control to dotfiles. In this case, you should remove your
78 local version of the file. Dotfiles will symlink in its version
79 the next time you run ``dotfiles.sh``. If you have many such files,
80 ``dotfiles.sh link --force`` will overwrite all of them at once.
82 You can use the ``diff`` command in ``dotfiles.sh`` to browse the
83 differences between your checked out source and installed targets.
84 The ``--local-patch`` option will record all such differences in the
85 ``local-patch`` directory for editing.
87 Additional repositories
88 -----------------------
90 Some dotfiles contain passwords, hostnames, or other personal
91 information. You may want to synchronize these files, but placing
92 them in a globally readable repository would not be a good idea. A
93 simple solution would be to distribute *all* your dotfiles through
94 secure channels (e.g. Git over SSH), but then nobody would benefit
95 from the cool tricks you've used in your non-sensitive dotfiles. A
96 better solution is to run two (or more) dotfiles repositories
97 concurrently, one for sensitive files and the other for public files.
98 Of course, you might also want to run concurrent repositories reason
99 besides privacy. Whatever your motivation, installing another
100 repository is the same as installing the first::
103 $ dotfiles.sh clone private git ssh://example.com/~/private-dotfiles.git
104 $ dotfiles.sh patch private
105 $ dotfiles.sh link --force-file private
107 Future calls to ``dotfiles.sh update`` will update all of your
108 repositories in turn.
113 ``dotfiles.sh`` is a script, so there are no compilation dependencies.
114 However, you will need sufficiently modern versions of the external
115 utilities it uses. They are listed at the beginning of
116 ``dotfiles.sh``, which should make it easy to select alternative
117 implementations if the version installed in your ``PATH`` is not up to
118 standard. For example, I just set things up on my university's archaic
119 SunOS 5.10 server (circa 2005), and I needed to install current
120 versions of ``bash``, ``ln`` (in the coreutils_ package), and ``tar``
121 to succesfully run a ``wget``-based dotfile repository.
123 .. _coreutils: http://www.gnu.org/software/coreutils/
128 This ``README`` is designed to get you started with this dotfiles
129 framework and give you a feel for the overall structure. For more
130 details, browse through the ``dotfiles.sh`` documentation, starting
138 http://blog.tremily.us/posts/dotfiles/
projects / dotfiles-framework.git / blob