datalad.api.update

datalad.api.update(path=None, sibling=None, merge=False, 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', merge=True)

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', merge=True, follow='parentds', 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. If no sibling is given, updates from all siblings are obtained. [Default: None]
  • merge (bool or {'any', 'ff-only'}, optional) – merge obtained changes from the sibling. If a sibling is not explicitly given and there is only a single known sibling, that sibling is used. Otherwise, an unspecified sibling defaults to the configured remote for the current branch. By default, changes are fetched from the sibling but not merged into the current branch. With merge=True or merge=”any”, the changes will be merged into the current branch. A value of ‘ff-only’ restricts the allowed merges to fast-forwards. [Default: False]
  • follow ({'sibling', 'parentds'}, 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. 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 subdataset. [Default: False]
  • recursion_limit (int or None, optional) – limit recursion into subdataset 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 ({'default', 'json', 'json_pp', 'tailored'} or None, optional) – format of return value rendering on stdout. [Default: None]
  • 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’]