# Submodule Manager Tutorial Guide

This guide explains how to use the **PowerShell + JSON Submodule Manager** we set up. We’ll cover:

* What submodules are

* The JSON manifest format

* Day-to-day commands: install, restore, update, remove

* How to add new submodules

* Explanations of important Git terms and nuances

---

## 1. What Are Git Submodules?

Think of a **submodule** as another Git repository (like a library or dependency) that lives inside your main repository. Instead of copying code, you **reference it**. The main repo records *which commit* of the submodule it should use. This ensures everyone on the team is working with the **exact same version**.

Analogy: If your project is a house, a submodule is a prefabricated room you install inside. You don’t build it from scratch — you bring it in at a certain stage of completion.

### Key Git Terms

* **Commit** – A snapshot of code at a point in time.

* **Tag** – A label pointing to a specific commit, often used for version numbers like v1.2.3.

* **Branch** – A moving line of development (e.g., main).

* **Detached HEAD** – A state where Git points directly to a commit (like when you checkout a tag) rather than tracking a branch.

* **.gitmodules** – A file in your repo that records where each submodule lives and its source URL.

---

## 2. The JSON Manifest (submodules.json)

The manifest defines which submodules your project needs. Example:

```json

{

  "installRoot": "submodules",

  "modules": [

  {

  "name": "sub-module-poc",

  "repo": "https://github.com/g4-api/sub-module-poc.git",

  "tag": "v1.2.3",

  "versionConstraint": ">=1.0.0",

  "target": "submodules/sub-module-poc"

  }

  ]

}

```

### Fields

* **installRoot** – Common folder where all submodules are stored.

* **name** – Friendly name for the submodule.

* **repo** – Git URL of the submodule repository.

* **tag** – Optional. A specific version tag to pin.

* **versionConstraint** – Optional. A rule like >=1.0.0 to choose the latest matching tag.

* **target** – Path inside your repo where this submodule should be placed.

---

## 3. Commands (Day-to-Day Usage)

All commands run through the script:

```pwsh

pwsh ./tools/submodules.ps1 -Command

```

### Install

Adds all submodules listed in the JSON.

```pwsh

pwsh ./tools/submodules.ps1 -Command install -Commit

```

* Creates the submodule folders.

* Checks out the right tag/commit.

* Records them in Git.

**When to use:** Setting up a new project, or after adding new submodules to the JSON.

---

### Restore

Initializes and updates submodules to the versions already pinned in the repo.

```pwsh

pwsh ./tools/submodules.ps1 -Command restore

```

**When to use:** After cloning the main repo, to download the submodules.

---

### Update

Moves one or more submodules to a new version.

```pwsh

# Update all (respecting constraints in JSON)

pwsh ./tools/submodules.ps1 -Command update -Commit

# Update one by name to a specific tag

pwsh ./tools/submodules.ps1 -Command update -Name sub-module-poc -Tag v1.3.0 -Commit

```

**When to use:** When a new release of a submodule is published and you want to upgrade/downgrade.

---

### Remove

Cleanly deletes a submodule from the repo.

```pwsh

pwsh ./tools/submodules.ps1 -Command remove -Name sub-module-poc -Commit

```

**When to use:** When you no longer want to use a submodule.

---

## 4. Adding New Submodules

1. Edit submodules.json and add a new entry:

  ```json

  {

  "name": "cool-lib",

  "repo": "https://github.com/example/cool-lib.git",

  "tag": "v2.0.0",

  "versionConstraint": ">=2.0.0",

  "target": "submodules/cool-lib"

  }

  ```

2. Run:

  ```pwsh

  pwsh ./tools/submodules.ps1 -Command install -Commit

  ```

3. Commit the updated manifest and .gitmodules so your team can pull it.

---

## 5. Git Nuances You’ll See

* **Detached HEAD**: When checking out a tag, Git puts the submodule into this state. It’s normal and safe. It just means the submodule is at an exact commit, not following a branch.

* **Pinning**: Even if you checkout v1.2.3, the main repo actually records the commit hash behind that tag. This ensures reproducibility.

* **Constraints**: The script can look at available tags and pick the highest one that fits a rule (e.g., >=1.0.0). This mimics package managers like npm or pip.

* **Committing**: Each time you install, update, or remove, you usually add -Commit so the parent repo records the changes. Otherwise, they stay local.

* **.gitmodules File**: Git automatically updates this file when you add or remove submodules. It should be versioned.

---

## 6. Common Workflows

### New Developer Joining

```pwsh

git clone https://github.com/g4-api/main-module-poc.git

cd main-module-poc

pwsh ./tools/submodules.ps1 -Command restore

```

Now they have the same submodule versions as everyone else.

---

### Upgrading a Dependency

```pwsh

# Edit JSON if needed

pwsh ./tools/submodules.ps1 -Command update -Name sub-module-poc -Tag v1.3.0 -Commit

git push

```

The repo now pins the new version.

---

### Removing a Dependency

```pwsh

# Remove entry from JSON

pwsh ./tools/submodules.ps1 -Command remove -Name sub-module-poc -Commit

git push

```

---

## 7. Best Practices

* Always commit and push after making changes so teammates get the new state.

* Prefer tags (v1.0.0) over branches (main) for stability.

* Keep all submodules under one folder (submodules/) for consistency.

* Document new submodules in the JSON manifest, not just .gitmodules.

---

## 8. Future Enhancements

* **Lock file**: Save exact commits resolved from constraints.

* **Dry run**: Preview changes before applying.

* **CI/CD integration**: Auto-run restore in pipelines.

* **Caching**: Speed up repeated submodule fetches.

---

With this system, submodules behave like a lightweight package manager: you declare dependencies in JSON, and use simple commands to install, restore, update, or remove them.