👷 Using Bricks
In this section, we'll take a look at how to use the make
command to generate code from an existing brick.
🚀 Overview
As we saw in the overview, we can run the mason make
command followed by the name of an installed brick to generate code from that brick:
mason make hello
? What is your name? (Dash) Mason
✓ Generated 1 file. (29ms)
created HELLO.md
🧑💻 Command-line Args
By default, if a brick requires variables mason
will prompt for those variables as seen in the snippet above. If we know in advance what variables a brick requires, we can provide variables to mason
as command-line arguments:
mason make hello --name Mason
✓ Generated 1 file. (29ms)
created HELLO.md
Notice how in the above example, mason
did not prompt for the name since it was already provided as an argument.
In cases where there are multiple variables, it's possible to supply any number of variables directly as command-line args and mason
will prompt for any missing variables automatically.
📝 Config File
In some cases, it may be inconvenient to have to provide variables manually or via command-line args (especially for templates that require many variables). In these cases, we can provide variables via a configuration file. For example, if we create a file called config.json
with the following contents:
{
"name": "Mason"
}
We can then pass the config file to mason make
via the -c
option:
mason make hello -c config.json
✓ Generated 1 file. (29ms)
created HELLO.md
The configuration file can have any name and can live anywhere on your local file system.
🗂 Custom Output Directory
By default mason make
will generate the output in the current working directory but a custom output directory can be specified via the -o
option:
mason make hello --name Mason -o ./out
✓ Generated 1 file. (29ms)
created out/HELLO.md
mason
will automatically create any missing directories for you if you specify an output directory which doesn't already exist.
❗️ File Conflict Resolution
A conflict can occur when mason
attempts to generate a file which already exists and the contents of the existing file differ from the contents of the generated file.
mason make hello --name Dash
conflict HELLO.md
Overwrite HELLO.md? (Yyna) y
✓ Generated 1 file. (21.6s)
created HELLO.md
HELLO.md
- Hello Mason! 👋
+ Hello Dash! 👋
By default, mason make
will prompt on each file conflict and will allow users to specify how the conflict should be resolved via the following options:
y - yes, overwrite (default)
Y - yes, overwrite this and all others
n - no, do not overwrite
a - append to existing file
✅ Conflict Resolution Strategy
A custom file conflict resolution strategy can be specified via the --on-conflict
option:
# Always prompt when there is a file conflict (default)
mason make hello --name Mason --on-conflict prompt
# Always overwrite when there is a file conflict
mason make hello --name Mason --on-conflict overwrite
# Always skip when there is a file conflict
mason make hello --name Mason --on-conflict skip
# Always append when there is a file conflict
mason make hello --name Mason --on-conflict append
🕵️ Detecting Changes
In some cases, it may be useful to detect whether running mason make
for a given brick produces a diff. For example, you may want to add a step in a continuous integration workflow which runs mason make
for a given brick to ensure developers ran a codegen step prior to opening a pull request. The --set-exit-if-changed
flag will exit with an error code if any files were changed after running mason make
:
# 🚨 Exit with error if any files were changed
mason make hello --name Dash --set-exit-if-changed