46 RH401-6-en-1-20110713
Revision Control Concepts
What Is Revision Control?
Revision control software is a useful tool for system administrators who write scripts, write documentation, and develop configuration files. Revision control keeps a record of changes made to files under its control, but the only changes it can manage are the ones checked into it by the user. Subversion is a revision control system normally used for software development. We will use Subversion throughout this course to manage changes and revisions made in later lab exercises. Subversion maintains a history of the four W's of changes: who committed what changes to the storage system when and why. The user who commits changes is the who. Subversion calculates the what - the differences between the previous version of a file and the version being checked in. The time when the revisions are committed is the when. The log messages entered by the user explain why the changes were made. Since log messages document the reasons why changes are made, they are often used when building and releasing errata packages.
Revision control software does not replace communication or good management. It can help merge changes made by multiple users, but it isn't going to make sure the changes make sense together -- that is the human's job! Subversion does not check for syntax errors (although it can be configured to run syntax checkers). However, Subversion can make coordination of changes and repair of mistakes simple.
How Subversion Works
All the files and directories under Subversion control are stored in a central repository. A repository is a directory structure that contains a database, lock files, and other administrative files. The database in the repository stores all the information necessary to recreate any version of the files and the log messages submitted for all of the revisions. The repository may be stored in a local directory or it may be accessed remotely using ssh or WebDAV.
Files should never be edited in the repository directly. Instead, each user creates a personal working directory where changes are made. When a user wants to edit files stored in the Subversion repository, they check out current copies of those files into a Subversion working directory. Copies of those files are put into a Subversion working directory and they can be edited normally. After the changes have been made, the user commits the files back to the repository so other users can check them out and edit them further.
If a user has old, outdated copies of files from the repository, they can update them before they start work to get the latest versions of the files and minimize conflicts when they commit their changed copies. Once a user has files checked out of Subversion, the user typically keeps modifying them in an update-edit-commit cycle.
Each subdirectory of a Subversion working directory has a .svn directory. This directory contains important support files for Subversion so it can keep track of changes to the files in the working directory:
• .svn/entries lists each of the Subversion-managed files in the directory and some information about them.
• .svn/text-base contains the latest editions of files that were copied from the repository when svn update was executed. This allows for comparisons with working copies without having to access the repository.
Selecting a Repository
There are other files in this directory that haven't been mentioned. These files should never be edited by hand! Let Subversion manage them automatically.
Selecting a Repository
Later in this unit you will learn how to use Subversion with files in an existing repository. The repository could be a directory on the local computer or it may be accessed remotely through one of several access methods. The repository URL is specified when the project is originally checked out into a local Subversion working directory. The .svn/entries files in the working directory contain the repository URL so the URL doesn't have to be specified when working in the Subversion working directory.
Remote Repositories
Frequently the Subversion repository is hosted on a different machine than the Subversion working directory. In this case one of Subversion's remote access methods will have to be used to contact the repository. The available methods depends on which access methods the Subversion administrator has configured.
A simple method that allows secure read-write access is svn+ssh, which uses the ssh program for transport. This method requires shell access to the system hosting the Subversion repository. SSH public key authentication eliminates the need to enter a password multiple times when accessing the Subversion repository.
Chapter 4. Using Subversion to Manage Changes
48 RH401-6-en-1-20110713
Subversion Administration
Initializing a New Repository
The svnadmin create command creates a new repository. This command must be executed by a user who has write permissions to the directory where the repository will be created. Although a user can create a private repository, most repositories are used by multiple users on a system so root usually must create and secure system-wide repositories.
A simple way to set up a repository that will allow secure authentication is to allow Subversion over SSH (svn+ssh). Make sure the sshd daemon is started and is configured to start on boot. User accounts will have to be created and passwords assigned for each of the remote users who will access the repository.
Subversion Security
Once a new Subversion repository is created, determine which users need read-only and read- write access to the projects that will be added to the repository. The best way to handle this is to put all of the appropriate users into a group and make the db directory read-write and set- gid for that group. When two groups of users have conflicting security requirements, create two separate repositories for their projects.
[root@host ~]# groupadd -g 20000 svnuser [root@host ~]# chgrp -R svnuser $REPO_PATH [root@host ~]# chmod -R g+w $REPO_PATH/db
ACLs on ext3 filesystems can be used to restrict or allow access to a repository by additional groups or individual users.
Starting a Subversion Project
Starting a project in Subversion is very simple. First, create a directory and populate it with the initial revisions of files that make up the project. Create and populate subdirectories as needed. Once you have decided on your project directory structure and created your initial content, import it into your repository. Change into the top level directory of your new directory tree and type:
[user@host tmp]$ svn import $REPO_URL/newproject
Notice the name of the original directory used to organize the project and the name of the project in the repository do not have to be the same. Choose a short, but descriptive, project name so it is easy to identify it when listing a repository's contents.
The svn import command will recursively search through subdirectories. Like svn commit, the import command will open the default text editor for an initial log message. Since this is the original import of a project's content, the log message should briefly describe what the project is.
Other Revision Control Software
RCS is the great-grandfather of open source revision control software. It works on a single system (it doesn't have network capability) and works on the premise that users have to check
Other Revision Control Software
out locked copies of files they want to edit. The rcs RPM provides the suite of RCS tools and is supported with Red Hat Enterprise Linux.
CVS (Concurrent Versions System) is a popular revision control system. Its commands are accessed using cvs followed by a subcommand then options and arguments. The CVS
subcommands were based upon the RCS commands, except CVS provided functionality over a network with a central repository. Subversion was designed to function like CVS, but without some of its limitations.
The cvs RPM provides the CVS revision control system for Linux and is supported by Red Hat Enterprise Linux. The info pages for CVS are much more useful than the man pages. A good reference book for CVS is also available online at the following URL: http://cvsbook.red- bean.com/cvsbook.html.
Another distributed revision control system is Mercurial. It provides similar functionality to Subversion, but it is invoked as hg on the command line and it has additional subcommands that Subversion doesn't provide. Mercurial is written in Python and has an integrated web interface. Red Hat Enterprise Linux does not provide Mercurial at this time, but it is provided by Fedora. git is a distributed revision control system that operates on the principle that every working directory acts as a complete repository managing complete change history. Developers use git to coordinate and facilitate Linux kernel development. Like Mercurial, git is provided by Fedora, but not Red Hat Enterprise Linux at this time.
References
“Version Control with Subversion” book available on-line at http://svnbook.red- bean.com
Chapter 4. Using Subversion to Manage Changes
50 RH401-6-en-1-20110713
Practice Exercise
Preparing the Subversion Repository and Users
Before you begin...
In this lab one of your two machines will be referred to as desktopX and will host the Subversion repository. This machine should be your RHN Satellite Server since you will reinstall desktopY to complete later labs.
Your client machine, desktopY, will serve as the remote workstation of one of your Subversion users. Make sure the clocks on both of your machines are synchronized with each other. If you need to install packages, yum should already be configured on desktopX and desktopY.
Carefully perform the following steps. Ask your instructor if you have problems or questions. Your internal DNS servers have had some problems lately. The DNS administrators, Stan and Oliver, have been modifying configuration files in such a way they have been stepping on each others' changes. Your task is to deploy a Subversion server which will allow Stan and Oliver to work together and stop the configuration file conflicts.
Build a Subversion repository on desktopX that will allow two users, oliver and stan, to create projects and work collaboratively.
1. Reinstall desktopY with Red Hat Enterprise Linux 6 to prepare it for this and future lab exercises. PXE boot desktopY and select the “Install a standard RHEL 6 workstation” option. 2. Log in as root on desktopX and install Subversion if necessary. Create a repo named /var/
local/svn on desktopX while desktopY reinstalls. After the installation finishes, check if Subversion is installed on desktopY. If not, then install it on desktopY also.
3. On desktopX, create a group called svnuser with a group ID of 60000. Modify the Subversion repository so all users in that group can create and modify projects.
4. Create user accounts for oliver and stan on both workstations. Assign their accounts the password of password on both systems.
Make all necessary adjustments to their accounts to allow them to use Subversion from either host. Both users should be able to commit their changes to the Subversion repository without typing a password when they are logged into desktopY.
Other Revision Control Software
Practice Exercise
Starting a New Project in Subversion
Carefully perform the following steps. Ask your instructor if you have problems or questions. Set up a new project in the Subversion repository for DNS configuration files.
1. Log in as oliver on desktopX and create a subdirectory in Oliver's home directory called source. Create etc and var/named subdirectories below ~/source to provide a temporary DNS chroot hierarchy.
2. Use anonymous FTP to download all the files in /pub/materials/namedfiles from instructor.example.com into ~/source. Move the files into the appropriate directories in the temporary tree. Do not change their names at this time.
3. Have oliver create a new project called dnsfiles in the Subversion repository. The project should initially be populated with the files from his ~/source directory.
If the group ownership and permissions assigned to the repository are correct, Oliver should be able to create the project since he is a member of the svnuser group.
4. Confirm the files are safely in the repository. Check the dnsfiles project out from the Subversion repository on desktopX and compare its contents with the files in ~/source. 5. Remove the ~/source directory from Oliver's home directory once it is confirmed the DNS
Chapter 4. Using Subversion to Manage Changes
52 RH401-6-en-1-20110713
Revision Management with Subversion
Preparing to Use Subversion
When using Subversion with an existing repository, only a few basic commands are needed to get started. These commands will be introduced in the following pages. Before we examine them, there are a couple of configuration items that need to be taken care of.
Subversion requires an environment variable specify which text editor to use to enter log messages. Valid environment variables include EDITOR, VISUAL, or SVN_EDITOR. One of these environment variables should be defined in a Subversion user's .bash_profile configuration file.
export EDITOR=vim
In Red Hat Enterprise Linux 6 and recent Fedora versions, the Subversion RPM provides a configuration file for bash that teaches it how to complete Subversion sub-commands. The following added to a user's ~/.bashrc would activate this feature:
. /etc/bash_completion.d/subversion
Starting a Working Directory
The svn checkout command copies the files of a project from a repository into your current working directory. The Subversion administrator must provide the URL to the repository and the name of the project. Projects can be listed if only the URL to the repository is given:
[user@host ~]$ svn list file:///var/local/svn myproject/
oneproject/ twoproject/
... Output Omitted ...
A project is usually the relative path to a set of related files stored in the repository. A single Subversion repository can store several different projects in its database. Given the output above, the following command would checkout the oneproject project from the repository into a Subversion working directory called oneproject below your current directory:
[user@host ~]$ svn checkout file:///var/local/svn/oneproject A oneproject/index.html
A oneproject/images
A oneproject/images/banner.png A oneproject/images/logo.png Checked out revision 7.
The lines that start with an A indicate these files have been added from the repository into your Subversion working directory.
Committing Changed Files
After one has finished editing files in the Subversion working directory, the new revision needs to be put into the repository. The svn commit command accomplishes this task. Without
Updating a Working Directory
arguments, svn commit will recursively check the current directory and all subdirectories for changed files and commit them to the repository.
Log messages are critically important!
Before the commit completes, a text editor launches and prompts for a log message which will be associated with this revision. Log messages should be brief descriptions explaining why the changes were made for future reference. When the log message is brief, the -m option can specify the log message on the command line:
[user@host myproject]$ svn commit -m 'Restrict cracker.org host access.' Sending etc/hosts.deny
Transmitting file data . Committed revision 15.
Particular files can be committed individually. The following command is an example of committing a file that is finished when other files are not ready to be committed:
[user@host myproject]$ svn commit filename
Updating a Working Directory
As files are edited in a Subversion working directory and the changes are committed, so are the changes of co-workers. If the current Subversion working directory was checked out some time ago, it may not have the latest revision of the files that need to be edited. The svn update command contacts the repository and updates the Subversion working directory with the latest revisions committed. It's a good idea to run svn update at the start of the day (before you start work) and any time a co-worker may have revised a file you plan to edit. Like checkout, update outputs a line for each file updated starting with a letter to indicate the state of the file:
• U: The file in the working directory has been updated from the repository.
• G: A file in the working directory was in conflict but Subversion was able to update it and merge the changes automatically.
• A: There is a new file in your Subversion working directory from the repository.
• D: A file was deleted from the Subversion working directory and will be marked as deleted from the repository.
• ?: A file is in your working directory, but it does not correspond to anything in the repository, and it is not scheduled for addition to the repository.
Chapter 4. Using Subversion to Manage Changes
54 RH401-6-en-1-20110713
[user@host sample]$ svn commit -m "fixed michael's last name" Sending namelist
svn: Commit failed (details follow): svn: File '/sample/namelist' is out of date [user@host sample]$ svn update
C namelist
Updated to revision 29.
When a conflict occurs, four files can be consulted for a possible fix. In the example above, namelist.mine is the original working copy of the file that has the changes that were being committed before the conflict was flagged. namelist.r28 is the pristine version of the file before any changes were made and namelist.r29 is the new update that came from the repository. The file, namelist, is modified so all conflicts are delimited by <<<<<<<, =======, and >>>>>>> markers:
[user@host sample]$ ls
hello namelist.mine namelist.r29 sample2 sample4 namelist namelist.r28 sample1 sample3
[user@host sample]$ cat namelist ... Output omitted ... <<<<<<< .mine michael thomason ======= michael thompson >>>>>>> .r29 ... Output omitted ...
Once the conflict has been resolved, the svn resolved command will clean up the extra version files and ready the Subversion working directory for a commit:
[user@host sample]$ svn resolved namelist Resolved conflicted state of 'namelist'
[user@host sample]$ svn commit -m "fixed michael's last name" Sending namelist
Transmitting file data . Committed revision 30.
File Manipulation
Adding a new file to a Subversion repository is simple. Create the new file, run svn add
filename to schedule it for addition, and then run svn commit. There are two important
things to remember: first, svn add doesn't actually add the file to the repository immediately; it just schedules it for addition on the next svn commit. Second, svn commit can take one or more filenames as arguments and commit only those files. This is useful when working on multiple edits at the same time and a subset of the changes. The svn add command can also be used to add a directory to the repository.
svn add should not be used to start a new project. When an entire directory tree of files needs to be added the svn import command is used instead.
Scheduling a file for removal from the repository is very similar to adding a file. svn delete
filename deletes the file from the Subversion working directory and marks it for deletion from
the repository upon commit. However, the file is not completely removed from the repository. Subversion will record that the file no longer exists, but the repository still stores old revisions