2009-04-29 05:18:26 +04:00
|
|
|
Hg-Git Mercurial Plugin
|
|
|
|
=======================
|
|
|
|
|
2012-07-06 02:40:18 +04:00
|
|
|
* Homepage: http://hg-git.github.com/
|
|
|
|
* https://bitbucket.org/durin42/hg-git (primary)
|
|
|
|
* https://github.com/schacon/hg-git (mirror)
|
|
|
|
|
2010-06-13 06:27:17 +04:00
|
|
|
This is the Hg-Git plugin for Mercurial, adding the ability to push
|
|
|
|
and pull to/from a Git server repository from Hg. This means you can
|
|
|
|
collaborate on Git based projects from Hg, or use a Git server as a
|
|
|
|
collaboration point for a team with developers using both Git and Hg.
|
|
|
|
|
|
|
|
The Hg-Git plugin can convert commits/changesets losslessly from one
|
|
|
|
system to another, so you can push via an Hg repository and another Hg
|
|
|
|
client can pull it and their changeset node ids will be identical -
|
|
|
|
Mercurial data does not get lost in translation. It is intended that
|
|
|
|
Hg users may wish to use this to collaborate even if no Git users are
|
|
|
|
involved in the project, and it may even provide some advantages if
|
|
|
|
you're using Bookmarks (see below).
|
2009-04-29 05:18:26 +04:00
|
|
|
|
2009-04-29 05:59:41 +04:00
|
|
|
Dependencies
|
|
|
|
============
|
|
|
|
|
2010-06-13 06:27:17 +04:00
|
|
|
This plugin is implemented entirely in Python - there are no Git
|
|
|
|
binary dependencies, you do not need to have Git installed on your
|
2014-05-20 07:44:53 +04:00
|
|
|
system. The only dependencies are Mercurial and Dulwich. See the
|
|
|
|
Makefile for information about which versions of Mercurial are
|
|
|
|
known to work, and setup.py for which versions of Dulwich are required.
|
2009-04-29 05:59:41 +04:00
|
|
|
|
2010-05-17 18:53:18 +04:00
|
|
|
Usage
|
|
|
|
=====
|
2009-04-29 05:18:26 +04:00
|
|
|
|
2012-08-23 07:39:45 +04:00
|
|
|
You can clone a Git repository from Hg by running `hg clone <url> [dest]`. For
|
2010-05-17 15:55:17 +04:00
|
|
|
example, if you were to run
|
2009-04-29 05:18:26 +04:00
|
|
|
|
2010-05-17 15:50:58 +04:00
|
|
|
$ hg clone git://github.com/schacon/hg-git.git
|
2009-06-22 13:24:48 +04:00
|
|
|
|
2012-08-23 07:39:45 +04:00
|
|
|
Hg-Git would clone the repository and convert it to an Hg repository
|
|
|
|
for you.
|
2009-04-29 05:18:26 +04:00
|
|
|
|
2010-06-13 06:27:17 +04:00
|
|
|
If you want to clone a github repository for later pushing (or any
|
|
|
|
other repository you access via ssh), you need to convert the ssh url
|
|
|
|
to a format with an explicit protocol prefix. For example, the git url
|
|
|
|
with push access
|
2009-04-29 05:18:26 +04:00
|
|
|
|
2010-05-17 18:31:43 +04:00
|
|
|
git@github.com:schacon/hg-git.git
|
2009-06-22 13:24:48 +04:00
|
|
|
|
2010-05-17 18:31:43 +04:00
|
|
|
would read
|
2009-06-29 00:49:44 +04:00
|
|
|
|
2010-05-17 18:31:43 +04:00
|
|
|
git+ssh://git@github.com/schacon/hg-git.git
|
|
|
|
|
|
|
|
(Mind the switch from colon to slash after the host!)
|
|
|
|
|
|
|
|
Your clone command would thus look like this:
|
2009-06-29 00:49:44 +04:00
|
|
|
|
2010-05-17 15:50:58 +04:00
|
|
|
$ hg clone git+ssh://git@github.com/schacon/hg-git.git
|
2009-06-29 00:49:44 +04:00
|
|
|
|
2012-08-23 07:39:45 +04:00
|
|
|
If you are starting from an existing Hg repository, you have to set up
|
|
|
|
a Git repository somewhere that you have push access to, add a path entry
|
|
|
|
for it in your .hg/hgrc file, and then run `hg push [name]` from within
|
|
|
|
your repository. For example:
|
2009-04-29 05:18:26 +04:00
|
|
|
|
2010-05-17 15:50:58 +04:00
|
|
|
$ cd hg-git # (an Hg repository)
|
|
|
|
$ # edit .hg/hgrc and add the target git url in the paths section
|
|
|
|
$ hg push
|
2009-06-22 13:24:48 +04:00
|
|
|
|
2012-08-23 07:39:45 +04:00
|
|
|
This will convert all your Hg data into Git objects and push them to the Git server.
|
2009-06-22 13:24:48 +04:00
|
|
|
|
2010-06-13 06:27:17 +04:00
|
|
|
Now that you have an Hg repository that can push/pull to/from a Git
|
|
|
|
repository, you can fetch updates with `hg pull`.
|
2009-04-29 05:18:26 +04:00
|
|
|
|
2010-05-17 15:49:49 +04:00
|
|
|
$ hg pull
|
2009-06-22 13:24:48 +04:00
|
|
|
|
2010-06-13 06:27:17 +04:00
|
|
|
That will pull down any commits that have been pushed to the server in
|
|
|
|
the meantime and give you a new head that you can merge in.
|
2009-04-29 05:18:26 +04:00
|
|
|
|
2012-09-14 04:57:37 +04:00
|
|
|
Hg-Git can also be used to convert a Mercurial repository to Git. You can use
|
|
|
|
a local repository or a remote repository accessed via SSH, HTTP or HTTPS. Use
|
2014-05-26 04:18:40 +04:00
|
|
|
the following commands to convert the repository (it assumes you're running this
|
2012-09-14 04:57:37 +04:00
|
|
|
in $HOME).
|
2010-04-06 19:19:30 +04:00
|
|
|
|
2010-05-17 15:49:49 +04:00
|
|
|
$ mkdir git-repo; cd git-repo; git init; cd ..
|
|
|
|
$ cd hg-repo
|
|
|
|
$ hg bookmarks hg
|
2012-09-14 04:57:37 +04:00
|
|
|
$ hg push ../git-repo
|
2010-04-06 19:19:30 +04:00
|
|
|
|
2010-06-13 06:27:17 +04:00
|
|
|
The hg bookmark is necessary to prevent problems as otherwise hg-git
|
|
|
|
pushes to the currently checked out branch confusing Git. This will
|
|
|
|
create a branch named hg in the Git repository. To get the changes in
|
|
|
|
master use the following command (only necessary in the first run,
|
|
|
|
later just use git merge or rebase).
|
2010-04-06 19:19:30 +04:00
|
|
|
|
2010-05-17 15:49:49 +04:00
|
|
|
$ cd git-repo
|
|
|
|
$ git checkout -b master hg
|
2010-04-06 19:19:30 +04:00
|
|
|
|
2010-06-13 06:27:17 +04:00
|
|
|
To import new changesets into the Git repository just rerun the hg
|
|
|
|
push command and then use git merge or git rebase in your Git
|
|
|
|
repository.
|
2010-04-06 19:19:30 +04:00
|
|
|
|
2010-05-17 19:00:56 +04:00
|
|
|
Commands
|
|
|
|
========
|
|
|
|
|
|
|
|
gclear
|
|
|
|
------
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
|
|
|
gimport
|
|
|
|
-------
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
|
|
|
gexport
|
|
|
|
-------
|
|
|
|
|
|
|
|
TODO
|
|
|
|
|
|
|
|
git-cleanup
|
|
|
|
-----------
|
|
|
|
|
|
|
|
TODO
|
2010-04-06 19:19:30 +04:00
|
|
|
|
2009-04-29 05:18:26 +04:00
|
|
|
Hg Bookmarks Integration
|
|
|
|
========================
|
|
|
|
|
2012-09-14 04:36:58 +04:00
|
|
|
Hg-Git pushes your bookmarks up to the Git server as branches and will
|
2010-06-13 06:27:17 +04:00
|
|
|
pull Git branches down and set them up as bookmarks.
|
2009-04-29 05:18:26 +04:00
|
|
|
|
|
|
|
Installing
|
|
|
|
==========
|
|
|
|
|
2010-06-13 06:27:17 +04:00
|
|
|
Clone this repository somewhere and make the 'extensions' section in
|
|
|
|
your `~/.hgrc` file look something like this:
|
2009-04-29 05:18:26 +04:00
|
|
|
|
2010-05-17 15:49:49 +04:00
|
|
|
[extensions]
|
|
|
|
hggit = [path-to]/hg-git/hggit
|
2009-04-29 05:18:26 +04:00
|
|
|
|
2012-09-14 04:36:58 +04:00
|
|
|
That will enable the Hg-Git extension for you.
|
2009-04-29 05:55:14 +04:00
|
|
|
|
2012-08-23 07:39:45 +04:00
|
|
|
This plugin is currently tested against the following Mercurial versions:
|
2014-02-20 03:48:27 +04:00
|
|
|
|
2012-08-23 07:39:45 +04:00
|
|
|
* 2.0.2
|
|
|
|
* 2.1.2
|
|
|
|
* 2.2.3
|
2012-09-10 08:23:35 +04:00
|
|
|
* 2.3.1
|
2012-08-23 07:39:45 +04:00
|
|
|
|
2010-05-17 16:15:50 +04:00
|
|
|
Configuration
|
|
|
|
=============
|
|
|
|
|
|
|
|
git.intree
|
|
|
|
----------
|
|
|
|
|
|
|
|
hg-git keeps a git repository clone for reading and updating. By default, the
|
|
|
|
git clone is the subdirectory `git` in your local Mercurial repository. If you
|
|
|
|
would like this git clone to be at the same level of your Mercurial repository
|
|
|
|
instead (named `.git`), add the following to your `hgrc`:
|
|
|
|
|
|
|
|
[git]
|
|
|
|
intree = True
|
2012-02-26 01:13:02 +04:00
|
|
|
|
2012-02-23 22:49:07 +04:00
|
|
|
git.authors
|
|
|
|
-----------
|
|
|
|
|
|
|
|
Git uses a strict convention for "author names" when representing changesets,
|
|
|
|
using the form `[realname] [email address]`. Mercurial encourages this
|
|
|
|
convention as well but is not as strict, so it's not uncommon for a Mercurial
|
|
|
|
repo to have authors listed as simple usernames. hg-git by default will
|
|
|
|
translate such names using the email address `none@none`, which then shows up
|
|
|
|
unpleasantly on GitHub as "illegal email address".
|
|
|
|
|
|
|
|
The `git.authors` option provides for an "authors translation file" that will
|
|
|
|
be used during outgoing transfers from mercurial to git only, by modifying
|
|
|
|
`hgrc` as such:
|
|
|
|
|
|
|
|
[git]
|
|
|
|
authors = authors.txt
|
|
|
|
|
|
|
|
Where `authors.txt` is the name of a text file containing author name translations,
|
|
|
|
one per each line, using the following format:
|
|
|
|
|
|
|
|
johnny = John Smith <jsmith@foo.com>
|
|
|
|
dougie = Doug Johnson <dougiej@bar.com>
|
|
|
|
|
|
|
|
Empty lines and lines starting with a "#" are ignored.
|
|
|
|
|
|
|
|
It should be noted that **this translation is on the hg->git side only**. Changesets
|
|
|
|
coming from Git back to Mercurial will not translate back into hg usernames, so
|
|
|
|
it's best that the same username/email combination be used on both the hg and git sides;
|
|
|
|
the author file is mostly useful for translating legacy changesets.
|
|
|
|
|
2012-02-26 01:13:02 +04:00
|
|
|
git.branch_bookmark_suffix
|
|
|
|
---------------------------
|
|
|
|
|
|
|
|
hg-git does not convert between Mercurial named branches and git branches as
|
|
|
|
the two are conceptually different; instead, it uses Mercurial bookmarks to
|
|
|
|
represent the concept of a git branch. Therefore, when translating an hg repo
|
|
|
|
over to git, you typically need to create bookmarks to mirror all the named
|
|
|
|
branches that you'd like to see transferred over to git. The major caveat with
|
|
|
|
this is that you can't use the same name for your bookmark as that of the
|
|
|
|
named branch, and furthermore there's no feasible way to rename a branch in
|
|
|
|
Mercurial. For the use case where one would like to transfer an hg repo over
|
|
|
|
to git, and maintain the same named branches as are present on the hg side,
|
|
|
|
the `branch_bookmark_suffix` might be all that's needed. This presents a
|
|
|
|
string "suffix" that will be recognized on each bookmark name, and stripped
|
|
|
|
off as the bookmark is translated to a git branch:
|
|
|
|
|
|
|
|
[git]
|
|
|
|
branch_bookmark_suffix=_bookmark
|
|
|
|
|
|
|
|
Above, if an hg repo had a named branch called `release_6_maintenance`, you could
|
|
|
|
then link it to a bookmark called `release_6_maintenance_bookmark`. hg-git will then
|
|
|
|
strip off the `_bookmark` suffix from this bookmark name, and create a git branch
|
|
|
|
called `release_6_maintenance`. When pulling back from git to hg, the `_bookmark`
|
|
|
|
suffix is then applied back, if and only if an hg named branch of that name exists.
|
|
|
|
E.g., when changes to the `release_6_maintenance` branch are checked into git, these
|
|
|
|
will be placed into the `release_6_maintenance_bookmark` bookmark on hg. But if a
|
|
|
|
new branch called `release_7_maintenance` were pulled over to hg, and there was
|
|
|
|
not a `release_7_maintenance` named branch already, the bookmark will be named
|
|
|
|
`release_7_maintenance` with no usage of the suffix.
|
|
|
|
|
|
|
|
The `branch_bookmark_suffix` option is, like the `authors` option, intended for
|
|
|
|
migrating legacy hg named branches. Going forward, an hg repo that is to
|
|
|
|
be linked with a git repo should only use bookmarks for named branching.
|
2014-10-31 21:36:39 +03:00
|
|
|
|
|
|
|
git.mindate
|
|
|
|
-----------
|
|
|
|
|
|
|
|
If set, branches where the latest commit's commit time is older than this will
|
|
|
|
not be imported. Accepts any date formats that Mercurial does -- see
|
|
|
|
`hg help dates` for more.
|
2014-12-05 12:18:43 +03:00
|
|
|
|
|
|
|
git.similarity
|
|
|
|
--------------
|
|
|
|
|
|
|
|
Specify how similar files modified in a Git commit must be to be imported as
|
|
|
|
Mercurial renames or copies, as a percentage between "0" (disabled) and "100"
|
|
|
|
(files must be identical). For example, "90" means that a delete/add pair will
|
|
|
|
be imported as a rename if more than 90% of the file has stayed the same. The
|
|
|
|
default is "0" (disabled).
|
|
|
|
|
|
|
|
git.renamelimit
|
|
|
|
---------------
|
|
|
|
|
|
|
|
The number of files to consider when performing the copy/rename detection.
|
|
|
|
Detection is disabled if the number of files modified in a commit is above the
|
|
|
|
limit. Detection is O(N^2) in the number of files modified, so be sure not to
|
|
|
|
set the limit too high. Similar to Git's `diff.renameLimit` config. The default
|
|
|
|
is "400", the same as Git.
|
|
|
|
|
|
|
|
git.findcopiesharder
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
Whether to consider unmodified files as copy sources. This is a very expensive
|
|
|
|
operation for large projects, so use it with caution. Similar to `git diff`'s
|
|
|
|
--find-copies-harder option.
|