Rebase a merge request

Rebase to the same base branch

If commits have been made in the base repository since the time when the issue fork was created, you may need to rebase the issue fork in order to prepare it to be merged into the base repository. For example, the merge request is against Drupal core 9.4.x, but since it was made, 9.4.x has moved forwards.

There are two cases:

• Commits were made in different areas of the repository from the changes you made in your merge request, so there are no conflicts. In this case, unless you are a maintainer and are merging in the merge request, you do not need to rebase at this time.
• Commits were made that conflict with the changes you made in your merge request, which you'll know because either the merge request links in the issue are showing up as red with a merge error notice on them, or an automatic test failed with a "Not currently mergeable" message. In this case, you need to rebase and fix the merge conflicts now so that the merge can be done by a maintainer later.

To rebase a merge request using Gitlab, assuming you're already set up to commit to it as described above (Cloning and committing code to an issue fork):

1. Click the merge request link in the issue fork area. This will take you to the merge request overview page in GitLab. Below the Merge Request Pipeline and Code Quality information you should find branch information including how far behind the source branch is:
   
    
2. If the changes in the "x commits behind" do not conflict with anything in the MR then you can rebase via the UI. There is no 'rebase' button, but just enter a comment with the single word /rebase including the leading / and this will trigger a rebase.
3. If the above automated rebase is not possible you can resolve conflicts via the UI.

Alternatively, you can perform the rebase locally:

1. Fetch the changes from the base repository:
   git fetch origin
2. Make sure the base branch is up to date. For example, this might be 9.4.x on Drupal core.
   git checkout BASE_BRANCH_NAME
git pull
3. Return to the issue branch and run the rebase command to attempt to merge the changes from the base repository into the issue fork branch you are working in:
   git checkout ISSUE_BRANCH_NAME
git rebase BASE_BRANCH_NAME
4. If the command works, you are done. If you see error messages in the merge, resolve the merge conflicts as in the Dealing with merge conflicts section of the Rerolling patches page.
5. Push the changes to the repository.
   1. If you used the copy-paste commands at the top of the issue
      git push --force-with-lease drupal-ISSUE_NUMBER
   2. If you cloned the fork directly then
      git push --force-with-lease origin

Rebase to a new base branch

When main development branch that a merge request was made against is no longer current, the merge request's branch will need to be rebased from the the original base branch to the new branch.

For example, when the merge request was created, it might be against Drupal core's 9.4.x branch. Later on, this branch is no longer being developed, and the merge request must be rebased onto the 9.5.x branch.

1. First, follow the instructions above for rebasing a merge request to the same base branch. This making the issue branch up to date with the current base branch will help minimize rebase conflicts
2. Fetch the changes from the base repository:
   git fetch origin
3. Switch to the new target branch, e.g. 9.5.x:
   git switch NEW_BASE_BRANCH_NAME
4. Ensure this is up to date:
   git pull
5. Switch to the feature branch:
   git switch FEATURE_BRANCH

6. Determine the old base branch. This is not always the version that the issue is set to, as the feature branch may be quite out of date, and drupal.org issues have their version number automatically updated. The following may provide the branch name, in order of simplicity:

   • Look at the target branch of the merge request
   • Do a git log of the feature branch, and look for the first commit that has the issue fork remote's tip of a main branch. For example, '(drupal-3226806/9.3.x)'
   • Do a git log of the feature branch, and look for the first commit whose log message starts with an issue number, for example, 'Issue #3224478'. Note the SHA of this commit, and do git branch --contains COMMIT_SHA | sort -V. The lowest branch number in the list is probably the base branch.

7. Make a new feature branch. This is so that the old merge request remains on the old base branch, to allow work on a backport and for the benefit of users still on that version. It is a good idea to use a logical name such as a suffix based on the new base branch to keep the issue fork's branches easy to understand.

8. git switch -c NEW_FEATURE_BRANCH
9. Run the rebase command:
   git rebase --onto NEW_BASE_BRANCH_NAME OLD_BASE_BRANCH_NAME
   If you tried, for example, the command
   git rebase --onto 9.5.x 9.4.x
   and the old base branch does not have an upstream, you may get the error fatal: Needed a single revision. invalid upstream '9.4.x'. In this case add the upstream into the command:
   git rebase --onto 9.5.x drupal-ISSUE_NUMBER/9.4.x

   If the command works, you are done. If you see error messages in the merge, resolve the merge conflicts. If there are merge conflicts which are very complex, it may help to do the rebase in several steps, advancing one core minor version each time. For example, starting from base branch of 9.3.x, rebase first to 9.4.x, then to 9.5.x, then to 10.0.x, and so on.

10. Push the changes to the repository
    1. If you used the copy-paste commands at the top of the issue
       git push --force-with-lease drupal-ISSUE_NUMBER
    2. If you cloned the fork directly then
       git push --force-with-lease origin
11. Create a new MR with as its target the NEW_BASE_BRANCH_NAME, or edit the existing one:
    • If you created the MR or have commit access to the target repository, you can change it yourself. On the MR click Edit and then choose the new target branch.
      
      
    • If you don't have access to edit the MR, try to ping the creator of the MR. If they don't respond, create a new MR and try to copy over any open threads from the old MR to the new.