Newsgroups: comp.software.config-mgmt Date: 1998/05/10
Newsgroups: comp.software.config-mgmt Date: 1998/05/10
I'm putting together a mini-HOWTO for CVS that focuses on how an individual might set up a CVS repository for maintaining an Internet-style project. The mini-HOWTO covers creating the repository, starting a project, the edit cycle, tagging releases, and making releases.
This is a final draft of the mini-HOWTO and I'd like to get your comments on it if you can spare a moment.
Thanks,
-- Ken
$Id: CVS-mini-HOWTO,v 1.3 1998/05/10 15:38:06 ken Exp $
CVS mini-HOWTO
Ken MacLeod <ken@bitsko.slc.ut.us>
INSTALLATION
There's no special setup required to build and install, it's a typical 'net software install, and all the setup happens afterward. Install RCS first, then CVS. Installing in your home directory is OK.
Pick an empty directory to be your CVSROOT and set the `CVSROOT' environment variable to point there. This can be in your home directory to start and you can move projects to a seperate account when you're ready to make them publicly available.
Run `cvs init'. This will create the directory if you didn't already, and create a subdirectory `$CVSROOT/CVSROOT' to contain log files and other admin files. As you create or import projects they'll each go into their own subdirectory under `$CVSROOT', and they will all be ordinary RCS files, feel free to look around (but don't touch :-).
See the info section “Repository”, and “Creating a repository” under it for more details.
STARTING A NEW PROJECT
Because renaming files and moving them between directories is somewhat inconvenient, the first thing you do when you start a new project should be to think through your file organization. It is not impossible to rename or move files, but it does increase the potential for confusion and CVS does have some quirks particularly in the area of renaming directories. — in “Starting a project with CVS”
[The rest of this section is copied from info, “Creating a directory tree from a number of files.” I'll use a project name `GeeWhiz'.]
When you begin using CVS, you will probably already have several projects that can be put under CVS control. In these cases the easiest way is to use the `import' command. An example is probably the easiest way to explain how to use it. If the files you want to install in CVS reside in `WDIR', and you want them to appear in the repository as `$CVSROOT/GeeWhiz', you can do this:
$ cd WDIR $ cvs import -m "Imported sources" GeeWhiz yoyo start
Unless you supply a log message with the `-m' flag, CVS starts an editor and prompts for a message. The string `yoyo' is a "vendor tag", and `start' is a "release tag". They may fill no purpose in this context, but since CVS requires them they must be present.
You can now verify that it worked, and remove your original source directory.
$ cd .. $ mv WDIR WDIR.orig $ cvs checkout GeeWhiz $ ls -R GeeWhiz $ rm -r WDIR.orig
Erasing the original sources is a good idea, to make sure that you do not accidentally edit them in WDIR, bypassing CVS. Of course, it would be wise to make sure that you have a backup of the sources before you remove them.
WHAT NOT TO ARCHIVE
Your repository does not need to have anything in it that you, the author, can regenerate on your machine. This includes `Makefile's from `Makefile.in', `configure', formatted docs, etc. All of these files will be generated when you create a release.
A TYPICAL EDIT CYCLE
A typical edit cycle starts with a checkout, goes through several commits as you make snapshots, and will most often end with releasing and deleting the project directory before starting on the next cycle. I'll leave tagged snapshots to a later section and focus on basic editing here.
CVS will use the project name as the directory name where you'll do your edits:
$ cvs checkout GeeWhiz
CVS will check out your project and you can begin editing right away. CVS doesn't “lock” files like RCS and SCCS do, so you don't have to lock a file before editing it. You'll notice that there are `CVS' directories in your project, this is where CVS tracks adds and removes of files and other admin info, you'll probably want to make sure your scripts ignore these directories.
You add files and directories using the `cvs add' command. You must create the directories and files first, and then add them with `cvs add NAME'. Add the directories first and then files inside the directories. You remove files and directories with the `cvs remove NAME' command, removing all files first if you want to remove the directory. CVS will simply record adds and removes until you commit your changes, it doesn't actually modify the repository at this point.
You can commit your changes at any time using `cvs commit', CVS will start your editor and ask you for a change description, if you've made changes in several directories it will ask you again for each directory, you can redit the comment for each directory or you can exit your editor and type `!' to use the same comment for all remaining directories.
I usually make changes in small batches and commit them as I finish a round of edits. I also try to make sure that I've tested somewhat before I commit, that way if I need to quickly export a copy there's a pretty good chance of it working.
As you are making changes, the `cvs diff' command will give you the diff between your current working copy and the copy that you last committed or originally checked out (i.e. if you're working with others, by default it won't show their changes). I do this often to double check my NEWS and ChangeLog. You can also use tags (described below) to show the diff from previous versions.
When you are finished with a new version of your project and have committed your changes, you can release and delete your work area by running the `cvs release' command in the parent directory of your work area:
$ cd .. $ cvs release -d GeeWhiz You have [0] altered files in this repository. Are you sure you want to release (and delete) module `GeeWhiz': y
CVS will display files it doesn't know about (leftovers or intermediate files) and ask you for confirmation before deleting the directory. I prefer to release and delete the project directories between versions just so I know this happens. If you notice anything unusual, just answer `n' and nothing will be touched. (You can also use the `-n' option to check first.)
** WARNING **
Answering `y' *will* delete the entire directory, even if there are modified files, unknown files, or that file you just spent six hours creating and forgot to add.
I always do a `make clean' before releasing so there are no suspect files and I look for `[0] altered files' before releasing.
See also “A sample session” in the “Overview” section of info.
TAGGING RELEASES
When you commit a batch of changes, CVS doesn't do anything special to record the fact except create new revisions of the individual files. You could view the log of commits and diff or export based on the date of commits, or you can do it the easy way and `tag' after each commit or the final commit. Tagging a project tags all the files at the current, or specified, revision together, not just modified files.
Version numbering is apparently a very personal thing, everyone seems to have their own idea of what makes up a good release number, including betas and developer snapshots. That's OK. You can tag your revisions with any label you want as long as it fits CVS's syntax: Tag names can contain uppercase and lowercase letters, digits, `-', and `_'. They must start with a letter, and sorry, no dots (`.') :-( Personally, I use `_' instead of dot and I start with an `r' for lack of anything better, i.e. `r1_2' for version `1.2'.
You can have more than one tag on a revision. You can tag a revision as `r2_4snap1', release it to a few people, come back later and add a tag `r2_4beta1' and release it to a lot more people, and then finally add a tag `r2_4' when you release it to the public. As I'm nearing a release, I will use `r2_4d1', `r2_4d2', `r2_4d3', etc. as I go through my release steps (below), and when everything builds without fail, I tag it with the final release tag and do one final build with the new tag.
Use the `rtag' command tag the latest revision of your project:
$ cvs rtag r2_4d3 GeeWhiz cvs rtag: Tagging GeeWhiz
Use the `-r' option to add another tag on top of an existing tag:
$ cvs rtag -rr2_4d3 r2_4 GeeWhiz cvs rtag: Tagging GeeWhiz
Always use the `-r' option to add another tag, so that you know for sure that you're not accidentally adding any more recently committed files since you last tested.
If you tag a release and then find that you still have an error (before you make it available, of course), you can delete the tag using:
$ cvs rtag -d r2_4 GeeWhiz cvs rtag: Untagging GeeWhiz
If you mistype a tag, or otherwise want to rename a tag, first add the new tag using `-r' with the old tag, and then delete the old tag:
$ cvs rtag -rold_tag new_tag GeeWhiz cvs rtag: Tagging GeeWhiz $ cvs rtag -d old_tag GeeWhiz cvs rtag: Untagging GeeWhiz
RELEASE STEPS
Releasing your project is going to vary a lot depending on how you create release files, how you handle putting revision numbers in your files, how you make your project available to others, and how you announce updates. A lot can, and probably should, be scripted to reduce errors, but leave yourself some checkpoints that you do manually so you can watch logs and catch errors.
My preferred way of making releases is to “freeze” my changes and “start into the release process”. Basically, if nothing goes wrong in the release process then my most recently committed changes will be my release, if there are any errors then I make the change and re-commit, starting the whole cycle again. For minor releases I've found this takes about 15 minutes, for major releases it can be 45 minutes or more, depending on how many errors my users don't have to find for me. :-)
Here are the steps I typically take, starting just before the freeze:
update README, NEWS, and double check ChangeLog, if there are any new files then check copyrights, RCS ids, and `cvs add'.
build and `make test' one last time in the work area, then `make maintainerclean' (no generated files) and delete any leftovers.
freeze and commit
I switch to another directory to test building
`cvs rtag TAG GeeWhiz'
`cvs export -r TAG GeeWhiz'
run `autoconf', `perl Makefile.PL', or whatever you need to prep the release
run `make dist', or whatever you need to create the distribution for your package
==> I have a script `make-rel' for these last three steps that also edits in the version numbers based on the tag.
http://bitsko.slc.ut.us/~ken/make-rel/
create binaries if you do that sort of thing
==> I have a script `make-rpm' that creates RPMs from the source tar file.
if everything works up to this point, go back and retag with a final release tag
upload or otherwise make your release available
post announcements and update your web page
release and delete your work area
SUMMARY OF COMMANDS
$CVSROOT
Points to the repository where all CVS (RCS) files are kept.
cvs init
Creates the repository and initializes the admin files.
cvs import -m "Imported sources" MODULE yoyo start
Creates the initial baseline of MODULE. `-m' is the initial
comment (otherwise you will be prompted), `yoyo' is a vendor
tag and `start' is the initial tag
cvs checkout MODULE
Checkout MODULE for editing. CVS does not lock out other
people from editing.
cvs add DIRECTORY
cvs add FILE
Schedules a directory or file to be added to the repository on
the next commit. You must add each of the files in the
directory after you add the directory (i.e. adding the
directory doesn't add the files underneath it). The directory
or files must exist before you run this command.
cvs remove FILE
cvs remove DIRECTORY
Schedules a file or a directory to be declared not to be part
of the project when they are committed (i.e. you can still
retrieve them as part of older revisions, they are not deleted
from the repository). The files or directory must already be
removed before you run this command.
cvs commit
Commit all changes that have been made since the last commit
or checkout. You will be placed in an editor to supply a
change description.
cvs diff
Display differences between the current work area and the last
commit or checkout.
cvs release -d MODULE
Release and delete the work area. WARNING: Be careful with
this command, you can delete uncommitted files. Run this
command in the parent directory of your work area.
cvs rtag TAG MODULE
Apply a new tag TAG to the most recent commited change to
MODULE. Tags must start with a letter and contain only
letters, digits, `-' and `_'.
cvs rtag -rOLDTAG TAG MODULE
Add a new tag TAG to the same OLDTAG revisions in MODULE.
cvs rtag -d TAG MODULE
Delete TAG from MODULE.
cvs export -r TAG MODULE
Export a copy of MODULE using TAG.
Below is a CVS version control mini tutorial I wrote. It should only take 10 to 15 minutes to complete. It shows how to install and use CVS on a local Windows PC. You neither need a network nor a file server, so you can try this at home, too. However, the same CVS installation can be used both locally and with a (Linux) file server. Changing the CVSROOT environment variable switches between your local repository and central repository. Yes, it is that easy.
This is a great way to learn CVS. Even better, you can try out (unfamiliar) commands locally on a test project first before you make (big) changes the file server that you are not sure about. Also, all commands shown in Karl Vogel's CVS book (available on the web at: http://cvsbook.red-bean.com) work in local mode.
If you still like CVS you can go ahead and setup a Linux CVS server.
Olaf
The intention of this tutorial is to give a brief overview of basic version control functions and to show how easy it is to install and use a version control system. This tutorial uses CVS as the version control system. CVS was chosen because it is freely available along with good documentation and it works on many operating systems. The steps below assume a 32 bit Microsoft Windows operating system. Please note that even though you downloaded and installed WinCVS we are only interested in the CVS command line interface (because it is simpler). WinCVS includes the latest version of CVS for Windows PCs along with a nice install program.
Multiple work areas (called sandboxes from here on) are used to simulate two users sharing code of a test source code project. This avoids having to log in with different user names. This is one example of using multiple sandboxes of the same project on the same PC.
Download WinCVS (currently version 1.1b8) from http://www.wincvs.org/download.html. Install WinCVS, accept all defaults.
Create a directory structure like this on your hard disk:
c:\cvs c:\cvs\test c:\cvs\work\sb1 c:\cvs\work\sb2
Populate the new directory tree with these files:
c:\cvs\env.bat (see below) c:\cvs\test\makefile.txt (optional) c:\cvs\test\include\file1.h (optional) c:\cvs\test\include\file2.h (optional) c:\cvs\test\source\file1.c (see below) c:\cvs\test\source\file2.c (optional)
Create a batch file called cvs_env.bat in the c:\cvs directory:
set path=%path%;C:\Program Files\GNU\WinCvs 1.1; set CVSROOT=:local:c:\cvs\repository
The five files in the test sub-directory simulate a source code project. All files contain only their file name on the first line. Note, only file1.c is used in the steps below.
Open a command prompt (DOS) window, go to the c:\cvs directory, and execute the cvs_env.bat file, i.e. type "cvs_env" (omit the quotes). This sets up the command line environment needed by the CVS version control system. Repeat this step each time you open a command prompt window for CVS. Hint, you can use multiple command prompt windows, one for each sandbox (explained below).
Type "cvs -help". This displays the CVS help screen and verifies the first line in the cvs_env.bat file.
Type "cvs init". This is the only command that does not require specific directory. This initializes the CVS repository and verifies the second line in the cvs_env.bat file. This CVS command will return without displaying any message, however it creates a directory called c:\cvs\repository. This repository (directory) contains administrative and configuration files at c:\cvs\repository\CVSROOT, all defaults will work fine for this tutorial. More importantly the repository will also contain the version control database (master copy of your source code along with a history of all changes). The repository is usually located on a central file server, but not in this tutorial to keep things simple.
Go to the c:\cvs\test directory and type:
cvs import -m"Initial import into CVS" test your_login_name start
This imports (copies) all files into the repository (to c:\cvs\repository\test) and puts the source code project under version control. The c:\cvs\test directory is no longer needed and can now be removed.
Go to the c:\cvs\work\test\sb1 directory. Type "cvs checkout test". This creates a sandbox (or work area) of the source code project.
Go to the C:\cvs\work\test\sb1\test\source directory. Add this line to file1.c (using your favorite editor or the Windows build-in editor called notepad):
"Added code for feature 1"
Type "cvs diff" or "cvs diff -c". This displays the change you just made to file1.c.
Type "cvs commit -m"Finished feature 1"". This will check-in your change into the repository.
Now go to the still empty sandbox 2 directory c:\cvs\work\test\sb2. Type "cvs checkout test". This creates another sandbox of the source code project. Note that this sandbox of the test source code project includes the change we made above in the sandbox 1 directory.
Go to the c:\cvs\work\test\sb2\test\source directory and add this line to file1.c:
"Added more code for feature 2"
Type "cvs commit -m"Finished feature 2"". This will check-in your change to the repository.
Go back to the sandbox 1 directory containing the file1.c file. Type "cvs status". This will show that there is a new version of file 1 available (file1.c status: Needs Checkout).
Type "cvs update". This will update sandbox 1 with the change made in sandbox 2.
Lastly, try "cvs log file1.c". This will display all revisions for file1.c along with all log information. Note the comments you entered above as part of the CVS commit commands.
Omitting the file name causes CVS to apply a command to the entire current directory tree. Go to the root of sandbox 1 (c:\cvs\work\sb1) and repeat the log command without a file name, i.e. "cvs log".
That's it. To summarize, you put your test source code project under version control, created a sandbox, made a change to the test project in your sandbox, and checked that change back in (to the repository). You then created a second sandbox (simulating a second user). The second sandbox contained the change you just made in the first sandbox. You then made another change, but this time in the second sandbox. The tutorial then concludes by showing how the first sandbox is updated to reflect the change from the second sandbox (user).
I would like to thank Stephen Coon for proofreading and testing this tutorial.
Olaf