diff options
Diffstat (limited to 'doc/install/clone-source.rst')
| -rw-r--r-- | doc/install/clone-source.rst | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/doc/install/clone-source.rst b/doc/install/clone-source.rst new file mode 100644 index 000000000..2d09ef9eb --- /dev/null +++ b/doc/install/clone-source.rst @@ -0,0 +1,195 @@ +========================================= + Cloning the Ceph Source Code Repository +========================================= + +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 <install-git>` and configure +``git``. + +.. _install-git: + +Install Git +=========== + +To install ``git`` on Debian/Ubuntu, run the following command: + +.. prompt:: bash $ + + sudo apt-get install git + + +To install ``git`` on CentOS/RHEL, run the following command: + +.. prompt:: bash $ + + sudo yum install 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 + + +Add SSH Keys (Optional) +======================= + +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 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``, run the following command: + +.. prompt:: bash $ + + 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.): + +.. prompt:: bash $ + + cat .ssh/id_rsa.pub + +Copy the public key. + +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. + + +Clone the Source +================ + +To clone the Ceph source code repository, run the following command: + +.. prompt:: bash $ + + 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 whether the submodules + are out of date. See :ref:`update-submodules` for more information. + + +.. prompt:: bash $ + + cd ceph + git status + +.. _update-submodules: + +Updating Submodules +------------------- + +#. Determine whether your submodules are out of date: + + .. prompt:: bash $ + + git status + + A. 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. + + + B. 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 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: + + .. 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 +=============== + +Once you clone the source code and submodules, your Ceph repository +will be on the ``main`` branch by default, which is the unstable +development branch. You may choose other branches too. + +- ``main``: The unstable development branch. +- ``stable-release-name``: The name of the stable, `Active Releases`_. e.g. ``Pacific`` +- ``next``: The release candidate branch. + +:: + + git checkout main + +.. _Active Releases: https://docs.ceph.com/en/latest/releases/#active-releases |