It's time for another edition of newbie developer tips in plain language! This round I am going to be speaking to the subtlety and delight that is interacting with GitHub using a push request.

To git (ok ok, I'll only make this joke once) value from this blog you'll want to be familiar with setting up your account and basic jargon like understanding what a repo is and what GitHub is in general. Also, you'll want to be up to speed with using the command line, CLI, terminal, or whatever you call it as your method for interacting with GitHub

There are also other resources out there speaking to the complexities of workflows in proper dev environments when working with teams worth investigating. This writeup is not that, but I highly recommend checking some out like this excellent reference on types of branching that added a few wrinkles to my brain by Vincent Driessen.

On to the pushin'

We all have some kind of general idea what pushing and pulling does in a variety of contexts but specifically within GitHub those words do not directly translate exactly to what is happening with your code when you use those commands. Things happen behind the scenes and there can be consequences for those actions. Let's explore a little deeper.

While it is true that the git push command does upload your local repository what is unclear is that there are other actions that affect what is pushed, when, and why. This is because the whole point of GitHub is version control. Lets take a second to define what that means.

Version control is effectively the detailed tracking of changes and updates to code in software development. Given the high specific, structured, and detailed nature of programming itself you might imagine that one of the most popular platforms for managing version control for developers also carries those traits.

You could say, one does not simply push code into Origin/Maindor.

Sure, if everything is in order and no other code is involved in where you are pushing your code to it might be as simple as adding, committing, and pushing your code but if you're working with other people on a project chances are you'll have some other concepts needed to get your code in to the bigger project.

Ok ok, great. I write my nifty code, I decide I'm ready to share it with the world, and so I push it into the broader codebase, right? Nerp. Sorry. We have hierarchy and structure and the grand order of things to consider here. In the aforementioned link to branching theory you'll learn that you have your local code which is likely on a branch. A subdirectory if you will in the hierarchy of version control so that when your misplaced comma throws the proverbial wrench in the operation the finger can be pointed squarely at you. No pressure.

This is a good thing, really. Branches and local work allow for the detailed hierarchy and version documentation needed to manage complex projects effectively. The graphic above gives a simple visual for what is happening when code is pushed. It goes from your local work on it's own branch into the main code for the project in a documented way.

Utilize many branches to segment your work appropriately for what you're working on. If it is a new feature? Branch. If it is a separate addition to the broader concept of the project? Branch. Methodic and documented is the name of the game in version control and well documented code.

Preparing for the push

Now that we know there is a top down structure with local and remote branches of code let's get to what you, fellow fledgeling, need to know to upload your precioussssss code to your branch.

A couple of nice to know commands to be aware of to ensure you're going in the right direction before we move forward:

git status allows you to view all of the files that are staged before committing them. Handy little tool, that.

git branch will verify what branch you're working on so that you don't just try to push your code directly to the main branch.

Adding your local code in preparation to push it up to the main branch is done via git add in your command line. You can use this to specify specific files like git add README.md or by adding everything in your local repo by adding a period like so:

git add .

Now that your files are added to the list of what is going to be pushed up you'll want to impress your therapist and commit to something. That's right, you have to own your work and even tell everyone what you did by adding a little description. Which, much like real life, it is very important to communicate where your head is at. The commit syntax is as follows:

git commit -m "And if you gaze for long into an abyss, the abyss gazes also into you"

In reality, commit is what records the changes to the repository. It is very important here to understand the style of commit messagges expected in the project your working on and to leave meaningful clues to what is happening in your code for those that might be reading it after you. Here is what is really going on with your commit message straight from the hubses mouth:

git commit creates a commit, which is like a snapshot of your repository. These commits are snapshots of your entire repository at specific times. You should make new commits often, based around logical units of change. Over time, commits should tell a story of the history of your repository and how it came to be the way that it currently is. Commits include lots of metadata in addition to the contents and message, like the author, timestamp, and more.

That is powerful stuff! I liken this step to a saying from my World of Warcraft raiding days. Pot early, pot often. Frequent commits create a paper trail so to speak of all your hard work. Use it to your advantage and commit early, commit often.

The final step is actually pushing your code. Which seems benign enough but this precipitates a variety of things happening. The push is part of syncing code with the broader code base. It takes your added changes and committed descriptions of those changes and moves them to the public version of your branch. This is only part of the equation though.

Depending on what state the branch you're pushing that code into is in you may need to address what to do with your changes and how they are going to affect the broader code.

Fetching, pulling, and merging are tools in the tool kit for working with ensuring your code is clean and pushed up to the branch that I'll visit in another post. For now, you should have a deeper understanding of what it means to add, commit, and push with some new tools to check up on your code before you push it on up.

Until next time.

I used this guide from Atlassian as a resource for this post including the image above.