user-manual: edit "ignoring files" for conciseness
The immediate motivation for writing this section was to explain the various places ignore patterns could be used. However, I still think .gitignore is the case most people will want to learn about first. It also makes it a bit more concrete to introduce ignore patterns in the context of .gitignore first. And the existance of gitignore(5) relieves the pressure to explain it all here. So, stick to the .gitignore example, with only a brief mention of the others, explain the syntax only by example, and leave the rest to gitignore(5). Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Cc: Johan Herland <johan@herland.net>
J. Bruce Fields committed
May 24, 2007 at 20:28 UTC
464a8a7a15fc70efbcf56c4569f0f7275a9c76fe
1 file changed
+18
-45
Documentation/user-manual.txt
+18
-45
@@ -1100,20 +1100,14 @@ backup files made by your editor. Of course, 'not' tracking files with git
1100
is just a matter of 'not' calling "`git add`" on them. But it quickly becomes
1101
annoying to have these untracked files lying around; e.g. they make
1102
"`git add .`" and "`git commit -a`" practically useless, and they keep
1103
-showing up in the output of "`git status`", etc.
1103
+showing up in the output of "`git status`".
1104
1105
-Git therefore provides "exclude patterns" for telling git which files to
1106
-actively ignore. Exclude patterns are thoroughly explained in the
1107
-gitlink:gitignore[5] manual page, but the heart of the concept is simply
1108
-a list of files which git should ignore. Entries in the list may contain
1109
-globs to specify multiple files, or may be prefixed by "`!`" to
1110
-explicitly include (un-ignore) a previously excluded (ignored) file
1111
-(i.e. later exclude patterns override earlier ones). The following
1112
-example should illustrate such patterns:
1105
+You can tell git to ignore certain files by creating a file called .gitignore
1106
+in the top level of your working directory, with contents such as:
1107
1108
-------------------------------------------------
1109
# Lines starting with '#' are considered comments.
1116
-# Ignore foo.txt.
1110
+# Ignore any file named foo.txt.
1111
foo.txt
1112
# Ignore (generated) html files,
1113
*.html
@@ -1123,41 +1117,20 @@ foo.txt
1117
*.[oa]
1118
-------------------------------------------------
1119
1126
-The next question is where to put these exclude patterns so that git can
1127
-find them. Git looks for exclude patterns in the following files:
1128
-
1129
-`.gitignore` files in your working tree:::
1130
- You may store multiple `.gitignore` files at various locations in your
1131
- working tree. Each `.gitignore` file is applied to the directory where
1132
- it's located, including its subdirectories. Furthermore, the
1133
- `.gitignore` files can be tracked like any other files in your working
1134
- tree; just do a "`git add .gitignore`" and commit. `.gitignore` is
1135
- therefore the right place to put exclude patterns that are meant to
1136
- be shared between all project participants, such as build output files
1137
- (e.g. `\*.o`), etc.
1138
-`.git/info/exclude` in your repo:::
1139
- Exclude patterns in this file are applied to the working tree as a
1140
- whole. Since the file is not located in your working tree, it does
1141
- not follow push/pull/clone like `.gitignore` can do. This is therefore
1142
- the place to put exclude patterns that are local to your copy of the
1143
- repo (i.e. 'not' shared between project participants), such as
1144
- temporary backup files made by your editor (e.g. `\*~`), etc.
1145
-The file specified by the `core.excludesfile` config directive:::
1146
- By setting the `core.excludesfile` config directive you can tell git
1147
- where to find more exclude patterns (see gitlink:git-config[1] for
1148
- more information on configuration options). This config directive
1149
- can be set in the per-repo `.git/config` file, in which case the
1150
- exclude patterns will apply to that repo only. Alternatively, you
1151
- can set the directive in the global `~/.gitconfig` file to apply
1152
- the exclude pattern to all your git repos. As with the above
1153
- `.git/info/exclude` (and, indeed, with git config directives in
1154
- general), this directive does not follow push/pull/clone, but remain
1155
- local to your repo(s).
1156
-
1157
-[NOTE]
1158
-In addition to the above alternatives, there are git commands that can take
1159
-exclude patterns directly on the command line. See gitlink:git-ls-files[1]
1160
-for an example of this.
1120
+See gitlink:gitignore[5] for a detailed explanation of the syntax. You can
1121
+also place .gitignore files in other directories in your working tree, and they
1122
+will apply to those directories and their subdirectories. The `.gitignore`
1123
+files can be added to your repository like any other files (just run `git add
1124
+.gitignore` and `git commit`, as usual), which is convenient when the exclude
1125
+patterns (such as patterns matching build output files) would also make sense
1126
+for other users who clone your repository.
1127
+
1128
+If you wish the exclude patterns to affect only certain repositories
1129
+(instead of every repository for a given project), you may instead put
1130
+them in a file in your repository named .git/info/exclude, or in any file
1131
+specified by the `core.excludesfile` configuration variable. Some git
1132
+commands can also take exclude patterns directly on the command line.
1133
+See gitlink:gitignore[5] for the details.
1134
1135
[[how-to-merge]]
1136
How to merge