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

# Submodules

> Manage nested repositories within your project

Submodules let you include other repositories inside your project while keeping them separate.

## Overview

Use submodules when you need to:

* Include a library as a subdirectory
* Share code between projects
* Pin external dependencies to specific versions
* Keep separate repositories for components

## Commands

### Add Submodule

```bash theme={null}
wit submodule add <url> <path>
```

**Example:**

```bash theme={null}
wit submodule add https://github.com/lib/utils.git vendor/utils
```

This:

1. Clones the repository to `vendor/utils`
2. Records the submodule in `.witmodules`
3. Stages the changes

### Initialize Submodules

After cloning a repo with submodules:

```bash theme={null}
wit submodule init
```

This registers submodules from `.witmodules`.

### Update Submodules

```bash theme={null}
wit submodule update
```

Fetch and checkout the recorded commits for all submodules.

**Combined initialize and update:**

```bash theme={null}
wit submodule init
wit submodule update

# Or in one command
wit submodule update --init
```

### Status

```bash theme={null}
wit submodule status
```

Output:

```
 a1b2c3d vendor/utils (v1.2.3)
 e5f6g7h vendor/logger (heads/main)
+i9j0k1l vendor/config (modified)
```

| Prefix | Meaning                        |
| ------ | ------------------------------ |
| (none) | Checked out at recorded commit |
| `+`    | Different commit than recorded |
| `-`    | Not initialized                |
| `U`    | Has merge conflicts            |

### Run Command in Submodules

```bash theme={null}
wit submodule foreach <command>
```

**Examples:**

```bash theme={null}
# Install dependencies in all submodules
wit submodule foreach "npm install"

# Pull latest in all submodules
wit submodule foreach "wit pull"

# Check status
wit submodule foreach "wit status"
```

## Configuration File

Submodules are recorded in `.witmodules`:

```ini theme={null}
[submodule "vendor/utils"]
    path = vendor/utils
    url = https://github.com/lib/utils.git
    branch = main

[submodule "vendor/logger"]
    path = vendor/logger
    url = https://github.com/lib/logger.git
```

## Workflow

### Adding a Submodule

```bash theme={null}
# Add the submodule
wit submodule add https://github.com/org/lib.git libs/mylib

# Commit the addition
wit commit -m "Add mylib submodule"
```

### Cloning a Repo with Submodules

```bash theme={null}
# Clone the main repo
wit clone https://github.com/org/project.git

# Initialize and update submodules
cd project
wit submodule init
wit submodule update
```

### Updating a Submodule

```bash theme={null}
# Enter the submodule
cd vendor/utils

# Pull latest changes
wit pull

# Go back to main repo
cd ../..

# Commit the update
wit add vendor/utils
wit commit -m "Update utils submodule"
```

### Removing a Submodule

```bash theme={null}
# Remove from index and config
wit submodule deinit vendor/utils
wit rm vendor/utils

# Commit the removal
wit commit -m "Remove utils submodule"
```

## Directory Structure

```
my-project/
├── .wit/
├── .witmodules          # Submodule configuration
├── src/
├── vendor/
│   ├── utils/             # Submodule (its own .wit)
│   │   ├── .wit/
│   │   └── src/
│   └── logger/            # Another submodule
│       ├── .wit/
│       └── src/
└── package.json
```

## Use Cases

### Shared Libraries

```bash theme={null}
# Add your shared library
wit submodule add git@github.com:company/shared-ui.git packages/shared-ui

# Use in your code
import { Button } from './packages/shared-ui';
```

### Pinned Dependencies

```bash theme={null}
# Add at specific version
wit submodule add https://github.com/lib/framework.git vendor/framework
cd vendor/framework
wit checkout v2.1.0
cd ../..
wit commit -m "Pin framework to v2.1.0"
```

### Multi-repo Project

```
project/
├── frontend/     # submodule: git@company:frontend.git
├── backend/      # submodule: git@company:backend.git
├── shared/       # submodule: git@company:shared.git
└── deploy/       # main repo scripts
```

## Best Practices

<Tip>
  **Always commit submodule updates**

  When you update a submodule, commit the change to the parent:

  ```bash theme={null}
  wit add vendor/lib
  wit commit -m "Update lib to v2.0"
  ```
</Tip>

<Tip>
  **Use branches for tracking**

  In `.witmodules`, specify a branch:

  ```ini theme={null}
  [submodule "vendor/lib"]
      branch = main
  ```
</Tip>

<Warning>
  **Be careful with submodule changes**

  Changes inside a submodule must be committed there first, then recorded in the parent.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Submodule is empty">
    Run init and update:

    ```bash theme={null}
    wit submodule init
    wit submodule update
    ```
  </Accordion>

  <Accordion title="Submodule has modifications">
    Either commit them in the submodule:

    ```bash theme={null}
    cd vendor/lib
    wit commit -am "Fix bug"
    ```

    Or discard:

    ```bash theme={null}
    cd vendor/lib
    wit restore .
    ```
  </Accordion>

  <Accordion title="Can't push submodule changes">
    Ensure you have push access to the submodule's repository, then push from within the submodule:

    ```bash theme={null}
    cd vendor/lib
    wit push
    ```
  </Accordion>
</AccordionGroup>