Fossil

How To Mirror A Fossil Repository On GitHub
Login

How To Mirror A Fossil Repository On GitHub

Beginning with Fossil version 2.9, you can mirror a Fossil-based project on GitHub (with limitations) by following these steps:

  1. Create an account on GitHub if you do not have one already. Log into that account.

  2. Create a new project. GitHub will ask you if you want to prepopulate your project with various things like a README file. Answer "no" to everything. You want a completely blank project. GitHub will then supply you with a URL for your project that will look something like this:

      https://github.com/username/project.git
    
  3. Back on your workstation, move to a checkout for your Fossil project and type:

    $ fossil git export /path/to/git/repo --autopush \
      https://username:password@github.com/username/project.git
    

    In place of the /path/to... argument above, put in some directory name that is outside of your Fossil checkout. If you keep multiple Fossil checkouts in a directory of their own, consider using ../git-mirror to place the Git export mirror alongside them, for example. Fossil will create this directory if necessary. This directory will become a Git repository that holds a translation of your Fossil repository.

    The --autopush option tells Fossil that you want to push the Git translation up to GitHub every time it is updated.

    The URL parameter is the same as the one GitHub gave you, but with your GitHub username and password added.

    If your GitHub account uses two-factor authentication (2FA), you will have to generate a personal access token and use that in place of your actual password in the URL. This token should have “repo” scope enabled, only.

    You can also run the command above outside of any open checkout of your project by supplying the “-R repository” option.

  4. Get some coffee. Depending on the size of your project, the initial "fossil git export" command in the previous step might run for several minutes.

  5. And you are done! Assuming everything worked, your project is now mirrored on GitHub.

  6. Whenever you update your project, simply run this command to update the mirror:

      $ fossil git export
    

    Unlike with the first time you ran that command, you don’t need the remaining arguments, because Fossil remembers those things. Subsequent mirror updates should usually happen in a fraction of a second.

  7. To see the status of your mirror, run:

      $ fossil git status
    

Notes:

Example GitHub Mirrors

As of this writing (2019-03-16) Fossil’s own repository is mirrored on GitHub at:

https://github.com/drhsqlite/fossil-mirror

In addition, an official Git mirror of SQLite is available:

https://github.com/sqlite/sqlite

The Fossil source repositories for these mirrors are at https://www2.fossil-scm.org/fossil and https://www2.sqlite.org/src, respectively. Both repositories are hosted on the same VM at Linode. On that machine, there is a cron job that runs at 17 minutes after the hour, every hour that does:

/usr/bin/fossil sync -u -R /home/www/fossil/fossil.fossil
/usr/bin/fossil sync -R /home/www/fossil/sqlite.fossil
/usr/bin/fossil git export -R /home/www/fossil/fossil.fossil
/usr/bin/fossil git export -R /home/www/fossil/sqlite.fossil

The initial two "sync" commands pull in changes from the primary Fossil repositories for Fossil and SQLite. The last two lines export the changes to Git and push the results up to GitHub.