Merge pull request #25072 from techhat/spm

Add man page for spm, change pillar to .orig

doc/ref/cli/index.rst

@@ -296,3 +296,9 @@ salt-api
 .. toctree::
 
     salt-api
+
+spm
+===
+.. toctree::
+
+    spm

doc/ref/cli/spm.rst

@@ -0,0 +1,90 @@
+=======
+``spm``
+=======
+
+Salt Package Manager
+
+Synopsis
+========
+
+.. code-block:: bash
+
+    spm <command> [<argument>]
+
+Description
+===========
+
+spm is the frontend command for managing Salt packages. Packages normally only
+include formulas, meaning a group of SLS files that install into the
+``file_roots`` on the Salt Master, but Salt modules can also be installed.
+
+Options
+=======
+
+.. program:: spm
+
+.. option:: -y, --assume-yes
+
+    Assume ``yes`` instead of prompting the other whether or not to proceed
+    with a particular command. Default is False.
+
+.. option:: -f, --force
+
+    When presented with a course of action that spm would normally refuse to
+    perform, that action will be performed anyway. This is often destructive,
+    and should be used with caution.
+
+.. include:: _includes/logging-options.rst
+.. |logfile| replace:: /var/log/salt/spm
+.. |loglevel| replace:: ``warning``
+
+
+Commands
+========
+
+.. program:: spm
+
+.. option:: update_repo
+
+    Connect to remote repositories locally configured on the system and download
+    their metadata.
+
+.. option:: install
+
+    Install a package from a configured SPM repository. Requires a package name.
+
+.. option:: remove
+
+    Remove an installed package from the system. Requires a package name.
+
+.. option:: info
+
+    List information about an installed package. Requires a package name.
+
+.. option:: files
+
+    List files belonging to an installed package. Requires a package name.
+
+.. option:: local
+
+    Perform one of the above options (except for remove) on a package file,
+    instead of on a package in a repository, or an installed package. Requires
+    a valid path to a local file on the system.
+
+.. option:: build
+
+    Build a package from a directory containing a FORMULA file. Requires a valid
+    path to a local directory on the system.
+
+.. option:: create_repo
+
+    Scan a directory for valid SPM package files and build an SPM-METADATA file
+    in that directory which describes them.
+
+
+See also
+========
+
+:manpage:`salt(1)`
+:manpage:`salt-master(1)`
+:manpage:`salt-minion(1)`

doc/topics/spm/index.rst

@@ -165,9 +165,9 @@ warning.
 Pillars
 =======
 Formula packages include a pillar.example file. Rather than being placed in the
-formula directory, this file is renamed to ``<formula name>.sls`` and placed
-in the ``pillar_roots``, where it can be easily updated to meet the user's
-needs.
+formula directory, this file is renamed to ``<formula name>.sls.orig`` and
+placed in the ``pillar_roots``, where it can be easily updated to meet the
+user's needs.
 
 Loader Modules
 ==============

salt/client/spm.py

@@ -162,7 +162,7 @@ class SPMClient(object):
                 out_file = os.path.join(roots_path, new_name)
             elif member.name == '{0}/pillar.example'.format(name):
                 # Pillars are automatically put in the pillar_roots
-                new_name = '{0}.sls'.format(name)
+                new_name = '{0}.sls.orig'.format(name)
                 out_file = os.path.join(pillar_path, new_name)
             else:
                 out_file = os.path.join(roots_path, member.name)
@@ -215,7 +215,7 @@ class SPMClient(object):
                 member.name = member.name.replace('{0}/'.format(name), '')
             elif member.name == '{0}/pillar.example'.format(name):
                 # Pillars are automatically put in the pillar_roots
-                member.name = '{0}.sls'.format(name)
+                member.name = '{0}.sls.orig'.format(name)
                 out_path = pillar_path
             formula_tar.extract(member, out_path)
             conn.execute('INSERT INTO files VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)', (