{"thread":{"id":"27001","subject":"[PATCHv3 2/2] Documentation: enhance gitignore whitelist example","startedAt":"2011-04-05T22:17:57Z","lastAt":"2011-04-06T12:48:17Z","messageCount":6,"participants":["Eric Blake","Junio C Hamano","Drew Northup"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"165227","messageId":"1302041878-24426-1-git-send-email-eblake@redhat.com","threadId":"27001","inReplyTo":null,"subject":"[PATCHv3 1/2] Documentation: clarify fnmatch behavior in gitignore","fromName":"Eric Blake","fromEmail":"eblake@redhat.com","sentAt":"2011-04-05T22:17:57Z","receivedAt":"2011-04-05T22:17:57Z","isPatch":false,"sender":{"key":"eblake@redhat.com","avatar":"https://avatars.githubusercontent.com/u/32933908?v=4"},"body":"Make it clear that in a .gitignore file,\n\n *ignore\n\nmatches (and therefore excludes) `.gitignore', even though the\nsame glob does not match in the shell.\n\nSigned-off-by: Eric Blake \n---\n\nv3: separate fnmatch wording cleanup into its own patch\n\n Documentation/gitignore.txt | 7 ++++---\n 1 files changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\nindex 2e7328b..9b1e5e1 100644\n--- a/Documentation/gitignore.txt\n+++ b/Documentation/gitignore.txt\n@@ -86,9 +86,10 @@ PATTERN FORMAT\n `.gitignore` file).\n\n - Otherwise, git treats the pattern as a shell glob suitable\n- for consumption by fnmatch(3) with the FNM_PATHNAME flag:\n- wildcards in the pattern will not match a / in the pathname.\n- For example, \"Documentation/{asterisk}.html\" matches\n+ for consumption by fnmatch(3) with the FNM_PATHNAME but not\n+ FNM_PERIOD flags: wildcards in the pattern will match leading\n+ . but not / in pathnames. For example,\n+ \"Documentation/{asterisk}.html\" matches \"Documentation/.html\" and\n \"Documentation/git.html\" but not \"Documentation/ppc/ppc.html\"\n or \"tools/perf/Documentation/perf.html\".\n\n-- \n1.7.4\n"},{"id":"165224","messageId":"1302041878-24426-2-git-send-email-eblake@redhat.com","threadId":"27001","inReplyTo":"1302041878-24426-1-git-send-email-eblake@redhat.com","subject":"[PATCHv3 2/2] Documentation: enhance gitignore whitelist example","fromName":"Eric Blake","fromEmail":"eblake@redhat.com","sentAt":"2011-04-05T22:17:58Z","receivedAt":"2011-04-05T22:17:58Z","isPatch":false,"sender":{"key":"eblake@redhat.com","avatar":"https://avatars.githubusercontent.com/u/32933908?v=4"},"body":"I was trying to whitelist a single file pattern in a directory\nthat I was otherwise content to ignore, but when I tried:\n\n /m4/\n !/m4/virt-*.m4\n\nthen 'git add' kept warning me that I had to use -f. I finally\nfigured out that ignoring a directory is much different than ignoring\nall files in a directory, when it comes to later negation patterns:\n\n /m4/*\n !/m4/virt-*.m4\n\nImproving the documentation will help others learn from my mistake.\n\nCC: Jonathan Nieder \nCC: Johannes Sixt \nSigned-off-by: Eric Blake \n---\n\nv3: split out fnmatch tweaks, don't tweak specification of patterns\nor existing examples but instead add an entirely new example, make\nthe example use a deeper hierarchy\n\n Documentation/gitignore.txt | 38 ++++++++++++++++++++++++++++++++++++++\n 1 files changed, 38 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\nindex 9b1e5e1..e1ad234 100644\n--- a/Documentation/gitignore.txt\n+++ b/Documentation/gitignore.txt\n@@ -139,6 +139,44 @@ EXAMPLES\n [...]\n --------------------------------------------------------------\n\n+It is possible to ignore most of a hierarchy, while still\n+white-listing a single file, by ignoring multiple files then using a\n+negation pattern for the file in question. However, this requires\n+ignoring files and not directories, since no patterns are ever matched\n+inside of an ignored directory. For nested files, it requires several\n+iterations of refined patterns.\n+\n+--------------------------------------------------------------\n+ $ git status\n+ [...]\n+ # Untracked files:\n+ [...]\n+ # Documentation/build/file\n+ # build/file\n+ # build/foo/baz\n+ # build/foo/other\n+ [...]\n+ $ cat .gitignore\n+ # Use anchoring, since `build' would ignore Documentation/build.\n+ # Do not ignore the directory itself, ...\n+ # /build/\n+ # rather ignore files in the top-level build directory, ...\n+ /build/*\n+ # but permit child directories, ...\n+ !/build/*/\n+ # then ignore all nested files, ...\n+ /build/*/*\n+ # and finally white-list the special file\n+ !/build/foo/baz\n+ $ git status\n+ [...]\n+ # Untracked files:\n+ [...]\n+ # Documentation/build/file\n+ # build/foo/baz\n+ [...]\n+--------------------------------------------------------------\n+\n Another example:\n\n --------------------------------------------------------------\n-- \n1.7.4\n"},{"id":"165228","messageId":"7vfwpwl43h.fsf@alter.siamese.dyndns.org","threadId":"27001","inReplyTo":"1302041878-24426-1-git-send-email-eblake@redhat.com","subject":"Re: [PATCHv3 1/2] Documentation: clarify fnmatch behavior in gitignore","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-04-05T22:34:42Z","receivedAt":"2011-04-05T22:34:42Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Blake writes:\n\n> Make it clear that in a .gitignore file,\n>\n> *ignore\n>\n> matches (and therefore excludes) `.gitignore', even though the\n> same glob does not match in the shell.\n>\n> Signed-off-by: Eric Blake \n> ---\n>\n> v3: separate fnmatch wording cleanup into its own patch\n>\n> Documentation/gitignore.txt | 7 ++++---\n> 1 files changed, 4 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\n> index 2e7328b..9b1e5e1 100644\n> --- a/Documentation/gitignore.txt\n> +++ b/Documentation/gitignore.txt\n> @@ -86,9 +86,10 @@ PATTERN FORMAT\n> `.gitignore` file).\n>\n> - Otherwise, git treats the pattern as a shell glob suitable\n> - for consumption by fnmatch(3) with the FNM_PATHNAME flag:\n> - wildcards in the pattern will not match a / in the pathname.\n> - For example, \"Documentation/{asterisk}.html\" matches\n> + for consumption by fnmatch(3) with the FNM_PATHNAME but not\n> + FNM_PERIOD flags: wildcards in the pattern will match leading\n> + . but not / in pathnames. For example,\n\nDoes this format correctly with asciidoc?\n\nEven if it does not get confused as a bullet or something, I think you\nwould want to quote it (and the slash), perhaps like\n\n\t`.` (dot) and `/` (slash)\n\nIn any case, I tend to think that we would want to add FNM_PERIOD to\ntighten the match in the longer term, perhaps at the 1.8.0 boundary.\n"},{"id":"165229","messageId":"7vbp0kl3p6.fsf@alter.siamese.dyndns.org","threadId":"27001","inReplyTo":"1302041878-24426-2-git-send-email-eblake@redhat.com","subject":"Re: [PATCHv3 2/2] Documentation: enhance gitignore whitelist example","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-04-05T22:43:17Z","receivedAt":"2011-04-05T22:43:17Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Blake writes:\n\n> v3: split out fnmatch tweaks, don't tweak specification of patterns\n> or existing examples but instead add an entirely new example, make\n> the example use a deeper hierarchy\n\nSomebody has to compare this vs making the existing example larger.\nGenerally speaking, I prefer to keep the number of examples smaller (the\nless the beginner has to read, the better), but the end result might be\nmore readable with a separate example, like this patch does.\n\n> + $ cat .gitignore\n> + # Use anchoring, since `build' would ignore Documentation/build.\n\n> + # Do not ignore the directory itself, ...\n> + # /build/\n> + # rather ignore files in the top-level build directory, ...\n\nDo you _really_ need these three lines? I suspect that it is unclear to\nthe first reader that the second one is a _bad_ example that is commented\nout. That is, how about starting like this, without the above three?\n\n> + # Ignore files in the top-level build directory, ...\n> + /build/*\n> + # but permit child directories, ...\n> + !/build/*/\n> + # then ignore all nested files, ...\n> + /build/*/*\n> + # and finally white-list the special file\n\nNit; s/the special file/&./;\n\n> + !/build/foo/baz\n> + $ git status\n> + [...]\n> + # Untracked files:\n> + [...]\n> + # Documentation/build/file\n> + # build/foo/baz\n> + [...]\n\nOther than that, as a free-standing example this was very straightforward\nillustration. I didn't check the flow-of-learning though.\n\nThanks.\n"},{"id":"165231","messageId":"4D9B9B15.8040600@redhat.com","threadId":"27001","inReplyTo":"7vfwpwl43h.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCHv3 1/2] Documentation: clarify fnmatch behavior in gitignore","fromName":"Eric Blake","fromEmail":"eblake@redhat.com","sentAt":"2011-04-05T22:43:33Z","receivedAt":"2011-04-05T22:43:33Z","isPatch":false,"sender":{"key":"eblake@redhat.com","avatar":"https://avatars.githubusercontent.com/u/32933908?v=4"},"body":"On 04/05/2011 04:34 PM, Junio C Hamano wrote:\n>> - Otherwise, git treats the pattern as a shell glob suitable\n>> - for consumption by fnmatch(3) with the FNM_PATHNAME flag:\n>> - wildcards in the pattern will not match a / in the pathname.\n>> - For example, \"Documentation/{asterisk}.html\" matches\n>> + for consumption by fnmatch(3) with the FNM_PATHNAME but not\n>> + FNM_PERIOD flags: wildcards in the pattern will match leading\n>> + . but not / in pathnames. For example,\n> \n> Does this format correctly with asciidoc?\n\nNo idea - I'm not an asciidoc whiz. How would I tell (or can someone\nelse offer some advice)?\n\n> \n> Even if it does not get confused as a bullet or something, I think you\n> would want to quote it (and the slash), perhaps like\n> \n> \t`.` (dot) and `/` (slash)\n> \n> In any case, I tend to think that we would want to add FNM_PERIOD to\n> tighten the match in the longer term, perhaps at the 1.8.0 boundary.\n\nPOSIX requires that \"find . -name '*'\" not use FNM_PERIOD, and I\nactually like the consistency with find(1). In other words, I would\ncomplain (then go with group consensus, if my complaint is in the\nminority) that it is a step backwards to tighten the match, where the short:\n\n dir/*\n\nwould have to become the much longer\n\n dir/*\n dir/.[!.]\n dir/.??*\n\nto properly exclude all except '.' and '..', or\n\n dir/*\n dir/.*\n\nif '.' and '..' are already special to the pattern matching.\n\n-- \nEric Blake eblake@redhat.com +1-801-349-2682\nLibvirt virtualization library http://libvirt.org\n\n"},{"id":"165266","messageId":"1302094097.25009.6.camel@drew-northup.unet.maine.edu","threadId":"27001","inReplyTo":"4D9B9B15.8040600@redhat.com","subject":"Re: [PATCHv3 1/2] Documentation: clarify fnmatch behavior in gitignore","fromName":"Drew Northup","fromEmail":"drew.northup@maine.edu","sentAt":"2011-04-06T12:48:17Z","receivedAt":"2011-04-06T12:48:17Z","isPatch":false,"sender":{"key":"drew.northup@maine.edu","avatar":"https://avatars.githubusercontent.com/u/18331571?v=4"},"body":"\nOn Tue, 2011-04-05 at 16:43 -0600, Eric Blake wrote:\n> On 04/05/2011 04:34 PM, Junio C Hamano wrote:\n> >> - Otherwise, git treats the pattern as a shell glob suitable\n> >> - for consumption by fnmatch(3) with the FNM_PATHNAME flag:\n> >> - wildcards in the pattern will not match a / in the pathname.\n> >> - For example, \"Documentation/{asterisk}.html\" matches\n> >> + for consumption by fnmatch(3) with the FNM_PATHNAME but not\n> >> + FNM_PERIOD flags: wildcards in the pattern will match leading\n> >> + . but not / in pathnames. For example,\n> > \n> > Does this format correctly with asciidoc?\n> \n> No idea - I'm not an asciidoc whiz. How would I tell (or can someone\n> else offer some advice)?\n\nFor my ongoing project of rearranging some of the Gitweb documentation I\njust went ahead and made a script based on the Documentation/Makefile\nand run that against my in-progress work. (In that case I'll get around\nto munging the local Makefile later if I decide I'm really that pleased\nwith what I've [re-]written.) This way I can incrementally become an\nAsciidoc genius if I really need to and remain a mortal otherwise.\n\n-- \n-Drew Northup\n________________________________________________\n\"As opposed to vegetable or mineral error?\"\n-John Pescatore, SANS NewsBites Vol. 12 Num. 59\n"}]}