1
<?xml version="1.0" encoding="UTF-8"?>
2
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
3
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
4
<!ENTITY % globalent SYSTEM "../../libs/global.ent">
6
<!ENTITY % gnome-menus-C SYSTEM "../../libs/gnome-menus-C.ent">
8
<!ENTITY % xinclude SYSTEM "../../libs/xinclude.mod">
10
<!ENTITY language "&EnglishAmerican;">
12
<chapter id="version-control-system" status="review">
13
<title>Version Control System</title>
15
Version control is the art of managing changes to information. It has long been a critical tool for programmers, who typically spend their time making small changes to software and then undoing those changes the next day. But the usefulness of version control software extends far beyond the bounds of the software development world. Anywhere you can find people using computers to manage information that changes often, there is room for version control.</para>
16
<sect1 id="bazaar" status="review">
19
Bazaar is a new version control system sponsored by Canonical, the
20
commercial company behind Ubuntu. Unlike Subversion and CVS that
21
only support a central repository model, Bazaar also supports
22
<emphasis>distributed version control</emphasis>, giving people
23
the ability to collaborate more efficiently. In particular,
24
Bazaar is designed to maximize the level of community participation
25
in open source projects.
27
<sect2 id="bzr-installation" status="review">
28
<title>Installation</title>
30
At a terminal prompt, enter the following command to install
31
<application>bzr</application>:
34
<command>sudo apt-get install bzr</command>
38
<sect2 id="bzr-configuration" status="review">
39
<title>Configuration</title>
41
To introduce yourself to <application>bzr</application>,
42
use the <emphasis>whoami</emphasis> command like this:
44
<command>$ bzr whoami 'Joe Doe <joe.doe@gmail.com>'</command>
48
<sect2 id="bzr-learning" status="review">
49
<title>Learning Bazaar</title>
51
Bazaar comes with bundled documentation installed into
52
<application>/usr/share/doc/bzr/html</application> by default.
53
The tutorial is a good place to start. The
54
<application>bzr</application> command also comes with
57
<command>$ bzr help</command>
61
To learn more about the <emphasis>foo</emphasis> command:
63
<command>$ bzr help foo</command>
67
<sect2 id="bzr-lp-integration" status="review">
68
<title>Launchpad Integration</title>
70
While highly useful as a stand-alone system, Bazaar has good, optional
71
integration with <ulink url="https://launchpad.net/">Launchpad</ulink>,
72
the collaborative development system used by Canonical and the
73
broader open source community to manage and extend Ubuntu itself.
74
For information on how Bazaar can be used with Launchpad to
75
collaborate on open source projects, see
76
<ulink url="http://bazaar-vcs.org/LaunchpadIntegration/">
77
http://bazaar-vcs.org/LaunchpadIntegration</ulink>.</para>
80
<sect1 id="subversion" status="review">
81
<title>Subversion</title>
83
Subversion is an open source version control system. Using Subversion, you can record the history of source files and documents. It manages files and directories over time. A tree of files is placed into a central repository. The repository is much like an ordinary file server, except that it remembers every change ever made to files and directories.
85
<sect2 id="subversion-installation" status="review">
86
<title>Installation</title>
88
To access Subversion repository using the HTTP protocol, you must install and
89
configure a web server. Apache2 is proven to work with Subversion. Please
90
refer to the HTTP subsection in the Apache2 section to install and configure
91
Apache2. To access the Subversion repository using the HTTPS protocol, you
92
must install and configure a digital certificate in your Apache 2 web server.
93
Please refer to the HTTPS subsection in the Apache2 section to install and
94
configure the digital certificate.
97
To install Subversion, run the following command from a terminal prompt:
101
<command>sudo apt-get install subversion libapache2-svn</command>
106
<sect2 id="subversion-configuration" status="review">
107
<title>Server Configuration</title>
109
This step assumes you have installed above mentioned packages on your system. This section explains how to create a Subversion repository and access the project.</para>
110
<sect3 id="create-svn-repos" status="review">
111
<title>Create Subversion Repository</title>
112
<para>The Subversion repository can be created using the following command from a terminal prompt:</para>
116
<command>svnadmin create /path/to/repos/project</command>
120
<sect3 id="import-svn-files" status="review">
121
<title>Importing Files</title>
123
Once you create the repository you can
124
<emphasis>import</emphasis> files into the
125
repository. To import a directory, enter the
126
following from a terminal prompt:
128
<command>svn import /path/to/import/directory file:///path/to/repos/project</command>
133
<sect2 id="access-methods" status="review">
134
<title>Access Methods</title>
135
<para>Subversion repositories can be accessed (checked out) through many
136
different methods --on local disk, or through various network protocols.
137
A repository location, however, is always a URL. The table describes how
138
different URL schemes map to the available access methods.</para>
139
<table><title>Access Methods</title>
142
<colspec colname="1"/>
143
<colspec colname="2"/>
146
<entry><para>Schema</para></entry>
147
<entry><para>Access Method</para></entry>
152
<entry><para>file://</para></entry>
153
<entry><para>direct repository access (on local disk)</para></entry>
156
<entry><para>http://</para></entry>
157
<entry><para>Access via WebDAV protocol to Subversion-aware Apache2 web server</para></entry>
160
<entry><para>https://</para></entry>
161
<entry><para>Same as http://, but with SSL encryption</para></entry>
164
<entry><para>svn://</para></entry>
165
<entry><para>Access via custom protocol to an svnserve server</para></entry>
168
<entry><para>svn+ssh://</para></entry>
169
<entry><para>Same as svn://, but through an SSH tunnel</para></entry>
176
In this section, we will see how to configure Subversion for all
177
these access methods. Here, we cover the basics. For more advanced
178
usage details, refer to the <ulink
179
url="http://svnbook.red-bean.com/">svn book</ulink>.
181
<sect3 id="direct-repos-access" status="review">
182
<title>Direct repository access (file://)</title>
183
<para> This is the simplest of all access methods. It does not
184
require any Subversion server process to be running. This access
185
method is used to access Subversion from the same machine. The
186
syntax of the command, entered at a terminal prompt, is as follows:</para>
190
<command>svn co file:///path/to/repos/project</command>
196
<command>svn co file://localhost/path/to/repos/project</command>
200
<para>If you do not specify the hostname, there are three forward slashes (///) -- two for the protocol (file, in this case) plus the leading slash in the path. If you specify the hostname, you must use two forward slashes (//).</para>
202
<para>The repository permissions depend on filesystem permissions. If the user has read/write permission, he can checkout from and commit to the repository.</para>
204
<sect3 id="access-via-webdav" status="review">
205
<title>Access via WebDAV protocol (http://)</title>
207
To access the Subversion repository via WebDAV protocol, you must configure your Apache 2 web server. Add the following snippet between the
208
<emphasis><VirtualHost></emphasis> and <emphasis></VirtualHost></emphasis> elements in
209
<filename>/etc/apache2/sites-available/default</filename>, or another VirtualHost file:
213
<Location /svn>
217
AuthName "Your repository name"
218
AuthUserFile /etc/subversion/passwd
223
<para>The above configuration snippet assumes that Subversion
224
repositories are created under <filename>/home/svn/</filename>
225
directory using <command>svnadmin</command> command. They can be
226
accessible using <command>http://hostname/svn/repos_name</command>
230
To import or commit files to your Subversion repository over
231
HTTP, the repository should be owned by the HTTP user. In
232
Ubuntu systems, normally the HTTP user is
233
<command>www-data</command>. To change the ownership of the
234
repository files enter the following command from terminal
238
<command>sudo chown -R www-data:www-data /path/to/repos</command>
242
By changing the ownership of repository as
243
<command>www-data</command> you will not be able to import or
244
commit files into the repository by running <command>svn import
245
file:///</command> command as any user other than
246
<command>www-data</command>.
251
Next, you must create the <filename>/etc/subversion/passwd</filename> file that will contain user authentication details.
252
To create a file issue the following command at a command prompt (which will create the file and add the first user):
256
<command>sudo htpasswd -c /etc/subversion/passwd user_name</command>
260
To add additional users omit the <emphasis>"-c"</emphasis> option as this option replaces the old file. Instead use this form:
264
<command>sudo htpasswd /etc/subversion/passwd user_name</command>
268
<para>This command will prompt you to enter the password. Once you enter the password, the user is added. Now, to access the repository you can run the following command:</para>
269
<screen><command>svn co http://servername/svn</command></screen>
272
The password is transmitted as plain text. If you are worried about password snooping, you are advised to use SSL encryption. For details, please refer next section.
276
<sect3 id="access-via-webdav-with-ssl" status="review">
277
<title>Access via WebDAV protocol with SSL encryption (https://)</title>
279
Accessing Subversion repository via WebDAV protocol with SSL
280
encryption (https://) is similar to http:// except that you
281
must install and configure the digital certificate in your
282
Apache2 web server. To use SSL with Subversion add the above
283
Apache2 configuration to <filename>/etc/apache2/sites-available/default-ssl</filename>.
284
For more information on setting up Apache2 with SSL see <xref linkend="https-configuration"/>.
288
You can install a digital certificate issued by a signing
289
authority. Alternatively, you can install your
290
own self-signed certificate.
293
This step assumes you have installed and configured a digital
294
certificate in your Apache 2 web server. Now, to access the
295
Subversion repository, please refer to the above section!
296
The access methods are exactly the same, except the protocol.
297
You must use https:// to access the Subversion repository.
301
<sect3 id="access-via-custom-protocol" status="review">
302
<title>Access via custom protocol (svn://)</title>
304
Once the Subversion repository is created, you can configure the
305
access control. You can edit the <filename>
306
/path/to/repos/project/conf/svnserve.conf</filename> file to
307
configure the access control. For example, to set up
308
authentication, you can uncomment the following lines in the
309
configuration file: </para>
310
<programlisting># [general]
311
# password-db = passwd</programlisting>
314
After uncommenting the above lines, you can maintain the user
315
list in the passwd file. So, edit the file <filename>passwd
316
</filename> in the same directory and add the new user. The
317
syntax is as follows:
319
<programlisting>username = password</programlisting>
321
For more details, please refer to the file.
325
Now, to access Subversion via the svn:// custom protocol, either
326
from the same machine or a different machine, you can run
327
svnserver using svnserve command. The syntax is as follows:
329
<programlisting>$ svnserve -d --foreground -r /path/to/repos
331
# --foreground -- run in foreground (useful for debugging)
332
# -r -- root of directory to serve
334
For more usage details, please refer to:
335
$ svnserve --help</programlisting>
337
<para>Once you run this command, Subversion starts listening on default port (3690). To access the project repository, you must run the following command from a terminal prompt: </para>
340
<command>svn co svn://hostname/project project --username user_name</command>
343
<para>Based on server configuration, it prompts for password. Once
344
you are authenticated, it checks out the code from Subversion
345
repository. To synchronize the project repository with the local
346
copy, you can run the <command>update</command> sub-command. The
347
syntax of the command, entered at a terminal prompt, is as follows:
351
<command>cd project_dir ; svn update</command>
354
<para>For more details about using each Subversion sub-command, you
355
can refer to the manual. For example, to learn more about the co
356
(checkout) command, please run the following command from a
357
terminal prompt:</para>
358
<para><screen><command>svn co help</command></screen></para>
361
<sect3 id="access-via-custom-protocol-with-ssl" status="review">
362
<title>Access via custom protocol with SSL encryption (svn+ssh://)</title>
363
<para> The configuration and server process is same as in the
364
svn:// method. For details, please refer to the above section.
365
This step assumes you have followed the above step and started
366
the Subversion server using <application>svnserve</application>
369
<para>It is also assumed that the ssh server is running on that
370
machine and that it is allowing incoming connections. To confirm,
371
please try to login to that machine using ssh. If you can login,
372
everything is perfect. If you cannot login, please address it
373
before continuing further.</para>
375
<para>The svn+ssh:// protocol is used to access the Subversion
376
repository using SSL encryption. The data transfer is encrypted
377
using this method. To access the project repository (for example
378
with a checkout), you must use the following command syntax:
382
<command>svn co svn+ssh://hostname/var/svn/repos/project</command>
386
<note><para> You must use the full path (/path/to/repos/project)
387
to access the Subversion repository using this access method.
390
Based on server configuration, it prompts for password. You must
391
enter the password you use to login via ssh. Once you are
392
authenticated, it checks out the code from the Subversion
398
<sect1 id="cvs-server" status="review">
399
<title>CVS Server</title>
401
CVS is a version control system. You can use it to record the
402
history of source files.
404
<sect2 id="cvs-installation" status="review">
405
<title>Installation</title>
407
To install <application>CVS</application>, run the following command from a terminal prompt:
409
<command>sudo apt-get install cvs</command>
412
After you install <application>cvs</application>, you should install
413
<application>xinetd</application> to start/stop the cvs server. At the
414
prompt, enter the following command to install
415
<application>xinetd</application>:
418
<command>sudo apt-get install xinetd</command>
422
<sect2 id="cvs-configuration" status="review">
423
<title>Configuration</title>
425
Once you install cvs, the repository will be automatically
426
initialized. By default, the repository resides under the
427
<application>/srv/cvs</application> directory. You can
428
change this path by running following command:
431
<command>cvs -d /your/new/cvs/repo init</command>
434
Once the initial repository is set up, you can configure
435
<application>xinetd</application> to start the CVS server.
436
You can copy the following lines to the <filename>
437
/etc/xinetd.d/cvspserver</filename> file.
448
server = /usr/bin/cvs
449
server_args = -f --allow-root /srv/cvs pserver
456
Be sure to edit the repository if you have changed the default
457
repository (<application>/srv/cvs</application>) directory.
461
Once you have configured <application>xinetd</application> you
462
can start the cvs server by running following command:
465
<command>sudo /etc/init.d/xinetd restart</command>
469
You can confirm that the CVS server is running by issuing
470
the following command:
475
<command>sudo netstat -tap | grep cvs</command>
480
When you run this command, you should see the following line
481
or something similar:
485
tcp 0 0 *:cvspserver *:* LISTEN
489
From here you can continue to add users, add new projects,
490
and manage the CVS server.
494
CVS allows the user to add users independently of the
495
underlying OS installation. Probably the easiest way is to use the Linux
496
Users for CVS, although it has potential security issues. Please refer
497
to the CVS manual for details.
502
<sect2 id="cvs-add-projects" status="review">
503
<title>Add Projects</title>
505
This section explains how to add new project to the CVS
506
repository. Create the directory and add necessary document
507
and source files to the directory. Now, run the following
508
command to add this project to CVS repository:
510
<command>cd your/project</command>
511
<command>cvs -d :pserver:username@hostname.com:/srv/cvs import -m "Importing my project to CVS repository" . new_project start</command>
516
You can use the CVSROOT environment variable to store the CVS root directory.
517
Once you export the CVSROOT environment variable, you can avoid using -d option in the
521
The string <emphasis>new_project</emphasis> is a vendor
522
tag, and <emphasis>start</emphasis> is a release tag.
523
They serve no purpose in this context, but since CVS requires them, they
528
When you add a new project, the CVS user you use must have write access to the
529
CVS repository (<application>/srv/cvs</application>). By default, the
530
<application>src</application> group has write access to the CVS
531
repository. So, you can add the user to this group, and he can then add and
532
manage projects in the CVS repository.
538
<sect1 id="version-control-ref" status="review">
539
<title>References</title>
540
<para><ulink url="http://bazaar-vcs.org/">Bazaar Home Page</ulink></para>
541
<para><ulink url="https://launchpad.net/">Launchpad</ulink></para>
542
<para><ulink url="http://subversion.tigris.org/">Subversion Home Page</ulink></para>
543
<para><ulink url="http://svnbook.red-bean.com/">Subversion Book</ulink></para>
545
url="http://ximbiot.com/cvs/manual/cvs-1.11.21/cvs_toc.html">CVS Manual</ulink></para>
546
<para><ulink url="https://help.ubuntu.com/community/EasyBazaar">Easy Bazaar Ubuntu Wiki page</ulink></para>
547
<para><ulink url="https://help.ubuntu.com/community/Subversion">Ubuntu Wiki Subversion page</ulink></para>