diff --git a/doc/05-repositories.md b/doc/05-repositories.md
index de6e323b0..369c46e14 100644
--- a/doc/05-repositories.md
+++ b/doc/05-repositories.md
@@ -548,6 +548,14 @@ Here is an example for the smarty template engine:
 
 Typically, you would leave the source part off, as you don't really need it.
 
+If a source key is included, the reference field should be a reference to the version that will be installed.
+Where the type field is `git`, this will the be the commit id, branch or tag name.
+
+**Note**: It is not recommended to use a git branch name for the reference field. While this is valid since it is supported by `git checkout`,
+branch names are mutable so cannot be locked.
+
+Where the type field is `svn`, the reference field should contain the reference that gets appended to the URL when running `svn co`.
+
 > **Note**: This repository type has a few limitations and should be avoided
 > whenever possible:
 >