Add troubleshooting section for building

flatpak · Oct 22, 2023 · 95ffefe · 95ffefe
1 parent 7c0b1c8
commit 95ffefe
Show file tree

Hide file tree

Showing 2 changed files with 17 additions and 0 deletions.
diff --git a/docs/building.rst b/docs/building.rst
@@ -19,3 +19,4 @@ before reading this section.
    manifests
    sandbox-permissions
    guides
+   troubleshooting
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
@@ -0,0 +1,16 @@
+Troubleshooting
+===============
+
+Sometimes you run into issues when building Flatpaks. This page includes a list
+of common problems and how to solve them.
+
+Remote server doesn't support shallow cloning
+---------------------------------------------
+
+If you get an error message like
+``fatal: dumb http transport does not support shallow capabilities`` when
+building your Flatpak application, it's because ``flatpak-builder`` will by
+default attempt to shallow clone git repositories as an optimisation. However,
+not all git remotes support shallow cloning, and in such cases you can disable
+this optimisation by setting the ``disable-shallow-clone`` property to ``true``
+in your source.