datalad.api.update

datalad.api.update(path=None, *, sibling=None, merge=False, how=None, how_subds=None, follow='sibling', dataset=None, recursive=False, recursion_limit=None, fetch_all=None, reobtain_data=False)

Update a dataset from a sibling.

Examples

Update from a particular sibling:

> update(sibling='siblingname')

Update from a particular sibling and merge the changes from a configured or matching branch from the sibling (see follow for details):

> update(sibling='siblingname', how='merge')

Update from the sibling ‘origin’, traversing into subdatasets. For subdatasets, merge the revision registered in the parent dataset into the current branch:

> update(sibling='origin', how='merge', follow='parentds', recursive=True)

Fetch and merge the remote tracking branch into the current dataset. Then update each subdataset by resetting its current branch to the revision registered in the parent dataset, fetching only if the revision isn’t already present:

> update(how='merge', how_subds='reset', follow='parentds-lazy', recursive=True)
Parameters:

  • path (sequence of str or None, optional) – constrain to-be-updated subdatasets to the given path for recursive operation. [Default: None]

  • sibling (str or None, optional) – name of the sibling to update from. When unspecified, updates from all siblings are fetched. If there is more than one sibling and changes will be brought into the working tree (as requested via merge, how, or how_subds), a sibling will be chosen based on the configured remote for the current branch. [Default: None]

  • merge (bool or {'any', 'ff-only'}, optional) – merge obtained changes from the sibling. This is a subset of the functionality that can be achieved via the newer how. merge=True or merge=”any” is equivalent to how=”merge”. merge=”ff-only” is equivalent to how=”ff-only”. [Default: False]

  • how ({'fetch', 'merge', 'ff-only', 'reset', 'checkout', None}, optional) – how to update the dataset. The default (“fetch”) simply fetches the changes from the sibling but doesn’t incorporate them into the working tree. A value of “merge” or “ff-only” merges in changes, with the latter restricting the allowed merges to fast-forwards. “reset” incorporates the changes with ‘git reset –hard <target>’, staying on the current branch but discarding any changes that aren’t shared with the target. “checkout”, on the other hand, runs ‘git checkout <target>’, switching from the current branch to a detached state. When recursive=True is specified, this action will also apply to subdatasets unless overridden by how_subds. [Default: None]

  • how_subds ({'fetch', 'merge', 'ff-only', 'reset', 'checkout', None}, optional) – Override the behavior of how in subdatasets. [Default: None]

  • follow ({'sibling', 'parentds', 'parentds-lazy'}, optional) – source of updates for subdatasets. For ‘sibling’, the update will be done by merging in a branch from the (specified or inferred) sibling. The branch brought in will either be the current branch’s configured branch, if it points to a branch that belongs to the sibling, or a sibling branch with a name that matches the current branch. For ‘parentds’, the revision registered in the parent dataset of the subdataset is merged in. ‘parentds-lazy’ is like ‘parentds’, but prevents fetching from a subdataset’s sibling if the registered revision is present in the subdataset. Note that the current dataset is always updated according to ‘sibling’. This option has no effect unless a merge is requested and recursive=True is specified. [Default: ‘sibling’]

  • dataset (Dataset or None, optional) – specify the dataset to update. If no dataset is given, an attempt is made to identify the dataset based on the current working directory. [Default: None]

  • recursive (bool, optional) – if set, recurse into potential subdatasets. [Default: False]

  • recursion_limit (int or None, optional) – limit recursion into subdatasets to the given number of levels. [Default: None]

  • fetch_all (bool, optional) – this option has no effect and will be removed in a future version. When no siblings are given, an all-sibling update will be performed. [Default: None]

  • reobtain_data (bool, optional) – if enabled, file content that was present before an update will be re-obtained in case a file was changed by the update. [Default: False]

  • on_failure ({'ignore', 'continue', 'stop'}, optional) – behavior to perform on failure: ‘ignore’ any failure is reported, but does not cause an exception; ‘continue’ if any failure occurs an exception will be raised at the end, but processing other actions will continue for as long as possible; ‘stop’: processing will stop on first failure and an exception is raised. A failure is any result with status ‘impossible’ or ‘error’. Raised exception is an IncompleteResultsError that carries the result dictionaries of the failures in its failed attribute. [Default: ‘continue’]

  • result_filter (callable or None, optional) – if given, each to-be-returned status dictionary is passed to this callable, and is only returned if the callable’s return value does not evaluate to False or a ValueError exception is raised. If the given callable supports **kwargs it will additionally be passed the keyword arguments of the original API call. [Default: None]

  • result_renderer – select rendering mode command results. ‘tailored’ enables a command- specific rendering style that is typically tailored to human consumption, if there is one for a specific command, or otherwise falls back on the the ‘generic’ result renderer; ‘generic’ renders each result in one line with key info like action, status, path, and an optional message); ‘json’ a complete JSON line serialization of the full result record; ‘json_pp’ like ‘json’, but pretty-printed spanning multiple lines; ‘disabled’ turns off result rendering entirely; ‘<template>’ reports any value(s) of any result properties in any format indicated by the template (e.g. ‘{path}’, compare with JSON output for all key-value choices). The template syntax follows the Python “format() language”. It is possible to report individual dictionary values, e.g. ‘{metadata[name]}’. If a 2nd-level key contains a colon, e.g. ‘music:Genre’, ‘:’ must be substituted by ‘#’ in the template, like so: ‘{metadata[music#Genre]}’. [Default: ‘tailored’]

  • result_xfm ({'datasets', 'successdatasets-or-none', 'paths', 'relpaths', 'metadata'} or callable or None, optional) – if given, each to-be-returned result status dictionary is passed to this callable, and its return value becomes the result instead. This is different from result_filter, as it can perform arbitrary transformation of the result value. This is mostly useful for top- level command invocations that need to provide the results in a particular format. Instead of a callable, a label for a pre-crafted result transformation can be given. [Default: None]

  • return_type ({'generator', 'list', 'item-or-list'}, optional) – return value behavior switch. If ‘item-or-list’ a single value is returned instead of a one-item return value list, or a list in case of multiple return values. None is return in case of an empty list. [Default: ‘list’]