This instance will be upgraded to Heptapod 0.19.0rc2 on 2021-01-18 at 11:00 UTC+1 (a few minutes of downtime)

README.md 11.2 KB
Newer Older
Scott Chacon's avatar
Scott Chacon committed
1 2 3
Hg-Git Mercurial Plugin
=======================

muxator's avatar
muxator committed
4
* Homepage: https://hg-git.github.io/
5 6
* https://dev.heptapod.net/mercurial/hg-git (primary)
* https://bitbucket.org/durin42/hg-git (deprecated)
7 8
* https://github.com/schacon/hg-git (mirror)

Augie Fackler's avatar
Augie Fackler committed
9 10 11 12 13 14 15 16 17 18 19 20
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).
Scott Chacon's avatar
Scott Chacon committed
21

22 23 24
Dependencies
============

Augie Fackler's avatar
Augie Fackler committed
25 26
This plugin is implemented entirely in Python - there are no Git
binary dependencies, you do not need to have Git installed on your
27 28 29
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.
30

Kevin Bullock's avatar
Kevin Bullock committed
31 32 33 34 35 36 37 38 39 40 41 42 43
Installing
==========

Clone this repository somewhere and make the 'extensions' section in
your `~/.hgrc` file look something like this:

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

That will enable the Hg-Git extension for you.

See the Makefile for a list of compatible Mercurial versions.

44 45 46
Contributing
============

47 48 49 50 51 52 53 54
Patches preferred via e-mail to the [hg-git Google Group][1],
[hg-git@googlegroups.com][2]. We use a variant of Mercurial's own
contribution system. https://www.mercurial-scm.org/wiki/ContributingChanges
contains their full guidelines. See the [CONTRIBUTING](CONTRIBUTING) file
in the source for more details.

[1]: https://groups.google.com/forum/#!forum/hg-git
[2]: mailto:hg-git@googlegroups.com
55

56 57
Usage
=====
Scott Chacon's avatar
Scott Chacon committed
58

59
You can clone a Git repository from Hg by running `hg clone <url> [dest]`.  For
60
example, if you were to run
Scott Chacon's avatar
Scott Chacon committed
61

62
    $ hg clone git://github.com/schacon/hg-git.git
63

64 65
Hg-Git would clone the repository and convert it to an Hg repository
for you.
Scott Chacon's avatar
Scott Chacon committed
66

Augie Fackler's avatar
Augie Fackler committed
67 68 69 70
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
Scott Chacon's avatar
Scott Chacon committed
71

72
    git@github.com:schacon/hg-git.git
73

74
would read
Abderrahim Kitouni's avatar
Abderrahim Kitouni committed
75

76 77 78 79 80
    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:
Abderrahim Kitouni's avatar
Abderrahim Kitouni committed
81

82
    $ hg clone git+ssh://git@github.com/schacon/hg-git.git
Abderrahim Kitouni's avatar
Abderrahim Kitouni committed
83

84 85 86 87
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:
Scott Chacon's avatar
Scott Chacon committed
88

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

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

Augie Fackler's avatar
Augie Fackler committed
95 96
Now that you have an Hg repository that can push/pull to/from a Git
repository, you can fetch updates with `hg pull`.
Scott Chacon's avatar
Scott Chacon committed
97

98
    $ hg pull
99

Augie Fackler's avatar
Augie Fackler committed
100 101
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.
Scott Chacon's avatar
Scott Chacon committed
102

Kevin Bullock's avatar
Kevin Bullock committed
103 104 105
Hg-Git pushes your bookmarks up to the Git server as branches and will
pull Git branches down and set them up as bookmarks.

106 107
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
CoolOppo's avatar
CoolOppo committed
108
the following commands to convert the repository (it assumes you're running this
109
in $HOME).
110

111 112 113
    $ mkdir git-repo; cd git-repo; git init; cd ..
    $ cd hg-repo
    $ hg bookmarks hg
114
    $ hg push ../git-repo
115

Augie Fackler's avatar
Augie Fackler committed
116 117 118 119 120
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).
121

122 123
    $ cd git-repo
    $ git checkout -b master hg
124

Augie Fackler's avatar
Augie Fackler committed
125 126 127
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.
128

129 130 131
Commands
========

Kevin Bullock's avatar
Kevin Bullock committed
132
See `hg help -e hggit`.
133

Tay Ray Chuan's avatar
Tay Ray Chuan committed
134 135 136
Configuration
=============

137 138 139 140
git.authors
-----------

Git uses a strict convention for "author names" when representing changesets,
141
using the form `[realname] [email address]`. Mercurial encourages this
142
convention as well but is not as strict, so it's not uncommon for a Mercurial
143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
repo to have authors listed as, for example, simple usernames. hg-git by default
will attempt to translate Mercurial usernames using the following rules:

* If the Mercurial username fits the pattern `NAME <EMAIL>`, the git name will be
  set to NAME and the email to EMAIL.
* If the Mercurial username looks like an email (if it contains an `@`), the
  git name and email will both be set to that email.
* If the Mercurial username consists of only a name, the email will be set to `none@none`.
* Illegal characters (stray `<`s or `>`s) will be stripped out, and for `NAME <EMAIL>`
  usernames, any content after the right-bracket (for example, a second `>`) will be
  turned into a url-encoded sigil like `ext:(%3E)` in the git author name.

Since these default behaviors may not be what you want (`none@none`, for example,
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:
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175

    [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.

176 177 178 179 180 181 182 183 184 185 186 187 188 189
git.blockdotgit
---------------

Blocks exporting revisions to Git that contain a directory named .git or any
letter-case variation thereof. This prevents creating repositories that newer
versions of Git and many Git hosting services block due to security
concerns. Defaults to True.

git.blockdothg
--------------

Blocks importing revisions from Git that contain a directory named .hg. Defaults
to True.

190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
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
208 209

Above, if an hg repo had a named branch called `release_6_maintenance`, you could
210 211 212 213 214 215 216
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
217
not a `release_7_maintenance` named branch already, the bookmark will be named
218 219 220
`release_7_maintenance` with no usage of the suffix.

The `branch_bookmark_suffix` option is, like the `authors` option, intended for
221
migrating legacy hg named branches.   Going forward, an hg repo that is to
222
be linked with a git repo should only use bookmarks for named branching.
223

224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241
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.

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

242 243 244 245 246 247
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.
248

249 250 251 252 253 254 255
git.public
----------

A list of Git branches that should be considered "published", and therefore
converted to Mercurial in the 'public' phase. This is only used if
hggit.usephases is set.

256 257 258 259 260 261 262 263 264
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.

265 266
git.similarity
--------------
267

268 269 270 271 272
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).
273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290

hggit.mapsavefrequency
----------------------

Controls how often the mapping between Git and Mercurial commit hashes gets
saved when importing or exporting changesets. Set this to a number greater than
0 to save the mapping after converting that many commits. This can help when the
conversion encounters an error partway through a large batch of
changes. Defaults to 0, so that the mapping is saved once at the end.

hggit.usephases
---------------

When converting Git revisions to Mercurial, place them in the 'public' phase as
appropriate. Namely, revisions that are reachable from the remote Git
repository's HEAD will be marked 'public'. For most repositories, this means the
remote 'master' will be converted as public. This speeds up some local Mercurial
operations including `hg shelve`.