Subject: Re: [RFC PATCH 4/5] maintenance: update systemd scheduler docs

From: Patrick Steinhardt <[email-masked]>
Date: Thu, 21 Mar 2024 13:37:54 +0100

On Mon, Mar 18, 2024 at 04:31:18PM +0100, Max Gautier wrote:

This commit is missing an explanation what exactly you are updating.
While you mention that you update something, the reader now has to
find out by themselves what exactly you update by reading through the
whole commit diff.

Patrick

> Signed-off-by: Max Gautier <[email-masked]>
> ---
>  Documentation/git-maintenance.txt | 33 +++++++++++++++----------------
>  1 file changed, 16 insertions(+), 17 deletions(-)
> 
> diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
> index 51d0f7e94b..6511c3f3f1 100644
> --- a/Documentation/git-maintenance.txt
> +++ b/Documentation/git-maintenance.txt
> @@ -304,10 +304,9 @@ distributions, systemd timers are superseding it.
>  If user systemd timers are available, they will be used as a replacement
>  of `cron`.
>  
> -In this case, `git maintenance start` will create user systemd timer units
> -and start the timers. The current list of user-scheduled tasks can be found
> -by running `systemctl --user list-timers`. The timers written by `git
> -maintenance start` are similar to this:
> +In this case, `git maintenance start` will enable user systemd timer units
> +and start them. The current list of user-scheduled tasks can be found by
> +running `systemctl --user list-timers`. These timers are similar to this:
>  
>  -----------------------------------------------------------------------
>  $ systemctl --user list-timers
> @@ -317,25 +316,25 @@ Fri 2021-04-30 00:00:00 CEST 5h 42min left Thu 2021-04-29 00:00:11 CEST 18h ago
>  Mon 2021-05-03 00:00:00 CEST 3 days left   Mon 2021-04-26 00:00:11 CEST 3 days ago [email-masked] [email-masked]
>  -----------------------------------------------------------------------
>  
> -One timer is registered for each `--schedule=<frequency>` option.
> +One timer instance is enabled for each `--schedule=<frequency>` option.
>  
> -The definition of the systemd units can be inspected in the following files:
> +The definition of the systemd units can be inspected this way:
>  
>  -----------------------------------------------------------------------
> -~/.config/systemd/user/git-maintenance@.timer
> -~/.config/systemd/user/git-maintenance@.service
> -~/.config/systemd/user/timers.target.wants/[email-masked]
> -~/.config/systemd/user/timers.target.wants/[email-masked]
> -~/.config/systemd/user/timers.target.wants/[email-masked]
> +$ systemctl cat --user git-maintenance@.timer
> +$ systemctl cat --user git-maintenance@.service
>  -----------------------------------------------------------------------
>  
> -`git maintenance start` will overwrite these files and start the timer
> -again with `systemctl --user`, so any customization should be done by
> -creating a drop-in file, i.e. a `.conf` suffixed file in the
> -`~/.config/systemd/user/git-maintenance@.service.d` directory.
> +Customization of the timer or service can be performed with the usual systemd
> +tooling:
> +-----------------------------------------------------------------------
> +$ systemctl edit --user git-maintenance@.timer # all the timers
> +$ systemctl edit --user [email-masked] # the hourly timer
> +$ systemctl edit --user git-maintenance@.service # all the services
> +$ systemctl edit --user [email-masked] # the hourly run
> +-----------------------------------------------------------------------
>  
> -`git maintenance stop` will stop the user systemd timers and delete
> -the above mentioned files.
> +`git maintenance stop` will disable and stop the user systemd timers.
>  
>  For more details, see `systemd.timer(5)`.
>  
> -- 
> 2.44.0
> 
>