Live on Product Hunt Intraface launched today. Less steering, more vacations. See the launch
Start for free

What is a rebase?

A rebase takes a change you made against an older version and replays it on top of the newest one, as if you had started there. In git, git rebase moves a branch's commits onto another branch's tip. On a shared board, an agent whose publish is refused as needs_rebase pulls the latest version and redoes its edit.

Part of Glossary: the terms behind MCP, coding agents and shared pages, defined plainly.

How it works

Your agent edited version 3; someone else published 4 first. The agent pulls 4, redoes the edit on top, and publishes 5.youyour agentedit made on version 3a teammate publishedversion 4 meanwhilethe boardversions 1 to 4version 5your edit, on top of 4asks for a change1. publish, based on 32. needs_rebase: see 43. pull 4, redo edit4. publish lands as 5
  1. You start from a known point: a commit on main, or version 3 of a board. You make your change against it.

  2. Meanwhile someone else lands a change on the same line: a new commit on main, or version 4 of the board.

  3. To rebase, you take their newest version and apply your change on top of it, as if you had started from there.

  4. Where you both touched the same lines, the replay stops and you decide. In git: fix the file, git add it, then git rebase --continue.

    git rebase --abort puts the branch back exactly as it was. --skip drops the commit that conflicted.

  5. The result is a straight line. In git the old commits are replaced by new ones; on a board your redo simply becomes version 5.

Source: Pro Git: Git Branching, Rebasing

Rebase versus merge

Pro Git describes rebasing as going to the common ancestor of two branches, saving the diff of each commit on your branch, resetting your branch to the other tip, and applying those diffs in turn. A merge does something else with the same inputs: it takes both tips plus the ancestor and produces one new commit with two parents.

The final snapshot is identical either way. What differs is the story the log tells. After a rebase the history is linear, as if you had waited for your colleague to finish before you began. After a merge the two lines stay visible and join at the merge commit. Teams that review by reading history tend to rebase; teams that want the record of parallel work as it happened tend to merge.

Example: an agent rebases a publish

A shared board works like a tiny repository with one branch. Suppose your agent pulls version 3 of a board, rewrites the pricing table in index.html, and publishes. While it worked, a teammate's agent published version 4, which also changed index.html. The queue refuses yours with needs_rebase, naming the file and the teammate.

The agent now does by hand what git rebase does by machine: it pulls version 4, reads what changed, applies its pricing rewrite on top, and publishes again. That publish lands as version 5. Had the teammate changed only style.css, there would have been nothing to rebase; publishes to different files are merged onto each other automatically, and both land.

The point worth noticing is who resolves the overlap. Git stops and shows you conflict markers. The board hands the whole file back to the agent that is behind, which rereads the newer version and redoes the edit with the new context in view.

When to rebase

Rebase when you want your change to sit cleanly on the newest state before anyone else sees it: a feature branch before a pull request, a local commit before git push, an agent's publish that was refused. git pull --rebase does this for the everyday case, and pull.rebase true makes it the default.

Do not rebase commits that exist outside your repository and that people may have based work on. That sentence is Pro Git's one rule for rebasing, and it exists because rebasing abandons the old commits and creates look-alikes; collaborators who built on the originals are left re-merging.

Common mistakes

  • Treating needs_rebase as an error. It is the normal outcome when two people edit the same file at once. The loop is pull, redo, publish.
  • Redoing the edit blind. The newer version may have moved or renamed the thing you were changing. Read it before replaying.
  • Rebasing a shared branch to tidy it. The log looks better and everyone else's clone breaks. Tidy before pushing, not after.
  • Aborting when you meant to continue. git rebase --abort returns to where you started; --continue goes on after you have staged the fix. Mixing them up loses the resolution you just made.

FAQ

Is a rebase the same as a merge?
They end with the same files but a different history. A merge takes the two branch tips and their common ancestor and makes one merge commit joining them. A rebase replays your commits one by one on top of the other tip, so the log reads as if the work had happened in series.
What does needs_rebase mean when an agent publishes?
The agent published from a version that is no longer the latest, and someone changed the same file in between. The response names the file and who changed it. The fix is the rebase loop: pull the current version, make the edit again on top of it, publish.
Why should you not rebase commits you have already pushed?
Rebasing replaces commits with new ones that have different ids. Anyone who built on the old commits now has history that no longer exists upstream and will have to re-merge. Pro Git's rule: rebase local work before you push, and never rebase anything you have pushed somewhere.

Stop sending HTMLover Slack.

Create an account in a minute, connect your coding agent, and make your first board.