# # # patch "NEWS" # from [c250beffa9fecd94d00db49663e5003df8b1cfee] # to [3c147657b89908d75235e849be0407a42afd2039] # # patch "monotone.texi" # from [6ff6c9ad19c38f1a46e635ec14ece77c84d697b0] # to [df08abf7652deb0bde6b31f14d9a72c61a313651] # ============================================================ --- NEWS c250beffa9fecd94d00db49663e5003df8b1cfee +++ NEWS 3c147657b89908d75235e849be0407a42afd2039 @@ -35,6 +35,10 @@ - Additional '--full' option for 'mtn db info' to display some statistic analysis of the date certs in the database. + - A monotone database may be exported in the git fast-import format + using the git_export command. The output from this command may be + piped into git fast-import or other tools supporting this format. + Internal - Using 64 bit integer values to represent dates internally. This ============================================================ --- monotone.texi 6ff6c9ad19c38f1a46e635ec14ece77c84d697b0 +++ monotone.texi df08abf7652deb0bde6b31f14d9a72c61a313651 @@ -29,7 +29,7 @@ Copyright @copyright{} 2003, 2004 Graydon Hoare @* Copyright @copyright{} 2004, 2005, 2006 Nathaniel Smith @* -Copyright @copyright{} 2005, 2008 Derek Scherger @* +Copyright @copyright{} 2005, 2008, 2009 Derek Scherger @* Copyright @copyright{} 2005, 2006 Daniel Carosone @* Copyright @copyright{} 2006 Jeronimo Pellegrini @* Copyright @copyright{} 2006 Alex Queiroz @* @@ -2619,6 +2619,7 @@ @chapter Advanced Uses * Merging:: Merging with external tools, handling binary files. * Migrating and Dumping:: Changing the underlying storage system. * Importing from CVS:: Building a monotone database from a CVS repository. +* Exporting to GIT:: Building a git repository from a monotone database. * Using packets:: Transferring data ``by hand''. @end menu @@ -3862,7 +3863,7 @@ @section Migrating and Dumping @command{init} your database before a @command{load}. @page address@hidden Importing from CVS, Using packets, Migrating and Dumping, Advanced Uses address@hidden Importing from CVS, Exporting to GIT, Migrating and Dumping, Advanced Uses @section Importing from CVS Monotone is capable of reading CVS files directly and importing them @@ -3906,7 +3907,92 @@ @section Importing from CVS @end smallexample @page address@hidden Using packets, , Importing from CVS, Advanced Uses address@hidden Exporting to GIT, Using packets, Importing from CVS, Advanced Uses address@hidden Exporting to GIT + +Monotone is capable of exporting the contents of a database to address@hidden in a form suitable to be piped to git-fast-import(1): + address@hidden address@hidden +$ mkdir test.git +$ cd test.git +$ git init +$ mtn --db test.mtn git_export | git fast import address@hidden group address@hidden smallexample + +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 address@hidden, @code{date}, @code{branch} and @code{tag} values so +some differences are to be expected. + +Git separates the concept of @code{committer} from the concept of address@hidden while monotone allows multiple @code{author} certs. In +an attempt to represent these different concepts the git exporter uses +the @emph{value} of the author cert as the git author and the address@hidden 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 @option{--log-certs} option described in address@hidden + +Monotone author names often look like raw email addresses such as address@hidden"user@@example.com"}. These are not considered valid by git +which requires leading `<' and trailing `>' characters around email +addresses and by convention often includes the display name with the +email address such as @code{"User Name "}. The git +exporter deals with this difference in several ways: address@hidden address@hidden +revisions that don't have any author certs will default to using address@hidden} for both the author and committer. address@hidden +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. address@hidden +both author and committer will be looked up in the file specified by +the @option{--authors-file} option described in @ref{GIT} and +translated to the specified value if found. address@hidden +any author or committer that does not contain both `<' and `>' +characters will have an initial ``<' character and a final `>' +character added so that they may form valid values. address@hidden itemize + +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 @option{--branches-file} option described in @ref{GIT} + +A monotone revision may have multiple @code{changelog} certs and +multiple @code{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 address@hidden more in some cases. If the exported file is +written to disk it will likely be @emph{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. + address@hidden address@hidden Using packets, , Exporting to GIT, Advanced Uses @section Using packets Suppose you made changes to your database, and want to send those @@ -4462,6 +4548,7 @@ @chapter Command Reference * Database:: Manipulation of your database as a whole * Automation:: Running monotone from other programs * RCS:: Importing legacy version control files +* GIT:: Exporting a monotone repository to git @end menu @@ -9232,7 +9319,7 @@ @section Automation @end ftable @page address@hidden RCS, , Automation, Command Reference address@hidden RCS, GIT, Automation, Command Reference @section RCS @ftable @command @@ -9262,6 +9349,92 @@ @section RCS @end ftable address@hidden address@hidden GIT, ,RCS, Command Reference + address@hidden GIT + address@hidden @command address@hidden mtn git_export address@hidden address@hidden address@hidden mtn git_export address@hidden address@hidden address@hidden mtn git_export [--log-revids] [--log-certs] address@hidden mtn git_export address@hidden + +This command exports all revisions from the current monotone database +to @code{stdout} in a format that can be piped directly to git +fast-import. + +The @option{--authors-file} option may be used to map monotone author +names to different values in a manner similar to that documented in +git-svn(1). Author mappings are specified in the @var{authors-file} as: address@hidden +loginname = Joe User address@hidden verbatim +The @option{--branches-file} option may be used to map monotone branch +names to different values. This may be required as monotone allows +branch names that are not valid according to git. Branch mappings are +specified in the @var{branches-file} as: address@hidden +monotone-branch-name = git-branch-name address@hidden verbatim +Revisions with no author cert will use for both the author +and the committer. These can be mapped to other values using the address@hidden option. + +The @option{--import-marks} and @option{--export-marks} options are +similar to those documented in git-fast-export(1) and +git-fast-import(1). These may be used for incremental exports and may +also be useful for repository verification. The @var{marks-file} is +read on startup if @option{--import-marks} is specified and all marked +revs are excluded from the export. The @var{marks-file} is written on +completion if @option{--export-marks} is specified and will contain +marks for all revs that were exported in addition to any marks that +were read on startup. It is safe to use the same file for both address@hidden and @option{--export-marks} but different +files may also be used. + +The original monotone revision ids may be included in the exported git +commit messages using the @option{--log-revids} option. These will +appear as: address@hidden +Monotone-Parent: ... +Monotone-Revision: ... address@hidden verbatim +in the git commit messages and may be useful for repository +verification. Merge revisions with two parents will include two address@hidden lines. + +The original monotone values for @code{author}, @code{date}, address@hidden and @code{tag} certificates may be included in the +exported git commit messages using the @option{--log-certs} +option. These will appear as: address@hidden +Monotone-Author: ... +Monotone-Date: ... +Monotone-Branch: ... +Monotone-Tag: ... address@hidden verbatim +in the git commit messages and may be useful for repository +verification or maintaining information that is otherwise not +maintained by git. In particular monotone may have several values for +each of these certs and git only represents a single @code{author} and address@hidden value. + +References to the original monotone branches and tags are exported as address@hidden/tags/} and @code{refs/heads/}. In +addition, references to the original monotone revision ids, the root +revisions and the leaf revisions may be exported using address@hidden, @option{--refs=roots} and @option{--refs=leaves} +respectively. These references are exported as address@hidden/mtn/revs/}, @code{refs/mtn/roots/} and address@hidden/mtn/leaves/} and may be useful for repository +verification. These additional references should probably not be +maintained after the exported repository has been verified as they +cause considerable clutter in tools like gitk. + address@hidden ftable + + @node Hook Reference, Special Topics, Command Reference, Top @chapter Hook Reference