--- layout: reference ---

Basic Snapshotting

Git is all about composing and saving snapshots of your project and then working with and comparing those snapshots. This section will explain the commands needed to compose and commit snapshots of your project.

An important concept here is that Git has an 'index', which acts as sort of a staging area for your snapshot. This allows you to build up a series of well composed snapshots from changed files in your working directory, rather than having to commit all of the file changes at once.

In a nutshell, you will use git add to start tracking new files and also to stage changes to already tracked files, then git status and git diff to see what has been modified and staged and finally git commit to record your snapshot into your history. This will be the basic workflow that you use most of the time.

docs   book git add adds file contents to the staging area

In Git, you have to add file contents to your staging area before you can commit them. If the file is new, you can run git add to initially add the file to your staging area, but even if the file is already "tracked" - ie, it was in your last commit - you still need to call git add to add new modifications to your staging area. Let's see a few examples of this.

Going back to our Hello World example, once we've initiated the project, we would now start adding our files to it and we would do that with git add. We can use git status to see what the state of our project is. 

$ git status -s
?? README
?? hello.rb
So right now we have two untracked files. We can now add them. 
$ git add README hello.rb
Now if we run git status again, we'll see that they've been added. 
$ git status -s
A  README
A  hello.rb

OK, so now if we edit one of these files and run git status again, we will see something odd.

$ vim README
$ git status -s
AM README
A  hello.rb

The 'AM' status means that the file has been modified on disk since we last added it. This means that if we commit our snapshot right now, we will be recording the version of the file when we last ran git add, not the version that is on our disk. Git does not assume that what the file looks like on disk is neccesarily what you want to snapshot - you have to tell Git with the git add command.

In a nutshell, you run git add on a file when you want to include whatever changes you've made to it in your next commit snapshot. Anything you've changed that is not added will not be included - this means you can craft your snapshots with a bit more precision than most other SCM systems.

For a very interesting example of using this flexibility to stage only parts of modified files at a time, see the '-p' option to git add in the Pro Git book.

docs   book git status view the status of your files in the working directory and staging area

As you saw in the git add section, in order to see what the status of your staging area is compared to the code in your working directory, you can run the git status command. I demonstrated using it with the -s option, which gives you short output. Without that flag, the git status command will give you more context and hints. Here is the same status output with and without the -s. The short output looks like this: 

$ git status -s
AM README
A  hello.rb
Where the same status with the long output looks like this: 
$ git status
# On branch master
#
# Initial commit
#
# Changes to be committed:
#   (use "git rm --cached ..." to unstage)
#
# new file:   README
# new file:   hello.rb
#
# Changed but not updated:
#   (use "git add ..." to update what will be committed)
#   (use "git checkout -- ..." to discard changes in working directory)
#
# modified:   README
#

You can easily see how much more compact the short output is, but the long output has useful tips and hints as to what commands you may want to use next.

Git will also tell you about files that were deleted since your last commit or files that were modified or staged since your last commit.

$ git status -s
M  README
 D hello.rb
You can see there are two columns in the short status output. The first column is for the staging area, the second is for the working directory. So for example, if you have the README file staged and then you modify it again without running git add a second time, you'll see this: 
$ git status -s
MM README
 D hello.rb

In a nutshell, you run git status to see if anything has been modified and/or staged since your last commit so you can decide if you want to commit a new snapshot and what will be recorded in it.

docs   book git diff shows diff of what is staged and what is modified but unstaged

There are two main uses of the git diff command. One use we will describe here, the other we will describe later in the "Inspection and Comparison" section. The way we're going to use it here is to describe the changes that are staged or modified on disk but unstaged.

git diff show diff of unstaged changes

Without any extra arguments, a simple git diff will display in unified diff format (a patch) what code or content you've changed in your project since the last commit that are not yet staged for the next commit snapshot. 

$ vim hello.rb
$ git status -s
 M hello.rb
$ git diff
diff --git a/hello.rb b/hello.rb
index d62ac43..8d15d50 100644
--- a/hello.rb
+++ b/hello.rb
@@ -1,7 +1,7 @@
 class HelloWorld
   
   def self.hello
-    puts "hello world"
+    puts "hola mundo"
   end
 
 end

So where git status will show you what files have changed and/or been staged since your last commit, git diff will show you what those changes actually are, line by line. It's generally a good follow-up command to git status

git diff --cached show diff of staged changes

The git diff --cached command will show you what contents have been staged. That is, this will show you the changes that will currently go into the next commit snapshot. So, if you were to stage the change to hello.rb in the example above, git diff by itself won't show you any output because it will only show you what is not yet staged. 

$ git status -s
 M hello.rb
$ git add hello.rb 
$ git status -s
M  hello.rb
$ git diff
$

If you want to see the staged changes, you can run git diff --cached instead.

$ git status -s
M  hello.rb
$ git diff
$ 
$ git diff --cached
diff --git a/hello.rb b/hello.rb
index d62ac43..8d15d50 100644
--- a/hello.rb
+++ b/hello.rb
@@ -1,7 +1,7 @@
 class HelloWorld
   
   def self.hello
-    puts "hello world"
+    puts "hola mundo"
   end
 
 end

git diff HEAD show diff of all staged or unstaged changes

If you want to see both staged and unstaged changes together, you can run git diff HEAD - this basically means you want to see the difference between your working directory and the last commit, ignoring the staging area. If we make another change to our hello.rb file then we'll have some changes staged and some changes unstaged. Here are what all three diff commands will show you:

$ vim hello.rb 
$ git diff
diff --git a/hello.rb b/hello.rb
index 4f40006..2ae9ba4 100644
--- a/hello.rb
+++ b/hello.rb
@@ -1,7 +1,7 @@
 class HelloWorld
   
+  # says hello
   def self.hello
     puts "hola mundo"
   end
 
 end
$ git diff --cached
diff --git a/hello.rb b/hello.rb
index 2aabb6e..4f40006 100644
--- a/hello.rb
+++ b/hello.rb
@@ -1,7 +1,7 @@
 class HelloWorld
 
   def self.hello
-    puts "hello world"
+    puts "hola mundo"
   end
 
 end
$ git diff HEAD
diff --git a/hello.rb b/hello.rb
index 2aabb6e..2ae9ba4 100644
--- a/hello.rb
+++ b/hello.rb
@@ -1,7 +1,8 @@
 class HelloWorld
 
+  # says hello
   def self.hello
-    puts "hello world"
+    puts "hola mundo"
   end
 
 end

You can also provide a file path at the end of any of these options to limit the diff output to a specific file or subdirectory.

In a nutshell, you run git diff to see details of the git status command - how files have been modified or staged on a line by line basis.

On to Branching and Merging »