Repository: clap-rs/clap (language: rust)

Issue:
Remove `{bin}` help template variable
When we added the `{name}` variable, we forgot to remove the broken `{bin}` variable in 4.0 and people are still accidentally using it for new use cases (#4561).

When removing it, we should assert on `{bin}` not being in the help template to help people transition across the breaking change.


Discussion / hints:

Fix patch:
diff --git a/clap_bench/benches/04_new_help.rs b/clap_bench/benches/04_new_help.rs
index 3398b58ef4b..dfb2157e58e 100644
--- a/clap_bench/benches/04_new_help.rs
+++ b/clap_bench/benches/04_new_help.rs
@@ -199,7 +199,7 @@ pub fn example10(c: &mut Criterion) {
 }
 
 pub fn example4_template(c: &mut Criterion) {
-    let mut cmd = app_example4().help_template("{bin} {version}\n{author}\n{about}\n\nUSAGE:\n    {usage}\n\nOPTIONS:\n{options}\n\nARGS:\n{args}\n");
+    let mut cmd = app_example4().help_template("{name} {version}\n{author}\n{about}\n\nUSAGE:\n    {usage}\n\nOPTIONS:\n{options}\n\nARGS:\n{args}\n");
     c.bench_function("example4_template", |b| b.iter(|| build_help(&mut cmd)));
 }
 
diff --git a/clap_bench/benches/05_ripgrep.rs b/clap_bench/benches/05_ripgrep.rs
index efca09c835b..00662ea5d51 100644
--- a/clap_bench/benches/05_ripgrep.rs
+++ b/clap_bench/benches/05_ripgrep.rs
@@ -256,7 +256,7 @@ const USAGE: &str = "
     rg [OPTIONS] --type-list";
 
 const TEMPLATE: &str = "\
-{bin} {version}
+{name} {version}
 {author}
 {about}
 
diff --git a/src/builder/command.rs b/src/builder/command.rs
index 203e677a7be..1a424993287 100644
--- a/src/builder/command.rs
+++ b/src/builder/command.rs
@@ -1744,7 +1744,7 @@ impl Command {
     /// Valid tags are:
     ///
     ///   * `{name}`                - Display name for the (sub-)command.
-    ///   * `{bin}`                 - Binary name.
+    ///   * `{bin}`                 - Binary name.(deprecated)
     ///   * `{version}`             - Version number.
     ///   * `{author}`              - Author information.
     ///   * `{author-with-newline}` - Author followed by `\n`.
@@ -1772,7 +1772,7 @@ impl Command {
     /// # use clap::Command;
     /// Command::new("myprog")
     ///     .version("1.0")
-    ///     .help_template("{bin} ({version}) - {usage}")
+    ///     .help_template("{name} ({version}) - {usage}")
     /// # ;
     /// ```
     ///
diff --git a/src/builder/debug_asserts.rs b/src/builder/debug_asserts.rs
index dff70e30fa7..bfebbb4c43f 100644
--- a/src/builder/debug_asserts.rs
+++ b/src/builder/debug_asserts.rs
@@ -359,6 +359,13 @@ pub(crate) fn assert_app(cmd: &Command) {
             cmd.get_name(),
             "`{unified}` template variable was removed in clap3, use `{options}` instead"
         );
+        #[cfg(feature = "unstable-v5")]
+        assert!(
+            !help_template.to_string().contains("{bin}"),
+            "Command {}: {}",
+            cmd.get_name(),
+            "`{bin}` template variable was removed in clap5, use `{name}` instead"
+        )
     }
 
     cmd._panic_on_missing_help(cmd.is_help_expected_set());
diff --git a/src/output/help_template.rs b/src/output/help_template.rs
index 3db80da7be6..6fe9db1b4a7 100644
--- a/src/output/help_template.rs
+++ b/src/output/help_template.rs
@@ -137,6 +137,7 @@ impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> {
                     "name" => {
                         self.write_display_name();
                     }
+                    #[cfg(not(feature = "unstable-v5"))]
                     "bin" => {
                         self.write_bin_name();
                     }


Test patch:
diff --git a/tests/builder/help.rs b/tests/builder/help.rs
index c448f7117e8..dbd8084a9b4 100644
--- a/tests/builder/help.rs
+++ b/tests/builder/help.rs
@@ -1042,6 +1042,7 @@ Options:
   -V, --version  Print version information
 ";
 
+    #[cfg(not(feature = "unstable-v5"))]
     let cmd = Command::new("ripgrep")
         .version("0.5")
         .override_usage(
@@ -1057,6 +1058,26 @@ Options:
 
 Usage: {usage}
 
+Options:
+{options}",
+        );
+
+    #[cfg(feature = "unstable-v5")]
+    let cmd = Command::new("ripgrep")
+        .version("0.5")
+        .override_usage(
+            "\
+       rg [OPTIONS] <pattern> [<path> ...]
+       rg [OPTIONS] [-e PATTERN | -f FILE ]... [<path> ...]
+       rg [OPTIONS] --files [<path> ...]
+       rg [OPTIONS] --type-list",
+        )
+        .help_template(
+            "\
+{name} {version}
+
+Usage: {usage}
+
 Options:
 {options}",
         );
diff --git a/tests/builder/template_help.rs b/tests/builder/template_help.rs
index 3df5ab4698a..4d305a24490 100644
--- a/tests/builder/template_help.rs
+++ b/tests/builder/template_help.rs
@@ -2,6 +2,7 @@ use super::utils;
 
 use clap::{arg, Command};
 
+#[cfg(not(feature = "unstable-v5"))]
 static EXAMPLE1_TMPL_S: &str = "{bin} {version}
 {author}
 {about}
@@ -10,6 +11,16 @@ Usage: {usage}
 
 {all-args}";
 
+#[cfg(feature = "unstable-v5")]
+static EXAMPLE1_TMPL_S: &str = "{name} {version}
+{author}
+{about}
+
+Usage: {usage}
+
+{all-args}";
+
+#[cfg(not(feature = "unstable-v5"))]
 static EXAMPLE1_TMPS_F: &str = "{bin} {version}
 {author}
 {about}
@@ -23,6 +34,20 @@ Arguments:
 Commands:
 {subcommands}";
 
+#[cfg(feature = "unstable-v5")]
+static EXAMPLE1_TMPS_F: &str = "{name} {version}
+{author}
+{about}
+
+Usage: {usage}
+
+Options:
+{options}
+Arguments:
+{positionals}
+Commands:
+{subcommands}";
+
 static CUSTOM_TEMPL_HELP: &str = "MyApp 1.0
 Kevin K. <kbknapp@gmail.com>
 Does awesome things
@@ -105,11 +130,20 @@ fn template_unknowntag() {
 
 #[test]
 fn template_author_version() {
+    #[cfg(not(feature = "unstable-v5"))]
     let cmd = Command::new("MyApp")
         .version("1.0")
         .author("Kevin K. <kbknapp@gmail.com>")
         .about("Does awesome things")
         .help_template("{author}\n{version}\n{about}\n{bin}");
+
+    #[cfg(feature = "unstable-v5")]
+    let cmd = Command::new("MyApp")
+        .version("1.0")
+        .author("Kevin K. <kbknapp@gmail.com>")
+        .about("Does awesome things")
+        .help_template("{author}\n{version}\n{about}\n{name}");
+
     utils::assert_output(
         cmd,
         "MyApp --help",