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 | |
39 | \U ARGUMENTS |
40 | |
41 | If you provide precisely two arguments to \cw{lns}, and the second |
42 | one is not a directory (or a symlink to a directory), then \cw{lns} |
43 | will interpret the second argument as a destination file name, and |
44 | create its target link with precisely that name. |
45 | |
46 | If the second argument is a directory, \cw{lns} will assume you want |
47 | a link created \e{inside} that directory, with the same filename as |
48 | the source file. If you supply more than two arguments, \cw{lns} |
49 | will \e{expect} the final argument to a directory, and will do this |
50 | for each of the other arguments. |
51 | |
52 | (This behaviour is intended to mimic \cw{cp} as closely as |
53 | possible.) |
54 | |
55 | The source file(s) are not required to exist. \cw{lns} will create |
56 | links to their locations whether they actually exist or not; if you |
57 | create them later, the links will point to them. |
58 | |
59 | \U OPTIONS |
60 | |
61 | \dt \cw{-a} |
62 | |
63 | \dd Create symlinks with absolute path names (beginning with a |
64 | slash). Normally, \cw{lns} will create relative symlinks. Relative |
65 | symlinks are often more useful: if a parent directory of both the |
66 | link and its target is moved to a new location, a relative symlink |
67 | will still work while an absolute one will fail. |
68 | |
69 | \dt \cw{-f} |
70 | |
71 | \dd Overwrite an existing symlink at the target location. Normally, |
72 | \cw{lns} will warn and refuse to do anything if the target location |
73 | is already occupied by a symlink to a file; using \cw{-f} will cause |
74 | it to replace the existing link with its new one. |
75 | |
76 | \lcont{ |
77 | |
78 | If the target location is occupied by something that is \e{not} a |
79 | symlink, \cw{lns} will refuse to overwrite it no matter what options |
80 | you supply. |
81 | |
82 | If you specify precisely two arguments, and the second is a symlink |
83 | to a directory, \cw{lns} will treat it as a destination directory |
84 | rather than a destination file, even if \cw{-f} is specified. Use |
85 | \cw{-F}, described next, to override this. |
86 | |
87 | } |
88 | |
89 | \dt \cw{-F} |
90 | |
91 | \dd Like \cw{-f}, but additionally forces \cw{lns} to interpret its |
92 | second argument as a destination \e{file} name rather than a |
93 | destination directory. This option is useful for overriding an |
94 | existing link to one directory with a link to a different one. |
95 | |
96 | \dt \cw{-v} |
97 | |
98 | \dd Verbose mode: makes \cw{lns} talk about what it is doing. You |
99 | can make it more verbose by adding a second instance of \cw{-v}. |
100 | |
101 | \dt \cw{-q} |
102 | |
103 | \dd Quiet mode: prevents \cw{lns} from printing an error message if |
104 | the link target already exists. |
105 | |
106 | \U EXAMPLES |
107 | |
108 | In simple situations, \cw{lns} can be used pretty much as you would |
109 | use \cw{cp}. For example, suppose you start in directory \cw{dir} |
110 | and issue the following commands: |
111 | |
112 | \c $ lns file1 subdir |
113 | \e bbbbbbbbbbbbbbbb |
114 | \c $ lns file2 .. |
115 | \e bbbbbbbbbbbb |
116 | \c $ lns subdir/file3 subdir2/subsubdir |
117 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
118 | \c $ lns subdir2/file4 subdir2/subsubdir |
119 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
120 | |
121 | Assuming all the subdirectories mentioned actually exist, this will |
122 | create the following symlinks: |
123 | |
124 | \b \cw{subdir/file1}, with link text \cq{../file1}. |
125 | |
126 | \b \cw{../file2}, with link text \cq{dir/file2}. |
127 | |
128 | \b \cw{subdir2/subsubdir/file3}, with link text |
129 | \cq{../../subdir/file3}. |
130 | |
131 | \b \cw{subdir3/subsubdir/file4}, with link text \cq{../file4}. |
132 | |
133 | Note that in each case \cw{lns} has constructed the \e{shortest} |
134 | relative link it could manage: it did not mindlessly create the |
135 | fourth link with text \cq{../../subdir/file4}. |
136 | |
137 | You can specify a target file name instead of a target directory. |
138 | For example, the following command has the same effect as the first |
139 | of the list above: |
140 | |
141 | \c $ lns file1 subdir/file1 |
142 | \e bbbbbbbbbbbbbbbbbbbbbb |
143 | |
144 | Now suppose there is another file called \cw{file1} in \cw{subdir2}, |
145 | and you want to change the link in \cw{subdir} to point to that. |
146 | Normally \cw{lns} will give you an error: |
147 | |
148 | \c $ lns subdir2/file1 subdir |
149 | \e bbbbbbbbbbbbbbbbbbbbbbbb |
150 | \c lns: failed to link subdir2/file1 to subdir/file1: target exists |
151 | |
152 | You can override this error by using \cw{-f}: |
153 | |
154 | \c $ lns -f subdir2/file1 subdir |
155 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbb |
156 | |
157 | This will overwrite the existing link \cw{subdir/file1} with a new |
158 | one whose text reads \cq{../subdir2/file1}. |
159 | |
160 | Now let's create some symlinks to \e{directories}. Again, this is |
161 | simple to begin with: |
162 | |
163 | \c $ lns subdir2 subdir3 |
4b2959c1 |
164 | \e bbbbbbbbbbbbbbbbbbb |
337ff285 |
165 | |
166 | This creates a symlink called \cw{subdir3} with text \cq{subdir2}. |
167 | |
168 | In order to overwrite this directory, the \cw{-F} option is likely |
169 | to be useful. Suppose I now want the link \cw{subdir3} to point at |
170 | \cw{subdir} instead of \cw{subdir2}. If I do this: |
171 | |
172 | \c $ lns -f subdir subdir3 |
4b2959c1 |
173 | \e bbbbbbbbbbbbbbbbbbbbb |
337ff285 |
174 | |
175 | then \cw{lns} will immediately notice that the second argument |
176 | \cw{subdir3} is (a symlink to) a directory, and will therefore |
177 | assume that it was intended to be the directory \e{containing} the |
178 | new link. So it will create a file \cw{subdir3/subdir} (equivalent |
179 | to \cw{subdir/subdir}, of course, since \cw{subdir3} is currently a |
180 | symlink to \cw{subdir}) with link text \cw{../subdir}. |
181 | |
182 | In order to overwrite the directory symlink correctly, you need the |
183 | \cw{-F} option: |
184 | |
185 | \c $ lns -F subdir subdir3 |
4b2959c1 |
186 | \e bbbbbbbbbbbbbbbbbbbbb |
337ff285 |
187 | |
188 | \cw{-F} tells \cw{lns} that you really want the new symlink to be |
189 | \e{called} \cw{subdir3}, not to be \e{in the directory} |
190 | \cw{subdir3}; and it also implies the \cw{-f} option to force |
191 | overwriting. So now you get what you wanted: the previous symlink |
192 | \cw{subdir3} is replaced with one whose link text reads \cq{subdir}. |
193 | |
194 | \U LICENCE |
195 | |
196 | \cw{lns} is free software, distributed under the MIT licence. Type |
197 | \cw{lns --licence} to see the full licence text. |
198 | |
199 | \versionid $Id$ |