path: root/usr.bin/cvs/cvsintro.7

.\"	$OpenBSD: cvsintro.7,v 1.13 2007/05/31 19:20:09 jmc Exp $
.\"
.\" Copyright (c) 2004 Jean-Francois Brousseau <jfb@openbsd.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
.\" EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLUDING, BUT NOT LIMITED TO,
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: May 31 2007 $
.Dt CVSINTRO 7
.Os
.Sh NAME
.Nm cvsintro
.Nd introduction to Concurrent Versioning System
.Sh DESCRIPTION
Concurrent Versions System is a popular open source version control system.
Although it is mostly used to track changes to software source code for
development teams, there are very few limitations to the kind of data that
can be managed by the system, and it can be used for document archival
purposes as well.
.Pp
This document provides an introduction to using OpenCVS to manage repositories.
It will first cover some of the aspects of using and managing CVS and,
where appropriate, explain the main differences between OpenCVS and other
distributions.
.Sh USING CVS TO TRACK SOURCE CHANGES
One of the most common uses of
.Xr cvs 1
is to track changes to a collection of source files (a
.Em module )
contained within a certain, defined, location (a
.Em repository ) .
This allows the user to keep a set of local sources in sync
with a set of remote sources.
It also allows the user to view information about changes to the repository
(such as what the exact change was, who made it, and when),
to view and compare information about different versions of a file,
and possibly to make local changes to files.
.Pp
As an example,
we'll look at a user wishing to track source changes to the
.Ox
tree,
maintaining a local (personal) copy of the source on their own machine.
The user will have to decide:
.Bl -bullet
.It
The CVS server to use.
There may be only one server or, for larger projects,
a number of mirror servers.
.It
Where the source module(s) will be kept on the local machine.
.El
.Pp
In our example, the
.Ox
project, there are a large number of servers to choose from.
It's generally better to use a server geographically closer to you
since this tends to be faster and less of a strain for the master server.
Utilities such as
.Xr ping 8
and
.Xr traceroute 8
can be used to decide which host will be best to use.
Secondly, the local repository has to be stored somewhere.
.Ox
uses
.Pa /usr/src
as the default location for its source tree
(the
.Dq src
module),
but this is largely arbitrary.
.Pp
This example shows how a user initially checks out a copy of the source tree
from local mirror anoncvs.nl.openbsd.org:
.Bd -literal -offset indent
$ cd /usr
$ cvs -d anoncvs@anoncvs.nl.openbsd.org:/cvs checkout -P src
.Ed
.Pp
In this case it was first necessary to add ourselves to the
.Dq wsrc
group, since
.Pa /usr/src
is writable only by user
.Dq root
and/or group
.Dq wsrc .
The
.Fl d
option was necessary to tell
.Xr cvs 1
the location of the remote server.
Note the
.Dq :/cvs
string appended to the server's address:
the path to the repository
.Em must
be specified.
Finally the
.Ic checkout
command was used to obtain a copy of the module
.Dq src .
.Pp
Note that the above example simply checked out
.Ox Ns -current :
often different software versions are available:
use an identifier
.Pq Em tag
to specify which version to check out.
.Pp
Thereafter the user is free to manipulate the source tree
using the
.Xr cvs 1
utility itself.
For example, the following would update (sync) the local copy of
.Dq src
with the remote copy:
.Bd -literal -offset indent
$ cd /usr/src
$ cvs -d anoncvs@anoncvs.nl.openbsd.org:/cvs update -Pd
.Ed
.Pp
General users may wish to use
.Xr cvs 1
simply to keep a copy of sources up to date with a development tree;
developers of software projects can also use
.Xr cvs 1
to make their own changes to a set of remote source files,
and to view changes made by other software developers.
.Pp
See
.Xr cvs 1
for more information on the different commands available.
See the entry for
.Pa $HOME/.cvsrc
in
.Xr cvs 5
for details on configuring
.Xr cvs 1
itself.
.Sh USING CVS TO MANAGE A REPOSITORY
Software developers may wish to use
.Xr cvs 1
to manage their own software projects.
Here we look at an example usage:
providing remote access to a small group of developers
working on project
.Dq foo ,
located in
.Pa /cvs/projects .
First of all a
.Em repository
has to be created.
A repository is just the location of the group of files
to be managed.
Within the repository,
files may be organised into collections of files,
called
.Em modules ,
which are just logical groupings of files.
.Pp
In our example, module
.Dq foo
is located at
.Pa /cvs/projects/foo
on machine
.Dq cvs.example.org .
Therefore
.Pa /cvs/projects
is both the root directory
.Pq Em $CVSROOT
of our repository and the name of our repository.
.Pp
If a set of source files already exist,
possibly already under revision control,
they can be added to a repository using the
.Xr cvs 1
command
.Ic import .
This is a useful way of adding modules to a pre-existing repository.
In our example we are starting from scratch,
so the repository has to be initialised using the
.Ic init
command:
.Bd -literal -offset indent
# cd /cvs/projects
# cvs -d /cvs/projects init
.Ed
.Pp
This will create a default administrative directory,
.Pa $CVSROOT/CVSROOT ,
filled with files concerned with the management of the repository.
.Pp
Thereafter, access will have to be arranged for
developers participating in the project.
This typically means providing SSH access via
.Xr sshd 8
for remote access,
unless the development network is local.
.Sh SEE ALSO
.Xr cvs 1 ,
.Xr rcs 1 ,
.Xr cvs 5 ,
.Xr sshd 8
.Sh HISTORY
The OpenCVS project is a BSD-licensed rewrite of the original
Concurrent Versioning System written by Jean-Francois Brousseau.
The original CVS code was written in large parts by Dick Grune,
Brian Berliner, and Jeff Polk.
.Sh AUTHORS
.An Jean-Francois Brousseau
.Sh CAVEATS
This CVS implementation does not fully conform to the GNU CVS version.
In some cases, this was done explicitly because GNU CVS has inconsistencies
or ambiguous behaviour.
Some things have also been left out or modified to enhance the overall
security of the system.
.Pp
Among other things, support for the pserver connection mechanism has been
dropped because of security issues with the authentication mechanism.