From 9f5c5ce93090e923b3fb2bc65ad5dadddc82272d Mon Sep 17 00:00:00 2001 From: Justus Winter Date: Wed, 27 Nov 2024 17:27:04 +0100 Subject: [PATCH] Mark `sq keyring filter` experimental. - Invoking it now requires the `--experimental` flag. This is a template that we may use to introduce features into sq with a bit of a chance to stabilize it over time. - Fixes #455. --- NEWS | 3 +++ sq-subplot.md | 18 ++++++++-------- src/cli/keyring.rs | 30 ++++++++++++++++++++++++++ tests/integration/sq_keyring_filter.rs | 1 + 4 files changed, 43 insertions(+), 9 deletions(-) diff --git a/NEWS b/NEWS index 544a2c98..fc7f13cd 100644 --- a/NEWS +++ b/NEWS @@ -124,6 +124,9 @@ - `sq` now reads a configuration file that can be used to tweak a number of defaults, like the cipher suite to generate new keys, the set of key servers to query, and the cryptographic policy. + - The command `sq keyring filter` is now considered experimental + and may change in the future. To acknowledge this, it has to be + invoked with the `--experimental` flag. * Changes in 0.39.0 ** Notable changes diff --git a/sq-subplot.md b/sq-subplot.md index d5457d63..5d6a1d3b 100644 --- a/sq-subplot.md +++ b/sq-subplot.md @@ -628,7 +628,7 @@ given an installed sq when I run sq key generate --own-key --without-password --userid Alice --output alice.pgp --rev-cert alice.pgp.rev when I run sq key generate --own-key --without-password --userid Bob --output bob.pgp --rev-cert bob.pgp.rev when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp -when I run sq keyring filter --to-cert ring.pgp --output filtered.pgp +when I run sq keyring filter --experimental --to-cert ring.pgp --output filtered.pgp when I run sq inspect filtered.pgp then stdout contains "OpenPGP Certificate." then stdout doesn't contain "Transferable Secret Key." @@ -646,7 +646,7 @@ given an installed sq when I run sq key generate --own-key --without-password --userid Alice --output alice.pgp --rev-cert alice.pgp.rev when I run sq key generate --own-key --without-password --userid Bob --output bob.pgp --rev-cert bob.pgp.rev when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp -when I run sq keyring filter --to-cert ring.pgp +when I run sq keyring filter --experimental --to-cert ring.pgp then stdout contains "-----BEGIN PGP PUBLIC KEY BLOCK-----" then stdout contains "-----END PGP PUBLIC KEY BLOCK-----" ~~~ @@ -659,7 +659,7 @@ criteria._ ~~~scenario given an installed sq when I run sq key generate --own-key --without-password --userid Alice --userid Bob --output alice.pgp --rev-cert alice.pgp.rev -when I run sq keyring filter --prune-certs --name Alice alice.pgp --output filtered.pgp +when I run sq keyring filter --experimental --prune-certs --name Alice alice.pgp --output filtered.pgp when I run sq inspect filtered.pgp then stdout contains "Alice" then stdout doesn't contain "Bob" @@ -675,7 +675,7 @@ given an installed sq when I run sq key generate --own-key --without-password --userid Alice --output alice.pgp --rev-cert alice.pgp.rev when I run sq key generate --own-key --without-password --userid Bob --output bob.pgp --rev-cert bob.pgp.rev when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp -when I run sq keyring filter --userid Alice ring.pgp --output filtered.pgp +when I run sq keyring filter --experimental --userid Alice ring.pgp --output filtered.pgp when I run sq inspect filtered.pgp then stdout contains "Alice" then stdout doesn't contain "Bob" @@ -691,7 +691,7 @@ given an installed sq when I run sq key generate --own-key --without-password --userid Alice --output alice.pgp --rev-cert alice.pgp.rev when I run sq key generate --own-key --without-password --userid Bob --output bob.pgp --rev-cert bob.pgp.rev when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp -when I run sq keyring filter --userid Alice --userid Bob ring.pgp --output filtered.pgp +when I run sq keyring filter --experimental --userid Alice --userid Bob ring.pgp --output filtered.pgp when I run sq inspect filtered.pgp then stdout contains "Alice" then stdout contains "Bob" @@ -707,7 +707,7 @@ given an installed sq when I run sq key generate --own-key --without-password --userid 'Alice ' --output alice.pgp --rev-cert alice.pgp.rev when I run sq key generate --own-key --without-password --userid 'Bob ' --output bob.pgp --rev-cert bob.pgp.rev when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp -when I run sq keyring filter --name Alice ring.pgp --output filtered.pgp +when I run sq keyring filter --experimental --name Alice ring.pgp --output filtered.pgp when I run sq inspect filtered.pgp then stdout contains "Alice" then stdout doesn't contain "Bob" @@ -723,7 +723,7 @@ given an installed sq when I run sq key generate --own-key --without-password --userid 'Alice ' --output alice.pgp --rev-cert alice.pgp.rev when I run sq key generate --own-key --without-password --userid 'Bob ' --output bob.pgp --rev-cert bob.pgp.rev when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp -when I run sq keyring filter --name Alice --name Bob ring.pgp --output filtered.pgp +when I run sq keyring filter --experimental --name Alice --name Bob ring.pgp --output filtered.pgp when I run sq inspect filtered.pgp then stdout contains "Alice" then stdout contains "Bob" @@ -739,7 +739,7 @@ given an installed sq when I run sq key generate --own-key --without-password --userid 'Alice ' --output alice.pgp --rev-cert alice.pgp.rev when I run sq key generate --own-key --without-password --userid 'Bob ' --output bob.pgp --rev-cert bob.pgp.rev when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp -when I run sq keyring filter --domain example.com ring.pgp --output filtered.pgp +when I run sq keyring filter --experimental --domain example.com ring.pgp --output filtered.pgp when I run sq inspect filtered.pgp then stdout contains "Alice" then stdout doesn't contain "Bob" @@ -755,7 +755,7 @@ given an installed sq when I run sq key generate --own-key --without-password --userid 'Alice ' --output alice.pgp --rev-cert alice.pgp.rev when I run sq key generate --own-key --without-password --userid 'Bob ' --output bob.pgp --rev-cert bob.pgp.rev when I run sq keyring merge alice.pgp bob.pgp --output ring.pgp -when I run sq keyring filter --domain example.com --domain sequoia-pgp.org ring.pgp --output filtered.pgp +when I run sq keyring filter --experimental --domain example.com --domain sequoia-pgp.org ring.pgp --output filtered.pgp when I run sq inspect filtered.pgp then stdout contains "Alice" then stdout contains "Bob" diff --git a/src/cli/keyring.rs b/src/cli/keyring.rs index 4cc46c45..8a34cb83 100644 --- a/src/cli/keyring.rs +++ b/src/cli/keyring.rs @@ -61,10 +61,32 @@ If multiple predicates are given, they are or'ed, i.e., a key matches \ if any of the predicates match. To require all predicates to match, \ chain multiple invocations of this command. See EXAMPLES for \ inspiration. + +Note: this command is considered experimental and may change in future \ +releases. To acknowledge this, you must give the `--experimental` \ +flag when invoking this command. ", after_help = FILTER_EXAMPLES, )] pub struct FilterCommand { + #[clap( + long = "experimental", + required = true, + help = "Opt-in to using an experimental feature", + long_help = "\ +Opt-in to using an experimental feature + +This command is considered experimental and may change in future \ +releases. To acknowledge this, you must give the `--experimental` \ +flag when invoking this command. + +In the future, we may stabilize this command. When that happens, \ +`--experimental` will no longer be required, but will be ignored \ +silently. +", + )] + pub _experimental: bool, + #[clap(value_name = "FILE", help = "Read from FILE or stdin if omitted")] pub input: Vec, #[clap( @@ -166,6 +188,7 @@ const FILTER_EXAMPLES: Actions = Actions { Convert all keys to certificates (i.e. remove any secret key material).", command: &[ "sq", "keyring", "filter", + "--experimental", "--to-cert", "certs.pgp", ], @@ -176,6 +199,7 @@ Convert all keys to certificates (i.e. remove any secret key material).", Get all certificates with a user ID on example.org.", command: &[ "sq", "keyring", "filter", + "--experimental", "--domain=example.org", "certs.pgp", ], @@ -186,6 +210,7 @@ Get all certificates with a user ID on example.org.", Get all certificates with a user ID on example.org or example.net.", command: &[ "sq", "keyring", "filter", + "--experimental", "--domain=example.org", "--domain=example.net", "certs.pgp", @@ -197,6 +222,7 @@ Get all certificates with a user ID on example.org or example.net.", Get all certificates with a name user ID matching Romeo.", command: &[ "sq", "keyring", "filter", + "--experimental", "--name=Romeo", "certs.pgp", ], @@ -207,9 +233,11 @@ Get all certificates with a name user ID matching Romeo.", Get all certificates with a name user ID matching Romeo on example.org.", command: &[ "sq", "keyring", "filter", + "--experimental", "--domain=example.org", "certs.pgp", "|", "sq", "keyring", "filter", + "--experimental", "--name=Romeo", ], }), @@ -219,6 +247,7 @@ Get all certificates with a name user ID matching Romeo on example.org.", Get all certificates with a user ID on example.org, pruning other user IDs.", command: &[ "sq", "keyring", "filter", + "--experimental", "--domain=example.org", "--prune-certs", "certs.pgp", @@ -325,6 +354,7 @@ const LIST_EXAMPLES: Actions = Actions { List all certificates with a user ID on example.org.", command: &[ "sq", "keyring", "filter", + "--experimental", "--domain=example.org", "certs.pgp", "|", "sq", "keyring", "list", diff --git a/tests/integration/sq_keyring_filter.rs b/tests/integration/sq_keyring_filter.rs index 6c6f880f..289890ee 100644 --- a/tests/integration/sq_keyring_filter.rs +++ b/tests/integration/sq_keyring_filter.rs @@ -69,6 +69,7 @@ fn filter(sq: &Sq, args: &[&str]) -> Vec { let mut cmd = sq.command(); cmd.arg("keyring") .arg("filter") + .arg("--experimental") .arg("--output=-") .args(args) .arg("keys.pgp");