diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/Makefile | 8 | ||||
| -rw-r--r-- | Documentation/asciidoc.conf | 2 | ||||
| -rw-r--r-- | Documentation/config.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-am.txt | 1 | ||||
| -rw-r--r-- | Documentation/git-config.txt | 76 | ||||
| -rw-r--r-- | Documentation/git-gc.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-ls-files.txt | 99 | ||||
| -rw-r--r-- | Documentation/git-read-tree.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-status.txt | 8 | ||||
| -rw-r--r-- | Documentation/gitignore.txt | 116 | ||||
| -rw-r--r-- | Documentation/repository-layout.txt | 3 | ||||
| -rw-r--r-- | Documentation/user-manual.txt | 12 |
12 files changed, 216 insertions, 121 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 3f92783d55..9cef4806d1 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -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)) @@ -112,8 +112,7 @@ clean: %.html : %.txt rm -f $@+ $@ $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -o - $< | \ - sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+ + $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< mv $@+ $@ %.1 %.5 %.7 : %.xml @@ -122,8 +121,7 @@ clean: %.xml : %.txt rm -f $@+ $@ $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ - $(ASCIIDOC_EXTRA) -o - $< | \ - sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+ + $(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index fa7dc94845..60e15ba349 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -40,7 +40,7 @@ template::[header-declarations] <refentrytitle>{mantitle}</refentrytitle> <manvolnum>{manvolnum}</manvolnum> <refmiscinfo class="source">Git</refmiscinfo> -<refmiscinfo class="version">@@GIT_VERSION@@</refmiscinfo> +<refmiscinfo class="version">{git_version}</refmiscinfo> <refmiscinfo class="manual">Git Manual</refmiscinfo> </refmeta> <refnamediv> diff --git a/Documentation/config.txt b/Documentation/config.txt index 6ea4f10150..5868d587a9 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -259,7 +259,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. diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 25cf84a0c7..f78e5dc28d 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -13,7 +13,6 @@ SYNOPSIS [--3way] [--interactive] [--binary] [--whitespace=<option>] [-C<n>] [-p<n>] <mbox>|<Maildir>... - 'git-am' [--skip | --resolved] DESCRIPTION diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 827a49970d..056b14724c 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -31,7 +31,7 @@ If you want to update or unset an option which can occur on multiple lines, a POSIX regexp `value_regex` needs to be given. Only the existing values that match the regexp are updated or unset. If you want to handle the lines that do *not* match the regex, just -prepend a single exclamation mark in front (see EXAMPLES). +prepend a single exclamation mark in front (see also <<EXAMPLES>>). The type specifier can be either '--int' or '--bool', which will make 'git-config' ensure that the variable(s) are of the given type and @@ -48,7 +48,7 @@ This command will fail if: . the section or key is invalid, . you try to unset an option which does not exist, . you try to unset/set an option for which multiple lines match, or -. you use --global option without $HOME being properly set. +. you use '--global' option without $HOME being properly set. OPTIONS @@ -75,11 +75,22 @@ OPTIONS Like --get-all, but interprets the name as a regular expression. --global:: - Use global ~/.gitconfig file rather than the repository .git/config. + For writing options: write to global ~/.gitconfig file rather than + the repository .git/config. ++ +For reading options: read only from global ~/.gitconfig rather than +from all available files. ++ +See also <<FILES>>. --system:: - Use system-wide $(prefix)/etc/gitconfig rather than the repository - .git/config. + For writing options: write to system-wide $(prefix)/etc/gitconfig + rather than the repository .git/config. ++ +For reading options: read only from system-wide $(prefix)/etc/gitconfig +rather than from all available files. ++ +See also <<FILES>>. --remove-section:: Remove the given section from the configuration file. @@ -106,21 +117,64 @@ OPTIONS by 1024, 1048576, or 1073741824 prior to output. +[[FILES]] +FILES +----- + +There are three files where git-config will search for configuration +options: + +.git/config:: + Repository specific configuration file. (The filename is + of course relative to the repository root, not the working + directory.) + +~/.gitconfig:: + User-specific configuration file. Also called "global" + configuration file. + +$(prefix)/etc/gitconfig:: + System-wide configuration file. + +If no further options are given, all reading options will read all of these +files that are available. If the global or the system-wide configuration +file are not available they will be ignored. If the repository configuration +file is not available or readable, git-config will exit with a non-zero +error code. However, in neither case will an error message be issued. + +All writing options will per default write to the repository specific +configuration file. Note that this also affects options like '--replace-all' +and '--unset'. *git-config will only ever change one file at a time*. + +You can override these rules either by command line options or by environment +variables. The '--global' and the '--system' options will limit the file used +to the global or system-wide file respectively. The GIT_CONFIG environment +variable has a similar effect, but you can specify any filename you want. + +The GIT_CONFIG_LOCAL environment variable on the other hand only changes +the name used instead of the repository configuration file. The global and +the system-wide configuration files will still be read. (For writing options +this will obviously result in the same behavior as using GIT_CONFIG.) + + ENVIRONMENT ----------- GIT_CONFIG:: Take the configuration from the given file instead of .git/config. - Using the "--global" option forces this to ~/.gitconfig. + Using the "--global" option forces this to ~/.gitconfig. Using the + "--system" option forces this to $(prefix)/etc/gitconfig. GIT_CONFIG_LOCAL:: - Currently the same as $GIT_CONFIG; when Git will support global - configuration files, this will cause it to take the configuration - from the global configuration file in addition to the given file. + Take the configuration from the given file instead if .git/config. + Still read the global and the system-wide configuration files, though. +See also <<FILES>>. -EXAMPLE -------- + +[[EXAMPLES]] +EXAMPLES +-------- Given a .git/config like this: diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 4ac839f938..c7742ca963 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -37,10 +37,10 @@ OPTIONS --aggressive:: Usually 'git-gc' runs very quickly while providing good disk - space utilization and performance. This option will cause - git-gc to more aggressive optimize the repository at the expense + space utilization and performance. This option will cause + git-gc to more aggressively optimize the repository at the expense of taking much more time. The effects of this optimization are - persistent, so this option only needs to be sporadically; every + persistent, so this option only needs to be used occasionally; every few hundred changesets or so. Configuration diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 43e0d2266c..a78a9ff1b8 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -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 --- diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 019c8bef7a..acb57447a8 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -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 diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index d7015387b5..1fd1af102a 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -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 ------ diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt new file mode 100644 index 0000000000..ea79d74b88 --- /dev/null +++ b/Documentation/gitignore.txt @@ -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 diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt index 0459bd9ca1..15221b5320 100644 --- a/Documentation/repository-layout.txt +++ b/Documentation/repository-layout.txt @@ -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 diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 4fabb8e2a9..7eaafa80e9 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -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. |