| Message ID | 20211020010624.675562-4-sandals@crustytoothpaste.net (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Additional FAQ entries | expand |
On Tue, Oct 19, 2021 at 9:06 PM brian m. carlson <sandals@crustytoothpaste.net> wrote: > 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> > --- > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt > @@ -464,14 +465,25 @@ references, URLs, and hashes stored in the repository. > +With text files, Git will generally the repository contains LF endings 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 (e.g., for functionality reasons). The first sentence in the paragraph is unparseable. > +# Ensure all shell files end up with LF endings and all batch files end up > +# with CRLF endings in the working tree and both end up with LF in the repo. > +*.sh text eol=lf > +*.bat text eol=crlf Maybe: s/end up with/have/g
On 2021-10-20 at 01:21:40, Eric Sunshine wrote: > On Tue, Oct 19, 2021 at 9:06 PM brian m. carlson > <sandals@crustytoothpaste.net> wrote: > > 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> > > --- > > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt > > @@ -464,14 +465,25 @@ references, URLs, and hashes stored in the repository. > > +With text files, Git will generally the repository contains LF endings 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 (e.g., for functionality reasons). > > The first sentence in the paragraph is unparseable. Yes, I think perhaps I omitted the word "ensure". And I should reflect that they should have that ending in the working tree, which I neglected to mention. > > +# Ensure all shell files end up with LF endings and all batch files end up > > +# with CRLF endings in the working tree and both end up with LF in the repo. > > +*.sh text eol=lf > > +*.bat text eol=crlf > > Maybe: s/end up with/have/g Great. That does read more clearly and succinctly. I'll include those fixes in a reroll.
Hi brian, On Wed, 20 Oct 2021, brian m. carlson wrote: > On 2021-10-20 at 01:21:40, Eric Sunshine wrote: > > On Tue, Oct 19, 2021 at 9:06 PM brian m. carlson > > <sandals@crustytoothpaste.net> wrote: > > > > > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt > > > @@ -464,14 +465,25 @@ references, URLs, and hashes stored in the repository. > > > +With text files, Git will generally the repository contains LF endings 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 (e.g., for functionality reasons). > > > > The first sentence in the paragraph is unparseable. > > Yes, I think perhaps I omitted the word "ensure". > > And I should reflect that they should have that ending in the working > tree, which I neglected to mention. Please note that Git for Windows defaults to `core.autoCRLF=true`, therefore this sentence is not completely correct. Maybe something as short as "(except in Git for Windows, which defaults to CRLF endings)" would suffice? Ciao, Dscho
On 2021-10-20 at 12:02:02, Johannes Schindelin wrote: > Hi brian, > > On Wed, 20 Oct 2021, brian m. carlson wrote: > > > On 2021-10-20 at 01:21:40, Eric Sunshine wrote: > > > On Tue, Oct 19, 2021 at 9:06 PM brian m. carlson > > > <sandals@crustytoothpaste.net> wrote: > > > > > > > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt > > > > @@ -464,14 +465,25 @@ references, URLs, and hashes stored in the repository. > > > > +With text files, Git will generally the repository contains LF endings 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 (e.g., for functionality reasons). > > > > > > The first sentence in the paragraph is unparseable. > > > > Yes, I think perhaps I omitted the word "ensure". > > > > And I should reflect that they should have that ending in the working > > tree, which I neglected to mention. > > Please note that Git for Windows defaults to `core.autoCRLF=true`, > therefore this sentence is not completely correct. Maybe something as > short as "(except in Git for Windows, which defaults to CRLF endings)" > would suffice? What I meant by that sentence was that I should add, "in the working tree" to the sentence ending "if those files must always have that ending". I believe that is still the case for Git for Windows, since otherwise our shell files in the repository would be broken there, and I'm fairly confident they are not.
Hi brian, On Wed, 20 Oct 2021, brian m. carlson wrote: > On 2021-10-20 at 12:02:02, Johannes Schindelin wrote: > > Hi brian, > > > > On Wed, 20 Oct 2021, brian m. carlson wrote: > > > > > On 2021-10-20 at 01:21:40, Eric Sunshine wrote: > > > > On Tue, Oct 19, 2021 at 9:06 PM brian m. carlson > > > > <sandals@crustytoothpaste.net> wrote: > > > > > > > > > diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt > > > > > @@ -464,14 +465,25 @@ references, URLs, and hashes stored in the repository. > > > > > +With text files, Git will generally the repository contains LF endings 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 (e.g., for functionality reasons). > > > > > > > > The first sentence in the paragraph is unparseable. > > > > > > Yes, I think perhaps I omitted the word "ensure". > > > > > > And I should reflect that they should have that ending in the working > > > tree, which I neglected to mention. > > > > Please note that Git for Windows defaults to `core.autoCRLF=true`, > > therefore this sentence is not completely correct. Maybe something as > > short as "(except in Git for Windows, which defaults to CRLF endings)" > > would suffice? > > What I meant by that sentence was that I should add, "in the working > tree" to the sentence ending "if those files must always have that > ending". I believe that is still the case for Git for Windows, since > otherwise our shell files in the repository would be broken there, and > I'm fairly confident they are not. I swear I read this sentence multiple times yesterday, and still managed to miss that you were talking about LF endings _in the repository_. FWIW I think that `core.autoCRLF` defaults to `off` everywhere but on Windows, so _technically_ Git would not ensure LF endings e.g. on Linux. In practice, it is highly unlikely that a Linux user would generate text files with CR/LF endings, so it would not matter in practice. I feel a bit bad for arguing subtleties that realistically won't matter, so please feel free to leave the sentence as you have intended it. Ciao, Dscho
diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt index abc0f62e6c..85ac99c7b2 100644 --- a/Documentation/gitfaq.txt +++ b/Documentation/gitfaq.txt @@ -401,8 +401,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. @@ -464,14 +465,25 @@ 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 the repository contains LF endings 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 (e.g., for functionality reasons). ++ +For example, 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 end up with LF endings and all batch files end up +# with CRLF endings in the working tree and both end up with LF in the repo. +*.sh text eol=lf +*.bat text eol=crlf # Mark all JPEG files as binary. *.jpg binary ----
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 | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-)