git-reference/basic/index.html

---
layout: reference
---

<div class="box">
  <h2>Basic Snapshotting</h2>
  <div class="block">
    <p>
    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.
    </p>

    <p>
    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.
    </p>

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

  </div>
</div>

<div class="box">
  <h2>
    <span class="docs">
      <a href="#">docs</a> &nbsp;
      <a href="#">book</a>
    </span>
    <a name="add">git add</a>
    <span class="desc">adds file contents to the staging area</span>
  </h2>

  <div class="block">
    <p>
    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 <code>git add</code>
    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 <code>git add</code> to add new modifications to your staging
    area. Let's see a few examples of this.
    </p>

    <p>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 
    <code>git add</code>.  We can use <code>git status</code> to see what the
    state of our project is.
    </p>

<pre>
<b>$ git status -s</b>
<span class="red">??</span> README
<span class="red">??</span> hello.rb
</pre>

    So right now we have two untracked files.  We can now add them.

<pre>
<b>$ git add README hello.rb</b>
</pre>
    
    Now if we run <code>git status</code> again, we'll see that they've been
    added.

<pre>
<b>$ git status -s</b>
<span class="green">A</span>  README
<span class="green">A</span>  hello.rb
</pre>

    <p>OK, so now if we edit one of these files and run <code>git status</code>
    again, we will see something odd.</p>
<pre>
<b>$ vim README</b>
<b>$ git status -s</b>
<span class="green">A</span><span class="red">M</span> README
<span class="green">A</span>  hello.rb
</pre>

    <p>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 <code>git add</code>,
    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 <code>git add</code> command.
    </p>

    <p class="nutshell">
    <strong>In a nutshell</strong>, 
    you run <code>git add</code> 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.</p>

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


  </div>

</div>

<div class="box">
  <h2>
    <span class="docs">
      <a href="#">docs</a> &nbsp;
      <a href="#">book</a>
    </span>
    <a name="status">git status</a>
    <span class="desc">view the status of your files in the working directory and staging area</span>
  </h2>

  <div class="block">
    <p>As you saw in the <code>git add</code> 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 <code>git status</code> command. I demonstrated
    using it with the <code>-s</code> option, which gives you short output.
    Without that flag, the <code>git status</code> command will give you more
    context and hints.  Here is the same status output with and without the 
    <code>-s</code>.  The short output looks like this:
    </p>

<pre>
<b>$ git status -s</b>
<span class="green">A</span><span class="red">M</span> README
<span class="green">A</span>  hello.rb
</pre>

    Where the same status with the long output looks like this:

<pre>
<b>$ git status</b>
# On branch master
#
# Initial commit
#
# Changes to be committed:
#   (use "git rm --cached <file>..." to unstage)
#
# <span class="green">new file:   README</span>
# <span class="green">new file:   hello.rb</span>
#
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
# <span class="red">modified:   README</span>
#
</pre>

    <p>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.
    </p>

    <p>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.</p>

<pre>
<b>$ git status -s</b>
<span class="green">M</span>  README
 <span class="red">D</span> hello.rb
</pre>

    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 <code>git add</code> a second time, you'll see 
    this:

<pre>
<b>$ git status -s</b>
<span class="green">M</span><span class="red">M</span> README
 <span class="red">D</span> hello.rb
</pre>

    <p class="nutshell">
    <strong>In a nutshell</strong>, 
    you run <code>git status</code> 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.
    </p>

  </div>
</div>

<div class="box">
  <h2>
    <span class="docs">
      <a href="#">docs</a> &nbsp;
      <a href="#">book</a>
    </span>
    <a name="diff">git diff</a>
    <span class="desc">shows diff of what is staged and what is modified but unstaged</span>
  </h2>

  <div class="block">
    <p>There are two main uses of the <code>git diff</code> command.  One use we
    will describe here, the other we will describe later in the 
    <a href="/inspection">"Inspection and Comparison"</a>
    section. The way we're going to use it here is to describe the
    changes that are staged or modified on disk but unstaged.</p>

    <h4>
      git diff
      <small>show diff of unstaged changes</small>
    </h4>

    <p>Without any extra arguments, a simple <code>git diff</code> 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.
    </p>

<pre>
<b>$ vim hello.rb</b>
<b>$ git status -s</b>
 <span class="red">M</span> hello.rb
<b>$ git diff</b>
<span class="umber">diff --git a/hello.rb b/hello.rb
index d62ac43..8d15d50 100644
--- a/hello.rb
+++ b/hello.rb</span>
<span class="lblue">@@ -1,7 +1,7 @@</span>
 class HelloWorld
   
   def self.hello
<span class="red">-    puts "hello world"</span>
<span class="green">+    puts "hola mundo"</span>
   end
 
 end
</pre>

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

    <h4>
      git diff --cached
      <small>show diff of staged changes</small>
    </h4>

    <p>The <code>git diff --cached</code> 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 <code>hello.rb</code> in the example above, 
    <code>git diff</code> by itself won't show you any output because it will
    only show you what is <i>not yet</i> staged.
    </p>

<pre>
<b>$ git status -s</b>
 <span class="red">M</span> hello.rb
<b>$ git add hello.rb </b>
<b>$ git status -s</b>
<span class="green">M</span>  hello.rb
<b>$ git diff</b>
<b>$ </b>
</pre>

    <p>If you want to see the staged changes, you can run 
    <code>git diff --cached</code> instead.</p>

<pre>
<b>$ git status -s</b>
<span class="green">M</span>  hello.rb
<b>$ git diff</b>
<b>$ </b>
<b>$ git diff --cached</b>
<span class="umber">diff --git a/hello.rb b/hello.rb
index d62ac43..8d15d50 100644
--- a/hello.rb
+++ b/hello.rb</span>
<span class="lblue">@@ -1,7 +1,7 @@</span>
 class HelloWorld
   
   def self.hello
<span class="red">-    puts "hello world"</span>
<span class="green">+    puts "hola mundo"</span>
   end
 
 end
</pre>

    <h4>
      git diff HEAD
      <small>show diff of all staged or unstaged changes</small>
    </h4>

    <p>If you want to see both staged and unstaged changes together, you
    can run <code>git diff HEAD</code> - 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 
    <code>hello.rb</code> file then we'll have some changes staged and some
    changes unstaged.  Here are what all three <code>diff</code> commands
    will show you:</p>
<pre>
<b>$ vim hello.rb </b>
<b>$ git diff</b>
<span class="umber">diff --git a/hello.rb b/hello.rb
index 4f40006..2ae9ba4 100644
--- a/hello.rb
+++ b/hello.rb</span>
<span class="lblue">@@ -1,7 +1,7 @@</span>
 class HelloWorld
   
<span class="green">+  # says hello</span>
   def self.hello
     puts "hola mundo"
   end
 
 end
<b>$ git diff --cached</b>
<span class="umber">diff --git a/hello.rb b/hello.rb
index 2aabb6e..4f40006 100644
--- a/hello.rb
+++ b/hello.rb</span>
<span class="lblue">@@ -1,7 +1,7 @@</span>
 class HelloWorld
 
   def self.hello
<span class="red">-    puts "hello world"</span>
<span class="green">+    puts "hola mundo"</span>
   end
 
 end
<b>$ git diff HEAD</b>
<span class="umber">diff --git a/hello.rb b/hello.rb
index 2aabb6e..2ae9ba4 100644
--- a/hello.rb
+++ b/hello.rb</span>
<span class="lblue">@@ -1,7 +1,8 @@</span>
 class HelloWorld
 
<span class="green">+  # says hello</span>
   def self.hello
<span class="red">-    puts "hello world"</span>
<span class="green">+    puts "hola mundo"</span>
   end
 
 end
</pre>

    <h4>
      git diff --stat
      <small>show summary of changes instead of a full diff</small>
    </h4>

    <p>If we don't want the full diff output, but we want more than the
    <code>git status</code> output, we can use the <code>--stat</code>
    option, which will give us a summary of changes instead. Here is the
    same example as above, but using the <code>--stat</code> option instead.
    </p>
    
<pre>
<b>$ git status -s</b>
<span class="green">M</span><span class="red">M</span> hello.rb
<b>$ git diff --stat</b>
 hello.rb |    1 <span class="green">+</span>
 1 files changed, 1 insertions(+), 0 deletions(-)
<b>$ git diff --cached --stat</b>
 hello.rb |    2 <span class="green">+</span><span class="red">-</span>
 1 files changed, 1 insertions(+), 1 deletions(-)
<b>$ git diff HEAD --stat</b>
 hello.rb |    3 <span class="green">++</span><span class="red">-</span>
 1 files changed, 2 insertions(+), 1 deletions(-)
</pre>

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


    <p class="nutshell">
    <strong>In a nutshell</strong>, 
    you run <code>git diff</code> to see details of the <code>git status</code>
    command - <i>how</i> files have been modified or staged on a line by line
    basis. 
    </p>


  </div>
</div>

<div class="box">
  <h2>
    <span class="docs">
      <a href="#">docs</a> &nbsp;
      <a href="#">book</a>
    </span>
    <a name="commit">git commit</a>
    <span class="desc">records a snapshot of the staging area</span>
  </h2>

  <div class="block">

    <p>Now that you have staged the content you want to snapshot with the 
    <code>git add</code> command, you run <code>git commit</code> to actually
    record the snapshot.  Let's stage and commit all the changes to our 
    <code>hello.rb</code> file.  In this first example, we'll use the 
    <code>-m</code> option to provide the commit message on the command line.
    </p>

<pre>
<b>$ git add hello.rb </b>
<b>$ git status -s</b>
<span class="green">M</span>  hello.rb
<b>$ git commit -m 'my hola mundo changes'</b>
[master 68aa034] my hola mundo changes
 1 files changed, 2 insertions(+), 1 deletions(-)
</pre>

    <p>Now we have recorded the snapshot.  If we run <code>git status</code>
    again, we will see that we have a "clean working directory", which means
    that we have not made any changes since our last commit - there is no
    un-snapshotted work in our checkout.</p>

<pre>
<b>$ git status</b>
# On branch master
nothing to commit (working directory clean)
</pre>

    <p>If you leave off the <code>-m</code> option, Git will try to open a
    text editor for you to write your commit message.  In <code>vim</code>,
    which it will default to if it can find nothing else in your settings,
    the screen might look something like this:
    </p>

<pre>

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
# modified:   hello.rb
#
~
~
".git/COMMIT_EDITMSG" 9L, 257C
</pre>

    <p>At this point you add your actual commit message at the top of the
    document.  Any lines starting with '#' will be ignored - Git will put
    the output of the <code>git status</code> command in there for you as
    a reminder of what you have modified and staged.</p>

    <p>In general, it's very important to write a good commit message. 
    For open source projects, it's generally a rule to write your message
    more or less in this format:</p>
    
<pre>
Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); some git tools can get confused if you run the
two together.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded by a
   single space, with blank lines in between, but conventions vary
   here

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch master
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
# modified:   hello.rb
#
~
~
~
".git/COMMIT_EDITMSG" 25L, 884C written
</pre>

    <p class="aside">
    The commit message is very important. Since much of the power of
    Git is this flexibility in carefully crafting commits locally and then
    sharing them later, it is very powerful to be able to write three or
    four commits of logically seperate changes so that your work may be more
    easily peer reviewed.  Since there is a seperation between committing and
    pushing those changes, do take the time to make it easier for the people
    you are working with to see what you've done by putting each logically 
    seperate change in a seperate commit with a nice commit message so it
    is easier for them to see what you are doing and why.</p>

    <h4>
      git commit -a
      <small>automatically stage all tracked, modified files before the commit</small>
    </h4>

    <p>If you think the <code>git add</code> stage of the workflow is too 
    cumbersome, Git allows you to skip that part with the <code>-a</code> 
    option.  This basically tells Git to run <code>git add</code> on any file
    that is "tracked" - that is, any file that was in your last commit and
    has been modified.  This allows you to do a more Subversion style workflow
    if you want, simply editing files and then running <code>git commit -a</code>
    when you want to snapshot everything that has been changed.  You still need
    to run <code>git add</code> to start tracking new files, though, just like
    Subversion.
    </p>

<pre>
<b>$ vim hello.rb</b>
<b>$ git status -s</b>
 <span class="red">M</span>  hello.rb
<b>$ git commit -m 'changes to hello file'</b>
# On branch master
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified:   hello.rb
#
<span class="hl">no changes added to commit (use "git add" and/or "git commit -a")</span>
<b>$ git commit -am 'changes to hello file'</b>
[master 78b2670] changes to hello file
 1 files changed, 2 insertions(+), 1 deletions(-)
</pre>

    <p>Notice how if you don't stage any changes and then run 
    <code>git commit</code>, Git will simply give you the output of the
    <code>git status</code> command, reminding you that nothing is staged.
    I've highlighted the important part of that message, saying that nothing
    is added to be committed.   If you use <code>-a</code>, it will add and
    commit everything at once.
    </p>

    <p>This now lets you complete the entire snapshotting workflow - you
    make changes to your files, then use <code>git add</code> to stage
    files you want to change, <code>git status</code> and <code>git diff</code>
    to see what you've changed, and then finally <code>git commit</code>
    to actually record the snapshot forever.</p>

    <p class="nutshell">
    <strong>In a nutshell</strong>, 
    you run <code>git commit</code> to record the snapshot of your staged
    content.  This snapshot can then be compared, shared and reverted to
    if you need to.
    </p>

  </div>
</div>

<p><a href="/basic">On to Branching and Merging &#187;</a></p>