Intro To Source Control Part 2

In part 2 of our source control tutorial, you’ll learn how to work on different versions of a repository at one time, and methods for working with others on the same project.

At this point you know how to create a repository, commit changes locally, and push those edits to your github account. If you haven’t read part 1, check it out now and then come back. Now we’ll take it a set further and learn some more advanced techniques that will let us experiment with our code and allow more than one person to work on the project at the same time. In order to do this, we’ll play a version of Exquisite Corpse.

Learning goals

Working with branches.

By default repositories on github have a main version of your code named master which is considered to be the definitive working version of your code. In industry terms this code would be considered your playable prototype and should work at all times (you never know when someone might want to try out your game). Now, let’s say you would like to add a feature to the game. Well, adding a feature usually requires major changes to your code which makes the code unusable until you finish. If the feature is experimental or if you’re not quite sure how to add that feature, your code might remain unusable for quite a while. Even well thought-out features might have bugs that will cause your game to break in new and interesting ways. So, rather than editing the code we know already works we’ll edit a copy of our codebase called a branch leaving our working codebase alone.

Let’s go back to the repository we made in part 1 and add some information to it. First, open the README.md file where we’ll add the rules to our game.

README.md

Exquisite Corpse

Exquisite corpse is a method by which a collection of words or images is collectively assembled. 
Exquisite corpse is meant to be played with multiple people with each collaborator contributing 
to a story, picture, or other work.

Rules:
1)	Any coder who would like to play this game must first make a branch or fork of the current state of
	the game.
2)	Do not read story.txt until your have made your contribution.
3)	Open nextLine.txt, read the sentence, and then continue the story by adding another 
	sentence below it.
4)	Take the sentence that was in nextLine.txt (not the one your wrote) delete it from nextLine.txt
	and add it to the end of story.txt. nextLine.txt should now only have the sentence you just added.
5)	Read story.txt so far.
6)	Submit a pull request for this repository.

Once you’ve copied and pasted this into your README.md open your nextLine.txt and add a short sentence to start your story. Here we’ll use “Once upon a time, there was a coder who was learning GIT.” as an example.

nextLine.txt

"Once upon a time, there was a coder who was learning GIT."

Open the github desktop app and commit these changes to your local repository. Finally push these commits to master. For a reminder on how to do this check out part 1.

Making your first branch

Now that we know why a branch is useful, let's make one. In your github account make a new branch by clicking on the branch menu and typing in a name for your branch. Once you've created a name for your branch, you should have the option to "Create branch from master". The screen should ook something like this:

Now go back to your exquisite corpse repo and follow the game's rules to add another line to the story. In this example we will add the sentence "By using git they were able to code things quicker, and more efficiently, than ever before." to nextLine.txt, but feel free to add any sentence to your own story. When you're done, move the previous sentence "Once upon a time, there was a coder who was learning GIT." to story.txt. Save your work and open the github desktop app. Like the previous tutorial, should now see the edits you made to the two files tracked and color coded. Before we commit, let's select the branch that we would like to commit to by clicking on the "current branch" menu and selecting the branch we made above. Commit your current changes and then push the changes to your account.

Congratulations! You just created a new branch and committed some changes to it!
Why is this powerful? Well, two things.

• First it means that the changes we made to our code isn't part of the master branch. This is a good because as we make more complex things we won't have to worry that the code in our master repository doesn't work while freeing us up to experiment with our code as much as we like.


• Second, we can switch from branch to branch whenever we like and the code on our local repo will change accordingly. Give it a try by going to the github desktop app and selecting the master branch. When you open the file nextLine.txt you should see the original sentence that we just move to story.txt and story.txt should be empty. MAGIC!

Branches are a powerful part of git and allows for multiple parts of the project to be worked on concurrently. This is especially helpful if you have two different coders working on two sperate parts of your game. As long as they each have their own branch, they should be able to work on the project at the same time without conflicts. Branches are great! Use them!

Now what happens when we want those changes to be part of our master repo?

Pull requests and merging

If you go back to the github site for your repository you’ll notice a few new options. While the main page for your repo will display the code to your master branch you can also view the current state of any other branch that was pushed to github. You will also notice a button labeled “compare & pull request”, click it to merge our “story edits” branch with our master branch.

The next screen will compare the code in our current branch with the code in the master branch and will allow us to decide what changes to the code we’d like to keep, and which we want to ignore, through a process called merging. Because our changes are small, Github will merge our code automatically, but bigger changes will require us to merge the code ourselves. While merging, keep in mind that your master branch will be the currently working codebase, so only accept changes to the code that you know will work.

Once we’re done merging, we’re ready to submit our first pull request. A pull request is a bit like a commit, but instead of committing code changes to it’s own branch, it attempts to submit those changes to another branch. Like a commit, we’ll give our pull request a short descriptive title that highlights the important changes while using the comment area to go into more detail. Once you’re done, click on create pull request.

Great job! You’ve successfully merged and submitted a pull request, but we’re not done yet. As a safeguard, pull requests aren’t automatically accepted, but must be approved by the owners of the repository. Go back to the repository’s github page and you’ll see a notification that you have a pull request.

Clicking on the notification will show you all the pull requests made so far. Because we’re the only people working on this repo we should see only one pull request. Click on the pull request we just created to bring up the pull request menu. In this menu we’ll be given an overview of the pull request including the changes to the code, plus the title and description we created above. We will also be given a choice to merge the pull, leave a comment (if we want to provide feedback), or close the pull request (if we do not want to accept the pull request). The drop down menu for the merge pull request button also gives us different ways to merge (merge, squash, and rebase) but aren’t needed for this tutorial. For now, just click on merge pull request.

Once you’ve successfully merged, you’ll be given the option to delete the branch you’ve been working with. Since the branch we were working on has served it’s purpose, we can safely delete it. Similarly, if this branch was created to add a feature to our game we would deleted the branch after the feature had been fully implemented and all changes had been merged to our master branch.

Conclusion

Congrats! You now know the basics of branching, and pull requests! I have no doubt these skills will serve you well in the future.

Want some further reading? Merging vs Rebasing Git tutorial by github

Contact us!

Follow @vgworkshop