git-tar-tree: no more void pointer arithmetic

[git.git] / Documentation / git-diff.txt

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index cadaf59..7ab2080 100644 (file)
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -3,7 +3,7 @@ git-diff(1)
 
 NAME
 ----
-git-diff - Show changes between commits, commit and working tree, etc.
+git-diff - Show changes between commits, commit and working tree, etc
 
 
 SYNOPSIS
@@ -17,14 +17,16 @@ ent and the index file, or the index file and the working tree.
 The combination of what is compared with what is determined by
 the number of ents given to the command.
 
-`----------------`--------`-----------------------------`------------------
-Number of ents    Options  What's Compared               Underlying command
----------------------------------------------------------------------------
-0                 -        index file and working tree   git-diff-files
-1                 --cached ent and index file            git-diff-index
-1                 -        ent and working tree          git-diff-index
-2                 -        two ents                      git-diff-tree
----------------------------------------------------------------------------
+* When no <ent> is given, the working tree and the index
+  file is compared, using `git-diff-files`.
+
+* When one <ent> is given, the working tree and the named
+  tree is compared, using `git-diff-index`.  The option
+  `--cached` can be given to compare the index file and
+  the named tree.
+
+* When two <ent>s are given, these two trees are compared
+  using `git-diff-tree`.
 
 OPTIONS
 -------
@@ -38,6 +40,68 @@ OPTIONS
        commands.
 
 
+EXAMPLES
+--------
+
+Various ways to check your working tree::
++
+------------
+$ git diff            <1>
+$ git diff --cached   <2>
+$ git diff HEAD       <3>
+------------
++
+<1> changes in the working tree since your last git-update-index.
+<2> changes between the index and your last commit; what you
+would be committing if you run "git commit" without "-a" option.
+<3> changes in the working tree since your last commit; what you
+would be committing if you run "git commit -a"
+
+Comparing with arbitrary commits::
++
+------------
+$ git diff test            <1>
+$ git diff HEAD -- ./test  <2>
+$ git diff HEAD^ HEAD      <3>
+------------
++
+<1> instead of using the tip of the current branch, compare with the
+tip of "test" branch.
+<2> instead of comparing with the tip of "test" branch, compare with
+the tip of the current branch, but limit the comparison to the
+file "test".
+<3> compare the version before the last commit and the last commit.
+
+
+Limiting the diff output::
++
+------------
+$ git diff --diff-filter=MRC            <1>
+$ git diff --name-status -r             <2>
+$ git diff arch/i386 include/asm-i386   <3>
+------------
++
+<1> show only modification, rename and copy, but not addition
+nor deletion.
+<2> show only names and the nature of change, but not actual
+diff output.  --name-status disables usual patch generation
+which in turn also disables recursive behavior, so without -r
+you would only see the directory name if there is a change in a
+file in a subdirectory.
+<3> limit diff output to named subtrees.
+
+Munging the diff output::
++
+------------
+$ git diff --find-copies-harder -B -C  <1>
+$ git diff -R                          <2>
+------------
++
+<1> spend extra cycles to find renames, copies and complete
+rewrites (very expensive).
+<2> output diff in reverse.
+
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org>