Essential CVS/Appendixes/Clients and Operating Systems
From Programmer 97-things
While some people like using the command line during development, others prefer graphical interfaces. Graphical user interfaces (GUIs) also use colors and shapes to make output clearer or make the sandbox easier to work with.
Graphical CVS interfaces are available for Windows, Macintosh, and Unix or Linux systems, and there are also two Java graphical interfaces that run on any operating system with a Java Runtime Environment. These GUIs were written by third-party developers and do not come with CVS.
Third-party developers have also written tools to interface between CVS and several of the common integrated development environments (IDEs). These interfaces are most useful to programmers and are available for Microsoft Developer Studio, MetroWerks CodeWarrior, NetBeans, GNU Emacs, and anything that uses the SCC-API (Common Source Code Control Application Programming Interface). IDEs that support the SCC-API include Macromedia ColdFusion, Sybase PowerBuilder, and Microsoft Visual Studio.
CVS is designed for the Unix and Linux operating systems, and it relies on the features of those operating systems. It can behave in unexpected ways when used from a different operating system. The most obvious problem is that Windows operating systems use a different character for line endings than Unix-based systems do. CVS corrects for that particular problem, but other problems are explained in this appendix.
If your development team is not familiar with CVS, you may want to ensure that everyone is using the same CVS client. This helps minimize support problems; if someone has a problem, his fellow developers are familiar with the tools he's using and can offer helpful advice.
The clients described in this section look and operate the same across several different environments. The first three represent a set of clients that are designed for all three major operating systems—Unix/Linux, Macintosh, and Windows—and work from the same base code. The other two GUI clients are Java clients that work on any operating system twith a Java Runtime Environment.
gCVS, WinCVS, and MacCVS
Three GUI clients—gCVS, MacCVS, and WinCVS—represent a set of clients available from the same development team that work identically across Unix/Linux, Macintosh, and Windows operating systems. The clients are detailed and implement most of the functions available from the CVS command line. Using these clients, you can create a new repository, tag files, create watches, and report on the differences between files. These clients are available from http://www.wincvs.org and http://cvsgui.sourceforge.net/.
gCVS is for Linux and Unix, WinCVS is for Windows, and MacCVS is for Macintosh. Because their interfaces are so similar, these are good clients for groups that develop software across different operating systems.
These clients are laid out with three main windows, as shown in Figure A-1 (gCVS) and Figure A-2 (WinCVS). The leftmost window contains a directory tree, the base directory of which is configurable. The upper-right window shows the contents of the current directory, and the lower-right window shows the output of the CVS commands that you execute using the GUI.
Using these GUI clients, you execute CVS commands by choosing a menu option and then filling out some fields in a dialog. The output of most commands is displayed in the lower-right window. This can be irritating if the output from a given command is particularly large or complex to read. Fortunately, you can resize the output window to accomodate large and complex output. If you need to use options that are not available in the menus and dialogs, you can run command-line commands in these clients using the Command Line option in the Admin menu.
Figure A-3 shows the Cvs Files menu in MacCVS, with the output window in the background.
In Chapter 2, I recommended gCVS, WinCVS, and MacCVS as CVS clients for a development team because they are popular and have a common interface. Installation is similar for all CVS clients on the same operating system, so I've chosen these three to give an example for each operating system.
gCVS is a Linux and Unix client available from http://www.wincvs.org/ and http://cvsgui.sourceforge.net/. You can install it from source, or you can use a package manager. To use a package manager, follow the procedures givin in Chapter 2.
To install CVS from source, read the detailed instructions in Chapter 2. The procedure for installing gCVS is similar to the procedure for installing CVS, though some of the commands differ slightly.
- Decompress and expand the.tar.gz file using tar - zxf filename.
- Read the INSTALL file in the top directory of the source tree. If the instructions in the INSTALL file differ from the instructions here, use the instructions in the INSTALL file.
- Check whether the gtk development libraries are available. gCVS needs to link to these libraries when it compiles. They are available from http://www.gtk.org/.
- Change directories into the top directory of the source tree.
- Run ./make-configure --prefix=directory, where directory is the location you want to install gCVS.
- Run make.
- Change user to root,then run make install.
- Add the installation directory to the path for your gCVS users.
- Run gCVS with the gcvscommand.
Whether you install gCVS as a package or from source, you may also need to install or configure SSH or Kerberos. If you intend to use SSH and have not used it before, you need to generate keys. If you are currently using SSH, you should already have keys. As an SSH client is often installed by default in Unix and Linux systems, you may only need to configure it.
WinCVS requires Python. If you intend to connect with SSH, it requires you to install SSH as well. These instructions assume that you will run WinCVS with SSH. Older versions of WinCVS used Cygwin instead of Python.
- Install Python 2.1 or later from http://www.python.org/.
- Install an SSH client such as Putty. Putty is available at http://www.chiark.greenend.org.uk/~sgtatham/putty/.
- Use the key-generation program for your SSH client. Store both private and public keys in files. If the key generator gives you a public key to cut and paste, use Notepad or another text editor to store the key in a file. Generate an ssh1 or ssh2 key, depending on your server's SSH protocol.
- Put a copy of the public key on the server, in your ~/.ssh/authorizedkeys file or whichever file your server's SSH program expects public keys to be in.
- If your SSH client runs a key agent, use it. Putty runs Pageant, which has an icon in the system tray. Add your private key to the key agent; to do this in Pageant, right-click on the icon and select View Keys, then Add Key.
- Download WinCVS from http://www.wincvs.org/.
- Extract WinCVS using the extractor provided; it's distributed in a self-extracting archive.
- Run setup.exe.
- Run WinCVS.
- Set ssh as the connection method. Use the following procedure:
- Select Preferences from the Admin menu.
- Open the General tab. Set the authentication option to ssh.
- Open the Settings button, and fill in the path to your SSH client. For Putty, the executable is plink.exe. Also set any options necessary for your SSH client. If you are using Putty, set the -ssh option.
MacCVS is distributed as an archive and needs to be opened with StuffIt, which is available for both OS X and pre-OS X systems. Most Macintosh systems have StuffIt installed; if yours doesn't, you can get Stuffit Expander (the free version) from http://www.stuffit.com/downloads.html. Once you've downloaded the compressed archive, just double-click it to open and install the program. That's it! You're done with the installation. To run MacCVS, open the MacCVS icon from the directory in which you installed it.
MacCVS and clients written for Macintosh systems older than OS X do not support SSH through the usual access method, where the repository path is :ext:hostname:/path and the CVS_RSH environment variable is used. To work around this, install an SSH client that supports port tunneling and use an SSH tunnel to connect to the CVS repository securely. Choose an alternate access method such as pserver or kserver and configure MacCVS to connect to the localhost on the port at the local end of the tunnel.
If you have OS X and want SSH support, try using an OS X-specific client, or use a Unix or Linux client. At the time of this writing, the MacCVS OS X client is in beta testing and has built-in SSH support.
jCVS is a Java-based CVS client (available from http://www.jcvs.org/) that is useful for development teams that need to work over a variety of operating systems. The tabs in the main window (shown in Figure A-4) control project administration, and the menus in the project window control the commands for the files.
The project window displays the files' hierarchy and the status of each file currently in the sandbox. Output from log, diff, and other commands is shown in a separate window.
SmartCVS is a Java-based client that runs on any operating system with a Java Runtime Environment. SmartCVS is available from http://www.smartcvs.com/.
There are two versions of SmartCVS: a free version and a professional version. Both implement the basic CVS commands and a few extra features, such as automatic detection of binary files. The professional version supports the annotate command and has more extensive support for tags than the basic version.
The main window has three parts: the folder hierarchy to the left, the files in the current sandbox in the right window, and CVS command output in the bottom window. SmartCVS provides side-by-side, color-coded displays of the differences between revisions, and a log display that includes graphical representation of branches.
Figure A-5 shows the SmartCVS main window in the background and the graphical log display in the foreground. The log display shows a branched file.
There are three clients available specifically for the Macintosh operating system: MacCVS (described earlier in Section A.1), MacCVSClient, and MacCVS Pro.
If you are running Mac OS 9 or earlier, you need to be aware of two issues:
- The Macintosh CVS clients for OS 9 and earlier don't have built-in SSH support. You can use SSH by following the tunnel workaround in Section A.1.1.3.
- CVS clients in Mac OS 9 and earlier may have line-ending issues, as described in Section A.4.
OS X does not have either of these problems, as it has a built-in SSH client and both OS X and CVS use Unix-style line endings.
If you are running OS X, in addition to using the Macintosh-specific clients mentioned in this chapter, you can use the CVS command-line client, as well as the Unix and Linux graphical clients.
The Concurrent Versions Librarian (CVL) client is designed specifically for Mac OS X. It is available from http://sente.epfl.ch/software/cvl/.
MacCVSClient is available for OS X and earlier versions from http://www.heilancoo.net/MacCVSClient/.
The main display of MacCVSClient is a modules window, which provides a hierarchical list of files that includes status information. Output from commands such as diff or log is stored and can be retrieved from this window later in the session, as well as immediately after you run a command. If you switch to another application, then return, MacCVSClient attempts to refresh the cached states and modification times of any open folders.
MacCVSClient supports the pserver and ext (rsh-only) repository-access methods. You can configure the repository path in the Preferences dialog from the Edit menu, shown in Figure A-6. Conflicts and the results of the diff command are color-coded to improve readability.
MacCVS Pro is a graphical client for the Macintosh, available from http://www.maccvs.org/. It has versions for OS X, OS 9, and earlier.
MacCVS Pro supports the Kerberos, pserver, and ext (rsh-only) access methods. The main display is a session window, which contains a hierarchical list of available folders and files. Files are shown with status information. Output from commands such as log and diff is displayed in a separate window. diff output is color-coded.
MacCVS Pro is fully multithreaded, enabling you to run several commands simultaneously. Commands that take time, such as update and commit, have a progress bar. A find lurkers command is a useful tool for locating files that have been left uncommitted.
Figure A-7 shows the MacCVS Pro Preferences dialog in the foreground and the main display window in the background.
Unix and Linux Clients
CVS is native to the Unix and Linux operating systems; consequently, there are no line-ending or capitalization issues. The standard, command-line client is intended for use with Unix and Linux, but there is also a wide variety of graphical CVS clients available for Unix and Linux systems.
Cervisia is available from http://cervisia.sourceforge.net/. It requires the QT and KDE libraries, but it runs on Gnome and other graphical environments if the QT and KDE libraries are available.
Cervisia provides a configurable list of frequently used CVS repositories, and configurable key bindings for common commands. Cervisia supports the commit, import, and updatecommands, as well as the tagging and watching sets of commands. One particularly useful setting is the option to run cvs edit automatically, to notify other developers when you intend to edit a file.
Cervisia has two main sections in its display screen, shown in Figure A-8. The upper section lists files and directories, and the lower section displays the output of the CVS commands that Cervisia executes for you. Right-click on a file in the upper section to open a menu with options to open the file in an editor, commit a changed file, add a file, remove a file, or run a diff over two revisions of a file.
The Resolve menu option, which you can access by right-clicking the mouse, supports automatic conflict resolution. When you invoke automatic conflict resolution, Cervisia displays both files, as well as the merged version of the two files. Cervisia then allows you to choose from several methods for handling any conflicts as a result of the merge.
LinCVS is available from http://www.lincvs.org/. It requires the QT toolkit, but it runs in most graphic environments.
The LinCVS web site displays in German by default, but it provides an English translation if you click on the British flag.
LinCVS is also available for Windows.
Start using LinCVS by selecting the "Add to workbench" option under the Projects menu and choosing a top-level directory above at least one of your sandboxes. LinCVS searches the directory and determines which files are controlled by CVS. It then adds those files to the workbench, which is a directory tree in the left window. The workbench is updated automatically on a periodic basis with a configurable timeout. You can add multiple directories to your workbench.
Figure A-9 shows the LinCVS display. The upper-right window contains the files in the active directory; double-clicking on a file opens it in an editor. The lower-right window displays CVS command output, though output for some of the commands is also displayed in a dialog.
Pharmacy is available from http://pharmacy.sourceforge.net/. It requires the Gnome libraries, but runs in almost any graphic environment.
The upper-left window is a directory tree that supports multiple repositories. The upper-right window displays files. The lower window is a console that also provides other tools. The console is a full command-line system, and it also displays command output. Figure A-10 shows the Pharmacy windows.
tkCVS is available from http://tkcvs.sourceforge.net/. It requires the Tcl/Tk libraries and works in most graphic environments.
tkCVS provides most CVS commands. It opens in your home directory and displays files and directories in the main window, with the last modification date to the right if a file or directory is not part of a sandbox. When the current working directory is a sandbox, the date, status, revision, and editors are displayed to the right of the filenames. Sandbox directories have a red "CVS" label on their folders.
Double-clicking on a filename opens an editor, as does selecting the file and clicking the Edit button. Double-clicking on a directory moves you into that directory. Double-clicking the ".."directory takes you back to the parent directory.
Commands are available from buttons at the bottom of the window or menus in the menu bar at the top. Some commands display a dialog and have further options within the dialog. The menus can be torn off and placed in convenient areas of your desktop. The results of a diff command are displayed side-by-side in a dialog window. diff, annotate, and log dialogs are searchable, and the color-coded annotation screen is helpful. Figure A-11 shows the tkCVS main windows.
There are two graphical CVS clients available specifically for Windows. One is WinCVS, which is described in Section A.1 of this chapter. The other is TortoiseCVS, which modifies the way Windows Explorer presents files.
Following are some issues you might encounter when using CVS from Windows. These issues apply equally to WinCVS and TortoiseCVS.
- Line endings differ between Windows and Unix
- CVS automatically attempts to convert the line endings of text files to Unix format. This is helpful in text files, but it causes problems in binary files that are committed accidentally as text files. When a binary file is corrupted because CVS tried to "fix" the line endings, often you can recover with the following procedure:
- Back up the current sandbox copy of the file.
- Update the file with cvs update to bring the repository version into the sandbox and reconvert the line endings.
- Check the file to ensure that it is no longer corrupt. If it is still corrupt, roll back to the most recent uncorrupted version (hopefully, the backup).
- Use cvs admin -kb filename to convert the default keyword-expansion mode of the file to binary.
- Recommit the file to the repository with cvs commit -f.
- SSH may attempt to convert line endings
- Because CVS performs its own line-ending conversion, you cannot use an SSH client that converts line endings as the client for CVS.
- Filename capitalization matters under Unix
- In Unix operating systems, file capitalization matters. NoSuchFile and nosuchfile are completely different files. If your repository contains two files whose names differ only in case and you are running an operating system that ignores case, the second file to download may overwrite the first when you check out or update a sandbox.
- Directory separators are different under Unix and Windows
- CVS uses the forward-slash character (/) as the directory separator. In most cases, internal CVS files use a forward slash wherever Windows uses the backslash character(\). This should not cause problems, but it may cause confusion.
- Universal time
- CVS stores times in UTC (Coordinated Universal Time). This may also cause confusion, but it should not cause any problems if the time on the client is configured correctly.
- File permissions problems
- If you are running the repository on a networked filesystem accessed through a Samba server, you may have permissions problems if you are using CVS from a Windows system with the local access method. These problems can usually be fixed by enabling WRITE=YES in the Samba configuration.
TortoiseCVS is a simple CVS client for Windows that allows you to manage CVS files from within Windows Explorer (not Internet Explorer). The standard right-click menu for files is expanded to include the CVS commands that apply to a given file. TortoiseCVS is available from http://www.tortoisecvs.org/.
For files, the menu is changed only in an active sandbox. The right-click menu for folders that are not sandboxes is changed to include a Checkout option and a CVS submenu. You can import a new project with the Make New Module option in the submenu.
TortoiseCVS also works within the standard Windows File → Open dialog.
Figure A-12 shows the menu items that TortoiseCVS adds when you right-click on a folder representing a sandbox directory, in this case the man folder.
Developers rarely use CVS in isolation. The tools described in this section coordinate CVS with other programs. Some integrate CVS into IDEs; others are used in separate windows but ensure CVS can manage an IDE's files properly.
abCVS is a plugin for CodeWarrior that allows you to use CVS without leaving the CodeWarrior IDE. It requires CodeWarrior and a command-line CVS implementation such as CVSNT (explained in Appendix B). The developers of abCVS also recommend that you have a CVS client such as WinCVS.
abCVS implements the update, commit, add, remove, edit, log, status, and diff commands. Most commands can run on a single file, or they can run recursively down a directory tree. abCVS is still in an early stage of development.
abCVS is available from http://www.iaanus.com/abCVS/.
Anjuta is an IDE for the Linux and Unix operating systems that relies on the Gnome libraries. It supports more than a dozen languages (including C/C++, Java, Python, Perl, and ADA) and provides an integrated debugging facility, syntax highlighting, context-sensitive help, and support for autoconf and automake.
Anjuta provides simple, clean access to CVS commands on files in CVS sandboxes, including an intuitive interface to cvs diff. Anjuta is available from http://anjuta.org/.
BBEdit is an HTML and text editor for the Macintosh. Version 7 for OS X includes an integrated CVS client that supports multiple repositories. BBEdit is available from http://www.barebones.com/products/bbedit.html.
CVSIn is an add-in for Microsoft Developer Studio that integrates Microsoft Developer Studio and WinCVS. It permits most simple CVS commands to operate directly from Microsoft Developer Studio and relies on WinCVS for more complex CVS commands and commands that operate on directories rather than individual files.
Once CVSIn is installed, new toolbar options are available in Microsoft Developer Studio. Most of these options operate on the selected file: update, commit, diff, log, status, edit, watch, tag, and branch. There is also an option to launch WinCVS. Output from commands is displayed in a screen at the bottom of the window.
CVSIn is available from http://www.geocities.com/kaczoroj/CvsIn/.
CWCVS is a plugin for CodeWarrior that allows you to use MacCVS without leaving the CodeWarrior IDE. It is available for the Macintosh and requires CodeWarrior Gold 11 or later, MacCVS, and a CVS repository.
CWCVS is implemented in CodeWarrior as an additional menu and provides most of the CVS functions, though you need to use MacCVS for checkout and some of the administrative or advanced functions. CWCVS provides dialogs for the commands that take parameters, and it displays command output in separate windows.
CWCVS is available from http://www.electricfish.com/products/CWCVS/.
Eclipse is an open source development environment that runs on Windows, Linux, and Unix systems and is designed to support Java developers. It is extensible, and the developers encourage plugin support for other systems and languages. A CVS client is built in, and can be found in the Window and Projects menus.
Eclipse is available from http://dev.eclipse.org/.
Jalindi Igloo works with any SCC-API-compliant environment and is being tested with the programs listed at http://www.jalindi.com/igloo/Compatibility/compatibility.html. Examples of SCC-API-compliant environments include: Microsoft Visual Studio, Macromedia ColdFusion, and IBM VisualAge for Java.
Igloo provides the usual set of CVS commands and an optional auto-commit mode that automatically commits added or deleted files to the repository and automatically updates files when they are edited in the IDE.
Jalindi Igloo is available from http://www.jalindi.com/igloo/.
NetBeans is an IDE that includes a built-in CVS client, as well as clients for other version control systems. CVS integration is implemented as a module, and there are two modules available. In both modules, the CVS sandbox is represented within the IDE as a filesystem and the CVS commands are available through a right-click menu. NetBeans also provides a command line to use for more complex CVS tasks.
The NetBeans system (platform and IDE) is open source. NetBeans is available from http://www.netbeans.org/.
PCL-CVS integrates CVS with Emacs. It relies on VC, the Emacs version control interface, to allow you to use the basic CVS commands within Emacs. PCL-CVS expands VC to allow CVS to work with directories as well as individual files. It also provides an overall view of the project.
PCL-CVS is available via http://www.cvshome.org/dev/addonpclcvs.html.
VC is the Emacs version control interface, and it provides a consistent user interface regardless of which version control system is actually recording changes. VC provides only the basic functions of CVS. To use advanced CVS functions with Emacs you need to use PCL-CVS, or you can combine use of VC with use of the command- line CVS client.
VC is part of the Emacs editor. The relevant part of the Emacs manual is at http://www.gnu.org/manual/emacs/html_node/emacs_127.html#SEC127. You need to configure VC to use CVS; the instructions for doing so are in the "Customizing VC" section of the Emacs manual.
Vim is a popular editor for Unix and Linux. The graphical version of Vim offers a script that adds a CVS menu. The script is available at http://www.vim.org/script.php?script_id=58.
Zeus SCC-CVS uses the SCC-API to connect the Zeus development environment to CVS. It should also work with any editor or development environment that uses the SCC-API.
With Zeus SCC-CVS, all CVS commands are accessed under the Workspace menu, but only a limited number of commands are available within the editor. By default, Zeus SCC-CVS automatically updates the sandbox, retrieving the most current revision from the repository when Zeus is opened.
Zeus SCC-CVS is available at http://www.zeusedit.com/archives/scccvs.html.