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>
This commit is contained in:
Josh Triplett
Junio C Hamano
parent
4159c57813
commit
cedb8d5d33
@ -2,7 +2,7 @@ MAN1_TXT= \
|
||||
$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
|
||||
$(wildcard git-*.txt)) \
|
||||
gitk.txt
|
||||
MAN5_TXT=gitattributes.txt
|
||||
MAN5_TXT=gitattributes.txt gitignore.txt
|
||||
MAN7_TXT=git.txt
|
||||
|
||||
DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
|
||||
|
||||
@ -266,7 +266,8 @@ Common unit suffixes of 'k', 'm', or 'g' are supported.
|
||||
core.excludeFile::
|
||||
In addition to '.gitignore' (per-directory) and
|
||||
'.git/info/exclude', git looks into this file for patterns
|
||||
of files which are not meant to be tracked.
|
||||
of files which are not meant to be tracked. See
|
||||
gitlink:gitignore[5].
|
||||
|
||||
alias.*::
|
||||
Command aliases for the gitlink:git[1] command wrapper - e.g.
|
||||
|
||||
@ -139,46 +139,24 @@ Exclude Patterns
|
||||
|
||||
'git-ls-files' can use a list of "exclude patterns" when
|
||||
traversing the directory tree and finding files to show when the
|
||||
flags --others or --ignored are specified.
|
||||
flags --others or --ignored are specified. gitlink:gitignore[5]
|
||||
specifies the format of exclude patterns.
|
||||
|
||||
These exclude patterns come from these places:
|
||||
These exclude patterns come from these places, in order:
|
||||
|
||||
1. command line flag --exclude=<pattern> specifies a single
|
||||
pattern.
|
||||
1. The command line flag --exclude=<pattern> specifies a
|
||||
single pattern. Patterns are ordered in the same order
|
||||
they appear in the command line.
|
||||
|
||||
2. command line flag --exclude-from=<file> specifies a list of
|
||||
patterns stored in a file.
|
||||
2. The command line flag --exclude-from=<file> specifies a
|
||||
file containing a list of patterns. Patterns are ordered
|
||||
in the same order they appear in the file.
|
||||
|
||||
3. command line flag --exclude-per-directory=<name> specifies
|
||||
a name of the file in each directory 'git-ls-files'
|
||||
examines, and if exists, its contents are used as an
|
||||
additional list of patterns.
|
||||
|
||||
An exclude pattern file used by (2) and (3) contains one pattern
|
||||
per line. A line that starts with a '#' can be used as comment
|
||||
for readability.
|
||||
|
||||
There are three lists of patterns that are in effect at a given
|
||||
time. They are built and ordered in the following way:
|
||||
|
||||
* --exclude=<pattern> from the command line; patterns are
|
||||
ordered in the same order as they appear on the command line.
|
||||
|
||||
* lines read from --exclude-from=<file>; patterns are ordered
|
||||
in the same order as they appear in the file.
|
||||
|
||||
* When --exclude-per-directory=<name> is specified, upon
|
||||
entering a directory that has such a file, its contents are
|
||||
appended at the end of the current "list of patterns". They
|
||||
are popped off when leaving the directory.
|
||||
|
||||
Each pattern in the pattern list specifies "a match pattern" and
|
||||
optionally the fate; either a file that matches the pattern is
|
||||
considered excluded or included. A filename is matched against
|
||||
the patterns in the three lists; the --exclude-from list is
|
||||
checked first, then the --exclude-per-directory list, and then
|
||||
finally the --exclude list. The last match determines its fate.
|
||||
If there is no match in the three lists, the fate is "included".
|
||||
examines, normally `.gitignore`. Files in deeper
|
||||
directories take precedence. Patterns are ordered in the
|
||||
same order they appear in the files.
|
||||
|
||||
A pattern specified on the command line with --exclude or read
|
||||
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
|
||||
by --exclude-per-directory is relative to the directory that the
|
||||
pattern file appears in.
|
||||
|
||||
An exclude pattern is of the following format:
|
||||
|
||||
- an optional prefix '!' which means that the fate this pattern
|
||||
specifies is "include", not the usual "exclude"; the
|
||||
remainder of the pattern string is interpreted according to
|
||||
the following rules.
|
||||
|
||||
- if it does not contain a slash '/', it is a shell glob
|
||||
pattern and used to match against the filename without
|
||||
leading directories.
|
||||
|
||||
- otherwise, it is a shell glob pattern, suitable for
|
||||
consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a
|
||||
slash in the pattern must match a slash in the pathname.
|
||||
"Documentation/\*.html" matches "Documentation/git.html" but
|
||||
not "ppc/ppc.html". As a natural exception, "/*.c" matches
|
||||
"cat-file.c" but not "mozilla-sha1/sha1.c".
|
||||
|
||||
An example:
|
||||
|
||||
--------------------------------------------------------------
|
||||
$ 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-ls-files --ignored \
|
||||
--exclude='Documentation/*.[0-9]' \
|
||||
--exclude-from=.git/info/exclude \
|
||||
--exclude-per-directory=.gitignore
|
||||
--------------------------------------------------------------
|
||||
|
||||
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 keeps `arch/foo/kernel/vmlinux.lds.S` file
|
||||
from getting ignored.
|
||||
|
||||
|
||||
See Also
|
||||
--------
|
||||
gitlink:git-read-tree[1]
|
||||
gitlink:git-read-tree[1], gitlink:gitignore[5]
|
||||
|
||||
|
||||
Author
|
||||
@ -246,7 +175,7 @@ Written by Linus Torvalds <torvalds@osdl.org>
|
||||
|
||||
Documentation
|
||||
--------------
|
||||
Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
|
||||
Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.
|
||||
|
||||
GIT
|
||||
---
|
||||
|
||||
@ -341,7 +341,8 @@ have finished your work-in-progress), attempt the merge again.
|
||||
|
||||
See Also
|
||||
--------
|
||||
gitlink:git-write-tree[1]; gitlink:git-ls-files[1]
|
||||
gitlink:git-write-tree[1]; gitlink:git-ls-files[1];
|
||||
gitlink:gitignore[5]
|
||||
|
||||
|
||||
Author
|
||||
|
||||
@ -42,11 +42,9 @@ mean the same thing and the latter is kept for backward
|
||||
compatibility) and `color.status.<slot>` configuration variables
|
||||
to colorize its output.
|
||||
|
||||
As for gitlink:git-add[1], the configuration variable
|
||||
'core.excludesfile' can indicate a path to a file containing patterns
|
||||
of file names to exclude, in addition to patterns given in
|
||||
'info/exclude' and '.gitignore'.
|
||||
|
||||
See Also
|
||||
--------
|
||||
gitlink:gitignore[5]
|
||||
|
||||
Author
|
||||
------
|
||||
|
||||
116
Documentation/gitignore.txt
Normal file
116
Documentation/gitignore.txt
Normal file
@ -0,0 +1,116 @@
|
||||
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
|
||||
@ -155,8 +155,7 @@ info/exclude::
|
||||
exclude pattern list. `.gitignore` is the per-directory
|
||||
ignore file. `git status`, `git add`, `git rm` and `git
|
||||
clean` look at it but the core git commands do not look
|
||||
at it. See also: gitlink:git-ls-files[1] `--exclude-from`
|
||||
and `--exclude-per-directory`.
|
||||
at it. See also: gitlink:gitignore[5].
|
||||
|
||||
remotes::
|
||||
Stores shorthands to be used to give URL and default
|
||||
|
||||
@ -1103,12 +1103,12 @@ showing up in the output of "`git status`", etc.
|
||||
|
||||
Git therefore provides "exclude patterns" for telling git which files to
|
||||
actively ignore. Exclude patterns are thoroughly explained in the
|
||||
"Exclude Patterns" section of the gitlink:git-ls-files[1] manual page,
|
||||
but the heart of the concept is simply a list of files which git should
|
||||
ignore. Entries in the list may contain globs to specify multiple files,
|
||||
or may be prefixed by "`!`" to explicitly include (un-ignore) a previously
|
||||
excluded (ignored) file (i.e. later exclude patterns override earlier ones).
|
||||
The following example should illustrate such patterns:
|
||||
gitlink:gitignore[5] manual page, but the heart of the concept is simply
|
||||
a list of files which git should ignore. Entries in the list may contain
|
||||
globs to specify multiple files, or may be prefixed by "`!`" to
|
||||
explicitly include (un-ignore) a previously excluded (ignored) file
|
||||
(i.e. later exclude patterns override earlier ones). The following
|
||||
example should illustrate such patterns:
|
||||
|
||||
-------------------------------------------------
|
||||
# Lines starting with '#' are considered comments.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user