copier copy --include option

[FourierMourier]

Actual Situation

Hi!
It would be great to have an "include" option to include files to be updated/copied to avoid overwriting unnecessary files.
So far, I've seen only the '--exclude' option and I can simulate the desired behavior by specifying all files except target ones, but when there are lots of files it becomes either more and more inconvenient or less intuitive.

Desired Situation

Ideally, it would be nice to have something like

copier copy --include myfile.txt --include "*.yaml"

and as the result, only the selected files will be copied/updated.

Proposed solution

As a proposed solution, I think just another option would fit the case.
I'm aware of using negative patterns like the ones mentioned in the issue #1794 but I'm not sure that it's an intuitive way to go

[sisp]

Thanks for suggesting this enhancement, @FourierMourier! 🙏

IIUC, --include myfile.txt --include '*.yaml' is exactly equivalent to --exclude '!myfile.txt' --exclude '!*.yaml'. Right? So, it would merely be a matter of some minor convenience to introduce the --include flag.

I'm not convinced yet about this addition for a few reasons:

• We'd introduce ambiguity, as the same outcome could be achieved in two ways. This might cause confusion for template users about the "right" way of excluding/including files.
• We'd probably have to add an _include setting in copier.yaml and an include: Sequence[str] argument to the relevant Python API for consistency. But that means ambiguity in even more places.
• --exclude (and _exclude/exclude: Sequence[str]) is conceptually equivalent to, e.g., .gitignore. Adding --include feels like introducing something like .gitinclude (or however it might be called), which doesn't exist and would probably cause confusion, too.

What are use cases for using only --include without a preceding --exclude? Off the top of my head, I can only think of overriding some excludes in the template's _exclude setting. Do you have a practical example?

[FourierMourier]

Hi! Thanks for the response!
Regarding equivalency between 2 excludes and include - practically yes, I just didn't find that in the docs and eventually ended up looking here :) ; there's a section about exclude but wouldn't it be better to cover the include replacement too?
About use cases/practical examples: let's suppose you have quite a template project and you need to update just certain files and for other developers --include update.me --include update_dir/* would seem more reasonable than doing so via exclude (even though it's not that a big deal). So, given the equivalency, I guess now it's more about overall clarity rather than functionality

[sisp]

Does your example assume --exclude '*' --exclude '!update.me' --exclude '!update_dir/*, i.e. include only those two paths?

[FourierMourier]

Sure! This workaround works; I just wondered whether there's a way to improve convenience/clarity regarding this behavior