# What Is the "git‑subdir" Source Type for Claude Plugins? A Complete Guide

> Learn about the git-subdir source type for Claude plugins. Discover how to install plugins from specific subdirectories in a Git repo, enabling independent versioning and shared repositories.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-05

---

**The `git‑subdir` source type lets the Claude plugins system install a plugin from a specific sub‑directory of a Git repository rather than the repository root, enabling multiple plugins to share one repo while maintaining independent versioning.**

The `git‑subdir` source type is a core mechanism in the `anthropics/claude-plugins-community` ecosystem. It solves a practical problem: many organizations want to maintain several related plugins together without creating separate repositories for each one. This article explains exactly how `git‑subdir` works, what fields it requires, and how the validation pipeline processes these entries.

---

## How the git‑subdir Source Type Works

When a plugin entry in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) declares `"source": "git‑subdir"`, the system knows to look inside a repository subfolder rather than treating the entire repo as a single plugin.

The CLI performs three critical steps during validation or installation:

1. **Clone** the repository at the specified `ref` (branch, tag, or commit).
2. **Verify** that the checked‑out commit matches the supplied `sha` for integrity.
3. **Navigate** to the `path` subdirectory and load the plugin from that location.

This approach provides **deterministic, reproducible builds** — the `sha` ensures you get exactly the code you expect, even if the `ref` tag gets moved or deleted.

---

## Required Fields for git‑subdir Entries

Every `git‑subdir` source must include four fields. These are validated by the scripts in `.github/actions/validate-plugins/scripts/`.

| Field | Description | Example |
|-------|-------------|---------|
| `url` | GitHub repository identifier (owner/repo) | `42Crunch-AI/claude-plugins` |
| `path` | Relative path to the plugin's `.claude-plugin` folder | `plugins/api-security-testing` |
| `ref` | Branch, tag, or commit reference to checkout | `v1.0.1` or `main` |
| `sha` | Full 40‑character commit SHA for verification | `30287f5e3f122a646d1ac5ca3ab96e130c52a3ad` |

Missing any of these fields causes validation to fail. The `sha` must match exactly — the pipeline runs `git rev-parse HEAD` and compares against this value.

---

## Real‑World Examples from the Repository

Two plugins in the official marketplace demonstrate typical `git‑subdir` usage patterns.

### 42Crunch API‑Security‑Testing Plugin

This entry at **lines 57‑61 of [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)** pins a specific release:

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

```

Notice the use of a **semantic version tag** (`v1.0.1`) combined with an explicit SHA. This protects against tag rewriting attacks.

### A11y‑Fixer Plugin

This entry at **lines 79‑84** tracks a development branch:

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

```

The `main` branch reference here requires more frequent SHA updates as the plugin evolves.

---

## Validation Pipeline Implementation

The `git‑subdir` source type is processed by two key scripts in the repository's GitHub Actions workflow.

### Change Detection (00-detect-changes.sh)

The detection script identifies entries where the source is an object containing `url` and `path` fields rather than a simple string. This triggers the specialized `git‑subdir` validation path.

### External Validation (30-validate-cli-external.sh)

This script implements the actual `git‑subdir` logic:

```bash

# Clone at specific ref

git clone --depth 1 --branch ${REF} https://github.com/${URL}.git ${TEMP_DIR}

# Verify SHA integrity

ACTUAL_SHA=$(git -C ${TEMP_DIR} rev-parse HEAD)
if [ "${ACTUAL_SHA}" != "${EXPECTED_SHA}" ]; then
    echo "SHA mismatch: expected ${EXPECTED_SHA}, got ${ACTUAL_SHA}"
    exit 1
fi

# Load plugin from subdirectory

PLUGIN_ROOT="${TEMP_DIR}/${PATH}"
validate_plugin_json "${PLUGIN_ROOT}/.claude-plugin/plugin.json"

```

The shallow clone (`--depth 1`) keeps CI fast while still allowing full SHA verification.

---

## Custom Plugin Manifest Template

To publish your own `git‑subdir` plugin, structure your [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) entry like this:

```json
{
  "name": "my-cool-plugin",
  "description": "Demo plugin stored in a sub-folder.",
  "source": {
    "source": "git-subdir",
    "url": "myorg/my-plugins-repo",
    "path": "plugins/my-cool-plugin",
    "ref": "v2.3.0",
    "sha": "a1b2c3d4e5f67890123456789abcdef012345678"
  },
  "homepage": "https://github.com/myorg/my-plugins-repo"
}

```

Place your actual plugin files — [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json), skills, icons — inside the `plugins/my-cool-plugin/.claude-plugin/` directory of your repository.

---

## Benefits of the git‑subdir Design

Using `git‑subdir` instead of repo‑per‑plugin provides several advantages:

- **Code reuse** — Shared utilities, test frameworks, or CI configurations live at the repository root.
- **Atomic updates** — Version‑bump multiple related plugins in a single commit.
- **Reduced overhead** — One repository to manage issues, permissions, and secrets instead of many.
- **Deterministic installs** — The `ref` + `sha` combination guarantees identical plugin code across all installations.

---

## Summary

- **`git‑subdir`** enables plugins to reside in subdirectories of Git repositories, defined in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json).
- Four required fields control the behavior: `url`, `path`, `ref`, and `sha`.
- The validation pipeline at [`.github/actions/validate-plugins/scripts/30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/actions/validate-plugins/scripts/30-validate-cli-external.sh) clones, verifies, and extracts these plugins.
- Real examples include 42Crunch API‑Security‑Testing (lines 57‑61) and A11y‑Fixer (lines 79‑84) in the marketplace manifest.

---

## Frequently Asked Questions

### What happens if the sha field doesn't match the actual commit?

The validation script [`30-validate-cli-external.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/30-validate-cli-external.sh) performs an explicit check: it runs `git rev-parse HEAD` and compares the output to the expected SHA. If they differ, validation fails with an error message and the plugin is not accepted into the marketplace. This prevents supply‑chain attacks where a tag is moved to a different commit.

### Can I use git‑subdir with private repositories?

The current marketplace validation is designed for public GitHub repositories. The scripts clone via `https://github.com/${URL}.git` without authentication. For private repositories, you would need to modify the validation pipeline to inject credentials or use deploy keys, which is not supported in the standard `anthropics/claude-plugins-community` workflow.

### How do I update a git‑subdir plugin to a new version?

Update both the `ref` field (to the new tag or branch) and the `sha` field (to the full 40‑character commit hash) in your marketplace.json entry. The detection script [`00-detect-changes.sh`](https://github.com/anthropics/claude-plugins-community/blob/main/00-detect-changes.sh) will flag this as a modification, triggering re‑validation. The PR must pass the SHA verification before merging.

### Why use git‑subdir instead of a separate repository for each plugin?

`git‑subdir` reduces maintenance burden when you maintain multiple related plugins. You can share CI configurations, testing utilities, and documentation in the repository root while keeping each plugin independently versioned. This is especially valuable for organizations with plugin suites that share common code — the 42Crunch example demonstrates this pattern with multiple security tools in one repo.