1 files changed, 141 insertions, 0 deletions
diff --git a/www/inout.wiki b/www/inout.wiki
new file mode 100644
index 0000000..74b8e97
--- /dev/null
+++ b/www/inout.wiki
@@ -0,0 +1,141 @@
+<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>