NAME

       datalad save - save the current state of a dataset

SYNOPSIS

       datalad   save   [-h]   [-m   MESSAGE]   [-d  DATASET]  [-t  ID]  [-r]  [-R  LEVELS]  [-u]
              [-F MESSAGE_FILE] [--to-git] [PATH [PATH ...]]

DESCRIPTION

       Saving the state of a dataset records changes that have been  made  to  it.   This  change
       record is annotated with a user-provided description.  Optionally, an additional tag, such
       as a version, can be assigned  to  the  saved  state.  Such  tag  enables  straightforward
       retrieval of past versions at a later point in time.

       NOTE   Before  Git  v2.22,  any  Git repository without an initial commit located inside a
              Dataset is ignored, and content underneath it  will  be  saved  to  the  respective
              superdataset.  DataLad  datasets  always  have  an  initial  commit,  hence are not
              affected by this behavior.

   Examples
       Save any  content  underneath  the  current  directory,  without  altering  any  potential
       subdataset::

        % datalad save .

       Save specific content in the dataset::

        % datalad save myfile.txt

       Attach a commit message to save::

        % datalad save -m 'add file' myfile.txt

       Save  any  content  underneath  the  current  directory,  and  recurse  into any potential
       subdatasets::

        % datalad save . --recursive

       Save any modification of known  dataset  content  in  the  current  directory,  but  leave
       untracked files (e.g. temporary files) untouched::

        % datalad save -u -d .

       Tag the most recent saved state of a dataset::

        % datalad save -d . --version-tag 'bestyet'

OPTIONS

       PATH   path/name  of  the  dataset component to save. If given, only changes made to those
              components are recorded in the new state. Constraints: value must be a string

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

       -m MESSAGE, -\-message MESSAGE
              a  description  of  the  state or the changes made to a dataset. Constraints: value
              must be a string

       -d DATASET, -\-dataset DATASET
              "specify the dataset to save. Constraints: Value must  be  a  Dataset  or  a  valid
              identifier of a Dataset (e.g. a path)

       -t ID, -\-version-tag ID
              an additional marker for that state. Every dataset that is touched will receive the
              tag. 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 convertible to type 'int'

       -u, -\-updated
              if given, only saves previously tracked paths.

       -F MESSAGE_FILE, -\-message-file MESSAGE_FILE
              take  the  commit  message from this file. This flag is mutually exclusive with -m.
              Constraints: value must be a string

       -\-to-git
              flag whether to add data directly to Git, instead of tracking data  identity  only.
              Usually  this  is not desired, as it inflates dataset sizes and impacts flexibility
              of data transport. If not specified -  it  will  be  up  to  git-annex  to  decide,
              possibly  on .gitattributes options. Use this flag with a simultaneous selection of
              paths to save. In general, it  is  better  to  pre-configure  a  dataset  to  track
              particular  paths,  file  types,  or  file  sizes with either Git or git-annex. See
              https://git-annex.branchable.com/tips/largefiles/.

AUTHORS

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