{"thread":{"id":"59628","subject":"[PATCH] docs: clarify how the text and text=auto attributes are different","startedAt":"2023-04-21T05:56:54Z","lastAt":"2023-05-01T00:42:04Z","messageCount":11,"participants":["Alex Henrie","Junio C Hamano","Torsten Bögershausen"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"475782","messageId":"20230421055641.550199-1-alexhenrie24@gmail.com","threadId":"59628","inReplyTo":null,"subject":"[PATCH] docs: clarify how the text and text=auto attributes are different","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-04-21T05:56:41Z","receivedAt":"2023-04-21T05:56:54Z","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 confusing that the explanation of how end-of-line conversion\nworks is in the paragraph for text=auto even though it applies equally\nto the text attribute which is described earlier.\n\nOn top of that, \"When the file has been committed with CRLF, no\nconversion is done\" implies that normalization is only suppressed if the\nfile has been committed. In fact, running `git add` on a CRLF file,\nadding the text attribute to the file, and running `git add` again does\nnot do anything to the line endings either.\n\nRephrase the documentation of text and text=auto to be clear about how\nthey are the same, how they are different, and in what cases\nnormalization is performed.\n\nSigned-off-by: Alex Henrie <alexhenrie24@gmail.com>\n---\n Documentation/gitattributes.txt | 16 +++++++++-------\n 1 file changed, 9 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\nindex 39bfbca1ff..6db4ecd794 100644\n--- a/Documentation/gitattributes.txt\n+++ b/Documentation/gitattributes.txt\n@@ -131,9 +131,12 @@ linkgit:git-config[1]).\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+\tSetting the `text` attribute on a path marks the path as a text\n+\tfile, which enables end-of-line normalization: When a matching file\n+\tis added to the index, even if it has CRLF line endings in the\n+\tworking directory, the file is stored in Git with LF line endings.\n+\tHowever, if the file was already in Git with CRLF endings, no\n+\tconversion is done.\n \n Unset::\n \n@@ -142,10 +145,9 @@ 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, line endings are converted as\n+\tdescribed above.  If it is binary, they are not.\n \n Unspecified::\n \n-- \n2.40.0\n\n"},{"id":"475792","messageId":"xmqqo7nhkxca.fsf@gitster.g","threadId":"59628","inReplyTo":"20230421055641.550199-1-alexhenrie24@gmail.com","subject":"Re: [PATCH] docs: clarify how the text and text=auto attributes are different","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-04-21T16:35:01Z","receivedAt":"2023-04-21T16:35:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Alex Henrie <alexhenrie24@gmail.com> 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> \"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\".\n\nTrue.  \n\nThe prerequisite to understand these two seemingly contradicting\nsentences is to know that \"attribute\" can be \"set\" (in the sense of\nBoolean \"yes\") and can be \"set to value\" (here in this case, to the\nstring \"auto\").  They are treated differently.\n\nIt is very good that you decided to clarify it.\n\n> It's also confusing that the explanation of how end-of-line conversion\n> works is in the paragraph for text=auto even though it applies equally\n> to the text attribute which is described earlier.\n\nGood observation.\n\nInstead of half-duplicating the same explanation in two places, it\nis very good to do so just once, in the introductory description of\nthe 'text' attribute before the individual description of what\nhappens when the attribute is in any of the four states.\n\n> On top of that, \"When the file has been committed with CRLF, no\n> conversion is done\" implies that normalization is only suppressed if the\n> file has been committed. In fact, running `git add` on a CRLF file,\n> adding the text attribute to the file, and running `git add` again does\n> not do anything to the line endings either.\n\nTrue again.  The conversion happens between the index and the\nworking tree, and \"committing\" does not have much say in the\nprocess.  Interestingly, the description of what happens when the\nattribute is \"Unset\" (in the sense of setting it to Boolean \"no\")\nuses a better terminology---\"checkin or checkout\", which is about\ngetting things out of or into the index.\n\nIt is very good that you decided to clarify it.\n\n> Rephrase the documentation of text and text=auto to be clear about how\n> they are the same, how they are different, and in what cases\n> normalization is performed.\n\nThanks.\n\n> Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>\n> ---\n>  Documentation/gitattributes.txt | 16 +++++++++-------\n>  1 file changed, 9 insertions(+), 7 deletions(-)\n>\n> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\n> index 39bfbca1ff..6db4ecd794 100644\n> --- a/Documentation/gitattributes.txt\n> +++ b/Documentation/gitattributes.txt\n> @@ -131,9 +131,12 @@ linkgit:git-config[1]).\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> +\tSetting the `text` attribute on a path marks the path as a text\n> +\tfile, which enables end-of-line normalization: When a matching file\n> +\tis added to the index, even if it has CRLF line endings in the\n> +\tworking directory, the file is stored in Git with LF line endings.\n> +\tHowever, if the file was already in Git with CRLF endings, no\n> +\tconversion is done.\n\nI think most of the new text should go to the paragraph before this\nhunk (i.e. \"... its line endings are converted to ...\"), where not\njust CRLF->LF conversion is described, but how it does and does not\nhappen depending on the eol, core.eol, and core.autocrlf are set.\n\n>  Unset::\n>  \n> @@ -142,10 +145,9 @@ 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, line endings are converted as\n> +\tdescribed above.  If it is binary, they are not.\n\nThis side is good.  \"As described above\" can still be used as-is\neven after the explanation of eol conversion is made before we start\nenumerating Set/Unset/set to auto/unspecified.\n\nThanks.\n\n"},{"id":"475796","messageId":"20230421182556.xxd4vrcksr6634ao@tb-raspi4","threadId":"59628","inReplyTo":"20230421055641.550199-1-alexhenrie24@gmail.com","subject":"Re: [PATCH] docs: clarify how the text and text=auto attributes are different","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2023-04-21T18:25:57Z","receivedAt":"2023-04-21T18:26:13Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On Thu, Apr 20, 2023 at 11:56:41PM -0600, Alex Henrie wrote:\n\nThanks for that, fully agree with comments from Junio.\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> +\tSetting the `text` attribute on a path marks the path as a text\n> +\tfile, which enables end-of-line normalization: When a matching file\n> +\tis added to the index, even if it has CRLF line endings in the\n> +\tworking directory, the file is stored in Git with LF line endings.\n\nHm, I stumbled a little bit over the word \"even\" here.\nBut it makes things very clear, so this is good.\n\n\n> +\tHowever, if the file was already in Git with CRLF endings, no\n> +\tconversion is done.\n\nBut I think that this is wrong, unless I missed something.\n\nUsing\n*.txt text\nin .gitattributes\nwill convert CRLF into LF in the repo at the next git commit/git add\n\nWhen you create a file with CRLF (no atttibutes), commit it into the repo,\nand later add the attribute \"text\", the file may be reported as modified.\nNot always. A `touch file.txt` typically asks Git to re-investigate things,\nand it may show up as modified.\nAfter a `git clone` it may be shown as modified or not.\nEnd of side-note.\n\nSetting\n\n\n\n\n>\n>  Unset::\n>\n> @@ -142,10 +145,9 @@ 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, line endings are converted as\n> +\tdescribed above.  If it is binary, they are not.\n\nHere we need to have the lines from above:\n\nWhen text is set to \"auto\", Git decides by itself whether the file\nis text or binary.  If it is text, line endings are converted as\ndescribed above.  If it is binary, they are not.\nHowever, if the file was already in Git with CRLF endings, no\nconversion is done.\n\nI hope that I didn't messed up while reading this patch ?\nThanks again for bringing this up\n"},{"id":"476106","messageId":"CAMMLpeRWXCFxk1wCjLPizdgJLG8n0Hy0o+Gm849Ln85cZkkH8w@mail.gmail.com","threadId":"59628","inReplyTo":"20230421182556.xxd4vrcksr6634ao@tb-raspi4","subject":"Re: [PATCH] docs: clarify how the text and text=auto attributes are different","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-04-26T13:18:44Z","receivedAt":"2023-04-26T13:19:25Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"On Fri, Apr 21, 2023 at 12:26 PM Torsten Bögershausen <tboegi@web.de> wrote:\n\n> Using\n> *.txt text\n> in .gitattributes\n> will convert CRLF into LF in the repo at the next git commit/git add\n>\n> When you create a file with CRLF (no atttibutes), commit it into the repo,\n> and later add the attribute \"text\", the file may be reported as modified.\n> Not always. A `touch file.txt` typically asks Git to re-investigate things,\n> and it may show up as modified.\n> After a `git clone` it may be shown as modified or not.\n> End of side-note.\n\nThank you very much for pointing that out. I had assumed that \"text\"\nand \"text=auto\" behaved the same for text files, but they do not:\n\"text\" normalizes line endings even if the file is already in Git.\nThat means that my proposed text is not correct, and I will have to\nchange it similarly to how you suggested below.\n\n> >  Set to string value \"auto\"::\n> >\n> > -     When `text` is set to \"auto\", the path is marked for automatic\n> > -     end-of-line conversion.  If Git decides that the content is\n> > -     text, its line endings are converted to LF on checkin.\n> > -     When the file has been committed with CRLF, no conversion is done.\n> > +     When text is set to \"auto\", Git decides by itself whether the file\n> > +     is text or binary.  If it is text, line endings are converted as\n> > +     described above.  If it is binary, they are not.\n>\n> Here we need to have the lines from above:\n>\n> When text is set to \"auto\", Git decides by itself whether the file\n> is text or binary.  If it is text, line endings are converted as\n> described above.  If it is binary, they are not.\n> However, if the file was already in Git with CRLF endings, no\n> conversion is done.\n\nYes, the note about what happens if the file is already in Git with\nCRLF endings applies specifically to text=auto, so it needs to be in\nthe text=auto section. The documentation of the eol attribute actually\nexplains it more clearly:\n\n\"Note that setting this attribute on paths which are in the index with\nCRLF line endings may make the paths to be considered dirty unless\ntext=auto is set. Adding the path to the index again will normalize\nthe line endings in the index.\"\n\nI think that explanation needs to be moved from the eol attribute\ndocumentation to the text attribute documentation and edited for\nclarity. I will send a v2 that revises the documentation of both\nattributes, taking into account your and Junio's feedback.\n\nThanks again,\n\n-Alex\n"},{"id":"476253","messageId":"20230428042221.871095-1-alexhenrie24@gmail.com","threadId":"59628","inReplyTo":"20230421055641.550199-1-alexhenrie24@gmail.com","subject":"[PATCH v2] docs: rewrite the documentation of the text and eol attributes","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-04-28T04:22:21Z","receivedAt":"2023-04-28T04:23:15Z","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 force normalization on checkin and checkout\nall by itself, but eol doesn't control normalization on checkin and\ndoesn't control normalization on checkout either unless accompanied by\nthe text attribute.\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 normalization is performed.\n\nSigned-off-by: Alex Henrie <alexhenrie24@gmail.com>\n---\nv2: rewrite completely and rewrite the eol documentation too\n---\n Documentation/gitattributes.txt | 58 +++++++++++++++++++--------------\n 1 file changed, 33 insertions(+), 25 deletions(-)\n\ndiff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\nindex 39bfbca1ff..bcea84f439 100644\n--- a/Documentation/gitattributes.txt\n+++ b/Documentation/gitattributes.txt\n@@ -120,20 +120,22 @@ 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+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 \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 \n Unset::\n \n@@ -142,10 +144,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@@ -162,23 +165,28 @@ 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-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 \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, 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+\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.0\n\n"},{"id":"476279","messageId":"xmqqsfcjevbz.fsf@gitster.g","threadId":"59628","inReplyTo":"20230428042221.871095-1-alexhenrie24@gmail.com","subject":"Re: [PATCH v2] docs: rewrite the documentation of the text and eol attributes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-04-28T18:05:20Z","receivedAt":"2023-04-28T18:05:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Alex Henrie <alexhenrie24@gmail.com> 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> \"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\".\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.\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>\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\nAll good observations, appropriate motivation of the change.\n\n> Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>\n> ---\n> v2: rewrite completely and rewrite the eol documentation too\n> ---\n\nThanks.  I wonder helped-by tboegi@ might be in order, but hopefully\nit may come during the review of this round.\n\n> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\n> index 39bfbca1ff..bcea84f439 100644\n> --- a/Documentation/gitattributes.txt\n> +++ b/Documentation/gitattributes.txt\n> @@ -120,20 +120,22 @@ 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> +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\nFour points.\n\n1. Overall, the new text is clearly written, and I think it made the\n   updated description of \"Set\" and \"Set to string 'auto'\" easier to\n   understand.\n\n2. \"on checkin and possibly also checkout\" may be redundant, as the\n   section in which the `text` attribute is described is all about\n   various conversions upon checking in (i.e. moving contents to the\n   index) and checking out (i.e. moving contents out of the index).\n   The introductory text for the whole section that does not define\n   what \"check-in\" and \"check-out\" are and instead loosely says\n   \"commands such as\" may want to be clarified, but that can be done\n   as a follow-on clean-up work after this patch lands.   \n\n3. It is unclear why we would want to mention \"even if it has CRLF\n   line endings in the working directory\".  \"Regardless of the line\n   endings in the working tree files\" may slightly be better [*1*],\n   but I think the text reads better without it as storing contents\n   with possibly different end-of-line convention is the point of\n   \"end-of-line normalization\" in the first place.\n\n   \"the file is stored in the index with LF line endings\" may better\n   be rephrased to \"the contents is stored, after converting to use\n   LF line endings if necessary, in the index\", so that we can use\n   the verb \"convert\" to stress the point of setting this attribute.\n\n4. This problem is shared with the original text, but \"This\n   attribute marks the path as a text file\" might be a bit\n   misleading.  If it is left unspecified (i.e. unmentioned, or any\n   earlier settings by explicitly overriding them with \"!text\") or\n   worse yet, explicitly unset (i.e. \"-text\"), it marks the path as\n   a non text.\n\n      This attribute is used to mark the path as a text file, which\n      needs certain end-of-line normalization upon check-in and\n      check-out, or a non-text file, which do not.\n\n  I dunno if the extra verbosity is too much, though.\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\n\"the next time\" -> \"every time\", but that is probably moot, because\nI would question the need for the whole sentence.\n\nThe last sentence, starting with \"Line endigns are normalized\", may\nbe redundant and we probably are better off without it.  It would\nrisk becoming maintenance burden because we have to make sure it\nstays in sync with what you wrote in the introductory text.  \"as\ndescribed above\" before that sentence is clear enough.\n\n> @@ -142,10 +144,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\nNice.\n\n> @@ -162,23 +165,28 @@ 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> -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\nThis level of clarification is very much appreciated.\n\nWe may want to use the phrase \"checking out\" somewhere in\nconjunction with \"in the working directory\" to be consistent with\nhow the section is titled.  Something like\n\n    This attribute marks a path to use a specific line-ending style\n    in the working tree when it is checked out.\n\n>  Set to string value \"crlf\"::\n>  \n> +\tThis setting converts the file's line endings in the working\n> +\tdirectory to CRLF when the file is checked out.\n\nNice.\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, 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\nFirst of all, \"uses the same, except if ... then LF is used\" is much\nharder to understand than \"use LF, except if ...\" as an explanation\nfor \"lf\".\n\nThe description may be correct but is 'eol=lf' what controls how the\nnormalization is done upon checking in?\n\nAs you said in the explanation for the `eol` attribute as a whole,\n`eol` is effective only when `text` says the path is a text file,\nand that (i.e. the fact that `text` controls the end-of-line) makes\nthe path to use LF line endings, isn't it?  The last sentence\nstarting with \"However, unless\" that talks about conversion going\ninto the index feels out of place.\n\nThere are some exception handling in the code for odd cases like the\ncontents with mixed line endings, a path set to use LF but the file\nactually has CRLF, etc.  While they are worth describing, I wonder\nif they should be done in a separate paragraph.\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\nNice.\n\n\n[Footnote]\n\n*1* The intent is not about special-casing CRLF but any other; if\n    Git were to be extended to support ancient MacOS, we would\n    convert even if it uses CR line endings.\n"},{"id":"476307","messageId":"CAMMLpeQB1zdTEWd+=d0kaKwpzax093iLTuytZtvn0nTSJ2xT4A@mail.gmail.com","threadId":"59628","inReplyTo":"xmqqsfcjevbz.fsf@gitster.g","subject":"Re: [PATCH v2] docs: rewrite the documentation of the text and eol attributes","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-04-29T19:19:00Z","receivedAt":"2023-04-29T19:20:26Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"On Fri, Apr 28, 2023 at 12:05 PM Junio C Hamano <gitster@pobox.com> wrote:\n\n> Thanks.  I wonder helped-by tboegi@ might be in order, but hopefully\n> it may come during the review of this round.\n\nSure, I'll add a Helped-by line in the next revision.\n\n> 1. Overall, the new text is clearly written, and I think it made the\n>    updated description of \"Set\" and \"Set to string 'auto'\" easier to\n>    understand.\n\nI'm glad you like it!\n\n> 2. \"on checkin and possibly also checkout\" may be redundant, as the\n>    section in which the `text` attribute is described is all about\n>    various conversions upon checking in (i.e. moving contents to the\n>    index) and checking out (i.e. moving contents out of the index).\n\nFor the `text` attribute's behavior to make sense, the first thing a\nnewbie has to understand is that `text` definitely enables\nnormalization on checkin and might or might not enable normalization\non checkout. The original text made it sound like `text` only controls\ncheckin and `eol` controls checkout, a false impression that is\nespecially misleading because on Linux and OS X, `text` without `eol`\n(or core.autocrlf or core.eol) does only enable normalization on\ncheckin. The new text may be slightly redundant, but it makes the\nimportant part crystal clear.\n\n> 3. It is unclear why we would want to mention \"even if it has CRLF\n>    line endings in the working directory\".  \"Regardless of the line\n>    endings in the working tree files\" may slightly be better [*1*],\n>    but I think the text reads better without it as storing contents\n>    with possibly different end-of-line convention is the point of\n>    \"end-of-line normalization\" in the first place.\n\n> *1* The intent is not about special-casing CRLF but any other; if\n>     Git were to be extended to support ancient MacOS, we would\n>     convert even if it uses CR line endings.\n\nI called out CRLF precisely because I was thinking about platforms\nthat use CR instead of LF or CRLF. I wanted to make it clear that if\nyou add a file that was written on or for an ancient Mac or Commodore,\nthe line endings are not normalized. Git can be used (and probably is\nbeing used by someone) to version-control files for those platforms\nwithout actually running on those platforms.\n\nThen again, maybe the fact that the `text` attribute does not\nnormalize CR line endings is a bug in Git, and we shouldn't advertise\nit in the documentation as if it were intended behavior. What do you\nthink?\n\n>    \"the file is stored in the index with LF line endings\" may better\n>    be rephrased to \"the contents is stored, after converting to use\n>    LF line endings if necessary, in the index\", so that we can use\n>    the verb \"convert\" to stress the point of setting this attribute.\n\nThe phrase \"if necessary\" would be a bit confusing. What makes\nconversion on checkin \"necessary\"? The reader would wonder if it\ndepends on the Git config and the platform like conversion on checkout\ndoes.\n\nWould you be OK with your proposed wording minus \"if necessary\"?\n\n> 4. This problem is shared with the original text, but \"This\n>    attribute marks the path as a text file\" might be a bit\n>    misleading.  If it is left unspecified (i.e. unmentioned, or any\n>    earlier settings by explicitly overriding them with \"!text\") or\n>    worse yet, explicitly unset (i.e. \"-text\"), it marks the path as\n>    a non text.\n>\n>       This attribute is used to mark the path as a text file, which\n>       needs certain end-of-line normalization upon check-in and\n>       check-out, or a non-text file, which do not.\n>\n>   I dunno if the extra verbosity is too much, though.\n\nHmm, I would find your proposed wording misleading because it seems to\nimply that the default is `text=auto` and that `-text` (or a config\nvariable) is necessary to turn end-of-line normalization off. In my\nopinion it's already clear enough that the attribute is unset by\ndefault and that `-text` unsets a previous `text`.\n\n> >  Set::\n> >\n> >       Setting the `text` attribute on a path enables end-of-line\n> > -     normalization and marks the path as a text file.  End-of-line\n> > -     conversion takes place without guessing the content type.\n> > +     normalization on checkin and checkout as described above.  Line\n> > +     endings are normalized in the index the next time the file is\n> > +     checked in, even if the file was previously added to Git with CRLF\n> > +     line endings.\n>\n> \"the next time\" -> \"every time\", but that is probably moot, because\n> I would question the need for the whole sentence.\n>\n> The last sentence, starting with \"Line endigns are normalized\", may\n> be redundant and we probably are better off without it.  It would\n> risk becoming maintenance burden because we have to make sure it\n> stays in sync with what you wrote in the introductory text.  \"as\n> described above\" before that sentence is clear enough.\n\nI added that sentence to make the difference between `text` and\n`text=auto` more clear. If all we have is the introductory paragraph,\nit sounds like Git only converts CRLF to LF on checkin if it had\nconverted LF to CRLF on checkout. However, if you feel strongly that\nthe sentence is unhelpful here, I'll remove it.\n\n> We may want to use the phrase \"checking out\" somewhere in\n> conjunction with \"in the working directory\" to be consistent with\n> how the section is titled.  Something like\n>\n>     This attribute marks a path to use a specific line-ending style\n>     in the working tree when it is checked out.\n\nThat's fine.\n\n> >  Set to string value \"lf\"::\n> >\n> > -     This setting forces Git to normalize line endings to LF on\n> > -     checkin and prevents conversion to CRLF when the file is\n> > -     checked out.\n> > +     This setting uses the same line endings in the working directory as\n> > +     in the index, whether they are LF or CRLF.  However, unless\n> > +     `text=auto`, adding the file to the index again will normalize its\n> > +     line endings to LF in the index.\n>\n> First of all, \"uses the same, except if ... then LF is used\" is much\n> harder to understand than \"use LF, except if ...\" as an explanation\n> for \"lf\".\n>\n> The description may be correct but is 'eol=lf' what controls how the\n> normalization is done upon checking in?\n>\n> As you said in the explanation for the `eol` attribute as a whole,\n> `eol` is effective only when `text` says the path is a text file,\n> and that (i.e. the fact that `text` controls the end-of-line) makes\n> the path to use LF line endings, isn't it?  The last sentence\n> starting with \"However, unless\" that talks about conversion going\n> into the index feels out of place.\n\nThat's a good point, it would be more clear here to explicitly say\nthat the setting affects checkout, and not mention what happens on\ncheckin (which was described previously in the `text` documentation).\nAlso, if we delete the sentence here then the seemingly redundant\nsentence that starts with \"Line endings are normalized\" wouldn't be as\nredundant.\n\n> There are some exception handling in the code for odd cases like the\n> contents with mixed line endings, a path set to use LF but the file\n> actually has CRLF, etc.  While they are worth describing, I wonder\n> if they should be done in a separate paragraph.\n\nProbably best done in a separate patch after this rewrite is done.\n\nWow, that was a LOT of feedback on a relatively short piece of text.\nAre you sure you don't want to rewrite the documentation yourself? ;-)\n\n-Alex\n"},{"id":"476313","messageId":"xmqqcz3m9ch1.fsf@gitster.g","threadId":"59628","inReplyTo":"CAMMLpeQB1zdTEWd+=d0kaKwpzax093iLTuytZtvn0nTSJ2xT4A@mail.gmail.com","subject":"Re: [PATCH v2] docs: rewrite the documentation of the text and eol attributes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-04-30T05:16:10Z","receivedAt":"2023-04-30T05:19:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Alex Henrie <alexhenrie24@gmail.com> writes:\n\n> The new text may be slightly redundant, but it makes the\n> important part crystal clear.\n\nI tend to disagree and think it is a bit too redundant, but we do\nnot have to agree on everything---after all you are doing all the\nwork, and it is your motivation and your topic.\n\n> Then again, maybe the fact that the `text` attribute does not\n> normalize CR line endings is a bug in Git, and we shouldn't advertise\n> it in the documentation as if it were intended behavior. What do you\n> think?\n\nJust not mentioning CRLF specifically would be sufficient.  When\n(and if) somebody actually comes and complains, we can say \"CR\ndelimited files are not considered text these days, we aren't doing\nMacOS System 7\" ;-).\n\n> The phrase \"if necessary\" would be a bit confusing. What makes\n> conversion on checkin \"necessary\"? The reader would wonder if it\n> depends on the Git config and the platform like conversion on checkout\n> does.\n>\n> Would you be OK with your proposed wording minus \"if necessary\"?\n\nI added it only because it would not be necessary if the original\nalready uses LF line endings, in which you do not have to do any\nconverison.  As long as it is clear that no conversion happens in\nsuch a case without saying, I am perfectly fine to drop it.\n\n>> There are some exception handling in the code for odd cases like the\n>> contents with mixed line endings, a path set to use LF but the file\n>> actually has CRLF, etc.  While they are worth describing, I wonder\n>> if they should be done in a separate paragraph.\n>\n> Probably best done in a separate patch after this rewrite is done.\n\nWhat I meant was that that your \"unless text=auto\" and everything\nafter it was one of thoese exception handling that should be dealt\nin a separate paragraph.  Leaving it as a follow-on work is fine.\n\n> Wow, that was a LOT of feedback on a relatively short piece of text.\n> Are you sure you don't want to rewrite the documentation yourself? ;-)\n\nAbsolutely not.  It is not my itch to update this document.\n\nMy itch is to make sure any change makes the resulting text better\nthan the previous one ;-).\n\nThanks.\n"},{"id":"476320","messageId":"20230430131943.4ag5gawuxkvuywlv@tb-raspi4","threadId":"59628","inReplyTo":"20230428042221.871095-1-alexhenrie24@gmail.com","subject":"Re: [PATCH v2] docs: rewrite the documentation of the text and eol attributes","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2023-04-30T13:19:43Z","receivedAt":"2023-04-30T13:19:54Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On Thu, Apr 27, 2023 at 10:22:21PM -0600, Alex Henrie wrote:\n\nThanks for picking this up.\nThere had been some comments from Junio, I haven't had time to look at\nthem yet.\nSome of my comments inline, lets see how we can converge things.\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> \"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\".\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.\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>\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>\n> Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>\n> ---\n> v2: rewrite completely and rewrite the eol documentation too\n> ---\n>  Documentation/gitattributes.txt | 58 +++++++++++++++++++--------------\n>  1 file changed, 33 insertions(+), 25 deletions(-)\n>\n> diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt\n> index 39bfbca1ff..bcea84f439 100644\n> --- a/Documentation/gitattributes.txt\n> +++ b/Documentation/gitattributes.txt\n> @@ -120,20 +120,22 @@ repository upon 'git add' and 'git commit'.\n>  `text`\n>  ^^^^^^\n>\n> -This attribute enables and controls end-of-line normalization.  When a\n\nHm, not only, I think. The terminologie is probably not very well specified.\nI would say that it \"controls end-of-line conversion\".\nThere are 2 type of conversions, from CRLF into LF and LF into CRLF.\nThe CRLF -> LF conversion happens only at `git commit`\n(strictly speaking already at `git add`) and is called normalization.\nBecause in Git a \"normalized\" file has LF in the repo (and index).\nThe term normalize has even been add to 2 commands:\n\n`git add --renormalize .`\ninspired by\n`git merge -Xrenormalize`\n\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\nIn general, the `eol` attribute can be used by more that a single file.\nAnd that is what we (or at least myself) recommend to do, in a kind\nof best practice fashion, as an example:\n\n*.sh text eol=lf\n\nThe core.eol is the fallback, when the eol attribute is not specified.\nBut the we look at core.autocrlf, before looking at core.eol,\nas pointed out below.\nAnd if none of them is set, Git uses the platform native setting,\nwhih is CRLF for Windows and LF for all other systems.\n\n\n> -Note that setting `core.autocrlf` to `true` or `input` overrides\n> -`core.eol` (see the definitions of those options in\n\nLooking with fresh eyes: I am not sure if like this historical construct.\nFirst we say the the \"core.eol\" sets the line endings (if not defined in\nthe attribute) and the we say that core.autcrlf overrides core.eol\n\nThis is mainly due to historically resons.\nI think that things goes like this:\nWhen text or text=auto (and Git identifies the file as text),\nand the eol attribute is not set, then:\ncore.autocrlf=true gives CRLF\ncore.autocrlf=input give LF\ncore.autocrlf=false looks at core.eol:\ncore.eol=clrf gives CRLF\ncore.eol=lf give LF\ncore.eol unset gives the platform default\n\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\nAs said before.\n ...normalization on checkin and possibly conversion at checkout...\n or\n  ... conversion on checkin and possibly also checkout...\n\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\"copied\" is not an ideal word here:\nWe may specify a filter and/or an encoding as well.\nWould \"transferred and possibly filtered/encoded\" be better ?\n\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>\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>\n>  Unset::\n>\n> @@ -142,10 +144,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\nSide note: We previously talked about files. path is better.\n>\n>  Unspecified::\n>\n> @@ -162,23 +165,28 @@ 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> -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.\n... Or `git add --renormalize <path> is run.\n\nAdding 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>\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, 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> +\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> --\n> 2.40.0\n>\n\nThanks again for working on this.\n/Torsten\n"},{"id":"476322","messageId":"CAMMLpeS7Cf5JbgtLMY5XCPdhSLgtyZEMt2xLdRpfD=Yj+uvz2g@mail.gmail.com","threadId":"59628","inReplyTo":"20230430131943.4ag5gawuxkvuywlv@tb-raspi4","subject":"Re: [PATCH v2] docs: rewrite the documentation of the text and eol attributes","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-04-30T23:43:00Z","receivedAt":"2023-04-30T23:44:48Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"On Sun, Apr 30, 2023 at 7:19 AM Torsten Bögershausen <tboegi@web.de> wrote:\n>\n> On Thu, Apr 27, 2023 at 10:22:21PM -0600, Alex Henrie wrote:\n\n> > -This attribute enables and controls end-of-line normalization.  When a\n>\n> Hm, not only, I think. The terminologie is probably not very well specified.\n> I would say that it \"controls end-of-line conversion\".\n> There are 2 type of conversions, from CRLF into LF and LF into CRLF.\n> The CRLF -> LF conversion happens only at `git commit`\n> (strictly speaking already at `git add`) and is called normalization.\n> Because in Git a \"normalized\" file has LF in the repo (and index).\n> The term normalize has even been add to 2 commands:\n>\n> `git add --renormalize .`\n> inspired by\n> `git merge -Xrenormalize`\n\nYes, we should probably be consistent about using the word \"normalize\"\nto refer to conversion to LF and the word \"convert\" to refer to\nconversion to CRLF or conversion in general. That would also allow us\nto use the word \"normalize\" for emphasis without wondering whether to\nadd \"if necessary\", because normalization certainly does not imply\nconversion if the file is already normalized.\n\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>\n> Looking with fresh eyes: I am not sure if like this historical construct.\n> First we say the the \"core.eol\" sets the line endings (if not defined in\n> the attribute) and the we say that core.autcrlf overrides core.eol\n>\n> This is mainly due to historically resons.\n> I think that things goes like this:\n> When text or text=auto (and Git identifies the file as text),\n> and the eol attribute is not set, then:\n> core.autocrlf=true gives CRLF\n> core.autocrlf=input give LF\n> core.autocrlf=false looks at core.eol:\n> core.eol=clrf gives CRLF\n> core.eol=lf give LF\n> core.eol unset gives the platform default\n\nYes, core.autocrlf takes precedence over core.eol. That's explained in\nthe git-config documentation and doesn't need to be explained again in\nthe attribute documentation. However, in the documentation for\nunspecified `eol`, I did make sure to name `eol`, core.autocrlf, and\ncore.eol in order of precedence.\n\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> \"copied\" is not an ideal word here:\n> We may specify a filter and/or an encoding as well.\n> Would \"transferred and possibly filtered/encoded\" be better ?\n\nAlthough \"transferred and possibly filtered/encoded\" might be\ntechnically more accurate, it is a mouthful. For readability, it would\nbe better to keep the documentation concise. It's clear in this\nsentence that \"copy\" does not mean a byte-for-byte copy (because the\nline endings may be changed), which leaves open the possibility that\nthe file may be transformed in other ways during checkout.\n\n> > +     When `text` is set to \"auto\", Git decides by itself whether the file\n> > +     is text or binary.  If it is text and the file was not already in\n> > +     Git with CRLF endings, line endings are converted on checkin and\n> > +     checkout as described above.  Otherwise, no conversion is done on\n> > +     checkin or checkout.\n>\n> Side note: We previously talked about files. path is better.\n\nIt depends: When talking about applying the attribute to a path, path\nis better, but the actual transformation happens on the file contents.\nThe file is what's text or binary and the file is what's transformed;\nthe path is always text and never transformed.\n\nThanks for the feedback. I will send a v3 that takes into account your\nfeedback and Junio's.\n\n-Alex\n"},{"id":"476323","messageId":"CAMMLpeTWxLKtrXxLWY=3mCwh2i8jhQ7ZcivdxpY36rDBpNtK8A@mail.gmail.com","threadId":"59628","inReplyTo":"xmqqcz3m9ch1.fsf@gitster.g","subject":"Re: [PATCH v2] docs: rewrite the documentation of the text and eol attributes","fromName":"Alex Henrie","fromEmail":"alexhenrie24@gmail.com","sentAt":"2023-05-01T00:40:00Z","receivedAt":"2023-05-01T00:42:04Z","isPatch":true,"sender":{"key":"alexhenrie24@gmail.com","avatar":"https://avatars.githubusercontent.com/u/5951993?v=4"},"body":"On Sat, Apr 29, 2023 at 11:16 PM Junio C Hamano <gitster@pobox.com> wrote:\n>\n> Alex Henrie <alexhenrie24@gmail.com> writes:\n>\n> > The new text may be slightly redundant, but it makes the\n> > important part crystal clear.\n>\n> I tend to disagree and think it is a bit too redundant, but we do\n> not have to agree on everything---after all you are doing all the\n> work, and it is your motivation and your topic.\n\nI just now realized that `eol=crlf` works when `text` is unspecified.\nIn that light, the phrase \"on checkin and possibly also checkout\"\nseems to go a little too far towards implying that the eol attribute\nand core.autocrlf config variable depend on the text attribute being\nset. Omitting that phrase would leave the introduction with a better\nbalance between precision and brevity, and the remainder of the\ndocumentation would still be there to flesh out the details.\n\n> > Then again, maybe the fact that the `text` attribute does not\n> > normalize CR line endings is a bug in Git, and we shouldn't advertise\n> > it in the documentation as if it were intended behavior. What do you\n> > think?\n>\n> Just not mentioning CRLF specifically would be sufficient.  When\n> (and if) somebody actually comes and complains, we can say \"CR\n> delimited files are not considered text these days, we aren't doing\n> MacOS System 7\" ;-).\n\nI don't think I would dare say \"CR-delimited text is not text\" to a\nretro computing enthusiast. But I'm fine with not mentioning CRLF in\nthis sentence, and when the angry mob shows up on my doorstep, I will\njust send them your way ;-)\n\n-Alex\n"}]}