Version control is like the double-entry bookkeeping technique of saving all of your hard work. If you recall on the last lesson, there was an off-the-cuff statement about how your computer is just a fancy interface for working with files. Version control typically excels at handling text files. This blog post is a text file. HTML is text files. The original file that the blog post is generated from is a text file. SVG images are also text files. There’s also non-text files. Generally we call these binary files, but really we could also call them shit-files. That’s a completely objective industry term and not me showing any bias at all. Honest.

Double entry bookkeeping is something you might have had some exposure to in grade school, where you have to write down every credit and debit that hits your account, and there will be a corresponding debit or credit on some other account. It’s a ruthlessly simple model for handling money. We’re going to use a ruthlessly simple model for handling changes in text files. Version control systems can handle binary files too, but things are more eww there, so we’re just going to skip over that for now.

Like the bookkeeping stuff, version control is expressed as just a series of changes. Sure, you can write down what the final amount is somewhere in your checking account, but the final amount is always some composition of all the credits and debits since the dawn of time against your account. In the same way any given text file can be seen as the composition of changes happening over time to a text file.

There’s a lot of benefits that fall out of version control, but perhaps a primary driver for it is it allows us to capture a state in time that your source code was in. As of version x in the software, some things might be known such as features, bugs, and other behaviors. If we need to, we can go back to that point. We can make fixes against software that we released a while back.

Making fixes against older versions of the software can be helpful if we’re working on some shiny new feature, but we found out some critical bug in our software that our uses are on right now. Caught with our proverbial software pants down, we don’t want to have to discard our current work nor do we want to inflict some half-complete feature upon our users. Instead we can get in our version-control-time-machine and assume a prior state of the code base, make the fix, and roll it out. Once we’re done we can switch back to working on our shiny new feature.

At its most basic form, version control can serve as a super efficient text backup system. It keeps a history of all of your changes made in little slices at a time, and it stores these changes are just a series of changes (add this line here, remove this other one, etc). Even if you aren’t planning on doing releases/rollbacks, or don’t want to share code with others, you need to be on version control. And believe me, if you want to find work out there, it will be a boon in a job interview for your first position to be able to say “yeah I use this”. Otherwise they’ll have to teach it to you, and while that’s all find and good, this is a fundamental skill we expect software engineers in the industry to know.

There are lots of version control systems out there, but git is kind of the gold standard. Open source, free, and serverless, git can be very powerful (thus very complicated) and an easy defacto standard for version control software.

If you’re on MacOS, you might have git installed already. That’s okay but let’s make sure we’re on the latest version with this:

$ brew install git

While waiting for that to install, let’s go over some git trivia. git was a tool born of necessity as part of working on the Linux kernel. Torvalds stated he named it “git” (roughly meaning idiot) because he needed to be reminded that he was an idiot, or something. git transformed an insanely vast open source project into something more manageable. git is “distributed”, meaning there’s no central server that you must use. This allows for arbitrary organization of your repository. Repository is the word we give to a single code base, but repository doesn’t imply code since it works with just text. Sometimes we call a repository a “repo” for short.

This arbitrary organization allowed the Linux kernel to be divided up in a more organic fashion. Linus Torvalds could assign a kind of trust to “generals” in his open source army, who in turn could have lieutenants. This means there’s a kind of flow to the work being done. Lieutenants contribute to various changes in the code base, which get reviewed, corrected, and vetted by the generals. The generals then present the changes to Linus directly. This is really helpful when you maintain a complex operating system kernel on largely your spare time.

From working on our prior cat-hatred directory, we already have a code base ready to become a repository.

$ cd ~/dev/cat-hatred

From here, we can do our initialization command.

$ git init

Initialized empty Git repository in /Users/me/dev/cat-hatred/.git/

That’s it for making the repo! Kind of.

We’re not going to add everything to the repository.

Make sure if you’re jumping around that you’ve handled everything in the 5 section. Now we’re going to add files to this repository. First, we can look to see what files are available with the git status command.

$ git status

On branch master

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)

  accept-test.sh
  .gitignore
  package.json
  server.js
  yarn.lock

nothing added to commit but untracked files present (use "git add" to track)

Your version may be more colorful than my post’s, and that’s okay. Generally untracked and modified files are displayed in red. Files that are “staged” for commit are shown in green. I realized red/green color blindness is very common, and I think these colors can be configured, but I haven’t looked into that yet.

To stage these files, we can use git add <file1>, <file2>, .... You can also indicate a directory and it will get everything under that directory that isn’t being ignored. Ignored files won’t show up in the git status output so long as they weren’t committed earlier.

If your output differs than mine above then definitely ask about it, or retrace your steps. It can be a pain to take out files you didn’t mean to add. You also lose badass points.

Once you’ve made sure that’s all correct, we’ll add these files just one at a time to get used to the flow:

$ git add accept-test.sh .gitignore package.json server.js yarn.lock

And now when you do git status again, you should see these are ready to commit:

$ git status

On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

  new file:   .gitignore
  new file:   accept-test.sh
  new file:   package.json
  new file:   server.js
  new file:   yarn.lock

All of the files will be green! And it describes that they are ready to be committed. Let’s commit them!

Regardless of where you stand with commitment, you must commit your files or this just isn’t going to work between us. Generally when you issue a commit command, you are presented with your editor (whatever your system has listed for EDITOR in your shell’s environment variables - frequently this is nano or vim but could be configured to be a number of things). This is so we can write a meaningful message for our commit. Instead of getting into those editors, we’re going to use the -m flag to specify the commit message for today.

$ git commit -m "initial commit"

  [master (root-commit) 8aed320] initial commit
  5 files changed, 380 insertions(+)
  create mode 100644 .gitignore
  create mode 100755 accept-test.sh
  create mode 100644 package.json
  create mode 100644 server.js
  create mode 100644 yarn.lock

The exact commit hash (8aed320) and insertions may differ for you and that’s okay. Although the files listed should be the same. That’s our first commit!

In git, everything is represented as a series of commits along these things called branches or “refs”. We’ll get more into branching later.

Right now, if your machine just caught fire and melted, you’d still lose your work forever and you’d probably be really sad because you lost all of this and those questionable pictures you weren’t sure if you should put in a shared location for privacy reasons. All the work we’ve done thus far in git has been local. That means you could do this without any server connection. You can now bring your laptop out to the wilderness on that stupid camping trip and tell your hippie friends to piss off while you whip up a script that replaces their dog walking talents with a Roomba, and then commit that shit. I’m not bitter.

We want to push your commit up to a server. There’s a number of places we can put this, and they are free. Generally I use Github for my public stuff, and Bitbucket for my private stuff (both of which are free for their public and private use, respectively). There’s also Gitlab, which you can self host and there’s an online version, but I’m less familiar with its monetary aspects.

There’s a lot more to git than what I’ve shown you thus far, but now you can continue to do work, commit files that you change or add, and push them to your repository’s online copy. In the future I will share code with you using git. For a solo endeavor, the skillset you have now will suffice. Now we can get back to making awesome software!