etckeeper

Resources

From the etckeeper website:

etckeeper is a collection of tools to let /etc be stored in a git, mercurial, bazaar or darcs repository. This lets you use git to review or revert changes that were made to /etc. Or even push the repository elsewhere for backups or cherry-picking configuration changes.

It hooks into package managers like 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 version control.

Installation

USE flags

USE flags for sys-apps/etckeeper A collection of tools to let /etc be stored in a repository

`cron`	Install cron script
`test`	Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)

Data provided by the Gentoo Package Database · Last update: 2025-04-14 07:10 More information about USE flags

Emerge

Install sys-apps/etckeeper

root #emerge --ask sys-apps/etckeeper

Additional software

etckeeper supports the following version control systems:

Configuration

Files

The main configuration file is /etc/etckeeper/etckeeper.conf. Following configuration options in the main configuration file need specific settings:

FILE /etc/etckeeper/etckeeper.conf

# The VCS to use.
VCS="git"

...

# Options passed to git commit when run by etckeeper.
GIT_COMMIT_OPTIONS=""

...

# Etckeeper includes both a cron job and a systemd timer, which each
# can commit exiting changes to /etc automatically once per day.
# To enable the systemd timer, run: systemctl enable etckeeper.timer
# The cron job is enabled by default; to disable it, uncomment this next line.
AVOID_DAILY_AUTOCOMMITS=1

...

# Uncomment to avoid etckeeper committing existing changes to
# /etc before installation. It will cancel the installation,
# so you can commit the changes by hand.
AVOID_COMMIT_BEFORE_INSTALL=1

...

# Gentoo specific:                                                                                                                                                                                          
# For portage this is emerge
# For paludis this is cave
HIGHLEVEL_PACKAGE_MANAGER=emerge

# Gentoo specific:
# For portage this is qlist
# For paludis this is cave
LOWLEVEL_PACKAGE_MANAGER=qlist

...

# To push each commit to a remote, put the name of the remote here.
# (eg, "origin" for git). Space-separated lists of multiple remotes
# also work (eg, "origin gitlab github" for git).
PUSH_REMOTE=""

Service

Cron

The cron job is enabled by default, to disable it, uncomment following configuration entry:

FILE /etc/etckeeper/etckeeper.conf

...
#AVOID_DAILY_AUTOCOMMITS=1
..

systemd

To enable the systemd timer, run:

root #systemctl enable etckeeper.timer

Usage

Note
Before configuring etckeeper further, inspect first the README file and read the "Security warnings" section.

root #cd /etc

To add interesting files of the /etc directory to the repository, run following command: Command used below creates a .gitignore file in the /etc directory. If a .gitignore file already exist then the content inside a "managed by etckeeper" comment block will get updated. It sets up pre-commit hooks. This command does not commit files, but does git add all interesting files for an initial commit later.

root #etckeeper init

Using the sudo command credentials of the user will be stored in the repository:

user $sudo etckeeper init

Before initial commit inspect the files added to the repository f.e. the shadow file

root #cd /etc

root #

git status | grep shadow

        new file:   gshadow
        new file:   gshadow-
        new file:   pam.d/shadow
        new file:   shadow
        new file:   shadow-

Remove not interesting files from the repository

root #git rm -r --cached shadow*

Add not interesting files to the .gitignore file

root #echo shadow* >> /etc/.gitignore

Finally commit all changes in /etc to the repository. A commit message can be specified. It is possible to use the underlying VCS to commit manually. Note that etckeeper commit will notice if a user has used sudo or su to become root, and record the original username in the commit. At this time it is recommended to use the git-commit command.

root #git commit -a -m 'initial /etc commit'

If the initial version has been commited, from this time forward it is safe to use following command below to commit diffs:

user $sudo etckeeper commit new-changes

or:

root #etckeeper commit new-changes

Pack git repository to save disk space:

user $git gc

Troubleshooting

(Troubleshoot issues in this section. Separate issues by best describing the error with a new section name. Remove if no issues are known.)

Removal

Following commands deletes the /etc/.git directory: