Skip to content

Commit 94b880d

Browse files
virgofxvirgofx
authored
docs: enhance README with pattern matching details for module exclusions (#205)
* docs: enhance README with pattern matching details for module exclusions * fix(devcontainer): add default YAML formatter to VSCode settings * fix(action.yml): formatting * fix: formatting
1 parent 7895a07 commit 94b880d

File tree

3 files changed

+101
-33
lines changed

3 files changed

+101
-33
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,9 @@
4141
},
4242
"[javascript]": {
4343
"editor.defaultFormatter": "biomejs.biome"
44+
},
45+
"[yaml]": {
46+
"editor.defaultFormatter": "esbenp.prettier-vscode"
4447
}
4548
}
4649
}

‎README.md‎

Lines changed: 73 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -162,21 +162,21 @@ resources.
162162
While the out-of-the-box defaults are suitable for most use cases, you can further customize the action's behavior by
163163
configuring the following optional input parameters as needed.
164164

165-
| Input | Description | Default |
166-
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
167-
| `major-keywords` | Keywords in commit messages that indicate a major release | `major change,breaking change` |
168-
| `minor-keywords` | Keywords in commit messages that indicate a minor release | `feat,feature` |
169-
| `patch-keywords` | Keywords in commit messages that indicate a patch release | `fix,chore,docs` |
170-
| `default-first-tag` | Specifies the default tag version | `v1.0.0` |
171-
| `terraform-docs-version` | Specifies the terraform-docs version used to generate documentation for the wiki | `v0.19.0` |
172-
| `delete-legacy-tags` | Specifies a boolean that determines whether tags and releases from Terraform modules that have been deleted should be automatically removed | `true` |
173-
| `disable-wiki` | Whether to disable wiki generation for Terraform modules | `false` |
174-
| `wiki-sidebar-changelog-max` | An integer that specifies how many changelog entries are displayed in the sidebar per module | `5` |
175-
| `disable-branding` | Controls whether a small branding link to the action's repository is added to PR comments. Recommended to leave enabled to support OSS. | `false` |
176-
| `module-path-ignore` | Comma separated list of module paths to completely ignore (relative to working directory). This will prevent any versioning, release, or documentation for these modules. | `` (empty) |
177-
| `module-change-exclude-patterns` | A comma-separated list of file patterns to exclude from triggering version changes in Terraform modules. Patterns follow glob syntax (e.g., `.gitignore,_.md`) and are relative to each Terraform module directory. Files matching these patterns will not affect version changes. **WARNING**: Avoid excluding '`_.tf`' files, as they are essential for module detection and versioning processes. | `.gitignore, *.md, *.tftest.hcl, tests/**` |
178-
| `module-asset-exclude-patterns` | A comma-separated list of file patterns to exclude when bundling a Terraform module for tag/release. Patterns follow glob syntax (e.g., `tests/\*\*`) and are relative to each Terraform module directory. Files matching these patterns will be excluded from the bundled output. | `.gitignore, *.md, *.tftest.hcl, tests/**` |
179-
| `use-ssh-source-format` | If enabled, all links to source code in generated Wiki documentation will use SSH standard format (e.g., `git::ssh://git@github.com/owner/repo.git`) instead of HTTPS format (`git::https://github.com/owner/repo.git`) | `false` |
165+
| Input | Description | Default |
166+
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
167+
| `major-keywords` | Keywords in commit messages that indicate a major release | `major change,breaking change` |
168+
| `minor-keywords` | Keywords in commit messages that indicate a minor release | `feat,feature` |
169+
| `patch-keywords` | Keywords in commit messages that indicate a patch release | `fix,chore,docs` |
170+
| `default-first-tag` | Specifies the default tag version | `v1.0.0` |
171+
| `terraform-docs-version` | Specifies the terraform-docs version used to generate documentation for the wiki | `v0.19.0` |
172+
| `delete-legacy-tags` | Specifies a boolean that determines whether tags and releases from Terraform modules that have been deleted should be automatically removed | `true` |
173+
| `disable-wiki` | Whether to disable wiki generation for Terraform modules | `false` |
174+
| `wiki-sidebar-changelog-max` | An integer that specifies how many changelog entries are displayed in the sidebar per module | `5` |
175+
| `disable-branding` | Controls whether a small branding link to the action's repository is added to PR comments. Recommended to leave enabled to support OSS. | `false` |
176+
| `module-path-ignore` | A comma-separated list of module paths to completely ignore during processing. Paths matching these patterns will not be considered for versioning, releases, or documentation generation. | `` (empty string) |
177+
| `module-change-exclude-patterns` | A comma-separated list of file patterns to exclude from triggering version changes in Terraform modules. Patterns follow glob syntax (e.g., `.gitignore,_.md`) and are relative to each Terraform module directory. Files matching these patterns will not affect version changes. **WARNING**: Avoid excluding '`_.tf`' files, as they are essential for module detection and versioning processes. | `.gitignore,*.md,*.tftest.hcl,tests/**` |
178+
| `module-asset-exclude-patterns` | A comma-separated list of file patterns to exclude when bundling a Terraform module for tag/release. Patterns follow glob syntax (e.g., `tests/\*\*`) and are relative to each Terraform module directory. Files matching these patterns will be excluded from the bundled output. | `.gitignore,*.md,*.tftest.hcl,tests/**` |
179+
| `use-ssh-source-format` | If enabled, all links to source code in generated Wiki documentation will use SSH standard format (e.g., `git::ssh://git@github.com/owner/repo.git`) instead of HTTPS format (`git::https://github.com/owner/repo.git`) | `false` |
180180

181181
### Understanding the filtering options
182182

@@ -188,18 +188,75 @@ configuring the following optional input parameters as needed.
188188
- Ignoring documentation-focused modules (e.g., `**/docs/**`)
189189
- Excluding entire directories or paths that contain Terraform files but shouldn't be versioned as modules
190190

191+
**Important pattern matching notes:**
192+
193+
- Patterns are relative to the workspace directory (no leading slash)
194+
- A pattern like `dir/**` will match files and directories INSIDE `dir` but NOT the `dir` directory itself
195+
- To match both a directory and its contents, you need both patterns: `dir,dir/**`
196+
- To exclude a specific directory and all its contents, use: `path/to/directory,path/to/directory/**`
197+
191198
Example:
192199

193200
```yaml
194201
module-path-ignore: "**/examples/**,**/test/**,root-modules"
195202
```
196203

204+
> **Note**:
205+
197206
- **`module-change-exclude-patterns`**: These patterns determine which file changes are _ignored_ when checking if a
198207
module needs a new release. For example, changes to documentation, examples, or workflow files typically don't require
199208
a new module release.
209+
210+
**Key details:**
211+
212+
- Patterns are relative to each **module directory**, not the workspace root
213+
- Uses `matchBase: true` for pattern matching, so `*.md` will match any Markdown file in any subdirectory
214+
- Applied only after a module is identified but before determining if it needs a version change
215+
- Default patterns: `.gitignore, *.md, *.tftest.hcl, tests/**`
216+
- Use this for files that should be part of the module but don't affect its functionality
217+
218+
**Common use cases:**
219+
220+
- Documentation files (`*.md`, `docs/**`)
221+
- Test files (`tests/**`, `*.tftest.hcl`)
222+
- Examples (`examples/**`)
223+
- Metadata files (`.gitignore`, `.gitattributes`)
224+
225+
Example:
226+
227+
```yaml
228+
module-change-exclude-patterns: ".gitignore,*.md,docs/**,examples/**,*.tftest.hcl,tests/**"
229+
```
230+
231+
> **Warning**: Avoid excluding `*.tf` files, as they are essential for module functionality and versioning.
232+
200233
- **`module-asset-exclude-patterns`**: When building a release asset for a module, these patterns determine which files
201234
are _excluded_ from the asset. This helps reduce the asset size by omitting test files, examples, documentation, etc.
202235

236+
**Key details:**
237+
238+
- Patterns are relative to each **module directory**, not the workspace root
239+
- Uses `matchBase: true` for pattern matching (same as `module-change-exclude-patterns`)
240+
- Applied during the bundle/archive creation phase for GitHub releases
241+
- Default patterns: `.gitignore, *.md, *.tftest.hcl, tests/**`
242+
- These patterns do NOT affect versioning decisions - only the contents of release assets
243+
244+
**Common use cases:**
245+
246+
- Test directories and files (`tests/**`, `*.tftest.hcl`)
247+
- Documentation that's not needed for module functionality (`*.md`)
248+
- Development-specific files (`.gitignore`, `CHANGELOG.md`)
249+
- Example code that shouldn't be included in the release (`examples/**`)
250+
251+
Example:
252+
253+
```yaml
254+
module-asset-exclude-patterns: ".gitignore,*.md,examples/**,tests/**,*.tftest.hcl"
255+
```
256+
257+
> **Important**: Unlike `module-change-exclude-patterns`, these patterns only affect what goes into the release asset,
258+
> not whether a release is triggered.
259+
203260
All pattern matching is implemented using [minimatch](https://github.com/isaacs/minimatch), which supports glob patterns
204261
similar to those used in `.gitignore` files. For more details on the pattern matching implementation, see our
205262
[source code](https://github.com/techpivot/terraform-module-releaser/blob/main/src/utils/file.ts) or visit the
@@ -237,7 +294,7 @@ jobs:
237294
delete-legacy-tags: true
238295
disable-wiki: false
239296
wiki-sidebar-changelog-max: 10
240-
module-change-exclude-patterns: .gitignore,*.md,*.tftest.hcl,tests/**
297+
module-change-exclude-patterns: .gitignore,*.md,docs/**,examples/**,*.tftest.hcl,tests/**
241298
module-asset-exclude-patterns: .gitignore,*.md,*.tftest.hcl,tests/**
242299
use-ssh-source-format: false
243300
module-path-ignore: path/to/ignore1,path/to/ignore2

0 commit comments

Comments
 (0)