1.\" $OpenBSD: cvsintro.7,v 1.14 2008/02/26 21:48:30 deraadt Exp $ 2.\" 3.\" Copyright (c) 2004 Jean-Francois Brousseau <jfb@openbsd.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. The name of the author may not be used to endorse or promote products 13.\" derived from this software without specific prior written permission. 14.\" 15.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 16.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 17.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 18.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 19.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 20.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 21.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 22.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 23.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 24.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd $Mdocdate: February 26 2008 $ 27.Dt CVSINTRO 7 28.Os 29.Sh NAME 30.Nm cvsintro 31.Nd introduction to Concurrent Versioning System 32.Sh DESCRIPTION 33Concurrent Versions System is a popular open source version control system. 34Although it is mostly used to track changes to software source code for 35development teams, there are very few limitations to the kind of data that 36can be managed by the system, and it can be used for document archival 37purposes as well. 38.Pp 39This document provides an introduction to using OpenCVS to manage repositories. 40It will first cover some of the aspects of using and managing CVS and, 41where appropriate, explain the main differences between OpenCVS and other 42distributions. 43.Sh USING CVS TO TRACK SOURCE CHANGES 44One of the most common uses of 45.Xr cvs 1 46is to track changes to a collection of source files (a 47.Em module ) 48contained within a certain, defined, location (a 49.Em repository ) . 50This allows the user to keep a set of local sources in sync 51with a set of remote sources. 52It also allows the user to view information about changes to the repository 53(such as what the exact change was, who made it, and when), 54to view and compare information about different versions of a file, 55and possibly to make local changes to files. 56.Pp 57As an example, 58we'll look at a user wishing to track source changes to the 59.Ox 60tree, 61maintaining a local (personal) copy of the source on their own machine. 62The user will have to decide: 63.Bl -bullet 64.It 65The CVS server to use. 66There may be only one server or, for larger projects, 67a number of mirror servers. 68.It 69Where the source module(s) will be kept on the local machine. 70.El 71.Pp 72In our example, the 73.Ox 74project, there are a large number of servers to choose from. 75It's generally better to use a server that is geographically closer 76since this tends to be faster and less of a strain for the master server. 77Utilities such as 78.Xr ping 8 79and 80.Xr traceroute 8 81can be used to decide which host will be best to use. 82Secondly, the local repository has to be stored somewhere. 83.Ox 84uses 85.Pa /usr/src 86as the default location for its source tree 87(the 88.Dq src 89module), 90but this is largely arbitrary. 91.Pp 92This example shows how a user initially checks out a copy of the source tree 93from local mirror anoncvs.nl.openbsd.org: 94.Bd -literal -offset indent 95$ cd /usr 96$ cvs -d anoncvs@anoncvs.nl.openbsd.org:/cvs checkout -P src 97.Ed 98.Pp 99In this case it was first necessary to add ourselves to the 100.Dq wsrc 101group, since 102.Pa /usr/src 103is writable only by user 104.Dq root 105and/or group 106.Dq wsrc . 107The 108.Fl d 109option was necessary to tell 110.Xr cvs 1 111the location of the remote server. 112Note the 113.Dq :/cvs 114string appended to the server's address: 115the path to the repository 116.Em must 117be specified. 118Finally the 119.Ic checkout 120command was used to obtain a copy of the module 121.Dq src . 122.Pp 123Note that the above example simply checked out 124.Ox Ns -current : 125often different software versions are available: 126use an identifier 127.Pq Em tag 128to specify which version to check out. 129.Pp 130Thereafter the user is free to manipulate the source tree 131using the 132.Xr cvs 1 133utility itself. 134For example, the following would update (sync) the local copy of 135.Dq src 136with the remote copy: 137.Bd -literal -offset indent 138$ cd /usr/src 139$ cvs -d anoncvs@anoncvs.nl.openbsd.org:/cvs update -Pd 140.Ed 141.Pp 142General users may wish to use 143.Xr cvs 1 144simply to keep a copy of sources up to date with a development tree; 145developers of software projects can also use 146.Xr cvs 1 147to make their own changes to a set of remote source files, 148and to view changes made by other software developers. 149.Pp 150See 151.Xr cvs 1 152for more information on the different commands available. 153See the entry for 154.Pa $HOME/.cvsrc 155in 156.Xr cvs 5 157for details on configuring 158.Xr cvs 1 159itself. 160.Sh USING CVS TO MANAGE A REPOSITORY 161Software developers may wish to use 162.Xr cvs 1 163to manage their own software projects. 164Here we look at an example usage: 165providing remote access to a small group of developers 166working on project 167.Dq foo , 168located in 169.Pa /cvs/projects . 170First of all a 171.Em repository 172has to be created. 173A repository is just the location of the group of files 174to be managed. 175Within the repository, 176files may be organised into collections of files, 177called 178.Em modules , 179which are just logical groupings of files. 180.Pp 181In our example, module 182.Dq foo 183is located at 184.Pa /cvs/projects/foo 185on machine 186.Dq cvs.example.org . 187Therefore 188.Pa /cvs/projects 189is both the root directory 190.Pq Em $CVSROOT 191of our repository and the name of our repository. 192.Pp 193If a set of source files already exist, 194possibly already under revision control, 195they can be added to a repository using the 196.Xr cvs 1 197command 198.Ic import . 199This is a useful way of adding modules to a pre-existing repository. 200In our example we are starting from scratch, 201so the repository has to be initialised using the 202.Ic init 203command: 204.Bd -literal -offset indent 205# cd /cvs/projects 206# cvs -d /cvs/projects init 207.Ed 208.Pp 209This will create a default administrative directory, 210.Pa $CVSROOT/CVSROOT , 211filled with files concerned with the management of the repository. 212.Pp 213Thereafter, access will have to be arranged for 214developers participating in the project. 215This typically means providing SSH access via 216.Xr sshd 8 217for remote access, 218unless the development network is local. 219.Sh SEE ALSO 220.Xr cvs 1 , 221.Xr rcs 1 , 222.Xr cvs 5 , 223.Xr sshd 8 224.Sh HISTORY 225The OpenCVS project is a BSD-licensed rewrite of the original 226Concurrent Versioning System written by Jean-Francois Brousseau. 227The original CVS code was written in large parts by Dick Grune, 228Brian Berliner, and Jeff Polk. 229.Sh AUTHORS 230.An Jean-Francois Brousseau 231.Sh CAVEATS 232This CVS implementation does not fully conform to the GNU CVS version. 233In some cases, this was done explicitly because GNU CVS has inconsistencies 234or ambiguous behaviour. 235Some things have also been left out or modified to enhance the overall 236security of the system. 237.Pp 238Among other things, support for the pserver connection mechanism has been 239dropped because of security issues with the authentication mechanism. 240