{"thread":{"id":"8387","subject":"[PATCH] Create a new manpage for the gitignore format, and reference it elsewhere","startedAt":"2007-06-01T20:49:47Z","lastAt":"2007-06-01T22:18:51Z","messageCount":3,"participants":["Josh Triplett","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"43759","messageId":"4660866B.7000304@freedesktop.org","threadId":"8387","inReplyTo":null,"subject":"[PATCH] Create a new manpage for the gitignore format, and reference it elsewhere","fromName":"Josh Triplett","fromEmail":"josh@freedesktop.org","sentAt":"2007-06-01T20:49:47Z","receivedAt":"2007-06-01T20:49:47Z","isPatch":true,"sender":{"key":"josh@joshtriplett.org","avatar":"https://avatars.githubusercontent.com/u/162737?v=4"},"body":"Only git-ls-files(1) describes the gitignore format in detail, and it does so\nwith reference to git-ls-files options.  Most users don't use the plumbing\ncommand git-ls-files directly, and shouldn't have to look in its manpage for\ninformation on the gitignore format.\n\nCreate a new manpage gitignore(5) (Documentation/gitignore.txt), and factor\nout the gitignore documentation into that file, changing it to refer to\n.gitignore and $GIT_DIR/info/exclude as used by porcelain commands.  Reference\ngitignore(5) from other relevant manpages.  Remove now-redundant information\non exclude patterns from git-ls-files(1), leaving only information on how\ngit-ls-files options specify exclude patterns and what precedence they have.\n\nSigned-off-by: Josh Triplett <josh@freedesktop.org>\n---\n Documentation/Makefile          |    2 +-\n Documentation/git-ls-files.txt  |   99 +++++---------------------------------\n Documentation/git-read-tree.txt |    3 +-\n Documentation/git-status.txt    |    8 +--\n Documentation/gitignore.txt     |  100 +++++++++++++++++++++++++++++++++++++++\n 5 files changed, 120 insertions(+), 92 deletions(-)\n create mode 100644 Documentation/gitignore.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 3f92783..ef4425c 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -2,7 +2,7 @@ MAN1_TXT= \\\n \t$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \\\n \t\t$(wildcard git-*.txt)) \\\n \tgitk.txt\n-MAN5_TXT=gitattributes.txt\n+MAN5_TXT=gitattributes.txt gitignore.txt\n MAN7_TXT=git.txt\n \n DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 43e0d22..62d8739 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -139,46 +139,24 @@ Exclude Patterns\n \n 'git-ls-files' can use a list of \"exclude patterns\" when\n traversing the directory tree and finding files to show when the\n-flags --others or --ignored are specified.\n+flags --others or --ignored are specified.  gitignore(5)\n+specifies the format of exclude patterns.\n \n-These exclude patterns come from these places:\n+These exclude patterns come from these places, in order:\n \n-  1. command line flag --exclude=<pattern> specifies a single\n-     pattern.\n+  1. The command line flag --exclude=<pattern> specifies a\n+     single pattern.  Patterns are ordered in the same order\n+     they appear in the command line.\n \n-  2. command line flag --exclude-from=<file> specifies a list of\n-     patterns stored in a file.\n+  2. The command line flag --exclude-from=<file> specifies a\n+     file containing a list of patterns.  Patterns are ordered\n+     in the same order they appear in the file.\n \n   3. command line flag --exclude-per-directory=<name> specifies\n      a name of the file in each directory 'git-ls-files'\n-     examines, and if exists, its contents are used as an\n-     additional list of patterns.\n-\n-An exclude pattern file used by (2) and (3) contains one pattern\n-per line.  A line that starts with a '#' can be used as comment\n-for readability.\n-\n-There are three lists of patterns that are in effect at a given\n-time.  They are built and ordered in the following way:\n-\n- * --exclude=<pattern> from the command line; patterns are\n-   ordered in the same order as they appear on the command line.\n-\n- * lines read from --exclude-from=<file>; patterns are ordered\n-   in the same order as they appear in the file.\n-\n- * When --exclude-per-directory=<name> is specified, upon\n-   entering a directory that has such a file, its contents are\n-   appended at the end of the current \"list of patterns\".  They\n-   are popped off when leaving the directory.\n-\n-Each pattern in the pattern list specifies \"a match pattern\" and\n-optionally the fate; either a file that matches the pattern is\n-considered excluded or included.  A filename is matched against\n-the patterns in the three lists; the --exclude-from list is\n-checked first, then the --exclude-per-directory list, and then\n-finally the --exclude list. The last match determines its fate.\n-If there is no match in the three lists, the fate is \"included\".\n+     examines, normally `.gitignore`.  Files in deeper\n+     directories take precedence.  Patterns are ordered in the\n+     same order they appear in the files.\n \n A pattern specified on the command line with --exclude or read\n from the file specified with --exclude-from is relative to the\n@@ -186,58 +164,9 @@ top of the directory tree.  A pattern read from a file specified\n by --exclude-per-directory is relative to the directory that the\n pattern file appears in.\n \n-An exclude pattern is of the following format:\n-\n- - an optional prefix '!' which means that the fate this pattern\n-   specifies is \"include\", not the usual \"exclude\"; the\n-   remainder of the pattern string is interpreted according to\n-   the following rules.\n-\n- - if it does not contain a slash '/', it is a shell glob\n-   pattern and used to match against the filename without\n-   leading directories.\n-\n- - otherwise, it is a shell glob pattern, suitable for\n-   consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a\n-   slash in the pattern must match a slash in the pathname.\n-   \"Documentation/\\*.html\" matches \"Documentation/git.html\" but\n-   not \"ppc/ppc.html\".  As a natural exception, \"/*.c\" matches\n-   \"cat-file.c\" but not \"mozilla-sha1/sha1.c\".\n-\n-An example:\n-\n---------------------------------------------------------------\n-    $ cat .git/info/exclude\n-    # ignore objects and archives, anywhere in the tree.\n-    *.[oa]\n-    $ cat Documentation/.gitignore\n-    # ignore generated html files,\n-    *.html\n-    # except foo.html which is maintained by hand\n-    !foo.html\n-    $ git-ls-files --ignored \\\n-        --exclude='Documentation/*.[0-9]' \\\n-        --exclude-from=.git/info/exclude \\\n-        --exclude-per-directory=.gitignore\n---------------------------------------------------------------\n-\n-Another example:\n-\n---------------------------------------------------------------\n-    $ cat .gitignore\n-    vmlinux*\n-    $ ls arch/foo/kernel/vm*\n-    arch/foo/kernel/vmlinux.lds.S\n-    $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore\n---------------------------------------------------------------\n-\n-The second .gitignore keeps `arch/foo/kernel/vmlinux.lds.S` file\n-from getting ignored.\n-\n-\n See Also\n --------\n-gitlink:git-read-tree[1]\n+gitlink:git-read-tree[1], gitlink:gitignore[5]\n \n \n Author\n@@ -246,7 +175,7 @@ Written by Linus Torvalds <torvalds@osdl.org>\n \n Documentation\n --------------\n-Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.\n+Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.\n \n GIT\n ---\ndiff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt\nindex 019c8be..acb5744 100644\n--- a/Documentation/git-read-tree.txt\n+++ b/Documentation/git-read-tree.txt\n@@ -341,7 +341,8 @@ have finished your work-in-progress), attempt the merge again.\n \n See Also\n --------\n-gitlink:git-write-tree[1]; gitlink:git-ls-files[1]\n+gitlink:git-write-tree[1]; gitlink:git-ls-files[1];\n+gitlink:gitignore[5]\n \n \n Author\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex d701538..1fd1af1 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -42,11 +42,9 @@ mean the same thing and the latter is kept for backward\n compatibility) and `color.status.<slot>` configuration variables\n to colorize its output.\n \n-As for gitlink:git-add[1], the configuration variable\n-'core.excludesfile' can indicate a path to a file containing patterns\n-of file names to exclude, in addition to patterns given in\n-'info/exclude' and '.gitignore'.\n-\n+See Also\n+--------\n+gitlink:gitignore[5]\n \n Author\n ------\ndiff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt\nnew file mode 100644\nindex 0000000..190bd9f\n--- /dev/null\n+++ b/Documentation/gitignore.txt\n@@ -0,0 +1,100 @@\n+gitignore(5)\n+============\n+\n+NAME\n+----\n+gitignore - Specifies intentionally untracked files to ignore\n+\n+SYNOPSIS\n+--------\n+$GIT_DIR/info/exclude, .gitignore\n+\n+DESCRIPTION\n+-----------\n+\n+A `gitignore` file specifies intentionally untracked files that\n+git should ignore.  Each line in a `gitignore` file specifies a\n+pattern.\n+\n+When deciding whether to ignore a path, git normally checks\n+`gitignore` patterns from multiple sources, with the following\n+order of precedence:\n+\n+ * Patterns read from the file specified by the configuration\n+   variable 'core.excludesfile'.\n+\n+ * Patterns read from `$GIT_DIR/info/exclude`.\n+\n+ * Patterns read from a `.gitignore` file in the same directory\n+   as the path, or in any parent directory, ordered from the\n+   deepest such file to a file in the root of the repository.\n+   These patterns match relative to the location of the\n+   `.gitignore` file.  A project normally includes such\n+   `.gitignore` files in its repository, containing patterns for\n+   files generated as part of the project build.\n+\n+Some git plumbing tools, such as git-ls-files(1) and\n+git-read-tree(1), read `gitignore` patterns specified by\n+command-line options, or from files specified by command-line\n+options.\n+\n+Patterns have the following format:\n+\n+ - A blank line matches no files, so it can serve as a separator\n+   for readability.\n+\n+ - A line starting with # \n+\n+ - An optional prefix '!' which negates the pattern; any\n+   matching file excluded by a previous pattern will become\n+   included again.\n+\n+ - If the pattern does not contain a slash '/', git treats it as\n+   a shell glob pattern and checks for a match against the\n+   pathname without leading directories.\n+\n+ - Otherwise, git treats the pattern as a shell glob suitable\n+   for consumption by fnmatch(3) with the FNM_PATHNAME flag: any\n+   slash in the pattern must match a slash in the pathname.  For\n+   example, \"Documentation/\\*.html\" matches\n+   \"Documentation/git.html\" but not \"ppc/ppc.html\".  A leading\n+   slash matches the beginning of the pathname; for example,\n+   \"/*.c\" matches \"cat-file.c\" but not \"mozilla-sha1/sha1.c\".\n+\n+An example:\n+\n+--------------------------------------------------------------\n+    $ cat .git/info/exclude\n+    # ignore objects and archives, anywhere in the tree.\n+    *.[oa]\n+    $ cat Documentation/.gitignore\n+    # ignore generated html files,\n+    *.html\n+    # except foo.html which is maintained by hand\n+    !foo.html\n+    $ git-ls-files --ignored \\\n+        --exclude='Documentation/*.[0-9]' \\\n+        --exclude-from=.git/info/exclude \\\n+        --exclude-per-directory=.gitignore\n+--------------------------------------------------------------\n+\n+Another example:\n+\n+--------------------------------------------------------------\n+    $ cat .gitignore\n+    vmlinux*\n+    $ ls arch/foo/kernel/vm*\n+    arch/foo/kernel/vmlinux.lds.S\n+    $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore\n+--------------------------------------------------------------\n+\n+The second .gitignore prevents git from ignoring\n+`arch/foo/kernel/vmlinux.lds.S`.\n+\n+Documentation\n+-------------\n+Documentation by Josh Triplett.\n+\n+GIT\n+---\n+Part of the gitlink:git[7] suite\n-- \n1.5.2\n\n\n"},{"id":"43764","messageId":"7vtztrxs8r.fsf@assigned-by-dhcp.cox.net","threadId":"8387","inReplyTo":"4660866B.7000304@freedesktop.org","subject":"Re: [PATCH] Create a new manpage for the gitignore format, and reference it elsewhere","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2007-06-01T21:46:44Z","receivedAt":"2007-06-01T21:46:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Triplett <josh@freedesktop.org> writes:\n\nThanks, but shouldn't all the in-text mention of \"gitignore(5)\"\nand friends, not just in \"See Also\" section, use\n\"gitlink:gitignore[5]\" instead?\n"},{"id":"43765","messageId":"46609B4B.9070104@freedesktop.org","threadId":"8387","inReplyTo":"7vtztrxs8r.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Create a new manpage for the gitignore format, and reference it elsewhere","fromName":"Josh Triplett","fromEmail":"josh@freedesktop.org","sentAt":"2007-06-01T22:18:51Z","receivedAt":"2007-06-01T22:18:51Z","isPatch":true,"sender":{"key":"josh@joshtriplett.org","avatar":"https://avatars.githubusercontent.com/u/162737?v=4"},"body":"Junio C Hamano wrote:\n> Josh Triplett <josh@freedesktop.org> writes:\n> \n> Thanks, but shouldn't all the in-text mention of \"gitignore(5)\"\n> and friends, not just in \"See Also\" section, use\n> \"gitlink:gitignore[5]\" instead?\n\nYes, thanks.  I followed some other example that didn't do that.\n\nNew patch momentarily.\n\n- Josh Triplett\n\n\n"}]}