--explain option

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;