@matheusbsbs / matheus-bagliano / commits / cedb8d5d33
Fork 0

Create a new manpage for the gitignore format, and reference it elsewhere

Only git-ls-files(1) describes the gitignore format in detail, and it does so with reference to git-ls-files options. Most users don't use the plumbing command git-ls-files directly, and shouldn't have to look in its manpage for information on the gitignore format. Create a new manpage gitignore(5) (Documentation/gitignore.txt), and factor out the gitignore documentation into that file, changing it to refer to .gitignore and $GIT_DIR/info/exclude as used by porcelain commands. Reference gitignore(5) from other relevant manpages and documentation. Remove now-redundant information on exclude patterns from git-ls-files(1), leaving only information on how git-ls-files options specify exclude patterns and what precedence they have. Signed-off-by: Josh Triplett <josh@freedesktop.org> Signed-off-by: Junio C Hamano <junkio@cox.net>

Josh Triplett committed Jun 2, 2007 at 10:08 UTC cedb8d5d33e6496cfc70493db841b3db886e8658
8 files changed +145 -101
Documentation/Makefile
+1 -1
@@ -2,7 +2,7 @@ MAN1_TXT= \
2 $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
3 $(wildcard git-*.txt)) \
4 gitk.txt
5 -MAN5_TXT=gitattributes.txt
5 +MAN5_TXT=gitattributes.txt gitignore.txt
6 MAN7_TXT=git.txt
7
8 DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
Documentation/config.txt
+2 -1
@@ -266,7 +266,8 @@ Common unit suffixes of 'k', 'm', or 'g' are supported.
266 core.excludeFile::
267 In addition to '.gitignore' (per-directory) and
268 '.git/info/exclude', git looks into this file for patterns
269 - of files which are not meant to be tracked.
269 + of files which are not meant to be tracked. See
270 + gitlink:gitignore[5].
271
272 alias.*::
273 Command aliases for the gitlink:git[1] command wrapper - e.g.
Documentation/git-ls-files.txt
+14 -85
@@ -139,46 +139,24 @@ Exclude Patterns
139
140 'git-ls-files' can use a list of "exclude patterns" when
141 traversing the directory tree and finding files to show when the
142 -flags --others or --ignored are specified.
142 +flags --others or --ignored are specified. gitlink:gitignore[5]
143 +specifies the format of exclude patterns.
144
144 -These exclude patterns come from these places:
145 +These exclude patterns come from these places, in order:
146
146 - 1. command line flag --exclude=<pattern> specifies a single
147 - pattern.
147 + 1. The command line flag --exclude=<pattern> specifies a
148 + single pattern. Patterns are ordered in the same order
149 + they appear in the command line.
150
149 - 2. command line flag --exclude-from=<file> specifies a list of
150 - patterns stored in a file.
151 + 2. The command line flag --exclude-from=<file> specifies a
152 + file containing a list of patterns. Patterns are ordered
153 + in the same order they appear in the file.
154
155 3. command line flag --exclude-per-directory=<name> specifies
156 a name of the file in each directory 'git-ls-files'
154 - examines, and if exists, its contents are used as an
155 - additional list of patterns.
156 -
157 -An exclude pattern file used by (2) and (3) contains one pattern
158 -per line. A line that starts with a '#' can be used as comment
159 -for readability.
160 -
161 -There are three lists of patterns that are in effect at a given
162 -time. They are built and ordered in the following way:
163 -
164 - * --exclude=<pattern> from the command line; patterns are
165 - ordered in the same order as they appear on the command line.
166 -
167 - * lines read from --exclude-from=<file>; patterns are ordered
168 - in the same order as they appear in the file.
169 -
170 - * When --exclude-per-directory=<name> is specified, upon
171 - entering a directory that has such a file, its contents are
172 - appended at the end of the current "list of patterns". They
173 - are popped off when leaving the directory.
174 -
175 -Each pattern in the pattern list specifies "a match pattern" and
176 -optionally the fate; either a file that matches the pattern is
177 -considered excluded or included. A filename is matched against
178 -the patterns in the three lists; the --exclude-from list is
179 -checked first, then the --exclude-per-directory list, and then
180 -finally the --exclude list. The last match determines its fate.
181 -If there is no match in the three lists, the fate is "included".
157 + examines, normally `.gitignore`. Files in deeper
158 + directories take precedence. Patterns are ordered in the
159 + same order they appear in the files.
160
161 A pattern specified on the command line with --exclude or read
162 from the file specified with --exclude-from is relative to the
@@ -186,58 +164,9 @@ top of the directory tree. A pattern read from a file specified
164 by --exclude-per-directory is relative to the directory that the
165 pattern file appears in.
166
189 -An exclude pattern is of the following format:
190 -
191 - - an optional prefix '!' which means that the fate this pattern
192 - specifies is "include", not the usual "exclude"; the
193 - remainder of the pattern string is interpreted according to
194 - the following rules.
195 -
196 - - if it does not contain a slash '/', it is a shell glob
197 - pattern and used to match against the filename without
198 - leading directories.
199 -
200 - - otherwise, it is a shell glob pattern, suitable for
201 - consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a
202 - slash in the pattern must match a slash in the pathname.
203 - "Documentation/\*.html" matches "Documentation/git.html" but
204 - not "ppc/ppc.html". As a natural exception, "/*.c" matches
205 - "cat-file.c" but not "mozilla-sha1/sha1.c".
206 -
207 -An example:
208 -
209 ---------------------------------------------------------------
210 - $ cat .git/info/exclude
211 - # ignore objects and archives, anywhere in the tree.
212 - *.[oa]
213 - $ cat Documentation/.gitignore
214 - # ignore generated html files,
215 - *.html
216 - # except foo.html which is maintained by hand
217 - !foo.html
218 - $ git-ls-files --ignored \
219 - --exclude='Documentation/*.[0-9]' \
220 - --exclude-from=.git/info/exclude \
221 - --exclude-per-directory=.gitignore
222 ---------------------------------------------------------------
223 -
224 -Another example:
225 -
226 ---------------------------------------------------------------
227 - $ cat .gitignore
228 - vmlinux*
229 - $ ls arch/foo/kernel/vm*
230 - arch/foo/kernel/vmlinux.lds.S
231 - $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
232 ---------------------------------------------------------------
233 -
234 -The second .gitignore keeps `arch/foo/kernel/vmlinux.lds.S` file
235 -from getting ignored.
236 -
237 -
167 See Also
168 --------
240 -gitlink:git-read-tree[1]
169 +gitlink:git-read-tree[1], gitlink:gitignore[5]
170
171
172 Author
@@ -246,7 +175,7 @@ Written by Linus Torvalds <torvalds@osdl.org>
175
176 Documentation
177 --------------
249 -Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
178 +Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.
179
180 GIT
181 ---
Documentation/git-read-tree.txt
+2 -1
@@ -341,7 +341,8 @@ have finished your work-in-progress), attempt the merge again.
341
342 See Also
343 --------
344 -gitlink:git-write-tree[1]; gitlink:git-ls-files[1]
344 +gitlink:git-write-tree[1]; gitlink:git-ls-files[1];
345 +gitlink:gitignore[5]
346
347
348 Author
Documentation/git-status.txt
+3 -5
@@ -42,11 +42,9 @@ mean the same thing and the latter is kept for backward
42 compatibility) and `color.status.<slot>` configuration variables
43 to colorize its output.
44
45 -As for gitlink:git-add[1], the configuration variable
46 -'core.excludesfile' can indicate a path to a file containing patterns
47 -of file names to exclude, in addition to patterns given in
48 -'info/exclude' and '.gitignore'.
49 -
45 +See Also
46 +--------
47 +gitlink:gitignore[5]
48
49 Author
50 ------
Documentation/gitignore.txt new
+116
@@ -0,0 +1,116 @@
1 +gitignore(5)
2 +============
3 +
4 +NAME
5 +----
6 +gitignore - Specifies intentionally untracked files to ignore
7 +
8 +SYNOPSIS
9 +--------
10 +$GIT_DIR/info/exclude, .gitignore
11 +
12 +DESCRIPTION
13 +-----------
14 +
15 +A `gitignore` file specifies intentionally untracked files that
16 +git should ignore. Each line in a `gitignore` file specifies a
17 +pattern.
18 +
19 +When deciding whether to ignore a path, git normally checks
20 +`gitignore` patterns from multiple sources, with the following
21 +order of precedence:
22 +
23 + * Patterns read from the file specified by the configuration
24 + variable 'core.excludesfile'.
25 +
26 + * Patterns read from `$GIT_DIR/info/exclude`.
27 +
28 + * Patterns read from a `.gitignore` file in the same directory
29 + as the path, or in any parent directory, ordered from the
30 + deepest such file to a file in the root of the repository.
31 + These patterns match relative to the location of the
32 + `.gitignore` file. A project normally includes such
33 + `.gitignore` files in its repository, containing patterns for
34 + files generated as part of the project build.
35 +
36 +The underlying git plumbing tools, such as
37 +gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read
38 +`gitignore` patterns specified by command-line options, or from
39 +files specified by command-line options. Higher-level git
40 +tools, such as gitlink:git-status[1] and gitlink:git-add[1],
41 +use patterns from the sources specified above.
42 +
43 +Patterns have the following format:
44 +
45 + - A blank line matches no files, so it can serve as a separator
46 + for readability.
47 +
48 + - A line starting with # serves as a comment.
49 +
50 + - An optional prefix '!' which negates the pattern; any
51 + matching file excluded by a previous pattern will become
52 + included again.
53 +
54 + - If the pattern does not contain a slash '/', git treats it as
55 + a shell glob pattern and checks for a match against the
56 + pathname without leading directories.
57 +
58 + - Otherwise, git treats the pattern as a shell glob suitable
59 + for consumption by fnmatch(3) with the FNM_PATHNAME flag:
60 + wildcards in the pattern will not match a / in the pathname.
61 + For example, "Documentation/\*.html" matches
62 + "Documentation/git.html" but not
63 + "Documentation/ppc/ppc.html". A leading slash matches the
64 + beginning of the pathname; for example, "/*.c" matches
65 + "cat-file.c" but not "mozilla-sha1/sha1.c".
66 +
67 +An example:
68 +
69 +--------------------------------------------------------------
70 + $ git-status
71 + [...]
72 + # Untracked files:
73 + [...]
74 + # Documentation/foo.html
75 + # Documentation/gitignore.html
76 + # file.o
77 + # lib.a
78 + # src/internal.o
79 + [...]
80 + $ cat .git/info/exclude
81 + # ignore objects and archives, anywhere in the tree.
82 + *.[oa]
83 + $ cat Documentation/.gitignore
84 + # ignore generated html files,
85 + *.html
86 + # except foo.html which is maintained by hand
87 + !foo.html
88 + $ git-status
89 + [...]
90 + # Untracked files:
91 + [...]
92 + # Documentation/foo.html
93 + [...]
94 +--------------------------------------------------------------
95 +
96 +Another example:
97 +
98 +--------------------------------------------------------------
99 + $ cat .gitignore
100 + vmlinux*
101 + $ ls arch/foo/kernel/vm*
102 + arch/foo/kernel/vmlinux.lds.S
103 + $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
104 +--------------------------------------------------------------
105 +
106 +The second .gitignore prevents git from ignoring
107 +`arch/foo/kernel/vmlinux.lds.S`.
108 +
109 +Documentation
110 +-------------
111 +Documentation by David Greaves, Junio C Hamano, Josh Triplett,
112 +Frank Lichtenheld, and the git-list <git@vger.kernel.org>.
113 +
114 +GIT
115 +---
116 +Part of the gitlink:git[7] suite
Documentation/repository-layout.txt
+1 -2
@@ -155,8 +155,7 @@ info/exclude::
155 exclude pattern list. `.gitignore` is the per-directory
156 ignore file. `git status`, `git add`, `git rm` and `git
157 clean` look at it but the core git commands do not look
158 - at it. See also: gitlink:git-ls-files[1] `--exclude-from`
159 - and `--exclude-per-directory`.
158 + at it. See also: gitlink:gitignore[5].
159
160 remotes::
161 Stores shorthands to be used to give URL and default
Documentation/user-manual.txt
+6 -6
@@ -1103,12 +1103,12 @@ showing up in the output of "`git status`", etc.
1103
1104 Git therefore provides "exclude patterns" for telling git which files to
1105 actively ignore. Exclude patterns are thoroughly explained in the
1106 -"Exclude Patterns" section of the gitlink:git-ls-files[1] manual page,
1107 -but the heart of the concept is simply a list of files which git should
1108 -ignore. Entries in the list may contain globs to specify multiple files,
1109 -or may be prefixed by "`!`" to explicitly include (un-ignore) a previously
1110 -excluded (ignored) file (i.e. later exclude patterns override earlier ones).
1111 -The following example should illustrate such patterns:
1106 +gitlink:gitignore[5] manual page, but the heart of the concept is simply
1107 +a list of files which git should ignore. Entries in the list may contain
1108 +globs to specify multiple files, or may be prefixed by "`!`" to
1109 +explicitly include (un-ignore) a previously excluded (ignored) file
1110 +(i.e. later exclude patterns override earlier ones). The following
1111 +example should illustrate such patterns:
1112
1113 -------------------------------------------------
1114 # Lines starting with '#' are considered comments.