Import And Export

<title>Import And Export</title>

Fossil has the ability to import and export repositories from and to
[http://git-scm.com/ | Git].  And since most other version control
systems will also import/export from Git, that means that you can
import/export a Fossil repository to most version control systems using
Git as an intermediary.

<h2>Git → Fossil</h2>

To import a Git repository into Fossil, say something like:

<pre>
cd git-repo
git fast-export --all | fossil import --git new-repo.fossil
</pre>

The 3rd argument to the "fossil import"
command is the name of a new Fossil repository that is created to hold the Git
content.

The --git option is not actually required.  The git-fast-export file format
is currently the only VCS interchange format that Fossil understands.  But
future versions of Fossil might be enhanced to understand other VCS
interchange formats, and so for compatibility, use of the
--git option is recommended.

<a id="fx_git"></a>
Note that in new imports, Fossil defaults to using the email component of the
Git <em>committer</em> (or <em>author</em> if <code>--use-author</code> is
passed) to attribute check-ins in the imported repository. Alternatively, the
[/help/import | <code>--attribute</code>] option can be passed to have all
commits by a given committer attributed to a desired username. This will create
and populate the new <code>fx_git</code> table in the repository database to
maintain a record of correspondent usernames and email addresses that can be
used in subsequent exports or incremental imports.

<h3>Converting Repositories on Windows</h3>

The above commands work best on proper POSIX systems like Linux, macOS,
and the BSDs, where everything <tt>git</tt> sends is consumed by
<tt>fossil</tt> as soon as it can manage, with both programs working
concurrently.

Historically, PowerShell indiscriminately sent objects — as opposed to raw
bytes — through its pipes, and buffered standard input for external processes.
This made it choke on the conversion when the in-flight repository size
exceeded available memory. Starting with version 7.4 (2023-11-16), PowerShell
supports byte stream piping between native commands and file redirection.

If you are stuck with an older version, one workaround is to fall back to
<tt>cmd.exe</tt> — which doesn't seem to be affected by this problem.
Nevertheless, we instead recommend using
Microsoft's own [https://learn.microsoft.com/en-us/windows/wsl/ | Windows
Subsystem for Linux] or either of the two popular "Git for Windows"
distributions based on MSYS2. They handle pipes the POSIX way, avoiding
any dependency on the amount of data involved.

<h2>Fossil → Git</h2>

To convert a Fossil repository into a Git repository, run commands like
this:

<pre>
git init new-repo
cd new-repo
fossil export --git ../repo.fossil | git fast-import
</pre>

In other words, create a new Git repository, then pipe the output from the
"fossil export --git" command into the "git fast-import" command.

Note that the "fossil export --git" command only exports the versioned files.
Tickets and wiki and events are not exported, since Git does not understand
those concepts.

As with the "import" command, the --git option is not required
since the git-fast-export file format is currently the only VCS interchange
format that Fossil will generate.  However,
future versions of Fossil might add the ability to generate other
VCS interchange formats, and so for compatibility, the use of the --git
option is recommended.

<h2>Mirror A Fossil Repository In Git</h2>

Fossil version 2.9 and later supports a simple mechanism for
doing a Git or
[./mirrortogithub.md|GitHub mirror of a Fossil repository].
See that separate document for details.  Fossil is self-hosting,
but a [https://github.com/drhsqlite/fossil-mirror|GitHub mirror of Fossil]
is available as a proof-of-concept.

<h2>Bidirectional Synchronization</h2>
Fossil also has the ability to synchronize with a Git repository via repeated
imports and/or exports.  To do this, it uses marks files to store a record of
artifacts which are known by both Git and Fossil to exist at a given point in
time.

To illustrate, consider the example of a remote Fossil repository that a
user wants to import into a local Git repository.  First, the user would clone
the remote repository and import it into a new Git repository:

<pre>
fossil clone /path/to/remote/repo.fossil repo.fossil
mkdir repo
cd repo
fossil open ../repo.fossil
mkdir ../repo.git
cd ../repo.git
git init .
fossil export --git --export-marks ../repo/fossil.marks  \
       ../repo.fossil | git fast-import                  \
       --export-marks=../repo/git.marks
</pre>

Once the import has completed, the user would need to <tt>git checkout
trunk</tt>.  At any point after this, new changes can be imported from the
remote Fossil repository:

<pre>
cd ../repo
fossil pull
cd ../repo.git
fossil export --git --import-marks ../repo/fossil.marks  \
       --export-marks ../repo/fossil.marks               \
       ../repo.fossil | git fast-import                  \
       --import-marks=../repo/git.marks                  \
       --export-marks=../repo/git.marks
</pre>

Changes in the Git repository can be exported to the Fossil repository and then
pushed to the remote:

<pre>
git fast-export --import-marks=../repo/git.marks                  \
    --export-marks=../repo/git.marks --all | fossil import --git  \
    --incremental --import-marks ../repo/fossil.marks             \
    --export-marks ../repo/fossil.marks ../repo.fossil
cd ../repo
fossil push
</pre>