If you modify a program to better fit your site, you
probably want to include your modifications when the next
release of the program arrives. CVS can help you with
In the terminology used in CVS, the supplier of the
program is called a vendor. The unmodified
distribution from the vendor is checked in on its own
branch, the vendor branch. CVS reserves branch
1.1.1 for this use.
When you modify the source and commit it, your revision
will end up on the main trunk. When a new release is
made by the vendor, you commit it on the vendor branch
and copy the modifications onto the main trunk.
import command to create and update
the vendor branch. When you import a new file,
the vendor branch is made the `head' revision, so
anyone that checks out a copy of the file gets that
revision. When a local modification is committed it is
placed on the main trunk, and made the `head'
import command to check in the sources
for the first time. When you use the
command to track third-party sources, the vendor
tag and release tags are useful. The
vendor tag is a symbolic name for the branch
(which is always 1.1.1, unless you use the `-b
branch' flag--see Multiple vendor branches.). The
release tags are symbolic names for a particular
release, such as `FSF_0_04'.
import does not change the
directory in which you invoke it. In particular, it
does not set up that directory as a CVS working
directory; if you want to work with the sources import
them first and then check them out into a different
directory (see section Getting the source).
Suppose you have the sources to a program called
wdiff in a directory `wdiff-0.04',
and are going to make private modifications that you
want to be able to use even when new releases are made
in the future. You start by importing the source to
$ cd wdiff-0.04
$ cvs import -m "Import of FSF v. 0.04" fsf/wdiff FSF_DIST WDIFF_0_04
The vendor tag is named `FSF_DIST' in the above
example, and the only release tag assigned is
When a new release of the source arrives, you import it into the
repository with the same
import command that you used to set up
the repository in the first place. The only difference is that you
specify a different release tag this time:
$ tar xfz wdiff-0.05.tar.gz
$ cd wdiff-0.05
$ cvs import -m "Import of FSF v. 0.05" fsf/wdiff FSF_DIST WDIFF_0_05
WARNING: If you use a release tag that already exists in one of the
repository archives, files removed by an import may not be detected.
For files that have not been modified locally, the newly created
revision becomes the head revision. If you have made local
import will warn you that you must merge the changes
into the main trunk, and tell you to use `checkout -j' to do so:
$ cvs checkout -jFSF_DIST:yesterday -jFSF_DIST wdiff
The above command will check out the latest revision of
`wdiff', merging the changes made on the vendor branch `FSF_DIST'
since yesterday into the working copy. If any conflicts arise during
the merge they should be resolved in the normal way (see section Conflicts example). Then, the modified files may be committed.
However, it is much better to use the two release tags rather than using
a date on the branch as suggested above:
$ cvs checkout -jWDIFF_0_04 -jWDIFF_0_05 wdiff
The reason this is better is that
using a date, as suggested above, assumes that you do
not import more than one release of a product per day.
More importantly, using the release tags allows CVS to detect files
that were removed between the two vendor releases and mark them for
import has no way to detect removed files, you
should do a merge like this even if
import doesn't tell you to.
You can also revert local changes completely and return
to the latest vendor release by changing the `head'
revision back to the vendor branch on all files. For
example, if you have a checked-out copy of the sources
in `~/work.d/wdiff', and you want to revert to the
vendor's version for all the files in that directory,
you would type:
$ cd ~/work.d/wdiff
$ cvs admin -bFSF_DIST .
You must specify the `-bFSF_DIST' without any space
after the `-b'. See section admin options.
Use the `-k' wrapper option to tell import which
files are binary. See section The cvswrappers file.
The sources which you are importing may contain
keywords (see section Keyword substitution). For example,
the vendor may use CVS or some other system
which uses similar keyword expansion syntax. If you
just import the files in the default fashion, then
the keyword expansions supplied by the vendor will
be replaced by keyword expansions supplied by your
own copy of CVS. It may be more convenient to
maintain the expansions supplied by the vendor, so
that this information can supply information about
the sources that you imported from the vendor.
To maintain the keyword expansions supplied by the
vendor, supply the `-ko' option to
import the first time you import the file.
This will turn off keyword expansion
for that file entirely, so if you want to be more
selective you'll have to think about what you want
and use the `-k' option to
cvs update or
cvs admin as appropriate.
All the examples so far assume that there is only one
vendor from which you are getting sources. In some
situations you might get sources from a variety of
places. For example, suppose that you are dealing with
a project where many different people and teams are
modifying the software. There are a variety of ways to
handle this, but in some cases you have a bunch of
source trees lying around and what you want to do more
than anything else is just to all put them in CVS so
that you at least have them in one place.
For handling situations in which there may be more than
one vendor, you may specify the `-b' option to
cvs import. It takes as an argument the vendor
branch to import to. The default is `-b 1.1.1'.
For example, suppose that there are two teams, the red
team and the blue team, that are sending you sources.
You want to import the red team's efforts to branch
1.1.1 and use the vendor tag RED. You want to import
the blue team's efforts to branch 1.1.3 and use the
vendor tag BLUE. So the commands you might use are:
$ cvs import dir RED RED_1-0
$ cvs import -b 1.1.3 dir BLUE BLUE_1-5
Note that if your vendor tag does not match your
`-b' option, CVS will not detect this case! For
$ cvs import -b 1.1.3 dir RED RED_1-0
Be careful; this kind of mismatch is sure to sow
confusion or worse. I can't think of a useful purpose
for the ability to specify a mismatch here, but if you
discover such a use, don't. CVS is likely to make this
an error in some future release.