Configuration File Version Control

Please note: The administration pages have all been migrated to the new PSF Systems Wiki. Please no longer add information to these pages. If you need access to the new wiki, please contact psf@python.org for details.

Bazaar Overview

We are using Bazaar to track files in /etc on python.org machines. Bazaar, also known as BZR, is a version-control system written in Python.

The home page for Bazaar is at http://bazaar-vcs.org/.

Send questions about the use of Bazaar on python.org to <amk at python.org>.

Directories tracked

On dinsdale:

/etc/  -- various directories tracked
/data/ -- initialized but nothing tracked yet

On ximinez:

/etc/  -- various directories tracked
/data/ -- MoinMoin configuration

On bag:

/etc/  -- various directories tracked

Bazaar cheatsheet

The command-line interface resembles that of CVS, but the executable is named bzr.

A more detailed introduction to Bazaar's basic features is part of the docs: http://doc.bazaar-vcs.org/bzr.dev/tutorial.htm

To get a list of available subcommands, run bzr help.

To get more details about one particular subcommand, run bzr help <command-name>.

Setting your ID

Bazaar remembers your ID and uses this ID when committing changes. If you're doing stuff as root, this means we won't know who made a particular change.

/usr/bin/bzr is a wrapper script that checks that the ID has been set, reporting an error and stopping when it hasn't been.

To set your ID, set the BZREMAIL environment variable:

export BZREMAIL=admin-person@python.org

Making changes

To commit a change: bzr commit -m "Add new virtual host" /etc

If you omit the path name, committing will search the entire repository containing the current directory, so you don't need to supply the path if you're currently in /etc. It's OK to commit only a portion of the tree; if you're in /etc/apache2 and do a commit specifying the current directory (bzr commit .), you'll only commit changes in /etc/apache2 and its subdirectories.

To back out an uncommitted change: bzr revert /etc/database.conf restores the last committed version of the file.

The revert subcommand works recursively on directories, so bzr revert /etc will undo all the changes you've made to the configuration files.

What have I changed?

bzr status lists the names of files that are different from the last committed version:

root@matterhorn:/etc# bzr status
removed:
  nanorc
added:
  vnc.conf
modified:
  syslog.conf
root@matterhorn:/etc#

To get a diff-style display of changes, use bzr diff:

root@matterhorn:/etc# bzr diff |less
=== removed file 'nanorc'
--- nanorc
+++ /dev/null
@@ -1,314 +0,0 @@
-## Sample initialization file for GNU nano
 ...
=== modified file 'syslog.conf'
--- syslog.conf
+++ syslog.conf
@@ -56,16 +56,3 @@
 #      *.=debug;*.=info;\
 #      *.=notice;*.=warn       /dev/tty8

-# The named pipe /dev/xconsole is for the `xconsole' utility.  To use it,
-# you must invoke `xconsole' with the `-file' option:
-#
-#    $ xconsole -file /dev/xconsole [...]
-#
-#
-daemon.*;mail.*;\
-       news.crit;news.err;news.notice;\
-       *.=debug;*.=info;\
-       *.=notice;*.=warn       |/dev/xconsole
-

The --diff-options switch can be used to change the output of the underlying diff program.

Adding/removing files

To begin tracking a new configuration file, it must be added to the repository and then committed:

bzr add /etc/database.conf
bzr commit -m "Add database config" /etc/

If you delete a tracked file using rm, Bazaar will notice it's gone and remove it from the repository when you commit:

root@matterhorn:/etc# rm database.conf
root@matterhorn:/etc# bzr status
removed:
  database.conf
root@matterhorn:/etc# bzr commit -m "Remove file"
missing database.conf
deleted database.conf
Committed revision 9.
root@matterhorn:/etc#

The bzr rm subcommand stops tracking a file, but does **not** remove the working copy in /etc.

Viewing history

bzr log displays all changes that have been made to the tracked files:

root@bag:/etc# bzr log |less
------------------------------------------------------------                   
revno: 3
committer: XXX@python.org
branch nick: etc
timestamp: Sat 2007-03-03 04:14:44 +0100
message:
  Add Apache files
------------------------------------------------------------
revno: 2
committer: XXX@python.org
branch nick: etc
timestamp: Sat 2007-03-03 00:16:43 +0100
message:
  Add a bunch of postfix config files.

...

Initializing a new machine

Here's how to set up the version control on a new system.

1. Initialize the /etc directory as a Bazaar repository.

bzr init /etc

This will create a directory called /etc/.bzr/ that stores the history of changes.

2. Make the 'add' and 'status' subcommands ignore all files by default.

bzr ignore '*'

This prevents a stray bzr add lacking arguments from adding lots and lots of files.

3. Manually add the files you want to track:

bzr add /etc/network/interfaces
bzr add /etc/apache2/httpd.conf
 ...

4. Commit for the first time:

cd /etc
bzr commit -m "Record configuration files"