Git Workflow with Rebase
Objectives
- Run over the concept of using a git rebase based workflow instead of git merge.
- Offer troubleshooting for merge conflicts that will inevitably come up.
- Save you from tearing your your hair out. <--Highly important.
- Note: this tutorial assumes working understanding of GitHub repositories and terminal command.
(Photo courtesy of http://git.mikeward.org/img/merge-rebase.png)
Introduction
Hello, this article is primarily for my LightCante team, but feel free to use this guide for your rebase needs. It covers the git/browser commands from the initial fork of a project to the pull request of you changes. Please note that this process is in BETA use. I claim no responsibility for lost hair.
Why rebase? Simplest reason is so that your commit history doesn't become crowded with a bunch of merge commits. When a rebase is run, it rewrites the project history by taking the old commits and incorporating them with the new rebased master. <--Don't worry about that too much. Just know that you're not adding a commit whenever you rebase(merge).
As I say to the barber, "Keep it clean."
Instruction
During this directions listed here, the heading in bold will inform you of where you are (Organization repo, personal repo, or local machine).
-->Organization Repo
Form the repo over from your organization at github.com/yourorganization/reponame to your own @username repositories.
-->Personal Repo
Copy the URL to clone down the repo. It'll be something like https://github.com/username/reponame.
-->Local Machine
In your terminal and directory of choice, run git clone https://github.com/username/reponame This copies the directory onto your machine.
Next, you'll need to create an upstream to the organization. Accomplish this with git remote add upstream https://github.com/yourorganization/reponame With this, you've set up the connection between your development repo on your machine and the production repo on your organization's Github page. Notice that there have been no rebase commands thus far. Thumbs check?? Ok, let's move on.
At this point, your local machine repo may only have a master branch. You do NOT want to work from here. Instead, for every feature that you want to have for your project, create a new branch via command git checkout -b feat/branchName. The "-b" allows for the creation of a new branch. Also, my particular workflow involves the use of naming the branch "feat/branchName" as it involves a feature. (Warning: only create new branches when you are on your master branch or you're gonna have a bad time).
As you're on the feature branch, perform your usual git add and git commit commands as you modify your code. Commit often and name them well. How you name them, that's on you, mate.
And now, it's rebase time!! (Make sure everything's all good and committed).
Before you push your material up to your own repo, you must first pull down the most recent version of the upstream master. Remember that the "upstream" refers to your organization's repo. You do this with git pull --rebase upstream master. Allow me to describe what happens at this point: Your terminal grabs the most up-to-date version of your organization's repo. It then pulls it down to your machine and merges all of your commits to it. In essence, after taking in all of the commits you have made, it overwrites all of your files. It also re-writes all of your old commits.
At this point, you may hit a conflit or two (or three or four). Some, you will be able to fix on the spot. For others, please refer to troubleshooting below ↓ for further info on what to do at this stage.
Time to push. Run git push origin feat/branchName. This will push the work that you've done on that branch to your repo.
-->Personal Repo
Perform a pull request from your personal github repository at https://github.com/username/reponame. Add whatever comments you want.
-->Organization Repo
Merge the repo as you see fit. Be merciful.
Troubleshooting
You hit a rebase conflict that you cannot rectify. Fear not, you can perform the following command: git rebase --abort. This will cancel the rebase process. Do understand that any merge conflict resolutions that you've fixed during this git pull --rebase upstream master command will be deleted. However, all the work you've added/committed up to this point will be safe. Go into the area where the error was happening. Check to see if you've made too drastic a change for a single commit.
Occasionally, you will hit this weird phenomenon when you run git push origin feat/branchName to push your feature branch to your personal online repo. Your feature branch on your machine is in conflict with the feature branch on your personal online repo. Run git push origin :feat/branchName. The ":" causes the feat/branchName to be deleted from your online repository. Then run git push origin feat/branchName and it should push up just fine. Then do your usual pull request, etc etc.
That's it. Thanks for reading!