Skip to content

Commit

Permalink
feat(cli): add garden create project/module commands
Browse files Browse the repository at this point in the history 
See the docs and CLI help texts for details. The generated configs
contain the full project/module config schema (minus deprecated fields),
so users can easily uncomment and/or remove fields depending on their
needs.

This required a bit of refactoring in our docs generation code, so a
bunch of the line changes relate to that. Also needed to make all links
in field descriptions absolute, and tweak the line breaks and formatting
for readability.
  • Loading branch information
@edvald
edvald committed Feb 14, 2020
1 parent f27ecd0 commit def652c
Show file tree
Hide file tree
Showing 77 changed files with 3,387 additions and 1,888 deletions.
116 changes: 49 additions & 67 deletions docs/module-types/conftest.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ title: conftest
Creates a test that runs `conftest` on the specified files, with the specified (or default) policy and
namespace.

> Note: In many cases, you'll let specific conftest providers (e.g. [`conftest-container`](../providers/conftest-container.md) and [`conftest-kubernetes`](../providers/conftest-kubernetes.md) create this module type automatically, but you may in some cases want or need to manually specify files to test.
> Note: In many cases, you'll let specific conftest providers (e.g. [`conftest-container`](https://docs.garden.io/providers/conftest-container) and [`conftest-kubernetes`](https://docs.garden.io/providers/conftest-kubernetes) create this module type automatically, but you may in some cases want or need to manually specify files to test.
See the [conftest docs](https://github.com/instrumenta/conftest) for details on how to configure policies.

Expand Down Expand Up @@ -36,55 +36,53 @@ type:
# The name of this module.
name:

# A description of the module.
description:

# Set this to `true` to disable the module. You can use this with conditional template strings to
# disable modules based on, for example, the current environment or other variables (e.g.
# `disabled: \${environment.name == "prod"}`). This can be handy when you only need certain modules for
# specific environments, e.g. only for development.
# Set this to `true` to disable the module. You can use this with conditional template strings to disable modules
# based on, for example, the current environment or other variables (e.g. `disabled: \${environment.name == "prod"}`).
# This can be handy when you only need certain modules for specific environments, e.g. only for development.
#
# Disabling a module means that any services, tasks and tests contained in it will not be deployed or run.
# It also means that the module is not built _unless_ it is declared as a build dependency by another enabled
# module (in which case building this module is necessary for the dependant to be built).
# Disabling a module means that any services, tasks and tests contained in it will not be deployed or run. It also
# means that the module is not built _unless_ it is declared as a build dependency by another enabled module (in which
# case building this module is necessary for the dependant to be built).
#
# If you disable the module, and its services, tasks or tests are referenced as _runtime_ dependencies, Garden
# will automatically ignore those dependency declarations. Note however that template strings referencing the
# module's service or task outputs (i.e. runtime outputs) will fail to resolve when the module is disabled,
# so you need to make sure to provide alternate values for those if you're using them, using conditional
# expressions.
# If you disable the module, and its services, tasks or tests are referenced as _runtime_ dependencies, Garden will
# automatically ignore those dependency declarations. Note however that template strings referencing the module's
# service or task outputs (i.e. runtime outputs) will fail to resolve when the module is disabled, so you need to make
# sure to provide alternate values for those if you're using them, using conditional expressions.
disabled: false

# Specify a list of POSIX-style paths or globs that should be regarded as the source files for this
# module. Files that do *not* match these paths or globs are excluded when computing the version of the module,
# when responding to filesystem watch events, and when staging builds.
# Specify a list of POSIX-style paths or globs that should be regarded as the source files for this module. Files that
# do *not* match these paths or globs are excluded when computing the version of the module, when responding to
# filesystem watch events, and when staging builds.
#
# Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your
# source tree, which use the same format as `.gitignore` files. See the
# [Configuration Files
# Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source
# tree, which use the same format as `.gitignore` files. See the [Configuration Files
# guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details.
#
# Also note that specifying an empty list here means _no sources_ should be included.
include:

# Specify a list of POSIX-style paths or glob patterns that should be excluded from the module. Files that
# match these paths or globs are excluded when computing the version of the module, when responding to filesystem
# watch events, and when staging builds.
# Specify a list of POSIX-style paths or glob patterns that should be excluded from the module. Files that match these
# paths or globs are excluded when computing the version of the module, when responding to filesystem watch events,
# and when staging builds.
#
# Note that you can also explicitly _include_ files using the `include` field. If you also specify the
# `include` field, the files/patterns specified here are filtered from the files matched by `include`. See the
# [Configuration Files
# guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details.
# Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include`
# field, the files/patterns specified here are filtered from the files matched by `include`. See the [Configuration
# Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for
# details.
#
# Unlike the `modules.exclude` field in the project config, the filters here have _no effect_ on which files
# and directories are watched for changes. Use the project `modules.exclude` field to affect those, if you have
# large directories that should not be watched for changes.
# Unlike the `modules.exclude` field in the project config, the filters here have _no effect_ on which files and
# directories are watched for changes. Use the project `modules.exclude` field to affect those, if you have large
# directories that should not be watched for changes.
exclude:

# A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific
# branch or tag, with the format: <git remote url>#<branch|tag>
#
# Garden will import the repository source code into this module, but read the module's
# config from the local garden.yml file.
# Garden will import the repository source code into this module, but read the module's config from the local
# garden.yml file.
repositoryUrl:

# When false, disables pushing this module to remote registries.
Expand All @@ -94,12 +92,14 @@ allowPublish: true
build:
# A list of modules that must be built before this module is built.
dependencies:
# Module name to build ahead of this module.
- name:
- # Module name to build ahead of this module.
name:

# Specify one or more files or directories to copy from the built dependency to this module.
copy:
# POSIX-style path or filename of the directory or file(s) to copy to the target.
- source:
- # POSIX-style path or filename of the directory or file(s) to copy to the target.
source:

# POSIX-style path or filename to copy the directory or file(s), relative to the build directory.
# Defaults to to same as source path.
target: ''
Expand Down Expand Up @@ -166,40 +166,29 @@ name: "my-sweet-module"

#### `description`

A description of the module.

| Type | Required |
| -------- | -------- |
| `string` | No |

#### `disabled`

Set this to `true` to disable the module. You can use this with conditional template strings to
disable modules based on, for example, the current environment or other variables (e.g.
`disabled: \${environment.name == "prod"}`). This can be handy when you only need certain modules for
specific environments, e.g. only for development.
Set this to `true` to disable the module. You can use this with conditional template strings to disable modules based on, for example, the current environment or other variables (e.g. `disabled: \${environment.name == "prod"}`). This can be handy when you only need certain modules for specific environments, e.g. only for development.

Disabling a module means that any services, tasks and tests contained in it will not be deployed or run.
It also means that the module is not built _unless_ it is declared as a build dependency by another enabled
module (in which case building this module is necessary for the dependant to be built).
Disabling a module means that any services, tasks and tests contained in it will not be deployed or run. It also means that the module is not built _unless_ it is declared as a build dependency by another enabled module (in which case building this module is necessary for the dependant to be built).

If you disable the module, and its services, tasks or tests are referenced as _runtime_ dependencies, Garden
will automatically ignore those dependency declarations. Note however that template strings referencing the
module's service or task outputs (i.e. runtime outputs) will fail to resolve when the module is disabled,
so you need to make sure to provide alternate values for those if you're using them, using conditional
expressions.
If you disable the module, and its services, tasks or tests are referenced as _runtime_ dependencies, Garden will automatically ignore those dependency declarations. Note however that template strings referencing the module's service or task outputs (i.e. runtime outputs) will fail to resolve when the module is disabled, so you need to make sure to provide alternate values for those if you're using them, using conditional expressions.

| Type | Default | Required |
| --------- | ------- | -------- |
| `boolean` | `false` | No |

#### `include`
#### `include[]`

Specify a list of POSIX-style paths or globs that should be regarded as the source files for this
module. Files that do *not* match these paths or globs are excluded when computing the version of the module,
when responding to filesystem watch events, and when staging builds.
Specify a list of POSIX-style paths or globs that should be regarded as the source files for this module. Files that do *not* match these paths or globs are excluded when computing the version of the module, when responding to filesystem watch events, and when staging builds.

Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your
source tree, which use the same format as `.gitignore` files. See the
[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details.
Note that you can also _exclude_ files using the `exclude` field or by placing `.gardenignore` files in your source tree, which use the same format as `.gitignore` files. See the [Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories) for details.

Also note that specifying an empty list here means _no sources_ should be included.

Expand All @@ -215,19 +204,13 @@ include:
- my-app.js
```

#### `exclude`
#### `exclude[]`

Specify a list of POSIX-style paths or glob patterns that should be excluded from the module. Files that
match these paths or globs are excluded when computing the version of the module, when responding to filesystem
watch events, and when staging builds.
Specify a list of POSIX-style paths or glob patterns that should be excluded from the module. Files that match these paths or globs are excluded when computing the version of the module, when responding to filesystem watch events, and when staging builds.

Note that you can also explicitly _include_ files using the `include` field. If you also specify the
`include` field, the files/patterns specified here are filtered from the files matched by `include`. See the
[Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details.
Note that you can also explicitly _include_ files using the `include` field. If you also specify the `include` field, the files/patterns specified here are filtered from the files matched by `include`. See the [Configuration Files guide](https://docs.garden.io/guides/configuration-files#including-excluding-files-and-directories)for details.

Unlike the `modules.exclude` field in the project config, the filters here have _no effect_ on which files
and directories are watched for changes. Use the project `modules.exclude` field to affect those, if you have
large directories that should not be watched for changes.
Unlike the `modules.exclude` field in the project config, the filters here have _no effect_ on which files and directories are watched for changes. Use the project `modules.exclude` field to affect those, if you have large directories that should not be watched for changes.

| Type | Required |
| ------------------ | -------- |
Expand All @@ -245,8 +228,7 @@ exclude:

A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: <git remote url>#<branch|tag>

Garden will import the repository source code into this module, but read the module's
config from the local garden.yml file.
Garden will import the repository source code into this module, but read the module's config from the local garden.yml file.

| Type | Required |
| ----------------- | -------- |
Expand Down Expand Up @@ -361,7 +343,7 @@ The policy namespace in which to find _deny_ and _warn_ rules.
| -------- | -------- | -------- |
| `string` | `"main"` | No |

#### `files`
#### `files[]`

A list of files to test with the given policy. Must be POSIX-style paths, and may include wildcards.

Expand Down
Loading

0 comments on commit def652c

Please sign in to comment.