{"thread":{"id":"25417","subject":"Undocumented git-diff syntax","startedAt":"2010-10-11T13:03:42Z","lastAt":"2010-10-13T22:40:29Z","messageCount":15,"participants":["Yann Dirson","Santi Béjar","Jonathan Nieder","Jakub Narebski","Sverre Rabbelier","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"153230","messageId":"20101011150342.292ad725@chalon.bertin.fr","threadId":"25417","inReplyTo":null,"subject":"Undocumented git-diff syntax","fromName":"Yann Dirson","fromEmail":"dirson@bertin.fr","sentAt":"2010-10-11T13:03:42Z","receivedAt":"2010-10-11T13:03:42Z","isPatch":false,"sender":{"key":"dirson@bertin.fr","avatar":null},"body":"When trying \"just to see it it would work\", I noticed that the\nfollowing syntax appears to do what it looks like it should do.\n\ngit diff v1.7.3-rc0:Documentation/RelNotes-1.7.3.txt v1.7.3:Documentation/RelNotes/1.7.3.txt\n\nIt is a useful thing, but I could not find described in the manpage. I have not dig this\npart of diff yet, and maybe someone would have already a description of it (does it simply allow\nto diff two arbitrary blobs ?). Is it here just by some magic side-effect ? :)\n\nAnother thought: if we can already compare arbitrary blobs, maybe it would not be so hard to\nextend it to take arbitrary contents that are not stored as blobs yet ? (a quick hack would be to\ninsert 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;\nthat makes the output of those scripts very inconsistent with native git commands.\n\nWould there be any objections to moving into that direction ?\n\n-- \nYann Dirson - Bertin Technologies\n"},{"id":"153232","messageId":"AANLkTinqPiGf1nbo0oOvDD5edgLBdO8xZfjGeFC4q0MU@mail.gmail.com","threadId":"25417","inReplyTo":"20101011150342.292ad725@chalon.bertin.fr","subject":"Re: Undocumented git-diff syntax","fromName":"Santi Béjar","fromEmail":"santi@agolina.net","sentAt":"2010-10-11T13:59:18Z","receivedAt":"2010-10-11T13:59:18Z","isPatch":false,"sender":{"key":"santi@agolina.net","avatar":null},"body":"On Mon, Oct 11, 2010 at 3:03 PM, Yann Dirson wrote:\n[...]\n>\n> Another thought: if we can already compare arbitrary blobs, maybe it would not be so hard to\n> extend it to take arbitrary contents that are not stored as blobs yet ?  (a quick hack would be to\n> 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;\n> that makes the output of those scripts very inconsistent with native git commands.\n\nAre you talking about \"git diff --no-index\"?\n\nHTH,\nSanti\n"},{"id":"153233","messageId":"20101011161721.35940919@chalon.bertin.fr","threadId":"25417","inReplyTo":"AANLkTinqPiGf1nbo0oOvDD5edgLBdO8xZfjGeFC4q0MU@mail.gmail.com","subject":"Re: Undocumented git-diff syntax","fromName":"Yann Dirson","fromEmail":"dirson@bertin.fr","sentAt":"2010-10-11T14:17:21Z","receivedAt":"2010-10-11T14:17:21Z","isPatch":false,"sender":{"key":"dirson@bertin.fr","avatar":null},"body":"On Mon, 11 Oct 2010 15:59:18 +0200\nSanti Béjar wrote:\n\n> On Mon, Oct 11, 2010 at 3:03 PM, Yann Dirson wrote:\n> [...]\n> >\n> > Another thought: if we can already compare arbitrary blobs, maybe\n> > it would not be so hard to extend it to take arbitrary contents\n> > that are not stored as blobs yet ?  (a quick hack would be to\n> > insert an object for them, but that does not look too clean...).\n> >  As a use-case, I'm often found generating diffs from within custom\n> > scripts, from contents derived from a git repo, but can't use all\n> > the bells and whistles (--color, --color-words, etc), just because\n> > I have to use plain diff; that makes the output of those scripts\n> > very inconsistent with native git commands.\n> \n> Are you talking about \"git diff --no-index\"?\n\nOh, right. That's what it takes to read only the 1st paragraph for\neach synopsis:\n\n|If exactly two paths are given, and at least one is untracked,\n|compare the two files / directories. This behavior can be\n|forced by --no-index.\n\nOTOH, that appears not to be 100% accurate (my tests would have\nshown me): although --no-index does give me the expected results when\none or two of the files are untracked, I have to explicitely add it,\nwhich seem to contradict this part of the doc.\n\nThat said, this two-path construct would surely deserve its own\nsynopsis.\n\nTo get back to my initial opuzzlement, maybe the behaviour I found is\nalso a special case that sets --no-index ?\n\n-- \nYann Dirson - Bertin Technologies\n"},{"id":"153234","messageId":"AANLkTikBxBMm-Pv_8M7SxEugQ5pdksm_k=ihAa4toVap@mail.gmail.com","threadId":"25417","inReplyTo":"20101011161721.35940919@chalon.bertin.fr","subject":"Re: Undocumented git-diff syntax","fromName":"Santi Béjar","fromEmail":"santi@agolina.net","sentAt":"2010-10-11T14:52:46Z","receivedAt":"2010-10-11T14:52:46Z","isPatch":false,"sender":{"key":"santi@agolina.net","avatar":null},"body":"On Mon, Oct 11, 2010 at 4:17 PM, Yann Dirson wrote:\n> On Mon, 11 Oct 2010 15:59:18 +0200\n> Santi Béjar wrote:\n>\n>> On Mon, Oct 11, 2010 at 3:03 PM, Yann Dirson wrote:\n>> [...]\n>> >\n>> > Another thought: if we can already compare arbitrary blobs, maybe\n>> > it would not be so hard to extend it to take arbitrary contents\n>> > that are not stored as blobs yet ?  (a quick hack would be to\n>> > insert an object for them, but that does not look too clean...).\n>> >  As a use-case, I'm often found generating diffs from within custom\n>> > scripts, from contents derived from a git repo, but can't use all\n>> > the bells and whistles (--color, --color-words, etc), just because\n>> > I have to use plain diff; that makes the output of those scripts\n>> > very inconsistent with native git commands.\n>>\n>> Are you talking about \"git diff --no-index\"?\n>\n> Oh, right.  That's what it takes to read only the 1st paragraph for\n> each synopsis:\n>\n> |If exactly two paths are given, and at least one is untracked,\n> |compare the two files / directories. This behavior can be\n> |forced by --no-index.\n>\n> OTOH, that appears not to be 100% accurate (my tests would have\n> shown me): although --no-index does give me the expected results when\n> one or two of the files are untracked, I have to explicitely add it,\n> which seem to contradict this part of the doc.\n\nYou are right.\n\nAdditionally these two are not equivalent:\n\n$ git diff Makefile ../Makefile\nfatal: '../Makefile' is outside repository\n\n$ git diff Makefile $HOME/Makefile\ndiff --git ...\n\n(with --no-index both work)\n\n>\n> That said, this two-path construct would surely deserve its own\n> synopsis.\n\n+1\n\nSanti\n"},{"id":"153241","messageId":"20101011160224.GA25842@burratino","threadId":"25417","inReplyTo":"20101011161721.35940919@chalon.bertin.fr","subject":"[PATCH 0/4] Re: Undocumented git-diff syntax","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-11T16:02:24Z","receivedAt":"2010-10-11T16:02:24Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Yann Dirson wrote:\n\n> OTOH, that appears not to be 100% accurate (my tests would have\n> shown me): although --no-index does give me the expected results when\n> one or two of the files are untracked, I have to explicitely add it,\n> which seem to contradict this part of the doc.\n\nYep, the doc is out of date. Luckily I had a series updating it\nrotting in my local tree.\n\nPatch 5 gives --no-index its own prominent mention in the DESCRIPTION\nsection. I suspect that is a bad idea --- too much to learn for new\nusers --- and that the description should go under OPTIONS, but I ran\nout of time.\n\nMaybe patches 1-4 can help?\n\nJonathan Nieder (5):\n Documentation: gitrevisions is in section 7\n Documentation: diff can compare blobs\n Documentation: expand 'git diff' SEE ALSO section\n Documentation: update \"git diff --no-index\" description\n Documentation: expand diff --no-index description\n\n Documentation/git-cat-file.txt | 2 +-\n Documentation/git-check-ref-format.txt | 2 +-\n Documentation/git-cherry-pick.txt | 2 +-\n Documentation/git-diff.txt | 36 ++++++++++++++++++++++++--------\n Documentation/git-fast-import.txt | 2 +-\n Documentation/git-format-patch.txt | 2 +-\n Documentation/git-log.txt | 2 +-\n Documentation/git-push.txt | 2 +-\n Documentation/git-reflog.txt | 2 +-\n Documentation/git-revert.txt | 2 +-\n Documentation/git-show-branch.txt | 2 +-\n Documentation/git-show.txt | 2 +-\n Documentation/git.txt | 2 +-\n Documentation/gitcore-tutorial.txt | 2 +-\n Documentation/gitk.txt | 2 +-\n Documentation/user-manual.txt | 8 +++---\n 16 files changed, 45 insertions(+), 27 deletions(-)\n\n-- \n1.7.2.3\n"},{"id":"153242","messageId":"20101011160332.GB25842@burratino","threadId":"25417","inReplyTo":"20101011160224.GA25842@burratino","subject":"[PATCH 1/5] Documentation: gitrevisions is in section 7","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-11T16:03:32Z","receivedAt":"2010-10-11T16:03:32Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Fix references to gitrevisions(1) in the manual pages and HTML\ndocumentation.\n\nIn practice, this will not matter much unless someone tries to use a\nhard copy of the git reference manual.\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-cat-file.txt | 2 +-\n Documentation/git-check-ref-format.txt | 2 +-\n Documentation/git-cherry-pick.txt | 2 +-\n Documentation/git-diff.txt | 4 ++--\n Documentation/git-fast-import.txt | 2 +-\n Documentation/git-format-patch.txt | 2 +-\n Documentation/git-log.txt | 2 +-\n Documentation/git-push.txt | 2 +-\n Documentation/git-reflog.txt | 2 +-\n Documentation/git-revert.txt | 2 +-\n Documentation/git-show-branch.txt | 2 +-\n Documentation/git-show.txt | 2 +-\n Documentation/git.txt | 2 +-\n Documentation/gitcore-tutorial.txt | 2 +-\n Documentation/gitk.txt | 2 +-\n Documentation/user-manual.txt | 8 ++++----\n 16 files changed, 20 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex a3f56b0..544ba7b 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -27,7 +27,7 @@ OPTIONS\n ::\n \tThe name of the object to show.\n \tFor a more complete list of ways to spell object names, see\n-\tthe \"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[1].\n+\tthe \"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[7].\n \n -t::\n \tInstead of the content, show the object type identified by\ndiff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt\nindex f5c2e06..205d83d 100644\n--- a/Documentation/git-check-ref-format.txt\n+++ b/Documentation/git-check-ref-format.txt\n@@ -49,7 +49,7 @@ git imposes the following rules on how references are named:\n These rules make it easy for shell script based tools to parse\n reference names, pathname expansion by the shell when a reference name is used\n unquoted (by mistake), and also avoids ambiguities in certain\n-reference name expressions (see linkgit:gitrevisions[1]):\n+reference name expressions (see linkgit:gitrevisions[7]):\n \n . A double-dot `..` is often used as in `ref1..ref2`, and in some\n contexts this notation means `{caret}ref1 ref2` (i.e. not in\ndiff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt\nindex 2cef579..3c96fa8 100644\n--- a/Documentation/git-cherry-pick.txt\n+++ b/Documentation/git-cherry-pick.txt\n@@ -21,7 +21,7 @@ OPTIONS\n ...::\n \tCommits to cherry-pick.\n \tFor a more complete list of ways to spell commits, see\n-\tlinkgit:gitrevisions[1].\n+\tlinkgit:gitrevisions[7].\n \tSets of commits can be passed but no traversal is done by\n \tdefault, as if the '--no-walk' option was specified, see\n \tlinkgit:git-rev-list[1].\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 08fd409..481a33c 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -68,11 +68,11 @@ for the last two forms that use \"..\" notations, can be any\n .\n \n For a more complete list of ways to spell , see\n-\"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[1].\n+\"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[7].\n However, \"diff\" is about comparing two _endpoints_, not ranges,\n and the range notations (\"..\" and\n \"\\...\") do not mean a range as defined in the\n-\"SPECIFYING RANGES\" section in linkgit:gitrevisions[1].\n+\"SPECIFYING RANGES\" section in linkgit:gitrevisions[7].\n \n OPTIONS\n -------\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex 966ba4f..2c6ad5b 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -439,7 +439,7 @@ Marks must be declared (via `mark`) before they can be used.\n * A complete 40 byte or abbreviated commit SHA-1 in hex.\n \n * Any valid Git SHA-1 expression that resolves to a commit. See\n- ``SPECIFYING REVISIONS'' in linkgit:gitrevisions[1] for details.\n+ ``SPECIFYING REVISIONS'' in linkgit:gitrevisions[7] for details.\n \n The special case of restarting an incremental import from the\n current branch value should be written as:\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 4b3f5ba..a00b783 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -39,7 +39,7 @@ There are two ways to specify which commits to operate on.\n that leads to the to be output.\n \n 2. Generic expression (see \"SPECIFYING\n- REVISIONS\" section in linkgit:gitrevisions[1]) means the\n+ REVISIONS\" section in linkgit:gitrevisions[7]) means the\n commits in the specified range.\n \n The first rule takes precedence in the case of a single . To\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex c213bdb..6d40f00 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -31,7 +31,7 @@ OPTIONS\n \teither or is omitted, it defaults to\n \t`HEAD`, i.e. the tip of the current branch.\n \tFor a more complete list of ways to spell \n-\tand , see linkgit:gitrevisions[1].\n+\tand , see linkgit:gitrevisions[7].\n \n --follow::\n \tContinue listing the history of a file beyond renames\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 020955f..e11660a 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -41,7 +41,7 @@ OPTIONS[[OPTIONS]]\n +\n The is often the name of the branch you would want to push, but\n it can be any arbitrary \"SHA-1 expression\", such as `master~4` or\n-`HEAD` (see linkgit:gitrevisions[1]).\n+`HEAD` (see linkgit:gitrevisions[7]).\n +\n The tells which ref on the remote side is updated with this\n push. Arbitrary expressions cannot be used here, an actual ref must\ndiff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt\nindex 5a0451a..e50bd9b 100644\n--- a/Documentation/git-reflog.txt\n+++ b/Documentation/git-reflog.txt\n@@ -40,7 +40,7 @@ see linkgit:git-log[1].\n The reflog is useful in various git commands, to specify the old value\n of a reference. For example, `HEAD@\\{2\\}` means \"where HEAD used to be\n two moves ago\", `master@\\{one.week.ago\\}` means \"where master used to\n-point to one week ago\", and so on. See linkgit:gitrevisions[1] for\n+point to one week ago\", and so on. See linkgit:gitrevisions[7] for\n more details.\n \n To delete single entries from the reflog, use the subcommand \"delete\"\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex b7d9ef7..f40984d 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -31,7 +31,7 @@ OPTIONS\n ...::\n \tCommits to revert.\n \tFor a more complete list of ways to spell commit names, see\n-\tlinkgit:gitrevisions[1].\n+\tlinkgit:gitrevisions[7].\n \tSets of commits can also be given but no traversal is done by\n \tdefault, see linkgit:git-rev-list[1] and its '--no-walk'\n \toption.\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex 6453263..8dbcf1a 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -32,7 +32,7 @@ no nor is given on the command line.\n OPTIONS\n -------\n ::\n-\tArbitrary extended SHA1 expression (see linkgit:gitrevisions[1])\n+\tArbitrary extended SHA1 expression (see linkgit:gitrevisions[7])\n \tthat typically names a branch head or a tag.\n \n ::\ndiff --git a/Documentation/git-show.txt b/Documentation/git-show.txt\nindex 0002bfb..2049c60 100644\n--- a/Documentation/git-show.txt\n+++ b/Documentation/git-show.txt\n@@ -36,7 +36,7 @@ OPTIONS\n ...::\n \tThe names of objects to show.\n \tFor a more complete list of ways to spell object names, see\n-\t\"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[1].\n+\t\"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[7].\n \n include::pretty-options.txt[]\n \ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex dd57bdc..b46c6f6 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -495,7 +495,7 @@ HEAD::\n \t(i.e. the contents of `$GIT_DIR/refs/heads/`).\n \n For a more complete list of ways to spell object names, see\n-\"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[1].\n+\"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[7].\n \n \n File/Directory Structure\ndiff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt\nindex 5e9c5eb..c27d086 100644\n--- a/Documentation/gitcore-tutorial.txt\n+++ b/Documentation/gitcore-tutorial.txt\n@@ -971,7 +971,7 @@ commits from the master branch. The string inside brackets\n before the commit log message is a short name you can use to\n name the commit. In the above example, 'master' and 'mybranch'\n are branch heads. 'master^' is the first parent of 'master'\n-branch head. Please see linkgit:gitrevisions[1] if you want to\n+branch head. Please see linkgit:gitrevisions[7] if you want to\n see more complex cases.\n \n [NOTE]\ndiff --git a/Documentation/gitk.txt b/Documentation/gitk.txt\nindex 05ac1c7..e21bac4 100644\n--- a/Documentation/gitk.txt\n+++ b/Documentation/gitk.txt\n@@ -69,7 +69,7 @@ frequently used options.\n \tthe form \"''..''\" to show all revisions between '' and\n \tback to ''. Note, more advanced revision selection can be applied.\n \tFor a more complete list of ways to spell object names, see\n-\tlinkgit:gitrevisions[1].\n+\tlinkgit:gitrevisions[7].\n \n ...::\n \ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex ce45bfc..5b6de22 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -397,7 +397,7 @@ is usually a shortcut for the HEAD branch in the repository \"origin\".\n For the complete list of paths which git checks for references, and\n the order it uses to decide which to choose when there are multiple\n references with the same shorthand name, see the \"SPECIFYING\n-REVISIONS\" section of linkgit:gitrevisions[1].\n+REVISIONS\" section of linkgit:gitrevisions[7].\n \n [[Updating-a-repository-With-git-fetch]]\n Updating a repository with git fetch\n@@ -568,7 +568,7 @@ We have seen several ways of naming commits already:\n \t- HEAD: refers to the head of the current branch\n \n There are many more; see the \"SPECIFYING REVISIONS\" section of the\n-linkgit:gitrevisions[1] man page for the complete list of ways to\n+linkgit:gitrevisions[7] man page for the complete list of ways to\n name revisions. Some examples:\n \n -------------------------------------------------\n@@ -909,7 +909,7 @@ commits reachable from some head but not from any tag in the repository:\n $ gitk $( git show-ref --heads ) --not $( git show-ref --tags )\n -------------------------------------------------\n \n-(See linkgit:gitrevisions[1] for explanations of commit-selecting\n+(See linkgit:gitrevisions[7] for explanations of commit-selecting\n syntax such as `--not`.)\n \n [[making-a-release]]\n@@ -1635,7 +1635,7 @@ you've checked out.\n The reflogs are kept by default for 30 days, after which they may be\n pruned. See linkgit:git-reflog[1] and linkgit:git-gc[1] to learn\n how to control this pruning, and see the \"SPECIFYING REVISIONS\"\n-section of linkgit:gitrevisions[1] for details.\n+section of linkgit:gitrevisions[7] for details.\n \n Note that the reflog history is very different from normal git history.\n While normal history is shared by every repository that works on the\n-- \n1.7.2.3\n"},{"id":"153243","messageId":"20101011160408.GC25842@burratino","threadId":"25417","inReplyTo":"20101011160224.GA25842@burratino","subject":"[PATCH 2/4] Documentation: diff can compare blobs","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-11T16:04:08Z","receivedAt":"2010-10-11T16:04:08Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Meanwhile, there is no plumbing command to compare two blobs.\nStrange.\n\nReported-by: Yann Dirson \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-diff.txt | 5 +++--\n 1 files changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 481a33c..db2c6c2 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -64,8 +64,9 @@ forced by --no-index.\n \n Just in case if you are doing something exotic, it should be\n noted that all of the in the above description, except\n-for the last two forms that use \"..\" notations, can be any\n-.\n+in the last two forms that use \"..\" notations, can be any\n+. The third form ('git diff ') can also\n+be used to compare two objects.\n \n For a more complete list of ways to spell , see\n \"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[7].\n-- \n1.7.2.3\n"},{"id":"153244","messageId":"20101011160532.GD25842@burratino","threadId":"25417","inReplyTo":"20101011160224.GA25842@burratino","subject":"[PATCH 3/4] Documentation: expand 'git diff' SEE ALSO section","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-11T16:05:32Z","receivedAt":"2010-10-11T16:05:32Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Point in many directions in the hope of helping the reader find what\nis needed more quickly.\n\nThis commit also removes the summary attached to the SEE ALSO entry\nfor difftool, to avoid making the SEE ALSO list too verbose. If the\nreader wants a summary of the commands referred to, she can always\nlook to the top of the named pages or to the table of contents on the\nmain git(1) page.\n\nSuggested-by: Goswin von Brederlow \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-diff.txt | 8 ++++++--\n 1 files changed, 6 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex db2c6c2..fe34d4e 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -160,8 +160,12 @@ rewrites (very expensive).\n \n SEE ALSO\n --------\n-linkgit:git-difftool[1]::\n-\tShow changes using common diff tools\n+diff(1),\n+linkgit:git-difftool[1],\n+linkgit:git-log[1],\n+linkgit:gitdiffcore[7],\n+linkgit:git-format-patch[1],\n+linkgit:git-apply[1]\n \n Author\n ------\n-- \n1.7.2.3\n"},{"id":"153245","messageId":"20101011160618.GE25842@burratino","threadId":"25417","inReplyTo":"20101011160224.GA25842@burratino","subject":"[PATCH 4/4] Documentation: update \"git diff --no-index\" description","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-11T16:06:18Z","receivedAt":"2010-10-11T16:06:18Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Originally \"git diff --no-index\" triggered for untracked files within\nthe tracked tree, but with v1.5.6-rc1~41 (Merge branch\n'jc/diff-no-no-index, 2008-05-26) the command changed to only trigger\nwhen paths outside the tracked tree are mentioned.\n\nReported-by: Yann Dirson \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-diff.txt | 6 +++---\n 1 files changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex fe34d4e..dd1fb32 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -23,9 +23,9 @@ tree and the index file, or the index file and the working tree.\n \tfurther add to the index but you still haven't. You can\n \tstage these changes by using linkgit:git-add[1].\n +\n-If exactly two paths are given, and at least one is untracked,\n-compare the two files / directories. This behavior can be\n-forced by --no-index.\n+If exactly two paths are given and at least one points outside\n+the current repository, 'git diff' will compare the two files /\n+directories. This behavior can be forced by --no-index.\n \n 'git diff' [--options] --cached [] [--] [...]::\n \n-- \n1.7.2.3\n"},{"id":"153246","messageId":"20101011160718.GF25842@burratino","threadId":"25417","inReplyTo":"20101011160224.GA25842@burratino","subject":"[RFC/PATCH 5/4] Documentation: flesh out diff --no-index description","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-10-11T16:07:18Z","receivedAt":"2010-10-11T16:07:18Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Explain what diff --no-index is used for in more detail.\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-diff.txt | 21 +++++++++++++++++----\n 1 files changed, 17 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex dd1fb32..6700e8c 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -25,7 +25,7 @@ tree and the index file, or the index file and the working tree.\n +\n If exactly two paths are given and at least one points outside\n the current repository, 'git diff' will compare the two files /\n-directories. This behavior can be forced by --no-index.\n+directories (see --no-index below).\n \n 'git diff' [--options] --cached [] [--] [...]::\n \n@@ -62,11 +62,24 @@ directories. This behavior can be forced by --no-index.\n \t\"git diff $(git-merge-base A B) B\". You can omit any one\n \tof , which has the same effect as using HEAD instead.\n \n+'git diff' [--options] --no-index [--] ::\n+\n+\tIn this form, 'git diff' will compare a pair of files or\n+\tdirectories that are not necessarily being managed by git.\n+\tThe tracked content of files in the index and the object\n+\tdatabase are ignored.\n++\n+In other words, this form allows 'git diff' to be used as a\n+traditional 'diff' command (plus the familiar extras like --check,\n+color, pagination, automatic use of -r, --stat/--name-status,\n+--pickaxe, --binary, copy/rename detection, -Oorderfile, and\n+--patience).\n+\n Just in case if you are doing something exotic, it should be\n noted that all of the in the above description, except\n-in the last two forms that use \"..\" notations, can be any\n-. The third form ('git diff ') can also\n-be used to compare two objects.\n+in the two forms that use \"..\" notations, can be any .\n+The third form ('git diff ') can also be used\n+to compare two objects.\n \n For a more complete list of ways to spell , see\n \"SPECIFYING REVISIONS\" section in linkgit:gitrevisions[7].\n-- \n1.7.2.3\n"},{"id":"153251","messageId":"m3wrpoekha.fsf@localhost.localdomain","threadId":"25417","inReplyTo":"20101011161721.35940919@chalon.bertin.fr","subject":"Re: Undocumented git-diff syntax","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2010-10-11T16:57:48Z","receivedAt":"2010-10-11T16:57:48Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Yann Dirson writes:\n\n> That said, this two-path construct would surely deserve its own\n> synopsis.\n\nSomething like this? Just kidding...\n\n\n SYNOPSIS\n --------\n+[verse]\n 'git diff' [] {0,2} [--] [...]\n+'git diff' [] [--] [...]\n+'git diff' [] \n\nPossibly that can be also a (on filesystem).\n\nYou can e.g. use\n\n git diff HEAD:git-gui/ 00e9de7^^\n ^^^^^^^^^^^^^ ~~~~~~~~~\n \\-- tree \\-- commit (in subtree-merged history)\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"153252","messageId":"20101011185250.GC4983@home.lan","threadId":"25417","inReplyTo":"20101011160224.GA25842@burratino","subject":"Re: [PATCH 0/4] Re: Undocumented git-diff syntax","fromName":"Yann Dirson","fromEmail":"ydirson@free.fr","sentAt":"2010-10-11T18:52:50Z","receivedAt":"2010-10-11T18:52:50Z","isPatch":true,"sender":{"key":"ydirson@free.fr","avatar":null},"body":"On Mon, Oct 11, 2010 at 11:02:24AM -0500, Jonathan Nieder wrote:\n> Yann Dirson wrote:\n> \n> > OTOH, that appears not to be 100% accurate (my tests would have\n> > shown me): although --no-index does give me the expected results when\n> > one or two of the files are untracked, I have to explicitely add it,\n> > which seem to contradict this part of the doc.\n> \n> Yep, the doc is out of date. Luckily I had a series updating it\n> rotting in my local tree.\n> \n> Patch 5 gives --no-index its own prominent mention in the DESCRIPTION\n> section. I suspect that is a bad idea --- too much to learn for new\n> users --- and that the description should go under OPTIONS, but I ran\n> out of time.\n\nOTOH, not making it prominent does not help users to realize it is\nthere. Keeping it last, or maybe in a \"less frequently used\" section\nlooks fine to me - eg. the ... form could join it into\nsuch a section\n\n> Maybe patches 1-4 can help?\n\nThey make things much more clear, thanks.\n\n\nSo it looks like after this doc patch series, we're left with a couple\nof bugs:\n\n* the \"fatal: '../Makefile' is outside repository\" seen by Santi\n* the following which should probably complain that the files cannot\n be compared:\n\n$ echo a>a;echo b>b\n$ git diff a b; echo $?\n0\n\nAt least, I can't think of them as meaningful behaviours.\n\nBest regards,\n-- \nYann\n"},{"id":"153257","messageId":"AANLkTimioZVvsu4GD=8dJBrWsg-=N+w2YDSGm29d9MhS@mail.gmail.com","threadId":"25417","inReplyTo":"20101011160332.GB25842@burratino","subject":"Re: [PATCH 1/5] Documentation: gitrevisions is in section 7","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-10-11T20:49:06Z","receivedAt":"2010-10-11T20:49:06Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\nOn Mon, Oct 11, 2010 at 18:03, Jonathan Nieder wrote:\n> Fix references to gitrevisions(1) in the manual pages and HTML\n> documentation.\n\nNice catch. How did you find this? Have you check there aren't similar\nreferences that are wrong?\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"153258","messageId":"AANLkTinJBmmZirkM5a9UEOamvJEC_iuPFcNUXZUvv9qO@mail.gmail.com","threadId":"25417","inReplyTo":"20101011160224.GA25842@burratino","subject":"Re: [PATCH 0/4] Re: Undocumented git-diff syntax","fromName":"Sverre Rabbelier","fromEmail":"srabbelier@gmail.com","sentAt":"2010-10-11T20:56:34Z","receivedAt":"2010-10-11T20:56:34Z","isPatch":true,"sender":{"key":"srabbelier@gmail.com","avatar":"https://avatars.githubusercontent.com/u/3098?v=4"},"body":"Heya,\n\nOn Mon, Oct 11, 2010 at 18:02, Jonathan Nieder wrote:\n> Patch 5 gives --no-index its own prominent mention in the DESCRIPTION\n> section.  I suspect that is a bad idea --- too much to learn for new\n> users --- and that the description should go under OPTIONS, but I ran\n> out of time.\n\nWell, that answers my question in [1/5], *mutters at gmail's lack of a\ntree view*.\n\n-- \nCheers,\n\nSverre Rabbelier\n"},{"id":"153463","messageId":"7vtykphg2q.fsf@alter.siamese.dyndns.org","threadId":"25417","inReplyTo":"20101011160718.GF25842@burratino","subject":"Re: [RFC/PATCH 5/4] Documentation: flesh out diff --no-index description","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-10-13T22:40:29Z","receivedAt":"2010-10-13T22:40:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> +'git diff' [--options] --no-index [--] ::\n> +\n> +\tIn this form, 'git diff' will compare a pair of files or\n> +\tdirectories that are not necessarily being managed by git.\n> +\tThe tracked content of files in the index and the object\n> +\tdatabase are ignored.\n> ++\n> +In other words, this form allows 'git diff' to be used as a\n> +traditional 'diff' command (plus the familiar extras like --check,\n> +color, pagination, automatic use of -r, --stat/--name-status,\n> +--pickaxe, --binary, copy/rename detection, -Oorderfile, and\n> +--patience).\n\nMy initial knee-jerk reaction was \"how would -C/-M/-O be useful when you\ncan only give two paths?\" Perhaps it would become easier to read if we\nphrased it like this?\n\n This form allows 'git diff' to be used as a better 'diff' command,\n with extras like whitespace checks (--check), coloring (--color),\n wordwise diff (--color-words), pagination, diffstat (--stat), binary\n patch (--binary), alternative algorithm (e.g. --patience). In\n addition, when comparing two directories, rename detection (-M) may\n come in handy.\n\nNote, by the way, that I didn't verify all the claims the above makes.\n"}]}