search

drush-ops / drush

Drush is a command-line shell and scripting interface for Drupal, a veritable Swiss Army knife designed to make life easier for those who spend their working hours hacking away at the command prompt.
https://www.drush.org
2.34k stars 1.08k forks source link

Complete --filter docs #4214

Open geek-merlin opened 5 years ago

geek-merlin commented 5 years ago

The output filters docs verbosely describe

What i saw in the source but miss in the docs is

Also some examples of that might help.

Some streamlined quick try...

Simple filters

You can add simple filter expressions, reducing the result set to only the matching rows:

Standard field filters

If the command has a default filter field, if you only supply a value, this is equivalent to default value field contains value. Note that not all commands have a default filter field.

Empty string value

To use an empty string as value, simply omit it (without further quotes).

Negating simple filters

Any simple filter can be negated by prefixing !, either before the filter, or before the operator.

Combining simple filters

Filters can be combined with logical conjunctions && and ||. Operators are evaluated from left to right. I.e. there is no operator precedence, nor are brackets allowed.

Nested fields

You can use field.subfield dot notation for nested fields.

Whitespace

Whitespace in filters is interpreted as part of field name or value.

Quoting filter values

Quotes around filter values are not needed and will be treated as part of the value.

Examples

drush pm:list --filter='status=enabled' # Enabled modules
drush pm:list --filter='name*=domain' # Name of module contains 'domain'
drush pm:list --filter='domain' # Equivalent to preceding (as 'name' is the default filter field of pm:list).
drush pm:list --filter='name*=domain&&status=enabled' # Combined filter
drush pm:list --filter='domain&&status=enabled' # Combined filter, leveraging default field

drush role:list --filter='perms*=post comments'
drush role:list --filter='post comments' # Equivalent to preceding (as 'perms' is the default filter field of role:list).

drush core:requirements --filter='title~=#(php|gd)#i' # Regular expression: Core requirement notices with title containing either "php" or "gd"

drush site:alias --filter='env-vars.PATH!=' # Aliases with nonempty PATH in env-vars.
drush site:alias --filter='my-custom-field!=' # Aliases with my-custom-field set to nonempty string.
drush site:alias --filter='!my-custom-field=' # Equivalent.

# Avoid leading '!' in double quoted strings. Bash does not like it.
drush site:alias --filter="!customfield=" # ERROR: "bash: !description=: event not found"
# These work.
drush site:alias --filter="customfield!=" # Put '!' not in front.
drush site:alias --filter=!customfield=' # Use single quotes
drush site:alias --filter='!'"customfield=$VAR" # Use bash string concatenation.
weitzman commented 2 days ago

A PR would be welcome. I just added a bit about negation to the doc.

gitressa commented 1 day ago

Thanks @weitzman, I'm just adding a link to the PR: #6150