something i regularly struggle with in engineering is being able to grasp a new concept just from an explanation. i’ve made peace with my learning style and i’ve compensated by doing what i do best: coming up with weird metaphors. not just any metaphor, it’s gotta be *sound.*

and thus git has escaped this treatment for the better part of a year. it’s been the bane of my existence ever since I first gained access to our codebase. i’ve scraped by  using the 5 things i’m fairly certain of and getting someone to take over when i eff myself into a git rebase cluster storm. git is hard. version control is hard to visualize in it’s entirety. and you can get away with not knowing most of it for a long time.

so today, being the friday of burning man, where offices around silicon valley are momentarily peaceful, I took some time to learn git on my own terms. and so here… is my metaphor…warning, this is stupid.

You and your friends are get together each week  to solve the New York Times Sunday crossword puzzle (i know, sorrynotsorry) and this is your wildly elaborate process for doing so:

Your friend Jeff is what we’ll call the “puzz master.” He’s the one hosting you and your friends at his house, and he’s mostly in charge of the master copy of the puzzle.

So before you and your friends arrive at Jeff’s place, Jeff is going to get everything set up for you guys to work on the puzzle together. First, he’s going to bring a big desk into his master bedroom. I’m calling this same as “mkdir ‘master_desk’ on a local system, basically just creating a place in the house for the puzzle to live.

Next he sits down at the desk, or ‘cd desk.’

With me so far?

Okay so now Jeff is going to ‘git init.’ What it does is turn the desk from a normal desk into something that he and his friends can use to do the puzzle. It’s basically going to lay out some general instructions on how to do crossword puzzles.

Next Jeff goes out onto his front porch and picks up his Sunday New York Times, pulls out the crossword puzzle, tosses the rest in recycling and walks back into the house. He lays the puzzle on his desk.

But so far this is all still in Jeff’s master bedroom, and he doesn’t want his friends going in and out of his room, so he walks into the kitchen and sets up his kitchen table, which he only brings out for puzzle nights. This is the same going into Git Hub and clicking on “create repository.” He puts a sign on the door to the kitchen that says “kitchen,” just to avoid confusion. This table, also has instructions on how to do puzzles, but it doesn’t have Sunday’s puzzle, which Jeff just put on his desk. So Jeff is going to do 2 things. First he’s going to put a sign on his bedroom door that says “master puzzle is in the kitchen.” This is to tell his roommate Kyle, who no one really likes, and has the unfortunate job of running back and forth between rooms and managing requests from you and your friends, where to take Jeff’s updates to. Next, Jeff is going to ‘git push kitchen puzzle.” He’s going to hand the Sunday puzzle to Kyle, who’s going to memorize what it looks like and go create the same one on the kitchen table.

Now Jeff and Kyle are ready for you and your friends. You arrive and walk immediately into one of the guest bedrooms. You do `mkdir desk` and set up a desk out of an old card table in the middle of the room. You ‘cd desk’ and sit down at the make-shift desk. But instead of starting from scratch, since Jeff already set things up in the kitchen, you’re just going to ‘git clone kitchen/master_puzzle.’ Almost immediately Kyle shows up with the instructions and copy of the puzzle. He sets them on your desk and tapes a sign outside your door that says “master puzzle in the kitchen” to remind himself where he should take your puzzle answers.

So Jeff is a bit of a times puzzle purist. He only does it in pen and he doesn’t allow anyone to put answers on the master copy of the puzzle. It’s kind of annoying but you love Jeff, so you comply with his ridiculous rules. He makes each of you copy the puzzle you have on your desk and set it next to the master copy. (Git checkout -b your_desk).  you move your chair over to the left so you’re sitting in front of the copy and get cracking.

20 minutes later you’re feeling pretty confident with the answers you’ve written down and you’re ready to have Jeff add them to the master copy in the kitchen. So first you take your puzzle and put it in a hanging folder just outside your door (git add). Since it’s outside the room, Kyle’s aware you’ve got some changes ready, but you haven’t called him over yet. So you call him over (git commit). Kyle comes over and makes a copy of your puzzle and files it in a filing cabinet underneath your card table. Then you’re ready to put it in the kitchen so you ‘git push kitchen your_desk.’ This takes a copy of your puzzle and puts it on the kitchen table next to the master copy of the puzzle. Kyle looks over your changes and makes sure there’s nothing on your puzzle that would overwrite other answers. Everything looks good so he stamps it green.

With the green stamp you ‘git merge’ your answers into the master puzzle where Kyle will write them down in pen.

And thus you and your weird OCD friends continue until you’ve decided the puzzle is finished.

So that’s my metaphor for now. I was going to cover merge conflicts and rebasing and reverting changes but I think this got long-winded more quickly than I’d hoped. Just like git to annoy me even in metaphor.

For posterity, I made this while I was writing this entry.