Let's Finally Git Along, GitHub

Git and Github are so misunderstood, but it's time we got to know them better.

I want to share how I understood them before and how I understand them now. If you don't want to read my story and rants, you can skip to the part where I share what I've learned about Git and GitHub workflow.

First Date Impressions

Here were my initial impressions of Git and Github before my first time using them.

Github’s website says Git and Github are easy to learn. They even say you can learn it without any code! That's a relief!

I heard Git reveals its greatest potential on the command line, which is itself seemingly straightforward and unassuming. Sounds simple, yet pretty powerful!

Looks like GitHub is a simple website even more intuitive to navigate than Git. Well, that seems manageable!

"Git" is a simple single-syllable, chirpy sounding name. And Github has their adorable mascot, the Octocat. So cute. All of that.

Looking into Octocat's eyes, I genuinely believed that GitHub was a sweet and harmless platform whose only purpose was to make my life easier.

Git is a Version Control System and it is a tool that you can use locally on your own computer to manage your project's development history. GitHub, on the other hand, is like Git with online social networking where you can share work remotely. They’re both there to allow us to build and collaborate on projects with peace of mind, and so you’d naturally get the impression that they're supposed to be simple and easy to use.

But if that were the case, why do people panic when it's time to use them?

Why Didn't I Get Git

For many reasons, I've had lots of internal freakouts whenever I've had to approach Git. It works on the command line, which is simple to use, but can also be obscure and intimidating for many inexperienced users. When things go wrong, it screams at you with lines of unfamiliar words, and when things go right, it's curt or you don’t get any validation, which then leaves you second-guessing whether or not you did anything at all!

I don't know about you, but to me, that sounds reminiscent of a bad, gaslight-y relationship.

I'm kidding (sort of), but it was hard for a new learner like myself to understand what was going on when all I could see was text, but I couldn't visualize the changing structure or the bigger picture of what I was working with.

Add GitHub and some equally confused people into the mix, and then it escalates into a far more confusing, high-risk, and stressful experience. You realize your decisions actually have consequences and that they can affect other people and your projects!

Learning From the Past

Several of my boot camp classmates and I learned the hard way after our very first collaborative project experience last week that without trying to understand how Git works and establishing a good workflow on Github, you'll not only potentially ruin your own efforts and projects, but you'll heavily bruise your relationships and confidence too.

Even though I had a less than desirable project experience thanks to Git and GitHub, it was a necessary one because now I've grown highly motivated to not repeat my mistakes. Since I know what it’s like to collaborate on a project now, I can read Git documentation with more clarity and I can effectively research solutions for problems I've had and never want to repeat. I have a stronger sense (I think!) of how Git and Github can help me work harmoniously with my team, and I think it's only right to share what I've learned so that we can all better maintain and preserve our relationships (and our sanity).

A Collaborative Workflow Guide

In my explanation of a simple workflow, I'm going to skip over explaining in depth the basic routine steps such as clone, add, commit, or push. Instead, I'll spend more time explaining the extra steps we need to take beyond that when we're working with collaborators. Also, for brevity, I'll illustrate an ideal situation. I figure issues like merge conflicts probably deserve their own post.

If you're not familiar with Git basics or you're a bit rusty, you can take a look at GitHub's own guide or git-the simple guide first, both of which I find clear enough.

1. Set Your Team Up for Collaboration

It's Pretend Project Week! We're a team consisting of multiple members, and we're all working together on a brand new project. To start things off right, we'll structure our project clearly, establish rules we can all agree to, and stick to a plan.

2. Create a Master Branch

First, we need to appoint one person, and let's name her Aliya, and ask Aliya to create a new repository for our project on Github. Or in the case that we're starting from a template of another repository, she can fork the repository. Whether a brand new repository or a fork of one, it's a new master branch for all of us to work with! Good job, Aliya!

3. Add Collaborators

But wait! Before we jump into the code, Aliya still has to add us as collaborators for the project!

She clicks on the new repository's Settings tab near the top, and then Collaborators on the left menu. Then using the search bar, she searches for each team member and clicks on the Add Collaborator button to add them to our project. Easily done!

Now that that's out of the way, everyone can clone (but not fork!) a copy of the repository onto their local directories and work on them independently.

4. Establish a Game Plan

Ideally, before we start our project and type away, we should have a clear plan of how we're going to tackle it together and establish expectations and rules. We agree we shouldn't ever be working on the same files, and we especially shouldn't be working on the same code.

We decide we're each going to work with our strengths and interests and assign each member a feature of the project to work on. We'll create feature branches off the master branch, and we'll work on our own branch independently. The rules are simple: Stay on your own branch and don't work on code that's not yours.

5. Create a Feature Branch

Each of us can create our own branch using the command line:

The -b flag will create our new branch uniquely called sweet-feature-im-working-on and checkout moves us to that branch immediately after its creation.*

So everyone's got their own branches with distinct names describing what they're working on. We can each work off our branch and start making changes to our own features. Just remember to focus on the task you were assigned and don't mess with other code!

6. I'm Finally Done with My Feature! Time to Push!

Once we've finished working on our features, we can push it up to our remote repository branch on GitHub using the command line:

That was easy!

7. Make a Pull Request

Then we'll hop over to our remote repository on Github and click the green button that says Compare and Pull Request.

On the pull request page, we'll need to compare our branch of the head repository to the master branch of the base repository.

Wha....what? So many big words...

Stop, breathe, and just read carefully to proceed. HEAD is just where our current branch is. So we want to be sure that when selecting what to compare, our base repository master branch is being compared with our head repository and the branch that we've been working on all this time, sweet-feature-im-working-on.

Make those selections, and if you get that green light of approval you're good to go and ready to merge! Finish off the process by clicking on the green button, Create pull request, on the bottom right corner of the form.

8. Merge!

There are many ways to go about doing this. By default, any contributor can approve a pull request, even their own, and merge changes into the master branch. It's fine if you're working alone, but in a group, things can get problematic if someone's not carefully reviewing their own code before merging it.

I like a democratic approach where we can either choose one person on our team to review and approve all the pull requests, or we can require that at least one other collaborator outside of our individual selves do it. Either way, a peer is double-checking our work and making sure it doesn't break the project. If a peer decides our code is acceptable, they'll approve the merge, but if they think it needs some additional work, they'll ask us to improve it to an acceptable level before a merge is approved.

Our work has been approved and merged into the master branch! Now that we're officially done working on our feature, we can safely delete our feature branch.

9. Pull All Updated Changes

After everyone has had their changes successfully merged, we'll go through most of the steps all over again.

But before we do this again, we'll need to start on a clean slate. Perhaps everyone should get the complete set of updated files before moving on to another new feature.

Let's go back to our master branch on command type...

...and pull all the updated changes into your local repository...

Now we have all the updated files and we're ready to work again!

10. Repeat Until Done

From here on out, the steps are the same,

1. Create another new branch to work on. Remember to work only on your own feature on your own files on your own branch. Meanwhile, commit freely and often!
2. Push when you have complete and functioning code
3. On GitHub, compare branches and make a pull request
4. Peer review code and approve pull request, then merge changes to the master branch.
5. Go back to master branch to pull all updated changes.

And we'll repeat that cycle until we're done our project!

Need more?

If that explanation was still not 100% for you, there's plenty of documentation and other resources out there to help out. I gained plenty of clarity by reading this explanation by Erin Hoffman, of one of the Software Engineering coaches at Seattle Flatiron School. Although it's a bit more specific to our project assignment, she lists out the important collaborative steps super clearly.

Conclusion

After lots and lots of googling, I've concluded that this is a collaborative workflow that makes sense to me and that I'm willing to try out. Some concepts and steps are admittedly still a little blurry to me, but the good news is that I feel way less intimidated by the process and I'm eager to experiment with this approach during my next project. Hopefully, it does wonderful things for me and my partners! And when it does, I plan to take in and appreciate every moment of peace. Rather than stressing and tip-toeing around the Git/GitHub minefield, I'll spend the time I save from not doing that actually creating a project with my partners and enjoying the experience!

*Edited June 7, 2019 Erin Hoffman helpfully pointed out yesterday that I had the purposes of -b flag and checkout switched up, so that's been corrected. (Thanks Erin!) For extra clarity, if I were to read git checkout -b this-new-branch as a sentence, it'd be "Let's go check out this new branch I made called 'this-new-branch.'"