Version 15 (modified by ltaylor.volks, 18 months ago)

Added link to other DVCS pages

For Twisted contributors

If you want to develop a patch for Twisted (as described in the BasicGuideToContributingCode) but prefer to use Git rather than SVN, this is the section for you.

For other version control systems, see DVCS Workflows.

Creating a Git clone

Twisted's SVN repository is very old, and has a lot of history, so trying to clone the whole thing would take days. Since you don't need the complete history to create a new patch, you can just clone the latest revision then update it occasionally.

  1. Find the SVN Revision number of the latest trunk commit:
    svn info svn:// | grep "Rev:"
    This should produce output like this:
    Last Changed Rev: 33142
  2. Create a Git clone of the repository by running this command, replacing REVNO with the revision number output by the previous command:
    git svn clone --stdlayout -rREVNO --prefix="svn/" svn://
    This should create a subdirectory named Twisted containing the latest trunk revision of the code.
  3. Create an ignore file that will prevent git from accidentally scooping up generated files like *.pyc or _trial_temp and including them in any patches you might submit:
    cat >> Twisted/.git/info/exclude << EOF
    See  the Git documentation on .gitignore, particularly core.excludesfile, for more information.
  4. Since Twisted is normally developed in SVN, Twisted developers are used to processing SVN-style patch files, not Git's patch format. You can change the behaviour of git diff to match SVN just for this single repository with the following commands:
    git config --file Twisted/.git/config --bool --add diff.noprefix true

Updating your Git clone

If more commits have been made to the SVN trunk, or a Twisted developer has created a new branch for your patch to live on, you'll want to update your clone with those changes so that you can produce new patches based on those changes. Just cd into the repository and run:

git checkout master
git svn rebase


Here are some solutions to common problems with git svn clones.

git svn operations seem to take forever

If you have your own git svn clone, and svn-based operations seem to take forever, try running:

git svn info

If that takes longer than 30 seconds to run, and eventually prints an error message, this is a clue that git svn has gotten confused about how your current branch connects to the imported SVN history. Either git checkout a git branch that's based on an SVN branch or (if you're already on such a branch, and it's broken) use git reset some-remote-branch-name to make sure your local branch is pointing exactly at a commit that was imported from SVN.

For Twisted core developers

If you are a Twisted developer and want to try developing Twisted via git svn, you are Very Brave and will need all the help you can get. Here are some chicken-scratches left on the poorly-lit cavern walls by previous explorers.

Creating a complete mirror

Note 1: Do not do this unless you are a Twisted developer and have asked permission. As of early 2010, this procedure takes about a week (YES, A WEEK) to run.

Note 2: This command hasn't yet been run for long enough to see whether it produces a properly-configured, working git svn clone. However, it's our best guess so far.

git svn clone --stdlayout --prefix="svn/" svn+ssh://

Issues with this command that need to be researched/addressed:

  • Apparently revision 2 creates a branch called "Glyph", which I can't find in the SVN browser in Trac. Not quite sure what's going on there.
  • My vague recollection is that there's some old, closed branches which cause problems for git svn because their names contain odd punctuation which gets doubly-URL-escaped somewhere... specifically, there's one branch that got created a number of different times because SVN couldn't really handle it either. Since they're old and closed, they can probably be ignored with the --ignore-paths=<regex> option.
  • We may want to supply a file that maps SVN usernames (glyph, exarkun) to the Git standard of real names and email addresses.
  • Twisted does not completely follow the standard SVN repository layout. In particular, there is a "branches/releases" directory that contains more branches (as opposed to being a branch) and a "tags/releases" directory that contains more tags (as opposed to being a tag).

After creating this clone, you'll want to make the same configuration changes listed for contributors above.

git svn branching

Follow the  standard Twisted branch-name conventions when creating branches with Git. In the following example, $BRANCH_NAME means the name of the branch you're trying to create.

# Create "branches/$BRANCH_NAME" in the central SVN repository.
git svn branch $BRANCH_NAME

# Create and checkout local branch "$BRANCH_NAME" that tracks "remotes/$BRANCH_NAME"
git checkout -b $BRANCH_NAME remotes/$BRANCH_NAME

git svn committing

No special rules apply about making Git commits, you can make as many commits as you like, then rebase them into a nice patch series as normal (although the Twisted review process generally reviews the diff of an entire branch, not individual commits, since rebasing isn't possible in SVN).

However, once you send your patches to the central SVN server with git svn dcommit, be very careful about messing with them. Don't rebase any further back than the last push, or else the next dcommit is likely to go awry.

Likewise, if you merge from trunk to branch, then dcommit the merge, it will become an ordinary commit that doesn't remember its ancestry, and merging it back onto the trunk later is likely to cause grief. So don't do that.

git svn merging forward

I haven't done this yet, but it probably needs special handling for the reasons mentioned in the previous section. Look at  this wiki for inspiration.

git svn branch merging

In the following example, $BRANCH_NAME means the name of the branch you're trying to merge to trunk.

# Check out the trunk (what git calls 'master'), make sure it's up-to-date.
git checkout master
git svn fetch && git svn rebase

# Apply all the changes on the branch to the trunk as one change set.
git merge --squash remotes/$BRANCH_NAME

# Commit the change set. Remember to use the Canonical Merge Commit Message Format!
git commit

# Push the commit to the central SVN repository.
git svn dcommit

By "Canonical Merge Commit Message Format", I mean the example merge commit message in  the Working From Twisted's Subversion Repository documentation.