Fossil SCM
delta-manifests.md: minor typos and phrasing improvements.
Commit
25e93b7075c35d3fb74b3a7d4c1985f4b4cac457d3f5b0577d7329deebf9c8ea
Parent
922b5c4d1521994…
1 file changed
+14
-15
+14
-15
| --- www/delta-manifests.md | ||
| +++ www/delta-manifests.md | ||
| @@ -1,8 +1,8 @@ | ||
| 1 | 1 | # Delta Manifests |
| 2 | 2 | |
| 3 | -This article describes "delta manifests," a special case form of | |
| 3 | +This article describes "delta manifests," a special-case form of | |
| 4 | 4 | checkin manifest which is intended to take up far less space than |
| 5 | 5 | a normal checkin manifest, in particular for repositories with |
| 6 | 6 | many files. We'll see, however, that the space savings, if indeed |
| 7 | 7 | there are any, come with some caveats. |
| 8 | 8 | |
| @@ -21,11 +21,11 @@ | ||
| 21 | 21 | |
| 22 | 22 | A checkin manifest includes a list of every file in that checkin. A |
| 23 | 23 | moderately-sized project can easily have a thousand files, and every |
| 24 | 24 | checkin manifest will include those thousand files. As of this writing |
| 25 | 25 | Fossil's own checkins contain 989 files and the manifests are 80kb |
| 26 | -each. Thus a checkin which changes only 2 bytes of sourse code | |
| 26 | +each. Thus a checkin which changes only 2 bytes of source code | |
| 27 | 27 | ostensibly costs another 80kb of storage for the manifest for that |
| 28 | 28 | change. |
| 29 | 29 | |
| 30 | 30 | Delta manifests were conceived as a mechanism to help combat that |
| 31 | 31 | storage overhead. |
| @@ -58,19 +58,18 @@ | ||
| 58 | 58 | a P-card does. A manifest may have multiple P-card parents (the second |
| 59 | 59 | and subsequent ones denoting merge parents) but B-cards always refer |
| 60 | 60 | to exactly one parent. |
| 61 | 61 | |
| 62 | 62 | What unambiguously distinguishes this as a delta is the existence of |
| 63 | -the B-card. All deltas have a B-card and no other type of artifact | |
| 64 | -has one. What also, but not unambiguously, distinguishes it as | |
| 65 | -a delta is that it has only 17 F-cards, whereas a baseline manifest in | |
| 66 | -that same repository has (as of this writing) 291 F-cards. In this | |
| 67 | -particular case, the delta manifest is 1363 bytes, compared to 20627 | |
| 68 | -bytes for the next checkin - a baseline manifest. That's a significant | |
| 69 | -saving in F-cards, especially once a repository grows to a size of | |
| 70 | -thousands of files. That savings, however, comes with caveats which | |
| 71 | -we'll address below. | |
| 63 | +the B-card. All deltas have a B-card and no other type of artifact has | |
| 64 | +one. What also, but not unambiguously, distinguishes it as a delta is | |
| 65 | +that it has only 17 F-cards, whereas a baseline manifest in that same | |
| 66 | +repository has (as of this writing) 291 F-cards. In this particular | |
| 67 | +case, the delta manifest is 1363 bytes, compared to 20627 bytes for | |
| 68 | +the next checkin - a baseline manifest. That's a significant saving in | |
| 69 | +F-cards, especially if a repository contains thousands of files. That | |
| 70 | +savings, however, comes with caveats which we'll address below. | |
| 72 | 71 | |
| 73 | 72 | Trivia regarding the B-card: |
| 74 | 73 | |
| 75 | 74 | - The B-card always refers to a baseline manifest, not another delta. |
| 76 | 75 | - Deltas may not chain with another delta, but any number of deltas |
| @@ -179,12 +178,12 @@ | ||
| 179 | 178 | 3rd-party code which can extract Fossil-format blobs both with and |
| 180 | 179 | without applying their deltas: |
| 181 | 180 | |
| 182 | 181 | ``` |
| 183 | 182 | $ f-acat tip > A # tip version's manifest |
| 184 | -$ f-acat prev --raw > B # previous manifest in its raw deltified form | |
| 185 | -$ f-acat prev > C # previous manifest undelta'd | |
| 183 | +$ f-acat prev --raw > B # previous manifest in its raw fossil-deltified form | |
| 184 | +$ f-acat prev > C # previous manifest fossil-undelta'd | |
| 186 | 185 | $ ls -la A B C |
| 187 | 186 | -rw-rw-r-- 1 user user 80252 Mar 12 07:09 A # tip |
| 188 | 187 | -rw-rw-r-- 1 user user 726 Mar 12 07:09 B # previous: delta'd |
| 189 | 188 | -rw-rw-r-- 1 user user 80256 Mar 12 07:09 C # previous: undelta'd |
| 190 | 189 | ``` |
| @@ -192,12 +191,12 @@ | ||
| 192 | 191 | For comparison's sake, when looking at a separate repository which |
| 193 | 192 | uses delta manifests, a delta-compressed delta manifest takes up |
| 194 | 193 | approximately the same space as a delta-compressed baseline manifest |
| 195 | 194 | (to within 10 bytes for the test samples). |
| 196 | 195 | |
| 197 | -i.e. delta manifests do not typically save any storage space except | |
| 198 | -for the tip version! (*Surprise!*) | |
| 196 | +i.e. delta manifests may not save any storage space except for the tip | |
| 197 | +version! (*Surprise!*) | |
| 199 | 198 | |
| 200 | 199 | In terms of RAM costs, deltas usually cost more memory than baseline |
| 201 | 200 | manifests. The reason is because traversing a delta requires having |
| 202 | 201 | not only that delta in memory, but also its baseline version. Delta |
| 203 | 202 | manifests are seldom used in ways which do not require also loading |
| 204 | 203 |
| --- www/delta-manifests.md | |
| +++ www/delta-manifests.md | |
| @@ -1,8 +1,8 @@ | |
| 1 | # Delta Manifests |
| 2 | |
| 3 | This article describes "delta manifests," a special case form of |
| 4 | checkin manifest which is intended to take up far less space than |
| 5 | a normal checkin manifest, in particular for repositories with |
| 6 | many files. We'll see, however, that the space savings, if indeed |
| 7 | there are any, come with some caveats. |
| 8 | |
| @@ -21,11 +21,11 @@ | |
| 21 | |
| 22 | A checkin manifest includes a list of every file in that checkin. A |
| 23 | moderately-sized project can easily have a thousand files, and every |
| 24 | checkin manifest will include those thousand files. As of this writing |
| 25 | Fossil's own checkins contain 989 files and the manifests are 80kb |
| 26 | each. Thus a checkin which changes only 2 bytes of sourse code |
| 27 | ostensibly costs another 80kb of storage for the manifest for that |
| 28 | change. |
| 29 | |
| 30 | Delta manifests were conceived as a mechanism to help combat that |
| 31 | storage overhead. |
| @@ -58,19 +58,18 @@ | |
| 58 | a P-card does. A manifest may have multiple P-card parents (the second |
| 59 | and subsequent ones denoting merge parents) but B-cards always refer |
| 60 | to exactly one parent. |
| 61 | |
| 62 | What unambiguously distinguishes this as a delta is the existence of |
| 63 | the B-card. All deltas have a B-card and no other type of artifact |
| 64 | has one. What also, but not unambiguously, distinguishes it as |
| 65 | a delta is that it has only 17 F-cards, whereas a baseline manifest in |
| 66 | that same repository has (as of this writing) 291 F-cards. In this |
| 67 | particular case, the delta manifest is 1363 bytes, compared to 20627 |
| 68 | bytes for the next checkin - a baseline manifest. That's a significant |
| 69 | saving in F-cards, especially once a repository grows to a size of |
| 70 | thousands of files. That savings, however, comes with caveats which |
| 71 | we'll address below. |
| 72 | |
| 73 | Trivia regarding the B-card: |
| 74 | |
| 75 | - The B-card always refers to a baseline manifest, not another delta. |
| 76 | - Deltas may not chain with another delta, but any number of deltas |
| @@ -179,12 +178,12 @@ | |
| 179 | 3rd-party code which can extract Fossil-format blobs both with and |
| 180 | without applying their deltas: |
| 181 | |
| 182 | ``` |
| 183 | $ f-acat tip > A # tip version's manifest |
| 184 | $ f-acat prev --raw > B # previous manifest in its raw deltified form |
| 185 | $ f-acat prev > C # previous manifest undelta'd |
| 186 | $ ls -la A B C |
| 187 | -rw-rw-r-- 1 user user 80252 Mar 12 07:09 A # tip |
| 188 | -rw-rw-r-- 1 user user 726 Mar 12 07:09 B # previous: delta'd |
| 189 | -rw-rw-r-- 1 user user 80256 Mar 12 07:09 C # previous: undelta'd |
| 190 | ``` |
| @@ -192,12 +191,12 @@ | |
| 192 | For comparison's sake, when looking at a separate repository which |
| 193 | uses delta manifests, a delta-compressed delta manifest takes up |
| 194 | approximately the same space as a delta-compressed baseline manifest |
| 195 | (to within 10 bytes for the test samples). |
| 196 | |
| 197 | i.e. delta manifests do not typically save any storage space except |
| 198 | for the tip version! (*Surprise!*) |
| 199 | |
| 200 | In terms of RAM costs, deltas usually cost more memory than baseline |
| 201 | manifests. The reason is because traversing a delta requires having |
| 202 | not only that delta in memory, but also its baseline version. Delta |
| 203 | manifests are seldom used in ways which do not require also loading |
| 204 |
| --- www/delta-manifests.md | |
| +++ www/delta-manifests.md | |
| @@ -1,8 +1,8 @@ | |
| 1 | # Delta Manifests |
| 2 | |
| 3 | This article describes "delta manifests," a special-case form of |
| 4 | checkin manifest which is intended to take up far less space than |
| 5 | a normal checkin manifest, in particular for repositories with |
| 6 | many files. We'll see, however, that the space savings, if indeed |
| 7 | there are any, come with some caveats. |
| 8 | |
| @@ -21,11 +21,11 @@ | |
| 21 | |
| 22 | A checkin manifest includes a list of every file in that checkin. A |
| 23 | moderately-sized project can easily have a thousand files, and every |
| 24 | checkin manifest will include those thousand files. As of this writing |
| 25 | Fossil's own checkins contain 989 files and the manifests are 80kb |
| 26 | each. Thus a checkin which changes only 2 bytes of source code |
| 27 | ostensibly costs another 80kb of storage for the manifest for that |
| 28 | change. |
| 29 | |
| 30 | Delta manifests were conceived as a mechanism to help combat that |
| 31 | storage overhead. |
| @@ -58,19 +58,18 @@ | |
| 58 | a P-card does. A manifest may have multiple P-card parents (the second |
| 59 | and subsequent ones denoting merge parents) but B-cards always refer |
| 60 | to exactly one parent. |
| 61 | |
| 62 | What unambiguously distinguishes this as a delta is the existence of |
| 63 | the B-card. All deltas have a B-card and no other type of artifact has |
| 64 | one. What also, but not unambiguously, distinguishes it as a delta is |
| 65 | that it has only 17 F-cards, whereas a baseline manifest in that same |
| 66 | repository has (as of this writing) 291 F-cards. In this particular |
| 67 | case, the delta manifest is 1363 bytes, compared to 20627 bytes for |
| 68 | the next checkin - a baseline manifest. That's a significant saving in |
| 69 | F-cards, especially if a repository contains thousands of files. That |
| 70 | savings, however, comes with caveats which we'll address below. |
| 71 | |
| 72 | Trivia regarding the B-card: |
| 73 | |
| 74 | - The B-card always refers to a baseline manifest, not another delta. |
| 75 | - Deltas may not chain with another delta, but any number of deltas |
| @@ -179,12 +178,12 @@ | |
| 178 | 3rd-party code which can extract Fossil-format blobs both with and |
| 179 | without applying their deltas: |
| 180 | |
| 181 | ``` |
| 182 | $ f-acat tip > A # tip version's manifest |
| 183 | $ f-acat prev --raw > B # previous manifest in its raw fossil-deltified form |
| 184 | $ f-acat prev > C # previous manifest fossil-undelta'd |
| 185 | $ ls -la A B C |
| 186 | -rw-rw-r-- 1 user user 80252 Mar 12 07:09 A # tip |
| 187 | -rw-rw-r-- 1 user user 726 Mar 12 07:09 B # previous: delta'd |
| 188 | -rw-rw-r-- 1 user user 80256 Mar 12 07:09 C # previous: undelta'd |
| 189 | ``` |
| @@ -192,12 +191,12 @@ | |
| 191 | For comparison's sake, when looking at a separate repository which |
| 192 | uses delta manifests, a delta-compressed delta manifest takes up |
| 193 | approximately the same space as a delta-compressed baseline manifest |
| 194 | (to within 10 bytes for the test samples). |
| 195 | |
| 196 | i.e. delta manifests may not save any storage space except for the tip |
| 197 | version! (*Surprise!*) |
| 198 | |
| 199 | In terms of RAM costs, deltas usually cost more memory than baseline |
| 200 | manifests. The reason is because traversing a delta requires having |
| 201 | not only that delta in memory, but also its baseline version. Delta |
| 202 | manifests are seldom used in ways which do not require also loading |
| 203 |