#Concept: Workspace Patterns

#Overview

Workspace patterns are used to match workspaces when running commands such as run-script or list-workspaces, and they are also used in some configuration options.

Negation is supported by prefixing any pattern with not: or !, the former suggested to avoid shell operator issues. These exclude workspaces from any other patterns provided.

Regular expressions are supported by prefixing any pattern value with re:.

Workspace Pattern Syntax:
[not:][(name|alias|path|tag):][re:]<value>

#Quick Examples:

"my-name-or-alias" # matches workspace name or alias
"my-name-pattern-*" # matches workspace names only by wildcard
"alias:my-alias-pattern-*" # matches workspace aliases by wildcard
"path:packages/**/*" # matches workspace paths by glob
"tag:my-tag" # matches workspaces with tag
"not:my-name-or-alias" # excludes workspace name or alias
"not:tag:my-tag-pattern-*" # excludes workspace tag matching wildcard
"re:^my-regex-pattern$" # matches workspace name or alias by regex
"not:tag:re:^my-tag-regex-pattern$" # excludes workspace tag by regex
"@root" # matches the root workspace

The @root special selector matches the root workspace.

#Default Matching

By default, normal strings match a workspace name or alias.

However, if a wildcard is provided, it will only match against workspace names, to prevent ambiguity.

pacwich run lint my-name-or-alias "my-name-pattern-*"

See below for how you can use wildcards with aliases.

#Matching Specifiers

Matching specifiers give you more control and options for how you match workspaces.

#Name

pacwich ls name:my-workspace "name:my-workspace-*"
pacwich run lint "name:my-workspace-*"

#Alias

pacwich ls "alias:my-alias-*"
pacwich run lint "alias:my-alias-b"

#Path

pacwich ls "path:packages/**/*"
pacwich run lint "path:packages/**/*"

#Tag

pacwich ls "tag:my-tag"
pacwich run lint "tag:my-tag-pattern-*"

#Negation

You can negate a pattern by prefixing it with not: or !. not: is preferred over ! to avoid shell operator issues. These exclude workspaces from any other patterns provided.

Negated patterns are removed from the set of matched workspaces, so a "all workspaces except my-workspace" requires two patterns: "*" and "not:my-workspace".

# All workspaces except the name or alias "my-name-or-alias"
pacwich ls "*" "not:my-name-or-alias"

# All workspaces except those with the tag "my-tag"
pacwich ls "*" "not:tag:my-tag"

#Regex Modifier

You can use the re: modifier to match patterns using regular expressions.

# All workspaces with names that start with "app-"
pacwich ls "re:^app-.*"

# All workspaces except those with tags that start with "my-tag-"
pacwich ls "*" "not:tag:re:^my-tag-.*"

#In the API

These same matching patterns can be used in the API.

import { createFileSystemProject } from "pacwich";

const project = createFileSystemProject();

project.findWorkspacesByPattern(
  "my-name-or-alias",
  "name:my-workspace-*", 
  "alias:my-alias-*", 
  "path:packages/**/*",
  "tag:my-tag",
);

project.runScriptAcrossWorkspaces({
  workspacePatterns: [
    "my-name-or-alias",
    "name:my-workspace-*",
    "alias:my-alias-*",
    "path:packages/**/*",
    "tag:my-tag",
  ],
  script: "lint",
});