@matheusbsbs / matheus-bagliano / commits / c98f78b806

gitfaq: give advice on using eol attribute in gitattributes

In the FAQ, we tell people how to use the text attribute, but we fail to explain what to do with the eol attribute. As we ourselves have noticed, most shell implementations do not care for carriage returns, and as such, people will practically always want them to use LF endings. Similar things can be said for batch files on Windows, except with CRLF endings. Since these are common things to have in a repository, let's help users make a good decision by recommending that they use the gitattributes file to correctly check out the endings. In addition, let's correct the cross-reference to this question, which originally referred to "the following entry", even though a new entry has been inserted in between. The cross-reference notation should prevent this from occurring and provide a link in formats, such as HTML, which support that. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

brian m. carlson committed Jul 9, 2024 at 23:37 UTC c98f78b806c93560c2a6c7eadda5449ac2a5432b
1 file changed +17 -4
Documentation/gitfaq.txt
+17 -4
@@ -393,8 +393,9 @@ I'm on Windows and git diff shows my files as having a `^M` at the end.::
393 +
394 You can store the files in the repository with Unix line endings and convert
395 them automatically to your platform's line endings. To do that, set the
396 -configuration option `core.eol` to `native` and see the following entry for
397 -information about how to configure files as text or binary.
396 +configuration option `core.eol` to `native` and see
397 +<<recommended-storage-settings,the question on recommended storage settings>>
398 +for information about how to configure files as text or binary.
399 +
400 You can also control this behavior with the `core.whitespace` setting if you
401 don't wish to remove the carriage returns from your line endings.
@@ -456,14 +457,26 @@ references, URLs, and hashes stored in the repository.
457 +
458 We also recommend setting a linkgit:gitattributes[5] file to explicitly mark
459 which files are text and which are binary. If you want Git to guess, you can
459 -set the attribute `text=auto`. For example, the following might be appropriate
460 -in some projects:
460 +set the attribute `text=auto`.
461 ++
462 +With text files, Git will generally ensure that LF endings are used in the
463 +repository. The `core.autocrlf` and `core.eol` configuration variables specify
464 +what line-ending convention is followed when any text file is checked out. You
465 +can also use the `eol` attribute (e.g., `eol=crlf`) to override which files get
466 +what line-ending treatment.
467 ++
468 +For example, generally shell files must have LF endings and batch files must
469 +have CRLF endings, so the following might be appropriate in some projects:
470 +
471 ----
472 # By default, guess.
473 * text=auto
474 # Mark all C files as text.
475 *.c text
476 +# Ensure all shell files have LF endings and all batch files have CRLF
477 +# endings in the working tree and both have LF in the repo.
478 +*.sh text eol=lf
479 +*.bat text eol=crlf
480 # Mark all JPEG files as binary.
481 *.jpg binary
482 ----