Skip to content

copier

cli.py

copier-org/copier

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.

CLI help generated from copier --help-all:

sh: 1: copier: not found

`CopierApp` ¶

Bases: Application

The Copier CLI application.

Source code in copier/_cli.py

class CopierApp(cli.Application):  # type: ignore[misc]
    """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.",
    )

    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.
        """

        def inner() -> None:
            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 _handle_exceptions(inner)

`main(template_src, destination_path)` ¶

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

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.
    """

    def inner() -> None:
        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 _handle_exceptions(inner)

`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",
    )

    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.
        """

        def inner() -> None:
            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 _handle_exceptions(inner)

`main(destination_path='.')` ¶

Call run_recopy.

Parameters:

Name	Type	Description	Default
`destination_path`	`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

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.
    """

    def inner() -> None:
        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 _handle_exceptions(inner)

`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",
    )

    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.
        """

        def inner() -> None:
            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 _handle_exceptions(inner)

`main(destination_path='.')` ¶

Call run_update.

Parameters:

Name	Type	Description	Default
`destination_path`	`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

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.
    """

    def inner() -> None:
        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 _handle_exceptions(inner)