Merge pull request #10105 from github/aeisenberg/about-codeql-packs

Merge and update `about-ql-packs` with `about-codeql-packs`

Author: aeisenberg

docs/codeql/codeql-cli/about-codeql-packs.rst

@@ -58,9 +58,10 @@ You can also specify:
   - a path to a directory containing query files
   - a path to a query suite file
   - the name of a CodeQL query pack
-    If omitted, the default query suite for the language
-    of the database being analyzed will be used. For more information, see the
-    :ref:`examples <database-analyze-examples>` below.
+     - with an optional version range
+     - with an optional path to a query, directory, or query suite inside the pack
+
+  If omitted, the default query suite for the language of the database being analyzed will be used. For more information, see the :ref:`examples <database-analyze-examples>` below.
 
 - ``--sarif-category``: an identifying category for the results. Used when
   you want to upload more than one set of results for a commit.
@@ -122,6 +123,14 @@ You can also run your own custom queries with the ``database analyze`` command.
 For more information about preparing your queries to use with the CodeQL CLI,
 see ":doc:`Using custom queries with the CodeQL CLI <using-custom-queries-with-the-codeql-cli>`."
 
+If you do not have the CodeQL repository checked out, you can execute the same queries by specifying the query pack name and the path to the queries::
+
+   codeql database analyze --download <javascript-database> codeql/javascript-queries:Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv
+
+Use the ``--download`` flag to download the query pack if it isn't yet available locally.
+
+.. _run-query-pack:
+
 Running a CodeQL pack
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -135,6 +144,34 @@ pack names and use the ``--download`` flag::
 The ``analyze`` command above runs the default suite from ``microsoft/coding-standards v1.0.0`` and the latest version of ``github/security-queries`` on the specified database.
 For further information about default suites, see ":ref:`Publishing and using CodeQL packs <publishing-and-using-codeql-packs>`".
 
+Running all queries in a directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can run all the queries located in a directory by providing the directory
+path, rather than listing all the individual query files. Paths are searched
+recursively, so any queries contained in subfolders will also be executed.
+
+.. pull-quote::
+
+   Important
+
+   You should avoid specifying the root of a :ref:`core CodeQL query pack
+   <standard-codeql-query-packs>` when executing ``database analyze``
+   as it might contain some special queries that aren't designed to be used with
+   the command. Rather, :ref:`run the query pack <run-query-pack>` to include the
+   pack's default queries in the analysis, or run one of the
+   code scanning query suites.
+
+For example, to execute all Python queries contained in the ``Functions`` directory you would run::
+
+   codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
+
+When the analysis has finished, a SARIF results file is generated. Specifying ``--format=sarif-latest`` ensures
+that the results are formatted according to the most recent SARIF specification
+supported by CodeQL.
+
+.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
+
 Running a subset of queries in a CodeQL pack
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -192,10 +229,10 @@ For more information, see `Analyzing a CodeQL database <https://docs.github.com/
 or `Code scanning API <https://docs.github.com/en/rest/reference/code-scanning>`__ in the GitHub documentation.
 
 CodeQL query suites are ``.qls`` files that use directives to select queries to run
-based on certain metadata properties. The standard QL packs have metadata that specify
+based on certain metadata properties. The standard CodeQL packs have metadata that specify
 the location of the query suites used by code scanning, so the CodeQL CLI knows where to find these
 suite files automatically, and you don't have to specify the full path on the command line.
-For more information, see ":ref:`About QL packs <standard-ql-packs>`."
+For more information, see ":ref:`About CodeQL packs <standard-codeql-packs>`."
 
 The standard query suites are stored at the following paths in
 the CodeQL repository::
@@ -227,35 +264,6 @@ Integrating a CodeQL pack into a code scanning workflow in GitHub
 You can use CodeQL query packs in your code scanning setup. This allows you to select query packs published by various sources and use them to analyze your code.
 For more information, see "`Using CodeQL query packs in the CodeQL action <https://docs.github.com/en/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-codeql-query-packs/>`_" or "`Downloading and using CodeQL query packs in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/configuring-codeql-cli-in-your-ci-system#downloading-and-using-codeql-query-packs>`_."
 
-
-Running all queries in a directory
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can run all the queries located in a directory by providing the directory
-path, rather than listing all the individual query files. Paths are searched
-recursively, so any queries contained in subfolders will also be executed.
-
-.. pull-quote::
-
-   Important
-
-   You shouldn't specify the root of a :doc:`QL pack
-   <about-ql-packs>` when executing ``database analyze``
-   as it contains some special queries that aren't designed to be used with
-   the command. Rather, to run a wide range of useful queries, run one of the
-   LGTM.com query suites.
-
-For example, to execute all Python queries contained in the ``Functions``
-directory you would run::
-
-   codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif
-
-A SARIF results file is generated. Specifying ``--format=sarif-latest`` ensures
-that the results are formatted according to the most recent SARIF specification
-supported by CodeQL.
-
-.. _including-query-help-for-custom-codeql-queries-in-sarif-files:
-
 Including query help for custom CodeQL queries in SARIF files
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/codeql/codeql-cli/about-ql-packs.rst

@@ -3,22 +3,19 @@
 CodeQL CLI reference
 ====================
 
-Learn more about the files you can use when running CodeQL processes and the results format and exit codes that CodeQL generates. 
+Learn more about the files you can use when running CodeQL processes and the results format and exit codes that CodeQL generates.
 
 .. toctree::
    :titlesonly:
    :hidden:
 
    about-codeql-packs
-   about-ql-packs
    query-reference-files
    sarif-output
    exit-codes
    extractor-options
 
-- :doc:`About CodeQL packs <about-codeql-packs>`: CodeQL packs are created with the CodeQL CLI and are used to create, depend on, publish, and run CodeQL queries and libraries.
-- :doc:`About QL packs <about-ql-packs>`: QL packs are used to organize the files used in CodeQL analysis. They
-  contain queries, library files, query suites, and important metadata. 
+- :doc:`About CodeQL packs <about-codeql-packs>`: CodeQL packs are created with the CodeQL CLI and are used to create, depend on, publish, and run CodeQL queries, libraries, and query suites.
 - :doc:`Query reference files <query-reference-files>`: A query reference file is text file that defines the location of one query to test.
 - :doc:`SARIF output <sarif-output>`: CodeQL supports SARIF as an output format for sharing static analysis results.
 - :doc:`Exit codes <exit-codes>`: The CodeQL CLI reports the status of each command it runs as an exit code.