This document describes the CVS environment used for Genghis development. Thanks to rmTrack and Rob McFadyen for donating both the CVS server (with web repository) and the bug tracking software!
The target audience for this document is developers who wish to retrieve the newest version of Genghis from source control, as well as people who are active contributors to the Genghis project. If you have any questions, comments or concerns about this document, please contact Brad Wilson, the document's maintainer.
This document will discuss the ways to use three different CVS clients in conjunction with Genghis. Differences are highlighted where appropriate. If you wish to use a different CVS client, you will need to figure out how to achieve each of these steps on your own.
This document was made using the following CVS clients:
Win32 CVS command line client v1.11
32-bit WinCVS v1.20
TortoiseCVS v0.54
Different versions of these CVS clients may behave and/or look slightly differently.
Part 1. Installing a CVS Client
Part 2. Getting Genghis for the First Time
Part 3. Keeping Genghis Up-to-Date
Part 4. Submitting Genghis Changes
Appendix A. Further Reading
Appendix A. Differences between CVS and SourceSafe
This section contains the steps needs to get a CVS client installed on your box so you can access the CVS repository that holds the Genghis source code. If you already have a CVS client installed on your box, then go ahead and skip to part 2.
The first thing you're going to need to do is get a CVS client. If you like command-line tools, then the standard CVS command line client is for you (but you're going to have to build it from the source code). If you like GUI source control tools, then you'll probably want to try either WinCVS or TortoiseCVS.
CVS command line tool
The CVS command line tool is useful because there are usually options on the command line tool that aren't exposed in the GUIs. It's also valuable for automatic retrieval of files (say for automated building). If you download any of the GUI tools, they will come with a pre-compiled CVS command line tool for your use. We're not going to cover the wealth of command line options here; I'll just give you what you need to get going.
WinCVS
WinCVS is a classic stand-alone "Explorer-style" GUI. It's fairly powerful, but can also be a bit cryptic at times. Most people who use CVS on Windows probably use this tool. I highly, highly recommend you read the WinCVS Daily Use Guide as it covers a lot of great topics for new WinCVS users.
TortoiseCVS
TortoiseCVS is still in beta, but offers what I feel is the most user-friendly GUI on CVS for new users. It integrates into Windows Explorer as a shell extension, so there is no traditional GUI interface to speak of. Most of the CVS functions appear as right click menu options from within Windows Explorer. However, it is quite sparse for features. It should be plenty adequate for normal use, but power users will likely want to gravitate towards WinCVS. Like WinCVS, TortoiseCVS has a Daily Use Guide. To access it, right click on your desktop, choose CVS, then choose Help. The Daily Use Guide is installed with TortoiseCVS. If you don't know what to get, this is what I recommend.
If you're going to be making contributions to Genghis, you'll want to get a diff tool. It's used to see the differences between a file in the CVS repository and the one you'd like to check in. Just about any diff tool will do the job properly; if you have one, you don't need a new one. If you need one, I recommend PrestoSoft's ExamDiff. The free tool (ExamDiff) is great, and they offer a commercial version (ExamDiff Pro) that has some cool features like intra-line diffing and directory diffing.
After your diff tool is installed, you'll need to configure your CVS client to know where to find it.
Cmd Line Users:
The command line CVS tool does not support automatic (seamless) diffing. You'll need
to manually get a clean copy of the file and diff it by hand. If you'll be doing a
lot of contributing, then you'll probably want to use one of the GUI tools for easier
diffing.
WinCVS Users:
Start WinCVS. From the Admin menu, choose Preferences. On the General tab, if the
CVSROOT is empty, type ":" in the box (don't worry, we're going to set
that properly later, but WinCVS is picky about leaving it empty). Change to the
"WinCvs" tab, check the box marked "External diff program",
and browse for your diff program using the ... button.
TortoiseCVS Users:
Right click on your desktop, choose the CVS menu, then
choose Preferences. From the "Main" tab, verify the value for "External
diff application" is pointing to your diff program.
This section contains the steps necessary to retrieve Genghis from the CVS repository for the first time. It also gets you acquainted with the GUI tools, if you're using one. If you've already retrieved the Genghis source code once, then go ahead and skip to part 3.
This section is broken down into three sub-sections, based on which CVS client you're using. Follow the appropriate directions for your CVS client, and then move onto part 3. You can jump to the section quickly by clicking here: CVS command line users, WinCVS users, or TortoiseCVS users.
It will be very helpful if the CVS program is on the PATH. Open a command prompt and type "cvs --version" to ensure that CVS is on the PATH.
Make a folder which will hold the Genghis source, using either Windows Explorer or your command prompt. From within the command prompt, change to the folder that will hold the source. Type the following:
cvs -d :pserver:anonymous@rmtrack.com:/sb login
If you have a user account on the CVS server, substitute your username for "anonymous" in the line above. Anonymous users can retrieve the source code, but you need to have a user account in order to commit changes to the database. More about that later.
You'll be prompted for your password. If you were given a CVS user account, then type your CVS password; anonymous users just press enter (blank password). You should not get any error messages. If you do, double-check the command (especially the username & password) and try again.
Finally, you can retrieve the source code for Genghis by typing:
cvs -z3 -d :pserver:anonymous@rmtrack.com:/sb checkout genghis
A note: The -z3 command line option specifies that you'd like the data mildly compressed when it comes over. You can tweak between not using it (no compression), using -z3 (mild), -z6 (medium), and -z9 (maximum). The trade off is that compression takes server CPU (and thus time); if you're on a slow link, you may want to try higher compression, but on fast links, using -z3 or even no compression may be the quickest.
If all goes well, you'll start seeing the results of the retrieval. They should look like this:
cvs server: Updating genghis
U Genghis.build
U Genghis.build2
U index.htm
Congratulations! You have the Genghis source code. :-) Now go to part 3.
When you start WinCVS, you'll notice that it's a classic Explorer style app. In the left panel you'll see local folders, and in the right panel you'll see files and sub-folders of the currently selected folder. Folders and files will generally label themselves as "NonCvs" if the folder or file is simply local. If the folder or file is associated with a CVS repository, the NonCvs label disappears.
Files have a variety of document icons that indicate the way WinCvs is treating the file. Here's a list of file icons:
Icon | Meaning | ||
![]() |
This is a normal file (i.e., not associated with a CVS repository) | ||
![]() |
This is a file from a CVS repository. It has not been modified. | ||
![]() |
This is a file from a CVS repository. It has been modified. |
Additionally, a pencil icon will appear to the left of these which tells you whether the file is writeable or not.
Folders also have icons that indicate their status:
Icon | Meaning | ||
![]() |
This is a normal folder (i.e., not associated with a CVS repository) | ||
![]() |
This is a folder from a CVS repository. |
Let's get WinCVS set up. Click the Admin menu, and choose Preferences. In the box titled "Enter the CVSROOT" type:
:pserver:anonymous@rmtrack.com:/sb
If you have a user account on the CVS server, substitute your username for "anonymous" in the line above. Anonymous users can retrieve the source code, but you need to have a user account in order to commit changes to the database. More about that later.
Next, change the drop-down labeled "Authentication" to the option that mentions a passwd file on the cvs server. Next, change to the Globals page, and uncheck the box titled "Checkout read-only". Check the box marked "Use TCP/IP compression" and set the compression level to 3. Finally, if you need to use a SOCKS proxy server, you can enter the information on the Proxy page. If you wish, you may change the default text viewer (it defaults to Notepad) on the WinCvs page. Press OK to save your changes.
The quirky WinCVS GUI "roots" the left hand pane to a single directory. By default, it should be rooted to C:\. If you keep all your source in a single directory, the easiest thing is to root WinCVS to that directory. You can change the root of the left hand pane by going to the View menu, then choosing Browse Location, and then choosing Change. For example, I have mine rooted to D:\Source.
1. The first thing you need to do is make a directory that will hold the Genghis source code. You can't do this within the WinCVS GUI; just pop open Windows Explorer and make a folder where you want it. Then navigate to that folder in the left hand pane of WinCVS (you might need to refresh it to get it to show).
2. With the folder selected in the left pane, you then need to login into the CVS server. If you were given a user account, then you'll use your assigned CVS password (anonymous users have a blank password). Click on the Admin menu, choose Login. The first time you do this, it may prompt you for the folder where it can store your passwords locally. At the password prompt, enter your password (or leave it blank for anonymous users), and then press Enter. Watch the status window at the bottom of the WinCVS window, and make sure it eventually says "***** CVS exited normally with code 0 *****". That means you got logged in okay. If CVS exits with a code other than 0, check the status window and see if it's something you can remedy (like an incorrect username or password).
3. Last step: checking out the Genghis module from CVS. Click on the Create menu, and choose "Checkout module". On the Checkout Settings page, enter "genghis" in "Enter the module name and path on the server". Make sure "Local folder to checkout to" is filled with the proper path name. You can explore the other options on this dialog, but we'll leave them at the default values. When you're ready, click OK. The status area should fill with information about the files and folders that are getting pulled down. It will look something like:
cvs -z3 checkout -P genghis (in directory D:\Source\Genghis)
cvs server: Updating genghis
U genghis/Genghis.build
U genghis/Genghis.build2
U genghis/index.htm
Congratulations! You have the Genghis source code. :-) Now go to part 3.
The first thing we'll do is configure some of the TortoiseCVS settings. Right click on your desktop, choose CVS, and then choose Preferences. Click on the Quirky page, and change "Network compression" to 3. Feel free to browse around the rest of the options, and then click OK when you're done.
Open Windows Explorer (in Explorer view) and make a folder to contain the Genghis source code. After the folder has been created, right click on it (in the left pane) and choose "CVS Checkout...". The TortoiseCVS checkout dialog will appear. In the CVSROOT field, type:
:pserver:anonymous@rmtrack.com:/sb
If you have a user account on the CVS server, substitute your username for "anonymous" in the line above. Anonymous users can retrieve the source code, but you need to have a user account in order to commit changes to the database. More about that later.
In the Module entry field, type "genghis". Click the OK button. TortoiseCVS should then successfully retrieve the Genghis source code into the folder of your choice. You will notice if you close and re-open Windows Explorer that any folders or files which are retrieved from a CVS repository should now have green color shaded over their folder or file icons. (If the folder is set for Thumbnail or Tiles view, the green looks pretty ugly... switch to Icons, List or Details view and it looks a lot better.) As you edit files, they will become red-shaded to indicate that they've been modified since your last checkout/update.
Congratulations! You have the Genghis source code. :-) Now go to part 3.
Your source code's smelling funny, like it's old and out of date. Now what do you do? You update it, of course! :)
Here's an important bit of information about using CVS that makes it very easy for you to use source code from multiple databases. Open up Windows Explorer and poke around the folders where you have CVS source code, and you'll notice that they all have a CVS directory in them. Inside this CVS directory there are a few files.
Root
Remember the :pserver:blahblah stuff that you used to get the source code? That's called the "CVS ROOT". The Root file contains this information, so that from now on you won't have to know any of that. Whew! Okay, the one downside is that this contains your user information, so if you move from anonymous access to a user account, I recommend that you delete the entire source tree, and re-get it for the first time (ala part 2) using your user account.
Repository
This marks the subdirectory inside the repository that corresponds to this directory.
Entries
This is the piece that makes CVS so different from SourceSafe: it keeps a list of all the files you've retrieved, and the version you've retrieved. This is what lets you start editing source without having to check anything out: the client side keeps track of what file you're editing instead of the server! This file also contains the list of sub-directories that you've retrieved.
Keeping Genghis up-to-date with the command line client is pretty simple. Open a command prompt and change to the root directory where you're putting the Genghis source code. Then just execute:
cvs -z3 update -P -d
That's it. Any unedited files will be updated. The -P option tells CVS to delete any local empty directories, and the -d option tells CVS to get any new directories that you don't already know about (without this option, it will just keep the directories you know about up-to-date).
The command above is safe even when you're editing, because it won't overwrite any locally changed (edited) files. If you want to overwrite files you're editing, you have a couple choices, depending on your needs. If you have just a couple files that you want to get new version of, just delete them from your local disk, and then re-update (it'll pull clean copies for files that are missing). However, if you want to make sure EVERY SINGLE local file is up-to-date, wiping out any changes you've made, then execute:
cvs -z3 update -C -P -d
There are no prompts for overwriting your source code, so use this checkbox with care!
Keeping Genghis up-to-date with WinCVS is pretty simple. Open WinCVS, and right click on the folder in the left panel that contains the root of the Genghis source code, then choose "Update Selection...". The update dialog box shows up. Check the box that says "Create missing directories that exist in the repository".
There's an additional check box on this page called "Get the clean copy" (don't yell at me about the grammar, I didn't code it). Normally, you will leave this box unchecked. Checking it causes CVS to overwrite ALL locally changed (edited) files with clean copies from the database, thus destroying any changes you might be making. There are no prompts for overwriting your source code, so use this checkbox with care!
Click OK. The source will update itself!
Keeping Genghis up-to-date with TortoiseCVS is pretty simple. Open Windows Explorer and navigate in the left pane to the folder that contains the root of the Genghis source code. Right click on that folder, and click "CVS Update". This will retrieve the newest version of the source code for any files you haven't edited. This is safe to do when you're editing files, because it won't overwrite your work.
If you want to overwrite all the changes you've made with what's in the CVS respository (thus losing all your changes), you need to take an extra step. Right click on the folder again, click "CVS", and then click "Update Special...". This displays the special update dialog box. Check the box named "clean copy", and then click OK. There are no prompts for overwriting your source code, so use this checkbox with care!
A bit of advice: Before you start making changes to Genghis, it's a good idea to make sure you have the most up-to-date verison of the source code (see part 3 for more information). While it's not required, it does help minimize the chance that you'll collide with some changes that've been made since you last updated the source code. If the system can't resolve the changes, then you get to do it by hand. :)
The process for submitting your changes to Genghis is called Committing, and you are required to have a CVS user account to commit changes to the CVS repository. If you don't have a CVS user account but would like to have changes submitted, you can e-mail Chris Sells for more information.
Generally speaking, there are two ways you'll be committing. First is you'll commit individual files, and the second is you'll commit an entire folder (and usually the subfolders). To commit all your changes, you'll commit the root folder where you keep Genghis, and all the sub-folders.
Committing files. Open a command prompt and change to the directory that contains the files you wish to commit. If you wish to commit files from multiple directories, you can either do it in multiple commits, or add relative/absolute directory names to the filename that are in different folders. The command is:
cvs -z3 commit file1 [file2 [file3 ...]]
This will commit the specific files. You'll be prompted for a log message (by way of Notepad).
Committing folders. If you want to commit an entire folder of files, CVS will find all the modified files and get ready for committing. In your comment prompt, change to the root folder you want to commit, and choose one of these two commands:
cvs -z3 commit (commits this folder and all subfolders)
cvs -z3 commit -l (commits this folder only)
Like when commiting files, you'll be prompted for a log message for this commit (by way of Notepad).
Committing files and folder is simple with WinCVS. Simply navigate to the files you wish to commit (multi-select while holding ALT), and then right click, find the Commit menu option, and choose it. Similarly for folders, find the folder you wish to commit, right click on it, and choose the Commit menu option.
Committing files and folder is simple with Tortoise. Open Windows Explorer and navigate to the files you wish to commit (multi-select while holding ALT), right click on the selection, choose the CVS Commit menu option. Similarly for folders, find the folder you wish to commit, right click on it, and choose the CVS Commit menu option.
Obviously, this only covered the basics of getting and committing files. It doesn't cover branching, merging, labeling, sticky bits, or any of the typical administrative functions. For further reading, you might try O'Reilly's CVS Pocket Reference, the CVS Web Site, or Google.
If you're a Visual SourceSafe user, then CVS is going to seem quite a bit different than what you're used to. Don't worry, that feeling of panic is normal. :-)
The first thing you're going to notice about CVS is that the GUI tools act quite differently from Visual SourceSafe. With VSS, you open a GUI which shows you all the available projects in a VSS database. With CVS, you generally are using a GUI that shows your local file structure, with indications of which folders and files correspond to files in the CVS repository.
One of the bigger hurdles in terminology. The following table illustrates typical actions in both source control systems.
Activity | SourceSafe | CVS | |||
Get files from a project, first time | Get (or Get Latest) | Check Out | |||
Ensure your local files are up-to-date | Get (or Get Latest) | Update | |||
Begin editing a file | Check-Out | (None) | |||
Submit changes | Check-In | Commit |
Visual SourceSafe uses an affirmative check-out system. Before you start editing a file, VSS requires you to check it out so that it knows which version you started editing with. If you don't do this, you can destroy the changes of others. Believe me, I've seen some people using tools (like Homesite) that just allowed people to turn off the read-only bits, and we had things disappearing form SourceSafe left and right! The users were doing "edit for a week, then check-out and immediately check-in" and they just didn't understand why SourceSafe was trashing the changes others had made.
CVS, on the other hand, always knows all the versions of all the files you have locally, and as such, a check-out-before-editing step is not required. Although CVS can be configured to require such a step, the common practice is to let the user start editing without a check-out. The Genghis repository follows common CVS practice, and does not require you to check-out files before editing.
CVS, like VSS, will attempt to resolve merge conflicts; and like VSS, it will require human intervention if the conflict cannot be resolved automatically. It makes good sense to make sure you have the latest local version if possible before you start editing, so that the chances of merge conflicts are minimized (but unlike VSS, this is not a required step).
Branching in CVS works significantly different than from VSS. In VSS, when you branch off a piece of a project, you must create a new project area to contain the branch.
In CVS, you create branches in place, and CVS uses a versioning system to keep track of branches. When you check-out or update, you can get files based on a particular branch. This requires a little more understanding of how branching works than VSS, since you can't necessarily see that something is branched. If you are not working on a branch, you are said to be working on the main trunk. It's a tree metaphor, you see. :-)
There is no analogue to VSS's "sharing" system in CVS. If you wish to share code, you're best off making shared libraries since you can't rely on the source control system to share copies of files between projects.