# How the source: git-subdir Shape Works for Claude Plugin Entries

> Discover how git-subdir shapes enable multiple Claude plugin entries in one repository. Learn to use subdir and sha for precise path and version control.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-09-11

---

**The `source: git-subdir` shape allows multiple plugins to coexist in a single repository by declaring that a plugin's code resides in a specific subdirectory, using the `subdir` field to specify the path and a `sha` for version pinning.**

The `anthropics/claude-plugins-community` repository uses a centralized manifest system to manage plugin distribution without requiring separate repositories for each component. When a plugin entry specifies **`source: git-subdir`**, it indicates that the plugin code lives within a subdirectory of the same repository rather than an external standalone repo. This shape enables maintainers to host multiple plugins in a monorepo structure while preserving isolated versioning and entry points for each component.

## Understanding the git-subdir Shape in marketplace.json

### The Central Manifest File

Each plugin is described in the **[`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)** manifest located at the repository root. This file contains an array of plugin objects where the **`source`** field determines how the plugin loader locates the code.

When **`source`** is set to **`git-subdir`**, the entry signals that the plugin files exist in a subdirectory of the current repository. The loader then interprets additional properties—specifically **`subdir`** (or **`path`**) and **`sha`**—to locate and version the plugin code.

Real-world examples appear throughout the manifest:

- Line 57: `source: "git-subdir"` pointing to a financial plugin
- Line 79: `source: "git-subdir"` for a data analysis tool
- Line 91: `source: "git-subdir"` referencing a utility plugin

### Required Fields for git-subdir Entries

A valid `git-subdir` entry requires specific fields that tell the loader exactly where to find and how to execute the plugin:

| Field | Description |
|-------|-------------|
| **`source`** | Must be the exact string `"git-subdir"` to trigger subdirectory resolution. |
| **`subdir`** | Relative path from repository root to the plugin directory (e.g., `tres-finance-plugin`). |
| **`entrypoint`** | The script or executable invoked when the plugin runs (e.g., [`main.py`](https://github.com/anthropics/claude-plugins-community/blob/main/main.py) or [`run.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/run.sh)). |
| **`sha`** | The commit SHA for reproducibility; the loader checks out this specific version. |
| **`manifest`** | Optional path to a plugin-specific [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) containing metadata. |

## How the Plugin Loader Resolves git-subdir Entries

### Path Resolution and Execution

When a Claude client requests a plugin, the platform reads the manifest entry and resolves the `subdir` path to the appropriate directory. The loader constructs the execution context by combining the `subdir` value with the `entrypoint` script.

The resolution process works as follows:

1. Parse [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) to extract the plugin object
2. Verify `source` equals `"git-subdir"`
3. Read the `subdir` value to locate the directory (e.g., `tres-finance-plugin`)
4. Check out the specific `sha` for reproducible builds
5. Execute the `entrypoint` relative to the subdirectory path

A simplified Bash implementation of this resolution logic:

```bash

# Extract the plugin entry from the manifest

ENTRY=$(jq -r '.plugins[] | select(.name=="tres-finance-plugin")' .claude-plugin/marketplace.json)

# Parse resolution fields

DIR=$(echo "$ENTRY" | jq -r .subdir)        # -> "tres-finance-plugin"

SHA=$(echo "$ENTRY" | jq -r .sha)           # -> "a1b2c3d4e5f6g7h8i9j0"

ENTRYPOINT=$(echo "$ENTRY" | jq -r .entrypoint)

# The loader checks out the given SHA and runs the entrypoint relative to $DIR

cd "$DIR" && exec "./$ENTRYPOINT"

```

### Version Pinning with SHA

Unlike external repositories that might track HEAD or tags, `git-subdir` entries rely on the **`sha`** field for deterministic versioning. This ensures that even as the main repository evolves, the plugin loader always checks out the exact commit specified in the manifest, providing reproducible builds and cached execution states.

## Validation and CI/CD Checks

The repository includes automated validation scripts in `.github/actions/validate-plugins` that verify `git-subdir` entries before merging.

### Change Detection

The script [`.github/actions/validate-plugins/scripts/00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/00-detect-changes.sh) scans the manifest for entries where **`source`** equals **`git-subdir`**. It identifies which subdirectories contain modified code and triggers targeted validation for those specific plugins rather than checking the entire repository.

### Manifest Validation

The script [`.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh) performs integrity checks on each `git-subdir` entry:

- Verifies the `subdir` path exists in the repository
- Confirms the subdirectory contains a valid [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)
- Validates that the `entrypoint` file exists at the specified path
- Checks that the `sha` references a valid commit in the repository history

These checks ensure that every `git-subdir` entry points to a functional, properly structured plugin before the changes reach the main branch.

## Complete Configuration Example

The following JSON fragment from [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) demonstrates a fully configured `git-subdir` entry:

```json
{
  "name": "tres-finance-plugin",
  "source": "git-subdir",
  "subdir": "tres-finance-plugin",
  "entrypoint": "run.sh",
  "sha": "a1b2c3d4e5f6g7h8i9j0",
  "manifest": ".claude-plugin/plugin.json"
}

```

This structure references a directory `tres-finance-plugin/` at the repository root. Inside that directory, the loader expects to find [`run.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/run.sh) as the executable entry point and [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json) as the metadata manifest.

## Summary

- The **`source: git-subdir`** shape enables monorepo hosting for Claude plugins by declaring that code lives in a subdirectory rather than an external repository.
- Required fields include **`subdir`** (path), **`entrypoint`** (executable), and **`sha`** (version pin).
- The loader resolves these entries by checking out the specified SHA and executing the entrypoint within the subdirectory context.
- Validation scripts in `.github/actions/validate-plugins` verify that `git-subdir` entries point to real directories with valid [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) manifests.
- This approach maintains multiple plugins in a single repository while ensuring reproducible versioning through commit SHA pinning.

## Frequently Asked Questions

### What is the difference between git-subdir and external repository sources?

**`git-subdir`** indicates the plugin code exists within the same repository as the manifest, specifically in a subdirectory defined by the `subdir` field. External repository sources would specify a remote URL or different repository identifier. The `git-subdir` shape keeps everything in one monorepo for easier maintenance and atomic updates across multiple plugins.

### Can I use path instead of subdir in the manifest?

Yes, the manifest accepts either **`subdir`** or **`path`** as the field name to specify the directory location. Both fields serve the same function: telling the loader where to find the plugin files relative to the repository root. However, **`subdir`** is the preferred and more commonly documented field name in the `anthropics/claude-plugins-community` repository.

### How does the validation script verify git-subdir entries?

The validation script [`.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh) reads each entry with `source: "git-subdir"` and performs filesystem checks. It verifies that the subdirectory exists, contains a valid [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) file, and that the `entrypoint` script is present and executable. This ensures that merged entries reference functional code rather than broken or missing paths.

### Why is the sha field required for git-subdir entries?

The **`sha`** field provides deterministic versioning by pinning the plugin to a specific commit hash. Even though the code lives in the same repository, the SHA ensures that clients always load the exact version of the plugin specified in the manifest, preventing unexpected behavior when the repository HEAD advances. This supports reproducible builds and allows the platform to cache plugin versions effectively.