Fossil SCM
Reworked section 5.0 of the rebaseharm doc to be less controversial. Charged words are quotes from the Git docs, not words we sling at it, etc. This also more clearly separates the "merge alternative" aspects of rebase from the history-mutating aspects.
Commit
1a4b8e58940beba52bb58d4c82ce80c86bc4d7763b2c33d81f3f5498cef2970e
Parent
a4e84fb5974058f…
1 file changed
+28
-45
+28
-45
| --- www/rebaseharm.md | ||
| +++ www/rebaseharm.md | ||
| @@ -298,63 +298,46 @@ | ||
| 298 | 298 | ## <a name="lying"></a>5.0 Rebasing is lying about the project history |
| 299 | 299 | |
| 300 | 300 | By discarding parentage information, rebase attempts to deceive the |
| 301 | 301 | reader about how the code actually came together. |
| 302 | 302 | |
| 303 | -The [Git rebase documentation][gitrebase] admits as much. They acknowledge | |
| 304 | -that when you view a repository as record of what actually happened, | |
| 305 | -doing a rebase is "blasphemous" and "you're _lying_ about what | |
| 306 | -actually happened", but then goes on to justify rebase as follows: | |
| 307 | - | |
| 308 | -> | |
| 309 | -_"The opposing point of view is that the commit history is the **story of | |
| 310 | -how your project was made.** You wouldn't publish the first draft of a | |
| 311 | -book, and the manual for how to maintain your software deserves careful | |
| 312 | -editing. This is the camp that uses tools like rebase and filter-branch | |
| 313 | -to tell the story in the way that's best for future readers."_ | |
| 314 | - | |
| 315 | -This counter-argument assumes you must | |
| 316 | -change history in order to enhance readability, which is not true. | |
| 317 | - | |
| 318 | -In fairness to the Git documentation authors, changing the | |
| 319 | -project history appears to be the only way to make editorial | |
| 320 | -changes in Git. | |
| 321 | -But it does not have to be that way. | |
| 322 | -Fossil demonstrates how "the story of your project" | |
| 323 | -can be enhanced without changing the actual history | |
| 324 | -by allowing users to: | |
| 303 | +You may be tempted to dismiss this as an anti-Git opinion on a Fossil | |
| 304 | +web site, but it’s spelled out just like that [in the Git rebase | |
| 305 | +documentation][gitrebase]. It speaks of “lying,” “telling stories,” | |
| 306 | +and “blasphemy.” | |
| 307 | + | |
| 308 | +That section of the Git docs is contrasting rebase with merge, which we | |
| 309 | +cover [above](#cap-loss), but Git’s rebase feature is more than just an | |
| 310 | +alternative to merging: it also provides mechanisms for changing the | |
| 311 | +project history in order to make editorial changes. Fossil shows that | |
| 312 | +you can get similar effects without modifying historical records, | |
| 313 | +allowing users to: | |
| 325 | 314 | |
| 326 | 315 | 1. Edit check-in comments to fix typos or enhance clarity |
| 327 | 316 | 2. Attach supplemental notes to check-ins or whole branches |
| 328 | - 3. Cross-reference check-ins with each other, or with | |
| 329 | - wiki, tickets, forum posts, and/or embedded documentation | |
| 330 | - 4. Hide ill-conceived or now-unused branches from routine display | |
| 331 | - 5. Fix faulty check-in date/times resulting from misconfigured | |
| 317 | + 3. Hide ill-conceived or now-unused branches from routine display | |
| 318 | + 4. Fix faulty check-in date/times resulting from misconfigured | |
| 332 | 319 | system clocks |
| 320 | + 5. Cross-reference check-ins with each other, or with | |
| 321 | + wiki, tickets, forum posts, and/or embedded documentation | |
| 333 | 322 | |
| 334 | 323 | …and so forth. |
| 335 | 324 | |
| 336 | -These changes are accomplished not by removing or modifying existing | |
| 325 | +Fossil allows all of this not by removing or modifying existing | |
| 337 | 326 | repository entries, but rather by adding new supplemental records. |
| 338 | -The original incorrect or unclear inputs are preserved and are | |
| 339 | -readily accessible. The original history is preserved. | |
| 340 | -But for routine display purposes, the more | |
| 341 | -readable edited presentation is provided. | |
| 342 | - | |
| 343 | -A repository can be a true and accurate | |
| 344 | -representation of history even without getting everything perfect | |
| 345 | -on the first draft. Those are not contradictory goals, at least | |
| 346 | -not in theory. | |
| 347 | - | |
| 348 | -Unfortunately, Git does not currently provide the ability to add | |
| 349 | -corrections or clarifications or supplimental notes to historical check-ins. | |
| 350 | -Hence, once again, | |
| 351 | -rebase can be seen as an attempt to work around limitations | |
| 352 | -of Git. Git could be enhanced to support editorial changes | |
| 353 | -to check-ins. | |
| 354 | -Wouldn't it be better to fix the version control tool | |
| 355 | -rather than requiring users to fabricate a fictitious project history? | |
| 327 | +Fossil keeps the original incorrect or unclear inputs and makes them | |
| 328 | +readily accessible, preserving the original historical record. Fossil | |
| 329 | +doesn’t make the user tell counter-factual “stories,” it only allows the | |
| 330 | +user to provide annotations to provide a more readable edited | |
| 331 | +presentation for routine display purposes. | |
| 332 | + | |
| 333 | +Git needs rebase because it lacks these annotation facilities. Rather | |
| 334 | +than consider rebase a desirable feature missing in Fossil, ask instead | |
| 335 | +why Git lacks support for making editorial changes to check-ins without | |
| 336 | +modifyihng history? Wouldn't it be better to fix the version control | |
| 337 | +tool rather than requiring users to fabricate a fictitious project | |
| 338 | +history? | |
| 356 | 339 | |
| 357 | 340 | ## <a name="collapsing"></a>6.0 Collapsing check-ins throws away valuable information |
| 358 | 341 | |
| 359 | 342 | One of the oft-cited advantages of rebasing in Git is that it lets you |
| 360 | 343 | collapse multiple check-ins down to a single check-in to make the |
| 361 | 344 |
| --- www/rebaseharm.md | |
| +++ www/rebaseharm.md | |
| @@ -298,63 +298,46 @@ | |
| 298 | ## <a name="lying"></a>5.0 Rebasing is lying about the project history |
| 299 | |
| 300 | By discarding parentage information, rebase attempts to deceive the |
| 301 | reader about how the code actually came together. |
| 302 | |
| 303 | The [Git rebase documentation][gitrebase] admits as much. They acknowledge |
| 304 | that when you view a repository as record of what actually happened, |
| 305 | doing a rebase is "blasphemous" and "you're _lying_ about what |
| 306 | actually happened", but then goes on to justify rebase as follows: |
| 307 | |
| 308 | > |
| 309 | _"The opposing point of view is that the commit history is the **story of |
| 310 | how your project was made.** You wouldn't publish the first draft of a |
| 311 | book, and the manual for how to maintain your software deserves careful |
| 312 | editing. This is the camp that uses tools like rebase and filter-branch |
| 313 | to tell the story in the way that's best for future readers."_ |
| 314 | |
| 315 | This counter-argument assumes you must |
| 316 | change history in order to enhance readability, which is not true. |
| 317 | |
| 318 | In fairness to the Git documentation authors, changing the |
| 319 | project history appears to be the only way to make editorial |
| 320 | changes in Git. |
| 321 | But it does not have to be that way. |
| 322 | Fossil demonstrates how "the story of your project" |
| 323 | can be enhanced without changing the actual history |
| 324 | by allowing users to: |
| 325 | |
| 326 | 1. Edit check-in comments to fix typos or enhance clarity |
| 327 | 2. Attach supplemental notes to check-ins or whole branches |
| 328 | 3. Cross-reference check-ins with each other, or with |
| 329 | wiki, tickets, forum posts, and/or embedded documentation |
| 330 | 4. Hide ill-conceived or now-unused branches from routine display |
| 331 | 5. Fix faulty check-in date/times resulting from misconfigured |
| 332 | system clocks |
| 333 | |
| 334 | …and so forth. |
| 335 | |
| 336 | These changes are accomplished not by removing or modifying existing |
| 337 | repository entries, but rather by adding new supplemental records. |
| 338 | The original incorrect or unclear inputs are preserved and are |
| 339 | readily accessible. The original history is preserved. |
| 340 | But for routine display purposes, the more |
| 341 | readable edited presentation is provided. |
| 342 | |
| 343 | A repository can be a true and accurate |
| 344 | representation of history even without getting everything perfect |
| 345 | on the first draft. Those are not contradictory goals, at least |
| 346 | not in theory. |
| 347 | |
| 348 | Unfortunately, Git does not currently provide the ability to add |
| 349 | corrections or clarifications or supplimental notes to historical check-ins. |
| 350 | Hence, once again, |
| 351 | rebase can be seen as an attempt to work around limitations |
| 352 | of Git. Git could be enhanced to support editorial changes |
| 353 | to check-ins. |
| 354 | Wouldn't it be better to fix the version control tool |
| 355 | rather than requiring users to fabricate a fictitious project history? |
| 356 | |
| 357 | ## <a name="collapsing"></a>6.0 Collapsing check-ins throws away valuable information |
| 358 | |
| 359 | One of the oft-cited advantages of rebasing in Git is that it lets you |
| 360 | collapse multiple check-ins down to a single check-in to make the |
| 361 |
| --- www/rebaseharm.md | |
| +++ www/rebaseharm.md | |
| @@ -298,63 +298,46 @@ | |
| 298 | ## <a name="lying"></a>5.0 Rebasing is lying about the project history |
| 299 | |
| 300 | By discarding parentage information, rebase attempts to deceive the |
| 301 | reader about how the code actually came together. |
| 302 | |
| 303 | You may be tempted to dismiss this as an anti-Git opinion on a Fossil |
| 304 | web site, but it’s spelled out just like that [in the Git rebase |
| 305 | documentation][gitrebase]. It speaks of “lying,” “telling stories,” |
| 306 | and “blasphemy.” |
| 307 | |
| 308 | That section of the Git docs is contrasting rebase with merge, which we |
| 309 | cover [above](#cap-loss), but Git’s rebase feature is more than just an |
| 310 | alternative to merging: it also provides mechanisms for changing the |
| 311 | project history in order to make editorial changes. Fossil shows that |
| 312 | you can get similar effects without modifying historical records, |
| 313 | allowing users to: |
| 314 | |
| 315 | 1. Edit check-in comments to fix typos or enhance clarity |
| 316 | 2. Attach supplemental notes to check-ins or whole branches |
| 317 | 3. Hide ill-conceived or now-unused branches from routine display |
| 318 | 4. Fix faulty check-in date/times resulting from misconfigured |
| 319 | system clocks |
| 320 | 5. Cross-reference check-ins with each other, or with |
| 321 | wiki, tickets, forum posts, and/or embedded documentation |
| 322 | |
| 323 | …and so forth. |
| 324 | |
| 325 | Fossil allows all of this not by removing or modifying existing |
| 326 | repository entries, but rather by adding new supplemental records. |
| 327 | Fossil keeps the original incorrect or unclear inputs and makes them |
| 328 | readily accessible, preserving the original historical record. Fossil |
| 329 | doesn’t make the user tell counter-factual “stories,” it only allows the |
| 330 | user to provide annotations to provide a more readable edited |
| 331 | presentation for routine display purposes. |
| 332 | |
| 333 | Git needs rebase because it lacks these annotation facilities. Rather |
| 334 | than consider rebase a desirable feature missing in Fossil, ask instead |
| 335 | why Git lacks support for making editorial changes to check-ins without |
| 336 | modifyihng history? Wouldn't it be better to fix the version control |
| 337 | tool rather than requiring users to fabricate a fictitious project |
| 338 | history? |
| 339 | |
| 340 | ## <a name="collapsing"></a>6.0 Collapsing check-ins throws away valuable information |
| 341 | |
| 342 | One of the oft-cited advantages of rebasing in Git is that it lets you |
| 343 | collapse multiple check-ins down to a single check-in to make the |
| 344 |