Git-Subdir vs URL Source Types for Claude Plugin Distribution

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 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, the 0x plugin demonstrates this approach at lines 17–20:

{
  "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 (lines 57–62) uses this method:

{
  "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 serves as the central registry that maps plugin names to their source definitions, individual plugins often include their own .claude-plugin/plugin.json files for local metadata validation. The repository root 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 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.

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