loading...

Git Staging Area: Explained Like I'm Five

sublimegeek profile image Jonathan Irvin ・2 min read

Imagine a box. You can put stuff into the box. You can take stuff out of the box. This box is the staging area of Git. You can craft commits here. Committing is like sealing that box and sticking a label on it. The contents of that box are your changes. So, why not have the label mean something? You wouldn’t label a moving box with kitchen items as simply “stuff.”

Staging Area

As you make changes locally, Git can "see" them. However, figuratively speaking, they're out of the box. If you were to try and make a commit at this point, Git wouldn't have anything to commit.

Here's how to relate the box analogy to some basic Git operations.

git config --global user.name "Jonathan Irvin"

You create a seal that you will use for each box. It has your full name on it. Not a username or a screen name. That would be silly. You laugh to yourself at the silliness.

git config --global user.email "jonathan@notmyemail.com"

You add your email address to your seal. Would be useful should someone need to contact you about the contents...or yell at you. You know, business as usual.

git init

You build your desk and keep an infinite supply of boxes underneath the surface to place work items in for storage.

git add

The moment you perform an add command, you're adding to the box. Yes, grab a box. Any box. Put something in it. You've just done a git add.

git stash

Pick up the box and put it on a shelf away from your desk. Your desk is clean, but your items are still easily accessible.

git stash apply

Take the box off of the shelf and empty the contents back on to your desk...neatly. Hopefully, you don't have anything on your desk already or you might have some conflicts!

git stash clear

Take your arm and swiftly swipe all of the shelf contents into the garbage chute. Who needed all of those half-baked ideas anyway?

git reset HEAD -- <file>

Take one item out of the box.

git reset HEAD -- <directory>

Take several grouped items out of the box.

git reset --hard HEAD

Pour gasoline on the box and light it on fire. Your stuff is now ashes. Gone. Forever.

git commit -m "message"

Tape the box shut. Label it with "message" and put it in storage with other labeled boxes.

git revert

Hold a mirror up to the sealed box. Magically, another box is created that appears to be an exact clone, yet completely opposite. You keep the two boxes apart for fear they would cancel each other out. It is the anti-box.

git status

You look at your desk and see items on your desk, in the box, or both.


Now anytime you look at a box, you can't unsee it.

Posted on by:

sublimegeek profile

Jonathan Irvin

@sublimegeek

I'm a full-stack cloud-minded engineer who enjoys devops and clean code.

Discussion

markdown guide
 

Clear explanation! Any five-year old could now get how git works! Also had a laugh in the process

I am just a bit confused about "git revert" and the anti-box. Could you please explain more? Does it mean we have the ability to revert the last commit? After typing "git revert" isn't it reverted automatically?

P.S.: Would love to see a second post with the box analogy explaining more about git!

 

A git revert will create another commit that is an exact mirror opposite of the commit you are reverting.

In my example, a sealed box is a commit. If you have a commit where you add 2 lines and remove one. The reverted commit will remove 2 lines and add one, effectively nullifying your original change.

This is why I was making the juxtaposition to anti-matter where a commit and a reverted commit combined would be the same as no commit.

Does that make sense?

 

Yes, very clear!

But do we have to commit this new anti-box? Or is it pushed automatically?

Whenever you perform a git revert the commit is created automagically for you. You can see it if you perform a git log or use a Git GUI like Sourcetree.

IF you want to make your revert public, you would do a git push and your local repo would be synced with the remote repo, assuming no conflicts with the public repo are present.

 

Awesome explanation! I'm already quite comfortable with git after a lot of reading and research, but this is the explanation I would've wanted back when I started.

I'd even suggest a follow up article about why the staging area is such a cool idea, using the box analogy. (Other version control systems without a staging area can only create labeled boxes by dumping the entire contents of your desk into the box all at once... git allows you control over what goes into each labeled box...etc)

 
 

How do I open one of the many sealed boxes find some old code and bring it back to life?

Let's say, I deleted a bunch of files in favour of one that does what all these other files were doing. That was 3 or commits ago. Now, I just remembered that one of the files would be useful to me.

 
 

Ok, I get that this opens the box. Now my HEAD is in the box, but how do I recover the one file?

Well, depends on what you mean by recover. If you checked out the commit, you'll see the version of the file you want. If there's a lot of changes you can make a copy and then paste it over the latest commit. If there's a few, you can revert lines or hunks selectively.

 

Two remarks

  • the opportunity to only add lines or blocks to a commit is important too. Not just the whole file.
  • the staging area is also an opportunity to review your changes.
 
git reset --merge HEAD

Same as --hard except you preserve ignored files.

(Pretty much always better)

 

How could you resolve conflict?

 

Stare at the box. You feel compelled to argue with it. It wins. Every time.

 

So helpful! Really good for beginners :)