README.rst 5.75 KB
Newer Older
1
2
3
Hg-Git Mercurial Plugin
=======================

4
5
6
7
8
9
10
Homepage:
  https://hg-git.github.io/
Repository:
  https://foss.heptapod.net/mercurial/hg-git
Mailing list:
  `hg-git@googlegroups.com <mailto:hg-git@googlegroups.com>`_ (`Google
  Group <https://groups.google.com/g/hg-git>`_)
11
12
13
14
15
16
17

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
18
system to another, so you can push via a Mercurial repository and another Hg
19
20
21
22
23
24
25
26
27
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).

Dependencies
============

28
29
This plugin is implemented entirely in Python — there are no Git
binary dependencies, and you do not need to have Git installed on your
30
31
system. The only dependencies are:

32
* Mercurial 5.4
33
* Dulwich 0.19.3
34
* Python 3.7
35
36
37

Please note that these are the earliest versions known to work; later
versions generally work better.
38
39
40
41

Installing
==========

42
43
We recommend installing the plugin using your a package manager, such
as pip::
44

45
  python -m pip install hg-git
46

47
48
Alternatively, you can clone this repository somewhere and install it
from the directory::
49

50
51
52
  hg clone https://foss.heptapod.net/mercurial/hg-git/
  cd hg-git
  python -m pip install .
53
54
55
56
57

And enable it from somewhere in your ``$PYTHONPATH``::

   [extensions]
   hggit =
58
59
60
61

Contributing
============

62
63
64
65
66
67
68
69
70
The primary development location for Hg-Git is `Heptapod
<http://foss.heptapod.net/mercurial/hg-git/>`_, and you can follow
their guide on `how to contribute patches
<https://heptapod.net/pages/quick-start-guide.html>`_.

Alternatively, you can follow the `guide on how to contribute to
Mercurial itself
<https://www.mercurial-scm.org/wiki/ContributingChanges>`_, and send
patches to `the list <https://groups.google.com/g/hg-git>`_.
71
72
73
74

Usage
=====

75
76
You can clone a Git repository from Mercurial by running
``hg clone <url> [dest]``. For example, if you were to run::
77

78
   $ hg clone git://github.com/hg-git/hg-git.git
79

80
81
82
Hg-Git would clone the repository and convert it to a Mercurial
repository for you. Other protocols are also supported, see ``hg help
git`` for details.
83

84
If you are starting from an existing Mercurial repository, you have to set up a
85
86
87
88
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::

89
   $ cd hg-git # (a Mercurial repository)
90
91
92
   $ # edit .hg/hgrc and add the target git url in the paths section
   $ hg push

93
This will convert all your Mercurial data into Git objects and push them to the
94
95
Git server.

96
97
Now that you have a Mercurial repository that can push/pull to/from a Git
repository, you can fetch updates with ``hg pull``::
98
99
100
101
102
103
104
105
106
107
108

   $ hg pull

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.

Hg-Git pushes your bookmarks up to the Git server as branches and will
pull Git branches down and set them up as bookmarks.

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
109
110
or HTTPS. Use the following commands to convert the repository, it
assumes you're running this in ``$HOME``::
111
112
113
114
115
116

   $ mkdir git-repo; cd git-repo; git init; cd ..
   $ cd hg-repo
   $ hg bookmarks hg
   $ hg push ../git-repo

117
118
119
120
121
122
The ``hg`` bookmark is necessary to prevent problems as otherwise
hg-git pushes to the currently checked out branch, confusing Git. The
snippet above 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 ``git
rebase``).
123
124
125
126
127
128

::

   $ cd git-repo
   $ git checkout -b master hg

129
130
131
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.
132
133
134
135
136
137
138
139

``.gitignore`` and ``.hgignore``
--------------------------------

If present, ``.gitignore`` will be taken into account provided that there is
no ``.hgignore``. In the latter case, the rules from ``.hgignore`` apply,
regardless of what ``.gitignore`` prescribes.

140
141
142
Please note that Mercurial doesn't support exclusion patterns, so any
``.gitignore`` pattern starting with ``!`` will trigger a warning.

143
144
This has been so since version 0.5.0, released in 2013.

145
146
Further reading
===============
147

148
See ``hg help -e hggit`` and ``hg help hggit-config``.
149

150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
Alternatives
============

Since version 5.4, Mercurial includes an extension called ``git``. It
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.

The extension has certain drawbacks, however:

 * It cannot handle all Git repositories. In particular, it cannot
   handle `octopus merges`_, i.e. merge commits with more than two
   parents. If any such commit is included in the history, conversion
   will fail.
 * You cannot interact with Mercurial repositories.

168
.. _octopus merges: https://git-scm.com/docs/git-merge
169
170
171
172
173
174
175

Another extension packaged with Mercurial, the ``convert`` extension,
also has Git support.

Other alternatives exist for Git users wanting to access Mercurial
repositories, such as `git-remote-hg`_.

176
.. _git-remote-hg: https://pypi.org/project/git-remote-hg/