feat(core): add include property specifying particular files for assets

[go-to-k]

This PR adds an include property including particular files for assets such as lambda.Code.fromAsset.

• Add an include parameter to interface FileOptions with exclude.
• Check for matching include along with ignores (actually exclude) in copyDirectory, where the actual file search is done.

Closes #26107.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[rittneje]

I think it would help to add some more detail here.

1. How does this interact with exclude? That is, if a file matches something in include and exclude, what happens? My assumption is that exclude takes priority but it would be nice to mention that explicitly.
2. How does this interact with symlinks when using a SymlinkFollowMode other than NEVER? That is, if I include the symlink but not its target, what happens?

It would also be good to add test cases for these points.

[go-to-k]

@rittneje

Thanks! I added the docs and tests.

1. exclude takes priority if both include and exclude are matched.
   • 5dedfcb
   • d16369c
2. If matching the symlink but not its target, it is included even if SymlinkFollowMode is NEVER or not. This is based on the same checking the exclude patterns.
   • bf41fa9
   • 454b69b

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: d16369c
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[tmokmss]

Can't we just use exclude with a negation pattern to get the behavior?

include: ['index.py'],
// this should be equivalent to the following
exclude: ['*', '!index.py']

I am not entirely convinced that it is a good idea to have both include and exclude properties, because it is not clear what the priority is between include and exclude, and how to handle files that do not match both include and exclude, which will confuse users.

[rittneje]

@tmokmss Negative exclusions aren't even documented. If that's going to be the solution (which I don't like because it's more confusing to have to think in terms of double negation), then the docs still should be amended.

[tmokmss]

@rittneje
It is deliberately supported even in glob patterns, so I don't see much reason not to use it :)

aws-cdk/packages/aws-cdk-lib/core/lib/fs/ignore.ts

Lines 122 to 124 in eea223b

	for (const pattern of this.patterns) {
	const negate = pattern.startsWith('!');
	const match = minimatch(relativePath, pattern, { matchBase: true, flipNegate: true });

I think using a negation in ignore files (like .gitignore or .dockerignore) is a common pattern, but yeah, we might need a clearer doc on this.

[go-to-k]

@tmokmss Hmmm, I was confused too, but you may be right! Then I would close this PR.

[go-to-k]

As for the document, I'll consider it in another PR.

[go-to-k]

I submitted the PR for the docs of exclude property using a negation.