Git-fu: How to avoid pulling a muscle while making pull requests

Even if you’re still new to coding, you’ve probably heard people talk about making pull requests. Maybe it was just a passing conversion:

You: That link is broken.
Someone: Just make a pull request.

Depending on your level of Git-Fu, you might be left wondering: “what the heck is a pull request?”

What is a pull request

Simply put, a pull request is what you do when you want to edit code in a repository that you do not have access to. For example, there are many open source projects where you can view the code, but since you are not a collaborator you cannot directly commit any code changes. So if you notice a problem, e.g. a broken path or an obscure error message, you cannot change it.

To make the changes, you submit what is called a pull request. The TL;DR version is that you are effectively checking out the code, editing it, and then submitting it for review rather than committing it directly to the project’s repository. The project collaborators can then review the suggested edits and choose whether or not to merge the code.

Making your edits

Since the whole point of a pull request is to touch code that isn’t yours, you have to fork the repository. Forking the repository puts a copy of the code in your repository

1. Fork the repository by clicking the fork button:
   
2. Clone your forked repository: git clone <forked project path>
3. Checkout a new branch: git checkout -b newBranch
4. Do an initial commit before making your changes: git push origin newBranch
5. Make your edits
6. Run git diff to make sure there were additional edits you did not intend
7. Add, commit, and push your edits to your branch. If you do not want to add all the files, you can add individual files with git add <file name>. Remember, to push the updates to your branch use git push origin newBranch.

As a side note for git diff, occasionally you may find that more code edits occurred than you intended to make. As an easy example, you may have a linting/formatting plugin installed for your text editor. If the plugin “cleans up” the code in a way you did not expect, the only way you would easily see these edits is by running git diff. Depending on the circumstances of your pull request, or how familiar you are with the project in general, you may or may not want to keep these edits.

Creating the pull request

Go back to the main project page – not your forked repository/branch. When you go to create your pull request on GitHub, the software should actually detect that you forked the project and prompt you to “Compare & pull request”:

Here you can see that it pulled the correct branch from my forked repository. If you don’t see this dialog box, do the following:

1. Click “Pull Requests” on the left nav bar:
   
2. Click big, green “New pull request” button:
   
3. Select the correct branch(es) from the drop down menus:
   

Regardless of which method you choose, once you have reached this step you can see your last commit message and an option to add additional details:

Then you can just click “Create pull request” to submit your changes.

Git-fu: Branch (-es, -ing)

When you’re new to the programming world, you may hear a word like branches and think of something like this:

Contextually, though, you know something is awry. Why would that have anything to do with your work?

Hint: It doesn’t.

Except for that whole “save the planet” thing.

…Seriously, though, we should take care of our environment. We live here after all.

Quick “How To” for branching with Git

As a new programmer, a lot of what I’ve done so far has been in my own GitHub repo with no one touching it but me. (Question: Who wants to touch the newbie’s code? Answer: No one. Duh.) As this is the case, it is really easy to get into the bad habit of pushing to the master branch. All the time. Well, most of the time. Perhaps a little unreliably, but that’s no big deal, right? I mean, you’ll just push it later. Maybe. When you remember and get around to it.

So yes. Really bad habits.

In an effort to break this habit, I decided to start making branches.

What is a branch?

If you want to read a bit about it and look at pretty diagrams, I recommend hopping over to git-scm’s “Git Branching – What a Branch Is” page. For now, I’ll just provide a TL;DR version:

• By default in git you have a master branch, which is where you I have been pushing your my code this entire time.
• When you create a branch, you can think of it as a copy of the code. Initially, both the master and newBranch are identical.
• When you push edits to newBranch, master is unaffected.
• When you want to include the newBranch edits in master, you merge the two branches.

Sounds like extra work…

…and it is, especially when your development team has only one member and that member is you, newbie :)

When used properly the main benefits, as I understand them, are:

• Branches are only merged to master when their code is working. Therefore master is always working. Don’t we all wish that were a thing?
• To get ready for the leap to a development team of 2+ developers, you’re going to want to branch so that your edits don’t mess up developer N’s edits (for N < numberOf(otherDevelopers)). (Likewise you don't want anyone else working on what you're trying to work on, right?)

So what do I do?

If you want to take this next step, then it's as easy as 1, 2, 3 (…4, 5, 6…):

1. Create the new branch. If you're a GitHub user, you can do this in the web UI. Or you can do this in the command line with git checkout -b newBranch
2. Edit some code.
3. Push some code.
4. Rinse, lather, repeat until the code is where you want it.
5. Switch back to the master branch: git checkout master
6. Optional (only as long as you're going solo): git pull origin master
7. Merge the new branch into master locally: git merge newBranch
8. Push the changes: git push origin master
9. Delete the branch: git branch -d newBranch
10. Push the changes (deleted branch) via git: git push origin --delete newBranch

That's it – you have now taken the next step into glory. Pretty awesome, right?

Yeah it is! I’m Super Programmer!

Easy, easy. Just be careful not to make it into the next episode of “Branching Gone Wrong”, ok? Remember:

• Don’t have long running branches. From one of my mentors:

“The longer you have the branch – usually – the further it diverges from master. So, the greater chance of merge conflicts, and of other changes making their way to master that are incompatible with your long-running one, but that’s not noticed until The Great Merging, which by now is An Event because of the sheer amount of things that will change when it happens.”

• Make sure to clean up after yourself and delete branches after they have been merged!

Reference: Git Branching Commands

• git status : Outputs your current branch as well as if you have any uncommitted changes.
• git checkout -b newBranch : Creates a new branch named newBranch and switches your current working branch to newBranch
• git checkout branchName : Switches your current working branch to the branch named branchName
• git branch : Lists all branches, current branch indicated with an *
  • git branch -v : Lists all branches with the last commit ID and message, current branch indicated with an * (-vv includes upstream branch)
  • git branch --merged : Lists all branches merged with your current branch, current branch indicated with an *
  • git branch --no-merged : Lists all branches not merged with your current branch, current branch indicated with an *
  • git branch -d branchName : Deletes the branch branchName locally if it has been successfully merged. If not, returns an error.
  • git branch -m currentName newName : Moves/Renames branch currentName to newName. If unspecified, currentName defaults to your current branch.
• git push origin --delete branchName: Deletes branch branchName from GitHub (as opposed to git branch -d, which only deletes the branch locally).
  • git push origin :branchName : Same as above – the : prefix means “delete”. I personally don’t use this method because I don’t want to get myself in a situation where I have trained my fingers to quickly, accidentally, delete things I don’t actually intend to delete.

Update (1/8): Interactive site to learn Git Branching