From b44a96af90b6770f8f73c99194bef680f2d2bc71 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 11:17:05 +0000 Subject: [PATCH 1/8] Initial plan From f9da8c6e60bc86757f10ea9bf59c46cd57fdf394 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 4 Nov 2025 11:32:13 +0000 Subject: [PATCH 2/8] Add package version constraints documentation Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com> --- commands/package.md | 18 ++++ commands/package/install.md | 2 + guides.md | 1 + guides/package-version-constraints.md | 139 ++++++++++++++++++++++++++ 4 files changed, 160 insertions(+) create mode 100644 guides/package-version-constraints.md diff --git a/commands/package.md b/commands/package.md index 45bd52f5..38fe18c9 100644 --- a/commands/package.md +++ b/commands/package.md @@ -37,6 +37,24 @@ Learn how to create your own command from the --- Success: Package installed. + # Install a specific version of a package. + $ wp package install wp-cli/server-command:^2.0 + Installing package wp-cli/server-command (^2.0) + Updating /home/person/.wp-cli/packages/composer.json to require the package... + Using Composer to install the package... + --- + Loading composer repositories with package information + Updating dependencies + Resolving dependencies through SAT + Dependency resolution completed in 0.005 seconds + Analyzed 732 packages to resolve dependencies + Analyzed 1034 rules to resolve dependencies + - Installing package + Writing lock file + Generating autoload files + --- + Success: Package installed. + # Uninstall package. $ wp package uninstall wp-cli/server-command Removing require statement for package 'wp-cli/server-command' from /home/person/.wp-cli/packages/composer.json diff --git a/commands/package/install.md b/commands/package/install.md index 37cb2d48..7691dcaf 100644 --- a/commands/package/install.md +++ b/commands/package/install.md @@ -20,6 +20,8 @@ When installing a .zip file, WP-CLI extracts the package to `~/.wp-cli/packages/ If Github token authorization is required, a GitHub Personal Access Token (https://github.com/settings/tokens) can be used. The following command will add a GitHub Personal Access Token to Composer's global configuration: composer config -g github-oauth.github.com <GITHUB_TOKEN> Once this has been added, the value used for <GITHUB_TOKEN> will be used for future authorization requests. +For more information about version constraints, see the [Package Version Constraints](https://make.wordpress.org/cli/handbook/guides/package-version-constraints/) guide. + ### OPTIONS <name|git|path|zip> diff --git a/guides.md b/guides.md index af4d23b2..5377ad15 100644 --- a/guides.md +++ b/guides.md @@ -8,5 +8,6 @@ * **[External resources](https://make.wordpress.org/cli/handbook/guides/external-resources/)** - Blog posts, slides and videos from users. * **[Force output to a specific locale](https://make.wordpress.org/cli/handbook/guides/force-output-specific-locale/)** - Localisation issue * **[Identify a Plugin or Theme Conflict](https://make.wordpress.org/cli/handbook/guides/identify-plugin-theme-conflict/)** - Debugging advise +* **[Package Version Constraints](https://make.wordpress.org/cli/handbook/guides/package-version-constraints/)** - Learn about version constraint syntax for packages * **[Sharing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/sharing-wp-cli-packages/)** - Some words about your environment * **[Troubleshooting Guide](https://make.wordpress.org/cli/handbook/guides/troubleshooting/)** - Some help to troubleshoot diff --git a/guides/package-version-constraints.md b/guides/package-version-constraints.md new file mode 100644 index 00000000..71e85f51 --- /dev/null +++ b/guides/package-version-constraints.md @@ -0,0 +1,139 @@ +# Package Version Constraints + +When installing WP-CLI packages using the `wp package install` command, you can specify version constraints to control which version of a package is installed. This is particularly useful for ensuring compatibility, testing specific versions, or maintaining stability in production environments. + +## Syntax + +Version constraints are specified by appending a colon (`:`) followed by the constraint to the package name: + +```bash +wp package install : +``` + +## Common Version Constraints + +WP-CLI uses Composer's version constraint syntax. Here are the most commonly used constraints: + +### Exact Version + +Install a specific version: + +```bash +wp package install wp-cli/server-command:2.0.0 +``` + +### Version Range + +Install a version within a specific range: + +```bash +# Install any version >= 1.0 and < 2.0 +wp package install wp-cli/server-command:^1.0 + +# Install any version >= 1.2 and < 1.3 +wp package install wp-cli/server-command:~1.2 +``` + +### Stability Flags + +Install packages with specific stability requirements: + +```bash +# Install the latest stable release +wp package install wp-cli/server-command:@stable + +# Install the latest development version +wp package install wp-cli/server-command:@dev + +# Install the latest release candidate +wp package install wp-cli/server-command:@rc + +# Install the latest beta version +wp package install wp-cli/server-command:@beta + +# Install the latest alpha version +wp package install wp-cli/server-command:@alpha +``` + +### Wildcard Versions + +Use wildcards to match multiple versions: + +```bash +# Install any 1.x version +wp package install wp-cli/server-command:1.* + +# Install any 1.2.x version +wp package install wp-cli/server-command:1.2.* +``` + +### Development Branches + +Install directly from a development branch: + +```bash +# Install from the main branch +wp package install wp-cli/server-command:dev-main + +# Install from a feature branch +wp package install wp-cli/server-command:dev-feature-branch +``` + +## Caret (^) vs Tilde (~) Operators + +### Caret Operator (^) + +The caret operator allows updates that do not change the leftmost non-zero digit: + +- `^1.2.3` is equivalent to `>=1.2.3 <2.0.0` +- `^0.3.0` is equivalent to `>=0.3.0 <0.4.0` +- `^0.0.3` is equivalent to `>=0.0.3 <0.0.4` + +This is useful for semantic versioning, where you want to allow non-breaking changes. + +### Tilde Operator (~) + +The tilde operator allows the last digit specified to go up: + +- `~1.2.3` is equivalent to `>=1.2.3 <1.3.0` +- `~1.2` is equivalent to `>=1.2.0 <2.0.0` + +This is useful when you want to allow patch-level updates but not minor version updates. + +## Examples + +### Installing a Stable Package + +To install the latest stable version of a package: + +```bash +wp package install wp-cli/server-command:@stable +``` + +### Installing a Specific Version + +To install a specific version for testing or compatibility: + +```bash +wp package install wp-cli/server-command:1.0.0 +``` + +### Installing with Semantic Versioning + +To install a package and allow non-breaking updates: + +```bash +wp package install wp-cli/server-command:^2.0 +``` + +### Installing from a Development Branch + +To install the latest development version: + +```bash +wp package install wp-cli/server-command:dev-main +``` + +## Additional Resources + +For more detailed information about version constraints and advanced usage, see the official [Composer documentation on versions and constraints](https://getcomposer.org/doc/articles/versions.md). From d9f7277bbeec094b7b626de033b789e84f8dd3cf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 20 Jan 2026 15:13:50 +0000 Subject: [PATCH 3/8] Revert changes to commands/package.md Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com> --- commands/package.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/commands/package.md b/commands/package.md index 38fe18c9..45bd52f5 100644 --- a/commands/package.md +++ b/commands/package.md @@ -37,24 +37,6 @@ Learn how to create your own command from the --- Success: Package installed. - # Install a specific version of a package. - $ wp package install wp-cli/server-command:^2.0 - Installing package wp-cli/server-command (^2.0) - Updating /home/person/.wp-cli/packages/composer.json to require the package... - Using Composer to install the package... - --- - Loading composer repositories with package information - Updating dependencies - Resolving dependencies through SAT - Dependency resolution completed in 0.005 seconds - Analyzed 732 packages to resolve dependencies - Analyzed 1034 rules to resolve dependencies - - Installing package - Writing lock file - Generating autoload files - --- - Success: Package installed. - # Uninstall package. $ wp package uninstall wp-cli/server-command Removing require statement for package 'wp-cli/server-command' from /home/person/.wp-cli/packages/composer.json From ea876d3faf8d2279d6227cd54758d011f87640db Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 20 Jan 2026 15:16:30 +0000 Subject: [PATCH 4/8] Make package version constraints guide more concise Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com> --- guides/package-version-constraints.md | 123 ++------------------------ 1 file changed, 8 insertions(+), 115 deletions(-) diff --git a/guides/package-version-constraints.md b/guides/package-version-constraints.md index 71e85f51..ab18835b 100644 --- a/guides/package-version-constraints.md +++ b/guides/package-version-constraints.md @@ -1,8 +1,6 @@ # Package Version Constraints -When installing WP-CLI packages using the `wp package install` command, you can specify version constraints to control which version of a package is installed. This is particularly useful for ensuring compatibility, testing specific versions, or maintaining stability in production environments. - -## Syntax +When installing WP-CLI packages using the `wp package install` command, you can specify version constraints to control which version of a package is installed. Version constraints are specified by appending a colon (`:`) followed by the constraint to the package name: @@ -10,130 +8,25 @@ Version constraints are specified by appending a colon (`:`) followed by the con wp package install : ``` -## Common Version Constraints - -WP-CLI uses Composer's version constraint syntax. Here are the most commonly used constraints: +## Common Constraints -### Exact Version - -Install a specific version: +WP-CLI uses Composer's version constraint syntax. Here are some commonly used examples: ```bash +# Install a specific version wp package install wp-cli/server-command:2.0.0 -``` -### Version Range - -Install a version within a specific range: - -```bash -# Install any version >= 1.0 and < 2.0 +# Install with caret operator (allows non-breaking updates) wp package install wp-cli/server-command:^1.0 -# Install any version >= 1.2 and < 1.3 +# Install with tilde operator (allows patch-level updates) wp package install wp-cli/server-command:~1.2 -``` -### Stability Flags - -Install packages with specific stability requirements: - -```bash # Install the latest stable release wp package install wp-cli/server-command:@stable -# Install the latest development version -wp package install wp-cli/server-command:@dev - -# Install the latest release candidate -wp package install wp-cli/server-command:@rc - -# Install the latest beta version -wp package install wp-cli/server-command:@beta - -# Install the latest alpha version -wp package install wp-cli/server-command:@alpha -``` - -### Wildcard Versions - -Use wildcards to match multiple versions: - -```bash -# Install any 1.x version -wp package install wp-cli/server-command:1.* - -# Install any 1.2.x version -wp package install wp-cli/server-command:1.2.* -``` - -### Development Branches - -Install directly from a development branch: - -```bash -# Install from the main branch +# Install from a development branch wp package install wp-cli/server-command:dev-main - -# Install from a feature branch -wp package install wp-cli/server-command:dev-feature-branch ``` -## Caret (^) vs Tilde (~) Operators - -### Caret Operator (^) - -The caret operator allows updates that do not change the leftmost non-zero digit: - -- `^1.2.3` is equivalent to `>=1.2.3 <2.0.0` -- `^0.3.0` is equivalent to `>=0.3.0 <0.4.0` -- `^0.0.3` is equivalent to `>=0.0.3 <0.0.4` - -This is useful for semantic versioning, where you want to allow non-breaking changes. - -### Tilde Operator (~) - -The tilde operator allows the last digit specified to go up: - -- `~1.2.3` is equivalent to `>=1.2.3 <1.3.0` -- `~1.2` is equivalent to `>=1.2.0 <2.0.0` - -This is useful when you want to allow patch-level updates but not minor version updates. - -## Examples - -### Installing a Stable Package - -To install the latest stable version of a package: - -```bash -wp package install wp-cli/server-command:@stable -``` - -### Installing a Specific Version - -To install a specific version for testing or compatibility: - -```bash -wp package install wp-cli/server-command:1.0.0 -``` - -### Installing with Semantic Versioning - -To install a package and allow non-breaking updates: - -```bash -wp package install wp-cli/server-command:^2.0 -``` - -### Installing from a Development Branch - -To install the latest development version: - -```bash -wp package install wp-cli/server-command:dev-main -``` - -## Additional Resources - -For more detailed information about version constraints and advanced usage, see the official [Composer documentation on versions and constraints](https://getcomposer.org/doc/articles/versions.md). +For complete documentation on version constraint syntax and operators, see the [Composer documentation on versions and constraints](https://getcomposer.org/doc/articles/versions.md). From 39e082ca6ba3074d2369db841c8f21768dba8795 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 20 Jan 2026 15:22:20 +0000 Subject: [PATCH 5/8] Revert changes to commands/package/install.md Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com> --- commands/package/install.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/commands/package/install.md b/commands/package/install.md index cda2360e..37cb2d48 100644 --- a/commands/package/install.md +++ b/commands/package/install.md @@ -20,12 +20,8 @@ When installing a .zip file, WP-CLI extracts the package to `~/.wp-cli/packages/ If Github token authorization is required, a GitHub Personal Access Token (https://github.com/settings/tokens) can be used. The following command will add a GitHub Personal Access Token to Composer's global configuration: composer config -g github-oauth.github.com <GITHUB_TOKEN> Once this has been added, the value used for <GITHUB_TOKEN> will be used for future authorization requests. -For more information about version constraints, see the [Package Version Constraints](https://make.wordpress.org/cli/handbook/guides/package-version-constraints/) guide. - ### OPTIONS -See the [argument syntax](https://make.wordpress.org/cli/handbook/references/argument-syntax/) reference for a detailed explanation of the syntax conventions used. - <name|git|path|zip> : Name, git URL, directory path, or .zip file for the package to install. Names can optionally include a version constraint (e.g. wp-cli/server-command:@stable). From f517c9e84afc6a6453ffca0eed8635bcdf45b5a5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 20 Jan 2026 15:25:33 +0000 Subject: [PATCH 6/8] Transform into general Installing WP-CLI Packages guide Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com> --- guides.md | 2 +- guides/installing-packages.md | 59 +++++++++++++++++++++++++++ guides/package-version-constraints.md | 32 --------------- 3 files changed, 60 insertions(+), 33 deletions(-) create mode 100644 guides/installing-packages.md delete mode 100644 guides/package-version-constraints.md diff --git a/guides.md b/guides.md index 5377ad15..4e3fcb09 100644 --- a/guides.md +++ b/guides.md @@ -8,6 +8,6 @@ * **[External resources](https://make.wordpress.org/cli/handbook/guides/external-resources/)** - Blog posts, slides and videos from users. * **[Force output to a specific locale](https://make.wordpress.org/cli/handbook/guides/force-output-specific-locale/)** - Localisation issue * **[Identify a Plugin or Theme Conflict](https://make.wordpress.org/cli/handbook/guides/identify-plugin-theme-conflict/)** - Debugging advise -* **[Package Version Constraints](https://make.wordpress.org/cli/handbook/guides/package-version-constraints/)** - Learn about version constraint syntax for packages +* **[Installing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/installing-packages/)** - Learn how to install packages and use version constraints * **[Sharing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/sharing-wp-cli-packages/)** - Some words about your environment * **[Troubleshooting Guide](https://make.wordpress.org/cli/handbook/guides/troubleshooting/)** - Some help to troubleshoot diff --git a/guides/installing-packages.md b/guides/installing-packages.md new file mode 100644 index 00000000..2f02c188 --- /dev/null +++ b/guides/installing-packages.md @@ -0,0 +1,59 @@ +# Installing WP-CLI Packages + +WP-CLI packages are community-maintained projects built on WP-CLI. They can contain WP-CLI commands, but they can also just extend WP-CLI in some way. + +## Installing a Package + +Use the `wp package install` command to install a package. Packages can be specified as: + +* Package name from WP-CLI's package index +* Git URL accessible by the current shell user +* Path to a directory on the local machine +* Local or remote .zip file + +```bash +# Install a package by name +wp package install wp-cli/server-command + +# Install from a Git URL +wp package install https://github.com/wp-cli/server-command.git + +# Install from a local directory +wp package install /path/to/package + +# Install from a .zip file +wp package install package.zip +``` + +Packages are installed to `~/.wp-cli/packages/` by default. Use the `WP_CLI_PACKAGES_DIR` environment variable to provide a custom path. + +## Version Constraints + +When installing WP-CLI packages, you can specify version constraints to control which version of a package is installed. + +Version constraints are specified by appending a colon (`:`) followed by the constraint to the package name: + +```bash +wp package install : +``` + +WP-CLI uses Composer's version constraint syntax. Here are some commonly used examples: + +```bash +# Install a specific version +wp package install wp-cli/server-command:2.0.0 + +# Install with caret operator (allows non-breaking updates) +wp package install wp-cli/server-command:^1.0 + +# Install with tilde operator (allows patch-level updates) +wp package install wp-cli/server-command:~1.2 + +# Install the latest stable release +wp package install wp-cli/server-command:@stable + +# Install from a development branch +wp package install wp-cli/server-command:dev-main +``` + +For complete documentation on version constraint syntax and operators, see the [Composer documentation on versions and constraints](https://getcomposer.org/doc/articles/versions.md). diff --git a/guides/package-version-constraints.md b/guides/package-version-constraints.md deleted file mode 100644 index ab18835b..00000000 --- a/guides/package-version-constraints.md +++ /dev/null @@ -1,32 +0,0 @@ -# Package Version Constraints - -When installing WP-CLI packages using the `wp package install` command, you can specify version constraints to control which version of a package is installed. - -Version constraints are specified by appending a colon (`:`) followed by the constraint to the package name: - -```bash -wp package install : -``` - -## Common Constraints - -WP-CLI uses Composer's version constraint syntax. Here are some commonly used examples: - -```bash -# Install a specific version -wp package install wp-cli/server-command:2.0.0 - -# Install with caret operator (allows non-breaking updates) -wp package install wp-cli/server-command:^1.0 - -# Install with tilde operator (allows patch-level updates) -wp package install wp-cli/server-command:~1.2 - -# Install the latest stable release -wp package install wp-cli/server-command:@stable - -# Install from a development branch -wp package install wp-cli/server-command:dev-main -``` - -For complete documentation on version constraint syntax and operators, see the [Composer documentation on versions and constraints](https://getcomposer.org/doc/articles/versions.md). From 1d56f309711c6fe5f2afb494dd4a990f997f9664 Mon Sep 17 00:00:00 2001 From: Pascal Birchler Date: Tue, 20 Jan 2026 17:27:47 +0100 Subject: [PATCH 7/8] Some minor tweaks --- commands/package/install.md | 2 ++ guides/installing-packages.md | 4 +++- references/tools.md | 2 +- 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/commands/package/install.md b/commands/package/install.md index f9f9508f..19cade35 100644 --- a/commands/package/install.md +++ b/commands/package/install.md @@ -22,6 +22,8 @@ composer config -g github-oauth.github.com <GITHUB_TOKEN> Once this has be ### OPTIONS +See the [argument syntax](https://make.wordpress.org/cli/handbook/references/argument-syntax/) reference for a detailed explanation of the syntax conventions used. + <name|git|path|zip> : Name, git URL, directory path, or .zip file for the package to install. Names can optionally include a version constraint (e.g. wp-cli/server-command:@stable). diff --git a/guides/installing-packages.md b/guides/installing-packages.md index 2f02c188..a81cef17 100644 --- a/guides/installing-packages.md +++ b/guides/installing-packages.md @@ -2,6 +2,8 @@ WP-CLI packages are community-maintained projects built on WP-CLI. They can contain WP-CLI commands, but they can also just extend WP-CLI in some way. +To finx existing packages to install, take a look at [Packagist](https://packagist.org/?type=wp-cli-package). + ## Installing a Package Use the `wp package install` command to install a package. Packages can be specified as: @@ -25,7 +27,7 @@ wp package install /path/to/package wp package install package.zip ``` -Packages are installed to `~/.wp-cli/packages/` by default. Use the `WP_CLI_PACKAGES_DIR` environment variable to provide a custom path. +Packages are installed to `~/.wp-cli/packages/` by default. Use the `WP_CLI_PACKAGES_DIR` environment variable to provide a custom path. See also: [Sharing WP-CLI Packages](https://make.wordpress.org/cli/handbook/guides/sharing-wp-cli-packages/). ## Version Constraints diff --git a/references/tools.md b/references/tools.md index 64facb56..8bcfb046 100644 --- a/references/tools.md +++ b/references/tools.md @@ -1,6 +1,6 @@ # Tools -The following is a list of projects that integrate with WP-CLI in some form. For installable WP-CLI packages, please see the [package index](https://wp-cli.org/package-index/). +The following is a list of projects that integrate with WP-CLI in some form. For installable WP-CLI packages, take a look at [Packagist](https://packagist.org/?type=wp-cli-package). ## Plugins From 3ce9359a861ca2c348343c3d4a4b9fa021943b54 Mon Sep 17 00:00:00 2001 From: Pascal Birchler Date: Tue, 20 Jan 2026 17:35:19 +0100 Subject: [PATCH 8/8] Fix typo Co-authored-by: Nilambar Sharma --- guides/installing-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installing-packages.md b/guides/installing-packages.md index a81cef17..4ccd5979 100644 --- a/guides/installing-packages.md +++ b/guides/installing-packages.md @@ -2,7 +2,7 @@ WP-CLI packages are community-maintained projects built on WP-CLI. They can contain WP-CLI commands, but they can also just extend WP-CLI in some way. -To finx existing packages to install, take a look at [Packagist](https://packagist.org/?type=wp-cli-package). +To find existing packages to install, take a look at [Packagist](https://packagist.org/?type=wp-cli-package). ## Installing a Package