feat(derive): Add #[command(defer)] for lazy subcommand initialization

[r-near]

Summary

Adds #[command(defer = true)] to the derive API, enabling lazy initialization of subcommand arguments via Command::defer(). This closes the gap between the builder API (which has had Command::defer since #4792) and the derive API.

• Subcommand metadata (.about(), .version(), etc.) is applied eagerly, so --help displays subcommand descriptions without needing build()
• Subcommand args and nested subcommands are wrapped in Command::defer() and only materialized when needed
• Defaults to false in v4, true under unstable-v5

Motivation

CLIs with many deeply nested subcommands pay a steep startup cost because clap eagerly initializes every subcommand and all their args — even when only one is invoked. For a CLI with ~330 subcommands, this was measured at 4–6 seconds of startup time, reduced to ~12ms with deferred initialization.

See #4959 for the original feature request.

Prior art

This picks up the work from #6225 by @frol, restructured to follow the project's contribution guidelines. Key differences from the original PR:

• gen_augment accepts a skip_top_level_methods parameter so metadata and args are each generated exactly once (no duplication)
• Commit history follows CONTRIBUTING.md conventions (refactor → baseline tests → feature)

Example

#[derive(Subcommand)]
#[command(defer = true)]
enum Commands {
    /// Add a file
    Add { #[arg(long)] file: String },
    /// Remove a file  
    Remove { #[arg(long)] force: bool },
}

Partially addresses #4959

[Copilot]

Pull request overview

This PR adds support in clap_derive for a new #[command(defer = ...)] attribute to enable lazy initialization of subcommand arguments (via Command::defer), aligning derive behavior with the existing builder API and improving startup time for CLIs with large subcommand trees.

Changes:

• Add defer tracking to derive Item and parse #[command(defer = true/false)].
• Generate deferred subcommand augmentation for derive-generated subcommands, splitting eager metadata from deferred arg/subcommand materialization.
• Add/adjust derive tests to validate deferred behavior and ensure help-related introspection calls Command::build() when needed.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/derive/help.rs	Updates tests to call cmd.build() before subcommand introspection and reformats an assertion.
tests/derive/defer.rs	Adds new integration tests covering deferred subcommand initialization (including nested subcommands and version-dependent defaults).
clap_derive/src/item.rs	Introduces Item::defer state with a default tied to unstable-v5, parses the new magic attribute, and exposes a getter.
clap_derive/src/derives/subcommand.rs	Wraps subcommand augmentation in Command::defer(...) when enabled and avoids duplicating top-level method generation in the deferred path.
clap_derive/src/derives/args.rs	Adds skip_top_level_methods plumbing to support eager metadata + deferred args generation without duplication.
clap_derive/src/attr.rs	Adds lit_bool_or_abort and registers defer as a magic attribute name.

Comments suppressed due to low confidence (1)

clap_derive/src/derives/subcommand.rs:343

• For named variants, args::gen_augment(...) already prepends parent_item.deprecations() (see derives/args.rs), but this code also injects item.deprecations() into the surrounding subcommand({ ... }) block. This can lead to duplicated deprecation warnings/work for the same item. Consider suppressing one of these (e.g., add a flag to args::gen_augment to skip deprecations when the caller handles them, or only emit #deprecations here for the non-Named branches).

                let deprecations = if !override_required {
                    item.deprecations()
                } else {
                    quote!()
                };

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[epage]

This squashed the refactor commit from #6225: 38bbeb6

[r-near]

This squashed the refactor commit from #6225: 38bbeb6

Split it back out here b98fc9e and unified the Named/Unit/Unnamed branches into the same tuple pattern.

@epage thanks for the quick review! Would you mind taking another look when you have a chance?

[epage]

The intention would be that we would do this consistently across all derives

[r-near]

Ok both callers now apply initial/final uniformly. Added here 560fef5 (this PR)

[epage]

Thanks! This is almost there, just some clean up.

[epage]

We don't seem to do this for Args. We're missing a test case for this.

Looking back at #6225, I see deferring of arguments discussed at #6225 (comment)

This is causing me to look back at #4959 where new trait methods are suggested and I'm wondering why I suggested those originally and if there is some missing functionality, e.g. around flatten.

[r-near]

Added a test case for this.

So for the current scope, I think flatten is covered under deferred subcommands, right?

The extra trait-method ideas from #4959 seem like broader defer semantics. IDK if you wanna add that into this PR?

[r-near]

@epage would you mind taking a look when you get a chance?

[r-near]

Please sir, may I have a review? @epage