git rebase: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

git rebase moves your commits on top of another base, rewriting them as new commits.

Rebase produces a linear history but rewrites commit SHAs, so a rebased branch needs a force push.

What it does

git rebase reapplies your branch commits one by one onto a new base commit, creating new commits with new SHAs. Conflicts pause the rebase until resolved.

Common usage

Terminal

git rebase main
git rebase -i HEAD~3            # squash/reorder last 3 commits
git rebase --onto main old new
# after fixing a conflict:
git add <file> && git rebase --continue
git rebase --abort

Options

Flag	What it does
-i / --interactive	Edit, squash, drop, or reorder commits
--onto <newbase>	Rebase a range onto an arbitrary base
--continue	Proceed after resolving a conflict
--abort	Restore the original branch state
--autosquash	Apply fixup!/squash! commits automatically

Common errors in CI

CONFLICT … "Resolve all conflicts manually, mark them as resolved with git add, then run git rebase --continue" - the rebase halts mid-way. After rebasing, a push is rejected as non-fast-forward; you must git push --force-with-lease. Interactive rebase needs a non-interactive editor or sequence in CI (e.g. GIT_SEQUENCE_EDITOR).

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

git rebase: Usage, Options & Common CI Errors?