Edit README_EXTERNALS.rst

- Talk about this in the context of CTSM rather than CESM

- Cut documentation on modifying a component, because we currently don't
  have a great workflow for doing this with components in git (due to
  ESMCI/manage_externals#34)

README_EXTERNALS.rst

@@ -1,136 +1,105 @@
-==================================
- The Community Earth System Model
-==================================
-
-See the CESM web site for documentation and information:
-
-http://www.cesm.ucar.edu
-
-This repository provides tools for managing the external components that
-make up a CESM tag - alpha, beta and release. CESM tag creation should
-be coordinated through CSEG at NCAR.
-
-.. sectnum::
-
-.. contents::
-
 Obtaining the full model code and associated scripting infrastructure
 =====================================================================
 
-CESM2.0 is now released via github. You will need some familiarity with git in order
+CTSM is released via github. You will need some familiarity with git in order
 to modify the code and commit these changes. However, to simply checkout and run the
 code, no git knowledge is required other than what is documented in the following steps.
 
-To obtain the CESM2.0 code you need to do the following:
+To obtain the CTSM code you need to do the following:
 
 #. Clone the repository. ::
 
-      git clone https://github.com/escomp/cesm.git my_cesm_sandbox
-
-   This will create a directory ``my_cesm_sandbox/`` in your current working directory.
-
-#. Go into the newly created CESM repository and determine what version of CESM you want.
-   To see what cesm tags are available, simply issue the **git tag** command. ::
-
-      cd my_cesm_sandbox
-      git tag
-
-#. Do a git checkout of the tag you want. If you want to checkout cesm2.0.beta07, you would issue the following. ::
+      git clone https://github.com/escomp/ctsm.git my_ctsm_sandbox
 
-      git checkout cesm2.0.beta07
-
-   (It is normal and expected to get a message about being in 'detached
-   HEAD' state. For now you can ignore this, but it becomes important if
-   you want to make changes to your Externals.cfg file and commit those
-   changes to a branch.)
+   This will create a directory ``my_ctsm_sandbox/`` in your current working directory.
 
 #. Run the script **manage_externals/checkout_externals**. ::
 
       ./manage_externals/checkout_externals
 
    The **checkout_externals** script is a package manager that will
-   populate the cesm directory with the relevant versions of each of the
+   populate the ctsm directory with the relevant versions of each of the
    components along with the CIME infrastructure code.
 
-At this point you have a working version of CESM.
+At this point you have a working version of CTSM.
 
 To see full details of how to set up a case, compile and run, see the CIME documentation at http://esmci.github.io/cime/ .
 
 More details on checkout_externals
 ----------------------------------
 
-The file **Externals.cfg** in your top-level CESM directory tells
+The file **Externals.cfg** in your top-level CTSM directory tells
 **checkout_externals** which tag/branch of each component should be
 brought in to generate your sandbox. (This file serves the same purpose
-as SVN_EXTERNAL_DIRECTORIES when CESM was in a subversion repository.)
+as SVN_EXTERNAL_DIRECTORIES when CLM was in a subversion repository.)
 
 NOTE: Just like svn externals, checkout_externals 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 checkout_externals will switch you
 back to the external described in Externals.cfg. See below
-documentation `Customizing your CESM sandbox`_ for more details.
+documentation `Customizing your CTSM sandbox`_ for more details.
 
 **You need to rerun checkout_externals whenever Externals.cfg 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:
 
-* After checking out a new CESM branch/tag
+* After checking out a new CTSM branch/tag
 
-* After merging some other CESM branch/tag into your currently
+* After merging some other CTSM branch/tag into your currently
   checked-out branch
 
 **checkout_externals** must be run from the root of the source
-tree. For example, if you cloned CESM with::
+tree. For example, if you cloned CTSM with::
 
-  git clone https://github.com/escomp/cesm.git my_cesm_sandbox
+  git clone https://github.com/escomp/ctsm.git my_ctsm_sandbox
 
 then you must run **checkout_externals** from
-``/path/to/my_cesm_sandbox``.
+``/path/to/my_ctsm_sandbox``.
 
 To see more details of **checkout_externals**, issue ::
 
   ./manage_externals/checkout_externals --help
 
-Customizing your CESM sandbox
+Customizing your CTSM sandbox
 =============================
 
-There are several use cases to consider when you want to customize or modify your CESM sandbox.
+There are several use cases to consider when you want to customize or modify your CTSM sandbox.
 
-Switching to a different CESM tag
----------------------------------
+Switching to a different CTSM branch or tag
+-------------------------------------------
 
-If you have already checked out a tag and **HAVE NOT MADE ANY
+If you have already checked out a branch or tag and **HAVE NOT MADE ANY
 MODIFICATIONS** it is simple to change your sandbox. Say that you
-checked out cesm2.0.beta07 but really wanted to have cesm2.0.beta08;
+checked out ctsm1.0.0 but really wanted to have ctsm1.1.0;
 you would simply do the following::
 
-  git checkout cesm2.0.beta08
+  git checkout ctsm1.1.0
   ./manage_externals/checkout_externals
 
 You should **not** use this method if you have made any source code
-changes, or if you have any ongoing CESM cases that were created from
+changes, or if you have any ongoing CTSM cases that were created from
 this sandbox. In these cases, it is often easiest to do a second **git
 clone**.
 
 Pointing to a different version of a component
 ----------------------------------------------
 
-Each entry in **Externals.cfg** has the following form (we use CAM as an
+Each entry in **Externals.cfg** has the following form (we use CIME as an
 example below)::
- 
-  [cam]
-  tag = trunk_tags/cam5_4_143/components/cam
-  protocol = svn
-  repo_url = https://svn-ccsm-models.cgd.ucar.edu/cam1
-  local_path = components/cam
+
+  [cime]
+  local_path = cime
+  protocol = git
+  repo_url = https://github.com/CESM-Development/cime
+  tag = cime5.4.0-alpha.20
   required = True
 
 Each entry specifies either a tag or a branch. To point to a new tag:
 
 #. Modify the relevant entry/entries in **Externals.cfg** (e.g., changing
-   ``cam5_4_143`` to ``cam5_4_144`` above)
+   ``cime5.4.0-alpha.20`` to ``cime5.4.0-alpha.21`` above)
 
 #. Checkout the new component(s)::
 
@@ -141,43 +110,15 @@ in an invalid model (won't compile, won't run, not scientifically
 meaningful) and is unsupported.
 
 Committing your change to Externals.cfg
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After making this change, it's a good idea to commit the change in your
-local CESM git repository. First create a CESM branch in your local
+local CTSM git repository. First create a branch in your local
 repository, then commit it. (Unlike with subversion, branches are stored
 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_cesm_branch
+  git checkout -b my_ctsm_branch
   git add Externals.cfg
-  git commit -m "Update CAM to cam5_4_144"
-
-Modifying a component
----------------------
-
-If you'd like to modify a component via a branch and point to that
-branch in your CESM sandbox, use the following procedure (again, using
-CAM as an example):
-
-#. Create a CAM branch. Since CAM originates from a subversion
-   repository, you will first need to create a branch in that
-   repository. Let's assume you have created this branch and called it
-   **my_branch**.
-
-#. Update **Externals.cfg** to point to your branch. You can replace the
-   **tag** entry with a **branch** entry, as follows::
-
-     [cam]
-     branch = branches/my_branch/components/cam
-     protocol = svn
-     repo_url = https://svn-ccsm-models.cgd.ucar.edu/cam1
-     local_path = components/cam
-     required = True
-
-#. Checkout your branch::
-
-     ./manage_externals/checkout_externals
+  git commit -m "Update CIME to cime5.4.0-alpha.20"
 
-It's a good idea to commit your **Externals.cfg** file changes. See the above
-documentation, `Committing your change to Externals.cfg`_.