Undocumented git-diff syntax

Undocumented git-diff syntax

[Yann Dirson]

When trying "just to see it it would work", I noticed that the
following syntax appears to do what it looks like it should do.

git diff v1.7.3-rc0:Documentation/RelNotes-1.7.3.txt v1.7.3:Documentation/RelNotes/1.7.3.txt

It is a useful thing, but I could not find described in the manpage.  I have not dig this
part of diff yet, and maybe someone would have already a description of it (does it simply allow
to diff two arbitrary blobs ?).  Is it here just by some magic side-effect ? :)

Another thought: if we can already compare arbitrary blobs, maybe it would not be so hard to
extend it to take arbitrary contents that are not stored as blobs yet ?  (a quick hack would be to
insert an object for them, but that does not look too clean...).  As a use-case, I'm often found generating diffs from within custom scripts, from contents derived from a git repo, but can't use all the bells and whistles (--color, --color-words, etc), just because I have to use plain diff;
that makes the output of those scripts very inconsistent with native git commands.

Would there be any objections to moving into that direction ?

-- 
Yann Dirson - Bertin Technologies

Re: Undocumented git-diff syntax

[Santi Béjar]

On Mon, Oct 11, 2010 at 3:03 PM, Yann Dirson <dirson@bertin.fr> wrote:
[...]
>
> Another thought: if we can already compare arbitrary blobs, maybe it would not be so hard to
> extend it to take arbitrary contents that are not stored as blobs yet ?  (a quick hack would be to
> insert an object for them, but that does not look too clean...).  As a use-case, I'm often found generating diffs from within custom scripts, from contents derived from a git repo, but can't use all the bells and whistles (--color, --color-words, etc), just because I have to use plain diff;
> that makes the output of those scripts very inconsistent with native git commands.

Are you talking about "git diff --no-index"?

HTH,
Santi

Re: Undocumented git-diff syntax

[Yann Dirson]

On Mon, 11 Oct 2010 15:59:18 +0200
Santi Béjar <santi@agolina.net> wrote:

> On Mon, Oct 11, 2010 at 3:03 PM, Yann Dirson <dirson@bertin.fr> wrote:
> [...]
> >
> > Another thought: if we can already compare arbitrary blobs, maybe
> > it would not be so hard to extend it to take arbitrary contents
> > that are not stored as blobs yet ?  (a quick hack would be to
> > insert an object for them, but that does not look too clean...).
> >  As a use-case, I'm often found generating diffs from within custom
> > scripts, from contents derived from a git repo, but can't use all
> > the bells and whistles (--color, --color-words, etc), just because
> > I have to use plain diff; that makes the output of those scripts
> > very inconsistent with native git commands.
> 
> Are you talking about "git diff --no-index"?

Oh, right.  That's what it takes to read only the 1st paragraph for
each synopsis:

|If exactly two paths are given, and at least one is untracked,
|compare the two files / directories. This behavior can be
|forced by --no-index.

OTOH, that appears not to be 100% accurate (my tests would have
shown me): although --no-index does give me the expected results when
one or two of the files are untracked, I have to explicitely add it,
which seem to contradict this part of the doc.

That said, this two-path construct would surely deserve its own
synopsis.

To get back to my initial opuzzlement, maybe the behaviour I found is
also a special case that sets --no-index ?

-- 
Yann Dirson - Bertin Technologies

Re: Undocumented git-diff syntax

[Santi Béjar]

On Mon, Oct 11, 2010 at 4:17 PM, Yann Dirson <dirson@bertin.fr> wrote:
> On Mon, 11 Oct 2010 15:59:18 +0200
> Santi Béjar <santi@agolina.net> wrote:
>
>> On Mon, Oct 11, 2010 at 3:03 PM, Yann Dirson <dirson@bertin.fr> wrote:
>> [...]
>> >
>> > Another thought: if we can already compare arbitrary blobs, maybe
>> > it would not be so hard to extend it to take arbitrary contents
>> > that are not stored as blobs yet ?  (a quick hack would be to
>> > insert an object for them, but that does not look too clean...).
>> >  As a use-case, I'm often found generating diffs from within custom
>> > scripts, from contents derived from a git repo, but can't use all
>> > the bells and whistles (--color, --color-words, etc), just because
>> > I have to use plain diff; that makes the output of those scripts
>> > very inconsistent with native git commands.
>>
>> Are you talking about "git diff --no-index"?
>
> Oh, right.  That's what it takes to read only the 1st paragraph for
> each synopsis:
>
> |If exactly two paths are given, and at least one is untracked,
> |compare the two files / directories. This behavior can be
> |forced by --no-index.
>
> OTOH, that appears not to be 100% accurate (my tests would have
> shown me): although --no-index does give me the expected results when
> one or two of the files are untracked, I have to explicitely add it,
> which seem to contradict this part of the doc.

You are right.

Additionally these two are not equivalent:

$ git diff Makefile ../Makefile
fatal: '../Makefile' is outside repository

$ git diff Makefile $HOME/Makefile
diff --git ...

(with --no-index both work)

>
> That said, this two-path construct would surely deserve its own
> synopsis.

+1

Santi

[PATCH 0/4] Re: Undocumented git-diff syntax

[Jonathan Nieder]

Yann Dirson wrote:

> OTOH, that appears not to be 100% accurate (my tests would have
> shown me): although --no-index does give me the expected results when
> one or two of the files are untracked, I have to explicitely add it,
> which seem to contradict this part of the doc.

Yep, the doc is out of date.  Luckily I had a series updating it
rotting in my local tree.

Patch 5 gives --no-index its own prominent mention in the DESCRIPTION
section.  I suspect that is a bad idea --- too much to learn for new
users --- and that the description should go under OPTIONS, but I ran
out of time.

Maybe patches 1-4 can help?

Jonathan Nieder (5):
  Documentation: gitrevisions is in section 7
  Documentation: diff can compare blobs
  Documentation: expand 'git diff' SEE ALSO section
  Documentation: update "git diff --no-index" description
  Documentation: expand diff --no-index description

 Documentation/git-cat-file.txt         |    2 +-
 Documentation/git-check-ref-format.txt |    2 +-
 Documentation/git-cherry-pick.txt      |    2 +-
 Documentation/git-diff.txt             |   36 ++++++++++++++++++++++++--------
 Documentation/git-fast-import.txt      |    2 +-
 Documentation/git-format-patch.txt     |    2 +-
 Documentation/git-log.txt              |    2 +-
 Documentation/git-push.txt             |    2 +-
 Documentation/git-reflog.txt           |    2 +-
 Documentation/git-revert.txt           |    2 +-
 Documentation/git-show-branch.txt      |    2 +-
 Documentation/git-show.txt             |    2 +-
 Documentation/git.txt                  |    2 +-
 Documentation/gitcore-tutorial.txt     |    2 +-
 Documentation/gitk.txt                 |    2 +-
 Documentation/user-manual.txt          |    8 +++---
 16 files changed, 45 insertions(+), 27 deletions(-)

-- 
1.7.2.3

[PATCH 1/5] Documentation: gitrevisions is in section 7

[Jonathan Nieder]

Fix references to gitrevisions(1) in the manual pages and HTML
documentation.

In practice, this will not matter much unless someone tries to use a
hard copy of the git reference manual.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-cat-file.txt         |    2 +-
 Documentation/git-check-ref-format.txt |    2 +-
 Documentation/git-cherry-pick.txt      |    2 +-
 Documentation/git-diff.txt             |    4 ++--
 Documentation/git-fast-import.txt      |    2 +-
 Documentation/git-format-patch.txt     |    2 +-
 Documentation/git-log.txt              |    2 +-
 Documentation/git-push.txt             |    2 +-
 Documentation/git-reflog.txt           |    2 +-
 Documentation/git-revert.txt           |    2 +-
 Documentation/git-show-branch.txt      |    2 +-
 Documentation/git-show.txt             |    2 +-
 Documentation/git.txt                  |    2 +-
 Documentation/gitcore-tutorial.txt     |    2 +-
 Documentation/gitk.txt                 |    2 +-
 Documentation/user-manual.txt          |    8 ++++----
 16 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
index a3f56b0..544ba7b 100644
--- a/Documentation/git-cat-file.txt
+++ b/Documentation/git-cat-file.txt
@@ -27,7 +27,7 @@ OPTIONS
 <object>::
 	The name of the object to show.
 	For a more complete list of ways to spell object names, see
-	the "SPECIFYING REVISIONS" section in linkgit:gitrevisions[1].
+	the "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
 
 -t::
 	Instead of the content, show the object type identified by
diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt
index f5c2e06..205d83d 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -49,7 +49,7 @@ git imposes the following rules on how references are named:
 These rules make it easy for shell script based tools to parse
 reference names, pathname expansion by the shell when a reference name is used
 unquoted (by mistake), and also avoids ambiguities in certain
-reference name expressions (see linkgit:gitrevisions[1]):
+reference name expressions (see linkgit:gitrevisions[7]):
 
 . A double-dot `..` is often used as in `ref1..ref2`, and in some
   contexts this notation means `{caret}ref1 ref2` (i.e. not in
diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt
index 2cef579..3c96fa8 100644
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@ -21,7 +21,7 @@ OPTIONS
 <commit>...::
 	Commits to cherry-pick.
 	For a more complete list of ways to spell commits, see
-	linkgit:gitrevisions[1].
+	linkgit:gitrevisions[7].
 	Sets of commits can be passed but no traversal is done by
 	default, as if the '--no-walk' option was specified, see
 	linkgit:git-rev-list[1].
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 08fd409..481a33c 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -68,11 +68,11 @@ for the last two forms that use ".." notations, can be any
 <tree-ish>.
 
 For a more complete list of ways to spell <commit>, see
-"SPECIFYING REVISIONS" section in linkgit:gitrevisions[1].
+"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
 However, "diff" is about comparing two _endpoints_, not ranges,
 and the range notations ("<commit>..<commit>" and
 "<commit>\...<commit>") do not mean a range as defined in the
-"SPECIFYING RANGES" section in linkgit:gitrevisions[1].
+"SPECIFYING RANGES" section in linkgit:gitrevisions[7].
 
 OPTIONS
 -------
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 966ba4f..2c6ad5b 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -439,7 +439,7 @@ Marks must be declared (via `mark`) before they can be used.
 * A complete 40 byte or abbreviated commit SHA-1 in hex.
 
 * Any valid Git SHA-1 expression that resolves to a commit.  See
-  ``SPECIFYING REVISIONS'' in linkgit:gitrevisions[1] for details.
+  ``SPECIFYING REVISIONS'' in linkgit:gitrevisions[7] for details.
 
 The special case of restarting an incremental import from the
 current branch value should be written as:
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 4b3f5ba..a00b783 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -39,7 +39,7 @@ There are two ways to specify which commits to operate on.
    that leads to the <since> to be output.
 
 2. Generic <revision range> expression (see "SPECIFYING
-   REVISIONS" section in linkgit:gitrevisions[1]) means the
+   REVISIONS" section in linkgit:gitrevisions[7]) means the
    commits in the specified range.
 
 The first rule takes precedence in the case of a single <commit>.  To
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index c213bdb..6d40f00 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -31,7 +31,7 @@ OPTIONS
 	either <since> or <until> is omitted, it defaults to
 	`HEAD`, i.e. the tip of the current branch.
 	For a more complete list of ways to spell <since>
-	and <until>, see linkgit:gitrevisions[1].
+	and <until>, see linkgit:gitrevisions[7].
 
 --follow::
 	Continue listing the history of a file beyond renames
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 020955f..e11660a 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -41,7 +41,7 @@ OPTIONS[[OPTIONS]]
 +
 The <src> is often the name of the branch you would want to push, but
 it can be any arbitrary "SHA-1 expression", such as `master~4` or
-`HEAD` (see linkgit:gitrevisions[1]).
+`HEAD` (see linkgit:gitrevisions[7]).
 +
 The <dst> tells which ref on the remote side is updated with this
 push. Arbitrary expressions cannot be used here, an actual ref must
diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt
index 5a0451a..e50bd9b 100644
--- a/Documentation/git-reflog.txt
+++ b/Documentation/git-reflog.txt
@@ -40,7 +40,7 @@ see linkgit:git-log[1].
 The reflog is useful in various git commands, to specify the old value
 of a reference. For example, `HEAD@\{2\}` means "where HEAD used to be
 two moves ago", `master@\{one.week.ago\}` means "where master used to
-point to one week ago", and so on. See linkgit:gitrevisions[1] for
+point to one week ago", and so on. See linkgit:gitrevisions[7] for
 more details.
 
 To delete single entries from the reflog, use the subcommand "delete"
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index b7d9ef7..f40984d 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -31,7 +31,7 @@ OPTIONS
 <commit>...::
 	Commits to revert.
 	For a more complete list of ways to spell commit names, see
-	linkgit:gitrevisions[1].
+	linkgit:gitrevisions[7].
 	Sets of commits can also be given but no traversal is done by
 	default, see linkgit:git-rev-list[1] and its '--no-walk'
 	option.
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 6453263..8dbcf1a 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -32,7 +32,7 @@ no <rev> nor <glob> is given on the command line.
 OPTIONS
 -------
 <rev>::
-	Arbitrary extended SHA1 expression (see linkgit:gitrevisions[1])
+	Arbitrary extended SHA1 expression (see linkgit:gitrevisions[7])
 	that typically names a branch head or a tag.
 
 <glob>::
diff --git a/Documentation/git-show.txt b/Documentation/git-show.txt
index 0002bfb..2049c60 100644
--- a/Documentation/git-show.txt
+++ b/Documentation/git-show.txt
@@ -36,7 +36,7 @@ OPTIONS
 <object>...::
 	The names of objects to show.
 	For a more complete list of ways to spell object names, see
-	"SPECIFYING REVISIONS" section in linkgit:gitrevisions[1].
+	"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
 
 include::pretty-options.txt[]
 
diff --git a/Documentation/git.txt b/Documentation/git.txt
index dd57bdc..b46c6f6 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -495,7 +495,7 @@ HEAD::
 	(i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
 
 For a more complete list of ways to spell object names, see
-"SPECIFYING REVISIONS" section in linkgit:gitrevisions[1].
+"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
 
 
 File/Directory Structure
diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt
index 5e9c5eb..c27d086 100644
--- a/Documentation/gitcore-tutorial.txt
+++ b/Documentation/gitcore-tutorial.txt
@@ -971,7 +971,7 @@ commits from the master branch.  The string inside brackets
 before the commit log message is a short name you can use to
 name the commit.  In the above example, 'master' and 'mybranch'
 are branch heads.  'master^' is the first parent of 'master'
-branch head.  Please see linkgit:gitrevisions[1] if you want to
+branch head.  Please see linkgit:gitrevisions[7] if you want to
 see more complex cases.
 
 [NOTE]
diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 05ac1c7..e21bac4 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -69,7 +69,7 @@ frequently used options.
 	the form "'<from>'..'<to>'" to show all revisions between '<from>' and
 	back to '<to>'. Note, more advanced revision selection can be applied.
 	For a more complete list of ways to spell object names, see
-	linkgit:gitrevisions[1].
+	linkgit:gitrevisions[7].
 
 <path>...::
 
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index ce45bfc..5b6de22 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -397,7 +397,7 @@ is usually a shortcut for the HEAD branch in the repository "origin".
 For the complete list of paths which git checks for references, and
 the order it uses to decide which to choose when there are multiple
 references with the same shorthand name, see the "SPECIFYING
-REVISIONS" section of linkgit:gitrevisions[1].
+REVISIONS" section of linkgit:gitrevisions[7].
 
 [[Updating-a-repository-With-git-fetch]]
 Updating a repository with git fetch
@@ -568,7 +568,7 @@ We have seen several ways of naming commits already:
 	- HEAD: refers to the head of the current branch
 
 There are many more; see the "SPECIFYING REVISIONS" section of the
-linkgit:gitrevisions[1] man page for the complete list of ways to
+linkgit:gitrevisions[7] man page for the complete list of ways to
 name revisions.  Some examples:
 
 -------------------------------------------------
@@ -909,7 +909,7 @@ commits reachable from some head but not from any tag in the repository:
 $ gitk $( git show-ref --heads ) --not  $( git show-ref --tags )
 -------------------------------------------------
 
-(See linkgit:gitrevisions[1] for explanations of commit-selecting
+(See linkgit:gitrevisions[7] for explanations of commit-selecting
 syntax such as `--not`.)
 
 [[making-a-release]]
@@ -1635,7 +1635,7 @@ you've checked out.
 The reflogs are kept by default for 30 days, after which they may be
 pruned.  See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn
 how to control this pruning, and see the "SPECIFYING REVISIONS"
-section of linkgit:gitrevisions[1] for details.
+section of linkgit:gitrevisions[7] for details.
 
 Note that the reflog history is very different from normal git history.
 While normal history is shared by every repository that works on the
-- 
1.7.2.3

[PATCH 2/4] Documentation: diff can compare blobs

[Jonathan Nieder]

Meanwhile, there is no plumbing command to compare two blobs.
Strange.

Reported-by: Yann Dirson <dirson@bertin.fr>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-diff.txt |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 481a33c..db2c6c2 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -64,8 +64,9 @@ forced by --no-index.
 
 Just in case if you are doing something exotic, it should be
 noted that all of the <commit> in the above description, except
-for the last two forms that use ".." notations, can be any
-<tree-ish>.
+in the last two forms that use ".." notations, can be any
+<tree>.  The third form ('git diff <commit> <commit>') can also
+be used to compare two <blob> objects.
 
 For a more complete list of ways to spell <commit>, see
 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
-- 
1.7.2.3

[PATCH 3/4] Documentation: expand 'git diff' SEE ALSO section

[Jonathan Nieder]

Point in many directions in the hope of helping the reader find what
is needed more quickly.

This commit also removes the summary attached to the SEE ALSO entry
for difftool, to avoid making the SEE ALSO list too verbose.  If the
reader wants a summary of the commands referred to, she can always
look to the top of the named pages or to the table of contents on the
main git(1) page.

Suggested-by: Goswin von Brederlow <goswin-v-b@web.de>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-diff.txt |    8 ++++++--
 1 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index db2c6c2..fe34d4e 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -160,8 +160,12 @@ rewrites (very expensive).
 
 SEE ALSO
 --------
-linkgit:git-difftool[1]::
-	Show changes using common diff tools
+diff(1),
+linkgit:git-difftool[1],
+linkgit:git-log[1],
+linkgit:gitdiffcore[7],
+linkgit:git-format-patch[1],
+linkgit:git-apply[1]
 
 Author
 ------
-- 
1.7.2.3

[PATCH 4/4] Documentation: update "git diff --no-index" description

[Jonathan Nieder]

Originally "git diff --no-index" triggered for untracked files within
the tracked tree, but with v1.5.6-rc1~41 (Merge branch
'jc/diff-no-no-index, 2008-05-26) the command changed to only trigger
when paths outside the tracked tree are mentioned.

Reported-by: Yann Dirson <dirson@bertin.fr>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-diff.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index fe34d4e..dd1fb32 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -23,9 +23,9 @@ tree and the index file, or the index file and the working tree.
 	further add to the index but you still haven't.  You can
 	stage these changes by using linkgit:git-add[1].
 +
-If exactly two paths are given, and at least one is untracked,
-compare the two files / directories. This behavior can be
-forced by --no-index.
+If exactly two paths are given and at least one points outside
+the current repository, 'git diff' will compare the two files /
+directories. This behavior can be forced by --no-index.
 
 'git diff' [--options] --cached [<commit>] [--] [<path>...]::
 
-- 
1.7.2.3

[RFC/PATCH 5/4] Documentation: flesh out diff --no-index description

[Jonathan Nieder]

Explain what diff --no-index is used for in more detail.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-diff.txt |   21 +++++++++++++++++----
 1 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index dd1fb32..6700e8c 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -25,7 +25,7 @@ tree and the index file, or the index file and the working tree.
 +
 If exactly two paths are given and at least one points outside
 the current repository, 'git diff' will compare the two files /
-directories. This behavior can be forced by --no-index.
+directories (see --no-index below).
 
 'git diff' [--options] --cached [<commit>] [--] [<path>...]::
 
@@ -62,11 +62,24 @@ directories. This behavior can be forced by --no-index.
 	"git diff $(git-merge-base A B) B".  You can omit any one
 	of <commit>, which has the same effect as using HEAD instead.
 
+'git diff' [--options] --no-index [--] <path> <path>::
+
+	In this form, 'git diff' will compare a pair of files or
+	directories that are not necessarily being managed by git.
+	The tracked content of files in the index and the object
+	database are ignored.
++
+In other words, this form allows 'git diff' to be used as a
+traditional 'diff' command (plus the familiar extras like --check,
+color, pagination, automatic use of -r, --stat/--name-status,
+--pickaxe, --binary, copy/rename detection, -Oorderfile, and
+--patience).
+
 Just in case if you are doing something exotic, it should be
 noted that all of the <commit> in the above description, except
-in the last two forms that use ".." notations, can be any
-<tree>.  The third form ('git diff <commit> <commit>') can also
-be used to compare two <blob> objects.
+in the two forms that use ".." notations, can be any <tree>.
+The third form ('git diff <commit> <commit>') can also be used
+to compare two <blob> objects.
 
 For a more complete list of ways to spell <commit>, see
 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
-- 
1.7.2.3

Re: Undocumented git-diff syntax

[Jakub Narebski]

Yann Dirson <dirson@bertin.fr> writes:

> That said, this two-path construct would surely deserve its own
> synopsis.

Something like this?  Just kidding...


 SYNOPSIS
 --------
+[verse]
 'git diff' [<common diff options>] <commit>{0,2} [--] [<path>...]
+'git diff' [<common diff options>] <tree-ish> <tree-ish> [--] [<path>...]
+'git diff' [<common diff options>] <blob-or-path> <blob-or-path>

Possibly that <tree-ish> can be also a <directory> (on filesystem).

You can e.g. use

  git diff HEAD:git-gui/ 00e9de7^^
           ^^^^^^^^^^^^^ ~~~~~~~~~
           \-- tree       \-- commit (in subtree-merged history)

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: [PATCH 0/4] Re: Undocumented git-diff syntax

[Yann Dirson]

On Mon, Oct 11, 2010 at 11:02:24AM -0500, Jonathan Nieder wrote:
> Yann Dirson wrote:
> 
> > OTOH, that appears not to be 100% accurate (my tests would have
> > shown me): although --no-index does give me the expected results when
> > one or two of the files are untracked, I have to explicitely add it,
> > which seem to contradict this part of the doc.
> 
> Yep, the doc is out of date.  Luckily I had a series updating it
> rotting in my local tree.
> 
> Patch 5 gives --no-index its own prominent mention in the DESCRIPTION
> section.  I suspect that is a bad idea --- too much to learn for new
> users --- and that the description should go under OPTIONS, but I ran
> out of time.

OTOH, not making it prominent does not help users to realize it is
there.  Keeping it last, or maybe in a "less frequently used" section
looks fine to me - eg. the <commit>...<commit> form could join it into
such a section

> Maybe patches 1-4 can help?

They make things much more clear, thanks.


So it looks like after this doc patch series, we're left with a couple
of bugs:

* the "fatal: '../Makefile' is outside repository" seen by Santi
* the following which should probably complain that the files cannot
  be compared:

$ echo a>a;echo b>b
$ git diff a b; echo $?
0

At least, I can't think of them as meaningful behaviours.

Best regards,
-- 
Yann

Re: [PATCH 1/5] Documentation: gitrevisions is in section 7

[Sverre Rabbelier]

Heya,

On Mon, Oct 11, 2010 at 18:03, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Fix references to gitrevisions(1) in the manual pages and HTML
> documentation.

Nice catch. How did you find this? Have you check there aren't similar
references that are wrong?

-- 
Cheers,

Sverre Rabbelier

Re: [PATCH 0/4] Re: Undocumented git-diff syntax

[Sverre Rabbelier]

Heya,

On Mon, Oct 11, 2010 at 18:02, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Patch 5 gives --no-index its own prominent mention in the DESCRIPTION
> section.  I suspect that is a bad idea --- too much to learn for new
> users --- and that the description should go under OPTIONS, but I ran
> out of time.

Well, that answers my question in [1/5], *mutters at gmail's lack of a
tree view*.

-- 
Cheers,

Sverre Rabbelier

Re: [RFC/PATCH 5/4] Documentation: flesh out diff --no-index description

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> +'git diff' [--options] --no-index [--] <path> <path>::
> +
> +	In this form, 'git diff' will compare a pair of files or
> +	directories that are not necessarily being managed by git.
> +	The tracked content of files in the index and the object
> +	database are ignored.
> ++
> +In other words, this form allows 'git diff' to be used as a
> +traditional 'diff' command (plus the familiar extras like --check,
> +color, pagination, automatic use of -r, --stat/--name-status,
> +--pickaxe, --binary, copy/rename detection, -Oorderfile, and
> +--patience).

My initial knee-jerk reaction was "how would -C/-M/-O be useful when you
can only give two paths?"  Perhaps it would become easier to read if we
phrased it like this?

    This form allows 'git diff' to be used as a better 'diff' command,
    with extras like whitespace checks (--check), coloring (--color),
    wordwise diff (--color-words), pagination, diffstat (--stat), binary
    patch (--binary), alternative algorithm (e.g. --patience).  In
    addition, when comparing two directories, rename detection (-M) may
    come in handy.

Note, by the way, that I didn't verify all the claims the above makes.