Git Submodule — Cara Pakai dan Konsep Dasar

Dasar Git Submodule

Menambahkan submodule

Untuk menambahkan Git submodule, gunakan perintah:

git submodule add <url> <path>

Perintah ini akan meng-clone repository lain ke dalam proyek sebagai subdirektori, tetapi tetap mempertahankan history-nya (repository tersebut) secara terpisah.

Keterangan:

<url> adalah repository yang ingin ditambahkan
<path> adalah lokasi folder di proyek (opsional, default mengikuti nama repo)
-b <branch> untuk langsung track branch tertentu (opsional)

Contoh penggunaan:

# Minimal harus menyebutkan URL-nya repo submodule
git submodule add https://github.com/user/repo.git

# Kalau path disebutkan, akan menggunakan path tersebut (libs/my-library)
git submodule add https://github.com/user/repo.git libs/my-library

# Bisa langsung track branch tertentu (opsional)
git submodule add -b main https://github.com/user/repo.git libs/my-library

Apa yang terjadi?

Setelah menjalankan perintah tersebut:

Git meng-clone repositori submodule ke folder path (atau default-nya: mengikuti nama repositori)
Git membuat file .gitmodules (kalau sebelumnya belum ada; kalau sudah ada, maka akan diupdate)

Note

Secara internal, di dalam direktori .git/modules di repo utamanya, Git juga membuat direktori <nama_submodule_atau_defaultnya_mengikuti_path>
untuk struktur internal git repo submodule-nya.

Lokasi direktori tersebut tertuliskan di file bernama .git di dalam folder repo submodule.

Kalau kita jalankan:

git status

di repo utamanya, akan terlihat changes:

file .gitmodules
folder submodule (sebagai gitlink, bukan folder biasa)

Simpan perubahan:

git add .gitmodules <path>
git commit -m "Add submodule"
git push

Catatan penting:

Repo utama tidak menyimpan isi submodule, hanya menyimpan referensi ke commit SHA tertentu
File .gitmodules berisi mapping antara URL dan path, dan harus ikut di-commit

Clone repo yang ada submodule-nya

Untuk pengguna lain (atau setelah clone ulang repo yang sudah ada submodule-nya):

git clone --recurse-submodules <url>

atau jika repo sudah ada:

git submodule update --init --recursive

Penjelasan:

--init menginisialisasi submodule
--recursive untuk submodule bersarang (nested)

Masalah umum

Beberapa masalah yang umum terjadi ketika menggunakan submodule:

Detached HEAD: submodule biasanya berada di commit tertentu (dalam detached head), bukan branch. Jika ingin mengedit:

cd <submodule>
git checkout <branch>

Folder sudah ada: git submodule add akan gagal jika path sudah berisi file
Submodule tidak otomatis update saat git pull, perlu:

git submodule update --recursive

Hal yang sering membingungkan (terkait nama submodule)

Submodule punya "name" dan "path"

Di .gitmodules:

[submodule "libs/my-library"]
    path = libs/my-library
    url = ...

path → lokasi folder kerja
name → identifier internal (yang ada di dalam tanda "")

Secara default:

name = path

`name` menentukan struktur internal Git

Git menyimpan struktur internal submodule git di:

.git/modules/<name>

Jadi:

path ≠ struktur internal Git
name = yang menentukan isi .git/modules/

Memisahkan `name` dan `path` (advanced)

Gunakan:

git submodule add --name <name> <url> <path>

Contoh:

git submodule add --name belajar-dev \
  https://github.com/SmartechStudios/BelajarDev.git \
  mikhsan/Vaults/BelajarDev

Hasil:

folder kerja:
```
mikhsan/Vaults/BelajarDev
```
internal Git:
```
.git/modules/belajar-dev
```

Ini berguna kalau:

path panjang / nested
ingin naming internal yang lebih rapi

Perintah Git menggunakan `path`, bukan `name`

Contoh:

git submodule update --init mikhsan/Vaults/BelajarDev

Bukan:

git submodule update --init belajar-dev

Jangan ubah `name` sembarangan

Jika kamu mengubah:

[submodule "old-name"]

menjadi:

[submodule "new-name"]

Maka:

.git/modules/old-name tidak otomatis berubah
bisa menyebabkan error

Jika terpaksa:

harus rename manual di .git/modules/
update .gitmodules dan .git/config
lalu jalankan:

git submodule sync