Title: Experimental Git repositories
Content-type: text/x-rst

=============================
Experimental Git repositories
=============================

This document explains how to perform an initial checkout of the Python
source ccode using Git_.  Read-only access is simple and is explained in
the section below.  Read-write access via 'git svn' is more complicated
and is explained in the rest of this document.

.. _Git: http://git.or.cz/


Read-only access to the repository
----------------------------------

If you don't need or don't have the ability to commit to Python's
Subversion repository then getting the Python source code using git is
simple.  To checkout a copy of the trunk, use::

    $ git clone git://code.python.org/python/trunk

To checkout the Python 3 branch, use::

    $ git clone git://code.python.org/python/branches/py3k

Refer to the `git documentation`_ for details on how to use your
checkout.

.. _git documentation: http://git-scm.com/documentation


Initializing the local repository for read-write access
-------------------------------------------------------

These commands more complicated but that's mostly because we are setting
up our repository so that it can be updated using either the Git
protocol or the Subversion protocol via the git-svn command.  We will
also be able to push our changes back to the Subversion version using
the git-svn command.

Ensure that you have a recent Git (at least version 1.5.1).  The
following commands will initialize an empty repository::

    % mkdir trunk.git
    % cd trunk.git
    % git init

Tell git-svn where the Subversion repository is located.  If you have
read-write access use::

    % git svn init svn+ssh://pythondev@svn.python.org/python/trunk

Tell git where the data can be fetched using the git protocol.  This is
more efficient than using the Subversion protocol, especially if you are
far behind the head::

    % git remote add git-svn git://code.python.org/python/trunk
    % git config remote.git-svn.fetch refs/heads/master:refs/remotes/git-svn
   
The following command populates the local repository (this will download
approximately 90 MB of data from code.python.org).  You only have to
this once and after can use the clone command to avoid copying so much
data off the Python server::

    % git fetch git-svn

We don't do our development on the git-svn branch since that follows the
head of the public Subversion repository.  Our main development branch
is called 'master', athough we can create as many others as we like.
Merge the changes from the 'git-svn' branch into our development
branch::

    % git pull git-svn master

The final step is to recreate the git-svn metadata and fetch any new
Subversion commits::

    % git svn fetch

This should complete quickly because nearly all the data is already
local and the git-svn command will merely go through the logs and
extract the Subversion revision numbers.

You will now have a full mirror of the Subversion trunk branch with all
history.  This download only has to be performed once.  Afterwards you
can use 'git clone' to locally copy the repository.  For example::

    % git clone trunk.git trunk-copy.git
    % cd trunk-copy.git
    % git svn init svn+ssh://pythondev@svn.python.org/python/trunk
    % git remote add git-svn git://code.python.org/python/trunk
    % git config remote.git-svn.fetch refs/heads/master:refs/remotes/git-svn
    % git pull git-svn master


Keeping up-to-date
------------------

Using the 'git svn fetch' command closely matches the behavior of the
'svn update' command.  It will fetch new versions from the Subversion
repository and then rebase your local changes on top of them::

    % git svn fetch

Note that this can be slow if your repository is far behind the
Subversion repository.  The most efficient method to update your local
respository is to use the Git protocol.  To fetch new commits, run::

    % git fetch git-svn

If you have no local changes, you can do a fast-forward merge of
upstream commits into your current development branch::

    % git merge git-svn

However, if you have local changes then you probably want to use
'rebase' as it more closely matches the behavior of 'svn up'::

    % git rebase git-svn


Sharing work
------------

Please refer to the `Git SVN tutorial`_ for general instructions on how
to interact with a Subversion repository.  The 'git format-patch', 'git
am' and 'git apply' commands are very useful when dealing with patches.

.. _Git SVN tutorial: http://git.or.cz/course/svn.html

If you have write access to the SVN repository then you can use 'git svn
dcommit' to push your local commits directly into the public SVN
repository.  Take extra care before using 'dcommit'.  It's a good idea
to use 'git log' or 'gitk' to check what will be sent before actually
running 'dcommit'.  Also note that your local copy must be up-to-date
(e.g. via 'git svn rebase') for 'dcommit' to work.


Checking out the p3k branch for read-write access
-------------------------------------------------

There is also a Git repository for the py3k branch.  The following
commands will create a local repository::

    % mkdir py3k.git
    % cd py3k.git
    % git init
    % git svn init svn+ssh://pythondev@svn.python.org/python/branches/py3k
    % git remote add git-svn git://code.python.org/python/branches/py3k
    % git config remote.git-svn.fetch refs/heads/master:refs/remotes/git-svn
    % git pull git-svn master