337ff285 |
1 | \cfg{man-identity}{lns}{1}{2004-11-21}{Simon Tatham}{Simon Tatham} |
2 | |
3 | \title Man page for \cw{lns} |
4 | |
5 | \U NAME |
6 | |
7 | \cw{lns} - symbolic link creation utility |
8 | |
9 | \U SYNOPSIS |
10 | |
11 | \c lns [ flags ] srcfile destfile |
12 | \e bbb iiiii iiiiiii iiiiiiii |
13 | \c lns [ flags ] srcfile [srcfile...] destdir |
14 | \e bbb iiiii iiiiiii iiiiiii iiiiiii |
15 | |
16 | \U DESCRIPTION |
17 | |
18 | \cw{lns} creates symbolic links. |
19 | |
20 | The standard command \cw{ln -s} also does this, but it interprets |
21 | its first argument as the literal text to be placed in the symlink. |
22 | If your current working directory is not the same as the target |
23 | directory, this can get confusing. For example, to create a symlink |
24 | to a file \cw{hello.c} in a subdirectory \cw{programs}, you would |
25 | have to write \c{ln -s ../hello.c programs}, even though |
26 | \cw{hello.c} is actually in your current directory, not one level |
27 | up. In particular, this is unhelpful because it makes it difficult |
28 | to use tab completion to set up the command line. |
29 | |
30 | \cw{lns} solves this problem, by creating symlinks using the obvious |
31 | semantics you would expect from \cw{mv} or \cw{cp}. All of its |
32 | arguments are expected to be either absolute path names, or relative |
33 | to the \e{current} working directory. So, in the above example, you |
34 | would write \c{lns hello.c programs/hello.c} or just \c{lns hello.c |
35 | programs}, exactly as you would have done if the command had been |
36 | \cw{cp}; and \cw{lns} will figure out for itself that the literal |
37 | text of the symlink needs to be \c{../hello.c}. |
38 | |
53ddbe1a |
39 | \cw{lns} also has a mode in which it will create a symlink mirror of |
40 | an entire directory tree: that is, instead of creating a single |
41 | symlink to the root of the tree, it will create \e{directories} in |
42 | the same structure as the whole of the original tree, and fill them |
43 | with individual symlinks to the files. This is occasionally handy if |
44 | you want to work with a slightly modified version of a large file |
45 | hierarchy but you don't want to waste the disk space needed to |
46 | create an entirely separate copy: you can symlink-mirror the whole |
47 | tree, and then just replace one or two of the symlinks with modified |
48 | versions of the files they point to. |
49 | |
337ff285 |
50 | \U ARGUMENTS |
51 | |
52 | If you provide precisely two arguments to \cw{lns}, and the second |
53 | one is not a directory (or a symlink to a directory), then \cw{lns} |
54 | will interpret the second argument as a destination file name, and |
55 | create its target link with precisely that name. |
56 | |
57 | If the second argument is a directory, \cw{lns} will assume you want |
58 | a link created \e{inside} that directory, with the same filename as |
59 | the source file. If you supply more than two arguments, \cw{lns} |
c800932b |
60 | will \e{expect} the final argument to be a directory, and will do |
61 | this for each of the other arguments. |
337ff285 |
62 | |
63 | (This behaviour is intended to mimic \cw{cp} as closely as |
64 | possible.) |
65 | |
66 | The source file(s) are not required to exist. \cw{lns} will create |
67 | links to their locations whether they actually exist or not; if you |
68 | create them later, the links will point to them. |
69 | |
70 | \U OPTIONS |
71 | |
72 | \dt \cw{-a} |
73 | |
74 | \dd Create symlinks with absolute path names (beginning with a |
75 | slash). Normally, \cw{lns} will create relative symlinks. Relative |
76 | symlinks are often more useful: if a parent directory of both the |
77 | link and its target is moved to a new location, a relative symlink |
78 | will still work while an absolute one will fail. |
79 | |
80 | \dt \cw{-f} |
81 | |
82 | \dd Overwrite an existing symlink at the target location. Normally, |
83 | \cw{lns} will warn and refuse to do anything if the target location |
84 | is already occupied by a symlink to a file; using \cw{-f} will cause |
85 | it to replace the existing link with its new one. |
86 | |
87 | \lcont{ |
88 | |
89 | If the target location is occupied by something that is \e{not} a |
90 | symlink, \cw{lns} will refuse to overwrite it no matter what options |
91 | you supply. |
92 | |
93 | If you specify precisely two arguments, and the second is a symlink |
94 | to a directory, \cw{lns} will treat it as a destination directory |
95 | rather than a destination file, even if \cw{-f} is specified. Use |
96 | \cw{-F}, described next, to override this. |
97 | |
98 | } |
99 | |
100 | \dt \cw{-F} |
101 | |
102 | \dd Like \cw{-f}, but additionally forces \cw{lns} to interpret its |
103 | second argument as a destination \e{file} name rather than a |
104 | destination directory. This option is useful for overriding an |
105 | existing link to one directory with a link to a different one. |
106 | |
53ddbe1a |
107 | \dt \cw{-r} |
108 | |
109 | \dd Enables recursive link-tree construction. If the source pathname |
110 | exists and is a directory, then instead of creating a symlink to it |
111 | at the target site, \cw{lns} will create a fresh directory, and then |
112 | recursively attempt to link every file inside the source directory |
113 | to the inside of the new target directory. |
114 | |
115 | \lcont{ |
116 | |
117 | If a directory already |
118 | exists at the target site, \cw{lns} will recurse into it; so you |
119 | can, for instance, use \cw{lns -r -f} to refresh an existing link |
120 | tree. |
121 | |
122 | } |
123 | |
337ff285 |
124 | \dt \cw{-v} |
125 | |
126 | \dd Verbose mode: makes \cw{lns} talk about what it is doing. You |
127 | can make it more verbose by adding a second instance of \cw{-v}. |
128 | |
129 | \dt \cw{-q} |
130 | |
131 | \dd Quiet mode: prevents \cw{lns} from printing an error message if |
132 | the link target already exists. |
133 | |
134 | \U EXAMPLES |
135 | |
136 | In simple situations, \cw{lns} can be used pretty much as you would |
137 | use \cw{cp}. For example, suppose you start in directory \cw{dir} |
138 | and issue the following commands: |
139 | |
140 | \c $ lns file1 subdir |
141 | \e bbbbbbbbbbbbbbbb |
142 | \c $ lns file2 .. |
143 | \e bbbbbbbbbbbb |
144 | \c $ lns subdir/file3 subdir2/subsubdir |
145 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
146 | \c $ lns subdir2/file4 subdir2/subsubdir |
147 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
148 | |
149 | Assuming all the subdirectories mentioned actually exist, this will |
150 | create the following symlinks: |
151 | |
152 | \b \cw{subdir/file1}, with link text \cq{../file1}. |
153 | |
154 | \b \cw{../file2}, with link text \cq{dir/file2}. |
155 | |
156 | \b \cw{subdir2/subsubdir/file3}, with link text |
157 | \cq{../../subdir/file3}. |
158 | |
19403684 |
159 | \b \cw{subdir2/subsubdir/file4}, with link text \cq{../file4}. |
337ff285 |
160 | |
161 | Note that in each case \cw{lns} has constructed the \e{shortest} |
162 | relative link it could manage: it did not mindlessly create the |
19403684 |
163 | fourth link with text \cq{../../subdir2/file4}. |
337ff285 |
164 | |
165 | You can specify a target file name instead of a target directory. |
166 | For example, the following command has the same effect as the first |
167 | of the list above: |
168 | |
169 | \c $ lns file1 subdir/file1 |
170 | \e bbbbbbbbbbbbbbbbbbbbbb |
171 | |
172 | Now suppose there is another file called \cw{file1} in \cw{subdir2}, |
173 | and you want to change the link in \cw{subdir} to point to that. |
174 | Normally \cw{lns} will give you an error: |
175 | |
176 | \c $ lns subdir2/file1 subdir |
177 | \e bbbbbbbbbbbbbbbbbbbbbbbb |
178 | \c lns: failed to link subdir2/file1 to subdir/file1: target exists |
179 | |
180 | You can override this error by using \cw{-f}: |
181 | |
182 | \c $ lns -f subdir2/file1 subdir |
183 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbb |
184 | |
185 | This will overwrite the existing link \cw{subdir/file1} with a new |
186 | one whose text reads \cq{../subdir2/file1}. |
187 | |
188 | Now let's create some symlinks to \e{directories}. Again, this is |
189 | simple to begin with: |
190 | |
191 | \c $ lns subdir2 subdir3 |
4b2959c1 |
192 | \e bbbbbbbbbbbbbbbbbbb |
337ff285 |
193 | |
194 | This creates a symlink called \cw{subdir3} with text \cq{subdir2}. |
195 | |
196 | In order to overwrite this directory, the \cw{-F} option is likely |
197 | to be useful. Suppose I now want the link \cw{subdir3} to point at |
198 | \cw{subdir} instead of \cw{subdir2}. If I do this: |
199 | |
200 | \c $ lns -f subdir subdir3 |
4b2959c1 |
201 | \e bbbbbbbbbbbbbbbbbbbbb |
337ff285 |
202 | |
203 | then \cw{lns} will immediately notice that the second argument |
204 | \cw{subdir3} is (a symlink to) a directory, and will therefore |
205 | assume that it was intended to be the directory \e{containing} the |
206 | new link. So it will create a file \cw{subdir3/subdir} (equivalent |
207 | to \cw{subdir/subdir}, of course, since \cw{subdir3} is currently a |
208 | symlink to \cw{subdir}) with link text \cw{../subdir}. |
209 | |
210 | In order to overwrite the directory symlink correctly, you need the |
211 | \cw{-F} option: |
212 | |
213 | \c $ lns -F subdir subdir3 |
4b2959c1 |
214 | \e bbbbbbbbbbbbbbbbbbbbb |
337ff285 |
215 | |
216 | \cw{-F} tells \cw{lns} that you really want the new symlink to be |
217 | \e{called} \cw{subdir3}, not to be \e{in the directory} |
218 | \cw{subdir3}; and it also implies the \cw{-f} option to force |
219 | overwriting. So now you get what you wanted: the previous symlink |
220 | \cw{subdir3} is replaced with one whose link text reads \cq{subdir}. |
221 | |
53ddbe1a |
222 | Next, a couple of examples with \cw{-r}. Suppose you have your |
223 | subdirectory \cw{subdir}. Then running |
224 | |
225 | \c $ lns -r subdir subdir-mirror |
226 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbb |
227 | |
228 | will create a new subdirectory called \c{subdir-mirror}, containing |
229 | symlinks to everything in \c{subdir}. |
230 | |
231 | If the directory \c{subdir-mirror} already existed, however, |
232 | \cw{lns}'s command-line processing will notice that it's a |
233 | directory, and will assume things are supposed to be copied \e{into} |
234 | it, so that your mirror of \c{subdir} will end up at |
235 | \c{subdir-mirror/subdir}. To fix this, you can again use \cw{-F}, to |
236 | tell \cw{lns} to literally create its output at the precise location |
237 | you specify rather than inside it: |
238 | |
239 | \c $ lns -rF subdir subdir-mirror |
240 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbb |
241 | |
337ff285 |
242 | \U LICENCE |
243 | |
244 | \cw{lns} is free software, distributed under the MIT licence. Type |
245 | \cw{lns --licence} to see the full licence text. |
246 | |
247 | \versionid $Id$ |