1.\" $OpenBSD: cvsintro.7,v 1.8 2005/08/02 16:50:05 xsa 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 November 15, 2004 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 geographically closer to you 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 also 154.Xr cvsrc 5 155for details on configuring 156.Xr cvs 1 157itself. 158.Sh USING CVS TO MANAGE A REPOSITORY 159Software developers may wish to use 160.Xr cvs 1 161to manage their own software projects. 162Here we look at an example usage: 163providing remote access to a small group of developers 164working on project 165.Dq foo , 166located in 167.Pa /cvs/projects . 168First of all a 169.Em repository 170has to be created. 171A repository is just the location of the group of files 172to be managed. 173Within the repository, 174files may be organised into collections of files, 175called 176.Em modules , 177which are just logical groupings of files. 178.Pp 179In our example, module 180.Dq foo 181is located at 182.Pa /cvs/projects/foo 183on machine 184.Dq cvs.example.org . 185Therefore 186.Pa /cvs/projects 187is both the root directory 188.Pq Em $CVSROOT 189of our repository and the name of our repository. 190.Pp 191If a set of source files already exist, 192possibly already under revision control, 193they can be added to a repository using the 194.Xr cvs 1 195command 196.Ic import . 197This is a useful way of adding modules to a pre-existent repository. 198In our example we are starting from scratch, 199so the repository has to be initialised using the 200.Ic init 201command: 202.Bd -literal -offset indent 203# cd /cvs/projects 204# cvs -d /cvs/projects init 205.Ed 206.Pp 207This will create a default administrative directory, 208.Pa $CVSROOT/CVSROOT , 209filled with files concerned with the management of the repository. 210.Pp 211Thereafter, access will have to be arranged for 212developers participating in the project. 213This typically means providing SSH access via 214.Xr sshd 8 215for remote access, 216unless the development network is local. 217.Sh SEE ALSO 218.Xr cvs 1 , 219.Xr rcs 1 , 220.Xr cvsignore 5 , 221.Xr cvsrc 5 , 222.Xr sshd 8 223.Sh HISTORY 224The OpenCVS project is a BSD-licensed rewrite of the original 225Concurrent Versioning System written by Jean-Francois Brousseau. 226The original CVS code was written in large parts by Dick Grune, 227Brian Berliner, and Jeff Polk. 228.Sh AUTHORS 229.An Jean-Francois Brousseau 230.Sh CAVEATS 231This CVS implementation does not fully conform to the GNU CVS version. 232In some cases, this was done explicitly because GNU CVS has inconsistencies 233or ambiguous behaviour. 234Some things have also been left out or modified to enhance the overall 235security of the system. 236.Pp 237Among other things, support for the pserver connection mechanism has been 238dropped because of security issues with the authentication mechanism. 239