Learn to love Git. Part three: collaboration.
In part two, we learned how to tell Git to track files and how to commit work to the projects history. Now I’ll walk you through a few slightly more advanced concepts that will be the building blocks of how you can use Git to work with others.
The workflow I’ll be showing you here is a single-player version of the very common feature branch workflow.
Branching
The first concept you’ll want to understand here is “branching.”
Branching is a way to separate different streams of your work into distinct, yet related, work spaces. Each branch you create is sort of like a copy of your primary work area with a new staging area, a new project history and new commits. Whatever work you do in this new area is separated and recorded in relation to the branch you’re working on only. This allows you and others you’re working with to work from the same codebase, on the same project, while keeping in sync and out of each other’s way.
It’s a bit hard to grasp at first, but you’re always working on a branch. The changes you just made were made in the “master” branch. You can see this if you run:
git status
There’s a line that reads “On branch master.” This tells you which branch you’re working on.
As you might expect, if I were to be working on the same project as you and we were both working in that branch, we could very likely run into some issues — some conflicts.
The solution is to work on separate branches off this main “master” branch. This is also helpful when working on your own. Branches allow you to give some context or scope to your work, while also keeping any changes you’re making in separate work efforts from conflicting with each other.
Here’s how it works. Open up Terminal and type:
git branch my-new-recipe
This creates a new branch called “my-new-recipe” — it’s important to note that all this does is create a new reference to any commits you do in that branch. It doesn’t actually change the repo.
It’s generally a good practice to name your branch after the work you’re doing on it. As an aside: many development teams will use a branch naming convention that includes references to the issue tracking tools they use, to help automate and/or better keep track of work being done.
Now that you’ve got the branch created, you’ll need to let Git know you’re going to do some work on it. Right now you’ve simply created a new branch, but you’re still working on the “master” branch. So we need to switch branches.
To do that, we’ll use the “git checkout” command.
git checkout my-new-recipe
You should see a success message letting you know you’ve switched branches. Any work you do now will be done on “my-new-recipe” as opposed to “master.” If you make changes now, and then run “git checkout master” (to switch back to the master branch), you wouldn’t see those changes reflected in your repo. In this way you can use branches to isolate your work.
Now that you’ve got a new branch, try testing what you’ve learned to add and commit another recipe.
Once that’s done, come on back and we’ll talk about how to “merge your branch with master” — essentially taking all the work you’ve done and placing it back into the master branch.
Merging
Merging (using the “git merge” command) is, at its heart, a fairly straightforward process. But, it can get pretty dicey if things go wrong or if you’re trying to deal with multiple branches with work streams going on simultaneously.
You most often want to merge the commits on your branch once you’ve fully finished with the work you’d slated for that new branch. In our case, adding a new recipe. There will be other times you might want to merge, too. Say if you hit a good break point, for example, or so many things have happened on your main project that you want to make sure you’re up to date.
So, you’ve added and committed a new recipe to your “my-new-recipe” branch and now it’s time to merge. Here’s how it works.
When you do a “git merge,” you’re taking one branch (“my-new-recipe”) and merging it into another (“master”). To do that, you first need to switch back to “master” and, if you’re working with remote repositories (which you usually will be), make sure it’s all up to date. In this particular case you’re the only one working on the project, but if there were others they would have likely made their own changes and pushed them up to your shared remote repo. Open Terminal and type:
git checkout master
git pull origin master
Now you’re on “master” and it’s been synced with your remote repo. You can now merge your changes on “my-new-recipe” into “master.” In this case it’s simple:
git merge my-new-recipe
Assuming all goes well, you should get a nice message telling you that your work has been merged.
The next thing to do is clean things up by deleting your feature branch. This is optional, but a nice practice. In Terminal type:
git branch -d my-new-recipe
That deletes the branch and you’ve now got a pristine local repo. All that’s left is to sync back with your remote (i.e. push the changes your merge action has made to the master branch on your local repository to the remote repository):
git push origin master
Assuming you don’t run into conflicts you’ll now have made a change in your branch, merged it in locally and then pushed the update to your remote repo.
Congrats! You’ve learned the basics of Git and the essentials of the feature branch workflow. While this is a great start, and can help you move forward, it doesn’t really simulate what it’s like to work on a team, or on an open source project with others. And that’s where Git gets really powerful.
For that, we’ll need to dive into one of the best and most powerful features you can get working with Git: pull requests. While not technically a Git feature, pull requests provide you with some really amazing ways to collaborate with others and get them to review your code.
Watch this space for a follow up where I’ll cover how to work with pull requests. If you’re hungry for knowledge and just can’t wait, you can refer to Atlassian’s documentation on pull requests and give it a shot by taking what you’ve learned here, forking The Mason Jar’s primary and public repo and adding some yummy recipes. I’ll be looking forward to your pull requests!
Did you enjoy this post? Want more of the same? Consider following Designing Atlassian.