diff --git a/doc/flatpak-builder.xml b/doc/flatpak-builder.xml
index 6cc19e2b..a7816ebf 100644
--- a/doc/flatpak-builder.xml
+++ b/doc/flatpak-builder.xml
@@ -542,6 +542,26 @@
                 <listitem><para>
                   When downloading sources (archives, files, git, bzr, svn), look in this
                   directory for pre-existing copies and use them instead of downloading.
+                  The directory must match the state directory structure:
+                  <itemizedlist>
+                    <listitem>
+                        <para>Files and archives must be inside the folder: <filename>downloads/&lt;sha256&gt;/</filename></para>
+                    </listitem>
+                    <listitem>
+                        <para>
+                            Sources of type <literal>git</literal>, <literal>bzr</literal> and <literal>svn</literal>
+                            must be inside the folder: <filename>&lt;type&gt;/&lt;converted-uri&gt;/</filename>
+                        </para>
+                    </listitem>
+                  </itemizedlist>
+                  The <literal>converted-uri</literal> is constructed from <literal>path</literal> or <literal>url</literal> (in case of <literal>git</literal>)
+                  and from <literal>url</literal> (in case of <literal>bzr</literal> and <literal>svn</literal>). <literal>://</literal> is converted to a single
+                  underscore and every other <literal>/</literal> is replaced by an underscore. For example, <literal>https://github.com/user/repo.git</literal>
+                  becomes <literal>https_github.com_user_repo.git</literal>.
+
+                  In case of <literal>svn</literal> sources if <literal>revision</literal> is present, the folder name is
+                  <filename>svn/&lt;converted-uri&gt;__r&lt;revision&gt;/</filename>. In case of <literal>git</literal>
+                  sources, it needs to be a mirrored clone.
                 </para></listitem>
             </varlistentry>
 
diff --git a/src/builder-main.c b/src/builder-main.c
index 45103629..70fb8bbb 100644
--- a/src/builder-main.c
+++ b/src/builder-main.c
@@ -107,7 +107,7 @@ static GOptionEntry entries[] = {
   { "disable-updates", 0, 0, G_OPTION_ARG_NONE, &opt_disable_updates, "Only download missing sources, never update to latest vcs version", NULL },
   { "download-only", 0, 0, G_OPTION_ARG_NONE, &opt_download_only, "Only download sources, don't build", NULL },
   { "bundle-sources", 0, 0, G_OPTION_ARG_NONE, &opt_bundle_sources, "Bundle module sources as runtime", NULL },
-  { "extra-sources", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_sources_dirs, "Add a directory of sources specified by SOURCE-DIR, multiple uses of this option possible", "SOURCE-DIR"},
+  { "extra-sources", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_sources_dirs, "Add an extra source directory with state directory structure. The option can be repeated", "SOURCE-DIR"},
   { "extra-sources-url", 0, 0, G_OPTION_ARG_STRING_ARRAY, &opt_sources_urls, "Add a url of sources specified by SOURCE-URL multiple uses of this option possible", "SOURCE-URL"},
   { "build-only", 0, 0, G_OPTION_ARG_NONE, &opt_build_only, "Stop after build, don't run clean and finish phases", NULL },
   { "finish-only", 0, 0, G_OPTION_ARG_NONE, &opt_finish_only, "Only run clean and finish and export phases", NULL },