|
1
|
# How To Mirror A Fossil Repository On GitHub |
|
2
|
|
|
3
|
Beginning with Fossil version 2.9, you can mirror a Fossil-based |
|
4
|
project on GitHub (with [limitations](./mirrorlimitations.md)) |
|
5
|
by following these steps: |
|
6
|
|
|
7
|
1. Create an account on GitHub if you do not have one already. Log |
|
8
|
into that account. |
|
9
|
|
|
10
|
2. Create a new project. GitHub will ask you if you want to prepopulate |
|
11
|
your project with various things like a README file. Answer "no" to |
|
12
|
everything. You want a completely blank project. GitHub will then |
|
13
|
supply you with a URL for your project that will look something |
|
14
|
like this: |
|
15
|
|
|
16
|
https://github.com/username/project.git |
|
17
|
|
|
18
|
3. Back on your workstation, move to a checkout for your Fossil |
|
19
|
project and type: |
|
20
|
|
|
21
|
<blockquote> |
|
22
|
<pre> |
|
23
|
$ fossil git export /path/to/git/repo --autopush \ |
|
24
|
https://<font color="orange">username</font>:<font color="red">password</font>@github.com/username/project.git |
|
25
|
</pre> |
|
26
|
</blockquote> |
|
27
|
|
|
28
|
In place of the <code>/path/to...</code> argument above, put in |
|
29
|
some directory name that is <i>outside</i> of your Fossil checkout. If |
|
30
|
you keep multiple Fossil checkouts in a directory of their own, |
|
31
|
consider using <code>../git-mirror</code> to place the Git export |
|
32
|
mirror alongside them, for example. Fossil will create this |
|
33
|
directory if necessary. This directory will become a Git |
|
34
|
repository that holds a translation of your Fossil repository. |
|
35
|
|
|
36
|
The <code>--autopush</code> option tells Fossil that you want to |
|
37
|
push the Git translation up to GitHub every time it is updated. |
|
38
|
|
|
39
|
The URL parameter is the same as the one GitHub gave you, but with |
|
40
|
your GitHub <font color="orange">username</font> and <font |
|
41
|
color="red">password</font> added. |
|
42
|
|
|
43
|
If your GitHub account uses two-factor authentication (2FA), you |
|
44
|
will have to <a href="https://github.com/settings/tokens">generate |
|
45
|
a personal access token</a> and use that in place of your actual |
|
46
|
password in the URL. This token should have “repo” scope enabled, |
|
47
|
only. |
|
48
|
|
|
49
|
You can also run the command above outside of any open checkout of |
|
50
|
your project by supplying the “<code>-R repository</code>” |
|
51
|
option. |
|
52
|
|
|
53
|
4. Get some coffee. Depending on the size of your project, the |
|
54
|
initial "<code>fossil git export</code>" command in the previous |
|
55
|
step might run for several minutes. |
|
56
|
|
|
57
|
5. And you are done! Assuming everything worked, your project is now |
|
58
|
mirrored on GitHub. |
|
59
|
|
|
60
|
6. Whenever you update your project, simply run this command to update |
|
61
|
the mirror: |
|
62
|
|
|
63
|
$ fossil git export |
|
64
|
|
|
65
|
Unlike with the first time you ran that command, you don’t need |
|
66
|
the remaining arguments, because Fossil remembers those things. |
|
67
|
Subsequent mirror updates should usually happen in a fraction of |
|
68
|
a second. |
|
69
|
|
|
70
|
7. To see the status of your mirror, run: |
|
71
|
|
|
72
|
$ fossil git status |
|
73
|
|
|
74
|
## Notes: |
|
75
|
|
|
76
|
* Unless you specify --force, the mirroring only happens if the Fossil |
|
77
|
repo has changed, with Fossil reporting "no changes", because Fossil |
|
78
|
does not care about the success or failure of the mirror run. If a mirror |
|
79
|
run failed (for example, due to an incorrect password, or a transient |
|
80
|
error at github.com), Fossil will not retry until there has been a repo |
|
81
|
change or --force is supplied. |
|
82
|
|
|
83
|
* The mirroring is one-way. If you check in changes on GitHub, those |
|
84
|
changes will not be reabsorbed by Fossil. There are technical problems |
|
85
|
that make a two-way mirror all but impossible. (This is not to be |
|
86
|
confused with the ability to import a Fossil mirror from Github back |
|
87
|
into a Fossil repository. That works, but it is not a mirror.) |
|
88
|
|
|
89
|
This also means that you cannot accept pull requests on GitHub. |
|
90
|
|
|
91
|
* The "`fossil git export`" command creates subprocesses that run "`git`" |
|
92
|
commands, so you must have Git installed on your machine for any |
|
93
|
of this to work. |
|
94
|
|
|
95
|
* The Git repository will have an extra unmanaged top-level directory named |
|
96
|
"`.mirror_state`" that contains one or more files. Those files are |
|
97
|
used to store the intermediate state of the translation so that |
|
98
|
subsequent invocations of "`fossil git export`" will know where you |
|
99
|
left off the last time and what new content needs to be moved over into |
|
100
|
Git. Be careful not to mess with the `.mirror_state` directory or |
|
101
|
any of its contents. Do not put those files under Git management. Do |
|
102
|
not edit or delete them. |
|
103
|
|
|
104
|
* The name of the "trunk" branch is automatically translated into "master" |
|
105
|
in the Git mirror unless you give the `--mainbranch` option. |
|
106
|
|
|
107
|
* Only check-ins and simple tags are translated to Git. Git does not |
|
108
|
support wiki or tickets or unversioned content or any of the other |
|
109
|
features of Fossil that make it so convenient to use, so those other |
|
110
|
elements cannot be mirrored in Git. |
|
111
|
|
|
112
|
* In Git, all tags must be unique. If your Fossil repository has the |
|
113
|
same tag on two or more check-ins, the tag will only be preserved on |
|
114
|
the chronologically newest check-in. |
|
115
|
|
|
116
|
* There is a |
|
117
|
[long list of restrictions](https://git-scm.com/docs/git-check-ref-format) |
|
118
|
on tag and branch names in Git. If any of your Fossil tag or branch names |
|
119
|
violate these rules, then the names are translated prior to being exported |
|
120
|
to Git. The translation usually involves converting the offending characters |
|
121
|
into underscores. |
|
122
|
|
|
123
|
* If your Fossil user contact info is not set and this repository was not |
|
124
|
initially [imported from Git](./inout.wiki), `fossil git export` will |
|
125
|
construct a generic `[email protected]` for the Git *committer* and *author* |
|
126
|
email fields of each commit. However, Fossil will first attempt to parse an |
|
127
|
email address from your user contact info, which can be set through a |
|
128
|
Fossil [UI][ui] browser window or with the [`user contact`][usercmd] |
|
129
|
subcommand on the command line. Alternatively, if this repository was |
|
130
|
previously imported from Git using the [`--attribute`][attr] option, the |
|
131
|
[`fx_git`][fxgit] table will be queried for correspondent email addresses. |
|
132
|
Only if neither of these methods produce a user specified email will the |
|
133
|
abovementioned generic address be used. |
|
134
|
|
|
135
|
[attr]: /help/import |
|
136
|
[fxgit]: ./inout.wiki#fx_git |
|
137
|
[ui]: /help/ui |
|
138
|
[usercmd]: /help/user |
|
139
|
|
|
140
|
|
|
141
|
## <a id='ex1'></a>Example GitHub Mirrors |
|
142
|
|
|
143
|
As of this writing (2019-03-16) Fossil’s own repository is mirrored |
|
144
|
on GitHub at: |
|
145
|
|
|
146
|
> <https://github.com/drhsqlite/fossil-mirror> |
|
147
|
|
|
148
|
In addition, an official Git mirror of SQLite is available: |
|
149
|
|
|
150
|
> <https://github.com/sqlite/sqlite> |
|
151
|
|
|
152
|
The Fossil source repositories for these mirrors are at |
|
153
|
<https://www2.fossil-scm.org/fossil> and <https://www2.sqlite.org/src>, |
|
154
|
respectively. Both repositories are hosted on the same VM at |
|
155
|
[Linode](https://www.linode.com). On that machine, there is a |
|
156
|
[cron job](https://linux.die.net/man/8/cron) |
|
157
|
that runs at 17 minutes after the hour, every hour that does: |
|
158
|
|
|
159
|
/usr/bin/fossil sync -u -R /home/www/fossil/fossil.fossil |
|
160
|
/usr/bin/fossil sync -R /home/www/fossil/sqlite.fossil |
|
161
|
/usr/bin/fossil git export -R /home/www/fossil/fossil.fossil |
|
162
|
/usr/bin/fossil git export -R /home/www/fossil/sqlite.fossil |
|
163
|
|
|
164
|
The initial two "sync" commands pull in changes from the primary |
|
165
|
Fossil repositories for Fossil and SQLite. The last two lines |
|
166
|
export the changes to Git and push the results up to GitHub. |
|
167
|
|