"UNIX's missing loop
command!"
loop
lets you write powerful, intuitive looping one-liners in your favorite shell! Finally, loops in Bash that make sense!
Loops in bash are surprisingly complicated and fickle! I wanted a simple and intuitive way to write controllable loops that:
-
Run on controllable timers!
$ loop 'ls' --every 10s
-
Have custom counters!
$ loop 'touch $COUNT.txt' --count-by 5
-
Loop until output matches a condition!
$ loop './get_response_code' --until-contains 200
-
Loop until a certain time!
$ loop './poke_server' --for-duration 8h
-
Loop until a program succeeds (or fails!)
$ loop './poke_server' --until-success
-
Iterate over the standard input!
$ cat files_to_create.txt | loop 'touch $ITEM'
-
Get a summary of the runs!
$ loop 'ls' --for-duration 10min --summary
-
..and much more!
And so loop
was born!
loop
is available on Snapcraft for all distributions as loop-rs
.
$ snap install loop-rs --beta
Issues related to this package are tracked here.
There is also an AUR for Arch Linux users, but I don't maintain it, so use it at your own risk:
$ yaourt -S loop
If you're a Homebrew user:
$ brew tap miserlou/loop https://github.com/Miserlou/Loop.git
$ brew install loop --HEAD
$ cargo install loop-rs
$ cargo build
./debug/loop
$ cargo run 'echo $COUNT'
1
2
[ .. ]
With no arguments, loop
will simply repeatedly execute a command string as fast as it can until ^C
(control + C) is sent.
$ loop 'echo hello'
hello
hello
hello
hello
[ .. ]
loop
places a counter value into the $COUNT
environment variable.
$ loop 'echo $COUNT'
0
1
2
[ .. ]
The amount this counter increments can be changed with --count-by
:
$ loop 'echo $COUNT' --count-by 2
2
4
6
[ .. ]
The counter can be offset with --offset
:
$ loop 'echo $COUNT' --count-by 2 --offset 10
10
12
14
[ .. ]
And iterators can be floats!
$ loop 'echo $COUNT' --count-by 1.1
0
1.1
2.2
[ .. ]
There's also an $ACTUALCOUNT
:
$ loop 'echo $COUNT $ACTUALCOUNT' --count-by 2
0 0
2 1
4 2
[ .. ]
You can get a summary of successes and failures (based on exit codes) with --summary
:
$ loop 'echo $COUNT' --num 3 --summary
0
1
2
Total runs: 3
Successes: 3
Failures: 0
or
$ loop 'ls -foobarbatz' --num 3 --summary
[ .. ]
Total runs: 3
Successes: 0
Failures: 3 (-1, -1, -1)
Loops can be set to timers which accept humanized times from the microsecond to the year with --every
:
$ loop 'date' --every 5s
Thu May 17 10:51:03 EDT 2018
Thu May 17 10:51:08 EDT 2018
Thu May 17 10:51:13 EDT 2018
Looping can be limited to a set duration with --for-duration
:
$ loop 'date' --for-duration 8s --every 2s
Fri May 25 16:46:42 EDT 2018
Fri May 25 16:46:44 EDT 2018
Fri May 25 16:46:46 EDT 2018
Fri May 25 16:46:48 EDT 2018
$
Or until a certain date/time with --until-time
:
$ loop 'date -u' --until-time '2018-05-25 20:50:00' --every 5s
Fri May 25 20:49:49 UTC 2018
Fri May 25 20:49:54 UTC 2018
Fri May 25 20:49:59 UTC 2018
$
loop
can iterate until output contains a string with --until-contains
:
$ loop 'echo $RANDOM' --until-contains "666"
11235
35925
666
$
Or until a program succeeds with --until-success
:
$ loop 'if (( RANDOM % 2 )); then (echo "TRUE"; true); else (echo "FALSE"; false); fi' --until-success
FALSE
FALSE
TRUE
$
Or until it fails with --until-error
(which also accepts an optional error code):
$ loop 'if (( RANDOM % 2 )); then (echo "TRUE"; true); else (echo "FALSE"; false); fi' --until-error
TRUE
TRUE
FALSE
$
Or until it matches a regular expression with --until-match
:
$ loop 'date' --until-match "(\d{4})"
Thu May 17 10:51:03 EDT 2018
$
Loops can iterate over all sorts of lists with --for
:
$ loop 'echo $ITEM' --for red,green,blue
red
green
blue
$
And can read from the standard input via pipes:
$ cat /tmp/my-list-of-files-to-create.txt | loop 'touch $ITEM'
$ ls
hello.jpg
goodbye.jpg
You can also easily pipe lists to loop
:
$ ls | loop 'cp $ITEM $ITEM.bak'; ls
hello.jpg
hello.jpg.bak
..or via the keyboard with -i
:
$ loop 'echo $ITEM | tr a-z A-Z' -i
hello
world^D
HELLO
WORLD
--for
can accept all sorts of lists:
$ loop 'echo $ITEM' --for "`ls`"
Cargo.lock
Cargo.toml
README.md
src
target
$
Here are some handy things you can do with loop
!
If you have a lot of files and a program, but don't know which file is the one the program takes, you can loop over them until you find it:
$ ls | loop './my_program $ITEM' --until-success;
Or, if you have a list of files but need to find the one which causes your program to fail:
$ ls | loop './my_program $ITEM' --until-fail;
If you've just kicked off a website deployment pipeline, you might want to run a process when the site starts returning 200 response codes. With --every
and --until-contains
, you can do this without flooding the site with requests:
$ ./deploy.sh; loop 'curl -sw "%{http_code}" http://coolwebsite.biz' --every 5s --until-contains 200; ./announce_to_slack.sh
Or until a host is online:
$ loop "ping -c 1 mysite.com" --until-success; ./do_next_thing
If you have a long-running process that creates a new file, you might want to kick off another program when that process outputs a new file, like so:
$ ./create_big_file -o my_big_file.bin; loop 'ls' --until-contains 'my_big_file.bin'; ./upload_big_file my_big_file.bin
If you've got a whole list of files that you want to create backup copies of, you can do it like so:
$ ls
hello.jpg
$ ls | loop 'cp $ITEM $ITEM.bak'
$ ls
hello.jpg
hello.jpg.bak
This is an example from StackExchange.
I want to write logic in shell script which will retry it to run again after 15 sec upto 5 times based on "status code=FAIL" if it fails due to some issue.
There are so many questions like this on StackExchange, which all end up with long threads of complicated answers.
With loop
, it's a simple one liner:
loop './do_thing.sh' --every 15s --until-success --num 5
Which will do the thing every 15 seconds until it succeeds, for a maximum of five times.
Got any more useful examples? Send a pull request!
This project is still young, so there is still plenty to be done. Contributions are more than welcome!
Please file tickets for discussion before submitting patches. Pull requests should target master
and should leave Loop in a "shippable" state if merged.
If you are adding a non-trivial amount of new code, please include a functioning test in your PR. The test suite will be run by Travis CI once you open a pull request. Please include the GitHub issue or pull request URL that has discussion related to your changes as a comment in the code (example). This greatly helps for project maintainability, as it allows us to trace back use cases and explain decision making. Similarly, please make sure that you meet all of the requirements listed in the pull request template.
Please feel free to work on any open ticket, especially any ticket marked with the "help-wanted" label!
(c) Rich Jones, 2018. MIT License.