Fossil SCM
Assorted improvements to the mirrorlimitations.md doc.
Commit
0874340b4531cfaeb030b739d642d06a4d3f182b2a4df79b9b3582c1e113b78d
Parent
b16db9d6e960fcf…
1 file changed
+38
-16
+38
-16
| --- www/mirrorlimitations.md | ||
| +++ www/mirrorlimitations.md | ||
| @@ -9,52 +9,74 @@ | ||
| 9 | 9 | Fossil is not included in an export to Git. |
| 10 | 10 | |
| 11 | 11 | ## (1) Wiki, Tickets, Technotes, Forum |
| 12 | 12 | |
| 13 | 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 and | |
| 14 | +as Wiki, Tickets, Technotes, and the Forum are not supported in Git, | |
| 15 | 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 | +blockchain, 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 blockchain 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. | |
| 16 | 28 | |
| 17 | 29 | ## (2) Cherrypick Merges |
| 18 | 30 | |
| 19 | -The Git client supports cherrypick merges 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. | |
| 31 | +The Git client supports cherrypick merges but does not record the | |
| 32 | +cherrypick parent(s). | |
| 33 | + | |
| 34 | +Fossil tracks cherrypick merges in its blockchain 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 blockchain, the | |
| 38 | +history of Fossil cherrypicks cannot be exported to Git, only their | |
| 39 | +direct effects on the managed file data. | |
| 27 | 40 | |
| 28 | 41 | ## (3) Named Branches |
| 29 | 42 | |
| 30 | 43 | Git has only limited support for named branches. Git identifies the head |
| 31 | 44 | check-in of each branch. Depending on the check-in graph topology, this |
| 32 | 45 | is sufficient to infer the branch for many historical check-ins as well. |
| 33 | 46 | However, complex histories with lots of cross-merging |
| 34 | 47 | can lead to ambiguities. Fossil keeps |
| 35 | -track of historical branch names unambiguously. | |
| 36 | -But the extra details about branch names that Fossil keeps | |
| 48 | +track of historical branch names unambiguously, | |
| 49 | +but the extra details about branch names that Fossil keeps | |
| 37 | 50 | at hand cannot be exported to Git. |
| 38 | 51 | |
| 39 | 52 | ## (4) Non-unique Tags |
| 40 | 53 | |
| 41 | -Git requires tags to be unique. Each tag must refer to exactly one | |
| 54 | +Git requires tags to be unique: each tag must refer to exactly one | |
| 42 | 55 | check-in. Fossil does not have this restriction, and so it is common |
| 43 | 56 | 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)) | |
| 57 | +it is common in Fossil to tag each check-in creating a release both | |
| 58 | +with a unique version tag *and* a common tag like "release" | |
| 59 | +so that all historical releases can be found at once. | |
| 60 | +([Example](/timeline?t=release).) | |
| 47 | 61 | |
| 48 | 62 | Git does not allow this. The "release" tag must refer to just one |
| 49 | 63 | check-in. The work-around is that the non-unique tag in the Git export is |
| 50 | 64 | made to refer to only the most recent check-in with that tag. |
| 51 | 65 | |
| 66 | +This is why the ["release" tag view][ghrtv] in the GitHub mirror of this | |
| 67 | +repository shows only the latest release version; contrast the prior | |
| 68 | +example. Both URLs are asking the repository the same question, but | |
| 69 | +because of Git's relatively impoverished data model, it cannot give the | |
| 70 | +same answer that Fossil does. | |
| 71 | + | |
| 72 | +[ghrtv]: https://github.com/drhsqlite/fossil-mirror/tree/release | |
| 73 | + | |
| 52 | 74 | ## (5) Amendments To Check-ins |
| 53 | 75 | |
| 54 | 76 | Check-ins are immutable in both Fossil and Git. |
| 55 | -However, Fossil has a mechanism by which tags can be added | |
| 77 | +However, Fossil has a mechanism by which tags can be added to | |
| 56 | 78 | its blockchain to provide after-the-fact corrections to prior check-ins. |
| 57 | 79 | |
| 58 | 80 | For example, tags can be added to check-ins that correct typos in the |
| 59 | 81 | check-in comment. The original check-in is immutable and so the |
| 60 | 82 | original comment is preserved in addition to the correction. But |
| 61 | 83 |
| --- www/mirrorlimitations.md | |
| +++ www/mirrorlimitations.md | |
| @@ -9,52 +9,74 @@ | |
| 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 and |
| 15 | so those features are not included in an export. |
| 16 | |
| 17 | ## (2) Cherrypick Merges |
| 18 | |
| 19 | The Git client supports cherrypick merges 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 unambiguously. |
| 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 |
| --- www/mirrorlimitations.md | |
| +++ www/mirrorlimitations.md | |
| @@ -9,52 +9,74 @@ | |
| 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 | blockchain, 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 blockchain 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 blockchain 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 blockchain, 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 | ## (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 | in Fossil to tag multiple check-ins with the same name. For example, |
| 57 | it is common in Fossil to tag each check-in creating a release both |
| 58 | with a unique version tag *and* a common tag like "release" |
| 59 | so that all historical releases can be found at once. |
| 60 | ([Example](/timeline?t=release).) |
| 61 | |
| 62 | Git does not allow this. The "release" tag must refer to just one |
| 63 | check-in. The work-around is that the non-unique tag in the Git export is |
| 64 | made to refer to only the most recent check-in with that tag. |
| 65 | |
| 66 | This is why the ["release" tag view][ghrtv] in the GitHub mirror of this |
| 67 | repository shows only the latest release version; contrast the prior |
| 68 | example. Both URLs are asking the repository the same question, but |
| 69 | because of Git's relatively impoverished data model, it cannot give the |
| 70 | same answer that Fossil does. |
| 71 | |
| 72 | [ghrtv]: https://github.com/drhsqlite/fossil-mirror/tree/release |
| 73 | |
| 74 | ## (5) Amendments To Check-ins |
| 75 | |
| 76 | Check-ins are immutable in both Fossil and Git. |
| 77 | However, Fossil has a mechanism by which tags can be added to |
| 78 | its blockchain to provide after-the-fact corrections to prior check-ins. |
| 79 | |
| 80 | For example, tags can be added to check-ins that correct typos in the |
| 81 | check-in comment. The original check-in is immutable and so the |
| 82 | original comment is preserved in addition to the correction. But |
| 83 |