user-manual: Add section on ignoring files
The todo list at the end of the user manual says that something must be said about .gitignore. Also, there seems to be a lack of documentation on how to choose between the various types of ignore files (.gitignore vs. .git/info/exclude, etc.). This patch adds a section on ignoring files which try to introduce how to tell git about ignored files, and how the different strategies complement eachother. The syntax of exclude patterns is explained in a simplified manner, with a reference to git-ls-files(1) which already contains a more thorough explanation. Signed-off-by: Johan Herland <johan@herland.net>
Johan Herland committed
May 16, 2007 at 02:31 UTC
2dc53617a43fda3df12e51e765fe4043935cfc22
1 file changed
+69
-2
Documentation/user-manual.txt
+69
-2
@@ -1089,6 +1089,75 @@ description. Tools that turn commits into email, for example, use
1089
the first line on the Subject line and the rest of the commit in the
1090
body.
1091
1092
+[[ignoring-files]]
1093
+Ignoring files
1094
+--------------
1095
+
1096
+A project will often generate files that you do 'not' want to track with git.
1097
+This typically includes files generated by a build process or temporary
1098
+backup files made by your editor. Of course, 'not' tracking files with git
1099
+is just a matter of 'not' calling "`git add`" on them. But it quickly becomes
1100
+annoying to have these untracked files lying around; e.g. they make
1101
+"`git add .`" and "`git commit -a`" practically useless, and they keep
1102
+showing up in the output of "`git status`", etc.
1103
+
1104
+Git therefore provides "exclude patterns" for telling git which files to
1105
+actively ignore. Exclude patterns are thoroughly explained in the
1106
+"Exclude Patterns" section of the gitlink:git-ls-files[1] manual page,
1107
+but the heart of the concept is simply a list of files which git should
1108
+ignore. Entries in the list may contain globs to specify multiple files,
1109
+or may be prefixed by "`!`" to explicitly include (un-ignore) a previously
1110
+excluded (ignored) file (i.e. later exclude patterns override earlier ones).
1111
+The following example should illustrate such patterns:
1112
+
1113
+-------------------------------------------------
1114
+# Lines starting with '#' are considered comments.
1115
+# Ignore foo.txt.
1116
+foo.txt
1117
+# Ignore (generated) html files,
1118
+*.html
1119
+# except foo.html which is maintained by hand.
1120
+!foo.html
1121
+# Ignore objects and archives.
1122
+*.[oa]
1123
+-------------------------------------------------
1124
+
1125
+The next question is where to put these exclude patterns so that git can
1126
+find them. Git looks for exclude patterns in the following files:
1127
+
1128
+`.gitignore` files in your working tree:::
1129
+ You may store multiple `.gitignore` files at various locations in your
1130
+ working tree. Each `.gitignore` file is applied to the directory where
1131
+ it's located, including its subdirectories. Furthermore, the
1132
+ `.gitignore` files can be tracked like any other files in your working
1133
+ tree; just do a "`git add .gitignore`" and commit. `.gitignore` is
1134
+ therefore the right place to put exclude patterns that are meant to
1135
+ be shared between all project participants, such as build output files
1136
+ (e.g. `\*.o`), etc.
1137
+`.git/info/exclude` in your repo:::
1138
+ Exclude patterns in this file are applied to the working tree as a
1139
+ whole. Since the file is not located in your working tree, it does
1140
+ not follow push/pull/clone like `.gitignore` can do. This is therefore
1141
+ the place to put exclude patterns that are local to your copy of the
1142
+ repo (i.e. 'not' shared between project participants), such as
1143
+ temporary backup files made by your editor (e.g. `\*~`), etc.
1144
+The file specified by the `core.excludesfile` config directive:::
1145
+ By setting the `core.excludesfile` config directive you can tell git
1146
+ where to find more exclude patterns (see gitlink:git-config[1] for
1147
+ more information on configuration options). This config directive
1148
+ can be set in the per-repo `.git/config` file, in which case the
1149
+ exclude patterns will apply to that repo only. Alternatively, you
1150
+ can set the directive in the global `~/.gitconfig` file to apply
1151
+ the exclude pattern to all your git repos. As with the above
1152
+ `.git/info/exclude` (and, indeed, with git config directives in
1153
+ general), this directive does not follow push/pull/clone, but remain
1154
+ local to your repo(s).
1155
+
1156
+[NOTE]
1157
+In addition to the above alternatives, there are git commands that can take
1158
+exclude patterns directly on the command line. See gitlink:git-ls-files[1]
1159
+for an example of this.
1160
+
1161
[[how-to-merge]]
1162
How to merge
1163
------------
@@ -3853,8 +3922,6 @@ Think about how to create a clear chapter dependency graph that will
3922
allow people to get to important topics without necessarily reading
3923
everything in between.
3924
3856
-Say something about .gitignore.
3857
-
3925
Scan Documentation/ for other stuff left out; in particular:
3926
howto's
3927
some of technical/?