I initially wrote this as a general explanation of version control software in a certain class's Piazza Q&A forum, while I was an undergrad student under Dr. Tal Moran @ IDC Herzliya. I really liked the metaphor, so I decided to publish it here as well. :)

Let's take a walk down metaphor lane for a second, shall we?

Say I'm not Tom the programmer, but I'm in fact Tomatia - the world-famous Italian restaurant.

We specialise in creating delicious, beautifully-crafted and ridiculously expensive pieces of software, that are universally liked and used in organisations big and small. We also give a lot of those pieces of software for free, so the world can enjoy them and create even better pieces of software on top of them.

In addition, let's say that my personal computer is the building the restaurant it's in, and all the little programs in my computer are workers, hired by me (and paid by tiny, tiny bits of processing power) to do certain jobs.

Out front you have the restaurant manager, a very serious-looking woman by the name of High Sierra, an esteemed member of the famous family of Macintosh. She is very beautiful, very fast on her feet and hates the guys over at the Office next door. She thinks they're kind of boring, and generally dislikes looking at them through the restaurant's Windows. Eh, ugly.

Back in the kitchen you'll find the cooks and the Chef. The Chef is a very IntelliJent - but kind of clumsy - guy called IDEA. A lot of the chefs in the other restaurants in the area are friends of his  - the guy who cooks for the Office that's located in front of the restaurant's Windows, the old and very tired chef who everybody knows is going to die soon, and even the sous-chef everybody likes and uses despite the fact that he has no intentions of ever becoming a full-fledged chef.

A very important part of the kitchen staff is Hal. Hal has hair of silver and slides through the kitchen like a fluid and not like a computer program. Because of these qualities, he's often referred to by the nickname Mercurial, like the chemical element Mercury - that is a silver-y coloured fluid of sorts.

Hal has a very important job - he is in charge of a small table in the front of the kitchen. That table is the place where the cooks and the Chef bring out the plates before they're going out to the customers in the dining area. Hal needs to make sure he knows everything that's going on at this table at any given time.

In order to remember all the things that happened in his table during a certain shift, he keeps a small notebook with a record of everything. Quickly, though, he realised that writing "Someone brought a new plate to the table" or "A plate went out to a customer" every time one of these things happen can take up all of his notebook in no time!

Hal is smart.

Instead of writing all of these long sentences, he decided he will write them in code. Hal's also a little weird, so in order to add some flavour to his notebook he decided he will prefix each line with the letters hg (yeah, you got it, like the chemical symbol for Mercury. Slick.

To remember his code, Hal made a small list on the back cover of his notebook:

  • hg add <plate-name> - Someone brought some  to the table.
  • hg add . - Instead of logging every single plate that's been brought to the table, Hal sometimes uses this code to note that a bunch of new plates came to the table.
  • hg commit -m"<plate-message>" - A plate was sent out to a customer. Sometimes the Chef asks to tell the customer something about the plate, so Hal will write that down in .  Actually, coming to think of it, the Chef always has something to say about his plates. In addition, whenever he sends out a plate for a customer, he will write down all the details of the plate and the specific way the table was organised at that moment in time. To differentiate between all the different times he does this, he marks each of these lines with a special combination of numbers and letters next to the line - he calls it a "changeset". He can always look back in his notebook to a specific changeset to see how the table was organised at that specific time, and what the plate sent out to the customer contained.
  • hg push <remote-restaurant>  - The Chef has sent a plate to another restaurant. This happens when the Chef wants to have a back-up for a certain plate in one of his friends' restaurants, or when he wants another chef to look at his plate and give his notes. He tries to do this kind of often, so he'll always have something to fall back on if something gets screwed up.
    hg pull  - The Chef wants to receive a plate from one of his chef friends for examination. A lot of the time the Chef will decide that this is a great plate, and will decide to add it to the menu.
  • hg update <changeset> - Sometimes, the dishes are not very good - and the customers throw up on High Sierra. High Sierra doesn't like people throwing up at her, so she comes storming in the kitchen and demands that the Chef will make the dishes again, this time making sure that nothing is wrong with them. It's a good thing Hal is so organised, then! Told you he has a very important job. Remember that combination of letters and numbers he wrote down next to the dishes he sent out? At any given time, Hal can re-arrange the table exactly like it was before the bad dishes went out, according to the changeset. This lets the Chef look at the dishes again, make changes if necessary, and send them out again to happy, vomit-free customers.
  • hg update - Sometimes, the Chef makes a small mistake that screws up everything in a bunch of plates. Hal will then write this down to note he has re-arranged everything back to the state before the last dish went out, so the Chef can start over again with a relatively organised table.
  • hg status - Sometimes, when the restaurant is really busy, Hal will do an inventory of the table - check to see which plates are there, which ones were changed in any way and which ones were removed. This helps him make sure everything is up to speed. He will then write down all of the different things that went on since the last dish went out to customers, just to be on the safe side.
  • hg log - Sometimes, the Chef asks Hal for a list of the latest dishes that went out to customers. When that happens, Hal writes those last few dishes in his notebook next to this special command.

All in all, Hal is very satisfied with the system he's created. In fact, he's so satisfied with it, that he's bragging about it to all of the other Hals in all the other restaurants in the area.

This doesn't always go well for Hal.

More specifically, there is one person - in the same position as Hal - working for a French restaurant on a nearby town. His full name is Guy Immanuel Trebouche, but most of his friends just call him Git. He's a lot more popular with the ladies than Hal is - most of the times they go out for post-shift drinks in a bar, Git gets lots of phone numbers while Hal gets just the one. Maybe.

Git also considers himself to be a much more complex and sophisticated person than Hal. This, unfortunately, means that none of the ladies he ends up calling understand what he has to say. He tells people it's because of his french accent, but deep inside Git knows that it's because he's truly a difficult person to understand.

Sometimes Git looks up at his pink-coloured ceiling and all the branches out his window, and wonders what it's like to be a simpleton like Hal. Maybe there's a blessing in disguise there? Maybe if he'll be more like Hal someone will actually understand him for once?

All the while, Hal sits at home, alone, and wonders the opposite thing: He wonders how his life would have turned out if he was more like Git and less like himself. Maybe he wouldn't sit at home every night waiting for the phone to ring.....

But the story of the differences between Git and Hal is, I'm afraid, a story for another day.