Git – A tale of changing code – Part 1
We have mentioned Source control before and touched a little on just how useful it can be. We also in this previous post said that we would try and issue a little tutorial. This is an attempt to do just that.
So… you want to learn more about git? Well, this is where I am going to heavily advise that you open an account with GitHub and Bitbucket if you like but we will be concentrating on GitHub. Now you don’t really need these but explaining how git works will be a lot easier if you do. In this tutorial, we will be using the command line all the way. There are apps out there (like SourceTree) and you can hook git right into most good code editors. I believe that by using the command line, you really begin to learn how it all works. It’s time to open your command line, along with a browser of choice and let’s tackle the first obstacle.
You have found a bit of open source software that you would like to contribute to. Maybe you have found a bug and want to fix it, maybe you want to add some functionality or suggest a breakdown of a large piece into smaller and more understandable components. The first thing you want to do is fork the repository. What this does behind the scenes is copy the code in its entirety to your account. This then means that you can change the code to your heart’s content without affecting the original. This is one of the very few things (as far as I am aware) that you cannot do from the command line. I could, of course, be very wrong about this even after years of using git I still learn things about it from time to time.
As an experiment, you can fork the GitHub repository called Spoon-Knife. It’s the repository that GitHub recommends you fork just to play with. Once that’s done we can move onto the next stage.
So congratulations on forking your first repository, it’s now time to download it onto your development machine. We do this so that we can actually begin to change things. Cloning is simple, each repository comes with its own address. You’ll see in GitHub that there is a clone or download button. Clicking this will give you an URL that you can copy into your buffer and then type into your command line it
git clone [url]
You should see something like this
Now you have some code you can change. Well done! But wait there is one more bit of advice I have for you before you go changing things.
So here we are ready to change the code, and you can do this but believe me as a piece of advice from a seasoned developer before you do that you’ll want to create a branch. Branches in git are where most of the usefulness is. Branches are something that you create and move to and from often. So what is a branch?
Think of the repository a bit like a tree. What you cloned was the master branch, or if you like the trunk. You create a branch again so that you have a point to return to should things go horribly wrong, or in fact, it could be a branch that you just want to experiment with to later on trash. Branches are not supposed to be permanent. At work, for instance, I will create a branch to add a new feature or a branch to fix a bug. The branch should only change one part or section of the code to make it easier for other people to understand.
So let’s take a go at changing something on our cloned code. Create a branch via the command line.
git checkout -b <name_of_your_branch>
So I’m going to add some information into the README file so here is my branch creation
You can see here that my terminal is giving me some helpful hints about what branch I am using. This is not a standard feature of git or indeed Macs. This is provided by OhMyZsh and maybe we will cover that in another post. Secretly what we actually just did was two commands in one. To do this in two commands we would have done the following
git branch <name_of_your_branch>
git checkout <name_of_your_branch>
Now I can go change the README.
You have changed something, now you’re ready to commit. Committing a file or multiple files is the way you register the changes with git. However, this does not mean that the changes are then going to show up in GitHub (that happens soon). In the real world, I try my hardest to stick to a little mantra with committing. I admit that when you are under pressure it is difficult but I always try.
- I must commit often
- I must commit small distinct changes.
- I must always provide a message with my commit.
- The message that I put with my commit should be meaningful
Let me break this down. If you commit often you will have more opportunities to turn back the clock should you change something so much that you break everything. Commit small distinct changes are a lot easier to remember what you did and why. The commit message will be a reminder to you, it will automatically list any file that you have changed plus any context that you wish to add to it. So let’s commit, first of all, we add any files that we changed then we commit the file with a message.
git add <file>
git commit -m "My meaningful note to myself or other developers"
Again I’m going to show you what mine looks like
So maybe you did one commit. Maybe you did many, you know it does not matter how many commits you have made, none of them has been synchronised with the remote server (GitHub). You do this so that you should your computer die you can download your changes on any machine that uses git. Also to submit your changes into the big wide world they generally need to be on the remote server. By putting them onto the remote server you also allow anyone who is interested in your project to also see your changes.
You don’t have to wait until you are complete with your changes to push them to the remote server. You can push as many times as you like, and if you want other people to have a view of what you’re doing this is a good way to do it. Right let’s push our branch to the remote server, once more head back to your command line
git push --set-upstream origin <name_of_your_branch>
Here is the sort of output that you might see
That’s it! Your code change and the branch is now available on GitHub. You can go and take a look at the branch and then compare it against either the original code, or your own personal copy of the master. Here, take a look at mine. From here I can create a pull request, and analyse all of my commits. In Part 2 of this tutorial, we will dive into these things a bit further and maybe merge our branch back in.
I hope this has made some sense. This kind of thing is incredibly hard to explain as a concept as to why you would do it. If you have any feedback for us then we would love to hear it. Get in touch with us using the comments section, Facebook or Twitter.