Skip to content
Snippets Groups Projects
Commit 55e0a6d4 authored by Dan Villiom Podlaski Christiansen's avatar Dan Villiom Podlaski Christiansen
Browse files

README: update content and improve syntax

parent 8fd5a9ee
No related branches found
No related tags found
1 merge request!78Preparations for a release
Hg-Git Mercurial Plugin
=======================
- Homepage: https://hg-git.github.io/
- https://dev.heptapod.net/mercurial/hg-git (primary)
- https://bitbucket.org/durin42/hg-git (deprecated)
- https://github.com/schacon/hg-git (mirror)
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>`_)
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
......@@ -12,7 +15,7 @@
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
system to another, so you can push via a Mercurial 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
......@@ -22,11 +25,10 @@
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 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.
This plugin is implemented entirely in Python — there are no Git
binary dependencies, and you do not need to have Git installed on your
system. The only dependencies are Mercurial 4.4 or later and a
relatively recent Dulwich.
Installing
==========
......@@ -39,8 +41,16 @@
That will enable the Hg-Git extension for you.
See the Makefile for a list of compatible Mercurial versions.
You can also install the plugin using your favourite package manager,
e.g. pip::
pip3 install hggit
And enable it from somewhere in your ``$PYTHONPATH``::
[extensions]
hggit =
Contributing
============
......@@ -43,15 +53,17 @@
Contributing
============
Patches preferred via e-mail to the `hg-git Google
Group <https://groups.google.com/forum/#!forum/hg-git>`__,
hg-git@googlegroups.com. 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.
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>`_.
Usage
=====
......@@ -54,11 +66,7 @@
Usage
=====
You can clone a Git repository from Hg by running
``hg clone <url> [dest]``. For example, if you were to run
::
$ hg clone git://github.com/schacon/hg-git.git
You can clone a Git repository from Mercurial by running
``hg clone <url> [dest]``. For example, if you were to run::
......@@ -64,9 +72,3 @@
Hg-Git would clone the repository and convert it to an Hg repository for
you.
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
$ hg clone git://github.com/hg-git/hg-git.git
......@@ -72,9 +74,5 @@
::
git@github.com:schacon/hg-git.git
would read
::
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.
......@@ -80,14 +78,6 @@
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::
$ hg clone git+ssh://git@github.com/schacon/hg-git.git
If you are starting from an existing Hg repository, you have to set up a
If you are starting from an existing Mercurial 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::
......@@ -90,8 +80,8 @@
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::
$ cd hg-git # (an Hg repository)
$ cd hg-git # (a Mercurial repository)
$ # edit .hg/hgrc and add the target git url in the paths section
$ hg push
......@@ -95,6 +85,6 @@
$ # edit .hg/hgrc and add the target git url in the paths section
$ hg push
This will convert all your Hg data into Git objects and push them to the
This will convert all your Mercurial data into Git objects and push them to the
Git server.
......@@ -99,9 +89,7 @@
Git server.
Now that you have an Hg repository that can push/pull to/from a Git
repository, you can fetch updates with ``hg pull``.
::
Now that you have a Mercurial repository that can push/pull to/from a Git
repository, you can fetch updates with ``hg pull``::
$ hg pull
......@@ -113,13 +101,11 @@
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 the following commands to convert the repository (it
assumes you're running this in $HOME).
::
or HTTPS. Use the following commands to convert the repository, it
assumes you're running this in ``$HOME``::
$ mkdir git-repo; cd git-repo; git init; cd ..
$ cd hg-repo
$ hg bookmarks hg
$ hg push ../git-repo
......@@ -120,17 +106,18 @@
$ mkdir git-repo; cd git-repo; git init; cd ..
$ cd hg-repo
$ hg bookmarks hg
$ hg push ../git-repo
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).
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``).
::
$ cd git-repo
$ git checkout -b master hg
......@@ -131,11 +118,12 @@
::
$ cd git-repo
$ git checkout -b master hg
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.
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.
``.gitignore`` and ``.hgignore``
--------------------------------
......@@ -155,9 +143,9 @@
=============
git.authors
-----------
``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
......@@ -160,8 +148,8 @@
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, for example,
uncommon for a Mercurial repository to have authors listed as, for example,
simple usernames. hg-git by default will attempt to translate Mercurial
usernames using the following rules:
......@@ -165,6 +153,6 @@
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
- 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
......@@ -169,8 +157,8 @@
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.
``@``), 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
......@@ -172,8 +160,8 @@
- 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.
url-encoded sigil like ``ext:(%3E)`` in the Git author name.
Since these default behaviors may not be what you want (``none@none``,
......@@ -178,5 +166,5 @@
Since these default behaviors may not be what you want (``none@none``,
for example, shows up unpleasantly on Github as "illegal email
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
......@@ -181,6 +169,6 @@
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::
Mercurial to Git only, by modifying ``hgrc`` as such::
[git]
authors = authors.txt
......@@ -193,10 +181,10 @@
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.
It should be noted that this translation is in *the Mercurial to Git
direction only*. Changesets coming from Git back to Mercurial will not
translate back into Mercurial usernames, so it's best that the same
username/email combination be used on both the Mercurial and Git sides; the
author file is mostly useful for translating legacy changesets.
......@@ -201,7 +189,7 @@
git.blockdotgit
---------------
``git.blockdotgit``
-------------------
Blocks exporting revisions to Git that contain a directory named .git or
any letter-case variation thereof. This prevents creating repositories
......@@ -209,10 +197,10 @@
security concerns. Defaults to True.
git.blockdothg
--------------
``git.blockdothg``
------------------
Blocks importing revisions from Git that contain a directory named .hg.
Defaults to True.
......@@ -214,8 +202,8 @@
Blocks importing revisions from Git that contain a directory named .hg.
Defaults to True.
git.branch_bookmark_suffix
--------------------------
``git.branch_bookmark_suffix``
------------------------------
......@@ -221,3 +209,3 @@
hg-git does not convert between Mercurial named branches and git
Hg-Git does not convert between Mercurial named branches and git
branches as the two are conceptually different; instead, it uses
......@@ -223,16 +211,17 @@
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::
Mercurial bookmarks to represent the concept of a Git branch.
Therefore, when translating a Mercurial repository 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
a Mercurial repository 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
......@@ -235,7 +224,7 @@
[git]
branch_bookmark_suffix=_bookmark
Above, if an hg repo had a named branch called
Above, if a Mercurial repository 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
......@@ -240,6 +229,6 @@
``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
``_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 a Mercurial named
branch of that name exists. E.g., when changes to the
......@@ -245,5 +234,5 @@
branch of that name exists. E.g., when changes to the
``release_6_maintenance`` branch are checked into git, these will be
``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
......@@ -251,8 +240,8 @@
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
intended for migrating legacy hg named branches. Going forward, a Mercurial
repository that is to be linked with a Git repository should only use bookmarks for
named branching.
......@@ -256,11 +245,11 @@
named branching.
git.findcopiesharder
--------------------
``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.
......@@ -261,9 +250,9 @@
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
----------
``git.intree``
--------------
......@@ -269,7 +258,7 @@
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
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``::
......@@ -277,11 +266,11 @@
intree = True
git.mindate
-----------
``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.
......@@ -282,11 +271,11 @@
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.
git.public
----------
``git.public``
--------------
A list of Git branches that should be considered "published", and
therefore converted to Mercurial in the 'public' phase. This is only
......@@ -290,6 +279,6 @@
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.
used if ``hggit.usephases`` is set.
......@@ -294,7 +283,7 @@
git.renamelimit
---------------
``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
......@@ -303,8 +292,8 @@
``diff.renameLimit`` config. The default is "400", the same as Git.
git.similarity
--------------
``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"
......@@ -313,8 +302,8 @@
the file has stayed the same. The default is "0" (disabled).
hggit.mapsavefrequency
----------------------
``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
......@@ -323,4 +312,7 @@
large batch of changes. Defaults to 0, so that the mapping is saved once
at the end.
Please note that this is meaningless for an initial clone, as any
error or interruption will delete the destination. So instead of
cloning a large Git repository, you might want to pull instead::
......@@ -326,6 +318,19 @@
hggit.usephases
---------------
$ hg init linux
$ cd linux
$ echo "[paths]\ndefault = https://github.com/torvalds/linux" > .hg/hgrc
$ hg pull
…and be extremely patient. Please note that converting very large
repositories may take *days* rather than mere *hours*, and may run
into issues with available memory for very long running clones. Even
any small, undiscovered leak will build up when processing hundreds of
thousands of files and commits. Cloning the Linux kernel is likely a
pathological case, but other storied repositories such as CPython do
work well, even if the initial clone requires a some patience.
``hggit.usephases``
-------------------
When converting Git revisions to Mercurial, place them in the 'public'
phase as appropriate. Namely, revisions that are reachable from the
......@@ -329,7 +334,7 @@
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``.
remote Git repository's ``HEAD`` will be marked *public*. For most
repositories, this means the remote ``master`` branch will be
converted as public. Publishing commits prevents their modification,
and speeds up many local Mercurial operations, such as ``hg shelve``.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment