Fossil SCM
Add section numbers to the Rebase document.
Commit
237bde9638cd0b7f050eb154b06a70ec3f9cb497495f6d8654e7a3217d67efdc
Parent
aaacce23cd81f05…
1 file changed
+10
-8
+10
-8
| --- www/rebaseharm.md | ||
| +++ www/rebaseharm.md | ||
| @@ -5,11 +5,11 @@ | ||
| 5 | 5 | Fossil deliberately does not implement "rebase", because the original |
| 6 | 6 | designer of Fossil (and author of this article) considers rebase to be |
| 7 | 7 | an anti-pattern to be avoided. This article attempts to |
| 8 | 8 | explain that point of view. |
| 9 | 9 | |
| 10 | -## Rebasing is dangerous | |
| 10 | +## 1.0 Rebasing is dangerous | |
| 11 | 11 | |
| 12 | 12 | Everyone, even the most vocal advocates of rebase, agrees that rebase can |
| 13 | 13 | cause problems when misused. All rebase documentation talks about the |
| 14 | 14 | [golden rule of rebase][golden], that it should never be used on a public |
| 15 | 15 | branch. Horror stories of misused rebase abound, and the rebase |
| @@ -19,11 +19,11 @@ | ||
| 19 | 19 | Sometimes sharp and dangerous tools are justified, |
| 20 | 20 | because they accomplish things that cannot be |
| 21 | 21 | (easily) done otherwise. But rebase does not fall into that category. |
| 22 | 22 | It provides no new capabilities, as we shall see in the next section: |
| 23 | 23 | |
| 24 | -## A rebase is just a merge with historical references omitted | |
| 24 | +## 2.0 A rebase is just a merge with historical references omitted | |
| 25 | 25 | |
| 26 | 26 | A rebase is really nothing more than a merge (or a series of merges) |
| 27 | 27 | that deliberately forgets one of the parents of each merge step. |
| 28 | 28 | To help illustrate this fact, |
| 29 | 29 | consider the first rebase example from the |
| @@ -62,10 +62,12 @@ | ||
| 62 | 62 | important. |
| 63 | 63 | |
| 64 | 64 | So, another way of thinking about rebase is that it is a kind of |
| 65 | 65 | merge the intentionally forgets some details in order to |
| 66 | 66 | not overwhelm the weak history display mechanisms available in Git. |
| 67 | + | |
| 68 | +### 2.1 Rebase does not actually provide better feature-branch diffs | |
| 67 | 69 | |
| 68 | 70 | Another argument, often cited, is that rebasing a feature branch |
| 69 | 71 | allows one to see just the changes in the feature branch without |
| 70 | 72 | the concurrent changes in the main line of development. |
| 71 | 73 | Consider a hypothetical case: |
| @@ -123,11 +125,11 @@ | ||
| 123 | 125 | |
| 124 | 126 | So to help with the problem of viewing changes associated with a feature |
| 125 | 127 | branch, perhaps what is needed is not rebase but rather better tools to |
| 126 | 128 | help users identify an appropriate baseline for their diffs. |
| 127 | 129 | |
| 128 | -## Rebase encourages siloed development | |
| 130 | +## 3.0 Rebase encourages siloed development | |
| 129 | 131 | |
| 130 | 132 | The [golden rule of rebase][golden] is that you should never do it |
| 131 | 133 | on public branches. So if you are using rebase as intended, that means |
| 132 | 134 | you are keeping private branches. Or, to put it another way, you are |
| 133 | 135 | doing siloed development. You are not sharing your intermediate work |
| @@ -147,11 +149,11 @@ | ||
| 147 | 149 | code right before I publish it". I sympathize with this sentiment, |
| 148 | 150 | and am frequently guilty of it myself. It is humbling to display |
| 149 | 151 | your stupid mistake to the whole world on an internet that |
| 150 | 152 | never forgets. And yet, humble programmers generate better code. |
| 151 | 153 | |
| 152 | -## Rebase commits untested check-ins to the blockchain | |
| 154 | +## 4.0 Rebase commits untested check-ins to the blockchain | |
| 153 | 155 | |
| 154 | 156 | Rebase adds new check-ins to the blockchain without giving the operator |
| 155 | 157 | an opportunity to test and verify those check-ins. Just because the |
| 156 | 158 | underlying three-way merge had no conflict does not mean that the resulting |
| 157 | 159 | code actually works. Thus, rebase runs the very real risk of adding |
| @@ -164,11 +166,11 @@ | ||
| 164 | 166 | and a chance to back out or fix the change if it is broken, without leaving |
| 165 | 167 | busted check-ins on the blockchain to complicate future bisects. |
| 166 | 168 | |
| 167 | 169 | With rebase, pre-commit testing is not an option. |
| 168 | 170 | |
| 169 | -## Rebase causes timestamp confusion | |
| 171 | +## 5.0 Rebase causes timestamp confusion | |
| 170 | 172 | |
| 171 | 173 | Consider the earlier example of rebasing a feature branch: |
| 172 | 174 | |
| 173 | 175 | ~~~ |
| 174 | 176 | ,-- C3 --- C5 ,-- C3' -- C5' |
| @@ -185,11 +187,11 @@ | ||
| 185 | 187 | unique timestamps for C3' and C5'. But then you lose the information |
| 186 | 188 | about when those check-ins were originally created, which can make |
| 187 | 189 | historical analysis of changes more difficult, and might also |
| 188 | 190 | complicate prior art claims. |
| 189 | 191 | |
| 190 | -## Rebasing is the same as lying | |
| 192 | +## 6.0 Rebasing is the same as lying | |
| 191 | 193 | |
| 192 | 194 | By discarding parentage information, rebase attempts to deceive the |
| 193 | 195 | reader about how the code actually came together. |
| 194 | 196 | |
| 195 | 197 | The [Git rebase documentation][gitrebase] admits as much. They acknowledge |
| @@ -225,11 +227,11 @@ | ||
| 225 | 227 | or clarifications to historical check-ins in its blockchain. Hence, |
| 226 | 228 | once again, rebase can be seen as an attempt to work around limitations |
| 227 | 229 | of Git. Wouldn't it be better to fix the tool rather that to lie about |
| 228 | 230 | the project history? |
| 229 | 231 | |
| 230 | -## Cherry-pick merges work better then rebase | |
| 232 | +## 7.0 Cherry-pick merges work better then rebase | |
| 231 | 233 | |
| 232 | 234 | Perhaps there some cases where a rebase-like transformation |
| 233 | 235 | is actually helpful. But those cases are rare. And when they do |
| 234 | 236 | come up, running a series of cherry-pick merges achieve the same |
| 235 | 237 | topology, but with advantages: |
| @@ -245,11 +247,11 @@ | ||
| 245 | 247 | cause problems for collaborators if you do them on public branches. |
| 246 | 248 | |
| 247 | 249 | 4. Cherry-picks preserve both the original and the revised check-ins, |
| 248 | 250 | so both timestamps are preserved. |
| 249 | 251 | |
| 250 | -## Summary And Conclusion | |
| 252 | +## 8.0 Summary And Conclusion | |
| 251 | 253 | |
| 252 | 254 | Rebasing is an anti-pattern. It is dishonest. It deliberately |
| 253 | 255 | omits historical information. It causes problems for collaboration. |
| 254 | 256 | And it has no offsetting benefits. |
| 255 | 257 | |
| 256 | 258 |
| --- www/rebaseharm.md | |
| +++ www/rebaseharm.md | |
| @@ -5,11 +5,11 @@ | |
| 5 | Fossil deliberately does not implement "rebase", because the original |
| 6 | designer of Fossil (and author of this article) considers rebase to be |
| 7 | an anti-pattern to be avoided. This article attempts to |
| 8 | explain that point of view. |
| 9 | |
| 10 | ## Rebasing is dangerous |
| 11 | |
| 12 | Everyone, even the most vocal advocates of rebase, agrees that rebase can |
| 13 | cause problems when misused. All rebase documentation talks about the |
| 14 | [golden rule of rebase][golden], that it should never be used on a public |
| 15 | branch. Horror stories of misused rebase abound, and the rebase |
| @@ -19,11 +19,11 @@ | |
| 19 | Sometimes sharp and dangerous tools are justified, |
| 20 | because they accomplish things that cannot be |
| 21 | (easily) done otherwise. But rebase does not fall into that category. |
| 22 | It provides no new capabilities, as we shall see in the next section: |
| 23 | |
| 24 | ## A rebase is just a merge with historical references omitted |
| 25 | |
| 26 | A rebase is really nothing more than a merge (or a series of merges) |
| 27 | that deliberately forgets one of the parents of each merge step. |
| 28 | To help illustrate this fact, |
| 29 | consider the first rebase example from the |
| @@ -62,10 +62,12 @@ | |
| 62 | important. |
| 63 | |
| 64 | So, another way of thinking about rebase is that it is a kind of |
| 65 | merge the intentionally forgets some details in order to |
| 66 | not overwhelm the weak history display mechanisms available in Git. |
| 67 | |
| 68 | Another argument, often cited, is that rebasing a feature branch |
| 69 | allows one to see just the changes in the feature branch without |
| 70 | the concurrent changes in the main line of development. |
| 71 | Consider a hypothetical case: |
| @@ -123,11 +125,11 @@ | |
| 123 | |
| 124 | So to help with the problem of viewing changes associated with a feature |
| 125 | branch, perhaps what is needed is not rebase but rather better tools to |
| 126 | help users identify an appropriate baseline for their diffs. |
| 127 | |
| 128 | ## Rebase encourages siloed development |
| 129 | |
| 130 | The [golden rule of rebase][golden] is that you should never do it |
| 131 | on public branches. So if you are using rebase as intended, that means |
| 132 | you are keeping private branches. Or, to put it another way, you are |
| 133 | doing siloed development. You are not sharing your intermediate work |
| @@ -147,11 +149,11 @@ | |
| 147 | code right before I publish it". I sympathize with this sentiment, |
| 148 | and am frequently guilty of it myself. It is humbling to display |
| 149 | your stupid mistake to the whole world on an internet that |
| 150 | never forgets. And yet, humble programmers generate better code. |
| 151 | |
| 152 | ## Rebase commits untested check-ins to the blockchain |
| 153 | |
| 154 | Rebase adds new check-ins to the blockchain without giving the operator |
| 155 | an opportunity to test and verify those check-ins. Just because the |
| 156 | underlying three-way merge had no conflict does not mean that the resulting |
| 157 | code actually works. Thus, rebase runs the very real risk of adding |
| @@ -164,11 +166,11 @@ | |
| 164 | and a chance to back out or fix the change if it is broken, without leaving |
| 165 | busted check-ins on the blockchain to complicate future bisects. |
| 166 | |
| 167 | With rebase, pre-commit testing is not an option. |
| 168 | |
| 169 | ## Rebase causes timestamp confusion |
| 170 | |
| 171 | Consider the earlier example of rebasing a feature branch: |
| 172 | |
| 173 | ~~~ |
| 174 | ,-- C3 --- C5 ,-- C3' -- C5' |
| @@ -185,11 +187,11 @@ | |
| 185 | unique timestamps for C3' and C5'. But then you lose the information |
| 186 | about when those check-ins were originally created, which can make |
| 187 | historical analysis of changes more difficult, and might also |
| 188 | complicate prior art claims. |
| 189 | |
| 190 | ## Rebasing is the same as lying |
| 191 | |
| 192 | By discarding parentage information, rebase attempts to deceive the |
| 193 | reader about how the code actually came together. |
| 194 | |
| 195 | The [Git rebase documentation][gitrebase] admits as much. They acknowledge |
| @@ -225,11 +227,11 @@ | |
| 225 | or clarifications to historical check-ins in its blockchain. Hence, |
| 226 | once again, rebase can be seen as an attempt to work around limitations |
| 227 | of Git. Wouldn't it be better to fix the tool rather that to lie about |
| 228 | the project history? |
| 229 | |
| 230 | ## Cherry-pick merges work better then rebase |
| 231 | |
| 232 | Perhaps there some cases where a rebase-like transformation |
| 233 | is actually helpful. But those cases are rare. And when they do |
| 234 | come up, running a series of cherry-pick merges achieve the same |
| 235 | topology, but with advantages: |
| @@ -245,11 +247,11 @@ | |
| 245 | cause problems for collaborators if you do them on public branches. |
| 246 | |
| 247 | 4. Cherry-picks preserve both the original and the revised check-ins, |
| 248 | so both timestamps are preserved. |
| 249 | |
| 250 | ## Summary And Conclusion |
| 251 | |
| 252 | Rebasing is an anti-pattern. It is dishonest. It deliberately |
| 253 | omits historical information. It causes problems for collaboration. |
| 254 | And it has no offsetting benefits. |
| 255 | |
| 256 |
| --- www/rebaseharm.md | |
| +++ www/rebaseharm.md | |
| @@ -5,11 +5,11 @@ | |
| 5 | Fossil deliberately does not implement "rebase", because the original |
| 6 | designer of Fossil (and author of this article) considers rebase to be |
| 7 | an anti-pattern to be avoided. This article attempts to |
| 8 | explain that point of view. |
| 9 | |
| 10 | ## 1.0 Rebasing is dangerous |
| 11 | |
| 12 | Everyone, even the most vocal advocates of rebase, agrees that rebase can |
| 13 | cause problems when misused. All rebase documentation talks about the |
| 14 | [golden rule of rebase][golden], that it should never be used on a public |
| 15 | branch. Horror stories of misused rebase abound, and the rebase |
| @@ -19,11 +19,11 @@ | |
| 19 | Sometimes sharp and dangerous tools are justified, |
| 20 | because they accomplish things that cannot be |
| 21 | (easily) done otherwise. But rebase does not fall into that category. |
| 22 | It provides no new capabilities, as we shall see in the next section: |
| 23 | |
| 24 | ## 2.0 A rebase is just a merge with historical references omitted |
| 25 | |
| 26 | A rebase is really nothing more than a merge (or a series of merges) |
| 27 | that deliberately forgets one of the parents of each merge step. |
| 28 | To help illustrate this fact, |
| 29 | consider the first rebase example from the |
| @@ -62,10 +62,12 @@ | |
| 62 | important. |
| 63 | |
| 64 | So, another way of thinking about rebase is that it is a kind of |
| 65 | merge the intentionally forgets some details in order to |
| 66 | not overwhelm the weak history display mechanisms available in Git. |
| 67 | |
| 68 | ### 2.1 Rebase does not actually provide better feature-branch diffs |
| 69 | |
| 70 | Another argument, often cited, is that rebasing a feature branch |
| 71 | allows one to see just the changes in the feature branch without |
| 72 | the concurrent changes in the main line of development. |
| 73 | Consider a hypothetical case: |
| @@ -123,11 +125,11 @@ | |
| 125 | |
| 126 | So to help with the problem of viewing changes associated with a feature |
| 127 | branch, perhaps what is needed is not rebase but rather better tools to |
| 128 | help users identify an appropriate baseline for their diffs. |
| 129 | |
| 130 | ## 3.0 Rebase encourages siloed development |
| 131 | |
| 132 | The [golden rule of rebase][golden] is that you should never do it |
| 133 | on public branches. So if you are using rebase as intended, that means |
| 134 | you are keeping private branches. Or, to put it another way, you are |
| 135 | doing siloed development. You are not sharing your intermediate work |
| @@ -147,11 +149,11 @@ | |
| 149 | code right before I publish it". I sympathize with this sentiment, |
| 150 | and am frequently guilty of it myself. It is humbling to display |
| 151 | your stupid mistake to the whole world on an internet that |
| 152 | never forgets. And yet, humble programmers generate better code. |
| 153 | |
| 154 | ## 4.0 Rebase commits untested check-ins to the blockchain |
| 155 | |
| 156 | Rebase adds new check-ins to the blockchain without giving the operator |
| 157 | an opportunity to test and verify those check-ins. Just because the |
| 158 | underlying three-way merge had no conflict does not mean that the resulting |
| 159 | code actually works. Thus, rebase runs the very real risk of adding |
| @@ -164,11 +166,11 @@ | |
| 166 | and a chance to back out or fix the change if it is broken, without leaving |
| 167 | busted check-ins on the blockchain to complicate future bisects. |
| 168 | |
| 169 | With rebase, pre-commit testing is not an option. |
| 170 | |
| 171 | ## 5.0 Rebase causes timestamp confusion |
| 172 | |
| 173 | Consider the earlier example of rebasing a feature branch: |
| 174 | |
| 175 | ~~~ |
| 176 | ,-- C3 --- C5 ,-- C3' -- C5' |
| @@ -185,11 +187,11 @@ | |
| 187 | unique timestamps for C3' and C5'. But then you lose the information |
| 188 | about when those check-ins were originally created, which can make |
| 189 | historical analysis of changes more difficult, and might also |
| 190 | complicate prior art claims. |
| 191 | |
| 192 | ## 6.0 Rebasing is the same as lying |
| 193 | |
| 194 | By discarding parentage information, rebase attempts to deceive the |
| 195 | reader about how the code actually came together. |
| 196 | |
| 197 | The [Git rebase documentation][gitrebase] admits as much. They acknowledge |
| @@ -225,11 +227,11 @@ | |
| 227 | or clarifications to historical check-ins in its blockchain. Hence, |
| 228 | once again, rebase can be seen as an attempt to work around limitations |
| 229 | of Git. Wouldn't it be better to fix the tool rather that to lie about |
| 230 | the project history? |
| 231 | |
| 232 | ## 7.0 Cherry-pick merges work better then rebase |
| 233 | |
| 234 | Perhaps there some cases where a rebase-like transformation |
| 235 | is actually helpful. But those cases are rare. And when they do |
| 236 | come up, running a series of cherry-pick merges achieve the same |
| 237 | topology, but with advantages: |
| @@ -245,11 +247,11 @@ | |
| 247 | cause problems for collaborators if you do them on public branches. |
| 248 | |
| 249 | 4. Cherry-picks preserve both the original and the revised check-ins, |
| 250 | so both timestamps are preserved. |
| 251 | |
| 252 | ## 8.0 Summary And Conclusion |
| 253 | |
| 254 | Rebasing is an anti-pattern. It is dishonest. It deliberately |
| 255 | omits historical information. It causes problems for collaboration. |
| 256 | And it has no offsetting benefits. |
| 257 | |
| 258 |