# What Is the git-subdir Source Reference for Claude Plugins?

> Learn how the git-subdir source reference lets Claude Plugins fetch code from a specific Git repository sub-directory, saving time and resources by avoiding full repo clones. Understand its key configuration fields.

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

---

**The `git-subdir` source reference is a manifest configuration that enables the Claude Plugins Marketplace to fetch a plugin from a specific sub-directory within a remote Git repository rather than cloning the entire repo, using fields like `url`, `path`, `ref`, and `sha` to pinpoint the exact code location and version.**

The Claude Plugins Marketplace supports multiple distribution methods, with `git-subdir` enabling monorepo-style organization where multiple plugins coexist in a single repository. According to the `anthropics/claude-plugins-community` source code, this reference type fetches only the specified sub-folder at a given revision, reducing duplication while maintaining precise version control through commit SHAs.

## How the git-subdir Source Reference Works

When the marketplace client processes a manifest entry, the validation scripts in [`.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) first categorize the source type before the loader executes a targeted fetch operation. The system performs a **shallow clone** of the repository and isolates only the specified directory.

The loading process follows these steps:

1. Clones the repository indicated by `url` using minimal depth when `sha` is supplied
2. Checks out the commit specified by `ref` (or defaults to the `main` branch if omitted)
3. Navigates to the directory given by `path`
4. Treats that directory as a complete plugin package containing [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) and [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md)

This approach allows multiple independent plugins to share a single repository history while maintaining separate release cycles.

## Required and Optional Fields

A `git-subdir` entry in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) must contain specific fields to locate and version-lock plugin code:

- **`source`**: Must contain the literal string `git-subdir` to activate this loader type
- **`url`**: The GitHub or Git-compatible repository URL (typically without the `.git` suffix)
- **`path`**: The relative path inside the repository where the plugin root resides
- **`ref`** (optional): The branch name, tag, or commit SHA to check out; defaults to `main` if omitted
- **`sha`** (optional but recommended): The exact commit SHA that the marketplace validates against, guaranteeing reproducible builds even if the branch moves

The helper library in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh) enforces these schema requirements during CI validation.

## Real-World Examples from marketplace.json

The central manifest at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) contains production implementations demonstrating various `git-subdir` configurations.

### 42Crunch API Security Testing

The 42Crunch plugin demonstrates strict version pinning with both `ref` and `sha` fields:

```json
{
  "source": {
    "source": "git-subdir",
    "url": "42Crunch-AI/claude-plugins",
    "path": "plugins/api-security-testing",
    "ref": "v1.0.1",
    "sha": "30287f5e3f122a646d1ac5ca3ab96e130c52a3ad"
  }
}

```

This entry (lines 57-62) fetches the plugin from the `plugins/api-security-testing` folder at tag `v1.0.1`, validating against commit `30287f5e3f122a646d1ac5ca3ab96e130c52a3ad`.

### SAP Development Core

The SAP Development Core plugin illustrates HTTPS URL formatting with branch tracking:

```json
{
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/sapdev-ai/sap-dev.git",
    "path": "plugins/sap-dev-core",
    "ref": "main",
    "sha": "751882881caa1a1762a16a51f262525519a034d2"
  }
}

```

Located at lines 117-122, this reference includes the `.git` suffix in the URL and pins to a specific commit on the main branch.

### A11y-Fixer

The A11y-Fixer plugin demonstrates nested directory structures and short-form URLs:

```json
{
  "source": {
    "source": "git-subdir",
    "url": "barnburner121/claude-plugin-marketplace",
    "path": "generated-plugins/a11y-fixer",
    "ref": "main",
    "sha": "5f6b5d32d9f457dc9c2c7c0fb1d67dffc9140f33"
  }
}

```

This example (lines 79-84) stores the plugin in a `generated-plugins` sub-directory, showing that `path` can represent deeply nested locations within the repository.

## Implementation Details

When the marketplace client reads a `git-subdir` entry, it executes Git operations equivalent to:

```bash
git clone --depth 1 --branch v2.3.0 https://github.com/example/my-repo.git repo
cd repo
git checkout a1b2c3d4e5f67890abcdef1234567890abcdef12
cd plugins/my-awesome-plugin

# ...load plugin files from this location...

```

The `--depth 1` flag ensures efficient shallow clones when a `sha` is provided, while the explicit `git checkout` guarantees the exact commit is loaded regardless of subsequent branch updates.

## Summary

- The `git-subdir` source reference enables plugin distribution from sub-directories within monorepos without cloning entire repositories
- Required fields include `source` (set to "git-subdir"), `url`, and `path`; optional fields include `ref` for branch/tag selection and `sha` for immutable builds
- The marketplace performs shallow clones and explicit checkouts to ensure reproducible plugin loading
- Real-world implementations in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) demonstrate HTTPS and SSH URL formats, deeply nested paths, and strict SHA pinning for security
- Validation occurs through [`.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) and [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh) before publication

## Frequently Asked Questions

### Can I use git-subdir with private Git repositories?

The `git-subdir` source reference supports any Git-compatible URL, including private repositories accessible via SSH or authenticated HTTPS. However, the marketplace client and validation environment must have appropriate credentials configured to access private repos. The validation scripts in `anthropics/claude-plugins-community` verify URL accessibility during the CI pipeline.

### What happens if I omit the sha field in my manifest?

While the `sha` field is optional, omitting it removes reproducibility guarantees. The marketplace will check out the latest commit on the specified `ref` branch or tag, which may introduce breaking changes if the remote repository updates. The production examples in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) consistently include `sha` values to ensure immutable plugin versions.

### How does git-subdir differ from a standard git source type?

Unlike a standard `git` source that expects the repository root to contain plugin files, `git-subdir` specifically directs the loader to navigate into a sub-directory after cloning. This architectural distinction allows multiple independent plugins to coexist in a single repository while maintaining separate versioning, whereas standard git sources assume the entire repo represents one plugin.

### Does the path field support parent directory traversal like ../?

No, the `path` field must specify a relative path within the repository without parent directory references. The validation logic in [`.github/actions/validate-plugins/lib/common.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/lib/common.sh) enforces path safety constraints to prevent directory escape vulnerabilities during the clone and checkout process.