diff --git a/README.asciidoc b/README.asciidoc
new file mode 100644
index 0000000..cb39fc5
--- /dev/null
+++ b/README.asciidoc
@@ -0,0 +1,124 @@
+'git-remote-hg' is the semi-official Mercurial bridge from Git project, once
+installed, it allows you to clone, fetch and push to and from Mercurial
+repositories as if they were Git ones:
+
+--------------------------------------
+git clone "hg::http://selenic.com/repo/hello"
+--------------------------------------
+
+To enable this, simply add the 'git-remote-hg' script anywhere in your `$PATH`:
+
+--------------------------------------
+wget https://raw.github.com/felipec/git/fc/master/git-remote-hg.py -O ~/bin/git-remote-hg
+chmod +x ~/bin/git-remote-hg
+--------------------------------------
+
+That's it :)
+
+== Configuration ==
+
+If you want to see Mercurial revisions as Git commit notes:
+
+--------------------------------------
+% git config core.notesRef refs/notes/hg
+--------------------------------------
+
+If you are not interested in Mercurial permanent and global branches (aka. commit labels):
+
+--------------------------------------
+% git config --global remote-hg.track-branches false
+--------------------------------------
+
+With this configuration, the 'branches/foo' refs won't appear.
+
+If you want the equivalent of 'hg clone --insecure':
+
+--------------------------------------
+% git config --global remote-hg.insecure true
+--------------------------------------
+
+If you want 'git-remote-hg' to be compatible with 'hg-git', and generate exactly the same commits:
+
+--------------------------------------
+% git config --global remote-hg.hg-git-compat true
+--------------------------------------
+
+== Notes ==
+
+Remember to run `git gc --aggressive` after cloning a repository, specially if
+it's a big one. Otherwise lots of space will be wasted.
+
+The oldest version of mercurial supported is 1.9. For the most part 1.8 works,
+but you might experience some issues.
+
+=== Pushing branches ===
+
+To push a branch, you need to use the "branches/" prefix:
+
+--------------------------------------
+% git checkout branches/next
+# do stuff
+% git push origin branches/next
+--------------------------------------
+
+All the pushed commits will receive the "next" Mercurial named branch.
+
+*Note*: Make sure you don't have +remote-hg.track-branches+ disabled.
+
+=== Cloning HTTPS ===
+
+The simplest way is to specify the user and password in the URL:
+
+--------------------------------------
+git clone hg::https://user:password@bitbucket.org/user/repo
+--------------------------------------
+
+You can also use the http://mercurial.selenic.com/wiki/SchemesExtension[schemes extension]:
+
+--------------------------------------
+[auth]
+bb.prefix = https://bitbucket.org/user/
+bb.username = user
+bb.password = password
+--------------------------------------
+
+Finally, you can also use the
+https://pypi.python.org/pypi/mercurial_keyring[keyring extension].
+
+However, some of these features require very new versions of 'git-remote-hg',
+so you might have better luck simply specifying the username and password in
+the URL.
+
+=== Caveats ===
+
+The only major incompatibility is that Git octopus merges (a merge with more
+than two parents) are not supported.
+
+Mercurial branches and bookmarks have some limitations of Git branches: you
+can't have both 'dev/feature' and 'dev' (as Git uses files and directories to
+store them).
+
+Multiple anonymous heads (which are useless anyway) are not supported; you
+would only see the latest head.
+
+Closed branches are not supported; they are not shown and you can't close or
+reopen. Additionally in certain rare situations a synchronization issue can
+occur (https://github.com/felipec/git/issues/65[Bug #65]).
+
+Limitations of the remote-helpers' framework apply. In particular, these
+commands don't work:
+
+* `git push origin :branch-to-delete`
+* `git push origin old:new` (it will push 'old') (Git v2.0)
+* `git push --dry-run origin branch` (it will push) (Git v2.0)
+
+== Other projects ==
+
+There are other 'git-remote-hg' projects out there, do not confuse this one,
+this is the one distributed officially by the Git project:
+
+* https://github.com/msysgit/msysgit/wiki/Guide-to-git-remote-hg[msysgit's git-remote-hg]
+* https://github.com/rfk/git-remote-hg[rfk's git-remote-hg]
+
+For a comparison between these and other projects go
+https://github.com/felipec/git/wiki/Comparison-of-git-remote-hg-alternatives[here].