A good way to do branching in CVS is to make a branch at every release and continue the main development on the trunk. Changes on the release branch that also need to be applied to the trunk can be merged back into the trunk from the branch. Having the branch will allow you to have an active working copy of the release version and continue making corrections to it without worrying about messing up the active development version and without applying every change you made in two places manually.
For an example of how to create a branch based on a release version we’ll use a revision tagged release_0630 for the head of the branch.
##$ ls
website/
##$ cvs co -d website0630 -r release_0630 website
U a whole bunch
U of stuff
##$ ls
website/ website0630/
##$ cd website0630
##$ cvs tag -b Release_0630-branch
T a whole bunch
T of stuff
##$
Branch tags are easy to confuse with other tags, so it may be a good idea to include the word branch in the tagname of a branch.
Now to actually check out that working copy as a working copy on the branch:
##$ cd ..
##$ mv website0630 website0630.bak
##$ cvs co -d website0630 -r Release_0630-branch website
(You can also change the working copy to a copy of that branch with an update command [ cvs up -r Release_0630-branch ] but be careful not to do this if you have made changes to any of the files in the working copy as it could create problems or unexpected changes to your data)
Like always, if you want to revert the working copy to the latest version on the trunk you need to clear the sticky tags:
##$ cvs up -A -d
(the -d option to up builds directories like co does)
first lets get back to the latest version on the trunk:
##$ cd ../website
##$ cvs up
Now we’ll check for differences between the trunk and the branch
##$ cvs -q diff -c -r Release_0630-branch
(the -c option to diff is for a context diff, -u is also nice)
Now we’ll pretend that we found some differences in the branch that need to be checked into the trunk
##$ cvs up -d -j Release_0630-branch
the -j option means join
Sometimes a branch will continue to be actively developed even after the trunk has undergone a merge from it. For example, this can happen if a second bug in the previous public release is discovered and has to be fixed on the branch.
If you try to merge those changes with that same command you’ll get conflicts.
What we’ll want to do to make it easiest to avoid this is to tag the branch whenever we merge changes. This way we can use the tag from the last merge as the starting point for the join.
Let’s take a look at a scenario where we’ve done this properly:
##$ pwd
website/ website0630/
##$ cd website
##$ cvs up
##$ cvs up -d -j Release_0630-branch
##$ cd ../website0630
##$ cvs up
##$ cvs tag Merge_Release0630_0708
After merging we tagged the branch, so now on July 10th when we want to merge again we can do it like this:
##$ cd ../website
##$ cvs up
##$ cvs up -d -j Merge_Release0630_0708 -j Release_0630-branch
##$ cd ../website0630
##$ cvs tag Merge_Release0630_0710
Those two -j options told it to start at the revision marked and proceed to the latest revision in the branch when determining what to merge with the trunk.
I included the branch name in the tag for merging because tag names must be unique per file, even across multiple branches. If we merged two seperate branches into the trunk on the same day it would be really easy to have problems with duplicate tag names. Adding the branch name solves that particular problem.
rtag
It is not really necessary to check out a working copy at the branch point in order to create the branch. We could have used rtags since we now the tag name of the release point:
##$ cvs rtag -b -r release_0630 Release_0630-branch website
To get a list of tags in the repository you can use cvs log. Here’s an example:
##$ cvs log index.html
Working file: index.html
head: 1.4
branch:
locks: strict
access list:
symbolic names:
Release_0630: 1.4
start: 1.1.1.1
akatombo: 1.1.1
keyword substitution: kv
total revisions: 5; selected revisions: 5
description:
----------------------------
revision 1.4
date: 2005/06/16 14:01:03; author: bob; state: Exp; lines: +150 -150
giant Japanese checkin
...
As you can see above, the symbolic names section contains a list of the tags on that file, and which revision number they are tied to
files in Repository CVSROOT directory
easiest way to look at them is to check them out like a normal cvs project (cvs co CVSROOT)
look at files in order of importance
config
allows you to configure certain global behavior parameters
you can give alternative names for a project and sub directories of it:
mp myproj
asub myproj/a-subdir
with this in the modules file, the following commands would be valid:
cvs co mp
cvs -d repository_directory co asub - for checking out a subdirectory of the project
when checking out files with this method, the folder that is checked out to will be given the aliases name, and not the full original name of the folder
you can also define modules containing only certain some files in a particular directory:
readme myproj README.txt
no-readme myproj hello.c foo.jpg
When checkinjg out readme you will get only the readme file, and no-readme will give youu hello.c and foo.jpg, but no readme, even though all three files existed in the same folder in the repository
You can create an alias to refer to multiple modules with one name:
twoproj -a myproj yourproj
would cause cvs co twoproj to checkout myproj and yourproj and put them in their own respective directories. (not in a directory called twoproj)
Aliases don't have to refer to multiple projects
modules can refer to other modules (prefix module name with ampersand):
tp &twoproj
more information see “Modules” in Cederqvist
commitinfo and loginfo
generally follow the form:
REGULAR_EXPRESSION PROGRAM_TO_RUN
commitinfo is for generic programmatic hooks you want to run on every commit.
for example:
^a-subdir* /usr/local/bin/check-asubdir.sh
ou /usr/local/bin/validate-project.pl
commits can only match once, so rules should be placed in the order of priority, the fist match will eliminate all other matches possible in the file.
In place of a regular expression the word DEAFAULT or ALL can be used. The first DEFAULT line in the file will be run in the event of no matches, and all ALL lines will be run in addition to any other matches that occurred in the file.
The loginfo file works basically the same as commitinfo except that instead of acting on file's contents, it acts on the log message. The prgram run will be passed the log message on it's standard input. You can also pass it an arbitrary number of command line arguments.
one of the arguments can be a special “%” code for cvs to expand at runtime:
%s -----------> name(s) of the files being committed
%V -----------> revision number(s) before the commit
%v -----------> revision number(s) after the commit
expansion always begins with the path to the repository followed by the requested information
example output:
%s:
myproj foo bar baz
%V:
myproj 1.7 1.134 1.12
%v:
myproj 1.8 1.135 1.13
There can only be one % expression per line so if you want to include more than one include them in curly quotes (%{sV}) results will be the path to the repository followed by a comma seperated list of results.
for example:
%{sv} might become:
myproj foo,1.8 bar,1.135 baz,1.13
%{sVv} might be:
myproj foo,1.7,1.8 bar,1.134,1.135 baz,1.12,1.13
sample login file:
^myproj$ /usr/login/cvsrep/CVROOT/log.pl -m myproj-devel@foobar.com %s
ou /usr/local/bin/ou-notify.pl %{sv}
DEAFAULT /usr/local/bin/default-notify.pl %{sVv}
The first line invokes log.pl and gives it an e-mail address (to which it will send an e-mail containing the log message) followed by the repository and then all the files in the commit. (-f filename can be used to make a log file of commit log messages)
The next two lines call imaginary files and I'll skip explaining them.
verifymsg and rcsinfo
The verifymsg follows the regular expression - program format of the last section. The rcsinfo file has a regular expression on the left side while the right side points to a template file.
A template file should be a list of fields that a developer is supposed to fill out to create a valid log message. If developors commit with the -m option them the rcsinfo file isn't used. When a developer runs cvs commit however, the template is inserted in the text editor for the developer to fill out.
When the user commits, the appropriate program in verifymsg is invokes, presumably to check that the message follows the appropriate format. Success is indicated with a '0' status. I'm not sure if an -m commit will activate the verifymsg file, but the fact that the path to the template from the rcsinfo file is appended as the last argument to the program command line in verifymsg so that the program can base it's verification process on the template itself, gives me the feeling that it won't.
In the verifymsg file, the ALL keyword is not supported, but DEFAULT is.
taginfo
taginfo files follow the regular expression - program format, and do for tags what loginfo does for logs. Programs invoked by taginfo are handed argument in this order:
arg 1: tag name
arg 2: operation ("add" => tag, "mov" => tag -F, "del" => tag -d)
arg 3: repository
arg 4, 5, etc: file revision [file revision ...]
If the program, returns a nonzero result, the tag is aborted.
the -F option to tag is a way to move a tag from one revision to another.
for example, to move the tag "Known_Working" from revision 1.7 to revision 1.11:
cvs tag -r 1.11 -F Known_Working foo.c
cvswrappers
Is a way to specify that certain files should be treated as binary, based on their file name.
I think this is a very useful thing to know for web designers
here is a line to specify that .jpg files are all binary:
*.jpg -k 'b'
The 'b' is seperate and in quotes because it is not the only possibleRCS keyword expansion mode. One could also specify 'o' which means not to expand $ keywords but to do newline conversion. for more nodes see “Wrappers” in Cerqvist.
editinfo
obsolete
notify
will cover later
checkoutlist
This is for adding extra files, such as programs or rcsinfo templates into the CVSROOT directory, and have them treated as administrative files. (You can then check them in and out like other projects) When commiting new or modified administrative files you will get an extra line at the end of the commit that looks like this:
cvs commit: Rebuilding administrative file database
The format of the checkoutlist file is:
FILENAME ERROR_MESSAGE_IF_FILE_CANNOT_BE_CHECKED_OUT
for example:
log.pl unable to check out / update log.pl in CVSROOT
bugfix.tmpl unable to check out / update bugfix.tmpl in CVSROOT
the history file is not included in this system. It is used for the cvs history command. If you remove it cvs will stop keeping a log of all repository actions.
The passwd fiule is also not included in the check out list by default. It can be added if you don't think that it is a security risk.
If something goes badly enough wrong that commits can't take place at all, you will have to go in and hand edit the repository's working copy of the administrative file.
For security's sake, it is important to make sure that your CVSROOT directory is writable only by users you trust. People with access to these files can run programs on your machine.
Creating a Repository
cvs -d repository_directory init
NOTE: repository directory needs to exist before you can turn it into a repository (probably)
The CVSROOT directory inside a repository contains administrative files that control CVS' behavior.
For security reasons it is highly recommended that you set up a cvs group and add any users that will be accessing the repository.
To do this in Mac Os X, open netinfo, go to the groups folder, click on a group and duplicate it. Change the name of the copy, the group id, and set up the users to be included, then save it.
You will then need to setup you repository folders to those permissions.
cd repository_directory
chgrp -R cvs .
chmod ug+rwx . CVSROOT
when adding a new project or files or folders you should probably chgrp -R cvs folder them.
Tip o ' Tod [ BSD systems (including Mac OS X) automatically assign the parent directory's group to sub directories and files inside them. This means we don't need my comment above. For Linux systems we can avoid the chgrp step above by doing this in advance:
chmod g+s path/to/repository]
If you are planning to run a publicly accessible repository, you should set up a Password-Authenticating Server. Since I am not doing that now, I have skipped this section.
understanding RCS Files
in repositories all files show up as filename,r
This file shows the whole text of the most recent update, and then diffs for each revision before that. When you revert to an old version say from 1.7 to 1.5, CVS applies the patch for 1.6 to 1.7 and then the patch for 1.5 to what is now the same as 1.6 was.
Repository structure
Don't use directories named Attic in CVS projects because when files are removed from the project, they will be moved there, and their revision history will be updated to say that the status is “dead.”
Bedtime for now, and I don’t feel I covered that much ground. Next Episode: The CVSROOT Administrative directory - stay tuned
Resolving Conflicts
I forgot to mention it earlier. When you commit changes and there are conflicts, the conflicting files will now contain both sets of changes, and it is up to you to go in and edit to fix this problem.
branching
I'll give a set of commands and explain them:
cd .. //get out of current working directory
cvs -q checkout -d new_folder -r Release_Name Project_Name // gets a working copy at the specified Release in the folder specified
cd new_folder
cvs -q tag -b Branch_Name // create a branch at the state in the working directory with the given branch name
two ways to get a check out files in new branch:
cvs co -d desired folder -r branch_name project_name // of course you don't have to use the -d option on check out
--or--
cvs update -r Branch_Name // this will try to merge changes in current working directory, so if you have changes you don't want added it is best to use the checkout method
if the working copy you have is on a branch, you can commit normally, and it will go into the branch
you can get back to the current version as always with:
cvs -q update -A
merging changes from branch to trunk:
(from trunk working copy)
cvs -q diff -c -r branch_name //this shows differences in branch and current versions
cvs -q update -j branch_name // -j means join
Resolve any conflicts as you normally would by editing the files with conflicts in them.
Trying to re-merge after new changes will cause conflicts because it looks at differences between the root and tip of the branch and tries to merge all of those changes. some of them have already been merged, hence the conflict.
To avoid re-merge conflicts
cvs -q update -j "branch_name:date -j branch_name // the first -j gives join a start point, and keeps it from using the root of the branch.
If you tagged the point at which you merged last time, you could do the following:
cvs -q update -j last_merge_tag -j branch_name
for this reason it is good to tag at every merge with a descriptive name (including the branch name in the tag is a good idea)
branching without first checking out a working copy of the release to branch
cvs rtag -b -r Release_to_be_branched_at desired_branch_name project_name
For permanent command options
edit .cvsrc file in home directory
e.g.:
diff -c
update -P
cvs -q
the cvs -q part is a global option
getting snapshots
By Date
cvs -q update -D "2003-09-22"
this means the first moment of September 22nd, 2003, to get stuff up tp 1:00 that afternoon:
cvs -q update -D "2003-09-22 13:00:00 GMT"
don't forget the GMT!
updating with -D will give you a sticky date that your working directory will remember until you run with -A or a different -D
You cannot check in changes with a sticky date, but you can diff them:
cvs -q diff -c -r 1.5 index.php
Adding a tag
tag marks a certain point in time in the development process
cvs -q tag "Test_Release-2003_09_22"
tag must start with letter and consist of letters, digits, hyphens, and undescores ([a-z][A-Z][0-9]-_)
Checking out a separate working copy at a tag
move to a new directory (not in existing working copy or parent directory)
cvs -d (CVS_ROOT information) checkout -r release_name project_name
Comparing current state to tagged state:
cvs diff -c -r Release_Name file name
Revert temporarily to tag:
cvs update -r Release_Name [filename]
(cannot check in changes to a release unless it is a branch [branches discussed next time])
as before update with -A option or a different revision or date to lose or change sticky option
an example of what I did to make this happen:
first make sure that you know which revision you want, check it out temporarily and have a look at it. I wanted revision 1.20 of the file en/2004/exhibitors/f-inf_promotion.html
so first I ran cvs update with the -p parameter to write it to standard output
cvs up -p -r 1.20 en/2004/exhibitors/f-inf_promotion.html
This was how I wanted it the first time, because I have my .cvsrc file set up to always add the -q tag to my cvs commands. If you don't have this then you will see some cruft before the contents of your file. This is exactly why we ran the file this way first. (In actuality the extra cruft that not using -q produces is harmless and wouldn't actually go into your file, but I always feel safer making sure it isn't there)
(you would run it like this to fix it):
cvs -q up -p -r 1.20 en/2004/exhibitors/f-inf_promotion.html
after you have verified that what is being printed to your screen is exactly what you want as the contents of your file you will direct this output into the file itself:
cvs up -p -r 1.20 en/2004/exhibitors/f-inf_promotion.html > en/2004/exhibitors/f-inf_promotion.html
Now just check in, and you are back to the desired version of the file.
setting up connection type:
CVS_RSH=ssh; export CVS_RSH
setting up repository location: CVSROOT=:ext:user@hostname:/usr/local/cvsrep; export CVSROOT
One doesn't need to set up the CVSROOT except for use in import and checkout, so one can just as easily use the cvs -d option
This uses the following form:
cvs -d :ext:user@hostname:/usr/local/cvsrep command
to import a project:
change to project directory
cvs import -m "log msg" projname vendortag releasetag
vendor tag and release tag usually don't matter, use username and start
checking out a working copy:
cvs checkout projname
If you want to check it out into a directory different than the project name:
cvs co -d directory project
Contents of CVS directory:
Root = location of cvs repository
Repository = location of project repository
Entries = details of individual files in directory (filename/revision number/datestamp//)
other stuff (no time to be specific):
cvs -q update [filename] = get latest versions
cvs -Q diff -c [filename] = find the differences between versions
cvs commit -m "log message" [filename] OR cvs ci etc = commit changes to repository
cvs status [filename] = get the status of the local file in relation to repository
cvs log [filename] = get log of cvs activity
to undo change:
(slow unwieldy method)
cvs -Q update -p -r {version number to revert to} {filename} > filename
cvs update
cvs -Q diff -c
check for accuracy of change
cvs ci -m "revert message"
adding files to project:
cvs add filename
cvs ci -m "log msg" filename
adding directory to project:
mkdir dirname
cvs add dirname
removing files from project:
rm filename
cvs remove filename
cvs ci -m "removal message" filename
removing directory from project:
remove all files from directory
cvs remove removed files
cvs ci -m "remove massage" filename(s)
cd ..
cvs update -P (P prunes empty directories)
(plain update doesn't bring in new directories occasionally should run update -d
Renaming Files and Directories
File
mv oldname newname
cvs remove oldname
cvs add newname
cvs ci -m "rename msg" olfname newname
Directory
mkdir newdir
cvs add newdir
mv olddir/* newdir
mv: newdir/CVS: cannot overwrite directory
cd olddir
cvs rm filenames
cd ../newdir
cvs add filenames
cd ..
cvs commit -m "move message"
cvs update -P