| 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{subdir2/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{../../subdir2/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 |
| 164 | \e bbbbbbbbbbbbbbbbbbb |
| 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 |
| 173 | \e bbbbbbbbbbbbbbbbbbbbb |
| 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 |
| 186 | \e bbbbbbbbbbbbbbbbbbbbb |
| 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$ |