The Free and Open Productivity Suite
Follow us on Twitter: @ApacheOO
Contributing changes with command-line CVS

Working with files

Between checking files out of the project repository and checking them back in, CVS has virtually nothing to do with how files are used in the project environment or build process. That is governed by the project owner and other external factors unique to the project.

When you make changes to existing files, you must edit your working copies of these files in a file editor on your local machine using your file editor of choice. None of the changes you make to your working files has any effect on the project's source repository or on other developers' work until you check in (that is, do a cvs commit) your modified versions of files.

More about "What CVS is not." More about How your project builds interact with CVS



About file types

The information provided in this document about CVS commands and actions assumes that the project files you are working with are text files. It is possible to include binary files in version control with CVS, although there are some special issues.

More about Handling binary files in CVS.



Contributing your changes into CVS

All commits are logged automatically and posted to the project's cvs mailing list.

Adding files/directories

To add a new file to the CVS repository after you have first created and edited it in your working directory, type:

cvs add filename
Then follow up with the "cvs commit filename" command. If you do not first add the file, CVS does not recognize it.

If you have cvs write permissions, you can add subdirectories to your project's source tree using the "cvs add" command. You can then move existing files into new subdirectories with the "cvs move" command.

More about committing changes
More about adding files and directories



Importing existing code?

If you have existing files to add to the project, you can import these into CVS using the following command:

cvs import filename

Importing allows you to add a lot of files at once, something like a super "cvs add." To import all existing directories and files, in your top level directory type:

cvs import -m "log message" projectname

This creates the files and directories in the CVS repository for your project on this site. If you want to preserve these files and directories in their original state, you may want to tag or archive this set of original files before you or any other developers begin checking out working copies of project files.

If your existing files are already under versioning control -- either in another CVS repository or in a versioning different system such as RCS -- there is no automated method for importing existing files that retains file histories. Using the cvs import command, copying files over, or creating them as new files does not retain these histories.



Neither cvs import nor cvs copy preserves the RCS revision histories of existing files brought in to CVS, but there is a way to do this by using:

cvs cp filename,v
If you do not copy files using the "filename,v", all versioning information for each file is lost.

More about "cvs import"



CVS and RCS

If you're already familiar with RCS, both RCS and CVS use a similar format for storing the version control histories of individual files. But you should be aware of at least two critical differences in adapting CVS:

More about RCS and CVS



Keyword substitution

Keyword substitution (a.k.a keyword expansion) is an RCS holdover that may be useful to you as a developer. Keywords essentially let you embed version information permanently in source files. A string containing the full version information associated with a particular keyword is substituted whenever the file is subsequently revised.

As an example, including:

$Author: edk $
within the files permanently retains the login name of the user who checked in that revision.

Keyword substitution is a method for tracking file versions once the files are no longer part of a CVS repository. Keyword substitution can also be configured and suppressed.

More about keywords (including a list of common keywords)



Keeping your working files up to date with the repository

If you want to look before you leap, you can get a list of all files in your local directory not up to date with the project repository by using the following command:

cvs -qn update
Files in the affected directory or directories are listed with their current status indicated as follows:

To go ahead and actually perform an update to make your working directory up to sync with the repository, the command is:

cvs update
You can also update individual files by adding the filename to the command.

Or, to include any new directories when updating, do:

cvs update -d

More about the cvs update command
More about CVS update output



Comparing your working files to the repository

Another way to determine whether all of your working files are in sync with the latest versions in the repository is with the command:

cvstatus
or for status on individual files:
cvs status filename

This comparison may return one of the following messages:

Locally modified
Your version has not yet been committed.
Needs patch
Your version needs to be updated because someone else has made changes.
File had conflicts on merge
CVS could not resolve changes made to this file and committed. (Resolving merge conflicts.)

In general, a good rule of thumb is to make sure your working files are up to date with the repository just before you commit your changes to a file. The reason for this is that sometimes your commit may be unsuccessful, for example, you may be trying to commit from the wrong directory or perhaps another developer has committed changes to that same file after you checked it out of the repository or last updated it. Trying to commit your changes to an older version of the same file often causes conflicts when CVS tries to merge these. The result of your commit attempt under such circumstances is a somewhat daunting failure message about "dying gasps" from CVS. (Unfortunately, you don't find this out until after you've gone through the process of mentally composing and entering a pithy change log message.)

  • To see the differences between your copy of a file and the latest version in the repository:
    cvs diff filename
  • More about comparing your work with the project repository



    Comparing versions of files before you commit (diff)

    Perhaps you want to see the changes another developer has made to the same file before you commit your own changes. For example, suppose you are committing some very complex changes which you anticipate may conflict with another developer's work.

    In this case, a workable solution is to save off your working file under a different name (something like: "filename-new"). Then you can run the "cvs update" command and compare the latest version from the repository with your file before committing your changes. You can even compare the two files side-by-side using the following diff command:

    diff -y filename filename-new



    Merging your changes with other developers' changes

    By giving the "cvs update" command, you are essentially telling CVS to merge the latest versions of files from the repository into your working copies.

    Sometimes, however, other modifications made to a file since you last updated do not mesh well with your version. Or, you've made changes that conflict with the repository version. CVS makes every attempt to resolve such conflicts automatically when you update and commit, but sometimes it cannot resolve everything. Conflicts within the file must be resolved by hand.



  • Resolving merge conflicts

    To resolve merge conflicts, open the file in your file editor. Look for lines or sections marked by ">>>>>>" and "<<<<<<<". When CVS cannot resolve a conflict, it includes both versions of the affect line or sections in the file, usually the latest version first. Your task is to delete the unwanted lines, along with the lines containing the conflict symbols and revision numbers. Then save the file and commit.

    An example of a conflict
    More about resolving conflicts



    Revision history and reverting

    Beyond the usefulness of being able to review a file's modification history using the "cvs log" command to review, earlier versions can actually be restored as the most current revision (that is, to the "repository head") by the process of reverting. This can become a particularly useful option if you want or need to return to an earlier point in a file's evolution for whatever reason, somewhat like being able to turn back the clock.

    The command to revert to an earlier version of a file is:

    cvs up -r filename version_#

    Reverting may results in "sticky tag" errors. You can resolve these using the following update command with a special switch:

    cvs update -dAP
    (What are sticky tag errors?)



    More about revision history
    More about reverting


    Back to main Help index

  • Apache Software Foundation

    Copyright & License | Privacy | Website Feedback | Contact Us | Donate | Thanks

    Apache, the Apache feather logo, and OpenOffice are trademarks of The Apache Software Foundation. OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.