cli.py

Command line entrypoint. This module declares the Copier CLI applications.

Basically, there are 3 different commands you can run:

• copier, the main app, which is a shortcut for the copy and update subapps.

  If the destination project is found and has an answers file with enough information, it will become a shortcut for copier update.

  Otherwise it will be a shortcut for copier copy.

  Example

  # Copy a new project
  copier gh:copier-org/autopretty my-project
  # Update it
  cd my-project
  copier
  

• copier copy, used to bootstrap a new project from a template.

  Example

  copier copy gh:copier-org/autopretty my-project
  

• copier update to update a preexisting project to a newer version of its template.

  Example

  copier update
  

Below are the docs of each one of those.

CopierApp

Bases: cli.Application

The Copier CLI application.

Source code in copier/cli.py

class CopierApp(cli.Application):
    """The Copier CLI application."""

    DESCRIPTION = "Create a new project from a template."
    DESCRIPTION_MORE = (
        dedent(
            """\
            Docs in https://copier.readthedocs.io/

            """
        )
        + (
            colors.yellow
            | dedent(
                """\
                WARNING! Use only trusted project templates, as they might
                execute code with the same level of access as your user.\n
                """
            )
        )
    )
    VERSION = copier_version()
    CALL_MAIN_IF_NESTED_COMMAND = False

CopierCopySubApp

Bases: _Subcommand

The copier copy subcommand.

Use this subcommand to bootstrap a new subproject from a template, or to override a preexisting subproject ignoring its history diff.

Source code in copier/cli.py

@CopierApp.subcommand("copy")
class CopierCopySubApp(_Subcommand):
    """The `copier copy` subcommand.

    Use this subcommand to bootstrap a new subproject from a template, or to override
    a preexisting subproject ignoring its history diff.
    """

    DESCRIPTION = "Copy from a template source to a destination."

    cleanup_on_error = cli.Flag(
        ["-C", "--no-cleanup"],
        default=True,
        help="On error, do not delete destination if it was created by Copier.",
    )
    defaults = cli.Flag(
        ["-l", "--defaults"],
        help="Use default answers to questions, which might be null if not specified.",
    )
    force = cli.Flag(
        ["-f", "--force"],
        help="Same as `--defaults --overwrite`.",
    )
    overwrite = cli.Flag(
        ["-w", "--overwrite"],
        help="Overwrite files that already exist, without asking.",
    )

    @handle_exceptions
    def main(self, template_src: str, destination_path: str) -> int:
        """Call [run_copy][copier.main.Worker.run_copy].

        Params:
            template_src:
                Indicate where to get the template from.

                This can be a git URL or a local path.

            destination_path:
                Where to generate the new subproject. It must not exist or be empty.
        """
        with self._worker(
            template_src,
            destination_path,
            cleanup_on_error=self.cleanup_on_error,
            defaults=self.force or self.defaults,
            overwrite=self.force or self.overwrite,
        ) as worker:
            worker.run_copy()
        return 0

main(template_src, destination_path)

Call run_copy.

Parameters:

Name	Type	Description	Default
template_src	str	Indicate where to get the template from. This can be a git URL or a local path.	required
destination_path	str	Where to generate the new subproject. It must not exist or be empty.	required

Source code in copier/cli.py

@handle_exceptions
def main(self, template_src: str, destination_path: str) -> int:
    """Call [run_copy][copier.main.Worker.run_copy].

    Params:
        template_src:
            Indicate where to get the template from.

            This can be a git URL or a local path.

        destination_path:
            Where to generate the new subproject. It must not exist or be empty.
    """
    with self._worker(
        template_src,
        destination_path,
        cleanup_on_error=self.cleanup_on_error,
        defaults=self.force or self.defaults,
        overwrite=self.force or self.overwrite,
    ) as worker:
        worker.run_copy()
    return 0

CopierRecopySubApp

Bases: _Subcommand

The copier recopy subcommand.

Use this subcommand to update an existing subproject from a template that supports updates, ignoring any subproject evolution since the last Copier execution.

Source code in copier/cli.py

@CopierApp.subcommand("recopy")
class CopierRecopySubApp(_Subcommand):
    """The `copier recopy` subcommand.

    Use this subcommand to update an existing subproject from a template that
    supports updates, ignoring any subproject evolution since the last Copier
    execution.
    """

    DESCRIPTION = "Recopy a subproject from its original template"
    DESCRIPTION_MORE = dedent(
        """\
        The copy must have a valid answers file which contains info from the
        last Copier execution, including the source template (it must be a key
        called `_src_path`).

        This command will ignore any diff that you have generated since the
        last `copier` execution. It will act as if it were the 1st time you
        apply the template to the destination path. However, it will keep the
        answers.

        If you want a smarter update that respects your project evolution, use
        `copier update` instead.
        """
    )

    defaults = cli.Flag(
        ["-l", "--defaults"],
        help="Use default answers to questions, which might be null if not specified.",
    )
    force = cli.Flag(
        ["-f", "--force"],
        help="Same as `--defaults --overwrite`.",
    )
    overwrite = cli.Flag(
        ["-w", "--overwrite"],
        help="Overwrite files that already exist, without asking.",
    )
    skip_answered = cli.Flag(
        ["-A", "--skip-answered"],
        default=False,
        help="Skip questions that have already been answered",
    )

    @handle_exceptions
    def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
        """Call [run_recopy][copier.main.Worker.run_recopy].

        Parameters:
            destination_path:
                Only the destination path is needed to update, because the
                `src_path` comes from [the answers file][the-copier-answersyml-file].

                The subproject must exist. If not specified, the currently
                working directory is used.
        """
        with self._worker(
            dst_path=destination_path,
            defaults=self.force or self.defaults,
            overwrite=self.force or self.overwrite,
            skip_answered=self.skip_answered,
        ) as worker:
            worker.run_recopy()
        return 0

main(destination_path='.')

Call run_recopy.

Parameters:

Name	Type	Description	Default
destination_path	cli.ExistingDirectory	Only the destination path is needed to update, because the src_path comes from the answers file. The subproject must exist. If not specified, the currently working directory is used.	'.'

Source code in copier/cli.py

@handle_exceptions
def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
    """Call [run_recopy][copier.main.Worker.run_recopy].

    Parameters:
        destination_path:
            Only the destination path is needed to update, because the
            `src_path` comes from [the answers file][the-copier-answersyml-file].

            The subproject must exist. If not specified, the currently
            working directory is used.
    """
    with self._worker(
        dst_path=destination_path,
        defaults=self.force or self.defaults,
        overwrite=self.force or self.overwrite,
        skip_answered=self.skip_answered,
    ) as worker:
        worker.run_recopy()
    return 0

CopierUpdateSubApp

Bases: _Subcommand

The copier update subcommand.

Use this subcommand to update an existing subproject from a template that supports updates, respecting that subproject evolution since the last Copier execution.

Source code in copier/cli.py

@CopierApp.subcommand("update")
class CopierUpdateSubApp(_Subcommand):
    """The `copier update` subcommand.

    Use this subcommand to update an existing subproject from a template
    that supports updates, respecting that subproject evolution since the last
    Copier execution.
    """

    DESCRIPTION = "Update a subproject from its original template"
    DESCRIPTION_MORE = dedent(
        """\
        The copy must have a valid answers file which contains info
        from the last Copier execution, including the source template
        (it must be a key called `_src_path`).

        If that file contains also `_commit`, and `destination_path` is a git
        repository, this command will do its best to respect the diff that you have
        generated since the last `copier` execution. To avoid that, use `copier recopy`
        instead.
        """
    )

    conflict = cli.SwitchAttr(
        ["-o", "--conflict"],
        cli.Set("rej", "inline"),
        default="inline",
        help=(
            "Behavior on conflict: Create .rej files, or add inline conflict markers."
        ),
    )
    context_lines = cli.SwitchAttr(
        ["-c", "--context-lines"],
        int,
        default=3,
        help=(
            "Lines of context to use for detecting conflicts. Increase for "
            "accuracy, decrease for resilience."
        ),
    )
    defaults = cli.Flag(
        ["-l", "-f", "--defaults"],
        help="Use default answers to questions, which might be null if not specified.",
    )
    skip_answered = cli.Flag(
        ["-A", "--skip-answered"],
        default=False,
        help="Skip questions that have already been answered",
    )

    @handle_exceptions
    def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
        """Call [run_update][copier.main.Worker.run_update].

        Parameters:
            destination_path:
                Only the destination path is needed to update, because the
                `src_path` comes from [the answers file][the-copier-answersyml-file].

                The subproject must exist. If not specified, the currently
                working directory is used.
        """
        with self._worker(
            dst_path=destination_path,
            conflict=self.conflict,
            context_lines=self.context_lines,
            defaults=self.defaults,
            skip_answered=self.skip_answered,
            overwrite=True,
        ) as worker:
            worker.run_update()
        return 0

main(destination_path='.')

Call run_update.

Parameters:

Name	Type	Description	Default
destination_path	cli.ExistingDirectory	Only the destination path is needed to update, because the src_path comes from the answers file. The subproject must exist. If not specified, the currently working directory is used.	'.'

Source code in copier/cli.py

@handle_exceptions
def main(self, destination_path: cli.ExistingDirectory = ".") -> int:
    """Call [run_update][copier.main.Worker.run_update].

    Parameters:
        destination_path:
            Only the destination path is needed to update, because the
            `src_path` comes from [the answers file][the-copier-answersyml-file].

            The subproject must exist. If not specified, the currently
            working directory is used.
    """
    with self._worker(
        dst_path=destination_path,
        conflict=self.conflict,
        context_lines=self.context_lines,
        defaults=self.defaults,
        skip_answered=self.skip_answered,
        overwrite=True,
    ) as worker:
        worker.run_update()
    return 0

handle_exceptions(method, *args, **kwargs)

Handle keyboard interruption while running a method.

Source code in copier/cli.py

@decorator
def handle_exceptions(method, *args, **kwargs):
    """Handle keyboard interruption while running a method."""
    try:
        try:
            return method(*args, **kwargs)
        except KeyboardInterrupt:
            raise UserMessageError("Execution stopped by user")
    except UserMessageError as error:
        print(colors.red | "\n".join(error.args), file=sys.stderr)
        return 1
    except UnsafeTemplateError as error:
        print(colors.red | "\n".join(error.args), file=sys.stderr)
        # DOCS https://github.com/copier-org/copier/issues/1328#issuecomment-1723214165
        return 0b100