Fossil SCM

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

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button