Monthly Archives: April 2014

Know Your Tools: A Crash Course on Mercurial Patch Queues

Imagine that you just made and committed a new feature, and are halfway through your next super awesome feature when catastrophe strikes!  There’s something wrong with your previous feature that was just committed!  What do you do with your current uncommitted work?  You could shelve it, you could create a separate repository, or you could simply carry on and make note of the problem, promising to fix it later.  You have numerous options.

Let me introduce you to another option: “Mercurial Patch Queues!” he shouted with unmatched enthusiasm.

If you had done this local work as patches instead of commits, you could turn your unfinished working directory changes into a new patch, pop it off the applied stack (out of the working directory), fix your previous patch, re-apply the working directory patch, and then carry on with the work you were in the middle off.  Since you modified the patch itself, it’s as if your work was extra perfect the first time around.

In general, making use of these patches will allow you greater control over your changeset history.  You can think of it as a private mutable history that you’re free to manipulate however you like before you transform it into the normal shareable state.  Allowing you to get your changes just right before committing them, but still giving you advantages of source control.

Another use-case would be temporary “checkpoints”.  Let’s say you’re coding, and you want to save your current state, to protect yourself from future blunders, but this effort isn’t done yet and you don’t want to pollute the changeset history with numerous commits.  You want one commit that contains all of your related work.  For this, you can create a patch of the working directory.  If you’ve made a patch, and then later screw up, you can revert your code to the patch, just like you would a previous changeset.  So if you screw up later, you can revert to the patch that was made and try again.

Walk-through

Enabling the Extension:

In your mercurial preferences file: add

[extensions]
hgext.mq =

And then check it’s working with “hg help mq”

C:UsersmurchDesktopNew folder>hg help mq
mq extension - manage a stack of patches

This extension lets you work with...
Creating a Repository With a Patch Queue – “hg init –mq”:
  1. hg init (if it’s already a repository, skip to step 2)
  2. hg init –mq (Two dashes.  Enables the patch queue functionality in the given repository)
Creating a New Patch – “qnew”:
  1. hg qnew patchname.patch
Update the Patch With Your Work – “qrefresh”:

After making some changes in your working directory, you can use qrefresh to update the topmost patch so that it represents all of your changes.

Note: If your change includes things such as adding a file, you still use the same “hg add” command and then you would use “qrefresh”, so that the change in the patch is “add this file with these contents”.

If you want to apply the changes to a patch that isn’t the topmost patch, you can simply make use of qpush and qpop until the desired patch is at the top of the applied patch stack, and then use qrefresh.

Note: Try to rearrange the patch stack before you make your local changes, otherwise when you go to rearrange with qpop and qpush, you’ll get a message like so: “abort: local changes found, refresh first”.  You can force the operation with the -f flag, if you really need to.

Manipulate the Patch Stack – “qpop” and “qpush”:

When working on multiple simultaneous patches, these allow you to manipulate the currently applied patches in your working directory: qpop takes the latest applied patch out of the working directory, and qpush will apply the most recently popped patch back into the working directory.

Make use of the -a flag to push or pop all patches.

Delete an Unwanted Patch – “qdelete”:

You can use qdelete to delete an unwanted patch by name.

Convert a Patch Into a Normal Mercurial Changeset – “qfinish”:

You can use qfinish to convert an applied patch into a normal revision in the changeset history.

Convert a Changeset Into a Patch – “qimport”:

The exact opposite of applying a patch to the changeset history is to take a specified revision and convert it into a patch.  You can do this with qimport.

Note: You can only do this if Mercurial considers the changeset to be mutable.  Which more or less means you haven’t sent that changeset off anywhere, such as with a push.

Sources and Further Reading:

(HG Book – Managing Change with Mercurial Queues) http://hgbook.red-bean.com/read/managing-change-with-mercurial-queues.html

(Why would I want to use MQ?) http://mercurial.selenic.com/wiki/MqTutorial#Why_would_I_want_to_use_mq.3F

 

Know your Tools: An Introduction to Eclipse Templates

How often do you find yourself writing the same small piece of code over and over and over?

Never, because I follow the D.R.Y. methodology, or “Don’t Repeat Yourself”, so I-

Let me stop you right there.  I mean really small pieces of code.  Things like this:

System.out.println( message );

That’s a good couple dozen keystrokes, and I’m positive you write other recurring code snippets over and over.  For me a common one is a null and empty check on Collections:

if( CollectionUtils.isNotEmpty( bar ) ) {
	//Do some stuff
}

Let’s go back to the print line example and see how we can speed that up, using a built-in template. In Eclipse, simply type “syso” and then hit the content assist shortcut (ctrl + space). Eclipse will replace the “syso” with the only named template that has a match in its name, which is the above print line code.

To more easily see what’s happening, hit the content assist shortcut first, and then type “syso”.  First, you’ll see the familiar dialog pop up:

content assist

Then, while typing “syso”, you’ll notice the options fall away as Eclipse filters out options that don’t match, and you’ll be left with one option, a template:

content assist filtered

That template is then used to generate code for you.

Built-in Templates

There are numerous templates already available for you.  Such as quickly generating a for-loop.

content assist for loop

Hint: Hitting ctrl+space a second time will show you just templates.  

Writing Your Own

For when the built-in templates have failed you and there isn’t one that does what you want, you can write your own.  For example, the second code snippet at the beginning of this post makes use of the class “CollectionUtils”, which is an Apache Commons utility class.  There wasn’t a built in template for that.  So to make it, go to:

Window -> Preferences -> Java -> Editor -> Templates

preferences templates

Click on “New”, and create whatever template you like!  Here’s mine to check Collections for null or being empty:
custom template creation

Hint: “Insert Variable” can help you figure out those “${…}” values.

Which is now in the content-assist window and will allow me to rapidly check future collections before I begin to use them:
custom template in action

In Conclusion

Using templates, both built-in and custom, can save you a lot of time and keystrokes.  Try ’em out.