GithubHelp home page GithubHelp logo

lastcallmedia / composer-upstream-files Goto Github PK

View Code? Open in Web Editor NEW
2.0 3.0 1.0 30 KB

A Composer plugin allowing you to update application files from remote sources

License: MIT License

PHP 100.00%

composer-upstream-files's Introduction

Composer Upstream Files Plugin

This Composer plugin allows you to update files belonging to your application from various upstream sources. There are a couple of different use cases for this:

  • You have files that are required for specific versions of your application dependencies, but which need to live as part of your application. For example, Drupal's index.php file is required, but must live outside of the core directory when you use a Composer based installation.
  • You have files you want to allow modifications to (so they're not appropriate for inclusion in a library), but that you want to keep in sync between different projects. For example, a default .eslintrc or phpcs.xml.dist.

In all cases, the files that would be managed by this plugin should be committed to the application's repository. This plugin does not automatically update these files - it only provides a Composer command you can use to update them -- you should do this periodically, then review and commit the resulting changes.

Installation

Install this plugin in your application with Composer:

composer require --dev lastcall/composer-upstream-files

Usage

Upstream files are defined in the extra section of your composer.json. Example:

{
  "name": "my-awesome-site",
  "require": {
    "my/package": "^1.0.0"
  },
  "extra": {
    "upstream-files": {
      "files": {
        "https://raw.githubusercontent.com/LastCallMedia/Drupal-Scaffold/circle20/.editorconfig": ".editorconfig",
        "https://raw.githubusercontent.com/LastCallMedia/Drupal-Scaffold/circle20/web/.htaccess": "web/.htaccess"
      }
    }
  }
}

In this example, we've defined two files with upstream sources. The key of the files array is the source, and the value is the destination. When we run composer upstream-files:update, both files will be refreshed from their respective URLs. We would then review and commit the changes.

Tokens

This plugin supports using tokens to reduce the amount of stuff you have to type and update. Tokens are enclosed in double brackets. Example:

{
  "extra": {
    "upstream-files": {
      "tokens": {
        "scaffold": "https://raw.githubusercontent.com/LastCallMedia/Drupal-Scaffold",
        "drupal": "https://raw.githubusercontent.com/drupal/drupal/{{drupal/core.version}}"
      },
      "files": {
        "{{drupal}}/index.php": "web/index.php",
        "{{scaffold}}/.editorconfig": ".editorconfig"
      }
    }
  }
}

You can define any tokens you want to use under the tokens key, and use them as replacements for your files. Additionally, you can reference the current version of any installed package by using {{PACKAGENAME.version}} (as we did with drupal/core above). Tokens are replaced recursively, so if your token contains a token, that's fine.

Manifests

You can also reference "manifests", or JSON files that contain an upstream-files specification. These manifests can be local or remote. See this example:

// composer.json
{
  "extra": {
    "upstream-files": {
      "tokens": {
        "scaffoldBranch": "master"
      },
      "manifests": [
        "drupal.json",
        "http://github.com/LastCallMedia/Drupal-Scaffold/upstream-files.json"
      ]
    }
  }
}
// drupal.json
{
  "tokens": {
    "drupal": "https://raw.githubusercontent.com/drupal/drupal/{{drupal/core.version}}"
  },
  "files": {
    "{{drupal}}/index.php": "web/index.php",
  }
}
// http://github.com/LastCallMedia/Drupal-Scaffold/upstream-files.json
{
  "tokens": {
    "scaffold": "https://raw.githubusercontent.com/LastCallMedia/Drupal-Scaffold/{{scaffoldBranch}}"
  },
  "files": {
    "{{scaffold}}/.editorconfig": ".editorconfig"
  }
}

Manifests can also specify other manifests, which is handy when you need to specify a lot of files.

Exclusions

It is also possible to exclude files based on their source or destination. This is most useful when you use manifests from upstream projects, and don't want to pull in certain files from upstream:

{
  "extra": {
    "upstream-files": {
      "manifests": [
        "drupal.json",
      ],
      "sourceExcludes": [
        "@LastCallMedia/Drupal-Scaffold@"
      ],
      "destinationExcludes": [
        "/\\.gitattributes/"
      ]
    }
  }
}

The sourceExcludes and destinationExcludes properties are both arrays of regular expressions indicating the files you wish to exclude. sourceExcludes will be matched against the fully resolved source URL, and destinationExcludes will be matched against the fully resolved destination path.

composer-upstream-files's People

Contributors

rbayliss avatar

Stargazers

 avatar  avatar

Watchers

 avatar  avatar  avatar

Forkers

diegoluisr

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.