From: Peter Krempa <pkrempa@redhat.com>

Document the '--once' option and how it combines with the setting
without '--once'.

Resolves: https://issues.redhat.com/browse/RHEL-89414
Signed-off-by: Peter Krempa <pkrempa@redhat.com>
---
 docs/manpages/virsh.rst | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst
index cef9959f16..7fa3725a59 100644
--- a/docs/manpages/virsh.rst
+++ b/docs/manpages/virsh.rst
@@ -1088,12 +1088,16 @@ autostart

 ::

-   autostart [--disable] domain
+   autostart [--disable] [--once] domain


-Configure a domain to be automatically started at boot.
+Configure a domain to be automatically started at each boot of the host. The
+*--once* option configures the domain to be started on the next boot of the host.

-The option *--disable* disables autostarting.
+The option *--disable* disables the corresponding autostarting.
+
+Note that the domain will be automatically started when either of the settings
+is enabled.


 blkdeviotune
-- 
2.49.0

On a Monday in 2025, Peter Krempa via Devel wrote:
>From: Peter Krempa <pkrempa@redhat.com>
>
>Document the '--once' option and how it combines with the setting
>without '--once'.
>
>Resolves: https://issues.redhat.com/browse/RHEL-89414
>Signed-off-by: Peter Krempa <pkrempa@redhat.com>
>---
> docs/manpages/virsh.rst | 10 +++++++---
> 1 file changed, 7 insertions(+), 3 deletions(-)
>
>diff --git a/docs/manpages/virsh.rst b/docs/manpages/virsh.rst
>index cef9959f16..7fa3725a59 100644
>--- a/docs/manpages/virsh.rst
>+++ b/docs/manpages/virsh.rst
>@@ -1088,12 +1088,16 @@ autostart
>
> ::
>
>-   autostart [--disable] domain
>+   autostart [--disable] [--once] domain
>
>
>-Configure a domain to be automatically started at boot.
>+Configure a domain to be automatically started at each boot of the host. The
>+*--once* option configures the domain to be started on the next boot of the host.
>
>-The option *--disable* disables autostarting.
>+The option *--disable* disables the corresponding autostarting.
>+

>+Note that the domain will be automatically started when either of the settings
>+is enabled.

I don't think this clarifies anything.

The paragraph you added to the virDomainSetAutostartOnce API was IMO
clearer, i.e.:

Note that autostart configured via the --once option is independent
from the autostart configured without it. Enabling either of them
will cause the VM to be started on the next boot.

Reviewed-by: Ján Tomko <jtomko@redhat.com>

Jano