GNU"> GPL"> RCS"> SCCS"> CSSC"> CVS"> Walter F. TichyTichy, Walter F."> ]> A User Guide for Gaining the Benefits of Version Control rcs Version Control Computer Utilities Aaron Hawley Computer science graduate willing to program, design or write for food or freedom. ashawley at uvm dot edu 2003 2004 2005 Free Software Foundation Hope to attribute to. 1.8 2005/04/05 19:06:10 ashawley Fixed revision history. Added year 2005 to copyright information. Re-organized COPYING section of manual. 1.7 2005/03/31 18:35:33 ashawley Improved tutorial section. Unified convention for "check-in" and "check-out". 1.6 2005/03/28 17:20:31 ashawley Spell checked document. 1.5 2005/03/24 20:28:35 ashawley Working version of the document (even for docbook2X). Other improvements to the material. 1.4 2003/06/04 14:08:29 ashawley Many changes and few new sections 1.3 2003/05/27 16:23:52 ashawley Finished concepts chapter. Added tutorial chapter. 1.2 2003/04/04 14:38:32 ashawley Here is a semi-annual update of my work so far. 1.1 2003/01/28 19:15:33 ashawley Here's the initial work. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled GNU Free Documentation License. Keeping versions of files with the Revision Control System Development

This manual is targeted at as many computers users as possible. The goal of the manual is to prove that all computer users can benefit from using version control in their work and that the Revision Control System (&rcs;) is the tool which can provide users access to version control. This manual will teach and also serve as a reference for anyone interested in using &rcs;. There are certain previous skills and knowledge needed to use &rcs;. &rcs; is a typical unixunix command-line tool. It is therefore similar to learning or understanding other unix command line tools. This manual does not introduce the concepts of file systemsfile systems, command-linecommand-line shellsshell, and other basic skills to navigating a unixunix operating system. Some users may find this manual more helpful if they were to first learn the fundamentals of the &gnu; operating system&gnu; System and working in a shellshell.

Write prose here instead of list. This manual serves as a reference manual. This manual serves as an introductory manual. This manual is a technical manual for &rcs;. This manual introduces the history and purpose of version control. This manual introduces version control concepts. This manual gives suggestions on when to use &rcs;. This manual has an introduction to using &rcs; This manual gives examples of how to incorporate &rcs; in your work. This manual gives suggestions on proper practices in &rcs;. This manual has the man pages included with the &gnu; distribution of &rcs;. This manual contains technical information about how &rcs; works. This manual contains installation information. In some sections we talk about this. In some sections we talk about that. In some sections we talk about the other thing.

file systemsAbstraction file fystemsDesign filesystemsfile systems folders directories Where does version control fit in the realm of computer tools and computer design? The following section takes a look at the problems version control tries to solve. There is no reason to adopt the use of a system when there is no need for it. The purpose of version control should become clear by taking a broader view of version control's place as a computer technology. Specifically, by looking at how version control is an extension of the computer file system design.

What is a file system? The computer file system is a design that has a long history. Computer users use file systems every day forgetting the importance of this genius abstraction of computer storage. This pervasive design can seem archaic, clumsy or even outdated. However, a higher abstraction that provides an improved way for storing digital information has yet to unseat the universally accepted file system. File systems are characterized as having components which include filesfilesfile system componentfilescomponenet, file system and directoriesdirectoriesfile system componeent (known to some as foldersfoldersdirectories). These file system elements also have defined properties. For instance, directories can contain files or more directories (these nested directories are commonly known as subdirectoriessubdirectories. Files on the other hand are single atomic units that contain varying amounts of data. This design makes available a set of operations to these file system objects. Files and directories can be created, deleted, and renamed. Files are special since they can have their contents modified, known as read and write operations. There are extensions to this design, including linked files, device files, and the ability to execute (run) a file as program. Information is sometimes attributed to file system objects including file size, creation date, modification date, file ownership and access permissions. This basic abstraction for file storage on computer systems is a paradigm that pervades all types of computers. One can only guess this genius but archaic paradigm will last indefinitely.

What is missing from the file system design? Unfortunately (or perhaps fortunately), the file system paradigm only provides a static representation of file systems. File systems can save the current contents of a file, but the past states of the file are lost. The notion that files are constantly changing is not incorporated into the design. In practice, computer users are constantly modifying the contents of files. File modification represents one of the most common and basic tasks for a computer user. When a user edits a file, the state, or makeup, of its previous contents are lost. To keep an old versionversion of a file a nearly duplicate copy would be needed to continue editing a newer copy. Keeping an older version of a file requires making a copy with a different name. This system of renaming files is a weak way of tracing the changes of a file's contents. Failing to integrate the dynamic and ever-changing nature of the file system in the original design was not a poor decision. A good abstraction--which the file system model is--avoids incorporating unnecessary extensions and complicated features. Another reason file system designers avoided incorporating maintaining file versions is because it is a fundamentally human task. How could a computer keep track of versions without being able to read the user's mind? It is suggested to users to save often to avoid losing their current work. How would a computer system differentiate between substantial revisions and precautionary file saving? If the solution was to keep every saved version of a file to arbitrary namesSomething the VAX operating system did., it could take a user forever to find the desired version among the thousand of saved versions.

The Revision Control System (&rcs;) is a tool that allows users to save the file modifications made over time. &rcs; allows users to store and retrieve versions of a file and allows users to associate information with each storing operation. The information associated to versions eases the task of retrieving versions and tracking changes to a file. Maintaining versions of files in &rcs; allows one to document the changes they have made to a file, for the benefit of themselves and their colleagues. Further, &rcs; provides features for handling groups of files, managing development among multiple individuals, and embedding and extracting version information in a working filefileworking file, a version of the file currently available to the user. It is a powerful yet simple tool for tracking the changes made to files. &rcs; is an addition to the file system design helpful to those who work with files.

Modifying Computer Files The most fundamental task on a computer is file modification. It is done in writing letters, writing books, creating web pages, writing documentation, programming software, drawing graphics, generating spreadsheets, working with digital imagery, and any other growing number of tasks being made possible on modern computers. The problem is there is no way to keep track of changes made to all these important files. Tracking changes to files can be beneficial and even a necessity to tasks that require backing up older versions, undoing previous changes, or documenting the changes of a file.

files renaming renaming files files One common situation the Revision Control System (&rcs;) can help users with is when they want to create backup copies. These backup copies can be for keeping old versions or as a precaution against losing your changes. Copying a file to a different name suffices to create versions and keep old copies. However, a few small modifications in a file often does not warrant the renaming of the file. Maintaining nearly duplicate copies of a file is a poor use of computer storage space. Homebrewed solutions of renaming files to file.old, file.bak, file.bak2 or some other variant is a weak system for describing the differences. Further, certain situations require a specific file name or file name extension. Renaming files is an inadequate way to maintain multiple versions of a file.

Version Systems

Version Control Systems purpose of A solution for storing the changes made to files and relating information to their changes is version control which provides the storage and retrieval of file versions (see section on versions). Version control systems act as databases by storing each version including helpful information about each version. Version control tools empower users to retrieve older versions of files, track file changes, and even supports multiple people working on the same files. Version control systems promote saving versions of files.

Version Control Systems features of Version control tools like the Revision Control System (&rcs;) provide a database-like storage system for file versions. These systems focus on storing revisions of a file in an efficient manner, and minimizing storage space. Specific information to each version is associated with each version including version date, version number, the person who stored the version, and a log entry entered by the user describing the version changes.

Version Control Systems basic operations Version Control Systems usage, basic Version Control Systems operations, basic check-in overview of check-out overview of While file systems provide operations like open, save, rename and delete, version control systems provide checking-inchecking-in and checking-outchecking-out. Like their file system counterparts checking-in stores a file version, and checking-out retrieves a file revision from the system. Upon checking-in a file, the system notes the current date and time, the name of the user submitting the revision, and prompts the user for a log message to be stored with the version. Unless otherwise explicitly specified by the user, the version control system automatically increments the version number. With checking-out, a complete copy of a file is retrieved from the version control system. The user can usually specify the version number or specify some other attribute, like revision date and time. If no information is specified then the most recent version of the file is made available.

Version Control Systems extra features Version Control Systems features, extra Version control systems usually include other tools and features for controlling files under version control. A log inspection tool is necessary for allowing users to investigate the version attributes and notes of a file, aiding search for a particular version or to track the revisions made by another person. A difference finding tool can display to a user what the difference between two versions are, or give what changes were made to the current working copy since the most recently checked-in revision. A version control system with a locking mechanism provides a means of restricting multiple people editing a file in a group development scenario. A version embedding and retrieving system would allow users to insert version information into the actual working files. This allows one to store version information in the working file, and be able to quickly determine version information about a working file.

Version Control Systems applications Version Control Systems uses Version control systems should be used by those who edit files. This is a broad generalization, but is largely true. There is some effort and learning on the part of the user necessary to utilize a version control system, however it is worth the effort. There are many tasks that do not require the use of a version control system, and even more that make it ridiculous. However, those who require or find themselves maintaining multiple versions of files, or needing to track the revision of files should seek the rewards of using a version control system. This is especially the case for those with release-critical tasks including writing, publishing, engineering, and software development. Being able to record, track and report changes in your work is a powerful asset for any discipline. Version control systems can aid group development projects. If one individual breaks or makes a poor modification to a file, an older version of that file can be retrieved. File locking (see section on file locking) can enforce multiple people editing a single file. Further, version control systems usually provide a way to merge two versions of a file, so that if two individuals edit the same version of file, there is still a chance the modifications can be combined. Version control systems, including the Revision Control System (&rcs;, were developed for and created by software programmers. They have provided sometimes awkward and specific tools for version control. For instance, version control systems assume they are working with text, and assume that changes are made on a line-by-line basis. However, recent version control systems, including &rcs;, are able to operate on a range of file formats, including Binary Filesbinary files. The greatest rewards of using a version control tool like &rcs; do not come from the rudimentary task of using the tool to store revisions, but come from having used such a tool. The reward of having used &rcs; appears when you accidentally lost your work, made a change that would have otherwise required you to start completely over, wish you had documented the changes you made to a file, or recognized the consequences of a change made long ago. Of course &rcs; provides a means of providing short-term revisions of files, but the true benefits of &rcs; are seen by investing in regular use of &rcs;. Stand-alone version control utilities like &rcs; have largely been disregarded by group development projects favoring other version repository systems. These other tools often provide network available repositories allowing individuals to submit versions of files over a network (like the InternetInternet). Some version control systems (which actually utilize &rcs; for low-level operations) also are complicated with numerous features that make learning impossible and small common tasks difficult. &rcs; however provides a stable and well accepted system for versioning your computer work. Individuals who have smaller-scale independent tasks can benefit from using &rcs;.

Version Control Systems applications Version Control Systems uses Version Control Systems purposes The original intended purpose of version control systems was to benefit software developers. A tool written by software developers to benefit software developers. The primary purpose being to help diffuse complications that arise from software projects of greater scope and with teams of expanding size. Therefore, software development is one of the primary beneficiaries of version control systems. However, there are other applications of version control. The place of version control systems in computer systems, as was presented previously, allows them to be extended to a variety of purposes. This includes any software application or task that uses files. Beyond computer programming, writers, authors and word processor users could use version control systems. Like software projects, authoring books and documentation projects can expand in size. Certain writing tasks can require maintaining versions of a piece. Writers often experiment and benefit from doing so in their work. Also maintaining editions of books is another common task of publishing that requires maintaining version information for files. Another technically-inclined group of individuals besides software programmers, are system administrators. This is another group of individuals who, early on, found benefits for version control systems. One of the tasks they found a purpose for their systems was their backup file systems. Rather than having to maintain multiple separate volumes for nightly backups of their systems, version control systems could instead store backup versions of files in a single volume and provide recovery by pulling a desired backup version stored at a particular date. These backup systems proved to be some of the most rigorous tests of version control software, but were an important addition to backup systems. As truly paperless electronic publishing system expands via the World Wide Web (web), the number of documents to maintain, and the constant modifications made to these documents grow enormously. Version control systems offer a tool for maintaing the chaos of web documents, scripts and applications. Most web servers offer their content by having access to selections of a file system. Therefore, web services that are file-based can be tied to version control systems. Version control systems are also designed for compilationcompilation tasks. This is another consequence of version control systems being used initially by software programmers. In computer programming and in advanced publishing applications, source files are compiled into target filesfilestargettarget filesfiles. For instance, computer program source code is compiled into binary executablesexecutables. Document source files are converted into printer-ready files. Version control systems, including &rcs;, can remove the source files for successfully compiled files. This feature is requested less frequently because storage space concerns are also infrequent. However, removing files in a working directoryworking directory can remove files that have been rendered inconsequential by compilation. Since version control systems were originally for software development, they lend themselves easily to file-based projects that are released intermittently and modified in the mean time. Much of the design was towards releasing specific versions of the files. But this can carry over to any computer task that requires releasing files to the world, but maintaining information about the version of each release.

Version Control Systems skills to learn Version Control Systems learn, skills to &rcs; skills to learn &rcs; learn, skills to Learning to use the Revision Control System (&rcs;) requires minimal previous knowledge. Since &rcs; is largely an extension of the file system, users are expected to be familiar with the working with file systems. &rcs; is a command linecommand line tool, therefore familiarity with using the command line, also referred to as the shellshell is a skill necessary for learning &rcs;. So &rcs; requires a moderate amount of ability to work with the file system from the command line. &gnu; &rcs; is not available by the use of a graphical user interface (GUI). There are proprietary version control systems with GUIs, and people have even created ones for &rcs;. Currently, a free software GUI for &rcs; has not been created, but one need only be developed.

The origins and purposes of version control and some of the first tools.

Version control systems originate from tools that were for software development management. The software was not originally designed for general use in a variety of tasks.

&sccs; Source Code Control System&sccs; &cssc; Compatibly Stupid Source Control&cssc; The Source Code Control System (&sccs;) was written by Marc Rochkind at AT&T Bell Labs. &sccs; has been uses since the 1970s and is still found and used on many systems. &sccs; was the first notable program to offer version control. It was originally written for developers. The major features were versioning and the ability for multiple developers to work on the same system. &sccs; is different from &rcs; by its interface and its implementation. &rcs; improved from &sccs; with an easier interface for users and a few more features. One notable feature of &sccs; is missing from &rcs;. &sccs; has the ability to display each line and the most recent revision responsible for the line. The &gnu; system needed a free softwarefree software implementation of &sccs;. The name of this application is the Compatibly Stupid Source Control (&cssc;).

&rcs;history This section needs to be finished. The Revision Control System (&rcs;) was designed by &wft;. &rcs; was developed at the Department of Computer Science at Purdue University. It was implemented in 1982, and has been used ever since. In 1991, &rcs; was licensed under the &gnu; General Public License (&gpl;) and adopted as a &gnu; package. &rcs; was at the time a major improvement as a tool for version control. It was originally written for software developers, but had other users in mind. The major features were versioning and the ability for multiple developers on a single system to work together.

&cvs; Concurrent Version Control&cvs; This section needs to be finished. &cvs; was written by somebody. It was originally developed at someplace in some year. It has been used since some year. &cvs; was the first notable program to offer network-capable version control. It was originally written for developers. The major features were versioning and the ability for multiple developers to work on the same system. It originally started out as shell scripts which utilized &rcs;. &cvs; and &rcs; are consequently similar in use. &cvs; can be used over a network, like the Internet, between multiple developers. Today, &cvs; is no longer dependent on &rcs;. &rcs; is an easier system for version control than &cvs;, and is helpful for single user or single system scenarios.

At the time, the Revision Control System (&rcs;) was an improvement upon previous version control utilities. &rcs; proved easier to use and provided powerful features including reverse-deltas, faster retrievals, locking systems, complex branches, improved keywords, multiple-user support and a well developed archive file format. It has become a predominant version control system. And a free software implementation is available. When available, &rcs; should be used in most all routine computer work. With practice and increased familiarity, the applications and benefits of using &rcs; with your work will become more apparent. No need for multiple repositories Multi-user development on a single system &rcs; and file format well acceptance Day-to-day work

As version control systems extend the possibilities of file systems, they also expand the concepts necessary to use the new facilities they provide. Those who recognize the purpose and benefits of version control tools should have no trouble understanding the foundation concepts. However, there is necessity of a certain amount of synthesized jargon with subtle and distinctive meanings. The following terminology provides skills to understand version control and not become confused by it. Learning these concepts will also better your chances of fully leveraging the features of version control. Version version revisionversion A version is a full copy of a file which represents the state, or composition, of a file at a certain point in time. Files change over time. When being edited users are encouraged to save their changes as they work. However, every save that modifies the file overwrites and loses the previous copy. Like saving, version control systems allows one to save copies of the file, allowing one to keep track of versions of the file that is edited. Revision revision A revision is formally defined as a change, correction or improvement. This is different from versions (see section on versions) because revisions are the products of revising while the products of revisions are versions. Delta delta deltarevision A delta is a computer representation of the difference between two versions (see section on version) of a file; a computer usable revision (see section on revision). The delta is the literal representation of a revision. The delta usually isolates what differed in the file from what remained unchanged in the file. The unixunix operating system popularized, and the &gnu; System&gnu; System the use of text files on a line-by-line basis. Deltas are thus represented by the lines added, deleted or replaced. In computer systems, the representation of a delta can be manifested in numerous ways. A representation may benefit humans by being easily readable. A delta representation may be designed to be stored efficiently by minimizing size. Or a delta representation may place priority in precision by emphasizing deltas that can be reliable or secure for application to other versions. Fortunately, the different advantages to delta types are not so much an issue to users of version control. Deltas give version control systems the ability to maintain revisionsof of a file. Deltas allow any previous version of a file. This should be redone, reorganized and verified. Branches Branches Version control systems are well versed in storing the linear progression of changes to a file. They are also endowed to maintain disparate or different developments to a file. The ability for the changes to a file to pursue multiple paths is termed branching. The terminology of branches is obviously derived from trees of the plant kingdom whose limbs split and span into space in multiple directions. The same would be the case for thinking about a tree of versions for a file. The ability to maintain branches in file revisions aids experimentation and allows multiple ways of editing a file. Branches also help with files that are released to or edited by multiple people. If two people make subsequent changes to the file, branches are necessary to track the revisions made. In the case of distribution and file release of versions of a file, edts by others that are are put into version control should be added as a branch when the original author had continued making edits. These revisions submitted to the original author will need to be added as Trunk Trunk Branches (see section on branches) represent versions that develop separately from the main line of versions. This main line of versions are called trunk versions. More could be added here

files &rcs;'s design relies on files. &rcs; is able to take files and store versions for them, and also uses files to actually store the versions. The following is terminology to differentiate between these two types of files.

working filefile fileworking A working file is a complete copy of some version of the file that is available. This file need not necessarily be the latest or current version, it can be any past version. The need for the terminology to differentiate working files from other files, is because &rcs; creates files to store versions to and operate with. Working files are no different from all the files you were previously familiar with working one.

version file library fileversion file &rcs; fileversion file archive fileversion file version archiveversion file fileversion fileversion file A version file is used by &rcs; to store version information. These files are the same name as the working file except they end in a suffix, which is by default ,v. For example, if you wanted version to keep track of a working file named freedom.txt &rcs; would create and use a version file named freedom.txt,v. The extension ,v stands for version file (see section on file naming). Which extension &rcs; should recognize as version files can be modified with a command-line option. Version filesversion file contain all the information necessary to retrieve any version. Besides storing past versions these files also contain the information related to each version, including date, version number and your notes. The existence of version filesversion file is necessary for all &rcs; operations. These files must be available in the current directory or a subdirectory named RCS (see section on file naming).

Version Numbers Each submitted version of a file to &rcs; is given a version number. Each version is given more information than just an arbitrary version number. Descriptive notes about versions should be added to each version by the individual submitting the changes. However, version numbers are used as a numerical shorthand to represent versions. Version numbers are strings composed of numerical digits and periods (.), examples include 1.1, 1.2, 1.23, 2.3.1.1 and 4.271.4.3. These numbers obviously specify the number of versions but also have other implied meanings about a version. The periods separating the numbers break up the different components of a version number. Each of these numbers gives hints about a version of a file or the file's history.

Release Numbers The first number in a version number is always the release number. For example, for the version number 1.2, the release number is 1. The release number for the version number 21.16.3.1 is 21. The release number is largely arbitrary. The initial release number of a file committed to &rcs; is one, resulting in an initial version number of 1.1. Incrementing the release number is decided by the user at their discretion. If a number of changes to a file results in what the author concludes is a different or new file, then they could increment the release number to separate future edits from past edits. This notation is a legacy of software development and their projects and products which are released with version numbers. Examples of software project versions include Gnu Emacs 19, &rcs; 5.7 or Linux 2.0.36. Changes from version like 4 to 5, or from 3.23 to 3.24 represent major or minor changes based on the judgment of the author or authors. This philosophy should similarly by applied to files in &rcs;. Numerous changes to a file that are logged with &rcs; will fail to separate major changes from minor ones. Changing the release number at well judged states of the file can help with retrieving older versions. Changing the release number too willingly can result in too numerous release numbers that can also hide where the substantial changes are.

Revision Numbers The last number in a version number is a revision number. The revision number for the version number 1.1 is 1. The release number for the version number 2.34.1.3 is 3. The revision number represents how many different versions have been made to a file. &rcs; automatically increases the revision number when a new version of a file is submitted, or can be specified by the user but must be a number greater than the current version. Similar to release numbers (see section on release numbers), numerous revisions to a file should be submitted often to &rcs;. Increasing the number of revisions along with notes that describe the changes made in the revision help better separate the changes made to a file over time. A large number of submitted changes to &rcs; resulting in large revision numbers will fail to make it clear which were groups of changes that made a major difference and which were only minor ones. This is where the feature of release numbers allows one to categorize major groups of changes as a release number. For example, after starting a file with version 1.1 then making dozens of changes until version 1.27 the author could decide to have these versions be part of release 1 and begin release 2 with version 2.1.

Branch Numbers A branch number is a number appended to a version number (see section on version number), representing a branch (see section on branch) in revisions (see section on revision) to a version of the file. The version number 2.3 would have its first branch number be 2.3.1. Now 2.3.1 is not a full version number. It says that revision number 3 of release number 2 was branched once. What about revisions to the branch? The first revision number on this branch is 1 resulting in the version number 2.3.1.1. To review, the branch number on the version number 1.7.3.5 is 3. The branch number represents how many branches have occurred to a version. &rcs; does not require the first branch to be 1. When a branch to a version is desired, choose a branch number. Good practice would have branch numbers represent the actual number of branches. More could be added here

Tree Numbers Like branch numbers (see section on branch numbers), tree numbers are version numbers with a specific format. Branch numbers are version numbers (see section on version numbers) with a branch number. Tree numbers take the form of a version number (see section on version numbers) without a branch number. Of course this is a logical corollary, but is a necessary point because a revision is only located on the main tree only if it has a tree version number. The version number 1.1 and 19.84 are examples of tree numbers. All other number formats are branch numbers. Branch numbers can never represent versions on the trunk.

Locking Maintaining version information for files is a primary purpose of version control systems. But with a design purpose serving software development, access to files by multiple people is a fundamental feature. Version control systems like &rcs; were a requirement for larger software development teams writing massive computer applications. One powerful feature of file systems on multiple-user systems is sharing files. Along with multi-user systems file permissions provide a system of ownership and access privileges for users who wish to read and edit files. A situation arises where individuals could be editing the same file at the same time. This creates a scenario where the modifications of one person could overwrite the modifications of another. &rcs; provides the locking mechanism, to avoid this situation. Need to redo some of this.

Locked A file is locked in &rcs; when one person checks-out (see section on check-out) a file giving them exclusive rights to editing the file. The individual having the lock is considered the locker. Since &rcs; is a version control system, files are not the unit that are locked. Versions of files are what are cable of being locked. Multiple people (or the same person) can check-out and lock multiple versions of the same file, so long as they are not locking the same versions. Locks are enforced by denying attempts to check-out a locked version. These can however be circumvented by breaking the lock. The breaking of a lock is usually followed with a message to the

Unocked A file is unlocked in &rcs; when no person has checked-out (see section on check-out) a file as locked (see section on locked). Checking-out a file only as unlocked is necessary when the file only needs to be read but not edited. This can be the case when the file needs to be available for processing by an application or simply for human review. Anything else to mention here?

LockingStrict In order to keep two or more individuals from simultenously editing the same file in &rcs;, strict locking enforces that only one person has the ability to edit a file. &rcs; enforces locking by ensuring that only one person can check-out (see section on checking-out) a version (see section on versions) of a file can be made at a time. Other versions of a file can be checked-out at one time Need to explain strictness. Need to explain details of how it works. Need to explain details of how to turn on or off strict locking (could be put somewhere else, though, perhaps a more advanced place).

Keywords Version control keywords are another release-related feature providing a mechanism for finding version information about a released working file (see section on working file). When files under version control are released, it can become necessary to know the version of a released file. This is common in scenarios where software bugs, problems, questions or even a suggestion relative are made relative to source code file of a software release. Without keywords, there is a great amount of difficulty finding which version of a released file. The alternative without version control is comparisons with every past version of the file. Fortunately, version control systems provide keywords which can be placed in files and updated automatically by version control. Keyword in &rcs; are unique strings which are substituted with values related to the file's revision, including revision number, revision date and author. In &rcs;, keywords are inserted into working files as recognized terms between two dollar-symbols ($). Some of these recognized terms are the strings Revision, Author, Date, Log and Id.

The following is a quick tutorial on using RCS starting with new files never previously combined in RCS. The tutorial will be short and quick. Important concepts will be overlooked and some fo the useful and powerful features of &rcs; will not be introduced. Instead, the general use of &rcs; is introdued to generate familiarity with the operations of &rcs; and the skills of version control.

The following examples will use the file our_file.txt. The commands assume our_file.txt is in the current directory, meaning the commands are run in the same directory the file our_file.txt is located in.

By default, when a file is initially checked-in (see section on checking-in), the respective version fileversion file (see section on version files) is placed in the same directory as the file. To avoid cluttering the directory, an RCS subdirectory can be created to collect the &rcs; files. If the subdirectory already exists, &rcs; will store all &rcs; files there rather than in the same directory as the working fileversion filedirectory location (see section on working file). Create an RCS subdirectory with the following command: $ mkdir RCS

check-in tutorial 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 the locations of the working file and the &rcs; file, and the prompts for a description. The default check-in behavior deletes the working file from the current directory if it is successfully checked-in. 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 lowercase letter v (,v) appended to the filename. A ,v is the default extension to &rcs; files. There are few reasons to change this behavior, but this behavior can be modified so &rcs; looks for a different extension for &rcs; files (see section on extension option). If the current directory does not have an RCS subdirectory, then the &rcs; file is placed in the same directory as the working file. After displaying the files in consideration, &rcs; gives directions on how to submit a file description (see section on file description). After these directions an interactive prompt expects a description to be inputed.

file description entering description file file description With the initial check-in (see section on check-in) of 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 (see section on file descriptions) 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 impractical and vague names like the one used in this example. So names should describe what the purpose of the file is and what type a file is that is more expressive than the file name extension. In the example, the extension is .txt. Descriptions, as &rcs; requests, must end with a single period (.), or an end of file character. An end of file character is issued on most systems by typing Ctrl D (^D). By single, &rcs; requests the period or end of file should be the only single-only character on the line. After entering the 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 provided as a command-line argument (see section on file description option), rather than taken from standard inputstandard inputfile descriptions.

check-out tutorial check-out unlocked check-out for reading Upon checking-in a file, &rcs; by default deletes the working copy (see section on working file) 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 in the current working directory but is unlocked (see section on unlocked) and therefore read-only. The file is read-only because the revision of the file would need to be locked (see section on locking). The file is actually unlocked, as &rcs; outputs above. It could have been checked-out with the more explicit check-out command specifying the -u option: $ co -u our_file.txt RCS/our_file.txt,v --> our_file.txt revision 1.1 (unlocked) done

check-out tutorial check-out locked check-out for editing To check-out the file for editing, a request for a lock and a request for retrieval of a version can be made with: $ 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 more efficient for actively editing and checking-in revisions of a file, and is used often. The single checking-in command is: $ 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

check-out previous revisions 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 familiarity and habit in using version control. However, the benefits of version control comes from being able to access previous revisions of a file. Retrieving revisions is done directly and simply by providing 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 as a request for the latest revision. After checking-in the file the first time, the latest revision of the file could have been retrieved by specifying the revision with the following revision option: $ co -r1.1 our_file.txt The revision command-line option can be combined with the check-out's locking option. The checking-out and locking of the example's first revision could have been accomplished 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 abbreviated: $ co -l1.1 our_file.txt The above options are also recognized by the check-in command for combining the checking-in, checking-out and locking of a file and simulatenously specifying a specific revision. To check-in, check-out and lock the second revision: $ ci -l1.2 our_file.txt

differences revision differences differences After making edits to the file, &rcs; can display the difference between the working file and the latest version. This is helpful when a file has been edited since you last checked it out and see the specific changes made to a file. The name of the command is rcsdiff. rcsdiff takes the same options as the diff command (see manual on diff). 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.

Another feature desired by users of &rcs; besides basic version control is file keywords. To utilize &rcs; keywords (see section on keywords) simply insert the keywords into the file. For example, placing the well-known Id keyword at the end of the file is accomplished by this shell command: $ echo '$∅Id$' >> 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 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: our_file.txt,v 1.3 2003-05-27 03:11:54-04 ashawley Exp $

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: our_file.txt,v 1.3 2003-05-27 03:11:54-04 ashawley Exp $ A comparable result to this command is accomplished with the grep command: $ grep -e '\$Id: rcs.xml,v 1.8 2005/04/05 19:06:10 ashawley Exp $' our_file.txt $∅Id: our_file.txt,v 1.3 2003-05-27 03:11:54-04 ashawley Exp $ Using ident is more predictable than using grep. The grep command will display any other text that is on the same line as an &rcs; variable. Besides being easier to run than grep, ident innately knows which &rcs; variables while grep requires they all be specified

The &rcs; log command can retrieve and display meta-information about versions of a file. Here is information of what we have done to the example text file in &rcs;: $ 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: 2003-05-27 03:11:54-04; author: ashawley; state: Exp; lines: +1 -0 Added Id keyword. ---------------------------- revision 1.2 date: 2003-05-27 03:08:56-04; author: ashawley; state: Exp; lines: +1 -0 Added another question. ---------------------------- revision 1.1 date: 2003-05-27 03:07:51-04; author: ashawley; state: Exp; Initial revision ============================================================================= The response of the &rcs; log command highlights the file's information including the path of the RCS file (see section on RCS file), the path of the working 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 for the revision.

This tutorial covered the fundamental operations of version control with &rcs;. The total functionality offered by &rcs; far surpasses the coverage of the introduction offered in this section. However, familiarity with just these routine version control tasks leverages many of the critical benefits of version control. The advanced features of &rcs; are still available for future use. From here, other concepts and features of &rcs; can be learned and understood. Other features and concepts skipped include branches, merges, keyword substitution options, version names, file initialization 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.

&appendixgfdl;