Git rebase and force push

In Git, a rebase updates your branch with the contents of another branch. A rebase confirms that changes in your branch don’t conflict with changes in the target branch.

If you have a merge conflict, you can rebase to fix it.

What happens during rebase

When you rebase:

  1. Git imports all the commits submitted to your target branch after you initially created your branch from it.

  2. Git stacks the commits you have in your branch on top of all the commits it imported from that branch:

    Git rebase illustration

While most rebases are performed against main, you can rebase against any other branch, such as release-15-3. You can also specify a different remote repository (such as upstream) instead of origin.

caution
git rebase rewrites the commit history. It can be harmful to do it in shared branches. It can cause complex and hard to resolve merge conflicts. Instead of rebasing your branch against the default branch, consider pulling it instead (git pull origin master). Pulling has similar effects with less risk of compromising others’ work.

Rebase by using Git

When you use Git to rebase, each commit is applied to your branch. When merge conflicts occur, you are prompted to address them.

If you want more advanced options for your commits, do an interactive rebase.

Prerequisites:

  • You must have permission to force push to branches.

To use Git to rebase your branch against the target branch:

  1. Open a terminal and change to your project.

  2. Ensure you have the latest contents of the target branch. In this example, the target branch is main: 

    git fetch origin main

  3. Check out your branch: 

    git checkout my-branch

  4. Optional. Create a backup of your branch: 

    git branch my-branch-backup

    Changes added to my-branch after this point are lost if you restore from the backup branch.

  5. Rebase against the main branch: 

    git rebase origin/main
  6. If merge conflicts exist:

    1. Fix the conflicts in your editor.

    2. Add the files: 

      git add .

    3. Continue the rebase: 

      git rebase --continue

  7. Force push your changes to the target branch, while protecting others’ commits: 

    git push origin my-branch --force-with-lease

Rebase from the UI

You can rebase a merge request from the GitLab UI.

Prerequisites:

  • No merge conflicts must exist.
  • You must have at least the Developer role for the source project. This role grants you permission to push to the source branch for the source project.
  • If the merge request is in a fork, the fork must allow commits from members of the upstream project.

To rebase from the UI:

  1. Go to your merge request.
  2. Type /rebase in a comment.
  3. Select Comment.

GitLab schedules a rebase of the branch against the default branch and executes it as soon as possible.

Rebase interactively by using Git

Use an interactive rebase when you want to specify how to handle each commit. You must do an interactive rebase from the command line.

Prerequisites:

  • Vim must be your text editor to follow these instructions.

To rebase interactively:

  1. Open a terminal and change to your project.

  2. Ensure you have the latest contents of the target branch. In this example, the target branch is main: 

    git fetch origin main

  3. Check out your branch: 

    git checkout my-branch

  4. Optional. Create a backup of your branch: 

    git branch my-branch-backup

    Changes added to my-branch after this point are lost if you restore from the backup branch.

  5. In the GitLab UI, in your merge request, confirm how many commits you want to rebase by viewing the Commits tab.

  6. Open these commits. For example, to edit the last five commits in your branch (HEAD~5), type: 

    git rebase -i HEAD~5

    Git opens the last five commits in your terminal text editor, oldest commit first. Each commit shows the action to take on it, the SHA, and the commit title: 

    pick 111111111111 Second round of structural revisions
pick 222222222222 Update inbound link to this changed page
pick 333333333333 Shifts from H4 to H3
pick 444444444444 Adds revisions from editorial
pick 555555555555 Revisions continue to build the concept part out

# Rebase 111111111111..222222222222 onto zzzzzzzzzzzz (5 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
  7. Switch to Vim’s edit mode by pressing i.
  8. Move to the second commit in the list by using your keyboard arrows.
  9. Change the word pick to squash or fixup (or s or f).
  10. Do the same for the remaining commits. Leave the first commit as pick.

  11. End edit mode, save, and quit:

    • Press ESC.
    • Type :wq.

  12. When squashing, Git outputs the commit message so you have a chance to edit it:

    • All lines starting with # are ignored and not included in the commit message. Everything else is included.
    • To leave it as-is, type :wq. To edit the commit message, switch to edit mode, edit the commit message, and save.

  13. Commit to the target branch.

    • If you didn’t push your commits to the target branch before rebasing, push your changes without a force push: 

      git push origin my-branch

    • If you pushed these commits already, use a force push: 

      git push origin my-branch --force-with-lease

Force pushing

Complex operations in Git require you to force an update to the remote branch. Operations like squashing commits, resetting a branch, or rebasing a branch rewrite the history of your branch. Git requires a forced update to help safeguard against these more destructive changes from happening accidentally.

Force pushing is not recommended on shared branches, because you risk destroying others’ changes.

If the branch you want to force push is protected, you can’t force push to it unless you either:

Then you can force push and protect it again.

Restore your backed up branch

Your branch is backed up, and you can try a rebase or a force push. If anything goes wrong, restore your branch from its backup:

  1. Make sure you’re in the correct branch: 

    git checkout my-branch

  2. Reset your branch against the backup: 

    git reset --hard my-branch-backup

Approving after rebase

If you rebase a branch, you’ve added commits. If your project is configured to prevent approvals by users who add commits, you can’t approve a merge request if you have rebased it.