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 (``master`` 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 <install-git>` 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, execute::
+To install ``git`` on CentOS/RHEL, run the following command:
- sudo yum install git
+.. prompt:: bash $
+ 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
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
-Get the key to add to your ``github`` account (the following example
-assumes you used the default file path)::
+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.):
- cat .ssh/id_rsa.pub
+.. prompt:: bash $
+
+ 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.
Clone the Source
================
-To clone the Ceph source code repository, execute::
+To clone the Ceph source code repository, run the following command:
+
+.. prompt:: bash $
- git clone --recursive https://github.com/ceph/ceph.git
+ git clone --recursive https://github.com/ceph/ceph.git
-Once ``git clone`` executes, you should have a full copy of the Ceph
+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:
+
+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:
-If your submodules are out of date, run::
+ ::
+
+ 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.
- git submodule update --force --init --recursive
+
+ 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 ``master`` branch by default, which is the unstable
+will be on the ``main`` branch by default, which is the unstable
development branch. You may choose other branches too.
-- ``master``: The unstable development branch.
-- ``stable``: The bugfix branch.
+- ``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 master
+ git checkout main
+
+.. _Active Releases: https://docs.ceph.com/en/latest/releases/#active-releases
projects / ceph.git / blobdiff