{"id":35143340,"url":"https://github.com/21-dot-dev/subtree","last_synced_at":"2026-04-22T02:04:46.651Z","repository":{"id":319773847,"uuid":"1066076074","full_name":"21-DOT-DEV/subtree","owner":"21-DOT-DEV","description":"Simple git subtree management through declarative configuration with file extraction and validation capabilities.","archived":false,"fork":false,"pushed_at":"2026-01-16T06:54:56.000Z","size":808,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-16T21:51:51.277Z","etag":null,"topics":["git","subtree","swift-package-manager"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/21-DOT-DEV.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"agents.md","dco":null,"cla":null}},"created_at":"2025-09-29T01:37:04.000Z","updated_at":"2026-01-16T06:28:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"da604170-2d0c-4098-8d39-1ed505136447","html_url":"https://github.com/21-DOT-DEV/subtree","commit_stats":null,"previous_names":["21-dot-dev/subtree"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/21-DOT-DEV/subtree","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/21-DOT-DEV%2Fsubtree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/21-DOT-DEV%2Fsubtree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/21-DOT-DEV%2Fsubtree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/21-DOT-DEV%2Fsubtree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/21-DOT-DEV","download_url":"https://codeload.github.com/21-DOT-DEV/subtree/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/21-DOT-DEV%2Fsubtree/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29961859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T05:59:08.471Z","status":"ssl_error","status_checked_at":"2026-03-01T05:58:04.208Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","subtree","swift-package-manager"],"created_at":"2025-12-28T12:57:21.889Z","updated_at":"2026-03-01T06:02:09.257Z","avatar_url":"https://github.com/21-DOT-DEV.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🌳 Subtree CLI\n\nSimplify git subtree management through declarative configuration with safe file extraction and validation capabilities.\n\n[![CI Status](https://github.com/21-DOT-DEV/subtree/actions/workflows/ci.yml/badge.svg)](https://github.com/21-DOT-DEV/subtree/actions/workflows/ci.yml)\n[![Swift 6.0+](https://img.shields.io/badge/Swift-6.0+-orange.svg)](https://swift.org)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n## Objectives\n\n- **Declarative Configuration** - Manage subtrees through a simple `subtree.yaml` file instead of remembering complex git commands\n- **Atomic Operations** - All subtree changes include configuration updates in single commits for perfect consistency\n- **Safe File Management** - Extract files from subtrees with smart overwrite protection and validation\n- **Developer Experience** - Intuitive CLI with clear error messages, dry-run modes, and helpful guidance\n\n\u003e [!NOTE]  \n\u003e Subtree CLI wraps `git subtree` with enhanced safety and convenience - your existing git history remains unchanged.\n\n## Table of Contents\n\n- [Objectives](#objectives)\n- [Installation](#installation)\n- [Usage Examples](#usage-examples)\n- [API Reference](#api-reference)\n- [Platform Compatibility](#platform-compatibility)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\n### Requirements\n\n\u003e [!IMPORTANT]  \n\u003e You must be inside a Git repository to use Subtree CLI. The tool will not initialize repositories for you.\n\n- **Swift 6.0+** toolchain\n- **macOS 13+** or **Linux (glibc 2.27+)** \n- **Git** installed and available on PATH\n\n\n### Swift Package Manager\n\nAdd the following to your `Package.swift` dependencies:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/21-DOT-DEV/subtree.git\", from: \"1.0.0\")\n]\n```\n\n### GitHub Releases\n\nDownload pre-built binaries from [GitHub Releases](https://github.com/21-DOT-DEV/subtree/releases):\n\n1. Download the appropriate binary for your platform:\n   - `subtree_1.0.0_macOS_arm64` (Apple Silicon)\n   - `subtree_1.0.0_macOS_x86_64` (Intel Mac)\n   - `subtree_1.0.0_linux_x86_64` (Linux)\n   - `subtree_1.0.0_linux_arm64` (Linux ARM)\n\n2. Make executable and add to PATH:\n   ```bash\n   chmod +x subtree_1.0.0_macOS_arm64\n   mv subtree_1.0.0_macOS_arm64 /usr/local/bin/subtree\n   ```\n\n### Swift Artifact Bundle\n\nUse the artifact bundle for Swift Package Manager integration:\n\n```swift\ndependencies: [\n    .binaryTarget(\n        name: \"subtree\",\n        url: \"https://github.com/21-DOT-DEV/subtree/releases/download/1.0.0/subtree.artifactbundle.zip\",\n        checksum: \"...\"\n    )\n]\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/21-DOT-DEV/subtree.git\ncd subtree\nswift build -c release\n./.build/release/subtree --help\n```\n\n## Usage Examples\n\n### 🚀 Quick Start\n\nCreate your first `subtree.yaml` configuration:\n\n```bash\n# Create minimal config in your git repository\nsubtree init\n\n# 🎯 Interactive setup with step-by-step guidance (TTY only)\nsubtree init --interactive\n```\n\n\u003e [!TIP]  \n\u003e Start with `--interactive` mode to get familiar with the configuration format!\n\n### 📦 Add Subtrees\n\nAdd configured subtrees to your repository:\n\n```bash\n# Add a single subtree by name\nsubtree add --name example-lib\n\n# Add with explicit overrides\nsubtree add --name libfoo \\\n  --remote https://github.com/example/libfoo.git \\\n  --prefix Vendor/libfoo \\\n  --ref main \\\n  --no-squash\n\n# Add all configured subtrees\nsubtree add --all\n```\n\n### 🔄 Update Subtrees\n\nManage subtree updates with various strategies:\n\n```bash\n# Report pending updates (no changes, exit 5 if updates available)\nsubtree update\n\n# Apply updates (one commit per subtree on topic branch)\nsubtree update --commit\n\n# Single commit with all updates on current branch\nsubtree update --commit --single-commit --on-current\n\n# Dry run to preview changes\nsubtree update --dry-run\n```\n\n### 🗑️ Remove Subtrees\n\n```bash\n# Remove a configured subtree\nsubtree remove --name example-lib\n```\n\n### 📂 Extract Files\n\nCopy files from subtrees to your repository:\n\n\u003e [!WARNING]  \n\u003e Extract operations respect Git's tracking status - tracked files are protected unless you use `--force`.\n\n```bash\n# Ad-hoc file extraction with glob patterns\nsubtree extract --name example-lib --from \"docs/**/*.md\" --to Docs/\n\n# Multi-pattern extraction (009) - extract from multiple directories at once\nsubtree extract --name mylib \\\n  --from \"include/**/*.h\" \\\n  --from \"src/**/*.c\" \\\n  --to vendor/\n\n# Multi-destination extraction (012) - fan-out to multiple locations\nsubtree extract --name mylib \\\n  --from \"**/*.h\" \\\n  --to Lib/include/ \\\n  --to Vendor/headers/\n\n# Combined: multi-pattern + multi-destination (cartesian product)\nsubtree extract --name mylib \\\n  --from \"*.h\" --from \"*.c\" \\\n  --to Lib/ --to Vendor/\n\n# Brace expansion (011) - compact patterns with {alternatives}\nsubtree extract --name mylib --from \"*.{h,c,cpp}\" --to Sources/\nsubtree extract --name mylib --from \"{src,test}/*.swift\" --to Sources/\n\n# Brace expansion with embedded path separators (different directory depths)\nsubtree extract --name crypto-lib \\\n  --from \"Sources/{PrettyBytes,SecureBytes,BoringSSL/RNG}.swift\" \\\n  --to Crypto/\n\n# With exclusions (applies to all patterns)\nsubtree extract --name mylib --from \"src/**/*.c\" --to Sources/ --exclude \"**/test/**\"\n\n# Save multi-destination mapping for future use\nsubtree extract --name mylib --from \"**/*.h\" --to Lib/ --to Vendor/ --persist\n\n# Execute saved mappings from subtree.yaml\nsubtree extract --name example-lib\nsubtree extract --all\n```\n\n### 🧹 Clean Extracted Files\n\nRemove previously extracted files with checksum validation:\n\n```bash\n# Clean specific files (validates checksums before deletion)\nsubtree extract --clean --name mylib --from \"src/**/*.c\" --to Sources/\n\n# Clean from multiple destinations (012)\nsubtree extract --clean --name mylib --from \"**/*.h\" --to Lib/ --to Vendor/\n\n# Clean all saved mappings for a subtree\nsubtree extract --clean --name mylib\n\n# Clean all mappings for all subtrees\nsubtree extract --clean --all\n\n# Force clean modified files (skips checksum validation)\nsubtree extract --clean --force --name mylib --from \"*.c\" --to Sources/\n```\n\n### ✅ Validate Subtree State\n\nVerify subtree integrity and synchronization:\n\n```bash\n# Offline validation against commit hash\nsubtree validate\n\n# Validate specific subtree with pattern\nsubtree validate --name example-lib --from \"**/*.md\"\n\n# Repair discrepancies\nsubtree validate --repair\n\n# Include remote divergence check\nsubtree validate --with-remote\n```\n\n## API Reference\n\n### Commands\n\n- **`init`** - Initialize `subtree.yaml` configuration\n  - `--import` - Scan for existing git subtrees\n  - `--interactive` - Guided setup (TTY only)\n  - `--force` - Overwrite existing configuration\n\n- **`add`** - Add configured subtrees \n  - `--name \u003cname\u003e` - Add specific subtree\n  - `--all` - Add all configured subtrees\n  - Override flags: `--remote`, `--prefix`, `--ref`, `--no-squash`\n\n- **`update`** - Update subtrees with various strategies\n  - `--name \u003cname\u003e` - Update specific subtree  \n  - `--all` - Update all subtrees\n  - `--commit` - Apply updates (default: report only)\n  - `--mode \u003cbranch|tag|release\u003e` - Update strategy\n  - `--branch \u003cname\u003e` - Custom topic branch name\n  - `--single-commit` - Squash all updates into one commit\n  - `--on-current` - Apply updates to current branch\n  - `--dry-run` - Preview changes without applying\n  - `--force` - Override safety checks\n\n- **`remove`** - Remove configured subtrees\n  - `--name \u003cname\u003e` - Remove specific subtree\n\n- **`extract`** - Copy or clean files from subtrees\n  - `--name \u003cname\u003e` - Extract from specific subtree\n  - `--from \u003cpattern\u003e` - Source glob pattern (repeatable for multi-pattern)\n  - `--to \u003cpath\u003e` - Destination path\n  - `--exclude \u003cpattern\u003e` - Exclude pattern (repeatable)\n  - `--all` - Execute all saved mappings\n  - `--persist` - Save mapping to subtree.yaml\n  - `--force` - Overwrite git-tracked files / force delete modified files\n  - `--clean` - Remove extracted files (validates checksums first)\n  - Multi-destination: Use `--to` multiple times for fan-out extraction\n\n- **`validate`** - Verify subtree integrity\n  - `--name \u003cname\u003e` - Validate specific subtree\n  - `--from \u003cpattern\u003e` - Validate specific files\n  - `--repair` - Fix discrepancies\n  - `--with-remote` - Include remote comparison\n\n### Exit Codes\n\n- **0** - Success\n- **1** - General error\n- **2** - Invalid usage or configuration  \n- **3** - Git operation failure or not in Git repository\n- **4** - Configuration file not found\n- **5** - Updates available (report mode only)\n\n### Configuration Format\n\n`subtree.yaml` schema:\n\n```yaml\nsubtrees:\n  - name: example-lib                    # Unique identifier\n    remote: https://github.com/example/lib.git\n    prefix: Sources/ThirdParty/ExampleLib\n    branch: main\n    squash: true                         # Default: true\n    commit: 0123456789abcdef...          # Latest known commit\n    extractions:                         # File extraction mappings\n      # Single pattern, single destination (legacy format)\n      - from: \"docs/**/*.md\"\n        to: Docs/\n      # Multi-pattern (009) - union extraction\n      - from:\n          - \"include/**/*.h\"\n          - \"src/**/*.c\"\n        to: vendor/\n        exclude:\n          - \"**/test/**\"\n      # Multi-destination (012) - fan-out to multiple locations\n      - from: \"**/*.h\"\n        to:\n          - Lib/include/\n          - Vendor/headers/\n      # Combined: multi-pattern + multi-destination\n      - from:\n          - \"*.h\"\n          - \"*.c\"\n        to:\n          - Lib/\n          - Vendor/\n```\n\n## Platform Compatibility\n\n| Platform | Architecture | Minimum Version | Status |\n|----------|-------------|-----------------|---------|\n| macOS | arm64, x86_64 | 13.0+ | ✅ Supported |\n| Linux | x86_64, arm64 | glibc 2.27+ | ✅ Supported |\n| Windows | x86_64, arm64 | Windows 10+ | Future |\n\n**Dependencies:**\n- Swift 6.0+ toolchain\n- Git (any recent version)\n- ArgumentParser 1.6.1\n- Yams 6.1.0  \n- swift-subprocess 0.1.0+\n- SemanticVersion 0.5.1\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Quick Start for Contributors\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Run tests: `swift test`\n4. Make your changes following our coding standards\n5. Add tests for new functionality\n6. Submit a pull request\n\n### Development Setup\n\n```bash\ngit clone https://github.com/21-DOT-DEV/subtree.git\ncd subtree\nswift build\nswift test\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F21-dot-dev%2Fsubtree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F21-dot-dev%2Fsubtree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F21-dot-dev%2Fsubtree/lists"}