path: root/doc/src/sgml/cvs.sgml

<!-- $PostgreSQL: pgsql/doc/src/sgml/cvs.sgml,v 1.53 2010/08/17 04:37:20 petere Exp $ -->

<appendix id="cvs">
 <appendixinfo>
  <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>
   <author>
    <firstname>David</firstname>
    <surname>Fetter</surname>
   </author>
  </authorgroup>
  <date>1999-05-20</date>
 </appendixinfo>

 <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. 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>
  Our wiki, <ulink
  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>

  <para>
   If you would like to keep up with the current sources on a regular
   basis, you can fetch them from our <productname>CVS</productname> server
   and then use <productname>CVS</productname> to
   retrieve updates from time to time.
  </para>

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

   <step>
    <para>
     You will need a local copy of <productname>CVS</productname>
     (Concurrent Version Control System), which you can get from
     <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
     <application>cvs</application> installed by default.
    </para>
   </step>

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

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

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

    <para>
     You should only need to do this once, since the password will be
     saved in <filename>.cvspass</filename> in your home directory.
    </para>
   </step>

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

     This installs the <productname>PostgreSQL</productname> sources into a
     subdirectory <filename>pgsql</filename>
     of the directory you are currently in.
    </para>

    <para>
     This initial checkout is a little slower than simply downloading
     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>

   <step>
    <para>
     Whenever you want to update to the latest <productname>CVS</productname> sources,
     <command>cd</command> into
     the <filename>pgsql</filename> subdirectory, and issue:
<programlisting>
cvs -z3 update -d -P
</programlisting>

     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>
     in your home directory that contains:

<programlisting>
cvs -z3
update -d -P
</programlisting>

     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
     to say:
<programlisting>
cvs update
</programlisting>

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

  <para>
   <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>.
  </para>
  <para>
   <productname>CVS</productname> has deficiencies.  For example,
   generating diffs that add or remove files requires write access to the
   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>, or use <productname>Git</>
   or another system designed to work offline.
  </para>

  <para>
   Note that building <productname>PostgreSQL</productname> from a CVS
   pull requires reasonably up-to-date versions of <application>bison</>
   and <application>flex</>, which are not needed to build from a distribution
   tarball because the files made with them are pre-built in a tarball.
   You will need Perl as well.
   Otherwise the tool requirements are the same as building from source.
  </para>
 </sect1>

 <sect1 id="rsync">
  <title>Getting The Source Via <productname>rsync</productname></title>

  <para>
   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> 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>.
   Other advantages include fast synchronization to the
   <productname>PostgreSQL</productname> server due to an efficient
   streaming transfer protocol which only sends the changes since the last
   update.
  </para>

  <para>
   You can download the CVS repository using this command:
<programlisting>
rsync -avzH --delete anoncvs.postgresql.org::pgsql-cvs cvsroot/
</programlisting>
   For full instructions, see the "rsync" section in the 
   <ulink url="http://pgfoundry.org/docman/view.php/1000040/4/PGBuildFarm-HOWTO.txt">
   PostgreSQL Build Farm instructions</ulink>.
  </para>
 </sect1>
</appendix>