Contribute > Development > DVCS Workflows > Git

  1. For Twisted contributors
    1. Creating a Git clone
    2. Updating your Git clone
    3. Submitting Patches
  2. For Twisted core developers
    1. git svn branching
    2. git svn committing
    3. git svn merging forward / solving conflicts
    4. git svn branch merging
    5. reverting - reopening ticktes

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 has an up-to-date mirror on github.

  1. Create a Git clone of the repository by running this command:
    git clone Twisted
    This should create a subdirectory named Twisted containing the latest trunk revision of the code.
  2. 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

Note: this can make tools like magit work in odd ways.

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 fetch
git checkout trunk
git rebase origin/trunk

Submitting Patches

Twisted core reviewers do not watch the GitHub pull request list. However, if you wish, you can submit a pull request to the Twisted project, and link to the pull request in a Twisted ticket when marking it for review.

If you like, you can instead attach a patch directly to the ticket:

While on the branch for which you want to generate a diff

git diff origin... > destroy-the-sun.patch

or, if there is already a branch in svn,

git fetch
git diff origin/destroy-the-sun-5000.. > destroy-the-sun-v666.patch

and then attach the patch to the appropriate ticket.

For Twisted core developers

Start by reading the general commiter check list

Event if you will use git, you still need to have SVN installed, as at least mkbranch needs it.

To be able to interact with svn, the following commands need to be run in the repository created above, replacing USERNAME with your SVN account name.

git svn init --stdlayout --tags tags/releases --prefix origin/ \
    --rewrite-root=svn:// \
git svn dcommit -n

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). Thus, git cannot be used to commit to release branches.

You also should set a global config to tell git-svn to remove directories that have been made newly-empty, since git doesn't track directories, while svn does:

git config --global --bool svn.rmdir true

git svn branching

Follow the standard Twisted branch-name conventions when creating branches with Git.

Use the mkbranch utility from twisted-dev-tools. Use it as follows:

mkbranch $BRANCH_NAME
git fetch
git checkout $BRANCH_NAME

git svn committing

git commit only makes local commits. To get commits into svn,

git svn dcommit --dry

will (update git-svn's metadata cache and) show where git will try to commit, and the list of commits it will push.

git svn dcommit

will actually push the changes to svn.

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 / solving conflicts

"Merging forward" means rebranching trunk and merging your changes in. It has roughly the same effect as merging trunk into your branch in git. Doing it this way works more reliably with svn.

In case your old branch conflicts with trunk, you will need to create a new branch merge it forward. Don't merge trunk into your branch in git using the usual git merge command. This will not fix the conflicts in SVN, but only on your local GIT branch.

mkbranch $BRANCH_NAME-2
git fetch
git checkout $BRANCH_NAME-2
git merge --ff --squash origin/$BRANCH_NAME
git commit -m'Merging forward'
git svn dcommit

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 origin/trunk

# Apply all the changes on the branch to the trunk as one change set.
git merge --ff --squash origin/$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 review process.

reverting - reopening ticktes

In the unfortunate event of breaking trunk the commit which cause the failure should be reverted as soon as possible and the fix merged in a separate commnit.

Identify the git SHA revision number of the commit which introduce the error and revert that commit.

git revert a1b2c313
# Edit the new commit message
# Then push the changes.
git svn dcommit

As the commit message use the standard format as described in ReviewProcess

For now the commit message will contain the SVN ID. The SVN revision ID look for the git-svn-id comment from the commit message.

Last modified 2 months ago Last modified on 02/25/2016 10:23:25 AM