Merge branch 'master' into subcommand-evaluation-refactor

README.md

@@ -1739,7 +1739,7 @@ Recipes, `mod` statements, and aliases may be annotated with attributes that cha
 | `[no-exit-message]`<sup>1.7.0</sup> | recipe | Don't print an error message if recipe fails. |
 | `[no-quiet]`<sup>1.23.0</sup> | recipe | Override globally quiet recipes and always echo out the recipe. |
 | `[positional-arguments]`<sup>1.29.0</sup> | recipe | Turn on [positional arguments](#positional-arguments) for this recipe. |
-| `[private]`<sup>1.10.0</sup> | alias, recipe | Make recipe or alias private. See [Private Recipes](#private-recipes). |
+| `[private]`<sup>1.10.0</sup> | alias, recipe | Make recipe, alias, or variable private. See [Private Recipes](#private-recipes). |
 | `[script]`<sup>1.33.0</sup> | recipe | Execute recipe as script. See [script recipes](#script-recipes) for more details. |
 | `[script(COMMAND)]`<sup>1.32.0</sup> | recipe | Execute recipe as a script interpreted by `COMMAND`. See [script recipes](#script-recipes) for more details. |
 | `[unix]`<sup>1.8.0</sup> | recipe | Enable recipe on Unixes. (Includes MacOS). |

src/config.rs

@@ -16,6 +16,7 @@ pub(crate) struct Config {
  pub(crate) dotenv_path: Option<PathBuf>,
  pub(crate) dry_run: bool,
  pub(crate) dump_format: DumpFormat,
+ pub(crate) explain: bool,
  pub(crate) highlight: bool,
  pub(crate) invocation_directory: PathBuf,
  pub(crate) list_heading: String,
@@ -88,6 +89,7 @@ mod arg {
  pub(crate) const DOTENV_PATH: &str = "DOTENV-PATH";
  pub(crate) const DRY_RUN: &str = "DRY-RUN";
  pub(crate) const DUMP_FORMAT: &str = "DUMP-FORMAT";
+ pub(crate) const EXPLAIN: &str = "EXPLAIN";
  pub(crate) const GLOBAL_JUSTFILE: &str = "GLOBAL-JUSTFILE";
  pub(crate) const HIGHLIGHT: &str = "HIGHLIGHT";
  pub(crate) const JUSTFILE: &str = "JUSTFILE";
@@ -206,6 +208,13 @@ impl Config {
  .value_name("FORMAT")
  .help("Dump justfile as <FORMAT>"),
  )
+ .arg(
+ Arg::new(arg::EXPLAIN)
+ .action(ArgAction::SetTrue)
+ .long("explain")
+ .env("JUST_EXPLAIN")
+ .help("Print recipe doc comment before running it"),
+ )
  .arg(
  Arg::new(arg::GLOBAL_JUSTFILE)
  .action(ArgAction::SetTrue)
@@ -685,6 +694,7 @@ impl Config {
  };
 
  let unstable = matches.get_flag(arg::UNSTABLE) || subcommand == Subcommand::Summary;
+ let explain = matches.get_flag(arg::EXPLAIN);
 
  Ok(Self {
  check: matches.get_flag(arg::CHECK),
@@ -702,6 +712,7 @@ impl Config {
  .get_one::<DumpFormat>(arg::DUMP_FORMAT)
  .unwrap()
  .clone(),
+ explain,
  highlight: !matches.get_flag(arg::NO_HIGHLIGHT),
  invocation_directory: env::current_dir().context(config_error::CurrentDirContext)?,
  list_heading: matches.get_one::<String>(arg::LIST_HEADING).unwrap().into(),

src/recipe.rs

@@ -153,14 +153,18 @@ impl<'src, D> Recipe<'src, D> {
  ) -> RunResult<'src, ()> {
  let config = &context.config;
 
+ let color = config.color.stderr().banner();
+ let prefix = color.prefix();
+ let suffix = color.suffix();
+
  if config.verbosity.loquacious() {
- let color = config.color.stderr().banner();
-  eprintln!(
- "{}===> Running recipe `{}`...{}",
-  color.prefix(),
-  self.name,
- color.suffix()
- );
+ eprintln!("{prefix}===> Running recipe `{}`...{suffix}", self.name);
+ }
+
+ if config.explain {
+ if let Some(doc) = self.doc() {
+ eprintln!("{prefix}#### {doc}{suffix}");
+ }
  }
 
  let evaluator = Evaluator::new(context, is_dependency, scope);

tests/explain.rs

@@ -0,0 +1,22 @@
+use super::*;
+
+#[test]
+fn explain_recipe() {
+ Test::new()
+ .justfile(
+ "
+ # List some fruits
+ fruits:
+ echo 'apple peach dragonfruit'
+ ",
+ )
+ .args(["--explain", "fruits"])
+ .stdout("apple peach dragonfruit\n")
+ .stderr(
+ "
+ #### List some fruits
+ echo 'apple peach dragonfruit'
+ ",
+ )
+ .run();
+}

tests/lib.rs

@@ -55,6 +55,7 @@ mod equals;
 mod error_messages;
 mod evaluate;
 mod examples;
+mod explain;
 mod export;
 mod fallback;
 mod fmt;