ppsspp/docs/patching-files.md

Patching files from a script

Most edits should go through an editor tool that does exact string replacement. This document is about the cases where you reach for a script instead - a repetitive change across many files, say - and the two ways that silently corrupts a diff on Windows.

The short versions of both live in AGENTS.md (General instructions, rules 5 and 6). This is the detail.

Line endings

Which ending a file has depends on where it was checked out. Markdown, .cpp and most sources are stored in git with LF, and a Windows checkout converts them to CRLF on the way out; a Linux checkout leaves them alone. So the same file - .vcxproj, .vcxproj.filters, android/jni/Android.mk, libretro/Makefile.common, AGENTS.md, much of the source - is CRLF in one working copy and LF in another. Don't hardcode either, and don't "fix" a file's endings to match what a doc claims.

If you patch one with a script, read and write with newline='', which keeps whatever was there. Reading with Python's default universal-newline translation and writing with newline='' silently converts the whole file, turning a two-line addition into a 5000-line diff.

Check git diff --stat before committing - a whole-file rewrite is obvious there and invisible in the editor.

Backslashes in a bash heredoc

Don't feed Python to bash -c via a heredoc when the code contains backslashes. The Git Bash / MinGW layer strips one level of backslash escaping on the way in, even with a quoted delimiter (<<'PY'), which normally suppresses all substitution. So the script Python receives is not the one you wrote:

You write in the heredoc	Python actually sees	Result
"\r\n"	"\r\n"	fine - survives, because you want Python to interpret it
"\\n" (intending a literal \n in the output)	"\n"	a real newline is written into the file
'foo \\\r\n' as a match anchor	'foo \<CR><LF>'	anchor silently doesn't match, reported as "anchor missing"

The tell for the first case is a compiler error like C2001: newline in string literal; the second case produces no error at all, just a patch that quietly did nothing. Both are invisible in the heredoc you wrote.

The rule: a heredoc is fine as long as every backslash in the script is one you want Python to interpret. The moment you need a literal backslash in the output, stop. Then either:

• use an exact-string-replacement editor tool instead (no shell in the path - the best option for the common case of "insert a few lines of C++ that contain \n"), or
• write the script to a file and run python thescript.py, or
• build the backslash as chr(92) so no literal backslash appears in the heredoc at all.

Note this is about the Python source, not the data: reading and rewriting a CRLF file with newline='' and \r\n anchors works fine in a heredoc, and is the normal way to patch files here.