Add a 'check' CLI command / API to check for new template version

[WernerWessely]

Is your feature request related to a problem? Please describe.

I would like for our developers or CI to check whether a new version of a project's template is available. This way they can know whether/when they should update.

I got the idea from the cruft check command: https://cruft.github.io/cruft/#checking-a-project. This command checks whether the project's template is up to date. Optionally the command can exit with some errorcode != 0 for use in scripts, e.g. in CI.

Does Copier maybe already offer this in some way that I overlooked?

Describe the solution you'd like

Perhaps a copier check command or a copier update --check option?

Describe alternatives you've considered
I am considering writing our own tool based on Copier until this becomes part of the CLI. My solution as part of Click based CLI currently looks like this:

@broj.command(
    short_help="Check for a newer template version for an existing project.")
@click.argument("project_dir", default=".",
                type=click.Path(file_okay=False, resolve_path=True,
                                writable=True, path_type=Path)
                )
@click.option(
    "-e", "--error",
    help="Exit with code 128 if a newer version is available.",
    is_flag=True
)
def check(project_dir, error):
    """
    Check if a newer template version is available for an existing project.

    PROJECT_DIR must be a git repo, if it is not passed, the current
    directory is used. It must also contain a '.copier-answers.yml' file
    with the current template settings.

    This command will try to compute the version currently used by the project
    and the remote template and decide whether an update is necessary.
    """
    with project_dir:

        _check_answers_file()

        with Worker() as worker:
            proj_version = worker.subproject.template.version
            temp_version = worker.template.version
            temp = worker.template.url

            if proj_version is None:
                raise click.ClickException(
                    f"Failed to determine version for project {project_dir}!")
            click.echo(
                f"Project {project_dir} template version: {proj_version}")

            if temp_version is None:
                raise click.ClickException(
                    f"Failed to determine version for template {temp}!")
            click.echo(f"Template {temp} version: {temp_version}")

            if temp_version > proj_version:
                click.echo("Update with 'broj update'!")
                if error:
                    exit(128)
            else:
                click.echo("There is nothing to do!")

Additional context

Thanks for the great work you guys do on Copier!

I would be willing to try my clumsy hand at a PR if we think such a feature makes sense.

[sisp]

Copier doesn't have this feature yet, but I like it. 👍 from my side.

[WernerWessely]

Great, any ideas or preferences as to the CLI?
Maybe a copier check command or can you think of something better suited to the Copier concepts overall?

[WernerWessely]

Ok, I created #1031 with the following CLI, any opinions?

~ ➜ copier -h
copier 0.0.0.post1067.dev0+beb174f

Create a new project from a template.

Docs in https://copier.readthedocs.io/

WARNING! Use only trusted project templates, as they might execute code with the same level of access as your
user.


Usage:
copier [MAIN_SWITCHES] [copy] [SUB_SWITCHES] template_src destination_path
copier [MAIN_SWITCHES] [update] [SUB_SWITCHES] [destination_path]
copier [MAIN_SWITCHES] check [SUB_SWITCHES] [destination_path]

Hidden-switches:
    -h, --help                         Prints this help message and quits
    --help-all                         Prints help messages of all sub-commands and quits
    -v, --version                      Prints the program's version and quits

Switches:
    -a, --answers-file VALUE:str       Update using this path (relative to `destination_path`) to find the answers
                                       file
    -d, --data VARIABLE=VALUE:str      Make VARIABLE available as VALUE when rendering the template; may be given
                                       multiple times
    -f, --force                        Same as `--defaults --overwrite`.
    -g, --prereleases                  Use prereleases to compare template VCS tags.
    -l, --defaults                     Use default answers to questions, which might be null if not specified.
    -n, --pretend                      Run but do not make any changes
    -q, --quiet                        Suppress status output
    -r, --vcs-ref VALUE:str            Git reference to checkout in `template_src`. If you do not specify it, it will
                                       try to checkout the latest git tag, as sorted using the PEP 440 algorithm. If
                                       you want to checkout always the latest version, use `--vcs-ref=HEAD`.
    -s, --skip VALUE:str               Skip specified files if they exist already; may be given multiple times
    -w, --overwrite                    Overwrite files that already exist, without asking.
    -x, --exclude VALUE:str            A name or shell-style pattern matching files or folders that must not be
                                       copied; may be given multiple times

Sub-commands:
    check                              Check if a copy is using the latest version of its original template; see
                                       'copier check --help' for more info
    copy                               Copy from a template source to a destination.; see 'copier copy --help' for
                                       more info
    update                             Update a copy from its original template; see 'copier update --help' for more
                                       info

~ ➜ copier check -h
copier check 0.0.0.post1067.dev0+beb174f

Check if a copy is using the latest version of its original template

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
determine whether a newer version is available, applying PEP 440 to the template's history.

Usage:
    copier check [SWITCHES] args...

Hidden-switches:
    -h, --help                     Prints this help message and quits
    --help-all                     Prints help messages of all sub-commands and quits
    -v, --version                  Prints the program's version and quits

Switches:
    -e, --exit-code VALUE:int      Exit code for the command if a newer version is available, for use in scripts.

test on  master ➜ copier check
Currently using template version 4.2.0, latest is 4.4.0.
New template version available.

[WernerWessely]

@sisp What should I do to see if we can make this feature happen?

[yajo]

You can make a cron that updates the project, checks if there's any diff and, if so, opens a PR. That'd be quite simple:

copier -f update
test -z "$(git status --porcelain)" || magic-open-pr

I think it's a better solution:

1. No changes for copier.
2. If the update is direct, devs just need to merge.

Would this be enough to solve your use case?

[sisp]

copier -f update might fail after #958 when questions change because there will be no implicit default value anymore. IMO, a native check for new template versions would be nice. 🙂

[WernerWessely]

IMO, a native check for new template versions would be nice.

Yes, that is at the core of the issue. Updates always require dev attention. As long as this is the case, it would be nice to have a reliable way of finding out whether a human should attempt an update. Checking the version seems like the simplest way of doing this 😃 .

[yajo]

I still think it's better to automate as much as possible. But probably this feature makes it easier to design an intermediate solution. I like easy things. 😉