Artifact c36bc320c43e2639ab9ee7aaea61edd06854b08e5b9c4c781c625883a872435b:

• File www/inout.wiki — part of check-in [19c347b460] at 2023-09-11 08:16:08 on branch trunk — Added the "Converting Repositories on Windows" section to the inout doc to cover a problem case involving PowerShell and to give solutions. (user: wyoung size: 6428)

---

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.

Windows has problems in this area which we can trace back to MS-DOS, where command.com emulated pipes in terms of temporary files. The source program's output was written to disk, and only when that executable stopped was the consuming program launched, with its input silently redirected in from the temporary file in the background. This problem isn't likely to affect you these days unless you boot up an old copy of Windows 98 or similar, being DOS-based, thus having command.com as its shell.

You may therefore wonder why we dig this historical fact up. Didn't Microsoft correct that in rebuilding their shell as cmd.exe for the Windows NT era? Yes, they did, but they then went and broke this underlying assumption again when they later designed PowerShell. Because PS wants to believe everything is an object stream between .NET programs and thus needs to translate expected data formats between them, it falls down when you try to run a command like the above when the size of the translated repository is greater than the size of available memory. PowerShell tries to load the entire fast-export output before sending it out to "fossil import," and that only works on sufficiently small repositories.

Mirosoft's own Windows Subsystem for Linux solves this problem, as do userspace clones like Cygwin and the MSYS2 underpinnings of the two major "Git for Windows" products. You may successfully use any of these systems to do the conversion directly.

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                  \
       --export-marks=../repo/git.marks

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                  \
       --export-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