datalad-save(1)

1datalad save(1)             General Commands Manual            datalad save(1)
2
3
4

NAME

6       datalad save - save the current state of a dataset
7

SYNOPSIS

9       datalad  save  [-h]  [-m MESSAGE] [-d DATASET] [-t ID] [-r] [-R LEVELS]
10              [-u]  [-F  MESSAGE_FILE]   [--to-git]   [-J   NJOBS]   [--amend]
11              [--version] [PATH ...]
12
13
14

DESCRIPTION

16       Saving  the  state  of a dataset records changes that have been made to
17       it.  This change record is annotated with a user-provided  description.
18       Optionally,  an  additional  tag, such as a version, can be assigned to
19       the saved state. Such tag enables  straightforward  retrieval  of  past
20       versions at a later point in time.
21
22       NOTE   Before  Git  v2.22, any Git repository without an initial commit
23              located inside a Dataset is ignored, and content  underneath  it
24              will  be  saved to the respective superdataset. DataLad datasets
25              always have an initial commit, hence are not  affected  by  this
26              behavior.
27
28   Examples
29       Save any content underneath the current directory, without altering any
30       potential subdataset::
31
32        % datalad save .
33
34       Save specific content in the dataset::
35
36        % datalad save myfile.txt
37
38       Attach a commit message to save::
39
40        % datalad save -m 'add file' myfile.txt
41
42       Save any content underneath the current directory, and recurse into any
43       potential subdatasets::
44
45        % datalad save . -r
46
47       Save  any modification of known dataset content in the current directo‐
48       ry, but leave untracked files (e.g. temporary files) untouched::
49
50        % datalad save -u .
51
52       Tag the most recent saved state of a dataset::
53
54        % datalad save --version-tag 'bestyet'
55
56       Save a specific change but integrate into last commit keeping  the  al‐
57       ready recorded commit message::
58
59        % datalad save myfile.txt --amend
60
61

OPTIONS

63       PATH   path/name  of  the  dataset  component  to  save. If given, only
64              changes made to those components are recorded in the new  state.
65              Constraints: value must be a string or value must be NONE
66
67
68       -h, --help, --help-np
69              show this help message. --help-np forcefully disables the use of
70              a pager for displaying the help message
71
72       -m MESSAGE, --message MESSAGE
73              a description of the state or the changes  made  to  a  dataset.
74              Constraints: value must be a string or value must be NONE
75
76       -d DATASET, --dataset DATASET
77              "specify  the  dataset  to  save.  Constraints:  Value must be a
78              Dataset or a valid identifier of a Dataset (e.g. a path) or val‐
79              ue must be NONE
80
81       -t ID, --version-tag ID
82              an  additional  marker  for  that  state.  Every dataset that is
83              touched will receive the  tag.  Constraints:  value  must  be  a
84              string or value must be NONE
85
86       -r, --recursive
87              if set, recurse into potential subdatasets.
88
89       -R LEVELS, --recursion-limit LEVELS
90              limit  recursion into subdatasets to the given number of levels.
91              Constraints: value must be convertible to type  'int'  or  value
92              must be NONE
93
94       -u, --updated
95              if given, only saves previously tracked paths.
96
97       -F MESSAGE_FILE, --message-file MESSAGE_FILE
98              take  the  commit  message from this file. This flag is mutually
99              exclusive with -m. Constraints: value must be a string or  value
100              must be NONE
101
102       --to-git
103              flag  whether  to  add data directly to Git, instead of tracking
104              data identity only. Use with caution, there is no guarantee that
105              a  file put directly into Git like this will not be annexed in a
106              subsequent save operation. If not specified, it will  be  up  to
107              git-annex  to decide how a file is tracked, based on a dataset's
108              configuration to track particular paths,  file  types,  or  file
109              sizes   with  either  Git  or  git-annex.  (see  https://git-an‐
110              nex.branchable.com/tips/largefiles).
111
112       -J NJOBS, --jobs NJOBS
113              how many parallel jobs (where possible) to  use.  "auto"  corre‐
114              sponds to the number defined by 'datalad.runtime.max-annex-jobs'
115              configuration item NOTE: This option can only parallelize  input
116              retrieval  (get)  and  output recording (save). DataLad does NOT
117              parallelize your scripts for you.  Constraints:  value  must  be
118              convertible to type 'int' or value must be NONE or value must be
119              one of ('auto',)
120
121       --amend
122              if set, changes are not recorded in a new, separate commit,  but
123              are  integrated  with  the changeset of the previous commit, and
124              both together are recorded by replacing  that  previous  commit.
125              This is mutually exclusive with recursive operation.
126
127       --version
128              show the module and its version which provides the command
129

AUTHORS

131        datalad is developed by The DataLad Team and Contributors <team@datal‐
132       ad.org>.
133
134
135
136datalad save 0.19.3               2023-08-11                   datalad save(1)