Belajar Git - Pengenalan dan Penjelasan Git Submodules & Subtrees

#Pendahuluan

Di episode 17 kita menjelajah dan menyelamatkan riwayat dalam satu repository. Di episode 18 ini persoalannya melebar: bagaimana jika sebuah project membutuhkan kode dari repository lain — misalnya shared library yang dipakai tiga tim berbeda? Kita membahas dua cara resmi Git: Submodules dan Subtrees.

Ini masalah nyata di perusahaan: pustaka internal lib-auth, lib-design-system, atau lib-utils dipakai lintas tim, tapi setiap tim punya kode utama masing-masing. Naif jika menyalin-paste kode library ke tiap project — perbaikan bug di satu salinan tidak pernah sampai ke salinan lain. Submodule dan subtree adalah jawaban resminya.

#Kapan Butuh Dependensi Multi-Repository

Sebelum memilih alat, pastikan masalahnya benar. Multi-repository dibutuhkan ketika:

Kode dipakai banyak project dan dikelola di repositori terpisah.
Ada batas kepemilikan yang jelas: tim library punya siklus rilis sendiri.
Ukuran project utama harus tetap ringan.

Jika library hanya dipakai satu project, pertimbangkan memindahkannya langsung ke dalam project itu. Dependency manager bahasa pemrograman (npm, pip, Bun) tetap pilihan utama; submodule dan subtree dipakai untuk kasus yang tidak tertangani alat-alat itu.

#Git Submodule

Submodule adalah commit eksternal yang disematkan ke repository utama. Repository utama hanya menyimpan referensi — sebuah pointer ke commit tertentu di repository lain.

Menambahkan submodule

git submodule add https://github.com/devnull/lib-auth.git libs/auth

Perintah di atas meng-clone lib-auth ke folder libs/auth dan mencatat referensinya di file .gitmodules:

Isi file .gitmodules

[submodule "libs/auth"]
	path = libs/auth
	url = https://github.com/devnull/lib-auth.git

.gitmodules ikut di-commit ke repository utama — dan di sinilah letak kelemahan utamanya, seperti akan kita lihat nanti.

#Mengkloning Repository yang Punya Submodule

git clone biasa tidak mengisi isi submodule — folder submodule datang kosong. Solusinya:

Clone beserta submodule

git clone --recurse-submodules https://github.com/devnull/my-app.git

Untuk repository yang sudah ter-clone:

Inisialisasi submodule

git submodule update --init --recursive

Flag --recursive penting ketika submodule memiliki submodule lagi (repository bertingkat). Saat versi library naik, perbarui submodule lalu commit perubahan pointer-nya:

Memperbarui submodule ke commit terbaru

git submodule update --remote
git add libs/auth && git commit -m "chore: update lib-auth"

Untuk memeriksa status seluruh submodule, termasuk apakah ada commit yang belum di-sinkronkan dengan versi yang direkam di .gitmodules:

Memeriksa status submodule

git submodule status

Baris dengan prefix minus menandakan submodule belum di-inisialisasi, sementara baris dengan suffix tambahan menandakan working tree submodule menyimpang dari commit yang dikunci.

#Git Subtree

Subtree adalah pendekatan berlawanan: isi repository lain disalin langsung ke dalam tree repository utama, tanpa file pointer, tanpa .gitmodules:

Menambahkan subtree

git subtree add --prefix=libs/auth https://github.com/devnull/lib-auth.git main

Hasilnya folder libs/auth berisi seluruh kode library yang di-commit biasa ke repository utama. Mengambil pembaruan dari upstream:

Menarik pembaruan subtree

git subtree pull --prefix=libs/auth https://github.com/devnull/lib-auth.git main

Karena kodenya menyatu, alur kerjanya seperti file biasa: edit, commit, review lewat PR — tanpa ritual inisialisasi tambahan.

#Submodule vs Subtree

Aspek	Submodule	Subtree
Penyimpanan	Pointer ke commit eksternal	Salinan penuh di dalam tree
File `.gitmodules`	Wajib	Tidak ada
Kode langsung terbaca	Perlu update dan init dulu	Langsung ada di working tree
Update versi	`git submodule update`	`git subtree pull`
Kemudahan kolaborasi	Lebih rumit, mudah lupa init	Alur kerja git biasa
Jejak riwayat kode library	Tidak ada di repository utama	Tersimpan penuh

Tip

Aturan praktis: jika anggota tim banyak dan nilai terpentingnya adalah kemudahan kolaborasi, subtree biasanya lebih ramah — tidak ada .gitmodules, tidak ada langkah init, dan PR berjalan seperti biasa. Pilih submodule jika kalian perlu mengunci versi library secara eksplisit per environment dan menerima biaya inisialisasi.

#Kesalahan Umum

Lupa menjalankan git submodule update. Tim men-download repository, submodule kosong, dan aplikasi error. Kenali gejalanya: folder submodule tampak ada tapi isinya tidak.
Submodule masuk dengan URL yang salah. Pastikan .gitmodules ikut ter-commit dan URL tidak berisi credential.
Subtree di-update dari cabang sembarang. Selalu pin upstream ke branch yang stabil, misalnya main.
Berganti-ganti pendekatan di tengah jalan. Konsisten memakai satu pola mencegah kebingungan lintas tim.

#Penutup

Poin yang harus kalian bawa:

Submodule menyematkan pointer ke commit eksternal lewat file .gitmodules.
git clone --recurse-submodules dan git submodule update --init --recursive mengisi submodule setelah clone.
Subtree menyalin kode ke dalam tree utama tanpa file .gitmodules — alur kerjanya seperti file biasa.
Pilih subtree untuk kemudahan kolaborasi tim; submodule untuk penguncian versi yang eksplisit.
Dependency manager bahasa tetap pilihan utama; submodule dan subtree untuk kasus khusus.

Automasi di level repository sudah lengkap, tapi ada satu lapisan terakhir di sisi lokal: memastikan setiap commit berkualitas sejak dari laptop. Di episode 19 berikutnya kita membahas Git Hooks & Automasi Lokal untuk menjalankan linter, validasi pesan commit, dan unit test secara otomatis. Sampai jumpa di episode 19!