File Apa Saja yang Tidak Boleh Masuk Git di Project Laravel?

Mengelola repositori Git dalam proyek Laravel terlihat sederhana saat pertama kali menjalankan perintah git init. Namun, tanpa pemahaman yang tepat mengenai manajemen berkas, repositori proyek bisa dengan mudah menjadi sarang kebocoran data sensitif atau membengkak hingga ratusan megabyte.

Masalah ini kerap terjadi ketika developer pemula atau tim yang baru berpindah ke Laravel secara tidak sengaja meng-commit file .env ke repositori publik, atau mengikutsertakan seluruh folder vendor/ dan node_modules/ ke dalam kendali versi. Dampaknya tidak main-main: mulai dari kunci rahasia API yang dicuri bot peretas dalam hitungan menit, hingga proses git pull dan git push yang memakan waktu lama karena harus mentransfer ribuan file dependensi kecil.

Artikel ini membahas secara rinci kategori file dan direktori apa saja yang dilarang masuk ke Git pada proyek Laravel, alasan teknis dan dampaknya, file apa saja yang justru wajib di-commit (whitelist), serta langkah taktis membersihkan file rahasia yang terlanjur terdorong ke repositori remote.

Mengapa Manajemen Git Alignment Sangat Krusial di Laravel?

Laravel adalah framework PHP modern yang kaya akan fitur bawaan. Saat pertama kali dibuat melalui Artisan atau Composer, Laravel menyusun struktur folder yang memisahkan antara kode sumber utama, konfigurasi lingkungan, file runtime (seperti cache dan log), serta dependensi pihak ketiga.

Jika semua berkas di dalam struktur tersebut dimasukkan ke dalam Git tanpa filtrasi, proyek akan menghadapi tiga risiko utama:

1. Kebocoran Kredensial dan Data Sensitif (Security Risks)

Proyek Laravel menyimpan kredensial sensitif seperti kata sandi database, kunci enkripsi aplikasi (APP_KEY), token API pengiriman email, hingga secret key payment gateway di dalam berkas konfigurasi lokal. Meng-commit berkas ini ke repositori, terutama repositori publik di GitHub atau GitLab, membuka pintu akses langsung bagi pihak tidak bertanggung jawab untuk mengeksploitasi infrastruktur server.

2. Pembengkakan Ukuran Repositori (Bloated Repository)

Folder dependensi seperti vendor/ (PHP) dan node_modules/ (JavaScript) mengandung puluhan ribu file kecil dari pustaka luar. Jika folder ini dimasukkan ke Git, ukuran direktori .git akan membengkak drastis. Setiap kali ada pembaruan versi paket, Git akan mencatat perubahan pada ribuan file tersebut, membuat operasi git clone, git fetch, dan git push menjadi sangat lambat.

3. Konflik Lingkungan dan Pengaturan Editor (Environment & IDE Mismatch)

Setiap pengembang dalam tim menggunakan sistem operasi (Windows, macOS, Linux) dan text editor atau IDE (PhpStorm, VS Code) yang berbeda. Memasukkan file konfigurasi personal editor atau file sistem ke Git akan menyebabkan bentrok (merge conflict) berulang kali akibat perbedaan format baris (line ending), path SDK, atau pengaturan auto-format.

Kategori File & Folder yang Dilarang Masuk Git

Untuk menjaga repositori tetap bersih, aman, dan efisien, berikut adalah daftar kategori file dan direktori di Laravel yang wajib masuk ke dalam daftar pengabaian (.gitignore).

1. File Lingkungan & Rahasia (Environment Secrets)

File lingkungan adalah tempat menyimpan variabel konfigurasi yang bersifat spesifik untuk mesin atau server tempat aplikasi berjalan.

• .env
• .env.local
• .env.development
• .env.staging
• .env.production
• .env.backup

Alasan Teknis

File .env menyimpan variabel kunci seperti DB_PASSWORD, MAIL_PASSWORD, AWS_SECRET_ACCESS_KEY, STRIPE_SECRET, dan MIDTRANS_SERVER_KEY. File ini dibaca langsung oleh Laravel saat bootstrapping untuk mengisi fungsi helper env().

Dampak Kebocoran

Bot peretas secara kontinu melakukan scraping pada repositori publik di platform seperti GitHub. Jika kunci AWS atau kredensial database ter-commit, bot dapat langsung memanfaatkan resource cloud tersebut untuk aktivitas berbahaya seperti crypto mining atau mencuri data sensitif pengguna.

2. Direktori Dependensi (Package Dependencies)

Laravel mengandalkan Composer untuk manajemen paket PHP dan NPM/Vite untuk manajemen paket JavaScript.

• /vendor/
• /node_modules/

Alasan Teknis

Folder /vendor berisi seluruh kode sumber pustaka PHP yang diunduh oleh Composer, sedangkan /node_modules berisi paket JavaScript yang diinstal oleh NPM atau Yarn. Kedua direktori ini dirancang untuk dapat dibuat ulang (reproducible) kapan saja di mesin mana pun hanya dengan menjalankan perintah composer install dan npm install.

Selain ukurannya yang sangat besar (bisa mencapai 100 MB hingga 500 MB+), beberapa paket mengompilasi biner khusus yang terikat pada arsitektur sistem operasi tertentu. Memasukkan folder ini ke Git akan merusak portabilitas aplikasi.

3. File Log, Cache, & Runtime Framework

Saat aplikasi Laravel dijalankan, framework secara otomatis membuat file sementara untuk menangani sesi, cache, dan catatan kesalahan (log).

• storage/logs/*.log
• storage/framework/cache/*
• storage/framework/sessions/*
• storage/framework/views/*
• storage/*.key
• storage/pail/

Alasan Teknis

File di dalam direktori storage/ bertambah dan berubah secara dinamis setiap kali ada request HTTP, job queue, atau kesalahan aplikasi. File-file ini bersifat lokal untuk mesin tersebut. Sebagai contoh, file kompilasi Blade di storage/framework/views/ dihasilkan secara otomatis dari file .blade.php. Meng-commit file hasil kompilasi Blade hanya akan mengotor repositori dengan kode PHP hasil generasi otomatis yang selalu berubah.

Demikian pula dengan storage/*.key (seperti file kunci enkripsi OAuth dari Laravel Passport) yang berisi kunci privat enkripsi aplikasi dan tidak boleh dibagikan. storage/pail adalah file runtime bawaan Laravel Pail untuk streaming log pada versi Laravel terbaru.

Cara Kerja Pola Nested .gitignore pada Folder Storage

Laravel menggunakan trik khusus agar direktori storage/ tetap ter-commit di Git tetapi isi filenya di-ignore. Di dalam direktori storage/framework/views/, Laravel menempatkan file .gitignore khusus dengan isi seperti berikut:

*
!.gitignore

Sintaks wildcard * memerintahkan Git untuk mengabaikan semua file dan folder di dalam direktori tersebut. Namun, baris !.gitignore (tanda seru menyatakan negasi) memberi tahu Git untuk tetap melacak file .gitignore itu sendiri. Dengan mekanisme ini, struktur folder fisik storage/framework/views/ tetap dipertahankan saat proyek di-clone di komputer baru, tanpa mengikutsertakan file cache yang ada di dalamnya.

4. Hasil Kompilasi Asset & Storage Link

Secara default, Laravel modern menggunakan Vite untuk memproses dan mengompresi aset front-end seperti CSS dan JavaScript.

• /public/build/
• /public/hot
• /public/storage

Alasan Teknis

• /public/build/: Merupakan folder keluaran dari perintah npm run build. Berisi file CSS dan JS yang telah diminifikasi dan diberi hash nama file. Pada alur deployment modern, proses kompilasi ini dilakukan langsung di server CI/CD atau server produksi, sehingga aset hasil kompilasi tidak perlu disimpan di Git.
• /public/hot: File penanda yang dibuat oleh Vite saat developer menjalankan npm run dev. File ini memberi tahu Laravel untuk mengarahkan aset ke server Hot Module Replacement (HMR) lokal. Jika file ini ter-commit, aplikasi di server produksi akan mencoba memuat aset dari localhost:5173 yang menyebabkan tampilan aplikasi rusak.
• /public/storage: Berkas ini bukan folder sungguhan, melainkan symbolic link (symlink) yang dibuat melalui perintah php artisan storage:link. Symlink ini mengarah ke direktori storage/app/public. Karena symlink menyimpan path absolut sistem file lokal (misalnya D:\laragon\www\... atau /Users/name/...), symlink tersebut tidak akan valid jika dijalankan di komputer atau server lain.

5. Konfigurasi IDE & File Sistem Operasi

Setiap developer memiliki preferensi lingkungan pengembangan tersendiri.

• /.idea/ (JetBrains PhpStorm)
• /.vscode/ (Visual Studio Code)
• /.fleet/, /.nova/, /.zed/
• .DS_Store (macOS Finder)
• Thumbs.db (Windows Explorer)

Alasan Teknis

Folder .idea/ atau .vscode/ menyimpan konfigurasi spesifik milik pengembang, seperti workspace state, lokasi pustaka lokal, atau breakpoint debugging. Meng-commit folder ini sering memicu konflik Git karena aturan formatting atau konfigurasi extension milik satu pengembang akan menimpa pengaturan milik pengembang lain.

Sementara itu, file seperti .DS_Store dan Thumbs.db adalah file tersembunyi yang dibuat otomatis oleh sistem operasi untuk menyimpan metadata tampilan folder. File ini tidak ada hubungannya dengan kode program aplikasi.

6. Cache Pengujian & Tooling Developer

Peralatan bantu pengembangan dan analisis pengujian juga menghasilkan file sementara.

• /.phpunit.cache
• .phpunit.result.cache
• _ide_helper.php
• .phpstorm.meta.php
• /.phpactor.json
• /auth.json

Alasan Teknis

File .phpunit.result.cache digunakan oleh PHPUnit untuk mencatat tes mana yang gagal agar dapat dijalankan lebih cepat pada eksekusi berikutnya. File _ide_helper.php dibuat oleh paket barryvdh/laravel-ide-helper untuk memberikan fitur auto-complete pada IDE. File-file ini dihasilkan secara dinamis dan berbeda di setiap lingkungan.

Khusus untuk auth.json, file ini digunakan oleh Composer jika proyek mengambil paket dari repositori privat yang memerlukan otentikasi (misalnya Laravel Nova atau paket berbayar). File ini menyimpan token akses rahasia sehingga dilarang keras untuk masuk ke repositori.

Whitelist: File yang WAJIB Masuk Git

Ada kalanya pengembang terlalu berlebihan dalam meng-ignore file sehingga berkas penting yang menjadi fondasi kolaborasi proyek justru ikut terhapus dari Git. Berikut adalah berkas yang wajib dimasukkan ke dalam kendali versi:

├── .env.example
├── composer.lock
├── package-lock.json
└── .gitignore (Root & Nested)

1. .env.example

File ini adalah cetak biru (blueprint) dari file .env. .env.example berisi semua daftar nama environment variable yang dibutuhkan aplikasi, tetapi nilainya dikosongkan atau diisi dengan nilai default yang aman (misalnya DB_HOST=127.0.0.1 tanpa menyertakan password asli).

Ketika pengembang baru bergabung ke dalam tim, mereka cukup mengopi file ini menjadi .env baru:

cp .env.example .env
php artisan key:generate

2. composer.lock & package-lock.json

Masih ada anggapan keliru bahwa file .lock tidak perlu di-commit. Pada proyek aplikasi web (termasuk proyek Laravel), composer.lock dan package-lock.json hukumnya wajib masuk Git.

File composer.json hanya mencatat batasan versi paket (misal "monolog/monolog": "^3.0"). Tanpa composer.lock, setiap pengembang yang menjalankan composer install bisa saja mendapatkan sub-versi paket yang berbeda tergantung hari pembaruan paket tersebut rilis. Hal ini berpotensi memunculkan bug aneh yang hanya terjadi di komputer salah satu pengembang (works on my machine syndrome).

composer.lock mengunci versi persis (exact hash and version) dari seluruh pohon dependensi aplikasi. Ini menjamin bahwa lingkungan lokal, server staging, dan server produksi menggunakan paket yang 100% identik.

Catatan: Pengecualian hanya berlaku jika Anda sedang membuat package/library PHP terpisah yang ditujukan untuk publik, bukan sedang membangun proyek aplikasi web Laravel.

3. Berkas .gitignore (Root dan Nested)

File .gitignore di akar proyek maupun file .gitignore turunan di dalam direktori storage/ dan bootstrap/cache/ wajib di-commit agar seluruh anggota tim dan sistem CI/CD mematuhi aturan pengabaian berkas yang seragam.

Bedah Default .gitignore Laravel (Laravel 12 Standard)

Saat Anda membuat proyek Laravel baru, framework sudah menyediakan file .gitignore standar di root direktori. Berikut adalah struktur bawaan dari repositori resmi laravel/laravel:

*.log
.DS_Store
.env
.env.backup
.env.production
.phpactor.json
.phpunit.result.cache
/.fleet
/.idea
/.nova
/.phpunit.cache
/.vscode
/.zed
/auth.json
/node_modules
/public/build
/public/hot
/public/storage
/storage/*.key
/storage/pail
/vendor
Homestead.json
Homestead.yaml
Thumbs.db

Memahami Sintaks Pola Gitignore

Memahami aturan pencocokan sintaks Git akan membantu saat Anda perlu membuat penyesuaian khusus:

1. Aturan Wildcard (*):
   Aturan *.log berarti semua berkas dengan ekstensi .log di folder mana pun akan diabaikan oleh Git.

2. Aturan Root Anchor (/):
   Garis miring di depan seperti /vendor atau /public/build menyatakan bahwa aturan hanya berlaku untuk folder vendor yang berada tepat di akar (root) proyek. Ini mencegah terabaikannya folder bernama vendor jika berada di dalam sub-direktori lain yang tidak disengaja.

3. Aturan Direktori Khusus:
   Penyebutan nama direktori seperti /.idea akan mengabaikan seluruh folder .idea beserta seluruh sub-folder dan file di dalamnya.

Cara Membersihkan File Sensitif yang Terlanjur Ter-commit

Kasus yang sering terjadi pada proyek real-world: seorang developer lupa mengecek .gitignore, lalu melakukan perintah git add . dan git commit, sehingga file .env atau folder vendor/ ikut masuk ke dalam riwayat commit.

Menambahkan .env ke .gitignore setelah file tersebut ter-commit tidak akan menyembunyikan file tersebut secara otomatis. Git akan terus melacak file yang sudah masuk ke dalam staging index.

Berikut adalah panduan taktis untuk mengatasinya tanpa mengacaukan file fisik di komputer lokal Anda:

Langkah 1: Hapus dari Staging Index Git (git rm --cached)

Gunakan opsi --cached agar Git menghapus file dari pelacakan repositori tanpa menghapus berkas fisiknya dari harddisk lokal.

Untuk menghapus file tunggal (.env):

git rm --cached .env

Untuk menghapus direktori beserta seluruh isinya (folder vendor/ atau node_modules/):

git rm -r --cached vendor/
git rm -r --cached node_modules/

Langkah 2: Verifikasi dan Perbarui .gitignore

Pastikan baris .env atau /vendor sudah terdaftar di dalam berkas .gitignore.

Langkah 3: Commit dan Push Perubahan

Jalankan commit untuk mencatat penghapusan pelacakan tersebut, lalu dorong ke repositori remote:

git commit -m "fix: remove sensitive .env and vendor from git tracking"
git push origin main

Peringatan Keamanan Wajib: Secret Rotation & Git History

Memerintahkan git rm --cached dan melakukan push baru hanya menghapus file dari commit terbaru. File .env dan kredensial rahasia tersebut masih ada di dalam riwayat commit lama (Git history).

Siapa pun yang melakukan git log atau mengeksplorasi commit terdahulu di GitHub masih bisa melihat password database dan API key Anda.

Prosedur Tindakan Keamanan:

1. Rotate Semua Credential (WAJIB):
   Asumsikan semua kredensial di dalam file .env yang pernah ter-push ke remote sudah bocor dan dikompromikan. Segera lakukan pembaruan:

   • Ubah kata sandi database.
   • Buat ulang kunci aplikasi (php artisan key:generate).
   • Regenerate semua API secret key (Stripe, AWS, Midtrans, Mailgun, dll).

2. Pembersihan Permanen Riwayat Git:
   Jika repositori bersifat publik dan Anda wajib menghapus jejak rahasia dari seluruh riwayat komit, gunakan alat khusus seperti BFG Repo-Cleaner atau perintah resmi git filter-repo.

   Contoh perintah menggunakan git filter-repo:

   git filter-repo --invert-paths --path .env
   

   Setelah riwayat dibersihkan, Anda harus melakukan force push ke remote:

   git push origin --force --all
   

   Perhatian: Lakukan force push dengan hati-hati dan koordinasikan dengan seluruh anggota tim, karena langkah ini akan mengeset ulang riwayat cabang bagi pengembang lain.

Common Misconceptions & Troubleshooting

Berikut adalah beberapa salah kaprah yang sering ditemui di komunitas developer Laravel:

1. "Composer lock tidak boleh di-commit karena sering bikin merge conflict."

Penjelasan:
Konflik pada composer.lock memang bisa terjadi ketika dua developer menginstal paket baru secara bersamaan di cabang (branch) terpisah. Solusinya bukanlah meng-ignore file tersebut, melainkan menyelesaikan konflik dengan menjalankan composer update atau meng-copy bagian lockfile yang relevan. Meng-ignore composer.lock pada proyek aplikasi web justru merusak kepastian versi dependensi saat aplikasi di-deploy ke server produksi.

2. "Saya sudah tambah .env ke .gitignore, tapi kok pas git status filenya masih kelihatan?"

Penjelasan:
Hal ini terjadi karena file .env sudah pernah ter-commit sebelumnya. Aturan di .gitignore hanya berlaku untuk file yang belum pernah dilacak (untracked files). Anda harus menjalankan git rm --cached .env terlebih dahulu agar Git berhenti melacak file tersebut.

3. "Saya menghapus semua file .gitignore di dalam folder storage/ supaya proyek terlihat bersih."

Penjelasan:
Tindakan ini akan membuat Git berhenti melacak direktori kosong seperti storage/framework/views/ atau storage/logs/. Ketika proyek di-clone oleh developer lain atau di-deploy ke server baru, folder-folder tersebut tidak akan terbentuk. Akibatnya, Laravel akan mengembalikan kesalahan Fatal Error karena tidak menemukan direktori untuk menulis log atau file cache.

Best Practices Checklist untuk Repositori Laravel

Gunakan daftar periksa berikut sebelum Anda melakukan push awal pada proyek Laravel baru:

• Periksa .gitignore awal: Pastikan berkas .gitignore sudah ada di root proyek sebelum mengeksekusi git add ..
• Verifikasi status .env: Jalankan git status dan pastikan file .env tidak tercantum dalam daftar Changes to be committed.
• Sediakan .env.example: Pastikan .env.example ter-commit dan hanya berisi variabel kunci dengan nilai dummy atau instruksi yang aman.
• Commit Lockfiles: Pastikan composer.lock dan package-lock.json ikut ter-commit ke dalam repositori.
• Hindari meng-commit aset build lokal: Biarkan /public/build di-ignore jika proses deployment memanfaatkan CI/CD untuk kompilasi otomatis.
• Cek file IDE: Pastikan direktori .idea/ atau .vscode/ tidak ikut ter-stage.
• Segera tanggapi kebocoran: Jika tidak sengaja meng-commit rahasia, lakukan git rm --cached dan segera ganti (rotate) semua token dan password terkait.

Penutup

Mengelola file yang tidak boleh masuk Git di proyek Laravel bukan sekadar masalah merapikan repositori, melainkan langkah fundamental dalam menjaga keamanan aplikasi dan kelancaran kolaborasi tim.

Dengan memahami peran file sensitif seperti .env, alasan pengabaian folder besar seperti vendor/ dan node_modules/, serta pentingnya mempertahankan file pembangun seperti composer.lock dan .env.example, Anda dapat membangun alur kerja pengembangan yang profesional, aman, dan mudah dipelihara.

Menjaga file sensitif dan buangan build keluar dari Git adalah standar keamanan wajib bagi setiap pengembang Laravel. Jika kamu ingin mendalami topik manajemen repositori dan kolaborasi Git lainnya, simak juga artikel terkait mengenai menghubungkan project lokal ke GitHub, perbedaan git clone vs git fork, cara mengambil branch remote, serta cara mengganti remote repository. Jika mengalami kendala autentikasi saat melakukan push atau pull, kamu bisa membaca panduan setup SSH key di Windows dan mengatasi error permission denied publickey.

Untuk rujukan dokumentasi resmi dan acuan keamanan, kamu dapat mempelajari: Laravel Documentation - Configuration, Laravel Documentation - Deployment, Official Laravel Repository .gitignore, GitHub Security Best Practices - Removing Sensitive Data, dan OWASP Secrets Management Cheat Sheet.