@@ -192,6 +192,8 @@ max_files = 100000 # default 100000 files in one tree
192192max_tree_bytes = 1073741824 # default 1 GiB in one tree
193193allow_older = false # default false (rule 5)
194194refuse_symlinks = false # default false; true refuses a commit with a symlink that points out of the tree
195+ settle = " 30m" # default 0 (ask at once); ask only when the tip has not changed for this long, at most 168h
196+ reask_after = " 24h" # default 0 (never); ask a skipped or expired tip once more after this time (ask mode)
195197
196198[listener ]
197199user = " pullgate" # the user of the listener; owns the inbox
@@ -315,10 +317,30 @@ used again.
315317 ("the branch is back to the applied commit").
316318 - tip = the SHA of the open question: nothing to do.
317319 - tip is the held SHA, or was asked before and the question expired or
318- was skipped, or its check failed, or it was refused, or it failed
319- ` max_failed_tries ` times: nothing to do. `pullgate status NAME
320- --ask-again` clears this mark, and also closes an open question for
321- the tip (section 13).
320+ was skipped, or its check failed, or it was refused, or its check
321+ said "nothing to apply" (step 7), or it failed ` max_failed_tries `
322+ times: nothing to do. ` pullgate status NAME --ask-again ` clears this
323+ mark, and also closes an open question for the tip (section 13).
324+ - ** ` reask_after ` ** (default 0, off): in ` ask ` mode, a tip marked
325+ skipped or expired is asked
326+ once more when its mark is at least ` reask_after ` old and it is still
327+ the tip. Asking sets the mark to asked; a second Skip or expiry sets
328+ a new mark time, so the next ask comes only after the next wait. It
329+ counts against ` questions_per_day ` like every question. ` auto ` mode
330+ has no Skip, so ` reask_after ` does nothing there.
331+ - ** ` settle ` ** (default 0, off): root keeps in its state the time it
332+ first saw the tip (` tip_since ` ). A new tip, or a clock that went back
333+ before that time, starts it again. While the tip is younger than
334+ ` settle ` , the run logs "settling" and stops: no check, no question,
335+ no notice. So three merges in ten minutes give one question, for the
336+ last one, and a writer cannot keep moving the branch to make the
337+ owner tap without reading. It also holds in ` auto ` mode. The time is
338+ root's own: the commit date is written by the writer and is not
339+ trusted. An open question for an older tip stays open while the new
340+ tip settles: it is closed only when the new tip is asked (step 9), as
341+ today while the new tip is checked. A state file from a version
342+ before ` settle ` has no ` tip_since ` ; the first run sets it to now, so
343+ the tip it knew waits one settle time (fail closed).
322344 - tip is not a descendant of the applied SHA (an older commit, a force
323345 push, a rewritten branch) and ` allow_older ` is false: refuse. Send one
324346 notice for this SHA and mark it refused. When ` allow_older ` is true,
@@ -328,7 +350,15 @@ used again.
328350 send one notice per day, and do not ask.
3293516 . Export the tree of the tip, and the tree of the applied SHA
330352 (` PULLGATE_OLD_TREE ` ).
331- 7 . Run ` check ` as ` check_user ` (section 11). If it fails, mark the SHA
353+ 7 . Run ` check ` as ` check_user ` (section 11). If it exits with status
354+ ** 3** , the commit has nothing to apply on this host (for example only
355+ docs, or files for other hosts): mark the SHA ` nothing ` , send no
356+ message, and do not ask. The applied SHA stays as it is, so the next
357+ question still lists every commit since the last real apply, and its
358+ check and summary still compare with the last applied tree. In the
359+ broken state (section 10) exit 3 is a failed check with its notice,
360+ so the owner sees that a fix forward was not asked. Any other
361+ non-zero status, a timeout or a signal is a failed check. If it fails, mark the SHA
332362 "check failed", send a notice with the end of its output, and do not
333363 ask. The same SHA is not checked again. In that output the tree paths
334364 (` PULLGATE_TREE ` , ` PULLGATE_OLD_TREE ` ) become ` NEW ` and ` OLD ` . The
@@ -684,7 +714,9 @@ Their working directory is `PULLGATE_TREE`. Their umask is 022. Each has a timeo
684714(` check_timeout ` , ` apply_timeout ` ); on timeout the whole process group is
685715killed and the command counts as failed. pullgate keeps at most 64 KiB of
686716their output. The output of ` apply ` and ` health ` goes to the journal; the
687- report shows only the exit status. The output of ` check ` (its last lines)
717+ report shows only the exit status. ` check ` exits 0 to pass, 3 for
718+ "nothing to apply on this host" (section 7, step 7), and anything else to
719+ fail. The output of ` check ` (its last lines)
688720and of ` summary ` goes into Telegram messages, after the cleaning of
689721section 12.
690722
@@ -775,11 +807,13 @@ closed after a cut.
775807- ` off ` : ` pullgate run ` and ` pullgate apply ` do nothing.
776808
777809` pullgate status NAME ` prints the mode, the applied SHA, the open question,
778- the held SHA, the broken state ("broken since …, last error …"), the pause
779- file and an apply in progress. Flags:
810+ the held SHA, the mark of the last tip (` nothing ` reads "nothing (the check
811+ found nothing to apply on this host)"), "settling until …" while the tip
812+ waits for ` settle ` , the broken state ("broken since …, last error …"), the
813+ pause file and an apply in progress. Flags:
780814
781815- ` --ask-again ` : clear the marks of the last fetched tip (expired, skipped,
782- check failed, refused, failed, held), so the next run asks again. If a
816+ check failed, nothing, refused, failed, held), so the next run asks again. If a
783817 question for the tip is open (for example its message was lost), root
784818 removes it from its state, then asks the listener to close its message.
785819 The next run asks again with a new question ID and a new code. An
0 commit comments