{"thread":{"id":"8390","subject":"[PATCH] Create a new manpage for the gitignore format, and reference it elsewhere","startedAt":"2007-06-02T01:01:12Z","lastAt":"2007-06-02T01:01:12Z","messageCount":1,"participants":["Josh Triplett"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"43777","messageId":"4660C158.6070505@freedesktop.org","threadId":"8390","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-02T01:01:12Z","receivedAt":"2007-06-02T01:01:12Z","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 and documentation.  Remove\nnow-redundant information on exclude patterns from git-ls-files(1), leaving\nonly information on how git-ls-files options specify exclude patterns and what\nprecedence they have.\n\nSigned-off-by: Josh Triplett <josh@freedesktop.org>\n---\n\nNew version; fixes issues pointed out by Junio C Hamano and Frank Lichtenheld.\n\n Documentation/Makefile              |    2 +-\n Documentation/config.txt            |    3 +-\n Documentation/git-ls-files.txt      |   99 +++++-----------------------------\n Documentation/git-read-tree.txt     |    3 +-\n Documentation/git-status.txt        |    8 +--\n Documentation/gitignore.txt         |  102 +++++++++++++++++++++++++++++++++++\n Documentation/repository-layout.txt |    3 +-\n Documentation/user-manual.txt       |   12 ++--\n 8 files changed, 131 insertions(+), 101 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/config.txt b/Documentation/config.txt\nindex 3d8f03d..bb4d6e0 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -259,7 +259,8 @@ Common unit suffixes of 'k', 'm', or 'g' are supported.\n core.excludeFile::\n \tIn addition to '.gitignore' (per-directory) and\n \t'.git/info/exclude', git looks into this file for patterns\n-\tof files which are not meant to be tracked.\n+\tof files which are not meant to be tracked.  See\n+\tgitlink:gitignore[5].\n \n alias.*::\n \tCommand aliases for the gitlink:git[1] command wrapper - e.g.\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 43e0d22..a78a9ff 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.  gitlink: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..c774ff0\n--- /dev/null\n+++ b/Documentation/gitignore.txt\n@@ -0,0 +1,102 @@\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+The underlying git plumbing tools, such as\n+gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read\n+`gitignore` patterns specified by command-line options, or from\n+files specified by command-line options.  Higher-level git\n+tools, such as gitlink:git-status[1] and gitlink:git-add[1],\n+use patterns from the sources specified above.\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 # serves as a comment.\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 David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.\n+\n+GIT\n+---\n+Part of the gitlink:git[7] suite\ndiff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt\nindex 0459bd9..15221b5 100644\n--- a/Documentation/repository-layout.txt\n+++ b/Documentation/repository-layout.txt\n@@ -155,8 +155,7 @@ info/exclude::\n \texclude pattern list. `.gitignore` is the per-directory\n \tignore file.  `git status`, `git add`, `git rm` and `git\n \tclean` look at it but the core git commands do not look\n-\tat it.  See also: gitlink:git-ls-files[1] `--exclude-from`\n-\tand `--exclude-per-directory`.\n+\tat it.  See also: gitlink:gitignore[5].\n \n remotes::\n \tStores shorthands to be used to give URL and default\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 4fabb8e..7eaafa8 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -1103,12 +1103,12 @@ showing up in the output of \"`git status`\", etc.\n \n Git therefore provides \"exclude patterns\" for telling git which files to\n actively ignore. Exclude patterns are thoroughly explained in the\n-\"Exclude Patterns\" section of the gitlink:git-ls-files[1] manual page,\n-but the heart of the concept is simply a list of files which git should\n-ignore. Entries in the list may contain globs to specify multiple files,\n-or may be prefixed by \"`!`\" to explicitly include (un-ignore) a previously\n-excluded (ignored) file (i.e. later exclude patterns override earlier ones).\n-The following example should illustrate such patterns:\n+gitlink:gitignore[5] manual page, but the heart of the concept is simply\n+a list of files which git should ignore. Entries in the list may contain\n+globs to specify multiple files, or may be prefixed by \"`!`\" to\n+explicitly include (un-ignore) a previously excluded (ignored) file\n+(i.e. later exclude patterns override earlier ones).  The following\n+example should illustrate such patterns:\n \n -------------------------------------------------\n # Lines starting with '#' are considered comments.\n-- \n1.5.2\n\n\n"}]}