# Copyright (C) 2015 Codethink Limited
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 2 of the License.
#
# This program 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 General Public License for more details.
#
# You should have received a copy of the GNU General Public License along
# with this program; if not, see <http://www.gnu.org/licenses/>.

help: |

    Deploy a Baserock system to an existing OSTree repository.

    Parameters:

    * location: the path to the OSTree repo.

    * OSTREE_BRANCH=branchname: the branch to commit to

    * OSTREE_COMMIT_SUBJECT=subject: one-line commit title

    * OSTREE_COMMIT_BODY=text: full commit message (optional)

    See `morph help deploy` for details of how to pass parameters to write
    extensions.

    This extension requires a local OSTree repository to deploy to, which must
    already exist. You can create a new repository using the `ostree init`
    command.

    If you want to deploy straight to the local machine, you should use a
    'bare' mode repository, which allows the resulting system to be quickly
    checked out.

    If you want to serve the results of a deployment from an OSTree server,
    you need to use a local 'archive-z2' mode repository. You can then use
    `ostree pull` on the server to pull the results of the deployment from the
    build machine. Note that 'push' style transfers are not currently supported
    by OSTree.

    For full OSTree documentation, see <https://wiki.gnome.org/Projects/OSTree>.

    IMPORTANT NOTE: OSTree can only store regular files. It cannot store device
    nodes. If your system contains static device nodes (which all of the
    Baserock reference systems do, at time of writing) you can use the
    strip-device-nodes.configure extension to remove them, and leave devtmpfs
    to create the device nodes.

    If you seen an error like "Not a regular file or symlink: null.", you have
    hit this problem.

    ANOTHER IMPORTANT NOTE: OSTree uses hardlinks to checkout files quickly.
    This has an important consequence: any files checked out from OSTree MUST
    not be overwritten at runtime, or you *will* cause corruption in the
    repository and/or your checked-out system. In general, if you want to
    use OSTree for container systems or chroots, it is enough to create a
    read-only bindmount:

        mount --bind ./ostree-checkout-dir ./sysroot-dir
        mount -o bind,remount,ro ./sysroot-dir

    If you want to run a system using OSTree as the real OS of a system, you
    are best off following this guide:

        https://developer.gnome.org/ostree/stable/adapting-existing.html

    This extension requires that the libostree-1 library and the Python
    GObject-introspection bindings are available.