.. _distgit_directive:


distgit_directive - download files from distgit
+++++++++++++++++++++++++++++++++++++++++++++++

.. versionadded:: 0.3.16

Download files from Fedora package repository (usually called 'distgit') hosted at
http://pkgs.fedoraproject.org/. Any files hosted at that repository can be downloaded for a
chosen package.


Parameters
----------

.. raw:: html

    <table class="rawhtml" border=1 cellpadding=4>
    <tr>
    <th class="head">parameter</th>
    <th class="head">required</th>
    <th class="head">description</th>
    <th class="head">type</th>
    <th class="head">default</th>
    <th class="head">choices</th>
    </tr>
            <tr>
    <td class="bold"><p>localpath</p></td>
    <td>no</td>
    <td><p>a local path of downloaded file. If not provided, path from distgit will be used.
    Example: <tt class="docutils literal">[specs/xchat.spec]</tt></p></td>
    <td><p>list of str</p></td>
    <td></td>
    <td><ul></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>package</p></td>
    <td>yes</td>
    <td><p>N(E)VR of a package. Package dist tag determines the git branch used for file download.
    Example: <tt class="docutils literal"><span class="pre">xchat-2.8.8-21.fc20</span></tt></p></td>
    <td><p>str</p></td>
    <td></td>
    <td><ul></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>path</p></td>
    <td>yes</td>
    <td><p>files (directories not supported at the moment) to be downloaded from distgit.
    Example: <tt class="docutils literal">[xchat.spec]</tt></p></td>
    <td><p>list of str</p></td>
    <td></td>
    <td><ul></ul></td>
    </tr>
            <tr>
    <td class="bold"><p>target_dir</p></td>
    <td>no</td>
    <td><p>directory into which to download files</p></td>
    <td><p>str</p></td>
    <td><p>${workdir}</p></td>
    <td><ul></ul></td>
    </tr>
        </table>

Return Values
-------------

A dictionary containing following items:

* `downloaded_files`: (list of str) a list of local filenames of the downloaded
  files


Exceptions
----------

* :class:`.TaskotronRemoteError`: if downloading failed
* :class:`.TaskotronValueError`: if path and localpath are not lists or are not of the same
  length
* :class:`.TaskotronDirectiveError`: if package or path is missing



Examples
--------


A task needs to download a spec file and httpd configuration check to run a check
on those files::

  - name: download spec file and httpd conf
    distgit:
      package: yourls-1.7-3.20150410gitabc7d6c.fc22
      path:
          - yourls.spec
          - yourls-httpd.conf
      localpath:
          - download/yourls_downloaded.spec
          - download/yourls-httpd_downloaded.conf