[eigen] using mercurial queues

[Benoit Jacob <jacob.benoit.1@xxxxxxxxx>]

Hi,

*** what follows is for experienced mercurial users only. With MQ, you
can lose work, and you can even wreak havoc in a remote hg repo! ***

next in my series "modernize our development processes"...

If we're going to move to a tracker with long patch discussions, that
means we're going to keep patches floating around for some time before
we agree on a solution.

So far, we had only two ways to do this:
 - manually apply/unapply uncommitted patches. Not convenient.
 - create a hg fork where we commit experimental work. The problem is
that this encourages us to work for several days alone before we
commit, because we don't want to commit silly stuff, not even to a
fork. This has generally meant that only 1 person worked on a given
experimental fork.

Enter MQ (mercurial queues).

MQ creates a separate hg repository in your local hg repository,
specifically under .hg/patches/.  Think of it as a specialized hg repo
to handle patches before you want to commit them to the actual hg
repo.

Typical workflow:

1. Enable MQ: in your hgrc put:
[extensions]
hgext.mq =

2. Create MQ repo: enter your local hg repo, and do:  hg qinit -c

3. Now code something (i.e. make changes in your working copy).

4. Create a MQ patch from your changes:   hg qnew -f my-wonderful-improvements

5. Now you can see your patch, ready to be sent for review, in
..hg/patches/my-wonderful-improvements

6. Now you want to make changes in this patch. Just edit your working
copy, and when you're done, do:
         hg qref
    Now your patch is updated, ready to be submitted again.

7. Now you want to work on another patch. Just edit again your working
copy and when you're done do again:
     hg qnew -f my-other-patch

8. Now you want to see the patches in your queue, do:  hg qseries

9. You would like to know which of these patches are currently applied
to your working copy, do hg qapplied  (there also is hg qunapplied)

10. To unapply the topmost patch, do:   hg qpop   (to unapply them
all, do hg qpop -a)

11. To apply the first unapplied patch, do:   hg qpush   (to apply
them all do hg qpush -a)

12. You would like to add a commit message to a patch?  Do:  hg qref -e

13. After this, you would like to turn it into a permanent changeset,
do:  hg qfinish qbase

14. You have done a bad qfinish! Don't worry, just make sure you have
no patches applied, and do:   hg qimport -r tip

**** YES, 14 IS VERY DANGEROUS! YES THAT MEANS THAT YOU CAN IMPORT ANY
EXISTING CHANGESET INTO MQ AND MODIFY IT! ****

15. Somebody attached a patch file some-buggy-patch, you would like to
import it, do:  hg qimport ~/path/to/some-buggy-patch

16. You want to reorder your patch queue. Say you have patch1, patch2,
patch3 in your queue, and you want to have only patch3 applied.
Problem: if you do
          hg qpush patch3
     that will push patch1 and patch2 too, because this is a queue.
Solution: make sure you have mercurial 1.6 and do:
          hg qpush --move patch3

17. You have patch1 and patch2, you want to merge patch2 into patch1,
go to patch1 (hg qpush patch1  or hg qpop patch1 depending on where
you are) and do:
         hg qfold patch2

18. You have big-patch touching files file1 and file2. You want to
split it into two patches touching one file each. Do:
         hg qref -X file2      # take out of current patch, into
working copy, all changes made to patch2
         hg qnew -f patch2  # take these changes into new patch2

19. Rename a patch:  hg qmv


Good reading:  https://developer.mozilla.org/en/Mercurial_Queues

Benoit