{"thread":{"id":"59676","subject":"[PATCH v3 0/1] docs: rewrite the documentation of the text and eol attributes","startedAt":"2023-05-01T02:35:57Z","lastAt":"2023-05-03T19:27:26Z","messageCount":10,"participants":["Alex Henrie","Torsten Bögershausen","Felipe Contreras","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":1},"messages":[{"id":"476324","messageId":"20230501023533.35370-1-alexhenrie24@gmail.com","threadId":"59676","inReplyTo":null,"subject":"[PATCH v3 0/1] docs: rewrite the documentation of the text and eol attributes","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-05-01T02:35:32Z","receivedAt":"2023-05-01T02:35:57Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"Changes from v2:\n- Correct incorrect statement in commit message about dependence of\n `eol` on `text`\n- Use \"normalize\" to refer to conversion to LF, and \"convert\" for\n conversion from LF\n- Add Helped-by line\n- Reduce wordiness/redundancy\n- Add Junio's suggested phrasing to introduce `eol`\n\nAlex Henrie (1):\n docs: rewrite the documentation of the text and eol attributes\n\n Documentation/gitattributes.txt | 60 ++++++++++++++++++---------------\n 1 file changed, 32 insertions(+), 28 deletions(-)\n\nRange-diff against v2:\n1: 446fb632a5 ! 1: 3d5985bc28 docs: rewrite the documentation of the text and eol attributes\n @@ Commit message\n does not do anything to the line endings either.\n \n On top of that, in several places the documentation for the eol\n - attribute sounds like it can force normalization on checkin and checkout\n - all by itself, but eol doesn't control normalization on checkin and\n - doesn't control normalization on checkout either unless accompanied by\n - the text attribute.\n + attribute sounds like it can turn on normalization on checkin, but eol\n + only controls conversion on checkout. It also sounds like setting eol\n + (or setting a config variable) is required to turn on conversion on\n + checkout, but the text attribute can turn on conversion on checkout by\n + itself if eol is unspecified.\n \n Rephrase the documentation of text, text=auto, eol, eol=crlf, and eol=lf\n to be clear about how they are the same, how they are different, and in\n - what cases normalization is performed.\n + what cases conversion is performed.\n \n + Helped-by: Torsten Bögershausen \n Signed-off-by: Alex Henrie \n \n ## Documentation/gitattributes.txt ##\n @@ Documentation/gitattributes.txt: repository upon 'git add' and 'git commit'.\n @@ Documentation/gitattributes.txt: repository upon 'git add' and 'git commit'.\n -`core.eol` (see the definitions of those options in\n -linkgit:git-config[1]).\n +This attribute marks the path as a text file, which enables end-of-line\n -+normalization on checkin and possibly also checkout: When a matching\n -+file is added to the index, even if it has CRLF line endings in the\n -+working directory, the file is stored in the index with LF line endings.\n -+Conversely, when the file is copied from the index to the working\n -+directory, its line endings may be converted from LF to CRLF depending\n -+on the `eol` attribute, the Git config, and the platform (see\n -+explanation of `eol` below).\n ++conversion: When a matching file is added to the index, the file's line\n ++endings are normalized to LF in the index. Conversely, when the file is\n ++copied from the index to the working directory, its line endings may be\n ++converted from LF to CRLF depending on the `eol` attribute, the Git\n ++config, and the platform (see explanation of `eol` below).\n \n Set::\n \n \tSetting the `text` attribute on a path enables end-of-line\n -\tnormalization and marks the path as a text file. End-of-line\n -\tconversion takes place without guessing the content type.\n -+\tnormalization on checkin and checkout as described above. Line\n -+\tendings are normalized in the index the next time the file is\n -+\tchecked in, even if the file was previously added to Git with CRLF\n -+\tline endings.\n ++\tconversion on checkin and checkout as described above. Line endings\n ++\tare normalized to LF in the index every time the file is checked in,\n ++\teven if the file was previously added to Git with CRLF line endings.\n \n Unset::\n \n @@ Documentation/gitattributes.txt: Unset::\n Unspecified::\n \n @@ Documentation/gitattributes.txt: unspecified.\n - This attribute sets a specific line-ending style to be used in the\n - working directory. This attribute has effect only if the `text`\n - attribute is set or unspecified, or if it is set to `auto`, the file is\n + `eol`\n + ^^^^^\n + \n +-This attribute sets a specific line-ending style to be used in the\n +-working directory. This attribute has effect only if the `text`\n +-attribute is set or unspecified, or if it is set to `auto`, the file is\n -detected as text, and it is stored with LF endings in the index. Note\n -that setting this attribute on paths which are in the index with CRLF\n -line endings may make the paths to be considered dirty unless\n -`text=auto` is set. Adding the path to the index again will normalize\n -the line endings in the index.\n -+detected as text, and it is stored with LF endings in the index.\n ++This attribute marks a path to use a specific line-ending style in the\n ++working tree when it is checked out. This attribute has effect only if\n ++the `text` attribute is set or unspecified, or if it is set to `auto`,\n ++the file is detected as text, and it is stored with LF endings in the\n ++index.\n \n Set to string value \"crlf\"::\n \n @@ Documentation/gitattributes.txt: unspecified.\n -\tcheckin and prevents conversion to CRLF when the file is\n -\tchecked out.\n +\tThis setting uses the same line endings in the working directory as\n -+\tin the index, whether they are LF or CRLF. However, unless\n -+\t`text=auto`, adding the file to the index again will normalize its\n -+\tline endings to LF in the index.\n ++\tin the index when the file is checked out.\n +\n +Unspecified::\n +\n-- \n2.40.1\n\n"},{"id":"476325","messageId":"20230501023533.35370-2-alexhenrie24@gmail.com","threadId":"59676","inReplyTo":"20230501023533.35370-1-alexhenrie24@gmail.com","subject":"[PATCH v3 1/1] docs: rewrite the documentation of the text and eol attributes","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-05-01T02:35:33Z","receivedAt":"2023-05-01T02:36:02Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"These two sentences are confusing because the description of the text\nattribute sounds exactly the same as the description of the text=auto\nattribute:\n\n\"Setting the text attribute on a path enables end-of-line normalization\"\n\n\"When text is set to \"auto\", the path is marked for automatic\nend-of-line conversion\"\n\nUnless the reader is already familiar with the two variants, there's a\nhigh probability that they will think that \"end-of-line normalization\"\nis the same thing as \"automatic end-of-line conversion\".\n\nIt's also not clear that the phrase \"When the file has been committed\nwith CRLF, no conversion is done\" in the paragraph for text=auto does\nnot apply equally to the bare text attribute which is described earlier.\nMoreover, it falsely implies that normalization is only suppressed if\nthe file has been committed. In fact, running `git add` on a CRLF file,\nadding the text=auto attribute to the file, and running `git add` again\ndoes not do anything to the line endings either.\n\nOn top of that, in several places the documentation for the eol\nattribute sounds like it can turn on normalization on checkin, but eol\nonly controls conversion on checkout. It also sounds like setting eol\n(or setting a config variable) is required to turn on conversion on\ncheckout, but the text attribute can turn on conversion on checkout by\nitself if eol is unspecified.\n\nRephrase the documentation of text, text=auto, eol, eol=crlf, and eol=lf\nto be clear about how they are the same, how they are different, and in\nwhat cases conversion is performed.\n\nHelped-by: Torsten Bögershausen \nSigned-off-by: Alex Henrie \n---\n Documentation/gitattributes.txt | 60 ++++++++++++++++++---------------\n 1 file changed, 32 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\nindex 39bfbca1ff..076a056a72 100644\n--- a/Documentation/gitattributes.txt\n+++ b/Documentation/gitattributes.txt\n@@ -120,20 +120,19 @@ repository upon 'git add' and 'git commit'.\n `text`\n ^^^^^^\n \n-This attribute enables and controls end-of-line normalization. When a\n-text file is normalized, its line endings are converted to LF in the\n-repository. To control what line ending style is used in the working\n-directory, use the `eol` attribute for a single file and the\n-`core.eol` configuration variable for all text files.\n-Note that setting `core.autocrlf` to `true` or `input` overrides\n-`core.eol` (see the definitions of those options in\n-linkgit:git-config[1]).\n+This attribute marks the path as a text file, which enables end-of-line\n+conversion: When a matching file is added to the index, the file's line\n+endings are normalized to LF in the index. Conversely, when the file is\n+copied from the index to the working directory, its line endings may be\n+converted from LF to CRLF depending on the `eol` attribute, the Git\n+config, and the platform (see explanation of `eol` below).\n \n Set::\n \n \tSetting the `text` attribute on a path enables end-of-line\n-\tnormalization and marks the path as a text file. End-of-line\n-\tconversion takes place without guessing the content type.\n+\tconversion on checkin and checkout as described above. Line endings\n+\tare normalized to LF in the index every time the file is checked in,\n+\teven if the file was previously added to Git with CRLF line endings.\n \n Unset::\n \n@@ -142,10 +141,11 @@ Unset::\n \n Set to string value \"auto\"::\n \n-\tWhen `text` is set to \"auto\", the path is marked for automatic\n-\tend-of-line conversion. If Git decides that the content is\n-\ttext, its line endings are converted to LF on checkin.\n-\tWhen the file has been committed with CRLF, no conversion is done.\n+\tWhen `text` is set to \"auto\", Git decides by itself whether the file\n+\tis text or binary. If it is text and the file was not already in\n+\tGit with CRLF endings, line endings are converted on checkin and\n+\tcheckout as described above. Otherwise, no conversion is done on\n+\tcheckin or checkout.\n \n Unspecified::\n \n@@ -159,26 +159,30 @@ unspecified.\n `eol`\n ^^^^^\n \n-This attribute sets a specific line-ending style to be used in the\n-working directory. This attribute has effect only if the `text`\n-attribute is set or unspecified, or if it is set to `auto`, the file is\n-detected as text, and it is stored with LF endings in the index. Note\n-that setting this attribute on paths which are in the index with CRLF\n-line endings may make the paths to be considered dirty unless\n-`text=auto` is set. Adding the path to the index again will normalize\n-the line endings in the index.\n+This attribute marks a path to use a specific line-ending style in the\n+working tree when it is checked out. This attribute has effect only if\n+the `text` attribute is set or unspecified, or if it is set to `auto`,\n+the file is detected as text, and it is stored with LF endings in the\n+index.\n \n Set to string value \"crlf\"::\n \n-\tThis setting forces Git to normalize line endings for this\n-\tfile on checkin and convert them to CRLF when the file is\n-\tchecked out.\n+\tThis setting converts the file's line endings in the working\n+\tdirectory to CRLF when the file is checked out.\n \n Set to string value \"lf\"::\n \n-\tThis setting forces Git to normalize line endings to LF on\n-\tcheckin and prevents conversion to CRLF when the file is\n-\tchecked out.\n+\tThis setting uses the same line endings in the working directory as\n+\tin the index when the file is checked out.\n+\n+Unspecified::\n+\n+\tIf the `eol` attribute is unspecified for a file, its line endings\n+\tin the working directory are determined by the `core.autocrlf` or\n+\t`core.eol` configuration variable (see the definitions of those\n+\toptions in linkgit:git-config[1]). The default if `text` is set but\n+\tneither of those variables is is `eol=lf` on Unix and `eol=crlf` on\n+\tWindows.\n \n Backwards compatibility with `crlf` attribute\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n-- \n2.40.1\n\n"},{"id":"476407","messageId":"20230502041725.7zbv3i4srdb7fqrg@tb-raspi4","threadId":"59676","inReplyTo":"20230501023533.35370-2-alexhenrie24@gmail.com","subject":"Re: [PATCH v3 1/1] docs: rewrite the documentation of the text and eol attributes","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2023-05-02T04:17:26Z","receivedAt":"2023-05-02T04:17:37Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"This looks much better, thanks.\nI have some minor comments:\na) The commit message from above:\n> docs: rewrite the documentation of the text and eol attributes\n\nThe word \"doc\" is used 2 times, that feel a little bit redundant\n(and should start with a uppercase letter)\n\n\"Docs: rewrite the documentation of the text and eol attributes\"\n\nOr may be shorter:\n\"Rewrite the documentation of the text and eol attributes\"\n\n\nb) Some more comments inline:\nOn Sun, Apr 30, 2023 at 08:35:33PM -0600, Alex Henrie wrote:\n> These two sentences are confusing because the description of the text\n> attribute sounds exactly the same as the description of the text=auto\n> attribute:\n\nThe word \"These\" is somewhat dangling: Which ones ?\nMay be \"The following two sentences\" ?\n\n>\n> \"Setting the text attribute on a path enables end-of-line normalization\"\n>\n> \"When text is set to \"auto\", the path is marked for automatic\n> end-of-line conversion\"\n>\n> Unless the reader is already familiar with the two variants, there's a\n> high probability that they will think that \"end-of-line normalization\"\n> is the same thing as \"automatic end-of-line conversion\".\nGood.\n>\n> It's also not clear that the phrase \"When the file has been committed\n> with CRLF, no conversion is done\" in the paragraph for text=auto does\n> not apply equally to the bare text attribute which is described earlier.\n> Moreover, it falsely implies that normalization is only suppressed if\n> the file has been committed. In fact, running `git add` on a CRLF file,\n> adding the text=auto attribute to the file, and running `git add` again\n> does not do anything to the line endings either.\nTrue.\n>\n> On top of that, in several places the documentation for the eol\n> attribute sounds like it can turn on normalization on checkin, but eol\n> only controls conversion on checkout. It also sounds like setting eol\n> (or setting a config variable) is required to turn on conversion on\n> checkout, but the text attribute can turn on conversion on checkout by\n> itself if eol is unspecified.\n>\n> Rephrase the documentation of text, text=auto, eol, eol=crlf, and eol=lf\n> to be clear about how they are the same, how they are different, and in\n> what cases conversion is performed.\n\nThat's all good.\n\n>\n> Helped-by: Torsten Bögershausen \n> Signed-off-by: Alex Henrie \n> ---\n> Documentation/gitattributes.txt | 60 ++++++++++++++++++---------------\n> 1 file changed, 32 insertions(+), 28 deletions(-)\n>\n> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\n> index 39bfbca1ff..076a056a72 100644\n> --- a/Documentation/gitattributes.txt\n> +++ b/Documentation/gitattributes.txt\n> @@ -120,20 +120,19 @@ repository upon 'git add' and 'git commit'.\n> `text`\n> ^^^^^^\n>\n> -This attribute enables and controls end-of-line normalization. When a\n> -text file is normalized, its line endings are converted to LF in the\n> -repository. To control what line ending style is used in the working\n> -directory, use the `eol` attribute for a single file and the\n> -`core.eol` configuration variable for all text files.\n> -Note that setting `core.autocrlf` to `true` or `input` overrides\n> -`core.eol` (see the definitions of those options in\n> -linkgit:git-config[1]).\n> +This attribute marks the path as a text file, which enables end-of-line\n> +conversion: When a matching file is added to the index, the file's line\n> +endings are normalized to LF in the index. Conversely, when the file is\n> +copied from the index to the working directory, its line endings may be\nI still stumble accross \"copied\". May be shorter:\n\n\"the file is written into the working directory\"\n\n> +converted from LF to CRLF depending on the `eol` attribute, the Git\n> +config, and the platform (see explanation of `eol` below).\nGood.\n>\n> Set::\n>\n> \tSetting the `text` attribute on a path enables end-of-line\n> -\tnormalization and marks the path as a text file. End-of-line\n> -\tconversion takes place without guessing the content type.\n> +\tconversion on checkin and checkout as described above. Line endings\n> +\tare normalized to LF in the index every time the file is checked in,\n> +\teven if the file was previously added to Git with CRLF line endings.\n>\n> Unset::\n>\n> @@ -142,10 +141,11 @@ Unset::\n>\n> Set to string value \"auto\"::\n>\n> -\tWhen `text` is set to \"auto\", the path is marked for automatic\n> -\tend-of-line conversion. If Git decides that the content is\n> -\ttext, its line endings are converted to LF on checkin.\n> -\tWhen the file has been committed with CRLF, no conversion is done.\n> +\tWhen `text` is set to \"auto\", Git decides by itself whether the file\n> +\tis text or binary. If it is text and the file was not already in\n> +\tGit with CRLF endings, line endings are converted on checkin and\n> +\tcheckout as described above. Otherwise, no conversion is done on\n> +\tcheckin or checkout.\n>\n> Unspecified::\n>\n> @@ -159,26 +159,30 @@ unspecified.\n> `eol`\n> ^^^^^\n>\n> -This attribute sets a specific line-ending style to be used in the\n> -working directory. This attribute has effect only if the `text`\n> -attribute is set or unspecified, or if it is set to `auto`, the file is\n> -detected as text, and it is stored with LF endings in the index. Note\n> -that setting this attribute on paths which are in the index with CRLF\n> -line endings may make the paths to be considered dirty unless\n> -`text=auto` is set. Adding the path to the index again will normalize\n> -the line endings in the index.\n> +This attribute marks a path to use a specific line-ending style in the\n> +working tree when it is checked out.\nIt enables even the normalization at checkin, see\n$ mkdir ttt\n$ cd ttt\n$ git init\n$ echo \"*.sh eol=lf\" >.gitattributes\n$ printf '#!/bin/sh\\r\\necho hello\\r\\n' >xx.sh\n$ git add xx.sh\nwarning: CRLF will be replaced by LF in xx.sh.\nThe file will have its original line endings in your working directory\n\n\n\n> + This attribute has effect only if\n> +the `text` attribute is set or unspecified, or if it is set to `auto`,\n> +the file is detected as text, and it is stored with LF endings in the\n> +index.\nIt took me a while to understand it.\nShould the \",\" after \"unspecified\" be removed ?\n\nOr, should we write:\n\nThe `eol` attribute automatically sets `text`, unless `-text`, `binary` or\n`text=auto` is specified.\n\nI dunno.\n\n>\n> Set to string value \"crlf\"::\n>\n> -\tThis setting forces Git to normalize line endings for this\n> -\tfile on checkin and convert them to CRLF when the file is\n> -\tchecked out.\n> +\tThis setting converts the file's line endings in the working\n> +\tdirectory to CRLF when the file is checked out.\n>\n> Set to string value \"lf\"::\n>\n> -\tThis setting forces Git to normalize line endings to LF on\n> -\tcheckin and prevents conversion to CRLF when the file is\n> -\tchecked out.\n> +\tThis setting uses the same line endings in the working directory as\n> +\tin the index when the file is checked out.\n> +\n> +Unspecified::\n> +\n> +\tIf the `eol` attribute is unspecified for a file, its line endings\n> +\tin the working directory are determined by the `core.autocrlf` or\n> +\t`core.eol` configuration variable (see the definitions of those\n> +\toptions in linkgit:git-config[1]). The default if `text` is set but\n> +\tneither of those variables is is `eol=lf` on Unix and `eol=crlf` on\n> +\tWindows.\n\nThat's good - I wonder if everyone understands Linux, MacOs and others as Unix.\n\nMay be something like this:\nThe default, if `text` is set but neither of those variables, is `eol=crlf` on\nWindows and `eol=lf` on all other systems.\n\n\n"},{"id":"476411","messageId":"CAMMLpeTNn_q_+pkOqjgPJBsB=s8EOTbngMJD7NXVo=rC8JWgwg@mail.gmail.com","threadId":"59676","inReplyTo":"20230502041725.7zbv3i4srdb7fqrg@tb-raspi4","subject":"Re: [PATCH v3 1/1] docs: rewrite the documentation of the text and eol attributes","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-05-02T05:59:22Z","receivedAt":"2023-05-02T06:00:03Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"On Mon, May 1, 2023 at 10:17 PM Torsten Bögershausen wrote:\n>\n> This looks much better, thanks.\n> I have some minor comments:\n> a) The commit message from above:\n> > docs: rewrite the documentation of the text and eol attributes\n>\n> The word \"doc\" is used 2 times, that feel a little bit redundant\n> (and should start with a uppercase letter)\n>\n> \"Docs: rewrite the documentation of the text and eol attributes\"\n>\n> Or may be shorter:\n> \"Rewrite the documentation of the text and eol attributes\"\n\nThe commit message is modeled after 8c591dbfce, which is incidentally\nthe commit that introduced the confusing wording discussed below.\nUnless there is a convention on how to write commit messages like\nthis, I would rather follow the existing precedent.\n\n> On Sun, Apr 30, 2023 at 08:35:33PM -0600, Alex Henrie wrote:\n> > These two sentences are confusing because the description of the text\n> > attribute sounds exactly the same as the description of the text=auto\n> > attribute:\n>\n> The word \"These\" is somewhat dangling: Which ones ?\n> May be \"The following two sentences\" ?\n\nThe colon indicates that the sentence refers to the following sentences.\n\n> > -This attribute enables and controls end-of-line normalization. When a\n> > -text file is normalized, its line endings are converted to LF in the\n> > -repository. To control what line ending style is used in the working\n> > -directory, use the `eol` attribute for a single file and the\n> > -`core.eol` configuration variable for all text files.\n> > -Note that setting `core.autocrlf` to `true` or `input` overrides\n> > -`core.eol` (see the definitions of those options in\n> > -linkgit:git-config[1]).\n> > +This attribute marks the path as a text file, which enables end-of-line\n> > +conversion: When a matching file is added to the index, the file's line\n> > +endings are normalized to LF in the index. Conversely, when the file is\n> > +copied from the index to the working directory, its line endings may be\n> I still stumble accross \"copied\". May be shorter:\n>\n> \"the file is written into the working directory\"\n\nMaybe, but then it almost sounds like Git watches the directory for\nchanges and transforms files as soon as the user creates them.\nConversion only happens when writing files _from the index_. Moreover,\nthe word \"copy\" does not always mean a byte-for-byte copy, and clearly\ndoes not mean that here.\n\n> > -This attribute sets a specific line-ending style to be used in the\n> > -working directory. This attribute has effect only if the `text`\n> > -attribute is set or unspecified, or if it is set to `auto`, the file is\n> > -detected as text, and it is stored with LF endings in the index. Note\n> > -that setting this attribute on paths which are in the index with CRLF\n> > -line endings may make the paths to be considered dirty unless\n> > -`text=auto` is set. Adding the path to the index again will normalize\n> > -the line endings in the index.\n> > +This attribute marks a path to use a specific line-ending style in the\n> > +working tree when it is checked out.\n> It enables even the normalization at checkin, see\n> $ mkdir ttt\n> $ cd ttt\n> $ git init\n> $ echo \"*.sh eol=lf\" >.gitattributes\n> $ printf '#!/bin/sh\\r\\necho hello\\r\\n' >xx.sh\n> $ git add xx.sh\n> warning: CRLF will be replaced by LF in xx.sh.\n> The file will have its original line endings in your working directory\n\nThis has got to be the most confusing Git feature ever. Clearly I did\nnot understand how it works.\n\n> > + This attribute has effect only if\n> > +the `text` attribute is set or unspecified, or if it is set to `auto`,\n> > +the file is detected as text, and it is stored with LF endings in the\n> > +index.\n> It took me a while to understand it.\n> Should the \",\" after \"unspecified\" be removed ?\n>\n> Or, should we write:\n>\n> The `eol` attribute automatically sets `text`, unless `-text`, `binary` or\n> `text=auto` is specified.\n\nYour proposed wording makes the relationship between `text` and `eol`\nfar more clear, and it avoids the need to repeat the detailed\nexplanation of how normalization on checkin works. However, I think we\nstill need to say in the introduction that `eol` does not work without\n`text`. How about this:\n\nIt has effect only if `text` or `text=auto` is set (see above), but\nspecifying `eol` automatically sets `text` if `text` was left\nunspecified.\n\nI've CCed the author of the original sentence on this email in case he\nwants to give any feedback on the rewrite.\n\n> > +Unspecified::\n> > +\n> > + If the `eol` attribute is unspecified for a file, its line endings\n> > + in the working directory are determined by the `core.autocrlf` or\n> > + `core.eol` configuration variable (see the definitions of those\n> > + options in linkgit:git-config[1]). The default if `text` is set but\n> > + neither of those variables is is `eol=lf` on Unix and `eol=crlf` on\n> > + Windows.\n>\n> That's good - I wonder if everyone understands Linux, MacOs and others as Unix.\n>\n> May be something like this:\n> The default, if `text` is set but neither of those variables, is `eol=crlf` on\n> Windows and `eol=lf` on all other systems.\n\nThat's fine, we can say \"all other platforms\" instead of \"Unix\" here.\nIt would only become a problem if someone ports Git to DOS, which\nseems unlikely.\n\nThanks for the insight and help,\n\n-Alex\n"},{"id":"476433","messageId":"645139edf1a0_1ba2d29474@chronos.notmuch","threadId":"59676","inReplyTo":"20230502041725.7zbv3i4srdb7fqrg@tb-raspi4","subject":"Re: [PATCH v3 1/1] docs: rewrite the documentation of the text and eol attributes","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-05-02T16:27:25Z","receivedAt":"2023-05-02T16:27:31Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Torsten Bögershausen wrote:\n> This looks much better, thanks.\n> I have some minor comments:\n> a) The commit message from above:\n> > docs: rewrite the documentation of the text and eol attributes\n> \n> The word \"doc\" is used 2 times, that feel a little bit redundant\n> (and should start with a uppercase letter)\n> \n> \"Docs: rewrite the documentation of the text and eol attributes\"\n> \n> Or may be shorter:\n> \"Rewrite the documentation of the text and eol attributes\"\n\nThis suggestion goes against the Git guideline in SubmittingPatches [1]:\n\n The title sentence after the \"area:\" prefix omits the full stop at the\n end, and its first word is not capitalized (the omission of\n capitalization applies only to the word after the \"area:\" prefix of\n the title) unless there is a reason to capitalize it other than\n because it is the first word in the sentence. E.g. \"doc: clarify...\",\n not \"doc: Clarify...\", or \"githooks.txt: improve...\", not\n \"githooks.txt: Improve...\".\n\nIf this is touching the documentation, it should have the \"docs: \"\nprefix, or \"doc: \".\n\n[1] https://git-scm.com/docs/SubmittingPatches\n\n-- \nFelipe Contreras"},{"id":"476488","messageId":"20230503044656.221175-1-alexhenrie24@gmail.com","threadId":"59676","inReplyTo":"20230501023533.35370-1-alexhenrie24@gmail.com","subject":"[PATCH v4 0/1] docs: rewrite the documentation of the text and eol attributes","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-05-03T04:46:55Z","receivedAt":"2023-05-03T04:48:45Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"Changes from v3:\n- Rewrite sentence about how `eol` can imply `text`\n- Use the phrase \"all other platforms\" instead of the word \"Unix\"\n\nAlex Henrie (1):\n docs: rewrite the documentation of the text and eol attributes\n\n Documentation/gitattributes.txt | 59 +++++++++++++++++----------------\n 1 file changed, 31 insertions(+), 28 deletions(-)\n\nRange-diff against v3:\n1: 3d5985bc28 ! 1: eccf627db1 docs: rewrite the documentation of the text and eol attributes\n @@ Commit message\n does not do anything to the line endings either.\n \n On top of that, in several places the documentation for the eol\n - attribute sounds like it can turn on normalization on checkin, but eol\n - only controls conversion on checkout. It also sounds like setting eol\n + attribute sounds like either it does not affect normalization on checkin\n + or it forces normalization on checkin. It also sounds like setting eol\n (or setting a config variable) is required to turn on conversion on\n checkout, but the text attribute can turn on conversion on checkout by\n itself if eol is unspecified.\n @@ Documentation/gitattributes.txt: unspecified.\n -`text=auto` is set. Adding the path to the index again will normalize\n -the line endings in the index.\n +This attribute marks a path to use a specific line-ending style in the\n -+working tree when it is checked out. This attribute has effect only if\n -+the `text` attribute is set or unspecified, or if it is set to `auto`,\n -+the file is detected as text, and it is stored with LF endings in the\n -+index.\n ++working tree when it is checked out. It has effect only if `text` or\n ++`text=auto` is set (see above), but specifying `eol` automatically sets\n ++`text` if `text` was left unspecified.\n \n Set to string value \"crlf\"::\n \n @@ Documentation/gitattributes.txt: unspecified.\n +\tIf the `eol` attribute is unspecified for a file, its line endings\n +\tin the working directory are determined by the `core.autocrlf` or\n +\t`core.eol` configuration variable (see the definitions of those\n -+\toptions in linkgit:git-config[1]). The default if `text` is set but\n -+\tneither of those variables is is `eol=lf` on Unix and `eol=crlf` on\n -+\tWindows.\n ++\toptions in linkgit:git-config[1]). If `text` is set but neither of\n ++\tthose variables is, the default is `eol=crlf` on Windows and\n ++\t`eol=lf` on all other platforms.\n \n Backwards compatibility with `crlf` attribute\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n-- \n2.40.1\n\n"},{"id":"476489","messageId":"20230503044656.221175-2-alexhenrie24@gmail.com","threadId":"59676","inReplyTo":"20230503044656.221175-1-alexhenrie24@gmail.com","subject":"[PATCH v4 1/1] docs: rewrite the documentation of the text and eol attributes","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-05-03T04:46:56Z","receivedAt":"2023-05-03T04:48:46Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"These two sentences are confusing because the description of the text\nattribute sounds exactly the same as the description of the text=auto\nattribute:\n\n\"Setting the text attribute on a path enables end-of-line normalization\"\n\n\"When text is set to \"auto\", the path is marked for automatic\nend-of-line conversion\"\n\nUnless the reader is already familiar with the two variants, there's a\nhigh probability that they will think that \"end-of-line normalization\"\nis the same thing as \"automatic end-of-line conversion\".\n\nIt's also not clear that the phrase \"When the file has been committed\nwith CRLF, no conversion is done\" in the paragraph for text=auto does\nnot apply equally to the bare text attribute which is described earlier.\nMoreover, it falsely implies that normalization is only suppressed if\nthe file has been committed. In fact, running `git add` on a CRLF file,\nadding the text=auto attribute to the file, and running `git add` again\ndoes not do anything to the line endings either.\n\nOn top of that, in several places the documentation for the eol\nattribute sounds like either it does not affect normalization on checkin\nor it forces normalization on checkin. It also sounds like setting eol\n(or setting a config variable) is required to turn on conversion on\ncheckout, but the text attribute can turn on conversion on checkout by\nitself if eol is unspecified.\n\nRephrase the documentation of text, text=auto, eol, eol=crlf, and eol=lf\nto be clear about how they are the same, how they are different, and in\nwhat cases conversion is performed.\n\nHelped-by: Torsten Bögershausen \nSigned-off-by: Alex Henrie \n---\n Documentation/gitattributes.txt | 59 +++++++++++++++++----------------\n 1 file changed, 31 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\nindex 39bfbca1ff..02a3ec83e4 100644\n--- a/Documentation/gitattributes.txt\n+++ b/Documentation/gitattributes.txt\n@@ -120,20 +120,19 @@ repository upon 'git add' and 'git commit'.\n `text`\n ^^^^^^\n \n-This attribute enables and controls end-of-line normalization. When a\n-text file is normalized, its line endings are converted to LF in the\n-repository. To control what line ending style is used in the working\n-directory, use the `eol` attribute for a single file and the\n-`core.eol` configuration variable for all text files.\n-Note that setting `core.autocrlf` to `true` or `input` overrides\n-`core.eol` (see the definitions of those options in\n-linkgit:git-config[1]).\n+This attribute marks the path as a text file, which enables end-of-line\n+conversion: When a matching file is added to the index, the file's line\n+endings are normalized to LF in the index. Conversely, when the file is\n+copied from the index to the working directory, its line endings may be\n+converted from LF to CRLF depending on the `eol` attribute, the Git\n+config, and the platform (see explanation of `eol` below).\n \n Set::\n \n \tSetting the `text` attribute on a path enables end-of-line\n-\tnormalization and marks the path as a text file. End-of-line\n-\tconversion takes place without guessing the content type.\n+\tconversion on checkin and checkout as described above. Line endings\n+\tare normalized to LF in the index every time the file is checked in,\n+\teven if the file was previously added to Git with CRLF line endings.\n \n Unset::\n \n@@ -142,10 +141,11 @@ Unset::\n \n Set to string value \"auto\"::\n \n-\tWhen `text` is set to \"auto\", the path is marked for automatic\n-\tend-of-line conversion. If Git decides that the content is\n-\ttext, its line endings are converted to LF on checkin.\n-\tWhen the file has been committed with CRLF, no conversion is done.\n+\tWhen `text` is set to \"auto\", Git decides by itself whether the file\n+\tis text or binary. If it is text and the file was not already in\n+\tGit with CRLF endings, line endings are converted on checkin and\n+\tcheckout as described above. Otherwise, no conversion is done on\n+\tcheckin or checkout.\n \n Unspecified::\n \n@@ -159,26 +159,29 @@ unspecified.\n `eol`\n ^^^^^\n \n-This attribute sets a specific line-ending style to be used in the\n-working directory. This attribute has effect only if the `text`\n-attribute is set or unspecified, or if it is set to `auto`, the file is\n-detected as text, and it is stored with LF endings in the index. Note\n-that setting this attribute on paths which are in the index with CRLF\n-line endings may make the paths to be considered dirty unless\n-`text=auto` is set. Adding the path to the index again will normalize\n-the line endings in the index.\n+This attribute marks a path to use a specific line-ending style in the\n+working tree when it is checked out. It has effect only if `text` or\n+`text=auto` is set (see above), but specifying `eol` automatically sets\n+`text` if `text` was left unspecified.\n \n Set to string value \"crlf\"::\n \n-\tThis setting forces Git to normalize line endings for this\n-\tfile on checkin and convert them to CRLF when the file is\n-\tchecked out.\n+\tThis setting converts the file's line endings in the working\n+\tdirectory to CRLF when the file is checked out.\n \n Set to string value \"lf\"::\n \n-\tThis setting forces Git to normalize line endings to LF on\n-\tcheckin and prevents conversion to CRLF when the file is\n-\tchecked out.\n+\tThis setting uses the same line endings in the working directory as\n+\tin the index when the file is checked out.\n+\n+Unspecified::\n+\n+\tIf the `eol` attribute is unspecified for a file, its line endings\n+\tin the working directory are determined by the `core.autocrlf` or\n+\t`core.eol` configuration variable (see the definitions of those\n+\toptions in linkgit:git-config[1]). If `text` is set but neither of\n+\tthose variables is, the default is `eol=crlf` on Windows and\n+\t`eol=lf` on all other platforms.\n \n Backwards compatibility with `crlf` attribute\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n-- \n2.40.1\n\n"},{"id":"476515","messageId":"xmqq8re5wg9r.fsf@gitster.g","threadId":"59676","inReplyTo":"20230503044656.221175-2-alexhenrie24@gmail.com","subject":"Re: [PATCH v4 1/1] docs: rewrite the documentation of the text and eol attributes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-03T16:06:56Z","receivedAt":"2023-05-03T16:07:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Alex Henrie writes:\n\n> These two sentences are confusing because the description of the text\n> attribute sounds exactly the same as the description of the text=auto\n> attribute:\n> ...\n> Rephrase the documentation of text, text=auto, eol, eol=crlf, and eol=lf\n> to be clear about how they are the same, how they are different, and in\n> what cases conversion is performed.\n>\n> Helped-by: Torsten Bögershausen \n> Signed-off-by: Alex Henrie \n> ---\n> Documentation/gitattributes.txt | 59 +++++++++++++++++----------------\n> 1 file changed, 31 insertions(+), 28 deletions(-)\n\nWill replace. Unless I hear objections soon, I'll mark it for\n'next' and merge it down. Thanks.\n\n"},{"id":"476547","messageId":"20230503190000.5icpfm5k3dxgoq4d@tb-raspi4","threadId":"59676","inReplyTo":"xmqq8re5wg9r.fsf@gitster.g","subject":"Re: [PATCH v4 1/1] docs: rewrite the documentation of the text and eol attributes","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2023-05-03T19:00:00Z","receivedAt":"2023-05-03T19:00:22Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On Wed, May 03, 2023 at 09:06:56AM -0700, Junio C Hamano wrote:\n> Alex Henrie writes:\n\n\n> > ---\n> > Documentation/gitattributes.txt | 59 +++++++++++++++++----------------\n> > 1 file changed, 31 insertions(+), 28 deletions(-)\n>\n> Will replace. Unless I hear objections soon, I'll mark it for\n> 'next' and merge it down. Thanks.\n>\nThat's all fine with me - no objections.\nHappy line-ending ;-)\n"},{"id":"476551","messageId":"xmqq5y99qkq4.fsf@gitster.g","threadId":"59676","inReplyTo":"20230503190000.5icpfm5k3dxgoq4d@tb-raspi4","subject":"Re: [PATCH v4 1/1] docs: rewrite the documentation of the text and eol attributes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-05-03T19:27:15Z","receivedAt":"2023-05-03T19:27:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Torsten Bögershausen writes:\n\n> On Wed, May 03, 2023 at 09:06:56AM -0700, Junio C Hamano wrote:\n>> Alex Henrie writes:\n>\n>\n>> > ---\n>> > Documentation/gitattributes.txt | 59 +++++++++++++++++----------------\n>> > 1 file changed, 31 insertions(+), 28 deletions(-)\n>>\n>> Will replace. Unless I hear objections soon, I'll mark it for\n>> 'next' and merge it down. Thanks.\n>>\n> That's all fine with me - no objections.\n\nThanks for a quick response. Let me merge it to 'next' on the next\nintegration cycle.\n"}]}