|
1
|
# Limitations On Git Mirrors |
|
2
|
|
|
3
|
The "<tt>[fossil git export](/help/git)</tt>" command can be used to |
|
4
|
mirror a Fossil repository to Git. |
|
5
|
([Setup instructions](./mirrortogithub.md) and an |
|
6
|
[example](https://github.com/drhsqlite/fossil-mirror).) |
|
7
|
But the export to Git is not perfect. Some information is lost during |
|
8
|
export due to limitations in Git. This page describes what content of |
|
9
|
Fossil is not included in an export to Git. |
|
10
|
|
|
11
|
## (1) Wiki, Tickets, Technotes, Forum |
|
12
|
|
|
13
|
Git only supports version control. The additional features of Fossil such |
|
14
|
as Wiki, Tickets, Technotes, and the Forum are not supported in Git, |
|
15
|
so those features are not included in an export. |
|
16
|
|
|
17
|
Third-party Git based tooling may add some of these features (e.g. |
|
18
|
GitHub, GitLab) but because their data are not stored in the Git |
|
19
|
repository, there is no single destination for Fossil to convert its |
|
20
|
equivalent data *to*. For instance, Fossil tickets do not become GitHub |
|
21
|
issues, because that is a proprietary feature of GitHub separate from |
|
22
|
Git proper, stored outside the repository on the GitHub servers. |
|
23
|
|
|
24
|
You can also see the problem in its inverse case: you do not get a copy |
|
25
|
of your GitHub issues when cloning the Git repository. You *do* get the |
|
26
|
Fossil tickets, wiki, forum posts, etc. when cloning a remote Fossil |
|
27
|
repo. |
|
28
|
|
|
29
|
## (2) Cherrypick Merges |
|
30
|
|
|
31
|
The Git client supports cherrypick merges but does not record the |
|
32
|
cherrypick parent(s). |
|
33
|
|
|
34
|
Fossil tracks cherrypick merges in its repository and displays |
|
35
|
cherrypicks in its timeline. (As an example, the dashed lines |
|
36
|
[here](/timeline?c=0a9f12ce6655b7a5) are cherrypicks.) Because Git does |
|
37
|
not have a way to represent this same information in its repository, the |
|
38
|
history of Fossil cherrypicks cannot be exported to Git, only their |
|
39
|
direct effects on the managed file data. |
|
40
|
|
|
41
|
## (3) Named Branches |
|
42
|
|
|
43
|
Git has only limited support for named branches. Git identifies the head |
|
44
|
check-in of each branch. Depending on the check-in graph topology, this |
|
45
|
is sufficient to infer the branch for many historical check-ins as well. |
|
46
|
However, complex histories with lots of cross-merging |
|
47
|
can lead to ambiguities. Fossil keeps |
|
48
|
track of historical branch names unambiguously, |
|
49
|
but the extra details about branch names that Fossil keeps |
|
50
|
at hand cannot be exported to Git. |
|
51
|
|
|
52
|
An example of the kinds of ambiguities that arise when branch names |
|
53
|
are not tracked is a "diamond-merge" history. In a diamond-merge, a |
|
54
|
long-running development branch merges enhancements from trunk from |
|
55
|
time to time and also periodically merges the development changes back |
|
56
|
to trunk at moments when the branch is stable. |
|
57
|
An example of diamond-merge in the Fossil source tree itself |
|
58
|
can be seen at on the [bv-corrections01 branch](/timeline?r=bv-corrections01). |
|
59
|
The distinction between checkins on the branch and checkins on trunk would |
|
60
|
be lost in Git, which does not track branches for individual checkins, |
|
61
|
and so you cannot (easily) tell which checkins are part of the branch and |
|
62
|
which are part of trunk in a diamond-merge history on Git. For that |
|
63
|
reason, diamond-merge histories are considered an anti-pattern in Git |
|
64
|
and the usual recommendation for Git users is to employ |
|
65
|
[rebase](./rebaseharm.md) to clean the history up. The point here is |
|
66
|
that if your project has a diamond-merge history that shows up cleanly |
|
67
|
in Fossil, it will export to Git and still be technically correct, but |
|
68
|
the history display might be a jumbled mess that is difficult for humans |
|
69
|
to comprehend. |
|
70
|
|
|
71
|
## (4) Non-unique Tags |
|
72
|
|
|
73
|
Git requires tags to be unique: each tag must refer to exactly one |
|
74
|
check-in. Fossil does not have this restriction, and so it is common |
|
75
|
in Fossil to tag multiple check-ins with the same name. For example, |
|
76
|
it is common in Fossil to tag each check-in creating a release both |
|
77
|
with a unique version tag *and* a common tag like "release" |
|
78
|
so that all historical releases can be found at once. |
|
79
|
([Example](/timeline?t=release).) |
|
80
|
|
|
81
|
Git does not allow this. The "release" tag must refer to just one |
|
82
|
check-in. The work-around is that the non-unique tag in the Git export is |
|
83
|
made to refer to only the most recent check-in with that tag. |
|
84
|
|
|
85
|
This is why the ["release" tag view][ghrtv] in the GitHub mirror of this |
|
86
|
repository shows only the latest release version; contrast the prior |
|
87
|
example. Both URLs are asking the repository the same question, but |
|
88
|
because of Git's relatively impoverished data model, it cannot give the |
|
89
|
same answer that Fossil does. |
|
90
|
|
|
91
|
[ghrtv]: https://github.com/drhsqlite/fossil-mirror/tree/release |
|
92
|
|
|
93
|
## (5) Amendments To Check-ins |
|
94
|
|
|
95
|
Check-ins are immutable in both Fossil and Git. |
|
96
|
However, Fossil has a mechanism by which tags can be added to |
|
97
|
its repository to provide after-the-fact corrections to prior check-ins. |
|
98
|
|
|
99
|
For example, tags can be added to check-ins that correct typos in the |
|
100
|
check-in comment. The original check-in is immutable and so the |
|
101
|
original comment is preserved in addition to the correction. But |
|
102
|
software that displays the check-ins knows to look for the comment-change |
|
103
|
tag and if present displays the corrected comment rather than the original. |
|
104
|
([Example](/info/8ed91bbe44d0d383) changing the typo "os" into "so".) |
|
105
|
|
|
106
|
Git has no mechanism for providing corrections or clarifications to |
|
107
|
historical check-ins. |
|
108
|
|
|
109
|
When exporting from Fossil to Git, the latest corrections to a Fossil check-in |
|
110
|
are used to generate the corresponding Git check-in. But once the Git |
|
111
|
check-in has been created, any subsequent corrections are omitted as there |
|
112
|
is no way to transfer them to Git. |
|
113
|
|