/ 
App-norepeat-0.05
River stage one • 1 direct dependent • 1 total dependent
/ norepeat

NAME

norepeat - Run commands, but not repeatedly

VERSION

This document describes version 0.05 of norepeat (from Perl distribution App-norepeat), released on 2015-05-16.

SYNOPSIS

Usage:

% norepeat [NOREPEAT OPTIONS] -- [PROGRAM] [PROGRAM OPTIONS ...]

Below are some examples.

This will run somecmd:

% norepeat -- somecmd --cmdopt

This won't run command again:

% norepeat -- somecmd --cmdopt

This will still run command because option is different:

% norepeat -- somecmd --anotheropt

This won't repeat somecmd with any argument:

% norepeat --key somecmd -- somecomd --cmdopt othervalue   ; # won't repeat
% norepeat --key somecmd -- somecomd --anotheropt          ; # won't repeat

This will repeat after 24 hours:

% norepeat --period 24h -- ...

This will repeat after change of day (equals to once daily):

% norepeat --period daily -- ...
% norepeat --daily -- ...

This allows twice daily:

% norepeat -n 2 --daily -- ...

DESCRIPTION

norepeat allows you to avoid repeat execution of the same command. You can customize the key (which command are considered the same, the default is the whole command), the repeat period, and some other stuffs.

It works simply by recording the keys and timestamps in a data file (defaults to ~/norepeat.dat, can be customized) after successful execution of commands. Commands might still repeat if norepeat fails to record to data file (e.g. disk is full, permission problem).

norepeat is typically used in shell startup scripts. I also use it with Dist::Zilla::Plugin::Run to run stuffs but not repeatedly.

Keywords: repeat interval, not too frequently, not more often than, at most, once daily, weekly, monthly, yearly, period, limit rate.

OPTIONS

  • --key=STR, -k

    Set key for determining which commands are considered the same. The default is the whole command. Example:

    % norepeat -- cmd --opt1
% norepeat -- cmd        ; # not considered the same command
% norepeat -- cmd --opt2 ; # not considered the same command, different options
% norepeat -- cmd2       ; # not considered the same command, obviously

    But with --key:

    % norepeat -k cmd -- cmd --opt1
% norepeat -k cmd -- cmd        ; # considered the same command, same key
% norepeat -k cmd -- cmd --opt2 ; # considered the same command, same key
% norepeat -k cmd -- whatever   ; # even this is considered the same command

  • --period=STR, -p

    Set maximum period for repeat detection. The default is forever (never repeat if the same command has ever been executed). Can either be "number + {sec,min,hour,day,month,year}" to express elapsed period after the last execution, or "{hourly,daily,monthly,yearly}" to express no repetition before the named period (hour,day,month,year) changes.

    For example, if period is "2 hour" then subsequent invocation won't repeat commands until 2 hours have elapsed. In other words, command won't repeat until the next 2 hours. Note that a month is defined as 30.5 days and a year is defined as 365.25 days.

    If period is "monthly", command won't repeat execution until the month changes (e.g. from June to July). If you execute the first command on June 3rd, command won't repeat until July 1st. The same thing would happen if you first executed the command on June 30th.

    When comparing, local times will be used.

  • --ignore-failure

    By default, if command exits with non-zero status, it is assumed to be a failure and won't be recorded in the data file. Another invocation will be allowed to repeat. This option will disregard exit status and will still log the data file.

  • --data-file, -f

    Set filename to record execution to. Defaults to ~/norepeat.dat.

  • --num=INT, -n

    Allow (n-1) repeating during the same period. Defaults to 1, which means to not allow any repeats. 2 means allow repeat once (for a total of 2 executions).

  • --hourly

    Shortcut for --period hourly.

  • --daily

    Shortcut for --period daily.

  • --weekly

    Shortcut for --period weekly.

  • --monthly

    Shortcut for --period monthly.

  • --yearly

    Shortcut for --period yearly.

EXIT CODES

0 on success.

0 on skipping repeated execution.

98 on failure to record to data file.

99 on command-line options error.

Otherwise exit code from command is returned.

ENVIRONMENT

DEBUG => bool

If set to true will show debugging messages.

NOW => int

Set arbitrary time as the current time. Useful for debugging, and will only take effect under DEBUG.

DATA FILE

Data file is a line-oriented text file, using labeled tab-separated value format (http://ltsv.org/). Each row contains these labels: time (a timestamp either in the format of UTC ISO8601YYYY-MM-DDTHH:MM:SSZ, local ISO8601 YYYY-MM-DDTHH:MM:SS, or Unix timestamp), key (tabs and newlines will be converted to spaces).

The rows are assumed to be sorted chronologically (increasing time).

SEE ALSO

Unix cron facility for periodic/scheduling of execution.

Related: modules to limit the number of program instances that can run at a single time: Proc::Govern, Sys::RunAlone.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/App-norepeat.

SOURCE

Source repository is at https://github.com/perlancar/perl-App-norepeat.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=App-norepeat

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.