Docs: Simplify getting started docs

It is no longer necessary to check out a version of `github/codeql` as
a sibling directory to the distribution. Instead, users can download
the required packs as needed. using the `pack download` command or
the `--download` option for `codeql database analyze`.

Author: aeisenberg

docs/codeql/codeql-cli/getting-started-with-the-codeql-cli.rst

@@ -4,7 +4,7 @@ Getting started with the CodeQL CLI
 ===================================
 
 To run CodeQL commands, you need to set up the CLI so that it can access
-the tools, queries, and libraries required to create and analyze databases. 
+the tools, queries, and libraries required to create and analyze databases.
 
 .. include:: ../reusables/license-note.rst
 
@@ -18,16 +18,16 @@ structures. To get started quickly, we recommend adopting a relatively simple
 setup, as outlined in the steps below.
 
 If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
-follow the steps below. For macOS version 10.15 ("Catalina") or newer, steps 1 
-and 4 are slightly different---for further details, see the sections labeled 
+follow the steps below. For macOS version 10.15 ("Catalina") or newer, steps 1
+and 4 are slightly different---for further details, see the sections labeled
 **Information for macOS "Catalina" (or newer) users**. If you are using macOS
 on Apple Silicon (e.g. Apple M1), ensure that the `Xcode command-line developer
 tools <https://developer.apple.com/downloads/index.action>`__ and `Rosetta 2
 <https://support.apple.com/en-us/HT211861>`__ are installed.
 
 For information about installing the CodeQL CLI in a CI system to create results
-to display in GitHub as code scanning alerts, see 
-`Installing CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system>`__ 
+to display in GitHub as code scanning alerts, see
+`Installing CodeQL CLI in your CI system <https://docs.github.com/en/code-security/secure-coding/using-codeql-code-scanning-with-your-existing-ci-system/installing-codeql-cli-in-your-ci-system>`__
 in the GitHub documentation.
 
 1. Download the CodeQL CLI zip package
@@ -42,9 +42,9 @@ Conditions <https://securitylab.github.com/tools/codeql/license>`__.
 
    There are several different versions of the CLI available to download, depending
    on your use case:
-   
+
    - If you want to use the most up to date CodeQL tools and features, download the
-     version tagged ``latest``. 
+     version tagged ``latest``.
 
    - If you want to create CodeQL databases to upload to LGTM Enterprise, download
      the version that is compatible with the relevant LGTM Enterprise version
@@ -53,9 +53,9 @@ Conditions <https://securitylab.github.com/tools/codeql/license>`__.
      <https://github.com/github/codeql-cli-binaries/releases>`__ on GitHub. Using the
      correct version of the CLI ensures that your CodeQL databases are
      compatible with your version of LGTM Enterprise. For more information,
-     see `Preparing CodeQL databases to upload to LGTM 
+     see `Preparing CodeQL databases to upload to LGTM
      <https://help.semmle.com/lgtm-enterprise/admin/help/prepare-database-upload.html>`__
-     in the LGTM admin help. 
+     in the LGTM admin help.
 
 If you use Linux, Windows, or macOS version 10.14 ("Mojave") or earlier, simply
 `download the zip archive
@@ -72,97 +72,23 @@ Alternatively, you can download ``codeql.zip``, which contains the CLI for all s
       **Information for macOS "Catalina" (or newer) users**
 
    .. pull-quote:: macOS "Catalina" (or newer)
-      
-      If you use macOS version 10.15 ("Catalina"), version 11 ("Big Sur"), or the upcoming 
-      version 12 ("Monterey"), you need to ensure that your web browser does not automatically 
-      extract zip files. If you use Safari, complete the following steps before downloading 
+
+      If you use macOS version 10.15 ("Catalina"), version 11 ("Big Sur"), or the upcoming
+      version 12 ("Monterey"), you need to ensure that your web browser does not automatically
+      extract zip files. If you use Safari, complete the following steps before downloading
       the CodeQL CLI zip archive:
-          
+
       i. Open Safari.
       ii. From the Safari menu, select **Preferences...**.
       iii. Click the **General** Tab.
       iv. Ensure the check-box labeled **Open "safe" files after downloading**.
           is unchecked.
 
-2. Create a new CodeQL directory
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Create a new directory where you can place the CLI and any queries and libraries
-you want to use. For example, ``$HOME/codeql-home``.
-
-The CLI's built-in search operations automatically look in all of its sibling
-directories for the files used in database creation and analysis. Keeping these
-components in their own directory prevents the CLI searching unrelated sibling
-directories while ensuring all files are available without specifying any
-further options on the command line.
-
-.. _local-copy-codeql-queries:
-
-3. Obtain a local copy of the CodeQL queries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The `CodeQL repository <https://github.com/github/codeql>`__ contains 
-the queries and libraries required for CodeQL analysis of C/C++, C#, Java,
-JavaScript/TypeScript, Python, and Ruby.
-Clone a copy of this repository into ``codeql-home``. 
- 
-By default, the root of the cloned repository will be called ``codeql``. 
-Rename this folder ``codeql-repo`` to avoid conflicting with the CodeQL 
-CLI that you will extract in step 4. If you use git on the command line, you can 
-clone and rename the repository in a single step by running 
-``git clone git@github.com:github/codeql.git codeql-repo`` in the ``codeql-home`` folder.
-
-The CodeQL libraries and queries for Go analysis live in the `CodeQL for Go
-repository <https://github.com/github/codeql-go/>`__. Clone a copy of this
-repository into ``codeql-home``. 
-
-The cloned repositories should have a sibling relationship. 
-For example, if the root of the cloned CodeQL repository is
-``$HOME/codeql-home/codeql-repo``, then the root of the cloned CodeQL for Go
-repository should be ``$HOME/codeql-home/codeql-go``.
-
-Within these repositories, the queries and libraries are organized into QL
-packs. Along with the queries themselves, QL packs contain important metadata
-that tells the CodeQL CLI how to process the query files. For more information,
-see ":doc:`About QL packs <about-ql-packs>`."
-
-.. pull-quote:: Important
-
-   There are different versions of the CodeQL queries available for different
-   users. Check out the correct version for your use case:
-
-   - For the queries used on `LGTM.com <https://lgtm.com>`__, check out the
-     ``lgtm.com`` branch. You should use this branch for databases you've built
-     using the CodeQL CLI, fetched from code scanning on GitHub, or recently downloaded from LGTM.com.
-     The queries on the ``lgtm.com`` branch are more likely to be compatible 
-     with the ``latest`` CLI, so you'll be less likely to have to upgrade 
-     newly-created databases than if you use the ``main`` branch. Older databases 
-     may need to be upgraded before you can analyze them.
-   
-   - For the most up to date CodeQL queries, check out the ``main`` branch. 
-     This branch represents the very latest version of CodeQL's analysis. Even
-     databases created using the most recent version of the CLI may have to be
-     upgraded before you can analyze them. For more information, see
-     ":doc:`Upgrading CodeQL databases <upgrading-codeql-databases>`."
-        
-   - For the queries used in a particular LGTM Enterprise release, check out the
-     branch tagged with the relevant release number. For example, the branch
-     tagged ``v1.27.0`` corresponds to LGTM Enterprise 1.27. You must use this
-     version if you want to upload data to LGTM Enterprise. For further
-     information, see `Preparing CodeQL databases to upload to LGTM 
-     <https://help.semmle.com/lgtm-enterprise/admin/help/prepare-database-upload.html>`__
-     in the LGTM admin help.
-
-4. Extract the zip archive
+2. Extract the zip archive
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier) 
-simply
-extract the zip archive into the directory you created in step 2.
-
-For example, if the path to your copy of the CodeQL repository is
-``$HOME/codeql-home/codeql-repo``, then extract the CLI into
-``$HOME/codeql-home/``.
+For Linux, Windows, and macOS users (version 10.14 "Mojave", and earlier)
+simply extract the zip archive.
 
 .. container:: toggle
 
@@ -171,17 +97,17 @@ For example, if the path to your copy of the CodeQL repository is
       **Information for macOS "Catalina" (or newer) users**
 
    .. pull-quote:: macOS "Catalina"
-   
-      macOS "Catalina", "Big Sur", or "Monterey" users should run the following 
-      commands in the Terminal, where ``${install_loc}`` is the path to the 
-      directory you created in step 2:
-   
-      i. ``mv ~/Downloads/codeql*.zip ${install_loc}``
-      ii. ``cd ${install_loc}``
+
+      macOS "Catalina", "Big Sur", or "Monterey" users should run the following
+      commands in the Terminal, where ``${extraction-root}`` is the path to the
+      directory where you will extract the CodeQL CLI zip archive:
+
+      i. ``mv ~/Downloads/codeql*.zip ${extraction-root}``
+      ii. ``cd ${extraction-root}``
       iii. ``/usr/bin/xattr -c codeql*.zip``
       iv. ``unzip codeql*.zip``
-   
-5. Launch ``codeql``
+
+3. Launch ``codeql``
 ~~~~~~~~~~~~~~~~~~~~
 
 Once extracted, you can run CodeQL processes by running the ``codeql``
@@ -191,7 +117,7 @@ executable in a couple of ways:
   ``<extraction-root>`` is the folder where you extracted the CodeQL CLI
   package.
 - By adding ``<extraction-root>/codeql`` to your ``PATH``, so that you
-  can run the executable as just ``codeql``. 
+  can run the executable as just ``codeql``.
 
 At this point, you can execute CodeQL commands. For a full list of the CodeQL
 CLI commands, see the "`CodeQL CLI manual <../manual>`__."
@@ -204,25 +130,28 @@ CLI commands, see the "`CodeQL CLI manual <../manual>`__."
    ":ref:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`."
 
 
-6. Verify your CodeQL CLI setup
+4. Verify your CodeQL CLI setup
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 CodeQL CLI has subcommands you can execute to verify that you are correctly set
 up to create and analyze databases:
 
 - Run ``codeql resolve languages`` to show which languages are
   available for database creation. This will list the languages supported by
-  default in your CodeQL CLI package. 
-- Run ``codeql resolve qlpacks`` to show which QL packs the CLI can find. This
-  will display the names of the QL packs included in the CodeQL repositories:
-  ``codeql-cpp``, ``codeql-csharp``, ``codeql-go``,
-  ``codeql-java``, ``codeql-javascript``, and ``codeql-python``. The CodeQL
-  repositories also contain 'upgrade' packs and 'legacy' packs. Upgrade packs
-  are used by the CLI when you want to upgrade a database so that it can be
-  analyzed with a newer version of the CodeQL toolchain than was used to create
-  it. Legacy packs ensure that custom queries and libraries created using older
-  products are compatible with your version of CodeQL.
+  default in your CodeQL CLI package.
+- (Optional) You can download some ":ref"`CodeQL packs <about-codeql-packs>` containing pre-compiled queries you would like to run.
+  To do this, run ``codeql pack download <pack-name> [...pack-name]``, where ``pack-name`` is the name of
+  the pack you want to download. The core query packs are a good place to start. They are:
+
+      - ``codeql/cpp-queries``
+      - ``codeql/csharp-queries``
+      - ``codeql/java-queries``
+      - ``codeql/javascript-queries``
+      - ``codeql/python-queries``
+      - ``codeql/ruby-queries``
 
+   Alternatively, you can download query packs during the analysis by using the `--download` flag of the `codeql database analyze`
+   command.
 
 .. _using-two-versions-of-the-codeql-cli:
 
@@ -242,4 +171,4 @@ recommended directory setup depends on which versions you want to install:
   directory. For example, if you unpack version 2.0.2 into
   ``$HOME/codeql-home/codeql-cli``, the older version should be
   unpacked into ``$HOME/codeql-older-version/old-codeql-cli``. Here, the common
-  grandparent is the ``$HOME`` directory. 
+  grandparent is the ``$HOME`` directory.