RCS TutorialRCS Tutorial

Dongsoo S. KimDongsoo S. Kim

RCS SubdirectoryRCS Subdirectory The following examples will use the file our_file.txt. The following examples will use the file our_file.txt. By default, version files when initially checked-in are placed in By default, version files when initially checked-in are placed in

the same directory as the file being checked-in.the same directory as the file being checked-in. To avoid clutter in your directory, an RCS subdirectory can be To avoid clutter in your directory, an RCS subdirectory can be

created to collect RCS files. created to collect RCS files. If such a subdirectory exists, RCS will store all RCS files to the If such a subdirectory exists, RCS will store all RCS files to the

subdirectory rather than the same directory of the working file.subdirectory rather than the same directory of the working file. Create an RCS subdirectory with the following command:Create an RCS subdirectory with the following command:$ mkdir RCS $ mkdir RCS

Or you can create a soft link for sharing sources among project Or you can create a soft link for sharing sources among project members. For example, members. For example, $ ln –s ~dskim/ece282/Lab12/T1/RCS RCS$ ln –s ~dskim/ece282/Lab12/T1/RCS RCS

Checking-in a FileChecking-in a File To check-in our file to RCS, you would issue the command:To check-in our file to RCS, you would issue the command:

$ ci our_file.txt $ ci our_file.txt RCS will respond with:RCS will respond with:

RCS/our_file.txt,v <-- our_file.txt RCS/our_file.txt,v <-- our_file.txt enter description, terminated with single '.' or end of enter description, terminated with single '.' or end of file: file: NOTE: This is NOT the log message! NOTE: This is NOT the log message! >> >>

RCS displays where the working file is and where the RCS file is. In this example, the RCS displays where the working file is and where the RCS file is. In this example, the location of the RCS file is in the RCS subdirectory with the name of the working file location of the RCS file is in the RCS subdirectory with the name of the working file with a comma and the letter v (,v) appended to the filename. A ,v is the default with a comma and the letter v (,v) appended to the filename. A ,v is the default extension to RCS files. This behavior can be modified so that RCS looks for a extension to RCS files. This behavior can be modified so that RCS looks for a different extension for RCS files.different extension for RCS files.

If there hadn't been an RCS subdirectory, then the RCS file would be placed in the If there hadn't been an RCS subdirectory, then the RCS file would be placed in the same directory as the working file. The RCS file would still have a ,v appended to the same directory as the working file. The RCS file would still have a ,v appended to the name.name.

RCS then gives directions on how to submit a file description (see section on file RCS then gives directions on how to submit a file description (see section on file description). After these directions an interactive prompt awaits the input for the description). After these directions an interactive prompt awaits the input for the description.description.

Entering File DescriptionsEntering File Descriptions Upon initially checking-in a file, RCS requests a file description. The request is not for a revision log message, so Upon initially checking-in a file, RCS requests a file description. The request is not for a revision log message, so

do not describe the changes made or the current state of the initial revision. Instead, this is a request for a do not describe the changes made or the current state of the initial revision. Instead, this is a request for a description of the file. description of the file.

The description has no functional purpose in RCS. The description serves only to describe the file to you and The description has no functional purpose in RCS. The description serves only to describe the file to you and others. others.

This can be helpful when files are given obscure, non-descriptive file names, or impracticcal and vague names like This can be helpful when files are given obscure, non-descriptive file names, or impracticcal and vague names like in this example.in this example.

Descriptions, as RCS requests, are ended with a single period (.), or an “end of file”. An “end of file” on most Descriptions, as RCS requests, are ended with a single period (.), or an “end of file”. An “end of file” on most systems is issued by typing systems is issued by typing Ctrl DCtrl D ( (^D^D). By “single”, the period or end of file should be the only character on the ). By “single”, the period or end of file should be the only character on the line. After entering a period a carriage return (on most systems line. After entering a period a carriage return (on most systems enterenter or or returnreturn) must be entered. A carriage ) must be entered. A carriage return is not necessary after terminating the description with an end of file.return is not necessary after terminating the description with an end of file.Here is a description entry for the initial revision of the example:Here is a description entry for the initial revision of the example:RCS/our_file.txt,v <-- our_file.txt RCS/our_file.txt,v <-- our_file.txt enter description, terminated with single '.' or end of file: enter description, terminated with single '.' or end of file: NOTE: This is NOT the log message! NOTE: This is NOT the log message! >> >> Our Example RCS Text FileOur Example RCS Text File >> >> .. initial revision: 1.1 initial revision: 1.1 done done

Descriptions can also be entered as a command-line argument (see section on file description option)Descriptions can also be entered as a command-line argument (see section on file description option)

Checking-out a FileChecking-out a File Upon checking-in a file, RCS by default deletes the working copy of the file. Upon checking-in a file, RCS by default deletes the working copy of the file.

To view, compile or distribute the file enter the following to make a working To view, compile or distribute the file enter the following to make a working copy of the file available:copy of the file available:$ $ co our_file.txtco our_file.txt RCS/our_file.txt,v --> our_file.txt RCS/our_file.txt,v --> our_file.txt revision 1.1 (unlocked) revision 1.1 (unlocked) done done

The file is now available but is unlocked and therefore read-only. This is The file is now available but is unlocked and therefore read-only. This is because the revision of the file would need to be locked. because the revision of the file would need to be locked.

The file is actually unlocked, as RCS outputs above, and could have been The file is actually unlocked, as RCS outputs above, and could have been checked-out with the more explicit check-out command:checked-out with the more explicit check-out command:$ $ co -u our_file.txtco -u our_file.txt RCS/our_file.txt,v --> our_file.txt RCS/our_file.txt,v --> our_file.txt revision 1.1 (unlocked) revision 1.1 (unlocked) done done

Checking-out a File for EditingChecking-out a File for Editing To check-out the file for editing, a request for a lock and a request for To check-out the file for editing, a request for a lock and a request for

retrieval of a version must be made:retrieval of a version must be made:$ $ co -l our_file.txtco -l our_file.txt RCS/our_file.txt,v --> our_file.txt RCS/our_file.txt,v --> our_file.txt revision 1.1 (locked) revision 1.1 (locked) done done

The checking-in, checking-out and locking of a file can be done with a single The checking-in, checking-out and locking of a file can be done with a single check-in. This is combined into a single checking-in command:check-in. This is combined into a single checking-in command:$ $ ci -l our_file.txtci -l our_file.txt RCS/our_file.txt,v <-- our_file.txt new RCS/our_file.txt,v <-- our_file.txt new revision: 1.2; previous revision: 1.1 revision: 1.2; previous revision: 1.1 enter log message, terminated with single '.' or enter log message, terminated with single '.' or end of file: end of file: >> >> Added another question.Added another question. >> >> ^D^D done done

Checking-out a Previous RevisionChecking-out a Previous Revision In the examples so far, we have been checking-out, editing, checking-in and In the examples so far, we have been checking-out, editing, checking-in and

locking only the most recent version of the file in RCS. locking only the most recent version of the file in RCS. These are adequate skills for gaining the familiariarty and good habit of using These are adequate skills for gaining the familiariarty and good habit of using

version control.version control. However, the benefits of using version control come from being able to have However, the benefits of using version control come from being able to have

access to previous revisions of a file.access to previous revisions of a file. The most direct and simple method for retrieving revisions is to specify the The most direct and simple method for retrieving revisions is to specify the

revision number with the revision command-line option (-r). In the examples revision number with the revision command-line option (-r). In the examples above, the revision was not specified in the RCS command but instead above, the revision was not specified in the RCS command but instead implied silently as a request for the most recent revision. implied silently as a request for the most recent revision.

However, after checking in the file the first time, the most recent revision of However, after checking in the file the first time, the most recent revision of the file could have also been retrieved by specifying the revision with the the file could have also been retrieved by specifying the revision with the revision option:revision option:$ $ co -r1.1 our_file.txtco -r1.1 our_file.txt

Checking-out a Previous RevisionChecking-out a Previous Revision The revision command-line option can be combined with the The revision command-line option can be combined with the

check-out's locking option. So, the check-out and locking of the check-out's locking option. So, the check-out and locking of the first revision done above could have been accomplished instead first revision done above could have been accomplished instead by combining the revision option with the lock option:by combining the revision option with the lock option:$ $ co -r1.1 -l our_file.txtco -r1.1 -l our_file.txt

The lock option is actually able to take an argument in the same The lock option is actually able to take an argument in the same format as the revision option, allowing the above command to format as the revision option, allowing the above command to be shortened:be shortened:$ $ co -l1.1 our_file.txtco -l1.1 our_file.txt

In the same vein, all these options are recognized by the check-in In the same vein, all these options are recognized by the check-in command. To check-in, check-out and lock the second revision:command. To check-in, check-out and lock the second revision:$ $ ci -l1.2 our_file.txtci -l1.2 our_file.txt

Displaying DifferencesDisplaying Differences After making edits to the file, RCS can display the differences made to the After making edits to the file, RCS can display the differences made to the

working file. This is helpful to tell when a file has been edited since you last working file. This is helpful to tell when a file has been edited since you last checked it out or to see the specific changes made to a file.checked it out or to see the specific changes made to a file.

The name of the command is The name of the command is rcsdiffrcsdiff. . rcsdiffrcsdiff takes the same options as the takes the same options as the diffdiff command. The general form of such a command is: command. The general form of such a command is:$ $ rcsdiff our_file.txtrcsdiff our_file.txt ============================================= ============================================= RCS file: RCS/our_file.txt,v RCS file: RCS/our_file.txt,v retrieving revision 1.1 retrieving revision 1.1 diff -r1.1 our_file.txt diff -r1.1 our_file.txt 1a2 1a2 > Which of it is ours? > Which of it is ours?

The output of The output of rcsdiffrcsdiff is the default output for the system's is the default output for the system's diffdiff command. command. For this example, the output is the For this example, the output is the eded format. format.

Inserting KeywordsInserting Keywords Another feature desired by users of RCS besides general version control is the Another feature desired by users of RCS besides general version control is the

use of keywords. use of keywords. To utilize RCS keywords simply insert the keywords. To utilize RCS keywords simply insert the keywords. For example, place the commonly Id keyword at the end of the file, For example, place the commonly Id keyword at the end of the file,

accomplished by this shell command:accomplished by this shell command:$ $ echo '$Id: tutorial.html,v 1.2 2005-04-06 echo '$Id: tutorial.html,v 1.2 2005-04-06 02:15:14-04 ashawley Exp $' >> our_file.txt02:15:14-04 ashawley Exp $' >> our_file.txt

When the file is checked-in and out, RCS will replace the keywords with their When the file is checked-in and out, RCS will replace the keywords with their respective values:respective values:$ $ ci -l our_file.txtci -l our_file.txt RCS/our_file.txt,v <-- our_file.txt RCS/our_file.txt,v <-- our_file.txt new revision: 1.3; previous revision: 1.2 new revision: 1.3; previous revision: 1.2 enter log message, terminated with single '.' or enter log message, terminated with single '.' or end of file: end of file: >> >> Added Id keyword.Added Id keyword. >> >> ^D^D done done

Here are the contents of the fileHere are the contents of the file$ $ cat our_file.txtcat our_file.txt

This is our file. This is our file.

Which of it is ours? Which of it is ours?

Do we agree to it?Do we agree to it?

$Id: tutorial.html,v 1.2 2005-04-06 02:15:14-04 ashawley Exp $ $Id: tutorial.html,v 1.2 2005-04-06 02:15:14-04 ashawley Exp $

Retrieving FilesRetrieving Files

In the case of our example, checking the values In the case of our example, checking the values of keywords is a simple task given the short of keywords is a simple task given the short length of the file. length of the file.

In the case of large files, finding keywords can In the case of large files, finding keywords can become a painful task. become a painful task.

Fortunately, an RCS command is able to retrieve Fortunately, an RCS command is able to retrieve the keywords from a file and display them:the keywords from a file and display them:$ $ ident our_file.txtident our_file.txt our_file.txt: our_file.txt: $Id: tutorial.html,v 1.2 2005-04-06 02:15:14-04 ashawley Exp $ $Id: tutorial.html,v 1.2 2005-04-06 02:15:14-04 ashawley Exp $

Viewing the LogViewing the Log The log command can retrieve and display a bulk great amount of meta-information about versions for a file The log command can retrieve and display a bulk great amount of meta-information about versions for a file

under RCS. Here is information of what we have done to our example text file with RCS:under RCS. Here is information of what we have done to our example text file with RCS: The response of the log command highlights the file's information including the path of the RCS file (see section The response of the log command highlights the file's information including the path of the RCS file (see section

on RCS file), the description (see section on file description), the number of revisions (see section on revisions) on RCS file), the description (see section on file description), the number of revisions (see section on revisions) and information about revisions including check-in date, author and the log submitted forthe revision.and information about revisions including check-in date, author and the log submitted forthe revision.

$ $ rlog our_file.txtrlog our_file.txt RCS file: RCS/our_file.txt,v RCS file: RCS/our_file.txt,v

Working file: our_file.txt Working file: our_file.txt

head: 1.3 head: 1.3 branch: branch: locks: strict locks: strict access list: access list: symbolic names: symbolic names: keyword substitution: kv keyword substitution: kv total revisions: 3; selected revisions: 3 total revisions: 3; selected revisions: 3 description: Our Example RCS Text File description: Our Example RCS Text File ---------------------------- ---------------------------- revision 1.3 revision 1.3

date: 2003-05-27 03:11:54-04; author: ashawley; state: Exp; lines: +1 -0 date: 2003-05-27 03:11:54-04; author: ashawley; state: Exp; lines: +1 -0 Added Id keyword. Added Id keyword. ---------------------------- ---------------------------- revision 1.2 revision 1.2 date: 2003-05-27 03:08:56-04; author: ashawley; state: Exp; lines: +1 -0 date: 2003-05-27 03:08:56-04; author: ashawley; state: Exp; lines: +1 -0 Added another question. Added another question. ---------------------------- ---------------------------- revision 1.1 revision 1.1 date: 2003-05-27 03:07:51-04; author: ashawley; state: Exp; date: 2003-05-27 03:07:51-04; author: ashawley; state: Exp; Initial revision Initial revision

============================================================================= =============================================================================

After the BasicsAfter the Basics This tutorial covered the fundamental operations of version This tutorial covered the fundamental operations of version

control with RCS. control with RCS. The total functionality offered by RCS far surpasses the coverage The total functionality offered by RCS far surpasses the coverage

of the tutorial in this section. of the tutorial in this section. However, familiarity with just these routine version control tasks However, familiarity with just these routine version control tasks

leverages many of the benefits of version control. From here, leverages many of the benefits of version control. From here, other concepts and features of RCS can be easily learned and other concepts and features of RCS can be easily learned and understood.understood.

Other features and concepts skipped include branches, merges, Other features and concepts skipped include branches, merges, keyword subsitution options, version names, file initilization keyword subsitution options, version names, file initilization options, localizations and the realm of multiple author usage and options, localizations and the realm of multiple author usage and administration. However, these operations are so rarely used or administration. However, these operations are so rarely used or needed for so few tasks that they need not complicate an needed for so few tasks that they need not complicate an introductory tutorial.introductory tutorial.