Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 138 lines (92 sloc) 3.944 kb
c3e5a23 @tj Initial commit
authored
1
2 # Watch
3
4 A tiny C program used to periodically execute a command.
5
6 ## Usage
7
8 ```
9
10 Usage: watch [options] <cmd>
11
12 Options:
13
14 -q, --quiet only output stderr
a82e983 @jvirtanen Add '-x' option for halting on failure
jvirtanen authored
15 -x, --halt halt on failure
c3e5a23 @tj Initial commit
authored
16 -i, --interval <n> interval in seconds or ms defaulting to 1
31ee09f @jvirtanen Fix '-v' option documentation
jvirtanen authored
17 -v, --version output version number
c3e5a23 @tj Initial commit
authored
18
19 ```
20
21 ## Installation
22
23 ```
24 $ make install
25 ```
26
b692e8c @gvangool Added documentation on how to use PREFIX
gvangool authored
27 Or in your local bin (`~/bin`)
28
29 ```
30 $ PREFIX=~ make install
31 ```
32
240aeeb @tj about
authored
33 ## About
34
35 This project is very similar to original [watch(1)](http://linux.die.net/man/1/watch) implemented in 1991, differences include:
36
37 - ansi escape sequences (colors etc)
38 - terminal is not cleared
39 - lower default interval of 1s
40 - millisecond interval resolution
41
c3e5a23 @tj Initial commit
authored
42 ## Milliseconds resolution
43
44 This version of `watch(1)` support millisecond resolution
45 with the `ms` suffix:
46
47 ```
48 $ watch -i 300ms echo hey
49 ```
50
51 whereas `300` would be seconds:
52
53 ```
54 $ watch -i 300 echo hey
55 ```
56
57 ## Examples
58
59 Watch is pretty handy, here are a few use-cases:
60
61 ### Running tests
62
63 Ad-hoc mtime watchers are annoying to construct,
64 and have relatively no purpose when you can simply
65 execute your tests at a regular interval. For example
66 run `watch(1)` as a job, running tests each second (or a
67 second after the program exits):
68
69 ```
70 $ watch make test &
71 [1] 3794
72 ✔ bifs.components
73 ✔ bifs.dark
74 ✔ bifs.darken
75 ✔ bifs.image-size
76 ...
77 ```
78
79 Your tests will happily chug away, when you want to
80 stop watch simply foreground the job and ^C:
81
82 ```
191689e @tj no need for fg 1
authored
83 $ fg
c3e5a23 @tj Initial commit
authored
84 ```
85
86 ### Auto-build CSS / JS etc
87
fc8b928 @tj docs
authored
88 Need to build CSS or JavaScript dependencies? use a _Makefile_. With the large quantity of copy-cats (Rake,Jake,Sake,Cake...) people seem to be forgetting that Make is awesome, if you take a little bit of time to learn it you'll love it (or at least most of it). Make will utilize `mtime` and only build what's necessary, this is _great_.
c3e5a23 @tj Initial commit
authored
89
90 Let's say we had some Jade templates, even some nested in sub-directories, we could list them in a _Makefile_ quite easily.
91
92 Below __JADE__ is a list constructed by the shell command `find templates -name "*.jade"`, which is usually a lot easier to manage than listing these files manually, which is also valid, and sometimes important of ordering is relevant. Following that we have __HTML__ which simply substitutes ".jade" with ".html", giving us our HTML targets.
93
94 ```make
95 JADE = $(shell find templates -name "*.jade")
96 HTML = $(JADE:.jade=.html)
97 ```
98
99 Our first target is `all`, becoming the default target for `make`. On the right-hand side of this we specify the dependencies, which in this case is a list of all of our HTML files, not yet built. Make will see this and execute the `%.html` targets, which allows use to use the `jade(1)` executable to translate the dependency on the right of `:`, to the target on the left.
100
101 ```make
102 JADE = $(shell find templates -name "*.jade")
103 HTML = $(JADE:.jade=.html)
104
105 all: $(HTML)
106
107 %.html: %.jade
108 jade < $< > $@
109 ```
110
111 Now we can build all of these files with a single command `make`:
112
113 ```
114 $ make
115 jade < templates/bar.jade > templates/bar.html
116 jade < templates/baz/raz.jade > templates/baz/raz.html
117 jade < templates/foo.jade > templates/foo.html
118 ```
119
34bcb33 @tj misc
authored
120 We can also add a `clean` pseudo-target to remove the compiled files with `make clean`. Here it's listed to the right of `.PHONY:`, telling make that it does not expect a file named `./clean` on the fs, so it wont compare mtimes etc. Make is smart about re-executing these actions, if you `make` again you'll notice that since none of the dependencies have changed it'll simply tell you "make: Nothing to be done for `all'.".
c3e5a23 @tj Initial commit
authored
121
122 ```make
123 JADE = $(shell find templates -name "*.jade")
124 HTML = $(JADE:.jade=.html)
125
126 all: $(HTML)
127
128 %.html: %.jade
129 jade < $< > $@
130
131 clean:
132 rm -f $(HTML)
133
134 .PHONY: clean
135 ```
136
137 The one missing component is periodical action, which is where `watch(1)` or similar utilities come in, this functionality coupled with Make as a build system creates a powerful duo.
Something went wrong with that request. Please try again.