refs: Add a --collections argument to the built-in refs command

Rather than change the output format used by the existing refs command
to output collection IDs in addition to ref names, this functionality has
been hidden behind an --collections argument. If it’s not specified `ostree
refs` will output the same content as before for a given repository. If
it is specified, the collection ID for each ref will be included in the
output as (collection ID, ref name).

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Closes: #924
Approved by: cgwalters

man/ostree-refs.xml

@@ -83,6 +83,26 @@ Boston, MA 02111-1307, USA.
 		  you will then need to <command>ostree prune</command> or <command>ostree admin cleanup</command>.
                 </para></listitem>
             </varlistentry>
+
+            <varlistentry>
+                <term><option>--collections</option></term>
+
+                <listitem><para>
+                  Enable interactions with refs using the combination of their
+                  collection IDs and ref names. When listing refs, this changes
+                  the output format to include collection IDs, and enables
+                  listing remote mirrored refs.</para>
+
+                  <para>When creating refs, the refspec value passed to the
+                  <option>--create</option> option is treated as
+                  <literal>COLLECTION-ID:REF-NAME</literal> and a mirrored ref
+                  is created. (This is an abuse of the refspec syntax.)</para>
+
+                  <para>When deleting refs, all refs whose collection ID equals
+                  the value of the <option>--delete</option> argument are
+                  deleted.
+                </para></listitem>
+            </varlistentry>
         </variablelist>
     </refsect1>