unx30.htm

Unix Unleashed, Third Edition is written with the power user and system administrator in mind. This

<P>The file revbranch should contain the following:

<BR></P>

<PRE>A line in the base file

Another line in the base file

A third line in the base file

A line added in revbranch

The final line of the base file</PRE>

<P>After you create these three files, type merge -p revmain base revbranch &gt; merged. When you look at the resulting file merged, you should see the following:

<BR></P>

<PRE>A line in the base file

A line added in revmain

Another line in the base file

A third line in the base file

A line added in revbranch

The final line of the base file</PRE>

<P>Because the merge process is automated and not intelligent, it can run into problems trying to merge changes that are in conflict. Try rerunning the merge command after changing the contents of revbranch to the following:

<BR></P>

<PRE>A line in the base file

A line added in revbranch

Another line in the base file

A third line in the base file

The final line of the base file</PRE>

<P>This time you should wind up with significantly different results. First, you should get a warning message from merge that says something like this: merge warning: overlaps or other problems during merge. Second, the file merged should look something 
like this:

<BR></P>

<PRE>A line in the base file

&lt;&lt;&lt;&lt;&lt;&lt;&lt; revmain

A line added in revmain

=======

A line added in revbranch

&gt;&gt;&gt;&gt;&gt;&gt;&gt; revbranch

Another line in the base file

A third line in the base file

The final line of the base file</PRE>

<P>When you try to merge files that have overlaps of the changed areas of the file, you will need to resolve the conflicts. You will need to manually review the merged file for all of the conflict areas marked. Some commercial source control systems and 
other products include graphical tools to help perform and verify merges.

<BR></P>

<H4 ALIGN="CENTER">

<CENTER><A ID="I12" NAME="I12">

<FONT SIZE=3><B>Symbolic Names, Baselines, and Releases</B>

<BR></FONT></A></CENTER></H4>

<P>A symbolic name is a name that is attached to a particular revision of a file and that you can use to check out the desired revision of a file without having to know the exact revision number. For example, if you send out for review copies of your great 

American novel, you might want to attach symbolic names to the revisions of the chapters you sent out so you can effectively use any editorial comments you get back.

<BR></P>

<HR ALIGN=CENTER>

<NOTE>

<IMG SRC="note.gif" WIDTH = 35 HEIGHT = 35>SCCS does not support symbolic names. Some uses of symbolic names can be replaced by using SCCS release numbers. For other uses it is possible to replicate the behavior of symbolic names by keeping the 
correspondence between names, files, and revision numbers in an outside file or database and implementing scripts that will perform SCCS operations based on that configuration information.

<BR></NOTE>

<HR ALIGN=CENTER>

<P>See Figure 30.8 for an example of how you might use symbolic names to record reviews of your novel. Your novel in this example has three chapters. For the first review, you sent revision 1.3 of Chapter 1 and only had the original outlines for Chapters 2 

and 3 (both revision 1.1). You used the name REVIEW1 for this review. For the second review, you had made minor changes to Chapter 1 (in revision 1.4) and had written Chapter 2 (revision 1.3) and drafted Chapter 3 (revision 1.2). This review was marked 
REVIEW2. You can now use the REVIEW1 and REVIEW2 names to refer to the correct versions of the novel to remember which revision of which chapter that meant. Revision names are a powerful tool for performing baselines and releases.

<BR></P>

<BR><B><A HREF="30unx08.gif">Figure 30.8. Symbolic names.</A></B>

<BR>

<P>A baseline is a captured set of revisions that have some special property. That property might be &quot;sent out for review,&quot; &quot;compiles successfully,&quot; &quot;passes lint successfully,&quot; &quot;released for alpha testing,&quot; or 
anything that you find useful. In the example on symbolic names, the files of REVIEW1 and REVIEW2 were baselines. A release is really a special kind of baseline with the property &quot;released,&quot; and you can decide exactly what you mean by released. 
Often, when you declare a release, you will check in new trunk revisions of all of your files so that you can use release numbers on source control commands.

<BR></P>

<H5 ALIGN="CENTER">

<CENTER><A ID="I13" NAME="I13">

<FONT SIZE=3><B>Using Releases to Replace Symbolic Names</B>

<BR></FONT></A></CENTER></H5>

<P>Without symbolic names you can achieve a similar effect using release numbers. Every time you ship out your novel for review, you increase the revision number of all files after the release. This allows you to use checkout commands that name the 
release, which in both RCS and SCCS check out the highest level within a release. In this example, after shipping release, you check in the next revision of the file as release 2, level 1. Therefore, instead of REVIEW1, you use release 1, which includes 
chap1 revision 1.3, chap2 revision 1.1, and chap3 revision 1.1. When you make you minor revisions to chap1, you check them in as revision 2.1. When you write and then rewrite chap2, you check it in as revision 2.1 and then as 2.2. When you draft chap3 you 

check it in as revision 2.1. Instead of REVIEW2, you use release 2, which includes chap1 revision 2.1, chap2 revision 2.2, and chap3 revision 2.1. This achieves the same effect (but with slightly more effort) as using symbolic names. Unfortunately, this 
approach is not always able to replace symbolic names. If you have checked in a new revision of a file using the old release number before deciding that you want to release the files, you may face some difficulties using this method.

<BR></P>

<H3 ALIGN="CENTER">

<CENTER><A ID="I14" NAME="I14">

<FONT SIZE=4><B>Introduction to RCS</B>

<BR></FONT></A></CENTER></H3>

<P>RCS was originally designed and developed by Walter Tichy of Purdue University as a version control system intended primarily for source code, documents, and test cases. Since its original release, the system has evolved somewhat over the years, but it 

maintains a great deal of backward compatibility with the initial release. The most popular current version is probably GNU RCS 5.6. RCS addresses several areas that are not well covered by SCCS, such as merging branches and marking baselines and 
configurations.

<BR></P>

<P>RCS is not available by default on all platforms, and only old versions are available on others. The 5.6.0.1 version of GNU RCS is included on the CD-ROM in case you need (a newer version of) RCS on your system.

<BR></P>

<H4 ALIGN="CENTER">

<CENTER><A ID="I15" NAME="I15">

<FONT SIZE=3><B>Interacting with RCS</B>

<BR></FONT></A></CENTER></H4>

<P>The basics of RCS are simply checking in a version of your file (ci), and checking out a version of your file (co). If you are a first-time user working alone, you may never need to do more. Viewing the history (rlog) and comparing changes from one 
revision to another (rcsdiff) may be useful to you. As your needs grow, you can start using branches and merging. If you are in a multiperson project, you should start using locking. Depending on the level of detail you need, RCS can be peripheral or 
central to your development environment.

<BR></P>

<H5 ALIGN="CENTER">

<CENTER><A ID="I16" NAME="I16">

<FONT SIZE=3><B>Initial Revisions</B>

<BR></FONT></A></CENTER></H5>

<P>In order to start using RCS to control revisions of a particular file, you need to create an initial revision, which is the root of the revision tree for this file. Maybe you have already created and edited a file. Now you realize that your development 

will be enhanced by using RCS. Or you may be planning ahead, just trying to get a project started, and you have no file contents yet. You would like to create an RCS file and you will check in an initial revision later.

<BR></P>

<P>In the first case, you have a file with contents. In RCS terminology, this is your working file. You can create an initial revision by using the RCS check-in command, ci. RCS will save the working file as the initial revision and prompt for a 
description of the revision group. Your working file is then removed from your directory.

<BR></P>

<P>In the second case, you have a file name but no contents. You can create an RCS file with the command rcs -i. RCS will prompt for the revision group description. Later, when you have some file contents, you can do an initial check in using ci. For now, 

there is no initial revision.

<BR></P>

<H5 ALIGN="CENTER">

<CENTER><A ID="I17" NAME="I17">

<FONT SIZE=3><B>RCS files</B>

<BR></FONT></A></CENTER></H5>

<P>RCS views your file as a pair of files. The file that you have named and to which you make changes is called the working file. You create this file in a directory of your choosing. When you check in this file, RCS creates an RCS file (if this is the 
first check in) or adds to an existing RCS file. The RCS filename is simply your working filename with a suffix added to the end. The default suffix on UNIX systems is usually v. You can control the suffix of a file via the -x option during check in. This 

option lets you specify a list of possible suffixes that will be tried, in order, during check in and check out.

<BR></P>

<P>RCS commands enable you to specify one of or both the working file and the RCS file. It is common to specify only the working file and let RCS handle the placement of the RCS file. If the RCS file is not specified, RCS first tries to deposit the 
revision in a subdirectory, RCS. If no such directory exists, the revision is placed in the current working directory. Creating a directory called RCS in your working directory helps to organize your work. All the RCS files are kept in this directory, out 

of sight.

<BR></P>

<H5 ALIGN="CENTER">

<CENTER><A ID="I18" NAME="I18">

<FONT SIZE=3><B>Checking Out a File</B>

<BR></FONT></A></CENTER></H5>

<P>To use a file you have under RCS control, you must check it out via the RCS command co, which causes RCS to copy the revision of the specified file into a working file. Then you can use the file, for example, for printing or compiling. But if you want 
to make changes to this file, you must obtain a lock for the file. You can check out a file with a lock via co -l. See the section &quot;Locks&#151;Mediating Conflict&quot; for details of using locks.

<BR></P>

<H5 ALIGN="CENTER">

<CENTER><A ID="I19" NAME="I19">

<FONT SIZE=3><B>Checking In a File</B>

<BR></FONT></A></CENTER></H5>

<P>To save a version of your working file after making changes, use the ci command. If you want to keep a copy of the working file around to use, you can add the -u option. This is just like doing a ci, followed by a co. Whenever you do a ci, you will be 
asked to enter a log message, a description of the changes you have made. This is for your (and your co-workers') use. Keep in mind that a short phrase might be very meaningful now, but these logs may be perused down the road. The more specific you are 
now, the easier it will be to figure out revision contents later.

<BR></P>

<P>It is common to check in several files at once, perhaps ones that are related to one another. For example, you are fixing a defect in your product, and several files must be modified to solve the problem. You check out the files as needed and work in 
your working directory until the product defect is fixed. You test your solution. When you are convinced that everything works, you want to check in the changes. It could be tedious to enter a log message for each file as it's checked in. When you check in 

more than one file at once, after the first file, RCS asks if you want to use the same log as the previous file. This speeds things up a bit. To totally automate the check in, you can specify the log message via the check in command's -m option. So if the 

log message is to be the same for each file, using the -m option to specify the log message, along with shell metacharacters to specify all the working files, can shorten a huge job so that it takes only a single command.

<BR></P>

<HR ALIGN=CENTER>

<NOTE>

<IMG SRC="imp.gif" WIDTH = 68 HEIGHT = 35><B>TIP: </B>If you have a lengthy log message that is common to more than one file, enter the text of the message into a file. Then on the check in command line, use -m'cat <I>filename</I>' to specify that the 
contents of the file <I>filename</I> should be used as the log message

<BR></NOTE>

<HR ALIGN=CENTER>

<H5 ALIGN="CENTER">

<CENTER><A ID="I20" NAME="I20">

<FONT SIZE=3><B>Examining Revision Details and History</B>

<BR></FONT></A></CENTER></H5>

<P>If you need to examine the history and status of an RCS file, you can use the rlog command. This displays each revision log, ordered from highest number to lowest. This can help you see the progress of changes that have been made during development 
history. These logs can be very helpful for locating a specific revision of the file that you want to examine in complete detail.

<BR></P>

<P>The rlog command shows you other details besides just the log messages. The first several lines are called the header and contain details about the revision group. Included in this header is the RCS pathname, the working pathname, the head revision, the 

default branch, the access list, locks, symbolic names, the suffix, and a few other items. If you are interested in header information only, and no log messages, use the -h option to limit the output to only the header. rlog has other useful options to 
limit the data it displays. Refer to the man page for details.

<BR></P>

<P>If you do find a particular revision that you would like to examine or use, you can check out the revision by specifying the revision number on the co command line. Keep in mind, though, that performing co will overwrite your existing working file. This 

may be okay with you. If not, you can ask RCS to check out a file to standard out. Then you can use UNIX redirection of standard output to place the old revision contents wherever you would like. Using the command 

<BR></P>

<PRE>co -r2.4 -p the_file &gt; the_file.2.4 </PRE>

<P>will put (old) revision 2.4 into a file called the_file.2.4.

<BR></P>

<H5 ALIGN="CENTER">

<CENTER><A ID="I21" NAME="I21">

<FONT SIZE=3><B>rcsdiff</B>

<BR></FONT></A></CENTER></H5>

<P>If you are familiar with the UNIX diff command, the RCS command rcsdiff will be familiar to you. rcsdiff compares two revisions of the same file and displays the differences between the two versions. RCS manages the retrieval of the versions while 
rcsdiff uses the UNIX diff to perform the actual comparison. The two versions are compared line-by-line, and if any character in the line is different between the two files, a message is displayed to standard out describing the place where the difference 
occurs.

<BR></P>

<P>To use the rcsdiff command, you need to specify the two revisions that are to be compared. You can explicitly specify each with two instances of the -r option. If you specify only one revision on the command line, this revision is compared against your 

working file. If you omit both revisions from the command line, your working file is compared against the head revision on the default branch (usually the trunk). Here are some examples:

<BR></P>

<PRE>rcsdiff -r2.3 -r2.6 the_file</PRE>

<P>compares revisions 2.3 and 2.6 of the_file.

<BR></P>

<PRE>rcsdiff -r2.3 the_file</PRE>

<P>compares revision 2.3 of the_file with the working file the_file.

<BR></P>

<PRE>rcsdiff the_file</PRE>

<P>compares the head of the default branch of the_file with the working file the_file.

<BR></P>

<H5 ALIGN="CENTER">

<CENTER><A ID="I22" NAME="I22">

<FONT SIZE=3><B>Keywords</B>

<BR></FONT></A></CENTER></H5>

<P>RCS allows the user to imbed certain words into the working file. These words, keywords, have special meaning to RCS. Each keyword is initially inserted into the working file, then later the current value is placed after the keyword, with a colon 
separator. When keywords are in the file during a check out, the co command updates the value of each keyword.

<BR></P>

<P>There are many keywords available. You should check which will be most useful to you by examining the co man page. The $Header:$ 30unxor2.adj,v 1.7 94/04/05 18:24:08 sartin Exp $ keyword contains a composite of most of the individual keywords. If you