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

<refentry id="flatpakrepo">

    <refentryinfo>
        <title>flatpakrepo</title>
        <productname>flatpak</productname>

        <authorgroup>
            <author>
                <contrib>Developer</contrib>
                <firstname>Alexander</firstname>
                <surname>Larsson</surname>
                <email>alexl@redhat.com</email>
            </author>
        </authorgroup>
    </refentryinfo>

    <refmeta>
        <refentrytitle>flatpakrepo</refentrytitle>
        <manvolnum>5</manvolnum>
    </refmeta>

    <refnamediv>
        <refname>flatpakrepo</refname>
        <refpurpose>Reference to a remote</refpurpose>
    </refnamediv>

    <refsect1>
        <title>Description</title>

        <para>
            Flatpak uses flatpakrepo files to share information about remotes.
            The <filename>flatpakrepo</filename> file contains enough information
            to add the remote. Use the <command>flatpak remote-add --from</command>
            command to do so.
        </para>

        <para>
            flatpakrepo files may also contain additional information that is useful
            when displaying a remote to the user, e.g. in an app store.
        </para>

        <para>
           The filename extension commonly used for flatpakrepo files is <filename>.flatpakrepo</filename>.
        </para>

        <para>
          flatpakrepo files can also be placed in
          <filename>/usr/share/flatpak/remotes.d/</filename> and
          <filename>/etc/flatpak/remotes.d/</filename>
          to statically preconfigure system-wide remotes. Such files must use the
          <filename>.flatpakrepo</filename> extension. If a file with the
          same name exists in both, the file under <filename>/etc</filename> will
          take precedence.
        </para>

    </refsect1>

    <refsect1>
        <title>File format</title>

        <para>
            The flatpakrepo file is using the same .ini file format that is used for
            systemd unit files or application .desktop files.
        </para>

        <refsect2>
            <title>[Flatpak Repo]</title>

            <para>
                All the information is contained in the [Flatpak Repo] group.
            </para>
            <para>
                The following keys can be present in this group:
            </para>
            <variablelist>
                <varlistentry>
                    <term><option>Version</option> (uint64)</term>
                    <listitem><para>The version of the file format, must be 1 if present.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>Url</option> (string)</term>
                    <listitem><para>The url for the remote. This key is mandatory.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>GPGKey</option> (string)</term>
                    <listitem><para>The base64-encoded gpg key for the remote.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>DefaultBranch</option> (string)</term>
                    <listitem><para>The default branch to use for this remote.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>Subset</option> (string)</term>
                    <listitem><para>Limit the remote to the named subset of refs.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>Title</option> (string)</term>
                    <listitem><para>The title of the remote. This should be a user-friendly name that can be displayed e.g. in an app store.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>Comment</option> (string)</term>
                    <listitem><para>A short summary of the remote, for display e.g. in an app store.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>Description</option> (string)</term>
                    <listitem><para>A longer description of the remote, for display e.g. in an app store.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>Icon</option> (string)</term>
                    <listitem><para>The url for an icon that can be used to represent the remote.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>Homepage</option> (string)</term>
                    <listitem><para>The url of a webpage describing the remote.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>Filter</option> (string)</term>
                    <listitem><para>The path of a local file to use to filter remote refs. See
                       <citerefentry><refentrytitle>flatpak-remote-add</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                       for details on the format of the file.
                    </para>
                    <para>
                      Note: This field is treated a bit special by flatpak remote-add. If you install a remote with --if-not-exists then
                      and the remote is already configured, then the filter field of the remote configuration will be update anyway.
                      And, if the filter field is *not* specified then any existing filters are cleared. The goal here is to allow
                      a pre-configured filtered remote to be replaced with the regular one if you add the normal upstream (unfiltered)
                      flatpakrepo file.
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>DeploySideloadCollectionID</option> (string)</term>
                    <listitem><para>
                        The collection ID of the remote, if it has one. This uniquely
                        identifies the collection of apps in the remote, to allow peer to peer
                        redistribution (see <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>).
                        It is recommended to use this key over DeployCollectionID or CollectionID because
                        only newer clients (Flatpak 1.12.8 or later) pay attention to it (and older clients don't handle
                        collection IDs properly).
                    </para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>DeployCollectionID</option> (string)</term>
                    <listitem><para>This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.</para></listitem>
                </varlistentry>
                <varlistentry>
                    <term><option>CollectionID</option> (string)</term>
                    <listitem><para>This is deprecated but still supported for backwards compatibility. Use DeploySideloadCollectionID instead.</para></listitem>
                </varlistentry>
            </variablelist>
        </refsect2>
    </refsect1>

    <refsect1>
        <title>Example</title>
<programlisting>
[Flatpak Repo]
Title=gedit
Url=http://sdk.gnome.org/repo-apps/
 
DeployCollectionID=org.gnome.Apps
</programlisting>
    </refsect1>

    <refsect1>
        <title>See also</title>

        <para>
            <citerefentry><refentrytitle>flatpak</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
            <citerefentry><refentrytitle>flatpak-remote-add</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
            <citerefentry><refentrytitle>flatpakref</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        </para>

    </refsect1>

</refentry>
