docs: Document how to fetch additional branches

[stephenfin]

Tools like reno depend on a complete git history. Simply unshallowing a clone is not sufficient, as we specifically fetch from the branch or tag that we are building docs for, e.g.:

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

Add documentation describing how you can correct this if necessary.

---

📚 Documentation previews 📚

• User's documentation (docs): https://docs--10795.org.readthedocs.build/en/10795/

• Developer's documentation (dev): https://dev--10795.org.readthedocs.build/en/10795/

[ericholscher]

Thanks for the contribution. If there's a specific tool that this is useful for, it's probably worth mentioning in the text, so it's easier to Google for.

[ericholscher]

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

[stephenfin]

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.

[stephenfin]

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.

[ericholscher]

Gotcha -- Thanks!