Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Document how to fetch additional branches #10795

Merged
merged 1 commit into from
Oct 24, 2023
Merged

docs: Document how to fetch additional branches #10795

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion docs/user/build-customization.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,8 @@ we recommend you use them as a starting point.
Unshallow git clone
^^^^^^^^^^^^^^^^^^^

Read the Docs does not perform a full clone on ``checkout`` job to reduce network data and speed up the build process.
Read the Docs does not perform a full clone in the ``checkout`` job in order to reduce network data and speed up the build process.
Instead, it performs a `shallow clone <https://git-scm.com/docs/shallow>`_ and only fetches the branch or tag that you are building documentation for.
Because of this, extensions that depend on the full Git history will fail.
To avoid this, it's possible to unshallow the :program:`git clone`:

Expand All @@ -104,6 +105,22 @@ To avoid this, it's possible to unshallow the :program:`git clone`:
post_checkout:
- git fetch --unshallow || true

If your build also relies on the contents of other branches, it may also be necessary to re-configure git to fetch these:

.. code-block:: yaml
:caption: .readthedocs.yaml

version: 2
build:
os: "ubuntu-20.04"
tools:
python: "3.10"
jobs:
post_checkout:
- git fetch --unshallow || true
- git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*' || true
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this line required? Seems pretty specific to a use case, and something I'd expect git to do by default?

Copy link
Contributor Author

@stephenfin stephenfin Oct 7, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is necessary because we're configuring git to only fetch a single branch in this command (which you'll see a variant of in all builds):

git fetch origin --force --prune --prune-tags --depth 50 refs/heads/main:refs/remotes/origin/main

If you shallow clone a repo then run the above locally and look at .git/config, you'll see something like the following:

[remote "origin"]
fetch = +refs/heads/main:refs/remotes/origin/main

Which means "map the main ref locally to the main remote ref". Because we've limited fetch to a single branch, we will always get just that single branch no matter what flags we pass. To fix this, you need to tell git to fetch all branches and map them to the same name locally, which is what we're doing here.

Perhaps there's another way to override the config file during a fetch operation, but if there is I'm not aware of it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, and as I mentioned in the blurb beforehand, you'll need to do this if you have a tool that needs access to other branches rather than just other tags.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gotcha -- Thanks!

- git fetch --all --tags || true


Cancel build based on a condition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand Down