'\" t
.\"     Title: git-remote-hg
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 07/21/2014
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "GIT\-REMOTE\-HG" "1" "07/21/2014" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
git-remote-hg \- bidirectional bridge between Git and Mercurial
.SH "SYNOPSIS"
.sp
.nf
\fIgit clone\fR hg::<hg repository>
.fi
.SH "DESCRIPTION"
.sp
This tool allows you to transparently clone, fetch and push to and from Mercurial repositories as if they were Git ones\&.
.sp
To use it you simply need to use the "\fIhg::\fR" prefix when specifying a remote URL (e\&.g\&. when cloning)\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
$ git clone hg::http://selenic\&.com/repo/hello
.fi
.if n \{\
.RE
.\}
.SH "CONFIGURATION"
.sp
If you want to see Mercurial revisions as Git commit notes:
.sp
.if n \{\
.RS 4
.\}
.nf
% git config core\&.notesRef refs/notes/hg
.fi
.if n \{\
.RE
.\}
.sp
If you are not interested in Mercurial permanent and global branches (aka\&. commit labels):
.sp
.if n \{\
.RS 4
.\}
.nf
% git config \-\-global remote\-hg\&.track\-branches false
.fi
.if n \{\
.RE
.\}
.sp
With this configuration, the \fIbranches/foo\fR refs won\(cqt appear\&.
.sp
If you want the equivalent of hg clone \-\-insecure:
.sp
.if n \{\
.RS 4
.\}
.nf
% git config \-\-global remote\-hg\&.insecure true
.fi
.if n \{\
.RE
.\}
.sp
If you want \fIgit\-remote\-hg\fR to be compatible with \fIhg\-git\fR, and generate exactly the same commits:
.sp
.if n \{\
.RS 4
.\}
.nf
% git config \-\-global remote\-hg\&.hg\-git\-compat true
.fi
.if n \{\
.RE
.\}
.SH "NOTES"
.sp
Remember to run git gc \-\-aggressive after cloning a repository, specially if it\(cqs a big one\&. Otherwise lots of space will be wasted\&.
.sp
The oldest version of Mercurial supported is 1\&.9\&. For the most part 1\&.8 works, but you might experience some issues\&.
.SS "Pushing branches"
.sp
To push a Mercurial named branch, you need to use the "branches/" prefix:
.sp
.if n \{\
.RS 4
.\}
.nf
% git checkout branches/next
# do stuff
% git push origin branches/next
.fi
.if n \{\
.RE
.\}
.sp
All the pushed commits will receive the "next" Mercurial named branch\&.
.sp
\fBNote\fR: Make sure you don\(cqt have remote\-hg\&.track\-branches disabled\&.
.SS "Cloning HTTPS"
.sp
The simplest way is to specify the user and password in the URL:
.sp
.if n \{\
.RS 4
.\}
.nf
git clone hg::https://user:password@bitbucket\&.org/user/repo
.fi
.if n \{\
.RE
.\}
.sp
You can also use the schemes extension:
.sp
.if n \{\
.RS 4
.\}
.nf
[auth]
bb\&.prefix = https://bitbucket\&.org/user/
bb\&.username = user
bb\&.password = password
.fi
.if n \{\
.RE
.\}
.sp
Finally, you can also use the keyring extension\&.
.SH "CAVEATS"
.sp
The only major incompatibility is that Git octopus merges (a merge with more than two parents) are not supported\&.
.sp
Mercurial branches and bookmarks have some limitations of Git branches: you can\(cqt have both \fIdev/feature\fR and \fIdev\fR (as Git uses files and directories to store them)\&.
.sp
Multiple anonymous heads (which are useless anyway) are not supported; you would only see the latest head\&.
.sp
Closed branches are not supported; they are not shown and you can\(cqt close or reopen\&. Additionally in certain rare situations a synchronization issue can occur (Bug #65)\&.