1 \cfg{man-identity}{lns}{1}{2004-11-21}{Simon Tatham}{Simon Tatham}
3 \define{dash} \u2013{-}
5 \title Man page for \cw{lns}
9 \cw{lns} \dash symbolic link creation utility
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
20 \cw{lns} creates symbolic links.
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.
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}.
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.
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.
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}
62 will \e{expect} the final argument to be a directory, and will do
63 this for each of the other arguments.
65 (This behaviour is intended to mimic \cw{cp} as closely as
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.
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.
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.
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
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.
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.
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.
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
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}.
133 \dd Quiet mode: prevents \cw{lns} from printing an error message if
134 the link target already exists.
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:
142 \c $ lns file1 subdir
146 \c $ lns subdir/file3 subdir2/subsubdir
147 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
148 \c $ lns subdir2/file4 subdir2/subsubdir
149 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
151 Assuming all the subdirectories mentioned actually exist, this will
152 create the following symlinks:
154 \b \cw{subdir/file1}, with link text \cq{../file1}.
156 \b \cw{../file2}, with link text \cq{dir/file2}.
158 \b \cw{subdir2/subsubdir/file3}, with link text
159 \cq{../../subdir/file3}.
161 \b \cw{subdir2/subsubdir/file4}, with link text \cq{../file4}.
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
165 fourth link with text \cq{../../subdir2/file4}.
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
171 \c $ lns file1 subdir/file1
172 \e bbbbbbbbbbbbbbbbbbbbbb
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:
178 \c $ lns subdir2/file1 subdir
179 \e bbbbbbbbbbbbbbbbbbbbbbbb
180 \c lns: failed to link subdir2/file1 to subdir/file1: target exists
182 You can override this error by using \cw{-f}:
184 \c $ lns -f subdir2/file1 subdir
185 \e bbbbbbbbbbbbbbbbbbbbbbbbbbb
187 This will overwrite the existing link \cw{subdir/file1} with a new
188 one whose text reads \cq{../subdir2/file1}.
190 Now let's create some symlinks to \e{directories}. Again, this is
191 simple to begin with:
193 \c $ lns subdir2 subdir3
194 \e bbbbbbbbbbbbbbbbbbb
196 This creates a symlink called \cw{subdir3} with text \cq{subdir2}.
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:
202 \c $ lns -f subdir subdir3
203 \e bbbbbbbbbbbbbbbbbbbbb
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}.
212 In order to overwrite the directory symlink correctly, you need the
215 \c $ lns -F subdir subdir3
216 \e bbbbbbbbbbbbbbbbbbbbb
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}.
224 Next, a couple of examples with \cw{-r}. Suppose you have your
225 subdirectory \cw{subdir}. Then running
227 \c $ lns -r subdir subdir-mirror
228 \e bbbbbbbbbbbbbbbbbbbbbbbbbbb
230 will create a new subdirectory called \c{subdir-mirror}, containing
231 symlinks to everything in \c{subdir}.
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:
241 \c $ lns -rF subdir subdir-mirror
242 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbb
246 \cw{lns} is free software, distributed under the MIT licence. Type
247 \cw{lns --licence} to see the full licence text.