Docs: Add branches guide content (#7094)

* Document branches

* Change to headings

so that we can easily show/hide changes per version

* WIP: Add branching guides

* Update intro and guide content with branching

* Add missing `branch merge` doc

* Clarify

* Add links to merge doc

* Add Get started > Branches to TOC

* Link to more info about rebasing

* Minor copy edits

* Link to docs for the correct command

* Fix branch commands

* Clarify final state of data after rebase

* Correct description, add data & strategy notes

* Move branch -> db notes & make command-specific

Since some branch commands do not have database command analogs, it
makes sense to mention this in the notes that tell users branch commands
only work on EdgeDB 5+. While I'm here, may as well offer alternatives
to those commands where that makes sense. While I'm doing that, may as
well make the notes for other commands that do have a database analog
point to the specific database alternative. This will make some of these
notes much longer, so I moved them below the initial command
description.

* Add note about VCS compatibility vs. examples

docs/cli/edgedb_branch/edgedb_branch_create.rst

@@ -5,19 +5,19 @@
 edgedb branch create
 ====================
 
-.. note::
-
-    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
-    or later. If you are running an earlier version of EdgeDB, you will instead
-    use the :ref:`ref_cli_edgedb_database` command suite to manage databases,
-    which branches replaced in EdgeDB 5.0.
-
 Create a new :ref:`branch <ref_datamodel_branches>`.
 
 .. cli:synopsis::
 
     edgedb branch create [<options>] <name>
 
+.. note::
+
+    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
+    or later. If you are running an earlier version of EdgeDB, you will instead
+    use the :ref:`ref_cli_edgedb_database_create` command to create a database,
+    which branches replaced in EdgeDB 5.0.
+
 
 Description
 ===========

docs/cli/edgedb_branch/edgedb_branch_drop.rst

@@ -5,19 +5,19 @@
 edgedb branch drop
 ==================
 
-.. note::
-
-    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
-    or later. If you are running an earlier version of EdgeDB, you will instead
-    use the :ref:`ref_cli_edgedb_database` command suite to manage databases,
-    which branches replaced in EdgeDB 5.0.
-
 Remove an existing :ref:`branch <ref_datamodel_branches>`.
 
 .. cli:synopsis::
 
     edgedb branch drop [<options>] <name>
 
+.. note::
+
+    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
+    or later. If you are running an earlier version of EdgeDB, you will instead
+    use the :ref:`ref_cli_edgedb_database_drop` command to drop a database,
+    which branches replaced in EdgeDB 5.0.
+
 
 Options
 =======

docs/cli/edgedb_branch/edgedb_branch_list.rst

@@ -5,15 +5,15 @@
 edgedb branch list
 ==================
 
-.. note::
-
-    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
-    or later. If you are running an earlier version of EdgeDB, you will instead
-    use the :ref:`ref_cli_edgedb_database` command suite to manage databases,
-    which branches replaced in EdgeDB 5.0.
-
 List all :ref:`branches <ref_datamodel_branches>`
 
 .. cli:synopsis::
 
     edgedb branch list
+
+.. note::
+
+    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
+    or later. If you are running an earlier version of EdgeDB, you will instead
+    use the :ref:`edgedb list databases <ref_cli_edgedb_list>` command to list
+    databases, which branches replaced in EdgeDB 5.0.

docs/cli/edgedb_branch/edgedb_branch_merge.rst

@@ -0,0 +1,53 @@
+.. _ref_cli_edgedb_branch_merge:
+
+
+===================
+edgedb branch merge
+===================
+
+Merge a :ref:`branch <ref_datamodel_branches>` into the current branch.
+
+.. cli:synopsis::
+
+    edgedb branch merge [<options>] <name>
+
+.. note::
+
+    This CLI command requires CLI version 4.0 or later and EdgeDB version 5.0
+    or later. Earlier versions did not feature branches and instead featured
+    databases. Databases offered no analog to merging. See the
+    :ref:`ref_cli_edgedb_database` command suite to manage databases.
+
+
+Description
+===========
+
+Merges the target branch with the current branch using a fast-forward strategy,
+applying any new migrations from the target branch on the current branch.
+
+.. note::
+
+    This is a fast-forward merge, so no conflict resolution will be applied to
+    the new migrations. If you want to merge but may have conflicts, you should
+    first use :ref:`ref_cli_edgedb_branch_rebase` from the target branch before
+    merging.
+
+.. note::
+
+    When merging, the data of the current branch is preserved. This means that
+    if you switch to a branch ``main`` and run ``edgedb branch merge feature``,
+    you will end up with a branch with the schema from ``main`` and any
+    new migrations from ``feature`` and the data from ``main``.
+
+
+Options
+=======
+
+The ``branch merge`` command runs in the EdgeDB instance it is
+connected to. For specifying the connection target see
+:ref:`connection options <ref_cli_edgedb_connopts>`.
+
+:cli:synopsis:`<name>`
+    The name of the branch to merge into the current branch.
+:cli:synopsis:`--no-apply`
+    Skip applying migrations generated from the merge

docs/cli/edgedb_branch/edgedb_branch_rebase.rst

@@ -5,27 +5,37 @@
 edgedb branch rebase
 ====================
 
-.. note::
-
-    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
-    or later. If you are running an earlier version of EdgeDB, you will instead
-    use the :ref:`ref_cli_edgedb_database` command suite to manage databases,
-    which branches replaced in EdgeDB 5.0.
-
 Create a :ref:`branch <ref_datamodel_branches>` based on the target branch but
 including new migrations on the current branch.
 
 .. cli:synopsis::
 
     edgedb branch rebase [<options>] <name>
 
+.. note::
+
+    This CLI command requires CLI version 4.0 or later and EdgeDB version 5.0
+    or later. Earlier versions did not feature branches and instead featured
+    databases. Databases offered no analog to rebasing. See the
+    :ref:`ref_cli_edgedb_database` command suite to manage databases.
+
 
 Description
 ===========
 
 Creates a new branch that is based on the target branch, but also contains any new migrations on the
 current branch.
 
+.. note::
+
+    When rebasing, the data of the target branch is preserved. This means that
+    if you switch to a branch ``feature`` and run ``edgedb branch rebase
+    main``, you will end up with a branch with the schema from ``main`` and any
+    new migrations from ``feature`` and the data from ``main``.
+
+For more about how rebasing works, check out the breakdown :ref:`in our schema
+migrations guide <ref_migration_guide_branches_rebasing>`.
+
 
 Options
 =======

docs/cli/edgedb_branch/edgedb_branch_rename.rst

@@ -5,19 +5,23 @@
 edgedb branch rename
 ====================
 
-.. note::
-
-    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
-    or later. If you are running an earlier version of EdgeDB, you will instead
-    use the :ref:`ref_cli_edgedb_database` command suite to manage databases,
-    which branches replaced in EdgeDB 5.0.
-
 Rename a :ref:`branch <ref_datamodel_branches>`
 
 .. cli:synopsis::
 
     edgedb branch rename [<options>] <old-name> <new-name>
 
+.. note::
+
+    This CLI command requires CLI version 4.0 or later and EdgeDB version 5.0
+    or later. Earlier versions did not feature branches and instead featured
+    databases. Databases offered no analog to the ``rename`` command. To
+    rename a database, you could :ref:`dump <ref_cli_edgedb_dump>` your
+    database, :ref:`create <ref_cli_edgedb_database_create>` a new database
+    with the desired name, and :ref:`restore <ref_cli_edgedb_restore>` the dump
+    to that new database. See the :ref:`ref_cli_edgedb_database` command suite
+    for other database management commands.
+
 
 Options
 =======

docs/cli/edgedb_branch/edgedb_branch_switch.rst

@@ -5,19 +5,35 @@
 edgedb branch switch
 ====================
 
-.. note::
-
-    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
-    or later. If you are running an earlier version of EdgeDB, you will instead
-    use the :ref:`ref_cli_edgedb_database` command suite to manage databases,
-    which branches replaced in EdgeDB 5.0.
-
 Change the currently active :ref:`branch <ref_datamodel_branches>`
 
 .. cli:synopsis::
 
     edgedb branch switch [<options>] <name>
 
+.. note::
+
+    This CLI command requires CLI version 4.0 or later and EdgeDB version 5.0
+    or later. Earlier versions did not feature branches and instead featured
+    databases.
+
+    Databases offered no direct analog to switching.
+
+    - To run a single command on a different database, use the ``-d <dbname>``
+      or ``--database=<dbname>`` options described in
+      :ref:`ref_cli_edgedb_connopts`
+    - To change the database for *all* commands, set the ``EDGEDB_DATABASE``
+      environment variable described in :ref:`ref_cli_edgedb_connopts`
+    - To change the database for all commands in a project, you may update the
+      ``credentials.json`` file's ``database`` value. To find that file for
+      your project, run :ref:`ref_cli_edgedb_info` to get the config path and
+      navigate to ``/<config-path>/credentials``.
+    - You may use ``\connect <dbname>`` or ``\c <dbname>`` to change the
+      connected database while in a REPL session.
+
+    See the :ref:`ref_cli_edgedb_database` command suite for other database
+    management commands.
+
 
 Options
 =======

docs/cli/edgedb_branch/edgedb_branch_wipe.rst

@@ -5,19 +5,19 @@
 edgedb branch wipe
 ==================
 
-.. note::
-
-    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
-    or later. If you are running an earlier version of EdgeDB, you will instead
-    use the :ref:`ref_cli_edgedb_database` command suite to manage databases,
-    which branches replaced in EdgeDB 5.0.
-
 Destroy the contents of a :ref:`branch <ref_datamodel_branches>`
 
 .. cli:synopsis::
 
     edgedb branch wipe [<options>] <name>
 
+.. note::
+
+    This CLI command requires CLI version 4.3.0 or later and EdgeDB version 5.0
+    or later. If you are running an earlier version of EdgeDB, you will instead
+    use the :ref:`ref_cli_edgedb_database_wipe` command to wipe a database,
+    which branches replaced in EdgeDB 5.0.
+
 
 Description
 ===========

docs/cli/edgedb_branch/index.rst

@@ -22,6 +22,7 @@ tools.
     edgedb_branch_create
     edgedb_branch_drop
     edgedb_branch_list
+    edgedb_branch_merge
     edgedb_branch_rebase
     edgedb_branch_rename
     edgedb_branch_switch
@@ -36,6 +37,8 @@ tools.
       - Drop a branch
     * - :ref:`ref_cli_edgedb_branch_list`
       - List all branches
+    * - :ref:`ref_cli_edgedb_branch_merge`
+      - Merge a branch into the current branch
     * - :ref:`ref_cli_edgedb_branch_rebase`
       - Create a branch based on a target branch
     * - :ref:`ref_cli_edgedb_branch_rename`

docs/guides/cheatsheet/admin.rst

@@ -3,12 +3,34 @@
 Administering an instance
 =========================
 
-Create a database:
+Create a schema branch:
 
 .. code-block:: edgeql-repl
 
-    db> create database my_new_project;
-    OK: CREATE DATABASE
+    db> create schema branch my_new_feature from main;
+    OK: CREATE BRANCH
+
+
+----------
+
+
+Create a data branch:
+
+.. code-block:: edgeql-repl
+
+    db> create data branch my_new_feature from main;
+    OK: CREATE BRANCH
+
+
+----------
+
+
+Create an empty branch:
+
+.. code-block:: edgeql-repl
+
+    db> create empty branch my_new_feature;
+    OK: CREATE BRANCH
 
 
 ----------