{"thread":{"id":"43471","subject":"[PATCH] Cleanup git-diff documentation","startedAt":"2006-12-14T08:09:43Z","lastAt":"2006-12-15T10:03:19Z","messageCount":5,"participants":["Brian Gernhardt","Junio C Hamano","Nicolas Pitre","Johannes Schindelin","Jakub Narebski"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"295088","messageId":"7vr6v2aofs.fsf@assigned-by-dhcp.cox.net","threadId":"43471","inReplyTo":null,"subject":"[PATCH] Update git-diff documentation","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2006-12-14T08:09:43Z","receivedAt":"2006-12-14T08:09:43Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Porcelain documentation should talk in terms of end-user workflow, not\nin terms of implementation details.  Do not suggest update-index, but\ngit-add instead.  Explain differences among 0-, 1- and 2-tree cases\nnot as differences of number of trees given to the command, but say\nwhy user would want to give these number of trees to the command in\nwhat situation.\n\nSigned-off-by: Junio C Hamano <junkio@cox.net>\n---\n\n * The same idea as the previous \"git commit\" documentation.\n\n Documentation/git-diff.txt |   55 ++++++++++++++++++++++++++++---------------\n 1 files changed, 36 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 228c4d9..8888e0d 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -12,32 +12,49 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Show changes between two trees, a tree and the working tree, a\n-tree and the index file, or the index file and the working tree.\n-The combination of what is compared with what is determined by\n-the number of trees given to the command.\n+This command shows changes between four combinations of states.\n \n-* When no <tree-ish> is given, the working tree and the index\n-  file are compared, using `git-diff-files`.\n+'git-diff' [--options] [--] [<path>...]::\n \n-* When one <tree-ish> is given, the working tree and the named\n-  tree are compared, using `git-diff-index`.  The option\n-  `--cached` can be given to compare the index file and\n-  the named tree.\n+\tThis form is to view the changes you made relative to\n+\tthe index (staging area for the next commit).  In other\n+\twords, the differences are what you _could_ tell git to\n+\tfurther add to the index but you still haven't.  You can\n+\tstage these changes by using gitlink:git-add[1].\n+\n+'git-diff' [--options] --cached [<commit>] [--] [<path>...]::\n+\n+\tThis form is to view the changes you staged for the next\n+\tcommit relative to the named <tree-ish>.  Typically you\n+\twould want comparison with the latest commit, so if you\n+\tdo not give <commit>, it defaults to HEAD.\n+\n+'git-diff' [--options] <commit> -- [<path>...]::\n+\n+\tThis form is to view the changes you have in your\n+\tworking tree relative to the named <commit>.  You can\n+\tuse HEAD to compare it with the latest commit, or a\n+\tbranch name to compare with the tip of a different\n+\tbranch.\n+\n+* 'git-diff' [--options] <commit> <commit> -- [<path>...]\n+\n+\tThis form is to view the changes between two <commit>,\n+\tfor example, tips of two branches.\n+\n+Just in case if you are doing something exotic, it should be\n+noted that all of the <commit> in the above description can be\n+any <tree-ish>.\n \n-* When two <tree-ish>s are given, these two trees are compared\n-  using `git-diff-tree`.\n \n OPTIONS\n -------\n---diff-options::\n-\t'--diff-options' are passed to the `git-diff-files`,\n-\t`git-diff-index`, and `git-diff-tree` commands.  See the\n-\tdocumentation for these commands for description.\n+include::diff-options.txt[]\n \n <path>...::\n-\tThe <path> arguments are also passed to `git-diff-\\*`\n-\tcommands.\n+\tThe <paths> parameters, when given, are used to limit\n+\tthe diff to the named paths (you can give directory\n+\tnames and get diff for all files under them).\n \n \n EXAMPLES\n@@ -51,7 +68,7 @@ $ git diff --cached   <2>\n $ git diff HEAD       <3>\n ------------\n +\n-<1> changes in the working tree since your last git-update-index.\n+<1> changes in the working tree not yet staged for the next commit.\n <2> changes between the index and your last commit; what you\n would be committing if you run \"git commit\" without \"-a\" option.\n <3> changes in the working tree since your last commit; what you\n-- \n1.4.4.2.g86bd\n\n"},{"id":"296407","messageId":"Pine.LNX.4.63.0612140957590.3635@wbgn013.biozentrum.uni-wuerzburg.de","threadId":"43471","inReplyTo":"7vr6v2aofs.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Update git-diff documentation","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2006-12-14T08:59:23Z","receivedAt":"2006-12-14T08:59:23Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Thu, 14 Dec 2006, Junio C Hamano wrote:\n\n> -Show changes between two trees, a tree and the working tree, a\n> -tree and the index file, or the index file and the working tree.\n> -The combination of what is compared with what is determined by\n> -the number of trees given to the command.\n> +This command shows changes between four combinations of states.\n\nI think the old explanation, while longer, is clearer.\n\nI like the rest of your patch, though.\n\nCiao,\n"},{"id":"294985","messageId":"9A80051B-1F6B-4FFD-B33F-84121D3A422F@silverinsanity.com","threadId":"43471","inReplyTo":"Pine.LNX.4.63.0612140957590.3635@wbgn013.biozentrum.uni-wuerzburg.de","subject":"[PATCH] Cleanup git-diff documentation","fromName":"Brian Gernhardt","fromEmail":"benji@silverinsanity.com","sentAt":"2006-12-14T12:32:56Z","receivedAt":"2006-12-14T12:32:56Z","isPatch":true,"sender":{"key":"benji@silverinsanity.com","avatar":"https://gravatar.com/avatar/e06c101dbc25c68114d859b4a9ec7cf8a2c52fd2b0270ef0eac0e2e63ff22311?d=mp&s=160"},"body":"There were a couple inconsistencies in the formatting of the command\ndescriptions and a more descriptive initial description is better.\n\nSigned-off-by: Brian Gernhardt <benji@silverinsanity.com>\n---\n\nI agree with Johannes about the original being clearer.  Plus two of\nthe command examples were missing brackets around -- and one had a\n* at the beginning the others didn't.  This patch is against Junio's\nchanges made on master (1d770), even though his patch didn't apply\ncleanly.\n\nDocumentation/git-diff.txt |   11 +++++++----\n1 files changed, 7 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 534f824..2ba9145 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -12,7 +12,10 @@ SYNOPSIS\nDESCRIPTION\n-----------\n-This command shows changes between four combinations of states.\n+Show changes between two trees, a tree and the working tree, a\n+tree and the index file, or the index file and the working tree.\n+The combination of what is compared with what is determined by\n+the number of trees given to the command.\n'git-diff' [--options] [--] [<path>...]::\n@@ -25,11 +28,11 @@ This command shows changes between four  \ncombinations of states.\n'git-diff' [--options] --cached [<commit>] [--] [<path>...]::\n\tThis form is to view the changes you staged for the next\n-\tcommit relative to the named <tree-ish>.  Typically you\n+\tcommit relative to the named <commit>.  Typically you\n\twould want comparison with the latest commit, so if you\n\tdo not give <commit>, it defaults to HEAD.\n-'git-diff' [--options] <commit> -- [<path>...]::\n+'git-diff' [--options] <commit> [--] [<path>...]::\n\tThis form is to view the changes you have in your\n\tworking tree relative to the named <commit>.  You can\n@@ -37,7 +40,7 @@ This command shows changes between four  \ncombinations of states.\n\tbranch name to compare with the tip of a different\n\tbranch.\n-* 'git-diff' [--options] <commit> <commit> -- [<path>...]\n+'git-diff' [--options] <commit> <commit> [--] [<path>...]\n\tThis form is to view the changes between two <commit>,\n\tfor example, tips of two branches.\n--\n"},{"id":"295183","messageId":"Pine.LNX.4.64.0612141157270.18171@xanadu.home","threadId":"43471","inReplyTo":"Pine.LNX.4.63.0612140957590.3635@wbgn013.biozentrum.uni-wuerzburg.de","subject":"Re: [PATCH] Update git-diff documentation","fromName":"Nicolas Pitre","fromEmail":"nico@cam.org","sentAt":"2006-12-14T17:02:25Z","receivedAt":"2006-12-14T17:02:25Z","isPatch":true,"sender":{"key":"nico@fluxnic.net","avatar":"https://avatars.githubusercontent.com/u/702790?v=4"},"body":"On Thu, 14 Dec 2006, Johannes Schindelin wrote:\n\n> Hi,\n> \n> On Thu, 14 Dec 2006, Junio C Hamano wrote:\n> \n> > -Show changes between two trees, a tree and the working tree, a\n> > -tree and the index file, or the index file and the working tree.\n> > -The combination of what is compared with what is determined by\n> > -the number of trees given to the command.\n> > +This command shows changes between four combinations of states.\n> \n> I think the old explanation, while longer, is clearer.\n\nIt might not if you don't know what a \"tree\" is in git speak.  The \nnotion of what a tree refers to is slowly introduced afterwards which I \nthink is better than delivering everything in a dense four lines right \nup front.\n\n\n"},{"id":"296767","messageId":"eltroi$b4q$3@sea.gmane.org","threadId":"43471","inReplyTo":"9A80051B-1F6B-4FFD-B33F-84121D3A422F@silverinsanity.com","subject":"Re: [PATCH] Cleanup git-diff documentation","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2006-12-15T10:03:19Z","receivedAt":"2006-12-15T10:03:19Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Brian Gernhardt wrote:\n\n> -This command shows changes between four combinations of states.\n> +Show changes between two trees, a tree and the working tree, a\n> +tree and the index file, or the index file and the working tree.\n> +The combination of what is compared with what is determined by\n> +the number of trees given to the command.\n\nYou talk here about \"number of _trees_\" while later you use <commit>,\nnot <tree> or <tree-ish>. Only at the very end you say that <commit>\n(<commit-ish> because you can use tags as well) can be replaced by\nany <tree-ish>.\n\nThat said, I like this clarification, especially the fact that\nI don't have to go to git-diff-tree(1) to find diff options.\n\n> 'git-diff' [--options] [--] [<path>...]::\n> @@ -25,11 +28,11 @@ This command shows changes between four  \n> combinations of states.\n> 'git-diff' [--options] --cached [<commit>] [--] [<path>...]::\n>         This form is to view the changes you staged for the next\n> -       commit relative to the named <tree-ish>.  Typically you\n> +       commit relative to the named <commit>.  Typically you\n>         would want comparison with the latest commit, so if you\n>         do not give <commit>, it defaults to HEAD.\n\n-- \nJakub Narebski\nWarsaw, Poland\nShadeHawk on #git\n\n"}]}