add documentation about the 'spurious EOL normalization' bug in GitHub by pchampin · Pull Request #452 · w3c/guide

pchampin · 2026-08-27T14:52:33Z

as discussed today during global

iherman · 2026-08-28T08:28:07Z

+  ```
+  * text=auto
+  ```


Others were advocating

* text=auto eol=lf

are we 100% sure that the eol=lf is superfluous? Or is it wrong to set it this way?

My understanding is that eol=lf will force the local copies to use LF, including on Windows, which some (crude) editors may not like.

From the GIT documentation

If the eol attribute is unspecified for a file, its line endings in the working directory are determined by the core.autocrlf or core.eol configuration variable (see the definitions of those options in git-config[1]). If text is set but neither of those variables is, the default is eol=crlf on Windows and eol=lf on all other platforms.

So leaving it unspecified seems better.

And I did explicitly test this on Windows, and it does force all files in my working directory to have LF line endings, which is wrong for Windows. That said, even Notepad can handle such files, so I am not sure what practical impact it has these days. But I advocate for not forcing that (no eol=lf added) as it seems unrelated (you just want to normalize line endings in the repo, what I do with the files should be up to me).

My understanding is that eol=lf will force the local copies to use LF, including on Windows

Maybe so. Somewhere someone must be able to answer why when those configuration files are not in place, a Mac-based LF user of the GitHub browser interface gets their file(s) normalized to the Windows CRLF.

iherman · 2026-08-28T08:31:36Z

+  + checkout the branch of the PR locally
+  + modify the incriminated commit with [`git rebase -i`](https://git-scm.com/docs/git-rebase#_interactive_mode);
+    a useful command to change all CRLFs back to LFs is `sed 's/\r$//' -i [filename]`
+  + "force-push" the rebased branch with `git push --force`


I think a slightly more verbose description of what can/should be done is worth adding for less advanced users...

That's why I marked this item as for "advanced users" :-)
I didn't have time to turn this into a proper tutorial, and I don't think this should block this page from being added. But +1 to be more explicit about it, eventually.

iherman · 2026-08-28T08:34:18Z

+* running `git add . --renormalize`
+  to ask GIT to remove all mixed EOL in text files already present in the repository.
+  (Again, this will *not* change the local copies.)


There are possible objections to this, see w3c/vc-wg#16 (comment)

I'll respond to those objections in that thread, but I don't think this step is actually required, so I added "optionally" in front of this bullet.

iherman · 2026-08-28T08:37:35Z

flagging @msporny @bduga for their possible inputs

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

bduga

LGTM. A couple of suggested changes, but they are codepoint neutral (no code points added or removed).

bduga · 2026-08-28T20:04:40Z

+in a PR, and possibly after using the
+[online editor](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor),
+the PR appears to modify *all the lines* of a given file.
+The change in most line is in fact only touching the end-of-line (EOL) character, changing all LFs to CRLFs.


Suggested change

The change in most line is in fact only touching the end-of-line (EOL) character, changing all LFs to CRLFs.

The change in most lines is in fact only touching the end-of-line (EOL) character, changing all LFs to CRLFs.

bduga · 2026-08-28T20:07:43Z

+> [!Note]
+> This behaviour is not a "normal" GIT behaviour:
+> to reproduce it, one has to tweak the GIT configuration between the time the file is checked out and the time the file is commited!
+> It seems more likely that it is a GitHUb bug.


FWIW, I was able to repro this bug entirely in git by setting autocrlf=false on my Windows client and checking out files from a repo that did not have a .gitattributes file specifying end-of-line behavior.

bduga · 2026-08-28T20:08:40Z

+* It is possible to ask GIT or github to ignore whitespaces when showing the difference between two versions of a file:
+
+  + in github, by clicking on the cog-wheel button in the 'Files changed' view of the PR,
+    and checking 'Hide whitespace' (alternatively: adds the `?w=1` parameter to the URL,


Suggested change

and checking 'Hide whitespace' (alternatively: adds the `?w=1` parameter to the URL,

and checking 'Hide whitespace' (alternatively: add the `?w=1` parameter to the URL,

bduga · 2026-08-28T20:16:31Z

+  ```
+  * text=auto
+  ```


And I did explicitly test this on Windows, and it does force all files in my working directory to have LF line endings, which is wrong for Windows. That said, even Notepad can handle such files, so I am not sure what practical impact it has these days. But I advocate for not forcing that (no eol=lf added) as it seems unrelated (you just want to normalize line endings in the repo, what I do with the files should be up to me).

TallTed · 2026-08-29T00:28:37Z

+[applying suggested changes](https://docs.github.com/en/pull-requests/how-tos/review-pull-requests/incorporating-feedback-in-your-pull-request#applying-suggested-changes)
+in a PR, and possibly after using the
+[online editor](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor),
+the PR appears to modify *all the lines* of a given file.


Suggested change

the PR appears to modify *all the lines* of a given file.

GitHub forces the PR modify *all the lines* of a given file,

"normalizing" the EOL characters to CRLF.

GitHub claims they do this only

when they have detected a mix of EOL characters in the file.

To the best of my knowledge, they have not documented what problem is caused by such

a mix of EOL characters, nor why they are defaulting to

normalize to Windows CRLF, which appears

to be a change from previous default behavior.

add documentation about the 'spurious EOL normalization' bug in GitHub

0a93510

TallTed reviewed Aug 27, 2026

View reviewed changes

Comment thread github/spurious_eol.md

iherman reviewed Aug 28, 2026

View reviewed changes

pchampin and others added 2 commits August 28, 2026 15:14

Update github/spurious_eol.md

b49055b

Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>

Update spurious_eol.md

92399cd

bduga approved these changes Aug 28, 2026

View reviewed changes

TallTed reviewed Aug 29, 2026

View reviewed changes

iherman approved these changes Aug 30, 2026

View reviewed changes

	The change in most line is in fact only touching the end-of-line (EOL) character, changing all LFs to CRLFs.
	The change in most lines is in fact only touching the end-of-line (EOL) character, changing all LFs to CRLFs.

	and checking 'Hide whitespace' (alternatively: adds the `?w=1` parameter to the URL,
	and checking 'Hide whitespace' (alternatively: add the `?w=1` parameter to the URL,

-the PR appears to modify *all the lines* of a given file.
+GitHub forces the PR modify *all the lines* of a given file,
+"normalizing" the EOL characters to CRLF.
+GitHub claims they do this only
+when they have detected a mix of EOL characters in the file.
+To the best of my knowledge, they have not documented what problem is caused by such
+a mix of EOL characters, nor why they are defaulting to
+normalize to Windows CRLF, which appears
+to be a change from previous default behavior.

Uh oh!

Conversation

pchampin commented Aug 27, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iherman commented Aug 28, 2026

Uh oh!

bduga left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants