Skip to content

Commit ad8c76d

Browse files
ecraig12345ecraig12345
committed
Update docs about glob matching
1 parent 75bb256 commit ad8c76d

File tree

3 files changed

+54
-42
lines changed

3 files changed

+54
-42
lines changed

‎.vscode/settings.json

+2-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@
1010
"search.exclude": {
1111
"**/node_modules": true,
1212
"**/lib": true,
13-
"**/*.svg": true
13+
"**/*.svg": true,
14+
"**/.yarn": true
1415
},
1516
"files.associations": {
1617
// VS Code doesn't have json5 support, so handle .json5 files as jsonc.

‎docs/concepts/groups.md

+14-12
Original file line numberDiff line numberDiff line change
@@ -28,12 +28,12 @@ For cases where it's necessary to bump packages together, `beachball` also provi
2828

2929
Groups can be added to the [configuration file](../overview/configuration). See the [`VersionGroupOptions` source](https://github.com/microsoft/beachball/blob/master/src/types/ChangelogOptions.ts) for full details.
3030

31-
| Name | Type | Description |
32-
| ----------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
33-
| `name` | `string` | Name of the version group |
34-
| `include` | `string \| string[] \| true` | minimatch pattern(s) for package paths to include in this group. Patterns are relative to the repo root and must use forward slashes. If `true`, include all packages except those matching `exclude`. |
35-
| `exclude` | `string \| string[]` | minimatch pattern(s) for package paths to include in this group. Patterns are relative to the repo root and must use forward slashes. Currently this must use **negated patterns only** (will be fixed in the next major version). |
36-
| `disallowedChangeTypes` | `ChangeType[] \| null` | Disallow these change types for the group. |
31+
| Name | Type | Description |
32+
| ----------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
33+
| `name` | `string` | Name of the version group |
34+
| `include` | `string \| string[] \| true` | glob pattern(s) for package paths to include (see [notes on globs][1]). If `true`, include all packages except those matching `exclude`. |
35+
| `exclude` | `string \| string[]` | glob pattern(s) for package paths to exclude (see [notes on globs][1]). |
36+
| `disallowedChangeTypes` | `ChangeType[] \| null` | Disallow these change types for the group. |
3737

3838
Example:
3939

@@ -58,12 +58,12 @@ If you only want to publish or record changes for certain packages, you should u
5858

5959
To show changes for multiple packages in one change file, use the `changelog.groups` option. See the [`ChangelogGroupOptions` source](https://github.com/microsoft/beachball/blob/master/src/types/ChangelogOptions.ts) for full details.
6060

61-
| Name | Type | Description |
62-
| ------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
63-
| `masterPackageName` | `string` | The main package which a group of changes bubbles up to. |
64-
| `include` | `string \| string[] \| true` | minimatch pattern(s) for package paths to include in this group. Patterns are relative to the repo root and must use forward slashes. If `true`, include all packages except those matching `exclude`. |
65-
| `exclude` | `string \| string[]` | minimatch pattern(s) for package paths to exclude from this group. Patterns are relative to the repo root and must use forward slashes. Currently this must use **negated patterns only** (will be fixed in the next major version). |
66-
| `changelogPath` | `string` | Put the grouped changelog file under this directory. Can be relative to the root, or absolute. |
61+
| Name | Type | Description |
62+
| ------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
63+
| `masterPackageName` | `string` | The main package which a group of changes bubbles up to. |
64+
| `include` | `string \| string[] \| true` | glob pattern(s) for package paths to include (see [notes on globs][1]). If `true`, include all packages except those matching `exclude`. |
65+
| `exclude` | `string \| string[]` | glob pattern(s) for package paths to exclude (see [notes on globs][1]). |
66+
| `changelogPath` | `string` | Put the grouped changelog file under this directory. Can be relative to the root, or absolute. |
6767

6868
In this example, changelogs for all packages under `packages/*` (except `packages/baz`) are written to a `CHANGELOG.md` at the repo root (`.`), with `foo` as the master package. (To replace `foo`'s usual changelog with a grouped one, you'd specify `changelogPath` as the path to `foo` instead, e.g. `packages/foo`.)
6969

@@ -99,3 +99,5 @@ Tue, 19 Nov 2024 08:03:08 GMT
9999
- `bar`
100100
- bar change ([email protected])
101101
```
102+
103+
[1]: ../overview/configuration#glob-matching

‎docs/overview/configuration.md

+38-29
Original file line numberDiff line numberDiff line change
@@ -71,46 +71,55 @@ For the latest full list of supported options, see `RepoOptions` [in this file](
7171

7272
"Applies to" indicates where the settings can be specified: repo-level config or package-level config.
7373

74-
| Option | Type | Default | Applies to | Description |
75-
| ----------------------- | ------------------------------ | -------------- | ------------- | ------------------------------------------------------------------------------------------------ |
76-
| `access` | `'public'` or `'restricted'` | `'restricted'` | repo | publish access level for scoped package names (e.g. `@foo/bar`) |
77-
| `branch` | `string` | [see notes][5] | repo | target branch; [see notes][5] |
78-
| `bumpDeps` | `boolean` | `true` | repo | bump dependent packages during publish (if B is bumped, and A depends on B, also bump A) |
79-
| `changeFilePrompt` | [`ChangeFilePromptOptions`][1] | | repo | customize the prompt for change files (can be used to add custom fields) |
80-
| `changehint` | `string` | | repo | hint message for when change files are not detected but required |
81-
| `changeDir` | `string` | `change` | repo | directory where change files are stored (relative to repo root) |
82-
| `changelog` | [`ChangelogOptions`][2] | | repo | changelog rendering and grouping options |
83-
| `defaultNpmTag` | `string` | `'latest'` | repo, package | the default dist-tag used for NPM publish |
84-
| `disallowedChangeTypes` | `string[]` | | repo, package | what change types are disallowed |
85-
| `fetch` | `boolean` | `true` | repo | fetch from remote before doing diff comparisons |
86-
| `generateChangelog` | `boolean \| 'md' \| 'json'` | `true` | repo | whether to generate `CHANGELOG.md/json` (`'md'` or `'json'` to generate only that type) |
87-
| `gitTags` | `boolean` | `true` | repo, package | whether to create git tags for published packages (eg: foo_v1.0.1) |
88-
| `groups` | [`VersionGroupOptions[]`][3] | | repo | bump these packages together ([see details][3]) |
89-
| `groupChanges` | `boolean` | `false` | repo | write multiple changes to a single changefile |
90-
| `hooks` | [`HooksOptions`][4] | | repo | hooks for custom pre/post publish actions |
91-
| `ignorePatterns` | `string[]` | | repo | ignore changes in these files (minimatch patterns with forward slashes; negations not supported) |
92-
| `package` | `string` | | repo | specifies which package the command relates to (overrides change detection based on `git diff`) |
93-
| `prereleasePrefix` | `string` | | repo | prerelease prefix for packages that are specified to receive a prerelease bump |
94-
| `publish` | `boolean` | `true` | repo | whether to publish to npm registry |
95-
| `push` | `boolean` | `true` | repo | whether to push to the remote git branch |
96-
| `registry` | `string` | | repo | target NPM registry to publish |
97-
| `retries` | `number` | `3` | repo | number of retries for a package publish before failing |
98-
| `scope` | `string[]` | | repo | only consider package paths matching these patterns ([see details](#scoping)) |
99-
| `shouldPublish` | `false \| undefined` | | package | manually disable publishing of a package by beachball (does not work to force publishing) |
100-
| `tag` | `string` | `'latest'` | repo, package | dist-tag for npm when published |
101-
| `transform` | [`TransformOptions`][4] | | repo | transformations for change files |
74+
| Option | Type | Default | Applies to | Description |
75+
| ----------------------- | ------------------------------ | -------------- | ------------- | ----------------------------------------------------------------------------------------------- |
76+
| `access` | `'public'` or `'restricted'` | `'restricted'` | repo | publish access level for scoped package names (e.g. `@foo/bar`) |
77+
| `branch` | `string` | [see notes][5] | repo | target branch; [see notes][5] |
78+
| `bumpDeps` | `boolean` | `true` | repo | bump dependent packages during publish (if B is bumped, and A depends on B, also bump A) |
79+
| `changeFilePrompt` | [`ChangeFilePromptOptions`][1] | | repo | customize the prompt for change files (can be used to add custom fields) |
80+
| `changehint` | `string` | | repo | hint message for when change files are not detected but required |
81+
| `changeDir` | `string` | `change` | repo | directory where change files are stored (relative to repo root) |
82+
| `changelog` | [`ChangelogOptions`][2] | | repo | changelog rendering and grouping options |
83+
| `defaultNpmTag` | `string` | `'latest'` | repo, package | the default dist-tag used for NPM publish |
84+
| `disallowedChangeTypes` | `string[]` | | repo, package | what change types are disallowed |
85+
| `fetch` | `boolean` | `true` | repo | fetch from remote before doing diff comparisons |
86+
| `generateChangelog` | `boolean \| 'md' \| 'json'` | `true` | repo | whether to generate `CHANGELOG.md/json` (`'md'` or `'json'` to generate only that type) |
87+
| `gitTags` | `boolean` | `true` | repo, package | whether to create git tags for published packages (eg: foo_v1.0.1) |
88+
| `groups` | [`VersionGroupOptions[]`][3] | | repo | bump these packages together ([see details][3]) |
89+
| `groupChanges` | `boolean` | `false` | repo | write multiple changes to a single changefile |
90+
| `hooks` | [`HooksOptions`][4] | | repo | hooks for custom pre/post publish actions |
91+
| `ignorePatterns` | `string[]` | | repo | ignore changes in files matching these glob patterns ([see notes][6]) |
92+
| `package` | `string` | | repo | specifies which package the command relates to (overrides change detection based on `git diff`) |
93+
| `prereleasePrefix` | `string` | | repo | prerelease prefix for packages that are specified to receive a prerelease bump |
94+
| `publish` | `boolean` | `true` | repo | whether to publish to npm registry |
95+
| `push` | `boolean` | `true` | repo | whether to push to the remote git branch |
96+
| `registry` | `string` | | repo | target NPM registry to publish |
97+
| `retries` | `number` | `3` | repo | number of retries for a package publish before failing |
98+
| `scope` | `string[]` | | repo | only consider package paths matching these patterns ([see details](#scoping)) |
99+
| `shouldPublish` | `false \| undefined` | | package | manually disable publishing of a package by beachball (does not work to force publishing) |
100+
| `tag` | `string` | `'latest'` | repo, package | dist-tag for npm when published |
101+
| `transform` | [`TransformOptions`][4] | | repo | transformations for change files |
102102

103103
[1]: https://github.com/microsoft/beachball/blob/master/src/types/ChangeFilePrompt.ts
104104
[2]: https://github.com/microsoft/beachball/blob/master/src/types/ChangelogOptions.ts
105105
[3]: ../concepts/groups#version-groups
106106
[4]: https://github.com/microsoft/beachball/blob/master/src/types/BeachballOptions.ts
107107
[5]: #determining-the-target-branch-and-remote
108+
[6]: #glob-matching
109+
110+
### Glob matching
111+
112+
Glob matching is implemented using [`minimatch`](https://www.npmjs.com/package/minimatch), which supports most glob syntax.
113+
114+
All glob patterns are relative to the repo or monorepo root and must use **forward slashes only**.
115+
116+
Unless otherwise noted (such as for `scope`), using gitignore-style negated patterns to modify previous matches is not supported.
108117

109118
### Scoping
110119

111120
The `scope` option allows limiting which packages are considered. You can set it in the config file if it should always apply, or on the command line for a specific operation.
112121

113-
This option takes a list of patterns which are matched against package paths. Patterns are relative to the monorepo root and must use forward slashes. Negations are supported.
122+
This option takes a list of patterns which are matched against package paths. Patterns are relative to the monorepo root and must use forward slashes. Negations are supported, similar to how gitignore works.
114123

115124
Example: with this config, `beachball` will only consider packages under `packages/foo` (excluding `packages/foo/bar`).
116125

0 commit comments

Comments
 (0)