Mercurial Queues

See Mercurial: The Definitive Guide, Chapters 12 and 13 and Appendix B.

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 <fake_email@abcdef.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

MercurialQueues (last edited 2012-01-10 16:28:29 by benjaminfjones)