Custom export_as paths in starter kit config

[jesseleite]

Add ability to specify custom export_as paths in starter-kit.yaml config.

For example, if your sandbox site has a README.md that you want installed into the user's app on starter-kit:install, but you don't want it to conflict with the separate README.md in your exported starter kit repo, you can export_as:

export_paths:
  - config
  - content
  - resources/views
export_as:
  file-in-sandbox.md: file-in-exported-repo.md
  README.md: README-for-new-site.md

This will instruct starter-kit:export to rename each of those paths on export, and in reverse on starter-kit:install to match where you had them in your sandbox app.

Closes #4313.

[jesseleite]

@robdekort @duncanmcclean How's that look fellas 🙂

[robdekort]

That looks great. Thank you! I'm wondering if export_as will overwrite any existing files? For example the Statamic readme. Or maybe even the .env? Not sure if the latter is wise as folks could've made adjustments to it already.

[jesseleite]

Good call. I have already some basic composer.json handling to prevent it from getting exported and overwritten on install. Makes sense to do the same with .env. That said @robdekort, what did you mean by needing to provide a correct .env in your comment here? #4313 (comment)

[robdekort]

Gotcha. Ok. This is just coming one use case (also mine) which would be statamic new my_site studio1902/statamic-peak. Currently Peak ships with a README.example.md file which I would like to overwrite the original README.md. However I understand this is not always desirable. Folks could just be playing around installing kits onto a fresh Statamic install and it would leave them with a README.md that doesn't make sense when you decide you don't want to use Peak, or Simple Commerce, or any other kit.

The same is true for .env. Whenever I start a new Peak install I don't just want the README.md to be overwritten, but also the .env.example to overwrite the existing .env file. The same objections apply. It's only useful in one use case and for others it would be confusing. Especially when they already had a .env file connecting them to a broadcast thing, an s3 service or whatever.

When you know what you're doing, having those files get overwritten makes it easy for folks to use all of the kit's features. For reference. Those files contain roughly the following:

• statamic-peak/README.example.md: link to the docs, install instructions, deploy scripts for Forge and Ploi and spots do dump both dev/prod .env structures without sensitive data.
• statamic-peak/.env.example: extra variables for caching, configuration, assets, image processing and white labeling.

What if you could flag a starter kit install with something like --force, or --overwrite-files? That way it would suit regular users and power users who just want to get cracking.

• statamic new my_site studio1902/statamic-peak: installs the kit, follows copy instructions, won't overwrite files.
• statamic new my_site studio1902/statamic-peak --overwrite-files: installs the kit, follows copy instructions, will overwrite files

Hope this helps explain my thoughts about it. ❤️

[duncanmcclean]

Looks great! Exactly what I need.

[jesseleite]

@robdekort I think the overwriting stuff you mention is a separate conversation to what this PR is trying to solve, which is to control the export paths of specific files and directories to prevent conflict between something like a starter kit README and an app README that's installed by the starter kit. This PR accomplishes that 👍

Regarding the overwriting of files though, I think at this point it's necessary. For example, if a starter kit wants to setup an asset container for a user, it's currently necessary for the starter kit to install a filesystems.php config. I have plans to allow kits to update config programatically without having to maintain and/or overwrite whole config files, but that's for another time. Until then, any changes the user doesn't want from a starter kit installation, they can discard before committing.

[robdekort]

I think I misunderstood Duncan's initial issue/FR then. Good it's solved though 👍.

[duncanmcclean]

Just want to check - if I have a README.example.md file in my starter kit and I want to publish it as README.md in the user's site, will this PR do that?

[jesseleite]

@duncanmcclean Yes. So with this...

export_as:
  file-in-site.md: file-in-exported-repo.md
  README.md: README.example.md

The README.md in your sandbox site would get exported to README.example.md in your starter kit repo, then installed back to README.md in the end user's site.

[duncanmcclean]

Okay... so if the user's end site also had a README.md file (it probably will because every site is based on statamic/statamic), my README.md would end up replacing that?

[jesseleite]

Yep 👍