Skip to content

aprendía

(I was learning)

Git staging — call it what it is

I love Git. I really do. However, learning to love it took a little bit of work, at least for me (and it has been worth it). This was because I found a couple of areas a bit confusing. This was a combination of two factors:

  1. I was coming from a Subversion background,
  2. Git’s inconsistency in how it refers to a key concept.

We will ignore the first factor, for now. I want to address the second one.

Background

For those unfamiliar with Git, it has a slightly different workflow than Subversion. (I will not discuss why it is different — I only show this for context.)

GitSubversion
Work, work, work …Work, work, work …
Stage changes,Commit changes to repository.
More work, work, work … if desired, 
Stage more changes, if desired, 
Commit staged changes to repository. 

The main concept we’re concerned with is staging — the buffer zone, of sorts, that allows changes to be held before they are committed.

Inconsistency

Unfortunately Git is all over the place when it refers to this concept of staging. The following example does four things:

  1. Checks the status of our repo, which has an un-staged change,
  2. Stages that change to be committed,
  3. Checks the status of our repo, which now has a staged change,
  4. Shows a diff of what is in the repo and what we have staged to commit.
$ git status
# On branch master
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#
#   modified:   foo.html
#
no changes added to commit (use "git add" and/or "git commit -a")

$ git add foo.html

$ git status
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#   modified:   foo.html
#

$ git diff --cached 
diff --git a/foo.html b/foo.html
index e812d0a..3d92c4d 100644
--- a/foo.html
+++ b/foo.html
@@ -5,8 +5,5 @@
-        <li><a href="bio.html">Biography</a></li>
+        <li><a href="about.html">About</a></li>

But notice that the concept of staging is referred to with the words

  1. update[d] = to stage, staged
  2. added = staged
  3. cached = staged
  4. unstage
  5. index = the stage itself

This is hardly intuitive. Maybe it could be a little easier …

Consistency

The sensible approach would be to refer to this concept of staging as, well, staging. The following makes more sense to me.

$ git status
# On branch master
# Changed but not staged:
#   (use "git add <file>..." to stage what will be committed)
#
#   modified:   foo.html
#
no changes staged to commit (use "git add" and/or "git commit -a")

$ git add foo.html

$ git status
# On branch master
# Changes staged to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#   modified:   foo.html
#

$ git diff --staged 
diff --git a/foo.html b/foo.html
stage e812d0a..3d92c4d 100644
--- a/foo.html
+++ b/foo.html
@@ -5,8 +5,5 @@
-        <li><a href="bio.html">Biography</a></li>
+        <li><a href="about.html">About</a></li>

Conclusion

Referring to concepts, tasks, and features consistently will ease the learning curve and frustrations of those trying to adopt new software.

And if Git happens to be the new software you’re trying to adopt, I highly recommend Travis Swicegood’s book Pragmatic Version Control Using Git. It covers introduction through advanced techniques and despite using Git for some time, I am giving it a read and am learning some useful things.