Import And Export

Import And Export

Fossil has the ability to import and export repositories from and to 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.

Git → Fossil

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

cd git-repo
git fast-export --all | fossil import --git new-repo.fossil

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.

Note that in new imports, Fossil defaults to using the email component of the Git committer (or author if --use-author is passed) to attribute check-ins in the imported repository. Alternatively, the --attribute option can be passed to have all commits by a given committer attributed to a desired username. This will create and populate the new fx_git 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.

Converting Repositories on Windows

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

For some reason, the current version of PowerShell included with Windows chokes on the conversion when the in-flight repository size exceeds available memory. We do not know why it buffers the entire stream emitted by "git fast-export" before sending it along to Fossil, but we've seen the problem recur on multiple machines.

While one workaround is to fall back to cmd.exe — which doesn't seem to be affected by this problem — we instead recommend using Mirosoft's own 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.

Fossil → Git

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

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

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 recommended.

Mirror A Fossil Repository In Git

Fossil version 2.9 and later supports a simple mechanism for doing a Git or GitHub mirror of a Fossil repository. See that separate document for details. Fossil is self-hosting, but a GitHub mirror of Fossil is available as a proof-of-concept.

Bidirectional Synchronization

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:

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                  \

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

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                  \

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

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