Suppose you were writing a three-stanza poem for a contest. The final product must be handwritten on fancy letterhead, in high-quality black pen. As multiple drafts go by, you finalize the first and the third stanza. You’re so confident in them that you write them on the letterhead in pen. But you’re stuck on the second stanza.
After some introspection and brainstorming, you finally come up with two potential second stanzas. But you can’t decide between the two! You decide that the best way to figure out which one you like is to write each one in the poem and see if it flows with the rest. You can’t just write one in the official poem (in pen!). What if the one you choose isn’t what you like? Then you have to rewrite the entire poem.
Instead, you decide to get out two pieces of scratch paper and write the poem in pencil and with a respective second stanza. That way you can hold them side-by-side and compare their flow. This method makes it easier for you to decide which of the two candidates you prefer. Once you have done so, you write the final stanza in pen on the letterhead and recycle the scratch paper with your drafts.
Believe it or not, this potentially unrealistic example is a great demonstration of what Git and Github call branches. Branches will be used extensively in the coming sections and chapters and are quite important to smoothing out your workflow.
Subsection3.3.1Thinking About Branches
Github organizes your edits and changes in a tree-like format. The official, published version of your files always lies on the main branch. You could think of the main branch as the trunk of a tree. When we created our README file back in Section 3.2, we started on the main branch, edited a file, and commited right back to the main branch. It was as if we wrote something new in pen on our official letterhead. See Figure 3.3.1.1 as a visualization of this type of commit.
Figure3.3.1.1.Diagram of a commit from main to main
This type of editing is usually discouraged. It is best practice to create a new branch, made some edits there, then submit a pull request to merge your changes into the main branch.
Whoa. I said a lot of stuff there. Lots of new words and things you don’t know how to do. Don’t worry, I’ll guide you through it in this section. When you get a new project, you want to try and break it up into pieces. Each piece will have its own branch on the Github tree. For instance, the two poems that you wrote on scratch paper above were two branches off of the official poem. They each had the same first and third stanzas; only their second stanzas differed. See Figure 3.3.1.2 for a visualization of branches in this instance.
Figure3.3.1.2.Diagram of two branches off of main
Notice how in Figure 3.3.1.2 that the main branch does not move forward when branches are created, it stops once a branch is made. When you first create a new branch, all you have is a copy of the main branch. However, when you edit your new branch, the changes do not appear into the main branch. Branches are like testing grounds. Try some new things, see if you like them, see if they work, then make it official. “Making it official” with Git and Github is called committing (as we have seen). Two new terms that go with commits 48 are merge and pull request. Oftentimes, you will hear people say that they just merged their changes into main. This means they committed their changes to the main branch and updated the official version. With the poem example, there are two possible merges you could make into main, as diagrammed in Figure 3.3.1.3.
Figure3.3.1.3.Diagram showing a possible merge into main
Figure3.3.1.4.Diagram showing another possible merge into main
You will also often hear about pull requests. Recall how GitHub allows anyone to edit anyone else’s code, but in order to change the official version, they have to ask for permission. The asking for permission is sending a pull request. You are asking the creator of the main branch their permission to pull in your changes. Don’t worry too much about this now; we will cover it when we get to multi-person collaboration. You will see the term come up in this chapter however which is why I chose to introduce it here.
Subsection3.3.2Creating a Branch
Creating a branch is not difficult. To do so, first make sure you are on the “Code” tab of your repository titled aboutme. Below the list of tabs, you should have a row of items. The first is a button with a branch-like icon with the word “main”. Next to that, there is the same branch-like icon with “1 branch” and then a tag-like icon with “0 tags” (Figure 3.3.2.1). 49 Now,
Click on the word “main”. This will open a drop-down menu with all of your current branches (Figure 3.3.2.1). You probably only have one branch: the main branch.
We will be adding a part to our README file: our favorite animal. Type animal in to the textbox that appears. Your cursor should navigate there automatically.
Since we don’t have a branch named animal, GitHub asks us if we want to create a new branch with that name. That is indeed what we want to do. Click on “Create branch: animal from ’main’”
Figure3.3.2.1.Reference for creating a new branch on GitHub
Once you have created the new branch animal, your screen will have changed slightly. The branch-like icon with the word “main” has changed to say “animal”. This is how you will know what branch you are looking at. Also notice how it says we have “2 branches”. We do: main and animal. Right underneath those items, you may also notice GitHub has placed a box stating that “This branch is up to date with main.”. This is what we should expect. This statement indicates that the main branch and the animal branch are identical (see Figure 3.3.2.2).
Figure3.3.2.2.Diagram mapping branches after creating the animal branch
A Few Notes on Branches.
Take caution when naming branches. You should follow the same guidelines the were discussed with file and folder names in Section 1.1.
Branch names should be extremely descriptive in the shortest way possible. It is wise to break up your project into distinct chunks and assign one branch for each chunk.
It is very easy to get lost within branches. You can create sub-branches off of normal branches. You can delete branches or ignore them. I advise only creating the branches you need at the current moment. If sub-branches (i.e., sub-tasks) are something you are interested in working with, I would recommend keeping a picture of the relationship between branches.
Once you are done with a branch, delete it. Otherwise, it will clog up your branch list. You can always create it again.
Subsection3.3.3Working On a Branch
We named the new branch animal to describe the changes we plan to make: add our favorite animal. Editing a file on a branch is no different than editing a file on main. However, we now have a safeguard. We can edit and commit as much as we want to the animal branch and never make any changes to main. Returning to the analogy at the beginning of the section, we no longer have to write in pen on fancy paper unless we are sure we want to change something.
Hopefully you are able to see the power in this. In a more serious project, commiting too early could have much bigger ramifications. Suppose I am coding a new character for a video game and the character has to use vulgar language. In a simple workflow, I would create a branch called vulgar or new_npc with a sub-branch of language. Then, I would incorporate my code on my branches. Once that was done, I would run my code to test that it worked. Then I would submit a pull request, requesting my boss to pull in my new changes into the official version of the game. They would likely take a look at my code and try it themselves before accepting the changes. But let’s say I forgot to add in the censorship beep over the language. If I had just merged right into main, my mistake may have been missed and I could get in serious trouble. But since I worked on a branch, my forgetfulness can be caught before the changes get incorporated and there won’t be any flustering to quickly revert changes or fix the error.
Checkpoint3.3.3.1.Editing a File On a Branch.
You should already have a README file in your repo from the activities in Editing a File. Now, head back to the file to edit it and add a level two heading called “My Favorite Animal”. Underneath that, type your favorite animal. Do not commit yet.
The current state of the branch is shown in Figure 3.3.3.2.
Figure3.3.3.2.Diagram showing branches after add a favorite animal
After you have made some changes, head to the “Commit changes” dialog (top right). Now, it is time to introduce commit messages. A commit message is a short, but informative (notice a recurring pattern?) note of what your changes do. You may be tempted to skip this when working with yourself. Please try to write the best commit messages at all times. When you look back at your repo in the future, it will be helpful for you to remember what you did. Commit messages also help others who may look at your project know what you did in each commit. You may see my various branch names and commit messages at the commit list for this book on GitHub 50 .
Let’s create a commit message for our changes on the animal branch. In the “Commit changes” dialog, there is a text box that is autofilled with “Update README.md”. This is the default and for some instances may be enough. But I have the tendency to write slightly more detailed messages for my commits and I recommend you do so as well. Instead, type “add favorite animal”. There is no need to add the file name as this message will only be tied to the file(s) you have edited. (Later on, we will see that specific commit messages are only associated with the files you have staged and committed but that’s a topic for Chapter 4.)
A Note On Commit Messages.
It is up to you how to format your message. Some people write in complete sentences while others use incomplete sentences with capital letters. Some people use past tense, others present tense, and even others use present participles (adding). I choose to use present tense with incomplete sentences and lowercase letters. But that’s my preference. You should find what you like and stick with it.
…Except when you’re editing someone else’s files. In this case, pay attention to how someone else words their commit messages and imitate them. This will make life easier for the owner of the files and for anyone else who looks at the files in the future. You may even find that your commit message is changed by the owner of a repository to match their guidelines.
It is not necessary to fill out the description text box (feel free to do so if you would like!). Ensure the “Commit directly to the animal branch.” is selected, then click “Commit changes”.Your file should be updated! Just remember, you have only updated the copy of the file on the animal branch, not main.
Navigate back to the code tab to continue. Make sure you are still on the animal branch. You can verify this by looking at the drop-down menu text or by checking the contents of your README file (if your favorite animal is there, you are on the animal branch).
Figure3.3.3.3.Diagram showing our commit from animal to animal
Subsection3.3.4Creating a Pull Request (with Yourself)
Alright, so you’ve edited a file on a branch AND you are happy with your changes. Everything looks good and works well on the branch so you are ready to incorporate your changes into the official version of your project. This is called creating a pull request. It may sound odd to call it a pull request when it seems like you are actually pushing your changes toward the main branch. However, in cases where you don’t have permission to access the main branch of another repo, so you have to request that someone pull your changes into the main branch.
I admit, it is silly to have to work with pull requests when working solo. Why would I need to ask myself permission to pull in my own changes? But pull requests are essential when working with multiple collaborators and I recommend using branches and pull requests in your own individual work for practice, good habits, and safeguards against code failures.
Pull requests are only necessary when using branches (recall how when we edited the README file directly from the main branch we had no pull requests). We are currently in a situation that would require a pull request. How do we create one? First notice (on your GitHub repository for the animal branch) how a new message has appeared. This probably says
This branch is 1 commit ahead of main.
Text on dialog box saying “This branch is 1 commit ahead of main.”
Figure3.3.4.1.The GitHub commits summary box
... as seen in Figure 3.3.4.1. This is GitHub’s way of telling you that the branch you are currently on has changes that are not reflected on the main branch. Specifically, we have committed one time and the changes from that single commit do not appear on main. We could go and edit the README file some more and commit those changes. In that case, we would be 2 commits ahead of main.
The dialog box that contains this message also has another feature: a “Contribute” option (Figure 3.3.4.2). If you click on this option, a box pops up telling us again that we are 1 commit ahead of main. Here, there is a button inviting us to “Open pull request”. Click on this.
The box found after clicking on "Contribute". Text says “This branch is 1 commit ahead of main. Open a pull request to contributue your changes upstream”
Figure3.3.4.2.The contribute dialog box.
There is a lot on this page but most of it will be dealt with later. For right now, notice that GitHub tells us which branch we are trying to send to main at the top. animal should be on the right and is pointing towards main (see Figure 3.3.4.3). Next to this, you should see a check mark and an “Able to merge” message. This is good; see Section C.7 if your branches cannot be automatically merged.
Figure3.3.4.3.Branch selection drop-down menus and able to merge confirmation.
Your cursor should have automatically navigated to a dialog box. This has defaulted to our latest commit message. You should make sure that you have put an informative message on what your pull request accomplishes as a whole. Remember, it is possible to have multiple commits before opening a pull request so you could have adjusted a few things. For us, “add favorite animal” is sufficient and we can open the pull request. Click on the “Create pull request” button.
Nice, another new screen. This time notice how we have changed tabs. We are now in the “Pull requests” area (and not the Code tab), which should make sense. The pull requests page is for more than just accpeting pull requests. If someone else has contributed to your repo and has opened a pull request, you can start a conversation here. Suppose you have a question about someone’s changes or think they should improve their addition before you approve it. You can say that here.
But we have no problems with ourselves. Our pull request has been created and is waiting for permission to be pulled into main. In some instances, you will have to wait for a repo owner to accept your pull request. However, you are the repo owner and can merge the changes yourself. You can do this on the current screen. Find the “Merge pull request” button (Figure 3.3.4.4). GitHub will give you the chance to edit the message if necessary. Since we have no changes to make, click on “Confirm merge”.
Figure3.3.4.4.The merge pull request dialog box.
Hopefully you were given the “Pull request successfully merged and closed” message. From here, click on “Delete branch”. You should have no fear about deleting the branch at this point. Your changes will not be lost because you just incorporated them into main. You now have two identical copies of the same files and can get rid of the extraneous copy: your old branch. If it makes you feel better, GitHub keeps track of commits and merges. If you ever want to revert back to an old version, you can in Section C.6. For now, go back to the “Code” tab and verify that your favorite animal appears in the README in the main branch.
Figure3.3.4.5.Diagram showing a pull request from animal to main
Checkpoint3.3.4.6.Branches and Pull Requests.
It is time to put together what you learned in this section and make some edits of your own. Don’t be afraid to look back at what we did earlier for reassurance. Start this exercise on the “Code” tab of your aboutme repo. The goal of this exercise is to add another section to the README file by creating a branch, making edits, and opening a pull request.
(a)
Think about something about you that you have not put in the README yet. Perhaps your favorite food, quote, or historical character. Once you have chosen what you want to add, create a branch with an appropriate name.
(b)
Edit your README file. You should have at the very least a new level two heading indicating what you are adding and a piece of text with your addition.
(c)
Add an approporiate commit message and commit your changes to your new branch.
(d)
Open a pull request to merge your changes into the main branch.
(e)
Merge your new pull request into main and delete your old branch.
(f)
Verify that your change did in fact get merged into main.
Congratulations! Hopefully you have a better understanding of how branches and pull requests work in GitHub (and their potential).
