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