Mercurial Plug-in for Xcode

This Mercurial Plug-in for Xcode allows, as its name suggests, to perform common SCM operations on Mercurial repositories right from Xcode. Not every operation that Xcode supports for git is supported for Mercurial, please see the list below.

Why Mercurial? Because Mercurial is a great distributed source code management tool, with a focus on progressive learning curve (easy command line), extensibility (plug-in API), and cross-platform (written in python). It's good to have choice, and to be able to use your tools together in an integrated way.

This project wouldn't have been possible without the work of hsivank on his bridge xcode4-with-mercurial.


Xcode 4.6+ or Xcode 5 and OS X 10.8 or higher are required.


Binary installation (available here)

  • Copy the Mercurial.xcplugin to ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins.
  • Restart Xcode.

From the sources:

  • Build the project in Xcode (this installs it in the proper location through a build phase)
  • Restart Xcode

Once in Xcode, there's nothing specific to do. Just watch as files statuses are updated while you work, see the log of any commit, or even display a diff with previous versions right from the editor.


To uninstall, remove the plugin from ~/Library/Application Support/Developer/Shared/Xcode/Plug-ins and restart Xcode.

Supported SCM operations

  • Reporting status in project navigator
  • Diffing with Xcode native tool of any arbitrary versions
  • Committing files
  • Moving/renaming
  • Removing a file

Unsupported (yet)

  • Pull/pull/rebase
  • Blame/annotate lines of code (should not be far from working)

Feel free to give a hand on these things!

How does it work?

The Mercurial plug-in tricks Xcode by making it believe it can handle .hg repositories. What happens behind the scene is that the Git backend of Xcode is handling all operations, but instead of invoking the git executable directly, it invokes a python script ( with the exact same command-line arguments ( that would be passed to git.

This script rewrites each git command into an equivalent Mercurial command, and invokes Mercurial. Then, it processes the Mercurial output to transform it back to what git would have outputted. That way, Xcode can in turn do its job of updating the UI and display results.

The is smart enough to still invoke the real git if it is operated on a git repository (no present .hg dir). That way, Xcode can be operated on both kinds of SCM, even within the same workspace.

The technique of swizzling (replacing Obj-C methods) is used in the plugin to replace built-in behaviors.

Warning: This is very experimental software. Because of the nature of this software (interaction with your source code repositories), be sure sure to backup your data very regularly.



This project (Mercurial Xcode Plug-in) is provided under a BSD License. See the LICENSE file for more info. has its own licensing scheme (GPL), see provided license files.