Cara Membuat .gitignore Laravel yang Benar: Panduan Lengkap dan Best Practices

File .gitignore pada proyek Laravel sering kali dianggap sepele sampai masalah besar terjadi: file Kredensial .env ter-commit ke GitHub public, repositori membengkak ratusan megabyte karena folder vendor atau node_modules masuk ke version control, atau aplikasi error saat di-deploy ke server staging karena direktori penyimpanan yang dibutuhkan Laravel tidak ada.

Laravel sebenarnya sudah menyediakan file .gitignore default saat kita pertama kali membuat proyek baru via Composer atau Laravel Installer. Namun dalam skenario pengembangan nyata (real-world development), kebutuhan proyek tidak berhenti di sana. Kita sering menggunakan SQLite untuk local database, Vite/Inertia untuk build assets, Filament Admin, Docker override, hingga preferensi kode dari editor yang dipakai oleh masing-masing developer di dalam tim.

Artikel ini membahas cara membuat, mengembalikan, mengatur, hingga men-debug file .gitignore di Laravel secara terstruktur. Baik saat menangani proyek baru, memperbaiki repositori legacy, maupun menyusun workflow pengembangan yang aman dalam tim.

Langkah 1: Cara Membuat dan Mengembalikan File .gitignore Default Laravel

Saat membuat proyek Laravel baru via perintah composer create-project laravel/laravel nama-proyek atau laravel new nama-proyek, file .gitignore otomatis dibuat di root proyek. Namun, ada kalanya file ini tidak ada karena beberapa alasan:

1. File .gitignore terhapus secara tidak sengaja.
2. Proyek di-clone dari repositori lama (legacy) yang dibuat tanpa menyertakan .gitignore.
3. Proyek dibangun dari direktori kosong lalu diinisialisasi sendiri menggunakan perintah git init.

Jika file .gitignore hilang, Anda akan melihat ribuan file tak teracak di folder vendor/, node_modules/, dan file cache lokal ketika menjalankan perintah git status.

Perintah Terminal Membuat File .gitignore

Langkah pertama adalah membuat file .gitignore baru di direktori utama (root) proyek Laravel Anda.

Pada Linux, macOS, atau Git Bash:

touch .gitignore

Pada Windows PowerShell:

New-Item -Path . -Name ".gitignore" -ItemType "File"

Template Default .gitignore Laravel 12

Setelah file dibuat, salin struktur template standar Laravel 12 (versi standar terbaru) ke dalam file .gitignore tersebut:

*.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

Perbedaan Template Laravel 12 dan Laravel 11

Jika Anda memperhatikan template pada versi Laravel sebelumnya (seperti Laravel 11 atau 10), ada beberapa perbedaan kecil yang disempurnakan pada Laravel 12:

• Wildcard Log: Laravel 11 menuliskan entri log secara spesifik seperti npm-debug.log dan yarn-error.log. Laravel 12 menyederhanakannya menjadi *.log untuk menangkap semua file log, baik bawaan Laravel (storage/logs/laravel.log) maupun bawaan package manager.
• Pembersihan OS Files: File sampah bawaan sistem operasi seperti .DS_Store (macOS) dan Thumbs.db (Windows) kini sudah langsung dimasukkan ke dalam template bawaan dan diurutkan secara alfabetis.

Jika Anda perlu mengembalikan file ke kondisi asal yang paling resmi, Anda bisa menyalin isi repositori skeleton Laravel langsung dari repositori GitHub resmi laravel/laravel.

Langkah 2: Memahami Sintaks Dasar dan Aturan Pattern .gitignore

Agar tidak asal copy-paste dan kebingungan saat aturan yang dibuat tidak bekerja, Anda perlu memahami bagaimana Git membaca matching pattern pada file .gitignore. Git menggunakan pencocokan pola berdasarkan standar POSIX glob (fnmatch).

Aturan Simbol dalam .gitignore

Batasan Penting Aturan Negasi (!) pada Git

Salah satu kesalahan paling sering yang dialami developer Laravel adalah mencoba membatalkan pengabaian (unignore) file di dalam folder yang sudah di-ignore induknya.

Sifat dasar Git menyatakan: Git tidak akan memeriksa file di dalam suatu direktori jika direktori induknya (parent directory) sudah di-exclude secara penuh.

Contoh skenario yang SALAH:

# Mencoba abaikan seluruh folder storage, lalu mengecualikan satu file
/storage/*
!/storage/app/public/sample.txt   # Gagal! Git tidak akan membaca baris ini

Mengapa gagal? Karena pola /storage/* memberi tahu Git untuk mengabaikan seluruh isi storage. Ketika Git melihat direktori storage/app, Git langsung melompatinya tanpa memeriksa aturan negasi ! di dalamnya.

Cara penulisan yang BENAR jika menggunakan nested pattern:

/storage/*
!/storage/app
/storage/app/*
!/storage/app/public

Mengapa Laravel Menggunakan Nested .gitignore di Folder storage/?

Untuk menghindari kerumitan sintaks unignore bertingkat di atas, tim pengembang Laravel menggunakan teknik Nested .gitignore.

Jika Anda membuka folder storage/framework/views/, storage/framework/sessions/, storage/framework/cache/, atau storage/logs/, Anda akan menemukan file .gitignore kecil di dalam folder-folder tersebut dengan isi:

*
!.gitignore

Artinya:

1. Tanda * mengabaikan seluruh file hasil kompilasi view, session, dan log yang tercipta di dalam folder tersebut.
2. Tanda !.gitignore menjaga agar file .gitignore itu sendiri tetap ter-commit ke repositori Git.

Teknik ini sangat cerdas karena Git pada dasarnya tidak pernah melacak direktori kosong. Dengan adanya file .gitignore di dalam folder storage/logs/, Git akan tetap menyimpan struktur folder storage/logs/ di dalam repositori tanpa mengikutsertakan file log temporary-nya. Saat anggota tim lain meng-clone proyek tersebut, folder storage/logs/ sudah tersedia dan aplikasi Laravel tidak akan crash akibat folder log yang hilang.

Langkah 3: Menambahkan Custom Rules untuk Tech Stack & Tools Laravel Real-World

Template default Laravel hanya mencakup konfigurasi standar dasar. Dalam proyek skala industri atau proyek tim nyata, kita pasti menambahkan berbagai library, database, dan build tools.

Berikut adalah penyesuaian aturan kustom (custom rules) yang perlu ditambahkan ke file .gitignore proyek Anda.

1. Database Lokal SQLite

Mulai Laravel 11 dan 12, SQLite menjadi pilihan database default untuk local development. File database .sqlite beserta file jurnal temporary-nya berisi data uji coba lokal yang tidak boleh ter-push ke repositori Git.

Tambahkan aturan berikut di bagian bawah .gitignore:

# Database Lokal SQLite
/database/*.sqlite
/database/*.sqlite-journal
/database/*.sqlite-shm
/database/*.sqlite-wal

Catatan: Jika Anda ingin menyediakan file basis data awal untuk tim, buatlah file sampel bernama database/database.sqlite.example dan jalankan seeder via migration, bukan meng-commit file .sqlite utama.

2. Frontend Build Assets, Inertia.js, Vite, dan Filament Admin

Jika proyek Anda menggunakan stack modern seperti React/Vue via Inertia.js, Server-Side Rendering (SSR), atau Filament Admin Panel, ada beberapa folder hasil kompilasi (build output) yang bersifat sementara.

# Build Output Frontend & SSR (Vite / Inertia)
/public/build
/public/hot
/public/ssr-manifest.json
/bootstrap/ssr

# Asset Kompilasi Filament Admin Panel
/public/js/filament
/public/css/filament

Asset di dalam /public/build dihasilkan secara otomatis saat Anda menjalankan perintah npm run build di server CI/CD atau server deployment. Meng-commit asset kompilasi ke Git akan menimbulkan merge conflict berulang kali setiap kali ada dua developer yang merubah kode frontend.

3. File Environment Overrides dan Docker

Laravel memiliki berbagai varian environment file untuk pengujian (seperti .env.testing atau .env.dusk.local) serta konfigurasi Docker local.

# File Environment & Overrides
.env.*
!.env.example
docker-compose.override.yml

Perhatikan baris !.env.example. Penggunaan wildcard .env.* akan mencocokkan file .env.example. Karena itu, baris negasi !.env.example dipasang tepat setelahnya untuk menggaransi bahwa file template .env.example selalu ter-track di Git.

4. Upload Media Lokal dan Private OAuth Keys

Dalam pengujian lokal, file gambar atau PDF yang di-upload melalui formulir aplikasi akan masuk ke storage/app/public/. File-file ujicoba ini tidak boleh masuk ke repositori.

# File Upload Media Uji Coba Lokal
/storage/app/public/uploads/*
!/storage/app/public/uploads/.gitkeep

# Kunci Enkripsi Private (Laravel Passport / OAuth / Custom Keys)
/storage/*.key

Langkah 4: Mengatur Global .gitignore untuk File OS dan IDE Personal

Kesalahan umum yang sering dilakukan developer adalah memasukkan konfigurasi editor pribadi atau file sampah sistem operasi ke dalam .gitignore milik proyek.

Contohnya:

• Developer A menggunakan VS Code (.vscode/).
• Developer B menggunakan PhpStorm (.idea/).
• Developer C menggunakan Zed (.zed/) atau Fleet (.fleet/).
• Developer D menggunakan macOS (.DS_Store).
• Developer E menggunakan Windows (Thumbs.db, desktop.ini).

Jika semua preferensi ini dimasukkan ke .gitignore proyek, file tersebut akan penuh dengan aturan yang tidak ada hubungannya dengan logika aplikasi Laravel. Solusi paling bersih dan profesional adalah menggunakan Global .gitignore.

Global .gitignore adalah file aturan pengabaian yang berlaku untuk seluruh repositori Git yang ada di komputer Anda, tanpa harus mengedit file .gitignore di masing-masing proyek.

Cara Konfigurasi Global .gitignore di Linux / macOS

Buka terminal Anda dan jalankan perintah berikut:

1. Buat file .gitignore_global di direktori home:

   touch ~/.gitignore_global
   

2. Daftarkan file tersebut ke konfigurasi global Git:

   git config --global core.excludesfile ~/.gitignore_global
   

Cara Konfigurasi Global .gitignore di Windows

Buka Windows PowerShell dan jalankan perintah berikut:

1. Buat file .gitignore_global di direktori profil user Anda (C:\Users\NamaUser):

   New-Item -Path $env:USERPROFILE -Name ".gitignore_global" -ItemType "File"
   

2. Hubungkan ke konfigurasi Git global:

   git config --global core.excludesfile "$env:USERPROFILE\.gitignore_global"
   

Isi Rekomendasi File ~/.gitignore_global

Isi file .gitignore_global yang telah dibuat dengan aturan preferensi pribadi Anda:

# Sampah Sistem Operasi (OS Junk)
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db
desktop.ini

# Konfigurasi IDE & Text Editor
.idea/
.vscode/
*.swp
*.swo
*~
.fleet/
.zed/
.phpls_cache

# File Temporary OS
*.tmp
*.bak

Dengan langkah ini, repositori Laravel tim Anda tetap bersih, dan preferensi editor Anda tidak akan mengganggu developer lain.

Langkah 5: Memverifikasi dan Debugging Aturan .gitignore dengan git check-ignore

Pernahkah Anda menuliskan aturan baru di .gitignore, tetapi saat menjalankan git status, file tersebut masih saja muncul? Atau sebaliknya, ada file kode yang tidak muncul saat git add . karena ter-ignore secara tidak sengaja oleh aturan wildcard?

Jangan menembak-nembak atau asal menghapus aturan. Git menyediakan perintah debugging bawaan bernama git check-ignore.

Perintah Debugging File Ter-ignore

Untuk memeriksa aturan mana yang menyebabkan suatu file di-ignore oleh Git, jalankan perintah berikut di terminal proyek:

git check-ignore -v <path/ke/file>

Opsi -v (verbose) sangat penting karena memberi tahu kita secara detail lokasi file dan nomor baris aturan yang aktif.

Membaca Output Debug git check-ignore

Contoh 1: Memeriksa mengapa file log di-ignore.

git check-ignore -v storage/logs/laravel.log

Output terminal:

.gitignore:1:*.log    storage/logs/laravel.log

Penjelasan output:

• .gitignore : Aturan dipicu dari file .gitignore di root proyek.
• :1 : Aturan tersebut berada pada baris ke-1.
• *.log : Pattern yang berhasil mencocokkan file tersebut.
• storage/logs/laravel.log : Path file yang sedang diperiksa.

Contoh 2: Memeriksa file database SQLite lokal.

git check-ignore -v database/database.sqlite

Output terminal:

.gitignore:26:/database/*.sqlite    database/database.sqlite

Jika perintah git check-ignore -v <filepath> tidak menghasilkan keluaran apapun di terminal, artinya file tersebut sama sekali tidak di-ignore oleh aturan mana pun (artinya status file tersebut aktif diteliti oleh Git).

Langkah 6: Pembersihan File yang Terlanjur Ter-track (git rm --cached)

Ini adalah masalah paling krusial yang sering membuat developer pemula frustrasi:

"Saya sudah menambahkan .env ke dalam .gitignore, tapi kenapa saat saya ubah nilai .env, file itu tetap muncul di git status dan minta di-commit?"

Mengapa .gitignore Tidak Mempan pada File yang Sudah Ter-track?

File .gitignore HANYA BERLAKU untuk file yang berstatus untracked (file baru yang belum pernah di-stage atau di-commit).

Jika suatu file (misalnya .env, folder vendor/, atau file .sqlite) sudah pernah masuk ke dalam Git index atau histori commit sebelumnya, menambahkan nama file tersebut ke .gitignore TIDAK AKAN menghentikan Git dari memantau perubahan file tersebut.

Solusi: Menghapus File dari Index Tanpa Menghapus File Fisik Lokal

Untuk memberitahu Git agar berhenti melacak file tersebut tanpa menghapus file fisiknya dari komputer Anda, gunakan perintah git rm dengan opsi --cached.

1. Menghapus File Tunggal (Contoh: .env)

git rm --cached .env

2. Menghapus Direktori/Folder (Contoh: vendor/ atau node_modules/)

Gunakan flag -r (recursive) untuk folder:

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

3. Menggunakan --dry-run untuk Simulasi Aman

Jika Anda ragu file apa saja yang akan dilepas dari lacakan Git, lakukan dry-run terlebih dahulu:

git rm -r --cached --dry-run vendor/

Git akan menampilkan daftar seluruh file yang akan dilepas dari lacakan tanpa benar-benar melakukan perubahan pada index.

Langkah Lengkap Memperbaiki File yang Terlanjur Ter-track

Berikut urutan perintah lengkap untuk membersihkan dan mengamankan repositori:

# 1. Pastikan aturan sudah ditulis di .gitignore
echo ".env" >> .gitignore

# 2. Lepas file dari lacakan index Git
git rm --cached .env

# 3. Amati perubahan status (file .env kini berstatus 'deleted' dari index)
git status

# 4. Commit perubahan aturan dan pelepasan index
git add .gitignore
git commit -m "fix: stop tracking .env and update gitignore"

# 5. Push ke repositori remote
git push origin main

Peringatan Keamanan Wajib: Secret Rotation & Cleansing History

Menjalankan git rm --cached .env hanya menghapus file .env dari commit yang akan datang. File .env beserta kredensial di dalamnya MASIH TERDAFTAR di histori commit lama Git!

Jika repositori Anda di-push ke platform publik seperti GitHub atau GitLab:

1. Segera Lakukan Secret Rotation (Wajib):

   • Jalankan php artisan key:generate untuk memperbarui APP_KEY.
   • Ganti password database produksi dan staging.
   • Ganti seluruh API Key rahasia (Stripe, Midtrans, Mailgun, AWS S3, Algolia, dll) yang sempat tertulis di .env.
   • Anggap semua kunci rahasia yang pernah ter-push ke histori Git sudah bocor.

2. Hapus Permanen dari Histori Commit Git:
   Untuk menghapus file dari seluruh histori commit Git dari awal hingga akhir, gunakan tools resmi seperti git filter-repo atau BFG Repo Cleaner.

Mitos dan Kesalahan Umum Seputar .gitignore Laravel

1. Mitos: Memasukkan File ke .gitignore Otomatis Menghapusnya dari Server Production

Fakta: .gitignore hanya mengatur version control di Git. Jika Anda menggunakan sistem deployment berbasis git pull langsung di server production, menghapus file dari Git index via git rm --cached lalu melakukan git pull di server akan membuat file tersebut terhapus di server! Pastikan Anda sudah menyiapkan file .env fisik manual di server production sebelum melepaskan file dari tracking.

2. Mitos: File .env.example Harus Di-ignore Demi Keamanan

Fakta: .env.example adalah dokumentasi variabel lingkungan aplikasi yang WAJIB ter-commit. File ini tidak boleh berisi password atau API Key asli, melainkan hanya struktur kunci (seperti DB_HOST=127.0.0.1, STRIPE_KEY=). Developer baru atau sistem CI/CD membutuhkan .env.example sebagai referensi untuk membuat file .env lokal mereka sendiri.

3. Misconception: Menghapus File .gitignore Bawaan di Folder storage/

Beberapa developer baru sering membersihkan proyek dengan menghapus seluruh isi folder storage/logs/ dan storage/framework/views/ beserta file .gitignore kecil di dalamnya.

Dampaknya, ketika proyek di-clone di komputer lain atau di-deploy ke server baru, folder-folder tersebut tidak ada. Aplikasi Laravel akan langsung melempar error Fatal Exception: Uncaught Error / Permission Denied karena tidak bisa menulis log atau menyimpan file session.

Checklist Ringkas Best Practices .gitignore Laravel

Gunakan daftar periksa ini setiap kali Anda memulai proyek Laravel baru atau melakukan peninjauan (code review):

• File .gitignore utama berada di root proyek sebelum commit pertama dilakukan.
• File .env terdaftar di .gitignore, dan file .env.example TIDAK terdaftar.
• Aturan untuk database lokal (/database/*.sqlite) sudah ditambahkan.
• Asset hasil kompilasi frontend (/public/build, /bootstrap/ssr) di-ignore.
• Preferensi IDE personal (.vscode/, .idea/) diletakkan di Global .gitignore (~/.gitignore_global), bukan di .gitignore proyek.
• File .gitignore internal di dalam folder storage/logs/, storage/framework/cache/, storage/framework/sessions/, dan storage/framework/views/ tetap dipertahankan.
• Gunakan git check-ignore -v <filepath> jika ada keraguan tentang aturan matching.
• Jalankan git rm --cached <file> jika ada file sensitif yang terlanjur ter-track sebelum melakukan push.

Penutup

Mengelola .gitignore pada proyek Laravel bukan sekadar urusan merapikan daftar file di git status. Langkah ini merupakan fondasi keamanan aplikasi dan kenyamanan kolaborasi tim.

Dengan menerapkan template standar Laravel 12/11, menambahkan custom rules untuk SQLite dan Vite, mengisolasi sampah IDE ke Global .gitignore, serta menguasai perintah git check-ignore dan git rm --cached, Anda dapat memastikan repositori Laravel Anda tetap bersih, aman, dan berstandar profesional.

Referensi Resmi

1. Dokumentasi Resmi Git — gitignore Documentation
2. Repositori GitHub Resmi Laravel — .gitignore Template Standard
3. Dokumentasi Resmi Git — git-check-ignore Debugging Tools
4. GitHub Gitignore Collection — Official Laravel Template

Menguasai pembuatan dan konfigurasi secara benar adalah fondasi penting dalam menjaga repositori Laravel kamu tetap rapi, efisien, dan aman dari kebocoran data. Jika kamu ingin mendalami daftar lengkap file apa saja yang wajib di-ignore beserta alasan keamanannya, simak artikel file apa saja yang tidak boleh masuk Git di Laravel.

Untuk topik kolaborasi dan manajemen repositori Git lainnya, kamu juga bisa membaca panduan tentang menghubungkan project lokal ke GitHub, perbedaan git clone vs git fork, cara mengambil branch remote, serta cara mengganti remote repository. Jika mengalami masalah autentikasi saat push atau pull, baca artikel setup SSH key di Windows dan mengatasi error permission denied publickey.

Untuk rujukan dokumentasi resmi, kamu dapat mempelajari: Dokumentasi Resmi Git — gitignore Documentation, Repositori GitHub Resmi Laravel — .gitignore Template Standard, Dokumentasi Resmi Git — git-check-ignore Debugging Tools, dan GitHub Gitignore Collection — Official Laravel Template.