Skip to content

P
Postgres FD Implementation
Commit 8df283d2 authored by Magnus Hagander's avatar Magnus Hagander
Browse files
Options

Update CVS documentation to be more current and add documentation about 

git mirror.

Remove information about cvsup and documentation that's more about cvs
than our use of cvs.

Backpatch to 8.4 so we get the git information up on the website as
soon as possible.
parent 0cb65564
Show whitespace changes
Inline Side-by-side
Showing with 94 additions and 325 deletions
doc/src/sgml/cvs.sgml
View file @ 8df283d2
<!-- $PostgreSQL: pgsql/doc/src/sgml/cvs.sgml,v 1.51 2009/06/23 03:46:00 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/cvs.sgml,v 1.52 2009/12/07 19:19:56 mha Exp $ -->
<appendix id="cvs">
<appendixinfo>
......@@ -23,22 +23,96 @@
<date>1999-05-20</date>
</appendixinfo>
<title>The <productname>CVS</productname> Repository</title>
<title>The Source Code Repository</title>
<para>
The <productname>PostgreSQL</productname> source code is stored and managed using the
<productname>CVS</productname> version control system.
<productname>CVS</productname> version control system. An official mirror using
<productname>Git</productname> is also available, for those who wish to use a
distributed version control system. This mirror is automatically
updated whenever the main repository changes, so it always contains the latest
versions of all branches.
</para>
<para>
Using <productname>git</> is the most flexible way to work with the source, and it
allows you to work offline without having constant access to the project servers.
<productname>rsync</> based <productname>cvs</> also lets you work offline, but
lacks many of the other advantages of <productname>git</>.
</para>
<para>
At least three methods, anonymous CVS, <productname>rsync</productname>,
and <productname>CVSup</productname>,
are available to pull the <productname>CVS</productname> code tree from the
<productname>PostgreSQL</productname> server to your local machine.
Our Wiki, <ulink
url="http://wiki.postgresql.org/index.php/Working_with_CVS"></ulink>,
has additional details on working with CVS.
url="http://wiki.postgresql.org/wiki/Working_with_CVS"></ulink> and
<ulink url="http://wiki.postgresql.org/wiki/Working_with_Git"></ulink>,
has additional details on working with CVS and Git.
</para>
<sect1 id="git">
<title>Getting The Source Via <productname>Git</></title>
<para>
With <productname>git</> you will make a copy of the entire code repository
to your local machine, so you will have access to all history and branches
offline. This is the fastest and most flexible way to develop or test
patches.
</para>
<procedure>
<title>Git</title>
<step>
<para>
You will need an installed version of <productname>git</>, which you can get
from <ulink url="http://git-scm.com"></ulink>. Many systems also have a recent
version of <application>git</> installed by default, or available in their
package repository system.
</para>
</step>
<step>
<para>
To being using the git repository, make a clone of the official mirror:
<programlisting>
git clone git://git.postgresql.org/git/postgresql.git
</programlisting>
This will copy the full repository to your local machine, so it may take
a while to complete, especially if you have a slow internet connection.
</para>
<para>
The git mirror can also be reached via the http protocol in case for example
a firewall is blocking access to the git protocol. Just replace the URL
like:
<programlisting>
git clone http://git.postgresql.org/git/postgresql.git
</programlisting>
The http protocol is less efficient than the git protocol, so it will be
slightly slower to use.
</para>
</step>
<step>
<para>
Whenever you want to get the latest updates in the system, <command>cd</>
into the repository, and run:
<programlisting>
git fetch
</programlisting>
</para>
</step>
</procedure>
<para>
<productname>git</> can do a lot more things than just fetch the source. For
more information, consult the man pages for the product, or the website at
<ulink url="http://git-scm.com"></>.
</para>
</sect1>
<sect1 id="anoncvs">
<title>Getting The Source Via Anonymous <productname>CVS</productname></title>
......@@ -92,22 +166,11 @@ cvs -z3 -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot co -P pgsql
This installs the <productname>PostgreSQL</productname> sources into a
subdirectory <filename>pgsql</filename>
of the directory you are currently in.
<note>
<para>
If you have a fast link to the Internet, you might not need
<option>-z3</option>, which instructs
<productname>CVS</productname> to use <command>gzip</command> compression for transferred data. But
on a modem-speed link, it's a very substantial win.
</para>
</note>
</para>
<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>
a <filename>tar.gz</filename> file. The advantage of <productname>CVS</>
doesn't show up until you want to update the file set later on.
</para>
</step>
......@@ -163,7 +226,8 @@ cvs update
CVS repository. To work around that deficiency, use
<productname>cvsutils</productname>, which is packaged in several
operating systems, and is available in source form at <ulink
url="http://www.red-bean.com/cvsutils/"></ulink>.
url="http://www.red-bean.com/cvsutils/"></ulink>, or use <productname>git</>
or another system designed to work offline.
</para>
<para>
......@@ -176,124 +240,6 @@ cvs update
</para>
</sect1>
<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:
<programlisting>
cvs checkout -r REL6_4 tc
</programlisting>
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
about the tag as <quote>a curve drawn through a matrix of file name vs.
revision number</quote>. Say we have 5 files with the following revisions:
<programlisting>
file1 file2 file3 file4 file5
1.1 1.1 1.1 1.1 /--1.1* &lt;-*- TAG
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>
then the tag <literal>TAG</literal> will reference
file1-1.2, file2-1.3, etc.
<note>
<para>
For creating a release branch, other than a
<literal>-b</> option added to the command, it's the same thing.</para>
</note>
</para>
<para>
So, to create the 6.4 release
I did the following:
<programlisting>
cd pgsql
cvs tag -b REL6_4
</programlisting>
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:
<programlisting>
cd RELEASE
cvs checkout -P -r REL6_4 pgsql
cd ../CURRENT
cvs checkout -P pgsql
</programlisting>
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>
After you've done the initial checkout on a branch:
<programlisting>
cvs checkout -r REL6_4
</programlisting>
anything you do within that directory structure is restricted to that
branch. If you apply a patch to that directory structure and do a:
<programlisting>
cvs commit
</programlisting>
while inside of it, the patch is applied to the branch and
<emphasis>only</emphasis> the branch.
</para>
</sect1>
<sect1 id="rsync">
<title>Getting The Source Via <productname>rsync</productname></title>
......@@ -301,7 +247,8 @@ cvs commit
An alternative to using anonymous CVS for retrieving the
<productname>PostgreSQL</productname> source tree is
<productname>rsync</productname>, an incremental file transfer tool.
A major advantage to using <productname>rsync</productname> is that it
A major advantage to using <productname>rsync</productname> instead of
plain <productname>cvs</> is that it
can reliably replicate the <emphasis>entire</emphasis> CVS repository
on your local system, allowing fast local access to <command>cvs</>
operations such as <option>log</option> and <option>diff</option>.
......@@ -321,187 +268,4 @@ rsync -avzH --delete anoncvs.postgresql.org::pgsql-cvs cvsroot/
pgbuildfarm instructions</ulink>.
</para>
</sect1>
<sect1 id="cvsup">
<title>Getting The Source Via <productname>CVSup</productname></title>
<para>
Another alternative to using anonymous CVS for retrieving
the <productname>PostgreSQL</productname> source tree
is <productname>CVSup</productname>.
<productname>CVSup</productname> was developed by
John Polstra (<email>jdp@polstra.com</email>) to
distribute CVS repositories and other file trees for the
<ulink url="http://www.freebsd.org">FreeBSD project</ulink>.
</para>
<sect2>
<title>Preparing A <productname>CVSup</productname> Client System</title>
<para>
Two directory areas are required for <productname>CVSup</productname>
to do its job: a local <productname>CVS</productname> repository
(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>
Decide where you want to keep your local copy of the
<productname>CVS</productname> repository. On one of our systems we
recently set up a repository in <filename>/home/cvs/</filename>,
but had formerly kept it under a
<productname>PostgreSQL</productname> development tree in
<filename>/opt/postgres/cvs/</filename>. If you intend to keep your
repository in <filename>/home/cvs/</filename>, then put:
<programlisting>
setenv CVSROOT /home/cvs
</programlisting>
in your <filename>.cshrc</filename> file, or a similar line in
your <filename>.bashrc</filename> or
<filename>.profile</filename> file, depending on your shell.
</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:
<programlisting>
cvs init
</programlisting>
after which you should see at least a directory named
<filename>CVSROOT</filename> when listing the
<envar>CVSROOT</envar> directory:
<programlisting>
$ ls $CVSROOT
CVSROOT/
</programlisting>
</para>
</sect2>
<sect2>
<title>Running a <productname>CVSup</productname> Client</title>
<para>
Verify that
<application>cvsup</application> is in your path; on most systems
you can do this by typing:
<programlisting>
which cvsup
</programlisting>
Then, simply run
<application>cvsup</application> using:
<programlisting>
cvsup -L 2 <replaceable class="parameter">postgres.cvsup</replaceable>
</programlisting>
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:
<programlisting>
# This file represents the standard CVSup distribution file
# for the <productname>PostgreSQL</> ORDBMS project
# Modified by lockhart@fourpalms.org 1997-08-28
# - Point to my local snapshot source tree
# - Pull the full CVS repository, not just the latest snapshot
#
# Defaults that apply to all the collections
*default host=cvsup.postgresql.org
*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
# base directory where CVSup will store its 'bookmarks' file(s)
# will create subdirectory sup/
#*default base=/opt/postgres # /usr/local/pgsql
*default base=/home/cvs
# prefix directory where CVSup will store the actual distribution(s)
*default prefix=/home/cvs
# complete distribution, including all below
pgsql
# individual distributions vs 'the whole thing'
# pgsql-doc
# pgsql-perl5
# pgsql-src
</programlisting>
</para>
<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>
<para>
The following is a suggested <productname>CVSup</productname> configuration file from
the <productname>PostgreSQL</>
<ulink url="ftp://ftp.postgresql.org/pub/CVSup/README.cvsup">
ftp site</ulink>
which will fetch the current snapshot only:
<programlisting>
# This file represents the standard CVSup distribution file
# for the <productname>PostgreSQL</> ORDBMS project
#
# Defaults that apply to all the collections
*default host=cvsup.postgresql.org
*default compress
*default release=cvs
*default delete use-rel-suffix
*default tag=.
# base directory where CVSup will store its 'bookmarks' file(s)
*default base=<replaceable class="parameter">/usr/local/pgsql</replaceable>
# prefix directory where CVSup will store the actual distribution(s)
*default prefix=<replaceable class="parameter">/usr/local/pgsql</replaceable>
# complete distribution, including all below
pgsql
# individual distributions vs 'the whole thing'
# pgsql-doc
# pgsql-perl5
# pgsql-src
</programlisting>
</para>
</sect2>
</sect1>
</appendix>
doc/src/sgml/installation.sgml
View file @ 8df283d2
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.328 2009/12/02 14:07:25 momjian Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.329 2009/12/07 19:19:56 mha Exp $ -->
<chapter id="installation">
<title><![%standalone-include[<productname>PostgreSQL</>]]>
......@@ -354,6 +354,11 @@ su - postgres
Change into that directory for the rest
of the installation procedure.
</para>
<para>
You can also get the source directly from the version control repository, see
<xref linkend="cvs">.
</para>
</sect1>
]]>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment