Add `--fresh` to docs to actually upgrade spack environments (#34433)

1 files changed, 40 insertions, 5 deletions

diff --git a/lib/spack/docs/replace_conda_homebrew.rst b/lib/spack/docs/replace_conda_homebrew.rst
index 3f640e35cf..a88fedffac 100644
--- a/lib/spack/docs/replace_conda_homebrew.rst
+++ b/lib/spack/docs/replace_conda_homebrew.rst
@@ -184,13 +184,48 @@ simply run the following commands:
 .. code-block:: console
 
    $ spack env activate myenv
-   $ spack concretize --force
+   $ spack concretize --fresh --force
    $ spack install
 
-The ``--force`` flag tells Spack to overwrite its previous concretization
-decisions, allowing you to choose a new version of Python. If any of the new
-packages like Bash are already installed, ``spack install`` won't re-install
-them, it will keep the symlinks in place.
+The ``--fresh`` flag tells Spack to use the latest version of every package
+where possible instead of trying to optimize for reuse of existing installed
+packages.
+
+The ``--force`` flag in addition tells Spack to overwrite its previous 
+concretization decisions, allowing you to choose a new version of Python. 
+If any of the new packages like Bash are already installed, ``spack install`` 
+won't re-install them, it will keep the symlinks in place.
+
+-----------------------------------
+Updating & Cleaning Up Old Packages
+-----------------------------------
+
+If you're looking to mimic the behavior of Homebrew, you may also want to 
+clean up out-of-date packages from your environment after an upgrade. To 
+upgrade your entire software stack within an environment and clean up old 
+package versions, simply run the following commands:
+
+.. code-block:: console
+
+   $ spack env activate myenv
+   $ spack mark -i --all
+   $ spack concretize --fresh --force
+   $ spack install
+   $ spack gc
+   
+Running ``spack mark -i --all`` tells Spack to mark all of the existing 
+packages within an environment as "implicitly" installed. This tells 
+spack's garbage collection system that these packages should be cleaned up.
+
+Don't worry however, this will not remove your entire environment.
+Running ``spack install`` will reexamine your spack environment after
+a fresh concretization and will re-mark any packages that should remain
+installed as "explicitly" installed.
+
+**Note:** if you use multiple spack environments you should re-run ``spack install``
+in each of your environments prior to running ``spack gc`` to prevent spack 
+from uninstalling any shared packages that are no longer required by the 
+environment you just upgraded.
 
 --------------
 Uninstallation