Rebase method of merging code on Github

github-rebase-howto.md

Rebase method of merging code on Github

Your manager wants to use Rebase method to merge code on Github, so we can have a nice tidy single path history of commits on main, rather than branches coming out and merging back in (the Merge method).

If the team all agree to this, they should do it consistently. Here are some instructions which I hope are clear and simple. Feel free to reach out if anything is unclear or could be improved.

Rebase Strategy

With Rebase the workflow is somewhat simplified so that it results in a single centralized line of commits in history of main branch, though you may loose some of the advanced functionality that git offers. In order for it to work, you should be mindful of:

• Only work on your own branch, dont share branches or allow others to branch your branch. One way to avoid is not to make your branch public till done, though that is not essential if others in the team know to avoid branching branches.
• Rebase your feature branch often (even if you are not pushing or merging it into main yet) to avoid falling behind.
• SHA hashes of commits get changed on rebase - this will screw up any tools or commands that rely on it, including merge.

Simple rebase in Github

Sometimes you will be able easily to merge your approved PRs into the main branch using the nice green "Rebase and merge" button in Github, maybe resolving minor conflicts then committing within Github . However, you might want to resolve more complicated conflicts locally (e.g. within VS Code), and test them locally, before merging and closing the PR.

To resolve and test conflicts locally:

git pull
git checkout -b {your-feature-branch}
git merge origin/main

Now look in the Source Control tab in VS Code. You will see the merge conflicts. Open each one and resolve them, then click the + button to add each to the commit (mark as resolved). TEST your changes locally to make sure they work. Now git commit the merge. Then git push the changes on your-feature-branch. Now you should be able to go back into Github and hit that oh-so-satisfying green "Rebase and merge" button.

But what if that lovely green "Rebase and merge" button is grayed out? OMG what now??!

No need to panic. This probably means others have pushed to main since you originally branched off it, and now there are conflicts in one or more of your commits that need to be resolved. Here is the workflow to resolve manually:

1. Pull latest and make sure you are on your feature branch

git pull
git checkout -b {your-feature-branch}

2. Do a rebase onto main, which will actually re-write history of your branch by moving your-feature-branch so that it branches out from the top of main, allowing you to merge your feature changes onto the changes that others put in main since you originally branched. So start an interactive rebase:

git rebase -i origin/main

3. You will see a text editor allowing you to modify and save any messages or commits. Normally you would just leave as is and quit the editor.
4. Now git will attempt to rebase (i.e. move your-feature-branch on top of head). If it finds conflicts, it will exit and show a message.
5. Now look in the Source Control tab in VS Code. You will see the merge conflicts. Open each one and resolve and save them, then click the + button to add each to the commit (i.e. mark as resolved). Now git commit the merge.
6. Now continue the rebase.

git rebase --continue

• Go back to step 6 if there are more conflicts found. This might take some work to merge if there are a lot of conflicts, so be patient and account for this time in your planning. Try to test that each merge at least builds if you can, and its a good idea to reach out to others if you have trouble here.

7. Once the rebase succeeds and all conflicts are resolved, TEST your changes locally to make sure they work.
8. Once working, you can now push the new rebased branch. After this, Github will be able to easily merge your PR into main with one press of the of that magical green "Rebase and merge" button. But WAIT... If you do git push now, you might see an error message. The way around it is to force push, which sounds bad, but should in theory be safe if you are the only one working on your-feature-branch, like so:

git push origin {your-feature-branch} --force

9. Now you should be able to go back into Github and hit the "Rebase and merge" button for your PR!
10. Finally, once you are happy with everything being merged into main, delete your-feature-branch and move your ticket to DONE.