A Manual to the GNU Revision Control System (RCS)

A User's Guide for Gaining the Benefits of Version Control

Aaron Hawley

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".


Table of Contents

Preface
The File System Design
The Missing Feature of the File System
A Solution for Changing Files
1. Background on Version Control
Purpose of Version Control
The Problem
Homebrewed Solutions
Enter Version Control Systems
Purpose of Version Control Systems
General Features of Version Control Systems
The Operations of Version Control Systems
Version Control System Features
When to Use Version Control Systems
Purposes of Version Control Systems
Skills Needed to Use a Version Control System
2. Introduction to Version Control
History of Version Control
Origins on Version Control
Concepts in Version Control
Fundamentals of Version Control
Files in Version Control
Version Numbers
Locking
A. GNU Free Documentation License
GNU Free Documentation License
0. PREAMBLE
1. APPLICABILITY AND DEFINITIONS
2. VERBATIM COPYING
3. COPYING IN QUANTITY
4. MODIFICATIONS
5. COMBINING DOCUMENTS
6. COLLECTIONS OF DOCUMENTS
7. AGGREGATION WITH INDEPENDENT WORKS
8. TRANSLATION
9. TERMINATION
10. FUTURE REVISIONS OF THIS LICENSE
ADDENDUM. How to use this License for your documents

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 files and directories (known to some as folders ). These file system elements also have defined properties. For instance, directories can contain files or more directories (these nested directories are commonly known as . 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.

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 version 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 precautious file saving ? If the solution was to keep every saved version of a file to arbitrary names [ 1 ] , it could take a user forever to find the desired version among the thousand of saved versions.



[ 1 ] Something the VAX operating system did.

Version control systems should be used by those who edit files. This is a broad statement, but it 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 RCS, were developed for and created by software programmers. They have provided sometimes akward 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 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 wouuld have otherwise required you to start completely over from scratch, 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 Internet ). 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.

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 layed out 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 maintaingin 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 rigourous 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 compilation tasks. This is another consequence of version control systems being used initially by software programmers. In computer programming and even in some advanced publishing applications, source files are compiled into target files . For instance, computer program source code is compiled into binary executables and document source files are formatted into printer-ready files This sentence could be clearer (in accuracy and written clarity) .

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 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.

Abstract

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.

Versions.  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.

Revisions.  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 .

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 mutiple 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 realesed 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, edits 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.  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

Abstract

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 File.  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.  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 exstension RCS should recognize as version files can be modified with a command-line option.RCS files 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 RCS files 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).

Abstract

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 useds 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.32-beta. Changes from version like 4 to 5, or from 3.23 to 3.24 represent major or minor changes based on the judgement 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, representing a branch in revisions 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 occured 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

Copyright © 2000,2001,2002 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

  1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

  2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.

  3. State on the Title page the name of the publisher of the Modified Version, as the publisher.

  4. Preserve all the copyright notices of the Document.

  5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

  6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below .

  7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

  8. Include an unaltered copy of this License.

  9. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

  10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

  11. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

  12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

  13. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.

  14. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.

  15. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements."

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4 . Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warrany Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement ( section 4 ) to Preserve its Title ( section 1 ) will typically require changing the actual title.