{"id":115,"date":"2026-11-16T16:40:00","date_gmt":"2026-11-16T16:40:00","guid":{"rendered":"https:\/\/www.masters-tool.com\/blog\/?p=115"},"modified":"2026-11-11T03:39:06","modified_gmt":"2026-11-11T03:39:06","slug":"line-ending-conversion-windows-linux","status":"publish","type":"post","link":"https:\/\/www.masters-tool.com\/blog\/line-ending-conversion-windows-linux\/","title":{"rendered":"Converting Line Endings Between Windows and Linux"},"content":{"rendered":"<p><strong>TL;DR \/ Summary:<\/strong> Line endings look invisible and cause real breakage: shell scripts fail with a carriage return, git shows every line as changed, and Windows tools double-space output. Convert deliberately, and configure the repository so it stops happening.<\/p>\n<h2>What the two formats are<\/h2>\n<p>Unix uses a line feed. Windows traditionally uses a carriage return followed by a line feed. The extra byte is invisible in most editors and very visible to interpreters.<\/p>\n<p>A shell script with Windows endings fails on Linux with an error like &#8220;bad interpreter&#8221;, because the kernel reads the carriage return as part of the path.<\/p>\n<p>That single byte explains a large share of &#8220;it works locally&#8221; deployment failures.<\/p>\n<h2>Which files should be which<\/h2>\n<p>Source code, scripts, and configuration files belong in Unix format, even on a Windows checkout, because they are consumed by servers.<\/p>\n<p>Batch files and some legacy Windows tools expect the Windows format. Those are the exceptions, and they should be listed explicitly.<\/p>\n<h3>A sensible rule set<\/h3>\n<ul>\n<li><strong>Default:<\/strong> Unix endings for text files<\/li>\n<li><strong>Exception:<\/strong> <code>.bat<\/code> and <code>.cmd<\/code> in Windows format<\/li>\n<li><strong>Binary files:<\/strong> never converted, always declared<\/li>\n<li><strong>Scripts with shebangs:<\/strong> Unix, enforced<\/li>\n<\/ul>\n<p>The rule needs to live in configuration, not in a document. People forget documents.<\/p>\n<h2>Converting a tree<\/h2>\n<p>Convert a batch of files with a single command, and do it on a branch so the change is reviewable.<\/p>\n<p>Expect a huge diff. The diff is the change, and it should be committed separately from functional edits so history stays legible.<\/p>\n<blockquote><p>Never mix a line-ending conversion with a logic change in one commit.<\/p><\/blockquote>\n<p>Check the result with a tool that shows invisible characters. A visual scan in a normal editor cannot tell you what you have.<\/p>\n<h2>Preventing the problem<\/h2>\n<p>Set the repository&#8217;s attributes so text files are normalised on checkout and commit. That is the durable fix, and it survives new contributors.<\/p>\n<p>Also configure the editor to save with the right endings, so files created outside the repository follow the same convention.<\/p>\n<p>Add a check in continuous integration that fails on carriage returns in shell scripts. One line catches a class of bug permanently.<\/p>\n<h2>Symptoms worth recognising<\/h2>\n<p>A script that works when pasted into a terminal but fails when executed is usually a line-ending problem. The paste normalises, the execution does not.<\/p>\n<p>Git showing entire files as modified after a Windows checkout is the same issue in the other direction.<\/p>\n<p>A CSV that opens with an extra blank row in some tools can also be an ending mismatch, particularly when the last line has no terminator.<\/p>\n<h2>Working across platforms<\/h2>\n<p>If the team uses both systems, standardise on Unix endings and accept that Windows editors may warn. The warning is cheaper than the deployment failure.<\/p>\n<p>Container images make this obvious quickly, which is an argument for building in the same environment you deploy to.<\/p>\n<p>Document the exception list once. Two files in Windows format is easy to remember; a general policy of &#8220;it depends&#8221; is not.<\/p>\n<p>For quick conversions of individual files, <a href=\"https:\/\/www.masters-tool.com\/\">the developer utility tools<\/a> handle encoding and line-ending changes without a full build pipeline, which is useful when you are fixing a single stubborn script. Then put the repository configuration in place so you never have to do it again.<\/p>\n<h2>Repository attributes in practice<\/h2>\n<p>A single attributes file at the repository root can normalise endings for every text file and declare the exceptions. It is read by Git on every checkout, so it works for contributors who never read the documentation.<\/p>\n<p>Set text files to normalise on commit and check out as Unix, then list batch files explicitly as Windows. Binary formats should be marked so Git never attempts a conversion.<\/p>\n<p>After adding the file, renormalise the working tree once and commit that change alone. The diff will be enormous and it will never appear again.<\/p>\n<blockquote><p>Configuration beats instruction. A rule in a file survives a new colleague.<\/p><\/blockquote>\n<p>Test by cloning fresh on both platforms. If the clone behaves, the attributes are right.<\/p>\n<h2>Batch files and legacy tools<\/h2>\n<p>Batch scripts genuinely need Windows endings, and some older Windows utilities misread files without them. Those are the only routine exceptions worth maintaining.<\/p>\n<p>Keep the exception list short and visible. Every addition is a file that needs remembering, and forgotten exceptions produce exactly the failures the policy was meant to prevent.<\/p>\n<p>For mixed toolchains, prefer running the conversion as a build step rather than storing two copies. Two copies drift, and the drifting copy is always the one that gets deployed.<\/p>\n<h2>Checking a file without opening it<\/h2>\n<p>A file inspection tool shows carriage returns as visible markers. That is faster and more reliable than opening an editor that silently normalises.<\/p>\n<p>Do the check after a conversion and after a fresh clone. Both states matter, and only one of them is usually tested.<\/p>\n<blockquote><p>Trust the bytes, not the editor.<\/p><\/blockquote>\n","protected":false},"excerpt":{"rendered":"<p>TL;DR \/ Summary: Line endings look invisible and cause real breakage: shell scripts fail with a carriage return, git shows every line as changed, and Windows tools double-space output. Convert deliberately, and configure the repository so it stops happening. What the two formats are Unix uses a line feed. Windows traditionally uses a carriage return [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":41,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4],"tags":[],"class_list":["post-115","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-everyday-workflows","entry","has-media"],"_links":{"self":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts\/115","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/comments?post=115"}],"version-history":[{"count":1,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts\/115\/revisions"}],"predecessor-version":[{"id":116,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts\/115\/revisions\/116"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/media\/41"}],"wp:attachment":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/media?parent=115"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/categories?post=115"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/tags?post=115"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}