From 0de073334628a791582eb9b424eb091ea049bc7c Mon Sep 17 00:00:00 2001
From: Zac Dover <zac.dover@gmail.com>
Date: Wed, 12 Oct 2022 18:27:42 +1000
Subject: [PATCH] doc/install: improve updating submodules procedure

This commit beefs up the "Updating Submodules" procedure,
which (prior to this commit) was quite brief.

Signed-off-by: Zac Dover <zac.dover@gmail.com>
(cherry picked from commit 9382a90342f96cabab4b7caf816d9381f77e7f46)
---
 doc/install/clone-source.rst | 82 ++++++++++++++++++++++++++++++++++--
 1 file changed, 79 insertions(+), 3 deletions(-)

diff --git a/doc/install/clone-source.rst b/doc/install/clone-source.rst
index 2de8518cdda4..f394366e5299 100644
--- a/doc/install/clone-source.rst
+++ b/doc/install/clone-source.rst
@@ -81,9 +81,85 @@ repository.
 	cd ceph
 	git status
 
-If your submodules are out of date, run::
-
-	git submodule update --force --init --recursive
+.. _update-submodules:
+
+Updating Submodules
+-------------------
+
+#. Determine whether your submodules are out of date:
+
+   .. prompt:: bash $
+
+      git status
+
+   #. If your submodules are up to date 
+         If your submodules are up to date, the following console output will
+         appear: 
+
+         ::
+   
+           On branch main
+           Your branch is up to date with 'origin/main'.
+           
+           nothing to commit, working tree clean
+   
+         If you see this console output, then your submodules are up to date.
+         You do not need this procedure.
+
+
+   #. If your submodules are not up to date 
+         If your submodules are not up to date, you will see a message that
+         includes a list of "untracked files". The example here shows such a
+         list, which was generated from a real situation in which the
+         submodules were no longer current. Your list of files will not be the
+         same as this list of files, but this list is provided as an example.
+         If in your case any untracked files are listed, then you should
+         continue to the next step of this procedure.
+
+         ::
+
+            On branch main
+            Your branch is up to date with 'origin/main'.
+            
+            Untracked files:
+              (use "git add <file>..." to include in what will be committed)
+            src/pybind/cephfs/build/
+            src/pybind/cephfs/cephfs.c
+            src/pybind/cephfs/cephfs.egg-info/
+            src/pybind/rados/build/
+            src/pybind/rados/rados.c
+            src/pybind/rados/rados.egg-info/
+            src/pybind/rbd/build/
+            src/pybind/rbd/rbd.c
+            src/pybind/rbd/rbd.egg-info/
+            src/pybind/rgw/build/
+            src/pybind/rgw/rgw.c
+            src/pybind/rgw/rgw.egg-info/
+            
+            nothing added to commit but untracked files present (use "git add" to track)
+
+#. If your submodules are out of date, run the following commands:
+
+   .. prompt:: bash $
+
+      git submodule update --force --init --recursive
+      git clean -fdx
+      git submodule foreach clean -fdx
+
+#. Run ``git status`` again:
+
+   .. prompt:: bash $
+
+      git status
+   
+   Your submodules are up to date if you see the following message:
+
+   ::
+
+     On branch main
+     Your branch is up to date with 'origin/main'.
+     
+     nothing to commit, working tree clean
 
 Choose a Branch
 ===============
-- 
2.47.3