On 2009-02-24, Junio C Hamano <gitster@xxxxxxxxx> wrote: > Sitaram Chamarty <sitaramc@xxxxxxxxx> writes: >> A few days ago, 'doener' (Björn Steinbrink) came up with >> some much simpler rules that said the same thing, and -- >> building on the insight that his rules gave me -- I came up >> with these: >> >> ----->8----- >> >> Note that rule 1 merely *modifies* rules 2 and 3, it does not >> supercede or preclude them. >> >> 1. If you pattern ends with a slash, it matches only >> directories (and their contents) >> 2. If there is no slash otherwise, it matches that name, at >> any depth in the tree >> 3. If there is a slash anywhere else, it matches that name, >> relative to the .gitignore (or $GIT_WORK_TREE if the >> pattern is from one of the other pattern sources like >> `.git/info/exclude` etc) >> >> The wildcards (`*` and `?`) do not match slashes, but otherwise >> the patterns are normal shell globs as defined by fnmatch(3) with >> the FNM_PATHNAME flag set. >> >> ----->8----- > > Nicely written, except that as a non-native speaker I fear "otherwise" and > "anywhere else" _might_ leave ambiguity for a pattern that has slash only > at the end [*1*], but I dunno. It certainly is much better than what I > wrote in the current documentation. > > Please send it in a patch form (possibly addressing my ambiguity concern > if it is real for other people) with a one-liner log message that says > "The existing documentation is unreadable even though it may be precise", > and I'll apply. I couldn't think of an easy way to clear that up without making it far more verbose. The ambiguity is partly because we're overloading the slash to control both "what matches" (only a directory, versus directory / file / symlink) and "where it matches" (anchored at the directory in which the current .gitignore is found or work tree, versus at any depth underneath). So I came up with this (see below). It keeps the "what" and the "where" clearly separate, so now the "otherwise" applies to only one preceding clause, and there is no "anywhere else". It's a somewhat larger change, replacing all 6 bullets and the line preceding them. I think it looks nicer but since I wrote it, I can't vote ;-) Please tell me what you think. If you like it, I'll send in this patch. If you prefer the previous one, I'll send that in. [I've also changed $GIT_WORK_TREE in my previous attempt to 'root of the working tree' because that variable is not normally set, and I don't want to imply that it does] ----->8----- The files containing the patterns have the following format: - A blank line matches no files, so it can serve as a separator for readability. - A line starting with # serves as a comment. This is _how_ the patterns match: - The wildcards (`*` and `?`) do not match slashes, but otherwise the patterns are normal shell globs as defined by fnmatch(3) with the FNM_PATHNAME flag set. - An optional prefix '!' negates the pattern; any matching file excluded by a previous pattern will become included again. If a negated pattern matches, this will override lower precedence patterns sources. This is _what_ the patterns match: - If the pattern ends with a slash, it matches only directories (and their contents), otherwise it matches regular files and symlinks also. This is _where_ the patterns match (a trailing slash is ignored for these rules): - If there is a slash at the start or within the pattern, it matches paths relative to the .gitignore file in which the pattern is found, or to the root of the working tree if the pattern is from one of the other pattern sources (i.e., `.git/info/exclude`, `core.excludesfile`) - Otherwise, it matches a path at any depth in the tree ----->8----- Regards, Sitaram -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
