<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
Copyright 2014 Anne LoVerso <anne.loverso@students.olin.edu>

SPDX-License-Identifier: LGPL-2.0+

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.
-->

<refentry id="ostree">

    <refentryinfo>
        <title>ostree refs</title>
        <productname>OSTree</productname>

        <authorgroup>
            <author>
                <contrib>Developer</contrib>
                <firstname>Colin</firstname>
                <surname>Walters</surname>
                <email>walters@verbum.org</email>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>ostree refs</refentrytitle>
        <manvolnum>1</manvolnum>
    </refmeta>

    <refnamediv>
        <refname>ostree-refs</refname>
        <refpurpose>List refs</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
            <cmdsynopsis>
                <command>ostree refs</command> <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt">PREFIX</arg>
            </cmdsynopsis>
            <cmdsynopsis>
                <command>ostree refs</command> <arg choice="req">EXISTING</arg> <arg choice="req">--create=NEWREF</arg>
            </cmdsynopsis>
    </refsynopsisdiv>

<!-- Could this be more specific?  What defines a "ref"?  etc -->
    <refsect1>
        <title>Description</title>
        <para>
            Lists all refs available on the host.  If specified, PREFIX assigns the refspec prefix; default
            prefix is null, which lists all refs. This command can also be used to create or delete refs.
        </para>
    </refsect1>

    <refsect1>
        <title>Options</title>

        <variablelist>
            <varlistentry>
                <term><option>--list</option></term>

                <listitem><para> For historical reasons, <literal>refs</literal>
                without this option will strip the specified prefix
                from the output.  Normally, one wants to see the full
                ref, so providing this option ensures the refs are
                printed in full, rather than
                truncated. </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--create</option>=NEWREF</term>

                <listitem><para>
                    Create a ref pointing to the commit EXISTING. NEWREF must not already exist, and EXISTING
                    must be an existing commit. More than one ref can point to the same commit.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--delete</option></term>

                <listitem><para>
                  Delete refs which match PREFIX, rather than listing them.  If you are trying to reclaim space,
		  you will then need to <command>ostree prune</command> or <command>ostree admin cleanup</command>.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--alias</option>, <option>-A</option></term>

                <listitem><para>
                    If used with <option>--create</option>, create an alias. Otherwise just list aliases.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--collections</option>, <option>-c</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
                  PREFIX are deleted.
                </para></listitem>
            </varlistentry>

            <varlistentry>
                <term><option>--force</option></term>

                <listitem><para>
                  When creating <literal>NEWREF</literal> with
                  <option>--create</option>, allow an existing ref to be
                  updated instead of erroring.
                </para></listitem>
            </varlistentry>
        </variablelist>
    </refsect1>

    <refsect1>
        <title>Example</title>
        <para><command>$ ostree refs</command></para>
<programlisting>
        my-branch
        gnome-ostree/buildmaster/x86_64-runtime
</programlisting>
    </refsect1>
</refentry>