docs: def run(self, cmd, target=None, lock_name=None, shell=None, nofail=False, clean=False, follow=None, container=None):
          """
          The primary workhorse function of PipelineManager, this runs a command.
  
          This is the command  execution function, which enforces
          race-free file-locking, enables restartability, and multiple pipelines
          can produce/use the same files. The function will wait for the file
          lock if it exists, and not produce new output (by default) if the
          target output file already exists. If the output is to be created,
          it will first create a lock file to prevent other calls to run
          (for example, in parallel pipelines) from touching the file while it
          is being created. It also records the memory of the process and
          provides some logging output.
  
          :param str | list[str] cmd: Shell command(s) to be run.
          :param str | Sequence[str] target: Output file(s) to produce, optional.
              If all target files exist, the command will not be run. If no target
              is given, a lock_name must be provided.
          :param str lock_name: Name of lock file. Optional.
          :param bool shell: If command requires should be run in its own shell.
              Optional. Default: None --will try to determine whether the
              command requires a shell.
          :param bool nofail: Whether the pipeline proceed past a nonzero return from
              a process, default False; nofail can be used to implement
              non-essential parts of the pipeline; if a 'nofail' command fails,
              the pipeline is free to continue execution.
          :param bool clean: True means the target file will be automatically added
              to an auto cleanup list. Optional.
          :param callable follow: Function to call after executing (each) command.
          :param str container: Name for Docker container in which to run commands.
          :return int: Return code of process. If a list of commands is passed,
              this is the maximum of all return codes for all commands.
          """
  
          # If the pipeline's not been started, skip ahead.
          if not self._active:
              cmds = [cmd] if isinstance(cmd, str) else cmd
              cmds_text = [c if isinstance(c, str) else " ".join(c) for c in cmds]
              print("Pipeline is inactive; skipping {} command(s):\n{}".
                    format(len(cmds), "\n".join(cmds_text)))
              return 0
  
          # Short-circuit if the checkpoint file exists and the manager's not
          # been configured to overwrite such files.
          if self.curr_checkpoint is not None:
              check_fpath = checkpoint_filepath(self.curr_checkpoint, self)
              if os.path.isfile(check_fpath) and not self.overwrite_checkpoints:
                  print("Checkpoint file exists for '{}' ('{}'), and the {} has "
                        "been configured to not overwrite checkpoints; "
                        "skipping command '{}'".format(
                      self.curr_checkpoint, check_fpath,
                      self.__class__.__name__, cmd))
                  return 0
  
          # TODO: consider making the logic such that locking isn't implied, or
          # TODO (cont.): that we can make it otherwise such that it's not
          # TODO (cont.): strictly necessary to provide target or lock_name.
          # The default lock name is based on the target name.
          # Therefore, a targetless command that you want
          # to lock must specify a lock_name manually.
          if target is None and lock_name is None:
              self.fail_pipeline(Exception(
                  "You must provide either a target or a lock_name."))
  
          # Downstream code requires target to be a list, so convert if only
          # a single item was given
          if not is_multi_target(target) and target is not None:
              target = [target]
  
          # Downstream code requires a list of locks; convert 
          if isinstance(lock_name, str):
              lock_name = [lock_name]
          
          # Default lock_name (if not provided) is based on the target file name,
          # but placed in the parent pipeline outfolder
          lock_name = lock_name or make_lock_name(target, self.outfolder)
          lock_files = [self._make_lock_path(ln) for ln in lock_name]
  
          process_return_code = 0
          local_maxmem = 0
  
          # Decide how to do follow-up.
          if not follow:
              call_follow = lambda: None
          elif not hasattr(follow, "__call__"):
              # Warn about non-callable argument to follow-up function.
              print("Follow-up function is not callable and won't be used: {}".
                    format(type(follow)))
              call_follow = lambda: None
          else:
              # Wrap the follow-up function so that the log shows what's going on.
              def call_follow():
                  print("Follow:")
                  follow()
  
  
          # The while=True loop here is unlikely to be triggered, and is just a
          # wrapper to prevent race conditions; the lock_file must be created by
          # the current loop. If not, we loop again and then re-do the tests.
          # The recover and newstart options inform the pipeline to run a command
          # in a scenario where it normally would not. We use these "local" flags
          # to allow us to report on the state of the pipeline in the first round
          # as normal, but then proceed on the next iteration through the outer
          # loop. The proceed_through_locks is a flag that is set if any lockfile
          # is found that needs to be recovered or overwritten. It instructs us to
          # ignore lock files on the next iteration.
          local_recover = False
          local_newstart = False 
          proceed_through_locks = False
  
          while True:
              ##### Tests block
              # Base case: All targets exists and not set to overwrite targets break loop, don't run process.
              # os.path.exists returns True for either a file or directory; .isfile is file-only
              if target is not None and all([os.path.exists(t) for t in target]) \
                      and not any([os.path.isfile(l) for l in lock_files]) \
                      and not local_newstart:
                  for tgt in target:
                      if os.path.exists(tgt): print("Target exists: `" + tgt + "`")
                  if self.new_start:
                      print("New start mode; run anyway.")
                      # Set the local_newstart flag so the command will run anyway.
                      # Doing this in here instead of outside the loop allows us
                      # to still report the target existence.
                      local_newstart = True
                      continue
                  # Normally we don't run the follow, but if you want to force. . .
                  if self.force_follow:
                      call_follow()
                  break  # Do not run command
  
              # Scenario 1: Lock file exists, but we're supposed to overwrite target; Run process.
              if not proceed_through_locks:
                  for lock_file in lock_files:
                      recover_file = self._recoverfile_from_lockfile(lock_file)
                      if os.path.isfile(lock_file):
                          print("Found lock file: {}".format(lock_file))
                          if self.overwrite_locks:
                              print("Overwriting target. . .")
                              proceed_through_locks = True
                          elif os.path.isfile(recover_file):
                              print("Found dynamic recovery file ({}); "
                                    "overwriting target. . .".format(recover_file))
                              # remove the lock file which will then be promptly re-created for the current run.
                              local_recover = True
                              proceed_through_locks = True
                              # the recovery flag is now spent; remove so we don't accidentally re-recover a failed job
                              os.remove(recover_file)
                          else:  # don't overwrite locks
                              self._wait_for_lock(lock_file)
                              # when it's done loop through again to try one more
                              # time (to see if the target exists now)
                              continue
  
  
              # If you get to this point, the target doesn't exist, and the lock_file doesn't exist 
              # (or we should overwrite). create the lock (if you can)
              # Initialize lock in master lock list
              for lock_file in lock_files:
                  self.locks.append(lock_file)
                  if self.overwrite_locks or local_recover:
                      self._create_file(lock_file)
                  else:
                      try:
                          self._create_file_racefree(lock_file)  # Create lock
                      except OSError as e:
                          if e.errno == errno.EEXIST:  # File already exists
                              print ("Lock file created after test! Looping again: {}".format(
                                  lock_file))
  
                              # Since a lock file was created by a different source, 
                              # we need to reset this flag to re-check the locks.
                              proceed_through_locks = False
                              continue  # Go back to start
  
              ##### End tests block
              # If you make it past these tests, we should proceed to run the process.
  
              if target is not None:
                  print("Target to produce: {}\n".format(",".join(['`'+x+'`' for x in target])))
              else:
                  print("Targetless command, running...\n")
  
              if isinstance(cmd, list):  # Handle command lists
                  for cmd_i in cmd:
                      list_ret, maxmem = \
                          self.callprint(cmd_i, shell, lock_file, nofail, container)
                      maxmem = max(maxmem) if isinstance(maxmem, Iterable) else maxmem
                      local_maxmem = max(local_maxmem,  maxmem)
                      list_ret = max(list_ret) if isinstance(list_ret, Iterable) else list_ret
                      process_return_code = max(process_return_code, list_ret)
  
              else:  # Single command (most common)
                  process_return_code, local_maxmem = \
                      self.callprint(cmd, shell, lock_file, nofail, container)  # Run command
                  if isinstance(process_return_code, list):
                      process_return_code = max(process_return_code)
  
              # For temporary files, you can specify a clean option to automatically
              # add them to the clean list, saving you a manual call to clean_add
              if target is not None and clean:
                  for tgt in target:
                      self.clean_add(tgt)
  
              call_follow()
              for lock_file in lock_files:
                  os.remove(lock_file)  # Remove lock file
                  self.locks.remove(lock_file)
  
              # If you make it to the end of the while loop, you're done
              break
  
          return process_return_code