pts' CVS over SSH tutorial for Win32 systems ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ by Péter Szabó at Mon Jul 4 11:11:49 CEST 2005 This tutorial will help you installing and using WinCVS for sharing and concurrent editing of your development project source files on Win32 systems. This tutorial is for beginners (i.e. who have never heared of CVS before, but have Win32 experience as a programmer or at least a power user), and it is not exhaustive. The latest plain text version of this tutorial can be downloaded from: http://www.inf.bme.hu/~pts/pts-win32-cvs-over-ssh-tutorial.txt If you need a deep understanding of CVS, and/or you want to host a repository on a UNIX system, you should read the CVS Book: http://cvsbook.red-bean.com/cvsbook.html This tutorial is not intended for Linux or other UNIX users. They should get the CVS package (the binary is usually /usr/bin/cvs), and an SSH server installed. E.g. on Debian systems, run `apt-get install ssh cvs'. After that, they should read the CVS Book or run `info cvs' to read the CVS documentation in info format. What is CVS? ~~~~~~~~~~~~ (Some text of this answer is taken from `info cvs'.) CVS (Concurrent Versions System) is a version control system. Using it, you can record the history of your source files. With CVS, you can easily retrieve old versions (e.g. by date and time). This can sometimes be a big help. CVS also helps you if you are part of a group of people working on the same project. Without a version control system, it is all too easy to overwrite each others' changes unless you are extremely careful. Some other free version control systems: Subversion (SVN) and darcs. They are not discussed in this tutorial. Overview of CVS concepts ~~~~~~~~~~~~~~~~~~~~~~~~ From now on we assume that you are working on a development project (e.g. software development or book authoring with LaTeX), either alone or with some co-developers. The files being developed are mostly text files (but there might be some binary files, too), organized into a directory tree. We also assume that all developers trust each other, and the general policy is to share new files and file changes with the other developers as soon as possible. Of course, it is a bad idea to share a source code modification which fails to compile or it doesn't work, so you want to explicitly invoke each sharing after your changes are mature enough. CVS stores all information about the shared files (including the newest version and all earlier versions) on a central location, named the ``repository''. The repository is a directory structure on a server to which all developers has access to. In this tutorial we assume that the repository is hosted on a UNIX server with direct SSH access. (Another popular, but less secure possibility is using ``cvs pserver''.) However, the files in the repository should not be directly copied, because they contain meta-information (differences from older versions, file change history etc.). You should access the repository using CVS client software. On UNIX, the ``cvs'' command on the command-line is the standard CVS client, but this tutorial is for Win32 users, so we describe the WinCVS client here. (WinCVS uses CVSNT, which contains cvs.exe, the equivalent of the ``cvs'' UNIX command.) The CVS development model is the following: -- Obtaining information about connecting to the repositry -- Installing a CVS client -- Downloading the most recent snapshot of the repository using the CVS client. This operation is called ``checking out'' a ``local copy''. (Please note that the local copy contains less information than the repository. If the repository is lost, it cannot be reconstructed from the local copies in its entirety.) -- Working on the local copy. The following cycle is usually repeated: -- Getting modifications by other developers, using the CVS client. This is called ``(recursive) update''. -- Viewing the modifications. A CVS client is not required for this. The modifications should be viewed in a text editor (for text files), an integrated development environment (IDE) (for program source files), a photo editor (for image files), or other development tool used in the project. -- Making modifications to source files. Again, a CVS client is not required for this. It is allowed to make any modification with any editor, as many times as required. -- Invoking the ``add'' operation in the CVS client to add newly created files to your repository. There is also a ``remove'' operation. -- Getting modifications by other developers, using the CVS client. This step is required here to check whether the modification done by you, on your local copy, conflict with the modifications done by the others. There is a conflict e.g. if two developers modify the same line in a text file, or they add a new file with the same name. -- Resolving conflicts. Most conflicts can be resolved by editing files having conflicts. The CVS client marks conflicting lines with these markers: `<<<<<<', `======' and `>>>>>>'. Some other conflicts asks you to remove or rename a file from your local copy. -- Running an ``update'' again to ensure that the conflicts have gone away. -- Uploading the modifications in your local copy to repository. This operation is called ``commit''. It is not possible to commit files with conflicts -- so you have to resolve the conflicts caused by your modifications before your changes are visible to the other developers. A textual description must be attached to each commit, e.g. ``fixed bug #42 concerning saving uncompressed PNG files'', ``added a chapter about horses'', ``separated GTK and Win32 GUI code''. -- If your modifications are important or urgent, telling the others to ``update'' immediately. The recommended method for this is writing an e-mail. It is not necessary to include the names of the changed or added files, or the description of the change, because the others can retrieve these information from the CVS repository using their CVS client. -- Removing the local copy if you don't need it anymore. Make sure to commit first, because the uncommitted changes are lost. You can remove your local copy with any file manager, because files are stored as regular files, and meta-information is stored in directories named ``CVS'' in your local copy. The ``CVS'' directories are hidden on Win32. You can has as many local copies as you wish. For example, you can have one in your home computer, and one in your work computer. You can synchronize them using the standard ``commit'' and ``update'' operations. Local copies don't occupy resources on the server hosting the repository. It is OK to have files in your local copy about which CVS doesn't know. For example, the C compiler might generate foo.obj from foo.c. Of course, only foo.c is member of the repository, because foo.obj can be generated from it. (As a general rule, don't add a file to the repository if many of these conditions hold: the file is binary, the file is big, the file can be generated from already added files, the file changes often.) Connecting to the repository with SSH ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This tutorial doesn't teach you how to create or administer a repository. A deeper undestanding of CVS is required or that; consider installing a UNIX system with permanent internet access, and read the CVS Book. So we can assume that there is already a repository. You should ask for connection information from your project manager, co-developers or system administrator. They will probably tell you a couple of UNIX commands, such as: export CVS_RSH=ssh cvs -d :ext:username@hostname/repository/dir co module Another, equivalent example: export CVS_RSH=ssh export CVSROOT=:ext:username@hostname:/repository/dir cvs get module In the examples above, the `username', `hostname', `repository/dir' and `module' parameters are replaced with values specific to your project. If you see `:pserver:' in your CVSROOT, than some parts of this tutorial doesn't apply to you. It is OK to have `:ssh:' instead of `:ext:' in the beginning of CVSROOT, they are equivalent in WinCVS. (The word in the two colons is called ``protocol''.) You should already know your password for the username--hostname configuration. If you don't, ask for help from whom you got the connection information. Installing WinCVS ~~~~~~~~~~~~~~~~~ WinCVS is a highly customizable, efficient-to-use, GUI CVS client for Win32. It isues CVSNT as a backend for communicating with the repository. You can get the latest version from http://www.wincvs.org/download.html . Click on ``Recommended Builds'', and then ``Download Installer''. Don't click on ``Download "Bare" Installer''. You will be redirected to the Sourceforge download page. Select and mirror, and wait for your download to appear. The downloaded fill name will be WinCvs20-2.zip or similar. At the time of writing this tutorial, the recommended version was WinCvs 2.0.0.2 (released 2005-03-24). You don't have to download anything else. Some tutorials on the web suggest downloading SSH (version 1 or 2), plink.exe from PuTTY or something else. You don't need any of the above. The latest version of the WinCVS distribution contains everything needed. For example, SSH communication is done by plink.dll, part of CVSNT shipped with WinCVS. You will need an archiver (such as WinZIP or WinRAR) to extract the contents of th ZIP file. Run the extracted wincvs_setup.exe. You don't have to run cvsnt_setup.exe manually, but it must be in the same folder as wincvs_setup.exe, because wincvs_setup.exe will run it automatically. When you are asked about which components to install, you may safely uncheck ``Shared DLL libraries''. Start WinCVS. It might complain about a missing Python or TCL. Ignore such messages. Create a new folder in which you'll store your local copies. For practical reasons, give it a imple and short name which you can type quickly. For example: `C:\cvswork'. In Admin / Preferences / CVS, set the HOME to this folder. If you like command-line tools, it is a nice to have the cvs.exe (part of the installed CVSNT) on your PATH. Just add the folder containing cvs.exe (probably C:\Program Files\CVSNT) to your PATH. If you don't know how to do it, don't do it, because you don't need it. (For example, on Windows XP, you can change your PATH environment variable in the ``Start menu / Settings / Control Panel / System / Special / Environment variables'' dialog box.) Checking out a local copy using WinCVS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See the section ``Connecting to the repository with SSH'' about obtaining the connection settings. Please note that the protocol `ext' doesn't work here, replace with `ssh'. If your computer or network has a firewall installed, you should configure it to allow outgoing connections on TCP port 22 (for the `ssh' protocol) and/or on TCP port 2401 (for the `pserver' protocol). For the `ssh' protocol, you can use PuTTY (download and run putty.exe from the page Google finds first for `download putty'') to check whether you are able to connect -- just type the hostname, your username, seject the SSH protocol in the ``PuTTY Configuration'' dialog. After that you may have to click Yes in the host key dialog box, and then a new window with background appears, where you have to type your password. If the system lets you log in, run the command `cvs' (type ), which should display a usage message containing the line The Concurrent Versions System (CVS) is a tool for version control. If all these works, this indicates that you can connect with SSH. Use Remote / Checkout module. Specify these: -- Module name...: the `module' parameter -- Local folder...: specify your HOME directory wich you set when installing WinCVS -- CVSROOT: check it, and type :protocol:username@hostname/repository/dir with the parameters `protocol' (`ssh' or `pserver'), `username', `hostname' and `repository/dir' substituted. Click on OK. You will be asked for your password in a new window soon. WinCVS displays status messages in a textarea in the bottom of its main window. If everything goes fine, you'll get a line starting with `U ' for each file in the repository, and the line ***** CVS exited normally with code 0 ***** indicating success. If you get a code other than zero, scroll up, read the reason of the problem, and try again. Working with WinCVS ~~~~~~~~~~~~~~~~~~~ Use View / Browse Location / Change, and locate your WinCVS home folder. The contents of this folder appear in a tree view on the left of the WinCVS main window. The icons of folders CVS knows about are checked. The WinCVS main window is similar to Windows Explorer, but CVS-specific functionality is added. You can open a file using its standard Open shell association by pressing when it is active. You can edit it using its standard Edit shell association by pressing . Don't forget to save the file after editing it. You may have to press in WinCVS to refresh its views. WinCVS displays a red icon in front of all changed files. To ``update'' your local copy to incorporate the other developers' committed modifications, right click on your `module' folder in the folder tree on the right of the WinCVS main window, and select `Update'. Unselect ``Do not recuse into sub-folders'', select ``Create missing directories that exist in the repository''. Click on OK. You will be asked for your SSH password soon. It might be annying to type this password again and again. You might use SSH public key authentication (if supported by the server), but this is out of scope of this tutorial. Each CVS operation displays information in the status textarea (at the bottom of the WinCVS main window) about files affected. Each file name is prefixed by an indicator letter and a space. The indicator letters are (copied from UNIX `man cvs'): -- U: The file was brought up to date with respect to the repository. This is done for any file that exists in the repository but not in your source, and for files that you haven't changed but are not the most recent versions available in the repository. -- P: Like U, but the cvs server sends a patch instead of an entire file. This accomplishes the same thing as U using less bandwidth. -- A: The file has been added to your private copy of the sources, and will be added to the source repository when you run commit on the file. This is a reminder to you that the file needs to be committed. -- R: The file has been removed from your private copy of the sources, and will be removed from the source repository when you run commit on the file. This is a reminder to you that the file needs to be committed. -- M: The file is modified in your working directory. M can indicate one of two states for a file you're working on: either there were no modifications to the same file in the repository, so that your file remains as you last saw it; or there were modifications in the repository as well as in your copy, but they were merged successfully, without conflict, in your working directory. cvs will print some messages if it merges your work, and a backup copy of your working file (as it looked before you ran update) will be made. The exact name of that file is printed while update runs. -- C: A conflict was detected while trying to merge your changes to file with changes from the source repository. file (the copy in your working directory) is now the result of attempting to merge the two revisions; an unmodified copy of your file is also in your working directory, with the name .#file.revision where revision is the revi- sion that your modified file started from. Resolve the conflict as described in see node `Conflicts example' in the CVS manual. (Note that some systems automatically purge files that begin with .# if they have not been accessed for a few days. If you intend to keep a copy of your original file, it is a very good idea to rename it.) Under vms, the file name starts with __ rather than .#. -- ?: file is in your working directory, but does not correspond to any- thing in the source repository, and is not in the list of files for cvs to ignore (see the description of the -I option, and see node `cvsignore' in the CVS manual). WinCVS displays these lines with color (e.g. the ``U'' line has green foreground), so you can find them easly by scrolling up the status textarea. To add a file to the repository, select it with the wide blue block cursor, and use Modify / Add (for text files, including .txt, .c, .tex, .html, .xml) or Modify / Add binary (for binary files such as Word Documents, PDF documents, JPEG images, .exe etc.). Adding a file needs network access to the repository (and typing your password again), but the file is added only in the next ``commit''. To remove a file from the repository, select it with the wide blue block cursor, and use Modify / Remove. This also needs network access to the repository, and the file will be removed only after the next ``commit''. This is a serious limitation which prevents using CVS offline. Disk space is not freed on the repository server, because the file is kept in the Attic folder (the folder for removed files) in the repository, so it will still be possible to travel back in time and check out a version from the past. It is not possible to rename or move a file. If you remove a file and add it with a different name, all history information gets lost (i.e. the new file doesn't inherit the history of the old one). So choose your file names carefully, so you don't have to rename files too often. The bad support for renaming is a limitation of CVS history handling design -- try Subversion or darcs instead of CVS if this is a big problem for you. To ``commit'' your changes back to the repository, right click on your `module' folder in the folder tree on the right of the WinCVS main window, and select `Commit'. Enter a log message (a natural-language description of _what_ you have changed and/or added and why -- not how you changed it). Click on OK. You will be asked for your SSH password soon. Wait for the line ***** CVS exited normally with code 0 ***** in the status textarea. If you get a different status, scroll up to see the details, resolve the problem and try again. Please note that you should ``update'' before you ``commit'', to get a full list of conflicts. See in the section ``Overview of CVS'' for resolving conflicts. Commit only after the conflicts are resolved. If you try to commit while there are still conflicts, the conflict would fail. Caution ~~~~~~~ One of the main goals of CVS is it allows concurrent development. But sometimes it doesn't happen automatically, you have to be careful. Don't commit something which doesn't compile. This is to ensure that others always feel safe to update. Don't commit something which you know is wrong (e.g. it is too buggy). If you have a conflict during an update, give yourself time to resolve it. Don't just blindly remove parts around `<<<<<<'. After resolving the conflict, verify that the code compiles etc. Never overwrite a file magaged by CVS if the old and the new files come from a different `cvs update' (i.e. their CVS version is different). Blindly overwriting is an easily destructive way to cancel the modifications done by others. This also has social implications: the co-developer invests hard time to find what and how to modify, and you blindly cancel his modifications. He detects what you've done in a déj\`a vu feeling: ``I remember I've already fixed this bug before''. A simple rule: never ever overwrite anything, work directly in the CVS tree with your text editor. Always save all files in your text editor before doing CVS operations. Don't use an text editor (e.g. Notepad, joe 2.x) which doesn't notify you when the file being edited has been modified on disk. (If you really must use such an editor, close all files before doing CVS operations.) The modification might be done by the `cvs update'. If you get such a notification, always choose to reload the original file (so your unsaved modifications get lost, and not the co-developers' modifications). Do you have suggestions? ~~~~~~~~~~~~~~~~~~~~~~~~ Contact the author of the tutorial. The e-mail address is near the beginning of the tutorial. Possible improvements to this tutorial ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Imp: why text file? because CVS diffs line-by-line Imp: WinCVS SUXX: which files were updated? (green in the status) Imp: modification or change? Imp: resolving conflicts Imp: lines U, C, P, ? etc. Imp: with pserver Imp: folder == directory Imp: plink.dll Imp: disabling firewall Imp: update / checkout from back in time Imp: no atomic updates...