feat: add `check-update` subcommand #2463

natescherer · 2026-01-20T00:35:23Z

Hello! This is my attempt to complete the work that was done in #1031. (Should close #1020, as well.)

What's Changed

Here's what I've changed versus the previous PR, by type:

Outstanding changes requested in discussions on old PR

Subcommand updated to check-update
Hard-coded exit code when an update is detected to 5
- 2 was discussed in the previous PR but I changed it based on Ambiguous exit code 2 #1328
Tests added

Necessary Updates

Restructured to match updates made to project in the intervening years

Other Changes

Minor rewording
Added --check-update-output-as-json flag for integrating with CI/scripts/etc
- I'm not in love with this name but seeing as how I had to add it at the Worker level I figured I should make it pretty specific

Questions/To-Do

I have a few questions for the maintainers:

Are we sure that having the app exit with an error when there is an update is the right pattern?
- I preserved it based on the work previously done, but if I was designing this from scratch, I wouldn't consider an update being available an error in the classic sense
- My addition of --check-update-output-as-json provides a hook for scripts to detect if there is an update, from the discussions I saw before that seemed to be the overall intention of the exit code
What level of documentation would you like for this subcommand?
- Maybe a docs/checking_for_updates.md?

Thanks for making such an awesome tool! Please let me know if there are changes you'd like me to make.

Resolves: copier-org#1020

sisp

Thanks for contributing this feature to Copier, @natescherer! 🙇

I've left a couple of inline comments.

sisp · 2026-02-10T21:24:29Z

copier/_cli.py

+    check_update_output_as_json = cli.Flag(
+        ["--check-update-output-as-json"],
+        help="Output a JSON object to stdout containing information about if an update is needed",
+    )


How about renaming this flag to --output-format with two allowed values plain and json similar to, e.g., Ruff's corresponding flag?

--output-format <OUTPUT_FORMAT> Output serialization format for violations. The default serialization format is "full" [env: RUFF_OUTPUT_FORMAT=] [possible values: concise, full, json, json-lines, junit, grouped, github, gitlab, pylint, rdjson, azure, sarif]

Works for me, is an updated help message like this acceptable?

Output format, either 'plain' (the default) or 'json'. This flag is only supported by the 'check-update' subcommand.

For the CLI flag, the context is clear, so the second sentence isn't needed. But it makes sense to keep it for the Worker class attribute. One day, I'll try to split this class, so we won't have attributes that are only meaningful for some operations. 🤞

sisp · 2026-02-10T21:26:35Z

copier/_main.py

+                "update_available": self.template.version
+                > self.subproject.template.version,


This might be a bit more legible with surrounding parentheses:

Suggested change

"update_available": self.template.version

> self.subproject.template.version,

"update_available": (

self.template.version > self.subproject.template.version

),

sisp · 2026-02-10T21:30:02Z

copier/_main.py

+                    "Parent template update available. "
+                    f"\nCurrent version is {self.subproject.template.version}, "


I think "template" suffices, parent template sounds like the parent of a template in a hierarchy. Or perhaps even "New template version available"? WDYT?

I'd move the line break to the first line for better legibility.

Suggested change

"Parent template update available. "

f"\nCurrent version is {self.subproject.template.version}, "

"New template version available.\n"

f"Current version is {self.subproject.template.version}, "

Good point, I agree with the terminology change. I have been making a series of hierarchical templates myself and got my wires crossed I think.

sisp · 2026-02-10T21:43:54Z

tests/test_check_update.py

Since this is a new test file for an entirely new feature, can we reduce the test cases code to a minimum?

Avoid Git bundles.

Avoid custom _envops settings.

Minimize test file content (README.txt.jinja).

Keep commit messages simple, e.g. git("commit", "-m", "v1").

It might make sense to factor out the test template to a fixture, similar to, e.g., this:

copier/tests/test_answersfile_templating.py

Lines 13 to 30 in d3dd580

@pytest.fixture(scope="module")

def template_path(tmp_path_factory: pytest.TempPathFactory) -> str:

root = tmp_path_factory.mktemp("template")

build_file_tree(

{

root / "{{ _copier_conf.answers_file }}.jinja": """\

# Changes here will be overwritten by Copier

{{ _copier_answers|to_nice_yaml }}

""",

root / "copier.yml": """\

_answers_file: ".copier-answers-{{ module_name }}.yml"

module_name:

type: str

""",

}

)

return str(root)

Sure, I can simplify it. I just grabbed an existing test more or less at random, I agree it is a little over complex.

natescherer · 2026-02-10T21:57:05Z

@sisp While I'm working on those changes, would appreciate your thoughts on the two questions I raised at the bottom of the PR, thanks. 🙏

sisp

Regarding the exit code: I think exiting with 0 when there's no update (i.e., the project is up-to-date) and with non-zero otherwise seems reasonable. At least Cruft follows a similar approach. The specific non-zero exit code is another question. Cruft exits with 1 when there is an update, but 1 is already used for, e.g., precondition errors like a missing old template reference. Exit code 2 is used for indicating unsafe templates without explicit user trust, but this error can only occur for copy and update operations but never when checking for an update. I think it's fine to use the same exit code for different errors by different subcommands.

[...] but if I was designing this from scratch, I wouldn't consider an update being available an error in the classic sense

What exactly do you mean by "in the classic sense"?

Regarding documentation: How about adding a section on our "Updating a project" page, similar to Cruft's corresponding section?

sisp · 2026-02-11T20:16:56Z

copier/_cli.py

+    check_update_output_as_json = cli.Flag(
+        ["--check-update-output-as-json"],
+        help="Output a JSON object to stdout containing information about if an update is needed",
+    )


For the CLI flag, the context is clear, so the second sentence isn't needed. But it makes sense to keep it for the Worker class attribute. One day, I'll try to split this class, so we won't have attributes that are only meaningful for some operations. 🤞

natescherer · 2026-02-11T20:45:08Z

Sounds good re: the documentation.

As far as what I mean by "in the classic sense" this is probably my SRE brain talking, but I tend to see any application ending with a non-zero status code as indicating that there is some failure in execution, but there's no failure/error/issue when the sub command checks and sees there is an update; the update checking process worked just fine. Hopefully that makes sense?

wesselyw and others added 11 commits May 2, 2023 16:07

feat: add the 'copier check' command

dc7dd2a

Resolves: copier-org#1020

fix: review corrections

effcd6e

fix: review corrections

751778a

refactor: sync branch with copier-org/copier

4a89dc4

refactor: refactor check code for current project structure

aec8eda

refactor: rename 'check' subcommand to 'check-update'

72e4c98

fix: hard-code exit code to 2 when updates are detected

bdfab92

fix: fix error handling to reflect project updates

62aa14d

refactor: rename 'run_check' to 'run_check_update'

10b62b8

feat: add --check-update-output-as-json flag for check-update subcommand

da98915

test: add tests for check-update subcommand

0e88aa6

sisp requested changes Feb 10, 2026

View reviewed changes

sisp reviewed Feb 11, 2026

View reviewed changes

		"update_available": self.template.version
		> self.subproject.template.version,

		"Parent template update available. "
		f"\nCurrent version is {self.subproject.template.version}, "

	@pytest.fixture(scope="module")
	def template_path(tmp_path_factory: pytest.TempPathFactory) -> str:
	root = tmp_path_factory.mktemp("template")
	build_file_tree(
	{
	root / "{{ _copier_conf.answers_file }}.jinja": """\
	# Changes here will be overwritten by Copier
	{{ _copier_answers\|to_nice_yaml }}
	""",
	root / "copier.yml": """\
	_answers_file: ".copier-answers-{{ module_name }}.yml"

	module_name:
	type: str
	""",
	}
	)
	return str(root)

Uh oh!

feat: add check-update subcommand #2463

Are you sure you want to change the base?

feat: add check-update subcommand #2463

Conversation

natescherer commented Jan 20, 2026

What's Changed

Outstanding changes requested in discussions on old PR

Necessary Updates

Other Changes

Questions/To-Do

Uh oh!

sisp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

natescherer commented Feb 10, 2026

Uh oh!

sisp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

natescherer commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: add `check-update` subcommand #2463

feat: add `check-update` subcommand #2463