![](/imgs/thumbnails/logo-git.png)
When to rewrite Git history?
Ok, so let's talk about Git and this "rule" that people often get attached to, "Don't rewrite history once it is shared!"
There is definitely some wisdom in this "rule". However, following this "rule" religiously also has some side effects. And it is worth understanding those in more depth, as well as understanding any alternatives and what their pros & cons might be.
When you follow this rule we have to ask, how do the branches we are working on
get updated with changes other developers have already integrated into main
?
Well, there are a couple of approaches we can use depending on our situation.
To explore these, let's assume we start with a Git tree that looks as follows.
* 9cabcd2 - (HEAD -> main, origin/main) commit C
* 6327c81 - commit B
* b68a192 - commit A
Now let's assume we have created some changes in a branch locally that we
have not pushed up to the remote yet. And that someone else has integrated
another change into main
.
* a0aca6f - (main, origin/main) commit G
| * fe06e90 - (HEAD -> feature/x) commit F
| * 81312b5 - commit E
| * f09acea - commit D
|/
* 9cabcd2 - commit C
* 6327c81 - commit B
* b68a192 - commit A
One option we have to include the new change in main
as part of our
feature/x
branch is to use git rebase
. This can effectively take the
commits from our branch and replay them on top of the commit that was added to
main
. Our tree would look as follows after doing this.
* ae46190 - (HEAD -> feature/x) commit F'
* 512b2ba - commit E'
* d09efea - commit D'
* a0aca6f - (main, origin/main) commit G
* 9cabcd2 - commit C
* 6327c81 - commit B
* b68a192 - commit A
This works great! It keeps our tree clean, simple, linear, and easy to
understand. However, commit D
, commit E
, and commit F
all have different
SHAs now, and are effectively commit D'
, commit E'
, and commit F'
. This
is totally fine right now because we hadn't shared commit D
, commit E
and
commit F
with anyone yet.
However, if we had shared commits D
, E
, and F
already by pushing our
branch up to the remote. We would have technically shared that history. And our
Git tree would look as follows.
* a0aca6f - (main, origin/main) commit G
| * fe06e90 - (HEAD -> feature/x, origin/feature/x) commit F
| * 81312b5 - commit E
| * f09acea - commit D
|/
* 9cabcd2 - commit C
* 6327c81 - commit B
* b68a192 - commit A
Therefore, when following this rule we can no longer use git rebase
to base
our branch on top of the latest main
because it would accomplish that by
rewriting the commits in the branch. Rewriting the commits could create
complications for other developers who happen to be working on the previous
state of the commits as the new commits have now diverged.
Instead, we need to bring the new commits in main
into our feature/x
branch
in a way that doesn't rewrite history. git merge
is exactly the command we
are looking for. As it creates a new merge commit that has multiple parent
commits. If we ran git merge main
it would look something like the following.
* f1cca4d - N - (HEAD -> feature/x) commit H
|\
| * fe06e90 - N - (origin/feature/x) commit F
| * 81312b5 - N - commit E
| * f09acea - N - commit D
* a0aca6f - N - (main, origin/main) commit G
|/
* 9cabcd2 - G - commit C
* 6327c81 - N - commit B
* b68a192 - N - commit A
In the above Git tree we can see that feature/x
contains the same commits
with the same SHAs as before, but also contains a new commit that merges main
into feature/x
.
This is great as it makes it so that you can easily collaborate with one or
more developers on the feature/x
branch. However, it also made the Git tree
more complex and complicated to understand. It might not be too bad with
one branch. But we haven't gotten to the step of merging our branch back into
main
at some point in the future. Or, the reality that often you need to
merge main into your feature branch multiple times as new changes are
introduced. Or, the reality of dealing with multiple branches doing the same
thing at the same time. Generally, you will end up with a very complicated tree
that looks something like the following.
Having these forward & backward merges happening also ends up eventually confusing Git when it comes to its ability to find merge bases correctly, in turn limiting the functionality of Git.
What is the Alternative?
The alternative is to simply use git rebase
on your feature branches.
However, we know that this can create problems for those collaborating on a
feature branch.
So we simply have an understanding of how we are going to treat feature
branches by default. For example, we can say that by default feature branches
are owned and controlled by their author. Anyone pulling down that branch and
testing it out or reviewing it should understand that the history is owned by
the author, and they will likely change it. Generally, the reviewing developer
uses something like git reset --hard origin/feature/x
to update their local
state to match that of the remote state.
Now, if you communicate out of band with the developer that owns the feature branch and let them know that you are going to push up a commit, they can integrate it into their feature branch in their local git repo and still use rebase. It just requires some out of band coordination. But this is actually a relatively rare situation for this to occur and therefore isn't a big deal.
It is also worth noting that taking this approach allows you to use the "Rebase & Merge" strategy in GitHub which will result in a linear Git history. Making it much easier to understand and manage over time.
Conclusion
I have used both these strategies and many others throughout my career. But the ease of understanding & management of a linear Git tree is far more valuable than simply not needing to worry about a tiny bit of out of band communication in the rare scenario that you need to directly contribute to someone else feature branch.
The key with this alternative is that you don't rewrite history for main
as
it is a central point of collaboration where you don't want to have deal with
the overhead of the out of bound communication and coordination. But due to the
rareness of the need to directly contribute to other peoples feature branches
the overhead of the out-of-band communication is more than an acceptable trade.