Git's CRLF transformations interfere with content hashes

[SteveSandersonMS]

Originally reported as #19775, but the issue is slightly more general than that so I'll rephrase it.

Problem: If you use Git [1] as a way of transferring build output to your production server, and the production server has different newline conventions from the build server [2], then content hashes in text files (such as blazor.webassembly.*.js) will not match and the application will not load.

[1] i.e., the source control technology, not necessarily GitHub. So this applies to Kudu too.
[2] e.g., build machine is Windows and production server is Linux, or vice-versa

This happens because by default Git performs automatic CRLF conversions on commit.

Strictly speaking this issue is not specific to Blazor, but would apply to any web technology that computes subresource integrity hashes during build. However it's a bigger issue for Blazor because (1) we're now computing subresource integrity hashes during build by default, and (2) an unusually large proportion of Blazor developers use Windows.

Possible solutions

People have two main ways to avoid this problem. They can use <BlazorCacheBootResources>false</BlazorCacheBootResources> to disable the caching-and-integrity-checking feature entirely, or they can put a .gitattributes file in their repo specifying autocrlf=false.

The question is: how are we going to help people with this?

1. Docs only

We could add documentation to the deployment pages giving advice about git-based deployment mechanisms, especially highlighting that this affects GitHub Pages.

We would advise people to add a .gitattributes file to their repo specifying autocrlf=false (at least in the subdirectory representing their GitHub Pages content, i.e., the published output).

2. Auto-generate a .gitattributes file

On publish, we could place the relevant .gitattributes file in the output.

It sucks pretty bad for us to couple aspects of our build pipeline to a particular source control system, even if it is the de-facto industry standard. We don't know whether the customer is planning to use Git as a deployment mechanism, so we don't know whether the .gitattributes file is really relevant.

We could:

• [A] Just do it all the time regardless, reasoning that it's not harmful in the cases where it's not needed. Possibly with an MSBuild option to disable this for people who care.
  • Pro: just works
  • Con: clumsy
• [B] Or, do that but with the default being "off", so people have to explicitly enable it by setting <DisableGitAutoCRLFInPublishOutput>true</DisableGitAutoCRLFInPublishOutput>
  • Pro: convenient for people who know about it
  • Con: undiscoverable without reading docs. People will still have deployment problems by default and not know what to do. If we're relying on people reading docs, why not just have docs telling them to add a .gitattributes file manually?
• [C] Or, have the default on/off setting determined by the condition "is the publish output going into a git repo?". We can detect this by scanning upwards for the presence of a .git directory.
  • Pro: just works at least in the most obvious and basic cases, without cluttering things in non-Git scenarios.
  • Con: Since Git is so overwhelmingly prevalent, why go to all this effort to detect non-Git scenarios? Virtually nobody is not using Git.
  • Con: Still doesn't work in more complicated cases, such as when the build process is operating on files outside a Git repo (due to some custom CI setup) but the results are then being copied into a Git repo.

My first instinct is to think about a docs-only solution initially, and consider upgrading it to a more automated solution if we keep getting customer reports about it.

[SteveSandersonMS]

Just in case anyone's about to suggest it, here's a solution that wouldn't work:

Change blazor.*.js in our packages to Linux-style line endings

If we knew for sure that you'd be deploying to Linux, we would benefit from having blazor.*.js use *nix-style line endings even on Windows because then it would just work. However that's just moving the problem, because if you now deploy to a Windows production server, the issue still occurs since the checkout on the Windows server would convert to CRLF.

There is no single correct line ending style to solve this problem. We just need Git to stop interfering with the line endings.

[chucker]

Blazor generating a .gitattributes smells like an unexpected layering violation to me.

---

Problem: If you use Git [1] as a way of transferring build output to your production server, and the production server has different newline conventions from the build server [2], then content hashes in text files (such as blazor.webassembly.*.js) will not match and the application will not load.

So, if I'm reading this correctly, the (flawed) flow is:

1. development machine produces hashes for files
2. development machine pushes the result, including those hashes, to the remote git
3. production machine has different linebreak convention; thus, the hashes are wrong
4. in this scenario, production machine has no dynamic code (e.g. an ASP.NET Core server) running, i.e. the files are served statically, so this cannot be fixed on the production end

So, given the existence of:

<BlazorCacheBootResources>false</BlazorCacheBootResources>

How about extending this as follows:

<BlazorCacheBootResources linebreakConvention="lf">false</BlazorCacheBootResources>

This still comes with the problem that now we've shifted the wrong behavior — production will now be right, and development no longer will be.

But that's a solved problem! Instead of placing BlazorCacheBootResources in the .csproj file, we put it in the .pubxml, which also uses MSBuild tooling. That way, we can even have different settings for this per-deployment endpoint.

[chanan]

@SteveSandersonMS I have not been able to get this solution to work.

I added autocrlf=false to my .gitattributes and after that did nothing I commented out: * text=auto which was created automatically by VS I think.

Before commenting out * text=auto nothing changed. Once I commented that out I got an email from github:

The page build failed for the `master` branch with the following error:

Unable to build page. Please try again later.

For information on troubleshooting Jekyll see:

  https://help.github.com/articles/troubleshooting-jekyll-builds

If you have any questions you can submit a request on the Contact GitHub page at https://support.github.com/contact/pages?repo_id=197678953&page_build_id=168691231

Now when I go to the site I get in the console:

(index):78 GET https://chanan.github.io/BlazorTypography/_framework/blazor.webassembly.js net::ERR_ABORTED 404

I am pretty sure its there. You can see the source of the site at: https://github.com/chanan/BlazorTypography/tree/master/docs

[jspuij]

@chanan autocrlf is for the git configuration, not for gitattributes.

* binary

would probably work for github pages. But do not use this in a source code repo, as line ending handling is a good thing.

More info:

https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes

[SteveSandersonMS]

But do not use this in a source code repo, as line ending handling is a good thing.

It's perfectly reasonable to use it in the directory containing your publish output, since that exists only as a way of transferring the content to your production server. The files in that directory are not meant to be edited; they are just emitted by the build system.

[chanan]

@SteveSandersonMS Are you saying I should have a different gitattributes in the root and one in the /Docs?

[jspuij]

server. The files in that directory are not meant to be edited; they are just emitted by the build system.

That's what I meant. Could have clarified that. Gitattributes supports patterns, so you could exclude directory from the root .gitattributes file, or just nest gitattributes files inside the repo structure.

[chanan]

Tried this. I put back the main gitattrbutes to the way it was before. Added a .gitattributes with the autocrlf in the /Docs - reuploaded the _framework folder.

Again I got an the same email from github that I pasted above. Still getting the 404 that I pasted in the same comment: #19796 (comment)

End result: still not working

[campersau]

@chanan the _framework folder got deleted in chanan/BlazorTypography@3f26aa4

[chanan]

Sorry, you are right, forgot to push... it's there now, same result.