Replace checkout_externals with git-fleximod in documentation

README_GITFLEXIMOD.rst

@@ -15,11 +15,15 @@ To obtain the CTSM code you need to do the following:
 
 #. Run **./bin/git-fleximod update**. ::
 
+      cd my_ctsm_sandbox
       ./bin/git-fleximod update
+      ./bin/git-fleximod --help  # for a user's guide
 
    **git-fleximod** is a package manager that will
    populate the ctsm directory with the relevant versions of each of the
    components along with the CIME infrastructure code.
+   Additional documentation for git-fleximod appears here:
+   https://github.com/ESMCI/git-fleximod?tab=readme-ov-file#git-fleximod
 
 At this point you have a working version of CTSM.
 
@@ -28,18 +32,18 @@ To see full details of how to set up a case, compile and run, see the CIME docum
 More details on git-fleximod
 ----------------------------
 
-The file **Externals.cfg** in your top-level CTSM directory tells
+The file **.gitmodules** in your top-level CTSM directory tells
 **git-fleximod** which tag/branch of each component should be
-brought in to generate your sandbox. **Externals_CLM.cfg** is used similarly to point to the correct version of FATES (and possibly other CTSM-specific externals in the future); the below instructions referring to **Externals.cfg** also apply to modifying **Externals_CLM.cfg**.
+brought in to generate your sandbox.
 
-NOTE: git-fleximod will always attempt
-to make the working copy exactly match the externals description. If
-you manually modify an external without updating Externals.cfg, e.g. switch
-to a different tag, then rerunning git-fleximod will switch you
-back to the external described in Externals.cfg. See below
-documentation `Customizing your CTSM sandbox`_ for more details.
+NOTE: If you manually modify an external without updating .gitmodules,
+e.g. switch to a different tag, then rerunning git-fleximod will warn you of
+local changes you need to resolve.
+git-fleximod will not change a modified external back to what is specified in
+.gitmodules without the --force option.
+See below documentation `Customizing your CTSM sandbox`_ for more details.
 
-**You need to rerun git-fleximod whenever Externals.cfg has
+**You need to rerun git-fleximod whenever .gitmodules has
 changed** (unless you have already manually updated the relevant
 external(s) to have the correct branch/tag checked out). Common times
 when this is needed are:
@@ -49,18 +53,6 @@ when this is needed are:
 * After merging some other CTSM branch/tag into your currently
   checked-out branch
 
-**./bin/git-fleximod** must be run from the root of the source
-tree. For example, if you cloned CTSM with::
-
-  git clone https://github.com/escomp/ctsm.git my_ctsm_sandbox
-
-then you must run **./bin/git-fleximod** from
-``/path/to/my_ctsm_sandbox``.
-
-To see more details of **git-fleximod**, issue ::
-
-  ./bin/git-fleximod --help
-
 Customizing your CTSM sandbox
 =============================
 
@@ -75,7 +67,7 @@ checked out ctsm1.0.0 but really wanted to have ctsm1.1.0;
 you would simply do the following::
 
   git checkout ctsm1.1.0
-  ./bin/git-fleximod
+  ./bin/git-fleximod update
 
 You should **not** use this method if you have made any source code
 changes, or if you have any ongoing CTSM cases that were created from
@@ -85,35 +77,31 @@ clone**.
 Pointing to a different version of a component
 ----------------------------------------------
 
-Each entry in **Externals.cfg** has the following form (we use CIME as an
+Each entry in **.gitmodules** has the following form (we use CIME as an
 example below)::
 
-  [cime]
-  local_path = cime
-  protocol = git
-  repo_url = https://github.com/CESM-Development/cime
-  tag = cime5.4.0-alpha.20
-  required = True
+  [submodule "cime"]
+  path = cime
+  url = https://github.com/ESMCI/cime
+  fxtag = cime6.0.246
+  fxrequired = ToplevelRequired
+  fxDONOTUSEurl = https://github.com/ESMCI/cime
 
-Each entry specifies either a tag, a hash or a branch. To point to a new tag:
+Each entry specifies either a tag or a hash. To point to a new tag or hash:
 
-#. Modify the relevant entry/entries in **Externals.cfg** (e.g., changing
-   ``cime5.4.0-alpha.20`` to ``cime5.4.0-alpha.21`` above)
+#. Modify the relevant entry/entries in **.gitmodules** (e.g., changing
+   ``cime6.0.246`` to ``cime6.0.247`` above)
 
 #. Checkout the new component(s)::
 
-     ./bin/git-fleximod
-
-To point to a hash, the process is the same, except also change ``tag = ...`` to ``hash = ...``.
-
-To point to a branch, use ``branch = ...``. Pointing to a branch means that, each time you run ``./bin/git-fleximod`` you will get the current latest version of that branch. This can be convenient for in-progress development work, but should not be used when you need a stable version for scientific simulations. There are a number of gotchas with this workflow, so in general you should default to pointing to fixed hashes. (For CTSM master, we require a fixed hash or, usually, a tag.)
+     ./bin/git-fleximod update <component>
 
 Keep in mind that changing individual components from a tag may result
 in an invalid model (won't compile, won't run, not scientifically
 meaningful) and is unsupported.
 
-Committing your change to Externals.cfg
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Committing your change to .gitmodules
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After making this change, it's a good idea to commit the change in your
 local CTSM git repository. First create a branch in your local
@@ -122,6 +110,6 @@ locally unless you explicitly push them up to GitHub. Feel free to
 create whatever local branches you'd like.) For example::
 
   git checkout -b my_ctsm_branch
-  git add Externals.cfg
+  git add .gitmodules
   git commit -m "Update CIME to cime5.4.0-alpha.20"
 

doc/source/lilac/obtaining-building-and-running/obtaining-and-building-ctsm.rst

@@ -91,7 +91,7 @@ Building CTSM requires:
 
 - ESMF version 8 or later
 
-  - **ESMF is not needed in general for CTSM, but is needed for LILAC**
+  - **ESMF is needed for LILAC (and for CESM3 and later)**
 
 Obtaining CTSM
 ==============
@@ -149,10 +149,11 @@ If you are using a machine that has been ported to CIME_ (for example, NCAR's ``
 machine), then you do not need to specify much information to ``build_ctsm``. In addition,
 in this case, CIME will load the appropriate modules and set the appropriate environment
 variables at build time, so you do not need to do anything to set up your environment
-ahead of time. **Building CTSM with LILAC requires ESMF. ESMF is currently an optional
-CIME dependency, so many CIME-ported machines do not provide information on an ESMF
-installation. NCAR's derecho machine DOES provide ESMF, but for other machines, you may
-need to add this to your CIME port.**
+ahead of time. **Building CTSM with LILAC requires ESMF. ESMF is an optional
+CIME dependency before CESM3 and not optional for CESM3.
+NCAR's derecho machine DOES provide ESMF. For other machines, you may
+need to add this to your CIME port. Please see esmf.org for download and build
+instructions.**
 
 To build CTSM and its dependencies in this case, run::