3.17 Exporting to GIT

Monotone is capable of exporting the contents of a database to stdout in a form suitable to be piped to git-fast-import(1):

$ mkdir test.git
$ cd test.git
$ git init
$ mtn --db test.mtn git_export | git fast-import

While this feature has been tested and verified to some extent with various “real-world” monotone databases it is important to realize that translating from one version control system to another can be a lossy process. Git represents things somewhat differently than monotone does and cannot fully represent some things that monotone can. In particular git does not treat directories as first class objects as monotone does and does not use certificates to represent author, date, branch and tag values so some differences are to be expected.

Git separates the concept of committer from the concept of author while monotone allows multiple author certs. In an attempt to represent these different concepts the git exporter uses the value of the author cert as the git author and the key used to sign the author cert as the git committer. When there are multiple author certs the git exporter arbitrarily choses one of them. The full list of monotone certs may be exported in the git commit message using the --log-certs option described in VCS.

Monotone author names often look like raw email addresses such as "user@example.com". These are not considered valid by git which requires the display name and leading ‘<’ and trailing ‘>’ characters around email addresses such as "User Name <user@example.com>". The git exporter deals with this difference in several ways:

• revisions that don’t have any author certs will default to using Unknown <unknown> for both the author and committer.
• revisions that have one or more author certs will use the value of one author cert as the author and the key used to sign this cert as the committer.
• both author and committer will be looked up in the file specified by the --authors-file option described in VCS and translated to the specified value if found.
• any author or committer value not found in the authors file will be processed by the unmapped_git_author hook which may adjust the value so that it represents a valid value.

All git author and committer values will be validated by the validate_git_author hook before being written to the output stream. The export will abort if any author or committer value is rejected by the validation hook.

Branch names used by monotone are allowed to contain characters that are not considered valid by git. These may be mapped to other names using the --branches-file option described in VCS

A monotone revision may have multiple changelog certs and multiple comment certs. The git exporter deals with these by first concatenating all of the changelog certs followed by all of the comment certs into one message to use as the git commit message. Duplicate changelog or comment cert messages that may exist due to automated merges are removed.

Exporting a database may be a time consuming and involved process, depending on the size and nature of the database. A 200MB database should export in less than an hour but may take several hours or longer depending on factors such as hardware, revision sizes, roster sizes and many others. The monotone process exporting such a database should require less than 200MB of RAM but may require considerably more in some cases. If the exported file is written to disk it will likely be substantially larger than the associated database, perhaps between 400MB to 4GB in size.

Anyone using the git exporter must take full responsibility for verifying that the exported repository matches their expectations and requirements.