Git update-refs in a nutshell

Original article on my blog (🇫🇷)

When working on a versioned project, it is relatively common to end up with a "stack" of branches. What could be more frustrating than having to rebase all the other branches on top of the first one when updating it? This process becomes even more tedious when the number of branches is high or when they are regularly modified.

Git version 2.38¹ introduces a solution to this problem: the update-refs rebase option.

Stack?

Branch stacking is a way to break down important features, allowing for smaller pull requests. In the example below, three branches dependent on each other have been created, allowing "my feature" to be divided into three distinct blocks.

The assumption here is that when each of these branches is individually merged into the main branch, the code will still be functional, as it has been appropriately divided.

Let's say a small typo was made in the commit of the my-feature-v1 branch. A second commit needs to be added to fix the issue, resulting in the following history:

In this situation, the only solution to update my-feature-v2 and my-feature-v3 is to checkout and rebase v2 on v1, then v3 on v2.

This cumbersome process is remedied by the update-refs rebase option.

The solution

update-refs

The goal of this option is to automatically update the n branches on which the branch being rebased depends.

Thus, in our case, we can simply checkout our my-feature-v3 branch and run the command git rebase my-feature-v1 --update-refs. With this option, Git updates not only the v3 branch but also the v2 branch to preserve the history. The result of this operation is as follows:

In practice:

Updating the Remote Repository

Even if the branches being manipulated have already been pushed to the remote repository, it is possible to update all of them in a single command: git push --force-with-lease origin my-feature-v1 my-feature-v2 my-feature-v3

Here, a specific force push is used to preserve the remote history².

Global Activation

Why not always use the update-refs option during a rebase? The Git team asked themselves the same question and decided to include this possibility in the configuration. Thus, git config --global rebase.updateRefs true activates the option globally for each of your rebases.

In Summary

• git rebase {my-branch} --update-refs updates a branch and all its dependencies
• git push --force-with-lease origin my-branch-1 my-branch-2 my-branch-n pushes the update of these branches to the remote repository

Happy rebasing!

---

1. The release note is available here ↩

2. See the use case ↩

Comments

[Dan Jones]

This is very cool. Should definitely save a lot of time.

[Andrej Podzimek]

And 2 years later, the feature still doesn’t work, perfectly aligned with the typical Git style of doing things. git checkout my-feature-v3; git rebase my-feature-v1 --update-refs; will in fact fail to update the my-feature-v2 branch, leaving the branch name on its previous path. This ranges from confusing to dangerous, depending on the user’s awareness of diverse Git bugs.

What you need to do additionally, after the rebase, is to

1. find the new commit hash corresponding to my-feature-v2 on the current path that leads to my-feature-v3 (e.g. from git log), and then
2. git checkout the_hash; git branch -f my-feature-v2; (plus git checkout my-feature-v3; to get back).

Then and only then you get the desired structure with my-feature-v2 on your current path.

That said: what if 20 different branches branch off my-feature-v1? Then Git becomes a total shipwreck.

To contrast this against a system that works: In Mercurial,

• if your typo fix doesn’t warrant a separate commit, then: hg amend; hg evolve;. There. That’s all. No hashes, no tricky bugs, no log inspection, no confusion. If 20 branches branch off my-feature-v1, they are covered too.
• if your typo fix does warrant a separate commit, then commit the typo fix and hg rebase -s my-feature-v2 -d my-feature-v1. Then, sadly, you have to do the same for the 20 other branches, but at least Mercurial gets it right every time.

[Andrej Podzimek]

Plus don’t get me started on how this “works” with git pull --rebase. It doesn’t. But with git config --global rebase.updateRefs true, it does something really odd. Uh oh.