------------------------------------------------------------------------------- $Id: cvs_tutorial.txt,v 1.1.1.1 1998/08/18 22:06:47 k2krep Exp $ ------------------------------------------------------------------------------- THIS FILE This file is designed to give you a bird's eye view of the workings of the Concurrent Versions System (CVS). It is based (loosely) around cvs version 1.3. It is recommended that you make sure the cvs your are working with is this version before continuing. Please send me comments/additions/questions about this tutorial. It needs more input from folks. Novices can help by pointing out confusing sections or by sending me questions not covered by this file. Masters can help by first verifying that the information here is sane, by sending their own tutorials, and by generally providing intelligent feedback. Thanks, gray gray.watson@antaire.com Section: Description: ----------------------------------------------------------------------- Introduction: basic description of the CVS system. Terms: some basic words and descriptions (needs more entries!) Basic CVS Commands: a look at the CVS basic command set. Getting Started: the things to do before using CVS. Basic Usage: a "real-life" example of the usage of CVS. General Help: how to get more information about CVS commands. RCS and CVS... explains what's the difference between the two. General Questions: some questions about cvs and some (often weak) answers. Experienced Questions: some questions for people more experiences with CVS. Contributions: list of some of the folks that have provided feedback. Mkmodules Patch: a patch for mkmodules to make it know about cvsignore ------------------------------------------------------------------------------- INTRODUCTION CVS is a system that lets groups of people work simultaneously on groups of files (for instance program sources). It works by holding a central 'repository' of the most recent version of the files. You may at any time create a personal copy of these files by 'checking out' the files from the reposity into one of your directories. If at a later date newer versions of the files are put in the repository, you can 'update' your copy. You may edit your copy of the files freely. If new versions of the files have been put in the repository in the meantime, doing an update merges the changes in the central copy into your copy. When you are satisfied with the changes you have made in your copy of the files, you can 'commit' them into the central repository. When you are finally done with your personal copy of the files, you can release them and then remove them. ------------------------------------------------------------------------------- TERMS: Repository: The directory storing the master copies of the files. The main or master repository is a tree of directories. Module: A specific directory in the main repository. Modules are defined in the cvs modules file. RCS: Revision Control System. A lower-level set of utilities on which CVS is layered. Check out: To make a copy of a file from its repository that can be worked on or examined. Revision: A numerical tag identifying the version of a file. ------------------------------------------------------------------------------- BASIC CVS COMMANDS: Most of the below commands should be executing while in the directory you checked out. If you did a 'cvs checkout malloc' then you should be in the malloc sub-directory to execute most of these commands. 'cvs release' is different and must be executed from the directory above. CVS CHECKOUT (or CVS CO) To make a local copy of a module's files from the repository execute 'cvs checkout module' where module is an entry in your modules file (see below). This will create a sub-directory module and check-out the files from the repository into the sub-directory for you to work on. CVS UPDATE To update your copy of a module with any changes from the central repository, execute 'cvs update'. This will tell you which files have been updated (their names are displayed with a U before them), and which have been modified by you and not yet committed (preceded by an M). It can be that when you do an update, the changes in the central copy clash with changes you have made in your own copy. You will be warned of any files that contain clashes, the clashes will be marked in the file surrounded by lines of the form <<<< and >>>>. You have to resolve the clashes in your copy. After an update where there have been clashes, your original version of the file is saved as .#file.version. To lose your changes and go back to the version from the repository, delete the file and do an update. CVS COMMIT When you think your files are ready to be merged back into the repository for the rest of your developers to see, execute 'cvs commit'. You will be put in an editor to make a message that describes the changes that you have made (for future reference). Your changes will then be added to the central copy. When you do a commit, if you haven't updated to the most recent version of the files, cvs tells you this; then you have to first update, resolve any possible clashes, and then redo the commit. CVS ADD and CVS REMOVE It can be that the changes you want to make involve a completely new file, or removing an existing one. The commands to use here are: cvs add cvs remove You still have to do a commit after these commands to make the additions and removes actually take affect. You may make any number of new files in your copy of the repository, but they will not be committed to the central copy unless you do a 'cvs add'. CVS RELEASE When you are done with your local copy of the files for the time being and want to remove your local copy use 'cvs release module'. This must be done in the directory about the module sub-directory you which to release. If you wish to have CVS also remove the module sub-directory and your local copy of the files then your 'cvs release -d module'. Take your time here. CVS will inform you of files that may have changed or it does not know about (watch for the ? lines) and then with ask you to confirm this action. Make sure you want to do this. CVS LOG To see the commit messages for files, and who made them, use: cvs log [filenames] CVS DIFF To see the differences between your version of the files and the version in the repository do: cvs diff [filenames] CVS TAG One of the exciting features of CVS is its ability to mark all the files in a module at once with a symbolic name. You can say 'this copy of my files is version 3'. And then later say 'this file I am working on looked better in version 3 so check out the copy that I marked as version 3.' Use 'cvs tag' to tag the version of the files that you have checked out. You can then at a later date retrieve this version of the files with the tag. cvs tag tag-name [filenames] Later you can do: cvs co -r tag-name module CVS RTAG Like tag, rtag marks the current versions of files but it does not work on your local copies but on the files in the repository. To tag all my libraries with a version name I can do: cvs tag LIBRARY_2_0 lib This is one of the most use features of cvs (IMHO). Use this feature if you about to release a copy of the files to the outside world or just want to mark a point in the developmental progression of the files. CVS HISTORY To find out information about your cvs repositories use the 'cvs history' command. By default history will show you all the entries that correspond to you. Use the -a optiont to show information about everyone. cvs history -a -o shows you (a)ll the checked (o)ut modules cvs history -a -T reports (a)ll the r(T)ags for the modules (!!!) cvs history -a -e reports (a)ll the information about (e)verthing ------------------------------------------------------------------------------- GETTING STARTED: Make sure all your developers have the CVSROOT environmental variable set to the directory that is to hold your main file repository (mine is set to /usr/src/master). Run the cvsinit script that comes with cvs to initialize the repository tree. Encourage all your developers to make a working directory where they will be working on the files (mine is ~/src/work). Edit the modules file to add the local "modules". Either cd to ${CVSROOT}/CVSROOT and 'co -l modules' and then edit it. Or better, cd to your working directory and do a 'cvs co modules'. NOTE: co is an alias for checkout Add your modules to the file. I add the below lines to my file: # libraries lib antaire/lib db antaire/lib/db dt antaire/lib/dt inc antaire/lib/inc lwp antaire/lib/lwp malloc antaire/lib/malloc inter antaire/lib/inter prt antaire/lib/inter/prt The above entries now allow me to 'cvs co malloc' which will create a directory malloc where I am and check out the files from ${CVSROOT}/antaire/lib/db into that directory. 'cvs co lib' will check out all my libraries and make a whole tree under lib: lib/db/*, lib/dt/*, lib/inc/*, etc Create a cvsignore file in ${CVSROOT}/CVSROOT: This file contains the local files that you want cvs to ignore. If you have standard temporary files, or log files, etc. that you would never want cvs to notice then you need to create this file. The first time you should go into the CVSROOT directory, edit the file and 'ci -u cvsignore' to check it in. You should apply the mkmodules.patch (included at the end of this file) and recompile and install the mkmodules file and add the below line to your modules file (see above) so you can use cvs to edit the file in the future. cvsignore -i mkmodules CVSROOT cvsignore I have in my file: *.t *.zip MAKE.LOG Makefile.dep a.out logfile ... CVS ignores a number of common temp files (*~, #*, RCS, SCCS, etc..) automatically. (see cvs(5)). WARNING: cvs is good at this. :-) any files in the cvsignore file will be ignored completely without a single warning. Add your files into their respective module directories: cd into your current directory which holds the files. Build clean/clobber and make sure that only the files you want to be checked into the repository are in the current directory. Execute: cvs import -m 'comment' repository vendortag releasetag The comment is for you to document the module The repository should be a path under ${CVSROOT}. My malloc library is checked into antaire/lib/malloc Vendortag is a "release tag" that the vendor assigned to the files. If you are the vendor then put whatever you want there: (PRT_INITIAL, MALLOC_1_01, etc); Releasetag is your local tag for this copy of the files. (PRT_1, malloc_1_01, etc); ------------------------------------------------------------------------------- BASIC USAGE: cd to your work directory (I do 'cd ~/src/work') Execute 'cvs co module' where module is an entry from the modules file (see above): I do 'cvs co malloc' to get my malloc library. It will create the sub-directory malloc and will load the files into this new directory. Edit the files to your heart's content. If you add any new files to the directory that you want the repository to know about you need to do a cvs add file1 [file2 ...] If you remove any files you need to do a cvs remove file1 [file2...] If you rename you need to do a combination remove and then add. Execute 'cvs update' to pull in the changes from the repository that others made. It will resolve conflicts semi-automatically. It will tell you about the files it updates. U means updated, C means there was a conflict that it could not automatically resolve. You need to edit the file by hand, look for the <<<<< and >>>>> lines and figure out how the file should look. Execute 'cvs commit' inside the directory you checked out to apply your changes to the repository so others can use them (if they have the module in question checked out already, they need to do a 'cvs update' to see your changes). When you are done with the files (for the time being) you cd .. to the above directory and do a 'cvs release [-d] module-name' which will "check-in" the files. The optional -d will remove the directory and files from your work directory when it is done releasing them. The release command will inform you if your made modifications to the files and if there are files it doesn't know about that you may have forgotten to add. watch for '? file' lines printed. You may have to stop the release and commit or cvs add/remove the files. WARNING: release -d is unrecoverable. Make sure you take your time here. Don't worry, release should ask whether you really want to do this before doing anything. ------------------------------------------------------------------------------- GENERAL HELP: All cvs commands take a -H option to give help: 'cvs -H' shows you the options and commands in cvs. 'cvs history -H' shows you the options for cvs history. All the cvs commands mentioned also accept a flag '-n', that doesn't do the action, but lets you see what would happen. For instance, you can use 'cvs -n update' to see which files would be updated. To get more information, see the manual page 'man cvs' for full (and much more complicated) details. A basic knowledge of the Revision Control System (RCS) on which CVS is layered may also be of some assistance. see 'man co' or 'man ci' for more details. ------------------------------------------------------------------------------- RCS and CVS - what's the difference? Collection of files ------------------- One of the strong points about CVS is that it does not only lets you retrieve old versions of specific files. You can collect some files (or directories of files) into ``modules'' and a lot of the CVS commands can operate on an entire module at once. The RCS history files of all modules are kept at a central place in the file system hierarchy. When someone wants to work an a certain module he just types "cvs checkout bugtrack" which causes the directory ``bugtrack'' to be created and populated with the files that make up the bugtrack project. With "cvs tag bugtrack-1.0" you can give the symbolic tag "bugtrack-1.0" to all the versions of the file in the bugtrack module. Later on, you can do "cvs checkout -r bugtrack-1.0 bugtrack" to retrieve the files that make up the 1.0 release of bugtrack. You can even do things like "cvs diff -c -r bugtrack-1.0 -r bugtrack-1.5" to get a context diff of all files that have changed between release 1.0 and release 1.5! No locking ---------- If you work in a group of programmer you have probably often wanted to edit the function foo() in bar.c, but Joe had locked bar.c because he is editing gazonk(). CVS does not lock files. Instead, both you and Joe can edit bar.c. The first one to check in it won't realize that the other have been editing it. (So if you are quicker than Joe you wont have any trouble at all). Poor Joe just have to do "cvs update bar.c" to merge in your changes in his copy of the file. As long as you changing different sections of the file the merge is totally automatic. If you change the same lines you will have to resolve the conflicts manually. Friendlier user interface ------------------------- If you don't remember the syntax of "cvs diff" you just type "cvs -H diff" and you will get a short description of all the flags. Just "cvs -H" lists all the sub-commands. I find the commands less cryptic than the RCS equivalents. Compare "cvs checkout module" (which can be abbreviated to "cvs co module") with "co -l RCS/*,v" (or whatever it is you are supposed to say - it was a year since I used RCS seriously). ------------------------------------------------------------------------------- GENERAL QUESTIONS: When I say 'cvs checkout module/sub-directory' and then 'cvs release module/sub-directory' it says unknown module name. why? - because module/sub-directory is not a module in the modules file. - cvs release module *should* work with this. Because of incorrect releasing of directories, I noticed that 'cvs history' reports that modules are still checked out. how do I correct this? - by editing $CVSROOT/CVSROOT/history VERY carefully - I do not know the correct way of doing this but the O lines are for checking Out modules. Removing the last O line that corresponds to the module is question may work. If I just typoed and started to check out a tree I did not want to. Can I hit control-c? What are the ramifications? - don't know exactly I screw up and removed the tree that I was about to start working on. How do I tell cvs that I want to release it if I don't have it anymore? - maybe you can't - you need to edit $CVSROOT/CVSROOT/history VERY carefully to fix this problem (see above) - FEATURE: an option to release to assure it that no changes were made and the status of the directory can be released What is the proper way to configure cvs for multi-user operations? What sort of file directory modes are appropriate aside from 770 modes everywhere. Any setgid support? - normal 770 directory modes should work. - set your default umask to 027 - make your $CVSROOT directories set-gid all with a common group (src would make sense) and mode 770 - make sure all your developers are in the src group. I am constantly running into different library modules to fix problems or add need features. This may not be a good practice but how does cvs fit in this scenario. Should I checkout the modules I need and once and a while commit them? - yes. I have 4 releases of my debug malloc subsystem. They are 1.01, 1.02, 1.03, 1.05. Should I: cvs import -b 1.1.1 -m 'Malloc 1.01' MALLOC_1_01 malloc_1_01 cvs import -b 1.1.2 -m 'Malloc 1.02' MALLOC_1_02 malloc_1_02 cvs import -b 1.1.3 -m 'Malloc 1.03' MALLOC_1_03 malloc_1_03 cvs import -b 1.1.5 -m 'Malloc 1.05' MALLOC_1_05 malloc_1_05 for each set of files? Are these sane incantations? - not really. cvs import may not be the right may to do this. - you should cvs import the *first* set of files then for each release you should: - copy in the new version - cvs add/remove the files that have been added/deleted - cvs commit the new version - cvs tag the files with the appropriate release-tag - repeat When I say 'cvs checkout malloc' I do not get 1.05 files. I get them all. I have to say 'cvs checkout -r malloc_1_05 malloc to do this. Is this correct? Do I need to 'cvs remove' the files that have been removed between the different versions? - yes, you need to cvs add/remove files to have the repository know about them. the files that are removed are placed in the Attic so that old-revisions can find them. Is there a cvs feature to tell me what files have changed, what are new what have been removed from the current directory? - when you do a cvs release, cvs will inform you of the missing files and the new files. - FEATURE: cvs commit with an option should tell you the files that are missing or added. If I had fileX at one point, then I 'cvs remove' it, then I recreate it. How can I re-add it. It complains that it is in the attic. Can it live there for old versions but have a new copy also? - I believe you can move the file out of the Attic directory by hand. this seems to work fine. ------------------------------------------------------------------------------- EXPERIENCED QUESTIONS: CVS handled binary files but it seems to corrupt them once and while? CVS uses RCS and RCS looks for certain sequences of characters like $Id: cvs_tutorial.txt,v 1.1.1.1 1998/08/18 22:06:47 k2krep Exp $ and replaces them with version information. So what if a keyword sequence just happens to occur in a binary file since any sequence of ASCII characters is possible? CVS will update any keyword sequences it finds and will corrupt any binary files in which these sequences occur. So keyword substitution must be prevented in binary files by added info to the rcs files for each binary file. I also prevent it in any files in which I don't plan to insert rcs keywords just to reduce checkout time. This can be done in the repository using the rcs command: rcs -ko How can I use the $Log: cvs_tutorial.txt,v $ How can I use the Revision 1.1.1.1 1998/08/18 22:06:47 k2krep How can I use the Offline Web page contents are here. How can I use the This part is controlled by JOS:) consept. you need to add How can I use the every progress of you by using CVS add/update/commit. How can I use the See http://neutrino.kek.jp/~k2k/ofl for detail, where How can I use the the newest contents of this modules are in. How can I use the keyword with CVS with Objective-C and // comments? RCS (and therefore CVS) doesn't know about Objective-C "//" comments by default. I must inform RCS so that when it expands its $Log: cvs_tutorial.txt,v $ default. I must inform RCS so that when it expands its Revision 1.1.1.1 1998/08/18 22:06:47 k2krep default. I must inform RCS so that when it expands its Offline Web page contents are here. default. I must inform RCS so that when it expands its This part is controlled by JOS:) consept. you need to add default. I must inform RCS so that when it expands its every progress of you by using CVS add/update/commit. default. I must inform RCS so that when it expands its See http://neutrino.kek.jp/~k2k/ofl for detail, where default. I must inform RCS so that when it expands its the newest contents of this modules are in. default. I must inform RCS so that when it expands its it will prepend the proper comment characters. rcs -c"// " ------------------------------------------------------------------------------- CONTRIBUTIONS: Steven Pemberton, CWI, Amsterdam; Steven.Pemberton@cwi.nl Per Cederqvist, ceder@lysator.liu.se Art Isbell, isbell@cats.UCSC.EDU