Mercurial Branches

This page documents how to use Mercurial, rather than Subversion, to hack on Django. See also DjangoBranches.

Core developers

For people who are core committers, and want to use Mercurial rather than Subversion as their client:

1. Install the ​hgsubversion extension (and understand basically how it works).
2. Clone the Subversion repository (do this using hg version 1.5 or higher, or else the changeset hashes generated by hgsubversion will be incompatible with those from repos generated using newer hg versions, including the ​official Django hg mirror).:

   hg clone svn+http://code.djangoproject.com/svn/django/ django
   

   This will take a Good While (lots of hours), and in some cases can take a Very Long Time for just one changeset (I gave up on r11505).
   ALTERNATIVELY:
   1. Clone the ​official Django hg mirror in the normal way, using hg 1.5 or greater.
   2. Edit .hg/hgrc to say:

      default = svn+http://code.djangoproject.com/svn/django/
      

   3. Do hg svn rebuildmeta. This works because the official Django mirror was been created by hgsubversion, and is updated only by hgsubversion.

3. Use normal hg commands to make commits, switch branches, push back to the subversion repository etc. Remember to use hg rebase --svn, and not hg merge.

Tips

• Use the ​bookmarks extension for git-style local feature branches, or named branches for feature branches that you need other people to see.
• Alternatively, use the ​queues extension to manage long lived patches.
• To collapse several commits into a single commit before pushing back to svn, use the ​histedit extension
• To backport a changeset from trunk, use the ​transplant extension. Or use this handy script which will generate the commit message for you:

  #!/bin/bash
  
  function usage {
      echo "Usage: hg_backport <branch> <hgrevision>";
  }
  
  if [ $# -ne 2 ]
  then
          usage;
          exit 1;
  fi
  
  SHORTBRANCH="$1"
  BRANCH="releases/$SHORTBRANCH" # we only backport to release branches.
  HGREV="$2"
  
  hg st -a -r -m | grep '' > /dev/null && { echo "Working directory not clean - exiting" > /dev/stderr; exit 1; }
  
  SVNREV=`hg svn info -r $HGREV | egrep '^Revision' | cut -f 2 -d ' '`
  if [ "x$SVNREV" = "x" ]
  then
          echo "Can't find svn rev";
          exit 1;
  fi
  
  echo "Backporting Subversion revision $SVNREV"
  hg update $BRANCH || exit 1;
  # Make a commit message first in case the transplant fails.
  hg log -r $HGREV --template "[$SHORTBRANCH] {desc}\n\nBackport of [$SVNREV] from trunk\n" > hg-commit-message.txt || exit 1
  hg transplant $HGREV || exit 1;
  # Modify the commit message
  hg rollback > /dev/null || exit 1
  hg commit -l hg-commit-message.txt || exit 1
  echo "Backport committed."
  

  The command line is like:

  hg_backport 1.2.X 13643
  

  where 1.2.X is a directory under 'releases/' in the Subversion repo, and 13643 is a hg revision ID. The change is already committed to the local repo, but not 'pushed', so you can still rollback if changes need to be made.

An alternate approach

Another way of doing the same thing: Use the --filter option to the transplant extension. This requires the use of a Python script. Put the following in backport.py, and stick it in a tools directory somewhere:

#!/usr/bin/python
import os
import sys

msg = sys.argv[1]
patch = sys.argv[2]

print
msg_file = open(msg, 'r')
outlines = []
firstline = True
for raw_line in msg_file:
    line = raw_line.strip()
    if firstline:
        if line.startswith('#'):
            outlines.append(line)
        else:
            firstline = False
            print 'MERGING: %s' % line
            outlines.append('[1.2.X] %s' % line)
    else:
        outlines.append(line)
msg_file.close()

svn_revision = os.environ.get('SVNMERGE_REVISION',None)
if svn_revision is None:
    svn_revision = raw_input('SVN Revision: ')
else:
    print "SVN Revision:", svn_revision
outlines.append('')
outlines.append('Backport of r%s from trunk.' % svn_revision)

# And write the updated message file.
msg_file = open(msg,'w')
for line in outlines:
    print >> msg_file, line
msg_file.close()

# In case of a clash, write the filename of the message file
print "Log message written to",msg

Then, use the following shell script to do the actual backport:

#!/bin/bash
export SVNMERGE_REVISION=`hg svn info -r $1 | egrep '^Revision' | cut -f 2 -d ' '`
hg transplant $1 --filter /path/to/backport.py
unset SVNMERGE_REVISION

If you call this script 'hg_backport', then

The command line is like:

hg_backport 13643

Any hg revision ID can be used as the argument; since the most common usage pattern is to backport the most recent svn commit on trunk, you can use 'tip':

hg_backport tip

This script needs to be manually updated after every release, because the [1.2.X] string is hardcoded. This is mostly due to my (Russell's) own laziness -- it would be trivial to update the script to pull the branch identifier from the output of hg branch.

Gotchas

If you make two commits, and only want to push the first, you will have some trouble, since the HgSubversion extensions doesn't support specifying revisions with the hg push command when pushing to a Subversion repository. Nice solutions to this welcome!