Edit history with Mercurial Evolve (Beta) in Bitbucket Cloud

By on March 28, 2017

Mercurial patch queues (MQ), even though they are deprecated, have long been the only way to share your not-yet-ready-to-land commits via Bitbucket. Patch queues have a long history of being thorny to use because they were developed for version control techniques that have been out of date for quite some time. Rising from the ashes of Mercurial patch queues and forged from the painful experience of “git push -f”, we are launching evolve in hopes of providing a better experience for Mercurial users. 

What does this mean for you? You’ll be able to edit the history for a pull request before merging it. You can rebase, if that’s your fancy. Plus, this paves the road for us to enable new merge options, like our new squash merge in pull requests.

Where to get evolve

After calming down a bit, it’s important to note that evolve is still in Beta in both Mercurial and Bitbucket. To facilitate rolling out this Beta feature as we do our other features in Bitbucket, we decided to write an extension to make integrating Mercurial’s configuration with our per-user labs settings. I call this magic hgenvconfig – a very simple extension that even has tests! (For the technically curious: the way “hgenvconfig” works is by adding our per-user configuration to an environment variable. Our Mercurial extensions and hooks are then able to read from this variable by the fact that subprocesses inherit environment variables from the main thread.)

With this extension, we were able to add evolve to our lab settings so we can help get evolve hardened for all Mercurial users. Our hope is that as this gets more testing, evolve will move out of experimental status in Mercurial. We need your feedback on terminology, UX, and bugs (of course). To start using it, first install evolve by running “pip install hg-evolve” then head to your account settings, Bitbucket Labs, and enable Mercurial Evolution Support.

Getting the most out of evolve

How is evolve different from “git push -f”? For starters, “git push -f” behaves just like your favorite FTP server: last one to write wins. In contrast, Mercurial marks commits as “replaced” by using an append-only store. Let’s see how this works (without getting too technical here):

Figure 1: unsafe history modification with core Mercurial (not using evolve): the original revision 1 is destroyed, similar to git when the reflog is cleaned.

Figure 2: safe history modification using evolve: the original revision 1 is preserved as an obsolete changeset providing more history than git. (The “temporary amend commit”, marked with T, is an implementation detail stemming from limitations in Mercurial’s current merge machinery. Future versions of Mercurial will not create them.)

Similar to “git push -f”, evolve is an advanced feature and editing history is tricky. Evolve is built on the Mercurial concept of phases. In preparation for evolve a little while ago, I switched the default state of new Mercurial repositories to be non-publishing (e.g. draft commits by default).

To get the most out of evolve, make sure to read up on the evolve concept of unstable. Simply put, this is analogous to a “rebase” that is in-progress. It represents, as the name suggests, an unstable state of your repository and should be used carefully. If you stick to “rebase” and “histedit” commands, then it should be rare to end up in this state and be safe to use.

Evolution ain’t easy

In order to help make features like this accessible to the community in the future, including through further development of the Mercurial platform, Bitbucket has made a charitable donation to the Software Freedom Conservancy. We’re proud to support the Software Freedom Conservancy and promote the development of platforms like Mercurial, and encourage you to keep a look out for advancements to come.

If you are new to Bitbucket, sign up for Bitbucket here or if you are already a Bitbucket user, head to your account settings, Bitbucket Labs, and enable Mercurial Evolution Support. It’s time to evolve.

Get started, it’s free

Have more specific questions about this post? Reach out to us on Twitter to get the information you need