unx30.htm

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

include the $Header:$ 30unxor2.adj,v 1.7 94/04/05 18:24:08 sartin Exp $ keyword, the value that is inserted will contain the RCS file, the revision number, the date, the author, the state, and the locker (if the file is locked).

<BR></P>

<HR ALIGN=CENTER>

<NOTE>

<IMG SRC="imp.gif" WIDTH = 68 HEIGHT = 35><B>TIP: </B>If you are using the $Revision:$ keyword to identify revisions distributed to other people, make sure you do a clean check out (co) of all files before distributing (or that you build source code). If 
you fail to check out a file, the revision number will not be up-to-date because only co updates the keyword values.

<BR></NOTE>

<HR ALIGN=CENTER>

<H4 ALIGN="CENTER">

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

<FONT SIZE=3><B>Locks&#151;Mediating Conflict</B>

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

<P>RCS has two kinds of locking mechanisms: strict and nonstrict. If you are the only person who will be modifying this file, you can turn off strict locking via rcs -U. This will allow you, the file owner, to make changes without obtaining a lock. Anyone 

else must obtain a lock in order to modify the file.

<BR></P>

<P>If you are one of several people who can modify this file, you should set the locking to strict. This is done via rcs -L. In this case, anyone wanting to modify the file should obtain a lock before making changes. This should be done during the check 
out with the -l option. This way, the revision is copied to your working file and the revision is locked, all at the same time.

<BR></P>

<P>Sometimes you will find yourself in the situation of modifying a file without first obtaining a lock. You usually find this out when you go to check in your changes and you get a ci error message saying that your user name does not have a lock set. If 
this happens, all is not lost, but you need to do a little investigation before you can resolve the situation.

<BR></P>

<P>First, you need to find out if anyone else has checked in any revisions since you last checked out this file. Look at the revision number at the top of your working file to find the revision that is the basis of your changes. If you have the keyword 
$Revision:$ in your file, RCS will substitute the revision number after this keyword. If you do not have this keyword in your file, it is much more difficult to figure out what revision you started editing. You can try looking at the RCS logs, using the 
rcsdiff command to examine changes between revisions, or use the rcs -P command to obtain temporary copies of old revisions. Hopefully you will be able to recognize the revision you started with! If someone has made changes and checked them in since the 
version you started with, you should check in your changes as a branch off your basis revision. Then do a merge of your file at the top of the other changes. See the sections &quot;Merges&#151;Controlling Parallel Changes&quot; and 
&quot;Branches&#151;Complicating the Tree&quot; for details.

<BR></P>

<P>If nobody has checked in any changes since your version was checked out, all you need to do is lock the file and check it in. Be careful here. Do not use co -l to obtain the lock. This will overwrite your working file and you'll lose all your changes. 
Instead, use the rcs -l command. This simply manipulates the file lock&#151;no copying is involved. After obtaining the lock, check in the file as usual.

<BR></P>

<P>In either of these possible scenarios, someone else could have the file locked. You can always check on the status of a file lock with the rlog -h command. This shows the header information for the specified file. If someone holds the lock, the header 
will contain a message stating which user has it locked. If this is the case, you can work out with that person a strategy to deal with the conflict. Once again, using the RCS merging facility can help this resolution. In an emergency, or if the user 
holding the lock is no longer available, you may break the lock with the rcs command. You first use the rcs -u command to unlock the revision. When you unlock someone else's lock, you are asked to enter a comment about breaking the lock that is forwarded 
to the user via electronic mail. After breaking the lock, you can then obtain the lock for yourself via rcs -l.

<BR></P>

<H4 ALIGN="CENTER">

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

<FONT SIZE=3><B>Branches&#151;Complicating the Tree</B>

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

<P>RCS has a very flexible branching scheme. It allows you to make branches off the main trunk. You can also make branches that branch off an existing branch. For example, main trunk file revision 2.3 has a branch. This branch is 2.3.1 and has revisions 
2.3.1.1, 2.3.1.2, and so on. At some point during this branch's development, say at 2.3.1.7, you need to branch off again. You create branch 2.3.1.7.1, which has revisions 2.3.1.7.1.1, 2.3.1.7.1.2, and so on. You get the idea. As you can see, the revision 

numbers get long quite quickly. For this reason it is probably good to limit the branching as much as is reasonable.

<BR></P>

<P>In order to create and refer to files on a branch, you need to explicitly reference the revision of the file. Look at how this works. Start with trunk revisions including 2.3 already checked in. Now you want to create branch 2.3.1. First check out with 

a lock revision 2.3. Next do your edits. Now when you go to check in your changes, specify the branch revision number. This creates revision number 2.3.1.1. Similar commands will create the next branch.

<BR></P>

<H4 ALIGN="CENTER">

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

<FONT SIZE=3><B>Merges&#151;Controlling Parallel Changes</B>

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

<P>If you have parallel development of a single file, for whatever reason, and you need to roll all the changes together into a single revision, you should use the rcsmerge command. Say you have branched off the main trunk of development at revision 2.3. 
Revisions 2.4 through 2.7 represent your main development efforts, whereas 2.3.1.1 through 2.3.1.4 represent defect fixes to your released (2.3) product. Now you would like to merge your changes together and check them in as revision 2.8.

<BR></P>

<P>Using rcsmerge to do this, you must specify the common base revision, in this case 2.3, via option -r. One set of the changes can be specified with a second -r option. If you do not specify this option, the default revision (usually the top of the main 

trunk) is assumed. In this example, 2.7 is one of the revisions that holds changes. You can either let this be the default or explicitly specify -r2.7. Alternatively, you could specify -r2.3.1.4 to denote the branch revision. The other set of changes that 

should be merged in are taken from the working file specified. Therefore, you must be aware of the contents of this file. It is also important to remember that this file is overwritten with the merged file. Use the -p option to make the output go to 
standard out, which you can redirect to a file if you don't want your working file modified.

<BR></P>

<P>Now look at a couple of ways to put together all the options with rcsmerge. If you are developing on the main branch, check out revision 2.7 with a lock: 

<BR></P>

<PRE>co -l2.7 the_file</PRE>

<P>merge together the changes:

<BR></P>

<PRE>rcsmerge -r2.3 -r2.3.1.4 the_file</PRE>

<P>and check in the changes to the main trunk: 

<BR></P>

<PRE>ci -u the_file</PRE>

<P>The command in step 2 could be changed to

<BR></P>

<PRE>rcsmerge -p -r2.3 -r2.3.1.4 the_file &gt; the_file.merged</PRE>

<P>to preserve the contents of file the_file. If you are working on the branched releases

<BR></P>

<P>obtain a lock on the main trunk (to check in the merge results):

<BR></P>

<PRE>rcs -l2.7 the_file</PRE>

<P>check out a copy of revision 2.3.1.4 without a lock:

<BR></P>

<PRE>co -u2.3.1.4 the_file</PRE>

<P>merge together the changes: 

<BR></P>

<PRE>rcsmerge -p -r2.3 -r2.7 the_file &gt; the_file.merged</PRE>

<P>when you wish to check in the changes, move the merged file into the working file:

<BR></P>

<PRE>mv the_file.merged the_file</PRE>

<P>and check in your changes as revision 2.8: 

<BR></P>

<PRE>ci -u the_file</PRE>

<P>These are only two variations of many possible ways to use the rcsmerge command to merge together two set of changes. These are the basic things you need to remember: The first revision specified is the common base. The second revision specified is one 

setof changes and can be implied. The working file specified includes the other changes. The working file will be overwritten with the merged file unless -p is specified.

<BR></P>

<P>There is a second way to merge together changes. The co command has an option, -j, that specifies pairs of files whose changes should be merged (joined) to the specified revision during the check out. Repeating the merge example with the co command 
gives the following possible solution:

<BR></P>

<PRE>co -l2.7 -j2.3:2.3.1.4 the_file</PRE>

<P>The first revision specified (-l2.7) is checked out. The changes that occurred between the two revisions specified in the join list, 2.3 and 2.3.1.4, are merged into revision 2.7. The resulting merged file is placed in the working file the_file. Then 
you may check in the changes using the following command:

<BR></P>

<PRE>ci -u the_file</PRE>

<P>The merging/joining abilities of RCS are quite flexible. You have seen several possible methods of combining your parallel development using the rcsmerge command and the co command. Each of these commands may not be able to resolve all types of merges. 

During the merge process, if RCS has conflicts you will be notified and must examine the resulting file. The conflicts will be denoted and you must choose the desired solution. See the man page for merge for details on conflicts.

<BR></P>

<H4 ALIGN="CENTER">

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

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

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

<P>So far, this section on RCS has used numeric revision numbers. However, RCS enables you to use symbolic revision numbers as well as symbolic branches. Two commands, rcs and ci, allow you to set these symbolic names. After you have created these names, 
you can use them in place of numeric revision numbers in all of the RCS commands. First look at how you set up symbolic names.

<BR></P>

<P>During check in, you can set or change the symbolic name associated with that revision number. If you have just added a new bit of functionality to your product, you may want to associate a symbolic name that you can advertise to your co-workers. Say 
you call it ERR-MUSIC, because your product plays a little music when the user makes an error. When you check in your changes, use the -n option to add this symbolic name: 

<BR></P>

<PRE>ci -u -nERR-MUSIC the_file</PRE>

<P>If you later need to fix a defect in your new music routines, make the change and check it in. However, this time you must use a capital -N as the option. This will override the previous value of the ERR-MUSIC symbol.

<BR></P>

<P>The rcs command can also be used to manipulate symbolic names. To add a symbolic name initially, use -n followed by : and then a revision number. The revision number is optional, and if left unspecified, the default revision will be used. Be careful, 
because if you omit the : the symbolic name will be deleted. The -N option has the same behavior except that it will override an existing symbol.

<BR></P>

<P>The rcs command is also used to create and manipulate the symbolic branch names. Say you are using a branch off revision 3.4 to do patches for an internal release. You have created branch 3.4.1 and checked in revision 3.4.1.1 as the first patch changes. 

To make interacting with this branch easier, you can name the branch (not a particular revision, but the branch as a whole) via rcs -nPATCH:3.4.1. Now when you want to check in and out off the head of the PATCH branch, simply use the symbolic name PATCH.

<BR></P>

<P>Here are some specific examples:

<BR></P>

<PRE>

<BR>rcs -nERR-MUSIC: the_file creates a new symbolic name, ERR-MUSIC, for the default revision of the_file.



<BR>rcs -NERR-MUSIC: the_file moves the symbolic name, ERR-MUSIC, to the default revision of the_file.



<BR>rcs -nERR-MUSIC:2.3 the_file creates a new symbolic name, ERR-MUSIC, for the 2.3 revision of the_file.



<BR>rcs -NERR-MUSIC:2.5 the_file moves the symbolic name, ERR-MUSIC, to the 2.5 revision of the_file.



<BR>rcs -NERR-MUSIC:RELEASE1 the_file moves the symbolic name, ERR-MUSIC, to the RELEASE1 revision of the_file.



<BR>rcs -nERR-MUSIC the_file deletes the symbolic name, ERR-MUSIC, from the_file.



<BR>co -lPATCH the_file checks out and locks the head of branch PATCH.</PRE>

<P>Now that you have created symbolic version numbers and branches, you can use these names in any places where you would use their numeric equivalents.

<BR></P>

<H3 ALIGN="CENTER">

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

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

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

<P>SCCS was developed by AT&amp;T as a system to control source code development. It has features in it that help support a production environment, including freezing of released code and hooks for integration of a problem-tracking system. This section 
includes a brief introduction to SCCS, primarily as a contrast to RCS. Refer to the sections &quot;A Simple Example&quot; and &quot;A Complex Example&quot; for detailed samples of SCCS command usage.

<BR></P>

<P>Some systems ship with SCCS, but without the sccs command that was introduced by BSD. This book's CD-ROM includes a version of the sccs command as available on the free source from BSD.

<BR></P>

<H4 ALIGN="CENTER">

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

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

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

<P>SCCS includes the admin command for interacting with the source control system. It can be used to create source control files, control availability of revisions, and change the rules about requirements for submitting a revision. SCCS also uses several 
temporary files to indicate internal state and temporary locks. SCCS files are named s.<I>filename</I>. All SCCS commands take the name of the SCCS file itself rather than allowing a working filename as RCS commands do. It also has get and delta, which are 

similar in function to the RCS commands co and ci.

<BR></P>

<H5 ALIGN="CENTER">

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

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

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

<P>SCCS files require explicit initialization using the admin command before you can perform any other action. There are two different ways to initialize an SCCS file. First, you can create an SCCS file with an empty initial revision by executing admin -n 

s.<I>filename</I>. This will create s.<I>filename</I> with the appropriate SCCS file structure and an empty revision 1.1. You can then use the get and delta commands to add text; unlike in RCS, the empty revision 1.1 will always remain. Second, you can 
create an SCCS file with initial contents from another file using admin -i<I> filename</I> s.<I>filename</I>. The two occurrences of <I>filename</I> are not required to be the same, but it is generally useful to do so because other SCCS commands assume 
that the working file for s.<I>filename</I> is <I>filename</I>.

<BR></P>

<H5 ALIGN="CENTER">

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

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

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

<P>Like RCS, SCCS has an implicit notion of working files, but SCCS always requires the command line to use the s-file, which is the s.<I>filename</I> source control file. SCCS uses a file format completely different from that of RCS.

<BR></P>

<HR ALIGN=CENTER>

<NOTE>

<IMG SRC="note.gif" WIDTH = 35 HEIGHT = 35><B>NOTE:</B> It is a common misconception that SCCS uses forward deltas that save the root revision and build all later revisions using deltas from there. This leads to the incorrect conclusion that SCCS checks 
out new revisions more slowly than it checks out old ones. In truth, SCCS uses a technique called interleaved deltas, which stores blocks of delta changes in such a way that a single pass over the entire SCCS file can produce any revision using fairly 
straightforward techniques. The result is that SCCS get performance slows as the SCCS file gets large, but has similar performance regardless of which revision is retrieved. In a study by Walter F. Tichy, the original author of RCS, the RCS command co is 
faster than the SCCS command get unless 10 or more deltas are being applied to derive a revision.

<BR>

<BR>This note is brought to you courtesy of RCS&#151;A System for Version Control by Tichy, which includes descriptions of RCS and the algorithms used by RCS and SCCS. A postscript version of this paper is on this book's CD-ROM.

<BR></NOTE>

<HR ALIGN=CENTER>

<H5 ALIGN="CENTER">

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

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

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

<P>SCCS enables you to get a read-only copy of a revision with the get command. Using get -p will output the revision contents to the standard output. You can also supply a revision number using the -r option. Partial revision numbers for the -r option