{"thread":{"id":"33864","subject":"git-diff-index man page","startedAt":"2013-05-18T16:26:11Z","lastAt":"2013-05-20T22:48:19Z","messageCount":7,"participants":["Albert Netymk","Junio C Hamano","Eric Sunshine","Jonathan Nieder"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"217818","messageId":"CAKEGsXQDB1=hizNqM6D=uuP6PXT4ytUiTgB5fvO-gVSsPqQkLQ@mail.gmail.com","threadId":"33864","inReplyTo":null,"subject":"git-diff-index man page","fromName":"Albert Netymk","fromEmail":"albertnetymk@gmail.com","sentAt":"2013-05-18T16:26:11Z","receivedAt":"2013-05-18T16:26:11Z","isPatch":false,"sender":{"key":"albertnetymk@gmail.com","avatar":null},"body":"Hello,\n\nThe man page of git-diff-index:\nhttp://git-scm.com/docs/git-diff-index\nstates that\n`git-diff-index - Compares content and mode of blobs between the index\nand repository`.\n\nHowever, in fact this command compares between files on disk and\nrepository by default. It's explained clearly in here:\nhttp://git-scm.com/docs/gitdiffcore\n\nMaybe the man page could be updated to reflect this in NAME section:\n`git-diff-index - Compares content and mode of blobs between files on\ndisk and repository or between the index and repository`\n\nIn DESCRIPTION section:\n`Compares the content and mode of the blobs found via a tree object\nwith the content of the files on disk by default, and could be\ncompared with index only using cached option. ...`\n\n--\nBest Regards\n\nYours faithfully\nAlbert Netymk\n"},{"id":"217847","messageId":"7vhahzza2v.fsf@alter.siamese.dyndns.org","threadId":"33864","inReplyTo":"CAKEGsXQDB1=hizNqM6D=uuP6PXT4ytUiTgB5fvO-gVSsPqQkLQ@mail.gmail.com","subject":"Re: git-diff-index man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-05-19T07:46:00Z","receivedAt":"2013-05-19T07:46:00Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Albert Netymk writes:\n\n> Hello,\n>\n> The man page of git-diff-index:\n> http://git-scm.com/docs/git-diff-index\n> states that\n> `git-diff-index - Compares content and mode of blobs between the index\n> and repository`.\n>\n> However, in fact this command compares between files on disk and\n> repository by default. It's explained clearly in here:\n> http://git-scm.com/docs/gitdiffcore\n>\n> Maybe the man page could be updated to reflect this in NAME section:\n> `git-diff-index - Compares content and mode of blobs between files on\n> disk and repository or between the index and repository`\n\nSurely; we need to keep it fit on a single line, though.\n\n> In DESCRIPTION section:\n> `Compares the content and mode of the blobs found via a tree object\n> with the content of the files on disk by default, and could be\n> compared with index only using cached option. ...`\n\nYes, mentioning both mode is a good change. The above exact text\nmay give a false impression (with that \"by default\") that it is\nsomehow more preferrable to compare tree with working tree through\nthe index, and only weirdos would use \"--cached\" to compare tree and\nthe index, though.\n\nPatches welcome. Thanks.\n"},{"id":"217927","messageId":"CAKEGsXRry_=BuPRPK_syW7_W+_Bh+A1bB9U5YC02=a+Z+SHv1w@mail.gmail.com","threadId":"33864","inReplyTo":"7vhahzza2v.fsf@alter.siamese.dyndns.org","subject":"Re: git-diff-index man page","fromName":"Albert Netymk","fromEmail":"albertnetymk@gmail.com","sentAt":"2013-05-19T20:23:03Z","receivedAt":"2013-05-19T20:23:03Z","isPatch":false,"sender":{"key":"albertnetymk@gmail.com","avatar":null},"body":"On Sun, May 19, 2013 at 9:46 AM, Junio C Hamano wrote:\n> Albert Netymk writes:\n>\n>> Hello,\n>>\n>> The man page of git-diff-index:\n>> http://git-scm.com/docs/git-diff-index\n>> states that\n>> `git-diff-index - Compares content and mode of blobs between the index\n>> and repository`.\n>>\n>> However, in fact this command compares between files on disk and\n>> repository by default. It's explained clearly in here:\n>> http://git-scm.com/docs/gitdiffcore\n>>\n>> Maybe the man page could be updated to reflect this in NAME section:\n>> `git-diff-index - Compares content and mode of blobs between files on\n>> disk and repository or between the index and repository`\n>\n> Surely; we need to keep it fit on a single line, though.\n\nHere's one excerpt from man page of git-diff-index: (this is how one\nline looks like)\nCompares the content and mode of the blobs found via a tree object\nwith the content of the current index and, optionally ignoring the\nstat state of\n`git-diff-index - Compares content and mode of blobs between files on\ndisk and repository or between the index and repository`\n\nIt seems that this one is not longer than one line.\n>\n>> In DESCRIPTION section:\n>> `Compares the content and mode of the blobs found via a tree object\n>> with the content of the files on disk by default, and could be\n>> compared with index only using cached option. ...`\n>\n> Yes, mentioning both mode is a good change. The above exact text\n> may give a false impression (with that \"by default\") that it is\n> somehow more preferrable to compare tree with working tree through\n> the index, and only weirdos would use \"--cached\" to compare tree and\n> the index, though.\nI am a little confused about \"somehow more preferrable to compare tree\nwith working tree through the index\". My understanding is that if\n`--cached` is not used, the content of index is ignore. This command\ndoes direct comparison between repository and working tree.\nI didn't realized that the above statement implies any subjective\npreference. If so, provide one objective description, please.\n\n> Patches welcome. Thanks.\nI don't know how to submit patches. Besides, the only part that is a\nbit misleading is the \"NAME\" and \"DESCRIPTION\" section. Could someone\njust update them?\n\n\n\n--\nBest Regards\n\nYours faithfully\nAlbert Netymk\n"},{"id":"217957","messageId":"7vr4h2w8gv.fsf@alter.siamese.dyndns.org","threadId":"33864","inReplyTo":"CAKEGsXRry_=BuPRPK_syW7_W+_Bh+A1bB9U5YC02=a+Z+SHv1w@mail.gmail.com","subject":"Re: git-diff-index man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-05-20T05:01:20Z","receivedAt":"2013-05-20T05:01:20Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Albert Netymk writes:\n\n> On Sun, May 19, 2013 at 9:46 AM, Junio C Hamano wrote:\n>> Albert Netymk writes:\n>>\n>>> Hello,\n>>>\n>>> The man page of git-diff-index:\n>>> http://git-scm.com/docs/git-diff-index\n>>> states that\n>>> `git-diff-index - Compares content and mode of blobs between the index\n>>> and repository`.\n>>> However, in fact this command compares between files on disk and\n>>> repository by default. It's explained clearly in here:\n>>> http://git-scm.com/docs/gitdiffcore\n>>>\n>>> Maybe the man page could be updated to reflect this in NAME section:\n>>> `git-diff-index - Compares content and mode of blobs between files on\n>>> disk and repository or between the index and repository`\n>>\n>> Surely; we need to keep it fit on a single line, though.\n>\n> Here's one excerpt from man page of git-diff-index: (this is how one\n> line looks like)\n> Compares the content and mode of the blobs found via a tree object\n> with the content of the current index and, optionally ignoring the\n> stat state of\n> `git-diff-index - Compares content and mode of blobs between files on\n> disk and repository or between the index and repository`\n>\n> It seems that this one is not longer than one line.\n\nI would say\n\n\tgit-diff-index - Compare a tree and the working tree or the index\n\nshould be sufficiently short and much more accurate than the current\ntext.\n\n> I don't know how to submit patches. Besides, the only part that is a\n> bit misleading is the \"NAME\" and \"DESCRIPTION\" section. Could someone\n> just update them?\n\nHow about something like this?\n\n-- >8 --\nSubject: [PATCH] Documentation/diff-index: mention two modes of operation\n\n\"diff-index\" can be used to compare a tree with the tracked working\ntree files (when used without the --index option), or with the index\n(when used with the --index option).\n\nThe text however did not say anything about the comparision with the\nworking tree at all. Fix this.\n\nReported-by: Albert Netymk \nSigned-off-by: Junio C Hamano \n---\n Documentation/git-diff-index.txt | 13 +++++++------\n 1 file changed, 7 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt\nindex c0b7c58..58308e1 100644\n--- a/Documentation/git-diff-index.txt\n+++ b/Documentation/git-diff-index.txt\n@@ -3,7 +3,7 @@ git-diff-index(1)\n \n NAME\n ----\n-git-diff-index - Compares content and mode of blobs between the index and repository\n+git-diff-index - Compare a tree and the working tree or the index\n \n \n SYNOPSIS\n@@ -13,11 +13,12 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-Compares the content and mode of the blobs found via a tree\n-object with the content of the current index and, optionally\n-ignoring the stat state of the file on disk. When paths are\n-specified, compares only those named paths. Otherwise all\n-entries in the index are compared.\n+\n+Compare the content and mode of the blobs found in a tree object\n+with the corresponding tracked file in the working tree, or with the\n+corresponding paths in the index. When paths are specified,\n+compares only those named paths. Otherwise all entries in the index\n+are compared.\n \n OPTIONS\n -------\n"},{"id":"217959","messageId":"CAPig+cTVjJpD4+s2TqgBR_ZNmnDTTw8OYb1Zpg_EtQ1nxf8eYg@mail.gmail.com","threadId":"33864","inReplyTo":"7vr4h2w8gv.fsf@alter.siamese.dyndns.org","subject":"Re: git-diff-index man page","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2013-05-20T05:40:00Z","receivedAt":"2013-05-20T05:40:00Z","isPatch":false,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, May 20, 2013 at 1:01 AM, Junio C Hamano wrote:\n> Subject: [PATCH] Documentation/diff-index: mention two modes of operation\n>\n> \"diff-index\" can be used to compare a tree with the tracked working\n> tree files (when used without the --index option), or with the index\n> (when used with the --index option).\n>\n> The text however did not say anything about the comparision with the\n\ns/comparision/comparison/\n\n> working tree at all. Fix this.\n>\n> Reported-by: Albert Netymk \n> Signed-off-by: Junio C Hamano \n"},{"id":"217960","messageId":"20130520062743.GA2919@elie.Belkin","threadId":"33864","inReplyTo":"7vr4h2w8gv.fsf@alter.siamese.dyndns.org","subject":"Re: git-diff-index man page","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-05-20T06:27:43Z","receivedAt":"2013-05-20T06:27:43Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Junio C Hamano wrote:\n\n> --- a/Documentation/git-diff-index.txt\n> +++ b/Documentation/git-diff-index.txt\n> @@ -3,7 +3,7 @@ git-diff-index(1)\n> \n> NAME\n> ----\n> -git-diff-index - Compares content and mode of blobs between the index and repository\n> +git-diff-index - Compare a tree and the working tree or the index\n\nLooks good. I think it scans better with the second \"the\" left out:\n\n\tgit diff-index - Compare a tree to the working tree or index\n\n[...]\n> @@ -13,11 +13,12 @@ SYNOPSIS\n> \n> DESCRIPTION\n> -----------\n> -Compares the content and mode of the blobs found via a tree\n> +Compare the content and mode of the blobs found in a tree object\n\nI think this s/Compares/Compare/ is a regression: traditionally\nthe DESCRIPTION sections of manpages describe what a command does in\nthe present indicative (\"When paths are specified, compares only those\nnamed paths\"), freeing up the imperative for cases where it is useful\nto instruct the user about what to do.\n\nThe s/via/in/ looks fine.\n\n> -object with the content of the current index and, optionally\n> +with the corresponding tracked file in the working tree, or with the\n\nSince they are being compared to blobs, \"file\" should be \"files\" here.\n\n> -ignoring the stat state of the file on disk. When paths are\n> -specified, compares only those named paths. Otherwise all\n> -entries in the index are compared.\n> +corresponding paths in the index. When paths are specified,\n> +compares only those named paths. Otherwise all entries in the index\n> +are compared.\n\nThe parameters to git diff-index are pathspecs and not literal\npaths.\n\nThis should say somewhere that this only looks at paths in the index\nand that untracked files are ignored. Perhaps something as simple\nas s/entries in the index/tracked files/ would do the trick.\n\nThanks and hope that helps,\nJonathan\n\ndiff --git i/Documentation/git-diff-index.txt w/Documentation/git-diff-index.txt\nindex 58308e15..a86cf62e 100644\n--- i/Documentation/git-diff-index.txt\n+++ w/Documentation/git-diff-index.txt\n@@ -3,7 +3,7 @@ git-diff-index(1)\n \n NAME\n ----\n-git-diff-index - Compare a tree and the working tree or the index\n+git-diff-index - Compare a tree to the working tree or index\n \n \n SYNOPSIS\n@@ -13,12 +13,11 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-\n-Compare the content and mode of the blobs found in a tree object\n-with the corresponding tracked file in the working tree, or with the\n-corresponding paths in the index. When paths are specified,\n-compares only those named paths. Otherwise all entries in the index\n-are compared.\n+Compares the content and mode of the blobs found in a tree object\n+with the corresponding tracked files in the working tree, or with the\n+corresponding paths in the index. When arguments are present,\n+compares only paths matching those patterns. Otherwise all tracked\n+files are compared.\n \n OPTIONS\n -------\n"},{"id":"218014","messageId":"7vy5b9s1xo.fsf@alter.siamese.dyndns.org","threadId":"33864","inReplyTo":"20130520062743.GA2919@elie.Belkin","subject":"Re: git-diff-index man page","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-05-20T22:48:19Z","receivedAt":"2013-05-20T22:48:19Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jonathan Nieder writes:\n\n> Thanks and hope that helps,\n> Jonathan\n\nThanks, the result reads much better, I think.\n\nAlbert?\n\n\n> diff --git i/Documentation/git-diff-index.txt w/Documentation/git-diff-index.txt\n> index 58308e15..a86cf62e 100644\n> --- i/Documentation/git-diff-index.txt\n> +++ w/Documentation/git-diff-index.txt\n> @@ -3,7 +3,7 @@ git-diff-index(1)\n> \n> NAME\n> ----\n> -git-diff-index - Compare a tree and the working tree or the index\n> +git-diff-index - Compare a tree to the working tree or index\n> \n> \n> SYNOPSIS\n> @@ -13,12 +13,11 @@ SYNOPSIS\n> \n> DESCRIPTION\n> -----------\n> -\n> -Compare the content and mode of the blobs found in a tree object\n> -with the corresponding tracked file in the working tree, or with the\n> -corresponding paths in the index. When paths are specified,\n> -compares only those named paths. Otherwise all entries in the index\n> -are compared.\n> +Compares the content and mode of the blobs found in a tree object\n> +with the corresponding tracked files in the working tree, or with the\n> +corresponding paths in the index. When arguments are present,\n> +compares only paths matching those patterns. Otherwise all tracked\n> +files are compared.\n> \n> OPTIONS\n> -------\n"}]}