> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ahmadraza.in/llms.txt
> Use this file to discover all available pages before exploring further.

# GitSubModule

# **Git Submodules Guide**

This guide explains how to manage dependent repositories (`<submodule1>` and `<submodule2>`) inside the main `<project>` repo using **Git submodules**.

***

## **1️⃣ Clone the Main Repo**

```bash theme={null}
git clone <main-repo-url>
cd <main-repo-folder>
```

* Clones only the **main repo**. Submodules are not fetched yet.

***

## **2️⃣ Add Dependent Repos as Submodules**

```bash theme={null}
# Add first submodule repo
git submodule add <submodule1-repo-url> <submodule1-folder>

# Add second submodule repo
git submodule add <submodule2-repo-url> <submodule2-folder>
```

* This creates `.gitmodules` automatically.
* `.gitmodules` maps the submodule **folder paths** to the **repo URLs**.

**Example `.gitmodules` content:**

```ini theme={null}
[submodule "<submodule1-folder>"]
    path = <submodule1-folder>
    url = <submodule1-repo-url>

[submodule "<submodule2-folder>"]
    path = <submodule2-folder>
    url = <submodule2-repo-url>
```

***

## **3️⃣ Commit Submodules in Main Repo**

```bash theme={null}
git add .gitmodules <submodule1-folder> <submodule2-folder>
git commit -m "Added submodules <submodule1> and <submodule2>"
git push origin main
```

* This **stores the submodule references (commit pointers)** in the main repo.
* **Important:** It does **not** include the actual submodule code in the main repo.

***

## **4️⃣ Workflow for Making Changes**

### **A. Make changes in a submodule**

```bash theme={null}
# Go inside submodule folder
cd <submodule1-folder>

# Edit files
echo "update something" >> file.txt

# Stage, commit, and push changes to submodule repo
git add file.txt
git commit -m "Updated <submodule1> files"
git push origin main
```

### **B. Update the main repo pointer**

```bash theme={null}
cd ../   # go back to main repo folder

# Stage the submodule pointer change
git add <submodule1-folder>
git commit -m "Updated submodule pointer for <submodule1>"
git push origin main
```

✅ This ensures the main repo points to the latest commit in the submodule.

***

### **C. Make changes in the main repo**

* Edit files outside submodule folders as usual:

```bash theme={null}
echo "new feature" >> README.md
git add README.md
git commit -m "Updated README"
git push origin main
```

* Submodule references remain unchanged unless you explicitly update them.

***

## **5️⃣ Pulling Updates**

### **A. Pull main repo updates**

```bash theme={null}
git pull origin main
```

* Updates main repo content and submodule commit pointers (but **not submodule content**).

### **B. Pull submodule updates**

```bash theme={null}
# Update all submodules to the commits the main repo points to
git submodule update --init --recursive

# Or, update submodules to latest remote commits
git submodule update --remote --merge
```

* `--init --recursive` → fetches submodules after a fresh clone.
* `--remote --merge` → updates submodules to latest commits from their remote repos.

***

## **6️⃣ Fresh Clone with Submodules**

To clone and have submodules ready automatically:

```bash theme={null}
git clone <main-repo-url>
cd <main-repo-folder>
git submodule update --init --recursive
```

* This populates `<submodule1-folder>` and `<submodule2-folder>` folders.

***

## **7️⃣ Optional: Setup Script**

You can create a `setup.sh` for developers:

```bash theme={null}
#!/bin/bash
git submodule update --init --recursive
```

Usage:

```bash theme={null}
chmod +x setup.sh
./setup.sh
```

***

## **8️⃣ Key Notes**

1. **Submodule commits are independent** — changes inside submodules must be committed and pushed **inside the submodule repo**.
2. **Main repo only tracks submodule commit pointers**.
3. `.gitmodules` contains **mapping info**: submodule path → repo URL.
4. Fresh clones **require `git submodule update --init --recursive`** to populate submodules.
5. Use `git submodule update --remote --merge` to sync submodules with the latest remote commits.

***