RCS Tutorial. Dongsoo S. Kim

Transcription

1 RCS Tutorial Dongsoo S. Kim

2 RCS Subdirectory The following examples will use the file our_file.txt. By default, version files when initially checked-in are placed in the same directory as the file being checked-in. To avoid clutter in your directory, an RCS subdirectory can be created to collect RCS files. If such a subdirectory exists, RCS will store all RCS files to the subdirectory rather than the same directory of the working file. Create an RCS subdirectory with the following command: $ mkdir RCS Or you can create a soft link for sharing sources among project members. For example, $ ln s ~dskim/ece282/lab12/t1/rcs RCS

3 Checking-in a File To check-in our file to RCS, you would issue the command: $ ci our_file.txt RCS will respond with: RCS/our_file.txt,v <-- our_file.txt enter description, terminated with single '.' or end of file: NOTE: This is NOT the log message! >> 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 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 different extension for RCS files. 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 name. 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.

4 Entering File Descriptions 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 description of the file. The description has no functional purpose in RCS. The description serves only to describe the file to you and others. This can be helpful when files are given obscure, non-descriptive file names, or impracticcal and vague names like in this example. 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 Ctrl D (^D). 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 enter or return) ) must be entered. A carriage 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: RCS/our_file.txt,v <-- our_file.txt enter description, terminated with single '.' or end of file: NOTE: This is NOT the log message! >> Our Example RCS Text File >>. initial revision: 1.1 done Descriptions can also be entered as a command-line argument (see section on file description option)

5 Checking-out a 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 copy of the file available: $ co our_file.txt RCS/our_file.txt,v --> our_file.txt revision 1.1 (unlocked) done 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. The file is actually unlocked, as RCS outputs above, and could have been checked-out with the more explicit check-out command: $ co -u our_file.txt RCS/our_file.txt,v --> our_file.txt revision 1.1 (unlocked) done

6 Checking-out a File for Editing To check-out the file for editing, a request for a lock and a request for retrieval of a version must be made: $ co -l our_file.txt RCS/our_file.txt,v --> our_file.txt revision 1.1 (locked) done 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: $ ci -l our_file.txt RCS/our_file.txt,v <-- our_file.txt new revision: 1.2; previous revision: 1.1 enter log message, terminated with single '.' or end of file: >> Added another question. >> ^D done

7 Checking-out a Previous Revision 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. These are adequate skills for gaining the familiariarty and good habit of using version control. However, the benefits of using version control come from being able to have access to previous revisions of a file. 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 above, the revision was not specified in the RCS command but instead implied silently as a request for the most recent revision. 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 revision option: $ co -r1.1 our_file.txt

8 Checking-out a Previous Revision The revision command-line option can be combined with the check-out's locking option. So, the check-out and locking of the first revision done above could have been accomplished instead by combining the revision option with the lock option: $ co -r1.1 -l our_file.txt The lock option is actually able to take an argument in the same format as the revision option, allowing the above command to be shortened: $ co -l1.1 our_file.txt In the same vein, all these options are recognized by the check-in command. To check-in, check-out and lock the second revision: $ ci -l1.2 our_file.txt

9 Displaying Differences 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 checked it out or to see the specific changes made to a file. The name of the command is rcsdiff. rcsdiff takes the same options as the diff command. The general form of such a command is: $ rcsdiff our_file.txt ============================================= RCS file: RCS/our_file.txt,v retrieving revision 1.1 diff -r1.1 our_file.txt 1a2 > Which of it is ours? The output of rcsdiff is the default output for the system's diff command. For this example, the output is the ed format.

10 Inserting Keywords Another feature desired by users of RCS besides general version control is the use of keywords. To utilize RCS keywords simply insert the keywords. For example, place the commonly Id keyword at the end of the file, accomplished by this shell command: $ echo '$Id: tutorial.html,v :15:14-04 ashawley Exp $' >> our_file.txt When the file is checked-in and out, RCS will replace the keywords with their respective values: $ ci -l our_file.txt RCS/our_file.txt,v <-- our_file.txt new revision: 1.3; previous revision: 1.2 enter log message, terminated with single '.' or end of file: >> Added Id keyword. >> ^D done

11 Here are the contents of the file $ cat our_file.txt This is our file. Which of it is ours? Do we agree to it? $Id: tutorial.html,v :15:14-04 ashawley Exp $

12 Retrieving Files In the case of our example, checking the values of keywords is a simple task given the short length of the file. In the case of large files, finding keywords can become a painful task. Fortunately, an RCS command is able to retrieve the keywords from a file and display them: $ ident our_file.txt our_file.txt: $Id: tutorial.html,v :15:14-04 ashawley Exp $

13 Viewing the Log 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: 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) and information about revisions including check-in date, author and the log submitted forthe revision. $ rlog our_file.txt RCS file: RCS/our_file.txt,v Working file: our_file.txt head: 1.3 branch: locks: strict access list: symbolic names: keyword substitution: kv total revisions: 3; selected revisions: 3 description: Our Example RCS Text File revision 1.3 date: :11:54-04; author: ashawley; state: Exp; lines: +1-0 Added Id keyword revision 1.2 date: :08:56-04; author: ashawley; state: Exp; lines: +1-0 Added another question revision 1.1 date: :07:51-04; author: ashawley; state: Exp; Initial revision =============================================================================

14 After the Basics This tutorial covered the fundamental operations of version control with RCS. The total functionality offered by RCS far surpasses the coverage of the tutorial in this section. However, familiarity with just these routine version control tasks leverages many of the benefits of version control. From here, other concepts and features of RCS can be easily learned and understood. Other features and concepts skipped include branches, merges, keyword subsitution options, version names, file initilization options, localizations and the realm of multiple author usage and administration. However, these operations are so rarely used or needed for so few tasks that they need not complicate an introductory tutorial.