perlmeditation
trs80
<p><b>Intro</b> </p>
<blockquote>The intent of this article/node is to give a short (semi-accurate)
overview of the steps it takes to "start" using [0]CVS on your local machine.
This is not intended to be an advanced usage, "The Only Way", or even "The
Right Way" to use CVS, but instead hopes to get those that might otherwise
pass it up to see that its isn't hard to keep things "under control".
It is based on the perspective that you have already created some directories/files
and you are wanting to use those as the basis of your project (CVS repository).
I
hope that others that have been using CVS longer and for more robust projects
will share their comments. All feedback is welcome.</blockquote>
<p> </p>
<p><b>Intended Audience</b> </p>
<blockquote>
<p>Developers that have not yet taken the plunge to install and use CVS
for their projects. </p>
</blockquote>
<p></p>
<b>Why use [1]Revision Control? </b>
<blockquote>
<p></p>
<p>Well... because you should. Just like you should brush your teeth.
There are lots of reasons to or not to, but just like brushing your teeth
you will likely suffer less and spend less time in painful situations if
you use a revision control system.
</blockquote>
<p></p>
<b>Why CVS?</b>
<blockquote>
<p>
I am focusing on CVS in this guide because
it is currently the most widely installed and used revision control system
in the GNU world and is freely available.</p>
</blockquote>
<p> </p>
<readmore>
<p><b>The Beginners CVS Guide (for Perl Developers)</b> </p>
<p></p>
<blockquote>
<p>Most books on good software development stress the importance of revision
of control for keeping track of what you did, when you did it, and if you
are on a team, who did it. </p>
<p>Like a good Perl programmer I am extremely lazy and have avoided putting
anything in version control for years. Now I realize that it isn't lazy
its almost suicidal not to. I have been able to keep track of what I did
and when I did it fairly good in my head....or so I thought (ugly details
removed). So begins my journey into CVS for Perl source control. </p>
<p>Now that I have moved to Linux
full time I am slowly applying and enjoying all the benefits that it brings.
CVS is supported under OSes other then Unix, but when I last went to try
it, it still suggested the server portion not be run on some platforms so
I had used that as another excuse to avoid it. CVS was included on the ISO
image I downloaded so it was as simple as installing the [2]RPM to get the
binaries installed. I will leave the build/install process to the [3]documentation
supplied with CVS if you don't/can't like/use RPMs. </p>
<p>I got ready to start and thought I would read the [3]documentation first
for a change. I did and that didn't seem to help; they make more sense after
you know what they are talking about however :) I looked up a couple of tutorial
sites on the internet, even found one angled toward Perl users, which is what
I used to get started, but still didn't go as far as I would have liked.
</p>
</blockquote>
<p><b>Clean up your act!</b> </p>
<blockquote> In my perpectual laziness the first time around I didn't clean
out all the junk files. Not that files can't be removed from CVS, but why
add them in the first place if you know they are junk.<br>
So clear out all the old .bak and test_junk.pl
that aren't productive/useful before you even think about moving on to the
next step. </blockquote>
<p> </p>
<p><b>Making a CVSROOT (aka Repository)</b> </p>
<blockquote>
<p>On NT/2000/XP you will need to add CVSROOT to your environment variables. I am not going
to go into details on NT in this tutorial since I don't have access to a windows machine
to confirm the steps. (win9x ???) </p>
<p>On a Unix based machine the preferred way to add CVSROOT to your environment
is to make an entry in your profile. This various from shell to shell, for
me and my bash shell I made this entry in the $HOME/.bash_profile file.
</p>
<br>
<code>CVSROOT=/home/trs80/cvsroot</code><br>
<code>export CVSROOT</code> </p>
<p>The CVSROOT is where the repositories will live. The repository is
really ugly and there is generally no reason for you to look at it directly,
consider yourself warned. </p>
<p>Now run this command (read below for important path information): <br>
<code> cvs -d $CVSROOT init </code></p>
<p>It should return you to the command prompt with no messages if you did everything right.
</p>
<p>Now if you have used or want to use a completely new tree you have to
create all the directories up but not including the last one. So if you
wanted to have a repository live in:<br>
<code> /cvs_stuff/myreally/cool/directory/cvsroot </code> </p>
<p>You could have to issue something like:<br>
<code> mkdir -p /cvs_stuff/myreally/cool/directory</code><code> </code>
</p>
<p>You COULD include the /cvsroot, but if you don't the cvs command will
add it for you.</p>
</blockquote>
<p> </p>
<p><b>Adding your killer app to the repository (CVSROOT)</b> </p><blockquote>
<p>In the CVS docs at the CVS site there is a nice little getting started
section that attempts to help you set things up, but if you tend to not
read all the information leading up to a point (like me) and skip right to
the topic of interest they gloss over some important details on how to get your
present files into the repository, which is in part of what prompted me to write
this. </p>
<p>We will deal with 2 main directories, the CVSROOT and the Working Directory.
For this example the CVSROOT will be as shown above:<br>
<code>/home/trs80/cvsroot</code><br>
and the Working Directory will be:<br>
<code> /home/trs80/working_directory</code> </p>
<p>(in the CVS docs they call it rdir (repository directory) and wdir (working
directory) I preferred it spelled out for my simple mind :) </p>
<p>So with those "facts" established let say you have a masterpiece of
Perl code in some obscure corner of your machine such as:<br>
<code>/var/www/html/cgi-bin/masterpiece</code> </p>
<p>We want to move that into CVS so we can keep better tabs on it and make
it available to others as the need should arise. There a minimum of three
variables now that are important to creating the repository, but once it is
created only one of them is important. </p>
<p>Repository_Name - this one remains important since it is what will be
"checkout"ed of CVS. The repository name is completely at your discretion,
no magic* is performed on it based on path or environment variables. It
does however allow you to specify the path under the CVSROOT. If you say
"<code>YourName/KillerApp</code>" as the Repository_Name then it will always
need to be "checkout"ed (see below) with the full sub path
(<code>YourName/KillerApp</code>). I say this because the
first time I created a repository I thought there WAS magic and stopped
one directory short of the files I wanted and got 10 directories and a load
of files that had nothing to do with what I wanted in CVS, so yes there really
are people out there that stupid :) </p>
<p>Vendortag - I honestly don't know enough to explain when this is useful
so for the purpose of this discussion simply set it to your personal ID
or "code name" (for me trs80). </p>
<p>Releasetag - This is the version tag in a way, but is string not numerical
nature so if you are working on Masterpiece-01 you could use that as the releasetag.
In the CVS docs the initial import is done with a 'start' string for the
releasetag value. That is most likely a safe way to begin using CVS and
as your knowledge/needs grow you will be able to better decide how to name
it. </p>
<ol>
<li><code>cd /var/www/html/cgi-bin/masterpiece</code> </li>
<li><code>cvs import -m "Import of Killer App" Repository_Name Vendortag
Releasetag</code><br>
(aka <code>cvs import -m "Import of Killer App" KillerApp trs80 start</code>)<br>
You should see a list of the files as they are added to the repository
with a letter in front of each one indicating the success code of the addition.
If it is a fresh directory it is unlikely you will see any thing "odd" unless
you have files of "unknown" content that CVS is not capable of checking revisions
on. </li>
</ol>
<p>The files in the directory you are currently in will NOT be effected,
the 'cvs import' command will simply copy each file and log it into the repository.
That being said, aways backup before doing anything "new". </p>
<p><br>
The -m is a common option on the cvs sub commands that allow you to enter
comments for the "Change Log". If you omit the <code>-m</code> cvs will open
the editor (as assigned by your environment as the default) to allow you to
enter comments as well so you can't say nobody reminded you to comment on
what the heck you were doing at 3:00AM.</p>
</blockquote>
<p> </p>
<p><b>"Checkout" the files into your working directory</b> </p>
<blockquote>
<p>Once the files are in the repository you will need to check them out of
CVS into your working directory so you are sure you are working on the right
code and "Its the Right Thing to Do"TM </p>
<p>Checking out is done by issuing the following commands: </p>
<p><code>cd /home/trs80/working_directory</code><br>
<code>cvs checkout Repository_Name</code><br>
(aka <code>cvs checkout KillerApp</code>) </p>
<p>That should have given you a list of all the files and directories brought
out of the repository. </p>
</blockquote>
<p><b>"Commit" a file</b> </p>
<blockquote>
<p>Go ahead and make a change to one of the files so we can "commit" a changed
file. </p>
<p>Once you have edited one run this command:<br>
<code>cvs commit <filename></code>
</p>
<p>If you use the above command you will be presented with an editor asking
you to make a comment for the change log. You can avoid the editor by using:<br>
<code>cvs commit -m "Change Log Message" <filename></code> </p>
</blockquote>
<p><b>Final Thoughts</b></p>
<blockquote>
<p><br>
That covers the very basics of CVS. There are about 1,784 other things you
MAY need to know about CVS, but at this point you can create a repository,
add files to the repository, check them out, and commit changes. When working
in a group environment CVS brings forth some powerful tools to allow for
more then one person to work on a file at a time and not lose any changes
or at least minimize the number of them, depending on how well separated
your efforts are. </p>
<p>I have only found one good standalone GUI tool so far in my quest for
handy tools and that is the [4]TkCVS application. It works well and gives
good access to most of the commands via icons (commit, checkout, branch,
etc.) and lesser used commands via the tool bar. </p>
<p>There is a [5]pcl-cvs project for Emacs that I looked at and appears to
offer everything (just like Emacs), but since I don't use [6]Emacs I can't
comment on its usability. </p>
<p>[7]CodeForge offers CVS integration with its editor and supports CVS.
<br>
<br>
There is an up and coming Revision Control system that is designed to replace
CVS called [8]Subversion, which is due to be at beta stage in Q4 2002.
</blockquote>
</p>
<p> </p>
<b>Links</b><br>
<br>
[0] [http://www.cvshome.org] - CVS home page<br>
[1] [http://www.google.com/search?hl=en&ie=UTF-8&oe=UTF-8&q=revision+control]<br>
- Revision control links on Google<br>
[2] [http://www.rpmfind.net/linux/rpm2html/search.php?query=CVS]<br>
- Query at rpmfind.net for CVS rpms<br>
[3] [http://www.cvshome.org/docs/manual/cvs.html] (CVS Manual)<br>
[4] [http://www.twobarleycorns.net/tkcvs.html] (TkCVS project)<br>
[5] [http://www.cs.utah.edu/dept/old/texinfo/cvs/pcl-cvs_toc.html] (pcl-cvs
for Emacs - comes with some distros of Linux)<br>
[6] [http://www.gnu.org/software/emacs/emacs.html] (Emacs)<br>
[7] [http://www.codeforge.com] (CodeForge)<br>
[8] [http://subversion.tigris.org/] (SubVersion)
<br>
* well if you consider it using the environment variable
CVSROOT to know where to put the files, then I guess there is some magic
<br>
<br>
<b>Updates</b>: Minor verbiage and grammatical errors were corrected (thanks [duelafn],[premchai21] ) and the Links were turned into real links at the urging of [podmaster]