finally, bump the version
[alioth/cvs.git] / contrib / descend.man
1 .TH DESCEND 1 "31 March 1992"
2 .SH NAME 
3 descend \- walk directory tree and execute a command at each node
4 .SH SYNOPSIS 
5 .B descend
6 [
7 .B \-afqrv
8 ]
9 .I command
10 [
11 .I directory
12 \&.\|.\|.
13 ]
14 .SH DESCRIPTION
15 .B descend
16 walks down a directory tree and executes a command at each node.  It
17 is not as versatile as
18 .BR find (1),
19 but it has a simpler syntax.  If no
20 .I directory
21 is specified,
22 .B descend
23 starts at the current one.
24 .LP
25 Unlike
26 .BR find ,
27 .B descend
28 can be told to skip the special directories associated with RCS,
29 CVS, and SCCS.  This makes
30 .B descend
31 especially handy for use with these packages.  It can be used with
32 other commands too, of course.
33 .LP
34 .B descend
35 is a poor man's way to make any command recursive.  Note:
36 .B descend
37 does not follow symbolic links to directories unless they are
38 specified on the command line.
39 .SH OPTIONS
40 .TP 15
41 .B \-a
42 .I All.
43 Descend into directories that begin with '.'.
44 .TP
45 .B \-f
46 .I Force.
47 Ignore errors during descent.  Normally,
48 .B descend
49 quits when an error occurs.
50 .TP
51 .B \-q
52 .I Quiet.
53 Suppress the message `In directory
54 .IR directory '
55 that is normally printed during the descent.
56 .TP
57 .B \-r
58 .I Restricted.
59 Don't descend into the special directories 
60 .SB RCS,
61 .SB CVS,
62 .SB CVS.adm,
63 and
64 .SB SCCS.
65 .TP
66 .B \-v
67 .I Verbose.
68 Print 
69 .I command
70 before executing it.
71 .SH EXAMPLES
72 .TP 15
73 .B "descend ls"
74 Cheap substitute for `ls -R'.
75 .TP 15
76 .B "descend -f 'rm *' tree"
77 Strip `tree' of its leaves.  This command descends the `tree'
78 directory, removing all regular files.  Since 
79 .BR rm (1)
80 does not remove directories, this command leaves the directory
81 structure of `tree' intact, but denuded.  The
82 .B \-f
83 option is required to keep
84 .B descend
85 from quitting.  You could use `rm \-f' instead.
86 .TP 
87 .B "descend -r 'co RCS/*'" /project/src/
88 Check out every RCS file under the directory
89 .BR "/project/src" .
90 .TP
91 .B "descend -r 'cvs diff'"
92 Perform CVS `diff' operation on every directory below (and including)
93 the current one.
94 .SH DIAGNOSTICS
95 Returns 1 if errors occur (and the
96 .B \-f
97 option is not used).  Otherwise returns 0.
98 .SH SEE ALSO
99 .BR find (1),
100 .BR rcsintro (1),
101 .BR cvs (1),
102 .BR sccs (1)
103 .SH AUTHOR
104 Lowell Skoog
105 .br
106 Software Technology Group
107 .br
108 John Fluke Mfg. Co., Inc.
109 .SH BUGS
110 Shell metacharacters in
111 .I command
112 may have bizarre effects.  In particular, compound commands
113 (containing ';', '[', and ']' characters) will not work.  It is best
114 to enclose complicated commands in single quotes \(aa\ \(aa.