Vagrant file provisioner should warn about Windows CRLF (\r\n) issues on Linux guests

[wngtk]

Is your feature request related to a problem? Please describe. Yes. When using vagrant provision file to transfer text files (e.g., .git-credentials, shell scripts) from a ​​Windows host​​ (CRLF line endings) to a ​​Linux guest​​, the retained \r\n characters can cause silent failures (e.g., Git authentication errors, script execution failures). Currently, Vagrant provides no warning about this potential compatibility issue, forcing users to manually debug.

Describe the solution you'd like Vagrant should ​​detect and warn users​​ when transferring text files with CRLF line endings to Linux guests. Specifically:

1. ​​Detection​​: During file provisioner execution, check if: Source file has CRLF endings (via quick scan or file command). Guest OS is Linux/Unix (via uname or VM metadata).
2. ​​Warning​​: Log a ​​non-blocking warning message​​ during transfer, e.g.:

[FILE PROVISIONER NOTICE] File "~/.git-credentials" contains Windows CRLF line endings.  
This may cause compatibility issues on Linux guests. Convert to LF (e.g., with `dos2unix`).  

Describe alternatives you've considered Currently, users must manually run sed -i 's/\r$//' or dos2unix in a subsequent shell provisioner. Or users can convert CRLF to LF directly in ​​VSCode.

Additional context

• Why this matters​​:

  • CRLF issues are subtle and time-consuming to debug (e.g., Git errors without obvious causes).
  • Windows users may not be aware of Linux line ending requirements.

• ​​Technical feasibility​​:

  • Line ending detection is lightweight (e.g., check first 1KB of file for \r\n).
  • Guest OS type is already known to Vagrant.

• Prior art​​:

  • Git warns about CRLF/LF conflicts (core.autocrlf).
  • VS Code/Notepad++ show line ending indicators.

[taru-garg-hashicorp]

Hi @wngtk,

Thank you for the detailed report. I completely understand the frustration that comes with debugging silent failures caused by line ending differences.

However, I don't think that Vagrant should be responsible for logging a warning in this case. Tools like git can provide such warnings because they typically know the type of files they're dealing with and can make reasonable assumptions about whether a file is text or binary. In contrast, Vagrant’s file provisioner is deliberately agnostic about file contents—it transfers files without inspecting or interpreting them. Trying to detect line ending mismatches in this context introduces several significant challenges:

1. Vagrant does not differentiate between text, zip archives, binary files and even directories to some extent. If it were to analyze every file for line endings, it could easily generate false positives by flagging valid files as problematic, which would only confuse users and cause unnecessary concern.
2. If Vagrant were to issue a blanket warning every time a file is copied from Windows to Linux (or vice versa), it would likely result in excessive noise, making it more difficult for users to spot real issues.
3. Similar concerns have been raised in Packer (packer#5212, packer#2489), where the consensus was that these tools should remain as general-purpose as possible and avoid making assumptions about user intent or file contents.

Although Shell Provisioner does have the ability to change line endings based on a configuration variable, but this is only possible because the shell script contents are known to Vagrant. In contrast, with the file provisioner, Vagrant doesn't know the file contents, so it can't reliably determine if a file contains line endings that are incompatible with the guest OS.

Happy to hear your thoughts on this!

[wngtk]

Hi @taru-garg-hashicorp ,

Thank you for your thoughtful response and for explaining the reasoning behind Vagrant's design decisions regarding file provisioning. I completely agree with your perspective - it makes sense for Vagrant to remain content-agnostic when transferring files to maintain its general-purpose nature and avoid false positives.

I appreciate you pointing out that the Shell Provisioner does have line ending handling capabilities through configuration variables. This is good to know and provides a built-in solution for cases where line ending conversion is needed.

While I understand the challenges involved, I still believe line ending issues could be worth documenting somewhere in Vagrant's documentation as a common pitfall for Windows-to-Linux provisioning scenarios. Perhaps this could be mentioned in the file provisioner documentation or troubleshooting guide as something for users to be aware of.

Thanks again for taking the time to consider this suggestion and for the clear explanation of Vagrant's design philosophy.

[taru-garg-hashicorp]

Hi @wngtk,

Yes, I agree that it is something that can be mentioned in the Vagrant Documentation. Will have a discussion with the team and look at getting this behaviour mentioned in the documentation.

Thanks!