[thirdparty/git.git] / Documentation / gitignore.txt

gitignore(5)
============

NAME
----
gitignore - Specifies intentionally untracked files to ignore

SYNOPSIS
--------
$GIT_DIR/info/exclude, .gitignore

DESCRIPTION
-----------

A `gitignore` file specifies intentionally untracked files that
git should ignore.  Each line in a `gitignore` file specifies a
pattern.

When deciding whether to ignore a path, git normally checks
`gitignore` patterns from multiple sources, with the following
order of precedence:

 * Patterns read from the file specified by the configuration
   variable 'core.excludesfile'.

 * Patterns read from `$GIT_DIR/info/exclude`.

 * Patterns read from a `.gitignore` file in the same directory
   as the path, or in any parent directory, ordered from the
   deepest such file to a file in the root of the repository.
   These patterns match relative to the location of the
   `.gitignore` file.  A project normally includes such
   `.gitignore` files in its repository, containing patterns for
   files generated as part of the project build.

The underlying git plumbing tools, such as
gitlink:git-ls-files[1] and gitlink:git-read-tree[1], read
`gitignore` patterns specified by command-line options, or from
files specified by command-line options.  Higher-level git
tools, such as gitlink:git-status[1] and gitlink:git-add[1],
use patterns from the sources specified above.

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.

 - An optional prefix '!' which negates the pattern; any
   matching file excluded by a previous pattern will become
   included again.

 - If the pattern does not contain a slash '/', git treats it as
   a shell glob pattern and checks for a match against the
   pathname without leading directories.

 - Otherwise, git treats the pattern as a shell glob suitable
   for consumption by fnmatch(3) with the FNM_PATHNAME flag:
   wildcards in the pattern will not match a / in the pathname.
   For example, "Documentation/\*.html" matches
   "Documentation/git.html" but not
   "Documentation/ppc/ppc.html".  A leading slash matches the
   beginning of the pathname; for example, "/*.c" matches
   "cat-file.c" but not "mozilla-sha1/sha1.c".

An example:

--------------------------------------------------------------
    $ git-status
    [...]
    # Untracked files:
    [...]
    #       Documentation/foo.html
    #       Documentation/gitignore.html
    #       file.o
    #       lib.a
    #       src/internal.o
    [...]
    $ cat .git/info/exclude
    # ignore objects and archives, anywhere in the tree.
    *.[oa]
    $ cat Documentation/.gitignore
    # ignore generated html files,
    *.html
    # except foo.html which is maintained by hand
    !foo.html
    $ git-status
    [...]
    # Untracked files:
    [...]
    #       Documentation/foo.html
    [...]
--------------------------------------------------------------

Another example:

--------------------------------------------------------------
    $ cat .gitignore
    vmlinux*
    $ ls arch/foo/kernel/vm*
    arch/foo/kernel/vmlinux.lds.S
    $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
--------------------------------------------------------------

The second .gitignore prevents git from ignoring
`arch/foo/kernel/vmlinux.lds.S`.

Documentation
-------------
Documentation by David Greaves, Junio C Hamano, Josh Triplett,
Frank Lichtenheld, and the git-list <git@vger.kernel.org>.

GIT
---
Part of the gitlink:git[7] suite
Commit	Line	Data
cedb8d5d JT	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