Fossil SCM
Updates to the mirrorlimitations.md document.
Commit
31bbb40f13184e9e5a935ec39ee7653f38f298202a38acfe406a03956cf2305f
Parent
f631c7c82e20ffc…
1 file changed
+23
-20
+23
-20
| --- www/mirrorlimitations.md | ||
| +++ www/mirrorlimitations.md | ||
| @@ -1,10 +1,10 @@ | ||
| 1 | 1 | # Limitations On Git Mirrors |
| 2 | 2 | |
| 3 | 3 | The "<tt>[fossil git export](/help?cmd=git)</tt>" command can be used to |
| 4 | 4 | mirror a Fossil repository to Git. |
| 5 | -([Setup instructions](./mirrortogithub) and an | |
| 5 | +([Setup instructions](./mirrortogithub.md) and an | |
| 6 | 6 | [example](https://github.com/drhsqlite/fossil-mirror).) |
| 7 | 7 | But the export to Git is not perfect. Some information is lost during |
| 8 | 8 | export due to limitations in Git. This page describes what content of |
| 9 | 9 | Fossil is not included in an export to Git. |
| 10 | 10 | |
| @@ -14,55 +14,58 @@ | ||
| 14 | 14 | as Wiki, Tickets, Technotes, and the Forum are not supported in Git and |
| 15 | 15 | so those features are not included in an export. |
| 16 | 16 | |
| 17 | 17 | ## (2) Cherrypick Merges |
| 18 | 18 | |
| 19 | -Git supports cherrypick merging, but the fact that a cherrypick merge occurred | |
| 20 | -is not recorded in the Git blockchain. There is no way to record a cherrypick | |
| 21 | -merge in the low-level Git file format. | |
| 19 | +The Git client supports cherrypick mergs but does not remember them. | |
| 20 | +In other words, Git does not record a history of cherrypick merges | |
| 21 | +in its blockchain. | |
| 22 | 22 | |
| 23 | -Fossil does track cherrypick merges in its low-level file format, but that | |
| 24 | -information must be discarded when exporting to Git as there is no way to | |
| 25 | -represent it in Git. | |
| 23 | +Fossil tracks cherrypick merges in its blockchain and display cherrypicks | |
| 24 | +(as dashed lines) in its timeline ([example](/timeline?c=0a9f12ce6655b7a5)). | |
| 25 | +But history information of cherrypicks cannot be exported to Git because | |
| 26 | +there is no way to represent it in the Git. | |
| 26 | 27 | |
| 27 | 28 | ## (3) Named Branches |
| 28 | 29 | |
| 29 | 30 | Git has only limited support for named branches. Git identifies the head |
| 30 | 31 | check-in of each branch. Depending on the check-in graph topology, this |
| 31 | 32 | is sufficient to infer the branch for many historical check-ins as well. |
| 32 | -However, for complex histories with lots of cross-merging | |
| 33 | -the branch names for historical check-ins can become ambiguious. Fossil keeps | |
| 34 | -track of historical branch names unambigously. But some of this information | |
| 35 | -can go missing when exporting to Git. | |
| 33 | +However, complex histories with lots of cross-merging | |
| 34 | +can lead to ambiguities. Fossil keeps | |
| 35 | +track of historical branch names unambigously. | |
| 36 | +But the extra details about branch names that Fossil keeps | |
| 37 | +at hand cannot be exported to Git. | |
| 36 | 38 | |
| 37 | 39 | ## (4) Non-unique Tags |
| 38 | 40 | |
| 39 | 41 | Git requires tags to be unique. Each tag must refer to exactly one |
| 40 | 42 | check-in. Fossil does not have this restriction, and so it is common |
| 41 | -in Fossil to tag every release check-in of a project with the "release" | |
| 43 | +in Fossil to tag multiple check-ins with the same name. For example, | |
| 44 | +it is common in Fossil to tag every release check-in with the "release" | |
| 42 | 45 | tag, so that all historical releases can be found all at once. |
| 43 | 46 | ([example](/timeline?t=release)) |
| 44 | 47 | |
| 45 | -Git does not allow this. In Git, the "release" tag must refer to just one | |
| 48 | +Git does not allow this. The "release" tag must refer to just one | |
| 46 | 49 | check-in. The work-around is that the non-unique tag in the Git export is |
| 47 | 50 | made to refer to only the most recent check-in with that tag. |
| 48 | 51 | |
| 49 | 52 | ## (5) Amendments To Check-ins |
| 50 | 53 | |
| 51 | -Both Fossil and Git are based on blockchain and hence check-ins are | |
| 52 | -immutable. However, Fossil has a mechanism by which tags can be added | |
| 53 | -the blockchain to provide after-the-fact corrections to prior check-ins. | |
| 54 | +Check-ins are immutable in both Fossil and Git. | |
| 55 | +However, Fossil has a mechanism by which tags can be added | |
| 56 | +its blockchain to provide after-the-fact corrections to prior check-ins. | |
| 54 | 57 | |
| 55 | 58 | For example, tags can be added to check-ins that correct typos in the |
| 56 | -check-in comment. The original check-in is unchanged and the | |
| 57 | -original comment is preserved in the blockchain. But | |
| 59 | +check-in comment. The original check-in is immutable and so the | |
| 60 | +original comment is preserved in addition to the correction. But | |
| 58 | 61 | software that displays the check-ins knows to look for the comment-change |
| 59 | 62 | tag and if present displays the corrected comment rather than the original. |
| 60 | 63 | ([Example](/info/8ed91bbe44d0d383) changing the typo "os" into "so".) |
| 61 | 64 | |
| 62 | -Git has no such mechanism for providing corrections or clarifications to | |
| 65 | +Git has no mechanism for providing corrections or clarifications to | |
| 63 | 66 | historical check-ins. |
| 64 | 67 | |
| 65 | 68 | When exporting from Fossil to Git, the latest corrections to a Fossil check-in |
| 66 | 69 | are used to generate the corresponding Git check-in. But once the Git |
| 67 | 70 | check-in has been created, any subsequent corrections are omitted as there |
| 68 | -is no way to transfer those corrections to Git. | |
| 71 | +is no way to transfer them to Git. | |
| 69 | 72 |
| --- www/mirrorlimitations.md | |
| +++ www/mirrorlimitations.md | |
| @@ -1,10 +1,10 @@ | |
| 1 | # Limitations On Git Mirrors |
| 2 | |
| 3 | The "<tt>[fossil git export](/help?cmd=git)</tt>" command can be used to |
| 4 | mirror a Fossil repository to Git. |
| 5 | ([Setup instructions](./mirrortogithub) 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 | |
| @@ -14,55 +14,58 @@ | |
| 14 | as Wiki, Tickets, Technotes, and the Forum are not supported in Git and |
| 15 | so those features are not included in an export. |
| 16 | |
| 17 | ## (2) Cherrypick Merges |
| 18 | |
| 19 | Git supports cherrypick merging, but the fact that a cherrypick merge occurred |
| 20 | is not recorded in the Git blockchain. There is no way to record a cherrypick |
| 21 | merge in the low-level Git file format. |
| 22 | |
| 23 | Fossil does track cherrypick merges in its low-level file format, but that |
| 24 | information must be discarded when exporting to Git as there is no way to |
| 25 | represent it in Git. |
| 26 | |
| 27 | ## (3) Named Branches |
| 28 | |
| 29 | Git has only limited support for named branches. Git identifies the head |
| 30 | check-in of each branch. Depending on the check-in graph topology, this |
| 31 | is sufficient to infer the branch for many historical check-ins as well. |
| 32 | However, for complex histories with lots of cross-merging |
| 33 | the branch names for historical check-ins can become ambiguious. Fossil keeps |
| 34 | track of historical branch names unambigously. But some of this information |
| 35 | can go missing when exporting to Git. |
| 36 | |
| 37 | ## (4) Non-unique Tags |
| 38 | |
| 39 | Git requires tags to be unique. Each tag must refer to exactly one |
| 40 | check-in. Fossil does not have this restriction, and so it is common |
| 41 | in Fossil to tag every release check-in of a project with the "release" |
| 42 | tag, so that all historical releases can be found all at once. |
| 43 | ([example](/timeline?t=release)) |
| 44 | |
| 45 | Git does not allow this. In Git, the "release" tag must refer to just one |
| 46 | check-in. The work-around is that the non-unique tag in the Git export is |
| 47 | made to refer to only the most recent check-in with that tag. |
| 48 | |
| 49 | ## (5) Amendments To Check-ins |
| 50 | |
| 51 | Both Fossil and Git are based on blockchain and hence check-ins are |
| 52 | immutable. However, Fossil has a mechanism by which tags can be added |
| 53 | the blockchain to provide after-the-fact corrections to prior check-ins. |
| 54 | |
| 55 | For example, tags can be added to check-ins that correct typos in the |
| 56 | check-in comment. The original check-in is unchanged and the |
| 57 | original comment is preserved in the blockchain. But |
| 58 | software that displays the check-ins knows to look for the comment-change |
| 59 | tag and if present displays the corrected comment rather than the original. |
| 60 | ([Example](/info/8ed91bbe44d0d383) changing the typo "os" into "so".) |
| 61 | |
| 62 | Git has no such mechanism for providing corrections or clarifications to |
| 63 | historical check-ins. |
| 64 | |
| 65 | When exporting from Fossil to Git, the latest corrections to a Fossil check-in |
| 66 | are used to generate the corresponding Git check-in. But once the Git |
| 67 | check-in has been created, any subsequent corrections are omitted as there |
| 68 | is no way to transfer those corrections to Git. |
| 69 |
| --- www/mirrorlimitations.md | |
| +++ www/mirrorlimitations.md | |
| @@ -1,10 +1,10 @@ | |
| 1 | # Limitations On Git Mirrors |
| 2 | |
| 3 | The "<tt>[fossil git export](/help?cmd=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 | |
| @@ -14,55 +14,58 @@ | |
| 14 | as Wiki, Tickets, Technotes, and the Forum are not supported in Git and |
| 15 | so those features are not included in an export. |
| 16 | |
| 17 | ## (2) Cherrypick Merges |
| 18 | |
| 19 | The Git client supports cherrypick mergs but does not remember them. |
| 20 | In other words, Git does not record a history of cherrypick merges |
| 21 | in its blockchain. |
| 22 | |
| 23 | Fossil tracks cherrypick merges in its blockchain and display cherrypicks |
| 24 | (as dashed lines) in its timeline ([example](/timeline?c=0a9f12ce6655b7a5)). |
| 25 | But history information of cherrypicks cannot be exported to Git because |
| 26 | there is no way to represent it in the Git. |
| 27 | |
| 28 | ## (3) Named Branches |
| 29 | |
| 30 | Git has only limited support for named branches. Git identifies the head |
| 31 | check-in of each branch. Depending on the check-in graph topology, this |
| 32 | is sufficient to infer the branch for many historical check-ins as well. |
| 33 | However, complex histories with lots of cross-merging |
| 34 | can lead to ambiguities. Fossil keeps |
| 35 | track of historical branch names unambigously. |
| 36 | But the extra details about branch names that Fossil keeps |
| 37 | at hand cannot be exported to Git. |
| 38 | |
| 39 | ## (4) Non-unique Tags |
| 40 | |
| 41 | Git requires tags to be unique. Each tag must refer to exactly one |
| 42 | check-in. Fossil does not have this restriction, and so it is common |
| 43 | in Fossil to tag multiple check-ins with the same name. For example, |
| 44 | it is common in Fossil to tag every release check-in with the "release" |
| 45 | tag, so that all historical releases can be found all at once. |
| 46 | ([example](/timeline?t=release)) |
| 47 | |
| 48 | Git does not allow this. The "release" tag must refer to just one |
| 49 | check-in. The work-around is that the non-unique tag in the Git export is |
| 50 | made to refer to only the most recent check-in with that tag. |
| 51 | |
| 52 | ## (5) Amendments To Check-ins |
| 53 | |
| 54 | Check-ins are immutable in both Fossil and Git. |
| 55 | However, Fossil has a mechanism by which tags can be added |
| 56 | its blockchain to provide after-the-fact corrections to prior check-ins. |
| 57 | |
| 58 | For example, tags can be added to check-ins that correct typos in the |
| 59 | check-in comment. The original check-in is immutable and so the |
| 60 | original comment is preserved in addition to the correction. But |
| 61 | software that displays the check-ins knows to look for the comment-change |
| 62 | tag and if present displays the corrected comment rather than the original. |
| 63 | ([Example](/info/8ed91bbe44d0d383) changing the typo "os" into "so".) |
| 64 | |
| 65 | Git has no mechanism for providing corrections or clarifications to |
| 66 | historical check-ins. |
| 67 | |
| 68 | When exporting from Fossil to Git, the latest corrections to a Fossil check-in |
| 69 | are used to generate the corresponding Git check-in. But once the Git |
| 70 | check-in has been created, any subsequent corrections are omitted as there |
| 71 | is no way to transfer them to Git. |
| 72 |