Document the new flags in the man page

rust-lang · Oct 15, 2024 · d30fde9 · d30fde9
1 parent 4e051c4
commit d30fde9
Show file tree

Hide file tree

Showing 4 changed files with 218 additions and 19 deletions.
diff --git 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 <https://github.com/rust-lang/cargo/issues/10948> 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 <https://github.com/rust-lang/cargo/issues/10948> 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 <https://github.com/rust-lang/cargo/issues/10948> 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 <https://github.com/rust-lang/cargo/issues/10948> 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
@@ -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
+       <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
+       requires the -Z package-workspace flag to enable. See
+       <https://github.com/rust-lang/cargo/issues/10948> 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 <https://github.com/rust-lang/cargo/issues/10948> for more information.
+
+       --workspace
+           Publish 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
+           <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
+           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
+           requires the -Z package-workspace flag to enable. See
+           <https://github.com/rust-lang/cargo/issues/10948> 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
@@ -77,15 +77,58 @@ which defaults to <code>crates-io</code>.</dd>
 
 ### 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 <https://github.com/rust-lang/cargo/issues/10948> for more information.
+
 
 <dl>
 
-<dt class="option-term" id="option-cargo-publish--p"><a class="option-anchor" href="#option-cargo-publish--p"></a><code>-p</code> <em>spec</em></dt>
-<dt class="option-term" id="option-cargo-publish---package"><a class="option-anchor" href="#option-cargo-publish---package"></a><code>--package</code> <em>spec</em></dt>
-<dd class="option-desc">The package to publish. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the SPEC
-format.</dd>
+<dt class="option-term" id="option-cargo-publish--p"><a class="option-anchor" href="#option-cargo-publish--p"></a><code>-p</code> <em>spec</em>…</dt>
+<dt class="option-term" id="option-cargo-publish---package"><a class="option-anchor" href="#option-cargo-publish---package"></a><code>--package</code> <em>spec</em>…</dt>
+<dd class="option-desc">Publish only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the
+SPEC format. This flag may be specified multiple times and supports common Unix
+glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally
+expanding glob patterns before Cargo handles them, you must use single quotes or
+double quotes around each pattern.</dd>
+
+
+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 <https://github.com/rust-lang/cargo/issues/10948> for more information.
+
+<dt class="option-term" id="option-cargo-publish---workspace"><a class="option-anchor" href="#option-cargo-publish---workspace"></a><code>--workspace</code></dt>
+<dd class="option-desc">Publish all members in the workspace.</p>
+<p>This option is unstable and available only on the
+<a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly channel</a>
+and requires the <code>-Z package-workspace</code> flag to enable.
+See <a href="https://github.com/rust-lang/cargo/issues/10948">https://github.com/rust-lang/cargo/issues/10948</a> for more information.</dd>
+
+
+<dt class="option-term" id="option-cargo-publish---exclude"><a class="option-anchor" href="#option-cargo-publish---exclude"></a><code>--exclude</code> <em>SPEC</em>…</dt>
+<dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the
+<code>--workspace</code> flag. This flag may be specified multiple times and supports
+common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell
+accidentally expanding glob patterns before Cargo handles them, you must use
+single quotes or double quotes around each pattern.</p>
+<p>This option is unstable and available only on the
+<a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly channel</a>
+and requires the <code>-Z package-workspace</code> flag to enable.
+See <a href="https://github.com/rust-lang/cargo/issues/10948">https://github.com/rust-lang/cargo/issues/10948</a> for more information.</dd>
 
 
 </dl>

diff --git 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 <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
+and requires the \fB\-Z package\-workspace\fR flag to enable.
+See <https://github.com/rust\-lang/cargo/issues/10948> 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 <https://github.com/rust-lang/cargo/issues/10948> 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 <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
+and requires the \fB\-Z package\-workspace\fR flag to enable.
+See <https://github.com/rust\-lang/cargo/issues/10948> 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 <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
+and requires the \fB\-Z package\-workspace\fR flag to enable.
+See <https://github.com/rust\-lang/cargo/issues/10948> for more information.
 .RE
 .SS "Compilation Options"
 .sp