Add composability convention, WIP

[mhkeller]

This PR adds a convention whereby you can modify a repo post-clone in a safe way, or combine two repos, which is neat because you can start to create variations on a scaffold in a modular way. It's a work in progress with some TODOs noted at the bottom and I'm open to other ideas on how it should work! This is a proof of concept that seems to cover my use cases for it so seemed like a good starting point to see if it's worthwhile to include in this project.

How it currently works

Let's say you do degit mhkeller/degit-example where that repo contains only a file called degit.json that looks like the following, it will clone down the specified repo and then remove the specified files.

[
  {
    "action": "clone",
    "values": [
      {"src": "my-org/project-scaffold", "opts": {}}
    ]
  },
  {
    "action": "remove",
    "values": [
      "CONTRIBUTING.md",
      "DCO.md",
      "LICENSE",
      "CHANGELOG.md"
    ]
  }
]

If you have other files in mhkeller/degit-example, they will be written on top of the cloned repo. IN this way, if you want to include your own README.md, you can include that in the repo you run degit on and they'll appear in your local directory when all is done running.

TODO / questions

• • File copying and removing should support directories also. The lazy option would be to use fs-extra but can also do a vanilla implementation (or copy the good bits from fs-extra) Done via sander in 688a390 d0639f2
• • I added a warn event to warn when you want to remove a file that doesn't exist. It's magenta. Seems like a good idea??

• • Add tests mhkeller@7f7e201 mhkeller@a8a29c8
• • Not sure if degit.json is the best naming convention. Open to others or for it to be configurable, it's currently hardcoded Added the name in src/utils.js so it's more configurable.
• • Similarly, maybe json isn't the best format. Maybe yaml, or maybe it looks for degit.json and then degit.yaml / degit.yml if it doesn't exist? Keep it as json for now
• • Maybe the format of degit.json as a list of actions is not flexible for other or future options. Maybe it should be an object with a actions as a list but allow for other top-level options that I haven't thought of? Add composability convention, WIP #28 (comment)

[mhkeller]

Switched up the degit.json convention to be the following. Also added it so that any subsequent clone is called with force: true.

[
  {
    "action": "clone",
    "src": "my-org/project-scaffold"
  },
  {
    "action": "remove",
    "files": [
      "CONTRIBUTING.md",
      "DCO.md",
      "LICENSE",
      "CHANGELOG.md"
    ]
  }
]

[mhkeller]

All set minus tests.

[mhkeller]

Added tests via mhkeller@a8a29c8 and mhkeller@7f7e201 plus some other edge case stuff.

The only question I have left is what to do about README.md files. I could see both someone wanting a README.md in their repo that contains a degit.json file to have that that readme be preserved AND someone who wants a README.md to explain how to initialize the project but expects that to be overwritten by the readme in the cloned project.

Maybe it's an option on the clone action such as:

{
  action: "clone",
  src: "test/repo",
  useReadme: true
}

That way if you're cloning multiple you could decide which readme you want. The only problem I could see is if you're cloning a repo that is also a degit.json-ified repo and it is cloning down something with useReadme: true and you get a conflict. A solution could be that setting useReadme: false cascades down for all cloned children from that action. I think that could work.

[Rich-Harris]

wooot!!! 🎉

Added a README section and released 2.1.0.

I'm not sure about useReadme, it seems very special-case. Maybe a way to handle that would be to have a rename action? In fact, I'll open a new issue to brainstorm additional actions that might be useful

[mhkeller]

Actually, the use case I described would be easily handled by doing a remove on that readme before the clone. So ya, I think between that and a rename action you'd handle all the use cases.