clarify push behavior

Author: skarim

README.md

@@ -355,7 +355,7 @@ Push all branches in the current stack to the remote.
 gh stack push [flags]
 ```
 
-Pushes every branch to the remote using `--force-with-lease --atomic`. This is a lightweight wrapper around `git push` that knows about all branches in the stack. It does not create or update pull requests — use `gh stack submit` for that.
+Pushes every branch in one `git push` using explicit per-branch `--force-with-lease` checks. The update is not atomic: branches whose leases pass may update even if another branch is rejected. Fix the rejected branch and rerun the command; branches already updated will be unchanged. This command does not create or update pull requests — use `gh stack submit` for that.
 
 | Flag | Description |
 |------|-------------|

cmd/push.go

@@ -22,9 +22,10 @@ func PushCmd(cfg *config.Config) *cobra.Command {
 		Short: "Push all branches in the current stack to the remote",
 		Long: `Push all branches in the current stack to the remote.
 
-Uses --force-with-lease and --atomic to ensure safe, all-or-nothing pushes.
-Merged and queued branches are automatically skipped. This command is safe to
-run repeatedly — it will only update branches that have changed.`,
+Uses explicit per-branch --force-with-lease checks. Updates are not atomic: a
+branch may update even if another branch is rejected. Fix the rejected branch
+and run the command again; branches already updated will be unchanged.
+Merged and queued branches are automatically skipped.`,
 		Example: `  # Push all stack branches to the default remote
   $ gh stack push
 
@@ -77,7 +78,7 @@ func runPush(cfg *config.Config, opts *pushOptions) error {
 	}
 	s := stacks[0]
 
-	// Push all active branches atomically
+	// Push all active branches with explicit per-branch leases.
 	remote, err := pickRemote(cfg, currentBranch, opts.remote)
 	if err != nil {
 		if !errors.Is(err, errInterrupt) {

docs/src/content/docs/guides/workflows.md

@@ -249,7 +249,7 @@ gh stack push
 
 This is equivalent but distinct from updating your branch using a merge commit. The key difference is that after changing a lower branch, rebase maintains a linear commit history so the unique set of commits on each branch have clean diffs.
 
-`gh stack push` then handles the force push safely via `--force-with-lease --atomic`, ensuring either all branches update or none do.
+`gh stack push` then handles the force push with explicit per-branch `--force-with-lease` checks. The multi-branch push is not atomic: branches whose leases pass may update even if another branch is rejected. Fix the rejected branch and rerun the command; branches already updated will be unchanged.
 
 For a simpler all-in-one flow, `gh stack sync` combines fetch, rebase, and push into a single command — useful when you just need to pull in the latest upstream changes:
 

docs/src/content/docs/reference/cli.md

@@ -408,7 +408,7 @@ gh stack push [flags]
 |------|-------------|
 | `--remote <name>` | Remote to push to (defaults to auto-detected remote) |
 
-Pushes every branch to the remote using `--force-with-lease --atomic`. This is a lightweight wrapper around `git push` that knows about all branches in the stack. It does not create or update pull requests — use `gh stack submit` for that.
+Pushes every branch in one `git push` using explicit per-branch `--force-with-lease` checks. The update is not atomic: branches whose leases pass may update even if another branch is rejected. Fix the rejected branch and rerun the command; branches already updated will be unchanged. This command does not create or update pull requests — use `gh stack submit` for that.
 
 **Examples:**
 

skills/gh-stack/SKILL.md

@@ -512,7 +512,8 @@ gh stack push --remote upstream
 
 **Behavior:**
 
-- Pushes all active (non-merged) branches atomically (`--force-with-lease --atomic`)
+- Pushes all active (non-merged, non-queued) branches in one non-atomic multi-ref push with explicit per-branch `--force-with-lease` checks
+- Some branches may update if another is rejected; fix the rejected branch and rerun the command
 - Does **not** create or update pull requests — use `gh stack submit` for that
 
 **Output (stderr):**
@@ -541,7 +542,7 @@ gh stack submit --auto --open
 
 **Behavior:**
 
-- Pushes all active (non-merged) branches atomically (`--force-with-lease --atomic`)
+- Pushes each active (non-merged, non-queued) branch sequentially with explicit per-branch `--force-with-lease` checks; the overall submit is not atomic
 - Creates a new PR for each branch that doesn't have one (base set to the first non-merged ancestor branch)
 - After creating PRs, links them together as a **Stack** on GitHub (requires the repository to have stacks enabled)
 - If every PR in the stack has already been merged, the stack is complete and can't be extended. `submit` automatically forks your unmerged branches into a **new** stack rooted at the trunk and creates it on GitHub, leaving the merged stack untouched.