diff options
Diffstat (limited to 'www/mirrortogithub.md')
| -rw-r--r-- | www/mirrortogithub.md | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/www/mirrortogithub.md b/www/mirrortogithub.md new file mode 100644 index 0000000..9360ca6 --- /dev/null +++ b/www/mirrortogithub.md @@ -0,0 +1,166 @@ +# 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](./mirrorlimitations.md)) +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: + + <blockquote> + <pre> + $ fossil git export /path/to/git/repo --autopush \ + https://<font color="orange">username</font>:<font color="red">password</font>@github.com/username/project.git + </pre> + </blockquote> + + In place of the <code>/path/to...</code> argument above, put in + some directory name that is <i>outside</i> of your Fossil checkout. If + you keep multiple Fossil checkouts in a directory of their own, + consider using <code>../git-mirror</code> 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 <code>--autopush</code> 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 <font color="orange">username</font> and <font + color="red">password</font> added. + + If your GitHub account uses two-factor authentication (2FA), you + will have to <a href="https://github.com/settings/tokens">generate + a personal access token</a> 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 “<code>-R repository</code>” + option. + +4. Get some coffee. Depending on the size of your project, the + initial "<code>fossil git export</code>" 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: + + * Unless you specify --force, the mirroring only happens if the Fossil + repo has changed, with Fossil reporting "no changes", because Fossil + does not care about the success or failure of the mirror run. If a mirror + run failed (for example, due to an incorrect password, or a transient + error at github.com), Fossil will not retry until there has been a repo + change or --force is supplied. + + * The mirroring is one-way. If you check in changes on GitHub, those + changes will not be reabsorbed by Fossil. There are technical problems + that make a two-way mirror all but impossible. (This is not to be + confused with the ability to import a Fossil mirror from Github back + into a Fossil repository. That works, but it is not a mirror.) + + This also means that you cannot accept pull requests on GitHub. + + * The "`fossil git export`" command creates subprocesses that run "`git`" + commands, so you must have Git installed on your machine for any + of this to work. + + * The Git repository will have an extra unmanaged top-level directory named + "`.mirror_state`" that contains one or more files. Those files are + used to store the intermediate state of the translation so that + subsequent invocations of "`fossil git export`" will know where you + left off the last time and what new content needs to be moved over into + Git. Be careful not to mess with the `.mirror_state` directory or + any of its contents. Do not put those files under Git management. Do + not edit or delete them. + + * The name of the "trunk" branch is automatically translated into "master" + in the Git mirror unless you give the `--mainbranch` option. + + * Only check-ins and simple tags are translated to Git. Git does not + support wiki or tickets or unversioned content or any of the other + features of Fossil that make it so convenient to use, so those other + elements cannot be mirrored in Git. + + * In Git, all tags must be unique. If your Fossil repository has the + same tag on two or more check-ins, the tag will only be preserved on + the chronologically newest check-in. + + * There is a + [long list of restrictions](https://git-scm.com/docs/git-check-ref-format) + on tag and branch names in Git. If any of your Fossil tag or branch names + violate these rules, then the names are translated prior to being exported + to Git. The translation usually involves converting the offending characters + into underscores. + + * If your Fossil user contact info is not set and this repository was not + initially [imported from Git](./inout.wiki), `fossil git export` will + construct a generic `user@noemail.net` for the Git *committer* and *author* + email fields of each commit. However, Fossil will first attempt to parse an + email address from your user contact info, which can be set through a + Fossil [UI][ui] browser window or with the [`user contact`][usercmd] + subcommand on the command line. Alternatively, if this repository was + previously imported from Git using the [`--attribute`][attr] option, the + [`fx_git`][fxgit] table will be queried for correspondent email addresses. + Only if neither of these methods produce a user specified email will the + abovementioned generic address be used. + +[attr]: /help/import +[fxgit]: ./inout.wiki#fx_git +[ui]: /help/ui +[usercmd]: /help/user + + +## <a id='ex1'></a>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](https://www.linode.com). On that machine, there is a +[cron job](https://linux.die.net/man/8/cron) +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. |