Table of Contents
Mercurial (hg) has for a long time had a plugin called hg-git that allows hg to interact with Git source code servers. The hg-git plugin sees regular contribution from several hg committers and the current maintainer is Kevin Bullock. The upstream repository is located at https://bitbucket.org/durin42/hg-git
hg-git depends on the Python library dulwich which is packaged for most GNU/Linux distributions. The Skara CLI tooling also requires both
git to be installed. hg-git itself is just a Mercurial extension written in Python that is distributed in source form.
hg-git by cloning it with hg:
Then update your
hgrc file to include the
First of all you should set up your full name and your email in your
Given that hg-git works a lot with bookmarks, tags and multiple heads for the default branch you probably want to enable a few extensions and create some aliases to make it easier to work with the commit graph in hg. The following extensions are recommended (in addition to hg-git itself of course):
The hg-git plugin maintains a mapping from hg commits to git commits. If you alter history in hg then this mapping can become outdated (refering to hg commits that no longer exists). To refresh this mapping you must run
hg git-cleanup. To import new commits from the Git repository within the .hg directory you need to run the command
hg gimport (this is done automatically as part of
hg pull). Since these two commands are frequently run together we run recommend to create the following alias:
Since the commit graph can become a bit more "branchy" when you work on multiple pull requests it is vital to be able to quickly visualize the commit graph. We recommend the following alias and color configuration for this:
Deleting a bookmark in hg will not delete the remote branch on the git server. To make this a bit easier to manage we recommend adding a
hg prune alias:
The hg-git plugin will represent git branches as bookmarks (see
hg help bookmarks for details) and git remotes (and remote branches) will be represented as tags (see
hg help git for details). To be able to clone a git repository with hg you must prefix the url with
git+ as in:
When working a Git source code hosting provider like GitHub or GitLab you probably want to clone your personal fork instead of the upstream repository. You would then add a path to the upstream repository, for example:
To get commits from the upstream repository you then run
Bookmarks and Pull Requests
To create a new bookmark for your changes, just run
You will then do your work and create a commit with
hg commit. If you want to update your commit with additional changes you can do so with
hg commit --amend. Finally when it is time to create a pull request you push your bookmark to your personal fork:
You can then click on the returned link to create a pull request on GitHub with you web browser. If you prefer to work only from the command line, see the Skara section for CLI commands to use.
Project Skara provices optional tooling for working with pull requests and Git source code hosting services from the command line. There is no need to use the Skara tooling to contribute using
hg-git, but contributors spending a lot of time on the command line might find them useful. All the Skara CLI tooling works equally well
git as with
hg-git. In other words the Skara CLI tooling can be used together with
hg on a repository cloned from e.g. GitLab or GitHub.
To install the Skara CLI tooling for Mercurial, first clone the Skara repository:
Then add the Skara extension to your
The Skara CLI tooling will bootstrap itself upon first use, but if you wan to ensure that everything works you can run:
Personal Access Token
In order to interact with the API:s for Git source code hosting services, you need to setup a personal access token to that service.
First of all add a credentials section to your
hgrc for github.com with your GitHub username:
Then you must create a personal access token (PAT) on GitHub with the "repo" scope, see the following link for how do this: https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line . Once you have created your personal access token you must store it somewhere. Git supports so called "credentials managers" and the Skara tooling will be able to work with a Git credential manager even when used from Mercurial. Please see https://wiki.openjdk.java.net/display/SKARA#Skara-GitCredentialManager for how to set up a Git credential manager. If you prefer to store your personal access token via some other means, perhaps in a gpg encrypted file, then the Skara tooling supports that as well. You only need to set the
HG_TOKEN environment variable when using the Skara commands, for example:
hg fork will allow you to create a personal fork repositories on a Git source code hosting services like GitHub or GitLab. Creating a personal fork is usually only done once, then bookmarks will be used to model concurrent work.
hg pr is the command to interact with pull requests on a Git source code hosting services. When you create a number of commits under a bookmark, you can use
hg pr create to create a pull request for that bookmark (
hg pr create will also, if needed, guide you through the process to push your bookmark). You can then list pull requests with
hg pr list, approve pull requests with
hg pr approve, and so on. See
hg pr help for all details.
All the activity that happens around an OpenJDK repository that has the Skara tooling enabled on a Git source code hosting provider will be bi-directionally mirrored to the OpenJDK mailiing lists. If a pull requested is created on e.g. GitHub then an "RFR" email will be automatically sent to the correct mailing list. If you want to make a review comment then you can either do so on the Git source code hosting platform or you can reply to the RFR email (email replies are mirrored on the Git source code hosting provider as a pull request comment).