WARNING (July 2014)
This page is obsolete, as Sage is now using Git instead of Mercurial as a version control system.
- qnew, qpop, qpush, qdelete, qimport, export
- Advanced usage
- guards, merge, etc.
See also Being more efficient: Mercurial queues in the Sage Developer's Guide (written by Rob Beezer).
The mercurial bash completion script is at http://www.cct.lsu.edu/~mkemp2/mercurial
Sample mercurial queue workflows
Before using mercurial queues, create/edit the file .hgrc in your home directory to contain:
[ui] username = John Smith <firstname.lastname@example.org> [extensions] mq = [diff] git = true
Provide your own details under username (patches you create will credit this field as author).
Next, go to the mercurial repository you want to work on (in our example, the Sage library) and initialize queues:
# cd into the repository cd sage/devel/sage/ # initialize the queues. This only needs to be done once for each repository. hg qinit
You're now ready to go. (Make sure the files you want to work on are not set to be ignored in a .hgignore file!) See the following examples for some typical use scenarios, and don't hesitate to ask questions on sage-devel if you get stuck.
Writing or editing code
# cd into the directory I am working in cd sage/devel/sage/sage/graphs/ emacs graph.py # write my function, save the file # The -e pops up an editor for me to enter a commit message # The -f retroactively saves my changes as a patch # (the changes visible in hg diff) hg qnew -e -f mypatch.patch # RUN THE DOCTESTS!!! sage -b sage -t graph.py # Happily all the doctests pass :) # Review the patch in diff format hg qdiff # Oops, I see a mistake in my patch! emacs graph.py # fix mistake # refresh the patch to reflect my current source # Do hg qrefresh -e to edit the commit message hg qrefresh # Export the tip of the queue (the last patch) hg export qtip > ~/mypatch.patch # Now I can upload the patch to trac or email it to someone else # If I want the patch to be unapplied, pop it off of the stack hg qpop # Now my source is back to where it was when I started. # To also bring the Sage library to its initial state, I run sage -b
Reviewing a patch from trac or somewhere else
# Download the patch from trac (in RAW format) and save to, e.g., newpatch.patch # cd into the repository cd sage/devel/sage/ # Pop off all my patches so I have a pristine release hg qpop -a # import the new patch hg qimport ~/newpatch.patch # apply the new patch hg qpush # build and run sage sage -br # or doctest a file sage -b sage -t file.py # pop the experimental patch off of the stack hg qpop # delete the patch hg qdelete newpatch.patch # bring the Sage library back to normal sage -b
Folding several patches into one
# If the patches are on trac, download them in RAW format # Say they are called one.patch, two.patch, three.patch in some # directory ~/downloads # cd into the repository cd sage/devel/sage/ # if it hasn't been already done, hg qinit # create a new (initially empty) patch in the queue hg qnew combined.patch # import the new patches (if they're coming from trac, say) hg qimport ~/downloads/one.patch ~/downloads/two.patch ~/downloads/three.patch # let's see what's in the queue series hg qseries [hg replies:] combined.patch [hg replies:] one.patch [hg replies:] two.patch [hg replies:] three.patch # fold the patches into combined.patch (they get applied in order) hg qfold one.patch two.patch three.patch # the previous step can also be done one-at-a-time, of course # combined.patch is the only applied patch now, containing all the others hg qapplied [hg replies:] combined.patch # the folded patches are also removed from the queue series hg qseries [hg replies:] combined.patch # now we go on with the usual things sage -b # rebuild sage -t ... # test hg qrefresh # if files were edited hg export qtip > ~/uploads/combined.patch # make a physical patch file with all the changes hg qpop # get back to the initial state of the repository sage -b # rebuild # upload ~/uploads/combined.patch to trac