Text of peps.python.org › pep-0374 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 374 – Choosing a distributed VCS for the Python project | peps.python.org

PEP 374 – Choosing a distributed VCS for the Python project PEP 374 – Choosing a distributed VCS for the Python project Author : Brett Cannon <brett at python.org>, Stephen J. Turnbull <stephen at xemacs.org>, Alexandre Vassalotti <alexandre at peadrop.com>, Barry Warsaw <barry at python.org>, Dirkjan Ochtman <dirkjan at ochtman.nl> Status : Final Type : Process Created : 07-Nov-2008 Post-History : 07-Nov-2008, 22-Jan-2009 Table of Contents Rationale Terminology Typical Workflow Contenders Interoperability Usage Scenarios Initial Setup svn bzr hg git One-Off Checkout svn bzr hg git Backing Out Changes svn bzr hg git Patch Review svn bzr hg git Backport svn bzr hg git Coordinated Development of a New Feature svn Separation of Issue Dependencies svn bzr hg git Doing a Python Release bzr hg git Platform/Tool Support Operating Systems CRLF -> LF Support Case-insensitive filesystem support Tools Usage On Top Of Subversion Server Support Development Special Features bzr hg git Tests/Impressions Barrier to Entry Performance of basic information functionality Figuring out what command to use from built-in help Updating a checkout Decision Why Mercurial over Subversion Why Mercurial over other DVCSs Transition Plan Copyright Rationale Python has been using a centralized version control system (VCS; first CVS, now Subversion) for years to great effect.

Having a master copy of the official version of Python provides people with a single place to always get the official Python source code. It has also allowed for the storage of the history of the language, mostly for help with development, but also for posterity. And of course the V in VCS is very helpful when developing. But a centralized version control system has its drawbacks. First and foremost, in order to have the benefits of version control with Python in a seamless fashion, one must be a “core developer” (i.e. someone with commit privileges on the master copy of Python).

People who are not core developers but who wish to work with Python’s revision tree, e.g. anyone writing a patch for Python or creating a custom version, do not have direct tool support for revisions. This can be quite a limitation, since these non-core developers cannot easily do basic tasks such as reverting changes to a previously saved state, creating branches, publishing one’s changes with full revision history, etc.

For non-core developers, the last safe tree state is one the Python developers happen to set, and this prevents safe development. This second-class citizenship is a hindrance to people who wish to contribute to Python with a patch of any complexity and want a way to incrementally save their progress to make their development lives easier. There is also the issue of having to be online to be able to commit one’s work.

Because centralized VCSs keep a central copy that stores all revisions, one must have Internet access in order for their revisions to be stored; no Net, no commit. This can be annoying if you happen to be traveling and lack any Internet. There is also the situation of someone wishing to contribute to Python but having a bad Internet connection where committing is time-consuming and expensive and it might work out better to do it in a single step.

Another drawback to a centralized VCS is that a common use case is for a developer to revise patches in response to review comments. This is more difficult with a centralized model because there’s no place to contain intermediate work. It’s either all checked in or none of it is checked in. In the centralized VCS, it’s also very difficult to track changes to the trunk as they are committed, while you’re working on your feature or bug fix branch.

This increases the risk that such branches will grow stale, out-dated, or that merging them into the trunk will generate too may conflicts to be easily resolved. Lastly, there is the issue of maintenance of Python. At any one time there is at least one major version of Python under development (at the time of this writing there are two). For each major version of Python under development there is at least the maintenance version of the last minor version and the in-development minor version (e.g. with 2.6 just released, that means that both 2.6 and 2.7 are being worked on).

Once a release is done, a branch is created between the code bases where changes in one version do not (but could) belong in the other version. As of right now there is no natural support for this branch in time in central VCSs; you must use tools that simulate the branching. Tracking merges is similarly painful for developers, as revisions often need to be merged between four active branches (e.g. 2.6 maintenance, 3.0 maintenance, 2.7 development, 3.1 development).

In this case, VCSs such as Subversion only handle this through arcane third party tools. Distributed VCSs (DVCSs) solve all of these problems. While one can keep a master copy of a revision tree, anyone is free to copy that tree for their own use. This gives everyone the power to commit changes to their copy, online or offline. It also more naturally ties into the idea of branching in the history of a revision tree for maintenance and the development of new features bound for Python.

DVCSs also provide a great many additional features that centralized VCSs don’t or can’t provide. This PEP explores the possibility of changing Python’s use of Subversion to any of the currently popular DVCSs, in order to gain the benefits outlined above. This PEP does not guarantee that a switch to a DVCS will occur at the conclusion of this PEP. It is quite possible that no clear winner will be found and that svn will continue to be used.

If this happens, this PEP will be revisited and revised in the future as the state of DVCSs evolves. Terminology Agreeing on a common terminology is surprisingly difficult, primarily because each VCS uses these terms when describing subtly different tasks, objects, and concepts. Where possible, we try to provide a generic definition of the concepts, but you should consult the individual system’s glossaries for details.

Here are some basic references for terminology, from some of the standard web-based references on each VCS. You can also refer to glossaries for each DVCS: Subversion : http://svnbook.red-bean.com/en/1.5/svn.basic.html Bazaar : http://bazaar-vcs.org/BzrGlossary Mercurial : http://www.selenic.com/mercurial/wiki/index.cgi/UnderstandingMercurial git : http://book.git-scm.com/1_the_git_object_model.html branch A line of development; a collection of revisions, ordered by time. checkout/working copy/working tree A tree of code the developer can edit, linked to a branch. index A “staging area” where a revision is built (unique to git). repository A collection of revisions, organized into branches. clone A complete copy of a branch or repository. commit To record a revision in a repository. merge Applying all the changes and history from one branch/repository to another. pull To update a checkout/clone from the original branch/repository, which can be remote or local push/publish To copy a revision, and all revisions it depends on, from a one repository to another. cherry-pick To merge one or more specific revisions from one branch to another, possibly in a different repository, possibly without its dependent revisions. rebase To “detach” a branch, and move it to a new branch point; move commits to the beginning of a branch instead of where they happened in time.

Typical Workflow At the moment, the typical workflow for a Python core developer is: Edit code in a checkout until it is stable enough to commit/push. Commit to the master repository. It is a rather simple workflow, but it has drawbacks. For one, because any work that involves the repository takes time thanks to the network, commits/pushes tend to not necessarily be as atomic as possible. There is also the drawback of there not being a necessarily cheap way to create new

The rest of this page is on the live site.