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