From Gentoo Wiki
Jump to: navigation, search

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.


USE flags

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

bazaar Support dev-vcs/bzr based repository
cron Install cron script


Install sys-apps/etckeeper

root #emerge --ask sys-apps/etckeeper

Additional software

etckeeper supports the following version control systems:



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.


# Options passed to git commit when run by etckeeper.


# 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.


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


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

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


# 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).



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

FILE /etc/etckeeper/etckeeper.conf


To enable the systemd timer, run:

root #systemctl enable etckeeper.timer


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


root #etckeeper commit new-changes

Pack git repository to save disk space:

user $git gc


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


Following commands deletes the /etc/.git directory:

root #etckeeper uninit

** Warning: This will DESTROY all recorded history for /etc,
** including the git repository.

Are you sure you want to do this? [yN]

Uninstall etckeeper:

root #emerge --ask --depclean sys-apps/etckeeper

See also

External resources