PHPackages                             yisraeldov/composer-subtree-plugin - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. yisraeldov/composer-subtree-plugin

ActiveComposer-plugin[Utility & Helpers](/categories/utility)

yisraeldov/composer-subtree-plugin
==================================

Composer plugin for safer git subtree workflows

v0.1.0(1mo ago)037↓50%MITPHPPHP ^8.2CI passing

Since Apr 21Pushed 1mo agoCompare

[ Source](https://github.com/yisraeldov/composer-subtree-plugin)[ Packagist](https://packagist.org/packages/yisraeldov/composer-subtree-plugin)[ Docs](https://github.com/yisraeldov/composer-subtree-plugin)[ RSS](/packages/yisraeldov-composer-subtree-plugin/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (12)Versions (2)Used By (0)

**⚠️ 🤖 💩 Made with lots of AI help, so use at your own risk**

composer-subtree-plugin
=======================

[](#composer-subtree-plugin)

A Composer plugin that adds practical Git subtree commands to your PHP project.

Implemented today:

- `composer subtree:add`
- `composer subtree:pull`
- `composer subtree:push`

What this project is
--------------------

[](#what-this-project-is)

`composer-subtree-plugin` helps you manage subtree-based package workflows from Composer commands. It stores subtree metadata on `type=path` repository entries in `composer.json.repositories[].composer-subtree-plugin` and uses those definitions for pull/push operations.

Why use this
------------

[](#why-use-this)

This plugin is useful when your team has internal libraries that were previously pulled in through Composer `vcs` repositories, and that setup is causing friction in CI and deployment.

Common pain points with `vcs` internal dependencies:

- CI and deploy jobs depend on external repository availability and auth at install time.
- Build environments need extra SSH/token setup just to resolve private package sources.
- Reproducibility can become harder when dependency resolution and Git access are tightly coupled.

How this plugin helps:

- You vendor internal libraries as Git subtrees directly in your main repository.
- Composer installs from local code paths already present in the checkout.
- CI and deploy pipelines become simpler because subtree sync is an explicit step (`subtree:pull` / `subtree:push`) instead of an implicit runtime dependency fetch.

Requirements
------------

[](#requirements)

- PHP `^8.2`
- Composer plugin API `^2.2`
- `git` with `git subtree` available

Installation
------------

[](#installation)

Install in the consumer project:

```
composer require yisraeldov/composer-subtree-plugin --dev
```

If your Composer setup requires explicit plugin approval, add:

```
{
  "config": {
    "allow-plugins": {
      "yisraeldov/composer-subtree-plugin": true
    }
  }
}
```

Configuration format
--------------------

[](#configuration-format)

Subtrees are configured on `type=path` repository entries:

```
{
  "repositories": [
    {
      "type": "path",
      "url": "packages/pcre",
      "composer-subtree-plugin": {
        "remote": "https://github.com/composer/pcre.git",
        "branch": "main",
        "squash": false
      }
    }
  ]
}
```

Fields:

- `url` (string): local subtree directory (path repository URL)
- `remote` (string): upstream repository URL
- `branch` (string): upstream branch
- `squash` (bool, optional): whether pull/add uses `--squash` (defaults to `false`)

Day-to-day usage
----------------

[](#day-to-day-usage)

### 1) Add a new subtree

[](#1-add-a-new-subtree)

```
composer subtree:add   [prefix] [--squash]
```

Example:

```
composer subtree:add https://github.com/composer/pcre.git main
```

What it does:

1. Runs `git subtree add --prefix=...   [--squash]`
2. Ensures `composer.json.repositories` contains a path repository entry for the subtree prefix
3. Writes/updates subtree metadata at `repositories[].composer-subtree-plugin`

Notes:

- If `prefix` is omitted, default is `packages/`.
- Target selection is path-based (for example `packages/pcre`) or `all`.
- If the git command fails, config is not persisted.

### 2) Pull subtree updates

[](#2-pull-subtree-updates)

```
composer subtree:pull [target]
```

- `target` can be a subtree path target (for example `packages/pcre`) or `all`.
- If omitted, it behaves like `all`.

Examples:

```
composer subtree:pull packages/pcre
composer subtree:pull all
composer subtree:pull
```

What it does per subtree:

1. `git fetch  `
2. `git subtree pull --prefix=   [--squash]`

### 3) Push subtree updates

[](#3-push-subtree-updates)

```
composer subtree:push [target]
```

- `target` can be a subtree path target or `all`.
- If omitted, it behaves like `all`.

Examples:

```
composer subtree:push packages/pcre
composer subtree:push all
composer subtree:push
```

What it does per subtree:

- `git subtree push --prefix=  `

Current scope (implemented)
---------------------------

[](#current-scope-implemented)

This plugin currently provides:

- Add subtree + persist subtree config
- Pull one/all configured subtrees
- Push one/all configured subtrees

No other subtree commands or update hooks are documented here because they are not implemented yet.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance91

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

49d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/beda65453943df08bfef191550555826e931447707fe6ea194f7329c9cc022ab?d=identicon)[yisraeldov](/maintainers/yisraeldov)

---

Top Contributors

[![yisraeldov](https://avatars.githubusercontent.com/u/138219?v=4)](https://github.com/yisraeldov "yisraeldov (61 commits)")

---

Tags

plugincomposergitsubtree

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/yisraeldov-composer-subtree-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/yisraeldov-composer-subtree-plugin/health.svg)](https://phpackages.com/packages/yisraeldov-composer-subtree-plugin)
```

###  Alternatives

[ergebnis/composer-normalize

Provides a composer plugin for normalizing composer.json.

1.1k40.0M2.6k](/packages/ergebnis-composer-normalize)[pyrech/composer-changelogs

Display changelogs after each composer update

5974.2M28](/packages/pyrech-composer-changelogs)[automattic/jetpack-autoloader

Creates a custom autoloader for a plugin or theme.

545.9M110](/packages/automattic-jetpack-autoloader)[laminas/laminas-component-installer

Composer plugin for injecting modules and configuration providers into application configuration

304.3M105](/packages/laminas-laminas-component-installer)[sllh/composer-lint

Extends the composer validate command with extra rules

14222.1k7](/packages/sllh-composer-lint)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)