Merge pull request #302 from fishtown-analytics/feature/node-selectio…

…n-0180

[v0.18.0] New selectors

website/docs/docs/guides/migration-guide/upgrading-to-0-18-0.md

@@ -0,0 +1,31 @@
+---
+title: "Upgrading to 0.18.0 (prerelease)"
+
+---
+
+:::info Prerelease
+
+dbt v0.18.0 is currently in beta. Please post in the dbt Slack #prereleases channel
+if you uncover any bugs or issues.
+
+:::
+
+dbt v0.18.0 introduces several new features around model selection.
+
+## Articles:
+
+ - [Changelog](https://github.com/fishtown-analytics/dbt/blob/dev/marian-anderson/CHANGELOG.md)
+
+## Breaking changes
+
+Please be aware of the following changes in v0.18.0. While breaking, we do not expect these to affect the majority of projects.
+
+### Adapter macros
+
+* Previously, dbt put macros from all installed plugins into the namespace. This version of dbt will not include adapter plugin macros unless they are from the currently-in-use adapter or one of its dependencies.
+
+## New and changed documentation
+
+**Core**
+- [model selection syntax](model-selection-syntax)
+- [`dbt ls`](commands/list)

website/docs/reference/commands/list.md

@@ -11,43 +11,55 @@ The `dbt ls` command lists resources in your dbt project. It accepts selector ar
 ```
 dbt ls
      [--resource-type {source,analysis,model,snapshot,test,seed,default,all}]
-     [--select SELECTOR [SELECTOR ...]]
+     [--select SELECTION_ARG [SELECTION_ARG ...]]
      [--models SELECTOR [SELECTOR ...]]
      [--exclude SELECTOR [SELECTOR ...]]
+     [--selector YML_SELECTOR_NAME [YML_SELECTOR_NAME ...]]
      [--output {json,name,path,selector}]
 ```
 
+See [resource selection syntax](model-selection-syntax) for more information on how to select resources in dbt
+
 **Arguments**:
 - `--resource-type`: This flag limits the "resource types" that dbt will return in the `dbt ls` command. By default, the following resources are included in the results of `dbt ls`: models, snapshots, seeds, tests, and sources.
-- `--select`: This flag specifies one or more "selectors" used to filter the nodes returned by the `dbt ls` command. See the docs on the [resource selection syntax](model-selection-syntax) for more information on selecting resources in dbt
+- `--select`: This flag specifies one or more selection-type arguments used to filter the nodes returned by the `dbt ls` command
 - `--models`: Like the `--select` flag, this flag is used to select nodes. It implies `--resource-type=model`, and will only return models in the results of the `dbt ls` command.
 - `--exclude`: Specify selectors that should be _excluded_ from the list of returned nodes.
+- `--selector`: This flag specifies one or more named selectors, defined in a `selectors.yml` file.
 - `--output`: This flag controls the format of output from the `dbt ls` command.
 
 Note that the `dbt ls` command does not include models which are disabled or schema tests which depend on models which are disabled. All returned resources will have a `config.enabled` value of `true`.
 
 ### Example usage
 
-**Listing models by selector**
+**Listing models by package**
 ```
 $ dbt ls --models snowplow.*
-model.snowplow.snowplow_base_events
-model.snowplow.snowplow_base_web_page_context
-model.snowplow.snowplow_id_map
-model.snowplow.snowplow_page_views
-model.snowplow.snowplow_sessions
+snowplow.snowplow_base_events
+snowplow.snowplow_base_web_page_context
+snowplow.snowplow_id_map
+snowplow.snowplow_page_views
+snowplow.snowplow_sessions
 ...
 ```
 
 **Listing tests by tag name**
 ```
 $ dbt ls --select tag:nightly --resource-type test
-model.my_project.orders
-model.my_project.order_items
-model.my_project.products
+my_project.schema_test.not_null_orders_order_id
+my_project.schema_test.unique_orders_order_id
+my_project.schema_test.not_null_products_product_id
+my_project.schema_test.unique_products_product_id
 ...
 ```
 
+**Listing schema tests of incremental models**
+```
+$ dbt ls --select config.materialized:incremental,test_type:schema
+model.my_project.logs_parsed
+model.my_project.events_categorized
+```
+
 **Listing JSON output**
 ```
 $ dbt ls --models snowplow.* --output json