From 9acf6bc0a1f83a47f754e0c31c829f1860f91642 Mon Sep 17 00:00:00 2001
From: theoboldalex <44616505+theoboldalex@users.noreply.github.com>
Date: Fri, 9 Feb 2024 13:17:21 +0000
Subject: [PATCH] Repositories docs reference (#11840)

* doc: Adds docs for reference field on package repo

* fixes double space

* minor grammar fix
---
 doc/05-repositories.md | 8 ++++++++
 1 file changed, 8 insertions(+)

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:
 >