fix(cli): keep multi-entry log diffs compact

Author: mohammedahmed18

crates/loc-cli/src/commands.rs

@@ -474,7 +474,10 @@ struct LogCliArgs {
         help = "Only show one push journal entry."
     )]
     push_id: Option<String>,
-    #[arg(long, help = "Print the readable diff saved with each journal entry.")]
+    #[arg(
+        long,
+        help = "Print the readable diff when the log resolves to one journal entry."
+    )]
     diff: bool,
 }
 
@@ -4262,6 +4265,7 @@ fn write_log_report<W: Write>(report: &LogReport, output: &mut W) -> io::Result<
         return Ok(());
     }
 
+    let inline_diff = report.entries.len() == 1;
     for (index, entry) in report.entries.iter().enumerate() {
         if index > 0 {
             writeln!(output)?;
@@ -4291,7 +4295,11 @@ fn write_log_report<W: Write>(report: &LogReport, output: &mut W) -> io::Result<
             entry.plan_summary.blocks_archived
         )?;
         writeln!(output, "  operations: {}", entry.operation_count)?;
-        write_readable_diff(output, entry.readable_diff.as_ref())?;
+        if inline_diff {
+            write_readable_diff(output, entry.readable_diff.as_ref())?;
+        } else if entry.readable_diff.is_some() {
+            writeln!(output, "  diff: loc log --push-id {} --diff", entry.push_id)?;
+        }
     }
 
     Ok(())
@@ -7782,6 +7790,66 @@ mod tests {
         );
     }
 
+    #[test]
+    fn log_report_writer_omits_inline_diffs_for_multiple_entries() {
+        let entry = |push_id: &str, diff_text: &str| JournalEntryOutput {
+            push_id: push_id.to_string(),
+            mount_id: "notion-main".to_string(),
+            remote_ids: vec!["page-1".to_string()],
+            status: "reconciled".to_string(),
+            failure: None,
+            author: "anonymous".to_string(),
+            previous_push_id: None,
+            created_at_unix_ms: None,
+            readable_diff: Some(locality_core::readable_diff::ReadableDiffOutput {
+                files: Vec::new(),
+                text: diff_text.to_string(),
+            }),
+            preimage_count: 1,
+            apply_effect_count: 1,
+            plan_summary: PlanSummaryOutput {
+                blocks_created: 0,
+                blocks_updated: 1,
+                blocks_replaced: 0,
+                blocks_moved: 0,
+                media_updated: 0,
+                blocks_archived: 0,
+                entities_created: 0,
+                entities_archived: 0,
+                entities_moved: 0,
+                properties_updated: 0,
+            },
+            operation_count: 1,
+        };
+        let report = LogReport {
+            ok: true,
+            command: "log",
+            entries: vec![
+                entry("push-2", "diff --locality a/two.md b/two.md\n"),
+                entry("push-1", "diff --locality a/one.md b/one.md\n"),
+            ],
+        };
+        let mut output = Vec::new();
+
+        write_log_report(&report, &mut output).expect("write log report");
+        let rendered = String::from_utf8(output).expect("utf8 output");
+
+        assert!(rendered.contains("push push-2"), "{rendered}");
+        assert!(rendered.contains("push push-1"), "{rendered}");
+        assert!(
+            !rendered.contains("diff --locality"),
+            "multi-entry log should not inline diff bodies:\n{rendered}"
+        );
+        assert!(
+            rendered.contains("diff: loc log --push-id push-2 --diff"),
+            "{rendered}"
+        );
+        assert!(
+            rendered.contains("diff: loc log --push-id push-1 --diff"),
+            "{rendered}"
+        );
+    }
+
     #[test]
     fn clean_diff_report_exits_successfully() {
         assert_eq!(diff_report_exit_code(&report(true)), EXIT_SUCCESS);

docs/cli.md

@@ -680,9 +680,10 @@ unified diff when file content changed.
 remote mutations. Once a push is journaled, Locality stores linked edit metadata
 and the readable diff in the durable push journal.
 
-`loc log --diff` reads those journaled diffs back for audit and review. Combine
-it with `--push-id <push-id>` to show the readable diff for one push entry, or
-with a path to narrow the journal before selecting a push.
+`loc log --diff` reads those journaled diffs back for audit and review. Use
+`--push-id <push-id> --diff` to show the readable diff for one push entry; when
+a human log view has multiple entries, Locality keeps the list compact and
+prints the command to inspect each entry's diff.
 
 ## Initial `loc push --json` Shape
 
@@ -780,7 +781,10 @@ from the SQLite state store. Without a path it lists all journal entries; with a
 path it resolves the path through the mount/entity mapping and lists entries
 that touched that entity. `--push-id` filters the path-scoped result to one push
 entry. By default, JSON and human output omit saved readable diffs so regular log
-calls stay compact; pass `--diff` to include them.
+calls stay compact. Pass `--diff` to include them in JSON. In human output,
+`--diff` prints the saved readable diff when the result has one entry; for
+multi-entry results it prints per-entry `loc log --push-id <push-id> --diff`
+hints instead of dumping every diff body.
 
 Each JSON entry includes:
 
@@ -801,7 +805,9 @@ Each JSON entry includes:
 
 Human output is a compact git-log-style list headed by `push <push-id>`. It
 prints linked edit fields such as `author`, `created_at_unix_ms`, and `previous`
-when available; with `--diff`, it then prints the saved readable diff text.
+when available. With `--diff`, one-entry output prints the saved readable diff
+text; multi-entry output prints a `diff: loc log --push-id <push-id> --diff`
+hint for each entry that has a saved diff.
 
 ## Initial `loc undo --json` Shape