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

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 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 and 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 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 enforces these schema requirements during CI validation.

Real-World Examples from marketplace.json

The central manifest at .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:

{
  "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:

{
  "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:

{
  "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:

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 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 and .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 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 enforces path safety constraints to prevent directory escape vulnerabilities during the clone and checkout process.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}