# Claude Plugin Source Types: url vs git-subdir Explained

> Understand Claude plugin source types url vs git-subdir. Learn how git-subdir optimizes monorepos by cloning only a specific subfolder for Claude plugins.

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

---

**The `url` source type retrieves an entire Git repository for a Claude plugin, whereas `git-subdir` performs a shallow clone and extracts only a specific subfolder, making it optimal for monorepos containing multiple plugins.**

Claude plugins in the `anthropics/claude-plugins-community` repository are configured within the Marketplace manifest at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json). Each plugin's `source` object instructs the Claude MCP (Model Context Protocol) how to fetch the plugin code, offering two distinct retrieval strategies depending on whether your plugin lives at the repository root or within a subdirectory.

## The url Source Type

The `url` source type provides the MCP with a complete repository view. When specified, the system clones the entire repository (or downloads a tarball) and checks out the code at the exact commit SHA provided.

### How url Retrieval Works

When using the `url` source type, the entire repository becomes available to the plugin runtime. This approach is ideal when the plugin occupies the repository root or when the plugin requires access to files distributed across multiple directories in the project.

### Required Fields for url

The `url` source type requires minimal configuration:

- **`source`**: Must be set to `"url"`
- **`url`**: The HTTPS URL of the Git repository
- **`sha`** (optional): The exact commit hash for reproducible builds

### url Example: The 0x Plugin

As defined in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) (lines 16-19), the 0x plugin demonstrates the `url` pattern by pulling the complete repository:

```json
{
  "name": "0x",
  "source": {
    "source": "url",
    "url": "https://github.com/0xProject/0x-ai.git",
    "sha": "0167bbb411cc972b966127d23c23de801061fa99"
  }
}

```

## The git-subdir Source Type

The `git-subdir` source type isolates a plugin to a specific directory within a larger repository. This method performs a shallow clone at the supplied `ref` (branch or tag), then extracts only the directory specified by the `path` field, ignoring the rest of the repository.

### How git-subdir Retrieval Works

This source type reduces download size and prevents naming collisions when multiple plugins share a single monorepo. The MCP fetches only the necessary subdirectory, making it efficient for repositories like `barnburner121/claude-plugin-marketplace` that contain numerous plugins under a common parent directory.

### Required Fields for git-subdir

The `git-subdir` source type accepts the following fields:

- **`source`**: Must be set to `"git-subdir"`
- **`url`**: The repository URL or shorthand (e.g., `owner/repo`)
- **`path`**: The subdirectory path containing the plugin code
- **`ref`** (optional): A human-readable branch or tag name
- **`sha`** (optional): The exact commit hash for immutable builds

### git-subdir Example: 42Crunch API Security

The 42Crunch plugin (lines 56-61 of the manifest) retrieves only the `plugins/api-security-testing` folder:

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

```

### git-subdir Example: Multi-Plugin Monorepos

Many community plugins reside in the `barnburner121/claude-plugin-marketplace` repository under the `generated-plugins/` directory. Each plugin defines its own subfolder path:

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

```

## Validation and Implementation

The repository's validation system distinguishes between these source types when detecting changes. According to the source code 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), the validation logic handles `url` and `git-subdir` entries differently when determining which plugins require re-validation during CI/CD workflows.

## Key Differences Summary

Understanding when to use each source type ensures optimal repository organization:

- **Scope of retrieval**: `url` fetches the entire repository; `git-subdir` extracts only the specified path
- **Use case**: `url` suits single-repository plugins; `git-subdir` excels in monorepos containing multiple plugins
- **Parameters**: `git-subdir` accepts both `ref` (branch/tag) and `sha`, while `url` typically uses `sha` only
- **Performance**: `git-subdir` reduces download overhead by fetching only necessary files

## When to Use Each Source Type

**Choose `url`** when your plugin constitutes an entire repository or requires access to files across multiple project directories. This approach simplifies configuration for standalone plugins.

**Choose `git-subdir`** when maintaining multiple plugins within a single monorepo or when your plugin lives as a subfolder within a larger project. This method prevents unnecessary data transfer and avoids path conflicts.

## Summary

- The `url` source type in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) clones complete repositories, ideal for standalone plugins like the 0x example
- The `git-subdir` source type performs shallow clones of specific directories, perfect for monorepos like those used by 42Crunch and barnburner121
- Both types support immutable `sha` values for reproducible builds
- The `git-subdir` type uniquely accepts a `ref` parameter for human-readable version references
- 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) process these source types differently during CI workflows

## Frequently Asked Questions

### Can I use git-subdir without specifying a ref?

Yes, the `ref` field is optional for `git-subdir` sources. However, you must provide either a `ref` or a `sha` to ensure the MCP can locate the correct commit. If both are provided, the system uses the `ref` to locate the branch or tag, then verifies the specific `sha` for immutability.

### What happens if both ref and sha are provided in a git-subdir source?

When both parameters are present, the MCP resolves the `ref` (branch or tag name) to locate the general area of the repository history, then validates the exact `sha` to ensure the code matches the expected immutable state. This provides both human-readable versioning and cryptographic verification.

### Is url or git-subdir better for a single plugin repository?

For single plugin repositories where the code lives at the root, use the `url` source type. This approach eliminates the need to specify a `path` parameter and provides the plugin runtime access to the entire repository context. The `git-subdir` type adds unnecessary complexity when the repository contains only one plugin.

### How does the validation script handle different source types?

The validation script at [`.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) distinguishes between `url` and `git-subdir` entries when detecting which plugins have changed in a commit. This differentiation ensures that modifications to specific subdirectories in monorepos trigger validation only for the affected plugins, while standalone repository changes trigger validation for the complete `url`-based plugin.