.. highlight:: xml
.. index:: download

.. _download:

``download``
------------

This task downloads files from the device to the local file system.

The task downloads all files that matched the provided regexp pattern.  Unless the ``flatten`` attribute is set to ``true``, the task will recreate the remote directories containing the files locally. Empty directories will not be created.

Attributes/Options
^^^^^^^^^^^^^^^^^^

.. list-table ::
   :widths: 20 80 8
   :header-rows: 1

   * - Name
     - Description
     - Required  
   * - include
     - Regular expression pattern defining what files to download.

       The match is done against the entire path of a file, including the filesystem (e.g., ``local:/``). Note that the filesystem is separated by a single slash, i.e., the pattern ``local://.*xsd`` will not match anything.
     - Yes
   * - toDir
     - Local directory where to save the files. 
     - Yes
   * - flatten
     - If set to ``true``, download all files into ``toDir`` instead of creating the directory tree replicating remote directory structure. 

       Defaults to ``false``.
     - No
   * - matchRequired
     - If set to ``true``, fail if no files matched the ``include`` pattern. 

       Defaults to ``true``. 
     - No
   * - cleanToDir
     - If set to ``true``, remove all files and subdirectories in ``toDir`` prior to downloading the files.
       
       Defaults to ``false``.
     - No
   * - dryRun
     - If set to ``true``, print the files that will be downloaded without downloading anything.

       Defaults to ``false``.
     - No
     
Examples
^^^^^^^^

Download all "\*.xsd" files from "local:/":

.. code-block:: bat

   dpbuddy download -include "local:/.*xsd" -toDir download

.. code-block:: xml   

   <dp:download include="local:/.*xsd" toDir="download"/>
   
You can find more examples under ``samples`` in your distribution or `online <http://myarch.com/dpbuddy-examples-files/>`_.