-etckeeper is a collection of tools to let /etc be stored in a git
-repository. It hooks into apt to automatically commit changes made to /etc
-during package upgrades. It uses `metastore` to track file metadata that
+etckeeper is a collection of tools to let /etc be stored in a git,
+mercurial, or bazaar repository. It hooks into apt to automatically commit
+changes made to /etc during package upgrades. It tracks file metadata that
git does not normally support, but that is important for /etc, such as the
permissions of `/etc/shadow`. It's quite modular and configurable, while
-also being simple to use if you understand the basics of working with git.
-
+also being simple to use if you understand the basics of working with
+version control.
## security warnings
or copying these repositories, not to allow anyone else to see the data.
Since git mushes all the files into packs under the .git directory, the
-whole .git directory content needs to be kept secret. Also, since git
-doesn't keep track of the mode of files like the shadow file, it will check
-it out world readable, before etckeeper fixes the permissions. The tutorial
-has some examples of safe ways to avoid these problems when cloning an /etc
-repository.
+whole .git directory content needs to be kept secret. (Ditto for mercurial
+and .hg as well as bazaar and .bzr)
+
+Also, since revision control systems don't keep track of the mode of files
+like the shadow file, it will check out world readable, before etckeeper
+fixes the permissions. The tutorial has some examples of safe ways to avoid
+these problems when cloning an /etc repository.
-Also note that `etckeeper init` runs code stored in the git repository.
-So don't use it on git repositories from untrusted sources.
+Also note that `etckeeper init` runs code stored in the repository.
+So don't use it on repositories from untrusted sources.
## what etckeeper does
etckeeper has special support to handle changes to /etc caused by
installing and upgrading packages. Before apt installs packages,
-`etckeeper pre-apt` will check that /etc contains no uncommitted changes.
-After apt installs packages, `etckeeper post-apt` will add any new
+`etckeeper pre-install` will check that /etc contains no uncommitted changes.
+After apt installs packages, `etckeeper post-install` will add any new
interesting files to the repository, and commit the changes.
-git is designed as a way to manage source code, not as a way to manage
-arbitrary directories like /etc. This means it has a few limitations that
-etckeeper has to work around. These include file metadata storage,
-empty directories, and special files.
+Revsion control systems are designed as a way to manage source code, not as
+a way to manage arbitrary directories like /etc. This means there are a few
+limitations that etckeeper has to work around. These include file metadata
+storage, empty directories, and special files.
-git has only limited tracking of file metadata, being able to track the
-executable bit, but not other permissions or owner info. So file metadata
-storage is handled by `metastore`. Amoung other chores, `etckeeper init`
-sets up a `pre-commit` hook that uses `metastore` to store metadata about
-file owners, permissions, and even extended attributes into a
-`/etc/.metadata` file. This metadata is stored in git along with everything
-else, and can be applied if the repo should need to be checked back out.
+Most VCS, including git, mercurial and bazaar have only limited tracking of
+file metadata, being able to track the executable bit, but not other
+permissions or owner info. So file metadata storage is stored separately.
+Among other chores, `etckeeper init` sets up a `pre-commit` hook that stores
+metadata about file owners and permissions into a `/etc/.metadata` file.
+This metadata is stored in version control along with everything else, and
+can be applied if the repo should need to be checked back out.
-git cannot track empty directories, but they can be significant sometimes
-in /etc. So the `pre-commit` hook also stores information that can be used
-to recreate the empty directories in a `/etc/.etckeeper` file.
+git and mercurial cannot track empty directories, but they can be
+significant sometimes in /etc. So the `pre-commit` hook also stores
+information that can be used to recreate the empty directories in a
+`/etc/.etckeeper` file.
-git doesn't support several special files that you _probably_ won't have in
-/etc, such as unix sockets, named pipes, hardlinked files (but softlinks
-are fine), and device files. The `pre-commit` hook will warn if your /etc
-contains such special files.
+Most VCS, including git, mercurial, and bazaar don't support several
+special files that you _probably_ won't have in /etc, such as unix
+sockets, named pipes, hardlinked files (but softlinks are fine), and
+device files. The `pre-commit` hook will warn if your /etc contains
+such special files.
## tutorial
A quick walkthrough of using etckeeper.
- etckeeper init
+First, edit `/etc/etckeeper/etckeeper.conf` to select which version control
+system to use. The default is git, and this tutorial assumes you're using
+it. Mercurial and bazaar are similar.
The `etckeeper init` command initialises an /etc/.git/ repository. This
command is careful to never overwrite existing files or directories in
/etc. It will create a `.gitignore` if one doesn't already exist, sets up
-git hooks if they don't already exist, and so on. It does *not* commit any
-files into to git, but does `git-add` all interesting files for an initial
-commit. So you might want to use git status to check that it includes all
+pre-commit hooks if they don't already exist, and so on. It does *not*
+commit any files, but does `git add` all interesting files for an initial
+commit later.
+
+ etckeeper init
+
+Now you might want to run `git status` to check that it includes all
the right files, and none of the wrong files. And you can edit the
-.gitignore and so forth. Once you're ready:
+`.gitignore` and so forth. Once you're ready, it's time to commit:
cd /etc
git commit -m "initial checkin"
git gc # pack git repo to save a lot of space
-After this first checkin, you can use regular git commands to check in
+After this first commit, you can use regular git commands to handle
further changes:
passwd someuser
git status
git commit -a -m "changed a password"
-Rinse, lather, repeat.
+Rinse, lather, repeat. You might find that some files are changed by
+daemons and shouldn't be tracked by git. These can be removed from git:
+
+ git rm --cached printcap # modified by CUPS
+ echo printcap >> .gitignore
+ git commit -a -m "don't track printcap"
-etckeeper hooks into apt so changes to files in /etc caused by installing or
-upgrading packages will automatically be committed. (`etckeeper post-apt`
-uses `git-add .`, so any new files in /etc that arn't gitignored will be
-added. If it auto-adds files you don't want added, put them in
-`.gitignore`.)
+etckeeper hooks into apt so changes to interesting files in /etc caused by
+installing or upgrading packages will automatically be committed. Here
+"interesting" means files that are not ignored by `.gitignore`.
You can use any git commands you like, but do keep in mind that, if you
check out a different branch or an old version, git is operating directly
-on your system's /etc. Often it's better to clone /etc to elsewhere and do
-potentially dangerous stuff in a staging directory. You can clone the
-repository using git-clone, but be careful that the directory it's cloned
-into starts out mode 700, to prevent anyone else from seeing files like
-shadow, before `etckeeper init` fixes their permissions:
+on your system's /etc. But if you do decide to check out a branch or tag,
+make sure you run "etckeeper init" again, to get any metadata changes:
+
+ git checkout april_first_joke_etc
+ etckeeper init
+
+Often it's better to clone /etc to elsewhere and do potentially dangerous
+stuff in a staging directory. You can clone the repository using git clone,
+but be careful that the directory it's cloned into starts out mode 700, to
+prevent anyone else from seeing files like shadow, before `etckeeper init`
+fixes their permissions:
mkdir /my/workdir
cd /my/workdir
chmod 700 .
git clone /etc
cd etc
- etckeeper init .
+ etckeeper init -d .
chmod 755 ..
Another common reason to clone the repository is to make a backup to a
-server. When using git-push to create a new remote clone, make sure the new
+server. When using git push to create a new remote clone, make sure the new
remote clone is mode 700! (And, obviously, only push over a secure
transport like ssh, and only to a server you trust.)
## configuration
-etckeeper uses `run-parts` to run the executable files in
-`/etc/etckeeper/$command.d/`. You can modify these files, or add your own
-custom files. Each individual file is short, simple, and does only one
-action.
+The main configuration file is `/etc/etckeeper/etckeeper.conf`
+
+etckeeper runs the executable files in `/etc/etckeeper/$command.d/`. (It
+ignores the same ones that run-parts(1) would ignore.) You can modify these
+files, or add your own custom files. Each individual file is short, simple,
+and does only one action.
For example, here's how to configure it to run `git gc` after each apt run,
which will save a lot of disk space:
- cd /etc/etckeeper/post-apt.d
- (echo '#!/bin/sh' ; echo 'exec git-gc') > 99git-gc
+ cd /etc/etckeeper/post-install.d
+ (echo '#!/bin/sh' ; echo 'exec git gc') > 99git-gc
chmod +x 99git-gc
git add .
- git-commit -m "run git-gc after each apt run"
+ git commit -m "run git gc after each apt run"
Here's how to disable the automatic commits after each apt run, while still
-letting it git-add new files and git-rm removed ones:
-
- chmod -x /etc/etckeeper/post-apt.d/75git-commit
+letting it git add new files and git rm removed ones:
-Note that the etckeeper commands are careful to not hardcode anything about
-git. If you want to use some other revision control system, that's
-theoretically possible to accomplish by just changing the files in
-/etc/etckeeper/. If you do this, please let me know.
+ chmod -x /etc/etckeeper/commit.d/50vcs-commit
## inspiration
* http://www.jukie.net/~bart/blog/20070312134706
* http://bryan-murdock.blogspot.com/2007/07/put-etc-under-revision-control-with-git.html
-isisetup (http://www.isisetup.ch/) has some of the same aims as etckeeper,
-however, unlike it, etckeeper does not aim to be a git porcelain with its
-own set of commands for manipulating the /etc repository. Instead,
-etckeeper provides a simple setup procedure and hooks for setting up an /etc
-repsository, and then gets out of your way; you manage the repository using
-regular git commands.
+[isisetup][2] has some of the same aims as etckeeper, however, unlike it,
+etckeeper does not aim to be a git porcelain with its own set of commands
+for manipulating the /etc repository. Instead, etckeeper provides a simple
+setup procedure and hooks for setting up an /etc repository, and then gets
+out of your way; you manage the repository using regular VCS commands.
+
+ [2]: http://www.isisetup.ch/
## license
git.samba.org / jelmer / etckeeper.git / blobdiff