4. Revisions

For many uses of CVS, one doesn't need to worry too much about revision numbers; CVS assigns numbers such as 1.1, 1.2, and so on, and that is all one needs to know. However, some people prefer to have more knowledge and control concerning how CVS assigns revision numbers.

If one wants to keep track of a set of revisions involving more than one file, such as which revisions went into a particular release, one uses a tag, which is a symbolic revision which can be assigned to a numeric revision in each file.

4.1 Revision numbers

Each version of a file has a unique revision number. Revision numbers look like `1.1', `1.2', `1.3.2.2' or even `1.3.2.2.4.5'. A revision number always has an even number of period-separated decimal integers. By default revision 1.1 is the first revision of a file. Each successive revision is given a new number by increasing the rightmost number by one. The following figure displays a few revisions, with newer revisions to the right.

       +-----+    +-----+    +-----+    +-----+    +-----+
       ! 1.1 !----! 1.2 !----! 1.3 !----! 1.4 !----! 1.5 !
       +-----+    +-----+    +-----+    +-----+    +-----+

It is also possible to end up with numbers containing more than one period, for example `1.3.2.2'. Such revisions represent revisions on branches (see section 5. Branching and merging); such revision numbers are explained in detail in 5.4 Branches and revisions.

4.2 Versions, revisions and releases

A file can have several versions, as described above. Likewise, a software product can have several versions. A software product is often given a version number such as `4.1.1'.

Versions in the first sense are called revisions in this document, and versions in the second sense are called releases. To avoid confusion, the word version is almost never used in this document.

4.3 Assigning revisions

By default, CVS will assign numeric revisions by leaving the first number the same and incrementing the second number. For example, 1.1, 1.2, 1.3, etc.

When adding a new file, the second number will always be one and the first number will equal the highest first number of any file in that directory. For example, the current directory contains files whose highest numbered revisions are 1.7, 3.1, and 4.12, then an added file will be given the numeric revision 4.1.

Normally there is no reason to care about the revision numbers--it is easier to treat them as internal numbers that CVS maintains, and tags provide a better way to distinguish between things like release 1 versus release 2 of your product (see section 4.4 Tags--Symbolic revisions). However, if you want to set the numeric revisions, the `-r' option to cvs commit can do that. The `-r' option implies the `-f' option, in the sense that it causes the files to be committed even if they are not modified.

For example, to bring all your files up to revision 3.0 (including those that haven't changed), you might invoke:

$ cvs commit -r 3.0

Note that the number you specify with `-r' must be larger than any existing revision number. That is, if revision 3.0 exists, you cannot `cvs commit -r 1.3'. If you want to maintain several releases in parallel, you need to use a branch (see section 5. Branching and merging).

4.4 Tags--Symbolic revisions

The revision numbers live a life of their own. They need not have anything at all to do with the release numbers of your software product. Depending on how you use CVS the revision numbers might change several times between two releases. As an example, some of the source files that make up RCS 5.6 have the following revision numbers:

ci.c            5.21
co.c            5.9
ident.c         5.3
rcs.c           5.12
rcsbase.h       5.11
rcsdiff.c       5.10
rcsedit.c       5.11
rcsfcmp.c       5.9
rcsgen.c        5.10
rcslex.c        5.11
rcsmap.c        5.2
rcsutil.c       5.10

You can use the tag command to give a symbolic name to a certain revision of a file. You can use the `-v' flag to the status command to see all tags that a file has, and which revision numbers they represent. Tag names must start with an uppercase or lowercase letter and can contain uppercase and lowercase letters, digits, `-', and `_'. The two tag names BASE and HEAD are reserved for use by CVS. It is expected that future names which are special to CVS will be specially named, for example by starting with `.', rather than being named analogously to BASE and HEAD, to avoid conflicts with actual tag names.

You'll want to choose some convention for naming tags, based on information such as the name of the program and the version number of the release. For example, one might take the name of the program, immediately followed by the version number with `.' changed to `-', so that CVS 1.9 would be tagged with the name cvs1-9. If you choose a consistent convention, then you won't constantly be guessing whether a tag is cvs-1-9 or cvs1_9 or what. You might even want to consider enforcing your convention in the taginfo file (see section 8.3 User-defined logging).

The following example shows how you can add a tag to a file. The commands must be issued inside your working directory. That is, you should issue the command in the directory where `backend.c' resides.

$ cvs tag rel-0-4 backend.c
T backend.c
$ cvs status -v backend.c
===================================================================
File: backend.c         Status: Up-to-date

    Version:            1.4     Tue Dec  1 14:39:01 1992
    RCS Version:        1.4     /u/cvsroot/yoyodyne/tc/backend.c,v
    Sticky Tag:         (none)
    Sticky Date:        (none)
    Sticky Options:     (none)

    Existing Tags:
        rel-0-4                     (revision: 1.4)

For a complete summary of the syntax of cvs tag, including the various options, see B. Quick reference to CVS commands.

There is seldom reason to tag a file in isolation. A more common use is to tag all the files that constitute a module with the same tag at strategic points in the development life-cycle, such as when a release is made.

$ cvs tag rel-1-0 .
cvs tag: Tagging .
T Makefile
T backend.c
T driver.c
T frontend.c
T parser.c

(When you give CVS a directory as argument, it generally applies the operation to all the files in that directory, and (recursively), to any subdirectories that it may contain. See section 6. Recursive behavior.)

The checkout command has a flag, `-r', that lets you check out a certain revision of a module. This flag makes it easy to retrieve the sources that make up release 1.0 of the module `tc' at any time in the future:

$ cvs checkout -r rel-1-0 tc

This is useful, for instance, if someone claims that there is a bug in that release, but you cannot find the bug in the current working copy.

You can also check out a module as it was at any given date. See section A.7.1 checkout options. When specifying `-r' to any of these commands, you will need beware of sticky tags; see 4.9 Sticky tags.

When you tag more than one file with the same tag you can think about the tag as "a curve drawn through a matrix of filename vs. revision number." Say we have 5 files with the following revisions:

        file1   file2   file3   file4   file5

        1.1     1.1     1.1     1.1  /--1.1*      <-*-  TAG
        1.2*-   1.2     1.2    -1.2*-
        1.3  \- 1.3*-   1.3   / 1.3
        1.4          \  1.4  /  1.4
                      \-1.5*-   1.5
                        1.6

At some time in the past, the * versions were tagged. You can think of the tag as a handle attached to the curve drawn through the tagged revisions. When you pull on the handle, you get all the tagged revisions. Another way to look at it is that you "sight" through a set of revisions that is "flat" along the tagged revisions, like this:

        file1   file2   file3   file4   file5

                        1.1
                        1.2
                1.1     1.3                       _
        1.1     1.2     1.4     1.1              /
        1.2*----1.3*----1.5*----1.2*----1.1     (--- <--- Look here
        1.3             1.6     1.3              \_
        1.4                     1.4
                                1.5

4.5 Specifying what to tag from the working directory

The example in the previous section demonstrates one of the most common ways to choose which revisions to tag. Namely, running the cvs tag command without arguments causes CVS to select the revisions which are checked out in the current working directory. For example, if the copy of `backend.c' in working directory was checked out from revision 1.4, then CVS will tag revision 1.4. Note that the tag is applied immediately to revision 1.4 in the repository; tagging is not like modifying a file, or other operations in which one first modifies the working directory and then runs cvs commit to transfer that modification to the repository.

One potentially surprising aspect of the fact that cvs tag operates on the repository is that you are tagging the checked-in revisions, which may differ from locally modified files in your working directory. If you want to avoid doing this by mistake, specify the `-c' option to cvs tag. If there are any locally modified files, CVS will abort with an error before it tags any files:

$ cvs tag -c rel-0-4
cvs tag: backend.c is locally modified
cvs [tag aborted]: correct the above errors first!

4.6 Specifying what to tag by date or revision

The cvs rtag command tags the repository as of a certain date or time (or can be used to tag the latest revision). rtag works directly on the repository contents (it requires no prior checkout and does not look for a working directory).

The following options specify which date or revision to tag. See A.5 Common command options, for a complete description of them.

-D date

Tag the most recent revision no later than date.

-f

Only useful with the `-D date' or `-r tag' flags. If no matching revision is found, use the most recent revision (instead of ignoring the file).

-r tag

Only tag those files that contain existing tag tag.

The cvs tag command also allows one to specify files by revision or date, using the same `-r', `-D', and `-f' options. However, this feature is probably not what you want. The reason is that cvs tag chooses which files to tag based on the files that exist in the working directory, rather than the files which existed as of the given tag/date. Therefore, you are generally better off using cvs rtag. The exceptions might be cases like:

cvs tag -r 1.4 stable backend.c

4.7 Deleting, moving, and renaming tags

Normally one does not modify tags. They exist in order to record the history of the repository and so deleting them or changing their meaning would, generally, not be what you want.

However, there might be cases in which one uses a tag temporarily or accidentally puts one in the wrong place. Therefore, one might delete, move, or rename a tag.

Warning: the commands in this section are dangerous; they permanently discard historical information and it can be difficult or impossible to recover from errors. If you are a CVS administrator, you may consider restricting these commands with taginfo (see section 8.3 User-defined logging).

To delete a tag, specify the `-d' option to either cvs tag or cvs rtag. For example:

cvs rtag -d rel-0-4 tc

deletes the non-branch tag rel-0-4 from the module tc. In the event that branch tags are encountered within the repository with the given name, a warning message will be issued and the branch tag will not be deleted. If you are absolutely certain you know what you are doing, the -B option may be specified to allow deletion of branch tags. In that case, any non-branch tags encountered will trigger warnings and will not be deleted.

Warning: Moving branch tags is very dangerous! If you think you need the -B option, think again and ask your CVS administrator about it (if that isn't you). There is almost certainly another way to accomplish what you want to accomplish.

When we say move a tag, we mean to make the same name point to different revisions. For example, the stable tag may currently point to revision 1.4 of `backend.c' and perhaps we want to make it point to revision 1.6. To move a non-branch tag, specify the `-F' option to either cvs tag or cvs rtag. For example, the task just mentioned might be accomplished as:

cvs tag -r 1.6 -F stable backend.c

If any branch tags are encountered in the repository with the given name, a warning is issued and the branch tag is not disturbed. If you are absolutely certain you wish to move the branch tag, the -B option may be specified. In that case, non-branch tags encountered with the given name are ignored with a warning message.

Warning: Moving branch tags is very dangerous! If you think you need the -B option, think again and ask your CVS administrator about it (if that isn't you). There is almost certainly another way to accomplish what you want to accomplish.

When we say rename a tag, we mean to make a different name point to the same revisions as the old tag. For example, one may have misspelled the tag name and want to correct it (hopefully before others are relying on the old spelling). To rename a tag, first create a new tag using the `-r' option to cvs rtag, and then delete the old name. (Caution: this method will not work with branch tags.) This leaves the new tag on exactly the same files as the old tag. For example:

cvs rtag -r old-name-0-4 rel-0-4 tc
cvs rtag -d old-name-0-4 tc

4.8 Tagging and adding and removing files

The subject of exactly how tagging interacts with adding and removing files is somewhat obscure; for the most part CVS will keep track of whether files exist or not without too much fussing. By default, tags are applied to only files which have a revision corresponding to what is being tagged. Files which did not exist yet, or which were already removed, simply omit the tag, and CVS knows to treat the absence of a tag as meaning that the file didn't exist as of that tag.

However, this can lose a small amount of information. For example, suppose a file was added and then removed. Then, if the tag is missing for that file, there is no way to know whether the tag refers to the time before the file was added, or the time after it was removed. If you specify the `-r' option to cvs rtag, then CVS tags the files which have been removed, and thereby avoids this problem. For example, one might specify -r HEAD to tag the head.

On the subject of adding and removing files, the cvs rtag command has a `-a' option which means to clear the tag from removed files that would not otherwise be tagged. For example, one might specify this option in conjunction with `-F' when moving a tag. If one moved a tag without `-a', then the tag in the removed files might still refer to the old revision, rather than reflecting the fact that the file had been removed. I don't think this is necessary if `-r' is specified, as noted above.

4.9 Sticky tags

Sometimes a working copy's revision has extra data associated with it, for example it might be on a branch (see section 5. Branching and merging), or restricted to versions prior to a certain date by `checkout -D' or `update -D'. Because this data persists -- that is, it applies to subsequent commands in the working copy -- we refer to it as sticky.

Most of the time, stickiness is an obscure aspect of CVS that you don't need to think about. However, even if you don't want to use the feature, you may need to know something about sticky tags (for example, how to avoid them!).

You can use the status command to see if any sticky tags or dates are set:

$ cvs status driver.c
===================================================================
File: driver.c          Status: Up-to-date

    Version:            1.7.2.1 Sat Dec  5 19:35:03 1992
    RCS Version:        1.7.2.1 /u/cvsroot/yoyodyne/tc/driver.c,v
    Sticky Tag:         rel-1-0-patches (branch: 1.7.2)
    Sticky Date:        (none)
    Sticky Options:     (none)

The sticky tags will remain on your working files until you delete them with `cvs update -A'. The `-A' option merges local changes into the version of the file from the head of the trunk, removing any sticky tags, dates, or options. See A.16 update--Bring work tree in sync with repository for more on the operation of cvs update.

The most common use of sticky tags is to identify which branch one is working on, as described in 5.3 Accessing branches. However, non-branch sticky tags have uses as well. For example, suppose that you want to avoid updating your working directory, to isolate yourself from possibly destabilizing changes other people are making. You can, of course, just refrain from running cvs update. But if you want to avoid updating only a portion of a larger tree, then sticky tags can help. If you check out a certain revision (such as 1.4) it will become sticky. Subsequent cvs update commands will not retrieve the latest revision until you reset the tag with cvs update -A. Likewise, use of the `-D' option to update or checkout sets a sticky date, which, similarly, causes that date to be used for future retrievals.

People often want to retrieve an old version of a file without setting a sticky tag. This can be done with the `-p' option to checkout or update, which sends the contents of the file to standard output. For example:

$ cvs update -p -r 1.1 file1 >file1
===================================================================
Checking out file1
RCS:  /tmp/cvs-sanity/cvsroot/first-dir/Attic/file1,v
VERS: 1.1
***************
$

However, this isn't the easiest way, if you are asking how to undo a previous checkin (in this example, put `file1' back to the way it was as of revision 1.1). In that case you are better off using the `-j' option to update; for further discussion see 5.8 Merging differences between any two revisions.