How etckeeper Tracks /etc via Git in Debian

The etckeeper utility automates version control for the /etc directory on Debian-based systems by turning the configuration folder into a Git repository. It operates seamlessly in the background, primarily hooking into the Debian package management workflow to automatically commit configuration snapshots before and after package installations, upgrades, or removals. This article explains how etckeeper initializes Git in /etc, integrates with APT hooks, preserves system file metadata, and allows administrators to inspect and revert system configuration changes.

Git Repository Initialization in /etc

When installed on Debian, etckeeper runs an initialization script that executes git init directly inside the /etc directory, creating /etc/.git. Unlike standard Git repositories, etckeeper manages existing system configurations immediately by staging and creating an initial baseline commit. It also generates an /etc/.gitignore file preconfigured with Debian-specific patterns to exclude volatile, binary, and temporary files—such as cache directories, .dpkg-old files, and secrets that should not be tracked.

APT Package Manager Integration

The core mechanism of etckeeper on Debian is its deep integration with the APT packaging system. During installation, it registers pre-install and post-install hooks via configuration files placed in /etc/apt/apt.conf.d/ (specifically 05etckeeper).

Pre-install hook: Before APT executes dpkg to install, upgrade, or remove packages, etckeeper checks for any uncommitted manual changes in /etc and commits them. This ensures manual edits are cleanly isolated from package-induced modifications.
Post-install hook: Once the package management operation completes, etckeeper automatically detects any configuration changes made by the newly installed packages or maintenance scripts and records a new commit containing the package transaction details.

Preserving File Permissions and Metadata

Standard Git repositories only track content and whether a file is executable; they do not preserve file ownership (UID/GID) or specific POSIX permission modes. Because security in /etc relies heavily on strict file permissions (such as /etc/shadow), etckeeper manages a special metadata file named /etc/.etckeeper.

Before each Git commit, etckeeper scans /etc and writes the ownership, permissions, and extended attributes of every tracked file into the .etckeeper file, which is then committed along with the file content. If files are restored or checked out using Git, etckeeper reads this metadata file to restore the original ownership and file modes accurately.

Capturing Manual Modifications

For changes made directly by system administrators outside of APT, etckeeper provides multiple capture paths:

Manual Commits: Administrators can run etckeeper commit "description" or use standard Git commands inside /etc (such as sudo git commit -m "message") to document edits.
Automated Timers: Debian ships etckeeper with a systemd timer (etckeeper.timer) or a daily cron job (/etc/cron.daily/etckeeper). Once per day, this service checks /etc for uncommitted modifications and creates an automated commit if differences are detected, preventing unrecorded manual edits from being lost.

Auditing and Rollbacks

Because the underlying store is a standard Git repository, auditing changes requires only standard Git tooling executed inside /etc. Administrators can view revision history using git log, inspect configuration diffs using git diff, or revert unwanted modifications using git checkout or git revert. When changes are restored, executing etckeeper init reapplies the correct metadata stored in /etc/.etckeeper, ensuring system security remains intact.