mercurial tips from hgtip.com

Debug Command Tricks

2010-04-23T00:00:00Z

If you tried hg help --debug, you may be familiar with the commands prefixed with ‘debug’. Most of them are used to inspect Mercurial’s internal storage, but some can come handy in certain situations. Two of these commands are hg debugsetparents and hg debugrebuildstate.

The first command forces Mercurial to forget the “real” parent revisions of a working-copy in favor of the specified revisions in ‘debugsetparents’. The second command is forcing Mercurial to rebuild its internal state.

So how can this be useful in normal conditions at all? Here are 3 scenarios where it comes handy to work with them:

1. Late-binding working-copy with repository.

Imagine an interesting project hosted with Mercurial. At first you only download a snapshot of the project to inspect the code and try something out. You didn’t clone it fully, because you wanted to avoid the overhead to just check the source.

Later in the process of playing with the code, you realize that this is going to be a longer-lasting relationship, so you decide to clone the repo and commit your changes. Since it is quite a big working-copy and you renamed/deleted/added some files, you don’t want to copy the whole thing over some checkout in order to not confuse the working-copy state. So how to commit this state at the proper location?

The solution is to copy the .hg folder into the snapshot’s root and issue:

$ hg debugsetparent tip
$ hg debugrebuildstate
$ hg commit -Am "my snapshot"

2. Creating alternate check-ins.

If you are anything like me, you don’t trust yourself. Therefore, you’d want to add alternative work BEFORE you delete one of the alternatives. So the usual workflow of using rollback to take back an ill-composed commit is not your thing.

Instead, it is possible to simply:

$ hg debugsetparent tip^^
$ hg debugrebuildstate

And you are back at the state you where before you commited, just with the “wrong” commit still there.

3. Simulate Git’s —no-ff merges with anonymous heads.

Most of the workflows for Git are easily reproducible with Mercurial, but some of them (gitflow) use so-called “non-fast-forward” merges. These merges can be done in Mercurial, too, but only with named-branches:

$ hg sl
$ echo x > x
$ hg ci -Am "base"
adding x
$ hg branch feature
marked working directory as branch feature
$ echo y > x
$ hg ci -m "feature"
$ hg up default
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ hg merge feature
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)
$ hg ci -m "merged"
$ hg glog
@    changeset:   2:e0502e1d12c6
|\   tag:         tip
| |  parent:      0:387ca709aeaf
| |  parent:      1:205ec0dce78f
| |  summary:     merged
| |
| o  changeset:   1:205ec0dce78f
|/   branch:      feature
|    summary:     feature
|
o  changeset:   0:387ca709aeaf
   summary:     base

As you can see in the above graphlog output, the merge contains no actual information besides indicating the merging of two named-branches (‘default’ and ‘feature’). As with Mercurial 1.5.1, you can’t do that with anonymous heads:

$ echo x > x
$ hg ci -Am "base"
adding x
$ echo y > x
$ hg ci -m "feature"
$ hg up 0
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ hg merge 1
abort: nothing to merge (use 'hg update' or check 'hg heads')

Why would you want to do that with anonymous heads, anyway? Well, one way of simulating Git branches is the bookmark extension. Unfortunately, using bookmarks (to name anonymous heads) is still using anonymous heads, so the above problem gets in your way:

$ hg bookmark master
$ hg bookmark feature -r 1
$ hg bookmark
 * master                    0:6965ee5bb884
   feature                   1:2061809a8e23
$ hg merge feature
abort: nothing to merge (use 'hg update' or check 'hg heads')

The solution:

$ hg debugsetparents master feature
$ hg revert -a -r feature
reverting x
$ hg ci -m "merged"
$ hg glog
@    changeset:   2:0dfae55684f6
|\   tag:         master
| |  tag:         tip
| |  parent:      0:6965ee5bb884
| |  parent:      1:2061809a8e23
| |  summary:     merged
| |
| o  changeset:   1:2061809a8e23
|/   tag:         feature
|    summary:     feature
|
o  changeset:   0:6965ee5bb884
   summary:     base

Keeping Informed with Progress

2010-03-24T00:00:00Z

Sometimes when using Mercurial it seems to sit at the command prompt for quite some time as it churns over some files. Thankfully, since Mercurial 1.5 you can now take advantage of a new extension! You’ll want to edit your ‘~/.hgrc’ file to contain something like this:

[extensions]
progress =

When this nifty little extension is enabled you should see something like this:

Notice the nice new progress bar? Here’s another little example:

I hope you find this little tip useful and it helps you in your daily usage of Mercurial. For more information on this extension, you can refer to its page on the Mercurial website.

Merging MQ Patches with Rebase

2010-02-11T00:00:00Z

First of all: I want to try something new with this tip. This is the first tip that includes a screencast. It’s a complex topic and I think a screencast is the best way to talk about it. Please post a comment and let me know if you like it or if you think hgtip should stick to text-only tips!

This tip is for those of you that are familiar and comfortable with using MQ to handle patches. If you use MQ regularly you may have noticed some problems. One of the biggest problems appears when you have some patches and someone else commits something that changes the files you’re working on.

The normal workflow is to pull their changes, qpop your patches, update to the new repository (or branch) tip, and qpush your patches. Unfortunately MQ doesn’t keep track of the parents of patches, so it can’t intelligently merge changes when you qpush.

The way to get around this limitation is to use the rebase extension to rebase your MQ patches while they’re still applied. I’ll demonstrate how to do this in the screencast below:

Styling Mercurial’s CLI

2010-01-15T00:00:00Z

Mercurial has a great command line interface and many people use it without ever feeling the need for a GUI to manage their repositories. However, we can make it even better by taking advantage of Mercurial’s templating features.

In this tip I’m going to post some of the templates I use and show you how to use them yourself. Check out hg help templating if you want more details on how the templating actually works.

If you like what you see you can grab my templates by cloning their repository from BitBucket:

hg clone http://bitbucket.org/sjl/mercurial-cli-templates/

NOTE: I’ve customized the colors of my Terminal, so the colors will look different for you. If you like the colors I’m using you can read the blog entry I wrote about it.

Short Log
Nice Log
Short Graphlog
Contribute

Short Log

In a previous tip I described how to create an hg slog alias that can be very useful for counting changesets. With the right styling it can be useful in your day-to-day work. Here’s what the output of my hg slog command looks like:

To use this template you can edit your ~/.hgrc file to contain the following:

[alias]
slog = log --style=/full/path/to/map-cmdline.slog

Nice Log

The short log is great a quick review of the past few changesets, but for a much more detailed view of a particular changeset I’ve created an hg nlog alias, which looks like this:

To use this template you can edit your ~/.hgrc file to contain the following:

[alias]
nlog = log --style=/full/path/to/map-cmdline.nlog

Short Graphlog

The graphlog command is wonderful for reviewing the history of repositories with branches, but we can make it more compact and easier to read with another template. The result looks like this:

To use this template you can edit your ~/.hgrc file to contain the following:

[alias]
sglog = glog --style=/full/path/to/map-cmdline.sglog

Contribute

If you have any other templates you find useful, or some improvements to mine, feel free to fork the repository on BitBucket!

Finding Uncommon Changesets

2009-12-09T00:00:00Z

This post was inspired by an email on the mercurial-devel mailing list.

The question in a nutshell is: how can you determine which changesets are included in revision X but not included in revision Y? This could be useful if you’re updating a piece of software you use and want to know everything that changed between the old revision and the new one.

It sounds like a simple task, but there are a few tricky things that you need to watch out for.

Note: In this tip I’ll be using the shortlog alias instead of the normal hg log command to make the output more readable. Everything will work exactly the same with hg log (because hg slog is just an alias to hg log with an extra template), so feel free to use that instead if you prefer more detail.

The Simple (and Incorrect) Way

Let’s start with the simplest way to list revisions: the --rev option. Say we have a simple repository whose graph looks like this:

$ hg glog
o  4 Fix another bug. (6 seconds ago by Steve Losh) tip 
|
o  3 Fix a bug. (16 seconds ago by Steve Losh)  
|
@  2 Add another simple feature. (34 seconds ago by Steve Losh)  
|
o  1 Add a simple feature. (40 seconds ago by Steve Losh)  
|
o  0 Initial revision. (7 minutes ago by Steve Losh)

If you’re currently at revision 2 and want to know what changes would be included if you updated to tip, you might use something like this:

 $ hg slog --rev 2:tip
 2 Add another simple feature. (5 minutes ago by Steve Losh) 
 3 Fix a bug. (5 minutes ago by Steve Losh) 
 4 Fix another bug. (5 minutes ago by Steve Losh) tip

You can see that the output includes revision 2, which really shouldn’t be listed because it’s the one you’re already at. This probably isn’t a big deal because you can just ignore it.

However, this approach doesn’t work if you have multiple branches in the repository that are being worked on simultaneously. For example:

$ hg glog
@  6 Fix a critical bug. (1 second ago by Steve Losh) tip 
|
| o  5 Start the rewrite of the UI. (24 seconds ago by Steve Losh)  ui-rewrite
| |
o |  4 Fix another bug. (8 minutes ago by Steve Losh)  
| |
o |  3 Fix a bug. (8 minutes ago by Steve Losh)  
| |
o |  2 Add another simple feature. (9 minutes ago by Steve Losh)  
|/
o  1 Add a simple feature. (9 minutes ago by Steve Losh)  
|
o  0 Initial revision. (16 minutes ago by Steve Losh)

$ hg slog --rev 2:tip
2 Add another simple feature. (9 minutes ago by Steve Losh) 
3 Fix a bug. (9 minutes ago by Steve Losh) 
4 Fix another bug. (9 minutes ago by Steve Losh) 
5 Start the rewrite of the UI. (54 seconds ago by Steve Losh) 
6 Fix a critical bug. (31 seconds ago by Steve Losh) tip

Notice that the output of the hg slog command included changeset 5. It’s on a separate branch, so updating from 2 to tip (6) won’t actually include changes from 5.

This happens because when you specify a range of revisions Mercurial will step through them in the revision-number order. That means saying 1:4 really means “1, 2, 3, and 4 no matter which branches they happen to be on.”

We can do better than this by using some extra hg log options.

The Correct Way

If we step back and think about the problem we’re trying to solve, we can reduce it to a simple definition. We want to see all changesets that:

Are included by (i.e. ancestors of) the destination revision.
Are not included by the source revision.

To solve the first problem, we can use a combination of two options, --rev and --follow, like so:

$ hg slog --rev tip:0 --follow
6 Fix a critical bug. (11 minutes ago by Steve Losh) tip
4 Fix another bug. (20 minutes ago by Steve Losh) 
3 Fix a bug. (20 minutes ago by Steve Losh) 
2 Add another simple feature. (20 minutes ago by Steve Losh) 
1 Add a simple feature. (21 minutes ago by Steve Losh) 
0 Initial revision. (28 minutes ago by Steve Losh)

Notice how the extra changeset on the other branch isn’t shown.

Using --rev DESTINATION:0 with --follow means “show me every changeset that is an ancestor of DESTINATION“. Check out hg help log for the details of what each option does.

We’ve still got one more thing to do — we want to remove changesets that are already included in our current revision from the list:

$ hg slog --rev tip:0 --follow --prune 2
6 Fix a critical bug. (16 minutes ago by Steve Losh) tip
4 Fix another bug. (25 minutes ago by Steve Losh) 
3 Fix a bug. (25 minutes ago by Steve Losh)

That’s it! Changesets 6, 4 and 3 are the changesets that will take effect if we update from 2 to 6 in our sample repository.

The general form for this command looks like this:

hg slog --rev DESTINATION:0 --follow --prune SOURCE

Of course you can use all the normal shortcuts for specifying revisions. If you want to see would be included in an update to tip from the current revision you’re working on:

hg slog -r tip:0 -fP .

Note: this command won’t work if you’re updating “backwards”. It can only show you additional changesets that would be included — it will not mention changesets that are included in SOURCE but not in DESTINATION.

Handling Binary Files in a Merge

2009-11-30T00:00:00Z

Say you’re building a website and you keep your images in the Mercurial repository for the site. Eventually two people are going to change that file at the same time and have a merge conflict.

Setting up Mercurial for Different Merge Tools

In your ~/.hgrc file, you should add the following section:

[merge-tools]
diff_images.args = $output $other

[merge-patterns]
**.png = diff_images

Now, create a diff_images shell script, set it to executable, and put it on your $PATH. Mine is:

open -a GraphicConverter $1 $2 -W 
# opens the first and second parameter with GraphicConverter, waiting
# until same is quit before letting the shell continue.

Now a merge that contains .png files that conflict will open up GraphicConverter. There will be two images that open up: one as it exists in the your source tree now, and one from Mercurial. You can tell the difference because the one from Mercurial will have a lot of random-seeming letters after the file extension. For example, if your conflicting file is image.png, GraphicConverter will open up two windows: image.png and image.png~other.bQkQxd.

Manually move your changes from the new file into the original file (image.png), saving the original when done and quitting GraphicConverter. These are the changes that will be committed.

How this Setup Works

First, diff_images.args sets up two parameters to pass into the graphics tool:

$output is the file that Mercurial will commit, and contains the version from the first parent.
$other is the version from revision you are merging in.

There are other options that the .args parameter provides:

$local is a copy of $output, but changes to this file will be ignored in the merge.
$base is the file from the revision right before the contents of the file diverged.

You could use these to set up a three way merge, if you desired, or enhance diff_images to show the user the contents of the file before this merge mess happened.

Next, the [merge-patterns] section associates what merge tool to use when a file name matches a particular pattern.

Without the merge-pattern section, diff_images would be considered for a diff candidate, but skipped over because Mercurial will assume that diff_images can’t handle diffing binary files. Adding lines to [merge-pattern] will tell Mercurial that diff_images can handle the file types specified.

Instead of putting in a merge-patterns section, you could add a line, like diff_images.args, that tells Mercurial that diff_images can handle binary documents: diff_images.binary = True

However, this will make diff_images a candidate for all binary differences, which GraphicConverter may not be up to (for example, diffing mp3s would not be a good task for GraphicConverter).

When Things Go Terribly Wrong: Aborting the Merge

Merges can not be aborted via the standard hg revert mechanism. Try it and you’ll get:

$ hg revert --all
abort: uncommitted merge - please provide a specific revision

But you just want to blow away your merge work and start from scratch. Use hg update --clean for this.

References

Reverting Dirty Files

2009-11-30T00:00:00Z

So you have a change you don’t want to keep. Example:

$ hg status
M fileone.txt
M filetwo.txt

Upon reviewing your changes you find out that filetwo.txt is junk you want to get rid of. You could go into the file and manually remove your changes, but Mercurial gives you a better tool for this: hg revert

$ hg revert filetwo.txt

If you have many files that have changes (for example, you want to throw away all your work and start again), use the --all command:

$ hg revert --all
reverting fileone.txt
reverting filetwo.txt

This works like the git reset --hard HEAD^ command, for those of you familiar with git.

Combining Repositories

2009-11-17T00:00:00Z

Thomas’ last tip about decomposing repositories made me want to write about the inverse: combining two separate repositories into a single repository.

Let’s say you’ve working on a project. The code lives in project while the documentation lives in docs. You might decide that it would be nice to have them in the same repository, so when someone clones your project’s code they get the documentation too.

You could just create a new repository and copy all the data into it, but that wouldn’t let you keep your nice history of changesets. Let’s take a look at how to combine these separate repositories.

Create the New, Combined Repository

First we’ll create the new repository where everything is going to live:

$ ls
total 24
drwxr-xr-x  5 sjl   170B Nov 17 19:56 docs
drwxr-xr-x  4 sjl   136B Nov 17 19:58 project

$ mv project project-code

$ hg init project

$ ls
total 24
drwxr-xr-x  5 sjl   170B Nov 17 19:56 docs
drwxr-xr-x  3 sjl   102B Nov 17 20:04 project
drwxr-xr-x  4 sjl   136B Nov 17 19:58 project-code

We’ve moved project to project-code to get it out of the way for the moment.

Prepare Each Repository

We probably don’t want to just dump everything into the root folder of the new repository, so let’s move things around a bit. First we’ll move everything in the project repository into a src/ directory:

$ cd project-code

$ mkdir src

$ mv * src
mv: rename src to src/src: Invalid argument

$ ls
total 0
drwxr-xr-x  3 sjl   102B Nov 17 20:08 src

$ hg addremove --similarity 100
removing myproject.py
adding src/myproject.py
recording removal of myproject.py as rename to src/myproject.py (100% similar)

$ hg commit -m 'Move the code into the src/ directory.'

Now we’ll do the same for the docs repository:

$ cd ../docs

$ mkdir docs

$ mv * docs
mv: rename docs to docs/docs: Invalid argument

$ ls
total 0
drwxr-xr-x  4 sjl   136B Nov 17 20:11 docs

$ hg addremove --similarity 100
removing LICENSE
removing README
adding docs/LICENSE
adding docs/README
recording removal of LICENSE as rename to docs/LICENSE (100% similar)
recording removal of README as rename to docs/README (100% similar)

$ hg commit -m 'Move the documentation into the docs/ directory.'

Pull Both Repositories

Now that we’ve adjusted the structure to our liking, we need to pull both repositories into project:

$ cd ..

$ ls
total 24
drwxr-xr-x  4 sjl   136B Nov 17 20:12 docs
drwxr-xr-x  3 sjl   102B Nov 17 20:04 project
drwxr-xr-x  4 sjl   136B Nov 17 20:08 project-code

$ cd project

$ ls

$ hg pull --update ../project-code
pulling from ../project-code
requesting all changes
adding changesets
adding manifests
adding file changes
added 4 changesets with 4 changes to 2 files
1 files updated, 0 files merged, 0 files removed, 0 files unresolved

$ ls
total 0
drwxr-xr-x  3 sjl   102B Nov 17 20:15 src

$ hg pull --force --update ../docs
pulling from ../docs
searching for changes
warning: repository is unrelated
adding changesets
adding manifests
adding file changes
added 3 changesets with 4 changes to 4 files (+1 heads)
not updating, since new heads added
(run 'hg heads' to see heads, 'hg merge' to merge)

$ ls
total 0
drwxr-xr-x  3 sjl   102B Nov 17 20:15 src

Notice that we used the --force flag with hg pull to say to Mercurial: “It’s okay, I know what I’m doing, I really do want to combine these repositories.”

Merge the Repositories

Take a look at the output of the last ls command. See how there’s still just the src/ directory? We need to merge the two repositories together to get a truly “combined” repository.

To make this a bit more clear, let’s look at the graph of our new repository:

$ hg glog
o  6 Move the documentation into the docs/ directory. (7 minutes ago by Steve Losh) tip
|
o  5 Add a LICENSE file. (22 minutes ago by Steve Losh)
|
o  4 Add a README file. (22 minutes ago by Steve Losh)

@  3 Move the code into the src/ directory. (10 minutes ago by Steve Losh)
|
o  2 Fix a bug. (21 minutes ago by Steve Losh)
|
o  1 Implement some basic functionality. (21 minutes ago by Steve Losh)
|
o  0 Start the project. (21 minutes ago by Steve Losh)

See how we have two separate graphs? Changesets 0 to 3 are linked, and changesets 4 to 6 are linked. Now we need to merge these two graphs together. This should be trivial because we’ve organized the folder structure beforehand so there won’t be any conflicts:

$ hg update 6
2 files updated, 0 files merged, 1 files removed, 0 files unresolved

$ hg merge 3
1 files updated, 0 files merged, 0 files removed, 0 files unresolved
(branch merge, don't forget to commit)

$ hg commit -m 'Combine the source and docs repositories.'

Now take a look at the graph:

$ hg glog
@    7 Combine the source and docs repositories. (37 seconds ago by Steve Losh) tip
|\
| o  6 Move the documentation into the docs/ directory. (11 minutes ago by Steve Losh)
| |
| o  5 Add a LICENSE file. (26 minutes ago by Steve Losh)
| |
| o  4 Add a README file. (27 minutes ago by Steve Losh)
|
o  3 Move the code into the src/ directory. (15 minutes ago by Steve Losh)
|
o  2 Fix a bug. (25 minutes ago by Steve Losh)
|
o  1 Implement some basic functionality. (25 minutes ago by Steve Losh)
|
o  0 Start the project. (26 minutes ago by Steve Losh)

$ ls
total 0
drwxr-xr-x  4 sjl   136B Nov 17 20:22 docs
drwxr-xr-x  3 sjl   102B Nov 17 20:22 src

Our two separate repositories are now nicely merged into one, with the changesets intact! Now we can delete the old repositories and push the new one to our public server for people to use.

This is especially nice because we haven’t changed the changeset hashes, which means that we can easily merge changesets from people that are still using the old, separate repositories.

Using Convert to Decompose Your Repository

2009-11-16T00:00:00Z

Say you have a repository that has evolved to contain many projects (folders). And you have decided you’d be better off if each project (folder) were a separate repository. You can use the convert extension to do just that and retain your changeset history.

For example, a repository laid out like this:

/yourrepository
    /DatabaseFoo
    /SweetBusinessLogic
    /BaseUI
    /AnotherDamnContentManagementSystem

You may have decided at some point that AnotherDamnContentManagementSystem really should belong in its own repository, and had you been able to predict the future so long ago, you would have seen that it was truly a poor choice on your part to combine them all together in one like you were still using Perforce and assumed that this whole version control thing was a super expensive operation.

Well lucky for you, the convert extension can help you undo this embarrassing decision before you show your work to the Venture Capitalist you’re meeting for lunch.

First enable the convert extension:

[extensions]
convert =

The convert command has a --filemap parameter which allows you to specify what you want included in the operation and what you don’t. You can even have things renamed as part of the operation. A filemap for the operation we are to perform will look like this:

include AnotherDamnContentManagementSystem
rename .

Then your command to convert will look like this:

$ hg convert --filemap myfilemap bigrepo AnotherDamnContentManagementSystem-Repo

And that’s it. AnotherDamnContentManagementSystem is now its own Mercurial repository.

Create a Git Mirror

2009-11-09T00:00:00Z

Of all the distributed revision control systems like Mercurial, git is probably the most popular. If you use Mercurial for a project you can quickly and easily make a git mirror of your project so that git users can contribute!

Install hg-git

First, you’ll need to download the hg-git plugin:

easy_install dulwich
hg clone http://bitbucket.org/durin42/hg-git/

Now edit your ~/.hgrc file to contain:

[extensions]
hggit = /path/to/hg-git

Create a GitHub Account

You’ll need a place to put your git mirror, and GitHub is perfect for that. Go ahead and sign up for a GitHub account if you don’t already have one.

Create a Repository on GitHub

Now that you have a GitHub account, you’ll need to create a repository with the “New Repository” button.

Once you create a new repository, you’ll be looking at a page that looks like this:

See the git@github.com:username/project.git URL? Remember that, because that’s what you’ll need to use when you push your mirror.

Push Your Project

Now that you’ve installed hg-git and created a repository for your project on GitHub, you need to push your Mercurial repository to GitHub. First, add the git URL to your Mercurial repository by editing the .hg/hgrc file in your project to contain:

[paths]
git = git+ssh://git@github.com/username/project.git

IMPORTANT NOTE: You will need to replace the : after github.com with a / (forward slash). This is necessary because of how Mercurial handles repository paths!

You’ll also need to replace username and project with the appropriate values, of course.

Now you just need to push to the git path to create your mirror:

hg push git

This will take a few seconds, especially if you have a big repository. Once it finishes you’ll have a 100% functional git mirror at http://github.com/username/project/. Git users can clone your project by running git clone git://github.com/username/project.git and might never even realize that you use Mercurial.

Accepting Contributions

Creating a mirror for git users to clone is very nice, but eventually (if your project is at all interesting) someone is going to send you a pull request on GitHub.

hg-git makes it easy to deal with contributions from git users. First, add the contributor’s fork to your projects’ paths:

[paths]
git = git+ssh://git@github.com/username/project.git
contributor = git+ssh://git@github.com/contributor_username/project.git

Again, make sure you replace the : after github.com with a / (forward slash)!

Then pull their changes into your Mercurial repository:

hg pull contributor

You can use graphlog to see exactly what your repository looks like at this point (and if you need to merge).

Merge if you need (and/or want) to merge, and then push their contributions to your main Mercurial repository and your git mirror:

hg push
hg push git

That covers the basics! Things can get more complicated if you’ve got a heavily branching workflow, but this tip should get your on your way to accepting patches from git users.