cvs.sgml 14 KB
Newer Older
1
<!-- $PostgreSQL: pgsql/doc/src/sgml/cvs.sgml,v 1.41 2007/02/01 00:28:16 momjian Exp $ -->
2

3
<appendix id="cvs">
4
 <appendixinfo>
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
  <authorgroup>
   <author>
    <firstname>Marc</firstname>
    <surname>Fournier</surname>
   </author>
   <author>
    <firstname>Tom</firstname>
    <surname>Lane</surname>
   </author>
   <author>
    <firstname>Thomas</firstname>
    <surname>Lockhart</surname>
   </author>
  </authorgroup>
  <date>1999-05-20</date>
20
 </appendixinfo>
21 22

 <title>The <productname>CVS</productname> Repository</title>
23

24
 <para>
25
  The <productname>PostgreSQL</productname> source code is stored and managed using the
26
  <productname>CVS</productname> version control system.
27
 </para>
28

29
 <para>
30
  At least two methods,
31 32
  anonymous CVS and <productname>CVSup</productname>,
  are available to pull the <productname>CVS</productname> code tree from the
33
  <productname>PostgreSQL</productname> server to your local machine.
34
 </para>
35

36
 <sect1 id="anoncvs">
37 38 39 40
  <title>Getting The Source Via Anonymous <productname>CVS</productname></title>

  <para>
   If you would like to keep up with the current sources on a regular
41
   basis, you can fetch them from our <productname>CVS</productname> server
42 43 44 45 46 47 48 49 50
   and then use <productname>CVS</productname> to
   retrieve updates from time to time.
  </para>

  <procedure>
   <title>Anonymous CVS</title>

   <step>
    <para>
51
     You will need a local copy of <productname>CVS</productname>
52
     (Concurrent Version Control System), which you can get from
53 54 55
     <ulink url="http://www.nongnu.org/cvs/"></ulink> (the official
     site with the latest version) or any GNU software archive site
     (often somewhat outdated). Many systems have a recent version of
56 57 58 59 60 61 62 63
     <application>cvs</application> installed by default.
    </para>
   </step>

   <step>
    <para>
     Do an initial login to the <productname>CVS</productname> server:

64
<programlisting>
65
cvs -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot login
66
</programlisting>
67

68 69 70 71 72
     You will be prompted for a password; you can enter anything except
     an empty string.
    </para>

    <para>
73
     You should only need to do this once, since the password will be
74
     saved in <filename>.cvspass</filename> in your home directory.
75 76 77 78 79
    </para>
   </step>

   <step>
    <para>
80
     Fetch the <productname>PostgreSQL</productname> sources:
81
<programlisting>
82
cvs -z3 -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot co -P pgsql
83
</programlisting>
84

85
     This installs the <productname>PostgreSQL</productname> sources into a
86 87 88 89 90
     subdirectory <filename>pgsql</filename>
     of the directory you are currently in.

     <note>
      <para>
91
       If you have a fast link to the Internet, you might not need
92
       <option>-z3</option>, which instructs
Peter Eisentraut's avatar
Peter Eisentraut committed
93
       <productname>CVS</productname> to use <command>gzip</command> compression for transferred data.  But
94 95 96 97
       on a modem-speed link, it's a very substantial win.
      </para>
     </note>
    </para>
98

99 100 101 102 103 104 105 106 107 108 109 110 111
    <para>
     This initial checkout is a little slower than simply downloading
     a <filename>tar.gz</filename> file; expect it to take 40 minutes or so if you
     have a 28.8K modem.  The advantage of
     <productname>CVS</productname>
     doesn't show up until you want to update the file set later on.
    </para>
   </step>

   <step>
    <para>
     Whenever you want to update to the latest <productname>CVS</productname> sources,
     <command>cd</command> into
112
     the <filename>pgsql</filename> subdirectory, and issue:
113 114 115
<programlisting>
cvs -z3 update -d -P
</programlisting>
116 117 118 119 120 121 122 123 124 125

     This will fetch only the changes since the last time you updated.
     You can update in just a couple of minutes, typically, even over
     a modem-speed line.
    </para>
   </step>

   <step>
    <para>
     You can save yourself some typing by making a file <filename>.cvsrc</filename>
126
     in your home directory that contains:
127

128
<programlisting>
129 130
cvs -z3
update -d -P
131
</programlisting>
132

Peter Eisentraut's avatar
Peter Eisentraut committed
133 134
     This supplies the <option>-z3</option> option to all <command>cvs</> commands, and the
     <option>-d</option> and <option>-P</option> options to <command>cvs update</>.  Then you just have
135
     to say:
136 137 138
<programlisting>
cvs update
</programlisting>
139 140 141 142 143 144 145

     to update your files.
    </para>
   </step>
  </procedure>

  <para>
146 147 148 149 150 151
   <productname>CVS</productname> can do a lot of other things, such
   as fetching prior revisions of the
   <productname>PostgreSQL</productname> sources rather than the
   latest development version.  For more info consult the manual that
   comes with <productname>CVS</productname>, or see the online
   documentation at <ulink url="http://www.nongnu.org/cvs/"></ulink>.
152 153
  </para>
 </sect1>
154

155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
 <sect1 id="cvs-tree">
  <title><productname>CVS</productname> Tree Organization</title>

  <para>
   <note>
    <title>Author</title>
    <para>
     Written by Marc G. Fournier (<email>scrappy@hub.org</email>) on 1998-11-05
    </para>
   </note>
  </para>

  <para>
   The command <command>cvs checkout</command> has a flag, <option>-r</option>,
   that lets you check out a
   certain revision of a module.  This flag makes it easy to, for example,
   retrieve the
   sources that make up release 6_4 of the module `tc' at any time in the
   future:

175 176 177
<programlisting>
cvs checkout -r REL6_4 tc
</programlisting>
178 179 180 181 182 183 184 185 186 187 188 189 190 191

   This is useful, for instance, if someone claims that there is a bug in
   that release, but you cannot find the bug in the current working copy.

   <tip>
    <para>
     You can also check out a module as it was at any given date using the
     <option>-D</option> option.
    </para>
   </tip>
  </para>

  <para>
   When you tag more than one file with the same tag you can think
Peter Eisentraut's avatar
Peter Eisentraut committed
192
   about the tag as <quote>a curve drawn through a matrix of file name vs.
193
   revision number</quote>.  Say we have 5 files with the following revisions:
194

195 196
   <programlisting>
             file1   file2   file3   file4   file5
197

198
             1.1     1.1     1.1     1.1  /--1.1*      &lt;-*-  TAG
199 200 201 202 203 204 205
             1.2*-   1.2     1.2    -1.2*-
             1.3  \- 1.3*-   1.3   / 1.3
             1.4          \  1.4  /  1.4
                           \-1.5*-   1.5
                             1.6
   </programlisting>

206
   then the tag <literal>TAG</literal> will reference
207 208 209 210
   file1-1.2, file2-1.3, etc.

   <note>
    <para>
211 212
     For creating a release branch, other than a
     <literal>-b</> option added to the command, it's the same thing.</para>
213 214 215 216 217 218 219
   </note>
  </para>

  <para>
   So, to create the 6.4 release
   I did the following:

220 221 222 223
<programlisting>
cd pgsql
cvs tag -b REL6_4
</programlisting>
224 225 226 227 228 229 230 231 232 233

   which will create the tag and the branch for the RELEASE tree.
  </para>

  <para>
   For those with <productname>CVS</productname> access, it's simple to
   create directories for different versions.
   First, create two subdirectories, RELEASE and CURRENT, so that you don't
   mix up the two.  Then do:

234
<programlisting>
235 236 237 238
cd RELEASE
cvs checkout -P -r REL6_4 pgsql
cd ../CURRENT
cvs checkout -P pgsql
239
</programlisting>
240 241 242 243 244 245 246 247 248 249 250 251 252 253 254

   which results in two directory trees, <filename>RELEASE/pgsql</filename> and
   <filename>CURRENT/pgsql</filename>. From that point on,
   <productname>CVS</productname>
   will keep track of which repository branch is in which directory tree, and will
   allow independent updates of either tree.
  </para>

  <para>
   If you are <emphasis>only</emphasis> working on the <literal>CURRENT</literal>
   source tree, you just do
   everything as before we started tagging release branches.
  </para>

  <para>
255
   After you've done the initial checkout on a branch:
256

257 258 259
<programlisting>
cvs checkout -r REL6_4
</programlisting>
260 261

   anything you do within that directory structure is restricted to that
262
   branch.  If you apply a patch to that directory structure and do a:
263

264
<programlisting>
265
cvs commit
266
</programlisting>
267 268 269 270 271 272

   while inside of it, the patch is applied to the branch and
   <emphasis>only</emphasis> the branch.
  </para>
 </sect1>

273
 <sect1 id="cvsup">
274
  <title>Getting The Source Via <productname>CVSup</productname></title>
275

276
  <para>
277
   An alternative to using anonymous CVS for retrieving
278
   the <productname>PostgreSQL</productname> source tree
279 280
   is <productname>CVSup</productname>.
   <productname>CVSup</productname> was developed by
281
   John Polstra (<email>jdp@polstra.com</email>) to
282 283
   distribute CVS repositories and other file trees for the
   <ulink url="http://www.freebsd.org">FreeBSD project</ulink>.
284
  </para>
285

286 287 288 289
  <para>
   A major advantage to using
   <productname>CVSup</productname> is that it can reliably
   replicate the <emphasis>entire</emphasis> CVS repository on your local system,
Peter Eisentraut's avatar
Peter Eisentraut committed
290
   allowing fast local access to <command>cvs</> operations such as <option>log</option>
291
   and <option>diff</option>. Other advantages include fast synchronization to
292
   the <productname>PostgreSQL</productname> server due to an efficient
293 294
   streaming transfer protocol which only sends the changes since the last update.
  </para>
295

296 297 298 299 300
  <sect2>
   <title>Preparing A <productname>CVSup</productname> Client System</title>

   <para>
    Two directory areas are required for <productname>CVSup</productname>
301
    to do its job: a local <productname>CVS</productname> repository
302 303 304 305 306 307 308
    (or simply a directory area if you are fetching a snapshot rather
    than a repository; see below)
    and a local <productname>CVSup</productname> bookkeeping
    area. These can coexist in the same directory tree.
   </para>

   <para>
309
    Decide where you want to keep your local copy of the
310
    <productname>CVS</productname> repository. On one of our systems we
311
    recently set up a repository in <filename>/home/cvs/</filename>,
312
    but had formerly kept it under a
313
    <productname>PostgreSQL</productname> development tree in
314
    <filename>/opt/postgres/cvs/</filename>. If you intend to keep your
315
    repository in <filename>/home/cvs/</filename>, then put:
316

317
<programlisting>
318
setenv CVSROOT /home/cvs
319
</programlisting>
320 321 322

    in your <filename>.cshrc</filename> file, or a similar line in
    your <filename>.bashrc</filename> or
323
    <filename>.profile</filename> file, depending on your shell.
324 325 326 327 328 329 330
   </para>

   <para>
    The <application>cvs</application> repository area must be initialized.
    Once <envar>CVSROOT</envar> is set, then this can be done with a
    single command:

331 332 333
<programlisting>
cvs init
</programlisting>
334 335 336 337 338

    after which you should see at least a directory named
    <filename>CVSROOT</filename> when listing the
    <envar>CVSROOT</envar> directory:

339
<programlisting>
340 341
$ ls $CVSROOT
CVSROOT/
342
</programlisting>
343 344 345 346 347 348 349 350 351
   </para>
  </sect2>

  <sect2>
   <title>Running a <productname>CVSup</productname> Client</title>

   <para>
    Verify that
    <application>cvsup</application> is in your path; on most systems
352
    you can do this by typing:
353

354
<programlisting>
355
which cvsup
356
</programlisting>
357

358
    Then, simply run
359 360
    <application>cvsup</application> using:

361 362 363
<programlisting>
cvsup -L 2 <replaceable class="parameter">postgres.cvsup</replaceable>
</programlisting>
364 365 366 367 368 369 370 371 372 373 374 375 376

    where <option>-L 2</option> enables some status messages so you
    can monitor the progress of the update,
    and <replaceable class="parameter">postgres.cvsup</replaceable> is
    the path and name you have given to your
    <productname>CVSup</productname> configuration file.
   </para>

   <para>
    Here is a <productname>CVSup</productname> configuration file
    modified for a specific installation, and which maintains a full
    local <productname>CVS</productname> repository:

377
<programlisting>
378
# This file represents the standard CVSup distribution file
379
# for the <productname>PostgreSQL</> ORDBMS project
380
# Modified by lockhart@fourpalms.org 1997-08-28
381 382 383 384
# - Point to my local snapshot source tree
# - Pull the full CVS repository, not just the latest snapshot
#
# Defaults that apply to all the collections
385
*default host=cvsup.postgresql.org
386 387 388 389 390 391 392 393
*default compress
*default release=cvs
*default delete use-rel-suffix
# enable the following line to get the latest snapshot
#*default tag=.
# enable the following line to get whatever was specified above or by default
# at the date specified below
#*default date=97.08.29.00.00.00
394

395
# base directory where CVSup will store its 'bookmarks' file(s)
396 397 398
# will create subdirectory sup/
#*default base=/opt/postgres # /usr/local/pgsql
*default base=/home/cvs
399

400
# prefix directory where CVSup will store the actual distribution(s)
401
*default prefix=/home/cvs
402

403
# complete distribution, including all below
404
pgsql
405

406 407 408 409
# individual distributions vs 'the whole thing'
# pgsql-doc
# pgsql-perl5
# pgsql-src
410
</programlisting>
411
   </para>
412

413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429
   <para>
    If you specify <option>repository</> instead of <option>pgsql</>
    in the above setup, you will get a complete copy of the entire
    repository at cvsup.postgresql.org, including its
    <filename>CVSROOT</filename> directory. If you do that, you will
    probably want to exclude those files in that directory that you
    want to modify locally, using a refuse file. For example, for the
    above setup you might put this in
    <filename>/home/cvs/sup/repository/refuse</>:
<programlisting>
CVSROOT/config*
CVSROOT/commitinfo*
CVSROOT/loginfo*
</programlisting>
    See the <productname>CVSup</> manual pages for how to use refuse files.
   </para>

430
   <para>
Peter Eisentraut's avatar
Peter Eisentraut committed
431
    The following is a suggested <productname>CVSup</productname> configuration file from
432 433 434
    the <productname>PostgreSQL</>
    <ulink url="ftp://ftp.postgresql.org/pub/CVSup/README.cvsup">
    ftp site</ulink>
435
    which will fetch the current snapshot only:
436

437
<programlisting>
438
# This file represents the standard CVSup distribution file
439
# for the <productname>PostgreSQL</> ORDBMS project
440 441
#
# Defaults that apply to all the collections
442
*default host=cvsup.postgresql.org
443 444 445 446
*default compress
*default release=cvs
*default delete use-rel-suffix
*default tag=.
447

448
# base directory where CVSup will store its 'bookmarks' file(s)
449
*default base=<replaceable class="parameter">/usr/local/pgsql</replaceable>
450

451
# prefix directory where CVSup will store the actual distribution(s)
452 453
*default prefix=<replaceable class="parameter">/usr/local/pgsql</replaceable>

454
# complete distribution, including all below
455 456 457 458 459 460
pgsql

# individual distributions vs 'the whole thing'
# pgsql-doc
# pgsql-perl5
# pgsql-src
461
</programlisting>
462 463 464 465
   </para>
  </sect2>
 </sect1>
</appendix>