"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

Copyright 2014 Colin Walters <walters@verbum.org>

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 summary</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 summary</refentrytitle>

        <manvolnum>1</manvolnum>

    </refmeta>

    <refnamediv>

        <refname>ostree-summary</refname>

        <refpurpose>Regenerate or view the summary metadata file</refpurpose>

    </refnamediv>

    <refsynopsisdiv>

            <cmdsynopsis>

                <command>ostree summary</command> <arg choice="opt">--gpg-sign=KEYID</arg> <arg choice="opt">--gpg-homedir=HOMEDIR</arg> <arg choice="opt">--sign=KEYID</arg> <arg choice="opt">--sign-type=ENGINE</arg> <arg choice="req">--update</arg> <arg choice="opt" rep="repeat">--add-metadata=<replaceable>KEY</replaceable>=<replaceable>VALUE</replaceable></arg>

            </cmdsynopsis>

            <cmdsynopsis>

                <command>ostree summary</command> <group choice="req"><arg choice="plain">--view</arg><arg choice="plain">--raw</arg></group>

            </cmdsynopsis>

    </refsynopsisdiv>

    <refsect1>

        <title>Description</title>

        <para>

	  The <filename>summary</filename> file is an optional higher

	  level form of repository metadata that describes the

	  available branches.  It needs to be manually regenerated after

	  a series of commits.  Among other things, this allows atomically

	  updating multiple commits.

        </para>

    </refsect1>

    <refsect1>

        <title>Options</title>

        <variablelist>

            <varlistentry>

                <term><option>--update</option>,<option>-u</option></term>

                <listitem><para>

                        Update the summary file. This option can be combined

                        with <option>--add-metadata</option> to add metadata

                        fields to the summary.

                    </para>

                <para>If the repository has a collection ID configured, the

                  <filename>ostree-metadata</filename> branch for that collection ID

                  will also be updated with a new commit containing the given metadata,

                  which will be signed if the summary file is signed.</para>

                </listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--add-metadata</option>,<option>-m</option>=KEY=VALUE</term>

                <listitem><para>

                    Specify an additional metadata field to add to the summary.

                    It must be in the format

                    <command><replaceable>KEY</replaceable>=<replaceable>VALUE</replaceable></command>

                    or as two separate arguments. The keys must be namespaced

                    for your organisation or repository using a dot prefix. The

                    values must be in GVariant text format. For example,

                    <command>exampleos.end-of-life "@t 1445385600"</command>.

                    This option can be used multiple times.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--view</option>,<option>-v</option></term>

                <listitem><para>

                    View the contents of the summary file in a human readable format.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--raw</option></term>

                <listitem><para>

                    View the raw bytes of the summary file.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--gpg-sign</option>=KEYID</term>

                <listitem><para>

                    GPG Key ID to sign the summary with.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--gpg-homedir</option>=HOMEDIR</term>

                <listitem><para>

                    GPG Homedir to use when looking for keyrings.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--sign-type</option>=ENGINE</term>

                <listitem><para>

                    Use particular signature engine. Currently

                    available <arg choice="plain">ed25519</arg> and <arg choice="plain">dummy</arg>

                    signature types.

                    The default is <arg choice="plain">ed25519</arg>.

                </para></listitem>

            </varlistentry>

            <varlistentry>

                <term><option>--sign</option>="KEY-ID"</term>

                <listitem><para>

                        There <literal>KEY-ID</literal> is:

                        <variablelist>

                            <varlistentry>

                                <term><option>for ed25519:</option></term>

                                <listitem><para>

                                        <literal>base64</literal>-encoded secret key for commit signing.

                                </para></listitem>

                            </varlistentry>

                            <varlistentry>

                                <term><option>for dummy:</option></term>

                                <listitem><para>

                                            ASCII-string used as secret key.

                                </para></listitem>

                            </varlistentry>

                        </variablelist>

                </para></listitem>

            </varlistentry>

        </variablelist>

    </refsect1>

    <refsect1>

        <title>Examples</title>

        <para><command>$ ostree summary -u</command></para>

        <para><command>$ ostree summary -u -m key="'value'"</command></para>

        <para><command>$ ostree summary -v</command></para>

<programlisting>

* ostree/1/1/0

    Latest Commit (4.2 MB):

      9828ab80f357459b4ab50f0629beab2ae3b67318fc3d161d10a89fae353afa90

    Timestamp (ostree.commit.timestamp): 2017-11-21T01:41:10-08

Last-Modified (ostree.summary.last-modified): 2018-01-12T22:06:38-08

</programlisting>

    </refsect1>

</refentry>