For many uses of CVS, one doesn't need to worry
too much about revision numbers; CVS assigns
numbers such as
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.
Each version of a file has a unique revision number. Revision numbers look like `1.1', `1.2', `22.214.171.124' or even `126.96.36.199.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 `188.8.131.52'. Such revisions represent revisions on branches (see section Branching and merging); such revision numbers are explained in detail in section Branches and revisions.
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.
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
4.12, then an added file will be given the
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 Tags--Symbolic revisions). However, if you want to set the
numeric revisions, the `-r' option to
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 Branching and merging).
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
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
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
cvs1_9 or what. You might
even want to consider enforcing your convention in the
taginfo file (see section 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
including the various options, see section 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 Recursive behavior.)
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 checkout options. When specifying `-r' to any of these commands, you will need beware of sticky tags; see section 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,
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
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!
cvs rtag command tags the repository as of a
certain date or time (or can be used to tag the latest
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 section Common command options, for a complete description of them.
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
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
rtag. The exceptions might be cases like:
cvs tag -r 1.4 backend.c
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 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 tag
rel-0-4 from the module
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 tag, specify the
`-F' option to either
cvs tag or
rtag. For example, the task just mentioned might be
cvs tag -r 1.6 -F stable backend.c
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. 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
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
then CVS tags the files which have been removed,
and thereby avoids this problem. For example, one
-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.
Sometimes a working copy's revision has extra data associated with it, for example it might be on a branch (see section 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: 184.108.40.206 Sat Dec 5 19:35:03 1992 RCS Version: 220.127.116.11 /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 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
section 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
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
not retrieve the latest revision until you reset the
cvs update -A. Likewise, use of the
`-D' option to
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
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 section Merging differences between any two revisions.
Go to the first, previous, next, last section, table of contents.