From 9d2513b4c3caa93b174b8a3285db44f07a1cce91 Mon Sep 17 00:00:00 2001
From: Rocker Zhang <zhang.rocker.liyuan@gmail.com>
Date: Fri, 15 May 2026 19:27:57 +0800
Subject: [PATCH] man: clarify that ExecCondition= skip triggers SuccessAction=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Unit-level Condition…= / Assert…= directives that fail prevent activation
entirely, so SuccessAction= / FailureAction= never fire. An ExecCondition=
skip in [Service] runs as part of the activation transition itself, so
the unit goes active → inactive and SuccessAction= is honored.

This asymmetry has tripped users up; document it explicitly in both
systemd.service(5) (ExecCondition= section) and systemd.unit(5)
(SuccessAction= / FailureAction= section) with cross-references.

Fixes: https://github.com/systemd/systemd/issues/42035

Co-developed-by: Claude Opus 4.7 <noreply@anthropic.com>
(cherry picked from commit 90e3b4cb2653f8a96512da625eb92bc72607a136)
(cherry picked from commit 82d3a4911495926ec9c029c6703d5e20647be15c)
(cherry picked from commit e9a039d14042f29f8515b88aa94157ab3cb7108d)
---
 man/systemd.service.xml |  9 +++++++++
 man/systemd.unit.xml    | 10 ++++++++++
 2 files changed, 19 insertions(+)

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 00c7e823d9f..d7ca9bf8425 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -463,6 +463,15 @@
         signal, etc.), the unit will be considered failed (and remaining commands will be skipped). Exit code of 0 or
         those matching <varname>SuccessExitStatus=</varname> will continue execution to the next commands.</para>
 
+        <para>Note that an <varname>ExecCondition=</varname> skip is <emphasis>not</emphasis> equivalent to a
+        unit-level <varname>Condition…=</varname> or <varname>Assert…=</varname> check failing. Because
+        <varname>ExecCondition=</varname> runs as part of the activation transition, a skip causes the unit to
+        transition from <constant>active</constant> to <constant>inactive</constant>, and consequently
+        <varname>SuccessAction=</varname> (see
+        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>) will be
+        honored. By contrast, <varname>Condition…=</varname> directives in the <literal>[Unit]</literal> section
+        prevent activation entirely and therefore do not trigger <varname>SuccessAction=</varname>.</para>
+
         <para>The same recommendations about not running long-running processes in <varname>ExecStartPre=</varname>
         also applies to <varname>ExecCondition=</varname>. <varname>ExecCondition=</varname> will also run the commands
         in <varname>ExecStopPost=</varname>, as part of stopping the service, in the case of any non-zero or abnormal
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 4e4b1714c0d..c84a365a96b 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -1108,6 +1108,16 @@
         allowed. In user mode, only <option>none</option>, <option>exit</option>, and
         <option>exit-force</option> are allowed. Both options default to <option>none</option>.</para>
 
+        <para>These actions are tied to the unit's state transitions and fire only when the unit actually
+        transitions out of an <constant>active</constant> or <constant>activating</constant> state. As a
+        consequence, <varname>Condition…=</varname> and <varname>Assert…=</varname> directives that fail do
+        <emphasis>not</emphasis> trigger <varname>SuccessAction=</varname> or
+        <varname>FailureAction=</varname>: they prevent activation in the first place, so no state transition
+        occurs. By contrast, the <varname>ExecCondition=</varname> directive in
+        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+        runs as part of activation, so an <varname>ExecCondition=</varname> skip <emphasis>will</emphasis>
+        trigger <varname>SuccessAction=</varname>.</para>
+
         <para>If <option>none</option> is set, no action will be triggered. <option>reboot</option> causes a
         reboot following the normal shutdown procedure (i.e. equivalent to <command>systemctl
         reboot</command>).  <option>reboot-force</option> causes a forced reboot which will terminate all