Main usage

API¶

copier.copy()¶

copier.copy(
    src_path,
    dst_path,

    data=DEFAULT_DATA,
    *,
    exclude=DEFAULT_FILTER,
    skip_if_exists=[],
    tasks=[],

    envops={},
    extra_paths=[],

    pretend=False,
    force=False,
    skip=False,
    quiet=False,
    cleanup_on_error=True,
    subdirectory=None,
)

Uses the template in src_path to generate a new project at dst_path.

Arguments:

• src_path (str):
  Absolute path to the project skeleton, which can also be a version control system URL.

• dst_path (str):
  Absolute path to where to render the skeleton.

• data (dict):
  Data to be passed to the templates in addition to the user data from a copier.yml.

• exclude (list):
  A list of names or gitignore-style patterns matching files or folders that must not be copied.

• skip_if_exists (list):
  A list of names or gitignore-style patterns matching files or folders, that are skipped if another with the same name already exists in the destination folder. (It only makes sense if you are copying to a folder that already exists).

• tasks (list):
  Optional lists of commands to run in order after finishing the copy. Like in the templates files, you can use variables on the commands that will be replaced by the real values before running the command. If one of the commands fails, the rest of them will not run.

• envops (dict):
  Extra options for the Jinja template environment. See available options in Jinja's docs.

  Copier uses these defaults that are different from Jinja's:

  # copier.yml
  _envops:
      block_start_string: "[%"
      block_end_string: "%]"
      comment_start_string: "[#"
      comment_end_string: "#]"
      variable_start_string: "[["
      variable_end_string: "]]"
      keep_trailing_newline: true
  

  You can use default Jinja syntax with:

  # copier.yml
  _envops:
      block_start_string: "{%"
      block_end_string: "%}"
      comment_start_string: "{#"
      comment_end_string: "#}"
      variable_start_string: "{{"
      variable_end_string: "}}"
      keep_trailing_newline: false
  

• extra_paths (list):
  Additional paths, from where to search for templates. This is intended to be used with shared parent templates, files with macros, etc. outside the copied project skeleton.

• pretend (bool):
  Run but do not make any changes.

• force (bool):
  Overwrite files that already exist, without asking.

• skip (bool):
  Skip files that already exist, without asking.

• quiet (bool):
  Suppress the status output.

• cleanup_on_error (bool):
  Remove the destination folder if the copy process or one of the tasks fails. True by default.

• subdirectory (str):
  Path to a sub-folder to use as the root of the template when generating the project. If not specified, the root of the git repository is used.