Whole document tree
For many uses of CVS, one doesn't need to worry
too much about revision numbers; CVS assigns
numbers such as
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', `126.96.36.199' or even `188.8.131.52.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.
It is also possible to end up with numbers containing more than one period, for example `184.108.40.206'. 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,
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
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
For example, to bring all your files up to revision 3.0 (including those that haven't changed), you might invoke:
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:
You can use the
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
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.
For a complete summary of the syntax of
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.
(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.)
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:
At some time in the past, the
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
One potentially surprising aspect of the fact that
4.6 Specifying what to tag by date or revision
The following options specify which date or revision to tag. See A.5 Common command options, for a complete description of them.
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 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).
deletes the tag
When we say move a tag, we mean to make the same
name point to different revisions. For example, the
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
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
On the subject of adding and removing files, the
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
The sticky tags will remain on your working files until you delete them with `cvs update -A'. The `-A' option retrieves the version of the file from the head of the trunk, and forgets any sticky tags, dates, or options.
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
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
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
This document was generated on September, 1 2005 using texi2html