NAME

       datalad install - install a dataset from a (remote) source.

SYNOPSIS

       datalad  install  [-h]  [-s  SOURCE]  [-d  DATASET]  [-g]  [-D  DESCRIPTION] [-r] [-R LEVELS] [--reckless
              [auto|ephemeral|shared-...]] [-J NJOBS] [--version] [PATH ...]

DESCRIPTION

       This command creates a local sibling of an existing dataset from a (remote) location identified via a URL
       or path. Optional recursion into potential subdatasets, and download of all referenced data is supported.
       The new dataset can be optionally registered in an  existing  superdataset  by  identifying  it  via  the
       DATASET argument (the new dataset's path needs to be located within the superdataset for that).

       It  is  recommended  to  provide  a  brief description to label the dataset's nature *and* location, e.g.
       "Michael's music on black laptop". This helps humans to identify data locations in distributed scenarios.
       By default an identifier comprised of user and machine name, plus path will be generated.

       When only partial dataset content shall be obtained, it is recommended to use this  command  without  the
       GET-DATA flag, followed by a `get` operation to obtain the desired data.

       NOTE   Power-user info: This command uses git clone, and git annex init to prepare the dataset. Register‐
              ing  to  a  superdataset  is  performed via a git submodule add operation in the discovered super‐
              dataset.

   Examples
       Install a dataset from Github into the current directory::

        % datalad install https://github.com/datalad-datasets/longnow-podcasts.git

       Install a dataset as a subdataset into the current dataset::

        % datalad install -d .    --source='https://github.com/datalad-datasets/longnow-podcasts.git'

       Install a dataset, and get all content right away::

        % datalad install --get-data    -s https://github.com/datalad-datasets/longnow-podcasts.git

       Install a dataset with all its subdatasets::

        % datalad install -r    https://github.com/datalad-datasets/longnow-podcasts.git

OPTIONS

       PATH   path/name of the installation target. If no PATH is provided a destination path  will  be  derived
              from a source URL similar to git clone.

       -h, --help, --help-np
              show  this  help message. --help-np forcefully disables the use of a pager for displaying the help
              message

       -s SOURCE, --source SOURCE
              URL or local path of the installation source. Constraints: value must be a string

       -d DATASET, --dataset DATASET
              specify the dataset to perform the install operation on. If no dataset is  given,  an  attempt  is
              made  to  identify  the  dataset in a parent directory of the current working directory and/or the
              PATH given. Constraints: Value must be a Dataset or a valid identifier of a Dataset (e.g. a path)

       -g, --get-data
              if given, obtain all data content too.

       -D DESCRIPTION, --description DESCRIPTION
              short description to use for a dataset location. Its primary purpose is to help humans to identify
              a dataset copy (e.g., "mike's dataset on lab server"). Note that when a dataset is published, this
              information becomes available on the remote side. Constraints: value must be a string

       -r, --recursive
              if set, recurse into potential subdataset.

       -R LEVELS, --recursion-limit LEVELS
              limit recursion into subdataset to the given number of levels. Constraints: value must be convert‐
              ible to type 'int'

       --reckless [auto|ephemeral|shared-...]
              Obtain a dataset or subdatset and set it up in a potentially unsafe way for performance, or access
              reasons. Use with care, any dataset is marked as 'untrusted'. The reckless mode  is  stored  in  a
              dataset's  local configuration under 'datalad.clone.reckless', and will be inherited to any of its
              subdatasets. Supported modes are: ['auto']: hard-link files between local clones. In-place modifi‐
              cation in any clone will alter original annex content. ['ephemeral']: symlink  annex  to  origin's
              annex  and discard local availability info via git-annex-dead 'here'. Shares an annex between ori‐
              gin and clone w/o git-annex being aware of it. In case of a change in origin you  need  to  update
              the clone before you're able to save new content on your end. Alternative to 'auto' when hardlinks
              are not an option, or number of consumed inodes needs to be minimized. Note that this mode can on‐
              ly  be  used  with clones from non-bare repositories or a RIA store! Otherwise two different annex
              object tree structures (dirhashmixed vs dirhashlower) will be used simultaneously, and annex  keys
              using  the  respective  other structure will be inaccessible. ['shared-<mode>']: set up repository
              and annex permission to enable multi-user access. This disables the standard write  protection  of
              annex'ed  files.  <mode>  can  be  any  value support by 'git init --shared=', such as 'group', or
              'all'. Constraints: value must be one of (True, False, 'auto', 'ephemeral'), or value  must  start
              with 'shared-'

       -J NJOBS, --jobs NJOBS
              how many parallel jobs (where possible) to use. "auto" corresponds to the number defined by 'data‐
              lad.runtime.max-annex-jobs'  configuration  item.  Constraints:  value must be convertible to type
              'int', or value must be one of ('auto',) [Default: 'auto']

       --version
              show the module and its version which provides the command

AUTHORS

        datalad is developed by The DataLad Team and Contributors <team@datalad.org>.

datalad install 0.15.5                             2022-02-10                                 datalad install(1)