feat: Add the possibility to exclude files in a mason brick

[Zoltán Katona, PhD]

Description

My understanding is that every single file in a brick is automatically part of that brick, there is no way to tell mason to ignore certain files, directories. The reason, why I have this problem, is that I want to store screenshots in the github repo of the brick and also want to include those screenshots in the README.md file, and for that I want to create a screenshots directory directly in the brick. The content of the brick (files, directories) are direct content of the git respository, in other words the brick is not a subdirectory inside the repository.

The issue with this is that, the size of the mason brick (bundle) gets big because of the screenshots, however they will be referenced directly from the README.md file with a URL pointing to the screenshots in the github repository. These screenshots could be just ignored by the mason brick, but I need to store these files in the same repository where the brick is located.

The potential workarounds I explored:

1. Upload images as issues to github and simply copy the generated links to the README.md file. The problem with this solution is that it is not really a nice way to store images as part of the repository, and links may be changed by github at any time.
2. Create a subdirectory in the repository called brick, put all the content of my mason brick inside, and create the screenshots directory outside of the brick directory. This way, the screenshots are stored in the same repository where the brick is located, and the screenshots would not become a part of the brick and so this could be a nice solution. The problem is that I need to duplicate the README.md file, because there will be one README.md file for the repository and one for the brick. As the repository stores a single brick, they would be exactly the same, and this creates redundancy.
3. Store images in a different repository or on a different service, server. The good thing is that the images would not become a content in the mason brick, but the downside is that images would not be part of the repository, where they naturally belong.

Proposed Solution

Add a plain text file, for example .masonignore, which could have a similar structure as .gitignore. It would contain list of folders, files and wildcards. The referenced directories and files in the .masonignore file would be ignored by mason and would not become a part of the mason brick.

Example content of the .masonbrick file

./screenshots
./requirements/*.docx

[Felix Angelov]

Hi @ka-zo 👋
Thanks for opening an issue!

I personally recommend approach 2 because the whole point of the __brick__ directory is to separate the template from the rest (LICENSE, CHANGELOG, etc.)

If you really want you can use a dynamic file import in the __brick__ to avoid redundancy:

├── __brick__
│   └── {{% readme_url %}}
├── brick.yaml
└── hooks
    ├── pre_gen.dart
    ├── pubspec.lock
    └── pubspec.yaml

import 'package:mason/mason.dart';

void run(HookContext context) {
  context.vars['readme_url'] =
      'https://raw.githubusercontent.com/felangel/mason/master/README.md';
}

Hope that helps! Closing for now but feel free to comment with additional questions/comments and I'm happy to continue the conversation 👍

[Zoltán Katona, PhD]

Hi @felangel ,

Thanks for your reply, I appreciated it a lot, and it also shed light on a misunderstanding, potentially on the need for a documentation update.

First of all, the definition of a brick seems not to be clear. Based on your response, it seems you understood my option No. 2 ("there will be one README.md file for the repository and one for the brick.") as the word brick in my sentence was referring to the __brick__ directory, because in your response you put the {{ readme_url }} inside the __brick__ directory. However this is not what I meant. According to your documentation (Installing Bricks) I interpret the word brick as a package that includes not just the __brick__ directory, but also other files, directories outside of it, like brick.yaml, LICENSE etc. Furthermore, based on the help of the mason command line tool and also the documentation on Unbundle Usage you also use the expression brick template interchangebly with brick. For me a brick template would rather mean an automatically generated brick file and directory structure, that is not yet customized by the developer.

So if you also feel, that there is a misunderstanding here, then the documentation probably needs to be updated, in order to provide a clear definition on what a brick is, and what a brick template is.

On the other hand, coming back to the original problem, I assume that the screenshot directory - that is on the same level as the __brick__ directory - shall probably not be published with the rest of the files, directories in the brick. I also understand that according to the documentation Bundling Bricks / Overview, the universal bundle is the one that shall be published, however the documentation does not say, that just certain files, directories shall be part of the bundle, others, such as the screenshot directory shall not be part of the bundle. I cross-checked this with my own brick by generating a bundle, then by unbundling it. I think the documentation should be updated with this information, as this information would have saved a lot of time for me, and the present issue would not have been opened at all.

Summary

• I recommend updating the documentation by clearly defining what a brick, and a brick template is, and harmonize the documentation and the mason command line tool help accordingly by consistently using these words.
• I recommend adding to the documentation what exactly shall be part of a bundle and what not, and also adding an example, like a screenshots directory can be added to the brick, because it will not be part of the bundle to be published.