From 3f5557e96e89160ee84a289516ffb2af16b8be61 Mon Sep 17 00:00:00 2001 From: "@permadeath.com" Date: Tue, 25 Aug 2026 09:17:20 -0400 Subject: [PATCH] docs(stack): correct six claims that stopped being true mid-branch `stack mark` said it was offline and then learned to fetch; `stack rebase`'s help never mentioned that an unreachable remote is a warning; `stack view` listed the columns it printed before the commit count existed; a JSON field claimed to carry positions it has never held; and a rebase failure asserted what --abort does to refs, which it should not. --- src/clients/git/run.rs | 4 +++- src/cmd/stack/mod.rs | 24 ++++++++++++++++-------- src/cmd/stack/read.rs | 9 ++++++--- src/cmd/stack/write.rs | 8 +++++--- 4 files changed, 30 insertions(+), 15 deletions(-) diff --git a/src/clients/git/run.rs b/src/clients/git/run.rs index bec5c35..00c0daa 100644 --- a/src/clients/git/run.rs +++ b/src/clients/git/run.rs @@ -571,7 +571,9 @@ pub fn rebase_update_refs(base: &str) -> Result<()> { bail!( "the rebase stopped:\n{text}\n\ resolve and `git rebase --continue`, or `git rebase --abort` to put the branch \ - back; the marks move either way" + back\n\ + --update-refs moves the marks as the rebase reaches them, so `atgc stack mark` \ + is worth a look either way" ); } Ok(()) diff --git a/src/cmd/stack/mod.rs b/src/cmd/stack/mod.rs index 95adac2..2974608 100644 --- a/src/cmd/stack/mod.rs +++ b/src/cmd/stack/mod.rs @@ -454,10 +454,15 @@ pub(crate) enum Command { /// is the whole reason this exists rather than a line of advice: a plain /// `git rebase` silently un-cuts a stack. /// - /// It stops on a conflict exactly where git stops, leaving the rebase in - /// progress for `git rebase --continue` or `--abort`, and refuses - /// outright on a dirty working tree. Nothing is sent: `atgc stack - /// resubmit` is what reconciles the records afterwards. + /// A target that cannot be fetched is a warning rather than a stop: the + /// copy already in the checkout is replayed onto, which may be behind. + /// A dirty working tree, or a rebase already in progress, is refused + /// outright, and a conflict stops exactly where git stops, leaving the + /// rebase in progress for `git rebase --continue` or `--abort`. + /// + /// Nothing is sent. `atgc stack resubmit` reconciles the records + /// afterwards, and `atgc stack sync` is the two of them in one command, + /// which is usually what you want. /// /// Examples: /// atgc stack rebase --dry-run @@ -509,14 +514,17 @@ pub(crate) enum Command { Resubmit(write::ResubmitArgs), /// View the current branch's stack, top to bottom /// - /// One line per pull: position, state, number, title, record key and - /// round count, with the top of the stack: the pull nothing depends - /// on: first. Refuses when the branch's pull is not stacked, because + /// One line per pull: position, state, number, title, record key, how + /// many commits it holds when that is more than one, and round count, + /// with the top of the stack: the pull nothing depends on: first. The + /// commit count is read off each member's latest patch, which is the + /// only place it is written. Refuses when the branch's pull is not stacked, because /// `atgc pr view` is the single-pull command. /// /// `--json` prints one object for the whole chain: the branch, its /// target, and a `members` array top first, each member carrying its - /// at-uri, record key, appview number, state, title and round count. + /// at-uri, record key, appview number, state, title, round count and + /// how many commits it holds (`null` where the patch could not be read). /// Richer than `pr view --json`'s `stack.members`, which is the same /// chain seen from beside a single pull. Same stability rule as every /// other --json; see docs/output.md. diff --git a/src/cmd/stack/read.rs b/src/cmd/stack/read.rs index b069f63..2491fe7 100644 --- a/src/cmd/stack/read.rs +++ b/src/cmd/stack/read.rs @@ -568,8 +568,11 @@ fn name_for(rev: &str) -> Result { /// `atgc stack mark`: place one, forget one, or list them. /// -/// Deliberately offline. Marks are a fact about this checkout, not about any -/// record, and a command that cuts a stack should work on a plane. +/// Reads no records: a mark is a fact about this checkout, not about +/// anything published, and nothing here is sent anywhere. The one thing it +/// needs from outside is the range the marks sit in, so it fetches the +/// target *only* when this checkout has never seen it — and says so plainly +/// when that fetch is the thing that failed. pub(crate) fn mark(args: MarkArgs) -> Result<()> { crate::term::jsonout::init(args.json); let branch = git::current_branch()?; @@ -676,7 +679,7 @@ pub(crate) fn mark(args: MarkArgs) -> Result<()> { pull request per commit", commits.len() ); - println!("`atgc stack mark part1 HEAD~3` cuts it"); + println!("`atgc stack mark HEAD~3` cuts it, named after that commit"); return Ok(()); } println!("branch: {branch} ({} commit(s) over {base})", commits.len()); diff --git a/src/cmd/stack/write.rs b/src/cmd/stack/write.rs index 7bf8438..7ef8ad2 100644 --- a/src/cmd/stack/write.rs +++ b/src/cmd/stack/write.rs @@ -511,7 +511,7 @@ async fn create_inner(args: CreateArgs, rewritten: &mut Option ` cuts it again", + `atgc stack mark ` cuts it again", commits.len(), ); } @@ -580,7 +580,7 @@ async fn create_inner(args: CreateArgs, rewritten: &mut Option println!( "cut: no marks on this branch: a pull per commit \ - (`atgc stack mark part1 HEAD~3` cuts it)" + (`atgc stack mark ` cuts it)" ), n => println!("cut: {n} mark(s), each ending a pull"), } @@ -2449,7 +2449,9 @@ pub(in crate::cmd) struct RebasedJson { pub was: String, pub now: String, pub commits: usize, - /// The marks that moved with their commits, and where they ended up. + /// The marks that travel with this replay, by branch name. Populated on + /// a dry run too, since naming what would move is most of what a dry run + /// is for; `atgc stack mark` is where their new positions are read back. pub marks: Vec, } -- 2.51.2