<?xml version="1.0" encoding="iso-8859-1"?>

<!DOCTYPE refentry PUBLIC "-//Sun Microsystems//DTD SolBook-XML 3.7//EN" "xsolbook.dtd" [

<!ENTITY % ent SYSTEM "entities.ent">

%ent;

]>

<refentry id="pkgsurf-1">

<refmeta><refentrytitle>pkgsurf</refentrytitle><manvolnum>1</manvolnum>

<refmiscinfo class="date">09 Aug 2013</refmiscinfo>

<refmiscinfo class="sectdesc">&man1;</refmiscinfo>

<refmiscinfo class="software">&release;</refmiscinfo>

<refmiscinfo class="arch">generic</refmiscinfo>

<refmiscinfo class="copyright">Copyright (c) 2013, 2016, Oracle and/or its affiliates. All rights reserved.</refmiscinfo>

</refmeta>

<refnamediv>

<refname>pkgsurf</refname><refpurpose>Image Packaging System repository resurfacing utility</refpurpose>

</refnamediv>

<refsynopsisdiv><title></title>

<synopsis>/usr/bin/pkgsurf -s <replaceable>target_repo</replaceable> -r <replaceable>reference_repo</replaceable> [-n]

[-p <replaceable>publisher_prefix</replaceable>]... [-i <replaceable>name</replaceable>]... [-c <replaceable>pattern</replaceable>]...</synopsis>

</refsynopsisdiv>

<refsect1 id="pkgsurf-1-desc" role="description"><title></title>

<para><command>pkgsurf</command> is a package publication tool for replacing packages in a target repository that have not changed since the latest published version in the reference repository. The result is a new version surface of all packages in the target repository.</para>

<para><command>pkgsurf</command> operations are not reversible. In case the <command>pkgsurf</command> operation must be reverted, you should store the target repository in its own ZFS dataset and take a snapshot of the dataset before you run <command>pkgsurf</command>.</para>

<para>Packages in the target repository are compared to packages in the reference repository and analyzed for content changes. For each package, if no content change is found, the package manifest is removed from the target repository and replaced with the manifest of the same package from the reference repository.</para>

<para>The target repository must be a file system based repository. For optimal performance, the reference repository should also be a file system based repository.</para>

<para>The target repository should contain only one version of each package. If the target repository contains a package that is both newer than the latest version in the reference repository and older than the latest version in the target repository, no package manifest replacement is done for that package.

</para>

<para>The reference repository can contain one or more versions of each package. However, only the latest version will be used for comparison.</para>

</refsect1>

<refsect1 role="options"><title></title>

<para>The following options are supported:</para>

<variablelist termlength="wholeline">

<varlistentry><term><option>?</option></term><term><option>-help</option></term><listitem><para>Display a usage message.</para>

</listitem>

</varlistentry>

<varlistentry><term><option>c</option> <replaceable>pattern</replaceable></term>

<listitem><para>Treat every package whose FMRI matches <replaceable>pattern</replaceable> as changed and do not reversion it, even if there is no content change. This option can be specified multiple times.</para></listitem>

</varlistentry>

<varlistentry><term><option>i</option> <replaceable>name</replaceable></term>

<listitem><para>Ignore <literal>set</literal> actions with the <literal>name</literal> field set to <replaceable>name</replaceable> for determination of content change. The package will be reversioned even if this action differs between target and reference versions. This option can be specified multiple times.</para></listitem>

</varlistentry>

<varlistentry><term><option>n</option></term>

<listitem><para>Perform a trial run of the operation with no changes made to the target repository.</para></listitem>

</varlistentry>

<varlistentry><term><option>p</option> <replaceable>publisher_prefix</replaceable></term>

<listitem><para>Specify the name of the publisher to be resurfaced. This option can be specified multiple times.</para>

<para>By default, packages from all publishers found in target and reference repositories are resurfaced.</para></listitem>

</varlistentry>

<varlistentry><term><option>r</option> <replaceable>reference_repo</replaceable></term>

<listitem><para>Specify the URI of the reference repository to be used for manifest comparison. Only the latest version of each package is considered.</para></listitem>

</varlistentry>

<varlistentry><term><option>s</option> <replaceable>target_repo</replaceable></term>

<listitem><para>Specify the path to the target repository. Packages in this repository are reversioned to the versions present in the reference repository according to the comparison results. The target repository should contain only one version of each package. The target repository must be a file system based repository.</para></listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="environment-variables"><title></title>

<para>The following environment variable is supported:</para>

<variablelist>

<varlistentry><term><envar>PKG_REPO</envar></term>

<listitem><para>The absolute path of the target repository.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="examples"><title></title>

<example><title>Resurface a Repository</title>

<para>Reversion each package in the target repository that did not have any content change from the same package in the reference repository.</para>

<screen>$ <userinput>pkgsurf -s /path/to/target -r http://reference.example.com</userinput></screen>

<para>Sample package in the target repository:</para>

<programlisting>set name=pkg.fmri value=pkg://example.com/foo@2.0:20381001T163427Z

dir group=sys mode=0755 owner=root path=usr</programlisting>

<para>Sample package in the reference repository:</para>

<programlisting>set name=pkg.fmri value=pkg://example.com/foo@1.0:20381001T163427Z

dir group=sys mode=0755 owner=root path=usr</programlisting>

<para>Sample package in the target repository after the <command>pkgsurf</command> operation:</para>

<programlisting>set name=pkg.fmri value=pkg://example.com/foo@1.0:20381001T163427Z

dir group=sys mode=0755 owner=root path=usr</programlisting>

</example>

</refsect1>

<refsect1 role="exit-status"><title></title>

<para>The following exit values are returned:</para>

<variablelist>

<varlistentry><term><returnvalue>0</returnvalue></term>

<listitem><para>Command succeeded.</para>

</listitem>

</varlistentry>

<varlistentry><term><returnvalue>1</returnvalue></term>

<listitem><para>An error occurred.</para>

</listitem>

</varlistentry>

<varlistentry><term><returnvalue>2</returnvalue></term>

<listitem><para>Invalid command line options were specified.</para>

</listitem>

</varlistentry>

<varlistentry><term><returnvalue>99</returnvalue></term>

<listitem><para>An unanticipated exception occurred.</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1 role="attributes"><title></title>

<para>See <literal>attributes</literal>(7) for descriptions of the following

attributes:</para>

<informaltable frame="all" orient="port">

<tgroup cols="2" colsep="1" rowsep="1"><colspec colname="col1" colwidth="198*"

align="left"/><colspec colname="col2" colwidth="198*" align="left"/><thead>

<row>

<entry align="center">

<para>ATTRIBUTE TYPE</para>

</entry>

<entry align="center">

<para>ATTRIBUTE VALUE</para>

</entry>

</row>

</thead>

<tbody>

<row>

<entry align="left">

<para>Availability</para>

</entry>

<entry align="left">

<para><literal>package/pkg</literal></para>

</entry>

</row>

<row>

<entry align="left">

<para>Interface Stability</para>

</entry>

<entry align="left">

<para>Uncommitted</para>

</entry>

</row>

</tbody>

</tgroup>

</informaltable></refsect1>

<refsect1 role="see-also"><title></title>

<para><olink targetdoc="refman" targetptr="pkgrepo-1"><citerefentry><refentrytitle>pkgrepo</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>, <olink targetdoc="refman" targetptr="pkg-7"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>7</manvolnum></citerefentry></olink></para>

<para><olink targetdoc="CCOSP"><citetitle remap="book">Copying and Creating Package Repositories in Oracle Solaris 11.2</citetitle></olink></para>

<para><literal>https://java.net/projects/ips/pages/Home</literal></para>

</refsect1>

</refentry>