# `url` vs `git-subdir` Source Types in `marketplace.json`: What's the Difference?

> Understand the difference between url and git-subdir source types in marketplace.json. Learn how git-subdir isolates plugins from monorepos, exposing only necessary code.

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

---

**The `url` source type clones an entire repository at a specific commit, while `git-subdir` isolates a single folder from a larger repository—letting you publish plugins from monorepos without exposing unrelated code.**

The [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file in the `anthropics/claude-plugins-community` repository controls how the Claude Marketplace fetches plugin source code. When adding your plugin, you must choose between two source types that differ fundamentally in **scope**: one captures a whole repository, the other extracts a specific sub-directory. Both resolve to an exact commit SHA for reproducible builds.

---

## How the `url` Source Type Works

The **`url`** source type is the simpler option. It clones the entire Git repository and treats the repository root as the plugin's base directory.

### Required Fields for `url`

| Field | Description |
|-------|-------------|
| `url` | Full HTTPS Git URL to the repository |
| `sha` | Exact commit SHA to checkout |

### Real-World Example: 0x Plugin

In [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) (lines 17–20), the 0x plugin uses `url` because its code lives at the repository root:

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

```

Use **`url`** when your plugin occupies the entire repository—this is the most common case for standalone plugins.

---

## How the `git-subdir` Source Type Works

The **`git-subdir`** source type targets a specific folder inside a repository. This is essential for **monorepos** that contain multiple plugins, shared libraries, or unrelated code you don't want exposed as part of your plugin.

### Required Fields for `git-subdir`

| Field | Description |
|-------|-------------|
| `url` | HTTPS Git URL **or** short `<owner>/<repo>` format |
| `path` | Relative path inside the repo to the plugin folder |
| `ref` | Branch, tag, or commit reference to checkout |
| `sha` | Resolved exact commit SHA for immutability |

### Real-World Example: 42Crunch API Security Testing

In [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) (lines 57–62), this plugin extracts only the `plugins/api-security-testing` folder from a larger repository:

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

```

Notice the **shortcut URL format**: `42Crunch-AI/claude-plugins` resolves to the full HTTPS URL automatically. The `ref` field provides readability (humans see `v1.0.1`), while `sha` guarantees the exact code that runs.

---

## Side-by-Side Comparison

| Aspect | `url` | `git-subdir` |
|--------|-------|--------------|
| **Scope** | Entire repository | Single sub-directory |
| **Use case** | Standalone plugin repos | Monorepos with multiple plugins |
| **URL format** | Full HTTPS only | Full HTTPS or `<owner>/<repo>` shortcut |
| **Path specification** | Implicit (repo root) | Explicit `path` field required |
| **Version reference** | `sha` only | `ref` (human-readable) + `sha` (resolved) |
| **Example repos** | 0x, single-purpose plugins | 42Crunch, multi-plugin repositories |

---

## Adding a New Plugin: Code Templates

### Template for Standalone Repository (`url`)

```json
{
  "name": "my-awesome-plugin",
  "description": "A plugin that lives at the repo root",
  "source": {
    "source": "url",
    "url": "https://github.com/example/my-awesome-plugin.git",
    "sha": "a1b2c3d4e5f67890123456789abcdef123456789"
  },
  "homepage": "https://github.com/example/my-awesome-plugin"
}

```

### Template for Monorepo Sub-Directory (`git-subdir`)

```json
{
  "name": "my-subdir-plugin",
  "description": "A plugin inside a larger monorepo",
  "source": {
    "source": "git-subdir",
    "url": "example/monorepo",
    "path": "plugins/my-subdir-plugin",
    "ref": "main",
    "sha": "1234567890abcdef1234567890abcdef12345678"
  },
  "homepage": "https://github.com/example/monorepo"
}

```

---

## Key Implementation Details from Source

The [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) file is the **authoritative source** for plugin discovery in the Claude Marketplace. Each entry's `source` field determines how the Marketplace fetches code:

- **`sha` immutability**: Both source types resolve to a concrete SHA. Even when `git-subdir` uses a `ref` like `v1.0.1`, the `sha` field locks the exact commit.
- **Path isolation**: With `git-subdir`, only files under the specified `path` are exposed as the plugin; sibling directories remain inaccessible.
- **URL flexibility**: The `git-subdir` shortcut format reduces repetition for GitHub-hosted repositories.

The companion [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file (located within each plugin's directory) provides per-plugin metadata, but [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) controls the fetch mechanism.

---

## Summary

- **`url`** — Clone entire repo, root directory is plugin. Use for standalone repositories.
- **`git-subdir`** — Clone repo, isolate specific folder. Use for monorepos with multiple plugins.
- Both require a resolved `sha` for reproducible, immutable builds.
- `git-subdir` adds `path` and `ref` fields for sub-directory targeting and human-readable versioning.
- Real implementations live in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) in the `anthropics/claude-plugins-community` repository.

---

## Frequently Asked Questions

### Can I use `git-subdir` with a full HTTPS URL instead of the shortcut?

Yes. The `url` field in `git-subdir` accepts either full HTTPS URLs (`https://github.com/owner/repo.git`) or the abbreviated `<owner>/<repo>` format. Both resolve to the same repository.

### Why does `git-subdir` require both `ref` and `sha`?

The `ref` field provides a human-readable pointer—like `main` or `v2.1.0`—that helps developers understand which version is intended. The `sha` field guarantees immutability by locking the exact commit hash, protecting against tag changes or branch updates.

### What happens if I use `url` for a plugin that isn't at the repository root?

The Marketplace will treat the repository root as your plugin, potentially exposing unwanted files or failing validation if [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) isn't found at that level. Use `git-subdir` with the correct `path` instead.

### Is there a performance difference between `url` and `git-subdir`?

Both clone the full repository internally. The `git-subdir` type simply restricts which files are exposed to the plugin system after checkout. Network and storage costs are identical; the difference is purely organizational convenience.