From 7e93720a5c77bff4208477e3d3fdf626968313a2 Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Sun, 11 Dec 2022 06:25:13 +1000 Subject: [PATCH] doc/install: update clone-source.rst Beef up clone-source.rst. Repair semantics. Add internal references. Fix a broken "git submodule foreach git clean -fdx" command. Signed-off-by: Zac Dover (cherry picked from commit 344ef1553e4d0ec86153252891a194097548c602) --- doc/install/clone-source.rst | 80 +++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 32 deletions(-) diff --git a/doc/install/clone-source.rst b/doc/install/clone-source.rst index 31b9d9993f48e..2d09ef9ebabe3 100644 --- a/doc/install/clone-source.rst +++ b/doc/install/clone-source.rst @@ -2,33 +2,37 @@ Cloning the Ceph Source Code Repository ========================================= -You may clone a Ceph branch of the Ceph source code by going to `github Ceph -Repository`_, selecting a branch (``main`` by default), and clicking the -**Download ZIP** button. +To clone a Ceph branch of the Ceph source code, go to `github Ceph +Repository`_, select a branch (``main`` by default), and click the **Download +ZIP** button. .. _github Ceph Repository: https://github.com/ceph/ceph +To clone the entire git repository, :ref:`install ` and configure +``git``. -To clone the entire git repository, install and configure ``git``. - +.. _install-git: Install Git =========== -To install ``git`` on Debian/Ubuntu, execute:: +To install ``git`` on Debian/Ubuntu, run the following command: + +.. prompt:: bash $ + + sudo apt-get install git - sudo apt-get install git +To install ``git`` on CentOS/RHEL, run the following command: -To install ``git`` on CentOS/RHEL, execute:: +.. prompt:: bash $ - sudo yum install git + sudo yum install git -You must also have a ``github`` account. If you do not have a -``github`` account, go to `github.com`_ and register. -Follow the directions for setting up git at -`Set Up Git`_. +You must have a ``github`` account. If you do not have a ``github`` +account, go to `github.com`_ and register. Follow the directions for setting +up git at `Set Up Git`_. .. _github.com: https://github.com .. _Set Up Git: https://help.github.com/linux-set-up-git @@ -37,26 +41,31 @@ Follow the directions for setting up git at Add SSH Keys (Optional) ======================= -If you intend to commit code to Ceph or to clone using SSH +To commit code to Ceph or to clone the respository by using SSH (``git@github.com:ceph/ceph.git``), you must generate SSH keys for github. -.. tip:: If you only intend to clone the repository, you may +.. tip:: If you want only to clone the repository, you can use ``git clone --recursive https://github.com/ceph/ceph.git`` without generating SSH keys. -To generate SSH keys for ``github``, execute:: +To generate SSH keys for ``github``, run the following command: + +.. prompt:: bash $ + + ssh-keygen - ssh-keygen +To print the SSH key that you just generated and that you will add to your +``github`` account, use the ``cat`` command. (The following example assumes you +used the default file path.): -Get the key to add to your ``github`` account (the following example -assumes you used the default file path):: +.. prompt:: bash $ - cat .ssh/id_rsa.pub + cat .ssh/id_rsa.pub Copy the public key. -Go to your ``github`` account, click on "Account Settings" (i.e., the -'tools' icon); then, click "SSH Keys" on the left side navbar. +Go to your ``github`` account, click "Account Settings" (represented by the +'tools' icon), and click "SSH Keys" on the left side navbar. Click "Add SSH key" in the "SSH Keys" list, enter a name for the key, paste the key you generated, and press the "Add key" button. @@ -65,21 +74,24 @@ key you generated, and press the "Add key" button. Clone the Source ================ -To clone the Ceph source code repository, execute:: +To clone the Ceph source code repository, run the following command: - git clone --recursive https://github.com/ceph/ceph.git +.. prompt:: bash $ -Once ``git clone`` executes, you should have a full copy of the Ceph + git clone --recursive https://github.com/ceph/ceph.git + +After ``git clone`` has run, you should have a full copy of the Ceph repository. -.. tip:: Make sure you maintain the latest copies of the submodules - included in the repository. Running ``git status`` will tell you if - the submodules are out of date. +.. tip:: Make sure you maintain the latest copies of the submodules included in + the repository. Running ``git status`` will tell you whether the submodules + are out of date. See :ref:`update-submodules` for more information. -:: - cd ceph - git status +.. prompt:: bash $ + + cd ceph + git status .. _update-submodules: @@ -144,7 +156,11 @@ Updating Submodules git submodule update --force --init --recursive git clean -fdx - git submodule foreach clean -fdx + git submodule foreach git clean -fdx + + If you still have problems with a submodule directory, use ``rm -rf + [directory name]`` to remove the directory. Then run ``git submodule update + --init --recursive`` again. #. Run ``git status`` again: -- 2.39.5