Diff for "HgGit" - Mercurial

Differences between revisions 13 and 23 (spanning 10 versions)

hg-git Extension

Note: This extension is not distributed with Mercurial.

Maintainers: Kevin Bullock, Georges Racinet & Dan V. P. Christiansen
Discussion: https://groups.google.com/group/hg-git, #hg-git:matrix.org and IRC
Repository: https://foss.heptapod.net/mercurial/hg-git
Old web page: https://hg-git.github.io/

Overview

This extension adds the ability to work on a Git repository from Mercurial. It also allows using a Git server as a collaboration point for a team with developers using both Git and Mercurial. At the same time, it can also be used to interact with a Mercurial repository using Git.

Commits and changesets are converted losslessly from one system to another, so you can push from a Mercurial repository and another Mercurial client can pull it and their changeset node ids will be identical - Mercurial data does not get lost in translation. It is intended that Mercurial 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).

Installation

This plugin is entirely in Python - you do not need to have Git installed on your system. The only dependency is Dulwich Python library.

To install hg-git, for example in ~/.hgext directory.

hg clone https://foss.heptapod.net/mercurial/hg-git ~/.hgext/hg-git

Testing.

hg --config extensions.hggit=~/.hgext/hg-git/hggit version -v

There should be no errors, and hg-git version should be visible.

Configuration

Configure your .hgrc to enable the extension by adding following lines:

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

Commands

You can clone a Git repository as you would clone a mercurial repository, for example :

hg clone git+https://github.com/dulwich/dulwich

will clone the git mirror of the hg-git repository in a directory named 'hg-git.git'.

If you want to clone a repository via ssh, you can do so using a git+ssh:// protocol prefix :

hg clone git+ssh://git@github.com/dulwich/dulwich

This will also create a bookmark for each git branch, and add local tags default/<branch name> for each branch. This is similar to origin/<branch name> in Git.

When you pull from a Git repository in the [paths] section of hgrc, it will "fast-forward" the bookmarks if the branches haven't diverged. It will also create local tags as above.

When pushing to Git, the following happens:

if there are no bookmarks and the remote repository is empty, the tip is pushed as the master branch.
for each branch in the remote repository, if there is a bookmark or a tag with the same name that points to a descendent of the head, then push it.
if there are bookmarks with no remote branch, a new branch is created.

Using hg-git to interact with a hg repository with git

Note:

This section is outdated (references to master branch and exportbranch config)

You can create a local .git repository like this:

Edit the .hg/hgrc (or your ~/.hgrc if you want to make this the default):

[git]
intree=1

Then do the following from in the hg repository:

hg gexport

This will create a .git repository in the working directory (alongside the .hg directory) that you can interact with like any regular git repository. If you have made commits in the git repository and want to convert them to hg commits, first make sure the changes you want are on the master branch, then do:

hg gimport

This will put your changes on top of the current hg tip.

Optionally you can change your hgrc to include an exportbranch statement:

[git]
intree=1
exportbranch=refs/heads/from-hg

This will cause 'hg gexport' to update the 'from-hg' branch, instead of the master branch, so that your changes will not be lost even if you work on the master branch.

TODO

TODO: this section is outdated

If you want to help with the development of hg-git, here are some things you can help with:

Add support for -r/--rev to pull.
the workflow and user experience is in general quite unsatisfying
making tags and Git state transferable between Mercurial repositories
make pushing using dulwich more efficient (faster packing, thin packs, etc).

Alternatives

Git extension

The GitExtension, which is packaged with Mercurial, interacts with a Git repository directly, avoiding the intermediate conversion. This has certain advantages:

Each commit only has one node ID, which is the Git hash.
Data is stored only once, so the on-disk footprint is much lower.

However, it is not able to handle all Git repositories; in particular, it cannot handle octopus merges, i.e. commits with more than two parents.

Convert

The ConvertExtension, packaged with Mercurial, has Git support.

CategoryExtensionsByOthers

-  ⇤ ← Revision 13 as of 2019-03-02 08:34:28 → 
  Size: 4526
  Editor: muxator
  Comment: Updated project URIs, using https where possible
+   ← Revision 23 as of 2024-06-25 14:53:49 → ⇥
  Size: 5178
  Editor: DanVilliomPodlaskiChristiansen
  Comment: Mention Matrix channel
-Deletions are marked like this.
+Additions are marked like this.
 Line 2:
-'''This extension is not distributed with Mercurial.'''
-Line 4:
+Line 3:
-''Author: Scott Chacon, Augie Fackler, Abderrahim Kitouni, and Sverre Rabbelier''
+{{{#!wiki note
   '''Note:''' ''This extension is not distributed with Mercurial.''}}}
 Line 6:
-Web page: https://hg-git.github.io/
+  Maintainers:: ''Kevin Bullock, Georges Racinet & Dan V. P. Christiansen''
  Discussion:: https://groups.google.com/group/hg-git, [[https://matrix.to/#/#hg-git:matrix.org>|#hg-git:matrix.org]] and [[IRC]]
  Repository:: https://foss.heptapod.net/mercurial/hg-git
  Old web page:: https://hg-git.github.io/
-Line 8:
+Line 11:
-Mailing list: https://groups.google.com/group/hg-git

Repository: https://bitbucket.org/durin42/hg-git
 Line 13:
-This extension adds the ability to work on a Git repository from Mercurial.  It also allows using a Git server as a collaboration point for a team with developers using both Git and Mercurial. At the same time, it can also be used to interact with a hg repository using git.
+This extension adds the ability to work on a Git repository from Mercurial.  It also allows using a Git server as a collaboration point for a team with developers using both Git and Mercurial. At the same time, it can also be used to interact with a Mercurial repository using Git.
 Line 15:
-It can convert commits/changesets losslessly from one system to another, so you can push from a Mercurial repository and another Mercurial client can pull it and their changeset node ids will be identical - Mercurial data does not get lost in translation.  It is intended that Mercurial 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).
+Commits and changesets are converted losslessly from one system to another, so you can push from a Mercurial repository and another Mercurial client can pull it and their changeset node ids will be identical - Mercurial data does not get lost in translation.  It is intended that Mercurial 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).

=== Installation ===
This plugin is entirely in Python - you do not need to have Git installed on your system.  The only dependency is [[https://www.dulwich.io/|Dulwich]] Python library.

To install `hg-git`, for example in `~/.hgext` directory.
{{{
hg clone https://foss.heptapod.net/mercurial/hg-git ~/.hgext/hg-git
}}}

Testing.
{{{
hg --config extensions.hggit=~/.hgext/hg-git/hggit version -v
}}}
There should be no errors, and `hg-git` version should be visible.

=== Configuration ===
Configure your .hgrc to enable the extension by adding following lines:

{{{
[extensions]
hggit = /path/to/hg-git/hggit
}}}
-Line 21:
+Line 43:
-hg clone git://github.com/schacon/hg-git.git
+hg clone git+https://github.com/dulwich/dulwich
-Line 24:
+Line 46:
-''TODO: document the difference between {{{ssh://host/path}}} and {{{host:path}}} git urls and how they map to hg.''
-Line 30:
+Line 50:
-hg clone git+ssh://git@github.com/schacon/hg-git.git
+hg clone git+ssh://git@github.com/dulwich/dulwich
-Line 32:
+Line 52:
-This will also create a bookmark for each git branch, and add local tags {{{default/<branch name>}}} for each branch. This is similar to {{{origin/<branch name>}}} in git.
+This will also create a bookmark for each git branch, and add local tags {{{default/<branch name>}}} for each branch. This is similar to {{{origin/<branch name>}}} in Git.
-Line 34:
+Line 54:
-When you pull from a git repository in the {{{[paths]}}} section of hgrc, it will "fast-forward" the bookmarks if the branches haven't diverged. It will also create local tags as above.
+When you pull from a Git repository in the {{{[paths]}}} section of hgrc, it will "fast-forward" the bookmarks if the branches haven't diverged. It will also create local tags as above.
-Line 36:
+Line 56:
-When pushing to git, the following is done to determine what's pushed :
+When pushing to Git, the following happens:
-Line 42:
+Line 62:
-The bookmarks extension is not necessary, one can work using solely local tags, but it's more convenient to use it.
+=== Using hg-git to interact with a hg repository with git ===
-Line 44:
+Line 64:
-=== Using hg-git to interact with a hg repository with git ===
''TODO: this section is outdated (references to master branch and exportbranch config)''
+{{{#!wiki caution
'''Note:'''

This section is outdated (references to master branch and exportbranch config)
}}}
-Line 49:
+Line 72:
-Editr the .hg/hgrc (or your ~/.hgrc if you want to make this the default):
+Edit the .hg/hgrc (or your ~/.hgrc if you want to make this the default):
-Line 79:
+Line 102:
-If you want to help with the development of hg-git, here are some things you can help with :
+If you want to help with the development of hg-git, here are some things you can help with:
-Line 81:
+Line 104:
- * push/pull -r
 * incoming/outgoing
 * better handling for tags (see [[http://www.selenic.com/pipermail/mercurial-devel/2009-July/014061.html|this thread]] on the mailing list).
+ * Add support for {{{-r/--rev}}} to {{{pull}}}.
 * the workflow and user experience is in general quite unsatisfying
 * making tags and Git state transferable between Mercurial repositories
-Line 86:
+Line 109:
-=== Dependencies ===
This plugin is implemented entirely in Python - there are no Git binary dependencies, you do not need to have Git installed on your system.  The only dependencies are [[http://samba.org/~jelmer/dulwich/|Dulwich]] 0.4.1 or later and Mercurial (it should work with Mercurial versions 1.1-1.3).
+== Alternatives ==
=== Git extension ===
The GitExtension, which is packaged with Mercurial, interacts with a Git repository directly, avoiding the intermediate conversion. This has certain advantages:
-Line 89:
+Line 113:
-=== Configuration ===
Configure your .hgrc to enable the extension by adding following lines:
+ * Each commit only has one node ID, which is the Git hash.
 * Data is stored only once, so the on-disk footprint is much lower.
-Line 92:
+Line 116:
-{{{
[extensions]
hgext.bookmarks =
hggit = /path/to/hg-git
}}}
+However, it is not able to handle all Git repositories; in particular, it cannot handle [[http://git-scm.com|octopus merges]], i.e. commits with more than two parents.

=== Convert ===
The ConvertExtension, packaged with Mercurial, has Git support.