diff mbox series

[v3,2/4] gitfaq: give advice on using eol attribute in gitattributes

Message ID 20240704003818.750223-3-sandals@crustytoothpaste.net (mailing list archive)
State Superseded
Headers show
Series Additional FAQ entries | expand

Commit Message

brian m. carlson July 4, 2024, 12:38 a.m. UTC
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>
---
 Documentation/gitfaq.txt | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

Comments

Junio C Hamano July 4, 2024, 5:22 a.m. UTC | #1
"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> 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.

Sounds good.

> 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.

Thanks for being forward-looking and extra careful.

> +With text files, Git will generally ensure that LF endings are used in the
> +repository, and will honor `core.autocrlf` and `core.eol` to decide what options
> +to use when checking files out.  You can also override this by specifying a
> +particular line ending such as `eol=lf` or `eol=crlf` if those files must always

"this" being ... Not what gets stored in the object database but
what is done to the working tree.

What is being "overridden" is that the earlier two mentioned here
are configuration variables that apply to _all_ text files in
general, and the attribute mechanism is a way to give settings that
are more tailored for each path.  I think the reason I found the
above a bit hard to understand when I read it for the first time was
because it didn't "click" that this paragraph was about configuration
giving the general default and attributes overriding it.  Perhaps...

    ... are used in the repository.  The `core.autocrlf` and
    `core.eol` configuration variables specify what line-ending
    convention is followed when any text file is checked out.  You
    can also use the `eol` attribute (e.g., "eol=crlf") to override
    which files get what line-ending treatment.

or something?

> +have that ending in the working tree (e.g., for functionality reasons).

I'd strike "(e.g., for functionality reasons)" out, as the next
paragraph makes it sufficiently clear.

> +For example, generally shell files must have LF endings and batch files must
> +have CRLF endings, so the following might be appropriate in some projects:
>  +
>  ----
>  # By default, guess.
>  *	text=auto
>  # Mark all C files as text.
>  *.c	text
> +# Ensure all shell files have LF endings and all batch files have CRLF
> +# endings in the working tree and both have LF in the repo.
> +*.sh text eol=lf
> +*.bat text eol=crlf
>  # Mark all JPEG files as binary.
>  *.jpg	binary
>  ----
brian m. carlson July 4, 2024, 9:10 p.m. UTC | #2
On 2024-07-04 at 05:22:13, Junio C Hamano wrote:
> "brian m. carlson" <sandals@crustytoothpaste.net> writes:
> > +With text files, Git will generally ensure that LF endings are used in the
> > +repository, and will honor `core.autocrlf` and `core.eol` to decide what options
> > +to use when checking files out.  You can also override this by specifying a
> > +particular line ending such as `eol=lf` or `eol=crlf` if those files must always
> 
> "this" being ... Not what gets stored in the object database but
> what is done to the working tree.
> 
> What is being "overridden" is that the earlier two mentioned here
> are configuration variables that apply to _all_ text files in
> general, and the attribute mechanism is a way to give settings that
> are more tailored for each path.  I think the reason I found the
> above a bit hard to understand when I read it for the first time was
> because it didn't "click" that this paragraph was about configuration
> giving the general default and attributes overriding it.  Perhaps...
> 
>     ... are used in the repository.  The `core.autocrlf` and
>     `core.eol` configuration variables specify what line-ending
>     convention is followed when any text file is checked out.  You
>     can also use the `eol` attribute (e.g., "eol=crlf") to override
>     which files get what line-ending treatment.
> 
> or something?

Sure, that sounds like a nice improvement.

> > +have that ending in the working tree (e.g., for functionality reasons).
> 
> I'd strike "(e.g., for functionality reasons)" out, as the next
> paragraph makes it sufficiently clear.

Sure, I can do that.
diff mbox series

Patch

diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
index e4125b1178..cdc5f5f4f8 100644
--- a/Documentation/gitfaq.txt
+++ b/Documentation/gitfaq.txt
@@ -393,8 +393,9 @@  I'm on Windows and git diff shows my files as having a `^M` at the end.::
 +
 You can store the files in the repository with Unix line endings and convert
 them automatically to your platform's line endings.  To do that, set the
-configuration option `core.eol` to `native` and see the following entry for
-information about how to configure files as text or binary.
+configuration option `core.eol` to `native` and see
+<<recommended-storage-settings,the question on recommended storage settings>>
+for information about how to configure files as text or binary.
 +
 You can also control this behavior with the `core.whitespace` setting if you
 don't wish to remove the carriage returns from your line endings.
@@ -456,14 +457,26 @@  references, URLs, and hashes stored in the repository.
 +
 We also recommend setting a linkgit:gitattributes[5] file to explicitly mark
 which files are text and which are binary.  If you want Git to guess, you can
-set the attribute `text=auto`.  For example, the following might be appropriate
-in some projects:
+set the attribute `text=auto`.
++
+With text files, Git will generally ensure that LF endings are used in the
+repository, and will honor `core.autocrlf` and `core.eol` to decide what options
+to use when checking files out.  You can also override this by specifying a
+particular line ending such as `eol=lf` or `eol=crlf` if those files must always
+have that ending in the working tree (e.g., for functionality reasons).
++
+For example, generally shell files must have LF endings and batch files must
+have CRLF endings, so the following might be appropriate in some projects:
 +
 ----
 # By default, guess.
 *	text=auto
 # Mark all C files as text.
 *.c	text
+# Ensure all shell files have LF endings and all batch files have CRLF
+# endings in the working tree and both have LF in the repo.
+*.sh text eol=lf
+*.bat text eol=crlf
 # Mark all JPEG files as binary.
 *.jpg	binary
 ----