9.6 KiB
stage | group | info | type | description |
---|---|---|---|---|
Create | Source Code | To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments | concepts, howto | Introduction to Git rebase, force-push, and resolving merge conflicts through the command line. |
Introduction to Git rebase, force-push, and merge conflicts
This guide helps you to get started with rebasing, force-pushing, and fixing merge conflicts locally.
Before diving into this document, make sure you are familiar with using Git through the command line.
Git rebase
Rebasing is a very common operation in Git. There are the following rebase options:
Before rebasing
WARNING:
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
). It has a similar
effect without compromising the work of your contributors.
It's safer to back up your branch before rebasing to make sure you don't lose
any changes. For example, consider a feature branch
called my-feature-branch
:
-
Open your feature branch in the terminal:
git checkout my-feature-branch
-
Checkout a new branch from it:
git checkout -b my-feature-branch-backup
-
Go back to your original branch:
git checkout my-feature-branch
Now you can safely rebase it. If anything goes wrong, you can recover your
changes by resetting my-feature-branch
against my-feature-branch-backup
:
-
Make sure you're in the correct branch (
my-feature-branch
):git checkout my-feature-branch
-
Reset it against
my-feature-branch-backup
:git reset --hard my-feature-branch-backup
Note that if you added changes to my-feature-branch
after creating the backup branch,
you lose them when resetting.
Regular rebase
With a regular rebase you can update your feature branch with the default branch (or any other branch). This is an important step for Git-based development strategies. You can ensure that the changes you're adding to the codebase do not break any existing changes added to the target branch after you created your feature branch.
For example, to update your branch my-feature-branch
with master
:
-
Fetch the latest changes from
master
:git fetch origin master
-
Checkout your feature branch:
git checkout my-feature-branch
-
Rebase it against
master
:git rebase origin/master
-
Force-push to your branch.
When you rebase:
- Git imports all the commits submitted to
master
after the moment you created your feature branch until the present moment. - Git puts the commits you have in your feature branch on top of all
the commits imported from
master
:
You can replace master
with any other branch you want to rebase against, for
example, release-10-3
. You can also replace origin
with other remote
repositories, for example, upstream
. To check what remotes you have linked to your local
repository, you can run git remote -v
.
If there are merge conflicts, Git prompts you to fix them before continuing the rebase.
To learn more, check Git's documentation on rebasing and rebasing strategies.
Interactive rebase
You can use interactive rebase to modify commits. For example, amend a commit message, squash (join multiple commits into one), edit, or delete commits. Use a rebase for changing past commit messages, and organizing the commit history of your branch to keep it clean.
NOTE: If you want to keep the default branch commit history clean, you don't need to manually squash all your commits before merging every merge request. With Squash and Merge, GitLab does it automatically.
When you want to change anything in recent commits, use interactive
rebase by passing the flag --interactive
(or -i
) to the rebase command.
For example, if you want to edit the last three commits in your branch
(HEAD~3
), run:
git rebase -i HEAD~3
Git opens the last three commits in your terminal text editor and describes
all the interactive rebase options you can use. The default option is pick
,
which maintains the commit unchanged. Replace the keyword pick
according to
the operation you want to perform in each commit. To do so, you need to edit
the commits in your terminal's text editor.
For example, if you're using Vim as the text editor in
a macOS's ZSH
shell, and you want to squash all the three commits
(join them into one):
- Press i on your keyboard to switch to Vim's editing mode.
- Navigate with your keyboard arrows to edit the second commit keyword
from
pick
tosquash
(ors
). Do the same to the third commit. The first commit should be left unchanged (pick
) as we want to squash the second and third into the first. - Press Escape to leave the editing mode.
- Type
:wq
to "write" (save) and "quit". - 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.
- All lines starting with
- If you haven't pushed your commits to the remote branch before rebasing, push your changes normally. If you had pushed these commits already, force-push instead.
Note that the steps for editing through the command line can be slightly different depending on your operating system and the shell you're using.
See Numerous undo possibilities in Git for a deeper look into interactive rebase.
Force-push
When you perform more complex operations, for example, squash commits, reset or
rebase your branch, you must force an update to the remote branch.
These operations imply rewriting the commit history of the branch.
To force an update, pass the flag --force
or -f
to the push
command. For
example:
git push --force origin my-feature-branch
Forcing an update is not recommended when you're working on shared branches.
Alternatively, you can pass the flag --force-with-lease
instead. It is safer, as it does not overwrite any work on the remote
branch if more commits were added to the remote branch by someone else:
git push --force-with-lease origin my-feature-branch
If the branch you want to force-push is protected, you can't force-push to it unless you unprotect it first. Then you can force-push and re-protect it.
Merge conflicts
As Git is based on comparing versions of a file line-by-line, whenever a line changed in your branch coincides with the same line changed in the target branch (after the moment you created your feature branch from it), Git identifies these changes as a merge conflict. To fix it, you need to choose which version of that line you want to keep.
Most conflicts can be resolved through the GitLab UI.
For more complex cases, there are various methods for resolving them. There are also Git GUI apps that can help by visualizing the differences.
To fix conflicts locally, you can use the following method:
-
Open the terminal and checkout your feature branch, for example,
my-feature-branch
:git checkout my-feature-branch
-
Rebase your branch against the target branch so Git prompts you with the conflicts:
git rebase origin/master
-
Open the conflicting file in a code editor of your preference.
-
Look for the conflict block:
- It begins with the marker:
<<<<<<< HEAD
. - Below, there is the content with your changes.
- The marker:
=======
indicates the end of your changes. - Below, there's the content of the latest changes in the target branch.
- The marker
>>>>>>>
indicates the end of the conflict.
- It begins with the marker:
-
Edit the file: choose which version (before or after
=======
) you want to keep, and then delete the portion of the content you don't want in the file. -
Delete the markers.
-
Save the file.
-
Repeat the process if there are other conflicting files.
-
Stage your changes:
git add .
-
Commit your changes:
git commit -m "Fix merge conflicts"
-
Continue rebasing:
git rebase --continue
WARNING: Up to this point, you can run
git rebase --abort
to stop the process. Git aborts the rebase and rolls back the branch to the state you had before runninggit rebase
. After you rungit rebase --continue
the rebase cannot be aborted. -
Force-push to your remote branch.