From d65d3264f4daa233dbd6afa2ac5870dddb109fb3 Mon Sep 17 00:00:00 2001
From: Valentin Haudiquet <valentin.haudiquet@canonical.com>
Date: Tue, 29 Sep 2026 12:17:05 +0200
Subject: [PATCH] deb: add opt-in --incremental flag for single-flag iterate
 loops

Iterating on a package currently needs two flags (--resume --keep):
without --keep a successful build consumes the session, and without
--resume nothing is reused, so incremental iteration never "just
works" opt-in.

--incremental is the single-flag form: with no --resume it adopts the
newest usable session of this tree (like `pkh deb --resume`), and it
always keeps the session on success, so the loop (edit, `pkh deb
--incremental`, edit, ...) reuses the chroot, build deps and objects
and only recompiles what changed. With an explicit `--resume <id>` it
only adds keep.

A plain `pkh deb` is unchanged: fresh session, consumed on success.
---
 README.md   |  9 +++++++++
 src/main.rs | 12 +++++++++---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index dc7e985..1d4d6d5 100644
--- a/README.md
+++ b/README.md
@@ -133,6 +133,9 @@ pkh deb --resume        # reuses the chroot, build deps and objects;
                         # only what changed is recompiled
 pkh deb list            # the sessions of this tree, with their ids
 pkh deb --resume <id>   # resume a specific session
+pkh deb --incremental   # one-flag iterate loop: adopts the newest
+                        # session like `--resume` and keeps it on
+                        # success (with `--resume <id>`, only adds keep)
 pkh deb --keep          # keep the session even after a successful build
                         # (iterate: edit, `pkh deb --resume --keep`, ...)
 pkh prune               # garbage-collect old sessions (7-day retention)
@@ -142,6 +145,12 @@ A plain `pkh deb` never reuses a session — everything is rechecked from
 scratch — and it replaces the session of its target. `pkh deb --resume`
 refuses to adopt a session built for a different series/architecture.
 
+`pkh deb --incremental` combines `--resume` (without an ID) with
+`--keep`, so iterating is a single flag: each successful build keeps the
+session and the next `--incremental` build reuses it, recompiling only
+what changed. With an explicit `--resume <id>` it only adds keep. A plain
+`pkh deb` still never reuses a session and consumes it on success.
+
 Packages whose `debian/rules` keeps an input-untracked stamp cache (the
 kernels' `debian/stamps`) declare it in the quirks data (`resume_clear`):
 resumed builds drop the cache so the wrapper steps — including the
diff --git a/src/main.rs b/src/main.rs
index 905238f..b7e94c0 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -376,6 +376,8 @@ fn main() {
                 )
                 .arg(arg!(--keep "Keep the build session after a successful build (for a later --resume)")
                     .long_help("Keep the build session after a successful build, so a later 'pkh deb --resume' can iterate on it (e.g. after editing sources).\nWithout it, a successful build consumes the session (failures and interrupts always keep it)."))
+                .arg(arg!(--incremental "Reuse a previous build session of this target (like --resume) and keep the session even on success; the next --incremental build reuses the chroot, build deps and objects")
+                    .required(false))
                 .arg(arg!(--verbose "Show raw tool output instead of the live build view").required(false)
                     .long_help("Show raw tool output instead of the live build view.\nAlso implied by RUST_LOG=debug for pkh's own logs."))
                 .subcommand(
@@ -937,14 +939,18 @@ fn main() {
                 })
             });
 
-            // Session handling: --resume [<id>] and --keep (see the deb
-            // subcommand help).
+            // Session handling: --resume [<id>], --incremental and --keep
+            // (see the deb subcommand help). --incremental adopts the newest
+            // session when no explicit --resume ID is given, and always adds
+            // keep so the session survives success.
+            let incremental = sub_matches.get_flag("incremental");
             let resume = match sub_matches.get_one::<String>("resume").map(String::as_str) {
                 Some("") => pkh::deb::SessionResume::Latest,
                 Some(id) => pkh::deb::SessionResume::Id(id.to_string()),
+                None if incremental => pkh::deb::SessionResume::Latest,
                 None => pkh::deb::SessionResume::Fresh,
             };
-            let keep_session = sub_matches.get_flag("keep");
+            let keep_session = sub_matches.get_flag("keep") || incremental;
 
             // Live build view, unless --verbose (DebUi additionally disables
             // itself when stdout is not a terminal)