code: def test_save(path=None):
      ds = Dataset(path).create(annex=False)
  
      with open(op.join(path, "new_file.tst"), "w") as f:
          f.write("something")
  
      ds.repo.add("new_file.tst", git=True)
      ok_(ds.repo.dirty)
  
      ds.save(message="add a new file")
      assert_repo_status(path, annex=isinstance(ds.repo, AnnexRepo))
  
      with open(op.join(path, "new_file.tst"), "w") as f:
          f.write("modify")
  
      ok_(ds.repo.dirty)
      ds.save(message="modified new_file.tst")
      assert_repo_status(path, annex=isinstance(ds.repo, AnnexRepo))
  
      # save works without ds and files given in the PWD
      with open(op.join(path, "new_file.tst"), "w") as f:
          f.write("rapunzel")
      with chpwd(path):
          save(message="love rapunzel")
      assert_repo_status(path, annex=isinstance(ds.repo, AnnexRepo))
  
      # and also without `-a` when things are staged
      with open(op.join(path, "new_file.tst"), "w") as f:
          f.write("exotic")
      ds.repo.add("new_file.tst", git=True)
      with chpwd(path):
          save(message="love marsians")
      assert_repo_status(path, annex=isinstance(ds.repo, AnnexRepo))
  
      files = ["one.txt", "two.txt"]
      for fn in files:
          with open(op.join(path, fn), "w") as f:
              f.write(fn)
  
      ds.save([op.join(path, f) for f in files])
      # superfluous call to save (alll saved it already), should not fail
      # but report that nothing was saved
      assert_status("notneeded", ds.save(message="set of new files"))
      assert_repo_status(path, annex=isinstance(ds.repo, AnnexRepo))
  
      # create subdataset
      subds = ds.create("subds")
      assert_repo_status(path, annex=isinstance(ds.repo, AnnexRepo))
      # modify subds
      with open(op.join(subds.path, "some_file.tst"), "w") as f:
          f.write("something")
      subds.save()
      assert_repo_status(
          subds.path, annex=isinstance(subds.repo, AnnexRepo)
      )
      # ensure modified subds is committed
      ds.save()
      assert_repo_status(path, annex=isinstance(ds.repo, AnnexRepo))
  
      # now introduce a change downstairs
      subds.create("someotherds")
      assert_repo_status(
          subds.path, annex=isinstance(subds.repo, AnnexRepo)
      )
      ok_(ds.repo.dirty)
      # and save via subdataset path
      ds.save("subds", version_tag="new_sub")
      assert_repo_status(path, annex=isinstance(ds.repo, AnnexRepo))
      tags = ds.repo.get_tags()
      ok_(len(tags) == 1)
      eq_(tags[0], dict(hexsha=ds.repo.get_hexsha(), name="new_sub"))
      # fails when retagged, like git does
      res = ds.save(version_tag="new_sub", on_failure="ignore")
      assert_status("error", res)
      assert_result_count(
          res,
          1,
          action="save",
          type="dataset",
          path=ds.path,
          message=(
              "cannot tag this version: %s",
              "fatal: tag 'new_sub' already exists",
          ),
      )
  
imports: import itertools
  import logging
  import os
  import os.path
  import pytest
  import datalad.utils
  from datalad.api import create, install, save
  from datalad.distribution.dataset import Dataset
  from datalad.support.annexrepo import AnnexRepo
  from datalad.support.exceptions import CommandError
  from datalad.tests.utils_pytest import DEFAULT_BRANCH, OBSCURE_FILENAME, SkipTest, assert_in, assert_in_results, assert_not_in, assert_raises, assert_repo_status, assert_result_count, assert_status, chpwd, create_tree, eq_, known_failure, known_failure_windows, maybe_adjust_repo, neq_, ok_, patch, skip_if_adjusted_branch, skip_wo_symlink_capability, swallow_logs, swallow_outputs, with_tempfile, with_tree
  from datalad.utils import Path, ensure_list, rmtree
label_desc: Use image node_id 1 for calling a global function with example usage: test_save(path) without return types