gitattributes: Document the unified "auto" handling
Update the documentation about text=auto: text=auto now follows the core.autocrlf handling when files are not normalized in the repository. For a cross platform project recommend the usage of attributes for line-ending conversions. Signed-off-by: Torsten Bögershausen <tboegi@web.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Torsten Bögershausen committed
Aug 26, 2016 at 22:18 UTC
e28eae3184b26d3cf3293e69403babb5c575342c
1 file changed
+24
-34
Documentation/gitattributes.txt
+24
-34
@@ -182,23 +182,6 @@ While Git normally leaves file contents alone, it can be configured to
182
normalize line endings to LF in the repository and, optionally, to
183
convert them to CRLF when files are checked out.
184
185
-Here is an example that will make Git normalize .txt, .vcproj and .sh
186
-files, ensure that .vcproj files have CRLF and .sh files have LF in
187
-the working directory, and prevent .jpg files from being normalized
188
-regardless of their content.
189
-
190
-------------------------
191
-* text=auto
192
-*.txt text
193
-*.vcproj text eol=crlf
194
-*.sh text eol=lf
195
-*.jpg -text
196
-------------------------
197
-
198
-Other source code management systems normalize all text files in their
199
-repositories, and there are two ways to enable similar automatic
200
-normalization in Git.
201
-
185
If you simply want to have CRLF line endings in your working directory
186
regardless of the repository you are working with, you can set the
187
config variable "core.autocrlf" without using any attributes.
@@ -208,35 +191,42 @@ config variable "core.autocrlf" without using any attributes.
191
autocrlf = true
192
------------------------
193
211
-This does not force normalization of all text files, but does ensure
194
+This does not force normalization of text files, but does ensure
195
that text files that you introduce to the repository have their line
196
endings normalized to LF when they are added, and that files that are
197
already normalized in the repository stay normalized.
198
216
-If you want to interoperate with a source code management system that
217
-enforces end-of-line normalization, or you simply want all text files
218
-in your repository to be normalized, you should instead set the `text`
219
-attribute to "auto" for _all_ files.
199
+If you want to ensure that text files that any contributor introduces to
200
+the repository have their line endings normalized, you can set the
201
+`text` attribute to "auto" for _all_ files.
202
203
------------------------
204
* text=auto
205
------------------------
206
225
-This ensures that all files that Git considers to be text will have
226
-normalized (LF) line endings in the repository. The `core.eol`
227
-configuration variable controls which line endings Git will use for
228
-normalized files in your working directory; the default is to use the
229
-native line ending for your platform, or CRLF if `core.autocrlf` is
230
-set.
207
+The attributes allow a fine-grained control, how the line endings
208
+are converted.
209
+Here is an example that will make Git normalize .txt, .vcproj and .sh
210
+files, ensure that .vcproj files have CRLF and .sh files have LF in
211
+the working directory, and prevent .jpg files from being normalized
212
+regardless of their content.
213
+
214
+------------------------
215
+* text=auto
216
+*.txt text
217
+*.vcproj text eol=crlf
218
+*.sh text eol=lf
219
+*.jpg -text
220
+------------------------
221
+
222
+NOTE: When `text=auto` conversion is enabled in a cross-platform
223
+project using push and pull to a central repository the text files
224
+containing CRLFs should be normalized.
225
232
-NOTE: When `text=auto` normalization is enabled in an existing
233
-repository, any text files containing CRLFs should be normalized. If
234
-they are not they will be normalized the next time someone tries to
235
-change them, causing unfortunate misattribution. From a clean working
236
-directory:
226
+From a clean working directory:
227
228
-------------------------------------------------
239
-$ echo "* text=auto" >>.gitattributes
229
+$ echo "* text=auto" >.gitattributes
230
$ rm .git/index # Remove the index to force Git to
231
$ git reset # re-scan the working directory
232
$ git status # Show files that will be normalized