572 lines
18 KiB
HTML
572 lines
18 KiB
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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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 »</a></p>
|
|
|