1 04/28/88 change_wdir, cwd
2
3 Syntax as a command: cwd PATH -control_args
4
5
6 Function: changes your working directory to the directory specified
7 by the PATH optional argument. If PATH is omitted and neither -pop
8 nor -rotate is specified, changes to the default working directory.
9
10 Several features help in moving among a group of directories. When
11 changing to another working directory, the current directory can be
12 remembered by pushing onto a stack. Directories on the stack can
13 be revisited by giving their location within the stack, rather than
14 their pathname. Stack locations are identified either by an integer
15 position from the top of the stack, or by a name label associated
16 with the stack entry when it was remembered. The most recently
17 pushed working directory is at the top of the stack position 1.
18 Directories pushed earlier appear lower in the stack.
19
20 The -push operation allows you to remember the current working
21 directory when you plan to move back to it again. Additionally,
22 -push with an optional LABEL argument allows you to attach a text
23 string LABEL to the current working directory being pushed onto a
24 stack to aid in moving back to that labelled working directory.
25 The -pop operation allows you to move back to a particular
26 directory without naming the directory and additionally removes
27 from the stack all working directories immediately above it. The
28 -rotate operation is similar to -pop, moves to a stack entry
29 identified by the stack LOCATION, but it doesn't remove any working
30 directory from the stack while -pop does. The -clear operation
31 allows you to remove working directories from the stack without
32 changing the current working directory.
33
34 There are some restrictions applied to the LABEL. See "Notes"
35 for more details. The PATH optional argument is mutually
36 exclusive with -pop and -rotate. -clear, -pop, -push and -rotate
37 are also mutually exclusive.
38
39
40 Arguments:
41 PATH
42 is the pathname of the new working directory. If PATH is
43 omitted and neither -pop nor -rotate is specified, the default
44 working directory becomes the current working directory. PATH
45 cannot be used when -pop or -rotate is specified.
46 -clear LOCATION, -cl LOCATION
47 remove working directories from the stack without changing the
48 current working directory. -clear must be the last control
49 argument on the command line. LOCATION can be an integer
50 position N from the top of the stack; or a text LABEL associated
51 with a stack entry; or one of the reserved words first f,
52 last l or all a. The reserved word first identifies the top
53 stack directory stack position 1; last identifies the bottom
54 stack entry; and all identifies all stacked directories.
55
56 More than one LOCATION can be given to select several entries.
57 Individual locations are separated by a space. A LOCATION_RANGE
58 is given by a starting and ending LOCATION separated by a colon.
59 For example, f:2 identifies the top two directories on the stack,
60 and 1:XXX identifies stack entries from the top of the stack to
61 the entry with label XXX. If no LOCATION are given, the entire
62 stack is cleared. This operation cannot be used when -pop, -push,
63 or -rotate are specified.
64
65
66 -pop LOCATION
67 pop to the working directory identified by the stack LOCATION.
68 LOCATION is the position number N from the top of the working
69 directory stack or the text string LABEL associated with a stack
70 entry. The directory popped to becomes the new working directory.
71 Directories above the selected directory are removed popped from
72 the stack. Directories below the selected directory remain on the
73 stack. If LOCATION is omitted, the position number 1 within stack
74 is assumed. This operation cannot be used when PATH, -clear,
75 -push, or -rotate are specified.
76
77
78 -push LABEL
79 push the current working directory onto the stack for later
80 reference. If LABEL is specified, it becomes a name attached to
81 the stack entry of the current working directory. See "Notes" for
82 further information. This operation cannot be used when -clear,
83 -pop, or -rotate are specified.
84
85
86 -rotate LOCATION LABEL
87 move to the working directory identified by the stack LOCATION.
88 LOCATION is the position number N from the top of the working
89 directory stack or the text string LABEL associated with a stack
90 entry. If LABEL argument is specified, this name is associated by
91 the stack entry of the current working directory. Rotation occurs
92 by placing the current working directory at the bottom of the
93 stack, and setting the current working directory from the top
94 stack entry. If LOCATION is a position number N, then the
95 rotation operation occurs N times until the Nth stack entry
96 becomes the current working directory. If LOCATION is a stack
97 label, the rotation operation occurs until the labelled stack
98 entry becomes the current working directory. If LOCATION is
99 omitted, a position of 1 is assumed. This operation cannot be
100 used when PATH, -clear, -pop, or -push are specified.
101
102
103 Notes: Status access mode is required on the directory PATH.
104
105 LABEL is a text string which identifies a stack entry. Its
106 maximum length is 32 characters. It cannot begin with a minus
107 sign - or a numeric digit, and cannot include a colon :.
108 The words "first", "f", "last", "l", "all", and "a" are reserved
109 words which cannot be used as LABEL names.
110
111 Also see the print_wdir and working_dir commands/active functions.
112
113
114 Examples: In the following examples, the current working
115 directory is shown above stack position 1. Assume that the current
116 working directory is ">udd>m>tai"
117
118 1. An attempt to use a push function without LABEL. For example:
119
120 ! cwd cwd_dev -push
121 pushes the >udd>m>tai current working directory onto the
122 stack of prior working directories and changes to the
123 >udd>m>tai>cwd_dev new current working directory.
124
125 ! pwd a
126 LOC LABEL PATHNAME
127
128 0 >udd>m>tai>cwd_dev
129 1 >udd>m>tai
130
131 2. An attempt to use a push function with LABEL. For example:
132
133 ! cwd <abbrev_dev -push XXX
134 ! pwd a
135 LOC LABEL PATHNAME
136
137 0 >udd>m>tai>abbrev_dev
138 1 XXX >udd>m>tai>cwd_dev
139 2 >udd>m>tai
140
141 3. Then attempt to use a pop function. For example:
142
143 ! cwd -pop XXX
144 ! pwd a
145 LOC LABEL PATHNAME
146
147 0 XXX >udd>m>tai>cwd_dev
148 1 >udd>m>tai
149
150 ! cwd <<barmar -push YYY
151 ! pwd a
152 LOC LABEL PATHNAME
153
154 0 >udd>m>barmar
155 1 YYY >udd>m>tai>cwd_dev
156 2 >udd>m>tai
157
158 4. An attempt to use a rotate function: Assume that the stack
159 contents look like:
160
161 0 YYY >udd>m>tai>archive_dev
162 1 >udd>m>tai>abbrev_dev
163 2 XXX >udd>m>tai>cwd_dev
164 3 >udd>m>tai
165
166 ! cwd -rotate XXX ZZZ
167 labels the >udd>m>tai>archive_dev current working directory
168 to ZZZ and rotates the stack until the top-most labelled
169 directory is at the top of the stack.
170
171 ! pwd a
172 LOC LABEL PATHNAME
173
174 0 XXX >udd>m>tai>cwd_dev
175 1 >udd>m>tai
176 2 ZZZ >udd>m>tai>archive_dev
177 3 >udd>m>tai>abbrev_dev
178
179 ! cwd -rotate 2
180 ! pwd a
181 LOC LABEL PATHNAME
182
183 0 ZZZ >udd>m>tai>archive_dev
184 1 >udd>m>tai>abbrev_dev
185 2 XXX >udd>m>tai>cwd_dev
186 3 >udd>m>tai
187
188 4. An attempt to use only PATH. For example:
189
190 ! cwd <test_dir
191 ! pwd a
192 LOC LABEL PATHNAME
193
194 0 >udd>m>tai>test_dir
195 1 >udd>m>tai>abbrev_dev
196 2 XXX >udd>m>tai>cwd_dev
197 3 >udd>m>tai
198
199 5. An attempt to use a clear function. The stack contents show
200 as belows. For example:
201
202 0 >udd>m>tai>abbrev_dev
203 1 XXX >udd>m>cwd_dev
204 2 YYY >udd>m>barmar
205 3 XXX >udd>m>tai
206
207 ! cwd -clear XXX
208 ! pwd a
209 LOC LABEL PATHNAME
210
211 0 >udd>m>tai>abbrev_dev
212 1 YYY >udd>m>barmar
213 2 XXX >udd>m>tai
214
215 ! cwd -clear a
216 ! pwd a
217 0 >udd>m>tai>abbrev_dev
218
219 6. Assume that a directory named >udd>m>gd exists.
220
221 ! cwd <<gd -clear
222 Warning: the stack of prior wdirs is empty.
223
224 ! pwd a
225 0 >udd>m>gd