summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2013-01-24 05:19:10 (GMT)
committerJunio C Hamano <gitster@pobox.com>2013-01-24 05:19:10 (GMT)
commita39b15b4f6a3f08b67b17d968935d177821e680f (patch)
tree188d8c7c1b4a4efa027516be3808db5e37b2bf13 /Documentation
parentf12e49ae877ad0644b9b9939b7cb742da98691d2 (diff)
parent72aeb18772deeb386da7dd8997b969877bd29e41 (diff)
downloadgit-a39b15b4f6a3f08b67b17d968935d177821e680f.zip
git-a39b15b4f6a3f08b67b17d968935d177821e680f.tar.gz
git-a39b15b4f6a3f08b67b17d968935d177821e680f.tar.bz2
Merge branch 'as/check-ignore'
Add a new command "git check-ignore" for debugging .gitignore files. The variable names may want to get cleaned up but that can be done in-tree. * as/check-ignore: clean.c, ls-files.c: respect encapsulation of exclude_list_groups t0008: avoid brace expansion add git-check-ignore sub-command setup.c: document get_pathspec() add.c: extract new die_if_path_beyond_symlink() for reuse add.c: extract check_path_for_gitlink() from treat_gitlinks() for reuse pathspec.c: rename newly public functions for clarity add.c: move pathspec matchers into new pathspec.c for reuse add.c: remove unused argument from validate_pathspec() dir.c: improve docs for match_pathspec() and match_pathspec_depth() dir.c: provide clear_directory() for reclaiming dir_struct memory dir.c: keep track of where patterns came from dir.c: use a single struct exclude_list per source of excludes Conflicts: builtin/ls-files.c dir.c
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/git-check-ignore.txt89
-rw-r--r--Documentation/gitignore.txt6
-rw-r--r--Documentation/technical/api-directory-listing.txt14
3 files changed, 102 insertions, 7 deletions
diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
new file mode 100644
index 0000000..854e4d0
--- /dev/null
+++ b/Documentation/git-check-ignore.txt
@@ -0,0 +1,89 @@
+git-check-ignore(1)
+===================
+
+NAME
+----
+git-check-ignore - Debug gitignore / exclude files
+
+
+SYNOPSIS
+--------
+[verse]
+'git check-ignore' [options] pathname...
+'git check-ignore' [options] --stdin < <list-of-paths>
+
+DESCRIPTION
+-----------
+
+For each pathname given via the command-line or from a file via
+`--stdin`, show the pattern from .gitignore (or other input files to
+the exclude mechanism) that decides if the pathname is excluded or
+included. Later patterns within a file take precedence over earlier
+ones.
+
+OPTIONS
+-------
+-q, --quiet::
+ Don't output anything, just set exit status. This is only
+ valid with a single pathname.
+
+-v, --verbose::
+ Also output details about the matching pattern (if any)
+ for each given pathname.
+
+--stdin::
+ Read file names from stdin instead of from the command-line.
+
+-z::
+ The output format is modified to be machine-parseable (see
+ below). If `--stdin` is also given, input paths are separated
+ with a NUL character instead of a linefeed character.
+
+OUTPUT
+------
+
+By default, any of the given pathnames which match an ignore pattern
+will be output, one per line. If no pattern matches a given path,
+nothing will be output for that path; this means that path will not be
+ignored.
+
+If `--verbose` is specified, the output is a series of lines of the form:
+
+<source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname>
+
+<pathname> is the path of a file being queried, <pattern> is the
+matching pattern, <source> is the pattern's source file, and <linenum>
+is the line number of the pattern within that source. If the pattern
+contained a `!` prefix or `/` suffix, it will be preserved in the
+output. <source> will be an absolute path when referring to the file
+configured by `core.excludesfile`, or relative to the repository root
+when referring to `.git/info/exclude` or a per-directory exclude file.
+
+If `-z` is specified, the pathnames in the output are delimited by the
+null character; if `--verbose` is also specified then null characters
+are also used instead of colons and hard tabs:
+
+<source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL>
+
+
+EXIT STATUS
+-----------
+
+0::
+ One or more of the provided paths is ignored.
+
+1::
+ None of the provided paths are ignored.
+
+128::
+ A fatal error was encountered.
+
+SEE ALSO
+--------
+linkgit:gitignore[5]
+linkgit:gitconfig[5]
+linkgit:git-ls-files[5]
+
+GIT
+---
+Part of the linkgit:git[1] suite
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 91a6438..0da205f 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -184,8 +184,10 @@ The second .gitignore prevents git from ignoring
SEE ALSO
--------
-linkgit:git-rm[1], linkgit:git-update-index[1],
-linkgit:gitrepository-layout[5]
+linkgit:git-rm[1],
+linkgit:git-update-index[1],
+linkgit:gitrepository-layout[5],
+linkgit:git-check-ignore[1]
GIT
---
diff --git a/Documentation/technical/api-directory-listing.txt b/Documentation/technical/api-directory-listing.txt
index 944fc39..9d3e352 100644
--- a/Documentation/technical/api-directory-listing.txt
+++ b/Documentation/technical/api-directory-listing.txt
@@ -67,11 +67,13 @@ marked. If you to exclude files, make sure you have loaded index first.
* Prepare `struct dir_struct dir` and clear it with `memset(&dir, 0,
sizeof(dir))`.
-* Call `add_exclude()` to add single exclude pattern,
- `add_excludes_from_file()` to add patterns from a file
- (e.g. `.git/info/exclude`), and/or set `dir.exclude_per_dir`. A
- short-hand function `setup_standard_excludes()` can be used to set up
- the standard set of exclude settings.
+* To add single exclude pattern, call `add_exclude_list()` and then
+ `add_exclude()`.
+
+* To add patterns from a file (e.g. `.git/info/exclude`), call
+ `add_excludes_from_file()` , and/or set `dir.exclude_per_dir`. A
+ short-hand function `setup_standard_excludes()` can be used to set
+ up the standard set of exclude settings.
* Set options described in the Data Structure section above.
@@ -79,4 +81,6 @@ marked. If you to exclude files, make sure you have loaded index first.
* Use `dir.entries[]`.
+* Call `clear_directory()` when none of the contained elements are no longer in use.
+
(JC)