Mark’s Devblog

git rebase –onto

2026-07-25T00:00:00+00:00

git rebase –onto

If you’re not familiar with git rebase, I wrote a bit of a primer in a previous post about basic rebasing and git fetch tricks, so it might be worth reading that first.

The rest of this post is for git users who’re comfortable with basic rebasing. I’m going to explain how to use git rebase --onto, the problem it solves and why you might find it useful.

Warning: As ever, rebase-based workflows are intended for branches with only a single contributor. If multiple developers are pushing to the same branch, I wouldn’t recommend rebasing it.

What does the `--onto` option do?

While the documentation is fairly dry, there is a worked example that’s more illuminating, too.

Docs aside, what do I use --onto for? I use it when I have ‘stacked’ branches and Pull Requests (PRs). I like to create easily reviewable, self-contained commits and PRs. Also, for the purposes of this post, we’ll assume that the smallest mergeable unit is a PR.

The thing with creating small PRs is that, unfortunately this sometimes means branching off a branch. E.g. let’s say we’re implementing a feature and realise the code we’re extending is a bit of a mess. While we could create a PR containing both the refactor and the feature addition, this causes problems:

It mixes non-functional (refactoring) and functional (feature work) changes
It increases the PR size
It makes the PR harder to read, understand and review

If we have a good idea of what’s to be done, we could structure our changes such that we have main <- refactor <- feature, e.g.:

m1  m2  m3
o---o---o branch: main
         \
          r1  r2
          o---o branch: refactor
               \
                f1  f2
                o---o branch: feature               

Aside: There are multiple ways to structure this. You don’t even necessarily need multiple local branches, but that’s for another day :-)

These PRs are smaller and easier to review. The downside is that there’s more dependencies involved, and landing those PRs back into main requires extra care.

How do we land dependent PRs into main?

In the above example with refactor and feature PRs, the latter builds on the former, so we need to get our refactor branch’s changes into main as the first step.

Firstly, let’s merge refactor into main using a squash commit. If we’re using GitHub, BitBucket or any other forge that uses PR flows, we use the UI or CLI to merge the refactor branch into main, then pull main.

If we’re using plain ol’ git and no forge, we can run the commands:

git switch main
git merge --squash refactor
git commit

After the first squash merge, our local repo will look like this, as the content from the refactor branch’s commits [r1, r2] is now in commit m4:

m1  m2  m3  m4 (squash: r1 + r2)
o---o---o---o branch: main
         \
          r1  r2
          o---o branch: refactor
               \
                f1  f2
                o---o branch: feature               

So refactor’s contents are in main. We’re halfway there. Unfortunately, we’ve got a few problems:

The refactor branch is stale and just kinda existing despite its contents existing in main via our squash merge
Our feature branch is still connected to the tip of refactor

Before we can merge feature into main, we need to rebase it. Instead of f1’s parent being r2, we need to re-parent it to m4 (remember, m4 contains the contents of [r1, r2]).

Let’s use `git rebase --onto`

The documentation for git rebase --onto isn’t the easiest to follow, but the usual use case isn’t too hard to remember once you try it a few times.

git rebase --onto

: The new starting point for our commits
: The old starting point – this basically tells git, “don’t take any commits before this one”
: The branch we’re rebasing

In our example, run the following to get the desired effect:

git rebase --onto main refactor feature

This tells git rebase:

The commit we want as our new parent is the tip of the main branch
The old parent commit is the tip of the refactor branch (this effectively excludes the branch’s commits from the rebase operation)
The commit we want to rebase up to is the tip of feature

After running the command, we get the following structure:

m1  m2  m3  m4 (squash: r1 + r2)
o---o---o---o branch: main
             \
              f1  f2
              o---o branch: feature               

You can now push the updated feature branch to the remote via:

git push origin feature --force-with-lease

Note: The old refactor branch still exists at this point; I omitted it from the diagram for brevity. You can delete it via your forge’s controls and/or through git itself:

git branch -D refactor
git push origin --delete refactor

References

I found GitHub dev sameenkarim’s comment on HN really useful for understanding how this all worked.

Yes, we handle this both in the CLI and server using git rebase --onto

  git rebase --onto   

So for ex in this scenario:

  PR1: main <- A, B              (branch1)
  PR2: main <- A, B, C, D        (branch2)
  PR3: main <- A, B, C, D, E, F  (branch3)

When PR 1 and 2 are squash merged, main now looks like:

  S1 (squash of A+B), S2 (squash of C+D)

Then we run the following:

  git rebase --onto S2 D branch3

Which rewrites branch3 to:

  S1, S2, E, F

This operation moves the unique commits from the unmerged branch and replays them on top of the newly squashed commits on the base branch, avoiding any merge conflicts.

Next time: This reminds me that I should also write about why squash “merges” are not actually merge commits (they have one parent, a merge commit by definition must have two or more parents), and how forges retain context and links to long-merged PRs despite this lack of linkage in the git commit history.

Note: This blog post was hand-written – I am not a robot 🤖🔫.

git trick – git fetch origin main:main

2026-07-24T00:00:00+00:00

Git rebase basics

A decent percentage of git users know what rebase does. In its simplest form, it takes one series of commits – typically from a branch –, detaches them from their parent commit and glues them onto the tip of another parent commit (which is frequently just the updated tip of same branch).

I started writing this post about rebase, but it ended up being partly about the curious git fetch origin : syntax – the : part is a refspec. Read on for details.

This post will take you through:

The concept of rebasing
The 4 commands that most tutorials contain
How to cut that down to 2 commands and eliminate branch switches
What the odd-looking git fetch origin : command does

Example: rebasing (the long way)

Note: if you’re familiar with rebase, skip on to the next bit.

We branched off main a while back (commit m3 to be precise), but after fetching the latest version of main, we can see new commits were made: [m4, m5].

m1  m2  m3  m4  m5
o---o---o---o---o branch: main
         \
          a1  a2
          o---o branch: a

We want to update our branch a (with commits [a1, a2]) so that it’s branched off the latest version of main, aka commit m5.

m1  m2  m3  m4  m5
o---o---o---o---o branch: main
                 \
                  a1' a2'
                  o---o branch: a

Note: The commits [a1', a2'] (pronounced a1 prime, a2 prime) no longer have the same commit hashes, even if the underlying change content is identical – a commit hash is calculated using the parent commit(s), message, file contents and more. The parent commit has changed, so the hash has too.

What commands do we need to execute to achieve this goal state? Most tutorials will tell you to run a series of commands similar to the following (assuming we’ve got branch a checked out and active):

# we're on branch `a`, so let's switch to the main branch
~/example (a) $ git switch main

# fetch latest changes and fast-forward the main branch
# this isn't the rebase we're interested in, though
~/example (main) $ git pull origin main --rebase

# switch back to last active branch, equiv. to `git switch a`
~/example (main) $ git switch -

# rebase, which basically says "glue branch a to the tip of main`
~/example (a) $ git rebase main

A slicker way – use `git fetch origin main:main`

If you’re like 95% of GitHub/BitBucket/Whatever projects these days, developers directly commits to the main branch or push it (or whatever your trunk branch is called). Consequently, the main branch is effectively readonly. Our Continuous Integration (CI) processes handle the merges to main.

This helps because we’ll never be locally editing main, so all updates will be saying to git, “please make my version of main reflect the remote’s version of things”.

Since we no longer need to merge or resolve conflicts on main, we can use the following (slightly odd-looking) git fetch syntax to streamline things:

# again, we've got branch `a` checked out and active
~/example (a) $ git fetch origin main:main

# rebase our `a` branch against freshly updated `main`
~/example (a) $ git rebase main

“Bringo.” We’ve halved the number of required commands. As there’s no need to switch to main, there’s no need to switch back to a – we were never switched to main in the first place!

The slightly odd-looking git fetch origin : refspec syntax fetches main from the remote and updates our local copy to match it. If your local main branch has commits not present on the remote, the command will be rejected so as to preserve your local repo’s history.

If you’re a devil-may-care type, you can overwrite your local history by prepending + to the start of the refspec:

# I wouldn't recommend doing this, as it can be destructive
~/example (a) $ git fetch origin +main:main

I’ve been carping on about git rebase, but we can use the same git fetch trick even if we’re going to use git merge to fold the latest main contents into a, instead. I just so happen to prefer rebasing by default:

# again, we've got branch `a` checked out and active
~/example (a) $ git fetch origin main:main

# merge the latest main into `a`
~/example (a) $ git merge main

So there we go. You can now rebase or merge faster and while using fewer commands. You also now understand what the funky refspec syntax does.

Note: This blog post was hand-written – I am not a robot 🤖🔫.

The new git history commands

2026-07-16T00:00:00+00:00

git has some rough edges

Git has been around a long time (I’ve been using it since around 2011, where’d the time go?) and doesn’t seem to be going anywhere. The main advantage with git is the flexibility – if you can think of doing something, you probably can do it. The downside is that its cli commands often lack comfort and consistency (and I’m saying that as someone who has a good grasp of its internals and is often the friendly “please help me fix my git disaster” guy).

Sometimes fairly simple things require incantations and a small sacrifice. I’m not sure if “un-ergonomic” is the right term, but git certainly can be trying – there’s a reason https://ohshitgit.com/ is a thing. I occasionally still backup branches before I perform git surgery. Still, it beats using Perforce, SVN or CVS.

Problem: `git checkout`

Even everyday commands can be unwieldy. Here’s an example of a particularly old, overloaded command: git checkout.

git checkout [-q] [-f] [-m] []
git checkout [-q] [-f] [-m] --detach []
git checkout [-q] [-f] [-m] [--detach] 
git checkout [-q] [-f] [-m] [[-b|-B|--orphan] ] []
git checkout  [--] …​
git checkout  --pathspec-from-file= [--pathspec-file-nul]
git checkout [-f|--ours|--theirs|-m|--conflict=

Mark’s Devblog

git rebase –onto

git rebase –onto

What does the --onto option do?

How do we land dependent PRs into main?

Let’s use git rebase --onto

References

git trick – git fetch origin main:main

Git rebase basics

Example: rebasing (the long way)

A slicker way – use git fetch origin main:main

The new git history commands

git has some rough edges

Problem: git checkout

What does the `--onto` option do?

Let’s use `git rebase --onto`

A slicker way – use `git fetch origin main:main`

Problem: `git checkout`