@matheusbsbs / matheus-bagliano / commits / 2dc53617a4
Fork 0

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/?