From d30fde980f524f0240aa5ccb1a10199aff5f5de1 Mon Sep 17 00:00:00 2001 From: Joe Neeman Date: Tue, 15 Oct 2024 09:46:55 +0700 Subject: [PATCH] Document the new flags in the man page --- src/doc/man/cargo-publish.md | 59 +++++++++++++++++++- src/doc/man/generated_txt/cargo-publish.txt | 62 +++++++++++++++++++-- src/doc/src/commands/cargo-publish.md | 55 ++++++++++++++++-- src/etc/man/cargo-publish.1 | 61 +++++++++++++++++--- 4 files changed, 218 insertions(+), 19 deletions(-) diff --git a/src/doc/man/cargo-publish.md b/src/doc/man/cargo-publish.md index fa4c823ea09..5c816b182fc 100644 --- a/src/doc/man/cargo-publish.md +++ b/src/doc/man/cargo-publish.md @@ -68,7 +68,64 @@ which defaults to `crates-io`. {{/options}} -{{> section-options-package }} +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +Selecting more than one package is unstable and available only on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z package-workspace` flag to enable. +See for more information. + + +{{#options}} + +{{#option "`-p` _spec_..." "`--package` _spec_..."}} +{{actionverb}} only the specified packages. See {{man "cargo-pkgid" 1}} for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like `*`, `?` and `[]`. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +{{/option}} + +Selecting more than one package with this option is unstable and available only +on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z package-workspace` flag to enable. +See for more information. + +{{#option "`--workspace`" }} +{{actionverb}} all members in the workspace. + +This option is unstable and available only on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z package-workspace` flag to enable. +See for more information. +{{/option}} + +{{#option "`--exclude` _SPEC_..." }} +Exclude the specified packages. Must be used in conjunction with the +`--workspace` flag. This flag may be specified multiple times and supports +common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. + +This option is unstable and available only on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z package-workspace` flag to enable. +See for more information. +{{/option}} + +{{/options}} ### Compilation Options diff --git a/src/doc/man/generated_txt/cargo-publish.txt b/src/doc/man/generated_txt/cargo-publish.txt index 6920f8dabb2..4b6d40affec 100644 --- a/src/doc/man/generated_txt/cargo-publish.txt +++ b/src/doc/man/generated_txt/cargo-publish.txt @@ -72,11 +72,65 @@ OPTIONS config key which defaults to crates-io. Package Selection - By default, the package in the current working directory is selected. - The -p flag can be used to choose a different package in a workspace. + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. - -p spec, --package spec - The package to publish. See cargo-pkgid(1) for the SPEC format. + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + Selecting more than one package is unstable and available only on the + nightly channel + and + requires the -Z package-workspace flag to enable. See + for more information. + + -p spec…, --package spec… + Publish only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + +Selecting more than one package with this option is unstable and available only + +on the + +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) + +and requires the `-Z package-workspace` flag to enable. + +See for more information. + + --workspace + Publish all members in the workspace. + + This option is unstable and available only on the nightly channel + and + requires the -Z package-workspace flag to enable. See + for more + information. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + This option is unstable and available only on the nightly channel + and + requires the -Z package-workspace flag to enable. See + for more + information. Compilation Options --target triple diff --git a/src/doc/src/commands/cargo-publish.md b/src/doc/src/commands/cargo-publish.md index d34ac72a622..d38547791ed 100644 --- a/src/doc/src/commands/cargo-publish.md +++ b/src/doc/src/commands/cargo-publish.md @@ -77,15 +77,58 @@ which defaults to crates-io. ### Package Selection -By default, the package in the current working directory is selected. The `-p` -flag can be used to choose a different package in a workspace. +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +Selecting more than one package is unstable and available only on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z package-workspace` flag to enable. +See for more information. +
-
-p spec
-
--package spec
-
The package to publish. See cargo-pkgid(1) for the SPEC -format.
+
-p spec…
+
--package spec…
+
Publish only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like *, ? and []. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern.
+ + +Selecting more than one package with this option is unstable and available only +on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z package-workspace` flag to enable. +See for more information. + +
--workspace
+
Publish all members in the workspace.

+

This option is unstable and available only on the +nightly channel +and requires the -Z package-workspace flag to enable. +See https://github.com/rust-lang/cargo/issues/10948 for more information.

+ + +
--exclude SPEC…
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times and supports +common Unix glob patterns like *, ? and []. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern.

+

This option is unstable and available only on the +nightly channel +and requires the -Z package-workspace flag to enable. +See https://github.com/rust-lang/cargo/issues/10948 for more information.

diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1 index c73dc28e8d5..8a33750d8be 100644 --- a/src/etc/man/cargo-publish.1 +++ b/src/etc/man/cargo-publish.1 @@ -89,14 +89,59 @@ Otherwise it will use the default registry, which is defined by the which defaults to \fBcrates\-io\fR\&. .RE .SS "Package Selection" -By default, the package in the current working directory is selected. The \fB\-p\fR -flag can be used to choose a different package in a workspace. -.sp -\fB\-p\fR \fIspec\fR, -\fB\-\-package\fR \fIspec\fR -.RS 4 -The package to publish. See \fBcargo\-pkgid\fR(1) for the SPEC -format. +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. +.sp +The default members of a workspace can be set explicitly with the +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. +.sp +Selecting more than one package is unstable and available only on the +\fInightly channel\fR +and requires the \fB\-Z package\-workspace\fR flag to enable. +See for more information. +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Publish only the specified packages. See \fBcargo\-pkgid\fR(1) for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +.RE +Selecting more than one package with this option is unstable and available only +on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z package-workspace` flag to enable. +See for more information. +.sp +\fB\-\-workspace\fR +.RS 4 +Publish all members in the workspace. +.sp +This option is unstable and available only on the +\fInightly channel\fR +and requires the \fB\-Z package\-workspace\fR flag to enable. +See for more information. +.RE +.sp +\fB\-\-exclude\fR \fISPEC\fR\[u2026] +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports +common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +.sp +This option is unstable and available only on the +\fInightly channel\fR +and requires the \fB\-Z package\-workspace\fR flag to enable. +See for more information. .RE .SS "Compilation Options" .sp