Git rebase and force push

This guide helps you to get started with rebases, force pushes, and fixing merge conflicts locally. Before you attempt a force push or a rebase, make sure you are familiar with Git through the command line.

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. In these cases, instead of rebasing your branch against the default branch, consider pulling it instead (git pull origin master). Pulling has similar effects with less risk compromising the work of your contributors.

In Git, a rebase updates your feature branch with the contents of another branch. This step is important for Git-based development strategies. Use a rebase to confirm that your branch’s changes don’t conflict with any changes added to your target branch after you created your feature branch.

When you rebase:

  1. Git imports all the commits submitted to your target branch after you initially created your feature branch from it.
  2. Git stacks the commits you have in your feature 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.

Back up a branch before rebase

To back up a branch before taking any destructive action, like a rebase or force push:

  1. Open your feature branch in the terminal: git checkout my-feature
  2. Check out a new branch from it: git checkout -b my-feature-backup Any changes added to my-feature after this point are lost if you restore from the backup branch.
  3. Change back to your original branch: git checkout my-feature

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 (my-feature): git checkout my-feature
  2. Reset it against my-feature-backup: git reset --hard my-feature-backup

Rebase a branch

Rebases are very common operations in Git, and have these options:

  • Regular rebases. This type of rebase can be done through the command line and the GitLab UI.
  • Interactive rebases give more flexibility by enabling you to specify how to handle each commit. Interactive rebases must be done on the command line.

Any user who rebases a branch is treated as having added commits to that branch. If a project is configured to prevent approvals by users who add commits, a user who rebases a branch cannot also approve its merge request.

Regular rebase

Standard rebases replay the previous commits on a branch without changes, stopping only if merge conflicts occur.

Prerequisites:

  • You must have permission to force push branches.

To update your branch my-feature with recent changes from your default branch (here, using main):

  1. Fetch the latest changes from main: git fetch origin main
  2. Check out your feature branch: git checkout my-feature
  3. Rebase it against main: git rebase origin/main
  4. Force push to your branch.

If there are merge conflicts, Git prompts you to fix them before continuing the rebase.

From the GitLab UI

The /rebase quick action rebases your feature branch directly from its merge request if all of these conditions are met:

  • No merge conflicts exist for your feature branch.
  • You have 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 feature branch against the default branch and executes it as soon as possible.

Interactive rebase

Use an interactive rebase (the --interactive flag, or -i) to simultaneously update a branch while you modify how its commits are handled. For example, to edit the last five commits in your branch (HEAD~5), run: 

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

After the list of commits, a commented-out section shows some common actions you can take on a commit:

  • Pick a commit to use it with no changes. The default option.
  • Reword a commit message.
  • Edit a commit to use it, but pause the rebase to amend (add changes to) it.
  • Squash multiple commits together to simplify the commit history of your feature branch.

Replace the keyword pick according to the operation you want to perform in each commit. To do so, edit the commits in your terminal’s text editor.

For example, with Vim as the text editor in a macOS Zsh shell, you can squash or fixup (combine) all of the commits together:

note
The steps for editing through the command line can be slightly different depending on your operating system and the shell you use.
  1. Press i on your keyboard to switch to Vim’s editing mode.
  2. Use your keyboard arrows to edit the second commit keyword from pick to squash or fixup (or s or f). Do the same to the remaining commits. Leave the first commit unchanged (pick) as we want to squash all other commits into it.
  3. Press Escape to leave the editing mode.
  4. Type :wq to “write” (save) and “quit”.
  5. 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 it is, type :wq. To edit the commit message: switch to the editing mode, edit the commit message, and save it as you just did.
  6. If you haven’t pushed your commits to the remote branch before rebasing, push your changes without a force push. If you had pushed these commits already, force push instead.

Configure squash options for a project

Keeping the default branch commit history clean doesn’t require you to manually squash all your commits on each merge request. GitLab provides squash and merge, options at a project level.

Force push

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, as you risk destroying the changes of others.

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.

--force-with-lease flag

The --force-with-lease flag force pushes. Because it preserves any new commits added to the remote branch by other people, it is safer than --force: 

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

--force flag

The --force flag forces pushes, but does not preserve any new commits added to the remote branch by other people. To use this method, pass the flag --force or -f to the push command: 

git push --force origin my-feature