Membaca Pesan Errornya

Ketika kamu menjalankan perintah git pull, git merge, atau git checkout ke branch lain, Git terkadang menolak operasi tersebut dan menampilkan pesan error yang cukup panjang. Pesan error asli (verbatim) yang muncul di terminal kurang lebih seperti ini:

error: The following untracked working tree files would be overwritten by merge:
    config/local.env
    src/generated/types.ts
Please move or remove them before you merge.
Aborting

Dalam bahasa Indonesia sederhana, pesan ini berarti: "Ada file yang belum dilacak oleh Git (untracked) di folder kerjamu, dan file-file tersebut akan ditimpa jika operasi merge ini dilanjutkan. Git membatalkan proses agar file kamu tidak hilang."

Kenapa error ini muncul? Intinya, Git sangat dirancang untuk melindungi data yang belum kamu simpan. Ketika kamu ingin menggabungkan (merge) branch lain ke branch saat ini, branch sumber bisa saja membawa file yang namanya sama persis dengan file untracked di working directory kamu. Karena file lokalmu belum pernah di-git add atau di-commit, Git tidak punya cara untuk mengembalikannya jika ditimpa. Sebagai langkah pencegahan, Git memilih untuk menghentikan operasi dan memintamu menyelesaikan konflik ini secara manual.

Contoh skenario yang paling umum: kamu membuat file konfigurasi lokal seperti config/local.env untuk keperluan development di mesinmu, tetapi tidak sengaja lupa menambahkannya ke .gitignore. Suatu hari, rekan kerjamu menambahkan file config/local.env ke repository dan kamu melakukan git pull. Git melihat file config/local.env di mesinmu yang belum dilacak, dan juga versi dari remote yang akan masuk — operasi dihentikan.

# Skenario yang memicu error
git checkout feature/login
# Error muncul karena branch feature/login punya file
# yang sama dengan file untracked di branch saat ini

Penyebab yang Paling Sering

Ada beberapa akar masalah yang bisa memicu error ini. Berikut adalah lima penyebab paling umum, diurutkan dari yang paling sering ditemui:

  1. File konfigurasi lokal yang lupa dimasukkan ke .gitignore. Ini adalah penyebab nomor satu. Banyak developer membuat file .env, config.local.js, atau sejenisnya untuk keperluan development lokal. Ketika file ini tidak di-gitignore, dan seseorang di tim mempush file dengan nama yang sama, error ini muncul saat kamu pull.

  2. File generated (otomatis) yang dihasilkan oleh tool build atau compiler. File seperti dist/, build/, *.pyc, atau src/generated/types.ts sering kali muncul karena proses build lokal. Jika folder output ini tidak di-gitignore dan branch target memilikinya, konflik terjadi.

  3. Melakukan git checkout ke branch yang memiliki file untracked dengan nama sama. Misalnya, kamu berada di branch main dengan file notes.md yang belum di-commit, lalu checkout ke branch feature yang sudah punya notes.md yang terlacak.

  4. Restore atau reset yang menyebabkan file yang sudah di-commit menjadi untracked. Misalnya, kamu melakukan git rm --cached pada sebuah file tapi belum commit, lalu mencoba merge. File tersebut sekarang untracked dan bisa bentrok dengan versi dari branch lain.

  5. Konflik akibat rebase atau cherry-pick. Selama proses rebase, Git perlu menerapkan commit satu per satu, dan jika di tengah jalan ada file untracked yang konflik dengan commit yang sedang di-apply, proses dihentikan.

Cara memastikan penyebab mana yang kamu alami:

Jalankan perintah berikut untuk melihat file-file untracked yang bermasalah:

git status

Perhatikan bagian "Untracked files" di output. File yang disebutkan di pesan error akan muncul di sana. Setelah itu, cek apakah file tersebut seharusnya masuk .gitignore:

git check-ignore -v nama_file

Jika perintah ini tidak menghasilkan output, berarti file tersebut tidak di-cover oleh .gitignore — inilah penyebab utamanya. Jika menghasilkan output yang menunjukkan rule .gitignore, berarti penyebabnya kemungkinan skenario nomor 3 atau 4.

Solusi Bertahap

Berikut adalah solusi yang bisa kamu terapkan, mulai dari yang paling langsung hingga yang menyelesaikan akar masalahnya.

Langkah 1: Identifikasi file yang bermasalah

Pertama, pastikan kamu tahu persis file mana yang menyebabkan konflik. Pesan error sudah menyebutkannya, tapi kamu juga bisa memverifikasi:

git status --short

Output yang diharapkan:

?? config/local.env
?? src/generated/types.ts

Tanda ?? menandakan file untracked.

Langkah 2A: Jika file lokal bisa dihapus (solusi langsung)

Jika file tersebut tidak penting atau bisa dibuat ulang (misalnya file generated), hapus saja:

# Hapus satu file
rm config/local.env

# Atau hapus semua file untracked sekaligus (hati-hati!)
git clean -f

Setelah itu, ulangi operasi merge:

git merge feature/login

Output yang diharapkan:

Merge made by the 'ort' strategy.
 config/local.env | 12 ++++++++++++
 1 file changed, 12 insertions(+)
 create mode 100644 config/local.env

Langkah 2B: Jika file lokal penting dan ingin disimpan (solusi langsung)

Jika file tersebut berisi konfigurasi yang kamu butuhkan, pindahkan dulu sebelum merge:

# Pindahkan file ke lokasi sementara
mv config/local.env /tmp/local.env.bak

# Lakukan merge
git merge feature/login

# Setelah merge selesai, salin kembali jika diperlukan
cp /tmp/local.env.bak config/local.env

Langkah 2C: Stash sebagai alternatif (solusi langsung)

git stash secara default hanya menyimpan file yang tracked. Untuk menyertakan file untracked, gunakan flag -u:

git stash -u

Output yang diharapkan:

Saved working directory and index state On main: stash untracked files

Setelah stash berhasil, lakukan merge:

git merge feature/login

Kemudian kembalikan stash:

git stash pop

Perhatikan: jika file yang sama ada di kedua versi, git stash pop bisa memicu konflik. Dalam kasus itu, kamu perlu resolve secara manual.

Langkah 3: Verifikasi solusi berhasil

Setelah menjalankan solusi di atas, verifikasi dengan:

git status

Pastikan tidak ada lagi file untracked yang bermasalah, dan branch sudah berhasil di-merge:

git log --oneline -3

Output yang diharapkan menunjukkan commit merge sebagai commit terbaru.

Root Cause + Fix Permanen

Solusi di atas adalah penyelesaian situasional. Agar error ini tidak muncul lagi, kamu harus menyelesaikan akar masalahnya: pastikan file yang tidak seharusnya masuk repository terdaftar di .gitignore.

# Tambahkan file ke .gitignore
echo "config/local.env" >> .gitignore
echo "src/generated/" >> .gitignore

# Commit perubahan .gitignore
git add .gitignore
git commit -m "chore: add local config and generated files to .gitignore"

Solusi Jangka Panjang

Solusi di atas menyelesaikan masalah saat ini, tetapi untuk benar-benar mencegah error ini kembali, kamu perlu melakukan beberapa konfigurasi dan mengadopsi best practice tertentu.

1. Konfigurasi .gitignore yang tepat

Pastikan .gitignore di root project mencakup semua file yang seharusnya tidak masuk repository. Template umum untuk project Node.js misalnya:

# Environment variables
.env
.env.local
.env.*.local
config/local.*

# Build output
dist/
build/
*.tsbuildinfo

# Generated files
src/generated/
*.pyc
__pycache__/

# OS-specific files
.DS_Store
Thumbs.db

Jika file tersebut sudah pernah terlanjur di-commit sebelumnya, kamu harus menghapusnya dari tracking:

git rm --cached config/local.env
git rm -r --cached src/generated/
git commit -m "chore: stop tracking local and generated files"

Flag --cached memastikan file hanya dihapus dari index Git, bukan dari disk. File akan tetap ada di mesinmu, tapi sekarang Git mengabaikannya.

2. Gunakan .gitignore global untuk file personal

Selain .gitignore per project, Git mendukung .gitignore global yang berlaku untuk semua repository di mesinmu. Ini sangat berguna untuk file editor atau OS:

# Buat file gitignore global
touch ~/.gitignore_global

# Tambahkan aturan
echo ".DS_Store" >> ~/.gitignore_global
echo ".idea/" >> ~/.gitignore_global
echo "*.swp" >> ~/.gitignore_global

# Konfigurasikan Git untuk menggunakan file global tersebut
git config --global core.excludesfile ~/.gitignore_global

3. Best practice: Komunikasi tim tentang file konfigurasi

Sering kali masalah ini muncul karena anggota tim yang berbeda menambahkan file konfigurasi dengan nama yang sama ke repository. Best practice-nya:

  • Gunakan file contoh (template) alih-alih file konfigurasi asli. Misalnya, sediakan config/env.example yang berisi struktur variabel tanpa nilai asli, dan tambahkan config/.env ke .gitignore.
  • Dokumentasikan file-file yang harus dibuat secara lokal di README atau wiki tim.
  • Gunakan tool seperti dotenv atau direnv yang memungkinkan setiap developer memiliki konfigurasi lokal tanpa harus meng-commit file ke repository.

4. Perbedaan antar OS

Ada beberapa perbedaan penting antar sistem operasi yang perlu diperhatikan:

  • macOS: File .DS_Store yang dibuat secara otomatis oleh Finder sering menjadi sumber masalah. Selalu tambahkan ke .gitignore global seperti yang ditunjukkan di atas.
  • Windows: File Thumbs.db dan desktop.ini adalah equivalennya. Perhatikan juga bahwa filesystem Windows case-insensitive, sehingga Config.env dan config.env dianggap sama — ini bisa menyebabkan masalah saat merge dari branch yang dibuat di sistem case-sensitive (Linux/macOS).
  • Linux: Cenderung tidak menghasilkan file sistem tersembunyi, tetapi file-file editor (seperti .swp dari Vim) bisa muncul dan memicu masalah.
# Di Windows, jika menghapus file yang terkunci:
del /f config\local.env

# Di macOS/Linux:
rm -f config/local.env

5. Konfigurasi Git tambahan untuk pencegahan

Git menyediakan beberapa konfigurasi yang bisa membantu:

# Aktifkan case-sensitive di filesystem (penting di Windows/macOS)
git config --global core.ignoreCase false

# Periksa apakah ada file yang akan ditimpa sebelum checkout
# (Git sudah melakukan ini secara default, tapi pastikan tidak di-disable)
git config --global advice.detachedHead true

Kalau Masih Belum Berhasil

Jika solusi di atas tidak berhasil

Ada situasi di mana solusi dasar tidak cukup. Berikut beberapa kasus dan penyelesaiannya:

Kasus 1: git clean -f tidak menghapus file. Beberapa file mungkin dilindungi oleh konfigurasi. Gunakan opsi yang lebih agresif:

# Hapus juga file yang di-ignore
git clean -f -d -x

# Atau interaktif (lebih aman, karena kamu bisa pilih file mana yang dihapus)
git clean -i -d

Output interaktif akan meminta konfirmasi file mana yang ingin dihapus satu per satu.

Kasus 2: git stash -u gagal karena submodules. Jika project kamu menggunakan submodules