# Git-Subdir vs URL Source Types for Claude Plugin Distribution

> Discover the difference between git-subdir and url source types for Claude plugin distribution. Learn how to effectively manage single plugins or multi-plugin collections in your repository.

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

---

**The `url` source type distributes a standalone plugin from a repository root, while `git-subdir` isolates a plugin located in a specific subdirectory of a larger repository, enabling multi-plugin collections.**

The Claude Plugins Marketplace uses a declarative `source` object to instruct the runtime where to fetch plugin code. Understanding the difference between **`url`** and **`git-subdir`** source types is essential for correctly packaging and distributing Claude plugins, whether you are maintaining a standalone tool or contributing to a community collection.

## How the Source Object Works

The `source` field defined in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) determines the distribution strategy for each plugin. According to the anthropics/claude-plugins-community source code, this configuration tells the Claude runtime whether to clone an entire repository or extract a specific subdirectory.

### URL Source Type for Standalone Plugins

Use the `url` source when a plugin occupies the root of its own dedicated repository. The runtime clones the entire repository at the specified commit hash and uses the top-level contents as the plugin code.

In [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json), the **`0x`** plugin demonstrates this approach at lines 17–20:

```json
{
  "source": "url",
  "url": "https://github.com/0xProject/0x-claude-plugin.git",
  "sha": "a1b2c3d4e5f6g7h8i9j0k1234567890abcdef12"
}

```

Required fields for `url` sources:

- `source`: Must be `"url"`
- `url`: The Git repository URL
- `sha`: The specific commit hash to checkout

### Git-Subdir Source Type for Repository Collections

Use the `git-subdir` source when multiple plugins live within subdirectories of a single larger repository. The runtime clones the repository, then isolates only the specified directory path, ignoring unrelated files in the parent repository.

The **`42crunch-api-security-testing`** plugin in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) (lines 57–62) uses this method:

```json
{
  "source": "git-subdir",
  "url": "https://github.com/42Crunch-AI/claude-plugins.git",
  "path": "42crunch-api-security-testing",
  "ref": "main",
  "sha": "1234567890abcdef1234567890abcdef12345678"
}

```

Required fields for `git-subdir` sources:

- `source`: Must be `"git-subdir"`
- `url`: The parent repository URL
- `path`: The subdirectory containing the plugin
- `ref`: The branch or tag name
- `sha`: The specific commit hash

## Key Differences Between URL and Git-Subdir Sources

**Repository Structure**
- **`url`**: Expects the plugin to exist at the repository root. Ideal for single-purpose repositories where the entire codebase constitutes one plugin.
- **`git-subdir`**: Expects the plugin to live within a nested directory. Enables monorepo patterns where multiple plugins share common infrastructure and history.

**Fetching Behavior**
- **`url`**: The runtime clones or archives the entire repository at the given `sha`, using the full checkout as the plugin context.
- **`git-subdir`**: The runtime clones the repository at the specified `ref` and `sha`, then extracts only the directory indicated by `path`. This reduces download size and prevents unrelated files from entering the plugin environment.

**Manifest Complexity**
- **`url`**: Requires minimal metadata—only the repository URL and commit hash.
- **`git-subdir`**: Requires additional fields (`path` and `ref`) to locate the plugin within the larger repository structure.

## When to Use Each Source Type

**Choose `url` when:**

- Your plugin is the sole content of the repository
- You want simple, minimal configuration with fewer manifest fields
- You need full repository visibility for debugging and development workflows

**Choose `git-subdir` when:**

- You maintain a collection of related plugins in one repository (monorepo pattern)
- You want to version plugins independently while sharing repository history and CI/CD pipelines
- You need to reduce runtime download size by excluding unrelated assets, documentation, or other plugins

## Implementation in the Marketplace Ecosystem

The ecosystem relies on a hierarchy of manifest files to resolve plugin sources. While [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) serves as the central registry that maps plugin names to their `source` definitions, individual plugins often include their own [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) files for local metadata validation. The repository root [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md) documents packaging conventions that explain how these source types correspond to physical repository layouts.

When the Claude runtime processes the marketplace manifest, it validates that the declared `source` type matches the actual repository structure. The `0x` entry uses the concise `url` format because it references a dedicated, single-purpose repository, whereas community collections like the 42Crunch plugins require the `git-subdir` structure to isolate individual tools from the shared codebase located at the parent repository level.

## Summary

- **`url` source** distributes standalone plugins from repository roots, requiring only a repository URL and commit hash in the manifest.
- **`git-subdir` source** enables subdirectory distribution from multi-plugin repositories, requiring `path` and `ref` fields in addition to the base URL.
- The Claude runtime handles these differently during fetch operations: `url` uses the full repository checkout, while `git-subdir` extracts only the specified directory to save space and isolate dependencies.
- Choose `url` for single-plugin repositories and `git-subdir` for monorepo collections or community-maintained plugin bundles that share a common repository.

## Frequently Asked Questions

### Can I convert a URL source plugin to git-subdir without changing the repository?

No, converting requires restructuring your repository. The `git-subdir` type expects the plugin to exist within a subdirectory of a larger repository, whereas `url` expects the plugin at the root. You would need to move your plugin code into a subdirectory and update the marketplace manifest in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) to use the `git-subdir` source type with the appropriate `path` value.

### Does git-subdir support nested subdirectories?

Yes, the `path` field accepts nested directory structures. You can specify `"path": "plugins/security/auth"` to isolate a plugin located three levels deep within the repository hierarchy. The runtime extracts exactly the directory tree specified by `path`, regardless of nesting depth.

### Which source type provides faster installation times?

The `git-subdir` type generally provides faster installation when the plugin resides in a large repository containing many unrelated files, because the runtime only extracts the specified subdirectory rather than cloning the entire repository history. However, for small, dedicated repositories where the plugin constitutes the majority of the content, the difference in installation speed is negligible.

### Is the `ref` field required for git-subdir sources?

Yes, the `ref` field is required for `git-subdir` sources according to the manifest schema implemented in the anthropics/claude-plugins-community repository. It specifies the branch or tag to checkout before resolving the `sha` commit hash, ensuring the runtime correctly locates the subdirectory contents at the specified version.