CRLF vs LF Kesalahan Penghentian Baris yang Menghancurkan CI

Skrip shell Anda bekerja dengan baik di laptop Anda. Anda mendorongnya ke GitHub, CI mengambilnya, dan pipeline gagal dengan kesalahan yang tidak jelas — sesuatu seperti /bin/bash^M: bad interpreter atau suatu pekerjaan yang keluar dengan kode 126 tanpa alasan yang jelas. Skrip tersebut secara sintaksis benar. Anda tidak mengubah satu baris pun. Namun, buildnya rusak.

Sembilan kali dari sepuluh kasus, penyebabnya adalah akhir baris. Secara khusus, akhir baris berbentuk Windows (CRLF) yang tersembunyi di dalam file yang diharapkan hanya memiliki akhir baris LF oleh Linux. Artikel ini menjelaskan apa yang sebenarnya dimaksud dengan dua karakter tersebut, mengapa perbedaan ini lebih penting daripada yang banyak pengembang sadari, dan bagaimana mengatasi masalah ini secara permanen.

Apa yang Dimaksud dengan CRLF dan LF

Setiap file teks perlu cara untuk menandai akhir baris. Dua karakter kendali digunakan di berbagai sistem operasi:

• LF (Line Feed, \n, heksa 0x0A) — standar Unix dan Linux. macOS telah menggunakan ini sejak OS X. Satu byte per akhir baris.
• CRLF (Carriage Return + Line Feed, \r\n, heksa 0x0D 0x0A) — standar Windows, yang diwariskan dari DOS, yang diwariskan dari mesin teletype. Dua byte per akhir baris.

Nama-nama ini berasal dari tindakan fisik dari mesin ketik kuno: carriage return memindahkan kepala cetak kembali ke awal baris; line feed memutar kertas satu baris ke atas. DOS mengkodekan kedua tindakan secara literal. Unix memilih pendekatan minimal dan hanya mempertahankan line feed.

Mengapa CI Gagal dan Laptop Anda Tidak

Jika Anda menulis kode di Windows dan editor Anda menyimpan file dengan CRLF, semuanya bekerja secara lokal — alat Windows menangani kedua format secara transparan. Namun, pipeline CI Anda hampir pasti berjalan di Linux, dan interpreter shell Linux menganggap \r sebagai karakter yang dapat dicetak, bukan spasi. Ketika bash membaca baris skrip yang berakhir dengan \r\n, ia melihat perintah ditambah karakter carriage return di akhir. Hasilnya terlihat seperti ini:

/bin/bash^M: bad interpreter: No such file or directory

Itu ^M dalam kesalahan tersebut adalah cara terminal menampilkan \r. Bash berusaha menjalankan baris shebang yang berakhir dengan carriage return, dan tentu saja tidak ada interpreter di jalur tersebut.

Masalah yang sama muncul dalam bentuk yang lebih halus:

• Nilai variabel lingkungan dengan karakter \r di akhir secara diam-diam menghancurkan perbandingan string.
• Skrip Docker ENTRYPOINT gagal dimulai karena shebangnya rusak.
• Skrip Python membaca file konfigurasi dan mendapatkan kunci seperti "setting\r" alih-alih "setting".
• File Makefile mengabaikan aturan karena karakter tab diikuti oleh \r.

Cara Mendeteksi Masalah Ini

Sebelum memperbaiki sesuatu, konfirmasi bahwa file memang memiliki akhir baris CRLF. Beberapa cara cepat:

cat -A (Linux/macOS)

cat -A deploy.sh

Baris yang berakhir dengan CRLF akan ditampilkan ^M$ di akhir. Hanya baris yang berakhir dengan LF yang menampilkan $.

perintah

file deploy.sh
# deploy.sh: Bash script, ASCII text, with CRLF line terminators

xxd atau hexdump

xxd deploy.sh | grep "0d 0a"

Setiap hasil yang cocok menunjukkan CRLF. Jika Anda hanya melihat 0a di akhir baris, maka Anda bersih.

Cara Memperbaikinya

dos2unix (perbaikan tercepat)

Instal sekali, jalankan pada setiap file:

# Install
sudo apt install dos2unix    # Debian/Ubuntu
brew install dos2unix        # macOS

# Convert a single file
dos2unix deploy.sh

# Convert all shell scripts in the repo
find . -name "*.sh" -exec dos2unix {} \;

sed (tidak perlu alat tambahan)

sed -i "s/\r//" deploy.sh

tr (amannya sesuai dengan POSIX)

tr -d "\r" < deploy.sh > deploy_fixed.sh && mv deploy_fixed.sh deploy.sh

Cara Mencegahnya: Konfigurasi Git

Memperbaiki file setelah terjadi adalah responsif. Solusi yang tahan lama adalah memberi tahu Git bagaimana mengelola akhir baris agar masalah tidak pernah mencapai repositori Anda.

Pendekatan .gitattributes (disarankan)

A .gitattributes File yang disimpan ke repositori memastikan akhir baris konsisten bagi semua orang, terlepas dari pengaturan lokal mereka. Tambahkan ini ke akar repositori Anda:

# Normalize all text files to LF in the repo
* text=auto eol=lf

# Explicitly enforce LF for files that must never have CRLF
*.sh text eol=lf
*.bash text eol=lf
Makefile text eol=lf
Dockerfile text eol=lf
*.yaml text eol=lf
*.yml text eol=lf
*.json text eol=lf

# Binary files — do not touch
*.png binary
*.jpg binary
*.gif binary
*.zip binary
*.gz binary

Itu text=auto eol=lf baris ini meminta Git untuk mendeteksi file teks secara otomatis dan menyimpannya dengan LF terlepas dari sistem operasi pengguna. Baris eksplisit di bawahnya membatasi file di mana CRLF akan menyebabkan kegagalan saat dijalankan.

Setelah menambahkan atau mengubah .gitattributes, normalisasi file yang sudah ada di repositori:

git add --renormalize .
git commit -m "normalize line endings"

Pengaturan core.autocrlf (hanya lokal)

Git memiliki pengaturan global yang disebut core.autocrlf yang mengontrol konversi akhir baris saat pengecekan dan komit. Nilai yang disarankan tergantung pada sistem operasi Anda:

# Windows — convert CRLF to LF on commit, LF to CRLF on checkout
git config --global core.autocrlf true

# Linux/macOS — convert CRLF to LF on commit, no conversion on checkout
git config --global core.autocrlf input

Masalah dengan mengandalkan core.autocrlf satu-satunya: hanya berlaku pada mesin di mana pengaturan tersebut diatur. Seorang kontributor yang belum mengaturinya masih bisa mendorong file dengan CRLF. File .gitattributes dipertahankan oleh repositori itu sendiri, sehingga lebih dapat diandalkan.

Pengaturan Editor yang Harus Diperbaiki

Editor Anda adalah pertahanan pertama. Beberapa pengaturan cepat:

VS Code

Akhir baris untuk file saat ini ditampilkan di status bar (kiri bawah). Klik untuk beralih antara CRLF dan LF. Untuk menetapkan default untuk file baru, tambahkan ini ke settings.json:

{
  "files.eol": "\n"
}

Editor JetBrains (IntelliJ, WebStorm, PyCharm)

Pergi ke Pengaturan → Editor → Gaya Kode dan atur Pemisah baris ke Unix dan macOS (\n). Anda juga dapat menambahkan sebuah .editorconfig file di akar repositori:

[*]
end_of_line = lf
insert_final_newline = true

Sebagian besar editor modern menghormati .editorconfig secara alami atau melalui plugin. Menyimpannya ke repositori berarti kontributor mendapatkan default yang konsisten tanpa konfigurasi manual.

Daftar Penuh

Jika Anda memperbaiki repositori yang pernah mengalami masalah akhir baris, kerjakan ini secara berurutan:

1. Tambahkan sebuah .gitattributes file dengan * text=auto eol=lf dan aturan eksplisit untuk skrip shell, Dockerfile, dan file konfigurasi.
2. Tambahkan .editorconfig file dengan end_of_line = lf.
3. sebelum menambahkan indeks apa pun. Pastikan masalahnya terlebih dahulu. git add --renormalize . && git commit -m "normalize line endings" untuk memperbaiki file yang sudah tercatat.
4. sebelum menambahkan indeks apa pun. Pastikan masalahnya terlebih dahulu. dos2unix pada semua skrip yang akan dijalankan di Linux.
5. Himpunan core.autocrlf input secara global pada mesin Linux/macOS; true pada Windows.
6. Tambahkan langkah pemeriksaan CI — sesuatu seperti grep -rUl $'\r' *.sh — untuk menangkap regresi sebelum mencapai deploymen.

Anda mungkin juga menyukai