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