{"thread":{"id":"38121","subject":"[PATCH] Improve --assume-unchanged in the git update-index man page","startedAt":"2014-12-05T22:21:56Z","lastAt":"2014-12-05T23:32:08Z","messageCount":4,"participants":["Philip Oakley","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"253195","messageId":"1417818117-368-1-git-send-email-philipoakley@iee.org","threadId":"38121","inReplyTo":null,"subject":"[PATCH] Improve --assume-unchanged in the git update-index man page","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-12-05T22:21:56Z","receivedAt":"2014-12-05T22:21:56Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Junio, this is my quick attempt at a patch for the man page.\n\n\nIn $gmane/260837 the --assume-unchanged flag was reported as buggy because\nof a misunderstanding about what it is being promised.\n\nThis patch looks to be more assertive in stating what promise is being made.\n\nWhile at it correct a confusing pluralisation of the option.\n\nPhilip Oakley (1):\n doc: make clear --assume-unchanged's user contract\n\n Documentation/git-update-index.txt | 9 +++++----\n 1 file changed, 5 insertions(+), 4 deletions(-)\n\n-- \n1.9.4.msysgit.0\n"},{"id":"253196","messageId":"1417818117-368-2-git-send-email-philipoakley@iee.org","threadId":"38121","inReplyTo":"1417818117-368-1-git-send-email-philipoakley@iee.org","subject":"[PATCH] doc: make clear --assume-unchanged's user contract","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2014-12-05T22:21:57Z","receivedAt":"2014-12-05T22:21:57Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Many users misunderstand the --assume-unchanged contract, believing\nit means Git won't look at the flagged file.\n\nBe explicit that the --assume-unchanged contract is by the user that\nthey will NOT change the file so that Git does not need to look (and\nexpend, fore example, lstat(2) cycles)\n\nSigned-off-by: Philip Oakley \n---\n Documentation/git-update-index.txt | 9 +++++----\n 1 file changed, 5 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex 929869b..c045509 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -82,13 +82,14 @@ OPTIONS\n Set the execute permissions on the updated files.\n \n --[no-]assume-unchanged::\n-\tWhen these flags are specified, the object names recorded\n+\tWhen this flag is specified, the object names recorded\n \tfor the paths are not updated. Instead, these options\n \tset and unset the \"assume unchanged\" bit for the\n-\tpaths. When the \"assume unchanged\" bit is on, Git stops\n+\tpaths. When the \"assume unchanged\" bit is on, the user promise\n+\tis not to change the file, so Git stops\n \tchecking the working tree files for possible\n-\tmodifications, so you need to manually unset the bit to\n-\ttell Git when you change the working tree file. This is\n+\tmodifications, so when you change the working tree file you\n+\tneed to manually unset the bit to tell Git . This is\n \tsometimes helpful when working with a big project on a\n \tfilesystem that has very slow lstat(2) system call\n \t(e.g. cifs).\n-- \n1.9.4.msysgit.0\n"},{"id":"253200","messageId":"xmqqtx19ogn9.fsf@gitster.dls.corp.google.com","threadId":"38121","inReplyTo":"1417818117-368-2-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH] doc: make clear --assume-unchanged's user contract","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-12-05T22:50:34Z","receivedAt":"2014-12-05T22:50:34Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> Many users misunderstand the --assume-unchanged contract, believing\n> it means Git won't look at the flagged file.\n\nYeah, I suspect that many of them come from how-tos floating on the\n'net (e.g. stackoverflow) that are misguided or outright incorrect.\nI've stopped correcting people who advise \"you can flip this bit and\nsquelch your changes from appearing in diffs\" number of years ago.\n\n> Be explicit that the --assume-unchanged contract is by the user that\n> they will NOT change the file so that Git does not need to look (and\n> expend, fore example, lstat(2) cycles)\n\nYes, but \"so that Git does not ...\" part is already very clear in\nthe existing part of the document. Stressing that this is the user\nmaking a promise to help Git help the user is indeed a good idea.\n\n> Signed-off-by: Philip Oakley \n> ---\n> Documentation/git-update-index.txt | 9 +++++----\n> 1 file changed, 5 insertions(+), 4 deletions(-)\n>\n> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\n> index 929869b..c045509 100644\n> --- a/Documentation/git-update-index.txt\n> +++ b/Documentation/git-update-index.txt\n> @@ -82,13 +82,14 @@ OPTIONS\n> Set the execute permissions on the updated files.\n> \n> --[no-]assume-unchanged::\n> -\tWhen these flags are specified, the object names recorded\n> +\tWhen this flag is specified, the object names recorded\n\nThanks. We are talking about a single flag bit.\n\n> \tfor the paths are not updated. Instead, these options\n> \tset and unset the \"assume unchanged\" bit for the\n\n\"this option sets/unsets\"?\n\n> -\tpaths. When the \"assume unchanged\" bit is on, Git stops\n> +\tpaths. When the \"assume unchanged\" bit is on, the user promise\n> +\tis not to change the file, so Git stops\n\n\"the user promises not to\".\n\n> \tchecking the working tree files for possible\n> -\tmodifications, so you need to manually unset the bit to\n> -\ttell Git when you change the working tree file. This is\n> +\tmodifications, so when you change the working tree file you\n> +\tneed to manually unset the bit to tell Git . This is\n\nThis reads much better than the original, but you may want to go a\nbit further. How about removing the original a bit more, like so:\n\n\t... the user promises not to change the file and allows Git\n to assume that the working tree file matches what is\n recorded in the index. If you want to change the working\n tree file, you need to unset the bit to tell Git. This is\n\n> \tsometimes helpful when working with a big project on a\n> \tfilesystem that has very slow lstat(2) system call\n> \t(e.g. cifs).\n\nThanks.\n"},{"id":"253209","messageId":"xmqqbnnhoepz.fsf@gitster.dls.corp.google.com","threadId":"38121","inReplyTo":"xmqqtx19ogn9.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] doc: make clear --assume-unchanged's user contract","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-12-05T23:32:08Z","receivedAt":"2014-12-05T23:32:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> This reads much better than the original, but you may want to go a\n> bit further. How about removing the original a bit more, like so:\n> ...\n\nSo here is what I came up to squash into your version when queuing\nit to 'pu'.\n\n-- >8 --\nSubject: [PATCH] SQUASH???\n\n - Further matching of number and verb; we are talking about a single\n flag bit.\n\n - The bit tells Git that it can assume that the files marked as\n such are unchanged. Mentioning \"Git stops checking\" does not\n help the reader, as it is only one possible consequence of what\n that assumption allows Git to do, but\n\n (1) there are things other than \"stop checking\" that Git can do\n based on that assumption; and\n (2) Git is not obliged to stop checking; it merely is allowed to.\n\n - Drop the stale and incorrect information about \"poor-man's\n ignore\", which is not this bit is about at all.\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/git-update-index.txt | 17 +++++++----------\n 1 file changed, 7 insertions(+), 10 deletions(-)\n\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex f1f5f7f..da1ccbc 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -79,20 +79,17 @@ OPTIONS\n \n --[no-]assume-unchanged::\n \tWhen this flag is specified, the object names recorded\n-\tfor the paths are not updated. Instead, these options\n-\tset and unset the \"assume unchanged\" bit for the\n-\tpaths. When the \"assume unchanged\" bit is on, the user promise\n-\tis not to change the file, so Git stops\n-\tchecking the working tree files for possible\n-\tmodifications, so when you change the working tree file you\n-\tneed to manually unset the bit to tell Git . This is\n+\tfor the paths are not updated. Instead, this option\n+\tsets/unsets the \"assume unchanged\" bit for the\n+\tpaths. When the \"assume unchanged\" bit is on, the user\n+\tpromises not to change the file and allows Git to assume\n+\tthat the working tree file matches what is recorded in\n+\tthe index. If you want to change the working tree file,\n+\tyou need to unset the bit to tell Git. This is\n \tsometimes helpful when working with a big project on a\n \tfilesystem that has very slow lstat(2) system call\n \t(e.g. cifs).\n +\n-This option can be also used as a coarse file-level mechanism\n-to ignore uncommitted changes in tracked files (akin to what\n-`.gitignore` does for untracked files).\n Git will fail (gracefully) in case it needs to modify this file\n in the index e.g. when merging in a commit;\n thus, in case the assumed-untracked file is changed upstream,\n-- \n2.2.0-155-g395db3e\n"}]}