Access Control Documentation: Explain special and magic refs

Gerrit makes use of several special and magic references outside of
the refs/heads and refs/tags namespaces. This is now explained in
detail.

Change-Id: I22c47f2336d16fe23bea46035583a9a1e38eb2d4
Signed-off-by: Fredrik Luthander <fredrik.luthander@sonymobile.com>

1 files changed, 102 insertions, 0 deletions

diff --git a/Documentation/access-control.txt b/Documentation/access-control.txt
index b7f69f36da..398a9aeceb 100644
--- a/Documentation/access-control.txt
+++ b/Documentation/access-control.txt
@@ -292,6 +292,108 @@ behavior is generally only useful on the `Read` category when
 granting 'DENY' within a specific project to deny a group access.
 
 
+[[references]]
+Special and magic references
+----------------------------
+
+The reference namespaces used in git are generally two, one for branches and
+one for tags:
+
+* +refs/heads/*+
+* +refs/tags/*+
+
+However, every reference under +refs/*+ is really available, and in Gerrit this
+opportunity for giving other refs a special meaning is used.  In Gerrit they
+are sometimes used as magic/virtual references that give the push to Gerrit a
+special meaning.
+
+
+[[references_special]]
+Special references
+~~~~~~~~~~~~~~~~~~
+
+The special references have content that's either generated by Gerrit or
+contains important project configuration that Gerrit needs. When making
+changes to these references, Gerrit will take extra precautions to verify the
+contents compatibility at upload time.
+
+
+refs/changes/*
+^^^^^^^^^^^^^^
+
+Under this namespace each uploaded patch set for every change gets a static
+reference in their git.  The format is convenient but still intended to scale to
+hundreds of thousands of patch sets.  To access a given patch set you will
+need the change number and patch set number.
+
+[verse]
+'refs/changes/'<last two digits of change number>/
+  <change number>/
+  <patch set number>
+
+You can also find these static references linked on the page of each change.
+
+
+refs/meta/config
+^^^^^^^^^^^^^^^^
+
+This is where the Gerrit configuration of each project is residing.  This
+branch contains several files of importance: +project.config+, +groups+ and
++rules.pl+.  Torgether they control access and behaviour during the change
+review process.
+
+
+refs/meta/dashboards/*
+^^^^^^^^^^^^^^^^^^^^^^
+
+There's a dedicated page where you can read more about
+link:user-dashboards.html[User Dashboards].
+
+
+refs/notes/review
+^^^^^^^^^^^^^^^^^
+
+Autogenerated copy of review notes for all changes in the git.  Each log entry
+on the refs/notes/review branch also references the patch set on which the
+review is made.  This functionality is provided by the review-notes plugin.
+
+
+[[references_magic]]
+Magic references
+~~~~~~~~~~~~~~~~
+
+These are references with added functionality to them compared to a regular
+git push operation.
+
+
+refs/for/<branch ref>
+^^^^^^^^^^^^^^^^^^^^^
+
+Most prominent is the `refs/for/<branch ref>` reference which is the reference
+upon which we build the code review intercept before submitting a commit to
+the branch it's uploaded to.
+
+Further documentation on how to push can be found on the
+link:user-upload.html#push_create[Upload changes] page.
+
+
+refs/publish/*
+^^^^^^^^^^^^^^
+
+`refs/publish/*` is an alternative name to `refs/for/*` when pushing new changes
+and patch sets.
+
+
+refs/drafts/*
+^^^^^^^^^^^^^
+
+Push to `refs/drafts/*` creates a change like push to `refs/for/*`, except the
+resulting change remains hidden from public review.  You then have the option
+of adding individual reviewers before making the change public to all.  The
+change page will have a 'Publish' button which allows you to convert individual
+draft patch sets of a change into public patch sets for review.
+
+
 [[access_labels]]
 Review Labels
 -------------