Mercurial Patch Queue Use Cases

Question

I use mercurial patches in the following cases:-

1. When I need to pull from a remote repository and have outstanding uncommitted changes. Then I simply create a patch, qpop it, pull from the remote repository, and then import the patch again.
2. When I need to upload patches to reviewboards. I simply make a patch and upload it.

How else do you use Mercurial Patch Queues? I feel that its a very powerful Mercurial extension and that I am not using it to its fullest potential.

Answer 1

The Mercurial wiki has a good section on use cases:

In summary:

1. Saving the current state of the working copy so you can easily revert to it later on
2. Preventing a "tangled working copy" - if you're halfway through a change and want to change something else
3. Provide mutable, rearrangeable commits so you can get 'history' looking just right before pushing.

Answer 2

You don't really need Mercurial patches for this. If you have outstanding uncommited changes when you pull, they will be merged with the tip.

Example:

C:\>hg init db
C:\>cd db
C:\db>echo >file1
C:\db>echo >file2
C:\db>echo >file3
C:\db>hg ci -Am codebase          # Create a code base with 3 files.
adding file1
adding file2
adding file3
C:\db>echo a change >>file2       # Outstanding change to file2.
C:\db>hg st
M file2

At this point we'll clone the database and commit a change that we can pull.

C:\db>hg clone . \db2
updating to branch default
3 files updated, 0 files merged, 0 files removed, 0 files unresolved
C:\db>cd \db2
C:\db2>echo a change >>file3
C:\db2>hg ci -m "file3 change"    # Commit a change to file3.

Back in the original database...

C:\db2>cd \db
C:\db>hg st                       # Still have uncommitted change
M file2
C:\db>hg pull \db2
pulling from \db2
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
(run 'hg update' to get a working copy)
C:\db>hg st                       # We have the new history, but haven't updated.
M file2                           # file2 has uncommitted change.
C:\db>type file3                  # file3 is unchanged. 
ECHO is on.
C:\db>hg update
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
C:\db>hg st                       # We've updated, and file2 *still* has
M file2                           #    uncommitted change.
C:\db>type file2
ECHO is on.
a change
C:\db>type file3                  # But file3 now has committed change
ECHO is on.                       #    that was pulled.
a change

So the moral is, you can just pull and update, even with uncommitted changes. If there are merge conflicts, normal merge behavior occurs as well.

For patch exporting hg export <rev> will export patches for review.

Answer 3

When you create a patch queue on Bitbucket, it lists some of the common uses for patch queues in the right pane. Their explanation is very good and answers your question directly. Quotes from it are below.

Patch queues are good for:

• Developing features you intend to submit for upstream review

  Because patches in patch queues can be modified, they provide an ideal way to develop a feature in a history-tracked manner, while still allowing you to easily incorporate feedback

• Experimenting with adding a new feature

  Patch queues don't clutter your project's history, so you can safely use them as a way to quickly try out an idea, and keeping it in version control, without cluttering up your project's history with failed excursions. If you decide to keep the experiment, you can easily turn a patch queue into a set of traditional Mercurial commits

• Maintaining private customizations for another project

  Because patch queues are not part of the official change log for a project, they are ideal for maintaining private customizations for an upstream project. For example, you might maintain a patch queue that makes program better integrate with your company's workflow

Patch queues are not good for

• Long-running branches

  Because patch queues are highly volatile, they do a poor job tracking the long-term history of your source code. For this reason, long-running branches, such as those that correspond to product releases, should be kept in repositories or named branches.

• Group development

  Patch queues do not track merge history, which makes them a poor choice for doing group development, where you really wish to see when a given set of features was merged into a repository. When in doubt, you should stick to a traditional fork, but mastering the power of patch queues will give you tremendous flexibility in your workflow, and provide you with greatly enhanced collaboration abilities.

Answer 4

MQ is a great tool to manage concurrent development. Blatant self-plagiarism and self-promotion from my own answer:

3 Use MQ with one patch (or multiple consecutive patches) per project.

• Pros: simple and easy.
• Cons: must qrefresh before switching and rebuild after; tricky and risky if projects are not orthogonal.

4 Use one MQ branch per project.

• Pros: ultra flexible and scalable (for the number of concurrent projects)
• Cons: must qrefresh and qcommit before switching and rebuild after; feels complicated.

Answer 5

I use MQ for developing on top of a big Subversion repository I don't want to checkout with hgsubversion or something similar. In my working folder I initiate a new .hg repo and a Mercurial Patch Queue. I track the svn revisions with HG and my patches are on top. Whenever I feel to update the svn state, I pop all the patches, run svn update and push and refresh the patches again. When I'm confident my series is okay for commit, I can qfinish my patches one by one. (Currently a new Subversion feature "shelve" is under development, but every time I tried that, it did not work well enough, so I still use that MQ approach.)