|
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.
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 Branching and merging); such revision numbers
are explained in detail in 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, 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.
(When using client/server CVS,
only files that are actually sent to the server are considered.)
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 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:
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 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 Taginfo).
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 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.)
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 checkout options. When specifying `-r' to
any of these commands, you will need beware of sticky
tags; see 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
|
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!
|
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 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:
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 the `taginfo' file (see section Taginfo).
To delete a tag, specify the `-d' option to either
cvs tag or cvs rtag. For example:
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
|
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.
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: 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 (other than sticky `-k' options on locally
modified files). See 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
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 Merging differences between any two revisions.
|
