|[[cvs: Keyword substitution#Keyword substitution| << ]]|

|[[cvs: Keyword substitution#Problems with the $ Log$ keyword.| < ]]|

|[[cvs#Top| Up ]]|

|[[#Importing for the first time| > ]]|

|[[cvs: How your build system interacts with CVS#How your build system interacts with CVS| >> ]]|

|[[cvs#Top|Top]]|

|[[cvs: Table of Contents#SEC_Contents|Contents]]|

|[[cvs: Index#Index|Index]]|

|[[cvs: About this Manual#SEC_About| ? ]]|

== Tracking third-party sources ==

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 this task.

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.

Use the `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’ revision.

----

|[[#Tracking third-party sources| << ]]|

|[[#Tracking third-party sources| < ]]|

|[[#Tracking third-party sources| Up ]]|

|[[#Updating with the import command| > ]]|

|[[cvs: How your build system interacts with CVS#How your build system interacts with CVS| >> ]]|

|[[cvs#Top|Top]]|

|[[cvs: Table of Contents#SEC_Contents|Contents]]|

|[[cvs: Index#Index|Index]]|

|[[cvs: About this Manual#SEC_About| ? ]]|

=== Importing for the first time ===

Use the `import` command to check in the sources for the first time. When you use the `import` 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|Multiple vendor branches]].). The release tags are symbolic names for a particular release, such as ‘`FSF_0_04`’.

Note that `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 [[cvs: Overview#Getting the source|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 your repository:

$ 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 ‘`WDIFF_0_04`’.

----

|[[#Tracking third-party sources| << ]]|

|[[#Importing for the first time| < ]]|

|[[#Tracking third-party sources| Up ]]|

|[[#Reverting to the latest vendor release| > ]]|

|[[cvs: How your build system interacts with CVS#How your build system interacts with CVS| >> ]]|

|[[cvs#Top|Top]]|

|[[cvs: Table of Contents#SEC_Contents|Contents]]|

|[[cvs: Index#Index|Index]]|

|[[cvs: About this Manual#SEC_About| ? ]]|

=== Updating with the import command ===

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

For files that have not been modified locally, the newly created revision becomes the head revision. If you have made local changes, `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 [[cvs: Multiple developers#Conflicts example|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 removal. Since `import` has no way to detect removed files, you should do a merge like this even if `import` doesn’t tell you to.

----

|[[#Tracking third-party sources| << ]]|

|[[#Updating with the import command| < ]]|

|[[#Tracking third-party sources| Up ]]|

|[[#How to handle binary files with cvs import| > ]]|

|[[cvs: How your build system interacts with CVS#How your build system interacts with CVS| >> ]]|

|[[cvs#Top|Top]]|

|[[cvs: Table of Contents#SEC_Contents|Contents]]|

|[[cvs: Index#Index|Index]]|

|[[cvs: About this Manual#SEC_About| ? ]]|

=== Reverting to the latest vendor release ===

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 -bWDIFF .

You must specify the ‘`-bWDIFF`’ without any space after the ‘`-b`’. See section [[cvs: Guide to CVS commands#admin options|admin options]].

----

|[[#Tracking third-party sources| << ]]|

|[[#Reverting to the latest vendor release| < ]]|

|[[#Tracking third-party sources| Up ]]|

|[[#How to handle keyword substitution with cvs import| > ]]|

|[[cvs: How your build system interacts with CVS#How your build system interacts with CVS| >> ]]|

|[[cvs#Top|Top]]|

|[[cvs: Table of Contents#SEC_Contents|Contents]]|

|[[cvs: Index#Index|Index]]|

|[[cvs: About this Manual#SEC_About| ? ]]|

=== How to handle binary files with cvs import ===

Use the ‘`-k`’ wrapper option to tell import which files are binary. See section [[cvs: Reference manual for Administrative files#The cvswrappers file|The cvswrappers file]].

----

|[[#Tracking third-party sources| << ]]|

|[[#How to handle binary files with cvs import| < ]]|

|[[#Tracking third-party sources| Up ]]|

|[[#Multiple vendor branches| > ]]|

|[[cvs: How your build system interacts with CVS#How your build system interacts with CVS| >> ]]|

|[[cvs#Top|Top]]|

|[[cvs: Table of Contents#SEC_Contents|Contents]]|

|[[cvs: Index#Index|Index]]|

|[[cvs: About this Manual#SEC_About| ? ]]|

=== How to handle keyword substitution with cvs import ===

The sources which you are importing may contain keywords (see section [[cvs: Keyword substitution#Keyword substitution|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 `cvs 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.

----

|[[#Tracking third-party sources| << ]]|

|[[#How to handle keyword substitution with cvs import| < ]]|

|[[#Tracking third-party sources| Up ]]|

|[[cvs: How your build system interacts with CVS#How your build system interacts with CVS| > ]]|

|[[cvs: How your build system interacts with CVS#How your build system interacts with CVS| >> ]]|

|[[cvs#Top|Top]]|

|[[cvs: Table of Contents#SEC_Contents|Contents]]|

|[[cvs: Index#Index|Index]]|

|[[cvs: About this Manual#SEC_About| ? ]]|

=== Multiple vendor branches ===

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 example,

$ 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.

----

|[[#Tracking third-party sources| << ]]| | |[[cvs: How your build system interacts with CVS#How your build system interacts with CVS| >> ]]| |  |  |  |  |  | |[[cvs#Top|Top]]| | |[[cvs: Table of Contents#SEC_Contents|Contents]]| | |[[cvs: Index#Index|Index]]| | |[[cvs: About this Manual#SEC_About| ? ]]|

This document was generated on a sunny day using [http://www.nongnu.org/texi2html/ texi2html].