diff --git a/doc/BUILD.rst b/doc/BUILD.rst index a4a112ff..7416440c 100644 --- a/doc/BUILD.rst +++ b/doc/BUILD.rst @@ -17,11 +17,11 @@ following: git clone --depth=1 --recurse-submodules https://github.com/taisei-project/taisei -The ``--depth=1`` flag is highly recommended, as it significantly reduces the -amount of data that needs to be downloaded, making the cloning process much -faster. Without it, the entire commit history of the repository would be -fetched, which can be quite large. If you accidentally omit it during checkout, -you can fix it with: +The ``--depth=1`` flag is highly recommended if you only need to build Taisei, +as it significantly reduces the amount of data that needs to be downloaded, +making the cloning process much faster. Without it, the entire commit history +of the repository would be fetched, which can be quite large. If you +accidentally omit it during checkout, you can fix it with: .. code:: sh @@ -29,6 +29,9 @@ you can fix it with: git checkout --detach && git reset --hard && git rev-parse --short HEAD git fetch --depth=1 origin +**However,** if a comprehensive history is necessary for troubleshooting or +other purposes, perform a full clone by omitting the depth flag. + The ``--recurse-submodules`` flag is absolutely necessary, or Taisei will not build, as it will be missing many of the dependencies its needs to compile. If you accidentally omit it during checkout, you can fix it with: @@ -38,6 +41,18 @@ you accidentally omit it during checkout, you can fix it with: cd taisei/ git submodule update --init --recursive +Unrolling Commit History +------------------------ + +If a shallow clone has been performed and comprehensive repository history is +required for troubleshooting or other purposes, unroll the commit history using +the following: + +.. code:: sh + + cd taisei/ + git fetch --unshallow + Dependencies ------------