git-cinnabar 0.2
================

When you update, please read this file again, it may contain
important notes.

[ cinnabar is the common natural form in which mercury can be found on
  Earth. It contains mercury sulfide and its powder is used to make
  the vermillion pigment. ]

git-cinnabar is a git remote helper to interact with mercurial
repositories. Contrary to other such helpers[*], it doesn't use a
local mercurial clone under the hood, although it currently does
require mercurial to be installed for some of its libraries.

* This applies to the following tools:
  - https://github.com/felipec/git-remote-hg
  - https://github.com/rfk/git-remote-hg
  - https://github.com/cosmin/git-hg
  - https://github.com/todesschaf/git-hg
  - https://github.com/msysgit/msysgit/wiki/Guide-to-git-remote-hg
  - https://github.com/buchuki/gitifyhg/

The main focus at the moment is to make it work with mozilla-central
and related mercurial repositories and support Mozilla workflows (try
server, etc.).

Please note that no guarantee is made about using git-cinnabar version
x.y on a repository that was last used with version x.(y-2). So, for
example, there is no guarantee that upgrading from version 0.1 to version
0.3 will work. Upgrading from version 0.1 to version 0.2 and then to
version 0.3, however, is guaranteed to work. A command invoking
git-cinnabar, such as `git ls-remote $remote` or `git remote update
$remote`, must be run with each intermediate version.

Setup:
------

- Install mercurial.
- Add this directory to your PATH. If you have another git-remote-hg project
  in your PATH already, make sure the git-cinnabar path comes before.

Alternatively to the latter, you can do the following to build a native
helper for faster operation:
  $ git submodule update --init
  Then see git-core/INSTALL for build/install instructions, but run the
  commands in this directory. This will build/install git as well as
  the tools from this directory.

Usage:
------

$ git clone hg::<mercurial repo>

where <mercurial repo> can be a path to a local directory containing a
mercurial repository, or a http, https or ssh url.

Essentially, use git like you would for a git repository, but use a
hg:: url where you would use a git:// url.

Mercurial bookmarks are exposed as `refs/heads/bookmarks/$bookmark` remote
refs. If you want to interact exclusively with mercurial with bookmarks,
you can use a refspec like `refs/heads/bookmarks/*:refs/remotes/$remote/*`.

Mercurial branches are exposed as namespaces under `refs/heads/branches/`.
As mercurial branches can have multiple heads, each head is exposed
as `refs/heads/branches/$branch/$head`, where `$head` is the mercurial sha1
of the head changeset. There is however an exception to that pattern,
for the tip changeset of the branch, which is exposed as
`refs/heads/branches/$branch/tip`. If you only care about the tip changeset
of each branch, you can use a refspec like
`refs/heads/branches/*/tip:refs/remotes/$remote/*`.

See http://glandium.org/blog/?page_id=3438 for an example workflow for
Mozilla repositories.

Translating git commits to mercurial changesets and vice-versa:
---------------------------------------------------------------

When dealing with a remote repository that doesn't use the same
identifiers, things can easily get complicated. Git-cinnabar comes
with commands to know the mercurial changeset a git commit represents
and the other way around.

The following command will give you the git commit corresponding to
the given mercurial changeset sha1:

$ git cinnabar hg2git <changeset>

The following command will give you the mercurial changeset
corresponding to the given git commit sha1:

$ git cinnabar git2hg <commit>

Both commands allow abbreviated forms, as long as they are unambiguous
(no need for all the 40 hex digits of the sha1).

Avoiding metadata:
------------------

In some cases, it is not desirable to have git-cinnabar create metadata
for all pushed commits. Notably, for volatile commits such as those
used on the Mozilla try repository.

By default, git-cinnabar doesn't store metadata when pushing to
non-publishing repositories. It does otherwise.

This behavior can be changed per-remote with a remote.$remote.cinnabar-data
preference with one of the following values:
- `always`
- `never`
- `phase`

`phase` is the default described above. `always` and `never` are
self-explanatory.

Limitations:
------------

At the moment, push is limited to non-merge commits.

Pushing to a local mercurial repository (hg::/path) only works with
mercurial 3.0 or later.

There is no support for the following mercurial features:
- obsolescence markers
- phases
- namespaces

Checking corruptions:
---------------------

Git-cinnabar is still in early infancy, and its metadata might get
corrupted for some reason.

The following command allows to detect various types of metadata
corruption:
  git cinnabar fsck

This command will fix the corruptions it can, as well as adjust some
of the metadata that contains items that became unnecessary in newer
versions.

The `--manifests` and `--files` options may be added for additional
validation on manifests and files. Using either or both adds a
significant amount of work, and the command can take more than half
an hour on repositories the size of mozilla-central.