<chapter id="cvs">
<title>Using &CVS;</title>
<indexterm zone="cvs"><primary>CVS</primary></indexterm>
<indexterm zone="cvs"><primary>revision control</primary></indexterm>

<sect1 id="cvs-basics">
<title>&CVS; Basics</title>

<para>
&CVS; is the revision control system which many open source projects -
including &kde; &mdash; are using. It stores all sources codes in a central place,
called the <emphasis>repository</emphasis>.  From the repository, developers
can check out a current version of the project or snapshots of it at arbitrary
points of time. In contrast to some other revision control systems, it is not
necessary to <emphasis>lock</emphasis> files one wants to work on. So
development can be highly parallelized.
</para>

<para>
Whenever a developer has finished a task, he <emphasis>commits</emphasis> his
code (accompanied by a log message). &CVS; takes the job to merge the changes
made by several developers. It can of course happen that developers work on
the same piece of code, resulting in a conflicting set of changes (in practice
this occurs seldom, and is often a sign of a lack of communication). In this
case &CVS; rejects a commit; only after all conflicts are resolved, a file can
be committed.
</para>

<para>
So far, this has been a description of the basic features of &CVS; one usually
has to cope with. But &CVS; can provide a lot more: One can  maintain several
branches of a project (&eg; &kde; 1.1.2 and &kde; 2 were branches in &kde;'s
development tree), merge changes from one branch to another, ask for
differences between revisions, the revision history of files &etc;
</para>

<para>
&CVS; is implemented as a client-server system. As a user, all communication
with the repository goes through the command line program &cvs;. A higher
level user interface is available through frontends like &cervisia; (<ulink
url="http://cervisia.sf.net"/>) or <application>TkCVS</application> (<ulink
url="http://tkcvs.sf.net"/>).  In &kdevelop;, only a small part of the &cvs;
functionality which is important for your daily work can be used directly.
</para>

<para>
Basic knowledge of &CVS; usage is assumed. In particular, you should know
how to checkout a given project from the repository. We recommend the
book <quote>Open Source Development With &CVS;</quote> by Karl Fogel which is freely
distributed (except for the non-technical chapters). See
<ulink url="http://cvsbook.red-bean.com/cvsbook.html"/>.
</para>

</sect1> <!-- cvs-basics -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="cvs-commands">
<title>&CVS; Commands in &kdevelop;</title>

<para>
In the file views, the following context menu items are available:
</para>

<variablelist>
<varlistentry>
<term>Add to Repository</term>
<listitem>
<para>Prepares the marked file for addition to the repository. The file
is transferred to the repository when you commit it (or the containing
directory) the next time.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Remove from Repository</term>
<listitem>
<para>
Prepares a file for removal from the repository. This also deletes
the file on the local file system, so use this feature with care!
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Update</term>
<listitem>
<para>
Runs <command>cvs update</command> to merge any changes from other
users into your working directory. When you use this menu item over
a directory, the update normally happens recursively, except if you
have disabled this in the configuration file <filename>.cvsrc</filename>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Commit</term>
<listitem>
<para>
Runs <command>cvs commit</command> to upload any locally made changes
to the repository. Note that you should update before doing this.
Otherwise, when another user has committed his own changes before,
&CVS; may give you an error message.
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
All these commands are invoked as subprocesses by &kdevelop; without any
further command line options or environment variables. This may be a
problem when the connection with the &CVS; server goes through a
&ssh; connection and requires that you enter your password each time
you commit or update. This is for instance necessary when your project is
hosted on <filename>sourceforge.net</filename>. Workarounds for this
problem are described on the &CVS;/SSH FAQ which you can find in the
SourceForge documentation.
</para>

</sect1> <!-- cvs-basics -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id="cvs-behind">
<title>Behind the Scenes</title>

<sect2 id="cvs-behind-workdir">
<title>What &CVS; Records in the Working Directory</title>

<para>
(... to be written ...)
</para>
</sect2> <!-- cvs-behind-workdir -->

</sect1> <!-- cvs-behind -->

</chapter> <!-- cvs -->