Or: How to finally enjoy version control
Adapted from the excellent WinCVS Daily Use Guide by Sverre Huseby.
CVS has a different way of working from other version control systems. Developers can edit the same files concurrently. First you checkout a version of the source from the repository. Then you simply edit the files that you want to change, and make new files or delete them. When you're done you commit the files to the repository.
If someone else has changed the same file while you were working on it, then the commit will fail. You then update all your source code files from the repository. This will automatically merge the other developers changes into your copy of the file.
Sometimes it can't do this automatically, for example if you both changed the same line of code. This is called a conflict. Conflicts happen much less often than you might expect. CVS puts both versions of the conflicting code in the file, with markings separating them. Then you manually edit the file to resolve the conflict.
Now you can commit again, and this time it will work.
This method of working has lots of advantages. Each developer lives in a sandbox. Changes that another developer makes are isolated from you until you want to check in your changes. It stops bottlenecks where people can't do things because someone else has the file checked out. Any developer can work on files without direct access to the server, they only need to connect to update or commit.
To obtain a module from the CVS server for the first time, is known as a checkout. Checking a module out from the repository gives you a local copy of the directory hierarchy that makes up the module.
If you've already checked out your module using WinCVS or another CVS client you can skip this section and just start working on it.
To perform a checkout, Right click on the directory where you'd like the module placed, and pick "CVS Checkout..." from the pop-up menu. The checkout dialog should appear with the following fields:
You'll need to know this information in advance. Most projects should have some documentation (often online) on how to connect and checkout their modules. Failing that, you'll just have to find someone in the know :-).
A directory named after the module will be created in the directory you checkout to, so you can keep all your checked out modules in the same directory if you'd like, even if they are for different projects.
[ CVS Doc: "checkout -- Check out sources for editing" ]
You will see some files and folders now have an icon overlay.
Occasionally you may want changes done by others to get incorporated in your local working copy. The process of getting changes from the server to your local copy is known as updating. Updating may be done on single files, a set of selected files, or recursively on entire directory hierarchies. To update, highlight the files and/or directories you want, right click and select "CVS Update". A window will pop up displaying the progress of the update as it runs.
Changes done by others will be merged into your files, keeping any changes you may have done to the same files. The repository is not affected by an updating.
If you receive reports of conflicts during the update, please read the "resolving conflicts" section.
The update output section in the CVS manual describes the cryptic codes which appear at the start of each progress line.
[ CVS Doc:
"Bringing a file up to date" ]
[ CVS Doc:
"update -- Bring work tree in sync with repository" ]
Making local modifications available in the repository is known as committing the changes.
Please note that committing changes will not automatically add new files that you have created to the repository. See Adding Files and Directories for a description of doing that.
[ CVS Doc: "commit -- Check files into the repository" ]
Once in a while, the CVS server will report a conflict when you update your files from the repository. A conflict occurs when two or more developers have changed the same few lines of a file. As CVS knows nothing of your project, it leaves resolving the conflicts to the developers. Whenever a conflict is reported, you should open the file in question, and search for lines starting with the string <<<<<<<. The conflicting area is marked like this:
<<<<<<< filename
your changes
=======
code merged from repository
>>>>>>> revision
You should decide what the code should look like, do the necessary changes, remove the CVS markup, and commit your modifications to the repository.
[ CVS Doc: "Conflicts example" ]
If you've made new files or directories you will notice that its icon appears with a question mark on it. To put such files or directorys under CVS control:
After an add operation on a file, the file icon appears as "changed". This is because additions are treated as local changes and are not applied to the repository until you commit them.
For directories, an extra menu item,
, is available. This operation descends down the directory structure, performing an addition on everything, including subdirectories. Be careful with this, as you don't want to accidentally add superfluous crap into your repository (for example, intermediate compiler files like .o or .obj).You don't need to worry about whether a file is binary or not, TortoiseCVS automatically detects this. See the FAQ entry for more information.
[ CVS Doc: "Adding, removing, and renaming files and directories" ]
To see the changes that have been made to a file, select the
menuitem.The ViewCVS or CVSWeb to view the history of a file. These programs let you browse the CVS repository, download old versions and display differences between them. I highly recommend that you persuade your server administrator to install ViewCVS - it supports the useful Annotate feature which tells you who last changed each line of code.
option launches your browser into
[ CVS Doc:
"diff -- Show differences between revisions" ]
[ CVS Doc:
"log -- Print out log information for files" ]
To remove files, you first schedule the files for removal, and then commit the change:
The files will now be removed from the repository and from your working set.
Directories are automatically removed when all their contents have been removed.
[ CVS Doc: "Adding, removing, and renaming files and directories" ]
Operation of moving or renaming files or directories is not available in CVS. This is one of CVS's shortcomings. To simulate moving or renaming, you have to combine remove and add operations. See Adding Files and Directories and Removing Files and Directories.
[ CVS Doc: "Moving and renaming files" ]
The easiest way to cancel the changes that you have made to a file is to delete the file on your hard disk. Then choose update on the directory, and you will get the latest version back again.
At a given stage of development, giving one or more files a common label to refers to their revisions, is known as tagging those files. Tagging is typically used on entire modules, so that the current state of the module can be reconstructed in the future. This kind of tagging should always be done on project deliverables, and before starting major changes.
To tag one or more files or directories with a label, do the following:
Note that the tag is immediately applied to the repository - no commit is required.
CVS is quite restrictive when it comes to what characters a tag may contain: A tag must start with a letter, and may contain letters, digits, "-" (dash) and "_" (underscore) only. In particular, this means no dots, and no spaces. If you want to include version numbers in a tag, replace the dots with dashes. Two tag names are reserved, as they have special meaning in CVS: "HEAD" refers to the most recent version available in the repository, while "BASE" is the revision you last checked out into the local directory.
[ CVS Doc: "Tags -- Symbolic revisions" ]
To create a new CVS module:
CVS lacks good support for restructuring a project file hierarchy, so you save yourself a lot of trouble if you spend some time planning the module layout in advance.
Be aware that CVS treats empty directories as non-existent. If you want to add a directory in which you have neither files nor subdirectories, you will have to create a dummy file in it. We suggest that you create a file named README.txt, which contains a short description of what this directory is for.
TortoiseCVS creates modules 'in-place'. This is different to the import method used by other CVS clients. Behind the scenes, TortoiseCVS does an import followed by a checkout.
[ CVS Doc: "Starting a project with CVS" ]
One of the features of version control systems, is the ability to isolate changes onto a separate line of development. This line is known as a branch. (See What branches are good for in the CVS documentation.)
To create a branch, do the following:
Now a new branch with the given name is created in the repository. Note: The branch is created in the repository only. To start working on the newly created branch, you have to do what is described in Selecting a Branch to Work on.
[ CVS Doc: "Branching and merging" ]
To start working on a branch instead of the default development line, you have to bind your local copy to the branch. This is needed to make sure that actions such as updates, commits etc. work on the branch rather than on the main line of development.
To move your local copy to another branch, do the following:
TortoiseCVS will now do the necessary updates to your working copy and move it to the desired branch. The updating may include adding or removing files.
CVS puts what is known as sticky tags on the files that are affected by the branch. To remove the sticky tags and thus go back to the main development line, follow the description in Going Back to the Main Line of Development.
[ CVS Doc: "Accessing branches" ]
When you are satisfied with the changes you have done on a branch, you may want those changes to be available on the main line of development. Incorporating changes from one branch to another, is known as merging. To merge from a branch, do the following:
Any changes on the branch will now be merged into your local copy. You will probably also want to commit the merged files back to the repository, as described in Sending Your Changes to CVS.
Important note: The merge given above will try to merge changes from the start of the branch. If you do the operation a second time (to merge changes done to the branch after the last merge), merging from the start of the branch is not what you want, and it will most likely get you into trouble. To get around this problem, you should give the branch a new tag after every merge, and use the new tag when naming the branch for subsequent merges.
[ CVS Doc: "Merging an entire branch" ]
If you want to stop working on a branch and move your local copy back to the main line of development, you have to make TortoiseCVS remove all sticky tags. To remove the sticky tags, and thus update your local copy to the main development line, do the following:
TortoiseCVS will now update your local copy so it matches the current main line of development. The branch you were on still exists in the repository, and you may return to it as described in Selecting a Branch to Work on whenever you want to.
The terminology used in the CVS documentation, and thus also in TortoiseCVS, may differ from terminology used in other source repository systems. In an attempt to avoid confusion, we provide a short list of the most essential terms.
For the entire story of "revisions", "releases", "versions" and "tags", see chapter 4 of the CVS documentation.
CVS and WinCvs differ from Visual Source Safe (VSS) in many ways. The most apparent difference may be that CVS does not require users to lock the files they are working on, as VSS does by default. In fact, the CVS documentation even encourages users not to use file locking. In the rare occation where several people have changed the same file at the same time, CVS will normally be able to merge their changes. If two or more developers have changed the same few lines, CVS will report a conflict, insert directives in the file, and leave it to the developers to decide what to do. Such conflicts are very rare, as they normally occur as a result of lacking communication between the developers (eg. two people trying to fix the same problem).
Another important difference is that VSS gives you a server view, while TortoiseCVS shows a client view. In practice this means that, unlike VSS, TortoiseCVS will not tell you about changes in the repository until you do an update, or explicitely query the status of selected files. Changes reported by TortoiseCVS reflect modifications done by you after the last checkout, update or commit.