Fossil SCM
Mention the problem of "diamond-merges" in the Git-mirror limitations document.
Commit
7f76faef497c73c35d280fc757ddeda243471fb7e5919c63fb543ca654133442
Parent
c07468c20725ccc…
1 file changed
+19
+19
| --- www/mirrorlimitations.md | ||
| +++ www/mirrorlimitations.md | ||
| @@ -46,10 +46,29 @@ | ||
| 46 | 46 | However, complex histories with lots of cross-merging |
| 47 | 47 | can lead to ambiguities. Fossil keeps |
| 48 | 48 | track of historical branch names unambiguously, |
| 49 | 49 | but the extra details about branch names that Fossil keeps |
| 50 | 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. | |
| 51 | 70 | |
| 52 | 71 | ## (4) Non-unique Tags |
| 53 | 72 | |
| 54 | 73 | Git requires tags to be unique: each tag must refer to exactly one |
| 55 | 74 | check-in. Fossil does not have this restriction, and so it is common |
| 56 | 75 |
| --- www/mirrorlimitations.md | |
| +++ www/mirrorlimitations.md | |
| @@ -46,10 +46,29 @@ | |
| 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 | ## (4) Non-unique Tags |
| 53 | |
| 54 | Git requires tags to be unique: each tag must refer to exactly one |
| 55 | check-in. Fossil does not have this restriction, and so it is common |
| 56 |
| --- www/mirrorlimitations.md | |
| +++ www/mirrorlimitations.md | |
| @@ -46,10 +46,29 @@ | |
| 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 |