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

NAME

6       datalad  configuration  -  get and set dataset, dataset-clone-local, or
7       global configuration
8

SYNOPSIS

10       datalad configuration [-h] [--scope {global|local|branch}] [-d DATASET]
11              [-r]     [-R    LEVELS]    [--version]    [{dump|get|set|unset}]
12              [name[=value] ...]
13
14
15

DESCRIPTION

17       This command works similar to git-config, but  some  features  are  not
18       supported  (e.g., modifying system configuration), while other features
19       are not available in git-config (e.g., multi-configuration queries).
20
21       Query and modification of three distinct configuration scopes  is  sup‐
22       ported:
23
24       -  'branch':  the  persistent  configuration  in  .datalad/config  of a
25       dataset
26
27       branch - 'local': a dataset clone's  Git  repository  configuration  in
28              .git/config - 'global': non-dataset-specific configuration (usu‐
29              ally in $USER/.gitconfig)
30
31       Modifications of the persistent  'branch'  configuration  will  not  be
32       saved  by this command, but have to be committed with a subsequent SAVE
33       call.
34
35       Rules of precedence regarding different configuration  scopes  are  the
36       same  as  in  Git, with two exceptions: 1) environment variables can be
37       used to override any datalad configuration, and  have  precedence  over
38       any  other  configuration  scope  (see below). 2) the 'branch' scope is
39       considered in addition to the standard git  configuration  scopes.  Its
40       content  has  lower precedence than Git configuration scopes, but it is
41       committed to  a  branch,  hence  can  be  used  to  ship  (default  and
42       branch-specific) configuration with a dataset.
43
44       Besides  storing  configuration settings statically via this command or
45       ``git config``, DataLad also reads any DATALAD_* environment on process
46       startup  or  import, and maps it to a configuration item.  Their values
47       take precedence over any other specification. In variable  names  ``_``
48       encodes  a ``.`` in the configuration name, and ``__`` encodes a ``-``,
49       such that ``DATALAD_SOME__VAR`` is mapped to ``datalad.some-var``.  Ad‐
50       ditionally,  a  DATALAD_CONFIG_OVERRIDES_JSON  environment  variable is
51       queried, which  may  contain  configuration  key-value  mappings  as  a
52       JSON-formatted string of a JSON-object::
53
54       DATALAD_CONFIG_OVERRIDES_JSON='{"datalad.credential.example_com.user":
55       "jane", ...}'
56
57       This is useful when characters are part of the configuration  key  that
58       cannot be encoded into an environment variable name. If both individual
59       configuration variables *and* JSON-overrides are used, the former  take
60       precedent  over the latter, overriding the respective *individual* set‐
61       tings from configurations declared in the JSON-overrides.
62
63       This command supports recursive operation for  querying  and  modifying
64       configuration across a hierarchy of datasets.
65
66   Examples
67       Dump  the  effective  configuration, including an annotation for common
68       items::
69
70        % datalad configuration
71
72       Query two configuration items::
73
74        % datalad configuration get user.name user.email
75
76       Recursively set configuration in all (sub)dataset repositories::
77
78        % datalad configuration -r set my.config=value
79
80       Modify the persistent branch configuration  (changes  are  not  commit‐
81       ted)::
82
83        % datalad configuration --scope branch set my.config=value
84
85

OPTIONS

87       {dump|get|set|unset}
88              which  action  to  perform.  Constraints:  value  must be one of
89              ('dump', 'get', 'set', 'unset') [Default: 'dump']
90
91       name[=value]
92              configuration name (for actions 'get' and 'unset'), or name/val‐
93              ue pair (for action 'set').
94
95
96       -h, --help, --help-np
97              show this help message. --help-np forcefully disables the use of
98              a pager for displaying the help message
99
100       --scope {global|local|branch}
101              scope for getting or setting configuration. If no scope  is  de‐
102              clared  for  a query, all configuration sources (including over‐
103              rides via environment variables) are considered according to the
104              normal  rules  of precedence. For action 'get' only 'branch' and
105              'local' (which include 'global' here) are supported. For  action
106              'dump',  a  scope  selection is ignored and all available scopes
107              are considered. Constraints: value must  be  one  of  ('global',
108              'local', 'branch')
109
110       -d DATASET, --dataset DATASET
111              specify the dataset to query or to configure. Constraints: Value
112              must be a Dataset or a valid identifier of  a  Dataset  (e.g.  a
113              path) or value must be NONE
114
115       -r, --recursive
116              if set, recurse into potential subdatasets.
117
118       -R LEVELS, --recursion-limit LEVELS
119              limit  recursion into subdatasets to the given number of levels.
120              Constraints: value must be convertible to type  'int'  or  value
121              must be NONE
122
123       --version
124              show the module and its version which provides the command
125

AUTHORS

127        datalad is developed by The DataLad Team and Contributors <team@datal‐
128       ad.org>.
129
130
131
132datalad configuration 0.19.3      2023-08-11          datalad configuration(1)